@pylonsync/create-pylon 0.3.283 → 0.3.285

package/templates/directory/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -37,6 +37,61 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
 
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
+
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe — it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
 ## Use the CLI — don't guess
 
 | Need | Command |
@@ -58,4 +113,4 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/directory/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Agent guidance for this Pylon project lives in **AGENTS.md** — the cross-editor
+standard that Claude Code, Cursor, Codex, and others all read. It's imported
+below so Claude Code picks it up automatically:
+
+@AGENTS.md

package/templates/directory/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "pylon dev",
     "deploy": "pylon deploy",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "pylon test"
   },
   "dependencies": {
     "@pylonsync/react": "^__PYLON_VERSION__",
@@ -26,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/directory/tests/button.test.tsx

@@ -0,0 +1,16 @@
+import { afterEach, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../components/ui/button";
+
+afterEach(cleanup);
+
+// A React component test. happy-dom + @testing-library/react are wired via
+// bunfig.toml — render a component and assert on the DOM. For a component that
+// reads Pylon data hooks (db.useQuery, callFn), mock the boundary first — see
+// AGENTS.md → Testing (Tier 2).
+test("Button renders its label", () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole("button", { name: "Click me" })).toBeDefined();
+});

package/templates/directory/tests/example.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+
+// Your first test. Run the suite with:  pylon test  (or: npm test)
+//
+// `pylon test` discovers every *.test.ts file under tests/ (or functions/) and
+// runs it with Bun's test runner against an in-memory Pylon. Replace this
+// placeholder with tests for your functions and helpers — see AGENTS.md →
+// Testing for the pure-logic and HTTP-against-`pylon dev` patterns.
+
+test("placeholder — replace me with a real test", () => {
+  expect(true).toBe(true);
+});

package/templates/directory/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/local-service/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -37,6 +37,61 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
 
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
+
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe — it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
 ## Use the CLI — don't guess
 
 | Need | Command |
@@ -58,4 +113,4 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/local-service/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Agent guidance for this Pylon project lives in **AGENTS.md** — the cross-editor
+standard that Claude Code, Cursor, Codex, and others all read. It's imported
+below so Claude Code picks it up automatically:
+
+@AGENTS.md

package/templates/local-service/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "pylon dev",
     "deploy": "pylon deploy",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "pylon test"
   },
   "dependencies": {
     "@pylonsync/react": "^__PYLON_VERSION__",
@@ -26,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/local-service/tests/button.test.tsx

@@ -0,0 +1,16 @@
+import { afterEach, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../components/ui/button";
+
+afterEach(cleanup);
+
+// A React component test. happy-dom + @testing-library/react are wired via
+// bunfig.toml — render a component and assert on the DOM. For a component that
+// reads Pylon data hooks (db.useQuery, callFn), mock the boundary first — see
+// AGENTS.md → Testing (Tier 2).
+test("Button renders its label", () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole("button", { name: "Click me" })).toBeDefined();
+});

package/templates/local-service/tests/example.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+
+// Your first test. Run the suite with:  pylon test  (or: npm test)
+//
+// `pylon test` discovers every *.test.ts file under tests/ (or functions/) and
+// runs it with Bun's test runner against an in-memory Pylon. Replace this
+// placeholder with tests for your functions and helpers — see AGENTS.md →
+// Testing for the pure-logic and HTTP-against-`pylon dev` patterns.
+
+test("placeholder — replace me with a real test", () => {
+  expect(true).toBe(true);
+});

package/templates/local-service/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/marketplace/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -37,6 +37,61 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
 
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
+
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe — it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
 ## Use the CLI — don't guess
 
 | Need | Command |
@@ -58,4 +113,4 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/marketplace/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Agent guidance for this Pylon project lives in **AGENTS.md** — the cross-editor
+standard that Claude Code, Cursor, Codex, and others all read. It's imported
+below so Claude Code picks it up automatically:
+
+@AGENTS.md

package/templates/marketplace/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "pylon dev",
     "deploy": "pylon deploy",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "pylon test"
   },
   "dependencies": {
     "@pylonsync/react": "^__PYLON_VERSION__",
@@ -27,6 +28,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/marketplace/tests/example.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+
+// Your first test. Run the suite with:  pylon test  (or: npm test)
+//
+// `pylon test` discovers every *.test.ts file under tests/ (or functions/) and
+// runs it with Bun's test runner against an in-memory Pylon. Replace this
+// placeholder with tests for your functions and helpers — see AGENTS.md →
+// Testing for the pure-logic and HTTP-against-`pylon dev` patterns.
+
+test("placeholder — replace me with a real test", () => {
+  expect(true).toBe(true);
+});

package/templates/marketplace/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/restaurant/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -37,6 +37,61 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
 
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
+
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe — it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
 ## Use the CLI — don't guess
 
 | Need | Command |
@@ -58,4 +113,4 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/restaurant/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Agent guidance for this Pylon project lives in **AGENTS.md** — the cross-editor
+standard that Claude Code, Cursor, Codex, and others all read. It's imported
+below so Claude Code picks it up automatically:
+
+@AGENTS.md

package/templates/restaurant/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "pylon dev",
     "deploy": "pylon deploy",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "pylon test"
   },
   "dependencies": {
     "@pylonsync/react": "^__PYLON_VERSION__",
@@ -26,6 +27,9 @@
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/templates/restaurant/tests/button.test.tsx

@@ -0,0 +1,16 @@
+import { afterEach, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../components/ui/button";
+
+afterEach(cleanup);
+
+// A React component test. happy-dom + @testing-library/react are wired via
+// bunfig.toml — render a component and assert on the DOM. For a component that
+// reads Pylon data hooks (db.useQuery, callFn), mock the boundary first — see
+// AGENTS.md → Testing (Tier 2).
+test("Button renders its label", () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole("button", { name: "Click me" })).toBeDefined();
+});

package/templates/restaurant/tests/example.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+
+// Your first test. Run the suite with:  pylon test  (or: npm test)
+//
+// `pylon test` discovers every *.test.ts file under tests/ (or functions/) and
+// runs it with Bun's test runner against an in-memory Pylon. Replace this
+// placeholder with tests for your functions and helpers — see AGENTS.md →
+// Testing for the pure-logic and HTTP-against-`pylon dev` patterns.
+
+test("placeholder — replace me with a real test", () => {
+  expect(true).toBe(true);
+});

package/templates/restaurant/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();

package/templates/shop/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt. Read it before guessing an API name.
 
 ## Directory conventions
 
@@ -37,6 +37,61 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
 
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
+
+**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe — it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
 ## Use the CLI — don't guess
 
 | Need | Command |
@@ -58,4 +113,4 @@ Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like fram
 
 `--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
 
-For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **/llms-full.txt**.
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.