up

docs/cli/cli-reference.md

@@ -152,6 +152,8 @@ Replays the AOC guard against stored raw documents. By default it checks all adv
 | `--tenant <tenant-id>` | Overrides tenant context. Required for cross-tenant verifications when run by platform operators. |
 | `--no-color` | Disables ANSI colours. |
 
+`table` mode prints a summary showing the active tenant, evaluated window, counts of checked advisories/VEX statements, the active limit, total writes/violations, and whether the page was truncated. Status is colour-coded as `ok`, `violations`, or `truncated`. When violations exist the detail table lists the code, total occurrences, first sample document (`source` + `documentId` + `contentHash`), and JSON pointer path.
+
 ### 3.4 Report structure (JSON)
 
 ```json
@@ -182,7 +184,8 @@ Replays the AOC guard against stored raw documents. By default it checks all adv
   "metrics": {
     "ingestion_write_total": 557,
     "aoc_violation_total": 2
-  }
+  },
+  "truncated": false
 }
 ```
 
@@ -262,6 +265,24 @@ Use these codes in CI to map outcomes to build statuses or alert severities.
 
 ---
 
+## 4 · `stella vuln observations` (Overlay paging)
+
+`stella vuln observations` lists raw advisory observations for downstream overlays (Graph Explorer, Policy simulations, Console). Large tenants can now page through results deterministically.
+
+| Option | Description |
+|--------|-------------|
+| `--limit <count>` | Caps the number of observations returned in a single call. Defaults to `200`; values above `500` are clamped server-side. |
+| `--cursor <token>` | Opaque continuation token produced by the previous page (`nextCursor` in JSON output). Pass it back to resume iteration. |
+
+Additional notes:
+
+- Table mode prints a hint when `hasMore` is `true`:  
+  `[yellow]More observations available. Continue with --cursor <token>[/]`.
+- JSON mode returns `nextCursor` and `hasMore` alongside the observation list so automation can loop until `hasMore` is `false`.
+- Supplying a non-positive limit falls back to the default (`200`). Invalid/expired cursors yield `400 Bad Request`; restart without `--cursor` to begin a fresh iteration.
+
+---
+
 ## 5 · Related references
 
 - [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md)
@@ -282,4 +303,14 @@ Use these codes in CI to map outcomes to build statuses or alert severities.
 
 ---
 
-*Last updated: 2025-10-26 (Sprint 19).* 
+*Last updated: 2025-10-29 (Sprint 24).*
+
+## 13. Authority configuration quick reference
+
+| Setting | Purpose | How to set |
+|---------|---------|------------|
+| `StellaOps:Authority:OperatorReason` | Incident/change description recorded with `orch:operate` tokens. | CLI flag `--Authority:OperatorReason=...` or env `STELLAOPS_ORCH_REASON`. |
+| `StellaOps:Authority:OperatorTicket` | Change/incident ticket reference paired with orchestrator control actions. | CLI flag `--Authority:OperatorTicket=...` or env `STELLAOPS_ORCH_TICKET`. |
+
+> Tokens requesting `orch:operate` will fail with `invalid_request` unless both values are present. Choose concise strings (≤256 chars for reason, ≤128 chars for ticket) and avoid sensitive data.
+

docs/cli/policy.md

@@ -3,6 +3,7 @@
 > **Audience:** Policy authors, reviewers, operators, and CI engineers using the `stella` CLI to interact with Policy Engine.  
 > **Supported from:** `stella` CLI ≥ 0.20.0 (Policy Engine v2 sprint line).  
 > **Prerequisites:** Authority-issued bearer token with the scopes noted per command (export `STELLA_TOKEN` or pass `--token`).
+> **2025-10-27 scope update:** CLI/CI tokens issued prior to Sprint 23 (AUTH-POLICY-23-001) must drop `policy:write`/`policy:submit`/`policy:edit` and instead request `policy:read`, `policy:author`, `policy:review`, and `policy:simulate` (plus `policy:approve`/`policy:operate`/`policy:activate` for promotion pipelines).
 
 ---
 
@@ -129,6 +130,23 @@ stella policy activate P-7 --version 4 --run-now --priority high
 - Optional `--scheduled-at 2025-10-27T02:00:00Z`.
 - Requires `policy:activate` and `policy:run`.
 
+**Options**
+
+- `--version <number>` (required) – target revision to promote.
+- `--note <text>` – record an activation note alongside the approval.
+- `--run-now` – enqueue an immediate full run after activation.
+- `--scheduled-at <timestamp>` – schedule activation for a specific UTC time (ISO-8601 format).
+- `--priority <label>` – optional scheduling priority hint (`low`, `standard`, `high`).
+- `--rollback` – mark the activation as a rollback of a previously active version.
+- `--incident <id>` – associate the activation with an incident identifier.
+
+**Exit codes**
+
+| Code | Meaning |
+|------|---------|
+| `0` | Activation completed (or policy already active). |
+| `75` | Activation recorded but awaiting a second approver. |
+
 ### 3.5 Archive / Rollback
 
 ```
@@ -226,6 +244,8 @@ Replay downloads sealed bundle for deterministic verification.
 stella findings ls --policy P-7 \
   --sbom sbom:S-42 \
   --status affected --severity High,Critical \
+  --since 2025-10-01T00:00:00Z \
+  --page 2 --page-size 100 \
   --format table
 ```
 
@@ -233,18 +253,25 @@ Common flags:
 
 | Flag | Description |
 |------|-------------|
-| `--page`, `--page-size` | Pagination (default page size 50). |
-| `--cursor` | Use cursor token from previous call. |
-| `--since` | ISO timestamp filter. |
+| `--sbom` | Repeatable filter for SBOM identifiers. |
+| `--status` | Repeatable filter (`affected`, `quieted`, `mitigated`, `not_affected`, etc.). |
+| `--severity` | Repeatable filter using normalized labels (`Critical`, `High`, `Medium`, `Low`, `Unknown`). |
+| `--since` | Return findings updated on/after the ISO-8601 timestamp. |
+| `--cursor` | Resume listing using the opaque token from a prior page. |
+| `--page`, `--page-size` | Page-based pagination (page >=1, size <=500; falls back to backend defaults). |
+| `--output` | Persist JSON payload to disk (implied JSON rendering). |
+| `--format` | `table` (default for TTY) or `json`. |
 
 ### 5.2 Fetch Explain
 
 ```
-stella findings explain --policy P-7 --finding P-7:S-42:pkg:npm/lodash@4.17.21:CVE-2021-23337 \
+stella findings explain --policy P-7 \
+  P-7:S-42:pkg:npm/lodash@4.17.21:CVE-2021-23337 \
+  --mode verbose \
   --format json --output explains/lodash.json
 ```
 
-Outputs ordered rule hits, inputs, and sealed-mode hints.
+Outputs ordered rule hits, inputs, evidence snapshots, and sealed-mode hints. Supported `--mode` values mirror API contracts (for example `summary`, `verbose`); omit to use backend default.
 
 ---