Binary Prerequisites & Offline Layout

For developers and release engineers who add, pin, or refresh binary dependencies in the Stella Ops monorepo, and for anyone preparing an offline / air-gapped build. It defines where binaries live, how integrity manifests are maintained, and how to keep restores deterministic and offline-friendly.

Layout (authoritative)

• ~/.nuget/packages/ — default system-wide NuGet package cache. Override it explicitly with NUGET_PACKAGES when preparing a bounded offline cache; repo-local .nuget/ directories are ignored scratch and are not the default restore authority.
• devops/manifests/ — binary integrity manifests (e.g., binary-plugins.manifest.json).
• devops/offline/feeds/ — air-gap bundles (tarballs, OCI layers, SBOM packs) registered in manifest.json.
• Module-owned binaries (currently plugins/, tools/, deploy/, ops/) are tracked for integrity in devops/manifests/ until relocated.

Adding or updating NuGet packages

1. Run dotnet restore, which populates the active global packages folder (normally ~/.nuget/packages/) from the sources in NuGet.config.
2. Never add new feeds to nuget.config without review; the configured sources are nuget.org and stellaops (internal feed).
3. For offline builds, pre-populate a bounded package cache from a network-connected machine and point NUGET_PACKAGES at that cache in the air-gapped environment.

Adding other binaries

1. Prefer building from source; if you must pin a binary, drop it under devops/offline/ and append an entry with SHA-256, origin URL, version, and intended consumer.
2. For module-owned binaries (e.g., plugins), record the artefact in devops/manifests/binary-plugins.manifest.json until it can be rebuilt deterministically as part of CI.

Automation & Integrity

• Run scripts/update-binary-manifests.py to refresh manifests after adding binaries.
• Run scripts/verify-binaries.sh locally; CI executes it on every PR/branch to block binaries outside approved roots.
• CI also re-runs the manifest generator and fails if the manifests would change — commit regenerated manifests as part of the change.
• NuGet restore uses the system-wide cache unless NUGET_PACKAGES is set. A stale repo-local .nuget/ cache can be removed after confirming dotnet nuget locals global-packages --list points elsewhere.
• For offline enforcement, set OFFLINE=1 (CI should fail if it reaches nuget.org without ALLOW_REMOTE=1).

Housekeeping

• Refresh manifests when binaries change and record the update in the current sprint’s Execution Log.