work

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.