@pylonsync/create-pylon 0.3.282 → 0.3.284

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.282",
+  "version": "0.3.284",
   "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"

package/templates/agency/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/agency/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/agency/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__",

package/templates/agency/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/ai-chat/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/ai-chat/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/ai-chat/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__",

package/templates/ai-chat/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/ai-studio/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/ai-studio/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/ai-studio/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__",

package/templates/ai-studio/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/barebones/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/barebones/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/barebones/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__",

package/templates/barebones/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/chat/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/chat/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/chat/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__",

package/templates/chat/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/consumer/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/consumer/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/consumer/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__",

package/templates/consumer/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/creator/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/creator/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/creator/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__",

package/templates/creator/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/default/AGENTS.md

@@ -37,6 +37,45 @@ 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` (or `.test.js`) file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`) against an in-memory Pylon. Run the whole suite with `pylon test`, or `npm test`; filter with `pylon test <substring>`. A starter test ships in `tests/example.test.ts` — replace it with your own.
+
+**Pure logic — no server needed.** Import the helper and assert. This is the cheapest, fastest shape; use it for validators, formatters, and data transforms.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Functions + the database — over HTTP against a running dev server.** A function's real behavior (policies, `ctx.db`, auth) lives in the running app, so test it the way a client calls it: start `pylon dev` in another terminal, then hit the API. Use `resetDb()` from `@pylonsync/functions` to clear the in-memory DB between cases (no-ops safely if the server isn't up, and refuses to run against 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 it shows up", async () => {
+  const created = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  expect(created.name).toBe("hello");
+
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((t: { id: string }) => t.id === created.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 |

package/templates/default/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/default/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__",