Phase R3: align production docs/ site with current codebase#44
Merged
Phase R3: align production docs/ site with current codebase#44
Conversation
… + cr/* branches + parity tests
Closes the two P1 drift findings and installs a drift-detection
mechanism so they don't come back:
1. contentrain_merge missing from public catalog — @contentrain/rules
MCP_TOOLS listed 15 tools while @contentrain/mcp registers 17
(merge + doctor). Skills tool reference also jumped submit → bulk
with no merge section.
2. Legacy contentrain/{operation}/... branch namespace still taught
by essentials, review/normalize prompts, and multiple skills.
MCP's buildBranchName() returns cr/... (Phase 7). Agents following
shipped guidance would look for branches that don't exist.
### @contentrain/mcp
- Public export TOOL_NAMES in ./tools/annotations (frozen, derived
from TOOL_ANNOTATIONS). Single source of truth.
- New ./tools/annotations subpath export. Build script emits it.
### @contentrain/rules
- MCP_TOOLS extended to 17 (contentrain_merge + contentrain_doctor).
- essentials: doctor row added; feature-branch pattern → cr/...;
health-threshold language mentions cr/*.
- review-mode prompt: every legacy contentrain/<op>/... → cr/<op>/...
- normalize-mode prompt: branch pattern table rewritten.
- shared/workflow-rules: branch pattern spec rewritten.
- tests/mcp-parity.test.ts (new, 4 tests): MCP_TOOLS ↔ TOOL_NAMES
match, essentials cite every tool, buildBranchName emits cr/,
docs contain no legacy branch prefix.
- package.json: @contentrain/mcp workspace devDep for parity test.
### @contentrain/skills
- references/mcp-tools.md: new contentrain_merge (after submit) +
contentrain_doctor (new Doctor Tools subsection). Submit description
updated to cr/*.
- references/mcp-pipelines.md + workflow.md: branch spec + examples
rewritten to cr/*.
- contentrain-normalize SKILL + references (extraction, reuse):
4 stale contentrain/normalize/* → cr/normalize/*.
- contentrain-translate SKILL: translate branch pattern updated.
- tests/mcp-parity.test.ts (new, 2 tests): references/mcp-tools.md
has ### <tool> heading for every MCP tool; 7 skill docs contain no
legacy branch prefix.
- package.json: workspace devDep.
### Monorepo
- tsconfig.json paths: @contentrain/mcp/tools/* alias so TS + vitest
resolve the new subpath from source during dev.
### Verification
- oxlint rules + skills + mcp/tools → 0 warnings
- tsc --noEmit rules + skills + mcp → 0 errors
- @contentrain/rules vitest → 16/16 (was 12, +4 parity)
- @contentrain/skills vitest → 85/85 (was 83, +2 parity)
Tool surface: no behaviour changes. TOOL_NAMES export is additive;
everything else is documentation + tests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every package README cross-checked against src/ exports, package.json exports map, and (for MCP) TOOL_ANNOTATIONS registry. Every claim in the rewritten READMEs is verified against current code. ### types - Provider contracts section (RepoProvider, RepoReader, RepoWriter, ProviderCapabilities, Commit, Branch, FileDiff, MergeResult with optional sync?: SyncResult, LOCAL_CAPABILITIES). - NormalizePlan* types, CONTENTRAIN_BRANCH, SECRET_PATTERNS, ModelSummary. - Browser-compatible validate/serialize surface for Studio integration. ### mcp - Tool count corrected to 17 (was 13/16 in different sections). contentrain_doctor row added to 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 uses cr/* branch naming. - Capability gates section mentions doctor alongside scan/apply. ### cli (contentrain) - Global --debug flag + CONTENTRAIN_DEBUG env var. - Flag matrix: --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 in command table. - Secure-by-default HTTP transport auth described. ### sdk (@contentrain/query) - contentrain generate (CLI) is now the recommended entry point; contentrain-query generate clarified as programmatic path. - Added programmatic generate() API snippet. ### rules - MCP_TOOLS length corrected to 17 (+merge +doctor). - New Parity section explaining tests/mcp-parity.test.ts. - shared/ directory catalog added (11 rule files, previously undocumented). - Context bridge section mentions the 4 stack templates. ### skills - Reference discovery pattern (references/*.md on-demand, tier table for progressive disclosure). - New Parity section mirroring rules package. - Public Exports includes discovery snippet. No code changes — READMEs only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every page under docs/ audited by 5 parallel Explore agents against
source (top-level, packages, reference, guides-infra, guides-content)
then applied with VitePress build verification.
### Tool-count corrections (16 → 17)
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" updated to 17 (contentrain_merge
+ contentrain_doctor).
### Branch-naming corrections (Phase 7 migration)
concepts.md, guides/normalize.md — legacy contentrain/{operation}/...
branch prefixes rewritten to cr/*. MCP emits cr/; docs must not teach
the stale prefix.
### Major rewrites
- packages/mcp.md — full 17-tool table, contentrain_doctor in read
section, complete subpath-export list (adds /core/doctor,
/core/contracts, /core/ops, /core/overlay-reader, /tools/annotations).
- packages/cli.md — every command with real flags: --json on read
commands, --watch on validate+generate, global --debug /
CONTENTRAIN_DEBUG, new commands (merge, describe, describe-format,
scaffold, setup, skills). Serve section documents --demo, --mcpHttp,
secure-by-default bearer token requirement.
- packages/types.md — new Provider Contract Types section
(RepoProvider, RepoReader, RepoWriter, ProviderCapabilities,
FileChange, ApplyPlanInput, Commit, Branch, FileDiff, MergeResult
with sync?, SyncResult) + LOCAL_CAPABILITIES.
- packages/rules.md — MCP_TOOLS.length === 17 + explicit includes for
contentrain_merge and contentrain_doctor.
- reference/providers.md — complete capability matrix, MergeResult
shape with sync? for LocalProvider, supporting types, minimum-viable
custom-provider recipe.
- guides/serve-ui.md — new sections for every Phase 14b/c/d surface:
/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 — contentrain generate (CLI) is now the recommended
generation entry; @contentrain/query/generate API documented for
build-tool authors.
- demo.md — code snippet gets explicit `import { singleton } from
'#contentrain'`.
### 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.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on R2 PR #43. Every docs page was audited by 5 parallel Explore agents against current source code, then applied with VitePress build verification.
Tool-count corrections (16 → 17)
8 files referenced "16 tools" — all updated to 17 (adds
contentrain_mergeandcontentrain_doctor).Branch-naming corrections (Phase 7 migration)
concepts.md+guides/normalize.md— legacycontentrain/{operation}/...branch prefixes rewritten tocr/*. MCP emitscr/; docs must not teach the stale prefix.Major rewrites
contentrain_doctoradded, complete subpath-export list./doctor+/formatpages, merge preview, 5 new WS events, 5 new HTTP routes, secure-by-default auth.Minor
contentrain generateis now recommended; programmatic API documented.Test plan
npx vitepress build→ success, no broken links, no rendering errors🤖 Generated with Claude Code