up

docs/24_OFFLINE_KIT.md

@@ -68,6 +68,13 @@ Outputs:
 - `telemetry/telemetry-offline-bundle.tar.gz` + `.sha256` — packaged OTLP collector assets for environments without upstream access
 - `plugins/scanner/analyzers/lang/StellaOps.Scanner.Analyzers.Lang.Python/*.sig` (+ `.sha256`) — Cosign signatures for the Python analyzer DLL and manifest
 
+### Policy Gateway configuration bundle
+
+- Copy `etc/policy-gateway.yaml` (or the `*.sample` template if you expect operators to override values) into `config/policy-gateway/policy-gateway.yaml` within the staging tree.
+- Include the gateway DPoP private key under `secrets/policy-gateway/policy-gateway-dpop.pem` and reference the location inside the manifest notes. Set the permissions explicitly (`chmod 600 secrets/policy-gateway/policy-gateway-dpop.pem`) so only the kit importer can read it; the importer will refuse keys that are broader.
+- Document the gateway base URL and activation verification steps in `docs/policy/gateway.md` (bundled alongside the kit). Operators can use those curl snippets to smoke-test pack CRUD once the Offline Kit is imported.
+- Ensure the Prometheus snapshot captured during packaging contains `policy_gateway_activation_requests_total` so auditors can reconcile activation attempts performed via the gateway during the validation window.
+
 Provide `--cosign-key` / `--cosign-identity-token` (and optional `--cosign-password`) to generate Cosign signatures for both the tarball and manifest.
 
 ---
@@ -189,6 +196,30 @@ The CLI validates recorded digests (when `.metadata.json` is present) before str
 * Old feeds are kept until the new bundle is fully verified.
 * Import time on a SATA SSD: ≈ 25 s for a 300 MB kit.
 
+### 2.1 Validator + idempotency enablement (air-gap)
+
+The Offline Kit carries the same helper scripts under `scripts/`:
+
+1. **Duplicate audit:** run
+   ```bash
+   mongo concelier ops/devops/scripts/check-advisory-raw-duplicates.js --eval 'var LIMIT=200;'
+   ```
+   to verify no `(vendor, upstream_id, content_hash, tenant)` conflicts remain before enabling the idempotency index.
+2. **Apply validators:** execute `mongo concelier ops/devops/scripts/apply-aoc-validators.js` (and the Excititor equivalent) with `validationLevel: "moderate"` in maintenance mode.
+3. **Restart Concelier** so migrations `20251028_advisory_raw_idempotency_index` and `20251028_advisory_supersedes_backfill` run automatically. After the restart:
+   - Confirm `db.advisory` resolves to a view on `advisory_backup_20251028`.
+   - Spot-check a few `advisory_raw` entries to ensure `supersedes` chains are populated deterministically.
+4. **Smoke test:** run `stella sources ingest --dry-run --fixture advisory` (bundled fixtures) to confirm ingestion succeeds post-guard and the CLI reports zero violations.
+
+### Authority scope sanity check
+
+Offline installs rely on the bundled `etc/authority.yaml.sample`. Before promoting the kit, confirm the sample clients keep the Aggregation-Only guardrails:
+
+- `aoc-verifier` requests `aoc:verify`, `advisory:read`, and `vex:read`.
+- `signals-uploader` requests `signals:write`, `signals:read`, and `aoc:verify`.
+
+Authority now rejects tokens that request `advisory:read`, `vex:read`, or any `signals:*` scope without `aoc:verify`; the sample has been updated to match. If you maintain tenant-specific overlays, mirror the same pairing so air-gapped automation fails deterministically with `invalid_scope` when misconfigured.
+
 **Quick smoke test:** before import, verify the tarball carries the Go analyzer plug-in:
 
 ```bash