Repository navigation
[P2] Make one convention-first onboarding path authoritative; stop leading with custom server wiring and ambiguous package/install roots #750
Description
Activity
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:
- 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.
- 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.
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 buildandpnpm 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.
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 turningunverifiedinto 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.
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-startadds the first tool by writingsrc/mcp/<server>/tools/<tool>.tsx; no registration array, noMcpServer, 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/capabilitiesmaps the two and links the generated host/event/diagnostic matrices instead of restating them.Unambiguous package and install roots guide/distribution/indexseparates the composite artifact root from the generated npm root, and says which command reads which;--artifactand--rootare documented as mutually exclusive (verified:option '--artifact <path>' cannot be used with option '--root <root>').Stop the framework-glue recipes New guide/authoring/reuse-frameworkgives 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
andpnpm 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-servertemplate using the
page's exact code.validatesucceeds from the route file alone;
renderRoute('tool:status/hello', { input: { name: 'Ada' } })returns
{ message: 'Hello, Ada.' }; addinghello.cli.tswithcommand: ['hello']makes
node artifact/bin/<plugin>.mjs hello --name AdaprintHello, Ada. - Twoslash is a real gate, not an assumption: an unresolvable import in the Quick start sample
failspnpm docs:site:buildwith[@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 ampover that template fails with
amp.mcp.generated-local), and had called every starter private (cli-toolis 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.- The Quick start journey was executed against a copy of the
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
mcp.servers.tools.entry: './src/mcp.ts', then expands into host schemas, diagnostic codes and package internals. The convention-firstsrc/mcp/<server>/tools/<tool>.tsxjourney is not the first complete worked example.artifact, publishingdist, and consumer-sidenpx agent-bundle installtogether. 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 →
devwith 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
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.