synergy moats product advisory implementations

docs/modules/cli/guides/commands/reference.md

@@ -13,6 +13,7 @@ graph TD
     CLI --> ADMIN[Administration]
     CLI --> AUTH[Authentication]
     CLI --> POLICY[Policy Management]
+    CLI --> EXPLAIN[Explainability]
     CLI --> VEX[VEX & Decisioning]
     CLI --> SBOM[SBOM Operations]
     CLI --> REPORT[Reporting & Export]
@@ -914,6 +915,73 @@ Platform: linux-x64
 
 ---
 
+## Explainability Commands
+
+### stella explain block
+
+Explain why an artifact was blocked by policy gates. Produces deterministic trace with referenced evidence artifacts.
+
+**Sprint:** SPRINT_20260117_026_CLI_why_blocked_command
+**Moat Reference:** M2 (Explainability with proof, not narrative)
+
+**Usage:**
+```bash
+stella explain block <digest> [options]
+```
+
+**Arguments:**
+- `<digest>` - Artifact digest (`sha256:abc123...`, raw hex, or OCI reference)
+
+**Options:**
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--format <format>` | Output format: `table`, `json`, `markdown` | `table` |
+| `--show-evidence` | Include full evidence artifact details | false |
+| `--show-trace` | Include policy evaluation trace | false |
+| `--replay-token` | Include replay token in output | false |
+| `--output <path>` | Write to file instead of stdout | stdout |
+| `--offline` | Query local verdict cache only | false |
+
+**Examples:**
+```bash
+# Basic explanation
+stella explain block sha256:abc123def456...
+
+# JSON output for CI/CD
+stella explain block sha256:abc123... --format json --output reason.json
+
+# Full explanation with evidence and trace
+stella explain block sha256:abc123... --show-evidence --show-trace
+
+# Markdown for PR comment
+stella explain block sha256:abc123... --format markdown | gh pr comment 123 --body-file -
+```
+
+**Exit Codes:**
+- `0` - Artifact is NOT blocked (all gates passed)
+- `1` - Artifact IS blocked
+- `2` - Error (not found, API error)
+
+**Output (table):**
+```
+Artifact: sha256:abc123def456789012345678901234567890123456789012345678901234
+Status: BLOCKED
+
+Gate: VexTrust
+Reason: Trust score below threshold (0.45 < 0.70)
+Suggestion: Obtain VEX statement from trusted issuer
+
+Evidence:
+  [VEX   ] vex:sha256:de...23  vendor-x  2026-01-15T10:00:00Z
+  [REACH ] reach:sha256...56   static    2026-01-15T09:55:00Z
+
+Replay: stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000
+```
+
+**See Also:** [Explain Commands Documentation](explain.md)
+
+---
+
 ## Additional Commands
 
 ### stella vuln query