Contentrain · ABB65 · Apr 18, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/.changeset/phase-r1-rules-skills-mcp-parity.md b/.changeset/phase-r1-rules-skills-mcp-parity.md
@@ -0,0 +1,86 @@
+---
+"@contentrain/mcp": minor
+"@contentrain/rules": minor
+"@contentrain/skills": minor
+---
+
+fix(rules,skills,mcp): align rules/skills catalogs with MCP tool surface + `cr/*` branches, lock with parity tests
+
+Closes the two P1 drift findings and installs a drift-detection
+mechanism so they don't come back:
+
+1. **Missing `contentrain_merge`** — `@contentrain/rules` public
+   `MCP_TOOLS` listed 15 tools. `@contentrain/mcp` registers 17
+   (including `merge` and the new `doctor`). `@contentrain/skills`
+   tool reference also jumped from `submit` straight to `bulk`.
+2. **Legacy `contentrain/{operation}/...` branch namespace** —
+   MCP's `buildBranchName()` returns `cr/...` (Phase 7 migration)
+   and `checkBranchHealth` filters on `cr/`, but essential rules,
+   review/normalize prompts, and multiple skills still taught the
+   old prefix. Agents following the shipped guidance would look
+   for branches that don't exist.
+
+### `@contentrain/mcp`
+
+- New public export `TOOL_NAMES: readonly string[]` in
+  `./tools/annotations`, frozen and derived from `TOOL_ANNOTATIONS`.
+  Single source of truth — parity tests in sibling packages now
+  import this instead of hardcoding.
+- New `./tools/annotations` subpath export in `package.json`.
+- Build script now emits the new subpath.
+
+### `@contentrain/rules`
+
+- `MCP_TOOLS` extended to **17 tools** (`contentrain_merge`,
+  `contentrain_doctor` added in catalog order).
+- `essential/contentrain-essentials.md` — tool table gains `doctor`
+  row; feature-branch pattern rewritten to `cr/{operation}/...`;
+  health-threshold language mentions `cr/*`.
+- `prompts/review-mode.md` — every legacy `contentrain/<op>/...`
+  reference → `cr/<op>/...` (pattern + type examples).
+- `prompts/normalize-mode.md` — branch pattern table rewritten.
+- `shared/workflow-rules.md` — branch pattern spec rewritten.
+- `tests/mcp-parity.test.ts` (new) — 4 tests:
+  - `MCP_TOOLS` ↔ `TOOL_NAMES` exact match
+  - Essential guardrails mention every MCP tool
+  - `buildBranchName()` output starts with `cr/` (sampled across scopes)
+  - Rules docs do not contain the legacy `contentrain/<op>/...`
+    branch prefix (false-positive filter excludes `.contentrain/` paths)
+- `package.json` — `@contentrain/mcp: workspace:*` added as devDep
+  for the parity test.
+
+### `@contentrain/skills`
+
+- `skills/contentrain/references/mcp-tools.md` — new sections for
+  `contentrain_merge` (after submit) and `contentrain_doctor`
+  (new Doctor Tools subsection). Submit description updated to
+  `cr/*` branches.
+- `skills/contentrain/references/mcp-pipelines.md` + `workflow.md`
+  — branch-naming spec + examples rewritten to `cr/*`.
+- `skills/contentrain-normalize/SKILL.md` + `references/extraction.md`
+  + `references/reuse.md` — 4 stale `contentrain/normalize/*`
+  references → `cr/normalize/*`.
+- `skills/contentrain-translate/SKILL.md` — translate branch pattern
+  updated.
+- `tests/mcp-parity.test.ts` (new) — 2 tests:
+  - `references/mcp-tools.md` has an `### <tool>` heading for every
+    MCP tool
+  - 7 key skill docs do not contain the legacy branch prefix
+- `package.json` — `@contentrain/mcp: workspace:*` devDep.
+
+### Monorepo
+
+- `tsconfig.json` paths — `@contentrain/mcp/tools/*` alias added so
+  TypeScript + vitest resolve the new subpath from source during dev.
+
+### Verification
+
+- `oxlint` across rules + skills + mcp/tools → 0 warnings.
+- `tsc --noEmit` across rules, skills, mcp → 0 errors.
+- `@contentrain/rules` vitest → 16/16 (was 12 — 4 new parity tests).
+- `@contentrain/skills` vitest → 85/85 (was 83 — 2 new parity tests).
+
+### Tool surface
+
+No MCP tool behaviour changes. The new `TOOL_NAMES` export is
+additive; everything else is documentation + tests.
diff --git a/.changeset/phase-r2-package-readmes.md b/.changeset/phase-r2-package-readmes.md
@@ -0,0 +1,64 @@
+---
+"@contentrain/types": patch
+"@contentrain/mcp": patch
+"contentrain": patch
+"@contentrain/query": patch
+"@contentrain/rules": patch
+"@contentrain/skills": patch
+---
+
+docs: phase R2 — align every package README with current public surface
+
+Each package README was cross-checked against its `src/` exports,
+`package.json` `exports` map, and (for MCP) the `TOOL_ANNOTATIONS`
+registry. Every claim in the rewritten READMEs is verified against the
+current codebase.
+
+### `@contentrain/types`
+- Adds the provider-contracts section (`RepoProvider`, `RepoReader`,
+  `RepoWriter`, `ProviderCapabilities`, `Commit`, `Branch`, `FileDiff`,
+  `MergeResult` with optional `sync?: SyncResult`, `LOCAL_CAPABILITIES`).
+- Documents `NormalizePlan*` types, `CONTENTRAIN_BRANCH` constant,
+  `SECRET_PATTERNS`, `ModelSummary`.
+- Keeps the browser-compatible validate/serialize surface described
+  for Studio integration.
+
+### `@contentrain/mcp`
+- Tool count corrected to **17** (was 13/16 depending on section).
+  `contentrain_doctor` row added to the annotations table.
+- Subpath export list now lists every entry in `package.json`:
+  `/core/doctor`, `/core/contracts`, `/core/ops`, `/core/overlay-reader`,
+  `/tools/annotations`.
+- `mergeBranch` description notes the `cr/*` branch naming.
+- Capability gates section mentions doctor alongside scan/apply.
+
+### `contentrain` (CLI)
+- Global `--debug` flag + `CONTENTRAIN_DEBUG` env var documented.
+- New flags table: `--json` on status/doctor/validate/generate/diff/
+  describe/scaffold; `--watch` on validate/generate; `--demo` and
+  `--mcpHttp` / `--authToken` on serve.
+- `setup`, `skills`, `merge`, `describe`, `describe-format`, `scaffold`
+  commands added to the command table.
+- Secure-by-default HTTP transport auth described.
+
+### `@contentrain/query`
+- Clarified that `contentrain generate` (CLI) is the recommended entry
+  point and `contentrain-query generate` is the programmatic path.
+- Added TypeScript snippet for the programmatic `generate()` API.
+
+### `@contentrain/rules`
+- `MCP_TOOLS` length corrected to **17** (includes `contentrain_merge`
+  and `contentrain_doctor`).
+- New Parity section that explains how drift is prevented by
+  `tests/mcp-parity.test.ts`.
+- `shared/` directory catalog added (11 rule files, previously
+  undocumented).
+- Context bridge section includes the 4 stack templates.
+
+### `@contentrain/skills`
+- Reference discovery pattern documented (`references/*.md` loaded on
+  demand, tier table for progressive disclosure).
+- New Parity section mirroring the rules package.
+- Quick discovery snippet added to Public Exports.
+
+No code changes — READMEs only.
diff --git a/.changeset/phase-r3-docs-site-alignment.md b/.changeset/phase-r3-docs-site-alignment.md
@@ -0,0 +1,75 @@
+---
+"contentrain": patch
+---
+
+docs(site): phase R3 — align production docs/ site with current codebase
+
+Every page under `docs/` (the ai.contentrain.io VitePress site) was
+audited against the current source by 5 parallel Explore agents (top-
+level, packages, reference, guides-infra, guides-content-domain), then
+applied sequentially with VitePress build verification.
+
+### Tool-count corrections
+
+- `getting-started.md`, `concepts.md`, `packages/mcp.md`,
+  `packages/cli.md`, `guides/embedding-mcp.md`,
+  `guides/http-transport.md`, `guides/providers.md`,
+  `guides/serve-ui.md` — every "16 tools" / "16 Contentrain tools"
+  reference updated to **17** (includes `contentrain_merge` + the new
+  `contentrain_doctor`).
+
+### Branch-naming corrections (post Phase 7)
+
+- `concepts.md`, `guides/normalize.md` — legacy
+  `contentrain/{operation}/...` branch prefixes rewritten to `cr/*`.
+  MCP's `buildBranchName()` emits `cr/` and `checkBranchHealth` filters
+  on `cr/` — docs must not teach the stale prefix.
+
+### Major rewrites
+
+- **`packages/mcp.md`** — full tool table with 17 rows and the new
+  `contentrain_doctor` in the read section. Capability gates section
+  mentions doctor alongside scan/apply. Complete subpath-export list
+  (adds `/core/doctor`, `/core/contracts`, `/core/ops`,
+  `/core/overlay-reader`, `/tools/annotations`).
+- **`packages/cli.md`** — every command expanded with its real flags:
+  `--json` on status/doctor/validate/generate/diff/describe/scaffold;
+  `--watch` on validate + generate; `--fix` / `--interactive` on
+  validate; global `--debug` / `CONTENTRAIN_DEBUG`; new commands
+  (`merge`, `describe`, `describe-format`, `scaffold`, `setup`,
+  `skills`). Serve section documents `--demo`, `--mcpHttp`, and the
+  secure-by-default Bearer-token requirement on non-localhost binds.
+- **`packages/types.md`** — new Provider Contract Types section
+  (`RepoProvider`, `RepoReader`, `RepoWriter`, `ProviderCapabilities`,
+  `FileChange`, `ApplyPlanInput`, `Commit`, `Branch`, `FileDiff`,
+  `MergeResult` with `sync?`, `SyncResult`, `CommitAuthor`), plus
+  `LOCAL_CAPABILITIES` constant.
+- **`packages/rules.md`** — MCP_TOOLS length (17) and explicit
+  include-checks for `contentrain_merge` and `contentrain_doctor`.
+- **`reference/providers.md`** — complete capability matrix, merge-
+  result shape (including `sync?` for LocalProvider), supporting
+  types, and a minimum-viable custom-provider recipe.
+- **`guides/serve-ui.md`** — new sections for every Phase 14b/c/d
+  capability: `/doctor` and `/format` UI pages, merge preview on
+  BranchDetail, `meta:changed` / `file-watch:error` / `sync:warning`
+  / `branch:merge-conflict` / `branch:rejected` WS events, new HTTP
+  routes (`/api/doctor`, `/api/describe-format`, `/api/preview/merge`,
+  `/api/capabilities`, `/api/branches/:name/sync-status`), secure-by-
+  default HTTP MCP auth.
+
+### Minor
+
+- `packages/sdk.md` — generation entry point ordering: `contentrain
+  generate` is now presented as the recommended path; the
+  programmatic `@contentrain/query/generate` API is documented for
+  build-tool authors.
+- `demo.md` — code snippet gets an explicit `import { singleton }
+  from '#contentrain'` line for copy-paste clarity.
+
+### Verified
+
+- `npx vitepress build` → success in 5.33s, no broken links, no
+  rendering errors.
+- Every claim cross-checked against current source code.
+
+No code changes — docs only.
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -43,9 +43,9 @@ Contentrain AI inverts the traditional CMS workflow:
 
 ### 1. MCP (Infrastructure)
 
-16 tools that AI agents call to manage content:
+17 tools that AI agents call to manage content:
 
-- **Read:** `contentrain_status`, `contentrain_describe`, `contentrain_describe_format`, `contentrain_content_list`
+- **Read:** `contentrain_status`, `contentrain_describe`, `contentrain_describe_format`, `contentrain_doctor`, `contentrain_content_list`
 - **Project setup:** `contentrain_init`, `contentrain_scaffold`
 - **Content and schema writes:** `contentrain_model_save`, `contentrain_model_delete`, `contentrain_content_save`, `contentrain_content_delete`
 - **Normalize:** `contentrain_scan`, `contentrain_apply`
@@ -178,10 +178,10 @@ singleton('hero').locale('tr').get()  // typed, with query API
 Every write operation creates a Git commit on a namespaced branch:
 
 ```
-contentrain/model/hero-section        ← model changes
-contentrain/content/blog-post         ← content changes
-contentrain/normalize/extract/...     ← normalize extraction
-contentrain/normalize/reuse/...       ← source patching
+cr/model/hero-section        ← model changes
+cr/content/blog-post         ← content changes
+cr/normalize/extract/...     ← normalize extraction
+cr/normalize/reuse/...       ← source patching
 ```
 
 Branches are auto-merged or held for review depending on your workflow config.

diff --git a/docs/demo.md b/docs/demo.md
@@ -90,6 +90,8 @@ The agent proposes a dry-run patch, then `contentrain_apply(mode: "reuse")` upda
 ## After
 
 ```tsx
+import { singleton } from '#contentrain'
+
 export default function Hero() {
   const hero = singleton('hero-section').locale('en').get()
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -215,7 +215,7 @@ All packages are published on npm:
 | Package | Description | Install |
 |---|---|---|
 | [`contentrain`](https://www.npmjs.com/package/contentrain) | CLI (init, serve, generate, validate) | `npx contentrain init` |
-| [`@contentrain/mcp`](https://www.npmjs.com/package/@contentrain/mcp) | 16 MCP tools for AI agents | `pnpm add @contentrain/mcp` |
+| [`@contentrain/mcp`](https://www.npmjs.com/package/@contentrain/mcp) | 17 MCP tools for AI agents | `pnpm add @contentrain/mcp` |
 | [`@contentrain/query`](https://www.npmjs.com/package/@contentrain/query) | TypeScript query SDK (optional) | `pnpm add @contentrain/query` |
 | [`@contentrain/types`](https://www.npmjs.com/package/@contentrain/types) | Shared TypeScript types | `pnpm add @contentrain/types` |
 | [`@contentrain/rules`](https://www.npmjs.com/package/@contentrain/rules) | AI agent quality rules | `pnpm add @contentrain/rules` |
@@ -253,7 +253,7 @@ Want to skip setup? Start from a production-ready template with content models,
 
 - [Core Concepts](/concepts) — Models, content kinds, domains, and the governance architecture
 - [Ecosystem Map](/ecosystem) — How AI packages and Studio fit together
-- [MCP Tools](/packages/mcp) — All 16 tools available to your agent
+- [MCP Tools](/packages/mcp) — All 17 tools available to your agent
 - [Normalize Flow](/guides/normalize) — Extract hardcoded strings from existing code
 - [i18n Workflow](/guides/i18n) — Add languages to your content
 - [Framework Integration](/guides/frameworks) — Platform-specific setup patterns

diff --git a/docs/guides/embedding-mcp.md b/docs/guides/embedding-mcp.md
@@ -15,7 +15,7 @@ Studio (`contentrain.io`) is the canonical consumer; the patterns below describe
 `@contentrain/mcp` ships three pieces you plug together:
 
 1. **A `RepoProvider`** — Local / GitHub / GitLab (or your own). Wraps whatever git backend you're targeting.
-2. **An `McpServer`** — the MCP JSON-RPC surface with all 16 Contentrain tools registered.
+2. **An `McpServer`** — the MCP JSON-RPC surface with all 17 Contentrain tools registered.
 3. **A transport** — stdio (for IDE agents) or HTTP (for hosted / remote drivers).
 
 The three are orthogonal. Mix them freely.
@@ -246,7 +246,7 @@ A GitHub Actions job:
 4. Drive it with an MCP client
 5. Let `contentrain_submit` push the `cr/*` branch
 
-All 16 tools are available because the runner has `LocalProvider`.
+All 17 tools are available because the runner has `LocalProvider`.
 
 ### Scripted automation
 

diff --git a/docs/guides/http-transport.md b/docs/guides/http-transport.md
@@ -14,7 +14,7 @@ Typical drivers:
 - **CI runners** — deterministic content operations as part of a pipeline (scaffold, validate, submit).
 - **Remote agents** — any MCP client that wants to operate a Contentrain project without a local checkout.
 
-All three tunnel the same 16 tools through the same `RepoProvider` contract. Which backend answers depends on how the server is wired — see [Providers & Transports](/guides/providers) for the capability matrix.
+All three tunnel the same 17 tools through the same `RepoProvider` contract. Which backend answers depends on how the server is wired — see [Providers & Transports](/guides/providers) for the capability matrix.
 
 ## Starting the HTTP server
 

diff --git a/docs/guides/normalize.md b/docs/guides/normalize.md
@@ -37,8 +37,8 @@ These strings are scattered across dozens of files. Translating means grep-and-r
 
 | Phase | What happens | Source files modified? | Branch pattern |
 |---|---|---|---|
-| 1. Extract | Strings pulled into `.contentrain/content/` | No | `contentrain/normalize/extract/{ts}` |
-| 2. Reuse | Source files patched to reference content | Yes | `contentrain/normalize/reuse/{model}/{ts}` |
+| 1. Extract | Strings pulled into `.contentrain/content/` | No | `cr/normalize/extract/{ts}` |
+| 2. Reuse | Source files patched to reference content | Yes | `cr/normalize/reuse/{model}/{ts}` |
 | 3. Translate | Content copied to new locales and translated | No | Standard content branch |
 
 ::: tip
@@ -246,7 +246,7 @@ After your confirmation:
 
 > "Apply the reuse patches"
 
-The agent calls `contentrain_apply(mode: "reuse", ..., dry_run: false)`. This patches source files and creates a `contentrain/normalize/reuse/hero-section/{timestamp}` branch.
+The agent calls `contentrain_apply(mode: "reuse", ..., dry_run: false)`. This patches source files and creates a `cr/normalize/reuse/hero-section/{timestamp}` branch.
 
 ### Step 5. Validate, submit, and repeat
 

diff --git a/docs/guides/providers.md b/docs/guides/providers.md
@@ -6,7 +6,7 @@ slug: providers
 
 # Providers & Transports
 
-Contentrain MCP runs the same 16 tools over three backends:
+Contentrain MCP runs the same 17 tools over three backends:
 
 - **LocalProvider** — simple-git + a temporary worktree on your disk. Default for `npx contentrain serve --stdio` and the HTTP transport when driven by the CLI.
 - **GitHubProvider** — Octokit over the GitHub Git Data + Repos APIs. No clone, no worktree.