feat(docs): rewrite contributor and end-user pages

[cameroncooke]

Two coordinated rewrites of the docs site so the published pages can be read end-to-end without prior project knowledge.

The Contributing section had drifted into contributor-jargon-first prose. Pages introduced canonical terms (manifest, runtime boundary, tool handler, daemon, transport, rendering) before defining them. Separately, end-user pages had accumulated developer-facing leaks: raw MCP annotation keys, internal TypeScript exports, an internal env var, all in pages targeted at users. Both problems are addressed here, driven by two audits checked in under docs/:

• docs/reviews/docs-audit-end-user-vs-contributing.md — page-by-page audit of every non-Contributing page, with explicit fix list
• docs/investigations/architecture-doc-accuracy-audit-2026-04-25.md — claim-by-claim verification of architecture.mdx against the source

Contributing / Architecture (full rewrite)

architecture.mdx is now the canonical entry point. It opens in plain English, then a ## Core terms section defines the architecture vocabulary once before any subpage uses it: workflow, manifest, predicate, exposure, availability, runtime boundary, tool handler, fragment, structured output, next step, rendering, render session, daemon, and transport. The existing Mermaid component diagram and design-pressures bullets stay in place; a new conceptual Request flow walkthrough lands before the diagram.

Each of the six architecture subpages (runtime-boundaries, startup-config, manifest-visibility, tool-lifecycle, rendering-output, daemon) opens with a plain-English orientation paragraph and a short Terms used here recap that links back to the canonical glossary. Existing diagrams, tables, and contracts are preserved.

contributing.mdx, tool-authoring.mdx, and testing.mdx received targeted accessibility fixes: define-before-use for handler / manifest / fragment / structured output / fixture / snapshot etc., without restructuring the practical setup or checklist content.

The Streaming tools section in tool-authoring.mdx was rewritten from one opaque example into three clearly scoped patterns: raw subprocess transcript (CLI raw mode only), typed domain fragments, and the xcodebuild pipeline. Each of the five xcodebuild-pipeline helpers gets a one-line explanation in a table, and a callout warns about the ctx variable shadowing inside pipeline executors. AnyFragment is documented as a closed union, and the architectural cost of adding a new fragment kind is called out explicitly.

The rewrite was validated by simulating six fresh-Claude readers asking realistic onboarding questions of the rewritten pages. All six produced correct answers; the small set of inconsistencies they surfaced (two missing glossary entries, a duplicate table cell in the runtime-boundaries page, naming drift between "final structured response" and "final envelope" in rendering-output, an unstated --output text → cli-text mapping) has been patched in this PR.

End-user pages (polished per audit)

Per the end-user audit, removed contributor-facing content from user-facing pages and rewrote a few passages in user voice:

• output-formats.mdx: dropped the internal StructuredOutputEnvelope<TData> TypeScript block and the "Environment signal for tool authors" section.
• mcp-mode.mdx: rewrote the tool-annotations passage as user-outcome prose; the raw readOnlyHint / destructiveHint / openWorldHint reference is now on the new mcp-protocol-support page.
• cli.mdx: rewrote the per-workspace daemon section to lead with user-facing outcome rather than implementation detail.
• Smaller framing/wording fixes in xcode-ide.mdx, privacy.mdx, session-defaults.mdx, workflows.mdx, introduction.mdx, and setup.mdx.

New pages

• mcp-protocol-support.mdx (Reference group) — declares which MCP protocol features XcodeBuildMCP implements (tools, annotations, structured content, resources, notifications, prompts, server capabilities), with the full annotation key reference for power users.
• output-formats.mdx is effectively a rebuild around the trimmed scope: cleaner separation of CLI output modes vs MCP structuredContent.

Site infrastructure

• New app/docs/_components/mermaid-diagram.tsx component for the diagrams used throughout the new architecture pages.
• app/docs/_data/routes.ts and app/docs/_content/index.ts updated to register all new slugs and reorder the Reference + Contributing sidebar groups.
• Small fixes to app/docs/_components/tabs.tsx, mdx-components.tsx, and app/docs/_styles/scraps.css.

Notes for review

• The two audit documents under docs/ are checked in as supporting context. They live outside app/docs/_content/ and are not published on the site.
• Generated tool docs (TOOLS.md, TOOLS-CLI.md) live in the main XcodeBuildMCP repo and are unchanged here.
• No routes.ts page slug was removed — only added — so existing inbound links to user pages are unaffected.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
xcodebuildmcp-com	Ready	Preview, Comment	Apr 25, 2026 7:50pm

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3db4301. Configure here.}

[cursor]

AGENTS.md fully duplicates CLAUDE.md risking drift

Low Severity

The newly added AGENTS.md is a duplicate of CLAUDE.md. This creates a maintenance burden, as future updates to project rules or documentation will require manual synchronization across both files, risking inconsistent instructions for different AI tools.

 

^{Reviewed by Cursor Bugbot for commit 3db4301. Configure here.}