pi-cloudflare 0.1.0

package/skills/durable-objects/references/workers.md

@@ -0,0 +1,346 @@
+# Cloudflare Workers Best Practices
+
+High-level guidance for Workers that invoke Durable Objects.
+
+## Wrangler Configuration
+
+### wrangler.jsonc (Recommended)
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-12-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "durable_objects": {
+    "bindings": [
+      { "name": "CHAT_ROOM", "class_name": "ChatRoom" },
+      { "name": "USER_SESSION", "class_name": "UserSession" }
+    ]
+  },
+
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["ChatRoom", "UserSession"] }
+  ],
+
+  // Environment variables
+  "vars": {
+    "ENVIRONMENT": "production"
+  },
+
+  // KV namespaces
+  "kv_namespaces": [
+    { "binding": "CONFIG", "id": "abc123" }
+  ],
+
+  // R2 buckets
+  "r2_buckets": [
+    { "binding": "UPLOADS", "bucket_name": "my-uploads" }
+  ],
+
+  // D1 databases
+  "d1_databases": [
+    { "binding": "DB", "database_id": "xyz789" }
+  ]
+}
+```
+
+### wrangler.toml (Alternative)
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[durable_objects.bindings]]
+name = "CHAT_ROOM"
+class_name = "ChatRoom"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatRoom"]
+
+[vars]
+ENVIRONMENT = "production"
+```
+
+## TypeScript Types
+
+### Environment Interface
+
+```typescript
+// src/types.ts
+import { ChatRoom } from "./durable-objects/chat-room";
+import { UserSession } from "./durable-objects/user-session";
+
+export interface Env {
+  // Durable Objects
+  CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
+  USER_SESSION: DurableObjectNamespace<UserSession>;
+
+  // KV
+  CONFIG: KVNamespace;
+
+  // R2
+  UPLOADS: R2Bucket;
+
+  // D1
+  DB: D1Database;
+
+  // Environment variables
+  ENVIRONMENT: string;
+  API_KEY: string; // From secrets
+}
+```
+
+### Export Durable Object Classes
+
+```typescript
+// src/index.ts
+export { ChatRoom } from "./durable-objects/chat-room";
+export { UserSession } from "./durable-objects/user-session";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Worker handler
+  },
+};
+```
+
+## Worker Handler Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    try {
+      // Route to appropriate handler
+      if (url.pathname.startsWith("/api/rooms")) {
+        return handleRooms(request, env);
+      }
+      if (url.pathname.startsWith("/api/users")) {
+        return handleUsers(request, env);
+      }
+
+      return new Response("Not Found", { status: 404 });
+    } catch (error) {
+      console.error("Request failed:", error);
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  },
+};
+
+async function handleRooms(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url);
+  const roomId = url.searchParams.get("room");
+
+  if (!roomId) {
+    return Response.json({ error: "Missing room parameter" }, { status: 400 });
+  }
+
+  const stub = env.CHAT_ROOM.getByName(roomId);
+
+  if (request.method === "POST") {
+    const body = await request.json<{ userId: string; message: string }>();
+    const result = await stub.sendMessage(body.userId, body.message);
+    return Response.json(result);
+  }
+
+  const messages = await stub.getMessages();
+  return Response.json(messages);
+}
+```
+
+## Request Validation
+
+```typescript
+import { z } from "zod";
+
+const SendMessageSchema = z.object({
+  userId: z.string().min(1),
+  message: z.string().min(1).max(1000),
+});
+
+async function handleSendMessage(request: Request, env: Env): Promise<Response> {
+  const body = await request.json();
+  const result = SendMessageSchema.safeParse(body);
+
+  if (!result.success) {
+    return Response.json(
+      { error: "Validation failed", details: result.error.issues },
+      { status: 400 }
+    );
+  }
+
+  const stub = env.CHAT_ROOM.getByName(result.data.userId);
+  const message = await stub.sendMessage(result.data.userId, result.data.message);
+  return Response.json(message);
+}
+```
+
+## Observability & Logging
+
+### Structured Logging
+
+```typescript
+function log(level: "info" | "warn" | "error", message: string, data?: Record<string, unknown>) {
+  console.log(JSON.stringify({
+    level,
+    message,
+    timestamp: new Date().toISOString(),
+    ...data,
+  }));
+}
+
+// Usage
+log("info", "Request received", { path: url.pathname, method: request.method });
+log("error", "DO call failed", { roomId, error: String(error) });
+```
+
+### Request Tracing
+
+```typescript
+async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const requestId = crypto.randomUUID();
+  const startTime = Date.now();
+
+  try {
+    const response = await processRequest(request, env);
+
+    log("info", "Request completed", {
+      requestId,
+      duration: Date.now() - startTime,
+      status: response.status,
+    });
+
+    return response;
+  } catch (error) {
+    log("error", "Request failed", {
+      requestId,
+      duration: Date.now() - startTime,
+      error: String(error),
+    });
+    throw error;
+  }
+}
+```
+
+### Tail Workers (Production)
+
+For production logging, use Tail Workers to forward logs:
+
+```jsonc
+// wrangler.jsonc
+{
+  "tail_consumers": [
+    { "service": "log-collector" }
+  ]
+}
+```
+
+## Error Handling
+
+### Graceful DO Errors
+
+```typescript
+async function callDO(stub: DurableObjectStub<ChatRoom>, method: string): Promise<Response> {
+  try {
+    const result = await stub.getMessages();
+    return Response.json(result);
+  } catch (error) {
+    if (error instanceof Error) {
+      // DO threw an error
+      log("error", "DO operation failed", { error: error.message });
+      return Response.json(
+        { error: "Service temporarily unavailable" },
+        { status: 503 }
+      );
+    }
+    throw error;
+  }
+}
+```
+
+### Timeout Handling
+
+```typescript
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error("Timeout")), ms)
+  );
+  return Promise.race([promise, timeout]);
+}
+
+// Usage
+const result = await withTimeout(stub.processData(data), 5000);
+```
+
+## CORS Handling
+
+```typescript
+function corsHeaders(): HeadersInit {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+  };
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: corsHeaders() });
+    }
+
+    const response = await handleRequest(request, env);
+    
+    // Add CORS headers to response
+    const newHeaders = new Headers(response.headers);
+    Object.entries(corsHeaders()).forEach(([k, v]) => newHeaders.set(k, v));
+    
+    return new Response(response.body, {
+      status: response.status,
+      headers: newHeaders,
+    });
+  },
+};
+```
+
+## Secrets Management
+
+Set secrets via wrangler CLI (not in config files):
+
+```bash
+wrangler secret put API_KEY
+wrangler secret put DATABASE_URL
+```
+
+Access in code:
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiKey = env.API_KEY; // From secret
+    // ...
+  },
+};
+```
+
+## Development Commands
+
+```bash
+# Local development
+wrangler dev
+
+# Deploy
+wrangler deploy
+
+# Tail logs
+wrangler tail
+
+# List DOs
+wrangler d1 execute DB --command "SELECT * FROM _cf_DO"
+```

package/skills/sandbox-migrate-to-next/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: sandbox-migrate-to-next
+description: Use when porting a Cloudflare Sandbox app from stable @cloudflare/sandbox to @cloudflare/sandbox@next (Sandbox SDK 1.0 preview), or when the user asks to migrate or upgrade to Sandbox 1.0 / @next. Not for day-to-day stable work (sandbox-stable) or new @next apps (sandbox-next).
+---
+
+# Migrate stable → Sandbox SDK 1.0 preview (`@next`)
+
+**Perform** the port. Follow the steps in order. Depth lives in docs—fetch the linked page when a step needs detail.
+
+Human guide: [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · [1.0 preview](https://developers.cloudflare.com/sandbox/1-0-preview/)
+
+**New projects** should start on `@next` (**`sandbox-next`**), not this skill. **Day-to-day stable work** → **`sandbox-stable`**. Deprecated-API cleanup **without** moving to `@next` → [2026 deprecation guide](https://developers.cloudflare.com/sandbox/guides/2026-deprecation/) first if needed.
+
+Existing apps should migrate **when you can**, so you are ready when 1.0 becomes the stable release. Do **not** force production cutover without the user agreeing.
+
+**Prefer installed `@next` types and the migrate doc over memory.**
+
+## Workflow
+
+1. **Review** hard rules and the replacement map  
+2. **Audit** the codebase; list hits and target shapes  
+3. **Clarify** with the user (cutover, bridge, Python image, unclear sites)  
+4. **Upgrade** package, image, and code  
+5. **Validate**  
+
+Stop after any step that needs a user decision.
+
+## Hard rules
+
+- Worker package and container image must be the **same** `@next` line.  
+- Production cutover uses **immediate** container rollout. Stable and `@next` control protocols are incompatible both ways; gradual rollout leaves a broken mixed window. In-flight container work can stop.  
+- After cutover, `await sandbox.exec(...)` means process **started**, not command **finished**.  
+- Argv is as-is (no implicit shell). Shell syntax needs an explicit shell binary.  
+- Process handles have **no stdin** → terminals for interactive input.  
+- Observation `timeout` / `AbortSignal` cancel the **wait only**, not the process.  
+- No single retry loop for every error.  
+- Do not invent APIs (`gitCheckout` on core, process stdin, string-exec completion helper).  
+- Self-deployed bridge stays on **stable** (not part of the preview line yet).  
+
+## Replacement map
+
+| Stable | `@next` |
+| ------ | ------- |
+| `SANDBOX_TRANSPORT` / `transport` / `setTransport` | Remove — RPC only |
+| `await sandbox.exec("cmd")` → buffered result | `await sandbox.exec(argv)` → handle, then `output` / waits |
+| `execStream` / `startProcess` | Same handle: `logs`, `waitFor*`, `kill` |
+| Default / named sessions | Gone — `cwd`/`env` per launch, or one shell script |
+| `sandbox.terminal(request)` / session terminal | `createTerminal` + `terminal.connect(request)` |
+| xterm `sessionId` | `terminalId` |
+| Interpreter methods on `Sandbox` | `withInterpreter` → `sandbox.interpreter.*` |
+| `gitCheckout` | argv `git` via `exec` |
+| String kill signals | Numeric only |
+| Files, mounts, backups, ports, tunnels, `proxyToSandbox` | Mostly unchanged (ignore session/transport bits on stable pages) |
+
+Depth: [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · after port, day-to-day → **`sandbox-next`**
+
+## Audit
+
+```sh
+rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'
+```
+
+Also: string `exec(`, `cd` then a later `exec`, bare `createCodeContext` / `runCode` on `Sandbox`.
+
+## Clarify (ask when needed)
+
+- OK to cut production with `--containers-rollout=immediate` (live processes/terminals/streams may stop)?  
+- Self-deployed bridge? Leave on stable.  
+- Python interpreter → **`-python`** image variant?  
+- Call sites not covered by the map?  
+
+## Upgrade
+
+### Package and image
+
+```sh
+npm install @cloudflare/sandbox@next
+```
+
+```dockerfile
+FROM cloudflare/sandbox:next
+# Python: cloudflare/sandbox:next-python
+```
+
+Same prerelease tag on Worker and image when not on floating `next`.
+
+### Code by area
+
+Apply replacements from the map. For each area, implement from the doc—not from stable habits:
+
+| Area | Doc |
+| ---- | --- |
+| Commands / handles / waits | [Processes](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) · [Processes API](https://developers.cloudflare.com/sandbox/1-0-preview/api/processes/) |
+| `cwd` / `env` / secrets | [Environment](https://developers.cloudflare.com/sandbox/1-0-preview/environment/) · [Outbound traffic](https://developers.cloudflare.com/sandbox/guides/outbound-traffic/) |
+| Drop sessions | [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · [Lifecycle](https://developers.cloudflare.com/sandbox/1-0-preview/lifecycle/) |
+| Terminals | [Terminals](https://developers.cloudflare.com/sandbox/1-0-preview/terminals/) |
+| Interpreter | [Interpreter](https://developers.cloudflare.com/sandbox/1-0-preview/interpreter/) |
+| Errors | [Errors](https://developers.cloudflare.com/sandbox/1-0-preview/errors/) |
+| Durable job across requests | [Process execution — lifetime / durability](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) |
+
+**Commands (shape):**
+
+```ts
+// Before (stable)
+const result = await sandbox.exec("npm test");
+
+// After (@next)
+const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
+const result = await process.output({ encoding: "utf8" });
+```
+
+```ts
+const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
+  cwd: "/workspace/app",
+});
+await server.waitForPort(3000, { timeout: 60_000 });
+await server.kill(); // numeric; default 15
+```
+
+**Terminals (shape):**
+
+```ts
+const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
+const t = await sandbox.getTerminal(terminal.id);
+if (!t) return new Response("terminal gone", { status: 410 });
+return t.connect(request, { cursor, cols, rows });
+```
+
+**Interpreter (shape):**
+
+```ts
+import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
+import { withInterpreter } from "@cloudflare/sandbox/interpreter";
+
+export class Sandbox extends BaseSandbox<Env> {
+  interpreter = withInterpreter(this);
+}
+```
+
+**Git (shape):**
+
+```ts
+const clone = await sandbox.exec(
+  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
+  { cwd: "/workspace" },
+);
+const result = await clone.output({ encoding: "utf8" });
+```
+
+Delete transport settings entirely. Remove session APIs. Isolate users with **separate sandbox IDs**.
+
+### Deploy cutover
+
+Staging/branch first. Production is **one** deploy of matching Worker + image:
+
+```sh
+npx wrangler deploy --containers-rollout=immediate
+```
+
+Leave `rollout_active_grace_period` at default `0` (or set `0` if raised). After cutover, pre-deploy process/terminal IDs are invalid. Details: [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · [Container rollouts](https://developers.cloudflare.com/containers/platform-details/rollouts/)
+
+## Validate
+
+1. Lockfile + Dockerfile on the same `@next` line  
+2. Typecheck against `@next`  
+3. Smoke argv `exec` + `output({ encoding: "utf8" })`  
+4. Smoke long process / terminal / interpreter if used  
+5. Errors distinguished: unavailable / interrupted-RPC / stale / local wait  
+6. No live secrets in sandbox env  
+7. Grep again for removed APIs  
+8. Production used `--containers-rollout=immediate`  
+
+Then day-to-day work uses **`sandbox-next`**.
+
+## Red flags — stop and fix
+
+- Mixing `@next` Worker with stable image (or reverse)  
+- Gradual container rollout for this cutover  
+- Treating `await exec` as command completion  
+- Assuming `cd` / exports persist across `exec` calls  
+- One retry wrapper for every error  
+- Inventing `gitCheckout`, process stdin, or undocumented APIs  
+- Keeping pre-cutover process/terminal IDs after deploy  
+- Forcing production cutover without user agreement  
+- Putting live secrets in `setEnvVars` / launch `env`  

package/skills/sandbox-next/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sandbox-next
+description: Use when building or changing Cloudflare Sandbox apps on @cloudflare/sandbox@next (Sandbox SDK 1.0 preview)—code execution, AI runners, interpreters, CI-like jobs, terminals, files, mounts, tunnels, preview URLs, lifecycle, or errors. Not for the default stable package (use sandbox-stable) or for porting stable to @next (use sandbox-migrate-to-next).
+---
+
+# Sandbox SDK — `@next` (1.0 preview)
+
+Isolated Linux environments on [Cloudflare Containers](https://developers.cloudflare.com/containers/), driven from Workers.
+
+**Prefer preview docs and installed `@next` types over memory.** APIs change; this skill is a gate, a contract, and a retrieval map—not a full manual.
+
+We recommend **new projects** on this line. Apps still on the default package use **`sandbox-stable`**. Port only when asked, via **`sandbox-migrate-to-next`**.
+
+## 1. Gate — confirm the package line
+
+Before writing code, inspect the app:
+
+| Check | Must match |
+| ----- | ---------- |
+| npm dependency | `@cloudflare/sandbox@next` (or another preview tag) |
+| Container image | Same line (e.g. `cloudflare/sandbox:next`, `next-python`) |
+
+| If you find… | Action |
+| ------------ | ------ |
+| Default `@cloudflare/sandbox` (no `@next`) | **Stop.** Load **`sandbox-stable`**. Do not apply this skill’s APIs. |
+| User wants to port stable → `@next` | **Stop.** Load **`sandbox-migrate-to-next`**. |
+| Self-deployed **bridge** only | Bridge is **not** on the 1.0 preview line yet. Keep bridge on stable package + image. [Bridge (stable)](https://developers.cloudflare.com/sandbox/bridge/) |
+
+Never mix an `@next` Worker package with a stable container image (or the reverse).
+
+Skills install: [Agent setup](https://developers.cloudflare.com/agent-setup/) · [cloudflare/skills](https://github.com/cloudflare/skills)
+
+## 2. Contract — non-negotiables
+
+- `sandbox.exec(argv)` takes an **argv** list and resolves when the process **starts**. It returns a **handle**, not a finished command result.
+- Collect results with handle methods: `output()`, `logs()`, `waitForExit()`, `waitForPort()`, `waitForLog()`, `kill(signal?)`.
+- No implicit shell. Shell syntax needs an explicit shell, e.g. `["/bin/bash", "-lc", script]`.
+- Each launch is independent. A `cd` / `export` in one `exec` is not visible to the next. Pass `cwd` and `env` per launch, or one shell script.
+- Process handles have **no stdin**. Interactive use → terminals (`createTerminal` + `connect`).
+- Local wait `timeout` / `AbortSignal` cancel the **wait only**. They do not kill the process. Use `kill` or `exec`’s remote `timeout`.
+- `getProcess` / `listProcesses` / `getTerminal` / `listTerminals` do **not** start a container; they return `null` / `[]` when none is up.
+- Process and terminal IDs belong to the **current container**, not forever to a sandbox ID. For work that must survive replace, store the full job (argv, cwd, env, app state)—not only an id.
+- Non-secret config only in `setEnvVars` / launch `env`. Live credentials stay in the Worker; use outbound handlers when the sandbox calls external APIs.
+- Do **not** invent removed stable APIs (`gitCheckout` on core, string-`exec` completion, session execution, `sandbox.terminal(request)`).
+- Do **not** use one retry loop for every error (see Errors docs).
+
+Minimal shape:
+
+```ts
+import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
+
+export { Sandbox };
+
+const sandbox = getSandbox(env.Sandbox, "user-123");
+const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
+const result = await process.output({ encoding: "utf8" });
+// result.stdout, result.exitCode
+```
+
+Optional **non-exhaustive** cheatsheet (process/terminal/interpreter only): [references/api-quick-ref.md](references/api-quick-ref.md)  
+Examples index (`next` branch): [references/examples.md](references/examples.md)
+
+## 3. Retrieve — open the doc for the task
+
+Fetch the page before implementing. Installed `@next` types win over guesses.
+
+| You need to… | Open |
+| ------------ | ---- |
+| Orient / choose preview | [1.0 preview overview](https://developers.cloudflare.com/sandbox/1-0-preview/) |
+| First Worker, wrangler, Dockerfile | [Get started](https://developers.cloudflare.com/sandbox/1-0-preview/get-started/) |
+| `exec`, handles, readiness, durability | [Process execution](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) |
+| Process API signatures | [Processes API](https://developers.cloudflare.com/sandbox/1-0-preview/api/processes/) |
+| Sandbox ID vs container vs sleep/destroy | [Lifecycle](https://developers.cloudflare.com/sandbox/1-0-preview/lifecycle/) |
+| `cwd` / `env` / `setEnvVars` | [Environment](https://developers.cloudflare.com/sandbox/1-0-preview/environment/) |
+| Interactive PTY / browser terminal | [Terminals](https://developers.cloudflare.com/sandbox/1-0-preview/terminals/) · [Terminals API](https://developers.cloudflare.com/sandbox/1-0-preview/api/terminals/) |
+| Python/JS code interpreter | [Interpreter](https://developers.cloudflare.com/sandbox/1-0-preview/interpreter/) · [Interpreter API](https://developers.cloudflare.com/sandbox/1-0-preview/api/interpreter/) |
+| Extensions model | [Extensions](https://developers.cloudflare.com/sandbox/1-0-preview/extensions/) |
+| Error classes and recovery | [Errors](https://developers.cloudflare.com/sandbox/1-0-preview/errors/) · [Errors API](https://developers.cloudflare.com/sandbox/1-0-preview/api/errors/) |
+| Common failures | [Troubleshooting](https://developers.cloudflare.com/sandbox/1-0-preview/troubleshooting/) |
+| API hub | [API reference](https://developers.cloudflare.com/sandbox/1-0-preview/api/) |
+| Files, mounts, backups, ports, tunnels, `proxyToSandbox` | Main docs for shared surfaces (ignore stable-only session/transport/`sandbox.terminal`): [Files](https://developers.cloudflare.com/sandbox/api/files/) · [Storage / mounts](https://developers.cloudflare.com/sandbox/api/storage/) · [Ports](https://developers.cloudflare.com/sandbox/api/ports/) · [Tunnels](https://developers.cloudflare.com/sandbox/api/tunnels/) · [Backups](https://developers.cloudflare.com/sandbox/api/backups/) · [Outbound traffic](https://developers.cloudflare.com/sandbox/guides/outbound-traffic/) · [Expose services](https://developers.cloudflare.com/sandbox/guides/expose-services/) · [Production](https://developers.cloudflare.com/sandbox/guides/production-deployment/) |
+| Example apps | [examples on `next`](https://github.com/cloudflare/sandbox-sdk/tree/next/examples) |
+| Still on stable package | **`sandbox-stable`** · [Main Sandbox docs](https://developers.cloudflare.com/sandbox/) |
+| Porting an existing stable app | **`sandbox-migrate-to-next`** · [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) |
+
+## 4. Before you ship
+
+- Lockfile and Dockerfile on the **same** `@next` line  
+- Typecheck against installed `@next` types  
+- No live secrets in sandbox env  
+- Production preview hostnames need wildcard DNS on a custom domain when using those URL patterns