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.