feat: sync docs examples and matrix baselines

Author: NathanFlurry

CLAUDE.md

@@ -201,6 +201,9 @@ Follow the style in `packages/secure-exec/src/index.ts`.
 
 - all public-facing docs (quickstart, guides, API reference, landing page, README) must focus on the **Node.js runtime** as the primary and default experience — do not lead with WasmVM, kernel internals, or multi-runtime concepts
 - code examples in docs should use the `NodeRuntime` API (`runtime.run()`, `runtime.exec()`) as the default path; the kernel API (`createKernel`, `kernel.spawn()`) is for advanced multi-process use cases and should be presented as secondary
+- keep documentation pages and their runnable example sources in sync: `docs/quickstart.mdx` must match `examples/kitchen-sink/src/`, and `docs/features/*.mdx` must match `examples/features/src/`
+- when updating a doc snippet, update the corresponding example file and the docs/example verification scripts in the same change
+- when converting runnable example code into documentation snippets, use public package imports like `from "secure-exec"` and `from "@secure-exec/typescript"` instead of repo-local source paths
 - WasmVM and Python docs are experimental docs and must stay grouped under the `Experimental` section in `docs/docs.json`
 - docs pages that must stay current with API changes:
   - `docs/quickstart.mdx` — update when core setup flow changes

docs/api-reference.mdx

@@ -136,7 +136,7 @@ createTypeScriptTools(options: TypeScriptToolsOptions)
 | `runtimeDriverFactory` | `NodeRuntimeDriverFactory` | Creates the compiler sandbox runtime. |
 | `memoryLimit` | `number` | Compiler sandbox isolate memory cap in MB. Default `512`. |
 | `cpuTimeLimitMs` | `number` | Compiler sandbox CPU time budget in ms. |
-| `compilerSpecifier` | `string` | Module specifier used to load the TypeScript compiler. Default `"/root/node_modules/typescript/lib/typescript.js"`. |
+| `compilerSpecifier` | `string` | Module specifier used to load the TypeScript compiler. Default `"typescript"`. |
 
 **Methods**
 

docs/features/child-processes.mdx

@@ -12,14 +12,16 @@ Sandboxed code can spawn child processes through the `CommandExecutor` interface
 
 ## Runnable example
 
+Source file: `examples/features/src/child-processes.ts`
+
 ```ts
 import {
   NodeRuntime,
   allowAllChildProcess,
   createNodeDriver,
   createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
-import type { CommandExecutor } from "../../../packages/secure-exec/src/types.ts";
+} from "secure-exec";
+import type { CommandExecutor } from "secure-exec";
 import { spawn } from "node:child_process";
 
 const commandExecutor: CommandExecutor = {
@@ -98,8 +100,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/child-processes.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/child-processes.ts)
-
 ## Permission gating
 
 Restrict which commands sandboxed code can spawn:

docs/features/filesystem.mdx

@@ -12,14 +12,16 @@ secure-exec supports three filesystem backends. The system driver controls which
 
 ## Runnable example
 
+Source file: `examples/features/src/filesystem.ts`
+
 ```ts
 import {
   NodeRuntime,
   allowAllFs,
   createInMemoryFileSystem,
   createNodeDriver,
   createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
+} from "secure-exec";
 
 const filesystem = createInMemoryFileSystem();
 const runtime = new NodeRuntime({
@@ -55,8 +57,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/filesystem.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/filesystem.ts)
-
 ## OPFS (browser)
 
 Persistent filesystem using the Origin Private File System API. This is the default for `createBrowserDriver()`.

docs/features/module-loading.mdx

@@ -13,6 +13,8 @@ Sandboxed code can `require()` and `import` modules through secure-exec's module
 
 ## Runnable example
 
+Source file: `examples/features/src/module-loading.ts`
+
 ```ts
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -21,7 +23,7 @@ import {
 	allowAllFs,
 	createNodeDriver,
 	createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
+} from "secure-exec";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 
@@ -58,8 +60,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/module-loading.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/module-loading.ts)
-
 ## node_modules overlay
 
 Node runtime executions expose a read-only dependency overlay at `/app/node_modules`, sourced from `<cwd>/node_modules` on the host (default `cwd` is `process.cwd()`).

docs/features/networking.mdx

@@ -12,6 +12,8 @@ Network access is deny-by-default. Enable it by setting `useDefaultNetwork: true
 
 ## Runnable example
 
+Source file: `examples/features/src/networking.ts`
+
 ```ts
 import * as http from "node:http";
 import {
@@ -20,7 +22,7 @@ import {
 	createDefaultNetworkAdapter,
 	createNodeDriver,
 	createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
+} from "secure-exec";
 
 const logs: string[] = [];
 const server = http.createServer((_req, res) => {
@@ -51,23 +53,19 @@ const runtime = new NodeRuntime({
 try {
 	const result = await runtime.exec(
 		`
-			(async () => {
-				const response = await fetch("http://127.0.0.1:${address.port}/");
-				const body = await response.text();
-
-				if (!response.ok || response.status !== 200 || body !== "network-ok") {
-					throw new Error(
-						"unexpected response: " + response.status + " " + body,
-					);
-				}
-
-				console.log(JSON.stringify({ status: response.status, body }));
-			})().catch((error) => {
-				console.error(error instanceof Error ? error.message : String(error));
-				process.exitCode = 1;
-			});
+			const response = await fetch("http://127.0.0.1:${address.port}/");
+			const body = await response.text();
+
+			if (!response.ok || response.status !== 200 || body !== "network-ok") {
+				throw new Error(
+					"unexpected response: " + response.status + " " + body,
+				);
+			}
+
+			console.log(JSON.stringify({ status: response.status, body }));
 		`,
 		{
+			filePath: "/entry.mjs",
 			onStdio: (event) => {
 				logs.push(`[${event.channel}] ${event.message}`);
 			},
@@ -107,8 +105,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/networking.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/networking.ts)
-
 ## Quick setup
 
 <Tabs>

docs/features/output-capture.mdx

@@ -12,12 +12,14 @@ Console output from sandboxed code is **not buffered** into result fields. `exec
 
 ## Runnable example
 
+Source file: `examples/features/src/output-capture.ts`
+
 ```ts
 import {
   NodeRuntime,
   createNodeDriver,
   createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
+} from "secure-exec";
 
 const events: string[] = [];
 
@@ -64,8 +66,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/output-capture.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/output-capture.ts)
-
 ## Default hook
 
 Set a runtime-level hook that applies to all executions:

docs/features/permissions.mdx

@@ -12,13 +12,15 @@ All host capabilities are **deny-by-default**. Sandboxed code cannot access the
 
 ## Runnable example
 
+Source file: `examples/features/src/permissions.ts`
+
 ```ts
 import {
 	NodeRuntime,
 	createInMemoryFileSystem,
 	createNodeDriver,
 	createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
+} from "secure-exec";
 
 const filesystem = createInMemoryFileSystem();
 await filesystem.writeFile("/secret.txt", "top secret");
@@ -69,8 +71,6 @@ console.log(
 );
 ```
 
-Source: [examples/features/src/permissions.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/permissions.ts)
-
 ## Permission helpers
 
 Quick presets for common configurations:

docs/features/resource-limits.mdx

@@ -12,12 +12,14 @@ Resource limits prevent sandboxed code from running forever or exhausting host m
 
 ## Runnable example
 
+Source file: `examples/features/src/resource-limits.ts`
+
 ```ts
 import {
   NodeRuntime,
   createNodeDriver,
   createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
+} from "secure-exec";
 
 const runtime = new NodeRuntime({
   systemDriver: createNodeDriver(),
@@ -52,8 +54,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/resource-limits.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/resource-limits.ts)
-
 ## CPU time limit
 
 Set a CPU time budget in milliseconds. When exceeded, the execution exits with code `124`.

docs/features/typescript.mdx

@@ -12,14 +12,16 @@ The `@secure-exec/typescript` companion package runs the TypeScript compiler ins
 
 ## Runnable example
 
+Source file: `examples/features/src/typescript.ts`
+
 ```ts
 import {
   NodeRuntime,
   allowAllFs,
   createNodeDriver,
   createNodeRuntimeDriverFactory,
-} from "../../../packages/secure-exec/src/index.ts";
-import { createTypeScriptTools } from "../../../packages/typescript/src/index.ts";
+} from "secure-exec";
+import { createTypeScriptTools } from "@secure-exec/typescript";
 
 const sourceText = `
   export const message: string = "hello from typescript";
@@ -42,7 +44,7 @@ const runtime = new NodeRuntime({
 const ts = createTypeScriptTools({
   systemDriver: compilerSystemDriver,
   runtimeDriverFactory,
-  compilerSpecifier: "/root/node_modules/typescript/lib/typescript.js",
+  compilerSpecifier: "typescript",
 });
 
 try {
@@ -91,8 +93,6 @@ try {
 }
 ```
 
-Source: [examples/features/src/typescript.ts](https://github.com/rivet-dev/secure-exec/blob/main/examples/features/src/typescript.ts)
-
 ## Install
 
 ```bash
@@ -119,7 +119,7 @@ const ts = createTypeScriptTools({
 | `runtimeDriverFactory` | `NodeRuntimeDriverFactory` | required | Creates the compiler sandbox |
 | `memoryLimit` | `number` | `512` | Compiler isolate memory cap in MB |
 | `cpuTimeLimitMs` | `number` | | Compiler CPU time budget in ms |
-| `compilerSpecifier` | `string` | `"/root/node_modules/typescript/lib/typescript.js"` | Module specifier for the TypeScript compiler |
+| `compilerSpecifier` | `string` | `"typescript"` | Module specifier for the TypeScript compiler |
 
 ## Type-check a source string