@maind-dev/cli 0.4.0 → 0.6.1

package/README.md

@@ -55,11 +55,61 @@ Writes two artifacts (defaults shown):
 | `--run-ref <id>` | `$GITHUB_RUN_ID` | Build identifier stored in the manifest |
 | `--mcp-url <url>` | `$MAIND_MCP_URL` or prod | MCP endpoint override |
 
+## Review (`maind review`)
+
+Provenance-backed review findings for a change set (ADR-228). The CLI links the
+code-index engine directly — no bridge needed in CI: it enumerates hunk-graded
+changed symbols + closed-enum risk flags **locally**, sends only symbol names and
+counts to the maind `review_changes` tool (paths, lines, and diff content never
+leave the machine), and renders the citable findings (convention id + version +
+matched symbols).
+
+```bash
+maind review --base origin/main --comment
+```
+
+Artifacts (defaults shown):
+
+| File | Purpose |
+|---|---|
+| `.maind/review.md` | Full findings report — always written, even fail-open |
+| `.maind/review.json` | Review manifest (`maind.review.manifest/v1`) — counts, citations, served attribution |
+| `.maind/review-comment.md` | With `--comment`: PR-comment markdown; line 1 carries the `<!-- maind-review -->` idempotency marker |
+
+The CLI never posts the comment itself — your workflow posts the file via
+`gh api`, so provider tokens stay outside the CLI.
+
+### Review options
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--base <ref>` | — | Review the diff against this ref; without it, uncommitted work |
+| `--uncommitted` | off | With `--base`: also include uncommitted changes |
+| `--summary <text>` | — | Prose change summary (enables index-less review) |
+| `--out <path>` | `.maind/review.md` | Report path (manifest lands next to it as `.json`) |
+| `--comment [<path>]` | off | Also write PR-comment markdown |
+| `--json` | off | Print the review manifest JSON to stdout |
+| `--gate` | off | Server-side `pass\|warn\|block` verdict (Team plan) |
+| `--fail-on block\|warn` | — | With `--gate`: exit `1` when the verdict crosses the threshold |
+| `--strict` | off | Infra errors exit `2` instead of failing open |
+| `--project-key <hex>` | auto | Repo `project_key` override |
+| `--mcp-url <url>` | `$MAIND_MCP_URL` or prod | MCP endpoint override |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Advisory run (default) — findings never fail a build; plan-gate on `--gate` also exits `0` with a hint |
+| `1` | Only a server verdict crossing `--fail-on` (requires `--gate`) |
+| `2` | Infra error, only under `--strict` |
+
 ## Fail-open contract
 
 A context pull must never fail a build. On any error (missing key, network,
 auth) the CLI still writes explanatory artifacts (the manifest carries an
 `error` field) and exits `0`. The agent simply runs without extra context.
+`maind review` follows the same contract: advisory runs exit `0` no matter
+what; only the explicit `--gate` + `--fail-on` combination is fail-closed.
 
 ## Example: GitHub Actions