code-review-forge 2.4.0__tar.gz → 2.9.0__tar.gz

{code_review_forge-2.4.0/src/code_review_forge.egg-info → code_review_forge-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-review-forge
-Version: 2.4.0
+Version: 2.9.0
 Summary: 3-state quality gate for code review
 Author-email: Minxi Hou <houminxi@gmail.com>
 License-Expression: Apache-2.0
@@ -19,17 +19,22 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: unidiff<0.8.0,>=0.7.5
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: mutmut<4.0,>=3.3; extra == "dev"
-Requires-Dist: semgrep<1.100,>=1.0; extra == "dev"
+Requires-Dist: semgrep<1.170,>=1.0; extra == "dev"
+Requires-Dist: jsonschema>=4.18; extra == "dev"
 Provides-Extra: vertex
 Requires-Dist: google-auth>=2.35.0; extra == "vertex"
 Requires-Dist: requests>=2.20.0; extra == "vertex"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == "mcp"
 Dynamic: license-file
 
 # code-forge
 
-[![PyPI version](https://img.shields.io/pypi/v/code-review-forge.svg)](https://pypi.org/project/code-review-forge/)
-[![Python](https://img.shields.io/pypi/pyversions/code-review-forge.svg)](https://pypi.org/project/code-review-forge/)
+[![PyPI version](https://img.shields.io/pypi/v/code-review-forge.svg?cacheSeconds=300)](https://pypi.org/project/code-review-forge/)
+[![Python](https://img.shields.io/pypi/pyversions/code-review-forge.svg?cacheSeconds=300)](https://pypi.org/project/code-review-forge/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/HouMinXi/forge/blob/main/LICENSE)
 
 A 5-step code review pipeline for AI coding assistants. Treats review as a
@@ -60,6 +65,12 @@ pip install code-review-forge
 code-forge install-skill
 ```
 
+For MCP server support (IDE integration):
+
+```bash
+pip install code-review-forge[mcp]
+```
+
 The first command installs the CLI (Python >=3.12). The second copies the
 6 review skills into `~/.claude/skills/`. Then in Claude Code, run the
 full pipeline:
@@ -88,15 +99,142 @@ code-forge install-skill --skill code-forge   # one skill only
 code-forge install-skill --force              # overwrite existing
 ```
 
+## Getting Started
+
+A complete walkthrough from install to your first gated commit.
+
+### 1. Install and initialize
+
+```bash
+pip install code-review-forge
+cd your-repo
+code-forge init
+```
+
+`init` creates `.code-forge/gate.yaml` with commented examples. It does **not**
+configure a backend or a test runner -- both are your responsibility.
+
+### 2. Configure a backend
+
+Open `.code-forge/gate.yaml` and uncomment one backend block. For the Anthropic
+API:
+
+```yaml
+backends:
+  claude-api:
+    type: api
+    format: anthropic
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+    default: true
+```
+
+`api_key_env` is the **name** of an environment variable, not the key itself.
+Set the variable in your shell:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Then trust the configuration (required once per gate.yaml change):
+
+```bash
+code-forge trust
+```
+
+Review **refuses to run** until at least one backend is configured and trusted.
+
+### 3. Run your first review
+
+code-forge requires a git worktree for review isolation. Create one and make a
+change:
+
+```bash
+git worktree add .worktrees/work -b my-feature
+cd .worktrees/work
+# edit some code, then stage it
+git add -A
+code-forge review
+```
+
+The review reads the **staged (index) diff** -- you do not need to commit first.
+
+**Simple single-branch repos:** if worktrees are overkill for your workflow,
+bypass the check:
+
+```bash
+code-forge review --allow-main
+# or permanently:
+FORGE_ALLOW_MAIN=1 code-forge review
+```
+
+### 4. Install the commit gate (optional but recommended)
+
+The commit gate runs `code-forge verify` (receipt tamper check) and
+`code-forge gate-check` (test suite) on every code commit. It requires a
+`test` section in gate.yaml:
+
+```yaml
+test:
+  command: [pytest, -q]
+  timeout_seconds: 900
+```
+
+Then install:
+
+```bash
+code-forge install-hooks
+```
+
+**What this means for your workflow:**
+
+- **Code commits** (`.py`, `.go`, `.rs`, etc.) require a passing review first.
+  The hook runs `code-forge verify` which checks that a full review has been
+  recorded for the staged diff. Without a prior review, the commit is blocked.
+- **Doc/config commits** (`.md`, `.yaml`, `.toml`, `LICENSE`, etc.) skip the
+  gate automatically -- no review or `--no-verify` needed.
+
+**Bootstrapping a new repo:** if you install hooks before running your first
+review, code commits will be blocked. Either run a successful `code-forge review`
+first, or set `FORGE_ALLOW_NO_BACKEND=1` temporarily to bypass the receipt gate
+while you get your backend working.
+
+### 5. Commit with the gate active
+
+```bash
+# 1. Stage your changes
+git add -A
+# 2. Run a review (must pass before committing code)
+code-forge review
+# 3. Commit -- the pre-commit hook verifies the review receipt
+git commit -m "your message"
+```
+
+If the review found issues, fix them and re-run `code-forge review` until it
+passes. The commit gate checks that the staged diff has a clean review receipt.
+
+### 6. Diagnostics
+
+```bash
+code-forge doctor    # check backend reachability, config health
+code-forge verify    # check review receipt status
+```
+
 ## Backend configuration
 
+Backends can also be set once for all projects in
+`~/.config/code-forge/config.yaml` (override the location with
+`FORGE_CONFIG_DIR`); a backend with the same name in a project's
+`gate.yaml` wins. `code-forge doctor` prints the resolved user-level
+config path every run.
+
 By default, code-forge uses the `claude` CLI in your PATH with the session
 model (no model pin). Three environment variables control the backend:
 
 | Variable | Purpose | Default |
 |---|---|---|
-| `FORGE_BACKEND` | Select a named backend from `backends.yaml` | session-default |
-| `FORGE_OUTLET` | Force outlet: `cli` or `inline` | auto-detected |
+| `FORGE_BACKEND` | Select a named backend from `gate.yaml` | session-default |
+| `FORGE_OUTLET` | Force outlet: `subprocess` \| `inline` \| `subagent` | auto-detected |
 | `FORGE_LLM_MODEL` | Override model for CLI backends | `claude-sonnet-4-6` |
 
 **Quick examples:**
@@ -108,29 +246,30 @@ code-forge review
 # Pin a specific model for this run
 FORGE_LLM_MODEL=claude-opus-4-5 code-forge review
 
-# Use a named API backend from backends.yaml
+# Use a named API backend from gate.yaml
 FORGE_BACKEND=claude-api code-forge review
 
-# Force inline outlet (no CLI subprocess)
+# Force inline outlet (no subprocess)
 FORGE_OUTLET=inline code-forge review
 ```
 
-**Named backends** (optional) are defined in `~/.config/code-forge/backends.yaml`:
+**Named backends** (optional) are defined in the `backends:` key of
+`.code-forge/gate.yaml` (created by `code-forge init`):
 
 ```yaml
 backends:
-  - name: claude-api
+  claude-api:
     type: api
     format: anthropic
     base_url: https://api.anthropic.com
     api_key_env: ANTHROPIC_API_KEY
     default: true
-  - name: openai
+  openai-compatible:
     type: api
     format: openai
     base_url: https://api.openai.com/v1
     api_key_env: OPENAI_API_KEY
-  - name: local-claude
+  local-claude:
     type: cli
     model: claude-opus-4-5
     command: claude
@@ -139,10 +278,77 @@ backends:
 Full reference: [docs/configuration.md](docs/configuration.md)
 
 Editor setup guides:
+- Claude Code: [docs/setup-claude-code.md](docs/setup-claude-code.md)
 - VS Code: [docs/setup-vscode.md](docs/setup-vscode.md)
 - Cursor: [docs/setup-cursor.md](docs/setup-cursor.md)
 - PyCharm: [docs/setup-pycharm.md](docs/setup-pycharm.md)
 
+## MCP server (IDE integration)
+
+`code-forge-mcp` is a local stdio MCP server that exposes forge as tools
+callable from any MCP-capable editor (Claude Code, VS Code Copilot, Cursor,
+PyCharm AI Assistant). Reviews route to the configured CN backend -- the
+calling model never reviews its own code.
+
+| Tool | Purpose |
+|------|---------|
+| `forge_review` | Review the current git diff (inline if fast, job_id if slow) |
+| `forge_gate_check` | Pre-commit gate on staged changes |
+| `forge_resolve_outlet` | Show which backend forge will use (read-only) |
+| `forge_job_status` | Poll a long-running review by job_id |
+| `forge_init` | Create `.code-forge/` in the workspace |
+| `forge_trust` | Trust the gate.yaml backends |
+
+**Prerequisite:** a configured backend with its API key in the server
+environment. Without it, `forge_review` fails closed (same as the CLI).
+One server instance serves one project -- for multi-project setups, use
+per-project `FORGE_PROJECT_DIR` entries (see [docs/setup-mcp.md](docs/setup-mcp.md)).
+
+**Claude Code:**
+
+```bash
+claude mcp add forge -- code-forge-mcp
+```
+
+Launch `claude` from the repo root so the server finds `.code-forge/gate.yaml`.
+
+**VS Code** (1.102+, `.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "forge": {
+      "type": "stdio",
+      "command": "code-forge-mcp",
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+**Gotcha:** GUI editors do not inherit your shell environment. Either wrap
+`code-forge-mcp` in a script that exports the API key, or set `env` in the
+server config. See [docs/setup-mcp.md](docs/setup-mcp.md) for a `pass`-based
+wrapper example and the per-editor MCP configs.
+
+**Verify:** call `forge_resolve_outlet` -- it should name a backend, not
+"key not set". Then call `forge_review` on a real diff.
+
+### Troubleshooting: stale server processes
+
+If old `code-forge-mcp` processes accumulate (visible as high memory or
+multiple PIDs), clean them up manually:
+
+```bash
+pgrep -af code-forge-mcp          # list survivors
+pkill -TERM -f code-forge-mcp     # graceful shutdown
+sleep 3
+pkill -KILL -f code-forge-mcp     # force-kill any that remain
+```
+
+After a server restart, job IDs from the previous instance become invalid.
+Completed reviews leave receipts under `.code-forge/` regardless.
+
 ## The pipeline
 
 ```
@@ -210,6 +416,24 @@ Code Change
   components mapping raises an uncertain finding when a hub and a
   dependent both change in the same diff and no integration test under
   the dependent's paths matches the configured test patterns.
+- **Execution before the verdict.** The reviewed diff is run, not just
+  read. A declared environment is verified against its lockfile by
+  sha256; the run happens in a disposable directory so the reviewed tree
+  stays read-only; a timeout kills the whole descendant process group.
+  The evidence is asymmetric on purpose -- a test failing before the fix
+  is a verdict input, a test passing after it is recorded but cannot
+  confirm a finding. When the environment cannot be grounded, the report
+  says so instead of reasoning against a version the build never used.
+- **Large diffs do not silently review as clean.** Past a token budget a
+  diff is split along def-use lines and each group reviewed separately,
+  with the shared prompt prefix placed ahead of the per-pass role
+  sentence so the backend can cache it. Measured on a 14-file diff that
+  previously lost all three passes to truncation and returned zero
+  findings: 15/15 passes completed, 16-22 findings per cycle, billed
+  input per pass down from 65,748 to 21,987 tokens. Under-budget diffs
+  keep the byte-identical single-pass path. A reply truncated inside its
+  own reasoning is salvaged only where the verdict is already complete,
+  never into a clean round.
 
 ## Honest limitations
 
@@ -239,6 +463,7 @@ passes count.
 - Python 3.12 or newer
 - `jq` for the bash smoke primitives
 - Claude Code or a compatible AI coding assistant for skill invocation
+- `mcp` Python package (optional, for `code-forge-mcp`): `pip install code-review-forge[mcp]`
 
 ## Installation alternatives
 
@@ -261,6 +486,9 @@ do not set up enforcement. The R1 pre-commit gate -- the un-fakeable layer that
 runs the test suite on every commit and blocks on new failures, regardless of
 what the in-editor review claims -- is a separate, manual step:
 
+For running this gate in CI rather than as a local hook, see
+[docs/setup-ci.md](docs/setup-ci.md).
+
 1. Add a `test:` section to `.code-forge/gate.yaml`. Without it, `gate-check`
    exits with `gate.yaml must have a 'test' section`:
 

{code_review_forge-2.4.0 → code_review_forge-2.9.0}/README.md

@@ -1,7 +1,7 @@
 # code-forge
 
-[![PyPI version](https://img.shields.io/pypi/v/code-review-forge.svg)](https://pypi.org/project/code-review-forge/)
-[![Python](https://img.shields.io/pypi/pyversions/code-review-forge.svg)](https://pypi.org/project/code-review-forge/)
+[![PyPI version](https://img.shields.io/pypi/v/code-review-forge.svg?cacheSeconds=300)](https://pypi.org/project/code-review-forge/)
+[![Python](https://img.shields.io/pypi/pyversions/code-review-forge.svg?cacheSeconds=300)](https://pypi.org/project/code-review-forge/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/HouMinXi/forge/blob/main/LICENSE)
 
 A 5-step code review pipeline for AI coding assistants. Treats review as a
@@ -32,6 +32,12 @@ pip install code-review-forge
 code-forge install-skill
 ```
 
+For MCP server support (IDE integration):
+
+```bash
+pip install code-review-forge[mcp]
+```
+
 The first command installs the CLI (Python >=3.12). The second copies the
 6 review skills into `~/.claude/skills/`. Then in Claude Code, run the
 full pipeline:
@@ -60,15 +66,142 @@ code-forge install-skill --skill code-forge   # one skill only
 code-forge install-skill --force              # overwrite existing
 ```
 
+## Getting Started
+
+A complete walkthrough from install to your first gated commit.
+
+### 1. Install and initialize
+
+```bash
+pip install code-review-forge
+cd your-repo
+code-forge init
+```
+
+`init` creates `.code-forge/gate.yaml` with commented examples. It does **not**
+configure a backend or a test runner -- both are your responsibility.
+
+### 2. Configure a backend
+
+Open `.code-forge/gate.yaml` and uncomment one backend block. For the Anthropic
+API:
+
+```yaml
+backends:
+  claude-api:
+    type: api
+    format: anthropic
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+    default: true
+```
+
+`api_key_env` is the **name** of an environment variable, not the key itself.
+Set the variable in your shell:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Then trust the configuration (required once per gate.yaml change):
+
+```bash
+code-forge trust
+```
+
+Review **refuses to run** until at least one backend is configured and trusted.
+
+### 3. Run your first review
+
+code-forge requires a git worktree for review isolation. Create one and make a
+change:
+
+```bash
+git worktree add .worktrees/work -b my-feature
+cd .worktrees/work
+# edit some code, then stage it
+git add -A
+code-forge review
+```
+
+The review reads the **staged (index) diff** -- you do not need to commit first.
+
+**Simple single-branch repos:** if worktrees are overkill for your workflow,
+bypass the check:
+
+```bash
+code-forge review --allow-main
+# or permanently:
+FORGE_ALLOW_MAIN=1 code-forge review
+```
+
+### 4. Install the commit gate (optional but recommended)
+
+The commit gate runs `code-forge verify` (receipt tamper check) and
+`code-forge gate-check` (test suite) on every code commit. It requires a
+`test` section in gate.yaml:
+
+```yaml
+test:
+  command: [pytest, -q]
+  timeout_seconds: 900
+```
+
+Then install:
+
+```bash
+code-forge install-hooks
+```
+
+**What this means for your workflow:**
+
+- **Code commits** (`.py`, `.go`, `.rs`, etc.) require a passing review first.
+  The hook runs `code-forge verify` which checks that a full review has been
+  recorded for the staged diff. Without a prior review, the commit is blocked.
+- **Doc/config commits** (`.md`, `.yaml`, `.toml`, `LICENSE`, etc.) skip the
+  gate automatically -- no review or `--no-verify` needed.
+
+**Bootstrapping a new repo:** if you install hooks before running your first
+review, code commits will be blocked. Either run a successful `code-forge review`
+first, or set `FORGE_ALLOW_NO_BACKEND=1` temporarily to bypass the receipt gate
+while you get your backend working.
+
+### 5. Commit with the gate active
+
+```bash
+# 1. Stage your changes
+git add -A
+# 2. Run a review (must pass before committing code)
+code-forge review
+# 3. Commit -- the pre-commit hook verifies the review receipt
+git commit -m "your message"
+```
+
+If the review found issues, fix them and re-run `code-forge review` until it
+passes. The commit gate checks that the staged diff has a clean review receipt.
+
+### 6. Diagnostics
+
+```bash
+code-forge doctor    # check backend reachability, config health
+code-forge verify    # check review receipt status
+```
+
 ## Backend configuration
 
+Backends can also be set once for all projects in
+`~/.config/code-forge/config.yaml` (override the location with
+`FORGE_CONFIG_DIR`); a backend with the same name in a project's
+`gate.yaml` wins. `code-forge doctor` prints the resolved user-level
+config path every run.
+
 By default, code-forge uses the `claude` CLI in your PATH with the session
 model (no model pin). Three environment variables control the backend:
 
 | Variable | Purpose | Default |
 |---|---|---|
-| `FORGE_BACKEND` | Select a named backend from `backends.yaml` | session-default |
-| `FORGE_OUTLET` | Force outlet: `cli` or `inline` | auto-detected |
+| `FORGE_BACKEND` | Select a named backend from `gate.yaml` | session-default |
+| `FORGE_OUTLET` | Force outlet: `subprocess` \| `inline` \| `subagent` | auto-detected |
 | `FORGE_LLM_MODEL` | Override model for CLI backends | `claude-sonnet-4-6` |
 
 **Quick examples:**
@@ -80,29 +213,30 @@ code-forge review
 # Pin a specific model for this run
 FORGE_LLM_MODEL=claude-opus-4-5 code-forge review
 
-# Use a named API backend from backends.yaml
+# Use a named API backend from gate.yaml
 FORGE_BACKEND=claude-api code-forge review
 
-# Force inline outlet (no CLI subprocess)
+# Force inline outlet (no subprocess)
 FORGE_OUTLET=inline code-forge review
 ```
 
-**Named backends** (optional) are defined in `~/.config/code-forge/backends.yaml`:
+**Named backends** (optional) are defined in the `backends:` key of
+`.code-forge/gate.yaml` (created by `code-forge init`):
 
 ```yaml
 backends:
-  - name: claude-api
+  claude-api:
     type: api
     format: anthropic
     base_url: https://api.anthropic.com
     api_key_env: ANTHROPIC_API_KEY
     default: true
-  - name: openai
+  openai-compatible:
     type: api
     format: openai
     base_url: https://api.openai.com/v1
     api_key_env: OPENAI_API_KEY
-  - name: local-claude
+  local-claude:
     type: cli
     model: claude-opus-4-5
     command: claude
@@ -111,10 +245,77 @@ backends:
 Full reference: [docs/configuration.md](docs/configuration.md)
 
 Editor setup guides:
+- Claude Code: [docs/setup-claude-code.md](docs/setup-claude-code.md)
 - VS Code: [docs/setup-vscode.md](docs/setup-vscode.md)
 - Cursor: [docs/setup-cursor.md](docs/setup-cursor.md)
 - PyCharm: [docs/setup-pycharm.md](docs/setup-pycharm.md)
 
+## MCP server (IDE integration)
+
+`code-forge-mcp` is a local stdio MCP server that exposes forge as tools
+callable from any MCP-capable editor (Claude Code, VS Code Copilot, Cursor,
+PyCharm AI Assistant). Reviews route to the configured CN backend -- the
+calling model never reviews its own code.
+
+| Tool | Purpose |
+|------|---------|
+| `forge_review` | Review the current git diff (inline if fast, job_id if slow) |
+| `forge_gate_check` | Pre-commit gate on staged changes |
+| `forge_resolve_outlet` | Show which backend forge will use (read-only) |
+| `forge_job_status` | Poll a long-running review by job_id |
+| `forge_init` | Create `.code-forge/` in the workspace |
+| `forge_trust` | Trust the gate.yaml backends |
+
+**Prerequisite:** a configured backend with its API key in the server
+environment. Without it, `forge_review` fails closed (same as the CLI).
+One server instance serves one project -- for multi-project setups, use
+per-project `FORGE_PROJECT_DIR` entries (see [docs/setup-mcp.md](docs/setup-mcp.md)).
+
+**Claude Code:**
+
+```bash
+claude mcp add forge -- code-forge-mcp
+```
+
+Launch `claude` from the repo root so the server finds `.code-forge/gate.yaml`.
+
+**VS Code** (1.102+, `.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "forge": {
+      "type": "stdio",
+      "command": "code-forge-mcp",
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+**Gotcha:** GUI editors do not inherit your shell environment. Either wrap
+`code-forge-mcp` in a script that exports the API key, or set `env` in the
+server config. See [docs/setup-mcp.md](docs/setup-mcp.md) for a `pass`-based
+wrapper example and the per-editor MCP configs.
+
+**Verify:** call `forge_resolve_outlet` -- it should name a backend, not
+"key not set". Then call `forge_review` on a real diff.
+
+### Troubleshooting: stale server processes
+
+If old `code-forge-mcp` processes accumulate (visible as high memory or
+multiple PIDs), clean them up manually:
+
+```bash
+pgrep -af code-forge-mcp          # list survivors
+pkill -TERM -f code-forge-mcp     # graceful shutdown
+sleep 3
+pkill -KILL -f code-forge-mcp     # force-kill any that remain
+```
+
+After a server restart, job IDs from the previous instance become invalid.
+Completed reviews leave receipts under `.code-forge/` regardless.
+
 ## The pipeline
 
 ```
@@ -182,6 +383,24 @@ Code Change
   components mapping raises an uncertain finding when a hub and a
   dependent both change in the same diff and no integration test under
   the dependent's paths matches the configured test patterns.
+- **Execution before the verdict.** The reviewed diff is run, not just
+  read. A declared environment is verified against its lockfile by
+  sha256; the run happens in a disposable directory so the reviewed tree
+  stays read-only; a timeout kills the whole descendant process group.
+  The evidence is asymmetric on purpose -- a test failing before the fix
+  is a verdict input, a test passing after it is recorded but cannot
+  confirm a finding. When the environment cannot be grounded, the report
+  says so instead of reasoning against a version the build never used.
+- **Large diffs do not silently review as clean.** Past a token budget a
+  diff is split along def-use lines and each group reviewed separately,
+  with the shared prompt prefix placed ahead of the per-pass role
+  sentence so the backend can cache it. Measured on a 14-file diff that
+  previously lost all three passes to truncation and returned zero
+  findings: 15/15 passes completed, 16-22 findings per cycle, billed
+  input per pass down from 65,748 to 21,987 tokens. Under-budget diffs
+  keep the byte-identical single-pass path. A reply truncated inside its
+  own reasoning is salvaged only where the verdict is already complete,
+  never into a clean round.
 
 ## Honest limitations
 
@@ -211,6 +430,7 @@ passes count.
 - Python 3.12 or newer
 - `jq` for the bash smoke primitives
 - Claude Code or a compatible AI coding assistant for skill invocation
+- `mcp` Python package (optional, for `code-forge-mcp`): `pip install code-review-forge[mcp]`
 
 ## Installation alternatives
 
@@ -233,6 +453,9 @@ do not set up enforcement. The R1 pre-commit gate -- the un-fakeable layer that
 runs the test suite on every commit and blocks on new failures, regardless of
 what the in-editor review claims -- is a separate, manual step:
 
+For running this gate in CI rather than as a local hook, see
+[docs/setup-ci.md](docs/setup-ci.md).
+
 1. Add a `test:` section to `.code-forge/gate.yaml`. Without it, `gate-check`
    exits with `gate.yaml must have a 'test' section`: