@agentskit/code-review 0.1.0 → 0.4.2

package/README.md

@@ -1,12 +1,34 @@
+<p align="center">
+  <img src="docs/assets/agentskit-mark.svg" width="64" height="57" alt="AgentsKit" />
+</p>
+
 # AgentsKit Code Review
 
+Profile: <code>top-level-repository</code>
+
 **Deep, low-noise AI code review with the model you already use.**
 
-[![CI](https://github.com/AgentsKit-io/code-review-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/AgentsKit-io/code-review-cli/actions/workflows/ci.yml)
+It is intended for developers and teams who want focused review feedback without changing their model subscription, and without adopting a separate chat product surface.
+
+[![CI](https://github.com/AgentsKit-io/code-review/actions/workflows/ci.yml/badge.svg)](https://github.com/AgentsKit-io/code-review/actions/workflows/ci.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13866/baseline)](https://www.bestpractices.dev/projects/13866)
 [![License: MIT](https://img.shields.io/badge/License-MIT-0f766e.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
 
-Run code review locally or on every pull request. Bring Claude, Codex, OpenAI, Gemini, Ollama, OpenRouter, or another AgentsKit adapter. Seven specialized review lenses find potential problems; adversarial verification filters weak findings before they reach your team.
+**Tags:** `agentskit` · `ai-code-review` · `github-action` · `typescript` · `sarif` · `codex` · `claude` · `ollama`
+
+**Topics:** `ai-agents` · `code-review` · `developer-experience`
+
+**Ecosystem:** [AgentsKit](https://www.agentskit.io/docs) · [Registry](https://registry.agentskit.io/docs) · [Chat](https://chat.agentskit.io/docs) · [Playbook](https://playbook.agentskit.io/docs) · [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) · **Code Review** · [AKOS](https://akos.agentskit.io/docs)
+
+Run code review locally or on every pull request. Bring Claude, Codex, OpenAI, Gemini, Ollama, OpenRouter, or another supported AgentsKit adapter. Seven focused review lenses propose potential problems; adversarial verification filters weak findings before they reach your team.
+
+## Verified proof
+
+- Offline CLI discovery works without credentials (`--help`, `--list-providers`) — covered by `test/cli-smoke.test.mjs`.
+- A clean local Codex CLI fixture completes an offline stdin review — covered by the same smoke suite.
+- Documentation, Action contract, and Doc Bridge gates run through `npm run check`.
+- Machine-readable public map: [`llms.txt`](llms.txt) and [`docs/for-agents/code-review-cli.md`](docs/for-agents/code-review-cli.md).
 
 ## Why this exists
 
@@ -18,31 +40,98 @@ AgentsKit Code Review is built around a different contract:
 - **Low noise by design.** Findings are challenged by independent verification votes before they survive.
 - **Local first, CI ready.** Review a diff before pushing, inspect complete paths, read stdin, or comment directly on a GitHub PR.
 - **Control cost and policy.** Set file budgets, concurrency, thresholds, project conventions, and blocking severity.
+- **See the cost before execution.** Use `--plan --json` to inspect files, lenses, retries, concurrency, deadline, estimated provider calls, and every `UNREVIEWED` path with its reason without a model request. Estimates are always `best-effort` because primary lens demand is predictable but model output determines how many skeptical verification calls are needed; the runtime counter remains the hard ceiling.
 
 ## Run your first review
 
 Open a terminal inside any Git repository and choose a provider you already use. You do not need to clone or install AgentsKit Code Review:
 
+<!-- readme-example:first-review -->
 ```sh
-# Codex CLI — uses your existing login
-npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli
+# Codex CLI — uses your existing login on a trusted local machine
+npx --yes github:AgentsKit-io/code-review --provider codex-cli --mode trusted-local
 
 # Claude CLI — uses your existing login
-npx --yes github:AgentsKit-io/code-review-cli --provider claude-cli
+npx --yes github:AgentsKit-io/code-review --provider claude-cli
 
 # OpenAI API
-OPENAI_API_KEY=... npx --yes github:AgentsKit-io/code-review-cli \
+OPENAI_API_KEY=... npx --yes github:AgentsKit-io/code-review \
   --provider openai --model gpt-4o
 ```
 
 The CLI reviews the current repository's diff against `origin/main` and prints the report in your terminal. Choose another base with `--base main`.
 
+For the Grok Build ACP worker, use `XAI_API_KEY` (or `--api-key`) in the default isolated mode. To reuse `grok login`, opt in explicitly with `--mode trusted-local`.
+
+Local `codex-cli` subprocesses have a 300-second deadline per model call; `claude-cli` and the other local workers use 120 seconds. Every run also has a global deadline (10 minutes for full, 2 minutes for `fast`) and a bounded Codex smoke check before fan-out. Set `--deadline-ms` for a smaller explicit budget; timed-out calls fail explicitly and cannot turn an unreviewed file into an approval.
+
+Terminal provider authentication failures stop the remaining lenses immediately; the review still exits incomplete and never converts a credential failure into approval.
+
+The default `isolated` mode does not inherit an interactive CLI login. Use `--mode trusted-local` only on a machine or runner you trust with the provider's local session and environment.
+
+`grok-cli` is stable and uses Grok Build's ACP transport (`grok agent stdio`) by default. In the default isolated mode, pass `XAI_API_KEY`/`--api-key`; the key is injected into the isolated worker environment, never into command arguments. Existing `grok login` state is available only with explicit local-only `--mode trusted-local`. Isolated workers grant no filesystem write, terminal, MCP, plugin, or subagent capability and use a temporary working directory. `--transport headless` is available for explicit non-interactive runs, while `--transport auto` is local-only and reports an ACP fallback before trying headless.
+
+`opencode-cli` is stable and uses OpenCode's ACP transport (`opencode acp`) by default. In the default isolated mode, pass `OPENCODE_API_KEY`/`--api-key`; the selected key is injected into the isolated worker environment, never into command arguments. Existing OpenCode login/configuration state is available only with explicit local-only `--mode trusted-local`. OpenCode is not installed automatically. `--transport headless` is available for explicit non-interactive runs, while `--transport auto` is local-only and reports an ACP fallback before trying headless.
+
+Preflight refuses an over-budget run before the first provider call. For GitHub PR sources, the CLI automatically caps the reviewed files to the safe call budget when `--max-files` is omitted; the remaining files are marked `UNREVIEWED`, so the result stays incomplete and cannot approve the PR. Use `--max-files` to choose a smaller explicit scope. `--dry-run` and `--plan` print the cap and concrete reductions; `--json` makes the plan machine-readable. CLI providers default to concurrency `1`, while API providers retain concurrency `4`. Required-lens or source coverage failures always exit `2`, even with `--no-fail`.
+Use `--profile fast` when latency and provider budget matter more than the optional lenses: correctness, security, and tests run in one structured batch with one verification vote and no retry. The result records provider calls, failures, skips, elapsed time, circuit state, and whether the deadline fired. Any incomplete evidence remains fail-closed.
+
+### Complete coverage for large PRs
+
+Do not silently cap a large PR and treat the partial result as clean. `--plan --json --batch-size <n>` exposes a stable, alphabetically ordered file manifest. With a GitHub PR, `--batch-manifest <private-file>` writes the immutable state that binds every batch to the exact head SHA and review-policy fingerprint. Run each batch with `--batch-index <n> --result <private-file>`; partial batches reject `--post` and their result files are private (`0600`). `--consolidate-manifest <manifest> --artifacts <comma-list> --result <private-file>` accepts only every planned batch with complete evidence. Its output is the only artifact accepted by `--publish-result <file> --pr owner/repo#N --post`; that command rechecks the current SHA and policy before creating one GitHub review. A new commit or policy change invalidates the artifacts and requires a new manifest.
+
+![AgentsKit Code Review showing an APPROVE result after seven review lenses complete](docs/assets/code-review-terminal.png)
+
 The current command runs directly from GitHub. After the first npm release, the shorter form will be:
 
 ```sh
 npx @agentskit/code-review --provider codex-cli
 ```
 
+## Run through pre-commit
+
+The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter.
+
+Add this to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AgentsKit-io/code-review
+    rev: main # pre-release; pin a release tag when one contains the hook
+    hooks:
+      - id: agentskit-review
+        args: [--provider, codex-cli, --no-fail, --max-files, "20"]
+```
+
+Then run it when a change is ready for review:
+
+```sh
+pre-commit run --hook-stage manual agentskit-review
+```
+
+The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository.
+
+### Review locally with Ollama
+
+Use Ollama when repository policy requires model inference to stay on a machine or self-hosted runner. Pull a tool-capable coding model that fits the available memory, start Ollama, and review a small branch diff first:
+
+```sh
+ollama pull qwen2.5-coder:7b
+
+npx --yes github:AgentsKit-io/code-review \
+  --provider ollama \
+  --model qwen2.5-coder:7b \
+  --base main \
+  --base-url http://localhost:11434 \
+  --max-files 10 \
+  --concurrency 1 \
+  --no-fail
+```
+
+This reviews committed changes between `main` and `HEAD`; it is not a staged-files-only hook. The selected model must support Ollama tool calling because every review lens submits a structured result. Requests have a 30-second default deadline. `--no-fail` keeps findings advisory, but connection, source, and execution errors still exit nonzero. No provider key is required. Local inference reduces code disclosure, but logs, SARIF files, caches, optional gateways, and observability exporters still need their own access and retention policy.
+
+See the [operations guide](docs/OPERATIONS.md#local-ollama-review) for model sizing, health checks, failure handling, and self-hosted CI guidance.
+
 ## Use the GitHub Action
 
 Add `.github/workflows/code-review.yml` to any repository:
@@ -61,29 +150,36 @@ jobs:
   review:
     runs-on: ubuntu-latest
     steps:
-      - uses: AgentsKit-io/code-review-cli@main
+      - uses: AgentsKit-io/code-review@v0.4.0
         with:
           provider: openai
           model: gpt-4o
           api-key: ${{ secrets.LLM_API_KEY }}
+          # max-files: '17'
+          # max-calls: '1000'
+          # max-findings-per-file: '7'
+          # profile: 'full' # or fast for a bounded required-lens batch
+          # deadline-ms: '600000'
           # fail-on-block: 'true' # advisory by default
           # block: high
 ```
 
-The Action fetches the PR diff and posts one batched inline review plus a summary. It is advisory by default. Enable `fail-on-block` and branch protection when you are ready to use it as a merge gate.
+The Action fetches the PR diff and posts one batched inline review plus a compact, persistent walkthrough. The walkthrough reports outcome and review evidence; actionable detail appears only on the relevant diff lines. Its defaults review at most 17 files, 7 findings per file, and 1,000 provider calls. It is advisory by default. Advisory mode affects findings only: source, provider, or execution failures still fail the check, and any reviewable file with zero successful primary lenses prevents approval. `codex-cli` requires a pre-authenticated `trusted-local` self-hosted runner; use an API provider with a secret on GitHub-hosted runners. Enable `fail-on-block` and branch protection when you are ready to use findings as a merge gate.
 
-Use `@main` while the project is pre-release. After the first stable release, pin `@v1` or a full release tag when reproducibility matters most.
+Building a conversational review experience? Use [AgentsKit Chat](https://chat.agentskit.io/docs) for the cross-framework application layer instead of embedding chat here. Looking for organization-wide orchestration, governance, and production controls? Continue with [AKOS](https://akos.agentskit.io/docs).
+
+Pin the Action to an immutable release tag such as `@v0.4.0`; use a full commit SHA when your policy requires the strongest reproducibility.
 
 ## Choose how to run
 
 | Mode | Provider examples | Credentials | Best for |
 |---|---|---|---|
-| Local CLI | `codex-cli`, `claude-cli` | Existing CLI login | Local development or self-hosted runners |
+| Local CLI | `codex-cli`, `claude-cli`, `grok-cli`, `opencode-cli` | Existing CLI login | Local development or self-hosted runners |
 | Hosted API | `openai`, `anthropic`, `gemini`, `mistral`, `groq` | Provider API key | Managed CI |
 | Local model | `ollama` | Usually none | Privacy and predictable cost |
 | Gateway | `openrouter` or a custom `--base-url` | Gateway-specific | Central routing and policy |
 
-Provider names other than the two local CLIs resolve to factories exported by [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters). Run `npx --yes github:AgentsKit-io/code-review-cli --list-providers` for common choices.
+`grok` is the xAI API provider; `grok-cli` is the separate Grok Build CLI entry. `opencode-cli` is the OpenCode CLI entry. API providers are discovered from factories exported by [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters). Run `npx --yes github:AgentsKit-io/code-review --list-providers` to see IDs, support levels, transports, and model requirements.
 
 Credentials resolve in this order:
 
@@ -95,18 +191,14 @@ Secrets passed to the GitHub Action are forwarded through the environment, not i
 
 ## How review works
 
-```text
-diff / PR / paths / stdin
-          ↓
-   normalize targets
-          ↓
-  7 specialized lenses
-          ↓
- adversarial verification
-          ↓
- thresholds + CI policy
-          ↓
-Markdown / GitHub / SARIF
+```mermaid
+flowchart LR
+  A["Diff · PR · paths · stdin"] --> B["Normalize targets"]
+  B --> C["7 focused lenses"]
+  C --> D["Adversarial verification"]
+  D --> E["Thresholds + CI policy"]
+  E --> F["Markdown · GitHub · SARIF"]
+  D -. "weak finding" .-> G["Dropped with audit note"]
 ```
 
 The review agent lives in `agents/code-review/` and is vendored from the [AgentsKit registry](https://github.com/AgentsKit-io/agentskit-registry/tree/main/registry/code-review). The CLI owns provider selection, input sources, policy, and reporting.
@@ -115,24 +207,36 @@ The review agent lives in `agents/code-review/` and is vendored from the [Agents
 
 ```sh
 # Tune verification and severity
-npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli \
+npx --yes github:AgentsKit-io/code-review --provider codex-cli \
   --base main --votes 5 --min-severity high
 
 # Review a GitHub PR and post the result
 GITHUB_TOKEN=... OPENAI_API_KEY=... \
-  npx --yes github:AgentsKit-io/code-review-cli --provider openai --model gpt-4o \
+  npx --yes github:AgentsKit-io/code-review --provider openai --model gpt-4o \
   --pr owner/repo#42 --post
 
 # Review complete files or directories
-npx --yes github:AgentsKit-io/code-review-cli --provider claude-cli \
+npx --yes github:AgentsKit-io/code-review --provider claude-cli \
   --paths src --max-files 30
 
 # Review piped source and also write SARIF
-echo 'const x = a.b' | npx --yes github:AgentsKit-io/code-review-cli \
+echo 'const x = a.b' | npx --yes github:AgentsKit-io/code-review \
   --provider ollama --model llama3 \
   --base-url http://localhost:11434 --stdin --lang ts --sarif out.sarif
+
+# After fetching the PR base and installing reviewdog, reuse its annotation transport
+REPORT_FILE="$(mktemp)"
+trap 'rm -f "${REPORT_FILE}"' EXIT
+npx --yes github:AgentsKit-io/code-review#3dfd7427640148281454d52846d369e5ddf85b11 \
+  --provider openai --model gpt-4o \
+  --base "origin/${BASE_REF}" --sarif "${REPORT_FILE}" --no-fail &&
+reviewdog -f=sarif -name=agentskit-review \
+  -reporter=github-pr-review -filter-mode=added -fail-level=error \
+  < "${REPORT_FILE}"
 ```
 
+The reviewdog recipe needs no custom converter: Code Review emits SARIF 2.1.0 and reviewdog consumes SARIF natively. See the [complete GitHub Actions job](docs/OPERATIONS.md#route-findings-through-reviewdog) for pinned installation, base-branch checkout, permissions, severity mapping, and CI ownership of the failure threshold.
+
 ## CLI reference
 
 ### Providers
@@ -141,8 +245,10 @@ Run these commands from the repository you want to review:
 
 | Provider | What you need | Model | Example |
 |---|---|---|---|
-| `codex-cli` | Codex CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review-cli --provider codex-cli` |
-| `claude-cli` | Claude CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review-cli --provider claude-cli` |
+| `codex-cli` | Codex CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review --provider codex-cli` |
+| `claude-cli` | Claude CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review --provider claude-cli` |
+| `grok-cli` | Grok Build CLI; stable ACP/headless | Optional | `... --provider grok-cli` |
+| `opencode-cli` | OpenCode CLI; stable ACP/headless | Optional | `... --provider opencode-cli` |
 | `openai` | `OPENAI_API_KEY` | Required | `... --provider openai --model gpt-4o` |
 | `anthropic` | `ANTHROPIC_API_KEY` | Required | `... --provider anthropic --model <model>` |
 | `gemini` | `GEMINI_API_KEY` | Required | `... --provider gemini --model <model>` |
@@ -150,7 +256,7 @@ Run these commands from the repository you want to review:
 | `openrouter` | `OPENROUTER_API_KEY` | Required | `... --provider openrouter --model <model>` |
 | Other adapters | `<PROVIDER>_API_KEY` when applicable | Usually required | `... --provider <name> --model <model>` |
 
-In shortened examples, replace `...` with `npx --yes github:AgentsKit-io/code-review-cli`.
+In shortened examples, replace `...` with `npx --yes github:AgentsKit-io/code-review`.
 
 ### Options
 
@@ -160,6 +266,7 @@ In shortened examples, replace `...` with `npx --yes github:AgentsKit-io/code-re
 | `--model <id>` | Model id; required for API/local-server providers |
 | `--api-key <key>` | Provider key; environment variables are preferred |
 | `--base-url <url>` | Provider endpoint, local server, or gateway |
+| `--transport <name>` | Provider transport: `acp`, `headless`, or local-only `auto` where supported |
 | `--base <ref>` | Git diff base; default `origin/main` |
 | `--pr owner/repo#N` | GitHub PR source; requires `GITHUB_TOKEN` |
 | `--paths <p...>` | Complete files or directories |
@@ -167,28 +274,126 @@ In shortened examples, replace `...` with `npx --yes github:AgentsKit-io/code-re
 | `--post` | Post a batched review when the source is a PR |
 | `--sarif <file>` | Also write SARIF |
 | `--votes <n>` | Adversarial verification votes; default `3` |
+| `--profile <full\|fast>` | Full review or one bounded required-lens batch |
 | `--min-severity <level>` | Minimum reported severity |
 | `--min-confidence <n>` | Minimum reported confidence |
-| `--max-files <n>` | File budget |
-| `--concurrency <n>` | Parallel model calls; default `4` |
+| `--max-files <n>` | Positive file budget; over-budget runs are refused before the provider |
+| `--max-calls <n>` | Provider-call budget; absolute ceiling `1000` |
+| `--max-findings-per-file <n>` | Maximum verified findings per file; bounds adversarial verification calls |
+| `--concurrency <n>` | Parallel model calls; default `1` for CLI providers, `4` for API providers |
+| `--deadline-ms <n>` | Global run deadline; defaults to `600000` (`120000` for `fast`) |
+| `--health-check <auto\|off>` | Bounded provider smoke check before model fan-out |
+| `--plan`, `--dry-run` | Print provider-free preflight; add `--json` for machine output |
 | `--validate-patch` | Run `git apply --check` on suggested patches |
 | `--block <severity>` | CI gate floor; default `blocker` |
 | `--no-fail` | Keep findings advisory |
 | `--conventions <path>` | Inject project conventions |
+| `--allow-incomplete` | Local-only exception for a config that declares incomplete lens coverage |
+| `--allow-unredacted` | Local-only exception; rejected in CI |
 | `--api` | Back-compatible alias for `--provider anthropic` |
+| `doctor --provider <name>` | Offline provider diagnostics; no model request |
+| `doctor --live` | Explicit provider smoke-test mode |
+| `doctor --json` | Stable machine-readable diagnostics |
+| `--mode <mode>` | `isolated` (default) or explicit local-only `trusted-local` |
 | `--help` | Full command help |
 
 When no conventions path is supplied, the CLI looks for `CONVENTIONS.md`, `CONTRIBUTING.md`, `.cursorrules`, or `AGENTS.md`.
 
+### Versioned configuration
+
+The repository may contain one strict `.agentskit-review.json` file. It must use
+`configVersion: 1`; unknown fields, secrets, unsupported values, and unsafe lens
+policies fail before provider execution with exit `2`. Every built-in lens is
+enabled by default, with `correctness`, `security`, and `tests` required. Flags
+override file values. A required lens may only be disabled in an explicitly
+declared `incompleteProfile`, which requires `--allow-incomplete` locally and is
+never accepted in CI.
+
+```json
+{
+  "configVersion": 1,
+  "profile": "full",
+  "lenses": {
+    "performance": { "enabled": false, "required": false }
+  },
+  "votes": 3,
+  "budget": { "maxFiles": 20, "maxCalls": 200, "concurrency": 1, "deadlineMs": 600000 },
+  "worker": { "timeoutMs": 120000, "maxOutputBytes": 20971520 },
+  "thresholds": { "minSeverity": "med", "minConfidence": 0.7 },
+  "context": { "mode": "prompt", "patterns": ["src/**"] }
+}
+```
+
+Provider, model, transport, context trust, redaction, and permissions are
+trusted execution inputs; a project config cannot set them in CI. Put provider
+credentials only in the environment or provider login, never in this file.
+Remote and unknown provider boundaries redact high-confidence credential
+patterns before the model sees source. Unsafe, oversized, binary, or excluded
+paths are reported as `UNREVIEWED`; content is never silently truncated.
+
+### Doctor
+
+Run `doctor` before a review to check a registered provider’s executable, version, transport, model requirement, configuration mode, and credential presence. It is offline by default; `doctor --live` and normal Codex reviews use a bounded smoke check to catch authentication or hangs before fan-out. API credentials are checked only for presence and values are never printed. Unknown local CLI versions warn locally and fail when `CI=true`. Exit `0` means healthy, `1` means a failed diagnostic, and `2` means invalid CLI usage.
+
+```sh
+npx --yes github:AgentsKit-io/code-review doctor --provider codex-cli
+npx --yes github:AgentsKit-io/code-review doctor --provider openai --model gpt-4o --json
+```
+
 ## Cost and privacy
 
-A full review runs seven lenses across selected files and then verifies candidate findings. Control usage with `--max-files`, `--votes`, `--concurrency`, paths, and workflow triggers. For sensitive code, use a local model or an approved private gateway; provider data policies still apply to hosted APIs.
+A full review runs seven lenses across selected files and then verifies candidate findings. Control usage with `--profile fast`, `--max-files`, `--max-calls`, `--votes`, `--deadline-ms`, `--concurrency`, paths, and workflow triggers. For sensitive code, use a local model or an approved private gateway; provider data policies still apply to hosted APIs.
+
+## Operations and machine-readable docs
+
+- [Operations guide](docs/OPERATIONS.md) — providers, permissions, secrets, cost controls, SARIF, failures, releases, and incident-safe defaults.
+- [Provider compatibility matrix](docs/provider-compatibility.json) — stable CLI transports and their offline fixtures.
+- [Agent handoff](docs/for-agents/code-review-cli.md) — ownership, edit roots, verification commands, and change routes.
+- [`llms.txt`](llms.txt) — compact public source map for LLMs and coding agents.
+- [`llms-full.txt`](llms-full.txt) — complete README, operations, and agent-handoff corpus.
+- [`doc-bridge.config.json`](doc-bridge.config.json) — executable Doc Bridge corpus, ownership, and gate contract.
+
+`npm run check` builds the CLI, executes a full credential-free review fixture, validates the composite Action and documentation contract, runs Doc Bridge gates, checks CLI help, and enforces README Standard v1. Prove credential-free discovery with:
+
+```sh
+node examples/verify-readme.mjs
+```
+
+`npm pack --dry-run` verifies the release payload.
+
+## Maturity
+
+The repository is **pre-v1 (`0.4.x`)**. The CLI and Action are available for evaluation and advisory CI; use an exact release tag such as `@v0.4.0` or a commit SHA, and treat the future `v1` moving tag as a separate stability milestone. See [ROADMAP.md](ROADMAP.md) and the [release guidance](docs/OPERATIONS.md#releases-and-maturity).
+
+## Compatibility
+
+- **Node.js 20+** (see `engines` in `package.json`)
+- **TypeScript** source and compiled ESM distribution
+- **GitHub Actions** composite Action at repository root (`action.yml`)
+- Providers via local CLIs or [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters)
+
+## AgentsKit ecosystem
+
+Code Review is the verification step in the broader AgentsKit journey:
+
+| Need | Continue with |
+|---|---|
+| Build the agent or custom review adapter | [AgentsKit](https://www.agentskit.io/docs) |
+| Install the vendored review agent or explore ready agents | [Registry](https://registry.agentskit.io/docs) |
+| Deliver review through a conversational application | [AgentsKit Chat](https://chat.agentskit.io/docs) |
+| Apply engineering patterns before review | [Playbook](https://playbook.agentskit.io/docs) |
+| Generate ownership-aware documentation handoffs | [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) ([source](https://github.com/AgentsKit-io/doc-bridge)) |
+| Add enterprise orchestration and production governance | [AKOS](https://akos.agentskit.io/docs) |
+
+This repository intentionally has **no Fumadocs application and no embedded AgentsChat**. Its public product surface is the CLI, GitHub Action, repository documentation, and machine-readable handoffs.
 
 ## Contributing
 
 Providers, review lenses, reporters, fixtures, documentation, and false-positive reductions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), browse issues labeled `good first issue`, or propose a new provider/lens with the issue templates.
 
 Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+Maintainer responsibilities, public decision-making, and the release process are
+documented in [GOVERNANCE.md](GOVERNANCE.md).
 
 ## Roadmap
 

package/ROADMAP.md

@@ -0,0 +1,20 @@
+# Roadmap
+
+This roadmap communicates direction, not a promise of dates.
+
+## Toward v1
+
+- [ ] Publish the calibrated `0.4.x` line of `@agentskit/code-review` and signed release artifacts.
+- [ ] Publish immutable GitHub Action releases with a moving `v1` tag.
+- [ ] Add credential-free adapter contract tests and opt-in provider smoke tests.
+- [ ] Document measured review cost and latency by configuration.
+- [ ] Expand fixtures for false-positive and multi-language regression testing.
+
+## Community tracks
+
+- Review lenses with precise evidence and low false-positive rates.
+- Additional local CLI and private-gateway adapters.
+- Reporters for other code-hosting and CI systems.
+- Better SARIF, monorepo, and large-diff workflows.
+
+Open an issue before starting a large item so maintainers and contributors can align on scope.

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published release. Older releases may
+be asked to upgrade before receiving a fix.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/AgentsKit-io/code-review/security/advisories/new) with the affected version, impact, reproduction steps, and any suggested mitigation.
+
+Please do not include secrets or private source code beyond what is necessary to reproduce the issue. We aim to acknowledge a complete report within 14 days, investigate it, and coordinate disclosure and remediation with the reporter. If the report is accepted, we will keep the reporter informed as the fix progresses.
+
+## Scope reminders
+
+This tool sends selected code to the provider you configure. Review that provider's data handling policy before using a hosted API. Prefer a local model or approved private gateway for repositories whose policy prohibits external processing. Store GitHub tokens and provider keys as secrets; never commit them to workflow files.

package/action.yml

@@ -0,0 +1,120 @@
+name: 'AgentsKit Code Review'
+description: 'Deep, low-noise AI code review on a pull request — 7 lenses + adversarial verification. Advisory by default.'
+branding:
+  icon: 'check-circle'
+  color: 'green'
+
+inputs:
+  provider:
+    description: 'Provider to use: a local CLI (claude-cli, codex-cli) or any @agentskit/adapters provider such as anthropic, openai, gemini, ollama, or openrouter.'
+    required: true
+  mode:
+    description: 'Execution mode: isolated (default) or trusted-local for an explicitly trusted runner with an existing CLI login.'
+    required: false
+    default: 'isolated'
+  api-key:
+    description: 'API key for the provider (required unless provider is claude-cli or a keyless local provider). Set as a repo/org secret. Passed via env, never the command line.'
+    required: false
+  claude-oauth-token:
+    description: 'For provider=claude-cli on headless/CI runners: a long-lived token from `claude setup-token` (uses your subscription, no per-call API cost). Set as a secret. Headless `claude -p` cannot use the interactive login session.'
+    required: false
+  base-url:
+    description: 'Override the provider base URL (e.g. ollama / openrouter / a self-hosted gateway).'
+    required: false
+    default: ''
+  github-token:
+    description: 'Token used to read the PR diff and post the review.'
+    required: false
+    default: ${{ github.token }}
+  model:
+    description: 'Model id. Required for API and local-server providers; optional for CLI providers.'
+    required: false
+  block:
+    description: 'Severity floor for the gate: blocker | high.'
+    required: false
+    default: 'high'
+  fail-on-block:
+    description: 'Fail the check when a finding at/above `block` survives. Default false (advisory — posts but never blocks).'
+    required: false
+    default: 'false'
+  votes:
+    description: 'Adversarial verify votes per finding.'
+    required: false
+    default: '3'
+  max-files:
+    description: 'Max files reviewed per run (budget cap).'
+    required: false
+    default: '17'
+  max-calls:
+    description: 'Maximum provider calls per run (absolute ceiling 1000).'
+    required: false
+    default: '1000'
+  max-findings-per-file:
+    description: 'Maximum findings verified per file; keeps the provider-call estimate bounded.'
+    required: false
+    default: '7'
+  profile:
+    description: 'Review profile: full or fast (one bounded required-lens batch).'
+    required: false
+    default: 'full'
+  deadline-ms:
+    description: 'Global review deadline in milliseconds.'
+    required: false
+    default: '600000'
+  health-check:
+    description: 'Provider preflight smoke test: auto or off.'
+    required: false
+    default: 'auto'
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      with:
+        node-version: '22'
+    - name: Install code-review
+      shell: bash
+      run: cd "$GITHUB_ACTION_PATH" && npm ci
+    - name: Review pull request
+      shell: bash
+      env:
+        LLM_API_KEY: ${{ inputs.api-key }}
+        CLAUDE_CODE_OAUTH_TOKEN: ${{ inputs.claude-oauth-token }}
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+        INPUT_PROVIDER: ${{ inputs.provider }}
+        INPUT_MODE: ${{ inputs.mode }}
+        INPUT_MODEL: ${{ inputs.model }}
+        INPUT_BASE_URL: ${{ inputs.base-url }}
+        INPUT_VOTES: ${{ inputs.votes }}
+        INPUT_MAX_FILES: ${{ inputs.max-files }}
+        INPUT_MAX_CALLS: ${{ inputs.max-calls }}
+        INPUT_MAX_FINDINGS_PER_FILE: ${{ inputs.max-findings-per-file }}
+        INPUT_PROFILE: ${{ inputs.profile }}
+        INPUT_DEADLINE_MS: ${{ inputs.deadline-ms }}
+        INPUT_HEALTH_CHECK: ${{ inputs.health-check }}
+        INPUT_BLOCK: ${{ inputs.block }}
+        INPUT_FAIL_ON_BLOCK: ${{ inputs.fail-on-block }}
+      run: |
+        cd "$GITHUB_ACTION_PATH"
+        if [[ "$INPUT_PROVIDER" == "codex-cli" && "$INPUT_MODE" != "trusted-local" ]]; then
+          echo "::error::codex-cli requires a pre-authenticated trusted-local runner; use provider openai with api-key on GitHub-hosted runners."
+          exit 2
+        fi
+        args=(
+          --pr "${{ github.repository }}#${{ github.event.pull_request.number }}" \
+          --post \
+          --provider "$INPUT_PROVIDER" \
+          --mode "$INPUT_MODE" \
+          --votes "$INPUT_VOTES" \
+          --max-files "$INPUT_MAX_FILES" \
+          --max-calls "$INPUT_MAX_CALLS" \
+          --max-findings-per-file "$INPUT_MAX_FINDINGS_PER_FILE" \
+          --profile "$INPUT_PROFILE" \
+          --deadline-ms "$INPUT_DEADLINE_MS" \
+          --health-check "$INPUT_HEALTH_CHECK" \
+          --block "$INPUT_BLOCK"
+        )
+        [[ -n "$INPUT_MODEL" ]] && args+=(--model "$INPUT_MODEL")
+        [[ -n "$INPUT_BASE_URL" ]] && args+=(--base-url "$INPUT_BASE_URL")
+        [[ "$INPUT_FAIL_ON_BLOCK" == "true" ]] || args+=(--no-fail)
+        npm run --silent review -- "${args[@]}"