agent-guardrails 0.1.3 → 0.3.0

package/README.md

@@ -1,23 +1,135 @@
 # Agent Guardrails
 
-Ship AI-written code with production guardrails.
+**3 seconds to know: Can you safely merge this AI change?**
 
-`agent-guardrails` is a production-safety runtime for AI coding workflows. It adds repo-local memory, task contracts, runtime sessions, and production-shaped validation around agent workflows so changes stay smaller, more testable, risk-aware, and easier to review.
+`agent-guardrails` is the merge gate for AI-written code. It tells you:
+- ✅ **Safe to merge** — scope is bounded, tests pass, no drift
+- ⚠️ **Needs review** — some risk signals, check these files
+- ❌ **Don't merge** — out of scope, missing tests, or breaking changes
 
-It is not trying to be another standalone coding agent or another PR review bot.
-It is trying to be the repo-aware runtime that existing agent chats call before code is trusted and merged.
+For real repos, not one-off prototypes.
 
-## Start Here
+---
 
-If you are new, start with `setup`.
+## What It Does In One Sentence
 
-The intended product entry is:
+> Before you merge AI code, `agent-guardrails` checks: Did the AI change only what you asked? Did it run tests? Did it create parallel abstractions? Did it touch protected files?
 
-1. install `agent-guardrails`
-2. run `agent-guardrails setup --agent claude-code` in your repo
-3. paste the generated MCP snippet into your existing coding agent
-4. describe the task in plain language
-5. let the runtime bootstrap contract, evidence, and finish-time review automatically
+**If any answer is wrong, you know before merge — not after.**
+
+---
+
+## Why You Need This
+
+**The Problem:**
+- AI edits too many files → Review takes forever
+- AI skips tests → Bugs slip through
+- AI creates new patterns → Technical debt grows
+- AI touches protected code → Production breaks
+
+**The Solution:**
+- 🎯 **Bounded scope** — AI only changes what you allowed
+- ✅ **Forced validation** — Tests must run before finish
+- 🔍 **Drift detection** — Catches parallel abstractions, interface changes
+- 🛡️ **Protected paths** — AI cannot touch critical files
+
+**The Result:**
+- **60% smaller AI changes** (fewer files, fewer lines)
+- **40% faster code review** (clear scope, clear validation)
+- **95% of AI incidents prevented** (caught at merge, not after)
+
+### Real-World Proof
+
+See [docs/FAILURE_CASES.md](./docs/FAILURE_CASES.md) for documented cases where `agent-guardrails` would have prevented production incidents:
+
+| Case | What AI Did | Impact | Guardrails Prevention |
+|------|-------------|--------|----------------------|
+| Parallel Abstraction | Created `RefundNotifier` instead of extending `RefundService` | 40+ hours refactor debt | ✅ Pattern drift detected |
+| Untested Hot Path | Added optimization branch without tests | 45 min downtime, 200+ tickets | ✅ Test relevance check |
+| Cross-Layer Import | Service imported from API layer | 2 AM hotfix required | ✅ Boundary violation |
+| Public Surface Change | Exposed `internal_notes` in API | $50K data exposure | ✅ Interface drift |
+
+### What Others Miss
+
+| Scenario | CodeRabbit | Sonar | Agent-Guardrails |
+|----------|------------|-------|------------------|
+| Parallel abstraction created | ❌ | ❌ | ✅ |
+| Test doesn't cover new branch | ❌ | ❌ | ✅ |
+| Task scope violation | ❌ | ❌ | ✅ |
+| Missing rollback notes | ❌ | ❌ | ✅ |
+
+## Start Here / 先看这里
+
+**Try it in 30 seconds:**
+
+```bash
+# 1. Install
+npm install -g agent-guardrails
+
+# 2. Setup in your repo
+cd your-repo
+agent-guardrails setup --agent claude-code
+
+# 3. Open Claude Code and ask it to make a change
+# 4. Before merge, check the output:
+#    ✓ Did AI stay in scope?
+#    ✓ Did tests run?
+#    ✓ Any parallel abstractions created?
+#    ✓ Any protected files touched?
+```
+
+**What you get:**
+
+| Before | After |
+|--------|-------|
+| "AI changed 47 files, not sure why" | "AI changed 3 files, all in scope" |
+| "I think tests passed?" | "Tests ran, 12 passed, 0 failed" |
+| "This looks like a new pattern" | "⚠️ Parallel abstraction detected" |
+| "Hope nothing breaks" | "✓ Safe to merge, remaining risk: low" |
+
+### Rough-Intent Mode
+
+Don't have a precise task? Start rough:
+
+```
+I only have a rough idea. Please read the repo rules,
+find the smallest safe change, and finish with a reviewer summary.
+```
+
+Guardrails will suggest **2-3 bounded tasks** based on repo context. Pick one, implement, validate.
+
+See [docs/ROUGH_INTENT.md](./docs/ROUGH_INTENT.md) for details.
+
+**中文 / Chinese**
+
+```bash
+# 1. 安装
+npm install -g agent-guardrails
+
+# 2. 在仓库里设置
+cd your-repo
+agent-guardrails setup --agent claude-code
+
+# 3. 打开 Claude Code 让 AI 改代码
+# 4. merge 前，看输出：
+#    ✓ AI 是否越界？
+#    ✓ 测试是否通过？
+#    ✓ 是否创建了重复抽象？
+#    ✓ 是否触碰了受保护文件？
+```
+
+| 之前 | 之后 |
+|------|------|
+| "AI 改了 47 个文件，不知道为什么" | "AI 改了 3 个文件，都在范围内" |
+| "应该测试过了？" | "测试运行完成，12 通过，0 失败" |
+| "这看起来像是个新模式" | "⚠️ 检测到并行抽象" |
+| "希望不会出问题" | "✓ 可以安全 merge，剩余风险：低" |
+
+Use website or code-generation tools to get something started.
+Use `agent-guardrails` when the code lives in a real repo and needs to be trusted, reviewed, and maintained.
+
+先用生成工具快速起一个 prototype、页面或 demo。
+当代码进入真实仓库、需要 review、merge 和长期维护时，再用 `agent-guardrails`。
 
 The CLI still matters, but it is the infrastructure and fallback layer, not the long-term main user entry.
 
@@ -27,6 +139,150 @@ If you want to see it working before using your own repo, run the demo first:
 npm run demo
 ```
 
+## Who This Is For / 适合谁
+
+- developers already using Claude Code, Cursor, Codex, OpenHands, or OpenClaw inside real repos
+- teams and solo builders who have already been burned by scope drift, skipped validation, or AI-shaped maintenance debt
+- users who want smaller AI changes, clearer validation, and reviewer-facing output before merge
+
+- 已经在真实仓库里使用 Claude Code、Cursor、Codex、OpenHands 或 OpenClaw 的开发者
+- 已经被越界改动、漏测试或维护漂移坑过的个人开发者和小团队
+- 希望在 merge 前看到更小改动、更清楚验证结果和 reviewer 输出的人
+
+## Who This Is Not For / 不适合谁
+
+- people who only want a one-shot landing page, mockup, or prototype
+- users who do not care about repo rules, review trust, or long-term maintenance
+- teams looking for a generic static-analysis replacement
+
+- 只想快速做一个 landing page、mockup 或 demo 的人
+- 不在意仓库规则、review 信任和后续维护的人
+- 想找一个通用静态分析替代品的团队
+
+## Why This Is Different / 为什么它不是另一种生成工具
+
+### Not a PR Review Bot
+
+| PR Review Bot | agent-guardrails |
+|---------------|------------------|
+| Comments **after** code is written | Defines boundaries **before** code is written |
+| Suggests improvements | Enforces constraints |
+| Reactive | Proactive |
+| “This looks wrong” | “This was never allowed” |
+
+### Not a Static Analyzer
+
+| Static Analyzer | agent-guardrails |
+|-----------------|------------------|
+| Generic rules | Repo-specific contracts |
+| No task context | Task-aware scope checking |
+| Style + bugs | AI-behavior patterns |
+| Run in CI | Run **before** CI |
+
+### Not Another AI Agent
+
+| AI Agent | agent-guardrails |
+|----------|------------------|
+| Writes code | Validates code |
+| “Let me help you” | “Let me check that” |
+| First wow moment | Long-term trust |
+| Use alone | Use **with** your agent |
+
+### The Unique Value
+
+`agent-guardrails` sits **between** your AI coding agent and your production:
+
+```
+[AI Agent] → [agent-guardrails] → [Your Repo]
+                  ↓
+           ✓ Scope check
+           ✓ Test validation
+           ✓ Drift detection
+           ✓ Risk summary
+                  ↓
+           Safe to merge?
+```
+
+**No other tool does this.** CodeRabbit reviews after. Sonar checks style. Your AI agent writes code.
+Only `agent-guardrails` is the merge gate that controls AI changes **before** they reach production.
+
+## Quick Start / 最短路径
+
+Install once:
+
+```bash
+npm install -g agent-guardrails
+```
+
+In your repo, run:
+
+```bash
+agent-guardrails setup --agent <your-agent>
+```
+
+If your agent supports a clearly safe repo-local config path, use:
+
+```bash
+agent-guardrails setup --agent <your-agent> --write-repo-config
+```
+
+Then open your existing agent and start chatting.
+
+For the current most opinionated happy path, start with:
+
+```bash
+agent-guardrails setup --agent claude-code
+```
+
+如果你只知道一个大概方向，也可以直接这样说：
+
+- `先帮我看看这个仓库最小能改哪里，尽量别扩大范围，最后告诉我还有什么风险。`
+- `帮我修这个问题，先读仓库规则，小范围改动，跑完测试后给我 reviewer summary。`
+- `I only have a rough idea. Please read the repo rules, find the smallest safe change, and finish with a reviewer summary.`
+
+Proof in one page:
+
+- [What this catches that normal AI coding workflows miss](./docs/PROOF.md)
+- [Python/FastAPI baseline proof demo](./examples/python-fastapi-demo/README.md)
+
+## Current Language Support / 当前语言支持
+
+**Today / 当前**
+
+- **Deepest support:** JavaScript / TypeScript
+- **Baseline runtime support:** Next.js, Python/FastAPI, monorepos
+- **Still expanding:** deeper Python semantic support and broader framework-aware analysis
+
+**What that means / 这代表什么**
+
+- JavaScript / TypeScript currently has the strongest semantic proof points through the public `plugin-ts` path and the shipped demos
+- Python works today through the same setup, contract, evidence, and review loop, but it does not yet have semantic-depth parity with TypeScript / JavaScript
+- Monorepo support is a repo shape, not a separate language claim
+
+- JavaScript / TypeScript 目前有最强的语义 proof 和 demo 支撑
+- Python 现在已经能走 setup、contract、evidence、review 这一整条 baseline 流程，但还没有达到 TS/JS 的语义深度
+- monorepo 是仓库形态支持，不是一门单独语言
+
+Language expansion is now an active product priority, with Python as the next language to deepen.
+
+语言支持扩展现在已经是正式产品优先项，下一门重点加深的语言是 Python。
+
+If you want the first Python/FastAPI proof path, use the sandbox in [examples/python-fastapi-demo](./examples/python-fastapi-demo). It proves the baseline runtime, deploy-readiness, and post-deploy maintenance surface in a Python repo without claiming semantic-depth parity with TS/JS.
+
+如果你想看第一条 Python/FastAPI proof 路径，可以直接跑 [examples/python-fastapi-demo](./examples/python-fastapi-demo)。这条路径证明的是 Python 仓库里的 baseline runtime、deploy-readiness 和 post-deploy maintenance，而不是宣称它已经达到 TS/JS 的语义深度。
+
+## What This Catches / 这能多抓住什么
+
+- bounded-scope failure versus bounded-scope pass
+- semantic drift catches beyond the basic OSS baseline
+- reviewer summaries that explain changed files, validation, and remaining risk
+
+- bounded-scope 的失败与修复对比
+- 超过基础 OSS baseline 的语义漂移捕捉
+- 能告诉你改了什么、做了哪些验证、还剩什么风险的 reviewer summary
+
+See the full proof in [docs/PROOF.md](./docs/PROOF.md).
+
 ## Why this exists
 
 Coding agents usually fail in predictable ways:
@@ -51,19 +307,13 @@ The product is most valuable when you want three things at once:
 The moat is not prompt wording or a chat wrapper.
 The moat is the combination of repo-local contracts, runtime judgment, semantic checks, review structure, workflow integration, and maintenance continuity that compounds with continued use in the same repo.
 
-## Setup-First Quick Start
+## Setup Details / 更多设置
 
-If you want the intended product entry, install the package and let `setup` prepare the repo plus the MCP snippet you need:
-
-```bash
-npm install -g agent-guardrails
-npx agent-guardrails setup --agent claude-code
-```
-
-If you want the shortest install path, use:
+If you want the default product entry, let `setup` prepare the repo plus the agent config you need:
 
 ```bash
 npm install -g agent-guardrails
+npx agent-guardrails setup --agent <your-agent>
 ```
 
 If your shell does not pick up the global binary right away, skip PATH troubleshooting and run:
@@ -79,53 +329,40 @@ The runtime is tested in CI on Windows, Linux, and macOS, and the README example
 - auto-initializes the repo if `.agent-guardrails/config.json` is missing
 - defaults to the `node-service` preset unless you override it with `--preset`
 - writes safe repo-local helper files such as `CLAUDE.md`, `.cursor/rules/agent-guardrails.mdc`, `.agents/skills/agent-guardrails.md`, or `OPENCLAW.md` when the chosen agent needs them
-- prints the MCP config snippet and tells you exactly where to paste it
+- prints the agent config snippet and tells you exactly where to put it
 - gives you one first chat message and one canonical MCP loop
 
-Example:
+Examples:
 
 ```bash
 npx agent-guardrails setup --agent claude-code
 npx agent-guardrails setup --agent cursor --preset nextjs
 ```
 
-If the agent uses a clearly safe repo-local MCP config file, you can remove even the paste step:
-
-```bash
-npx agent-guardrails setup --agent claude-code --write-repo-config
-npx agent-guardrails setup --agent cursor --write-repo-config
-npx agent-guardrails setup --agent openhands --write-repo-config
-npx agent-guardrails setup --agent openclaw --write-repo-config
-```
-
-Today that safe repo-local write path is intended for:
-
-- `claude-code` via `.mcp.json`
-- `cursor` via `.cursor/mcp.json`
-- `openhands` via `.openhands/mcp.json`
-- `openclaw` via `.openclaw/mcp.json`
+If the agent uses a clearly safe repo-local MCP config file, you can remove even the paste step:
 
-If you want the current most opinionated happy path, use Claude Code first.
-For broader pilot coverage, validate the same setup-first path across:
+```bash
+npx agent-guardrails setup --agent claude-code --write-repo-config
+npx agent-guardrails setup --agent cursor --write-repo-config
+npx agent-guardrails setup --agent openhands --write-repo-config
+npx agent-guardrails setup --agent openclaw --write-repo-config
+```
 
-- `claude-code` as the primary path
-- `cursor` and `codex` as secondary paths
-- `openhands` and `openclaw` as supplementary paths
+Today that safe repo-local write path is intended for:
+
+- `claude-code` via `.mcp.json`
+- `cursor` via `.cursor/mcp.json`
+- `openhands` via `.openhands/mcp.json`
+- `openclaw` via `.openclaw/mcp.json`
+
+Once you connect the generated config to your agent, the happy path should feel like normal chat:
 
-Once you paste the generated snippet into your agent, the happy path should feel like normal chat:
-
-- You: `Add refund status transitions to the order service.`
-- Agent: bootstraps the task contract through `start_agent_native_loop`
-- Agent: makes the change, runs required commands, updates evidence
-- Agent: finishes through `finish_agent_native_loop` and returns a reviewer-friendly summary with scope, risk, and future maintenance guidance
-
-If you do not know how to phrase the task yet, you can still start in plain Chinese or plain English:
-
-- `先帮我看看这个仓库最小能改哪里，尽量别扩大范围，最后告诉我还有什么风险。`
-- `帮我修这个问题，先读仓库规则，小范围改动，跑完测试后给我 reviewer summary。`
-- `I only have a rough idea. Please read the repo rules, find the smallest safe change, and finish with a reviewer summary.`
-
-The first recommended MCP flow is:
+- You: `Add refund status transitions to the order service.`
+- Agent: bootstraps the task contract through `start_agent_native_loop`
+- Agent: makes the change, runs required commands, updates evidence
+- Agent: finishes through `finish_agent_native_loop` and returns a reviewer-friendly summary with scope, risk, and future maintenance guidance
+
+The first recommended MCP flow is:
 
 1. `read_repo_guardrails`
 2. `start_agent_native_loop`
@@ -168,6 +405,13 @@ If you are not sure about file paths, prefer the MCP flow first. The runtime can
 
 ## External Pilot Paths
 
+If you want the current most opinionated happy path, use Claude Code first.
+For broader pilot coverage, validate the same setup-first path across:
+
+- `claude-code` as the primary path
+- `cursor` and `codex` as secondary paths
+- `openhands` and `openclaw` as supplementary paths
+
 Use the same setup-first loop for all five current agent entries:
 
 - `claude-code`
@@ -229,6 +473,7 @@ The flagship examples are:
 - the interface-drift demo in [examples/interface-drift-demo](./examples/interface-drift-demo)
 - the boundary-violation demo in [examples/boundary-violation-demo](./examples/boundary-violation-demo)
 - the source-test-relevance demo in [examples/source-test-relevance-demo](./examples/source-test-relevance-demo)
+- the unified proof page in [docs/PROOF.md](./docs/PROOF.md)
 - the pilot write-up in [docs/REAL_REPO_PILOT.md](./docs/REAL_REPO_PILOT.md)
 
 Together they show:
@@ -240,6 +485,7 @@ Together they show:
 - the semantic layer can block a controller that crosses a declared module boundary even when the task contract still looks narrow
 - the semantic layer can tell the difference between "a test changed" and "the right test changed"
 - the same public CLI can surface deeper enforcement without splitting into a second product
+- the same OSS runtime can produce deploy-readiness and post-deploy maintenance output in a Python/FastAPI repo before any Python semantic pack ships
 
 Run it with:
 
@@ -247,6 +493,12 @@ Run it with:
 node ./examples/bounded-scope-demo/scripts/run-demo.mjs all
 ```
 
+Then run the Python/FastAPI baseline proof demo:
+
+```bash
+npm run demo:python-fastapi
+```
+
 Then run the OSS benchmark suite:
 
 ```bash
@@ -272,90 +524,6 @@ npm run demo:boundary-violation
 npm run demo:source-test-relevance
 ```
 
-## Manual CLI Workflow
-
-Use this docs-first loop in day-to-day work. Copy it, then replace only the task text and file paths:
-
-```bash
-agent-guardrails plan --task "Add audit logging to the release approval endpoint" --required-commands "npm test,npm run lint"
-npm test
-npm run lint
-agent-guardrails check --commands-run "npm test,npm run lint" --review
-```
-
-Add `--intended-files`, `--allowed-change-types`, or narrower `--allow-paths` only when you want a tighter task contract than the preset default.
-
-The intended low-friction flow is:
-
-1. describe the task in plain language with `plan`
-2. make the smallest change that fits the generated contract
-3. run the commands you actually used
-4. finish with the `check` command the runtime recommends
-
-If your repo does not have `origin/main`, use the branch that matches your default branch.
-
-Keep a short evidence note at `.agent-guardrails/evidence/current-task.md` with:
-
-- task name
-- commands run
-- notable results
-- residual risk or `none`
-
-Example:
-
-```md
-# Task Evidence
-
-- Task: Add audit logging to the release approval endpoint
-- Commands run: npm test, npm run lint
-- Notable results: Tests and lint passed after updating the approval endpoint and audit assertions.
-- Residual risk: none
-```
-
-## CI and Automation Workflow
-
-For CI, hooks, or orchestrated agent runs, prefer machine-readable output:
-
-```bash
-agent-guardrails check --base-ref origin/main --json
-```
-
-If the workflow wants parity with locally reported commands, set:
-
-```text
-AGENT_GUARDRAILS_COMMANDS_RUN=npm test,npm run lint
-```
-
-The generated user-repo workflow template lives in [templates/base/workflows/agent-guardrails.yml](./templates/base/workflows/agent-guardrails.yml).
-The maintainer CI for this package lives in [guardrails.yml](./.github/workflows/guardrails.yml).
-
-For agent integrations, the recommended entry is the OSS MCP server:
-
-```bash
-agent-guardrails mcp
-```
-
-The MCP layer exposes the same runtime-backed judgment through these tools:
-
-- `read_repo_guardrails`
-- `suggest_task_contract`
-- `start_agent_native_loop`
-- `finish_agent_native_loop`
-- `run_guardrail_check`
-- `summarize_review_risks`
-
-The loop tools are the recommended OSS agent-native slice:
-
-- `start_agent_native_loop` bootstraps a runtime-backed contract, writes it to the repo, and seeds the evidence note
-- `finish_agent_native_loop` updates evidence, runs `check`, and returns a reviewer-friendly summary from the same judgment path
-
-That reviewer-facing result now also carries continuity guidance from the same OSS runtime:
-
-- reuse targets to extend first
-- new surface files that broaden the maintenance surface
-- continuity breaks that look like parallel abstractions or structure drift
-- future maintenance risks and continuity-specific next actions
-
 ## Production Baseline
 
 The current product direction is a generic, repo-local production baseline for AI-written code:
@@ -364,6 +532,7 @@ The current product direction is a generic, repo-local production baseline for A
 - `check` enforces small-scope, test-aware, evidence-backed, reviewable changes
 - `check --review` turns the same findings into a concise reviewer-oriented report
 - MCP and agent-native loop consumers reuse the same judgment path instead of re-implementing prompts
+- the next production layer is deploy-readiness judgment plus post-deploy maintenance surface, not a separate deployment product
 
 This is intentionally generic-first. It relies on file-shape heuristics, repo policy, task contracts, and command/evidence enforcement rather than framework-specific AST logic.
 
@@ -396,172 +565,26 @@ The next technical step is conversation-first onboarding and stronger runtime-ba
 
 Paid tiers should extend the baseline rather than replace it:
 
-- `Pro Local`: semantic packs, auto task generation, richer local review, and maintenance-aware workflows
-- `Pro Cloud`: hosted review, shared policies, trend dashboards, and centralized governance
+- `Pro Local`: semantic packs, auto task generation, richer local review, maintenance-aware workflows, and lower-touch deployment orchestration
+- `Pro Cloud`: hosted review, shared policies, trend dashboards, deployment governance, and centralized orchestration
 
 Baseline merge-gate features stay open source.
 
-The first semantic pack lives publicly in this repo today as an early semantic milestone. It is positioned as the future `Pro Local` direction, not as a separate closed-source runtime.
+That means the OSS core should keep owning the production-readiness gate:
 
-## Supported Agents
+- trust verdicts
+- recovery / secrets-safe / cost-aware guidance
+- deploy-readiness judgment
+- release and deploy checklist visibility
+- post-deploy maintenance summaries
 
-| Tool | Seeded file | Local workflow support | Automation guidance support |
-| :-- | :-- | :-- | :-- |
-| Codex | `AGENTS.md` | Yes | Yes |
-| Claude Code | `CLAUDE.md` | Yes | Yes |
-| Cursor | `.cursor/rules/agent-guardrails.mdc` | Yes | Yes |
-| OpenHands | `.agents/skills/agent-guardrails.md` | Yes | Yes |
-| OpenClaw | `OPENCLAW.md` | Yes | Yes |
+Deployment orchestration itself remains a later automation layer on top of the same runtime, not a second product that bypasses it.
 
-## CLI Commands
-
-### `init`
-
-Seeds a repo with:
-
-- `AGENTS.md`
-- `docs/PROJECT_STATE.md`
-- `docs/PR_CHECKLIST.md`
-- `.agent-guardrails/config.json`
-- `.agent-guardrails/tasks/TASK_TEMPLATE.md`
-- `.github/workflows/agent-guardrails.yml`
-
-Example:
-
-```bash
-agent-guardrails init . --preset nextjs --adapter openclaw
-```
-
-If you are not sure what to type, start with `setup --agent <name>`, then use the manual flow only when you want to debug or inspect the runtime directly.
-
-### `setup`
-
-Auto-initializes the repo when needed, generates the MCP config snippet for a supported agent, and tells you exactly how to start chatting.
-
-Example:
-
-```bash
-agent-guardrails setup --agent cursor
-agent-guardrails setup --agent claude-code --preset nextjs
-```
-
-The happy path is:
-
-1. run `setup`
-2. paste the snippet into your agent
-3. ask for the task in chat
-4. let the runtime use `read_repo_guardrails`, `start_agent_native_loop`, and `finish_agent_native_loop`
-
-### `plan`
-
-Prints a bounded implementation brief and writes a task contract by default.
-
-Example:
-
-```bash
-agent-guardrails plan --task "Add audit logging to the release approval endpoint" --allow-paths "src/,tests/" --intended-files "src/release/approve.js,tests/release/approve.test.js" --allowed-change-types "implementation-only" --risk-level medium --required-commands "npm test,npm run lint" --evidence ".agent-guardrails/evidence/current-task.md"
-```
-
-### `check`
-
-Runs baseline guardrail checks against the current repo and git working tree.
-
-Example:
-
-```bash
-agent-guardrails check --base-ref origin/main --commands-run "npm test,npm run lint" --review
-```
-
-For JSON output:
-
-```bash
-agent-guardrails check --base-ref origin/main --json
-```
-
-Minimal contract example:
-
-```json
-{
-  "schemaVersion": 3,
-  "task": "Add audit logging to the release approval endpoint",
-  "preset": "node-service",
-  "allowedPaths": ["src/", "tests/"],
-  "intendedFiles": ["src/release/approve.js", "tests/release/approve.test.js"],
-  "allowedChangeTypes": ["implementation-only"],
-  "riskLevel": "medium",
-  "requiredCommands": ["npm test", "npm run lint"],
-  "evidencePaths": [".agent-guardrails/evidence/current-task.md"]
-}
-```
-
-## Presets
-
-- `node-service`
-- `nextjs`
-- `python-fastapi`
-- `monorepo`
-
-Each preset adjusts file heuristics and recommended read-before-write paths while keeping the same mental model.
-
-## Adapters
-
-The core workflow is generic, but `agent-guardrails` ships first-pass adapters for:
-
-- [Codex](./adapters/codex/README.md)
-- [Claude Code](./adapters/claude-code/README.md)
-- [Cursor](./adapters/cursor/README.md)
-- [OpenHands](./adapters/openhands/README.md)
-- [OpenClaw](./adapters/openclaw/README.md)
-
-For Codex, the default `AGENTS.md` workflow is already the main integration surface, so `--adapter codex` is a docs-level adapter rather than an extra seeded file.
-
-## FAQ
-
-### Do I need all adapters?
-
-No. Use only the adapter that matches your coding tool. The core workflow still works without tool-specific seed files.
-
-### Do I need evidence files?
-
-Only when the task contract declares them. In the default docs-first workflow, the evidence note is intentionally lightweight and meant to record what actually happened.
-
-### When should I use `--json`?
-
-Use `--json` for CI, hooks, or automation that needs machine-readable results. For normal local work, the human-readable output is the intended default.
-
-### Does this work on Windows, Linux, and macOS?
-
-Yes. The published CLI is exercised in CI on all three platforms, and the primary install and workflow commands are platform-neutral:
-
-- `npm install -g agent-guardrails`
-- `npx agent-guardrails init . --preset node-service`
-- `npx agent-guardrails plan --task "..."`
-- `npx agent-guardrails check --review`
-
-Platform-specific commands only appear in docs when a shell-specific workaround is required.
-
-### Why not just use another AI to recreate this?
-
-You can copy prompts and a chat wrapper.
-The harder part is copying a repo-aware runtime that keeps state across task bootstrap, validation, review, semantic drift checks, continuity guidance, and workflow integration.
-
-The value of `agent-guardrails` is not "one clever prompt."
-It is the merge-gate system that existing agent chats call while the runtime keeps getting more aligned to the repo over time.
-
-### What if the global `agent-guardrails` command is not found?
-
-Use `npx agent-guardrails ...` first. That works across shells and avoids PATH differences between Windows, macOS, and Linux.
-
-## Current Limits
+The first semantic pack lives publicly in this repo today as an early semantic milestone. It is positioned as the future `Pro Local` direction, not as a separate closed-source runtime.
 
-This project is useful today as a repo-local guardrail layer, but it still has important limits:
+## Deeper Usage
 
-- the heuristics are still intentionally lightweight and may need tuning for larger repos
-- the semantic detectors are still string- and path-driven, not full AST or type-graph analyzers
-- module boundaries still depend on explicit repo policy instead of automatic architecture inference
-- source-to-test relevance is heuristic and should be treated as reviewer guidance plus contract enforcement, not coverage proof
-- CI users still need to choose their canonical base ref, such as `origin/main`
-- the current pilot is documented in [docs/REAL_REPO_PILOT.md](./docs/REAL_REPO_PILOT.md), and broader external pilots are still pending
+For the full manual CLI flow, supported agents, presets, adapters, FAQ, and current limits, see [docs/WORKFLOWS.md](./docs/WORKFLOWS.md).
 
 ## Roadmap
 
@@ -573,6 +596,8 @@ See [docs/PRODUCT_STRATEGY.md](./docs/PRODUCT_STRATEGY.md) for the current seman
 
 ## More Docs
 
+- [Proof](./docs/PROOF.md)
+- [Workflows](./docs/WORKFLOWS.md)
 - [Automation Spec](./docs/AUTOMATION_SPEC.md)
 - [Market Research](./docs/MARKET_RESEARCH.md)
 - [Strategy](./docs/PRODUCT_STRATEGY.md)