Maintain Release And Packaging Surfaces

Companion Guidance

Use karpathy-guidelines alongside this skill for implementation or review work. Keep changes scoped, surface assumptions, and define focused validation before editing.

Use this skill when a change affects how NeMo Fabric is built, packaged, named, or consumed outside the source tree.

OpenShell Build Context

The optional host provider lives in environment-providers/openshell and links the OpenShell Rust SDK at a pinned release commit. Build it with just build-openshell-provider. Keep gateway, CLI, and runtime versions aligned with the qualified release. Task Docker build contexts must include every Cargo workspace member, including this provider, even when building only the native Python SDK. Keep the Dockerfile COPY statements and its whitelist dockerignore in parity. The task uses fabric-agent-ctl from the Python SDK.

Audit Areas

• Rust Cargo.toml package names and workspace metadata
• Root development coordination in pyproject.toml
• Published Python package metadata under sdk/python/ and adapter-contract/python/
• Native extension naming and placement under sdk/python/nemo-fabric-runtime/src/nemo_fabric
• Dependency resolution in Cargo.lock and uv.lock
• TypeScript adapter-contract metadata and dependency resolution in adapter-contract/typescript/package.json and package-lock.json
• Documentation tooling metadata in docs/package.json and docs/package-lock.json
• CI workflows, install commands, and example commands
• npm trusted publishing through .github/workflows/publish_typescript.yml and the protected npmjs environment
• justfile build, test, clean, and documentation recipes
• Release tags, registry publication, and release-facing documentation in RELEASING.md
• Metadata-only adapter catalog under sdk/python/nemo-fabric-adapter-catalog: regenerate its single resource bundle with just adapter-catalog and check freshness with just check-adapter-catalog. Keep source metadata outside descriptor objects and catalog resources outside automatic execution discovery. just set-version refreshes the bundle after stamping both ecosystems; just wheels checks freshness and builds the package.

Dependency Selection

Catalog Bundle Maintenance

scripts/ci/generate_adapter_catalog.py collects canonical descriptors and registered targets from leaf packages under adapters/python/ and adapters/typescript/, without an adapter-ID allowlist. Support packages, presets, fixtures, and source-only external integrations are excluded. The bundle keeps source package names, versions, paths, ecosystems, and fingerprints outside descriptor objects. Fingerprints use UTF-8 JSON with sorted keys, compact separators, and unescaped Unicode. These fields describe a release snapshot, not an observed execution environment.

Run just adapter-catalog, just check-adapter-catalog, and uv build --wheel --sdist --out-dir dist sdk/python/nemo-fabric-adapter-catalog when maintaining the bundle. just set-version refreshes it after stamping Python and TypeScript versions. Python tests and wheel builds reject stale bundles; wheels and source distributions must build independently of the adapter source tree. Keep these maintainer details out of the PyPI-facing package README.

Pi SDK Compatibility

Keep Pi’s optional peer constraints, development pins, consumer install command, and harness-install diagnostic aligned across all four SDK packages, including pi-codemode. Verify imports in a fresh consumer install from packed artifacts; the workspace lockfile can hide incompatible transitive SDK resolutions.

Select Dependencies

Treat every direct dependency as a long-lived API, supply-chain, and licensing commitment.

• Keep nemo-fabric as a metapackage that unconditionally installs the exact-version nemo-fabric-runtime distribution. Its harness extras delegate to version-matched leaf adapter harness extras. Hermes Agent is the sole exception: its root extra delegates to the bare adapter because Hermes Agent 0.20 and later is not installable from PyPI. Do not add other adapter-only aliases.
• Keep the runtime streaming extra pinned to the version-matched nemo-fabric-collector distribution. The metapackage streaming extra must delegate to the version-matched runtime extra. Do not expose a separate metapackage collector extra.
• Relay integrations use >=0.11,<0.12 for the Python binding and >=0.9,<0.12 for the CLI. Hermes keeps >=0.10,<0.11 to match the pinned upstream harness. Keep Hermes in its separate Python 3.14 environment; preserve the independent Hermes compatibility check when updating the shared Relay range.
• Keep credential-free HTTP model host support aligned across the Claude, Codex, and Pi descriptors and Relay config writers. Exact host trust uses harness.settings.insecure_http_model_hosts; an explicit empty list clears inherited trust. Regenerate embedded descriptors and the adapter catalog when settings change.
• Keep leaf adapters adapter-only by default. Every leaf provides full, and every package-installable harness provides harness. The Hermes adapter omits harness because users install Hermes Agent separately from source. Provide relay only when the adapter imports the NeMo Relay Python package. For adapters that launch the Relay CLI, both harness and full install the version-matched nemo-relay-cli-bin package and remain equivalent.
• First prefer the standard library, an existing dependency, or a small local implementation when it keeps the behavior clear and maintainable.
• When multiple dependencies satisfy the technical requirement, prefer the maintained OSS option with clear SPDX metadata, a smaller transitive graph, and permissive terms such as Apache-2.0, MIT, BSD, or ISC.
• Inspect the resolved transitive graph, not only the direct package license.
• Treat UNKNOWN, non-SPDX/custom, proprietary or source-available terms, and copyleft or network-copyleft terms as explicit review points. Do not silently accept or reject them; route them to the dependency approvers with the distribution and linkage context.
• Record the functional need, viable alternatives considered, why the selected dependency is the narrowest fit, and any unresolved licensing question.
• Run uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main after updating manifests and lockfiles, then review added packages and license changes.
• For adapter-contract/typescript/package-lock.json, inspect the resolved package entries and their license fields. The adapter-contract package must keep an empty production dependency graph; build-only dependencies still require permissive, recorded license evidence.

• Regenerate the attribution files with the named pre-commit hooks instead of editing generated output:

  uv run pre-commit run --all-files attributions-rust
  uv run pre-commit run --all-files attributions-python
  uv run pre-commit run --all-files attributions-node

The license diff is evidence for reviewers. Dependency approvers make compatibility decisions using the distribution and linkage context.

Checklist

• Package names, import paths, and module names are internally consistent
• Generated artifacts still land where downstream consumers expect
• Docs and examples use the current install/import/build commands
• CI references the same package names as local workflows
• Public packaging changes are reflected in release-facing docs
• Workspace, Python, and lockfile versions remain aligned where required
• The TypeScript adapter-contract package version follows the workspace release version without changing its independent wire contract version
• The editable maturin build still produces nemo_fabric._native
• New dependencies are necessary, maintained, and narrower than the viable alternatives
• Direct and transitive license changes were reviewed from the resolved lockfiles
• Licensing uncertainties are called out for dependency approver review
• Changed attribution files are regenerated and included

References

• pyproject.toml
• RELEASING.md
• sdk/python/nemo-fabric/pyproject.toml
• sdk/python/nemo-fabric-runtime/pyproject.toml
• adapter-contract/python/pyproject.toml
• Cargo.toml
• Cargo.lock
• uv.lock
• docs/package.json
• docs/package-lock.json
• adapter-contract/typescript/package.json
• adapter-contract/typescript/package-lock.json
• .github/workflows/ci_typescript.yml
• .github/workflows/publish_typescript.yml
• scripts/ci/publish_typescript_package.py
• .github/workflows/ci_python.yml
• .github/workflows/ci_rust.yml
• .pre-commit-config.yaml
• scripts/licensing/license_diff.py
• justfile

New Public npm Packages

Run python3 scripts/ci/check_npm_bootstrap.py when introducing a public npm package. The check discovers the contract and public adapter workspaces from manifests; add the adapter to the npm workspace. Separately wire it into release version stamping, build/test coverage, and the publication list before enabling uploads. Discovery alone does not enable publication. Complete the npm maintainer bootstrap and authenticated trusted-publisher readback in RELEASING.md before release. Public existence alone cannot verify trusted publishing. If the PR check reports HTTP 404, ask an authorized npm maintainer to bootstrap the exact manifest name, then rerun the check. Do not add CI write tokens or manually publish supported versions.

• The Python runtime and adapter contract both depend on the exact-version, standard-library nemo-fabric-evidence package for shared evidence, codecs, and validation. Keep package builds, version stamping, editable sources, locks, and release artifacts aligned. The SDK must not depend on or import the southbound adapter contract. Preserve adapter-contract compatibility re-exports. Keep SDK/adapter package selection, snapshot caching and lifecycle/transport implementations outside the shared package; shared bounded metadata primitives may live alongside the evidence models.
• Canonical shared evidence schemas live in schemas/evidence/, separate from schemas/adapter-contract/ and schemas/sdk/. The Rust generator owns this path. The TypeScript adapter-contract package consumes the shared schema and retains its existing bundled schema exports; update generation, parity tests and docs together when moving canonical snapshots.