[P2] Make one convention-first onboarding path authoritative; stop leading with custom server wiring and ambiguous package/install roots

[ScriptedAlchemy]

Author-experience gap

Audited main 14c9822bc6c01d8ff2788454d0e1dc7861bc3816. The framework can now generate routes, servers, App contracts, launch records and package-bound installers, but a new author still encounters several incompatible-looking explanations of how to create the first plugin.

This is a documentation/template integration task, not a request for another API layer or another compiler.

Evidence

• Root README Quick start immediately shows explicit skills/hooks and mcp.servers.tools.entry: './src/mcp.ts', then expands into host schemas, diagnostic codes and package internals. The convention-first src/mcp/<server>/tools/<tool>.tsx journey is not the first complete worked example.
• Scaffolder options still describes the MCP template in factory-era terms, while the actual template is already conventional.
• MCP starter config additionally exposes a library export and explicit script binding in the first sample. These are valid optional capabilities, not minimum setup for a generated tool.
• Starter README teaches artifact, publishing dist, and consumer-side npx agent-bundle install together. The root README explicitly warns that the unqualified npm name belongs to an unrelated project. A downstream consumer without the locally installed compiler must not be directed to resolve that name accidentally.

Desired first journey

One current scaffold invocation → a tiny identity/targets config → one conventional tool → dev with an immediately navigable route → one normal test command → build/pack → the exact generated installation instructions. Add a CLI projection or an App only when the tutorial needs that surface. Explain shared layouts/providers/state after the first useful operation works.

Keep a separate lightweight static-skills/plain-hook path; 'Next-like' does not mean every plugin needs JSX or a running server.

Required changes

• Align root README, scaffolder prompt descriptions, generated README and bilingual getting-started pages with the actual conventional template.
• Move manual server factories, arbitrary bin/library exports, host overrides and bundler hooks into explicitly labelled advanced sections. Keep their supported interoperability tests.
• Name each directory by responsibility: authored source, disposable development/type state, composite host artifact, and publishable npm root. State the one exact directory a user packs/installs for the selected delivery mode.
• For downstream installation, use the generated native instructions or supported package-bound entry. Where the compiler itself must be installed, give its verified preview/release selector explicitly; no accidental fetch of the unrelated npm package.
• Remove historical issue numbers, schema provenance detail and diagnostic inventories from the critical first-run path; keep those in reference pages where they belong.
• Document real lifecycle limits such as dev-host support separately from the native target list. [P2] Make scaffolding and installation guidance consume the supported host catalog; Amp is currently rejected at project creation #745 owns the actual Amp scaffolder-list defect.

Acceptance

Run the exact documented journey in a clean temporary directory from published preview packages, not workspace aliases. Add a second tool by creating only its route file; no registry or manifest edit. Verify discovery, generated types, dev navigation, default tests and a relocated/source-free installation. Repeat the static template without a renderer/runtime dependency.

The public tutorial should not require authors to understand epochs, Flight workers, host descriptor lowering, manifest record versions or proof-level internals before calling their first tool. Those implementation concepts remain available in advanced diagnostics. Coordinate #748/#749 for type readiness and default test behavior; do not duplicate their implementations here.

[ScriptedAlchemy]

Cross-repository closeout criterion — prove deletion from the normal user journey

The deeper continuation found two additional author-facing seams: #752 (caller input versus parsed handler types) and #753 (shared descriptive metadata rather than repeated host blocks). Add their outcomes to this existing first-run acceptance, without turning this issue into another implementation umbrella.

A useful completion proof is two small published-package fixtures:

1. Static plugin: add one skill and one plain hook, choose a supported host, run the normal check, pack the documented root and verify installation. No synthetic MCP/React/state process.
2. Executable plugin: create a tool with an optional/defaulted field, add a CLI projection and an App only when needed, call it from Workbench, run the default tests, and install the same built behavior with source removed. Changing a schema or adding a route requires no second catalog, browser interface, manifest edit, or warmed-up build in another terminal.

Keep details available in reference pages, but make the first screen/README answer four questions: what file to edit, what command to run, where the result appears, and what exact output to install. Distinguish a native compilation target from a compatible portable reader and an authenticated live-dev host; do not compress those into a misleading single support checkbox.

Use existing #745/#746/#748/#749/#747/#751 implementations and test owners. No new orchestration CLI, parallel compiler, universal host registry, or mandatory framework reorganization is necessary to prove this journey. The acceptance is observable behavior from clean consumer packages, not a line-count target or an empty issue list.

[ScriptedAlchemy]

Docsite implementation: #754 — expanded capability/authoring pass, hosted Docs gate now green

Draft PR #754 changes nine English/Chinese guide/reference pairs plus six sidebar metadata files. Current head: 36a18979c6c3169d771c21b289312592915f19cf.

The convention-first introduction, executable quick start, composite source-tree guide and corrected shipping path are joined by:

• Target and capability map: all five built-in outputs, practical feature-to-authoring navigation, and direct links to the existing generated host/event/notice matrices and dated client records.
• Reuse the framework: canonical tools across CLI/App surfaces, shared contracts, public client transport, semantic/plain hooks, preflight, observed context/state, notices, payloads and supported installation.
• Troubleshooting: discovery/types, target eligibility, App opening/lifecycle, package/bin paths, runtime data and proof boundaries.
• Corrected target/output and reference pages: Amp nesting, conditional isolation files, canonical npm output, and manifest-v4 web records referencing existing server launch bindings instead of duplicating them.

No second capability registry was added. Native targets, portable readers, live-dev hosts, display profiles and npm delivery are distinct. Research issues do not become support claims; Aider and Jules remain excluded.

Verified hosted gate

Docs run 34166074213 passed on the current head, including pnpm lint, pnpm build and pnpm docs:site:build. CI, Changeset and Package preview also passed. Pages deployment was skipped.

The preceding Docs run caught a translated label inside a code fence that must match across locales. The authored fence was corrected in 36a18979; the locale checker was not weakened.

Keep #750 open: root README/scaffolder-template integration and the complete fresh-project tutorial remain outside this docs-only change, as do #745–#753's actual framework fixes. The PR remains draft for independent review and tutorial acceptance. No local build or native session was run, and no merge, deployed-site update or npm release was performed.

[ScriptedAlchemy]

Second docsite audit pass is reflected in draft #754. The branch now has 24 bilingual doc/navigation changes, not the original eight-page slice.

The author-facing target/capability guide now explicitly lists all five built-in outputs (amp, claude, codex, cursor, portable), maps major authoring surfaces to the generated Hosts/Events/Notices evidence, distinguishes native target vs portable-compatible client vs development/browser/runtime proof, and documents capability-state semantics without turning unverified into unsupported.

The target/artifact and shipping references were also rewritten around the current composite artifact/npm-root/install contracts, including Amp's nested native directory and source-free package proof. Reuse/troubleshooting pages were added so the critical path says what the framework owns instead of teaching second registries/transports/installers.

One separate stale page remains outside this PR's author-facing scope: the compiler-architecture guide still enumerates only four built-in adapters and omits Amp from createDefaultRegistry. Filed #755 with exact EN/ZH corrections rather than silently mixing a large compiler-internals rewrite into this onboarding PR.

#754 remains draft because MDX/Twoslash/docsite build and the clean preview-package tutorial have not been executed in this GitHub-only environment. Do not close #750 until its root README/scaffolder/template/default-test acceptance is also reconciled.

[ScriptedAlchemy]

Closed by #754, squash-merged as 361d27ff5e92cd47032e4e954d4d92301d913e3e.

One onboarding path is now authoritative, in both locales:

Ask	Where it landed
Lead with the conventional route, not custom server wiring	guide/start/quick-start adds the first tool by writing src/mcp/<server>/tools/<tool>.tsx; no registration array, no McpServer, no generated route script. A custom server is named as the deliberate escape hatch it is.
One place that says what a target compiles vs. what a client does	New guide/start/capabilities maps the two and links the generated host/event/diagnostic matrices instead of restating them.
Unambiguous package and install roots	guide/distribution/index separates the composite artifact root from the generated npm root, and says which command reads which; --artifact and --root are documented as mutually exclusive (verified: option '--artifact <path>' cannot be used with option '--root <root>').
Stop the framework-glue recipes	New guide/authoring/reuse-framework gives the supported recipe for each surface (CLI projection, browser App, events/hooks, request context, assets, installation) and names the reimplementations not to write.
Somewhere to look when the path fails	New guide/development/troubleshooting, organized by failing boundary: authored source, compiled artifact, installed package, running host.

Acceptance, beyond the local gate (pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit
and pnpm docs:site:build, all green — 0 broken links over 30105 anchors, language parity
checked):

• The Quick start journey was executed against a copy of the mcp-server template using the
  page's exact code. validate succeeds from the route file alone;
  renderRoute('tool:status/hello', { input: { name: 'Ada' } }) returns
  { message: 'Hello, Ada.' }; adding hello.cli.ts with command: ['hello'] makes
  node artifact/bin/<plugin>.mjs hello --name Ada print Hello, Ada.
• Twoslash is a real gate, not an assumption: an unresolvable import in the Quick start sample
  fails pnpm docs:site:build with [@rspress/plugin-twoslash] Twoslash error in code … 2307.
  All ten twoslash blocks in the PR compile.

Two blocking review findings were fixed before merge: the docs had claimed the MCP starter could
be retargeted to Amp (it cannot — validate --target amp over that template fails with
amp.mcp.generated-local), and had called every starter private (cli-tool is publishable as
scaffolded).

Still open, deliberately: the pages document today's scaffolder, which rejects --targets amp
at project creation. #745 closes that in source and updates these paragraphs in the same PR.