@thomas.f/prnext 0.1.17-alpha → 0.1.19-alpha

package/docs/ai/compatibility.md

@@ -18,12 +18,181 @@ transpilation, image/font tooling and caching deserve targeted build and browser
 tests. Support for one configuration shape does not imply support for all
 upstream plugin behavior.
 
+## Instrumentation and tracing
+
+Use a single `instrumentation.ts`, `.js`, `.mjs` or `.cjs` at the project root
+or in `src`. Export an optional async `register()` for runtime initialization
+and an optional async `onRequestError(error, request, context)` for reporting.
+The `Instrumentation.onRequestError` type is exported from PRNext's root API.
+`process.env.NEXT_RUNTIME` distinguishes `nodejs` and `edge`; conditional imports
+keep Node SDKs out of an Edge bundle. Registration runs once per server realm,
+including the separate RSC realm, before application requests. A production
+prerender does not run the runtime startup hook. Request-time ISR and PPR
+regeneration initialize their server realm and report failures through the same
+hooks. Repeated propagation of an RSC error to the HTML worker does not report
+the same error again.
+
+```ts
+import type { Instrumentation } from '@thomas.f/prnext'
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./observability.node')
+  }
+}
+
+export const onRequestError: Instrumentation.onRequestError = async (
+  error, request, context
+) => {
+  await reportError(error, request, context)
+}
+```
+
+`reportError` above is an application function, not a PRNext API. Initialization
+has a 30-second budget. Each error hook has a five-second budget; reporting
+failure does not replace the application failure. Redirect/not-found control
+signals are excluded. Hooks receive request information: the application owns
+redaction before sending that information to a third party.
+
+For built-in correlated traces, explicitly set
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to an OTLP HTTP collector's complete traces
+URL and `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json`. Alternatively,
+`OTEL_EXPORTER_OTLP_ENDPOINT` supplies a base URL with `/v1/traces` appended.
+`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS` (or general
+`OTEL_EXPORTER_OTLP_HEADERS`) and `OTEL_SDK_DISABLED=true` are supported. Keep
+exporter credentials in the server environment. This built-in path supports
+HTTP JSON, not gRPC or HTTP protobuf; use your own SDK for other protocols.
+
+Native HTTP spans cover static and dynamic responses through body completion
+or cancellation. Node, RSC and fetch spans share W3C trace context. Export queues
+are bounded and telemetry is best effort; an unavailable collector does not
+block a site response. Built-in span attributes exclude bodies, cookie values,
+query strings and authorization headers. An application-installed
+`@opentelemetry/api` can use the same parent context when its SDK installs a
+context manager in `register`. No SDK is installed automatically, and this does
+not certify every vendor integration.
+
+## Production bytes and navigation
+
+Production CSS Modules use deterministic compact class and animation names.
+Global classes and declared composition exports retain their meaning; development
+keeps readable names. Internal JavaScript exports are shortened by the selected
+compiler, while public exports and dynamic imports keep their interfaces. Asset
+hashes and source maps remain compiler-owned.
+
+App navigation can negotiate binary differential Flight responses. Every request
+still runs fresh rendering and access checks. The server retains at most 64
+completed bases, 32 MiB in total, with a two-MiB per-base limit and 30-second
+expiry. Bases are keyed by deployment and credentials; an unknown, expired or
+incompatible base produces ordinary Flight. The browser retains one completed
+base, streams reconstructed bytes to React and can retry one failed differential
+navigation as a full GET. Server Actions are never replayed through this path.
+Per worker, at most eight captures and two encoders run together. Additional
+requests use ordinary Flight, keeping transient transport work bounded too.
+
 Configuration uses one `next.config.*` or `prnext.config.*` file and rejects
-unknown keys rather than ignoring them. `reactCompiler: false` is accepted;
-enabling React Compiler is explicitly unsupported. `typedRoutes: true` is
+unknown keys rather than ignoring them. React Compiler is available through an
+explicit `reactCompiler` option described below. `typedRoutes: true` is
 implemented through PRNext's generated route registry. Do not copy a full
 Next.js configuration template into a new application.
 
+The repository's reference tests build and run matching applications against
+Next.js 16.4.3, including mounted App navigation, form Actions and cookies,
+metadata, Pages locale routing, redirects, APIs and selected webpack loader
+contracts. These executable examples cover specific behavior; they do not
+certify every Next.js application or plugin. `NextRequest.nextUrl` understands
+data-route build IDs and locales, and request-cookie mutations synchronize the
+request header. Request cookies have different mutation results from response
+cookies; do not use them interchangeably.
+
+A locked real-application fixture additionally exercises Better Auth 1.7.14
+(email/password, session cookies and logout), Drizzle ORM 0.45.4 over SQLite
+through its proxy driver, next-intl 4.14.9 (server and client translations),
+and the MDX 3.1.1 webpack loader against Next.js 16.4.3. It covers authenticated
+Server Actions, user-owned rows, cookie/locale isolation, client navigation and
+Server Component `after()` callbacks. This is evidence for those workflows,
+not a guarantee for every plugin, provider or deployment configuration.
+
+PRNext-specific options such as `prerender` and `htmlOnly` are described in
+[Build and deployment](deployment.md). Do not pass them to an upstream Next.js
+build when comparing the two implementations.
+
+## TypeScript 7 and earlier compilers
+
+PRNext uses the application's installed TypeScript. TypeScript 7 runs through its
+official native `tsc` command for production checks, `prnext typecheck` and live
+development diagnostics. Install TypeScript normally, including its platform
+optional dependencies. PRNext does not download a compiler during a build.
+TypeScript 5 and 6 retain their compiler API integration.
+
+Checks use `--noEmit` and keep incremental compiler state in an owned temporary
+directory. Development reports updated errors and clears fixed diagnostics;
+new source files and configuration changes restart the native watch generation.
+`typedRoutes` also supports native TypeScript and preserves JSONC comments when
+adding its generated declaration to the config. Compiler support does not imply
+that every application is ready for TypeScript 7's own language/config changes.
+
+## React Compiler
+
+Enable the bundled official React Compiler in the project's existing config:
+
+```js
+export default {
+  reactCompiler: true,
+};
+```
+
+No separate compiler installation is required. The default is disabled;
+`reactCompiler: false` preserves the uncompiled component path. Enabled builds
+optimize project-owned browser components in both Pages and App applications,
+in development and production. App Client Components also use the transform in
+their isolated server-rendering graph. The Pages server graph stays uncompiled,
+including APIs, custom Document code and data-loader utilities, so ordinary
+server functions never acquire client-only memoization hooks. React Server
+Components, Server Action modules, PRNext internals, generated entrypoints and
+npm packages are not compiled. Keep the matching React 19 peer versions required
+by the installed framework.
+
+Ordinary `.mts`/`.cts` hook helpers can be optimized; server/client directives
+in those extensions remain unsupported. Decorated `.mts`/`.cts` utility modules
+keep their native compilation path while importing React components can still
+be optimized.
+
+For gradual adoption, use `reactCompiler: { compilationMode: 'annotation' }`, then
+put `"use memo";` at the beginning of each component or hook to optimize. In
+either mode, `"use no memo";` excludes an individual function. Supported object
+options are `compilationMode: 'infer' | 'annotation'`,
+`panicThreshold: 'none' | 'critical_errors' | 'all_errors'` and `target: '19'`.
+Defaults are `'infer'`, `'none'` and `'19'`; other fields are rejected.
+
+After a successful build, inspect the compiler's actual results:
+
+```sh
+prnext compiler
+prnext compiler --json
+```
+
+The report names observed functions, their project-relative files, optimization
+or skip status, and the compiler's reasons. These are transform decisions;
+server-code removal and tree shaking can later omit a function from the browser
+bundle. Cached transforms retain their
+diagnostics and are identified as reused. Browser and server graphs do not
+inflate the function count. An incremental build can reuse graph inputs without
+observing every transform; the report states that scope rather than claiming
+complete application coverage. Disabled compilation is reported explicitly.
+The report describes the last successful build, stays outside public assets and
+does not include source code. A failed build preserves the previous report.
+
+The compiler can skip code that cannot be safely optimized. Follow the Rules of
+React and check actual behavior rather than assuming every component was
+compiled. It reduces repeated component work; it does not guarantee faster
+server responses, smaller JavaScript or a specific speed multiplier. Validate
+hydration, interactions and Fast Refresh in the application, then compare a
+production build with the option enabled and disabled. Compilation adds build
+work; PRNext caches pure transforms with their compiler version and settings.
+
+See the [official React Compiler documentation](https://react.dev/learn/react-compiler).
+
 Only explicit private Next.js import adapters are supported. Do not add arbitrary
 `next/dist/...` imports or install another Next runtime to satisfy one: isolate
 or replace the incompatible dependency, retain the original framework where
@@ -67,6 +236,29 @@ by silently adding `--force` or `--legacy-peer-deps`.
 can run project code, and installed custom loaders still require a real build.
 The audit is not a sandbox for untrusted projects.
 
+The version 2 JSON report follows static imports from project sources into the
+installed packages they reference. It checks explicit PRNext adapters and their
+statically declared named exports, and includes the importing file, line and
+import chain when a dependency uses an unavailable API. It resolves selected
+Node, browser and React Server Component package conditions, including workspace
+symlinks, without importing those package modules. Unreferenced packages are not
+enumerated. Runtime branches, custom loader output and every possible bundler
+condition remain outside this check.
+
+A module-level `use server` directive is a server boundary even when a Client
+Component reaches it through a re-export. Its dependencies are still audited in
+the server context. A client dependency on a Node builtin needs an actual browser
+implementation; package `browser` mappings and installed shims are resolved
+before diagnosing it. Custom configuration aliases still require a build with
+that application's configuration.
+
+`evidence.state: "checked"` means the selected static graph was inspected, not
+that migration is certified. `"unknown"` identifies unresolved/computed imports,
+loader inputs or incomplete coverage. The graph is bounded to 2,000 modules,
+12,000 imports, 32 MiB of source reads and 32 import hops. Hitting a limit leaves
+the remaining coverage unknown. `ok` means no blocking diagnostic was found;
+inspect warnings and coverage even when it is true.
+
 ## Compare running applications
 
 Start the original application and the candidate on separate available ports.
@@ -89,6 +281,60 @@ in a real browser, test authorized and unauthorized states, and run the existing
 application tests. Keep the original setup available until the candidate is
 actually verified. Timings from this comparison are not controlled benchmarks.
 
+## Run application browser scenarios
+
+An explicit browser option can run the application's own assertions against
+each server. Install Playwright and its Chromium browser in the application
+using its normal development setup; PRNext never installs them for this check.
+Provide a trusted `.mjs`, `.cjs` or `.js` module inside the application directory:
+
+```js
+// migration.scenarios.mjs
+export default [
+  {
+    async run({page, baseURL}) {
+      await page.goto(`${baseURL}/sign-in`);
+      await page.getByLabel('Email').fill(process.env.MIGRATION_TEST_EMAIL);
+      await page.getByLabel('Password').fill(process.env.MIGRATION_TEST_PASSWORD);
+      await page.getByRole('button', {name: 'Sign in', exact: true}).click();
+      await page.getByRole('heading', {name: 'Dashboard', exact: true}).waitFor();
+      await page.getByRole('button', {name: 'Save note', exact: true}).click();
+      await page.getByText('Note saved', {exact: true}).waitFor();
+      await page.getByRole('button', {name: 'Sign out', exact: true}).click();
+      await page.getByRole('heading', {name: 'Sign in', exact: true}).waitFor();
+    },
+  },
+];
+```
+
+Replace the URLs and accessible names with the application's real controls.
+Supply dedicated test account values through the command's environment rather than
+command arguments or source files. Use isolated test databases: these explicit
+callbacks execute application code and can submit forms or mutate data.
+
+```sh
+prnext migrate --check --against http://localhost:3000 --candidate http://localhost:3001 --routes paths.json --browser-scenarios migration.scenarios.mjs --timeout 15000 --json
+```
+
+Only this option loads the scenario module and starts a browser. It requires
+the application's installed `playwright` or `@playwright/test`. Each callback
+receives a new isolated browser context for each target. Assert observable
+behavior inside the callback; its return value is ignored. A callback that
+fulfills passes for that target, and a thrown assertion fails. Both targets
+must pass independently; equal durations or response samples are not used to
+infer browser equivalence.
+
+The report records scenario numbers, targets and pass/fail results. It excludes
+application console output, raw error messages, request data, cookies and
+screenshots. Read or debug the original application test separately when a
+generic failure needs investigation. Keep credentials out of assertion labels
+and application-managed artifacts too. An unavailable browser or incomplete run
+is reported as unknown. There are at most 20 scenarios, a 100–60,000 ms budget
+per callback, a bounded startup period and a five-minute maximum for the worker.
+A timeout closes its context and ends the run before another target starts.
+The worker also closes its owned browser when it finishes. This is explicit
+execution of trusted test code, not a sandbox for an untrusted module.
+
 ## Boundaries that often matter
 
 React server/client directives in `.mts`/`.cts` are rejected; use `.ts`/`.tsx`.

package/docs/ai/data.md

@@ -114,13 +114,173 @@ enable them to silence a request-context error or assume their complete upstream
 behavior. Keep a working `unstable_cache` or fetch solution unless the project
 needs a different model.
 
+## Navigation stages
+
+Enable `cacheComponents: true` and `partialPrefetching: true` to separate runtime
+App Shell work from per-link prefetch work and actual navigation work:
+
+```jsx
+import { Suspense } from 'react';
+import { navigation, prefetch } from 'next/cache';
+
+async function Recommendations() {
+  await prefetch();
+  return <div>{await getCachedRecommendations()}</div>;
+}
+
+async function ExpensiveReport() {
+  await navigation();
+  return <div>{await getCachedReport()}</div>;
+}
+
+export default function Page() {
+  return <>
+    <Suspense fallback={<p>Loading recommendations</p>}><Recommendations /></Suspense>
+    <Suspense fallback={<p>Loading report</p>}><ExpensiveReport /></Suspense>
+  </>;
+}
+```
+
+Define and authorize the application-specific data functions above. Call gates
+before invoking a cached function, never inside its cached scope. Both gates
+require Cache Components. Static prerenders continue through them, so static
+output can already contain the result. Without partial prefetching, `prefetch()`
+has no effect and an explicit `Link prefetch={true}` requests the full route.
+
+A default Link requests the shell. `prefetch={true}` permits per-link work;
+content below `navigation()` waits for the navigation. Runtime previews are
+private, size-bounded and tied to the request's authorization identity. They do
+not authorize a subsequent navigation.
+Uncached runtime fetches and `connection()` remain deferred during speculative
+rendering. Put reusable I/O in a cached function to make it eligible for an
+earlier stage; a gate does not itself cache data.
+
+Pages and layouts may export `ensureStatic = 'shell'`, `'prefetch'` or
+`'navigation'`. Earlier stages are included in stricter levels. A descendant
+cannot weaken a parent; `false` conflicts with a static requirement elsewhere
+in the route. `'auto'` adds no requirement. Client Component exports are rejected.
+`'shell'` and `'prefetch'` request static output for those stages without adding
+a separate full-route build check. `'navigation'` validates complete static
+server output during build and development, including request APIs beneath
+Suspense, metadata and complete dynamic parameter sets. It requires nonempty,
+complete `generateStaticParams()` results for dynamic routes. All levels require
+Cache Components; shell/prefetch levels need partial prefetching to select stages.
+
+## Shared Redis Cache Components
+
+The optional first-party Redis handler shares `'use cache'` results across Node
+processes. Install `@redis/client@^6.3.0` only in applications using it; a normal PRNext
+installation and generated project do not require Redis.
+
+### `redis-handler.mjs`
+
+```js
+import { createRedisCache } from '@thomas.f/prnext/cache/redis';
+
+export default createRedisCache({
+  namespace: 'my-app-production-v1',
+  urlEnv: 'REDIS_URL',
+});
+```
+
+### `prnext.config.mjs`
+
+```js
+export default {
+  cacheComponents: true,
+  cacheHandlers: { remote: './redis-handler.mjs' },
+};
+```
+
+### `app/catalog/read.ts`
+
+```ts
+import { cacheLife, cacheTag } from 'next/cache';
+
+export async function readCatalog() {
+  'use cache: remote';
+  cacheLife('hours');
+  cacheTag('catalog');
+  return [{ id: 'demo', name: 'Demo product' }];
+}
+```
+
+Set the Redis URL in the server's runtime environment. It is not embedded in the
+handler bundle. Replicas sharing results need the same namespace and compatible
+build output. Use separate namespaces for unrelated apps, environments and
+incompatible deployments. This factory handles Cache Components. The separate
+incremental factory below handles native HTML/ISR, fetch and `unstable_cache`.
+
+Cache fills use a bounded cross-process lease. Atomic tag generations prevent a
+fill invalidated while running, or an expired lease owner, from publishing old
+data. Soft tag invalidation retains stale-while-revalidate behavior; immediate
+expiration prevents another replica from reading the old entry. Losing the tag
+registry invalidates existing entries rather than resurrecting them.
+
+Values are limited to 2 MiB, metadata to 64 KiB and each entry to 256 tags.
+The tag registry is bounded; excess cardinality conservatively invalidates the
+namespace. Default retention is at most seven days. Defaults use a 30-second
+lease, a 2.5-second fill wait and one-second command timeout. Reads can fall back
+to fresh computation on cache failure; invalidation failures remain errors.
+Cached callbacks must be safe to execute more than once after timeout or outage:
+leases reduce duplicate work, not provide exactly-once business operations.
+
+An already connected node-redis client can be supplied as `client`; its lifecycle
+remains the application's responsibility. Otherwise the handler connects lazily
+and owns its client. Use Redis appropriate for the application's availability,
+access controls and data sensitivity; a shared cache is not an authorization
+boundary or a durable database.
+
+## Shared Redis pages and request data
+
+Configure `cacheHandler` with the constructor returned by the incremental factory:
+
+```js
+// incremental-redis.mjs
+import { createRedisIncrementalCache } from '@thomas.f/prnext/cache/redis';
+export default createRedisIncrementalCache({ namespace: 'my-app-production' });
+```
+
+```js
+// prnext.config.mjs
+export default {
+  cacheHandler: './incremental-redis.mjs',
+  cacheMaxMemorySize: 0,
+};
+```
+
+Set `REDIS_URL` at runtime and install the optional `@redis/client@^6.3.0` client.
+The same configuration works for App and Pages HTML/ISR, static Route Handlers,
+cacheable `fetch` and `unstable_cache`. It does not cache private dynamic pages.
+Replicas must use compatible builds and share an application-specific namespace.
+Cache Components still select their own `cacheHandlers`; both factories may use
+the same namespace to share tag invalidations.
+
+The runtime acquires a shared generation lease before rendering, checks for a
+winner's result after waiting and carries that lease through publication. An
+invalidation or expired lease rejects late writes atomically. Runtime reads and
+publication remain bounded; unavailable Redis can prevent a page regeneration
+from succeeding. A shared cache is not a durable database or an exactly-once
+execution mechanism. Keep producers safe to retry.
+
+Incremental entries preserve Buffer and Map values, have a 16 MiB serialized
+limit and use V8-major-specific keys. The default generation lease is 60 seconds;
+`leaseMs` can be configured up to 120 seconds. Configure it for the expected
+generation duration. The default maximum storage age remains seven days.
+New cacheHandler builds include a native generation-lease capability check;
+use the matching PRNext native binary and rebuild existing output.
+
 ## Background work and durable data
 
-`after()` from `next/server` is supported in Node Route Handlers and Server
-Actions. It runs tracked callbacks after the response completes or disconnects;
-it is not supported for Server Components or Edge lifecycles. Cookie reads are
-allowed in that retained context, but cookie writes and path/tag invalidation
-are rejected there. Invalidate before returning from the mutation.
+`after()` from `next/server` is supported in Node Server Components (including
+layouts and metadata), Route Handlers and Server Actions. It runs tracked
+callbacks after the response completes or disconnects; static renders execute
+them during the build. Edge lifecycles remain unsupported. In a Server Component,
+read request data before registering the callback and capture the needed values:
+`headers()`, `cookies()` and `draftMode()` inside that callback are rejected.
+Route Handler and Action callbacks can read their retained request context.
+Cookie writes and path/tag invalidation are rejected after the response;
+invalidate before returning from the mutation.
 
 Tracked callbacks are bounded by the route's `maxDuration` and shutdown
 deadlines; forced termination can interrupt them. Use an external durable queue

package/docs/ai/deployment.md

@@ -20,6 +20,22 @@ run `next start` on a PRNext build or hand-edit its manifests to bypass runtime
 compatibility checks. PRNext's native server handles HTTP while React rendering
 uses Node workers. Published native components must match the framework version.
 
+Each production artifact also has its own deployment identity, even when
+`generateBuildId` returns a constant. App navigation, Pages data and JavaScript
+Server Actions check this identity before decoding a response. A stale GET can
+fall back to a document navigation. A stale action fails without executing or
+automatically replaying the mutation; preserve the user's work and ask them to
+reload before retrying it explicitly.
+
+When rebuilding into the same output directory, PRNext can carry forward public
+hashed assets from two previous artifacts for up to one hour, within a 64 MiB
+budget. This does not retain old server code, HTML, data responses or sessions.
+It does not coordinate independent servers or a CDN: deploy matching artifacts
+and configure the proxy to preserve the deployment headers and cache variation.
+Use `deploymentRetention: false` to disable carry-over, or configure
+`deploymentRetention: { maxAge: 3600, maxGenerations: 2, maxBytes: 67108864 }`;
+`maxAge` is in seconds. A new output directory has no previous assets to retain.
+
 For an existing reverse proxy, bind the application to loopback and configure
 the proxy according to the deployment environment. Set required production
 environment variables and exercise a real health route before switching
@@ -35,6 +51,141 @@ relative files. Build for the target OS/architecture and retain compatible Node;
 a standalone bundle is not a universal executable. Read the shipped
 [build output contract](../../build/ADAPTERS.md) for artifact boundaries.
 
+## HTML rendering paths
+
+Buffered App HTML decodes UTF-8 chunks incrementally, avoiding a second aggregate
+binary copy. The existing 16 MiB response limit still applies, including to large
+chunks and multi-byte text.
+
+The default remains React's Web stream renderer. To evaluate the experimental
+Node pipeable renderer, set `PRNEXT_SSR_STREAM=node` in the server environment.
+It uses bounded backpressure and cancellation for ordinary Node App rendering.
+Partial/PPR continuations keep the Web API and their original resume state;
+Edge rendering is unchanged. Unset the variable to restore the default.
+This is a workload comparison option, not a promised performance multiplier:
+small-page CPU and larger-page timings can move in different directions.
+
+## Readiness and first-request latency
+
+`prnext start --prewarm` initializes the framework renderers before accepting
+HTTP requests. It warms one render host and its RSC isolate; additional hosts
+remain lazy. It does not call application pages, API handlers or data loaders.
+Normal instrumentation initialization still runs. Existing `workerPreload`
+configuration, if present, separately imports the application modules selected
+by that configuration. Prewarming failure prevents HTTP readiness.
+
+For a supervisor, add `--readiness-file /private/run/instance-ready.json`.
+Create its parent directory first, and use a separate path per application or
+independent instance. The atomically replaced JSON contains `ready`, `pid`,
+`address`, `generation`, and `render: 'prewarmed' | 'lazy'`. HTTP readiness alone
+does not mean a lazy React renderer is loaded. Replacement and shutdown
+coordinate through a private sidecar lock; normal shutdown removes only its
+own generation. A forced termination can leave a stale marker, so the supervisor
+must also verify the process identity and a real application health check.
+
+Idle retirement saves memory at the cost of the next render's wake latency.
+For an application that must keep its used hosts alive, explicitly pass
+`--worker-idle-seconds 0`. Prewarming is a startup operation, not periodic
+synthetic traffic, and does not silently disable retirement. Measure the first
+dynamic page as well as startup time; prewarming moves work earlier rather
+than eliminating all cold work.
+
+## Profiles under resource limits
+
+Balanced remains the default. On Linux, effective policies consider CPU quotas
+and memory ceilings at visible cgroup-v2 ancestors, as well as available CPUs.
+Speed uses a smaller nursery and admission/buffer budgets when limited to one
+CPU or at most 1 GiB memory. Balanced also lowers its budgets below 512 MiB.
+The native launcher passes its effective policy to the RSC isolate so both use
+the same resource decision. Explicit `NODE_OPTIONS` heap flags keep their precedence.
+
+Memory favors a smaller nursery and earlier idle retirement, without forcing
+V8's optimize-for-size policy. It can still trade CPU and latency for RAM.
+Classic preserves the historical policy. These settings are advisory budgets,
+not total RSS caps; use an OS/container limit for hard isolation. Explicit
+worker counts are not automatically increased to match the host CPU count.
+Compare throughput, CPU per correct response, p95 and memory together before
+choosing Speed or adding workers.
+
+## Production worker memory and recovery
+
+A production Node host can be drained when its RSS stays above an explicit soft
+budget for three one-second samples:
+
+```js
+export default { workerMemory: { maxRssMb: 512 } };
+```
+
+This is opt-in (64–65536 MiB), separate from the build's prerender budget. It
+observes process RSS, including rendering threads; it does not cap V8's heap or
+force garbage collection. Existing responses and tracked work finish on the old
+host while new work uses a replacement. At most two process generations per
+host group can overlap, including child reaping; further replacement waits for
+capacity. This is not an OS memory sandbox: a busy draining host can exceed the
+soft target. Serial maintenance workers check their budget after requests.
+Development keeps its existing worker behavior.
+
+Repeated failed Node starts and unexpected host exits use a shared startup
+cooldown, from 100 ms up to 30 seconds. A sustained healthy period of 60 seconds
+resets the circuit. Queued callers keep their original deadlines; no failed
+request, POST or Server Action is automatically replayed. Ordinary client
+cancellations and planned memory/idle retirements do not count as crashes.
+
+The private local data cache uses a versioned binary value transport when
+negotiated by the native worker launcher. Existing JSON clients remain accepted.
+Authentication, limits, leases, tag/path invalidation and cache policy are
+unchanged. This internal transport is not a public application API.
+
+## Production prerendering
+
+App and Pages static paths can render in separate Node processes during a
+production build. Path discovery runs once; results are published in a stable
+order. Small batches and `workers: 1` use the local renderer. Defaults account
+for available CPUs and memory. To set explicit ceilings:
+
+```js
+export default {
+  prerender: { workers: 4, maxMemoryMb: 2048 },
+};
+```
+
+`workers` accepts 1–8; `maxMemoryMb` accepts 256–16384 MiB and covers the sum of
+observed child-process RSS, including their rendering threads. This is a sampled
+admission budget, not an OS memory limit; it does not include the build
+coordinator. A path error or exhausted budget fails the build, stops pending
+work and closes the workers. Paths are not automatically retried: keep static
+data loaders free of mutations and independent of execution order.
+
+Build workers share a temporary, bounded cache for eligible App reads which the
+application explicitly elects to cache. It is discarded after the build and
+never uses the production cache. `no-store` requests and `Set-Cookie` responses
+are not coalesced. Authentication does not opt a read into caching; cached reads
+retain request-derived keys. Pages loaders retain their existing cache behavior.
+
+## Selected pages without browser JavaScript
+
+Use the PRNext-specific `htmlOnly` option for fully static, noninteractive App
+pages. Select registered route patterns exactly, or use a final `/**` subtree:
+
+```js
+export default {
+  htmlOnly: ['/about', '/articles/[slug]', '/manual/**'],
+};
+```
+
+Build validation requires Node App routes with complete static output. A
+dynamic pattern needs `dynamicParams = false` and a nonempty
+`generateStaticParams` result. Client Components, Server Actions, interactive
+`next/link`, scripts, ISR, PPR, `cacheComponents`, Edge and advanced parallel or
+intercepting routes are rejected for selected pages. Use ordinary `<a>` links.
+Unknown patterns fail the production build rather than silently doing nothing.
+
+HTML keeps CSS, fonts, metadata and resolved Suspense content. It has no
+bootstrap scripts or Flight payload; entering it performs document navigation.
+Unknown generated parameters return 404. The mode is enforced in production,
+including static export and standalone output; development retains its normal
+JavaScript tools. It is an explicit PRNext extension, not a Next.js config key.
+
 ## Static browser output
 
 PRNext can serve a plain HTML/CSS/JavaScript directory:
@@ -103,6 +254,13 @@ an explicit choice, not a reason to print credentials or copy `.env` into assets
 
 ## Observe before tuning
 
+Production rendering, API and regeneration admission use bounded queues grouped
+by resolved route pattern. Different parameter values share one pattern's
+waiting budget. Waiting patterns take turns as capacity becomes available;
+a single pattern can still use all execution slots. Excess requests receive
+503 with `Retry-After`; an expensive request already executing is not preempted.
+This limits backlog monopolization, not all CPU use or application-level quotas.
+
 Use `prnext start --inspect` and `prnext inspect --json` for sampled route/cache
 and runtime observations. `prnext analyze --json` describes built browser
 JavaScript; it is not an SSR latency measurement. A production profile can be

package/docs/ai/quickstart.md

@@ -19,11 +19,36 @@ dependencies enabled. Consumers do not need Rust; building PRNext from its sourc
 repository is a different workflow. Do not install a platform package separately
 or combine package versions to work around an installation failure.
 
-## Minimal App Router application
+## Create a new application
 
-For a new application, start with the manifest below, then install dependencies.
-For an existing application, merge only the necessary scripts and preserve its
-other fields. Follow [Compatibility](compatibility.md) for a Next.js migration.
+```sh
+npx @thomas.f/prnext create my-app
+cd my-app
+npm run dev
+```
+
+`create` writes a minimal App Router application and runs `npm install`. The
+default template uses TypeScript and includes the application components, CSS,
+scripts, TypeScript configuration and an `AGENTS.md` pointer to the installed
+PRNext documentation. It pins PRNext to the version running the command and the
+matching React peer versions.
+
+Use an empty directory or a new path. Quote paths containing spaces. Options:
+
+- `--js` creates JavaScript components without TypeScript configuration or type dependencies.
+- `--no-install` writes the files without installing dependencies; run `npm install` in the new application before starting it.
+- `--json` returns a structured creation report for automation.
+
+`npm i @thomas.f/prnext` only installs the package in the current project. It does
+not create application files, scripts or configuration. For an existing
+application, preserve its package manager and follow
+[Compatibility](compatibility.md) for a Next.js migration.
+
+## Set up an application manually
+
+To set up a new application manually, start with the manifest below, then install
+dependencies. For an existing application, merge only the necessary scripts and
+preserve its other fields.
 
 ### `package.json`