@alibaba-group/open-code-review 1.7.14 → 1.7.16

package/README.md

@@ -6,8 +6,11 @@
 </div>
 
 <p align="center">
+  <a href="https://trendshift.io/repositories/41087?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-41087" target="_blank" rel="noopener noreferrer">
+    <img src="https://trendshift.io/api/badge/repositories/41087" alt="alibaba%2Fopen-code-review | Trendshift" style="width: 280px; height: 60px;" width="280" height="60" />
+  </a>
   <a href="https://trendshift.io/repositories/41087" target="_blank">
-    <img src="https://trendshift.io/api/badge/trendshift/repositories/41087/weekly?language=Go" alt="alibaba%2Fopen-code-review | Trendshift" style="width: 320px; height: 70px;" width="320" height="70" />
+    <img src="https://trendshift.io/api/badge/trendshift/repositories/41087/weekly?language=Go" alt="alibaba%2Fopen-code-review | Trendshift" style="width: 280px; height: 60px;" width="280" height="60" />
   </a>
 </p>
 <p align="center">
@@ -99,116 +102,19 @@ The agent's strengths are concentrated where they matter most — dynamic decisi
 
 #### Install
 
-**Via NPM (Recommended)**
-
 ```bash
 npm install -g @alibaba-group/open-code-review
 ```
 
 After installation, the `ocr` command is available globally.
 
-**Update**
-
-If you installed via NPM, update manually to the latest version:
-
-```bash
-npm install -g @alibaba-group/open-code-review@latest
-```
-
-NPM installations also check for newer versions in the background by default and upgrade automatically. To disable auto-updates, set `OCR_NO_UPDATE=1`.
-
-If you installed with the install script or a manually downloaded binary, rerun the same install/download command to replace the local binary with the latest release. Use `OCR_VERSION` when you need to pin a specific release tag.
-
-**From GitHub Release**
-
-Install the latest binary for your OS/architecture with one command (macOS / Linux):
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh
-```
-
-The script picks the right release binary, verifies its SHA-256 checksum, and installs it as `ocr` in `/usr/local/bin`. Override the target with `OCR_INSTALL_DIR` or pin a release with `OCR_VERSION`:
-
-```bash
-OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \
-  sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)"
-```
-
-On Windows (PowerShell 5.1+):
-
-```powershell
-irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex
-```
-
-The script picks the right Windows release binary, verifies its SHA-256 checksum, and installs it as `ocr.exe` in `%LOCALAPPDATA%\Programs\ocr`. Override the target with `OCR_INSTALL_DIR` or pin a release with `OCR_VERSION`:
-
-```powershell
-$env:OCR_INSTALL_DIR = "$env:USERPROFILE\bin"
-$env:OCR_VERSION = "v1.3.13"
-irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex
-```
-
-Piping a remote script into a shell executes code from the internet. Prefer downloading and inspecting first:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh -o install.sh
-less install.sh && sh install.sh
-```
-
-```powershell
-irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 -OutFile install.ps1
-notepad install.ps1   # review, then: .\install.ps1
-```
-
-<details>
-<summary>Manual download (all platforms, including Windows)</summary>
-
-Download the binary for your platform from [GitHub Releases](https://github.com/alibaba/open-code-review/releases):
-
-```bash
-# macOS (Apple Silicon)
-curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
-chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
-
-# macOS (Intel)
-curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
-chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
-
-# Linux (x86_64)
-curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
-chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
-
-# Linux (ARM64)
-curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
-chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
-
-# Windows (x86_64) — move ocr.exe to a directory in your PATH
-curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe
-
-# Windows (ARM64) — move ocr.exe to a directory in your PATH
-curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe
-```
-
-</details>
-
-**From Source**
-
-```bash
-git clone https://github.com/alibaba/open-code-review.git
-cd open-code-review
-make build
-sudo cp dist/opencodereview /usr/local/bin/ocr
-```
+For other installation methods (install script, GitHub Release binary, from source), see [Installation](https://open-codereview.ai/docs/installation).
 
 #### Quick Start
 
 **1. Configure LLM**
 
-**You must configure an LLM before reviewing code.**
-
-OCR manages LLM configuration through a unified **Provider** system. It ships with many popular built-in providers and also supports adding custom providers to connect to private deployments or other compatible endpoints. Config is stored in `~/.opencodereview/config.json`.
-
-**Option A: Interactive setup (Recommended)**
+You must configure an LLM before reviewing code, unless you use [Delegation Mode](https://open-codereview.ai/docs/delegate).
 
 ```bash
 ocr config provider          # Select a built-in provider or add a custom one
@@ -219,91 +125,9 @@ ocr config model             # Pick a model for the active provider
 
 The interactive UI guides you through provider selection, API key entry, and model configuration, then automatically tests connectivity.
 
-Run `ocr llm providers` to see all built-in providers. Built-in providers come with preset API URLs and protocols — just supply an API key to get started. If the corresponding environment variable is already set (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`), the API key is picked up automatically.
-
-**Custom providers** can also be added through the interactive UI — you'll need to provide a name, API URL, protocol type (`anthropic` or `openai`), and API key.
-
-**Option B: CLI setup (for CI/CD and non-interactive environments)**
-
-Use `ocr config set` to write provider configuration directly, suitable for scripts and automation.
-
-Using a built-in provider:
-
-```bash
-ocr config set provider anthropic
-ocr config set providers.anthropic.api_key your-api-key-here
-ocr config set providers.anthropic.model claude-sonnet-4-6
-```
-
-Using a custom provider (private gateway or other compatible endpoint):
-
-```bash
-ocr config set provider my-gateway
-ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1
-ocr config set custom_providers.my-gateway.protocol openai
-ocr config set custom_providers.my-gateway.api_key your-api-key-here
-ocr config set custom_providers.my-gateway.model gpt-4o
-```
-
-> `url` and `protocol` are required for custom providers. Supported protocols: `anthropic`, `openai`, `openai-responses`.
-
-Optional settings:
-
-| Key | Description |
-|-----|-------------|
-| `providers.<name>.auth_header` | Auth header: `x-api-key` or `authorization` (default: `authorization`) |
-| `providers.<name>.extra_body` | Custom JSON fields merged into the request body |
-| `providers.<name>.extra_headers` | Comma-separated `key=value` pairs of custom HTTP headers added to every request |
-| `providers.<name>.models` | Model list for interactive selection |
-
-**`extra_headers` (optional):** Adds custom HTTP headers to every LLM API request. Useful for proxies, gateways, or enterprise endpoints that require additional headers (e.g. organization IDs, tracing IDs). Format is comma-separated `key=value` pairs. Double-quote values that contain commas:
-
-```bash
-ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\""
-```
-
-You can also set extra headers per-provider:
-
-```bash
-ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123"
-```
-
-**Environment variables (highest priority)**
-
-Environment variables override config file settings, useful in CI/CD where writing config files is inconvenient:
+For CLI setup, environment variables, custom providers, and other advanced configuration, see [Configuration](https://open-codereview.ai/docs/configuration).
 
-```bash
-export OCR_LLM_URL=https://api.anthropic.com/v1/messages
-export OCR_LLM_TOKEN=your-api-key-here
-export OCR_LLM_MODEL=claude-opus-4-6
-export OCR_USE_ANTHROPIC=true
-```
-
-To use the OpenAI Responses API (GPT-5.x / o-series), set `OCR_LLM_PROTOCOL` instead of `OCR_USE_ANTHROPIC`:
-
-```bash
-export OCR_LLM_URL=https://api.openai.com/v1
-export OCR_LLM_TOKEN=your-openai-key
-export OCR_LLM_MODEL=gpt-5.4
-export OCR_LLM_PROTOCOL=openai-responses
-```
-
-`OCR_LLM_PROTOCOL` accepts `anthropic`, `openai`, `openai-responses`, and takes priority over `OCR_USE_ANTHROPIC` when both are set.
-
-Also compatible with Claude Code environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) and parses `~/.zshrc` / `~/.bashrc` for those exports.
-
-> **Note for CC-Switch Users**: If you are using [CC-Switch](https://github.com/farion1231/cc-switch) with [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service) enabled, you can point the provider's `url` to the CC-Switch proxy address without additional configuration:
-> - For **Claude** provider: set `providers.anthropic.url` to `http://127.0.0.1:15721`
-> - For **Codex** provider: set the corresponding provider's `url` to `http://127.0.0.1:15721/v1`
-> - `api_key` can be any value; `extra_body` settings still apply
-
-**2. Test Connectivity**
-
-```bash
-ocr llm test
-```
-
-**3. Review**
+**2. Review**
 
 ```bash
 cd your-project
@@ -331,633 +155,24 @@ ocr delegate preview
 ocr delegate rule src/main.go src/handler.go
 ```
 
-### Integrate with Coding Agents
-
-OCR can be seamlessly integrated into AI coding agents as a slash command, enabling code review directly within your agent workflow.
-
-#### Option 1: Install as a Skill
-
-Use `npx` to install the OCR skill into your project:
-
-```bash
-npx skills add alibaba/open-code-review --skill open-code-review
-```
-
-This installs the `open-code-review` skill from the [skills registry](skills/open-code-review/SKILL.md), which teaches your coding agent how to invoke `ocr` for code review, classify issues by priority, and optionally apply fixes.
-
-**Delegation mode** — if you want your coding agent to perform the review itself (using OCR only for file selection and rule resolution, no LLM configuration needed on the OCR side):
-
-```bash
-npx skills add alibaba/open-code-review --skill open-code-review-delegate
-```
-
-See [skills/open-code-review-delegate/SKILL.md](skills/open-code-review-delegate/SKILL.md) for details.
-
-#### Option 2: Install as a Claude Code Plugin
-
-For [Claude Code](https://docs.anthropic.com/en/docs/claude-code), install the command plugin through the following command in Claude Code:
-
-```bash
-/plugin marketplace add alibaba/open-code-review
-/plugin install open-code-review@open-code-review
-```
-
-This registers the `/open-code-review:review` slash command, which runs OCR and automatically filters and fixes issues. It also provides `/open-code-review:delegate-review` for delegation mode (the agent reviews using its own capabilities while OCR handles file selection and rules).
-
-#### Option 3: Install as a Codex Plugin
-
-For local Codex, install the Open Code Review plugin from this repository:
-
-```bash
-codex plugin marketplace add alibaba/open-code-review
-codex
-/plugins
-```
-
-For a local checkout or fork:
-
-```bash
-codex plugin marketplace add .
-codex
-/plugins
-```
-
-Install and enable `Open Code Review`, then start a new Codex thread and invoke it explicitly:
-
-```text
-@Open Code Review review my current changes
-@Open Code Review review this branch against main
-@Open Code Review review and fix high-confidence issues
-```
-
-This registers a Codex skill that runs the local OCR CLI:
-
-```bash
-ocr review --audience agent
-```
-
-This integration does not change OCR's internal LLM backend and does not require configuring an OpenAI Responses API endpoint for Codex. OCR itself still requires the `ocr` CLI to be installed and configured as described in the CLI setup section.
-
-Korean guide: [`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md)
-
-#### Option 4: Install as a Cursor Plugin
-
-For [Cursor](https://www.cursor.com/), install the Open Code Review plugin from this repository:
-
-```
-cursor-plugin marketplace add alibaba/open-code-review
-```
-
-Or add the marketplace manually. In Cursor, open `/plugins`, search for `Open Code Review`, and install it.
-
-For a local checkout or fork:
-
-```
-cursor-plugin marketplace add .
-```
-
-After installation, invoke it in Cursor:
-
-```text
-@Open Code Review review my current changes
-@Open Code Review review this branch against main
-@Open Code Review review and fix high-confidence issues
-```
-
-This registers a Cursor skill that runs the local OCR CLI:
-
-```bash
-ocr review --audience agent
-```
-
-This integration does not change OCR's internal LLM backend. OCR itself still requires the `ocr` CLI to be installed and configured as described in the CLI setup section.
-
-#### Option 5: Copy the Command File Directly
-
-For a quick setup without any package manager, simply copy the command file to use the `/open-code-review` slash command in Claude Code.
-
-**Project-level** (shared with team via git):
-
-```bash
-mkdir -p .claude/commands
-curl -o .claude/commands/open-code-review.md \
-  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md
-```
-
-**User-level** (personal global use across all projects):
-
-```bash
-mkdir -p ~/.claude/commands
-curl -o ~/.claude/commands/open-code-review.md \
-  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md
-```
-
-For delegation mode (no LLM configuration needed on OCR side):
-
-```bash
-# Project-level
-mkdir -p .claude/commands
-curl -o .claude/commands/open-code-review-delegate.md \
-  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md
-
-# User-level
-mkdir -p ~/.claude/commands
-curl -o ~/.claude/commands/open-code-review-delegate.md \
-  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md
-```
-
-> **Prerequisite**: All integration methods require the `ocr` CLI to be installed. Standard mode additionally requires an LLM configured — see [Install](#install) and [Configure LLM](#1-configure-llm) above. Delegation mode does **not** require LLM configuration on the OCR side.
-
-### CI/CD Integration
-
-OCR can be integrated into CI/CD pipelines to automate code review on Merge Requests / Pull Requests.
-
-The core command for CI integration:
-
-```bash
-ocr review \
-  --from "origin/main" \
-  --to "<commit_sha>" \
-  --format json
-```
-
-The `--from` flag accepts a branch ref (e.g., `origin/main`) or commit SHA as the base, while `--to` accepts a commit SHA or branch ref as the head. In CI environments, using commit SHA for `--to` is recommended to correctly handle fork PRs/MRs where the source branch doesn't exist on the origin remote.
-
-The `--format json` flag outputs machine-readable results suitable for parsing in CI scripts.
-
-Each finding carries two structured fields so CI integrations can sort, group, filter, or gate builds without re-parsing comment text:
-
-| Field | Allowed values | Notes |
-|-------|----------------|-------|
-| `category` | `bug`, `security`, `performance`, `maintainability`, `test`, `style`, `documentation`, `other` | The category the issue belongs to. |
-| `severity` | `critical`, `high`, `medium`, `low` | The importance of the issue. |
-
-In JSON output the two fields appear as siblings alongside `content`, `start_line`, etc. In the terminal, they render as an inline `[category · severity]` badge before the comment, colored by severity.
-
-See the [`examples/`](./examples/) directory for integration examples:
-
-- [`github_actions/`](./examples/github_actions/) — GitHub Actions integration example
-- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI integration example
-- [`gitflic_ci/`](./examples/gitflic_ci/) — GitFlic CI integration example
-- [`gerrit_ci/`](./examples/gerrit_ci/) — Gerrit (Jenkins / Gerrit Trigger) integration example
-
-#### GitHub Action
-
-For GitHub, this repository also ships a ready-to-use composite Action at the repo root ([`action.yml`](./action.yml)). Instead of scripting `ocr review` yourself, reference it directly and it handles the full pipeline — checkout, OCR install, running the review, posting inline and summary comments, uploading artifacts, and retry/idempotency:
-
-```yaml
-- uses: alibaba/open-code-review@main
-  with:
-    llm_url: ${{ secrets.OCR_LLM_URL }}
-    llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }}
-    llm_model: ${{ vars.OCR_LLM_MODEL }}
-    llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }}
-```
-
-Pin to a version tag or commit SHA for reproducibility. See the [`examples/github_actions/`](./examples/github_actions/) directory for a complete workflow demo and the full list of inputs, outputs, and comment-posting modes (sticky summary, incremental non-destructive posting).
-
-## Commands
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `ocr review` | `ocr r` | Start a diff-based code review |
-| `ocr scan` | `ocr s` | Review whole files (no diff required) |
-| `ocr delegate preview` | `ocr d preview` | Preview reviewable files with mode/ref metadata (no LLM required) |
-| `ocr delegate rule <path...>` | `ocr d rule` | Output resolved review rules grouped by content (no LLM required) |
-| `ocr rules check <file>` | — | Preview which review rule applies to a file path |
-| `ocr config provider` | — | Interactive provider setup (built-in, custom, or manual) |
-| `ocr config model` | — | Interactive model selection for the active provider |
-| `ocr config set <key> <value>` | — | Set configuration values |
-| `ocr config unset custom_providers.<name>` | — | Delete a custom provider |
-| `ocr llm test` | — | Test LLM connectivity |
-| `ocr llm providers` | — | List built-in LLM providers |
-| `ocr session list` | `ocr sessions list`, `ocr session ls` | List saved review sessions |
-| `ocr session show <id>` | `ocr sessions show <id>` | Inspect one session and its per-file checkpoints |
-| `ocr viewer` | `ocr v` | Launch WebUI session viewer on `localhost:5483` |
-| `ocr version` | — | Show version info |
-
-### `ocr review` Flags
-
-| Flag | Shorthand | Default | Description |
-|------|-----------|---------|-------------|
-| `--repo` | — | current dir | Git repository root |
-| `--from` | — | — | Source ref (e.g., `main`) |
-| `--to` | — | — | Target ref (e.g., `feature-branch`) |
-| `--commit` | `-c` | — | Single commit to review |
-| `--exclude` | — | — | Comma-separated gitignore-style patterns to skip; merged with rule.json excludes |
-| `--preview` | `-p` | `false` | Preview which files will be reviewed without running the LLM |
-| `--resume` | — | — | Resume from a previous compatible range or commit review session |
-| `--format` | `-f` | `text` | Output format: `text` or `json` |
-| `--concurrency` | — | `8` | Max concurrent file reviews |
-| `--timeout` | — | `10` | Concurrent task timeout in minutes |
-| `--audience` | — | `human` | `human` (show progress) or `agent` (summary only) |
-| `--background` | `-b` | — | Optional requirement/business context for the review; auto-filled from commit message when using `--commit` |
-| `--background-file` | `-B` | — | Optional requirement/business context from a Markdown file; Combined with `--background` the inline value is given first |
-| `--model` | — | — | Select or override the LLM model for this review |
-| `--rule` | — | — | Path to custom JSON review rules |
-| `--max-tools` | — | built-in | Max tool call rounds per file; only takes effect when greater than template default |
-| `--max-git-procs` | — | `16` | Max concurrent git subprocesses |
-| `--tools` | — | built-in | Path to custom JSON tools config |
-
-#### Resumable Reviews and Sessions
-
-Every `ocr review` run persists a local session log under
-`~/.opencodereview/sessions/`. Successful text output stays focused on review
-results and does not print the session ID; use `ocr session list/show` to find
-saved sessions, or `--format json` to include `session_id` in machine-readable
-output. If a range or commit review is interrupted, list the saved sessions and
-resume from the one that matches the same review target:
-
-```bash
-ocr session list
-ocr session show <session-id>
-ocr review --from main --to feature-branch --resume <session-id>
-ocr review --commit abc123 --resume <session-id>
-```
-
-Resume is intentionally strict: it only supports branch-range and single-commit
-reviews, not workspace reviews, and the current `--from/--to` or `--commit`
-must match the saved session. `--preview` cannot be combined with `--resume`.
-
-When `--format json` is used, resumed runs include:
-
-- `session_id` — the current run's session ID
-- `resume.resumed_from` — the source session ID
-- `resume.reused_files` — files reused from saved checkpoints
-- `resume.rerun_files` — files reviewed again in the current run
-
-### `ocr session` Flags
-
-| Command | Flag | Default | Description |
-|---------|------|---------|-------------|
-| `ocr session list` | `--repo` | current dir | Repository whose sessions should be listed |
-| `ocr session list` | `--json` | `false` | Emit session summaries as JSON |
-| `ocr session list` | `--limit` | `20` | Cap listed sessions; use `0` for unlimited |
-| `ocr session show <id>` | `--repo` | current dir | Repository whose session should be inspected |
-| `ocr session show <id>` | `--json` | `false` | Emit session metadata and per-file items as JSON |
-
-### `ocr scan` Flags
-
-`ocr scan` reviews entire files rather than a diff — useful for auditing an unfamiliar
-codebase, a pre-migration sweep, or any directory with no meaningful diff. It works in
-non-git directories too (it falls back to a filesystem walk that honors `.gitignore`).
-
-| Flag | Shorthand | Default | Description |
-|------|-----------|---------|-------------|
-| `--path` | — | whole repo | Comma-separated dirs/files to scan |
-| `--exclude` | — | — | Comma-separated gitignore-style patterns to skip; merged with rule.json excludes |
-| `--preview` | `-p` | `false` | List which files would be scanned without running the LLM |
-| `--max-tokens-budget` | — | `0` (unlimited) | Cap total token usage; dispatch stops once exceeded |
-| `--no-plan` | — | `false` | Skip the per-file planning pre-pass |
-| `--no-dedup` | — | `false` | Skip per-batch de-duplication of similar comments |
-| `--no-summary` | — | `false` | Skip the project-level summary |
-| `--batch` | — | `by-language` | Batching strategy: `none`, `by-language`, or `by-directory` |
-| `--format` | `-f` | `text` | Output format: `text` or `json` (JSON includes a `project_summary` field) |
-| `--concurrency` | — | `8` | Max concurrent file scans |
-| `--rule` | — | — | Path to custom JSON review rules |
-| `--repo` | — | current dir | Repository or directory root to scan |
-
-Before each run, `ocr scan` prints a rough token-cost estimate. Use `--preview` to see the
-file list first, and `--max-tokens-budget` to cap spend on large repositories.
-
-### `ocr delegate` Flags
-
-`ocr delegate` is the delegation mode for AI coding agents. It provides deterministic
-file selection and rule resolution without calling any LLM — the host agent performs
-the actual review using its own capabilities.
-
-| Sub-command | Description |
-|-------------|-------------|
-| `ocr delegate preview` | Output reviewable file list with mode/ref metadata |
-| `ocr delegate rule <path...>` | Output resolved review rules grouped by content |
-
-Both sub-commands share these flags:
-
-| Flag | Shorthand | Default | Description |
-|------|-----------|---------|-------------|
-| `--repo` | — | current dir | Git repository root |
-| `--from` | — | — | Source ref (e.g., `main`) |
-| `--to` | — | — | Target ref (e.g., `feature-branch`) |
-| `--commit` | `-c` | — | Single commit to review |
-| `--exclude` | — | — | Comma-separated gitignore-style patterns to skip |
-| `--rule` | — | — | Path to custom JSON review rules |
-| `--background` | `-b` | — | Optional requirement/business context |
-| `--background-file` | `-B` | — | Business context from a Markdown file |
-| `--max-git-procs` | — | `16` | Max concurrent git subprocesses |
-
-## Examples
-
-```bash
-# Interactive provider and model setup
-ocr config provider
-ocr config model
-ocr llm providers
-
-# Delete a custom provider
-ocr config unset custom_providers.my-gateway
-
-# Preview which files will be reviewed (no LLM calls)
-ocr review --preview
-ocr review -c abc123 -p
-
-# Review workspace changes with default settings
-ocr review
-
-# Review branch diff with higher concurrency
-ocr review --from main --to my-feature --concurrency 4
-
-# Review a specific commit with verbose JSON output
-ocr review --commit abc123 --format json --audience agent
-
-# Resume an interrupted range or commit review
-ocr session list
-ocr session show <session-id>
-ocr review --from main --to my-feature --resume <session-id>
-ocr review --commit abc123 --resume <session-id>
-
-# Select or override model for this review
-ocr review --model claude-opus-4-6
-ocr review --commit abc123 --model claude-sonnet-4-6
-
-# Provide requirement context for more targeted review
-ocr review --background "Adding rate limiting to the login API"
-
-# Provide requirement context from a Markdown file
-ocr review --background-file ./docs/my_business_context.md
-
-# Combine inline context with a local context file (both are used)
-ocr review --background "Focus on auth" --background-file ./docs/my_business_context.md
-
-# Use custom review rules
-ocr review --rule /path/to/my-rules.json
-
-# Preview which rule applies to a file
-ocr rules check src/main/java/com/example/Foo.java
-ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml
-
-# Full-file scan: preview the file list first (no LLM calls)
-ocr scan --preview
-
-# Scan the whole repo, cap spend at ~500k tokens
-ocr scan --max-tokens-budget 500000
-
-# Scan a subdirectory, skipping generated/test files
-ocr scan --path internal --exclude '**/*_test.go,**/generated/**'
-
-# Scan a non-git directory with JSON output (includes project_summary)
-ocr scan --repo /path/to/plain/dir --format json
-
-# Fastest scan: skip planning, dedup, and the project summary
-ocr scan --no-plan --no-dedup --no-summary
-
-# Delegation mode — let your AI agent drive the review (no LLM config needed)
-ocr delegate preview
-ocr delegate preview --from main --to feature-branch
-ocr delegate preview --commit abc123
-ocr delegate rule internal/handler.go internal/service.go cmd/main.go
-
-# View review session history in browser
-ocr viewer
-ocr viewer --addr :3000
-```
-
-### Viewer security
-
-The viewer serves session JSONL contents (LLM request messages and responses) over HTTP. It enforces a Host-header allowlist on every request: loopback names (`localhost`, `127.0.0.0/8`, `::1`) and the concrete bind host are always allowed. Wildcard binds (`--addr :3000`, `--addr 0.0.0.0:3000`) and other non-loopback Hostnames must be added via the `OCR_VIEWER_ALLOWED_HOSTS` environment variable (comma-separated):
-
-```bash
-OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000
-```
-
-This blocks DNS-rebinding attacks against the local viewer.
-
-## Review Rules
-
-OCR resolves review rules using a four-layer priority chain. Each layer uses first-match-wins: if a file path matches a pattern, that rule is used; otherwise it falls through to the next layer.
-
-| Priority | Source | Path | Description |
-|----------|--------|------|-------------|
-| 1 (highest) | `--rule` flag | User-specified path | CLI explicit override |
-| 2 | Project config | `<repoDir>/.opencodereview/rule.json` | Per-project rules, can be committed to git |
-| 3 | Global config | `~/.opencodereview/rule.json` | User-wide personal preferences |
-| 4 (lowest) | System default | Embedded `system_rules.json` | Built-in rules covering common languages and file types |
-
-### Rule File Format
-
-Layers 1–3 share the same JSON format:
-
-```json
-{
-  "rules": [
-    {
-      "path": "force-api/**/*.java",
-      "rule": "All new methods must validate required parameters for null values",
-      "merge_system_rule": true
-    },
-    {
-      "path": "**/*mapper*.xml",
-      "rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
-    }
-  ]
-}
-```
-
-- `path` supports `**` recursive matching and `{java,kt}` brace expansion.
-- `merge_system_rule` is optional. When `true`, the matched built-in system rule is merged with this user rule; otherwise the user rule replaces the system rule.
-- Within each layer, rules are evaluated in declaration order — the first match wins.
-- If a rule file does not exist, it is silently skipped.
-
-**The `rule` field supports both inline content and file paths.** The system auto-detects which one you mean:
-
-1. If the value contains newlines → **inline content** (multi-line rules are never file paths).
-2. If the value is a single line, contains no spaces, and ends with `.md` / `.txt` / `.markdown` → **file path**.
-   - Absolute paths (starting with `/`) are used directly.
-   - Relative paths are resolved against the project root. Path traversal (e.g. `../../etc/passwd.md`) is blocked. If not found, a `[WARN]` is emitted and the rule is cleared (no fallback to inline).
-   - The file must pass validation: whitelisted extension, ≤ 512 KB, and resolved symlink target must also be a whitelisted extension. If validation fails, the rule is cleared.
-3. Otherwise → **inline content**.
-
-```json
-{
-  "rules": [
-    {
-      "path": "**/*mapper*.xml",
-      "rule": "docs/sql-rules.md"
-    },
-    {
-      "path": "**/*.java",
-      "rule": "Always check for null safety and resource leaks"
-    },
-    {
-      "path": "**/*.go",
-      "rule": "shared/go-concurrency.md"
-    },
-    {
-      "path": "**/*.py",
-      "rule": "/Users/me/team-rules/python.md"
-    }
-  ]
-}
-```
-
-- `docs/sql-rules.md` — relative path, resolved from `<project>/docs/sql-rules.md`.
-- `Always check for null safety…` — inline string, used directly.
-- `shared/go-concurrency.md` — relative path, same resolution.
-- `/Users/me/team-rules/python.md` — absolute path, used directly.
-
-> Absolute paths can access files outside the project directory — this is intentional. `rule.json` is authored by project maintainers, i.e. trusted input. Teams can store shared rules at a common path (e.g. `/opt/company-rules/`) instead of copying them into every project.
-
-### Path Filtering
-
-Rule files also support `include` and `exclude` fields to control which files enter the review scope:
-
-```json
-{
-  "rules": [
-    {"path": "**/*.java", "rule": "Check for null safety"}
-  ],
-  "include": ["src/main/**/*.java", "lib/**/*.kt"],
-  "exclude": ["**/generated/**", "vendor/**"]
-}
-```
-
-**Filter decision priority (highest to lowest):**
-
-| Step | Condition | Result |
-|------|-----------|--------|
-| 1 | File is binary | Excluded |
-| 2 | Path matches user `exclude` pattern | Excluded |
-| 3 | File extension not in supported list | Excluded |
-| 4 | `include` is configured and path matches | **Reviewed** (skips step 5) |
-| 5 | Path matches built-in default exclude pattern (test files, etc.) | Excluded |
-| 6 | None of the above | Reviewed |
-
-**How it works:**
-
-- `include` and `exclude` follow the same priority chain as review rules (`--rule` > project config > global config). The **highest-priority layer that has include/exclude configured** takes effect as a whole — patterns are not merged across layers.
-- `exclude` always wins over `include` — a file matching both is excluded.
-- `include` acts as a **bypass for built-in default exclude patterns** (e.g., test files), not as an exclusive allowlist — files not matching any `include` pattern still proceed through the default filter checks normally.
-- Pattern syntax: supports `**` recursive matching, `*` single-segment matching, and `{a,b}` brace expansion. Matching is case-insensitive.
-
-**Built-in default exclude patterns** (filters test files, etc. — can be overridden with `include`):
-
-```
-**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
-**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
-**/src/test/java/**/*.java, **/src/test/**/*.kt,
-**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
-**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**
-```
-
-## Configuration Reference
-
-Config file: `~/.opencodereview/config.json`
-
-| Key | Type | Example |
-|-----|------|---------|
-| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` |
-| `providers.<name>.api_key` | string | Provider-specific API key |
-| `providers.<name>.url` | string | Provider base URL override |
-| `providers.<name>.protocol` | string | `anthropic` \| `openai` \| `openai-responses` |
-| `providers.<name>.model` | string | Model name for the provider |
-| `providers.<name>.models` | array | Optional provider model list for interactive selection |
-| `providers.<name>.auth_header` | string | `x-api-key` \| `authorization` |
-| `providers.<name>.extra_body` | object | JSON object merged into every request body |
-| `providers.<name>.timeout_sec` | integer | Per-request HTTP timeout in seconds (default: `300`) |
-| `providers.<name>.extra_headers` | string | Comma-separated `key=value` HTTP headers |
-| `custom_providers.<name>.*` | — | Same fields as `providers.<name>.*`, including optional `models` |
-| `llm.url` | string | `https://api.openai.com/v1/chat/completions` |
-| `llm.auth_token` | string | `sk-xxxxxxx` |
-| `llm.auth_header` | string | Anthropic only: `x-api-key` \| `authorization` |
-| `llm.extra_body` | object | JSON object merged into every request body |
-| `llm.timeout_sec` | integer | Per-request HTTP timeout in seconds (default: `300`) |
-| `llm.extra_headers` | string | Comma-separated `key=value` HTTP headers |
-| `llm.model` | string | `claude-opus-4-6` |
-| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; takes priority over `llm.use_anthropic` |
-| `llm.use_anthropic` | boolean | `true` \| `false` (legacy; prefer `llm.protocol`) |
-| `mcp_servers.<name>.command` | string | Command to start the MCP server |
-| `mcp_servers.<name>.args` | array | Command-line arguments for the MCP server |
-| `mcp_servers.<name>.env` | array | Environment variables in `KEY=VALUE` format |
-| `mcp_servers.<name>.tools` | array | Allowed tool names (empty = all tools) |
-| `mcp_servers.<name>.setup` | string | Setup command to run before starting the server |
-| `language` | string | Any language name, e.g. `English`, `Chinese` (default: `English`) |
-| `telemetry.enabled` | boolean | `true` \| `false` |
-| `telemetry.exporter` | string | `console` \| `otlp` |
-| `telemetry.otlp_endpoint` | string | OTLP collector address |
-| `telemetry.content_logging` | boolean | Include prompts in telemetry |
-
-Environment variables take precedence over the config file.
-
-### MCP Server
-
-Open Code Review supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers, allowing the review agent to use external tools during code review via the stdio transport.
-
-Configure MCP servers via the CLI:
-
-```bash
-# Add an MCP server
-ocr config set mcp_servers.<name>.command <command>
-ocr config set mcp_servers.<name>.args '["arg1","arg2"]'
-ocr config set mcp_servers.<name>.env '["KEY=VALUE"]'
-ocr config set mcp_servers.<name>.tools '["tool_name"]'
-ocr config set mcp_servers.<name>.setup '<setup command>'
-
-# Delete an MCP server
-ocr config unset mcp_servers.<name>
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `command` | Yes | The executable command to start the MCP server |
-| `args` | No | Command-line arguments passed to the server |
-| `env` | No | Environment variables in `KEY=VALUE` format |
-| `tools` | No | Allowed tool names; if empty, all tools from the server are available |
-| `setup` | No | A shell command to run before starting the server (e.g. build an index) |
-
-> **Note:** If an MCP tool's name conflicts with a built-in tool, it will be skipped with a warning. The `setup` command has a 5-minute timeout.
-
-**Example: Add [CodeGraph](https://github.com/nicholasgasior/codegraph) for code structure analysis**
-
-```bash
-ocr config set mcp_servers.codegraph.command codegraph
-ocr config set mcp_servers.codegraph.args '["serve","--mcp"]'
-ocr config set mcp_servers.codegraph.tools '["codegraph_explore"]'
-ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index'
-```
-
-### Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `OCR_LLM_URL` | LLM API endpoint URL |
-| `OCR_LLM_TOKEN` | API key / auth token |
-| `OCR_LLM_AUTH_HEADER` | Anthropic auth header (`x-api-key` or `authorization`) |
-| `OCR_LLM_EXTRA_HEADERS` | Comma-separated `key=value` HTTP headers |
-| `OCR_LLM_MODEL` | Model name |
-| `OCR_LLM_PROTOCOL` | Protocol: `anthropic` \| `openai` \| `openai-responses`; takes priority over `OCR_USE_ANTHROPIC` |
-| `OCR_LLM_TIMEOUT` | Per-request HTTP timeout in seconds (overrides config file `timeout_sec`) |
-| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (legacy; prefer `OCR_LLM_PROTOCOL`) |
-
-## Telemetry
-
-OpenTelemetry integration for observability (spans, metrics). Disabled by default.
-
-```bash
-ocr config set telemetry.enabled true
-ocr config set telemetry.exporter otlp
-ocr config set telemetry.otlp_endpoint localhost:4317
-```
-
-Set `telemetry.content_logging` to include LLM prompts and responses in exported data.
-
-**Protocol selection:** Set the environment variable `OTEL_EXPORTER_OTLP_PROTOCOL` to choose the export protocol:
-
-| Value | Transport | Notes |
-|---|---|---|
-| `grpc` (default) | gRPC | Default port 4317 |
-| `http/protobuf` | HTTP | Default port 4318 |
-
-**Endpoint format:** `telemetry.otlp_endpoint` expects a base URL in `host:port` or `http://host:port` format, without a path component. The SDK appends the signal path (e.g. `/v1/traces`) automatically per the [OTLP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request).
-
+## Documentation
+
+Full documentation lives at **[open-codereview.ai/docs](https://open-codereview.ai/docs)**:
+
+- [Quickstart](https://open-codereview.ai/docs/quickstart) — install and run your first review
+- [Installation](https://open-codereview.ai/docs/installation) — all platforms and package managers
+- [CLI Reference](https://open-codereview.ai/docs/cli-reference) — every command and flag
+- [Review Rules](https://open-codereview.ai/docs/review-rules) — customize review rules with path filtering and targeting
+- [Configuration](https://open-codereview.ai/docs/configuration) — config keys and environment variables
+- [MCP Server](https://open-codereview.ai/docs/mcp) — extend the review agent with external tools
+- Coding Agent Integrations — integrate OCR into Claude Code, Codex, Cursor, etc.
+  - [Skill](https://open-codereview.ai/docs/agent-skill) — install as a reusable agent skill
+  - [Plugin](https://open-codereview.ai/docs/claude-code) — install as a Claude Code / Codex / Cursor plugin
+  - [Delegation Mode](https://open-codereview.ai/docs/delegate) — let your agent review using its own LLM
+- [CI/CD Integration](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI, and Gerrit integration
+- [Session Viewer](https://open-codereview.ai/docs/viewer) — browse and replay review sessions in browser
+- [Telemetry](https://open-codereview.ai/docs/telemetry) — OpenTelemetry integration for observability
+- [FAQ](https://open-codereview.ai/docs/faq) — common questions and troubleshooting
 
 ## Contributing