nerdsystem 0.0.0-stage → 0.0.2

package/template/.claude/skills/nerdsystem/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: nerdsystem
+description: How to build, run, and deploy this app on nerdsystem. Use whenever the task touches the API (src/server), the database schema or migrations, auth, roles, deploying, or debugging the deployed app. Covers the nerd CLI, the @nerdsystem/sdk runtime, and the platform rules that `nerd check` enforces.
+---
+
+# Building on nerdsystem
+
+This app is deployed by nerdsystem, which also provides authentication, authorization, a D1 database, and an R2 bucket. You never touch Cloudflare directly. Everything goes through the `nerd` CLI, which wraps the platform API. Every `nerd` command accepts `--json`; prefer it when you need to parse output.
+
+## First session with a new project
+
+If this project still has the template's todo app (the `todos` table and `src/server/routes/todos.ts`), treat the person as new and offer a short walkthrough before building anything:
+
+1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
+2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
+5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
+6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
+
+Throughout, show commands rather than describing them, and never ask the person to edit config files; the platform owns `wrangler.jsonc` and `nerd.json`.
+
+## The loop
+
+1. Make the change.
+2. `nerd check` (static rules, then typecheck). Fix anything it reports.
+3. `nerd dev` to run locally when you need to try it. The local app talks to the real auth service, so signup and login work exactly as in production.
+4. `nerd deploy` when it is ready. It runs the checks, builds, applies pending migrations, uploads, and prints the URL.
+5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
+
+Run `nerd check --json` when you want a machine-readable list of problems.
+
+## Deploying from GitHub
+
+Once the repo is linked (`nerd github connect`, then `nerd github link owner/repo`), every push to the production branch builds and deploys automatically, and every pull request gets a preview at its own URL, posted as a PR comment. `nerd builds` lists builds; `nerd builds show <id>` prints the log when one fails. A failing build reports the same `nerd check` problems you would see locally, so fix and push again. Previews share the production database and do not run migrations; a PR that changes the schema will only work in full after it merges.
+
+## Where things go
+
+| Concern | Location |
+| --- | --- |
+| API routes | `src/server/index.ts` mounts routers under `/api/...`. Put each resource in `src/server/routes/<name>.ts`. |
+| Database schema | `src/server/db/schema.ts` (Drizzle). Then `pnpm db:generate` to produce a migration in `migrations/`. |
+| Queries | `db(c.env.DB)` from `src/server/db/index.ts`. Drizzle query builder, D1 dialect (SQLite). |
+| Files | `c.env.STORAGE` is an R2 bucket. `put`, `get`, `delete`, `list`. Key files by user id. |
+| Frontend | `src/client/` React, built by Vite. `src/client/api.ts` has a fetch wrapper that sends the session cookie. |
+| Roles and signup policy | `nerd auth config`. Not in code. |
+
+## Auth and authorization
+
+The SDK handles sessions. There is no login code to write.
+
+- `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
+- `requireAuth()` middleware returns 401 when signed out.
+- `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
+- To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
+
+Example of a protected resource router:
+
+```ts
+import { Hono } from "hono";
+import { eq } from "drizzle-orm";
+import { requireAuth, type NerdHonoEnv } from "@nerdsystem/sdk";
+import { db, schema } from "../db";
+
+const notes = new Hono<NerdHonoEnv>();
+notes.use("*", requireAuth());
+notes.get("/", async (c) => {
+  const rows = await db(c.env.DB).select().from(schema.notes).where(eq(schema.notes.userId, c.var.user!.id)).all();
+  return c.json({ notes: rows });
+});
+export default notes;
+```
+
+Then in `src/server/index.ts`: `app.route("/api/notes", notes);`
+
+## Data rules
+
+- Every table holding user data has a `user_id` text column, and every read and write filters on `c.var.user.id`. This is how users are kept apart.
+- Schema changes are migrations. Edit `schema.ts`, run `pnpm db:generate`, commit the new file in `migrations/`. Never hand-write SQL into production; `nerd deploy` applies migrations in name order and records which ran.
+- Migrations are forward-only. To undo, write another migration.
+- Prefer small, additive migrations. SQLite cannot alter columns in place.
+
+## Errors
+
+API errors are `{ error: { code, message } }` with a matching HTTP status. Use the same shape in your routes so the frontend's `ApiError` keeps working. Codes in use: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `internal`.
+
+## Security gates
+
+The `nerdsystem` MCP server (configured in `.mcp.json`) gives you two tools; prefer them over shelling out:
+
+- `run_gates` runs every gate a deploy runs (secrets in source and in the built bundle, vulnerable dependencies, platform rules, static analysis, acceptable-use policy, personal-data heuristics, typecheck, and scanner suppressions) and returns `failures`. Each has `rule_id`, `file`, `line`, `risk` (what could happen), `fix` (what to change), `verify` (the command that confirms it), `attempt`, and `audience`.
+- `explain_failure` takes a `rule_id` and returns the risk, the fix, and a wrong/right example.
+
+The loop: run `run_gates`, fix every failure with `audience: "agent"`, run `run_gates` again (it re-runs every gate, not just the one that failed), repeat. Rules you cannot clear:
+
+- `audience: "human"` means a person must act: a secret that was committed must be rotated at the provider before you remove it; an ignore comment, ignore file, or gate setting you added is a suppression that only a person can approve in the dashboard. Never add `nosemgrep`, `gitleaks:allow`, `nerd-ignore`, or a `gates` key in `nerd.json` to make a finding go away.
+- When `stop` is non-empty, the same rule has failed three runs in a row. Stop, summarize what you tried in plain words, and hand it to the person.
+
+Without MCP, `nerd verify --json` returns the same shape, and `nerd verify --rule <rule_id>` runs one rule. Secrets are reported masked (`sk_live_****4f2a`); never print a credential yourself. Keep secrets in `.dev.vars` locally and in platform settings in production; never prefix a secret with `VITE_`, because those values are compiled into the public client bundle.
+
+## What `nerd check` rejects
+
+- A root app that is not `createNerdApp()` from `@nerdsystem/sdk`.
+- Any route outside `/api/`. Other paths serve the static client and never reach the Worker.
+- New bindings in `wrangler.jsonc`. Only `DB`, `STORAGE`, and `ASSETS` exist. Durable Objects are not available.
+- Scripts that call `wrangler deploy`, `wrangler secret`, or remote `wrangler d1` commands.
+- Typecheck failures in either `src/server` or `src/client`.
+
+## Scheduled jobs and email
+
+- **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.
+- **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
+- **Email**: `sendEmail(c.env, { to, subject, text, html? })` from `@nerdsystem/sdk` sends through the platform. It is limited per day by plan (50 on Free, 2,000 on Pro at $39 a month, 10,000 on Studio), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price.
+
+## Debugging production
+
+When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.
+
+## Not available yet
+
+Queues, Durable Objects, and log streaming. If the task needs one, say so instead of working around it with an unsupported binding.

package/template/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nerdsystem": {
+      "command": "npx",
+      "args": ["-y", "@nerdsystem/mcp"]
+    }
+  }
+}

package/template/.cursor/rules/nerdsystem.mdc

@@ -0,0 +1,124 @@
+---
+description: How to build, run, and deploy this app on nerdsystem. Applies to server, database, auth, and deploy work.
+alwaysApply: true
+---
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+
+# Building on nerdsystem
+
+This app is deployed by nerdsystem, which also provides authentication, authorization, a D1 database, and an R2 bucket. You never touch Cloudflare directly. Everything goes through the `nerd` CLI, which wraps the platform API. Every `nerd` command accepts `--json`; prefer it when you need to parse output.
+
+## First session with a new project
+
+If this project still has the template's todo app (the `todos` table and `src/server/routes/todos.ts`), treat the person as new and offer a short walkthrough before building anything:
+
+1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
+2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
+5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
+6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
+
+Throughout, show commands rather than describing them, and never ask the person to edit config files; the platform owns `wrangler.jsonc` and `nerd.json`.
+
+## The loop
+
+1. Make the change.
+2. `nerd check` (static rules, then typecheck). Fix anything it reports.
+3. `nerd dev` to run locally when you need to try it. The local app talks to the real auth service, so signup and login work exactly as in production.
+4. `nerd deploy` when it is ready. It runs the checks, builds, applies pending migrations, uploads, and prints the URL.
+5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
+
+Run `nerd check --json` when you want a machine-readable list of problems.
+
+## Deploying from GitHub
+
+Once the repo is linked (`nerd github connect`, then `nerd github link owner/repo`), every push to the production branch builds and deploys automatically, and every pull request gets a preview at its own URL, posted as a PR comment. `nerd builds` lists builds; `nerd builds show <id>` prints the log when one fails. A failing build reports the same `nerd check` problems you would see locally, so fix and push again. Previews share the production database and do not run migrations; a PR that changes the schema will only work in full after it merges.
+
+## Where things go
+
+| Concern | Location |
+| --- | --- |
+| API routes | `src/server/index.ts` mounts routers under `/api/...`. Put each resource in `src/server/routes/<name>.ts`. |
+| Database schema | `src/server/db/schema.ts` (Drizzle). Then `pnpm db:generate` to produce a migration in `migrations/`. |
+| Queries | `db(c.env.DB)` from `src/server/db/index.ts`. Drizzle query builder, D1 dialect (SQLite). |
+| Files | `c.env.STORAGE` is an R2 bucket. `put`, `get`, `delete`, `list`. Key files by user id. |
+| Frontend | `src/client/` React, built by Vite. `src/client/api.ts` has a fetch wrapper that sends the session cookie. |
+| Roles and signup policy | `nerd auth config`. Not in code. |
+
+## Auth and authorization
+
+The SDK handles sessions. There is no login code to write.
+
+- `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
+- `requireAuth()` middleware returns 401 when signed out.
+- `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
+- To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
+
+Example of a protected resource router:
+
+```ts
+import { Hono } from "hono";
+import { eq } from "drizzle-orm";
+import { requireAuth, type NerdHonoEnv } from "@nerdsystem/sdk";
+import { db, schema } from "../db";
+
+const notes = new Hono<NerdHonoEnv>();
+notes.use("*", requireAuth());
+notes.get("/", async (c) => {
+  const rows = await db(c.env.DB).select().from(schema.notes).where(eq(schema.notes.userId, c.var.user!.id)).all();
+  return c.json({ notes: rows });
+});
+export default notes;
+```
+
+Then in `src/server/index.ts`: `app.route("/api/notes", notes);`
+
+## Data rules
+
+- Every table holding user data has a `user_id` text column, and every read and write filters on `c.var.user.id`. This is how users are kept apart.
+- Schema changes are migrations. Edit `schema.ts`, run `pnpm db:generate`, commit the new file in `migrations/`. Never hand-write SQL into production; `nerd deploy` applies migrations in name order and records which ran.
+- Migrations are forward-only. To undo, write another migration.
+- Prefer small, additive migrations. SQLite cannot alter columns in place.
+
+## Errors
+
+API errors are `{ error: { code, message } }` with a matching HTTP status. Use the same shape in your routes so the frontend's `ApiError` keeps working. Codes in use: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `internal`.
+
+## Security gates
+
+The `nerdsystem` MCP server (configured in `.mcp.json`) gives you two tools; prefer them over shelling out:
+
+- `run_gates` runs every gate a deploy runs (secrets in source and in the built bundle, vulnerable dependencies, platform rules, static analysis, acceptable-use policy, personal-data heuristics, typecheck, and scanner suppressions) and returns `failures`. Each has `rule_id`, `file`, `line`, `risk` (what could happen), `fix` (what to change), `verify` (the command that confirms it), `attempt`, and `audience`.
+- `explain_failure` takes a `rule_id` and returns the risk, the fix, and a wrong/right example.
+
+The loop: run `run_gates`, fix every failure with `audience: "agent"`, run `run_gates` again (it re-runs every gate, not just the one that failed), repeat. Rules you cannot clear:
+
+- `audience: "human"` means a person must act: a secret that was committed must be rotated at the provider before you remove it; an ignore comment, ignore file, or gate setting you added is a suppression that only a person can approve in the dashboard. Never add `nosemgrep`, `gitleaks:allow`, `nerd-ignore`, or a `gates` key in `nerd.json` to make a finding go away.
+- When `stop` is non-empty, the same rule has failed three runs in a row. Stop, summarize what you tried in plain words, and hand it to the person.
+
+Without MCP, `nerd verify --json` returns the same shape, and `nerd verify --rule <rule_id>` runs one rule. Secrets are reported masked (`sk_live_****4f2a`); never print a credential yourself. Keep secrets in `.dev.vars` locally and in platform settings in production; never prefix a secret with `VITE_`, because those values are compiled into the public client bundle.
+
+## What `nerd check` rejects
+
+- A root app that is not `createNerdApp()` from `@nerdsystem/sdk`.
+- Any route outside `/api/`. Other paths serve the static client and never reach the Worker.
+- New bindings in `wrangler.jsonc`. Only `DB`, `STORAGE`, and `ASSETS` exist. Durable Objects are not available.
+- Scripts that call `wrangler deploy`, `wrangler secret`, or remote `wrangler d1` commands.
+- Typecheck failures in either `src/server` or `src/client`.
+
+## Scheduled jobs and email
+
+- **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.
+- **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
+- **Email**: `sendEmail(c.env, { to, subject, text, html? })` from `@nerdsystem/sdk` sends through the platform. It is limited per day by plan (50 on Free, 2,000 on Pro at $39 a month, 10,000 on Studio), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price.
+
+## Debugging production
+
+When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.
+
+## Not available yet
+
+Queues, Durable Objects, and log streaming. If the task needs one, say so instead of working around it with an unsupported binding.

package/template/.gemini/settings.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nerdsystem": {
+      "command": "npx",
+      "args": ["-y", "@nerdsystem/mcp"]
+    }
+  }
+}

package/template/.github/copilot-instructions.md

@@ -0,0 +1,120 @@
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+
+# Building on nerdsystem
+
+This app is deployed by nerdsystem, which also provides authentication, authorization, a D1 database, and an R2 bucket. You never touch Cloudflare directly. Everything goes through the `nerd` CLI, which wraps the platform API. Every `nerd` command accepts `--json`; prefer it when you need to parse output.
+
+## First session with a new project
+
+If this project still has the template's todo app (the `todos` table and `src/server/routes/todos.ts`), treat the person as new and offer a short walkthrough before building anything:
+
+1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
+2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
+5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
+6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
+
+Throughout, show commands rather than describing them, and never ask the person to edit config files; the platform owns `wrangler.jsonc` and `nerd.json`.
+
+## The loop
+
+1. Make the change.
+2. `nerd check` (static rules, then typecheck). Fix anything it reports.
+3. `nerd dev` to run locally when you need to try it. The local app talks to the real auth service, so signup and login work exactly as in production.
+4. `nerd deploy` when it is ready. It runs the checks, builds, applies pending migrations, uploads, and prints the URL.
+5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
+
+Run `nerd check --json` when you want a machine-readable list of problems.
+
+## Deploying from GitHub
+
+Once the repo is linked (`nerd github connect`, then `nerd github link owner/repo`), every push to the production branch builds and deploys automatically, and every pull request gets a preview at its own URL, posted as a PR comment. `nerd builds` lists builds; `nerd builds show <id>` prints the log when one fails. A failing build reports the same `nerd check` problems you would see locally, so fix and push again. Previews share the production database and do not run migrations; a PR that changes the schema will only work in full after it merges.
+
+## Where things go
+
+| Concern | Location |
+| --- | --- |
+| API routes | `src/server/index.ts` mounts routers under `/api/...`. Put each resource in `src/server/routes/<name>.ts`. |
+| Database schema | `src/server/db/schema.ts` (Drizzle). Then `pnpm db:generate` to produce a migration in `migrations/`. |
+| Queries | `db(c.env.DB)` from `src/server/db/index.ts`. Drizzle query builder, D1 dialect (SQLite). |
+| Files | `c.env.STORAGE` is an R2 bucket. `put`, `get`, `delete`, `list`. Key files by user id. |
+| Frontend | `src/client/` React, built by Vite. `src/client/api.ts` has a fetch wrapper that sends the session cookie. |
+| Roles and signup policy | `nerd auth config`. Not in code. |
+
+## Auth and authorization
+
+The SDK handles sessions. There is no login code to write.
+
+- `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
+- `requireAuth()` middleware returns 401 when signed out.
+- `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
+- To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
+
+Example of a protected resource router:
+
+```ts
+import { Hono } from "hono";
+import { eq } from "drizzle-orm";
+import { requireAuth, type NerdHonoEnv } from "@nerdsystem/sdk";
+import { db, schema } from "../db";
+
+const notes = new Hono<NerdHonoEnv>();
+notes.use("*", requireAuth());
+notes.get("/", async (c) => {
+  const rows = await db(c.env.DB).select().from(schema.notes).where(eq(schema.notes.userId, c.var.user!.id)).all();
+  return c.json({ notes: rows });
+});
+export default notes;
+```
+
+Then in `src/server/index.ts`: `app.route("/api/notes", notes);`
+
+## Data rules
+
+- Every table holding user data has a `user_id` text column, and every read and write filters on `c.var.user.id`. This is how users are kept apart.
+- Schema changes are migrations. Edit `schema.ts`, run `pnpm db:generate`, commit the new file in `migrations/`. Never hand-write SQL into production; `nerd deploy` applies migrations in name order and records which ran.
+- Migrations are forward-only. To undo, write another migration.
+- Prefer small, additive migrations. SQLite cannot alter columns in place.
+
+## Errors
+
+API errors are `{ error: { code, message } }` with a matching HTTP status. Use the same shape in your routes so the frontend's `ApiError` keeps working. Codes in use: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `internal`.
+
+## Security gates
+
+The `nerdsystem` MCP server (configured in `.mcp.json`) gives you two tools; prefer them over shelling out:
+
+- `run_gates` runs every gate a deploy runs (secrets in source and in the built bundle, vulnerable dependencies, platform rules, static analysis, acceptable-use policy, personal-data heuristics, typecheck, and scanner suppressions) and returns `failures`. Each has `rule_id`, `file`, `line`, `risk` (what could happen), `fix` (what to change), `verify` (the command that confirms it), `attempt`, and `audience`.
+- `explain_failure` takes a `rule_id` and returns the risk, the fix, and a wrong/right example.
+
+The loop: run `run_gates`, fix every failure with `audience: "agent"`, run `run_gates` again (it re-runs every gate, not just the one that failed), repeat. Rules you cannot clear:
+
+- `audience: "human"` means a person must act: a secret that was committed must be rotated at the provider before you remove it; an ignore comment, ignore file, or gate setting you added is a suppression that only a person can approve in the dashboard. Never add `nosemgrep`, `gitleaks:allow`, `nerd-ignore`, or a `gates` key in `nerd.json` to make a finding go away.
+- When `stop` is non-empty, the same rule has failed three runs in a row. Stop, summarize what you tried in plain words, and hand it to the person.
+
+Without MCP, `nerd verify --json` returns the same shape, and `nerd verify --rule <rule_id>` runs one rule. Secrets are reported masked (`sk_live_****4f2a`); never print a credential yourself. Keep secrets in `.dev.vars` locally and in platform settings in production; never prefix a secret with `VITE_`, because those values are compiled into the public client bundle.
+
+## What `nerd check` rejects
+
+- A root app that is not `createNerdApp()` from `@nerdsystem/sdk`.
+- Any route outside `/api/`. Other paths serve the static client and never reach the Worker.
+- New bindings in `wrangler.jsonc`. Only `DB`, `STORAGE`, and `ASSETS` exist. Durable Objects are not available.
+- Scripts that call `wrangler deploy`, `wrangler secret`, or remote `wrangler d1` commands.
+- Typecheck failures in either `src/server` or `src/client`.
+
+## Scheduled jobs and email
+
+- **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.
+- **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
+- **Email**: `sendEmail(c.env, { to, subject, text, html? })` from `@nerdsystem/sdk` sends through the platform. It is limited per day by plan (50 on Free, 2,000 on Pro at $39 a month, 10,000 on Studio), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price.
+
+## Debugging production
+
+When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.
+
+## Not available yet
+
+Queues, Durable Objects, and log streaming. If the task needs one, say so instead of working around it with an unsupported binding.

package/template/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# Keeps dependencies current. Each update arrives as a pull request, which nerdsystem builds,
+# scans, and previews before you merge it. Minor and patch bumps are grouped into one weekly PR;
+# security updates come separately so they stand out.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    groups:
+      minor-and-patch:
+        update-types: [minor, patch]

package/template/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nerdsystem": {
+      "command": "npx",
+      "args": ["-y", "@nerdsystem/mcp"]
+    }
+  }
+}

package/template/.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "nerdsystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@nerdsystem/mcp"]
+    }
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,120 @@
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2834c4c81f7f); edit the skill, then run: nerd agents sync -->
+
+# Building on nerdsystem
+
+This app is deployed by nerdsystem, which also provides authentication, authorization, a D1 database, and an R2 bucket. You never touch Cloudflare directly. Everything goes through the `nerd` CLI, which wraps the platform API. Every `nerd` command accepts `--json`; prefer it when you need to parse output.
+
+## First session with a new project
+
+If this project still has the template's todo app (the `todos` table and `src/server/routes/todos.ts`), treat the person as new and offer a short walkthrough before building anything:
+
+1. Ask one question: what should the app do, in a sentence or two. Do not ask about stacks, databases, or hosting; those are decided.
+2. Say what you will build first, in plain words: the one table and the one screen that make the idea real. Keep the first feature small enough to deploy within the session.
+3. Replace the todo example with that feature: schema, migration (`pnpm db:generate`), a router under `/api/...`, and the client screen. Keep signup and login as they are; they already work.
+4. Run `nerd check`, then `nerd dev`, and tell the person to open the local URL, create an account, and try it. Fix what they report.
+5. Run `nerd deploy` and give them the live URL. Explain in two lines that every deploy is checked for leaked secrets and vulnerable dependencies, and that they can run `nerd verify` any time.
+6. Offer the next steps once, briefly: link the GitHub repo for previews on pull requests (`nerd github connect`), add a custom domain, or invite a teammate from the dashboard.
+
+Throughout, show commands rather than describing them, and never ask the person to edit config files; the platform owns `wrangler.jsonc` and `nerd.json`.
+
+## The loop
+
+1. Make the change.
+2. `nerd check` (static rules, then typecheck). Fix anything it reports.
+3. `nerd dev` to run locally when you need to try it. The local app talks to the real auth service, so signup and login work exactly as in production.
+4. `nerd deploy` when it is ready. It runs the checks, builds, applies pending migrations, uploads, and prints the URL.
+5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
+
+Run `nerd check --json` when you want a machine-readable list of problems.
+
+## Deploying from GitHub
+
+Once the repo is linked (`nerd github connect`, then `nerd github link owner/repo`), every push to the production branch builds and deploys automatically, and every pull request gets a preview at its own URL, posted as a PR comment. `nerd builds` lists builds; `nerd builds show <id>` prints the log when one fails. A failing build reports the same `nerd check` problems you would see locally, so fix and push again. Previews share the production database and do not run migrations; a PR that changes the schema will only work in full after it merges.
+
+## Where things go
+
+| Concern | Location |
+| --- | --- |
+| API routes | `src/server/index.ts` mounts routers under `/api/...`. Put each resource in `src/server/routes/<name>.ts`. |
+| Database schema | `src/server/db/schema.ts` (Drizzle). Then `pnpm db:generate` to produce a migration in `migrations/`. |
+| Queries | `db(c.env.DB)` from `src/server/db/index.ts`. Drizzle query builder, D1 dialect (SQLite). |
+| Files | `c.env.STORAGE` is an R2 bucket. `put`, `get`, `delete`, `list`. Key files by user id. |
+| Frontend | `src/client/` React, built by Vite. `src/client/api.ts` has a fetch wrapper that sends the session cookie. |
+| Roles and signup policy | `nerd auth config`. Not in code. |
+
+## Auth and authorization
+
+The SDK handles sessions. There is no login code to write.
+
+- `c.var.user` is `{ id, email, name, roles }` or `null` on every request.
+- `requireAuth()` middleware returns 401 when signed out.
+- `requireRole("admin")` returns 403 unless the user has one of the given roles. Multiple roles are OR.
+- The frontend calls `/api/auth/signup`, `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/forgot`, and `/api/auth/reset`. The template's `auth` helper in `src/client/api.ts` wraps them. Password reset emails link to `/reset-password?token=...`, which the template client renders; keep that route if you restructure the client.
+- Roles are a list the platform owns. See the current list with `nerd auth config`. Add one with `nerd auth config --roles admin,member,editor`. The default role for new signups is set with `--default-role`. Turn public signup off with `--signup off`.
+- To promote a user from code, use the admin client: `new AuthServiceClient(c.env).users.setRoles(userId, ["admin"])`. Guard that route with `requireRole("admin")`.
+
+Example of a protected resource router:
+
+```ts
+import { Hono } from "hono";
+import { eq } from "drizzle-orm";
+import { requireAuth, type NerdHonoEnv } from "@nerdsystem/sdk";
+import { db, schema } from "../db";
+
+const notes = new Hono<NerdHonoEnv>();
+notes.use("*", requireAuth());
+notes.get("/", async (c) => {
+  const rows = await db(c.env.DB).select().from(schema.notes).where(eq(schema.notes.userId, c.var.user!.id)).all();
+  return c.json({ notes: rows });
+});
+export default notes;
+```
+
+Then in `src/server/index.ts`: `app.route("/api/notes", notes);`
+
+## Data rules
+
+- Every table holding user data has a `user_id` text column, and every read and write filters on `c.var.user.id`. This is how users are kept apart.
+- Schema changes are migrations. Edit `schema.ts`, run `pnpm db:generate`, commit the new file in `migrations/`. Never hand-write SQL into production; `nerd deploy` applies migrations in name order and records which ran.
+- Migrations are forward-only. To undo, write another migration.
+- Prefer small, additive migrations. SQLite cannot alter columns in place.
+
+## Errors
+
+API errors are `{ error: { code, message } }` with a matching HTTP status. Use the same shape in your routes so the frontend's `ApiError` keeps working. Codes in use: `bad_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `internal`.
+
+## Security gates
+
+The `nerdsystem` MCP server (configured in `.mcp.json`) gives you two tools; prefer them over shelling out:
+
+- `run_gates` runs every gate a deploy runs (secrets in source and in the built bundle, vulnerable dependencies, platform rules, static analysis, acceptable-use policy, personal-data heuristics, typecheck, and scanner suppressions) and returns `failures`. Each has `rule_id`, `file`, `line`, `risk` (what could happen), `fix` (what to change), `verify` (the command that confirms it), `attempt`, and `audience`.
+- `explain_failure` takes a `rule_id` and returns the risk, the fix, and a wrong/right example.
+
+The loop: run `run_gates`, fix every failure with `audience: "agent"`, run `run_gates` again (it re-runs every gate, not just the one that failed), repeat. Rules you cannot clear:
+
+- `audience: "human"` means a person must act: a secret that was committed must be rotated at the provider before you remove it; an ignore comment, ignore file, or gate setting you added is a suppression that only a person can approve in the dashboard. Never add `nosemgrep`, `gitleaks:allow`, `nerd-ignore`, or a `gates` key in `nerd.json` to make a finding go away.
+- When `stop` is non-empty, the same rule has failed three runs in a row. Stop, summarize what you tried in plain words, and hand it to the person.
+
+Without MCP, `nerd verify --json` returns the same shape, and `nerd verify --rule <rule_id>` runs one rule. Secrets are reported masked (`sk_live_****4f2a`); never print a credential yourself. Keep secrets in `.dev.vars` locally and in platform settings in production; never prefix a secret with `VITE_`, because those values are compiled into the public client bundle.
+
+## What `nerd check` rejects
+
+- A root app that is not `createNerdApp()` from `@nerdsystem/sdk`.
+- Any route outside `/api/`. Other paths serve the static client and never reach the Worker.
+- New bindings in `wrangler.jsonc`. Only `DB`, `STORAGE`, and `ASSETS` exist. Durable Objects are not available.
+- Scripts that call `wrangler deploy`, `wrangler secret`, or remote `wrangler d1` commands.
+- Typecheck failures in either `src/server` or `src/client`.
+
+## Scheduled jobs and email
+
+- **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.
+- **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
+- **Email**: `sendEmail(c.env, { to, subject, text, html? })` from `@nerdsystem/sdk` sends through the platform. It is limited per day by plan (50 on Free, 2,000 on Pro at $39 a month, 10,000 on Studio), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price.
+
+## Debugging production
+
+When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.
+
+## Not available yet
+
+Queues, Durable Objects, and log streaming. If the task needs one, say so instead of working around it with an unsupported binding.

package/template/CLAUDE.md

@@ -0,0 +1,32 @@
+# This app runs on nerdsystem
+
+nerdsystem deploys this app to Cloudflare and provides authentication and authorization. Work within these boundaries and `nerd check` will pass. The `nerdsystem` skill in `.claude/skills/` has the full workflow and code examples; load it for anything touching the server, database, auth, or deploys. `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, and `.github/copilot-instructions.md` are generated copies of it for other agents; edit the skill and run `nerd agents sync`.
+
+## Commands
+
+- `nerd dev` starts the app locally with a real session flow against the platform auth service.
+- `nerd check` typechecks both sides and verifies the platform rules below. Run it before `nerd deploy`.
+- `nerd deploy` builds, applies pending migrations to the production database, and ships the app. Prints the URL.
+- `nerd db query "select ..."` runs SQL against the production database. `nerd deployments` lists recent deploys.
+- With a linked GitHub repo, pushes to the production branch and pull requests deploy automatically. `nerd builds` and `nerd builds show <id>` show what happened.
+- `pnpm db:generate` creates a migration after editing `src/server/db/schema.ts`. Never edit the database by hand.
+
+## Layout
+
+- `src/server/index.ts` is the Worker entry. Build the API here with Hono; mount routers under `/api/...`.
+- `src/client/` is the React app, built by Vite and served as static assets for every path outside `/api`.
+- `src/server/db/schema.ts` is the Drizzle schema for the app's D1 database (`c.env.DB`). Files go in `c.env.STORAGE` (R2).
+
+## Rules the platform enforces
+
+1. Keep `createNerdApp()` from `@nerdsystem/sdk` as the app's root. Do not replace it with a bare Hono instance.
+2. Authentication is handled by the SDK. Do not write login, signup, password, or token code. Use `c.var.user`, `requireAuth()`, and `requireRole("admin")`.
+3. Every table that stores user data carries a `user_id` column, and every query filters by `c.var.user.id`. Users must never see each other's rows.
+4. Database changes go through Drizzle migrations in `migrations/`. `nerd deploy` applies them.
+5. Keep every API route under `/api/`. Other paths are served from static assets and never reach the Worker.
+6. Do not add Cloudflare bindings to `wrangler.jsonc`, and do not run `wrangler deploy`. Bindings are provisioned by the platform.
+7. Secrets and environment variables for the deployed app are managed with `nerd` commands, never committed.
+
+## Roles
+
+The platform owns the list of roles and which users hold them. The default roles are `admin` and `member`; new signups get `member`. Change the list with `nerd auth config --roles admin,member,editor`. In code, gate with `requireRole("admin")` or check `c.var.user.roles`.