work

docs/modules/cli/guides/commands/advisory.md

@@ -0,0 +1,25 @@
+# stella advisory — Command Guide
+
+## Commands
+- `stella advisory list --source <provider> [--status <status>] [--output json|ndjson|table] [--offline]`
+- `stella advisory get --id <advisoryId> [--output json|table] [--offline]`
+- `stella advisory export --bundle <path> [--offline]`
+
+## Flags (common)
+- `--offline`: pull from cached advisory snapshots/mirror bundles only; exit code 5 if remote needed.
+- `--source`: provider filter (msrc, nvd, osv, csaf, etc.).
+- `--status`: affected, fixed, not_affected, withdrawn, disputed.
+- `--output`: json (default), ndjson, table.
+
+## Inputs/outputs
+- Inputs: Concelier/Excititor advisory projections; cached mirror bundles when offline.
+- Outputs: raw evidence with provenance (`observationId`, `linksetId`, signatures); no merging/inference.
+- Exit codes per `output-and-exit-codes.md`; not found → 4, offline violation → 5.
+
+## Determinism rules
+- Sorted by advisory key; withdrawn/duplicate handling matches upstream evidence; no severity inference.
+- Timestamps UTC; hashes lowercase hex.
+
+## Offline/air-gap notes
+- Mirror bundles must be preloaded for offline use; CLI verifies signatures against trust roots.
+- Export uses local evidence only; produces deterministic bundle with manifest + checksums.

docs/modules/cli/guides/commands/aoc.md

@@ -0,0 +1,21 @@
+# stella aoc — Command Guide
+
+## Commands
+- `stella aoc verify --input <evidence> [--policy <path>] [--offline]`
+- `stella aoc explain --input <evidence> [--output json|table]`
+
+## Flags (common)
+- `--offline`: verify evidence without remote calls; exit code 5 if network would be required.
+- `--policy`: optional AOC policy file; defaults to platform policy.
+- `--output`: json (default), table.
+
+## Inputs/outputs
+- Inputs: AOC evidence bundle; optional policy file.
+- Outputs: verification results with rationale; aggregation-only.
+- Exit codes per `output-and-exit-codes.md`; 3 for auth failures, 4 for missing evidence, 5 for offline violation.
+
+## Determinism rules
+- Stable ordering of findings; timestamps UTC; hashes lowercase hex.
+
+## Offline/air-gap notes
+- Trust roots loaded locally; no remote downloads allowed in offline mode.

docs/modules/cli/guides/commands/auth.md

@@ -0,0 +1,19 @@
+# stella auth — Command Guide
+
+## Commands
+- `stella auth login --token <token> [--url <baseUrl>]`
+- `stella auth status`
+- `stella auth logout`
+
+## Flags
+- `--url`: API base URL; defaults to config/env.
+- `--token`: bearer token or OIDC device code (future); stored in config if allowed.
+
+## Behaviour
+- Login writes token to config file or keyring (where supported) with deterministic permissions; never echoes secrets.
+- Status prints current user/tenant scopes if available; uses exit code 3 when unauthenticated.
+- Logout removes stored token and cached session data.
+
+## Offline/air-gap notes
+- Login requires network; if `--offline` is set, command must fail with exit code 5.
+- Status/logout work offline using cached credentials only.

docs/modules/cli/guides/commands/export.md

@@ -0,0 +1,25 @@
+# stella export — Command Guide
+
+## Commands
+- `stella export mirror --bundle <path> --profile <name> [--offline]`
+- `stella export verify --bundle <path> --trust-roots <file>`
+- `stella export plan --output json` (preview bundle contents)
+
+## Flags (common)
+- `--offline`: enforce no network; fail with exit code 5 if registry/object-store calls would occur.
+- `--profile`: named export profile (schema/manifest version); defaults to latest supported.
+- `--trust-roots`: PEM/TUF/DSSE trust roots for verification.
+- `--output`: json (default) or table for plan outputs.
+
+## Inputs/outputs
+- Inputs: export profiles, mirror configuration, optional cached artefacts.
+- Outputs: deterministic bundle tarball + manifest (checksums, signatures, metadata); verify emits status + detailed reasons.
+- Exit codes follow `output-and-exit-codes.md`; verification failure uses exit code 3.
+
+## Determinism rules
+- Manifest ordering is stable; checksums hex-lowercase; timestamps UTC.
+- No network-dependent mutation; offline bundles must be reproducible.
+
+## Offline/air-gap notes
+- `--offline` must be honored; registry pulls are forbidden unless cached in profile path.
+- Verification uses only local trust roots; no remote key fetch.

docs/modules/cli/guides/commands/notify.md

@@ -0,0 +1,24 @@
+# stella notify — Command Guide
+
+## Commands
+- `stella notify send --channel <email|chat|webhook> --template <id> --data <file>`
+- `stella notify list --status <pending|sent|failed> [--output json|table] [--offline]`
+- `stella notify get --id <messageId> [--offline]`
+
+## Flags (common)
+- `--offline`: only allowed when notification queue snapshots are cached; otherwise exit code 5.
+- `--tenant`: scope to tenant; enforced by server RLS.
+- `--output`: json/ndjson/table.
+
+## Inputs/outputs
+- Inputs: Notify API; optional cached queue snapshots when offline.
+- Outputs: message metadata, status, delivery results; no template content leaks.
+- Exit codes follow `output-and-exit-codes.md`; 4 for not found, 5 for offline violation.
+
+## Determinism rules
+- Listings sorted by created time then id; timestamps UTC.
+- No retries triggered by the CLI; it only submits/reads.
+
+## Offline/air-gap notes
+- Sending in offline mode is disallowed (exit code 5); only listing cached snapshots is permitted.
+- Templates must be preloaded; no remote fetches when `--offline`.

docs/modules/cli/guides/commands/orchestrator.md

@@ -0,0 +1,23 @@
+# stella orchestrator — Command Guide
+
+## Commands
+- `stella orchestrator jobs list --output json|table [--offline]`
+- `stella orchestrator jobs get --id <jobId> [--offline]`
+- `stella orchestrator runs get --id <runId> [--offline]`
+
+## Flags (common)
+- `--offline`: only allowed when cached ledger snapshots are available; otherwise exit code 5.
+- `--status`, `--type`: filters for job listings; deterministic sort by created time then id.
+- `--output`: json/ndjson/table.
+
+## Inputs/outputs
+- Inputs: Orchestrator API or cached run ledger snapshots.
+- Outputs: job/run metadata with provenance hashes and DSSE/attestation pointers when available.
+- Exit codes per `output-and-exit-codes.md`; 4 for not found, 5 for offline violation.
+
+## Determinism rules
+- Sorted outputs; timestamps UTC; hashes hex lowercase.
+- No inferred state beyond orchestrator responses.
+
+## Offline/air-gap notes
+- Ledger snapshots must be preloaded; no live scheduler calls when `--offline`.

docs/modules/cli/guides/commands/policy.md

@@ -0,0 +1,25 @@
+# stella policy — Command Guide
+
+## Commands
+- `stella policy eval --input <bundle> --subject <sbom|vex|vuln> [--offline] [--output json|ndjson|table]`
+- `stella policy simulate --from <bundleA> --to <bundleB> [--budget <ms>] [--offline]`
+- `stella policy publish --input <bundle> --sign --attest`
+
+## Flags (common)
+- `--offline` / `STELLA_OFFLINE=1`: forbid network calls; use cached bundles only.
+- `--tenant <id>`: scope evaluation to tenant; RLS enforcement required on the server.
+- `--rationale`: include rationale IDs in responses.
+- `--output`: `json` (default), `ndjson`, or `table`.
+
+## Inputs/outputs
+- Inputs: policy bundles (signed), subject artifacts (SBOM/VEX/Vuln snapshots).
+- Outputs: deterministic JSON/NDJSON or tables; includes `correlationId`, `policyVersion`, `rationaleIds` when requested.
+- Exit codes follow `output-and-exit-codes.md`.
+
+## Determinism rules
+- Sort evaluation results by subject key; timestamps UTC ISO-8601.
+- No inferred verdicts beyond Policy Engine response.
+
+## Offline/air-gap notes
+- When `--offline`, evaluation must use locally cached bundles and subject artifacts; fail with exit code 5 if network would be needed.
+- Trust roots loaded from `STELLA_TRUST_ROOTS` when verifying signed bundles.

docs/modules/cli/guides/commands/sbom.md

@@ -0,0 +1,25 @@
+# stella sbom — Command Guide
+
+## Commands
+- `stella sbom generate --image <ref> [--output sbom.spdx.json] [--offline]`
+- `stella sbom compose --fragment <path> --output composition.json --offline`
+- `stella sbom verify --file <sbom> --signature <sig> --key <keyfile>`
+
+## Flags (common)
+- `--offline`: no network pulls; use local cache/OCI archive.
+- `--format`: `spdx-json` (default) or `cyclonedx-json`.
+- `--attest`: emit DSSE attestation alongside SBOM.
+- `--hash`: include layer/file hashes (deterministic ordering).
+
+## Inputs/outputs
+- Inputs: container image, directory, or fragments.
+- Outputs: deterministic SPDX/CycloneDX JSON, optional DSSE + checksums.
+- Exit codes per `output-and-exit-codes.md`; verification failure uses exit code 3 or 4 depending on cause.
+
+## Determinism rules
+- Stable ordering of packages/files; timestamps UTC.
+- Hashes hex-lowercase; no host-specific paths.
+
+## Offline/air-gap notes
+- With `--offline`, image sources must already be cached (tar/OCI archive); command fails with exit code 5 if it would fetch remotely.
+- Verification uses local trust roots; no remote key fetch.

docs/modules/cli/guides/commands/vex.md

@@ -0,0 +1,23 @@
+# stella vex — Command Guide
+
+## Commands
+- `stella vex consensus --query <filter> [--output json|ndjson|table] [--offline]`
+- `stella vex get --id <consensusId> [--offline]`
+- `stella vex simulate --input <vexDocs> --policy <policyConfig> [--offline]`
+
+## Flags (common)
+- `--offline`: use cached consensus snapshots; fail with exit code 5 if remote would be hit.
+- `--policy <path>`: apply trust/weighting config; aggregation-only outputs.
+- `--page-size`, `--page-token`: deterministic pagination.
+
+## Inputs/outputs
+- Inputs: VEX consensus projection (VexLens); optional cached snapshots when offline.
+- Outputs: consensus states with `consensus_state`, `confidence`, `weights`, `issuers`, `rationale`; stable ordering.
+
+## Determinism rules
+- Sort by `consensusId`; pagination tokens deterministic.
+- No verdict inference beyond upstream consensus projection; CLI stays aggregation-only.
+
+## Offline/air-gap notes
+- Cached snapshots are required when `--offline`; otherwise exit code 5 with remediation message.
+- Trust roots for signature verification are loaded from `STELLA_TRUST_ROOTS` when verifying cached snapshots.

docs/modules/cli/guides/commands/vuln.md

@@ -0,0 +1,25 @@
+# stella vuln — Command Guide
+
+## Commands
+- `stella vuln list --query <filter> [--group-by <field>] [--output json|ndjson|table] [--offline]`
+- `stella vuln get --id <vulnId> [--output json|table] [--offline]`
+- `stella vuln simulate --from <policyA> --to <policyB> --subjects <path> [--offline]`
+
+## Flags (common)
+- `--offline`: read from cached snapshots; fail with exit code 5 if network would be used.
+- `--policy <id>`: scope queries to a policy projection.
+- `--page-size`, `--page-token`: deterministic pagination.
+- `--group-by`: `cve`, `package`, `status`, `advisory` (results stay stably ordered within groups).
+
+## Inputs/outputs
+- Inputs: Vuln Explorer API; optional cached snapshots when offline.
+- Outputs: sorted lists or detail documents with provenance pointers (`advisoryId`, `evidenceIds`, `consensusId`).
+- Exit codes follow `output-and-exit-codes.md`; 4 for not found, 5 for offline violation.
+
+## Determinism rules
+- Lists sorted by primary key then timestamp; group-by keeps stable ordering inside each bucket.
+- Timestamps UTC ISO-8601; hashes lower-case hex.
+
+## Offline/air-gap notes
+- Use cached snapshots (`--offline`) when remote Explorer is unavailable; commands must not attempt network calls in this mode.
+- Simulation must read local policy snapshots and subjects when offline.

docs/modules/cli/guides/configuration.md

@@ -0,0 +1,40 @@
+# stella CLI — Configuration
+
+## Precedence (highest → lowest)
+1. Command-line flags (e.g., `--output json`, `--offline`)
+2. Environment variables
+3. Config file (`config.yaml`/`config.json`) loaded from the first existing path:
+   - `$STELLA_CONFIG` (explicit override)
+   - `$XDG_CONFIG_HOME/stella/config.yaml` (or `%APPDATA%\\Stella\\config.yaml` on Windows)
+   - `$HOME/.config/stella/config.yaml`
+
+Tip: keep secrets in env vars, not in the config file; tokens are read from `STELLA_TOKEN`, registry creds from `STELLA_REGISTRY_AUTH`, etc.
+
+## Common settings (YAML example)
+```yaml
+output: json            # json|ndjson|table
+offline: true           # force no-network mode
+api:
+  baseUrl: https://console.stella.local
+  token: ${STELLA_TOKEN} # prefer env substitution
+policy:
+  tenant: demo-tenant
+  rationale: true
+airgap:
+  bundlesPath: /var/stella/bundles
+  trustRoots: /var/stella/trust/roots.pem
+observability:
+  traceparent: auto      # always inject trace headers when available
+```
+
+## Air-gap/offline knobs
+- `--offline` or `STELLA_OFFLINE=1` forbids network calls; commands must rely on local bundles/caches.
+- `airgap.bundlesPath` controls where imports/exports read/write sealed bundles.
+- Mirror/import/export commands respect `STELLA_TRUST_ROOTS` for DSSE/TUF verification.
+
+## Logging & telemetry
+- `STELLA_LOG_LEVEL=debug` for verbose logs; `trace` adds wire dumps (still deterministic).
+- Tracing headers: CLI injects `traceparent` when provided by the environment (CI runners, gateways); never emits PII.
+
+## Profiles (planned)
+- Profiles will live under `profiles/<name>.yaml` and can be selected with `--profile <name>`; until shipped, stick to the single default config file.

docs/modules/cli/guides/forensics.md

@@ -0,0 +1,32 @@
+# stella CLI — Forensics Guide
+
+## Commands
+- `stella forensic snapshot create --case <id> --output <path>`: capture current evidence snapshot; emits manifest + checksums.
+- `stella forensic verify --bundle <path>`: validate checksums, DSSE signatures, and timeline chain-of-custody.
+- `stella attest verify --file <attestation>`: reuse attestor flows for envelope verification (see `guides/commands/attest.md`).
+
+## Flags
+- `--offline`: prohibit network access; use local bundles only (exit code 5 if remote call would occur).
+- `--output json|table` (default json) for verification results.
+- `--trust-roots <file>`: PEM/TUF/DSSE trust roots for verification.
+
+## Outputs & exit codes
+- Success → 0; verification failure → 3; missing bundle → 4; offline violation → 5.
+- Verification output includes `status`, `checksum`, `signature`, `subject`, `rationale` fields; ordering is deterministic.
+
+## Determinism rules
+- Snapshots record UTC timestamps and stable file ordering; hashes are lowercase hex.
+- CLI never mutates evidence; it only validates and reports.
+
+## Offline/air-gap notes
+- Always supply trust roots from sealed media when in air-gap mode; no remote key fetch is allowed.
+- Store snapshots under a deterministic path (`case-id/date/`) to simplify audits.
+
+## Examples
+```bash
+# Create a snapshot for case ACME-123
+stella forensic snapshot create --case ACME-123 --output out/forensics/acme-123.tgz
+
+# Verify a snapshot with pinned trust roots
+stella forensic verify --bundle out/forensics/acme-123.tgz --trust-roots trust/roots.pem --output table
+```

docs/modules/cli/guides/observability.md

@@ -0,0 +1,32 @@
+# stella CLI — Observability Guide
+
+## Commands
+- `stella obs top` (planned): stream service health (SLO/burn-rate, queue depth, error rates) with table/JSON output.
+- `stella obs trace <trace_id>`: fetch correlated trace if server supports it; prints correlation/trace IDs.
+- `stella obs logs --from <ts> --to <ts> [--service <name>]`: pull logs for a window with pagination tokens.
+
+## Flags
+- `--output json|ndjson|table` (default: json).
+- `--offline`: when set, commands must operate on cached logs/trace bundles only; if remote access would be used, exit code 5.
+- `--page-size`, `--page-token`: deterministic pagination.
+
+## Output & exit codes
+- Exit codes follow `guides/output-and-exit-codes.md` (not found → 4; offline violation → 5).
+- Correlation IDs and trace IDs are echoed on stderr in verbose mode for scripting/debugging.
+
+## Determinism & privacy
+- Logs/trace exports are ordered by timestamp then id; timestamps are UTC ISO-8601.
+- CLI never redacts server-side; it only forwards what the API returns. Avoid printing secrets—use `--output json` with `jq` to filter locally.
+
+## Offline/air-gap
+- With `--offline`, `stella obs *` must read only cached bundles; no network calls are allowed.
+- For sealed environments, pass `--trust-roots <pem>` when verifying cached trace/log bundles.
+
+## Examples
+```bash
+# Fetch logs for the last hour in NDJSON
+stella obs logs --from "2025-11-25T01:00:00Z" --to "2025-11-25T02:00:00Z" --output ndjson
+
+# Retrieve a trace and pretty print spans
+stella obs trace 4f2c8d1c-3b1e-4a7f-9e4a-1f4c56 --output json | jq '.spans[0]'
+```

docs/modules/cli/guides/output-and-exit-codes.md

@@ -0,0 +1,34 @@
+# stella CLI — Output & Exit Codes
+
+## Output formats
+- `--output json` (default): deterministic JSON objects per record.
+- `--output ndjson`: one JSON object per line for streaming/large results.
+- `--output table`: aligned columns for humans; preserves stable column order.
+- Use `--quiet` to suppress informational logs; errors still print to stderr.
+
+## Exit codes (contract)
+- `0` — Success.
+- `1` — Generic error (unexpected exception).
+- `2` — Validation or user input error.
+- `3` — AuthN/AuthZ failure (expired token, missing scope).
+- `4` — Not found / resource missing.
+- `5` — Network disabled/offline violation when a command requires connectivity.
+- `10` — Retryable/transient error (service unavailable, backoff suggested).
+
+Clients and scripts should treat `2–5` as non-retryable unless input changes; only `10` should trigger automated retry with backoff.
+
+## Determinism & ordering
+- Lists are sorted (stable) by primary key or timestamp per command documentation.
+- Timestamps are UTC ISO-8601; hashes use hex lowercase.
+- Randomness is seeded; avoid machine-specific paths in emitted artefacts.
+
+## Examples
+```bash
+stella vuln list --output json | jq '.items[0]'
+stella export mirror --offline --output ndjson > mirror.ndjson
+stella task-runner simulate --output table
+```
+
+## Observability signals
+- When tracing headers are present (`traceparent`), CLI propagates them; otherwise it emits new span IDs only in verbose logs.
+- Metrics are not emitted by the CLI itself; servers capture request telemetry and can be correlated via the returned correlation/trace IDs printed on errors in verbose mode.

docs/modules/cli/guides/overview.md

@@ -0,0 +1,32 @@
+# stella CLI — Overview
+
+## What it does
+- Single entrypoint for scans, exports, policy management, VEX/Vuln queries, air-gapped kit operations, and task-runner interactions.
+- Evidence-preserving: the CLI never mutates upstream evidence; it emits signed manifests and deterministic JSON/NDJSON where possible.
+- Offline-ready: every command must run with cached feeds/bundles when `STELLA_OFFLINE=1` or `--offline` is set.
+
+## Core verbs (at a glance)
+- `stella scan ...` — container/dir scans; emits SBOM + findings bundles.
+- `stella policy ...` — push/eval/simulate policy bundles; attach evidence; request rationale.
+- `stella vex ...` / `stella vuln ...` — query VEX consensus and vulnerability projections with pagination/budgets.
+- `stella export ...` — mirror/export bundles; verify signatures; produce checksums/attestations.
+- `stella airgap ...` — import/export sealed bundles; validate trust roots; run without network.
+- `stella task-runner ...` — submit/inspect pack runs; stream logs; collect artefacts.
+
+## Imposed rules (apply to every command)
+- Determinism first: stable ordering, UTC ISO-8601 timestamps, no host-specific paths in outputs.
+- Aggregation-only: if a command shows advisory/VEX data, it must not infer verdicts beyond published evidence.
+- Offline/air-gap parity: every feature documents its offline flag(s) and expected cache locations.
+
+## Quick start
+```bash
+stella --help           # top-level verbs
+stella scan image ghcr.io/acme/app:1.2.3 --output json --offline
+stella policy eval --input policy.bundle.json --subject sbom.spdx.jsonl --explain
+stella export mirror --bundle out/mirror.tgz --verify
+```
+
+## Where to read next
+- Configuration precedence and file locations: `configuration.md`
+- Output formats and exit codes: `output-and-exit-codes.md`
+- Command-specific guides: see `cli-reference.md` and verb-specific guides under `guides/`.

docs/modules/cli/guides/parity-matrix.md

@@ -0,0 +1,19 @@
+# stella CLI — Parity Matrix
+
+Use this matrix to verify that CLI surfaces match the corresponding service APIs, schemas, and offline behaviours. Every row must stay deterministic and aggregation-only.
+
+| Area | Server/API | CLI command(s) | Output contract | Offline support | Notes |
+| --- | --- | --- | --- | --- | --- |
+| Policy eval/simulate | Policy Engine `/policy/eval` `/policy/simulate` | `stella policy eval`, `stella policy simulate` | Stable JSON/NDJSON; includes `correlationId`, `policyVersion`, `rationaleIds` | Must run with cached bundles when `--offline` | No verdict inference beyond engine response. |
+| VEX consensus | VexLens `/vex/consensus` | `stella vex consensus` | Deterministic pagination; weights/issuers/rationale echoed | Cached consensus snapshots permitted | Uses aggregation-only contract. |
+| Vulnerability list/detail | Vuln Explorer `/vuln` | `stella vuln list`, `stella vuln get` | Sorted by `vulnId`; includes provenance pointers; no missing fields inferred | Must respect `--offline` using cached snapshots | |
+| Export/mirror bundles | Export Service `/export/*` | `stella export mirror`, `stella export verify` | Emits manifest + checksums; verification errors are deterministic | Yes (air-gap bundles) | All paths must be relative and normalized. |
+| Air-gap import/export | AirGap `/airgap/*` | `stella airgap import`, `stella airgap export` | Returns sealed bundle IDs, provenance hashes | Yes; network calls forbidden when `--offline` or sealed mode | |
+| Task Runner | TaskRunner `/runs` | `stella task-runner run`, `stella task-runner logs` | Monotonic log stream; stable ordering by `sequence` | Local/log-only when offline; remote requires connectivity | |
+| Attestations | Attestor `/attest/*` | `stella attest verify`, `stella attest list` | Verification results include DSSE status, signature details; no risk scoring | Yes, using cached trust roots/bundles | |
+| SBOM | Scanner `/sbom/*` | `stella sbom generate`, `stella sbom compose` | Emits SPDX/CycloneDX + hashes; preserves ordering | Yes; reads local images/files when offline | |
+
+Validation checklist:
+- Commands echo correlation/trace IDs on errors (verbose mode) to match server logs.
+- Exit codes follow the contract in `output-and-exit-codes.md`.
+- When a server feature is unavailable offline, the CLI must fail with exit code 5 and an actionable message.