# Binary Prerequisites & Offline Layout

## Layout (authoritative)
- `local-nugets/` — single source for NuGet: holds curated `.nupkg` and the restored packages cache in `local-nugets/packages/`; see `local-nugets/manifest.json` for hashes of the `.nupkg` inputs.
- `vendor/` — pinned binaries/CLIs tracked via `vendor/manifest.json`.
- `offline/feeds/` — air-gap bundles (tarballs, OCI layers, SBOM packs) registered in `offline/feeds/manifest.json`.
- Module-owned binaries (currently `plugins/`, `tools/`, `deploy/`, `ops/`) are tracked for integrity in `vendor/manifest.json` until relocated.

## Adding or updating NuGet packages
1) Place `.nupkg` into `local-nugets/` and update `local-nugets/manifest.json` (use the manifest script in `scripts/` if available or recompute hashes manually).
2) Run `dotnet restore --source local-nugets` (or set `OFFLINE=1`) to populate `.nuget/packages/`.
3) Never add new feeds to `NuGet.config` without review; the default feed order is `local-nugets` first, then `nuget.org` for online builds.

## Adding other binaries
1) Prefer building from source; if you must pin a binary, drop it under `vendor/` (or `offline/feeds/` for air-gap bundles) 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 `vendor/manifest.json` until it can be rebuilt deterministically as part of CI.

## Automation & Integrity
- Run `scripts/update-binary-manifests.py` to refresh `local-nugets/manifest.json`, `vendor/manifest.json`, and `offline/feeds/manifest.json` 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.
- Restore uses the single location: `dotnet restore --source local-nugets` with `globalPackagesFolder=local-nugets/packages` (configured in `NuGet.config`). Clean by removing `local-nugets/packages/` if needed.
- For offline enforcement, set `OFFLINE=1` (CI should fail if it reaches `nuget.org` without `ALLOW_REMOTE=1`).

## Housekeeping
- Do not resurrect `local-nuget/`; the single source of truth is `local-nugets/`.
- Refresh manifests when binaries change and record the update in the current sprint’s Execution Log.