carson 1.0.1 → 2.6.0

data/README.md

@@ -1,43 +1,97 @@
-# Carson
+<img src="icon.svg" width="141" alt="Carson">
 
-Enforce the same governance rules across every repository you manage — from a single install, without polluting any of them with governance tooling.
+# ⧓ Carson
+
+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.
-The usual fix is to copy governance scripts into each repository. That works until you need to update them — now you are maintaining dozens of copies, each free to diverge.
+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.
 
-## What Carson Does
+**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           │
+└──────────────────────────────────────────────┘
+```
 
-Carson is a governance runtime that lives on your workstation and in CI, never inside the repositories it governs. You install it once, point it at each repository, and it enforces a consistent baseline — same checks, same rules, same exit codes — everywhere.
+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.
 
-**One command to onboard a repo.**
-`carson init` installs git hooks, synchronises PR and AI-coding templates, and runs a first governance audit. From that point, every commit is checked automatically.
+The data flow:
 
-**Same checks locally and in CI.**
-The `pre-commit` hook runs `carson audit` before every commit. The same `carson audit` runs in your GitHub Actions workflow. If it passes locally, it passes in CI. No surprises.
+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.
 
-**Review accountability.**
-`carson review gate` blocks merge until every actionable reviewer comment — risk keywords, change requests — has been formally acknowledged by the PR author. No more "I missed that comment" after merge.
+## Commands at a Glance
 
-**Template consistency.**
-Carson keeps PR templates and AI coding guidelines identical across all governed repositories. `carson template check` detects drift; `carson template apply` repairs it.
+**Govern** — autonomous portfolio management:
 
-**Centralised lint policy.**
-Lint rules come from a single policy source you control. Carson owns the lint execution path — repo-local config overrides are hard-blocked so teams cannot silently weaken the baseline.
+| 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). |
 
-**Branch hygiene.**
-`carson sync` fast-forwards your local main. `carson prune` removes branches whose upstream is gone, including squash-merged branches verified through the GitHub API.
+**Setup** — run once per machine or per repository:
 
-**Clean boundary.**
-No Carson scripts, config files, or governance payloads are ever placed inside your repositories. Carson actively blocks if it detects its own artefacts in a host repo.
+| 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. |
 
-## When to Use Carson
+**Daily** — regular development workflow:
 
-- A platform team standardising policy across many product repositories — one governance flow for all of them, no per-repo tooling.
-- A consultancy governing client repositories you do not own — enforce rules without committing your tooling into their repos.
-- A regulated engineering team that needs auditable, reproducible gates — every merge decision has a deterministic pass/block result.
-- A solo developer who wants the same lint and review discipline everywhere — without maintaining governance scripts in each project.
+| 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
 
@@ -48,15 +102,21 @@ Prerequisites: Ruby `>= 4.0`, `git`, and `gem` in your PATH.
 # Install
 gem install --user-install carson
 carson version
+```
 
-# Prepare your lint policy baseline
-carson lint setup --source /local/path/of/policy-repo
+**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:
 
-# Onboard a repository
-carson init /local/path/of/repo
+```bash
+carson lint setup --source /path/to/your-policy-repo
 ```
 
-After `carson init`, your repository has:
+**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.
@@ -66,17 +126,30 @@ Commit the generated `.github/*` changes, and the repository is governed.
 **Daily workflow:**
 
 ```bash
-carson sync                 # fast-forward local main
-carson audit                # full governance check (also runs on every commit via hook)
+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`
+
+- **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`

data/RELEASE.md

@@ -5,6 +5,350 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 2.6.0 — Default Squash Merge + Agent Discovery Templates
+
+### What changed
+
+- **Default merge method changed from `merge` to `squash`.** 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 and is individually revertable. This aligns Carson's built-in default with how most teams should run.
+- **Agent discovery via managed templates.** Interactive agents (Claude Code, Codex, Copilot) working in Carson-governed repos now discover Carson automatically. A new source-of-truth file `.github/carson-instructions.md` contains the full governance baseline. Agent-specific files (`.github/CLAUDE.md`, `.github/AGENTS.md`, `.github/copilot-instructions.md`) are one-line pointers to it. Zero drift risk — one file to maintain, all agents follow the same reference.
+- **Managed template set expanded.** `carson template apply` now writes five files: `carson-instructions.md`, `copilot-instructions.md`, `CLAUDE.md`, `AGENTS.md`, and `pull_request_template.md`.
+
+### What users must do now
+
+1. Upgrade Carson to `2.6.0`.
+2. Run `carson prepare` in each governed repository.
+3. Run `carson template apply` to write the new managed files.
+4. Commit the new `.github/*` files.
+5. If you previously set `govern.merge.method` to `"merge"` explicitly in `~/.carson/config.json`, review whether `"squash"` (now the default) is the right choice.
+
+### Breaking or removed behaviour
+
+- `govern.merge.method` default changed from `merge` to `squash`. If your GitHub repository only allows merge commits, set `"govern": { "merge": { "method": "merge" } }` in `~/.carson/config.json`.
+- `.github/copilot-instructions.md` content replaced with a one-line reference. The governance baseline now lives in `.github/carson-instructions.md`.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+carson prepare
+carson template apply
+```
+
+### Engineering Appendix
+
+#### Modified components
+
+- `lib/carson/config.rb` — `govern.merge.method` default changed from `"merge"` to `"squash"`; `template.managed_files` expanded to include `carson-instructions.md`, `CLAUDE.md`, and `AGENTS.md`.
+- `script/ci_smoke.sh` — offboard removal check updated for new managed files.
+- `test/runtime_govern_test.rb` — unit test updated for squash default.
+
+#### New files
+
+- `templates/.github/carson-instructions.md` — governance baseline source of truth.
+- `templates/.github/CLAUDE.md` — one-line reference for Claude Code.
+- `templates/.github/AGENTS.md` — one-line reference for Codex.
+
+#### Changed files
+
+- `templates/.github/copilot-instructions.md` — replaced full content with one-line reference.
+
+#### Public interface and config changes
+
+- `govern.merge.method` default: `"merge"` → `"squash"`.
+- `template.managed_files` default expanded from 2 to 5 files.
+- Exit status contract unchanged.
+
+#### Verification evidence
+
+- CI passes on PRs #77 and #78.
+
+---
+
+## 2.4.0 — Agent Skill Injection + Scope Guard Reform
+
+### What changed
+
+- **SKILL.md injected into agent prompts.** Carson now embeds the full SKILL.md content into every dispatched agent work order. Codex and Claude receive Carson governance knowledge without any files inside the governed repository — the outsider principle holds.
+- **SKILL.md added.** A new agent interface document covering commands, exit codes, output interpretation, config, and common scenarios. Ships with the gem.
+- **Scope integrity guard is advisory only.** The cross-boundary check no longer blocks commits. Commits should be grouped by feature intent, not file type. The scope guard still prints diagnostics but never prevents a commit.
+- **App icon.** Added `icon.svg` (⧓ black bowtie mark) with centered display in README.
+- **Hooks moved to repo root.** `assets/hooks/` → `hooks/`. The `assets/` directory is removed.
+
+### What users must do now
+
+1. Upgrade Carson to `2.4.0`.
+2. Run `carson prepare` in each governed repository.
+
+### Breaking or removed behaviour
+
+- Scope integrity guard no longer hard-blocks commits with multiple core module groups. If you relied on this as a gate, it is now advisory only.
+- `assets/` directory removed. Hook templates now live at `hooks/` in the gem root.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+carson prepare
+carson govern --dry-run
+```
+
+### Engineering Appendix
+
+#### Modified components
+
+- `lib/carson/adapters/prompt.rb` — reads SKILL.md at build time and wraps it in `<carson_skill>` XML tags in the agent prompt.
+- `lib/carson/runtime/audit.rb` — removed `split_required` hard-block escalation; scope guard status capped at `attention`.
+- `lib/carson/runtime/local.rb` — hook template path updated from `assets/hooks` to `hooks`.
+- `lib/carson/config.rb` — scope path updated from `assets/hooks/**` to `hooks/**`.
+- `carson.gemspec` — glob updated, `SKILL.md` and `icon.svg` added to files list.
+- `script/ci_smoke.sh` — scope guard smoke test expects advisory exit instead of block.
+
+#### New files
+
+- `SKILL.md` — agent interface document, shipped with the gem.
+- `icon.svg` — app icon.
+
+#### Public interface and config changes
+
+- No new CLI commands or config keys.
+- Exit status contract unchanged.
+
+#### Verification evidence
+
+- All CI checks pass across PRs #70–#73.
+
+---
+
+## 2.3.0 — Continuous Govern Loop + Brand Badge
+
+### What changed
+
+- Command renames: `init` → `onboard`, `check` → `inspect`, `hook` → `prepare`.
+- Configurable workflow style (`trunk` or `branch`) with hook enforcement.
+- Review gate UX improvements: bot-aware filtering, warmup wait, convergence polling.
+- `carson govern --loop SECONDS` — run the govern cycle continuously with built-in sleep loop. Per-cycle error isolation keeps the daemon alive through transient failures. `Ctrl-C` exits cleanly with a cycle count summary.
+
+### What users must do now
+
+1. Upgrade Carson to `2.3.0`.
+2. Run `carson refresh` in each governed repository to update hooks for the new command names.
+3. Optionally use `carson govern --loop 300` for unattended continuous governance.
+
+### Breaking or removed behaviour
+
+- Commands `init`, `check`, and `hook` have been renamed to `onboard`, `inspect`, and `prepare` respectively.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+carson refresh ~/Dev/your-project
+carson govern --dry-run
+```
+
+### Engineering Appendix
+
+#### Modified components
+
+- `lib/carson/cli.rb` — added `--loop SECONDS` to govern parser, banner, and dispatch.
+- `lib/carson/runtime/govern.rb` — extracted `govern_cycle!`, added `govern_loop!` with per-cycle error isolation and `Interrupt` handling.
+
+#### Public interface and config changes
+
+- Added CLI flag: `--loop SECONDS` for `carson govern`.
+- No new config keys. The loop interval is a runtime argument, not a persistent preference.
+- Exit status contract unchanged.
+
+#### Verification evidence
+
+- All govern unit tests pass including 4 new loop CLI tests.
+
+---
+
+## 2.1.0 — Enriched Agent Work Orders
+
+### What changed
+
+- Agent work orders now include structured evidence instead of just the PR title. Before dispatching a coding agent, Carson gathers CI failure logs or review comment bodies and includes them in the work order so the agent can act on real context.
+- Configurable check wait (`govern.check_wait`, default 30 seconds). When PR checks are still pending and the PR was recently updated, Carson skips it instead of prematurely dispatching a fix — giving GitHub bots and CI time to post results.
+- Shared prompt module extracted from Codex/Claude adapters. Both adapters now use `Adapters::Prompt` with structured XML context tags.
+- Developer documentation updated with an ASCII flow diagram of the autonomous governance loop.
+
+### Evidence gathering detail
+
+- `fix_ci` objectives: Carson fetches the most recent failed CI run via `gh run list --status failure`, then retrieves failure logs via `gh run view --log-failed`. The tail of the log (up to 8,000 chars) is included in the work order.
+- `address_review` objectives: Carson fetches unresolved review threads and actionable top-level findings via GraphQL, and includes each finding's body text (up to 2,000 chars each).
+- Re-dispatch: if a prior dispatch for the same PR failed, the previous attempt summary is included so the agent can avoid repeating the same approach.
+- Graceful degradation: if evidence gathering fails, the agent receives the PR title and is told to investigate locally.
+
+### What users must do now
+
+1. Upgrade Carson to `2.1.0`.
+2. Optionally tune `govern.check_wait` in `~/.carson/config.json` or via `CARSON_GOVERN_CHECK_WAIT`.
+
+### Breaking or removed behaviour
+
+- None. The `context` field on `WorkOrder` is backward compatible — String values are still accepted.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+carson govern --dry-run
+```
+
+### Engineering Appendix
+
+#### New components
+
+- `lib/carson/adapters/prompt.rb` — shared prompt builder module with structured XML context tags.
+
+#### Modified components
+
+- `lib/carson/runtime/govern.rb` — evidence methods (`evidence`, `ci_evidence`, `review_evidence`, `prior_attempt`, `truncate_log`), check wait logic (`within_check_wait?`, `TRIAGE_PENDING`), `updatedAt` added to `gh pr list` fields.
+- `lib/carson/config.rb` — added `govern.check_wait` (integer, seconds, default 30).
+- `lib/carson/adapters/codex.rb`, `lib/carson/adapters/claude.rb` — now include `Prompt` module, removed duplicate `build_prompt`/`sanitize`.
+- `lib/carson/adapters/agent.rb` — updated `context` field documentation for Hash shapes.
+- `docs/develop.md` — added autonomous governance loop section with ASCII diagram.
+
+#### Public interface and config changes
+
+- Added config key: `govern.check_wait` (integer, seconds, default 30).
+- Added env override: `CARSON_GOVERN_CHECK_WAIT`.
+- Exit status contract unchanged.
+
+#### Verification evidence
+
+- 37 govern unit tests pass (18 new, 0 regressions).
+- CI smoke tests pass.
+
+---
+
+## 2.0.0 — Autonomous Governance
+
+### Architectural shift
+
+Carson 2.0.0 is an architectural change. Prior versions were a passive governance tool: Carson checked, reported, and blocked — but you still had to triage PRs, dispatch fixes, click merge, and clean up. Across a portfolio of repositories with coding agents producing many PRs, you were the bottleneck.
+
+Carson is now an autonomous governance runtime. `carson govern` is a portfolio-level triage loop that scans every governed repository, classifies each open PR by CI/review/audit status, and acts: merge what's ready, dispatch a coding agent (Codex or Claude) to fix what's failing, and escalate what needs human judgement. After merging, it housekeeps — syncing main and pruning stale branches.
+
+The per-commit governance (audit, lint, review gate, scope integrity) is unchanged. What's new is the layer above: Carson now orchestrates the full lifecycle from PR to merge to cleanup.
+
+### What changed
+
+- `carson govern [--dry-run] [--json]` — portfolio-level PR triage loop.
+- `carson housekeep` — standalone sync + prune for post-merge cleanup.
+- Agent dispatch adapters for Codex and Claude CLIs, with work-order/result contracts and dispatch state tracking at `~/.carson/govern/dispatch_state.json`.
+- `govern` configuration section: repo list, merge authority/method, agent provider selection.
+- Merge authority is on by default — Carson merges ready PRs autonomously.
+- `.rubocop.yml` removed from repository; lint config now lives at `~/.carson/lint/rubocop.yml` per Carson's own policy.
+
+### What users must do now
+
+1. Upgrade Carson to `2.0.0`.
+2. Run `carson refresh` in each governed repository to update hooks.
+3. Optionally configure `govern.repos` in `~/.carson/config.json` to enable multi-repo portfolio mode.
+4. Run `carson govern --dry-run` to see what Carson would do across your portfolio.
+
+### Breaking or removed behaviour
+
+- `.rubocop.yml` is no longer in the repository. All repos use `~/.carson/lint/rubocop.yml`.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+carson refresh ~/Dev/your-project
+carson govern --dry-run
+```
+
+### Engineering Appendix
+
+#### New components
+
+- `lib/carson/runtime/govern.rb` — portfolio triage loop, PR classification, merge, housekeep orchestration.
+- `lib/carson/adapters/agent.rb` — work-order/result data contracts (`WorkOrder`, `Result`).
+- `lib/carson/adapters/codex.rb` — Codex CLI adapter via `Open3.capture3`.
+- `lib/carson/adapters/claude.rb` — Claude CLI adapter via `Open3.capture3`.
+
+#### Decision tree
+
+For each open PR in each governed repo: CI green? Review gate pass? Audit pass? All yes → merge + housekeep. CI failing → dispatch agent. Review blocked → dispatch agent. Other → escalate.
+
+#### Public interface and config changes
+
+- Added CLI commands: `govern [--dry-run] [--json]`, `housekeep`.
+- Added config section: `govern.repos`, `govern.merge.authority` (default: `true`), `govern.merge.method`, `govern.agent.provider`, `govern.dispatch_state_path`.
+- Added env overrides: `CARSON_GOVERN_REPOS`, `CARSON_GOVERN_MERGE_AUTHORITY`, `CARSON_GOVERN_MERGE_METHOD`, `CARSON_GOVERN_AGENT_PROVIDER`.
+- Exit status contract unchanged: `0` OK, `1` runtime/configuration error, `2` policy blocked.
+
+#### Verification evidence
+
+- 87 unit tests pass (19 new govern tests, 0 regressions).
+- 60 smoke tests pass (6 new govern/housekeep tests).
+
+---
+
+## 1.1.0
+
+### User Overview
+
+#### What changed
+
+- All Carson home-directory paths consolidated under `~/.carson/`:
+  - Lint policy files: `~/AI/CODING/` moved to `~/.carson/lint/`.
+  - Audit reports and cache: `~/.cache/carson/` moved to `~/.carson/cache/`.
+  - Launcher symlink: `~/.local/bin/carson` moved to `~/.carson/bin/carson`.
+
+#### Why users should care
+
+- Carson now uses a single top-level directory (`~/.carson/`) for all state. Uninstalling is `rm -rf ~/.carson` plus `gem uninstall carson`.
+- No more scattered paths across `~/.cache`, `~/.local/bin`, and `~/AI`.
+
+#### What users must do now
+
+1. Upgrade Carson to `1.1.0`.
+2. Update PATH: replace `~/.local/bin` with `~/.carson/bin` in your shell profile.
+3. Rerun `carson lint setup --source <path-or-git-url> --force` to populate `~/.carson/lint/`.
+4. Optionally clean up old paths: `rm -rf ~/.cache/carson ~/AI/CODING ~/.local/bin/carson`.
+
+#### Breaking or removed behaviour
+
+- `~/AI/CODING/` is no longer the default lint policy directory.
+- `~/.cache/carson/` is no longer the default report output directory.
+- `~/.local/bin/carson` is no longer the default launcher symlink location.
+- Users with custom `lint.languages` entries in `~/.carson/config.json` pointing to `~/AI/CODING/` must update those paths.
+
+#### Upgrade steps
+
+```bash
+gem install --user-install carson -v 1.1.0
+mkdir -p ~/.carson/bin
+ln -sf "$(ruby -e 'print Gem.user_dir')/bin/carson" ~/.carson/bin/carson
+export PATH="$HOME/.carson/bin:$PATH"
+$HOME/.carson/bin/carson version
+$HOME/.carson/bin/carson lint setup --source /path/to/your-policy-repo --force
+```
+
+Add the `PATH` export to your shell profile so it persists across sessions.
+
+---
+
 ## 1.0.0 (2026-02-25)
 
 ### User Overview
@@ -184,7 +528,7 @@ carson version
 #### What users must do now
 
 1. Upgrade to `0.6.1` where Carson is pinned.
-2. Re-run `carson hook` in governed repositories after upgrade.
+2. Re-run `carson prepare` in governed repositories after upgrade.
 3. Update CI `carson_version` pins to `0.6.1`.
 
 #### Breaking or removed behaviour
@@ -384,7 +728,7 @@ carson version
 #### What users must do now
 
 1. Use `carson offboard /local/path/of/repo` when removing Carson from a repository.
-2. Re-run `carson init /local/path/of/repo` when re-onboarding later.
+2. Re-run `carson onboard /local/path/of/repo` when re-onboarding later.
 
 #### Breaking or removed behaviour
 
@@ -483,7 +827,7 @@ carson version
 
 #### What changed
 
-- Added one-command initialisation: `carson init [repo_path]` (`hook` + `template apply` + `audit`).
+- Added one-command initialisation: `carson onboard [repo_path]` (`hook` + `template apply` + `audit`).
 - Default report output moved to `~/.cache/carson`.
 - Outsider boundary now hard-blocks Carson-owned host artefacts (`.carson.yml`, `bin/carson`, `.tools/carson/*`).
 - Installation/setup guidance now targets standard-user package-consumer flow.
@@ -497,7 +841,7 @@ carson version
 #### What users must do now
 
 1. Install Carson as a normal user executable (`carson` in `PATH`).
-2. Initialise each repository with `carson init /local/path/of/repo`.
+2. Initialise each repository with `carson onboard /local/path/of/repo`.
 3. Remove forbidden Carson-owned artefacts from host repositories if reported.
 4. Read reports from `~/.cache/carson`.
 
@@ -516,7 +860,7 @@ mkdir -p ~/.local/bin
 ln -sf "$(ruby -e 'print Gem.user_dir')/bin/carson" ~/.local/bin/carson
 carson version
 
-carson init /local/path/of/repo
+carson onboard /local/path/of/repo
 carson audit
 ```
 
@@ -538,7 +882,7 @@ carson audit
 
 #### Public interface and config changes
 
-- Command surface is `audit`, `sync`, `prune`, `hook`, `check`, `init`, `template`, `review`, `version`.
+- Command surface is `audit`, `sync`, `prune`, `prepare`, `inspect`, `onboard`, `template`, `review`, `version`.
 - Initialisation command: `init [repo_path]` (no `run` alias).
 - Default report output: `~/.cache/carson`.
 - Exit status contract unchanged: `0` OK, `1` runtime/configuration error, `2` policy block.