work

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/`.