create-patties 0.0.6 → 0.0.9

package/templates/_claude/.claude/rules/build-time-discovery.md

@@ -0,0 +1,17 @@
+# Build-time discovery rule
+
+Routes, islands, agents, and tools are discovered from the filesystem
+at **build time**, not at request time.
+
+- `patties build` scans `app/routes/`, `app/islands/`, `app/agents/`,
+  `app/tools/`, and `app/jobs/` and inlines the discovered tables into
+  the server bundle. The production server never calls `Bun.Glob` /
+  `scanRoutes` / `scanIslands`.
+- This is what makes Patties cold-start fast and adapter-portable
+  (edge runtimes that disallow filesystem access still work).
+- **Dev mode is the exception.** The dev server re-scans on file
+  change to drive HMR.
+- **Don't break the rule:** never write code that calls `Bun.Glob` or
+  reads `app/**` at request time. If you find yourself wanting to,
+  the answer is probably a build-time macro or a config option in
+  `patties.config.ts`.

package/templates/_claude/.claude/rules/bun-native.md

@@ -0,0 +1,28 @@
+# Bun-native rule
+
+This project runs on Bun. Reach for Bun primitives first; do not
+reintroduce Node-era replacements just because a familiar library
+provides them.
+
+- **HTTP server:** `Bun.serve`. The framework already wires it — do
+  not add Express / Fastify / Hono / `node:http`.
+- **Filesystem discovery:** `Bun.Glob`. Do not pull in `fast-glob`,
+  `globby`, or `chokidar`.
+- **Bundling:** `Bun.build`. The framework runs it for you at
+  `patties build`; you should not add Webpack / Rollup / esbuild /
+  Vite / tsup.
+- **File I/O:** `Bun.file(path).text()` / `.json()` / `.bytes()` and
+  `Bun.write(path, data)` before reaching for `node:fs`.
+- **Hashing / crypto:** `Bun.CryptoHasher`, `Bun.password`. Avoid
+  `crypto` / `bcrypt` unless you have a real reason.
+- **Databases:** `bun:sqlite`, `Bun.sql` (Postgres), `Bun.RedisClient`,
+  `Bun.S3Client` before reaching for npm wrappers.
+- **Environment:** `Bun.env`. The framework injects the public subset
+  declared in `patties.config.ts#env.public`; secrets live in the OS
+  keychain (see `patties-cli` skill).
+- **Tests:** `bun test`. Do not add Jest or Vitest.
+- **Package manager:** `bun` / `bunx`. Do not run `npm` / `npx` /
+  `yarn` / `pnpm` in this project.
+
+If you genuinely need a Node-only library, that's fine — Bun's Node
+compatibility is strong. But default to Bun primitives.

package/templates/_claude/.claude/rules/filesystem-routing.md

@@ -0,0 +1,31 @@
+# Filesystem routing rule
+
+Routes are discovered from the filesystem under `app/routes/`. Path
+conventions:
+
+| File | URL |
+|---|---|
+| `app/routes/index.tsx` | `/` |
+| `app/routes/about.tsx` | `/about` |
+| `app/routes/hotels/index.tsx` | `/hotels` |
+| `app/routes/hotels/[city].tsx` | `/hotels/:city` |
+| `app/routes/api/revenue.ts` | `/api/revenue` |
+| `app/routes/_internal.tsx` | (private — never routed) |
+
+- **Page routes** are `.tsx` files that default-export a React
+  component. The component receives no props by default; read params
+  / cookies / env from `PattiesContext` via the page's optional
+  `loader` (export `loader` if you need server-side data).
+- **API routes** are `.ts` files that export named HTTP-method handlers:
+  `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. They return a standard
+  `Response`. Default exports in `.ts` files are reserved and will
+  error.
+- **Dynamic segments** use `[param]` in the filename. The values land
+  in `ctx.params`.
+- **Files starting with `_`** are private — co-located helpers,
+  components, or test files. They are never routed.
+- **Reserved URL prefixes:** `/__patties_*` and `/_patties/*` are
+  framework-owned. Don't put your own routes under them.
+- **Discovery happens at build time.** The production server bundle
+  has the route table inlined; it does not call `Bun.Glob` at runtime.
+  Dev mode re-scans on file change (that's where HMR comes from).

package/templates/_claude/.claude/rules/islands.md

@@ -0,0 +1,32 @@
+# Islands rule
+
+The default rendering mode is server-side. Use **islands** for the
+parts of a page that need browser-side interactivity (`useState`,
+`useEffect`, event handlers).
+
+- **Where they live:** `app/islands/*.tsx`. Files outside this
+  directory are server-only and never ship to the browser.
+- **How to mark one:** start the file with `"use client";` and
+  default-export a React component. The framework will register it,
+  bundle the client code, and inject the hydration script when the
+  component is rendered from a route.
+- **How to use one:** import the component from a route file:
+  ```tsx
+  import TodoApp from "../islands/TodoApp.tsx";
+
+  export default function Index(): JSX.Element {
+    return <main><TodoApp /></main>;
+  }
+  ```
+- **Today's gap (`bun dev`):** dev mode SSRs the island but does not
+  yet ship the client bundle. Click handlers are dead under `bun
+  dev`. To exercise interactivity right now, run `bun run build &&
+  bun start`. Full dev-mode hydration lands with framework spec 18.
+- **Naming:** the island's auto-registered name is the file path
+  relative to `app/islands/` with slashes replaced by dashes and the
+  extension stripped (e.g. `app/islands/forms/Signup.tsx` →
+  `forms-Signup`). Default exports are the only export consulted.
+- **Don't put non-island helpers in `app/islands/`.** Every `.tsx`
+  in there is treated as a hydratable component. Put shared
+  presentational components in `app/components/` or co-locate them
+  under a `_` prefix.

package/templates/_claude/.claude/rules/optional-ai.md

@@ -0,0 +1,15 @@
+# Optional AI dependency rule
+
+The Anthropic SDK is an **optional** peer dependency. Apps that do
+not use the `app/agents/`, `app/tools/`, or `app/jobs/` directories
+must still install and run without `@anthropic-ai/sdk` present.
+
+- Never `import "@anthropic-ai/sdk"` at the top level of a route or
+  middleware file. Wrap it in a dynamic `import()` inside the function
+  that needs it, or accept an `AnthropicLike` instance from
+  `PattiesContext`.
+- Do not move `@anthropic-ai/sdk` into `dependencies` unless your app
+  genuinely requires it at boot. Even then, prefer keeping it as a
+  peer + `bun add @anthropic-ai/sdk` step.
+- The auto-generated `AGENTS.md` references AI types, but does not
+  require a live SDK at import time.

package/templates/_claude/.claude/rules/web-standards-boundary.md

@@ -0,0 +1,25 @@
+# Web-standards boundary rule
+
+The framework stays close to web standards at handler boundaries. Do
+not paper over them with a custom request abstraction.
+
+- **Handler signature:** `(req: Request, ctx: PattiesContext) => Response | Promise<Response>`.
+  `req` is a standard web `Request`; the handler returns a standard web
+  `Response`. Streaming responses use `ReadableStream`.
+- **`PattiesContext` is the only framework-added affordance.** It
+  exposes `params`, `cookies`, `env`, `vars`, `url`, and the
+  short-circuit helpers `ctx.json(data, init?)`, `ctx.html(body, init?)`,
+  `ctx.redirect(to, status?)`. Keep it thin — don't expect a
+  Next-style `request.cookies.set(...)` API.
+- **No Hono / Express / Fastify types.** If you find yourself reaching
+  for `MiddlewareHandler` from Hono, write the standard
+  `Middleware = (req, ctx, next) => Promise<Response>` instead.
+- **React SSR uses `renderToReadableStream`** (the streaming web API).
+  Do not use `renderToString` or `renderToPipeableStream`.
+- **Client hydration uses `hydrateRoot`** (React 19). Do not use
+  `ReactDOM.render`.
+
+If a deployment target needs platform-specific wiring (Vercel edge
+context, Cloudflare bindings, etc.), the framework's adapters under
+`patties/adapters` translate to/from these web-standard handlers — that
+belongs in the adapter, not in your routes.

package/templates/_claude/.claude/settings.json

@@ -1,5 +1,22 @@
 {
 	"permissions": {
-		"allow": ["Bash(bun:*)", "Bash(bunx:*)", "Bash(git status:*)"]
+		"allow": [
+			"Bash(bun:*)",
+			"Bash(bunx:*)",
+			"Bash(patties:*)",
+			"Bash(git status)",
+			"Bash(git diff:*)",
+			"Bash(git log:*)"
+		]
+	},
+	"hooks": {
+		"PostToolUse": [
+			{
+				"matcher": "Edit|Write|MultiEdit",
+				"hooks": [
+					{ "type": "command", "command": ".claude/hooks/biome-check.sh" }
+				]
+			}
+		]
 	}
 }

package/templates/_claude/.claude/skills/patties-cli/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: patties-cli
+description: Use when running, building, deploying, or managing secrets for a Patties app. Covers `patties dev`, `patties build`, `patties start`, `patties deploy`, and `patties secret`. Trigger phrases include "start the dev server", "build the app", "deploy", "set a secret", "run patties".
+---
+
+# patties CLI
+
+`patties` is the project's CLI. It's installed via the `patties` dependency
+and exposed through `package.json#scripts` (`bun dev`, `bun run build`,
+`bun start`). Reach for these commands directly instead of inventing
+ad-hoc Bun invocations.
+
+## Commands
+
+### `patties dev` — start the dev server
+
+```sh
+bun dev          # equivalent to `patties dev`
+patties dev --port 4000
+patties dev --host 0.0.0.0
+```
+
+Starts the dev server with HMR over WebSocket. Reads `patties.config.ts`
+for `target`, `port`, env, and secrets. SSR-only today — full island
+hydration in dev lands with framework spec 18. To exercise interactivity
+right now, build and start instead.
+
+### `patties build` — produce a production bundle
+
+```sh
+bun run build    # equivalent to `patties build`
+patties build --target bun
+patties build --target edge --out-dir dist
+patties build --compile           # bun target only; single-binary
+```
+
+Outputs to `.patties/` by default. The server entry is at
+`.patties/server/server-entry.js`. Build also regenerates `AGENTS.md` at
+the project root.
+
+### `patties start` — run the production bundle
+
+```sh
+bun start        # equivalent to `patties start`
+```
+
+Runs the last `patties build` output. If no build exists, prints an
+error directing you to `patties build` first. Use this (after `bun run
+build`) to verify island hydration today, since dev mode only SSRs.
+
+### `patties deploy` — build then dispatch to a deploy plugin
+
+```sh
+patties deploy                    # build + dispatch
+patties deploy --skip-build       # reuse the existing `.patties/`
+```
+
+Requires a deploy plugin declared in `patties.config.ts#plugins`. If no
+plugin is installed, prints the command to run the server bundle
+manually.
+
+### `patties secret` — manage dev-time secrets
+
+Dev-only. In production, secrets come from the host's secrets surface
+(env vars, Cloudflare bindings, Vercel env, etc.) — not from this CLI.
+
+```sh
+patties secret set DATABASE_URL   # prompts for value
+patties secret set DATABASE_URL "postgres://..."
+patties secret get DATABASE_URL
+patties secret list
+patties secret rm DATABASE_URL
+patties secret doctor             # checks OS keychain access
+```
+
+Values live in the OS keychain (macOS Keychain, GNOME Keyring, Windows
+Credential Manager). They are loaded into `Bun.env` automatically when
+the dev server reads `config.secrets`.
+
+## Global flags
+
+- `--cwd <path>` — project root (default `process.cwd()`)
+- `--config <path>` — explicit config file (default: discovery in cwd)
+- `--verbose` — verbose diagnostics, includes stack traces
+- `--version` / `-v` — print version
+- `--help` / `-h` — show help
+
+## Common workflows
+
+**First-run sanity check after scaffolding:**
+```sh
+bun install
+bun dev          # opens http://localhost:3000
+```
+
+**Verify an island actually hydrates today (workaround until spec 18):**
+```sh
+bun run build
+bun start
+```
+
+**Iterate on a deploy config:**
+```sh
+patties build --target edge
+patties deploy --skip-build
+```
+
+## What this skill does NOT cover
+
+- Authoring framework primitives (routes, islands, agents, tools, jobs).
+  See the project's `CLAUDE.md` and `.claude/rules/*.md` for those.
+- Bun-the-runtime invocations (`bun add`, `bun upgrade`, `bun pm`).
+  Those are upstream Bun commands; check `bun --help` directly.

package/templates/_claude/CLAUDE.md

@@ -1,56 +1,21 @@
-# {{PROJECT_NAME}}
+# {{name}}
 
-Built with Patties — Bun-native full-stack meta-framework.
+Built with Patties — a Bun-native full-stack meta-framework.
 
-## Stack
+Project conventions live in `.claude/rules/` as small focused files.
+Read each one when it's relevant to the task at hand:
 
-Bun runtime · `Bun.serve({ routes })` dispatcher · React renderer (`react-dom/server` + `react-dom/client`) · `{{DEPLOY_TARGET}}` deploy.
+- @.claude/rules/bun-native.md — reach for Bun primitives, not Node-era replacements
+- @.claude/rules/web-standards-boundary.md — handlers use standard Request / Response; PattiesContext stays thin
+- @.claude/rules/filesystem-routing.md — how `app/routes/` becomes URLs
+- @.claude/rules/islands.md — when and how to use `app/islands/*.tsx`
+- @.claude/rules/build-time-discovery.md — discovery happens at build, not at request time
+- @.claude/rules/optional-ai.md — keep `@anthropic-ai/sdk` import-disjoint from non-AI code paths
 
-## File conventions
+The CLI surface (`patties dev/build/start/deploy/secret`) lives in the
+`patties-cli` skill at `.claude/skills/patties-cli/SKILL.md` — it loads
+automatically when CLI work is in scope.
 
-| Path | Becomes |
-|---|---|
-| `app/routes/index.tsx` | `/` |
-| `app/routes/about.tsx` | `/about` |
-| `app/routes/hotels/[city].tsx` | `/hotels/:city` |
-| `app/routes/api/revenue.ts` | `/api/revenue` |
-| `app/islands/counter.tsx` | interactive island `Counter` |
-| `app/agents/booking.ts` | agent `booking` |
-| `app/tools/search.ts` | MCP tool `search` |
-| `app/middleware.ts` | global middleware |
-| `patties.config.ts` | framework config |
-
-Files starting with `_` are private and never routed. The URL prefix `/__patties_*` and output directory `/_patties/*` are reserved.
-
-## Critical rules
-
-1. Never import from `"next"`.
-2. Never use Node.js `http`, `fs.watch`, or `chokidar`. Use `Bun.serve` and `bun --watch`.
-3. Never use webpack or vite. Use `Bun.build`.
-4. Use React for rendering. Server: `react-dom/server.renderToReadableStream`. Client: `react-dom/client.hydrateRoot`. Never `renderToPipeableStream` or `renderToString`. Never `hono/jsx` or `hono/jsx/dom`.
-5. `tsconfig.json` sets `"jsx": "react-jsx"` and `"jsxImportSource": "react"` — no manual `import React` in user code.
-6. All routes are plain `(req: Request, ctx: PattiesContext) => Response | Promise<Response>`. Never import from `"hono"`.
-7. Islands live in `app/islands/` — no exceptions.
-8. API routes export named `GET`, `POST`, `PUT`, `DELETE` functions. Default exports are reserved for page components.
-9. Middleware default-exports a `Middleware = (req, ctx, next) => Promise<Response>`. Never `MiddlewareHandler` from Hono.
-10. Use Bun primitives for I/O: `Bun.file`, `Bun.write`, `Bun.spawn`, `Bun.CryptoHasher`, `Bun.env`, `Bun.password`, `bun:sqlite`, `Bun.sql`, `Bun.RedisClient`, `Bun.S3Client`. `node:fs` only when no Bun built-in exists.
-
-## How to run
-
-- `bun install`
-- `bun dev` — start the dev server
-- `bun build` — build for production
-- `bun test`
-
-## How to add a feature
-
-Use the slash commands under `.claude/commands/`:
-
-- `/new-route <path>` — page or API route
-- `/new-island <Name>` — interactive island
-- `/new-agent <name>` — agent
-- `/new-tool <name>` — MCP tool
-
-## Where to find things
-
-`AGENTS.md` (auto-regenerated by `patties build`) is the live inventory of routes, islands, agents, and tools. Trust `AGENTS.md` over this file for inventory questions; trust this file for rules and conventions.
+The live inventory of routes, islands, agents, tools, and jobs is in
+`AGENTS.md` (regenerated by `patties build`). Trust `AGENTS.md` for
+inventory questions; trust the rules files for conventions.

package/templates/_codex/.codex/README.md

@@ -0,0 +1,10 @@
+# Codex workspace config
+
+Codex CLI reads conventions from `AGENTS.md` at the project root — that
+file is the single source of truth for rules, the CLI surface, and the
+auto-regenerated inventory of routes / islands / agents / tools.
+
+This directory is reserved for future Codex-specific config (the
+conventions are still evolving — see https://github.com/openai/codex).
+Leave it in place; the scaffolder relies on it as a marker that the
+project opted into the Codex agent overlay.

package/templates/_codex/.codex/rules/build-time-discovery.md

@@ -0,0 +1,17 @@
+# Build-time discovery rule
+
+Routes, islands, agents, and tools are discovered from the filesystem
+at **build time**, not at request time.
+
+- `patties build` scans `app/routes/`, `app/islands/`, `app/agents/`,
+  `app/tools/`, and `app/jobs/` and inlines the discovered tables into
+  the server bundle. The production server never calls `Bun.Glob` /
+  `scanRoutes` / `scanIslands`.
+- This is what makes Patties cold-start fast and adapter-portable
+  (edge runtimes that disallow filesystem access still work).
+- **Dev mode is the exception.** The dev server re-scans on file
+  change to drive HMR.
+- **Don't break the rule:** never write code that calls `Bun.Glob` or
+  reads `app/**` at request time. If you find yourself wanting to,
+  the answer is probably a build-time macro or a config option in
+  `patties.config.ts`.

package/templates/_codex/.codex/rules/bun-native.md

@@ -0,0 +1,28 @@
+# Bun-native rule
+
+This project runs on Bun. Reach for Bun primitives first; do not
+reintroduce Node-era replacements just because a familiar library
+provides them.
+
+- **HTTP server:** `Bun.serve`. The framework already wires it — do
+  not add Express / Fastify / Hono / `node:http`.
+- **Filesystem discovery:** `Bun.Glob`. Do not pull in `fast-glob`,
+  `globby`, or `chokidar`.
+- **Bundling:** `Bun.build`. The framework runs it for you at
+  `patties build`; you should not add Webpack / Rollup / esbuild /
+  Vite / tsup.
+- **File I/O:** `Bun.file(path).text()` / `.json()` / `.bytes()` and
+  `Bun.write(path, data)` before reaching for `node:fs`.
+- **Hashing / crypto:** `Bun.CryptoHasher`, `Bun.password`. Avoid
+  `crypto` / `bcrypt` unless you have a real reason.
+- **Databases:** `bun:sqlite`, `Bun.sql` (Postgres), `Bun.RedisClient`,
+  `Bun.S3Client` before reaching for npm wrappers.
+- **Environment:** `Bun.env`. The framework injects the public subset
+  declared in `patties.config.ts#env.public`; secrets live in the OS
+  keychain (see `patties-cli` skill).
+- **Tests:** `bun test`. Do not add Jest or Vitest.
+- **Package manager:** `bun` / `bunx`. Do not run `npm` / `npx` /
+  `yarn` / `pnpm` in this project.
+
+If you genuinely need a Node-only library, that's fine — Bun's Node
+compatibility is strong. But default to Bun primitives.

package/templates/_codex/.codex/rules/filesystem-routing.md

@@ -0,0 +1,31 @@
+# Filesystem routing rule
+
+Routes are discovered from the filesystem under `app/routes/`. Path
+conventions:
+
+| File | URL |
+|---|---|
+| `app/routes/index.tsx` | `/` |
+| `app/routes/about.tsx` | `/about` |
+| `app/routes/hotels/index.tsx` | `/hotels` |
+| `app/routes/hotels/[city].tsx` | `/hotels/:city` |
+| `app/routes/api/revenue.ts` | `/api/revenue` |
+| `app/routes/_internal.tsx` | (private — never routed) |
+
+- **Page routes** are `.tsx` files that default-export a React
+  component. The component receives no props by default; read params
+  / cookies / env from `PattiesContext` via the page's optional
+  `loader` (export `loader` if you need server-side data).
+- **API routes** are `.ts` files that export named HTTP-method handlers:
+  `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. They return a standard
+  `Response`. Default exports in `.ts` files are reserved and will
+  error.
+- **Dynamic segments** use `[param]` in the filename. The values land
+  in `ctx.params`.
+- **Files starting with `_`** are private — co-located helpers,
+  components, or test files. They are never routed.
+- **Reserved URL prefixes:** `/__patties_*` and `/_patties/*` are
+  framework-owned. Don't put your own routes under them.
+- **Discovery happens at build time.** The production server bundle
+  has the route table inlined; it does not call `Bun.Glob` at runtime.
+  Dev mode re-scans on file change (that's where HMR comes from).

package/templates/_codex/.codex/rules/islands.md

@@ -0,0 +1,32 @@
+# Islands rule
+
+The default rendering mode is server-side. Use **islands** for the
+parts of a page that need browser-side interactivity (`useState`,
+`useEffect`, event handlers).
+
+- **Where they live:** `app/islands/*.tsx`. Files outside this
+  directory are server-only and never ship to the browser.
+- **How to mark one:** start the file with `"use client";` and
+  default-export a React component. The framework will register it,
+  bundle the client code, and inject the hydration script when the
+  component is rendered from a route.
+- **How to use one:** import the component from a route file:
+  ```tsx
+  import TodoApp from "../islands/TodoApp.tsx";
+
+  export default function Index(): JSX.Element {
+    return <main><TodoApp /></main>;
+  }
+  ```
+- **Today's gap (`bun dev`):** dev mode SSRs the island but does not
+  yet ship the client bundle. Click handlers are dead under `bun
+  dev`. To exercise interactivity right now, run `bun run build &&
+  bun start`. Full dev-mode hydration lands with framework spec 18.
+- **Naming:** the island's auto-registered name is the file path
+  relative to `app/islands/` with slashes replaced by dashes and the
+  extension stripped (e.g. `app/islands/forms/Signup.tsx` →
+  `forms-Signup`). Default exports are the only export consulted.
+- **Don't put non-island helpers in `app/islands/`.** Every `.tsx`
+  in there is treated as a hydratable component. Put shared
+  presentational components in `app/components/` or co-locate them
+  under a `_` prefix.

package/templates/_codex/.codex/rules/optional-ai.md

@@ -0,0 +1,15 @@
+# Optional AI dependency rule
+
+The Anthropic SDK is an **optional** peer dependency. Apps that do
+not use the `app/agents/`, `app/tools/`, or `app/jobs/` directories
+must still install and run without `@anthropic-ai/sdk` present.
+
+- Never `import "@anthropic-ai/sdk"` at the top level of a route or
+  middleware file. Wrap it in a dynamic `import()` inside the function
+  that needs it, or accept an `AnthropicLike` instance from
+  `PattiesContext`.
+- Do not move `@anthropic-ai/sdk` into `dependencies` unless your app
+  genuinely requires it at boot. Even then, prefer keeping it as a
+  peer + `bun add @anthropic-ai/sdk` step.
+- The auto-generated `AGENTS.md` references AI types, but does not
+  require a live SDK at import time.

package/templates/_codex/.codex/rules/patties-cli.md

@@ -0,0 +1,113 @@
+---
+name: patties-cli
+description: Use when running, building, deploying, or managing secrets for a Patties app. Covers `patties dev`, `patties build`, `patties start`, `patties deploy`, and `patties secret`. Trigger phrases include "start the dev server", "build the app", "deploy", "set a secret", "run patties".
+---
+
+# patties CLI
+
+`patties` is the project's CLI. It's installed via the `patties` dependency
+and exposed through `package.json#scripts` (`bun dev`, `bun run build`,
+`bun start`). Reach for these commands directly instead of inventing
+ad-hoc Bun invocations.
+
+## Commands
+
+### `patties dev` — start the dev server
+
+```sh
+bun dev          # equivalent to `patties dev`
+patties dev --port 4000
+patties dev --host 0.0.0.0
+```
+
+Starts the dev server with HMR over WebSocket. Reads `patties.config.ts`
+for `target`, `port`, env, and secrets. SSR-only today — full island
+hydration in dev lands with framework spec 18. To exercise interactivity
+right now, build and start instead.
+
+### `patties build` — produce a production bundle
+
+```sh
+bun run build    # equivalent to `patties build`
+patties build --target bun
+patties build --target edge --out-dir dist
+patties build --compile           # bun target only; single-binary
+```
+
+Outputs to `.patties/` by default. The server entry is at
+`.patties/server/server-entry.js`. Build also regenerates `AGENTS.md` at
+the project root.
+
+### `patties start` — run the production bundle
+
+```sh
+bun start        # equivalent to `patties start`
+```
+
+Runs the last `patties build` output. If no build exists, prints an
+error directing you to `patties build` first. Use this (after `bun run
+build`) to verify island hydration today, since dev mode only SSRs.
+
+### `patties deploy` — build then dispatch to a deploy plugin
+
+```sh
+patties deploy                    # build + dispatch
+patties deploy --skip-build       # reuse the existing `.patties/`
+```
+
+Requires a deploy plugin declared in `patties.config.ts#plugins`. If no
+plugin is installed, prints the command to run the server bundle
+manually.
+
+### `patties secret` — manage dev-time secrets
+
+Dev-only. In production, secrets come from the host's secrets surface
+(env vars, Cloudflare bindings, Vercel env, etc.) — not from this CLI.
+
+```sh
+patties secret set DATABASE_URL   # prompts for value
+patties secret set DATABASE_URL "postgres://..."
+patties secret get DATABASE_URL
+patties secret list
+patties secret rm DATABASE_URL
+patties secret doctor             # checks OS keychain access
+```
+
+Values live in the OS keychain (macOS Keychain, GNOME Keyring, Windows
+Credential Manager). They are loaded into `Bun.env` automatically when
+the dev server reads `config.secrets`.
+
+## Global flags
+
+- `--cwd <path>` — project root (default `process.cwd()`)
+- `--config <path>` — explicit config file (default: discovery in cwd)
+- `--verbose` — verbose diagnostics, includes stack traces
+- `--version` / `-v` — print version
+- `--help` / `-h` — show help
+
+## Common workflows
+
+**First-run sanity check after scaffolding:**
+```sh
+bun install
+bun dev          # opens http://localhost:3000
+```
+
+**Verify an island actually hydrates today (workaround until spec 18):**
+```sh
+bun run build
+bun start
+```
+
+**Iterate on a deploy config:**
+```sh
+patties build --target edge
+patties deploy --skip-build
+```
+
+## What this skill does NOT cover
+
+- Authoring framework primitives (routes, islands, agents, tools, jobs).
+  See the project's `CLAUDE.md` and `.claude/rules/*.md` for those.
+- Bun-the-runtime invocations (`bun add`, `bun upgrade`, `bun pm`).
+  Those are upstream Bun commands; check `bun --help` directly.

package/templates/_codex/.codex/rules/web-standards-boundary.md

@@ -0,0 +1,25 @@
+# Web-standards boundary rule
+
+The framework stays close to web standards at handler boundaries. Do
+not paper over them with a custom request abstraction.
+
+- **Handler signature:** `(req: Request, ctx: PattiesContext) => Response | Promise<Response>`.
+  `req` is a standard web `Request`; the handler returns a standard web
+  `Response`. Streaming responses use `ReadableStream`.
+- **`PattiesContext` is the only framework-added affordance.** It
+  exposes `params`, `cookies`, `env`, `vars`, `url`, and the
+  short-circuit helpers `ctx.json(data, init?)`, `ctx.html(body, init?)`,
+  `ctx.redirect(to, status?)`. Keep it thin — don't expect a
+  Next-style `request.cookies.set(...)` API.
+- **No Hono / Express / Fastify types.** If you find yourself reaching
+  for `MiddlewareHandler` from Hono, write the standard
+  `Middleware = (req, ctx, next) => Promise<Response>` instead.
+- **React SSR uses `renderToReadableStream`** (the streaming web API).
+  Do not use `renderToString` or `renderToPipeableStream`.
+- **Client hydration uses `hydrateRoot`** (React 19). Do not use
+  `ReactDOM.render`.
+
+If a deployment target needs platform-specific wiring (Vercel edge
+context, Cloudflare bindings, etc.), the framework's adapters under
+`patties/adapters` translate to/from these web-standard handlers — that
+belongs in the adapter, not in your routes.