# Binary Prerequisites & Offline Layout

## Layout (authoritative)
- `.nuget/packages/` — NuGet package cache (configured via `nuget.config` `globalPackagesFolder`).
- `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 `.nuget/packages/` per 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 `.nuget/packages/` from a network-connected machine, then copy to 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 `.nuget/packages/` as configured in `nuget.config`. Clean by removing `.nuget/packages/` if needed.
- 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.