carson 1.0.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f56a11a84e2d19363137153a34302874e8ad0941e4fb330012a1ec92a124eb6a
-  data.tar.gz: 060f8f8c2fbe673321255c32d6b064c674358908b4171a71cf778ab2215cf3aa
+  metadata.gz: cd6dd1f0f0879b5838bc8d808261e44c408b4796ca85dcdd96f6885e397fd109
+  data.tar.gz: 0313e015a232d3eb29b46c16567457ac5403d83f0bcd062f42d4a9efd374d22b
 SHA512:
-  metadata.gz: 39c24b390c66d13428e7bede056a0465481759ec3abf64a380118c954c84705242645d772a3ecd9f52e85a9b61a33f27e345b641a7b8af63757d7fd8383904e4
-  data.tar.gz: 25612172dd0f5649f8fc54af37cba2a43727d3848caac284805ee0e3c7ba6b40da4ce9fedab8fd7cd780e05ff370862e2b03d0d259572f741b064df442af952d
+  metadata.gz: 7932b95b9798bd6935e5fc1f4f21962e31ebc473863e802f3870691e1613e00eaef5daa035239f6041d45750a6fb3fd85d29a8b72aa95285edcfbf9922992707
+  data.tar.gz: 5ed203aa2b53d844cd71b2496c45de3abed272ce765d590e7695314e29c8b2affbe79cd59ee86286adaa1118696438448b0079da97107e30dd5d5d21fb0b83c2

data/.github/copilot-instructions.md

@@ -1,12 +1 @@
-## Shared Governance Baseline
-
-- GitHub rulesets and required checks are merge authority.
-- Carson runs as an outsider runtime for hook health, main sync, scope integrity, and gh visibility.
-- Before commit and before push, run `carson audit`.
-- At session start and again immediately before merge recommendation, run `gh pr list --state open --limit 50` and re-confirm active PR priorities.
-- Before merge recommendation, run `carson review gate`; it enforces warm-up wait, unresolved-thread convergence, and `Disposition:` dispositions for actionable top-level findings.
-- Actionable findings are unresolved review threads, any non-author `CHANGES_REQUESTED` review, or non-author comments/reviews with risk keywords (`bug`, `security`, `incorrect`, `block`, `fail`, `regression`).
-- `Disposition:` dispositions must include one token (`accepted`, `rejected`, `deferred`) and the target review URL.
-- Scheduled governance runs `carson review sweep` every 8 hours to track late actionable review activity on recent open/closed PRs.
-- Do not treat green checks or `mergeStateStatus: CLEAN` as sufficient if unresolved review threads remain.
-- Never suggest destructive operations on protected refs (`main`/`master`, local or remote).
+Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.

data/.github/workflows/carson_policy.yml

@@ -79,7 +79,7 @@ jobs:
           CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
         run: |
           carson lint setup --source https://github.com/wanghailei/ai.git --ref main --force
-          carson hook
+          carson prepare
           carson audit
 
       - name: Carson review gate

data/API.md

@@ -1,6 +1,7 @@
 # Carson API
 
 This document defines Carson's user-facing interface contract for CLI commands, configuration inputs, and exit behaviour.
+For operational usage and daily workflows, see `MANUAL.md`.
 
 ## Command interface
 
@@ -10,25 +11,53 @@ Command form:
 carson <command> [subcommand] [arguments]
 ```
 
-Supported commands:
+### Setup commands
+
+| Command | Purpose |
+|---|---|
+| `carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]` | Seed or refresh `~/.carson/lint` policy files from an explicit source. |
+| `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. |
+| `carson prepare` | Install or refresh Carson-managed global hooks. |
+| `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. |
+| `carson offboard [repo_path]` | Remove Carson-managed host artefacts and detach Carson hooks path where applicable. |
+
+### Daily commands
 
 | Command | Purpose |
 |---|---|
-| `carson version` | Print installed Carson version. |
-| `carson init [repo_path]` | Apply one-command baseline setup for a target git repository. |
-| `carson sync` | Fast-forward local `main` from configured remote when tree is clean. |
 | `carson audit` | Evaluate governance status and generate report output. |
-| `carson hook` | Install or refresh Carson-managed global hooks. |
-| `carson check` | Run governance checks against current repository state. |
+| `carson sync` | Fast-forward local `main` from configured remote when tree is clean. |
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
-| `carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]` | Seed or refresh `~/AI/CODING` policy files from an explicit source. |
+
+### Govern commands
+
+| Command | Purpose |
+|---|---|
+| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level PR triage: classify, merge, dispatch agents, escalate. |
+| `carson housekeep` | Sync main + prune stale branches (also runs automatically after govern merges). |
+
+`--loop SECONDS` runs the govern cycle continuously, sleeping SECONDS between cycles. The loop isolates errors per cycle — a single failing cycle does not stop the daemon. `Ctrl-C` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
+
+`govern.merge.method` accepts `squash`, `merge`, or `rebase` (default: `squash`). Squash keeps main linear — one PR, one commit. When the target repository enforces linear history via branch protection, only `rebase` is accepted by GitHub — set `govern.merge.method` to `rebase` to match.
+
+### Review commands
+
+| Command | Purpose |
+|---|---|
 | `carson review gate` | Block until actionable review findings are resolved or convergence timeout is reached. |
 | `carson review sweep` | Scan recent PR activity and update a rolling tracking issue for late actionable feedback. |
-| `carson offboard [repo_path]` | Remove Carson-managed host artefacts and detach Carson hooks path where applicable. |
+
+### Info commands
+
+| Command | Purpose |
+|---|---|
+| `carson version` | Print installed Carson version. |
+| `carson inspect` | Verify Carson-managed hook installation and repository setup. |
 
 ## Exit status contract
+
 - `0`: success
 - `1`: runtime/configuration/command error
 - `2`: policy blocked (hard stop)
@@ -36,15 +65,21 @@ Supported commands:
 Automation and CI integrations should treat exit `2` as an expected policy failure signal.
 
 ## Repository boundary contract
+
 Blocked Carson artefacts in host repositories:
 - `.carson.yml`
 - `bin/carson`
 - `.tools/carson/*`
 
 Allowed Carson-managed persistence in host repositories:
-- selected GitHub-native files under `.github/*`
+- `.github/carson-instructions.md` — governance baseline (source of truth)
+- `.github/copilot-instructions.md` — agent discovery pointer for Copilot
+- `.github/CLAUDE.md` — agent discovery pointer for Claude Code
+- `.github/AGENTS.md` — agent discovery pointer for Codex
+- `.github/pull_request_template.md` — PR template
 
 ## Configuration interface
+
 Default global configuration path:
 - `~/.carson/config.json`
 
@@ -71,7 +106,7 @@ Environment overrides:
         "enabled": true,
         "globs": ["**/*.rb"],
         "command": ["ruby", "/absolute/path/to/carson/lib/carson/policy/ruby/lint.rb", "{files}"],
-        "config_files": ["~/AI/CODING/rubocop.yml"]
+        "config_files": ["~/.carson/lint/rubocop.yml"]
       }
     }
   }
@@ -84,7 +119,7 @@ Environment overrides:
 - `command`: argv array executed without shell interpolation.
 - `config_files`: required files that must exist before lint runs.
 - `{files}` token: replaced with matched files; if omitted, matched files are appended at the end of argv.
-- Default Ruby policy source is `~/AI/CODING/rubocop.yml`; Ruby execution logic is Carson-owned.
+- Default Ruby policy source is `~/.carson/lint/rubocop.yml`; Ruby execution logic is Carson-owned.
 - Client repositories containing repo-local `.rubocop.yml` are hard-blocked by `carson audit` in outsider mode.
 - Non-Ruby language entries (`javascript`, `css`, `html`, `erb`) are present but disabled by default.
 
@@ -101,14 +136,16 @@ Ruby source requirement for `carson lint setup` (when Ruby lint is enabled):
 - `CODING/rubocop.yml` must exist in the source tree.
 
 Policy layout requirement:
-- Language policy files are stored directly under `CODING/` and copied to `~/AI/CODING/` without language subdirectories.
+- Language policy files are stored directly under `CODING/` and copied to `~/.carson/lint/` without language subdirectories.
 
 ## Output interface
+
 Report output directory precedence:
-- `~/.cache/carson`
+- `~/.carson/cache`
 - `TMPDIR/carson` (used when `HOME` is invalid and `TMPDIR` is absolute)
 - `/tmp/carson` (fallback)
 
 ## Versioning and compatibility
+
 - Pin Carson in automation by explicit release and version pair (`carson_ref`, `carson_version`).
 - Review upgrade actions in `RELEASE.md` before moving to a newer minor or major version.

data/MANUAL.md

@@ -1,19 +1,14 @@
 # Carson Manual
 
-This manual is for users who need to install Carson, configure repository governance, and run a stable daily operating cadence.
-
-## Prerequisites
-- Ruby `>= 4.0`
-- `gem` in `PATH`
-- `git` in `PATH`
-- `gh` in `PATH` (recommended for full review governance features)
+This manual covers installation, first-time setup, CI configuration, and daily operations.
+For the mental model and command overview, see `README.md`. For formal interface definitions, see `API.md`.
 
 ## Install Carson
 
-Recommended installation path:
+Prerequisites: Ruby `>= 4.0`, `gem` and `git` in `PATH`. `gh` (GitHub CLI) recommended for full review governance.
 
 ```bash
-gem install --user-install carson -v 1.0.0
+gem install --user-install carson
 ```
 
 If `carson` is not found after installation:
@@ -22,53 +17,53 @@ If `carson` is not found after installation:
 export PATH="$(ruby -e 'print Gem.user_dir')/bin:$PATH"
 ```
 
-Verify installation:
+Verify:
 
 ```bash
 carson version
 ```
 
-Expected result:
-- Carson version is printed.
-- The `carson` command is available in your shell.
+## First-Time Setup
+
+### Step 1: Prepare your lint policy
 
-## Configure your first repository
-Assume your repository path is `/local/path/of/repo`.
+Carson enforces lint rules from a central policy source — a directory or git repository you control that contains a `CODING/` folder. For Ruby governance, the required file is `CODING/rubocop.yml`.
 
-Prepare your global lint policy baseline first:
+Run `lint setup` to copy policy files into `~/.carson/lint/`:
 
 ```bash
-carson lint setup --source /path/to/ai-policy-repo
+carson lint setup --source /path/to/your-policy-repo
 ```
 
-`lint setup` expects the source to contain `CODING/` and writes policy files to `~/AI/CODING/`.
-For Ruby, the required policy file is `CODING/rubocop.yml`.
-Language policy files are expected directly under `CODING/` (flat layout, no language subfolders).
-Use `--ref <git-ref>` when `--source` is a git URL.
-Use `--force` to overwrite existing `~/AI/CODING` files.
+After this command, `~/.carson/lint/rubocop.yml` exists and is ready for Carson to use. Every governed repository will reference these same policy files — this is how Carson keeps lint consistent.
+
+Options:
+- `--source <path-or-git-url>` — where to read policy files from (required).
+- `--ref <git-ref>` — branch or tag when `--source` is a git URL.
+- `--force` — overwrite existing `~/.carson/lint` files.
 
-Audit policy notes:
-- Ruby lint policy data lives only in `~/AI/CODING/rubocop.yml`; execution logic is Carson-owned.
-- Client repositories must not contain repo-local `.rubocop.yml`; `carson audit` blocks when it exists.
-- Non-Ruby language entries remain configured but disabled by default.
+Policy layout: language config files sit directly under `CODING/` (flat layout, no language subfolders). Non-Ruby entries are present but disabled by default.
 
-Run baseline initialisation:
+### Step 2: Onboard a repository
 
 ```bash
-carson init /local/path/of/repo
+carson onboard /path/to/your-repo
 ```
 
-`init` performs:
-- remote alignment using configured `git.remote` (default `github`)
-- hook installation under `~/.carson/hooks/<version>/`
-- repository `core.hooksPath` alignment to Carson global hooks
-- commit-time governance gate via managed `pre-commit` hook
-- managed `.github/*` template synchronisation
-- initial governance audit
+`onboard` performs:
+- Remote alignment using configured `git.remote` (default `github`).
+- Hook installation under `~/.carson/hooks/<version>/`.
+- Repository `core.hooksPath` alignment to Carson global hooks.
+- Commit-time governance gate via managed `pre-commit` hook.
+- Managed `.github/*` template synchronisation.
+- Initial governance audit.
+
+### Step 3: Commit generated files
+
+After `onboard`, commit the generated `.github/*` changes in your repository. From this point the repository is governed.
 
-After `init`, commit generated `.github/*` changes in your repository.
+## CI Setup
 
-## Pin Carson in CI
 Use the reusable workflow with explicit release pins:
 
 ```yaml
@@ -79,7 +74,7 @@ on:
 
 jobs:
   governance:
-    uses: wanghailei/carson/.github/workflows/carson_policy.yml.8.1
+    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v1.0.0
     secrets:
       CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
     with:
@@ -88,20 +83,22 @@ jobs:
       rubocop_version: "1.81.0"
 ```
 
-When upgrading Carson, update both `carson_ref` and `carson_version` together.
-`CARSON_READ_TOKEN` must have read access to `wanghailei/ai` so CI can run `carson lint setup`.
-The reusable workflow installs a pinned RuboCop gem before `carson audit`; mirror the same pin in host governance workflows (including BOS) for deterministic checks.
+Notes:
+- When upgrading Carson, update both `carson_ref` and `carson_version` together.
+- `CARSON_READ_TOKEN` must have read access to your policy source repository so CI can run `carson lint setup`.
+- The reusable workflow installs a pinned RuboCop gem before `carson audit`; mirror the same pin in host governance workflows for deterministic checks.
 
-## Daily operations
-Start of work:
+## Daily Operations
+
+**Start of work:**
 
 ```bash
-carson sync
-carson lint setup --source /path/to/ai-policy-repo
-carson audit
+carson sync                                          # fast-forward local main
+carson lint setup --source /path/to/your-policy-repo # refresh policy if needed
+carson audit                                         # full governance check
 ```
 
-Before push or PR update:
+**Before push or PR update:**
 
 ```bash
 carson audit
@@ -114,57 +111,135 @@ If template drift is detected:
 carson template apply
 ```
 
-Before merge recommendation:
+**Before merge:**
 
 ```bash
-gh pr list --state open --limit 50
 carson review gate
 ```
 
-Scheduled late-review monitoring:
+**Periodic maintenance:**
 
 ```bash
-carson review sweep
+carson review sweep    # update tracking issue for late review feedback
+carson prune           # remove stale local branches
 ```
 
-Local branch clean-up:
+## Running Carson Govern Continuously
+
+Use `--loop SECONDS` to run `carson govern` as a persistent daemon that cycles on a schedule:
 
 ```bash
-carson prune
+carson govern --loop 300              # cycle every 5 minutes
+carson govern --loop 300 --dry-run    # observe mode, no merges or dispatches
+```
+
+The loop is built-in and cross-platform — no cron, launchd, or Task Scheduler required. Run it in a terminal, tmux, screen, or as a system service.
+
+Each cycle runs independently: if one cycle fails (network error, GitHub API timeout), the error is logged and the next cycle proceeds normally. Press `Ctrl-C` to stop — Carson exits cleanly with a cycle count summary.
+
+## Merge Method and Linear History
+
+Carson's `govern.merge.method` controls how `carson govern` merges ready PRs. The options are `squash`, `merge`, and `rebase` (default: `squash`). Set this in `~/.carson/config.json`:
+
+```json
+{
+  "govern": {
+    "merge": {
+      "method": "squash"
+    }
+  }
+}
 ```
 
-## Exit contract
-- `0`: success
-- `1`: runtime or configuration error
-- `2`: policy blocked (hard stop)
+**Why squash is the default.** Squash-to-main keeps history linear: one PR = one commit on main. Every commit on main corresponds to a reviewed, CI-passing unit of work. The benefits:
+
+- `git log --oneline` on main tells the full story without merge noise or work-in-progress commits.
+- Every commit is individually revertable — `git revert <sha>` undoes exactly one PR.
+- `git bisect` operates on meaningful boundaries, not intermediate fixup commits.
+- Individual branch commits are still preserved in the PR on GitHub for full traceability.
+
+**When to use other methods:**
+
+- `rebase` — if you want to preserve individual commits from the branch on main. Requires "Require linear history" in GitHub branch protection. GitHub rejects merge commits and squash merges when this is enabled.
+- `merge` — if you want explicit merge commits. This creates a non-linear graph but preserves branch topology.
+
+**Important:** Carson's merge method must match your GitHub repository's allowed merge types. If your repo only allows squash merges and Carson is set to `merge`, govern will fail when it tries to auto-merge. Check your repository settings under Settings > General > Pull Requests.
 
-Treat exit `2` as a mandatory stop until the policy violation is resolved.
+## Agent Discovery
+
+Carson writes managed files that help interactive agents (Claude Code, Codex, Copilot) discover the governance system when they work in a governed repository.
+
+**How it works:**
+
+- `.github/carson-instructions.md` — the single source of truth containing the full governance baseline. This file tells agents what Carson is, what commands to run, and what rules to follow.
+- `.github/CLAUDE.md` — read by Claude Code at session start. Points to `carson-instructions.md`.
+- `.github/AGENTS.md` — read by Codex at session start. Points to `carson-instructions.md`.
+- `.github/copilot-instructions.md` — read by GitHub Copilot. Points to `carson-instructions.md`.
+
+Each agent reads its own expected filename and follows the reference to the shared baseline. One file to maintain, zero drift across agents.
+
+All four files are managed templates — `carson template check` detects drift, `carson template apply` writes them, and `carson offboard` removes them.
+
+**Why this matters:** without discovery, agents working in governed repos hit Carson's hooks blindly and don't understand the governance contract. With discovery, agents know to run `carson audit` before committing, `carson review gate` before recommending a merge, and to respect protected refs.
+
+## Configuration
+
+Default global config path: `~/.carson/config.json`.
+
+Precedence (highest wins): environment variables > config file > built-in defaults.
+
+Override the config file path with `CARSON_CONFIG_FILE=/absolute/path/to/config.json`.
+
+Common environment overrides:
+
+| Variable | Purpose |
+|---|---|
+| `CARSON_HOOKS_BASE_PATH` | Custom hooks installation directory. |
+| `CARSON_REVIEW_WAIT_SECONDS` | Initial wait before first review poll. |
+| `CARSON_REVIEW_POLL_SECONDS` | Interval between review polls. |
+| `CARSON_REVIEW_MAX_POLLS` | Maximum review poll attempts. |
+| `CARSON_REVIEW_DISPOSITION_PREFIX` | Required prefix for disposition comments. |
+| `CARSON_REVIEW_SWEEP_WINDOW_DAYS` | Lookback window for review sweep. |
+| `CARSON_REVIEW_SWEEP_STATES` | PR states to include in sweep. |
+| `CARSON_RUBY_INDENTATION` | Ruby indentation policy (`tabs`, `spaces`, or `either`). |
+
+For the full configuration schema and `lint.languages` definition, see `API.md`.
 
 ## Troubleshooting
-`carson: command not found`
+
+**`carson: command not found`**
 - Confirm Ruby and gem installation.
 - Confirm `$(ruby -e 'print Gem.user_dir')/bin` is in `PATH`.
 
-`review gate` fails on actionable comments
+**`review gate` fails on actionable comments**
 - Respond with a valid disposition comment using the required prefix.
 - Re-run `carson review gate`.
 
-Template drift blocks
+**Template drift blocks**
 
 ```bash
 carson template apply
 carson template check
 ```
 
-## Offboard from a repository
+**Audit blocks on repo-local `.rubocop.yml`**
+- Carson hard-blocks governed repositories that contain their own `.rubocop.yml`. Remove the repo-local file and rely on the central policy in `~/.carson/lint/rubocop.yml`.
+
+**Hook version mismatch after upgrade**
+- Run `carson refresh` to re-apply hooks and templates for the new Carson version.
+
+## Offboard a Repository
+
 To retire Carson from a repository:
 
 ```bash
-carson offboard /local/path/of/repo
+carson offboard /path/to/your-repo
 ```
 
 This removes Carson-managed host artefacts and unsets `core.hooksPath` when it points to Carson-managed global hooks.
 
-## Related documents
-- Interface reference: `API.md`
+## Related Documents
+
+- Mental model and command overview: `README.md`
+- Formal interface contract: `API.md`
 - Release notes: `RELEASE.md`

data/README.md

@@ -1,48 +1,155 @@
-# Carson
+<img src="icon.svg" width="141" alt="Carson">
 
-Carson is an outsider governance runtime for teams that need predictable GitHub policy controls without placing Carson-owned tooling inside client repositories.
+# ⧓ Carson
 
-## Introduction
-Repository governance often drifts over time: local protections weaken, review actions are missed, and policy checks become inconsistent between contributors.
-Carson solves this by running from your workstation or CI, applying a deterministic governance baseline, and managing only selected GitHub-native policy files where necessary.
-This model is effective because ownership stays explicit: Carson runtime assets remain outside host repositories, while merge authority remains with GitHub branch protection and human review.
+Named after the head of household in Downton Abbey, Carson is your repositories' autonomous governance runtime — you write the code, Carson manages everything else. From commit-time checks through PR triage, agent dispatch, merge, and cleanup, Carson runs the household with discipline and professional standards. Carson itself has no intelligence — it follows a deterministic decision tree. The intelligence comes from the coding agents it dispatches (Codex, Claude) to fix problems.
+
+## The Problem
+
+If you govern more than a handful of repositories, you know the pattern: lint configs drift between repos, PR templates go stale, reviewer feedback gets quietly ignored, and what passes on a developer's laptop fails in CI. Across a portfolio of projects with coding agents producing many PRs, you become the bottleneck — manually checking results, dispatching fixes, clicking merge, and cleaning up.
+
+## How Carson Works
+
+Carson is an autonomous governance runtime that lives on your workstation and in CI, never inside the repositories it governs. It operates at two levels:
+
+**Per-commit governance** — Carson enforces lint policy, gates merges on unresolved review comments, synchronises templates, and keeps your local branches clean. Every commit triggers `carson audit` through managed hooks; the same checks run in GitHub Actions.
+
+**Portfolio-level autonomy** — `carson govern` is a scheduled triage loop that scans all your repositories, classifies every open PR, and acts: merge what's ready, dispatch coding agents (Codex or Claude) to fix what's failing, and escalate what needs human judgement. One command, all your projects, unmanned.
+
+```
+┌──────────────────────────────────────────────�┐
+│  Your workstation                             │
+│                                               │
+│  ~/.carson/            Carson config          │
+│  ~/.carson/hooks/      Git hooks              │
+│  ~/.carson/lint/       Lint policy            │
+│  ~/.carson/cache/      Reports                │
+│  ~/.carson/govern/     Dispatch state         │
+│                                               │
+│  carson govern ──► for each repo:             │
+│    1. List open PRs (gh)                      │
+│    2. Classify: CI / review / audit status    │
+│    3. Act: merge | dispatch agent | escalate  │
+│    4. Housekeep: sync + prune                 │
+│                                               │
+│  Governed repos:  repo-A/  repo-B/  repo-C/   │
+│    .github/* templates (committed)            │
+│    core.hooksPath → ~/.carson/hooks           │
+└──────────────────────────────────────────────┘
+```
+
+This separation is Carson's defining trait — the **outsider boundary**: no Carson scripts, config files, or governance payloads are ever placed inside a governed repository.
+
+The data flow:
+
+1. You maintain a **policy source** — a directory or git repository containing your lint rules (e.g. `CODING/rubocop.yml`). Carson copies these to `~/.carson/lint/` via `carson lint setup`.
+2. `carson init` installs git hooks, synchronises `.github/*` templates, and runs a first governance audit on a host repository.
+3. From that point, every commit triggers `carson audit` through the managed `pre-commit` hook. The same `carson audit` runs in GitHub Actions. If it passes locally, it passes in CI.
+4. `carson review gate` enforces review accountability: it blocks merge until every actionable reviewer comment has been formally acknowledged by the PR author through a **disposition comment**.
+5. `carson govern` triages all open PRs across your portfolio. Ready PRs are merged and housekept. Failing PRs get a coding agent dispatched to fix them. Stuck PRs are escalated for your attention.
+
+## Commands at a Glance
+
+**Govern** — autonomous portfolio management:
+
+| Command | What it does |
+|---|---|
+| `carson govern` | Triage all open PRs: merge ready ones, dispatch agents for failures, escalate the rest. |
+| `carson govern --dry-run` | Show what Carson would do without taking action. |
+| `carson govern --loop SECONDS` | Run the govern cycle continuously, sleeping SECONDS between cycles. |
+| `carson housekeep` | Sync main + prune stale branches (also runs automatically after govern merges). |
+
+**Setup** — run once per machine or per repository:
+
+| Command | What it does |
+|---|---|
+| `carson lint setup` | Seed `~/.carson/lint/` from your policy source. |
+| `carson onboard` | One-command baseline: hooks + templates + first audit. |
+| `carson prepare` | Install or refresh Carson-managed global hooks. |
+| `carson refresh` | Re-apply hooks, templates, and audit after upgrading Carson. |
+| `carson offboard` | Remove Carson from a repository. |
+
+**Daily** — regular development workflow:
+
+| Command | What it does |
+|---|---|
+| `carson audit` | Full governance check (also runs automatically on every commit). |
+| `carson sync` | Fast-forward local `main` from remote. |
+| `carson prune` | Remove stale local branches whose upstream is gone. |
+| `carson template check` | Detect drift between managed and host `.github/*` files. |
+| `carson template apply` | Repair drifted `.github/*` files. |
+
+**Review** — PR merge readiness:
+
+| Command | What it does |
+|---|---|
+| `carson review gate` | Block or approve merge based on unresolved review comments. |
+| `carson review sweep` | Scan recent PRs and update a tracking issue for late feedback. |
+
+**Info**:
+
+| Command | What it does |
+|---|---|
+| `carson version` | Print installed version. |
+| `carson inspect` | Verify Carson-managed hook installation and repository setup. |
 
 ## Quickstart
-Prerequisites:
-- Ruby `>= 4.0`
-- `gem` and `git` available in `PATH`
-- `gh` available in `PATH` for PR/check reporting (recommended, not required for core local commands)
+
+Prerequisites: Ruby `>= 4.0`, `git`, and `gem` in your PATH.
+`gh` (GitHub CLI) is recommended for full review governance features.
 
 ```bash
-gem install --user-install carson -v 1.0.0
+# Install
+gem install --user-install carson
 carson version
-carson lint setup --source /path/to/ai-policy-repo
-carson init /local/path/of/repo
 ```
 
-Expected result:
-- `carson version` prints `1.0.0` (or newer).
-- `carson lint setup` seeds `~/AI/CODING` from your explicit source.
-- Ruby lint policy data is sourced from `~/AI/CODING/rubocop.yml`; Ruby lint execution stays Carson-owned.
-- Policy files live directly under `~/AI/CODING/` (no per-language subdirectories).
-- `carson init` aligns remote naming, installs Carson-managed hooks, synchronises managed `.github/*` files, and runs an initial audit.
-- Your repository is ready for daily governance commands.
+**Prepare your lint policy.** A policy source is any directory (or git URL) that contains a `CODING/` folder with your lint configuration files. For Ruby, the required file is `CODING/rubocop.yml`. Carson copies these into `~/.carson/lint/` so that every governed repository uses the same rules:
+
+```bash
+carson lint setup --source /path/to/your-policy-repo
+```
+
+**Onboard a repository:**
+
+```bash
+carson onboard /path/to/your-repo
+```
+
+After `carson onboard`, your repository has:
+- Git hooks that run `carson audit` on every commit.
+- Managed `.github/*` templates synchronised from Carson.
+- An initial governance audit report.
+
+Commit the generated `.github/*` changes, and the repository is governed.
+
+**Daily workflow:**
+
+```bash
+carson govern --dry-run     # see what Carson would do across all repos
+carson govern               # triage PRs, merge ready ones, dispatch agents, housekeep
+carson govern --loop 300    # run continuously, cycling every 5 minutes
+```
+
+Or the individual commands if you prefer manual control:
+
+```bash
+carson audit                # full governance check
+carson review gate          # block or approve merge based on review status
+carson sync                 # fast-forward local main
+carson prune                # clean up stale local branches
+```
 
 ## Where to Read Next
-- User manual: `MANUAL.md`
-- API reference: `API.md`
-- Release notes: `RELEASE.md`
-
-## Core Capabilities
-- Outsider boundary enforcement that blocks Carson-owned host artefacts (`.carson.yml`, `bin/carson`, `.tools/carson/*`).
-- Deterministic governance checks with stable exit codes for local and CI automation.
-- Ruby lint governance from `~/AI/CODING/rubocop.yml` with Carson-owned execution and deterministic local/CI blocking.
-- Hard policy block when a client repository contains repo-local `.rubocop.yml`.
-- Non-Ruby lint language entries remain present but disabled by default in this phase.
-- Managed `.github/*` template synchronisation with drift detection and repair.
-- Review governance controls (`review gate`, `review sweep`) for actionable feedback handling.
-- Local branch hygiene and fast-forward sync workflow (`sync`, `prune`).
+
+- **MANUAL.md** — installation, first-time setup, CI configuration, daily operations, troubleshooting.
+- **API.md** — formal interface contract: commands, exit codes, configuration schema.
+- **RELEASE.md** — version history and upgrade actions.
+- **docs/define.md** — product definition and scope.
+- **docs/design.md** — experience and brand design.
+- **docs/develop.md** — contributor guide: architecture, development workflow.
 
 ## Support
+
 - Open or track issues: <https://github.com/wanghailei/carson/issues>
 - Review version-specific upgrade actions: `RELEASE.md`