create-patties 0.0.9 → 0.0.10

package/README.md

@@ -9,7 +9,7 @@ bunx create-patties@latest my-app
 
 Runs an interactive prompt (project name, agent overlay, demo template,
 runtime target, deploy target), then scaffolds, installs, and gets you
-to `bun dev` in one shot.
+to `bunx patties dev` in one shot.
 
 ## Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-patties",
-	"version": "0.0.9",
+	"version": "0.0.10",
 	"type": "module",
 	"description": "Scaffolder for new Patties projects.",
 	"bin": {

package/src/index.ts

@@ -148,7 +148,13 @@ export async function run(argv: string[]): Promise<number> {
 		deploy: args.deploy,
 		scaffold: args.scaffold,
 	});
-	step("rendered template variables (README, AGENTS.md, …)");
+	const manifestName =
+		args.template === "codex"
+			? "AGENTS.md"
+			: args.template === "claude"
+				? "CLAUDE.md"
+				: "manifest";
+	step(`rendered template variables (README, ${manifestName}, …)`);
 
 	if (args.install) {
 		pending("installing dependencies (bun install)…");
@@ -182,8 +188,8 @@ export async function run(argv: string[]): Promise<number> {
 	}
 
 	const nextSteps = args.git
-		? `\n  cd ${args.name}\n  bun dev\n`
-		: `\n  cd ${args.name}\n  bun dev\n\n  # when you're ready to track this in git:\n  git init && git add -A && git commit -m "initial commit"\n`;
+		? `\n  cd ${args.name}\n  bunx patties dev\n`
+		: `\n  cd ${args.name}\n  bunx patties dev\n\n  # when you're ready to track this in git:\n  git init && git add -A && git commit -m "initial commit"\n`;
 	process.stdout.write(`\n✓ created ${args.name}\n${nextSteps}`);
 	if (gitSkippedReason === "git-missing") {
 		stderr("create-patties: `git` not found — skipping `git init`.");
@@ -345,10 +351,18 @@ async function patchPattiesConfig(dir: string, args: Args): Promise<void> {
 	const path = `${dir}/patties.config.ts`;
 	if (!(await Bun.file(path).exists())) return;
 	const current = await Bun.file(path).text();
-	const next = current.replace(
+	let next = current.replace(
 		/target:\s*"(bun|edge)"/,
 		`target: "${args.target}"`,
 	);
+	// Point the agent manifest at the file the chosen agent already reads.
+	// Default (claude / none) leaves the framework default ("CLAUDE.md").
+	if (args.template === "codex" && !/agentsMd:/.test(next)) {
+		next = next.replace(
+			/target:\s*"(bun|edge)",?\n/,
+			(m) => `${m.replace(/,?\n$/, ",\n")}\tagentsMd: { path: "AGENTS.md" },\n`,
+		);
+	}
 	if (next !== current) await Bun.write(path, next);
 }
 

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

@@ -7,25 +7,39 @@ parts of a page that need browser-side interactivity (`useState`,
 - **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:
+  default-export a React component. The framework auto-registers it,
+  bundles its client code, and serves the chunk under
+  `/_patties/client/*` (in dev via `setupDevClient`; in production via
+  `patties build`).
+- **How to use one:** import the component from a route file and
+  wrap each use-site in `<Island name="…">…</Island>` from
+  `patties/render`. The wrapper emits the `data-island` marker + props
+  sibling that the client runtime scans for — without it the markup
+  SSRs fine but never hydrates.
+
   ```tsx
+  import { Island } from "patties/render";
   import TodoApp from "../islands/TodoApp.tsx";
 
   export default function Index(): JSX.Element {
-    return <main><TodoApp /></main>;
+    return (
+      <main>
+        <Island name="TodoApp">
+          <TodoApp />
+        </Island>
+      </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.
+  `forms-Signup`). Pass the same string as `<Island name="…">`. Default
+  exports are the only export consulted.
+- **Dev mode hydrates.** `patties dev` builds islands in
+  `--mode development` (no minify), serves them, and the client runtime
+  hydrates each `[data-island]` marker. HMR reloads the page on island
+  changes.
 - **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

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

@@ -11,5 +11,6 @@ must still install and run without `@anthropic-ai/sdk` present.
 - 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.
+- The auto-generated manifest (default `CLAUDE.md`; configurable via
+  `config.agentsMd.path`) references AI types, but does not require a
+  live SDK at import time.

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

@@ -15,15 +15,14 @@ ad-hoc Bun invocations.
 ### `patties dev` — start the dev server
 
 ```sh
-bun dev          # equivalent to `patties dev`
+bunx patties dev # the canonical invocation (bun dev runs the same thing via the package.json script)
 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.
+for `target`, `port`, env, and secrets. Islands are bundled and hydrated
+in dev — the same code path users see in production, minus minification.
 
 ### `patties build` — produce a production bundle
 
@@ -35,8 +34,9 @@ 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/server/server-entry.js`. Build also regenerates the agent
+manifest section (default `CLAUDE.md`; configurable via
+`config.agentsMd.path`).
 
 ### `patties start` — run the production bundle
 
@@ -45,8 +45,7 @@ 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.
+error directing you to `patties build` first.
 
 ### `patties deploy` — build then dispatch to a deploy plugin
 
@@ -90,10 +89,10 @@ the dev server reads `config.secrets`.
 **First-run sanity check after scaffolding:**
 ```sh
 bun install
-bun dev          # opens http://localhost:3000
+bunx patties dev # opens http://localhost:3000 — SSR + island hydration
 ```
 
-**Verify an island actually hydrates today (workaround until spec 18):**
+**Verify the production bundle:**
 ```sh
 bun run build
 bun start

package/templates/_claude/CLAUDE.md

@@ -16,6 +16,13 @@ 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.
 
-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.
+The live inventory of routes, islands, agents, tools, and jobs is spliced
+into this file between `<!-- patties:manifest-start -->` and
+`<!-- patties:manifest-end -->` — regenerated on every `patties dev/build`
+while everything else here is preserved. Trust that section for inventory
+questions; trust the rules files for conventions. Change the target file
+with `config.agentsMd.path` in `patties.config.ts` if you'd rather the
+manifest live elsewhere.
+
+<!-- patties:manifest-start -->
+<!-- patties:manifest-end -->

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

@@ -7,25 +7,39 @@ parts of a page that need browser-side interactivity (`useState`,
 - **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:
+  default-export a React component. The framework auto-registers it,
+  bundles its client code, and serves the chunk under
+  `/_patties/client/*` (in dev via `setupDevClient`; in production via
+  `patties build`).
+- **How to use one:** import the component from a route file and
+  wrap each use-site in `<Island name="…">…</Island>` from
+  `patties/render`. The wrapper emits the `data-island` marker + props
+  sibling that the client runtime scans for — without it the markup
+  SSRs fine but never hydrates.
+
   ```tsx
+  import { Island } from "patties/render";
   import TodoApp from "../islands/TodoApp.tsx";
 
   export default function Index(): JSX.Element {
-    return <main><TodoApp /></main>;
+    return (
+      <main>
+        <Island name="TodoApp">
+          <TodoApp />
+        </Island>
+      </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.
+  `forms-Signup`). Pass the same string as `<Island name="…">`. Default
+  exports are the only export consulted.
+- **Dev mode hydrates.** `patties dev` builds islands in
+  `--mode development` (no minify), serves them, and the client runtime
+  hydrates each `[data-island]` marker. HMR reloads the page on island
+  changes.
 - **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

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

@@ -1,8 +1,3 @@
----
-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
@@ -15,15 +10,14 @@ ad-hoc Bun invocations.
 ### `patties dev` — start the dev server
 
 ```sh
-bun dev          # equivalent to `patties dev`
+bunx patties dev # the canonical invocation (bun dev runs the same thing via the package.json script)
 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.
+for `target`, `port`, env, and secrets. Islands are bundled and hydrated
+in dev — the same code path users see in production, minus minification.
 
 ### `patties build` — produce a production bundle
 
@@ -35,8 +29,10 @@ 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/server/server-entry.js`. Build also regenerates the agent
+manifest section. For Codex projects, set `config.agentsMd.path =
+"AGENTS.md"` in `patties.config.ts` so the manifest lands in the file
+Codex reads from.
 
 ### `patties start` — run the production bundle
 
@@ -45,8 +41,7 @@ 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.
+error directing you to `patties build` first.
 
 ### `patties deploy` — build then dispatch to a deploy plugin
 
@@ -90,10 +85,10 @@ the dev server reads `config.secrets`.
 **First-run sanity check after scaffolding:**
 ```sh
 bun install
-bun dev          # opens http://localhost:3000
+bunx patties dev # opens http://localhost:3000 — SSR + island hydration
 ```
 
-**Verify an island actually hydrates today (workaround until spec 18):**
+**Verify the production bundle:**
 ```sh
 bun run build
 bun start

package/templates/_codex/AGENTS.md

@@ -18,11 +18,9 @@ Built with Patties — a Bun-native full-stack meta-framework.
 
 ## Live inventory
 
-The block below is regenerated by `patties build` from the actual
-contents of `app/`. Hand-edited content above the
-`<!-- patties:generated -->` marker is preserved across regenerations;
-everything below it is owned by the generator.
+The section between the markers below is regenerated by `patties dev`
+and `patties build` from the actual contents of `app/`. Everything
+outside the markers is preserved across regenerations.
 
-<!-- patties:generated -->
-<!-- The block below is rewritten by `patties build`. Do not edit by hand. -->
-<!-- /patties:generated -->
+<!-- patties:manifest-start -->
+<!-- patties:manifest-end -->

package/templates/default/README-template.md

@@ -17,27 +17,18 @@ An interactive todo demo:
 
 ```sh
 bun install      # if you used --no-install
-bun dev          # → http://localhost:3000
+bunx patties dev # → http://localhost:3000
 ```
 
-> **Heads up — dev mode currently only does SSR.** The todo list will render
-> but the buttons won't react to clicks under `bun dev`. To see the island
-> hydrate and the demo actually work, build and serve:
->
-> ```sh
-> bun run build
-> bun start
-> ```
->
-> Full dev-mode hydration is tracked under framework spec 18 and will land
-> in a future Patties release — at that point `bun dev` will be enough.
+Dev mode SSRs the page and hydrates the island, so the todo buttons work
+immediately. HMR reloads the browser when you edit a route or island.
 
 ## Try editing
 
 1. Open `app/routes/index.tsx`, change the heading text, save. The browser
    reloads (HMR).
 2. Open `app/islands/TodoApp.tsx`, change the initial todo list or input
-   placeholder, save, rebuild with `bun run build && bun start`, and try it.
+   placeholder, save, and try it — the bundle rebuilds on the next request.
 
 ## Remove the demo when you're ready
 
@@ -73,18 +64,15 @@ A minimal hello-world Patties app:
 
 ```sh
 bun install      # if you used --no-install
-bun dev          # → http://localhost:3000
+bunx patties dev # → http://localhost:3000
 ```
 
 ## Add your first interactive feature
 
 Create `app/islands/` and drop in a component that uses `useState` or
-`useEffect`. Import it from a route file under `app/routes/`. Islands hydrate
-on the client; everything else runs server-only.
-
-> Note: full dev-mode island hydration is tracked under framework spec 18
-> and lands in a future Patties release. Until then, build + start to see
-> islands react: `bun run build && bun start`.
+`useEffect`. Import it from a route file under `app/routes/` and wrap the
+use site in `<Island name="MyIsland">…</Island>` (from `patties/render`)
+so the SSR markers are emitted and the client runtime hydrates it.
 <!-- /if -->
 
 ## Project layout
@@ -156,9 +144,10 @@ Launch a session with `claude` in this directory.
 ## Codex is set up
 
 `AGENTS.md` at the project root describes the framework conventions for
-Codex CLI and other AGENTS.md-aware tools. Patties regenerates this file on
-`patties build` while preserving sections you mark with
-`<!-- patties:user --> ... <!-- /patties:user -->`.
+Codex CLI and other AGENTS.md-aware tools. Patties regenerates the
+inventory section between `<!-- patties:manifest-start -->` and
+`<!-- patties:manifest-end -->` on every `patties dev/build` — everything
+outside those markers is yours to edit.
 
 Launch a session with `codex` in this directory.
 <!-- /if -->