docs: complete convention-first guides, targets, and capability navigation (EN/ZH)

[ScriptedAlchemy]

Completes the convention-first onboarding path on the docsite in both locales: one authoritative
Quick start that adds a tool by writing a route file, a capability map that separates compiled
output from client behavior, and reference/troubleshooting pages that send an author to the
existing generated matrices instead of a second hand-maintained one.

Pages added: guide/start/capabilities, guide/authoring/reuse-framework,
guide/development/troubleshooting (en + zh, with matching _meta.json navigation). Pages
rewritten: guide/start/{index,quick-start,project-structure}, guide/distribution/index,
reference/{index,targets-artifacts}.

Docs-only: no publishable package changes, so no changeset (skip-changeset).

Local gate (authoritative)

Run on 867d3787fb, which contains current origin/main:

Command	Result
pnpm build	pass
pnpm typecheck	pass
pnpm lint	pass
pnpm test:unit	pass, 0 failures
pnpm docs:site:build	pass — locale drift, diagnostics coverage, Rspress build, language parity, 0 broken links / 30105 anchors over 35421 internal links in 122 files

Tutorial and Twoslash acceptance

Twoslash is a real gate, verified by falsification rather than assumed: with an unresolvable
import in the Quick start's defineConfig sample the docsite build fails
([@rspress/plugin-twoslash] Twoslash error in code … 2307, exit 1). All ten twoslash blocks in
this PR compile against the built declarations. (A first attempt at falsification — an extra
key in the defineConfig object — correctly did not fail, because defineConfig is generic
and infers the literal type.)

The Quick start's "add your first tool" journey was executed end to end against a copy of the
mcp-server template, using the page's exact code:

• src/mcp/status/tools/hello.tsx (route file only, no registration edit) → validate succeeds.
• renderRoute('tool:status/hello', { input: { name: 'Ada' } }) → result is
  { message: 'Hello, Ada.' }, passing in the template's own route-unit pool.
• hello.cli.ts with command: ['hello'] → build emits the routed bin, and
  node artifact/bin/<plugin>.mjs hello --name Ada prints Hello, Ada.
• agent-bundle --version and the documented inspect --artifact / --root exclusivity
  (option '--artifact <path>' cannot be used with option '--root <root>') match the
  troubleshooting page.

Deslop

Deslop: gpt-5.6-sol-max + claude-fable-5-1-thinking-xhigh, 6 edits. Removed a duplicated
capability matrix that would have forked the generated host reference, an unused
import React from 'react' in a route sample, and renamed the example server from tools to
greeter so the sample path no longer reads src/mcp/tools/tools/hello.tsx.

Self-review

Reviewers: claude-fable-5-1-thinking-xhigh and gpt-5.6-sol-max (full diff), then
gpt-5.6-sol-max again on the fix commit.

Finding	Disposition
Blocking: the docs told an author to retarget this MCP starter to Amp, but Amp's skill-scoped MCP contract refuses the starter's compiler-owned local server — validate --target amp over templates/mcp-server fails with amp.mcp.generated-local	Fixed in 867d3787fb: Quick start and the capability map now name the failure and point an Amp project at minimal or at a remote/globally resolvable command server beside exactly one Skill
Blocking: "The starters are private development packages" — only minimal and mcp-server set private: true; cli-tool is publishable as scaffolded	Fixed in 867d3787fb (en + zh)
Non-blocking: the capability page duplicated the generated host matrix	Fixed before review completed (23d6bdc343) — the page now links the generated pages
Non-blocking: Amp's skill-scoped MCP restriction appears on four pages	Dismissed: tutorial, capability map, reference, and troubleshooting each need the statement at a different level of detail; the authoritative rows stay generated
Non-blocking: "Compiled surfaces" prose said to be duplicated across two pages	Dismissed: the heading and paragraph exist once, in reference/targets-artifacts

Confirmation pass on 867d3787fb: no blocking or non-blocking findings.

The scaffolder gap this PR documents (--targets amp rejected at project creation) is
#745; the follow-up closes it in
source and updates these paragraphs.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 867d378

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@754

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@754

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/rsc-markdown-stream@754

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@754

commit: 867d378

[ScriptedAlchemy]

Second documentation audit pass

Re-audited the Rspress site against the current target registry, pinned capability records, generated reference ownership, package/install APIs, and the branch's actual changed-file inventory.

The branch already contains the broader work requested here: 24 bilingual files, including a dedicated guide/start/capabilities.mdx, reuse-framework.mdx, troubleshooting, rewritten target/artifact reference, and Reference navigation. I briefly created a second capability page under Reference during the audit, then removed it after confirming the Start capability map is already the authoritative human-oriented page. The generated Hosts/Events/Notices pages remain the exact versioned evidence; there is no second hand-maintained matrix.

Verified the author-facing map explicitly covers all five built-in output targets: amp, claude, codex, cursor, portable; major authoring surfaces; capability states; recorded portable clients versus native targets; dev/browser/runtime proof distinctions; Amp's skill-scoped MCP limitation; installation roots; and proof-level boundaries.

Two stale generated/compiler-reference sources remain outside this PR's focused rewrite and now have dedicated issues:

• [P2 docs] Refresh compiler-architecture target registry and capability evidence for Amp #755 — guide/concepts/architecture.mdx still omits Amp from the built-in adapter table and createDefaultRegistry prose.
• [P2 docs] Fix generated AB4100 diagnostics reference to include Amp as a built-in target #756 — docs/diagnostics.md still tells AB4100 readers the built-in registry has only Claude/Codex/Cursor/portable, which propagates into the generated diagnostics page.

Do not hand-edit generated hosts.md, events.md, notices.md, or diagnostics.md output in this PR. Fix their owning source contracts.

Current head after cleanup is 72411bf9907d2b77c66d547ed030a505d169220a. CI, Changeset, and Package preview report success; Docs is still pending at this check. That is not yet a docsite-pass claim. Keep draft until Docs finishes and the tutorial/MDX/Twoslash acceptance described in the PR body is actually exercised.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-07T23:57:40.273872Z	867d378	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.