Clarify the operation/JSX model and what “RSC runtime” does not provide

[ScriptedAlchemy]

Problem

The current framework-mode example makes the central abstraction difficult to recognize:

• examples/audiobook-curator/src/application.ts only composes operation arrays, so it contains no JSX.
• Each src/operations/*.tsx file contains mostly schemas, CLI parsing, and MCP metadata; its JSX may be only render: (receipt) => <CuratorResult ... />.
• src/result.tsx renders <Mcp.Result> / <Mcp.Text>, which lowerMcpResult synchronously lowers into an MCP CallToolResult.
• The CLI projection does not render JSX at all; it serializes the validated result as JSON.
• @agent-bundle/rsc-runtime explicitly does not own an RSC renderer, transport, persistence, or application state.

A reader reasonably expects “RSC runtime” and .tsx operation files to expose React Server Component composition or a server-rendering lifecycle. What exists today is a shared typed operation definition with optional CLI/MCP projections and a React-element result DSL for the MCP projection.

Why it matters

This obscures what an operation actually is and makes framework mode look either more magical or less complete than it is. It also makes it unclear whether JSX is the application model, the transport result format, or merely an MCP serializer.

Suggested direction

• Document one operation end to end: input schema -> execute -> result schema -> CLI JSON output and MCP JSX lowering.
• State explicitly that an operation is a host-neutral use-case/endpoint definition, not a CLI command.
• State explicitly whether the package intends to become a real RSC renderer/runtime or remain a synchronous React-element protocol DSL.
• If it remains the latter, reconsider the rsc-runtime naming or introduce terminology that does not imply a React Server Components transport/lifecycle.
• Show the actual JSX in the primary framework-mode example instead of making readers discover the one-line renderer at the bottom of a metadata-heavy file.

Acceptance

A new reader can answer, from the framework-mode docs alone:

1. What is an operation?
2. Which parts are shared by CLI and MCP?
3. Which projection consumes render?
4. Is any React Server Components renderer or Flight transport involved?
5. Why are operation modules .tsx?

[ScriptedAlchemy]

Docs for this landed in #89 (squash 766e8243). Leaving this open — the docs half is done, the naming half is not. Details below.

What the merged docs now cover

docs/framework-mode.md gained two sections that answer the acceptance questions from the docs alone:

• "One operation, end to end" — the full defineOperation for the status operation that the defineRscApplication snippet already referenced, with the render JSX inline instead of implied. Fields are grouped by role (shared core / CLI projection / MCP projection), then the pipeline is walked: inputSchema.parse → execute → resultSchema.parse, after which the CLI writes one line of JSON and sets an exit code while MCP calls render and lowers the element tree through lowerMcpResult.
• "Why .tsx, and what 'RSC runtime' is not" — states that an operation is a host-neutral use-case definition rather than a CLI command, that no RSC renderer or Flight transport is involved, names the thing an MCP result DSL, and closes with a five-point recap keyed to the acceptance list above.

packages/rsc-runtime/README.md (ships in the npm tarball) says the same up front, and its Applications section spells out shared core vs projections and that only MCP consumes render. The npm description no longer claims "React Server Component primitives".

examples/audiobook-curator README gained an "Operation model" section showing the real <CuratorResult> JSX from src/result.tsx; src/result.tsx and src/application.ts gained header comments naming which one holds the runtime JSX and which deliberately holds none.

Against the acceptance list: 1, 2, 3 and 5 are answered directly; 4 is answered with an explicit no.

Two claims that were wrong on the first pass

Both were caught against packages/rsc-runtime/src during review and corrected before merge:

• render is unconditionally required. RscOperationInput.render is not optional, so a CLI-only operation still has to declare one — a render-less defineOperation fails with TS2741: Property 'render' is missing. The first draft had grouped render with the optional MCP projection, which would have sent a CLI-only author into a type error while following the docs.
• lowerHookResult does not call caller-authored components. Unlike lowerMcpResult, lower-hook.ts resolves only the functions in the exported Hook object, so a Hook.Result tree returned from your own component throws Expected exactly one agent-hook-result root. The README's "does the same for hook results" now says so explicitly.

The cli.parse(argv) wording was also tightened: runRscCli passes the arguments after the command name, and cli.exitCode is returned to the entry rather than set on process by the runtime.

Pinned

docs/framework-mode.md and both READMEs were previously unpinned, so the new prose could drift the same way the old prose did. New packages/rsc-runtime/tests/docs-contract.test.ts builds the documented status operation and locks the three behavioural claims:

• the CLI projection writes exactly {"status":"ready"}\n — one line of JSON — and never invokes render (asserted with a render counter);
• the MCP projection lowers the same validated result into the documented CallToolResult;
• a multi-child Mcp.Text is rejected with mcp-text requires one text child, which is why the documented snippet uses a template literal.

Why this stays open

The "Suggested direction" bullet about reconsidering the name is only half done. The docs introduce non-implying terminology ("MCP result DSL"), but two things still assert React Server Components on the package's own surface:

• the package name @agent-bundle/rsc-runtime;
• the react-server-components keyword in packages/rsc-runtime/package.json, which now sits in the same file as a description that denies RSC.

#89 deliberately left both alone. The name is genuinely entangled with #78/#81, but note those track "agent-bundle is taken on npm" — not "the name implies a runtime we do not have", which is this issue's concern. The keyword is separable from any rename and is the cheapest thing to settle next.

Also unanswered in the docs: whether the package intends to become a real RSC renderer. The merged text answers the present tense only.

[ScriptedAlchemy]

Superseded by the explicit meta-framework implementation stack: #93 owns filesystem routes and generated registries, #95 owns request context/providers, #96 commits to a real RSC/Flight Agent Document renderer, #102 owns CLI/script projections, and #105 owns the browser Workbench. Those issues make the operation/JSX direction unambiguous and retain this issue as linked motivation rather than a competing implementation target.

[ScriptedAlchemy]

Closed-issue re-audit (G3) — VERIFIED as superseded. The #89 docs answered the five questions for the operation model; that model has since been replaced by the route model (#93/#96), and docs/framework-mode.md on origin/main now answers the same questions for the current contract ("JSX = rendering", one async default Server Component, Flight as an internal transport, defineOperation/createRscMcpServer/runRscCli as compatibility escape hatches that never render JSX). The naming half is resolved: the package is @agent-bundle/runtime (#139), its description says "streaming React Flight dispatch", and the react-server-components keyword is gone (#106). No stale "no RSC renderer is involved" claim survives in docs/, README.md, or packages/rsc-runtime/README.md.