@thomas.f/prnext 0.1.16-alpha → 0.1.18-alpha

package/docs/ai/troubleshooting.md

@@ -0,0 +1,155 @@
+# Troubleshooting and live verification
+
+[AI documentation index](../../AI.md)
+
+## Collect a useful failure
+
+Read the installed version, command, working directory, Node version, manager,
+configuration and first complete diagnostic. Separate build errors, semantic
+TypeScript errors, server exceptions, HTTP failures and browser hydration
+errors; they have different causes. Keep secrets, cookies and authorization
+headers out of reports.
+
+```sh
+prnext --version
+prnext check --json
+prnext typecheck --json
+```
+
+`check` does not install, compile or start the application. `typecheck` generates
+types and runs application-installed TypeScript; it needs the application's
+tsconfig and may update generated references. `build` then exercises loaders,
+server/client transforms and prerendering. A browser visit checks the live
+result. Report which layer failed instead of treating one green command as proof
+of all layers.
+
+## Common diagnoses
+
+| Symptom | Check first |
+| --- | --- |
+| Native component missing or wrong version | Optional dependencies, supported platform/Node, package lock, framework/native version family and an unintended `PRNEXT_BINARY` override. |
+| Peer or React server/client mismatch | Exact installed React, React DOM and RSC peers; duplicate React instances and a second framework runtime. |
+| Unknown configuration option | The installed version's accepted config; remove or replace only after understanding the intended feature. |
+| Cannot resolve a framework import | Public supported subpath, dependency placement and the migration audit; do not fabricate a private adapter. |
+| Hook or server-only import error | The nearest `'use client'` boundary and everything it imports; keep Node/secret code on the server. |
+| Request API outside context | Move cookie/header access into a request; cached callbacks receive needed values as arguments. |
+| Type errors missing from editor or build | Run `prnext typecheck`; inspect `typescript.tsconfigPath`, inherited roots and existing aliases. |
+| A prerender needs runtime data | Decide whether the route is actually dynamic; do not insert build-time production credentials or suppress the bailout blindly. |
+| Cached content remains stale | The affected cache layer, explicit key/tags and mutation-phase invalidation; custom handlers may delegate caching. |
+
+Do not manually patch installed native binaries or force a different release
+into an application. Reinstall through the existing manager and reviewed
+lockfile if installation is the actual problem. Keep the original diagnostic
+when reporting a platform that lacks a compatible published component.
+
+## Hydration errors
+
+Compare server HTML with the first client render. Typical causes include
+`Date.now()`, random values, locale/time-zone differences, invalid HTML nesting,
+browser-only conditions and client state initialized from storage. Pass stable
+server values as props or move browser reads to a lifecycle. Check that the
+browser loaded assets from the matching build. Use `suppressHydrationWarning`
+only for a deliberately unavoidable, understood mismatch; it is not a general
+repair. Verify the interactive result after the change.
+
+## HMR and cache failures
+
+Development compiles requested routes and preserves state for compatible edits;
+config/environment, custom Document or incompatible module changes can reload
+the document. Production prerendering and compression are not development HMR.
+An unused route need not rebuild until requested.
+
+Middleware and rewrites can select a cold destination after routing. PRNext
+compiles that destination through its private development compiler and continues
+the same request. It does not send an upload or action through middleware again.
+Retained parallel branches are compiled together when their source is needed.
+An error in an unrelated unopened route should not force that route into the
+active graph. Safe mode remains available for full-graph comparisons.
+
+For a controlled diagnosis, stop only the development process you own and try:
+
+```sh
+prnext dev --safe
+```
+
+Safe mode uses full builds and fresh workers. `PRNEXT_BUILD_CACHE=0` disables
+PRNext's persistent compiler/build caches when set in the current process environment; use
+the syntax appropriate to the user's shell and restore the previous setting
+after the comparison. In-memory compiler/transform reuse is a separate layer.
+Optional cache-storage failures should fall back to work,
+while genuine loader errors remain build failures. Do not delete every cache or
+lockfile as a first response, especially with another server running.
+
+Production builds can reuse eligible compiled JavaScript graphs and CSS Module
+outputs from the default CSS engine across processes through the private
+`.prnext-cache` directory. The successful artifact's `compilation-cache-report.json` and the
+programmatic build result's `compilationCache` report actual hits, misses and
+bypasses. These are compilation diagnostics, not response-cache or latency
+measurements. App graphs that discover actions or client boundaries, development
+graphs, the explicit PostCSS engine and custom loader/PostCSS pipelines still
+execute their compiler work.
+HTML, Flight responses and private rendered data are not stored in this cache.
+Changes to tracked dependencies, resolution candidates, options, environment
+or framework identity invalidate eligible entries. Corrupt or unavailable cache
+records fall back to compilation; `PRNEXT_BUILD_CACHE=0` disables their persistent reuse.
+
+For production observations:
+
+```sh
+prnext start --inspect
+prnext inspect --json
+```
+
+The inspector needs actual traffic for observed timings. Header-ready timings
+exclude the full streaming body, and missing/dropped samples are not zero.
+`prnext routes` describes compiled routes. Bundle size questions use
+`prnext analyze`, after building, rather than interpreting request time as
+compiler performance.
+
+Initial-JS analysis includes required hydration imports and SSR-used dynamic
+chunks. Schema 2 reports per-prerendered-path samples and the maximum size for
+each compression metric; a route's file list can be the union of its samples.
+Request-dependent or incomplete graphs are lower bounds. Their size budgets
+fail as `initial-unknown`, even if that lower bound is small. Do not present it
+as a complete measurement or a size saving. Rebuild old schema-1 baselines before
+comparing them with schema 2. An opaque webpack graph is also marked incomplete.
+
+For memoization questions, run `prnext compiler --json` after a successful build
+with `reactCompiler` enabled. Inspect the affected function and its skip reason,
+the reported graph coverage and cached-transform counts. An absent function in
+an observed-transforms report is not proof that it was optimized or rejected.
+Keep application behavior and hydration checks alongside this diagnostic.
+
+## Connect the existing development MCP
+
+Start `prnext dev` in the application, then configure a compatible assistant to
+launch the following **stdio MCP command** with its absolute project directory:
+
+```sh
+prnext mcp /absolute/path/to/application
+```
+
+Use the locally installed executable, not an unreviewed remote package. This
+stdio process is a tool server for an MCP client, not a second application
+server. The development endpoint binds to loopback; its private
+`.prnext-dev/tools.json` contains a capability, so never publish or paste that
+file. No new shell-access tool or public debug endpoint is needed.
+
+The existing tools include `dev_snapshot`, `dev_logs`, `dev_routes`,
+`dev_route_ensure`, `dev_cache_invalidate`, `dev_source`, `dev_ai_context` and
+`dev_verify`. Read their returned schemas rather than inventing tool arguments.
+
+For a fix, capture `dev_snapshot` before editing and retain its `sequence`.
+After the edit, call `dev_verify` with that value as `sinceSequence` and the
+pathname being checked. Keep an actual application browser open. Verification
+requires a newer successful generation and browser evidence that it applied
+that exact build. A missing build or browser is inconclusive; compilation,
+TypeScript or reported browser errors fail the observation. Continue relevant
+application tests: this development observation does not establish complete
+functional correctness.
+
+Local MCP works independently of managed hosting. `prnext dev --host-ai` is an
+explicit relay option for a logged-in terminal and a compatible connected Host
+server; it can share requested diagnostics and queued context. Do not enable
+remote sharing or change a user's assistant configuration as a hidden side
+effect of fixing an application.

package/index.mjs

@@ -1,3 +1,5 @@
 export { build } from './build/index.mjs';
+export {createBuilder} from './build/production-builder.mjs';
+export {route} from './runtime/typed-route.mjs';
 export { buildStatic } from './build/static-adapter.mjs';
 export { readBuildOutput, validateBuildOutput } from './build/output-contract.mjs';

package/native/diagnostics.mjs

@@ -0,0 +1,34 @@
+import { packageManifest, nativePlatform, resolveNativeBinary } from './resolve.mjs';
+
+// The package's Node engines use explicit minimum versions and major ranges.
+// Keep this check local: a diagnostic must never fetch package metadata.
+export function supportedNode(version, range = packageManifest.engines.node) {
+  const parsed = /^(?:v)?(\d+)\.(\d+)\.(\d+)(?:\+[^\s]+)?$/.exec(version);
+  if (!parsed) return false;
+  const actual = parsed.slice(1).map(Number);
+  return range.split('||').some(part => {
+    const match = /^\s*(\^|>=)(\d+)\.(\d+)\.(\d+)\s*$/.exec(part);
+    if (!match) return false;
+    const minimum = match.slice(2).map(Number);
+    const compared = actual[0] - minimum[0] || actual[1] - minimum[1] || actual[2] - minimum[2];
+    return compared >= 0 && (match[1] !== '^' || actual[0] === minimum[0]);
+  });
+}
+
+/** Inspect installation metadata and executable access; never execute or build it. */
+export async function environmentDiagnostics({ version = process.version, platform = process.platform, arch = process.arch,
+  libc, env = process.env, resolve = resolveNativeBinary } = {}) {
+  const diagnostics = [];
+  diagnostics.push(supportedNode(version)
+    ? { id: 'node', severity: 'info', message: `Node ${version} satisfies ${packageManifest.engines.node}.` }
+    : { id: 'node', severity: 'error', message: `Node ${version} is unsupported.`, action: `Use Node ${packageManifest.engines.node}.` });
+  try {
+    const target = env.PRNEXT_BINARY ? null : nativePlatform({ platform, arch, libc });
+    await resolve({ env, allowBuild: false, platform: { platform, arch, libc } });
+    diagnostics.push({ id: 'native', severity: 'info', message: `Native executable is accessible for ${platform}/${arch}${target?.libc ? `/${target.libc}` : ''}; metadata/access checked without running it.`, ...(target ? { package: target.package } : { override: true }) });
+  } catch (error) {
+    diagnostics.push({ id: 'native', severity: 'error', message: error.message,
+      action: 'Install matching PRNext optional dependencies on this machine. For a source checkout, build the native server explicitly; check never builds it.' });
+  }
+  return diagnostics;
+}

package/native/resolve.mjs

@@ -14,10 +14,15 @@ export const nativeBinaryName = (platform = process.platform) => platform === 'w
 // the framework checkout, even if that consumer also has a Cargo workspace.
 export function sourceCheckout(root = packageRoot) {
   try {
-    const repository = path.resolve(root, '../..');
+    // Package-manager portals and linked checkouts may expose a virtual path.
+    // Establish the physical package root before looking for its repository.
+    // The native resolver also expands Windows DOS aliases and canonicalizes
+    // junction target casing; the JS resolver preserves their stored spelling.
+    const canonicalRoot = realpathSync.native(root);
+    const repository = path.resolve(canonicalRoot, '../..');
     const manifest = JSON.parse(readFileSync(path.join(repository, 'package.json'), 'utf8'));
     if (manifest.name !== 'prnext-monorepo' || manifest.private !== true) return null;
-    if (realpathSync(root) !== realpathSync(path.join(repository, 'packages/prnext'))) return null;
+    if (canonicalRoot !== realpathSync.native(path.join(repository, 'packages/prnext'))) return null;
     readFileSync(path.join(repository, 'crates/prnext/Cargo.toml'));
     return repository;
   } catch { return null; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thomas.f/prnext",
-  "version": "0.1.16-alpha",
+  "version": "0.1.18-alpha",
   "license": "MIT",
   "description": "Experimental Rust-powered runtime for Next.js apps, React and npm",
   "homepage": "https://prnext.dev",
@@ -33,6 +33,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
+    "AI.md",
+    "docs/ai/",
     "cli.mjs",
     "index.mjs",
     "build/",
@@ -49,6 +51,14 @@
     "prn": "./cli.mjs"
   },
   "exports": {
+    "./AI.md": "./AI.md",
+    "./docs/ai/manifest.json": "./docs/ai/manifest.json",
+    "./docs/ai/quickstart.md": "./docs/ai/quickstart.md",
+    "./docs/ai/routing.md": "./docs/ai/routing.md",
+    "./docs/ai/data.md": "./docs/ai/data.md",
+    "./docs/ai/compatibility.md": "./docs/ai/compatibility.md",
+    "./docs/ai/deployment.md": "./docs/ai/deployment.md",
+    "./docs/ai/troubleshooting.md": "./docs/ai/troubleshooting.md",
     "./package.json": "./package.json",
     "./og": {
       "types": "./compat/og.d.cts",
@@ -66,6 +76,10 @@
       "types": "./compat/index.d.ts",
       "default": "./index.mjs"
     },
+    "./route": {
+      "types": "./compat/typed-route.d.cts",
+      "default": "./runtime/typed-route.mjs"
+    },
     "./link": "./compat/link.cjs",
     "./head": "./compat/head.cjs",
     "./script": {
@@ -101,6 +115,14 @@
     "./headers": "./compat/headers.cjs",
     "./server": "./compat/server.cjs",
     "./cache": "./compat/cache.cjs",
+    "./cache/redis": {
+      "types": "./compat/redis-cache.d.cts",
+      "default": "./compat/redis-cache.cjs"
+    },
+    "./offline": {
+      "types": "./compat/offline.d.cts",
+      "default": "./compat/offline.cjs"
+    },
     "./constants": "./compat/constants.cjs"
   },
   "dependencies": {
@@ -110,34 +132,49 @@
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
     "@edge-runtime/vm": "5.0.0",
+    "@jridgewell/trace-mapping": "0.3.31",
     "@vercel/nft": "1.11.0",
+    "babel-plugin-react-compiler": "1.0.0",
+    "browserslist": "4.29.0",
     "dotenv": "16.6.1",
     "dotenv-expand": "11.0.7",
     "esbuild": "^0.28.2",
     "fontkit": "2.0.4",
+    "get-tsconfig": "4.14.3",
+    "html-to-image": "1.11.13",
+    "jsonc-parser": "3.3.1",
+    "lightningcss": "1.31.0",
     "loader-runner": "4.3.2",
+    "oxc-parser": "0.155.0",
     "path-to-regexp": "6.3.0",
     "picomatch": "4.0.7",
     "postcss": "8.5.28",
     "postcss-flexbugs-fixes": "5.0.2",
     "postcss-preset-env": "11.5.3",
+    "postcss-selector-parser": "7.1.6",
     "postcss-value-parser": "4.2.0",
     "react-refresh": "0.19.0",
     "schema-utils": "4.3.3",
     "webpack": "5.111.1"
   },
   "peerDependencies": {
+    "@redis/client": "^6.3.0",
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "react-server-dom-webpack": "19.3.1"
   },
+  "peerDependenciesMeta": {
+    "@redis/client": {
+      "optional": true
+    }
+  },
   "optionalDependencies": {
-    "prnext-darwin-arm64": "0.1.16-alpha",
-    "prnext-darwin-x64": "0.1.16-alpha",
-    "prnext-linux-arm64-gnu": "0.1.16-alpha",
-    "prnext-linux-x64-gnu": "0.1.16-alpha",
-    "@thomas.f/prnext-win32-x64-msvc": "0.1.16-alpha",
-    "@thomas.f/prnext-win32-arm64-msvc": "0.1.16-alpha"
+    "prnext-darwin-arm64": "0.1.18-alpha",
+    "prnext-darwin-x64": "0.1.18-alpha",
+    "prnext-linux-arm64-gnu": "0.1.18-alpha",
+    "prnext-linux-x64-gnu": "0.1.18-alpha",
+    "@thomas.f/prnext-win32-x64-msvc": "0.1.18-alpha",
+    "@thomas.f/prnext-win32-arm64-msvc": "0.1.18-alpha"
   },
   "engines": {
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1"

package/release/ai-docs.mjs

@@ -0,0 +1,48 @@
+import { readFile, access } from 'node:fs/promises';
+import path from 'node:path';
+
+const expectedTopics = ['quickstart', 'routing', 'data', 'compatibility', 'deployment', 'troubleshooting'];
+
+// These guides ship as package API. Validate their distribution and local links
+// on every release, independently of a website or a native server installation.
+export async function verifyAiDocumentation(root, pkg) {
+  if (!pkg.files?.includes('AI.md') || !pkg.files?.includes('docs/ai/')) {
+    throw new Error('The npm files list must include AI.md and docs/ai/.');
+  }
+  const manifest = JSON.parse(await readFile(path.join(root, 'docs/ai/manifest.json'), 'utf8'));
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.topics) ||
+      JSON.stringify(manifest.topics.map(topic => topic.id)) !== JSON.stringify(expectedTopics)) {
+    throw new Error('AI documentation manifest has missing, duplicate or unexpected topics.');
+  }
+  const files = ['AI.md'];
+  for (const topic of manifest.topics) {
+    if (topic.file !== `docs/ai/${topic.id}.md` || typeof topic.title !== 'string' || !topic.title.trim() || /[\r\n\x00-\x1f]/.test(topic.title)) {
+      throw new Error(`Invalid AI documentation topic: ${topic.id}`);
+    }
+    files.push(topic.file);
+  }
+  for (const file of [...files, 'docs/ai/manifest.json']) {
+    if (pkg.exports?.[`./${file}`] !== `./${file}`) throw new Error(`Missing npm documentation export: ${file}`);
+  }
+  let totalBytes = 0;
+  for (const file of files) {
+    const content = await readFile(path.join(root, file), 'utf8');
+    const bytes = Buffer.byteLength(content);
+    totalBytes += bytes;
+    if (!/^# .+/m.test(content) || bytes > (file === 'AI.md' ? 6_000 : 32_000)) {
+      throw new Error(`AI guide is missing its heading or exceeds its focused reading budget: ${file}`);
+    }
+    for (const match of content.matchAll(/\[[^\]\n]+\]\(([^)\s]+)\)/g)) {
+      const link = match[1];
+      if (link.startsWith('#') || /^https?:\/\//.test(link)) continue;
+      const target = path.resolve(root, path.dirname(file), decodeURIComponent(link.split('#')[0]));
+      const relative = path.relative(root, target);
+      if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`AI guide link leaves the package: ${file}: ${link}`);
+      try { await access(target); }
+      catch { throw new Error(`Broken AI guide link: ${file}: ${link}`); }
+    }
+  }
+  if (totalBytes > 100_000) throw new Error('AI documentation exceeds the total focused reading budget.');
+  await access(path.join(root, 'runtime/ai-docs.mjs'));
+  return { topics: manifest.topics.length, files: files.length, bytes: totalBytes };
+}

package/release/verify.mjs

@@ -2,6 +2,7 @@ import { readFile, access } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { packageRoot, packageManifest, platforms, sourceCheckout } from '../native/resolve.mjs';
+import { verifyAiDocumentation } from './ai-docs.mjs';
 
 export async function verifyPackage() {
   const pkg = packageManifest;
@@ -25,6 +26,7 @@ export async function verifyPackage() {
     for (const target of Object.values(value)) await exported(target);
   }
   await exported(pkg.exports);
+  await verifyAiDocumentation(packageRoot, pkg);
   await access(path.join(packageRoot, 'runtime/profiles.json'));
   for (const name of ['index.node.mjs', 'resvg.wasm', 'hb.wasm', 'Geist-Regular.ttf', 'LICENSE', 'LICENSE.fflate', 'LICENSE.Geist', 'LICENSE.harfbuzzjs', 'LICENSE.satori', 'NOTICE.txt']) await access(path.join(packageRoot, 'runtime/og', name));
   if (pkg.dependencies['@vercel/og'] || (await readFile(path.join(packageRoot, 'runtime/og/index.node.mjs'), 'utf8')).includes('fflate@0.7.3')) throw new Error('OG renderer still depends on vulnerable upstream fflate. Run scripts/prepare-og.mjs.');

package/runtime/action-client.mjs

@@ -1,19 +1,25 @@
-let referenceFactory;
-let transport;
+// A newly opened route can move this helper into a different development ESM
+// chunk. Its action proxies still belong to the already mounted application.
+// Production keeps the ordinary per-graph module state.
+const state = process.env.NODE_ENV === 'development'
+  ? globalThis[Symbol.for('prnext.development.server-actions')] ||= {}
+  : {};
 
 // App bootstrap installs the official Flight client after its module loader is
 // ready. Action proxy modules load through that same client graph afterwards.
 export function configureServerActions({ createServerReference, callServer }) {
-  referenceFactory = createServerReference;
-  transport = callServer;
+  state.referenceFactory = createServerReference;
+  state.transport = callServer;
 }
 
 export function callServer(id, args) {
+  const transport = state.transport;
   if (!transport) return Promise.reject(new Error('The PRNext Server Action transport is not initialized'));
   return transport(id, args);
 }
 
 export function createServerReference(id) {
+  const referenceFactory = state.referenceFactory;
   if (!referenceFactory) throw new Error('Server Action references must load after the PRNext Flight client');
   return referenceFactory(id, callServer);
 }

package/runtime/action-server.mjs

@@ -1,3 +1,4 @@
+import {reportRequestError} from './instrumentation.mjs';
 import { decodeReply, decodeAction, decodeFormState, createTemporaryReferenceSet } from 'react-server-dom-webpack/server.node';
 import { pathToFileURL } from 'node:url';
 import path from 'node:path';
@@ -126,6 +127,7 @@ export async function invokeAction(request) {
       } else if (navigation?.status === 404) {
         actionNotFound = true;
       } else {
+        reportRequestError(error,{routeType:'action'});
         console.error('[prnext]', error?.stack || error);
         actionError = errorPayload(error, request.production);
         failure = { message: error?.message || String(error), stack: error?.stack, digest: error?.digest };

package/runtime/ai-docs.mjs

@@ -0,0 +1,202 @@
+import fs, {constants} from 'node:fs';
+import {lstat, open, realpath, unlink} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const defaultPackageRoot = fileURLToPath(new URL('../', import.meta.url));
+const maxDocumentBytes = 256 * 1024;
+const maxInstructionsBytes = 1024 * 1024;
+const startMarker = '<!-- prnext-ai-docs:start -->';
+const endMarker = '<!-- prnext-ai-docs:end -->';
+const noFollow = constants.O_NOFOLLOW || 0;
+
+const help = `Usage: prnext docs --ai [topic] [--json]
+       prnext docs --ai --list [--json]
+       prnext docs --ai --init [directory] [--json]
+
+Read the AI documentation shipped with the installed PRNext package.
+With no topic, print the short documentation index. --list shows available topics.
+--init explicitly appends a short documentation pointer to a project's AGENTS.md.
+Existing instructions are preserved; no files are changed by documentation reads.
+For initialization, use a physical directory path without symbolic links or junctions.
+No native binary, project configuration, network access, or installation is needed.
+`;
+
+function parseArguments(args) {
+  if (!Array.isArray(args) || args.some(arg => typeof arg !== 'string')) throw new Error('Documentation arguments must be strings.');
+  if (args.includes('--help') || args.includes('-h')) {
+    if (args.every(arg => ['--ai', '--help', '-h'].includes(arg))) return {help: true};
+    throw new Error('Use prnext docs --help without other documentation options.');
+  }
+  const flags = new Set(), positional = [];
+  for (const arg of args) {
+    if (['--ai', '--list', '--json', '--init'].includes(arg)) {
+      if (flags.has(arg)) throw new Error(`Duplicate documentation option: ${arg}`);
+      flags.add(arg);
+    } else if (arg.startsWith('-')) throw new Error(`Unknown documentation option: ${arg}`);
+    else positional.push(arg);
+  }
+  if (!flags.has('--ai')) throw new Error('Use prnext docs --ai to read the installed AI documentation.');
+  if (positional.length > 1) throw new Error('Provide only one documentation topic or initialization directory.');
+  if (flags.has('--list') && (flags.has('--init') || positional.length)) throw new Error('--list cannot be combined with a topic or --init.');
+  return {list: flags.has('--list'), json: flags.has('--json'), init: flags.has('--init'), value: positional[0]};
+}
+
+async function readBounded(handle, limit, label) {
+  const info = await handle.stat();
+  if (!info.isFile()) throw new Error(`${label} must be a regular file.`);
+  if (info.size > limit) throw new Error(`${label} exceeds the ${limit}-byte limit.`);
+  const buffer = Buffer.alloc(limit + 1);
+  let size = 0;
+  while (size < buffer.length) {
+    const {bytesRead} = await handle.read(buffer, size, buffer.length - size, size);
+    if (!bytesRead) break;
+    size += bytesRead;
+  }
+  if (size > limit) throw new Error(`${label} exceeds the ${limit}-byte limit.`);
+  return buffer.subarray(0, size);
+}
+
+function decodeUtf8(buffer, label) {
+  try { return new TextDecoder('utf-8', {fatal: true, ignoreBOM: true}).decode(buffer); }
+  catch { throw new Error(`${label} must contain UTF-8 text.`); }
+}
+
+async function readPackageFile(root, relative, limit = maxDocumentBytes) {
+  const file = path.resolve(root, relative);
+  const canonicalRoot = await realpath(root), canonicalFile = await realpath(file);
+  const inside = path.relative(canonicalRoot, canonicalFile);
+  if (inside.startsWith(`..${path.sep}`) || inside === '..' || path.isAbsolute(inside)) throw new Error(`Documentation file escapes the installed package: ${relative}`);
+  const handle = await open(file, constants.O_RDONLY);
+  try { return decodeUtf8(await readBounded(handle, limit, relative), relative); }
+  finally { await handle.close(); }
+}
+
+async function readCatalog(root) {
+  const metadata = JSON.parse(await readPackageFile(root, 'package.json', 64 * 1024));
+  if (typeof metadata.name !== 'string' || typeof metadata.version !== 'string') throw new Error('The installed package metadata has no name or version.');
+  const manifest = JSON.parse(await readPackageFile(root, 'docs/ai/manifest.json', 64 * 1024));
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.topics) || manifest.topics.length > 64) throw new Error('The AI documentation manifest must use schemaVersion 1 and contain a bounded topics array.');
+  const topics = [{id: 'index', title: 'AI documentation index', file: 'AI.md'}], ids = new Set(['index']);
+  for (const topic of manifest.topics) {
+    if (!topic || !/^[a-z][a-z0-9-]*$/.test(topic.id) || ids.has(topic.id)
+      || typeof topic.title !== 'string' || !topic.title.trim() || /[\r\n\x00-\x1f]/.test(topic.title)
+      || topic.file !== `docs/ai/${topic.id}.md`) throw new Error('The AI documentation manifest contains an invalid or duplicate topic.');
+    ids.add(topic.id);
+    topics.push({id: topic.id, title: topic.title, file: topic.file});
+  }
+  return {name: metadata.name, version: metadata.version, topics};
+}
+
+function instructionBlock(newline) {
+  return [startMarker, '## PRNext documentation', '',
+    'Before changing PRNext configuration, routes, data fetching, or deployment, read the documentation shipped with the installed package:', '',
+    '`npx --no-install prnext docs --ai`', '',
+    'Use `npx --no-install prnext docs --ai --list` to find topics, then read only the relevant topic with `npx --no-install prnext docs --ai <topic>`.',
+    'With pnpm or Yarn, use `pnpm exec prnext docs --ai` or `yarn prnext docs --ai` instead. The installed package documentation is the version-specific reference; do not assume full Next.js compatibility.',
+    endMarker, ''].join(newline);
+}
+
+function samePath(left, right) {
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+async function checkDirectory(directory) {
+  const parts = path.relative(path.parse(directory).root, directory).split(path.sep).filter(Boolean);
+  let current = path.parse(directory).root;
+  for (const part of parts) {
+    current = path.join(current, part);
+    const info = await lstat(current);
+    if (info.isSymbolicLink()) throw new Error(`Refusing to initialize through a symbolic link or junction: ${current}`);
+    if (!info.isDirectory()) throw new Error(`Initialization directory is not a directory: ${current}`);
+  }
+  if (!samePath(await realpath(directory), directory)) throw new Error('Initialization directory resolves outside its requested path.');
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function verifyTarget(directory, file, handle) {
+  await checkDirectory(directory);
+  const actual = await lstat(file), opened = await handle.stat();
+  if (actual.isSymbolicLink() || !actual.isFile() || !sameFile(actual, opened) || opened.nlink !== 1) {
+    throw new Error('AGENTS.md changed identity or is linked; no instructions were appended.');
+  }
+}
+
+function hasPointer(content) {
+  const starts = content.split(startMarker).length - 1, ends = content.split(endMarker).length - 1;
+  if (!starts && !ends) return false;
+  if (starts !== 1 || ends !== 1 || content.indexOf(startMarker) > content.indexOf(endMarker)) {
+    throw new Error('AGENTS.md contains incomplete or duplicate PRNext documentation markers; preserve and fix those markers before initializing again.');
+  }
+  return true;
+}
+
+async function initializeInstructions(directory) {
+  await checkDirectory(directory);
+  const file = path.join(directory, 'AGENTS.md'), lockFile = path.join(directory, '.prnext-ai-docs.lock');
+  let lock;
+  try { lock = await open(lockFile, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Another initialization or an existing lock prevents changes: ${lockFile}`);
+    throw error;
+  }
+  let handle;
+  try {
+    await checkDirectory(directory);
+    let existing;
+    try { existing = await lstat(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (existing && (existing.isSymbolicLink() || !existing.isFile() || existing.nlink !== 1)) throw new Error('AGENTS.md must be a regular file with no symbolic or hard links.');
+    handle = await open(file, existing
+      ? constants.O_RDWR | constants.O_APPEND | noFollow
+      : constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_EXCL | noFollow, 0o644);
+    await verifyTarget(directory, file, handle);
+    const before = await readBounded(handle, maxInstructionsBytes, 'AGENTS.md');
+    const content = decodeUtf8(before, 'AGENTS.md');
+    if (hasPointer(content)) return {path: file, changed: false};
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const separator = !content ? '' : content.endsWith(newline + newline) ? '' : content.endsWith(newline) ? newline : newline + newline;
+    const addition = Buffer.from(separator + instructionBlock(newline));
+    if (before.length + addition.length > maxInstructionsBytes) throw new Error('Appending the PRNext pointer would exceed the AGENTS.md size limit.');
+    // Append through the verified handle: concurrent appends never get replaced by
+    // a stale full-file write. Refuse observed edits or target replacement.
+    if (!before.equals(await readBounded(handle, maxInstructionsBytes, 'AGENTS.md'))) throw new Error('AGENTS.md changed during initialization; retry without overwriting those edits.');
+    await verifyTarget(directory, file, handle);
+    await handle.writeFile(addition);
+    // Yarn PnP wraps FileHandle.sync() with an unimplemented method, even for
+    // physical project files. Its descriptor still supports callback fsync.
+    await new Promise((resolve, reject) => fs.fsync(handle.fd, error => error ? reject(error) : resolve()));
+    return {path: file, changed: true};
+  } finally {
+    await handle?.close();
+    // Only remove the lock we created, never a replacement supplied by another process.
+    try {
+      const opened = await lock.stat(), actual = await lstat(lockFile);
+      if (sameFile(opened, actual) && !actual.isSymbolicLink()) await unlink(lockFile);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    finally { await lock.close(); }
+  }
+}
+
+/** Read bundled docs or explicitly append a project pointer. Never launches native code. */
+export async function executeAiDocs(args, {cwd = process.cwd(), packageRoot = defaultPackageRoot} = {}) {
+  const options = parseArguments(args);
+  if (options.help) return {output: help};
+  const catalog = await readCatalog(packageRoot);
+  if (options.init) {
+    const initialized = await initializeInstructions(path.resolve(cwd, options.value || '.'));
+    const result = {name: catalog.name, version: catalog.version, initialized};
+    return {initialized, output: options.json ? JSON.stringify(result, null, 2) + '\n'
+      : `${initialized.changed ? 'Added the PRNext documentation pointer to' : 'Kept the existing PRNext documentation pointer in'} ${initialized.path}\n`};
+  }
+  if (options.list) return {output: options.json ? JSON.stringify(catalog, null, 2) + '\n'
+    : `${catalog.name} ${catalog.version}\n\n${catalog.topics.map(topic => `${topic.id.padEnd(18)} ${topic.title}`).join('\n')}\n`};
+  const id = options.value || 'index';
+  const topic = catalog.topics.find(item => item.id === id);
+  if (!topic) throw new Error(`Unknown AI documentation topic: ${id}. Use prnext docs --ai --list.`);
+  const content = await readPackageFile(packageRoot, topic.file);
+  return {output: options.json ? JSON.stringify({...catalog, topic: topic.id, content}, null, 2) + '\n'
+    : `${catalog.name} ${catalog.version} — ${topic.title}\n\n${content}${content.endsWith('\n') ? '' : '\n'}`};
+}