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/.changeset/phase-r3b-root-md-alignment.md b/.changeset/phase-r3b-root-md-alignment.md
@@ -0,0 +1,30 @@
+---
+"contentrain": patch
+---
+
+docs: phase R3b — align root README / CLAUDE / AGENTS with current codebase
+
+Repo root guidance files updated so they agree with the per-package
+READMEs (phase R2) and the docs site (phase R3):
+
+### README.md
+- Architecture diagram: `MCP (16 tools)` → `MCP (17 tools)`.
+- Feature bullet: "MCP engine — 16 tools" → "17 tools".
+- Packages table: `@contentrain/mcp` row → "17 MCP tools + ...".
+
+### CLAUDE.md
+- Monorepo tree `packages/mcp` comment → `17 MCP tools`.
+- npm-packages table → `17 MCP tools`.
+- Obsolete "Octokit YOK in MCP" decision rewritten: `@octokit/rest`
+  and `@gitbeaker/rest` are optional peer dependencies (Phase 5.1 + 8).
+
+### AGENTS.md
+- Essentials bullet: "16 MCP tools with mandatory calling protocols"
+  → 17.
+- Packages table: mcp row → "17 MCP tools — content operations engine".
+
+### RELEASING.md
+- No changes — release flow docs stayed accurate through R1-R3.
+
+### CONTRIBUTING.md, CLA.md, CODE_OF_CONDUCT.md
+- No changes — standards files, no code-specific content.
diff --git a/AGENTS.md b/AGENTS.md
@@ -48,15 +48,15 @@ Load `packages/rules/essential/contentrain-essentials.md` (~120 lines) for compa
 - Architecture (MCP = deterministic infra, Agent = intelligence)
 - Four model kinds (singleton, collection, document, dictionary)
 - Content format rules (JSON only, canonical serialization)
-- 16 MCP tools with mandatory calling protocols
+- 17 MCP tools with mandatory calling protocols
 - Git workflow (dedicated contentrain branch, worktree isolation)
 - Security boundaries
 
 ## Packages
 
 | Directory | npm | What it does |
 |-----------|-----|-------------|
-| `packages/mcp` | `@contentrain/mcp` | 16 MCP tools — content operations engine |
+| `packages/mcp` | `@contentrain/mcp` | 17 MCP tools — content operations engine |
 | `packages/cli` | `contentrain` | CLI + Serve UI + MCP stdio entrypoint |
 | `packages/sdk/js` | `@contentrain/query` | Generated TypeScript query SDK |
 | `packages/types` | `@contentrain/types` | Shared type definitions |

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -11,7 +11,7 @@ MIT-licensed monorepo for Contentrain's open-source packages: MCP tools, CLI, Ty
 ```
 contentrain-ai/
 ├── packages/
-│   ├── mcp/          — 16 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers (simple-git + zod + MCP SDK)
+│   ├── mcp/          — 17 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers (simple-git + zod + MCP SDK)
 │   ├── cli/          — citty + tsdown (init/serve/validate/normalize/connect)
 │   ├── types/        — Shared TypeScript types (@contentrain/types)
 │   ├── rules/        — AI agent quality rules & conventions
@@ -72,7 +72,7 @@ When working with Contentrain content operations (models, content, normalize, va
 
 - **JSON only** — no YAML
 - **Git mandatory** — `contentrain init` auto `git init`
-- **Octokit YOK in MCP** — MCP = local-first, platform-agnostic. GitHub API = Studio/CLI only
+- **Optional remote providers** — MCP is local-first by default (stdio + LocalProvider). `@octokit/rest` (GitHubProvider) and `@gitbeaker/rest` (GitLabProvider) ship as **optional peer dependencies** — installed only when a remote provider is used
 - **Every write uses worktree + dedicated contentrain branch + update-ref** — model_save and content_save alike
 - **Collection storage = object-map** — `{ entryId: { fields } }`, sorted by ID
 - **Canonical serialization** — deterministic JSON output, sorted keys, 2-space indent, trailing newline
@@ -90,7 +90,7 @@ When working with Contentrain content operations (models, content, normalize, va
 
 | Package | Name | Description |
 |---|---|---|
-| packages/mcp | @contentrain/mcp | 16 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers |
+| packages/mcp | @contentrain/mcp | 17 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers |
 | packages/cli | contentrain | CLI (npx contentrain) |
 | packages/types | @contentrain/types | Shared TypeScript types |
 | packages/rules | @contentrain/rules | AI agent quality rules & conventions |

diff --git a/README.md b/README.md
@@ -94,7 +94,7 @@ This is the strongest entry point into the product:
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
-│  AI Agent    │────▶│  MCP (16 tools)  │────▶│ .contentrain/│
+│  AI Agent    │────▶│  MCP (17 tools)  │────▶│ .contentrain/│
 │  (decides)   │     │  (enforces)      │     │ (stores)     │
 └─────────────┘     └──────────────────┘     └──────┬───────┘
                                                      │
@@ -145,7 +145,7 @@ Works with Nuxt, Next.js, Astro, SvelteKit, Vue, React, Node, Go, Python, Swift,
 
 - **Git-native** — every write goes through worktree isolation + review branches
 - **Normalize flow** — scan codebase for hardcoded strings → extract → create i18n-ready content → patch source files
-- **MCP engine** — 16 tools over stdio or HTTP transport, works with Claude Code, Cursor, Windsurf, or any MCP client
+- **MCP engine** — 17 tools over stdio or HTTP transport, works with Claude Code, Cursor, Windsurf, or any MCP client
 - **Provider-agnostic engine** — the same tool surface runs over a local worktree, GitHub, or GitLab (self-hosted included) with zero tool-code changes. HTTP transport available for remote drivers such as Studio.
 - **Canonical serialization** — sorted keys, deterministic output, clean git diffs, conflict-free parallel edits
 - **Agent rules & skills** — behavioral policies and step-by-step workflows ship as npm packages
@@ -176,7 +176,7 @@ See [`AGENTS.md`](AGENTS.md) for the full skill catalog and agent guidance.
 
 | Package | npm | Role |
 |---|---|---|
-| [`@contentrain/mcp`](packages/mcp) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Fmcp)](https://www.npmjs.com/package/@contentrain/mcp) | 16 MCP tools + stdio / HTTP transport + Local / GitHub / GitLab providers |
+| [`@contentrain/mcp`](packages/mcp) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Fmcp)](https://www.npmjs.com/package/@contentrain/mcp) | 17 MCP tools + stdio / HTTP transport + Local / GitHub / GitLab providers |
 | [`contentrain`](packages/cli) | [![npm](https://img.shields.io/npm/v/contentrain)](https://www.npmjs.com/package/contentrain) | CLI + Serve UI + MCP stdio entrypoint |
 | [`@contentrain/query`](packages/sdk/js) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Fquery)](https://www.npmjs.com/package/@contentrain/query) | Generated TypeScript query SDK |
 | [`@contentrain/types`](packages/types) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Ftypes)](https://www.npmjs.com/package/@contentrain/types) | Shared type definitions + constants |

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