@zigrivers/scaffold 3.1.0 → 3.4.1

package/README.md

@@ -12,24 +12,24 @@ Here's how it works:
 
 1. **Initialize** — run `scaffold init` in your project directory. The init wizard detects whether you're starting fresh (greenfield) or working with an existing codebase (brownfield), and lets you pick a methodology preset (deep, mvp, or custom).
 
-2. **Run steps** — each step is a composable meta-prompt (a short intent declaration in `pipeline/`) that gets assembled at runtime into a full 7-section prompt. The assembly engine injects relevant knowledge base entries, project context from prior steps, methodology settings, and depth-appropriate instructions.
+2. **Run steps** — each step is a composable meta-prompt (a short intent declaration in `content/pipeline/`) that gets assembled at runtime into a full 7-section prompt. The assembly engine injects relevant knowledge base entries, project context from prior steps, methodology settings, and depth-appropriate instructions.
 
 3. **Follow the dependency graph** — Scaffold tracks which steps are complete, which are eligible, and which are blocked. Run `scaffold next` to see what's unblocked, or `scaffold status` for the full picture. Each step produces a specific artifact — a planning document, architecture decision, specification, or actual code.
 
 You can run steps two ways:
 
 - **CLI**: `scaffold run create-prd` — the assembly engine builds a full prompt from the meta-prompt, knowledge base entries, and project context. Best for the structured pipeline with dependency tracking.
-- **Slash commands**: `/scaffold:create-prd` in Claude Code or Gemini — uses pre-rendered, self-contained prompts. Best for quick access to individual commands without the full pipeline ceremony.
+- **Runner skill**: In Claude Code or Gemini, the scaffold-runner skill provides an interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting the AI pick defaults silently.
 
-Either way, Scaffold constructs the prompt and the target AI tool does the work. The CLI tracks pipeline state and dependencies; slash commands are fire-and-forget.
+Either way, Scaffold constructs the prompt and the target AI tool does the work. The CLI tracks pipeline state and dependencies; the runner skill adds interactive decision surfacing on top.
 
 ## Key Concepts
 
-**Meta-prompts** — Each pipeline step is defined as a short `.md` file in `pipeline/` with YAML frontmatter (dependencies, outputs, knowledge entries) and a markdown body describing the step's intent. These are *not* the prompts Claude sees — they're assembled into full prompts at runtime.
+**Meta-prompts** — Each pipeline step is defined as a short `.md` file in `content/pipeline/` with YAML frontmatter (dependencies, outputs, knowledge entries) and a markdown body describing the step's intent. These are *not* the prompts Claude sees — they're assembled into full prompts at runtime.
 
 **Assembly engine** — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
 
-**Knowledge base** — 60 domain expertise entries in `knowledge/` organized in seven categories (core, product, review, validation, finalization, execution, tools) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
+**Knowledge base** — 60 domain expertise entries in `content/knowledge/` organized in seven categories (core, product, review, validation, finalization, execution, tools) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
@@ -76,6 +76,13 @@ Independent review from Google's model. Can run alongside or instead of Codex.
 - Requires: Google account (free tier available)
 - Verify: `gemini --version`
 
+**mmr** (multi-model review CLI)
+Automates dispatching, monitoring, and reconciling code reviews across multiple AI model CLIs. Works standalone or with Scaffold.
+- Install: `npm install -g @zigrivers/mmr`
+- Verify: `mmr --help`
+- Setup: `mmr config init` (auto-detects installed CLIs)
+- See: [mmr — Multi-Model Review CLI](#mmr--multi-model-review-cli)
+
 **Playwright MCP** (web apps only)
 Lets Claude control a real browser for visual testing and screenshots.
 - Install: `claude mcp add playwright npx @playwright/mcp@latest`
@@ -85,7 +92,7 @@ Lets Claude control a real browser for visual testing and screenshots.
 Scaffold has two parts that install separately:
 
 - **CLI** (`scaffold`) — the core tool. Install via npm or Homebrew. Use it from your terminal or from Claude Code with `! scaffold run <step>`.
-- **Plugin** (`/scaffold:`) — optional slash commands for Claude Code. Lets you type `/scaffold:create-prd` instead of `! scaffold run create-prd`.
+- **Plugin** — optional Claude Code plugin that auto-activates the scaffold runner and pipeline reference skills for interactive guidance.
 
 ### Step 1: Install the CLI
 
@@ -108,7 +115,7 @@ Verify: `scaffold version`
 
 ### Step 2: Add the plugin (recommended)
 
-Install the Scaffold plugin inside Claude Code for slash commands AND the interactive runner skill:
+Install the Scaffold plugin inside Claude Code for auto-activated skills:
 
 ```
 /plugin marketplace add zigrivers/scaffold
@@ -116,7 +123,6 @@ Install the Scaffold plugin inside Claude Code for slash commands AND the intera
 ```
 
 This gives you:
-- **Slash commands** (`/scaffold:create-prd`, `/scaffold:tdd`, etc.) — quick access to any pipeline step
 - **Scaffold Runner skill** — intelligent interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting Claude pick defaults silently
 - **Pipeline reference skill** — shows pipeline ordering, dependencies, and phase structure
 - **Multi-model dispatch skill** — correct invocation patterns for Codex and Gemini CLIs
@@ -134,13 +140,9 @@ This gives you:
 
 The plugin is optional — everything it does can also be done with `scaffold run <step>` from the CLI. But you lose the interactive decision surfacing without the Scaffold Runner skill.
 
-> **CLI-only users**: If you prefer not to install the plugin, add skills with one command:
-> ```bash
-> scaffold skill install
-> ```
-> This copies the Scaffold Runner and Pipeline Reference skills to both `.claude/skills/` and `.agents/skills/` in your project.
+> **CLI-only users**: If you prefer not to install the plugin, skills are installed automatically — `scaffold init` sets them up, and any subsequent CLI command keeps them current after upgrades. No manual `scaffold skill install` needed.
 
-> **Gemini users**: `scaffold build` keeps a root `GEMINI.md` in sync with the shared runner instructions and generates `.gemini/commands/scaffold/*.toml` slash commands. Plain prompts like `scaffold status` work because Gemini loads `GEMINI.md`.
+> **Gemini users**: `scaffold build` keeps a root `GEMINI.md` in sync with the shared runner instructions and generates `.gemini/commands/scaffold/*.toml` wrappers. Plain prompts like `scaffold status` work because Gemini loads `GEMINI.md`.
 
 ## Updating
 
@@ -156,14 +158,18 @@ npm update -g @zigrivers/scaffold
 brew upgrade scaffold
 ```
 
+### mmr
+
+```bash
+npm update -g @zigrivers/mmr
+```
+
 ### Plugin
 
 ```
-/scaffold:update
+/plugin marketplace update zigrivers-scaffold
 ```
 
-Or: `/plugin marketplace update zigrivers-scaffold`
-
 ### Existing projects
 
 After upgrading the CLI, existing projects still get automatic state migrations. Run `scaffold status` in your project directory — the state manager detects and renames old step keys, removes retired steps, normalizes artifact paths, and persists the changes atomically. No manual editing of `.scaffold/state.json` is needed.
@@ -189,7 +195,7 @@ The canonical execution entrypoints are still `scaffold run <step>` and the inst
 This release is a clean breaking change for generated adapter output. To migrate an existing project:
 
 1. Upgrade Scaffold.
-2. Remove old root-level generated Scaffold output if present: `commands/`, `prompts/`, `codex-prompts/`, and root `AGENTS.md` only if it was Scaffold-generated.
+2. Remove old root-level generated Scaffold output if present: `prompts/`, `codex-prompts/`, `commands/`, and root `AGENTS.md` only if it was Scaffold-generated. Run `scaffold status` — it warns about any legacy output.
 3. Run `scaffold build`.
 4. Review the Scaffold-managed block in `.gitignore`.
 5. Commit `.gitignore` plus the intended committed `.scaffold/` state files (`config.yml`, `state.json`, `decisions.jsonl`, `instructions/`).
@@ -551,11 +557,299 @@ npm install -g @google/gemini-cli
 
 You don't need both — Scaffold works with whichever CLIs are available. Having both gives the strongest review (three independent perspectives). See [Prerequisites](#prerequisites) for auth setup and verification commands.
 
+### mmr — Multi-Model Review CLI
+
+`mmr` is a standalone CLI that automates multi-model code review. It solves the problems teams hit when manually orchestrating reviews across Claude, Codex, and Gemini: timeouts, auth failures, inconsistent prompts, fragile output parsing, and manual reconciliation.
+
+**The core problem it solves:** Without `mmr`, an AI agent dispatching multi-model reviews has to manually construct CLI commands for each model, handle per-tool auth quirks, improvise timeout handling, parse different output formats, and reconcile findings across channels. In practice, this takes 4-6+ minutes per review and frequently fails. `mmr` reduces this to three commands.
+
+#### How mmr Works
+
+```
+mmr review --pr 47           ──→  Dispatches to all channels in background
+                                   Returns job ID immediately
+                                   Agent continues working
+
+mmr status mmr-a1b2c3        ──→  Poll progress (which channels done?)
+                                   Exit code: 0=done, 1=running, 2=failed
+
+mmr results mmr-a1b2c3       ──→  Reconcile findings across channels
+                                   Apply severity gate
+                                   Output unified findings
+                                   Exit code: 0=passed, 1=gate failed
+```
+
+**Key features:**
+
+- **Async job model** — reviews run in background processes. The agent fires `mmr review` and continues working. No blocking for 4-6 minutes.
+- **Per-channel auth verification** — checks authentication before every dispatch. Auth failures are never silent — `mmr` tells you exactly what expired and the command to fix it.
+- **Immutable core prompt** — every channel gets the same severity definitions (P0-P3), output format spec (JSON), and review criteria. No prompt drift between channels.
+- **Automated reconciliation** — when two channels flag the same location, that's consensus (high confidence). When only one channel flags something, it's unique (medium confidence). P0 from any single source is always high confidence.
+- **Configurable severity gate** — project default in `.mmr.yaml`, override per-review with `--fix-threshold`. Default: P2 (fix P0/P1/P2, skip P3).
+- **Multiple output formats** — JSON (default, for machines), text (terminals), markdown (PR comments).
+
+#### Installing mmr
+
+**npm** (available now):
+```bash
+npm install -g @zigrivers/mmr
+```
+
+**Homebrew** (available after next scaffold release):
+```bash
+brew tap zigrivers/scaffold
+brew install mmr
+```
+
+Verify: `mmr --help`
+
+#### Enabling mmr in an Existing Project
+
+**Step 1: Install the model CLIs you want to use**
+
+You need at least one. More models = more diverse review perspectives.
+
+```bash
+# Claude Code (you probably already have this)
+npm install -g @anthropic-ai/claude-code
+
+# Codex CLI (requires ChatGPT Plus/Pro/Team subscription)
+npm install -g @openai/codex
+
+# Gemini CLI (free tier available with Google account)
+npm install -g @google/gemini-cli
+```
+
+**Step 2: Authenticate each CLI**
+
+Each CLI needs a one-time interactive authentication:
+
+```bash
+# Claude — if not already logged in
+claude login
+
+# Codex — opens browser for OAuth
+codex login
+
+# Gemini — opens browser for OAuth
+gemini -p "hello"
+```
+
+**Step 3: Initialize mmr in your project**
+
+```bash
+cd your-project
+mmr config init
+```
+
+This auto-detects which CLIs are installed and generates `.mmr.yaml` in your project root:
+
+```
+Detected CLIs:
+  ✓ claude (claude -p)
+  ✓ gemini (gemini -p)
+  ✗ codex (not found)
+
+Generated .mmr.yaml with 2 enabled channels.
+Run `mmr config test` to verify authentication.
+```
+
+**Step 4: Verify authentication**
+
+```bash
+mmr config test
+```
+
+```
+  claude    ✓ installed    ✓ authenticated
+  gemini    ✓ installed    ✓ authenticated
+  codex     ✗ not installed (skipped)
+
+  2/3 channels ready.
+```
+
+If any channel shows an auth failure, `mmr` tells you the exact command to fix it.
+
+**Step 5: Commit the config**
+
+```bash
+git add .mmr.yaml
+git commit -m "chore: add mmr multi-model review config"
+```
+
+This ensures your team shares the same channel configuration.
+
+**Step 6 (optional): Customize review criteria**
+
+Edit `.mmr.yaml` to add project-specific review criteria that get injected into every review prompt:
+
+```yaml
+review_criteria:
+  - "Verify all database queries use parameterized statements"
+  - "Check that error messages do not leak internal state"
+  - "Ensure all API endpoints validate authentication"
+```
+
+You can also adjust per-channel timeouts, the default severity threshold, and named review templates for different review types (PR reviews, implementation plan reviews, etc.).
+
+#### Using mmr Day-to-Day
+
+**After creating a PR:**
+
+```bash
+mmr review --pr 47 --focus "auth flow, session handling"
+# → Job mmr-a1b2c3 started. 2/2 channels dispatched.
+```
+
+**Continue working, then check back:**
+
+```bash
+mmr status mmr-a1b2c3
+# → claude: completed (47s) | gemini: running (2m12s)
+
+# Later:
+mmr status mmr-a1b2c3
+# → All channels complete.
+```
+
+**Collect reconciled results:**
+
+```bash
+mmr results mmr-a1b2c3
+# → JSON output with gate_passed, reconciled_findings, per_channel details
+
+mmr results mmr-a1b2c3 --format text
+# → Human-readable terminal output
+
+mmr results mmr-a1b2c3 --format markdown
+# → Markdown table for PR comments
+```
+
+**Review staged changes before committing:**
+
+```bash
+mmr review --staged --focus "regression risk"
+```
+
+**Review a diff between branches:**
+
+```bash
+mmr review --base main --head feature/auth
+```
+
+**Override severity gate for a critical path:**
+
+```bash
+mmr review --pr 47 --fix-threshold P1    # Only fix P0 and P1
+mmr review --pr 47 --fix-threshold P0    # Only fix critical/security issues
+```
+
+#### mmr Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `mmr review` | Dispatch a review job to all configured channels |
+| `mmr status <job-id>` | Check progress of a running job |
+| `mmr results <job-id>` | Collect, reconcile, and output findings |
+| `mmr config init` | Auto-detect CLIs and generate `.mmr.yaml` |
+| `mmr config test` | Verify all channels (installation + auth) |
+| `mmr config channels` | List configured channels |
+| `mmr jobs list` | Show recent review jobs |
+| `mmr jobs prune` | Remove old jobs (default: older than 7 days) |
+
+#### mmr Configuration (.mmr.yaml)
+
+The config file controls channel definitions, defaults, and project-specific review criteria:
+
+```yaml
+version: 1
+
+defaults:
+  fix_threshold: P2        # P0/P1/P2 block the gate, P3 is informational
+  timeout: 300             # Per-channel timeout in seconds
+  format: json             # Default output format
+  job_retention_days: 7    # Auto-prune old jobs
+
+# Project-specific criteria appended to every review prompt
+review_criteria:
+  - "Check for SQL injection in all query builders"
+  - "Verify RBAC rules match API contract"
+
+# Channel definitions (auto-generated by mmr config init)
+channels:
+  claude:
+    enabled: true
+    command: claude -p
+    auth:
+      check: "claude -p 'respond with ok' 2>/dev/null"
+      timeout: 5
+      failure_exit_codes: [1]
+      recovery: "Run: claude login"
+
+  gemini:
+    enabled: true
+    command: gemini -p
+    flags:
+      - "--approval-mode yolo"
+      - "--output-format json"
+    env:
+      NO_BROWSER: "true"
+    auth:
+      check: "NO_BROWSER=true gemini -p 'respond with ok' -o json 2>&1"
+      timeout: 5
+      failure_exit_codes: [41]
+      recovery: "Run: gemini -p 'hello' (interactive, opens browser)"
+    timeout: 360     # Gemini tends to be slower
+
+  codex:
+    enabled: true
+    command: codex exec
+    flags:
+      - "--skip-git-repo-check"
+      - "-s read-only"
+      - "--ephemeral"
+    auth:
+      check: "codex login status 2>/dev/null"
+      timeout: 5
+      failure_exit_codes: [1]
+      recovery: "Run: codex login"
+```
+
+**User-level defaults** can be set in `~/.mmr/config.yaml` for settings that apply across all projects (e.g., which channels are installed on your machine). Project config overrides user config. CLI flags override everything.
+
+**Adding a new model CLI** requires only a YAML config change — no code modifications to `mmr`. When a new model CLI ships, add its channel definition to `.mmr.yaml` and you're ready.
+
+#### Severity Levels
+
+mmr uses a standardized P0-P3 severity classification across all channels:
+
+| Level | Name | Definition | Gate Default |
+|-------|------|------------|-------------|
+| **P0** | Critical | Will cause failure, data loss, security vulnerability, or fundamental architectural flaw | Blocks |
+| **P1** | High | Will cause bugs in normal usage, inconsistency, or blocks downstream work | Blocks |
+| **P2** | Medium | Improvement opportunity — style, naming, documentation, minor optimization | Blocks |
+| **P3** | Trivial | Personal preference, trivial nits | Informational |
+
+With the default `fix_threshold: P2`, any P0, P1, or P2 finding fails the gate. Only P3-only reviews pass.
+
+#### Reconciliation Rules
+
+When multiple channels return findings, mmr applies consensus rules:
+
+| Scenario | Confidence | Action |
+|----------|-----------|--------|
+| 2+ channels flag same location, same severity | **High** | Report at agreed severity |
+| 2+ channels flag same location, different severity | **Medium** | Report at higher severity |
+| All channels approve (no findings) | **High** | Gate passed |
+| One channel flags P0, others approve | **High** | Report P0 (critical from any source) |
+| One channel flags P1/P2, others approve | **Medium** | Report with attribution |
+| Channels contradict each other | **Low** | Present both for user adjudication |
+
 ### How It Works
 
 1. **Claude reviews first** — completes its own structured multi-pass review using different review lenses (coverage, consistency, quality, downstream readiness)
 2. **Independent external review** — the document being reviewed is sent to each available CLI. They don't see Claude's findings or each other's output — every review is independent.
-3. **Findings are reconciled** — Scaffold merges all findings by confidence level:
+3. **Findings are reconciled** — Scaffold (or `mmr`) merges all findings by confidence level:
 
 | Scenario | Confidence | Action |
 |----------|-----------|--------|
@@ -616,7 +910,7 @@ You can change methodology mid-pipeline with `scaffold init --methodology <prese
 | `scaffold dashboard` | Open a visual progress dashboard in your browser |
 | `scaffold decisions` | Show all logged decisions |
 | `scaffold knowledge` | Manage project-local knowledge base overrides |
-| `scaffold skill install` | Install scaffold skills into the current project |
+| `scaffold skill install` | Install scaffold skills into the current project (automatic — rarely needed manually) |
 | `scaffold skill list` | Show available skills and installation status |
 | `scaffold skill remove` | Remove scaffold skills from the current project |
 
@@ -705,7 +999,7 @@ These are stateless pipeline steps — they appear in `scaffold next` once Phase
 
 ### Utility Tools
 
-These are orthogonal to the pipeline — usable at any time, not tied to pipeline state. Defined in `tools/` with `category: tool` frontmatter. Run `scaffold list --section tools` for a complete listing (or `--verbose` for argument hints, `--format json` for machine-readable output):
+These are orthogonal to the pipeline — usable at any time, not tied to pipeline state. Defined in `content/tools/` with `category: tool` frontmatter. Run `scaffold list --section tools` for a complete listing (or `--verbose` for argument hints, `--format json` for machine-readable output):
 
 | Command | When to Use |
 |---------|-------------|
@@ -722,14 +1016,14 @@ These are orthogonal to the pipeline — usable at any time, not tied to pipelin
 
 Use `scaffold run review-code` before commit or push when you want a local gate on the current delivery candidate. Use `scaffold run review-pr` after a GitHub PR exists.
 
-All of these are also available as slash commands (`/scaffold:release`, `/scaffold:quick-task`, etc.) when the plugin is installed.
+Run any of these via the CLI or ask the scaffold runner skill in Claude Code or Gemini.
 
 ## Releasing Your Project
 
 ### Version bumps (development milestones)
 
 ```
-/scaffold:version-bump
+scaffold run version-bump
 ```
 
 Bumps the version number and updates the changelog, but doesn't create tags, push, or run the formal release ceremony. Think of it as a checkpoint.
@@ -737,10 +1031,10 @@ Bumps the version number and updates the changelog, but doesn't create tags, pus
 ### Creating a release
 
 ```
-/scaffold:release
+scaffold run release
 ```
 
-Claude analyzes your commits since the last release, suggests whether this is a major, minor, or patch version bump, and walks you through:
+The AI analyzes your commits since the last release, suggests whether this is a major, minor, or patch version bump, and walks you through:
 1. Running your project's tests
 2. Updating the version number in your project files
 3. Generating a changelog entry
@@ -748,7 +1042,7 @@ Claude analyzes your commits since the last release, suggests whether this is a
 
 Depending on the target project, that may include a Git tag, hosted release,
 package publish, deployment, registry update, or another project-specific
-release step. `/scaffold:release` is intentionally generic; it should follow
+release step. `scaffold run release` is intentionally generic; it follows
 the target project's own documented workflow rather than assuming npm or GitHub
 for every project.
 
@@ -764,17 +1058,18 @@ Options: `--dry-run` to preview, `minor`/`major`/`patch` to specify the bump, `c
 | **Frontmatter** | The YAML metadata block at the top of meta-prompt files, declaring dependencies, outputs, knowledge entries, and other configuration. |
 | **Knowledge base** | 60 domain expertise entries that get injected into prompts. Can be extended with project-local overrides. |
 | **MCP** | Model Context Protocol. A way for Claude to use external tools like a headless browser. |
-| **Meta-prompt** | A short intent declaration in `pipeline/` that gets assembled into a full prompt at runtime. |
+| **Meta-prompt** | A short intent declaration in `content/pipeline/` that gets assembled into a full prompt at runtime. |
+| **mmr** | Multi-Model Review CLI (`@zigrivers/mmr`). Standalone tool for async multi-model code review dispatch, reconciliation, and severity gating. |
 | **Methodology** | A preset (deep, mvp, custom) controlling which steps run and at what depth. |
 | **Multi-model review** | Independent validation from Codex/Gemini CLIs at depth 4-5, catching blind spots a single model misses. |
 | **PRD** | Product Requirements Document. The foundation for everything Scaffold builds. |
-| **Slash commands** | Commands in Claude Code starting with `/`. For example, `/scaffold:create-prd`. |
+| **Runner skill** | Auto-activated Claude Code/Gemini skill that surfaces decision points before executing pipeline steps. |
 | **Worktrees** | A git feature for multiple working copies. Scaffold uses these for parallel agent execution. |
 
 ## Troubleshooting / FAQ
 
 **I ran a command and nothing happened.**
-Make sure Scaffold is installed — run `scaffold version` or `/scaffold:prompt-pipeline` in Claude Code.
+Make sure Scaffold is installed — run `scaffold version` in your terminal.
 
 **Which steps can I skip?**
 Use `scaffold skip <step> --reason "..."` to skip any step. You can skip multiple steps at once: `scaffold skip design-system add-e2e-testing --reason "backend-only"`. The mvp preset only enables 7 critical steps by default. With the custom preset, you choose exactly which steps to run.
@@ -820,6 +1115,15 @@ NO_BROWSER=true gemini -p "Review this artifact..." --output-format json --appro
 ```
 These are documented in detail in the `multi-model-dispatch` skill.
 
+**mmr review dispatches but no channels return results**
+Check auth: `mmr config test`. If channels show auth failures, re-authenticate with the recovery command shown. If channels are installed but the review hangs, check the per-channel timeout in `.mmr.yaml` — some models take 3-5 minutes for large diffs. Increase `timeout` to 360-600 seconds for large PRs.
+
+**mmr results says "gate failed" but I disagree with the findings**
+Use `mmr results <job-id> --format text` to see the full reconciled findings with source attribution and confidence scores. Single-source findings with "unique" agreement are less certain than "consensus" findings. Override the threshold for a specific review: `mmr review --pr 47 --fix-threshold P1` (only gate on P0 and P1).
+
+**How do I add a new AI model CLI to mmr?**
+Add a channel definition to `.mmr.yaml` with the command, auth check, and output parser. No code changes needed. See the [mmr Configuration](#mmr-configuration-mmryaml) section for the full schema.
+
 **I upgraded and my pipeline shows old step names**
 Run `scaffold status` — the state manager automatically migrates old step names (e.g., `add-playwright` → `add-e2e-testing`, `multi-model-review` → `automated-pr-review`) and removes retired steps.
 
@@ -859,14 +1163,36 @@ src/
 
 ### Content layout
 
+All build inputs live under `content/`:
+
+```
+content/
+├── pipeline/         # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
+├── tools/            # 10 tool meta-prompts (stateless, category: tool)
+├── knowledge/        # 61 domain expertise entries (core, product, review, validation, finalization, execution, tools)
+├── methodology/      # 3 YAML presets (deep, mvp, custom)
+└── skills/           # Skill templates with {{markers}} for multi-platform resolution (includes mmr)
+```
+
+### mmr package layout
+
+`@zigrivers/mmr` lives in `packages/mmr/` as an independent workspace package:
+
+```
+packages/mmr/
+├── src/
+│   ├── commands/     # review, status, results, config, jobs (yargs)
+│   ├── config/       # Zod schema, 4-layer config loader, builtin channel presets
+│   ├── core/         # job-store, auth, prompt assembly, parser, reconciler, dispatcher
+│   └── formatters/   # json, text, markdown output formatters
+├── templates/        # Immutable core review prompt (severity defs, output format)
+└── tests/            # 60 tests across 11 files
+```
+
+Generated output (gitignored):
 ```
-pipeline/             # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
-tools/                # 9 tool meta-prompts (stateless, category: tool)
-knowledge/            # 61 domain expertise entries (core, product, review, validation, finalization, execution, tools)
-methodology/          # 3 YAML presets (deep, mvp, custom)
-commands/             # 72 Claude Code slash commands (60 pipeline + 9 tools + 3 supplemental)
-skills/               # 3 Claude Code skills (pipeline reference, runner, multi-model dispatch)
-agent-skills/         # 2 shared agent skills packaged for Claude Code and Gemini installs
+skills/               # Resolved skills (built from content/skills/ templates)
+dist/                 # Compiled TypeScript output
 ```
 
 ### Testing
@@ -880,12 +1206,12 @@ agent-skills/         # 2 shared agent skills packaged for Claude Code and Gemin
 
 ### Contributing
 
-1. Meta-prompt content lives in `pipeline/` — edit the relevant `.md` file
+1. Meta-prompt content lives in `content/pipeline/` — edit the relevant `.md` file
 2. If you changed adapter behavior, run `scaffold build` in a test project and inspect the generated artifacts under `.scaffold/generated/` plus the Gemini project-local outputs (`.agents/skills/`, `GEMINI.md`, `.gemini/commands/scaffold/`).
 3. Run `make check-all` (lint + type-check + test + evals) before submitting
-4. Knowledge entries live in `knowledge/` — follow the existing frontmatter schema
-5. ADRs documenting architectural decisions are in `docs/v2/adrs/`
-6. Run `make hooks` to install git hooks (ShellCheck, frontmatter validation, stale command detection)
+4. Knowledge entries live in `content/knowledge/` — follow the existing frontmatter schema
+5. ADRs documenting architectural decisions are in `docs/architecture/adrs/`
+6. Run `make hooks` to install git hooks (ShellCheck, frontmatter validation)
 
 ## License