Phase R2: align every package README with current public surface#43
Merged
Phase R2: align every package README with current public surface#43
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>
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 top of PR #42 (R1). Every package README was cross-checked against source and rewritten where stale.
Verified against source
Each README was diffed against:
src/exports (every public symbol documented)package.jsonexportsmap (every subpath listed)TOOL_ANNOTATIONSregistry (17 tools)src/index.tssubCommands + per-command flagsPer-package changes
@contentrain/types — Adds provider contracts section (RepoProvider, RepoReader, RepoWriter, ProviderCapabilities, MergeResult.sync), NormalizePlan* types, CONTENTRAIN_BRANCH constant, SECRET_PATTERNS, ModelSummary.
@contentrain/mcp — Tool count 13 → 17, new contentrain_doctor row, subpath exports now complete (/core/doctor, /core/contracts, /core/ops, /core/overlay-reader, /tools/annotations).
contentrain (CLI) — Global --debug flag documented; full flag matrix for --json/--watch/--yes/--demo/--mcpHttp; setup/skills/merge/describe/describe-format/scaffold commands in command table.
@contentrain/query —
contentrain generateis now the recommended entry (wascontentrain-query generate); programmatic API snippet added.@contentrain/rules — MCP_TOOLS length corrected to 17, new Parity section, shared/ directory catalog (11 rule files), context bridge includes stack templates.
@contentrain/skills — Reference discovery pattern, progressive-disclosure tier table, Parity section mirroring rules.
Test plan
No code, no tests, no behavior change.
🤖 Generated with Claude Code