@octanejs/mcp-server 0.2.3 → 0.2.6

package/README.md

@@ -5,9 +5,10 @@ MCP server for agents working with [Octane](https://github.com/octanejs/octane).
 It serves two audiences:
 
 - **Octane users** (any project): skills and tools for bridging React packages
-  to Octane, migrating React components to `.tsrx`, understanding Octane's
-  intentional divergences from React, and setting up SSR. These work anywhere;
-  the skills ship inside this package.
+  to Octane, engineering production-grade applications and libraries, migrating
+  React components to `.tsrx`, understanding Octane's intentional divergences
+  from React, and setting up SSR. These work anywhere; the skills ship inside
+  this package.
 - **Octane maintainers** (the octane monorepo): repo triage, validation
   planning, benchmark and React-test-port automation. These tools register
   only when the server detects an octane monorepo checkout at its root.
@@ -56,20 +57,50 @@ maintainer tools):
 
 ## Tools (always available)
 
+The server initialization instructions direct coding agents to call
+`octane_engineering_plan` and load `build-octane-software` before creating or
+materially changing Octane code. This makes the correctness, performance
+evidence, adversarial self-review, and handoff requirements available even when
+the host does not automatically discover skills.
+
+### `octane_engineering_plan`
+
+Returns structured engineering gates for application, library, or
+framework-core work. Framework-core plans always require hot-path analysis,
+comparable baseline/candidate performance evidence, the maintainer core and
+performance skills, a second review of the final diff, and explicit residual
+risk reporting. In repo mode, the response also includes validation commands for
+the supplied paths. A framework-core request outside repo mode returns a blocking
+condition directing the client to configure `OCTANE_REPO_ROOT`, because the
+required maintainer skills and repository validation are otherwise unavailable.
+
+```json
+{
+  "scope": "framework-core",
+  "changeKind": "performance",
+  "paths": ["packages/octane/src/runtime.ts"]
+}
+```
+
 ### `octane_bridge_react_package`
 
 Scans a React package (by name from `node_modules`, or any source directory by
 path) for React API usage and returns an Octane compatibility report: which
-APIs map one-to-one, which need rewrites (`forwardRef`, `useDebugValue`,
-`lazy`, class components, synthetic `onChange`), whether a framework-agnostic
-core can be reused verbatim, whether an official `@octanejs/*` binding already
-exists, an overall verdict (`bridgeable`, `bridgeable-with-rewrites`,
-`needs-rework`), and a step-by-step plan.
+APIs map one-to-one, which need rewrites (`forwardRef`, class components,
+synthetic `onChange`, `react-dom/server` imports), whether a
+framework-agnostic core can be reused verbatim, whether an official
+`@octanejs/*` binding already exists, an overall verdict (`bridgeable`,
+`bridgeable-with-rewrites`, `needs-rework`), and a step-by-step plan.
 
 ```json
 { "package": "jotai", "projectRoot": "/path/to/my-app" }
 ```
 
+The event scan is host-aware: it recommends `onInput` only for direct standard
+text-host wiring that appears to mean “every edit.” It leaves component callbacks,
+selects, checkboxes/radios, dynamic input types, and explicitly intentional native
+text commits alone.
+
 ### `octane_bindings`
 
 Returns the map of React packages with maintained `@octanejs/*` ports. The map
@@ -82,6 +113,8 @@ without registering its React-package mapping fails CI.
 Returns a skill by name. Bundled skills (shipped with this package):
 
 - `bridge-react-package` — the full workflow for porting a React library.
+- `build-octane-software` — production engineering, performance, validation,
+  and adversarial self-review gates for Octane code.
 - `migrate-react-component` — React JSX to `.tsrx` conversion reference.
 - `react-divergences` — Octane's intentional differences from React.
 - `setup-ssr` — server rendering and hydration setup.
@@ -101,11 +134,14 @@ invariants, and validation commands.
 ### `octane_triage_paths`
 
 Classifies repository-relative paths by Octane area (compiler, core runtime,
-SSR, ecosystem binding, mcp-server, benchmark, docs, RuleSync source).
+SSR, ecosystem binding, vite-plugin, deploy adapter, evals, website,
+mcp-server, benchmark, docs, RuleSync source).
 
 ### `octane_validate_plan`
 
-Recommends validation commands for changed paths and task kind.
+Recommends validation commands for changed paths and task kind. Core task plans
+include the quick benchmark ratio gate in addition to core tests, typechecking,
+and repository-wide formatting.
 
 ### `octane_scaffold_react_port`
 
@@ -114,8 +150,13 @@ optionally writes the generated Vitest skeleton to an output file.
 
 ### `octane_benchmark`
 
-Runs a known benchmark workspace (`news`, `js-framework`, `recursive-context`,
-`signal-favoring`, `dbmon`) or all benchmarks.
+Runs benchmark suites through the unified runner (`node benchmarks/bench.mjs`):
+one manifest suite by name (`js-framework`, `todomvc`, `weather-app`,
+`weather-app-lighthouse`, `chat-stream`, `dbmon`, `news`, `react-hosted-islands`,
+`ssr-throughput`, `streaming-ssr`,
+`codegen-size`, `bundle-size`, `three-renderer`, `three-bundle-size`, …) or every
+suite with `all`; `quick` selects the reduced-iteration smoke pass. The suite
+list mirrors the runner manifest and `node benchmarks/bench.mjs --list`.
 
 ### `octane_issue_context`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/mcp-server",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -28,7 +28,8 @@
     "octane-mcp-server": "src/index.js"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./bridge": "./src/bridge.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.21.0",

package/skills/bridge-react-package.md

@@ -12,20 +12,36 @@ of bridging by hand:
 | `zustand` | `@octanejs/zustand` |
 | `jotai` | `@octanejs/jotai` |
 | `@apollo/client` | `@octanejs/apollo-client` |
+| `@tanstack/ai-react` | `@octanejs/tanstack-ai` |
+| `@tanstack/react-form` | `@octanejs/tanstack-form` |
 | `@tanstack/react-query` | `@octanejs/tanstack-query` |
 | `@tanstack/react-router` | `@octanejs/tanstack-router` |
+| `@tanstack/react-store` | `@octanejs/tanstack-store` |
 | `@tanstack/react-table` | `@octanejs/tanstack-table` |
 | `@tanstack/react-virtual` | `@octanejs/tanstack-virtual` |
 | `framer-motion` / `motion` | `@octanejs/motion` |
 | `@stylexjs/stylex` | `@octanejs/stylex` |
+| `styled-components` | `@octanejs/styled-components` |
 | `react-router` / `react-router-dom` | `@octanejs/remix-router` |
 | `@lexical/react` | `@octanejs/lexical` |
 | `lucide-react` | `@octanejs/lucide` |
 | `@floating-ui/react` | `@octanejs/floating-ui` |
 | `radix-ui` | `@octanejs/radix` |
 | `react-i18next` | `@octanejs/i18next` |
-
-For anything else, run the `octane_bridge_react_package` tool to get a scan of the
+| `react-hook-form` | `@octanejs/hook-form` |
+| `@base-ui-components/react` | `@octanejs/base-ui` |
+| `@dnd-kit/react` | `@octanejs/dnd-kit` |
+| `sonner` | `@octanejs/sonner` |
+| `recharts` | `@octanejs/recharts` |
+| `@react-three/fiber` | `@octanejs/three` |
+| `@visx/*` | `@octanejs/visx` |
+| `react-redux` | `@octanejs/redux` |
+| `@reduxjs/toolkit` | `@octanejs/redux-toolkit` |
+| `@testing-library/react` | `@octanejs/testing-library` |
+| `@mdx-js/react` | `@octanejs/mdx` |
+
+The `octane_bindings` tool returns the same map machine-readably. For anything
+else, run the `octane_bridge_react_package` tool to get a scan of the
 package's React API usage and a tailored plan, then follow the workflow below.
 
 ## Mental model
@@ -60,23 +76,25 @@ So a bridge never means "run the React package unchanged". It means:
    `useCallback`, `useRef`, `useContext`, `useId`, `useImperativeHandle`,
    `useSyncExternalStore` (full React 19 shape, including `getServerSnapshot`),
    `useTransition`, `useDeferredValue`, `useActionState`, `useOptimistic`,
-   `useEffectEvent`, `use`, `startTransition`, `memo`, `createContext`,
-   `Suspense`, `createPortal`, `flushSync`, `createRoot`, `hydrateRoot`.
-   Everything imports from `octane` (no separate `react-dom`).
+   `useEffectEvent`, `useDebugValue` (accepted no-op), `use`, `startTransition`,
+   `memo`, `lazy` (also accepts a bare component from the loader),
+   `createContext`, `Suspense`, `createPortal`, `flushSync`, `createRoot`,
+   `hydrateRoot`. Everything imports from `octane` (no separate `react-dom`);
+   server rendering imports from `octane/server`, including the streaming
+   `renderToPipeableStream`/`renderToReadableStream`.
 
 3. **Handle the gaps:**
    - `forwardRef`: does not exist. Accept `ref` as a normal prop (React 19
      style) and drop the wrapper.
-   - `useDebugValue`: shim as a no-op.
-   - `lazy`: use dynamic `import()` plus `use()` inside a `Suspense` boundary.
    - Class components: rewrite as function components. Error boundary classes
      become `<ErrorBoundary>` or the `@try { } @catch (e) { }` directive.
-   - Synthetic `onChange` on text inputs: use native `onInput`. Octane events
-     are native and delegated.
-   - Controlled inputs: Octane inputs are uncontrolled and native; `value` and
-     `checked` are plain attributes. Port controlled-input logic to
-     read-from-DOM plus explicit writes, or keep state in the store and write
-     the attribute on change.
+   - Synthetic `onChange` on standard text hosts: use native `onInput` when the
+     callback means every edit. Octane events are native and delegated.
+     Controlled `value`/`checked` follow React's semantics (the prop drives the
+     DOM property and reasserts on commits), so per-edit controlled-input logic
+     ports unchanged apart from the event name. Do not blanket-rewrite public
+     callbacks, selects, or checkbox/radio handlers. A deliberate uncontrolled
+     text commit may keep `onChange` with `suppressNativeChangeWarning`.
    - StrictMode double-invoke: does not exist; delete test expectations that
      count double renders.
 
@@ -118,7 +136,7 @@ So a bridge never means "run the React package unchanged". It means:
 
 - `bridgeable`: only same-name hooks used; a mechanical rename of imports to
   `octane` plus a `.tsrx` re-author of components is enough.
-- `bridgeable-with-rewrites`: needs the `forwardRef` / `useDebugValue` / `lazy` /
-  event rewrites above, but no architectural blockers.
-- `needs-rework`: class components, `renderToPipeableStream`, `findDOMNode`, or
-  React internals. Bridge the core, redesign the binding.
+- `bridgeable-with-rewrites`: needs the `forwardRef` / event / `react-dom/server`
+  import rewrites above, but no architectural blockers.
+- `needs-rework`: class components, `findDOMNode`, or React internals. Bridge
+  the core, redesign the binding.

package/skills/build-octane-software.md

@@ -0,0 +1,69 @@
+# Skill: Build production-grade Octane software
+
+Use this before creating or materially changing an Octane application, component,
+library binding, or framework integration. It is the quality baseline for work
+performed with Octane's MCP tools; task-specific skills add syntax and migration
+details but do not replace these gates.
+
+## Start with the contract
+
+1. State the user-visible behavior, inputs, failure states, accessibility needs,
+   and server/hydration expectations before choosing components or hooks.
+2. Inspect the current project conventions, package versions, compiler/Vite
+   configuration, existing tests, and official `@octanejs/*` bindings. Do not
+   invent an API that current sources do not expose.
+3. Identify the important user journey and its likely performance budget: initial
+   JavaScript, render/hydration work, interaction latency, network/data work, and
+   memory lifetime.
+
+## Design for Octane's performance model
+
+- Keep stable work outside reactive updates. Avoid state that can be derived,
+  effects that only mirror state, and subscriptions broader than the component
+  needs.
+- Use keyed `@for` blocks for dynamic collections with stable domain keys. Keep
+  item components focused so an item update does not rebuild unrelated work.
+- Prefer the platform and Octane's compiled directives over runtime abstraction
+  layers. Do not import React runtime packages or ship React-created JSX trees.
+- Keep expensive parsing, sorting, formatting, and object construction off common
+  render paths; memoize only when the avoided work and invalidation rules justify
+  the retained state.
+- Use native event semantics. `onInput` is the per-edit event for text controls;
+  do not add synthetic `onChange` compatibility or event wrapper allocation.
+- For SSR, avoid client/server data divergence and duplicate fetches. Exercise
+  hydration with production-compiled output and preserve abort/error behavior.
+- Treat bundle size and dependency cost as performance. Check for an official
+  binding before adding a compatibility layer or a second framework runtime.
+
+## Validate behavior and performance
+
+- Test realistic public behavior: rendered output, native events, focus,
+  accessibility state, errors, loading, cleanup, and hydration when used.
+- Include empty, loading, error, repeated-interaction, and large-data cases that
+  can expose stale state, duplicate work, or unbounded retention.
+- Use a production build for final validation. Measure the important user journey
+  before and after performance-sensitive changes under comparable conditions.
+- Do not claim that code is faster because it is shorter, uses memoization, or
+  causes fewer apparent renders. Report measured results and the command or
+  procedure that produced them; call inconclusive measurements inconclusive.
+
+## Adversarial self-review
+
+Before handoff, reread the complete diff and try to reject it:
+
+1. Can a simpler design preserve the contract with less state, indirection, or
+   retained data?
+2. What happens for empty, large, rapid, nested, failing, aborted, and unmounted
+   cases?
+3. Are effects cleaned up, async results made stale safely, and subscriptions
+   scoped to their consumers?
+4. Does the same code work in development, production, SSR, and hydration modes
+   that the project supports?
+5. Did an optimization move work to startup, the server, garbage collection, or
+   another component rather than remove it?
+6. Are accessibility, security, diagnostics, and maintainability at least as
+   strong as before?
+
+Fix findings, rerun the relevant checks, and review the final diff again. Report
+validation, measured performance evidence, improvements made during self-review,
+and any residual risk. Never hide an unverified path behind “all tests pass.”

package/skills/migrate-react-component.md

@@ -42,11 +42,11 @@ locals, early returns) stays above it.
 | `<Suspense fallback={...}>` | `<Suspense>` or `@try { } @pending { }` |
 | Error boundary class | `<ErrorBoundary>` or `@try { } @catch (e) { }` |
 | `forwardRef((props, ref) => ...)` | plain function; `ref` arrives as a prop |
-| `<input onChange={...}>` | `<input onInput={...}>` (native event) |
-| controlled `value={state}` | uncontrolled; `value` is a plain attribute, read the DOM in handlers |
+| text `<input onChange={...}>` meaning every edit | `<input onInput={...}>` (native event) |
+| controlled `value={state}` | keep it — React's controlled semantics apply; pair with `onInput` |
 | `className={clsx(...)}` | `class={[...]}` composes clsx-style natively |
-| `useDebugValue(x)` | delete it |
-| `React.lazy(() => import(...))` | dynamic `import()` + `use()` under Suspense |
+| `useDebugValue(x)` | keep or delete — present as an accepted no-op |
+| `React.lazy(() => import(...))` | `lazy()` works as-is (and also accepts a bare component from the loader) |
 | `defaultProps` | parameter defaults / destructuring defaults |
 
 ## Text holes
@@ -64,8 +64,12 @@ treated as a renderable (component, element, coerced primitive).
 ## Hooks
 
 The hook API matches React, and there are no rules of hooks: a hook may sit
-behind a condition, after an early return, or in a loop, because identity comes
-from the call site, not call order.
+behind a condition or after an early return, because identity comes from the
+call site, not call order. The one exception is a plain JS loop — a slot-keyed
+hook there is a compile error (every iteration would share one call-site slot);
+use the keyed `@for` directive or extract a child component. Dependency arrays
+may be omitted: the compiler infers them from lexical captures (explicit arrays
+keep React's exact behavior; `null` means every render).
 
 ```tsx
 export function Panel(props) @{
@@ -92,6 +96,20 @@ Events are native, delegated DOM events. `onClick`, `onInput`, `onSubmit`,
 `onKeyDown` behave exactly like the platform. `onChange` on a text input fires
 on commit (native change), not per keystroke.
 
+`OCTANE_NATIVE_TEXT_ONCHANGE` reports likely React-style text-host wiring. Its
+phase-preserving fixes are `onInput` and `onInputCapture`; it does not rewrite the
+event. Keep component/library callbacks named `onChange`, and keep native change on
+select and checkbox/radio hosts. If an uncontrolled text field intentionally saves
+only on commit/blur, keep `onChange` and add the non-serialized host hint:
+
+```tsx
+<input
+	defaultValue={draft}
+	onChange={(event) => save(event.currentTarget.value)}
+	suppressNativeChangeWarning
+/>
+```
+
 ## Refs
 
 React 19 style. `ref={cb}` with optional cleanup return, `ref={refObject}`, or

package/skills/react-divergences.md

@@ -3,17 +3,50 @@
 Use this when behavior differs from React and you need to decide whether it is a
 bug or by design. Do not "fix" these toward React.
 
-## No rules of hooks
+## No rules of hooks — except plain JS loops
 
 Hooks are tracked by compiler-assigned call-site slot, not call order. A hook may
-sit behind a condition, after an early return, or in a loop. Code that relies on
-hook-order errors firing does not apply.
+sit behind a condition or after an early return; code that relies on hook-order
+errors firing does not apply. The one restriction: a slot-keyed hook inside a
+plain JS loop is a **compile error** (every iteration would share the one
+call-site slot). Loop with the keyed `@for` template directive or extract a
+child component instead. `use()` and `useContext` are exempt (call-order /
+context-identity keyed, not slot-keyed).
 
-## No controlled components, no synthetic onChange
+## Dependency arrays are compiler-inferred when omitted
 
-`value` and `checked` are plain attributes; inputs are uncontrolled and native.
-There is no per-keystroke synthetic `onChange`; use native `onInput`. React's
-controlled-input value-reassertion model does not exist and must not be added.
+Omitting the array on `useEffect`, `useLayoutEffect`, `useInsertionEffect`,
+`useMemo`, `useCallback`, or `useImperativeHandle` does not mean "every render"
+— the compiler derives dependencies from lexical captures, omitting stable hook
+results (state setters/dispatchers, refs, state getters, `useEffectEvent`
+results). Locally declared custom hooks in full-compiled `.tsrx`/`.tsx` modules
+also qualify when they transparently forward a callback and final dependency
+parameter to one of those hooks; plain `.ts`/`.js`, imported/method, or
+transforming wrappers require an explicit list. Explicit arrays keep React's
+exact behavior and are never rewritten; `null` explicitly means run or
+recompute after every render.
+
+## State hooks expose a current-state getter
+
+`useState` and `useReducer` have a stable third tuple member
+(`[state, update, getState]`) that reads the latest scheduled hook-cell value.
+Ordinary two-item destructures keep the allocation-free React shape.
+
+## Controlled inputs match React — on native events
+
+Controlled `value`/`checked` follow React's semantics exactly: the prop drives
+the DOM property and reasserts on every commit and after discrete events;
+`defaultValue`/`defaultChecked` are the uncontrolled escape hatch. But there is
+no synthetic event layer: `onInput` is the per-keystroke handler for text
+controls, and native `change` fires on blur/commit. Do not add a synthetic
+`onChange` normalization.
+
+The compiler warning `OCTANE_NATIVE_TEXT_ONCHANGE` points out a statically known
+text host with `onChange`/`onChangeCapture` but no usable input handler; development
+runtime checking covers unresolved final props on uncontrolled text controls. This
+is migration guidance only. Deliberate native text commit behavior uses the
+non-serialized `suppressNativeChangeWarning` host hint. Selects, checkables, custom
+elements, and component callbacks remain quiet.
 
 ## Native delegated events
 
@@ -21,6 +54,16 @@ controlled-input value-reassertion model does not exist and must not be added.
 synthetic layer. Timing, bubbling, and `event.target` semantics match the
 platform, not React's wrapper.
 
+## Parallel `use()` — no suspense waterfalls
+
+The compiler unconditionally memoizes `use()`
+argument creations per call site, starts provably-independent fetches together,
+suspends once per stratum, and prefetches independent descendant fetch trees.
+React runs the same code as a serial waterfall — do not "fix" fetch-start
+timing, batch replay counts, or prefetch behavior toward React. True data
+dependencies stay sequential; unwrap order, hydration-seed order, and rejection
+routing match React.
+
 ## Keyed reconciler moves differ
 
 Reconciliation is LIS-based (minimal DOM moves), not React's `lastPlacedIndex`.
@@ -28,6 +71,20 @@ The final DOM and survivor node identity are guaranteed identical to React; the
 set of physically moved nodes is not. Tests asserting which nodes moved will
 diverge; tests asserting final order and identity will pass.
 
+## Synchronous first root mount and root API extensions
+
+The first `root.render()` mounts synchronously, so render-then-unmount in one
+outer batch can expose intermediate DOM that React's concurrent root elides.
+`root.render(App, props)` is supported alongside `root.render(<App />)`. A root
+whose managed DOM was externally removed unmounts safely instead of throwing
+the browser's incidental `NotFoundError`.
+
+## `lazy()` accepts bare components
+
+React's `{ default }` module shape works, and Octane additionally accepts a
+component directly from the loader. Suspense and ViewTransition are ordinary
+components, so wrapping them in `lazy()` is valid; nested lazy wrappers are not.
+
 ## class / className composes clsx-style
 
 Strings, numbers, arrays, objects, and nesting compose into a class string;
@@ -35,11 +92,10 @@ falsy parts drop out. React coerces an array to `"a,b"`; Octane yields `"a b"`.
 
 ## Not present at all
 
-- Class components.
+- Class components (rewrite as function components).
 - Server Components / `'use client'` / `'use server'`.
 - StrictMode double-invoke (renders and effects run once).
 - `forwardRef` (refs are props, React 19 style).
-- `useDebugValue` (shim as no-op).
 - SuspenseList, Profiler, findDOMNode.
 
 ## Everything else matches
@@ -47,4 +103,4 @@ falsy parts drop out. React coerces an array to `"a,b"`; Octane yields `"a b"`.
 Observable hook, effect, Suspense, and transition semantics match React,
 including effect ordering (child-first on mount, parent-first cleanup on
 deletion), `Object.is` state bailouts, batching, and `useId` stability across
-server render and hydration.
+server render and hydration. `useDebugValue` exists as an accepted no-op.

package/skills/setup-ssr.md

@@ -4,9 +4,11 @@ Use this when adding server-side rendering to an Octane app.
 
 ## The API
 
-The entry points mirror React: `octane/server` (`react-dom/server`) has
-`renderToString` (sync) and `renderToStaticMarkup`; `octane/static`
-(`react-dom/static`) has `prerender` (async, awaits Suspense data). All return
+The entry points mirror React. `octane/server` (`react-dom/server`) has
+`renderToString` (sync), `renderToStaticMarkup` (non-hydratable), and the two
+streaming renderers `renderToPipeableStream` (Node streams) and
+`renderToReadableStream` (web streams); `octane/static` (`react-dom/static`)
+has `prerender` (async, awaits Suspense data). The buffered renderers return
 `{ html, css }`.
 
 ```ts
@@ -28,9 +30,22 @@ const { html, css } = await prerender(App, props, {
   leaves `@pending` fallbacks in place; use `prerender` to await the data.
 - Options are optional: `nonce` stamps CSP nonces on the emitted inline tags (all
   renderers); `signal` aborts a suspended render with the request and `timeoutMs`
-  bounds how long a `use(thenable)` may take to settle (async `prerender`; global
+  bounds how long a `use(thenable)` may take to settle (async renders; global
   default via `setSsrSuspenseTimeout`); `onError` observes render errors.
 
+### Streaming
+
+`renderToPipeableStream(App, props?, options?)` returns `{ pipe, abort }`; the
+shell — the full page with `@pending` fallbacks for anything still suspended —
+flushes immediately, then each Suspense boundary streams out of order as a
+hidden segment plus an inline swap script when its data settles.
+`renderToReadableStream` is the same engine over web streams: it resolves with
+a `ReadableStream<Uint8Array>` once the shell is ready and rejects on a shell
+error; consume the stream concurrently rather than awaiting its `allReady`
+promise first. `StreamOptions` extends `RenderOptions` with `onShellReady()`,
+`onShellError(err)`, and `onAllReady()`. `hydrateRoot` adopts streamed-in DOM
+byte-for-byte, including per-boundary `use()` value or rejection seeds.
+
 On the client:
 
 ```ts
@@ -43,24 +58,35 @@ hydration-stable; the client adopts server DOM instead of rebuilding it.
 
 ## Two integration paths
 
-1. **Vite plugin (dev SSR + routing)**: `@octanejs/vite-plugin` matches routes
-   from `octane.config.ts`, renders pages into `index.html` at
-   `<!--ssr-head-->` / `<!--ssr-body-->`, and wires hydration automatically.
-   Production server output is not generated yet; for production SSR today use
-   path 2.
+1. **Vite plugin (routing + dev and production SSR)**: `@octanejs/vite-plugin`
+   matches routes from `octane.config.ts`, streams pages with
+   `renderToReadableStream()` into `index.html` around `<!--ssr-head-->` /
+   `<!--ssr-body-->`, and wires hydration automatically. In production,
+   `vite build` emits hashed client assets in `dist/client` plus a
+   self-contained SSR server at `dist/server/entry.js` (exports
+   `handler`/`nodeHandler`; preview with `octane-preview`);
+   `server.render: 'buffered'` switches it to the await-everything `prerender`.
+   A deploy adapter prepares the output for a host: `adapter: vercel()` from
+   `@octanejs/adapter-vercel` emits Vercel's Build Output API, while
+   `adapter: cloudflare()` from `@octanejs/adapter-cloudflare` emits a module
+   Worker at `dist/server/worker.js` for Workers Static Assets. Cloudflare apps
+   keep a user-owned `wrangler.jsonc` pointing `main` at that Worker and
+   `assets.directory` at `dist/client`, with `nodejs_compat` enabled. Leave
+   `assets.not_found_handling` unset or `"none"` so navigation misses reach SSR.
 2. **Custom server**: write `entry-server.ts` exporting a function that calls
-   `prerender()` (or `renderToString()`) and splices the result into your HTML template, and
-   `entry-client.ts` calling `hydrateRoot`. Serialize app data (for example a
-   dehydrated query-client cache) into your own inline JSON script and read it
-   before hydrating.
+   `prerender()` (or `renderToString()`, or a streaming renderer) and splices
+   the result into your HTML template, and `entry-client.ts` calling
+   `hydrateRoot`. Serialize app data (for example a dehydrated query-client
+   cache) into your own inline JSON script and read it before hydrating.
 
 ## Data and Suspense on the server
 
 `use(promise)` suspends a pass; `prerender()` awaits it and re-renders, so
 `@try { } @pending { }` boundaries resolve to their success arm in the emitted
-HTML. Resolved values serialize into the seed script and hydration consumes
-them without re-fetching. For query-style data, prefetch into a cache before
-rendering and dehydrate it yourself.
+HTML, while the streaming renderers flush the fallback in the shell and stream
+the resolved boundary behind it. Resolved values serialize into the seed script
+and hydration consumes them without re-fetching. For query-style data, prefetch
+into a cache before rendering and dehydrate it yourself.
 
 ## Constraints to remember
 
@@ -68,6 +94,11 @@ rendering and dehydrate it yourself.
   `useSyncExternalStore` uses `getServerSnapshot`.
 - Server components must be compiled by the Octane compiler in server mode;
   you cannot feed client-compiled output to the renderers.
-- Output is buffered, not streamed: send it as one response.
+- Hydration adopts the whole tree in one synchronous pass (no selective or
+  progressive hydration), and head elements hoisted from inside a streamed
+  Suspense boundary are re-created on hydration rather than shipped in the
+  stream.
 - Render errors reject the promise unless an `ErrorBoundary`/`@catch` inside
   the tree handles them; map rejections to HTTP status codes in your server.
+  With streaming, a recoverable error inside Suspense content keeps the emitted
+  fallback and marks only that boundary for client rendering.