devrites 3.0.4 → 3.0.6

package/docs/architecture.md

@@ -1,9 +1,11 @@
-# DevRites Architecture
+# DevRites architecture
 
-DevRites is a **distributed but coordinated** set of project-local Claude Code skills
-that make an AI coding agent behave like a disciplined senior engineer: clarify →
-spec+plan → build one verified slice → prove with evidence → polish → review → seal →
-ship.
+DevRites is a **distributed but coordinated** set of project-local Claude Code
+and Codex skill surfaces backed by one Go control plane. It makes an AI coding
+agent behave like a disciplined senior engineer: frame → spec → optional temper
+→ define → mandatory vet → build one verified slice → prove with evidence →
+polish → review → seal → ship. `converge` is the recovery state when live code
+and recorded intent need to meet again.
 
 For the `.devrites/` load order, file budgets, artifact schema, aliases,
 traceability rules, and phase-relative completeness model, see
@@ -11,20 +13,25 @@ traceability rules, and phase-relative completeness model, see
 
 ## Layers
 
-1. **Public workflow skills** — `.claude/skills/rite-*`, `user-invocable: true`. Each
-   owns exactly one phase and reads/writes the `.devrites/` workspace.
-   Sequence: `rite-spec`, `rite-define`, `rite-plan`, `rite-build`,
-   `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`, `rite-ship`,
-   plus the read-only `rite-status`, the resume verb `rite-resolve` (answer
-   a HITL gate and clear `Awaiting human`), and the thin `/rite` menu.
+1. **Public lifecycle and workspace skills**: `.claude/skills/rite-*`,
+   `user-invocable: true`. Each owns one bounded phase or workspace transition.
+   Sequence: `rite-spec`, optional `rite-temper`, `rite-define`, mandatory
+   `rite-vet`, `rite-build`, recovery `rite-converge`, `rite-prove`,
+   `rite-polish`, `rite-review`, `rite-seal`, `rite-ship`; `rite-plan` repairs
+   or reslices an active plan,
+   plus the resume verb `rite-resolve` (answer a HITL gate and clear
+   `Awaiting human`). The thin `/rite` menu and read-only `rite-status` live in
+   the public utility layer below.
    `/rite-seal` **decides** GO/NO-GO and writes the verdict to `seal.md`;
-   `/rite-ship` is the eighth lifecycle phase that **executes** the
+   `/rite-ship` is the eighth core lifecycle rite that **executes** the
    irreversible git ladder and **closes** the task (archives the workspace,
    clears `ACTIVE`). Keeping the decision and the irreversible action as two
    separately-auditable steps is the point.
-2. **Public utility skills** — `.claude/skills/rite-zoom-out`,
-   `rite-prototype`, `rite-handoff`, `rite-pressure-test`, `rite-pov`,
-   `rite-dogfood`, `rite-pr-feedback`, and `rite-autocomplete` — public commands. `rite-autocomplete` is the
+2. **Public utility and on-ramp skills**: `rite-adopt`, `rite-quick`,
+   `rite-frame`, `rite-status`, `rite-doctor`, `rite-learn`, `rite-explain`,
+   `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
+   `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, and
+   `rite-autocomplete`. These are public commands. `rite-autocomplete` is the
    unattended orchestrator: it drives the whole lifecycle (spec → … → seal →
    ship) end-to-end, choosing the best option at each soft gate, pausing only
    on hard irreversible-risk / blocking / escalating gates or a NO-GO. The
@@ -32,36 +39,37 @@ traceability rules, and phase-relative completeness model, see
    Claude Code skill names like `prototype`, `handoff`, `triage`, `diagnose`),
    not a visibility marker; `rite-pressure-test` carries no prefix because it
    doesn't collide.
-3. **Internal specialist skills** — `.claude/skills/devrites-*` with
+3. **Internal specialist skills**: `.claude/skills/devrites-*` with
    `user-invocable: false`: `devrites-interview`, `-source-driven`,
    `-doubt`, `-ux-shape` (plans UX/UI into `design-brief.md` at `/rite-spec`),
    `-frontend-craft`, `-browser-proof`, `-debug-recovery`,
    `-api-interface`, `-audit` (dispatches the security / perf / simplify
-   reviewer subagent on an axis argument). Model-invoked by public skills
-   or Claude's auto-selection; not menu noise. Whether a skill is public or
+   reviewer subagent on an axis argument), `-prose-craft`, and
+   `-refresh-indexes`. These 11 specialists are model-invoked by public skills
+   or host auto-selection; not menu noise. Whether a skill is public or
    internal is governed by the `user-invocable:` flag, not by the name
    prefix.
 
    Engineering rules live at `.claude/skills/devrites-lib/reference/standards/`.
    Workspace-operating lifecycle rites load `core.md` first and disclose phase-specific
-   files on demand; compact utilities keep a narrower local contract. Parallel reviewer fan-out at
-   `/rite-seal` is a reference file
-   (`rite-seal/reference/parallel-dispatch.md`), not a skill.
-4. **Supporting references** — `reference/*.md` inside each skill. Long checklists,
+   files on demand; compact utilities keep a narrower local contract. Parallel
+   reviewer fan-out at `/rite-seal` is the shared reference file
+   `devrites-lib/reference/parallel-dispatch.md`, not a skill.
+4. **Supporting references**: `reference/*.md` inside each skill. Long checklists,
    templates, and anti-rationalization tables loaded on demand (progressive
    disclosure) so `SKILL.md` bodies stay small.
-5. **Agents** — `.claude/agents/devrites-*` fresh-context subagents: **13 read-only + 1
-   write-capable**. The read-only set is twelve reviewers — the post-build fan-out used by
+5. **Agents**: `.claude/agents/devrites-*` fresh-context subagents: **13 read-only + 1
+   write-capable**. The read-only set is twelve reviewers: the post-build fan-out used by
    `/rite-seal` and the doubt loop (`devrites-spec-reviewer`, `-code-reviewer`, `-test-analyst`,
    `-frontend-reviewer`, `-security-auditor`, `-performance-reviewer`, `-devex-reviewer`,
    `-doubt-reviewer`, `-simplifier-reviewer`), the **pre-plan** `devrites-strategy-reviewer`
    (`/rite-temper`), the **pre-build** `devrites-plan-reviewer` (`/rite-vet`), and the
    **build-time** `devrites-forge-judge` (scores competing candidate builds on a `Forge: yes`
-   slice) — plus the cross-feature `devrites-retrospector` (mines the shipped archive at
+   slice), plus the cross-feature `devrites-retrospector` (mines the shipped archive at
    `/rite-ship` close). The one **write-capable** executor, `devrites-slice-wright`, is
    dispatched by `/rite-build` to write one slice in a clean context (the write-side mirror of
    the reviewers).
-6. **Engineering rules** — DevRites' own stack-agnostic rules installed to
+6. **Engineering rules**: DevRites' own stack-agnostic rules installed to
    `.claude/skills/devrites-lib/reference/standards/`. Workspace-operating lifecycle
    skills read `core.md` in step 0; compact utilities load only their local or conditional
    rules. On-demand files load by the phase that needs them:
@@ -88,8 +96,8 @@ capabilities belong.
 ## Design rationale
 
 ### Why the engine owns shared orientation (`devrites-lib`)
-Every workspace-operating skill's first move is the same: orient on the active feature —
-slug, phase, artifacts present, run mode, open-question tally — before acting. Re-deriving
+Every workspace-operating skill starts by reading the active feature's slug,
+phase, present artifacts, run mode, and open-question tally. Re-deriving
 that from raw Markdown in each skill was duplicated (step-0 prose across ~20 skills),
 token-heavy (counting open gates meant re-reading the append-only `questions.md`, which
 only grows), and error-prone (a missed AFK sentinel or a miscounted gate changes behavior).
@@ -131,23 +139,26 @@ Built-in / bundled Claude Code commands include `/plan`, `/review`, `/run`, `/ve
 `rite-` prefix avoids all of them. (Collision audit: `research/claude-code-skills-notes.md`.)
 
 ### Why a thin menu skill, not a mega-router
-`/rite` is **only** an entrypoint: it shows a compact phase-grouped menu, prints live
-`.devrites/ACTIVE` status via `` !`cmd` `` injection, and suggests the next command.
-It deliberately does **not** execute workflows or duplicate skill logic — that would
-recreate the mega-command problem. DevRites keeps selection thin and lets each phase
-own its context, rather than centralizing every workflow behind one command.
+`/rite` is **only** an entrypoint: it shows a compact phase-grouped menu, prints
+recommended-start guidance from `devrites-engine first-task`, and dispatches a
+named verb to its owning skill. Menu mode does not read raw workspace state;
+`/rite-status` owns detailed status. `/rite` deliberately does **not** duplicate
+workflow logic. Doing so would recreate the mega-command problem. DevRites keeps
+selection thin and lets each phase own its context.
 
 ### Why internal skills exist
 Specialist processes (doubt, source-driven, frontend craft, browser proof, audits)
-are **disciplines**, not user commands. As `user-invocable: false` skills they:
+are **disciplines**, not user commands. As `user-invocable: false` specialist
+skills they:
 - stay out of the command menu (less cognitive load);
-- are invoked automatically by Claude or explicitly by a public skill when their
+- are invoked automatically by the host model or explicitly by a public skill when their
   trigger conditions hit;
 - keep each public `SKILL.md` small by housing the heavy process elsewhere.
 
 ### Why spec, architecture, plan, tasks, and traceability are separate artifacts
-Doing investigation, spec, plan, and slicing in one batch lets things slip — a gap goes
-unasked, placement is guessed, a slice misses a requirement. DevRites splits them so each
+Combining investigation, specification, planning, and slicing makes it easier
+to miss a question, guess at placement, or leave a requirement out of a slice.
+DevRites splits them so each
 is focused and gated. `/rite-spec` **investigates deeply and writes `spec.md`** (product
 what/why, requirements, acceptance, non-goals, measurable success) and must pass its
 readiness gate. `/rite-define` then turns that **approved spec** into `architecture.md`
@@ -158,45 +169,46 @@ is the separate repair/reslice/re-order tool for an *active* plan when it goes s
 drifts.
 
 ### Why `/rite-polish` is one skill with two progressive-disclosure halves
-Polish has two natural halves — **code** (simplify, dead code, naming, plus
+Polish has two natural halves: **code** (simplify, dead code, naming, plus
 backend if BE was touched) and **UI** (normalize to the design system, then
 ship-quality detail). The earlier design split them into `rite-polish-code`
 and `rite-polish-ui` sub-skills, but a skill-on-skill dispatch is fragile
 (the caller has to re-discover the callee by description) and the two halves
 share the same operating rules. They now live as `reference/code.md` and
 `reference/ui.md` inside the same skill, loaded only when their phase
-trigger fires — the canonical progressive-disclosure pattern from
-<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>.
+trigger fires. This follows the supporting-files pattern from Claude Code's current
+[skills reference](https://code.claude.com/docs/en/slash-commands#add-supporting-files).
 `/rite-polish` is the orchestrator: always reads `reference/code.md`
 (Phase 1 + 2), detects UI scope from the diff and reads `reference/ui.md`
 (Phase 3 + 4) when needed. The orchestrator accepts mode tokens (`bolder`,
 `quieter`, `distill`, `harden`, `normalize-only`) that pass through to
 Phase 4.
 
-Normalization remains the entry gate of UI polish — polishing UI that hasn't
-been aligned to the project's design system is "decoration on drift," and
-the UI reference refuses to run Phase 4 before Phase 3.
+Normalization remains the entry gate for UI polish. The UI reference refuses
+to run Phase 4 before Phase 3 because detail work would otherwise reinforce
+patterns that do not match the project's design system.
 
 ### Why seal and ship are separate phases (`/rite-seal`, `/rite-ship`)
-Deciding "is this safe to ship" and *actually shipping* are different acts with
+Deciding "is this safe to ship" and *shipping it* are different acts with
 different blast radii. `/rite-seal` is a **pure decision gate**: it walks acceptance
 against evidence, fans out the fresh-context reviewers, and writes the GO / NO-GO
-verdict to `seal.md` — it runs no git. On GO it sets `state.md` `Next step:
-/rite-ship` and stops. `/rite-ship` is the eighth lifecycle phase: it refuses to run
+verdict to `seal.md` and runs no git. On GO it sets `state.md` `Next step:
+/rite-ship` and stops. `/rite-ship` is the eighth core lifecycle rite: it refuses to run
 without a GO recorded in `seal.md`, renders the type-`GO` prompt, runs the irreversible
 git ladder (commit → push → tag/PR per the project's convention), writes `ship.md`,
-then **closes the task** — sets phase `done` and archives `.devrites/work/<slug>/` →
+then **closes the task** by setting phase `done` and archiving `.devrites/work/<slug>/` →
 `.devrites/archive/<slug>/` (every `.md` preserved, never deleted) and clears
 `.devrites/ACTIVE`. A GO seal is a verdict, not an authorization to push; keeping the
 decision and the irreversible action as two separately-auditable steps is the point.
 
 ### Why `/rite-autocomplete` exists (the unattended orchestrator)
 Some features are routine enough to run end-to-end without per-phase human iteration.
-`/rite-autocomplete` drives the whole lifecycle (spec → define → build×N → prove →
-polish → review → seal → ship) by reading each phase's `SKILL.md` and executing its
+`/rite-autocomplete` drives the whole lifecycle (spec → temper → define → vet →
+build×N → prove → polish → review → seal → ship) by reading each phase's
+`SKILL.md` and executing its
 workflow, carrying state through the workspace files rather than chat. A vague prompt
-triggers an up-front `devrites-interview` — the only interactive window — after which it
-runs unattended, choosing the best option at each soft gate and recording the rationale
+triggers an up-front `devrites-interview`, which is the only interactive window.
+After that it runs unattended, choosing the best option at each soft gate and recording the rationale
 in `decisions.md`. It does **not** weaken the safety gates: hard irreversible-risk
 (auth / migration / public-API / red tests), blocking / escalating gates, an open
 `gate: validating`, a NO-GO, exhausted `max_slices`, or low confidence all still pause.
@@ -204,58 +216,60 @@ By default it stops at the final type-`GO`; the `--ship` flag (alias `--yolo`)
 auto-confirms it for a zero-touch push.
 
 ### Why persistent `.devrites/` state
-Long features outlive a single context window. Durable Markdown (spec/plan/tasks/
-state/evidence/drift/decisions) lets any phase — in any session, after any compaction
-— reload exactly where work stands. This is the main thing DevRites adds over typical
+Long features outlive a single context window. Durable Markdown for the spec,
+plan, tasks, state, evidence, drift, and decisions lets any phase reload the
+current position in any session, even after compaction. This is the main thing DevRites adds over typical
 session-scoped workflows, which don't persist feature state.
 
-### Run modes — HITL & AFK
+### Run modes: HITL & AFK
 
 DevRites runs the same lifecycle two ways, configured at two levels:
 
-- **Per-slice** (planning-time) — each `tasks.md` slice declares `Mode: AFK | HITL`.
+- **Per-slice** (planning-time): each `tasks.md` slice declares `Mode: AFK | HITL`.
   HITL slices add `Gate: advisory | validating | blocking | escalating`, `SLA`, and
   `Checkpoint` so the agent knows how disruptive the pause should be.
-- **Per-session** (run-time) — the presence of `.devrites/AFK` flips the session-level
+- **Per-session** (run-time): the presence of `.devrites/AFK` flips the session-level
   default. Empty file = AFK with safe defaults; YAML body widens behavior
   (`max_slices`, `notify`, `allow_gates`).
 
-The pause primitive is a **pre-action interrupt**, not a post-action review queue —
-inspired by LangGraph's `interrupt()` / `Command(resume=)` model. `/rite-build` writes
+The pause primitive is a **pre-action interrupt**, not a post-action review queue.
+It follows LangGraph's `interrupt()` / `Command(resume=)` model. `/rite-build` writes
 an `Awaiting human` block to `state.md` and a question to `questions.md`, then stops.
 `/rite-resolve` is the canonical resume verb. Restarting a session reads the workspace
 back into a consistent state because the pause is durable Markdown, not chat memory.
 
 Why a four-gate taxonomy (instead of a single "ask the user" pause): a single gate
 becomes a queue under load. Mixing `advisory` (audit-only log) with `validating`
-(async — build continues, merge blocks) and reserving `blocking` for synchronous halts
-keeps the loop alive when the answer can wait, and pauses hard when it can't. The
-"AFK never silently accepts irreversible risk" rule — destructive migrations,
-auth/authz boundaries, public API breaks, red tests/types/lint — always pauses
-regardless of the sentinel. See
+(async: build continues, merge blocks) and reserving `blocking` for synchronous halts
+keeps the loop alive when the answer can wait, and pauses hard when it cannot.
+AFK always pauses for destructive migrations, auth/authz boundaries, public API
+breaks, and failed tests, type checks, or lint, regardless of the sentinel. See
 [`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md) for the full
 contract.
 
 ## Design choices at a glance
 
-- **Surface**: 29 public `rite-*` skills (42 total) — the thin `/rite` menu
+- **Surface**: 29 public `rite-*` skills (42 total): the thin `/rite` menu
   (carries the routing) + 8 lifecycle phases (`rite-spec`, `rite-define`,
   `rite-build`, `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`,
-  `rite-ship` — seal **decides**, ship **executes + closes**) + the
+  `rite-ship`: seal **decides**, ship **executes + closes**) + the
   `rite-temper` (strategic, optional) and `rite-vet` (engineering, every plan)
   reviews + the `rite-quick` express lane and `rite-frame` pre-flight/self-audit
   lens + `rite-adopt` (onboard an existing codebase) + `rite-learn` (cross-feature
   lessons) + `rite-status` + `rite-doctor` (install health) +
   `rite-customize` (project-local overrides/extensions) +
+  `rite-explain` (grounded concept/diff/idea/recap explanation) +
   `rite-pov` (external-option verdicts) + `rite-dogfood` (browser QA) +
   `rite-pr-feedback` (review-thread closure) +
-  the `rite-plan` replan verb + the `rite-resolve` resume verb + 4 ideation /
+  the `rite-plan` replan verb + `rite-converge` recovery + the `rite-resolve`
+  resume verb + 4 ideation /
   handoff utilities (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
   `rite-pressure-test`) + `rite-autocomplete` (the unattended full-lifecycle
-  orchestrator) — plus 11 internal model-invoked `devrites-*` specialists and the
+  orchestrator), plus 11 internal model-invoked `devrites-*` specialists and the
   `devrites-lib` library, not one mega-command. The `devrites-` prefix is a
-  namespace (collision avoidance), not a public/internal marker —
-  `user-invocable:` is. All `devrites-*` skills are model-invoked.
+  namespace (collision avoidance), not a public/internal marker.
+  `user-invocable:` is. The 11 specialists are model-invoked;
+  `devrites-lib` explicitly disables model invocation.
 - **Selection**: the `/rite` menu skill carries the routing table; every
   workflow skill enforces a "right skill, right time" rule in its body.
 - **State**: durable `.devrites/` Markdown that survives compaction and new sessions.
@@ -264,24 +278,25 @@ contract.
 - **Run modes**: same lifecycle runs HITL (default; pause at typed gate) or AFK
   (drop `.devrites/AFK`; loop continues, discretionary pauses downgrade to
   advisory log, irreversible risk always pauses).
-- **Slice rule**: build **one vertical slice, then stop** — no auto-continue.
+- **Slice rule**: build **one vertical slice, then stop**. There is no automatic continuation.
 - **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
 - **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
-- **Review**: **feature-scoped** five-axis review with severity labels + fresh-context
-  subagents at the seal.
-- **Scope**: clarify → seal (decide) → ship (the irreversible git ladder —
-  commit → push → tag/PR — per the project's own convention) → close; the CI
+- **Review**: **feature-scoped** multi-axis review with severity labels +
+  fresh-context subagents at the seal.
+- **Scope**: clarify → seal (decide) → ship (commit → push → tag or PR,
+  following the project's convention) → close. The CI
   pipeline stays with the project.
-- **Install**: project-local, manifest-managed; ships DevRites' own engineering rules.
+- **Install**: project-local, manifest-managed host artifacts; the optional
+  shared engine binary is the sole sanctioned global artifact.
 
 ## Deviations from the original build brief (and why)
 
-1. **`user-invocable` semantics corrected from the docs.** The brief said set
-   `user-invocable: true` for public and `false` for internal. That is exactly right
-   for internal skills. For public skills we keep them model-invocable (no
-   `disable-model-invocation`) so phases can hand off and the selector can route;
-   per-phase side-effect discipline (e.g. "stop after one slice") is enforced in the
-   skill **body**, which is the correct mechanism (invocation flags can't express it).
+1. **Invocation semantics are explicit in frontmatter.** `user-invocable`
+   controls whether a skill is a public command; `disable-model-invocation`
+   independently marks explicit-only public utilities and the internal
+   `devrites-lib` library. Model-invocable phases can still hand off and route;
+   per-phase side-effect discipline (for example, "stop after one slice") is
+   enforced in the skill **body**, because invocation flags cannot express it.
 2. **`context: fork` used selectively.** Verified it is a real field (isolated
    subagent, body-as-prompt, no conversation history). It is applied only to the three
    self-contained read-only audit skills (`devrites-audit simplify`,
@@ -298,6 +313,7 @@ acceptance criteria.
 ## Repository layout
 
 See the top-level tree in `README.md` and the installed-target tree in `usage.md`.
-Source pack lives under `pack/.claude/` (skills, agents, and rules); the installer copies
-it into a target project's `.claude/`, including DevRites' engineering rules in
-`.claude/skills/devrites-lib/reference/standards/`.
+The canonical source pack lives under `pack/.claude/` (skills, agents, rules,
+and Claude hook wiring). The build renders `pack/generated/` host artifacts;
+the installer writes Claude assets under project `.claude/` and Codex assets
+under `.agents/`, `.codex/`, and the managed `AGENTS.md` block.

package/docs/capability-surface-selection.md

@@ -12,7 +12,9 @@ Pick the smallest surface that keeps the behavior deterministic:
 
 Rules:
 
-- Install and update through npm: `npx devrites ...`. No Claude/Codex plugin path.
+- npm (`npx devrites ...`) is the canonical distribution path. The supported
+  `curl | bash` bootstrap exists for environments without Node; neither path is
+  a Claude/Codex plugin or marketplace install.
 - Prefer the engine for gates; prompts may call gates, not reimplement them.
 - Prefer scripts for repo-local release/build glue that is not part of the user contract.
 - Do not add a dependency for what the Go engine or shell can do in a few lines.

package/docs/cli.md

@@ -1,14 +1,17 @@
-# Tool-agnostic state core — the `devrites-engine` CLI
+# Tool-agnostic state core: the `devrites-engine` CLI
 
-DevRites' discipline lives in `.devrites/` Markdown files and the `devrites-engine`
-engine binary, not in one chat harness. Any tool — Claude Code, Codex, Cursor,
-Gemini CLI, CI, or a human — can drive the same deterministic gates from the
-project root.
+DevRites stores its workflow in `.devrites/` Markdown files and the
+`devrites-engine` binary rather than tying it to one chat harness. Claude Code,
+Codex, Cursor, Gemini CLI, CI, and human operators can all run the same
+deterministic gates from the project root.
 
 ## The `devrites-engine` CLI
 
 Install DevRites normally, then run the engine from the project root:
 
+The examples below are a curated working set. `devrites-engine help` is the
+exhaustive current command and hook inventory.
+
 ```bash
 devrites-engine preamble                 # workspace digest for the active feature
 devrites-engine snapshot [slug]          # machine-readable workspace/status snapshot
@@ -16,11 +19,13 @@ devrites-engine build-readiness [slug]   # build-readiness gate      (exit 0 rea
 devrites-engine evidence-fresh [slug]    # proof freshness gate      (exit 0 fresh · 3 stale)
 devrites-engine check-acceptance <dir>   # acceptance gate           (exit 0 proven · 1 gap)
 devrites-engine ledger sync <dir>        # fold a feature's spec deltas into the living capability ledger
-devrites-engine ledger list|show <cap>   # read the ledger — what the system already does
+devrites-engine ledger list|show <cap>   # read the ledger: what the system already does
 devrites-engine context show --json      # report root, active workspace, and host command forms
 devrites-engine timeline log|list        # append/list session events, decisions, and state moves
-devrites-engine health record|list       # append/list compact workspace health history
+devrites-engine health run               # run known project checks + record a code-health dashboard
+devrites-engine health record|list       # append/list manual or dashboard health history
 devrites-engine review-fingerprints [slug] # stable IDs for review findings; --write saves JSONL
+devrites-engine reviewer-stats report --json # direct structured reviewer-dispatch verdicts
 devrites-engine progress [slug]          # compact phase/slice footer
 devrites-engine resolve <qid> "<answer>" # answer a HITL gate
 devrites-engine close-out <slug>         # archive a shipped feature and clear ACTIVE
@@ -29,12 +34,14 @@ devrites-engine help
 
 The AFK-parsed read commands (`status`, `readiness`, `seal`, `spec-validate`,
 `evidence-fresh`, `preamble`, `coverage`, `analyze`, `doctor`, `ledger`) accept
-`--json`, which wraps the result in a stable envelope — see
+`--json`, which wraps the result in a stable envelope: see
 [`engine/agent-contract.md`](engine/agent-contract.md). `snapshot` is already a
 structured JSON contract and emits `schemaVersion: devrites.workspace.v1`
 directly rather than wrapping human text. Snapshot consumers should read
 `nextCommands.claude` or `nextCommands.codex` for the current host instead of
-hardcoding a `/rite-*` or `$rite-*` command form.
+hardcoding a `/rite-*` or `$rite-*` command form. `context show --json` and
+`reviewer-stats report --json` are also direct structured reports rather than
+envelopes.
 
 The npm `devrites` shim remains the installer/updater/uninstaller entry point and
 proxies these engine subcommands when `devrites-engine` is installed. Install and
@@ -47,7 +54,7 @@ in an agent loop, a local script, or pre-merge CI.
 
 ## Why this exists
 
-DevRites workspaces and standards are tool-agnostic data. The CLI makes that
-workflow drivable from agent loops, local scripts, CI, and humans without
-reimplementing the discipline. A verdict from the CLI or a `rite-*` workflow
-should agree because they run the same engine gates.
+DevRites workspaces and standards are tool-agnostic data. The CLI lets agent
+loops, local scripts, CI, and humans use that data without rebuilding the
+workflow. CLI verdicts and `rite-*` verdicts agree because both run the same
+engine gates.