up

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