create-nifra 3.5.0 → 4.0.2

package/README.md

@@ -11,11 +11,11 @@ bun create nifra my-app
 
 `--template <name>` (default `api`):
 
-- **`api`** - a typed nifra server (`src/app.ts` + `src/index.ts`) with an example test and
+- **`api`** - a typed nifra server (`backend/app.ts` + `backend/index.ts`) with an example test and
   `dev`/`start`/`test`/`typecheck` scripts.
 - **`site`** - the full-stack template: a nifra + React SSR site (file-routed frontend + typed
-  `backend.ts`), one source deployable to Cloudflare Pages, Node, Deno, or Vercel Edge. Pick the
-  frontend with `--framework react|preact|vue|solid|svelte`.
+  `backend/app.ts`) for one deploy target, `--target bun|node|deno|cloudflare|vercel` (default `bun`).
+  Pick the frontend with `--framework react|preact|vue|solid|svelte`.
 - **`isr`** - a nifra + React app with **Incremental Static Regeneration** on Cloudflare Workers + KV
   (pages cached + served stale-while-revalidate; on-demand purge endpoint).
 - **`batteries`** - the `api` starter plus the batteries a real API needs: background jobs

package/dist/agent-files.d.ts

@@ -1,25 +1,24 @@
 /**
- * The canonical generators for the agent-discovery files an app ships so a coding agent auto-discovers
- * the project's nifra MCP server and prefers it over writing nifra from memory:
+ * The canonical generators for the agent files an app ships. `AGENTS.md` is the single source of agent
+ * guidance; every other agent's file is a thin pointer to it, so no two copies can drift:
  *
- *   .mcp.json          - Claude Code's project MCP registry  ({ mcpServers: { nifra: { command, args } } })
- *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
- *   CLAUDE.md          - Claude's preamble (use the MCP first; gate on `nifra check`) + `@AGENTS.md` import
- *   AGENTS.md "MCP"    - a section for non-Claude agents pointing at the same server
+ *   AGENTS.md                         - the guidance (read natively by Codex, Cursor, Copilot and others)
+ *   CLAUDE.md                         - Claude Code: `@AGENTS.md` import
+ *   GEMINI.md                         - Gemini CLI: `@./AGENTS.md` import
+ *   .cursor/rules/nifra.mdc           - Cursor: an always-applied rule pointing at AGENTS.md
+ *   .github/copilot-instructions.md   - GitHub Copilot: points at AGENTS.md
+ *   .mcp.json, .cursor/mcp.json       - the nifra MCP server, registered for Claude Code and Cursor
  *
- * Single source of truth: both `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents`
- * (retrofit an existing app) import these, so the four files can never drift apart. This module is
- * dependency-free (pure string + object generation) on purpose - `create-nifra` ships with no runtime
- * deps, and `@nifrajs/cli` imports it as a workspace dependency.
+ * Both `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents` (retrofit an existing app)
+ * import these, so the files can never drift apart. This module is dependency-free (pure string + object
+ * generation) on purpose - `create-nifra` ships with no runtime deps, and `@nifrajs/cli` imports it as a
+ * workspace dependency.
  *
  * Why `bunx @nifrajs/cli mcp` (not `bunx nifra mcp`): the `nifra` binary is provided by the
- * `@nifrajs/cli` package. A scaffolded `site` app carries `@nifrajs/cli` as a devDependency, so either
- * spelling would resolve `node_modules/.bin/nifra` locally - BUT the `api`/`isr` templates do NOT carry
- * `@nifrajs/cli`, and the bare npm package literally named `nifra` (this monorepo's `@nifrajs/web` shim)
- * exposes NO `nifra` bin. So `bunx nifra mcp` would fetch the wrong package and fail there. Naming the
- * bin-owning package, `bunx @nifrajs/cli mcp`, resolves the locally-installed bin when present and
- * otherwise fetches the package that actually provides the `nifra` command - robust across every
- * template and for any existing app.
+ * `@nifrajs/cli` package, and the bare npm package literally named `nifra` (this monorepo's
+ * `@nifrajs/web` shim) exposes NO `nifra` bin, so `bunx nifra mcp` would fetch the wrong package in an
+ * app that does not carry `@nifrajs/cli`. Naming the bin-owning package resolves the locally-installed
+ * bin when present and otherwise fetches the package that actually provides the `nifra` command.
  */
 /** The MCP launch command, shared by `.mcp.json` and `.cursor/mcp.json`. See the module header for why
  * the package is named explicitly rather than relying on the bare `nifra` bin. */
@@ -43,7 +42,8 @@ export declare const MCP_SERVER_COMMAND: "bunx";
  * keeps respawning the stale binary even after a newer one is published (the MCP server silently runs
  * old code). Pinning the exact version makes the version part of the cache key, so each release fetches
  * fresh and a stale cache can never shadow it. The cost: an already-scaffolded app's `.mcp.json` freezes
- * at its scaffold-time version until `nifra init-agents` is re-run - an acceptable, deterministic trade.
+ * at its scaffold-time version until `nifra init-agents --sync-mcp` re-pins it to the nifra the project
+ * installs - an acceptable, deterministic trade.
  */
 export declare const MCP_CLI_VERSION: string;
 export declare const MCP_SERVER_ARGS: readonly [`@nifrajs/cli@${string}`, "mcp"];
@@ -61,20 +61,27 @@ export declare const MCP_CONFIG: McpConfig;
 /** Serialize the canonical MCP config as the JSON written to `.mcp.json` and `.cursor/mcp.json`.
  * Trailing newline so the file is POSIX-clean and diffs don't flag a missing EOL. */
 export declare function mcpJson(): string;
-/**
- * `CLAUDE.md` - Claude Code reads this automatically. It is deliberately NOT a copy of `AGENTS.md`:
- * a short preamble that (1) tells Claude this project ships a nifra MCP, registered in `.mcp.json`, and
- * to PREFER it, and (2) pulls in the full cookbook with Claude Code's `@file` import directive on its
- * own line - `@AGENTS.md` - so the conventions live in exactly one place and can't drift between the
- * two files. Keep this short; the depth is in `AGENTS.md`.
- */
+/** `CLAUDE.md`: Claude Code expands the `@AGENTS.md` import in place. */
 export declare function claudeMd(): string;
+/** `GEMINI.md`: Gemini CLI expands `@./AGENTS.md` imports in its context files. */
+export declare function geminiMd(): string;
+/** `.cursor/rules/nifra.mdc`: an always-applied Cursor rule; `@AGENTS.md` attaches the file. */
+export declare function cursorRule(): string;
+/** `.github/copilot-instructions.md`: Copilot has no import syntax, so this names the file. */
+export declare function copilotInstructions(): string;
 /**
  * The "## MCP server" section appended to a scaffolded (or retrofitted) `AGENTS.md`, so non-Claude
  * agents (Cursor, and anything that reads `AGENTS.md`) also learn the MCP exists and what to prefer.
  * Mirrors the CLAUDE.md preamble's guidance without the Claude-specific `@import`.
  */
 export declare function agentsMcpSection(): string;
+/**
+ * The "## Project structure" section of a web app's `AGENTS.md`: the zones the build enforces. Shared so
+ * a scaffolded app and one `nifra init-agents` retrofits teach the same rules.
+ */
+export declare function agentsStructureSection(): string;
+/** The heading `nifra init-agents` looks for before appending {@link agentsStructureSection}. */
+export declare const STRUCTURE_HEADING = "## Project structure";
 /** Identifies a generated agent-discovery file: where it goes (relative to the project root) and how to
  * produce its content. `merge` is for files that augment an existing one (AGENTS.md) rather than own it. */
 export interface AgentFileSpec {
@@ -84,9 +91,17 @@ export interface AgentFileSpec {
     readonly label: string;
 }
 /** The standalone files this module fully owns (whole-file generators). AGENTS.md is handled separately
- * because create-nifra builds it from `agents.ts` and the retrofit command appends a section to it. */
+ * because create-nifra builds it from `agents.ts` and the retrofit command appends sections to it. */
 export declare const MCP_JSON_PATH = ".mcp.json";
 export declare const CURSOR_MCP_JSON_PATH = ".cursor/mcp.json";
 export declare const CLAUDE_MD_PATH = "CLAUDE.md";
+export declare const GEMINI_MD_PATH = "GEMINI.md";
+export declare const CURSOR_RULE_PATH = ".cursor/rules/nifra.mdc";
+export declare const COPILOT_INSTRUCTIONS_PATH = ".github/copilot-instructions.md";
 export declare const AGENTS_MD_PATH = "AGENTS.md";
+/** Every agent's pointer to `AGENTS.md`, in the order they are written and reported. */
+export declare const AGENT_POINTERS: readonly {
+    readonly path: string;
+    readonly content: () => string;
+}[];
 //# sourceMappingURL=agent-files.d.ts.map

package/dist/agent-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-files.d.ts","sourceRoot":"","sources":["../src/agent-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;kFACkF;AAClF,eAAO,MAAM,kBAAkB,EAAG,MAAe,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,EAAE,MAIrB,CAAA;AACT,eAAO,MAAM,eAAe,4CAAsD,CAAA;AAElF,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;CAC/D;AAED,2FAA2F;AAC3F,eAAO,MAAM,UAAU,EAAE,SAIxB,CAAA;AAED;qFACqF;AACrF,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAsBjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAczC;AAED;4GAC4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;uGACuG;AACvG,eAAO,MAAM,aAAa,cAAc,CAAA;AACxC,eAAO,MAAM,oBAAoB,qBAAqB,CAAA;AACtD,eAAO,MAAM,cAAc,cAAc,CAAA;AACzC,eAAO,MAAM,cAAc,cAAc,CAAA"}
+{"version":3,"file":"agent-files.d.ts","sourceRoot":"","sources":["../src/agent-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;kFACkF;AAClF,eAAO,MAAM,kBAAkB,EAAG,MAAe,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,EAAE,MAIrB,CAAA;AACT,eAAO,MAAM,eAAe,4CAAsD,CAAA;AAElF,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;CAC/D;AAED,2FAA2F;AAC3F,eAAO,MAAM,UAAU,EAAE,SAIxB,CAAA;AAED;qFACqF;AACrF,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAKD,yEAAyE;AACzE,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,gGAAgG;AAChG,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAczC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CA6B/C;AAED,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD;4GAC4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;sGACsG;AACtG,eAAO,MAAM,aAAa,cAAc,CAAA;AACxC,eAAO,MAAM,oBAAoB,qBAAqB,CAAA;AACtD,eAAO,MAAM,cAAc,cAAc,CAAA;AACzC,eAAO,MAAM,cAAc,cAAc,CAAA;AACzC,eAAO,MAAM,gBAAgB,4BAA4B,CAAA;AACzD,eAAO,MAAM,yBAAyB,oCAAoC,CAAA;AAC1E,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC,wFAAwF;AACxF,eAAO,MAAM,cAAc,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAA;CAAE,EAM5F,CAAA"}

package/dist/agent-files.js

@@ -1,25 +1,24 @@
 /**
- * The canonical generators for the agent-discovery files an app ships so a coding agent auto-discovers
- * the project's nifra MCP server and prefers it over writing nifra from memory:
+ * The canonical generators for the agent files an app ships. `AGENTS.md` is the single source of agent
+ * guidance; every other agent's file is a thin pointer to it, so no two copies can drift:
  *
- *   .mcp.json          - Claude Code's project MCP registry  ({ mcpServers: { nifra: { command, args } } })
- *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
- *   CLAUDE.md          - Claude's preamble (use the MCP first; gate on `nifra check`) + `@AGENTS.md` import
- *   AGENTS.md "MCP"    - a section for non-Claude agents pointing at the same server
+ *   AGENTS.md                         - the guidance (read natively by Codex, Cursor, Copilot and others)
+ *   CLAUDE.md                         - Claude Code: `@AGENTS.md` import
+ *   GEMINI.md                         - Gemini CLI: `@./AGENTS.md` import
+ *   .cursor/rules/nifra.mdc           - Cursor: an always-applied rule pointing at AGENTS.md
+ *   .github/copilot-instructions.md   - GitHub Copilot: points at AGENTS.md
+ *   .mcp.json, .cursor/mcp.json       - the nifra MCP server, registered for Claude Code and Cursor
  *
- * Single source of truth: both `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents`
- * (retrofit an existing app) import these, so the four files can never drift apart. This module is
- * dependency-free (pure string + object generation) on purpose - `create-nifra` ships with no runtime
- * deps, and `@nifrajs/cli` imports it as a workspace dependency.
+ * Both `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents` (retrofit an existing app)
+ * import these, so the files can never drift apart. This module is dependency-free (pure string + object
+ * generation) on purpose - `create-nifra` ships with no runtime deps, and `@nifrajs/cli` imports it as a
+ * workspace dependency.
  *
  * Why `bunx @nifrajs/cli mcp` (not `bunx nifra mcp`): the `nifra` binary is provided by the
- * `@nifrajs/cli` package. A scaffolded `site` app carries `@nifrajs/cli` as a devDependency, so either
- * spelling would resolve `node_modules/.bin/nifra` locally - BUT the `api`/`isr` templates do NOT carry
- * `@nifrajs/cli`, and the bare npm package literally named `nifra` (this monorepo's `@nifrajs/web` shim)
- * exposes NO `nifra` bin. So `bunx nifra mcp` would fetch the wrong package and fail there. Naming the
- * bin-owning package, `bunx @nifrajs/cli mcp`, resolves the locally-installed bin when present and
- * otherwise fetches the package that actually provides the `nifra` command - robust across every
- * template and for any existing app.
+ * `@nifrajs/cli` package, and the bare npm package literally named `nifra` (this monorepo's
+ * `@nifrajs/web` shim) exposes NO `nifra` bin, so `bunx nifra mcp` would fetch the wrong package in an
+ * app that does not carry `@nifrajs/cli`. Naming the bin-owning package resolves the locally-installed
+ * bin when present and otherwise fetches the package that actually provides the `nifra` command.
  */
 import { readFileSync } from "node:fs";
 /** The MCP launch command, shared by `.mcp.json` and `.cursor/mcp.json`. See the module header for why
@@ -44,7 +43,8 @@ export const MCP_SERVER_COMMAND = "bunx";
  * keeps respawning the stale binary even after a newer one is published (the MCP server silently runs
  * old code). Pinning the exact version makes the version part of the cache key, so each release fetches
  * fresh and a stale cache can never shadow it. The cost: an already-scaffolded app's `.mcp.json` freezes
- * at its scaffold-time version until `nifra init-agents` is re-run - an acceptable, deterministic trade.
+ * at its scaffold-time version until `nifra init-agents --sync-mcp` re-pins it to the nifra the project
+ * installs - an acceptable, deterministic trade.
  */
 export const MCP_CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 export const MCP_SERVER_ARGS = [`@nifrajs/cli@${MCP_CLI_VERSION}`, "mcp"];
@@ -59,35 +59,22 @@ export const MCP_CONFIG = {
 export function mcpJson() {
     return `${JSON.stringify(MCP_CONFIG, null, 2)}\n`;
 }
-/**
- * `CLAUDE.md` - Claude Code reads this automatically. It is deliberately NOT a copy of `AGENTS.md`:
- * a short preamble that (1) tells Claude this project ships a nifra MCP, registered in `.mcp.json`, and
- * to PREFER it, and (2) pulls in the full cookbook with Claude Code's `@file` import directive on its
- * own line - `@AGENTS.md` - so the conventions live in exactly one place and can't drift between the
- * two files. Keep this short; the depth is in `AGENTS.md`.
- */
+const POINTER_INTRO = "This project's agent guidance - commands, the project structure, the rules, and the nifra MCP server - lives in AGENTS.md, the single source every agent reads.";
+/** `CLAUDE.md`: Claude Code expands the `@AGENTS.md` import in place. */
 export function claudeMd() {
-    return `# CLAUDE.md
-
-This project ships a **nifra MCP server**, registered for Claude Code in \`.mcp.json\` (it launches with
-\`${MCP_SERVER_COMMAND} ${MCP_SERVER_ARGS.join(" ")}\`). **Prefer the MCP tools** over writing nifra from memory - they are
-typechecked against *this* project and this installed version, so they beat training-data recall:
-
-- \`nifra_docs\` / \`nifra_example\` - exact signatures + verified, compiling snippets. Reach for these
-  before hand-writing a route, a loader, or a client call; a remembered API is often stale or wrong.
-- \`nifra_context\` - this project's route index + conventions, so changes fit the existing surface.
-- \`nifra_types\` - the EXACT TypeScript of any \`@nifrajs/*\` symbol (e.g. \`nifra_types({ name: "RateLimitStore" })\`).
-  Call it for a precise type; **never read \`node_modules/@nifrajs/**/*.d.ts\`** - the tool is the authoritative, complete source.
-- **\`nifra_check\` is the done-gate.** Before declaring any change complete, run \`nifra_check\` (or
-  \`nifra check --json\` in a terminal). It typechecks the frontend↔backend contract and flags drift
-  (hand-rolled \`fetch()\` to this app's own API, server-only imports in \`routes/\`). A failing check
-  means the work isn't done - fix it, don't ship around it.
-
-The full nifra cookbook for this app - backend rules, the typed never-throwing client, file routing, and
-the gotchas - lives in \`AGENTS.md\`, imported here so it stays the single source of truth:
-
-@AGENTS.md
-`;
+    return `# CLAUDE.md\n\n${POINTER_INTRO}\n\n@AGENTS.md\n`;
+}
+/** `GEMINI.md`: Gemini CLI expands `@./AGENTS.md` imports in its context files. */
+export function geminiMd() {
+    return `# GEMINI.md\n\n${POINTER_INTRO}\n\n@./AGENTS.md\n`;
+}
+/** `.cursor/rules/nifra.mdc`: an always-applied Cursor rule; `@AGENTS.md` attaches the file. */
+export function cursorRule() {
+    return `---\ndescription: nifra project guidance\nalwaysApply: true\n---\n\n${POINTER_INTRO} Read it before changing code:\n\n@AGENTS.md\n`;
+}
+/** `.github/copilot-instructions.md`: Copilot has no import syntax, so this names the file. */
+export function copilotInstructions() {
+    return `${POINTER_INTRO} Read AGENTS.md at the repository root before changing code, and follow it.\n`;
 }
 /**
  * The "## MCP server" section appended to a scaffolded (or retrofitted) `AGENTS.md`, so non-Claude
@@ -109,10 +96,56 @@ project + the installed version, so they beat training-data recall:
 - \`nifra_check\` - the done-gate (typecheck + drift lints). Run it before calling work complete; a
   failing check means it isn't done. (\`nifra check --json\` in a terminal does the same.)`;
 }
+/**
+ * The "## Project structure" section of a web app's `AGENTS.md`: the zones the build enforces. Shared so
+ * a scaffolded app and one `nifra init-agents` retrofits teach the same rules.
+ */
+export function agentsStructureSection() {
+    return `${STRUCTURE_HEADING}
+
+Every file a build loads belongs to one side, and the build refuses an import that crosses the wrong
+way - it fails naming the import chain rather than shipping server code to the browser.
+
+| Where | Holds | Reaches the browser |
+|---|---|---|
+| \`routes/x.tsx\` (\`.svelte\`, \`.vue\`, \`.mdx\`) | a page: the component, \`meta\` | yes |
+| \`routes/x.backend.ts\` | that page's \`loader\`, \`action\`, \`loaderOutput\`, \`actionOutput\`, \`middleware\` | never |
+| \`frontend/\` | components, hooks, browser-only code | yes |
+| \`backend/\` | \`app.ts\` (the API), \`framework.ts\`, the database, auth, secrets | never |
+| \`shared/\` | schemas, types and pure helpers both sides import | yes |
+| \`public/\` | static files served as they are | yes |
+
+A file outside those folders joins a side with a \`.frontend.ts\`, \`.backend.ts\` or \`.shared.ts\` suffix.
+
+- **A route is two files.** \`routes/blog/[slug].tsx\` renders; \`routes/blog/[slug].backend.ts\` loads.
+  A server-only export (\`loader\`, \`action\`, ...) in the \`.tsx\` file is a build error.
+- **Frontend code never imports backend code** - not \`backend/\`, not a \`.backend.ts\` file, not a
+  database driver or \`node:\` built-in. Data reaches a page only as its loader's return value.
+- **Every loader and action declares what it sends**: \`export const loaderOutput = t.object({ ... })\`
+  (and \`actionOutput\`). Only what the schema declares reaches the browser, and a loader without one
+  is refused.
+- **Type a route with its generated \`./+types/<name>\`**: \`import type { Route } from "./+types/[slug]"\`
+  gives \`Route.LoaderArgs\` (with the typed \`api\`) in the backend half and \`Route.ComponentProps\` in
+  the page. \`nifra dev\`, \`nifra build\`, \`nifra check\` and \`nifra types\` write them.
+- **Secrets stay in \`backend/\`.** A value only the server may see is read there (\`process.env\`), never
+  in a frontend file; a build that finds what looks like a credential in browser output fails.`;
+}
+/** The heading `nifra init-agents` looks for before appending {@link agentsStructureSection}. */
+export const STRUCTURE_HEADING = "## Project structure";
 /** The standalone files this module fully owns (whole-file generators). AGENTS.md is handled separately
- * because create-nifra builds it from `agents.ts` and the retrofit command appends a section to it. */
+ * because create-nifra builds it from `agents.ts` and the retrofit command appends sections to it. */
 export const MCP_JSON_PATH = ".mcp.json";
 export const CURSOR_MCP_JSON_PATH = ".cursor/mcp.json";
 export const CLAUDE_MD_PATH = "CLAUDE.md";
+export const GEMINI_MD_PATH = "GEMINI.md";
+export const CURSOR_RULE_PATH = ".cursor/rules/nifra.mdc";
+export const COPILOT_INSTRUCTIONS_PATH = ".github/copilot-instructions.md";
 export const AGENTS_MD_PATH = "AGENTS.md";
+/** Every agent's pointer to `AGENTS.md`, in the order they are written and reported. */
+export const AGENT_POINTERS = [
+    { path: CLAUDE_MD_PATH, content: claudeMd },
+    { path: GEMINI_MD_PATH, content: geminiMd },
+    { path: CURSOR_RULE_PATH, content: cursorRule },
+    { path: COPILOT_INSTRUCTIONS_PATH, content: copilotInstructions },
+];
 //# sourceMappingURL=agent-files.js.map

package/dist/agent-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-files.js","sourceRoot":"","sources":["../src/agent-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC;kFACkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAe,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAG7E,CAAC,OAAO,CAAA;AACT,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,gBAAgB,eAAe,EAAE,EAAE,KAAK,CAAU,CAAA;AAalF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC,UAAU,EAAE;QACV,KAAK,EAAE,EAAE,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,GAAG,eAAe,CAAC,EAAE;KACnE;CACF,CAAA;AAED;qFACqF;AACrF,MAAM,UAAU,OAAO;IACrB,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO;;;IAGL,kBAAkB,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;CAiBlD,CAAA;AACD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;;+DAEsD,kBAAkB,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;;;;;;2FAUnB,CAAA;AAC3F,CAAC;AAWD;uGACuG;AACvG,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AACxC,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAA;AACtD,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA"}
+{"version":3,"file":"agent-files.js","sourceRoot":"","sources":["../src/agent-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC;kFACkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAe,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAG7E,CAAC,OAAO,CAAA;AACT,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,gBAAgB,eAAe,EAAE,EAAE,KAAK,CAAU,CAAA;AAalF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC,UAAU,EAAE;QACV,KAAK,EAAE,EAAE,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,GAAG,eAAe,CAAC,EAAE;KACnE;CACF,CAAA;AAED;qFACqF;AACrF,MAAM,UAAU,OAAO;IACrB,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC;AAED,MAAM,aAAa,GACjB,iKAAiK,CAAA;AAEnK,yEAAyE;AACzE,MAAM,UAAU,QAAQ;IACtB,OAAO,kBAAkB,aAAa,kBAAkB,CAAA;AAC1D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,QAAQ;IACtB,OAAO,kBAAkB,aAAa,oBAAoB,CAAA;AAC5D,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,UAAU;IACxB,OAAO,uEAAuE,aAAa,gDAAgD,CAAA;AAC7I,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,mBAAmB;IACjC,OAAO,GAAG,aAAa,+EAA+E,CAAA;AACxG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;;+DAEsD,kBAAkB,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;;;;;;2FAUnB,CAAA;AAC3F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,GAAG,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;+FA2BkE,CAAA;AAC/F,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAA;AAWvD;sGACsG;AACtG,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AACxC,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAA;AACtD,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAA;AACzD,MAAM,CAAC,MAAM,yBAAyB,GAAG,iCAAiC,CAAA;AAC1E,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AAEzC,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GACzB;IACE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE;IAC3C,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE;IAC3C,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,EAAE;IAC/C,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,mBAAmB,EAAE;CAClE,CAAA"}

package/dist/agents.d.ts

@@ -1,9 +1,9 @@
 /**
  * Generate the `AGENTS.md` a scaffolded app ships with - the conventions file read by coding agents
  * (Claude Code, Cursor, …). It encodes nifra's non-obvious rules so an agent writes correct code from
- * the first prompt: validate at the boundary, the never-throwing client, `app.fetch` as the universal
- * entry, and (for full-stack apps) the one gotcha that bites everyone - never top-level-import
- * server-only code into a route module. Tailored per template so the paths + commands are real.
+ * the first prompt: validate at the boundary, the never-throwing client, `backend.fetch` as the universal
+ * entry, and (for full-stack apps) the frontend/backend zones the build enforces. Tailored per template so
+ * the paths + commands are real.
  */
 import type { AuthChoice } from "./auth.js";
 import type { Framework, TemplateName } from "./cli.js";

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAc,KAAK,QAAQ,EAAiB,MAAM,SAAS,CAAA;AAkRlE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAA;IACtB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAuBtD"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAc,KAAK,QAAQ,EAAiB,MAAM,SAAS,CAAA;AA8QlE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAA;IACtB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAuBtD"}

package/dist/agents.js

@@ -1,11 +1,11 @@
 /**
  * Generate the `AGENTS.md` a scaffolded app ships with - the conventions file read by coding agents
  * (Claude Code, Cursor, …). It encodes nifra's non-obvious rules so an agent writes correct code from
- * the first prompt: validate at the boundary, the never-throwing client, `app.fetch` as the universal
- * entry, and (for full-stack apps) the one gotcha that bites everyone - never top-level-import
- * server-only code into a route module. Tailored per template so the paths + commands are real.
+ * the first prompt: validate at the boundary, the never-throwing client, `backend.fetch` as the universal
+ * entry, and (for full-stack apps) the frontend/backend zones the build enforces. Tailored per template so
+ * the paths + commands are real.
  */
-import { agentsMcpSection } from "./agent-files.js";
+import { agentsMcpSection, agentsStructureSection } from "./agent-files.js";
 import { DB_PRESETS } from "./db.js";
 const FRAMEWORK_LABEL = {
     react: "React",
@@ -21,7 +21,7 @@ const API_RULES = `## The backend: \`server()\`
 import { server } from "@nifrajs/core/server"
 import { t } from "@nifrajs/schema"
 
-export const app = server()
+export const backend = server()
   .get("/users/:id", { response: t.object({ id: t.string() }) }, (c) => ({ id: c.params.id }))
   .post(
     "/users",
@@ -33,19 +33,21 @@ export const app = server()
     },
   )
 
-export type App = typeof app
+export type Backend = typeof backend
 \`\`\`
 
 Rules an agent must follow:
 
-- **Validate every input at the boundary.** The route schema slots are \`{ body, query }\` (plus
-  \`response\`, below) - use \`t\` from \`@nifrajs/schema\` (installed) or any Standard Schema (zod, valibot).
-  Read the typed, already-validated \`c.body\` / \`c.query\` (invalid input was rejected with a 422 before the
-  handler ran). **Never** hand-parse \`await c.req.json()\` and poke at properties - that's the bug class the
-  schema exists to remove.
-- **Path params are NOT a schema slot.** \`:id\` etc. are inferred from the path literal as \`string\` and
-  read via \`c.params.id\`; there is no \`params\` (or \`headers\`) key in the route schema. Validate a param's
-  shape inside the handler (a length/format check), not via \`{ params: ... }\` - that's a type error.
+- **Validate every input at the boundary.** The route schema slots are \`{ body, query, params, headers,
+  cookies }\` (plus \`response\`, below) - use \`t\` from \`@nifrajs/schema\` (installed) or any Standard Schema
+  (zod, valibot). Read the typed, already-validated \`c.body\` / \`c.query\` / \`c.params\` / \`c.headers\` /
+  \`c.cookies\` (invalid input was rejected with a 422 before the handler ran). **Never** hand-parse
+  \`await c.req.json()\` and poke at properties - that's the bug class the schema exists to remove.
+- **Path params are strings until a \`params\` schema says otherwise.** \`:id\` is inferred from the path
+  literal as a \`string\` on \`c.params.id\`. Declare \`{ params: t.object({ id: t.string({ format: "uuid" }) }) }\`
+  to reject a malformed id with a 422 before the handler runs, or \`t.query({ id: t.integer() })\` to coerce a
+  numeric one, instead of a format check inside the handler. The schema covers every path param. Header
+  names in a \`headers\` schema are lower-case.
 - **Lock the output shape with \`response\` (no drift).** Add \`{ response: t.object({...}) }\` to a route:
   the handler's return is type-checked against it, and the typed client sees exactly that shape. One
   contract, both sides - the frontend physically can't drift from the backend's output.
@@ -60,8 +62,9 @@ Rules an agent must follow:
 - **Raw \`Response\` is for redirects / streams / files** (\`Response.redirect(url, 302)\`, a file body, an
   SSE stream). The typed client infers \`res.data: never\` on such a route and \`nifra check\` emits a
   non-blocking \`response-route\` warning - both are EXPECTED there, not defects.
-- **\`app.fetch(request)\` is the whole app** - \`(Request) => Response | Promise<Response>\`. Tests drive it
-  directly (\`await app.fetch(new Request("http://x/users/1"))\`); no server needs to be running.
+- **\`backend.fetch(request)\` is the whole app** - \`(Request) => Response | Promise<Response>\`. Tests
+  drive it directly (\`await backend.fetch(new Request("http://x/users/1"))\`); no server needs to be
+  running.
 - **Don't reach for a heavy ORM/HTTP layer.** Routing, validation, cookies, and the typed client are
   built in. Parameterize DB queries; use \`timingSafeEqual\` (or WebCrypto) for secret comparison.
 - **Cross-cutting concerns - use \`@nifrajs/middleware\`, don't hand-roll.** Rate limiting (\`429\` +
@@ -73,30 +76,30 @@ Rules an agent must follow:
 
 \`\`\`ts
 import { client } from "@nifrajs/client"
-import type { app } from "./app"          // type-only import - server code never ships to the client
+import type { Backend } from "./backend/app"   // type-only import - server code never ships
 
-const api = client<typeof app>("https://api.example.com")
+const api = client<Backend>("https://api.example.com")
 const res = await api.users({ id: "42" }).get()
 if (res.ok) res.data            // typed from the route's return type - zero codegen
 else res.error                  // errors are returned, never thrown
 \`\`\`
 
 **Never hand-roll \`fetch\` + ad-hoc response types for this app's own API** - that's exactly how a screen
-drifts from the backend. \`client<typeof app>\` derives both the request inputs and \`res.data\` from the
+drifts from the backend. \`client<Backend>\` derives both the request inputs and \`res.data\` from the
 route types, so \`tsc\` (and \`nifra build\`) catch any mismatch the moment a route changes. When building a
 page that calls the API, reach for the client first.
 `;
-/** File-routing + the server-only gotcha - only for full-stack (site/isr) templates. */
+/** File routing, loaders and the zones - only for full-stack (site/isr) templates. */
 function webRules(framework) {
     const label = FRAMEWORK_LABEL[framework];
     return `## The frontend: file routing + loaders (${label})
 
 - Routes live in \`routes/\`. \`index.tsx\` → \`/\`, \`[id].tsx\` → \`/:id\`, \`_layout.tsx\` wraps a subtree,
   \`_404.tsx\` / \`_error.tsx\` are the fallbacks.
-- A route file may export: \`default\` (the page component), \`loader\` (server-only data), \`action\`
-  (server-only mutation), and \`meta\` (head tags). The \`loader\` returns data typed straight into the page.
+- A page's \`.tsx\` file exports \`default\` (the component) and \`meta\` (head tags). Its \`.backend.ts\` file
+  exports \`loader\` (data) and \`action\` (mutations), each with its output schema.
 - **The \`server()\` backend is IN-PROCESS, not a public HTTP surface.** Loaders/actions call it through
-  \`ctx.api\` (the typed client - no network) during SSR; there is no \`GET /your-route\` endpoint on the page
+  \`api\` (the typed client - no network) during SSR; there is no \`GET /your-route\` endpoint on the page
   server to curl. Build features through loaders/actions + the typed client, not direct HTTP calls.
 - Swap UI frameworks by changing one import (\`@nifrajs/web-${framework}\` → another adapter); your route,
   loader, and action code do not change.
@@ -105,20 +108,14 @@ function webRules(framework) {
   and navigate without a full reload. Throwing in an action or returning in a loader is a silent bug
   that produces a false "operation failed" error on the client.
 
-## ⚠️ The one rule that bites everyone: never import server-only code at a route's top level
-
-A route module's \`loader\`/\`action\` run **only on the server**, but the module is **also bundled for the
-browser** (for the component) - and the loader is *not* stripped. So a top-level
-\`import db from "./db"\` (or anything touching \`process.env\`, secrets, \`node:\` APIs) ships server code to
-the client and crashes hydration. Reach server resources through \`ctx.api\` / \`ctx.env\` (injected via
-\`createWebApp\`) inside the loader instead - never as a top-level import in a \`routes/\` file.
+${agentsStructureSection()}
 `;
 }
 /** Per-ORM body of the DB rules: the query idiom, schema location, and migrate story all differ. */
 function dbRulesBody(orm) {
     if (orm === "prisma") {
-        return `A Prisma data layer is wired: \`prisma/schema.prisma\` (a starter \`Note\` model) + \`db/index.ts\` (a
-singleton \`PrismaClient\`).
+        return `A Prisma data layer is wired: \`prisma/schema.prisma\` (a starter \`Note\` model) +
+\`backend/db/index.ts\` (a singleton \`PrismaClient\`).
 
 - **Wire it into the backend once**, then read \`c.db\` in handlers:
   \`\`\`ts
@@ -137,9 +134,9 @@ singleton \`PrismaClient\`).
   applies the migration and regenerates the client). \`bun run db:studio\` opens a DB browser.`;
     }
     if (orm === "kysely") {
-        return `A Kysely typed query builder is wired in \`db/\`: \`db/schema.ts\` (the DB-shape interface - keep it in
-sync with your migrations) + \`db/index.ts\` (the typed client). You own the migrations (\`db/migrations/\`,
-run by \`db/migrate.ts\`).
+        return `A Kysely typed query builder is wired in \`backend/db/\`: \`backend/db/schema.ts\` (the DB-shape
+interface - keep it in sync with your migrations) + \`backend/db/index.ts\` (the typed client). You own the
+migrations (\`backend/db/migrations/\`, run by \`backend/db/migrate.ts\`).
 
 - **Wire it into the backend once**, then read \`c.db\` in handlers:
   \`\`\`ts
@@ -154,11 +151,11 @@ run by \`db/migrate.ts\`).
     .post("/notes", { body: t.object({ title: t.string({ minLength: 1 }) }) }, async (c) =>
       c.db.insertInto("notes").values({ title: c.body.title }).returningAll().executeTakeFirstOrThrow())
   \`\`\`
-- **Migrations:** add a file to \`db/migrations/\` (copy the \`0001_create_notes.ts\` shape), update the
-  \`db/schema.ts\` interface to match, then \`bun run db:migrate\`.`;
+- **Migrations:** add a file to \`backend/db/migrations/\` (copy the \`0001_create_notes.ts\` shape),
+  update the \`backend/db/schema.ts\` interface to match, then \`bun run db:migrate\`.`;
     }
-    return `A Drizzle data layer is wired in \`db/\`: \`db/schema.ts\` (a starter \`notes\` table) + \`db/index.ts\` (the
-typed client).
+    return `A Drizzle data layer is wired in \`backend/db/\`: \`backend/db/schema.ts\` (a starter \`notes\`
+table) + \`backend/db/index.ts\` (the typed client).
 
 - **Wire it into the backend once**, then read \`c.db\` in handlers:
   \`\`\`ts
@@ -173,8 +170,8 @@ typed client).
       (await c.db.insert(notes).values({ title: c.body.title }).returning())[0],
     )
   \`\`\`
-- **Migrations:** edit \`db/schema.ts\`, then \`bun run db:generate\` (writes SQL to \`db/migrations\`) +
-  \`bun run db:migrate\` (applies it). \`bun run db:studio\` opens a DB browser.`;
+- **Migrations:** edit \`backend/db/schema.ts\`, then \`bun run db:generate\` (writes SQL to
+  \`backend/db/migrations\`) + \`bun run db:migrate\` (applies it). \`bun run db:studio\` opens a DB browser.`;
 }
 /** DB rules - only when scaffolded with `--db`. Teaches the wired data layer + the `c.db` seam. */
 function dbRules(db) {
@@ -184,15 +181,15 @@ function dbRules(db) {
 ${dbRulesBody(p.orm)} ${p.note}
 
 - **Query is fully typed** - types flow from the schema/model; \`c.db\` is typed end to end.
-- **Never top-level-import \`db\` into a \`routes/\` page file** - it's server-only; reach it via \`c.db\` on
-  the backend (or \`ctx.api\` from a loader). A top-level import ships it to the browser and breaks the build.`;
+- **\`backend/db/\` is backend code.** Reach it via \`c.db\` on the backend, or through \`api\` from a
+  route's \`.backend.ts\` loader. A frontend file that imports it fails the build.`;
 }
 /** Auth rules - only when scaffolded with `--auth`. Teaches the better-auth mount + the typed guards. */
 function authRules(_auth) {
     return `## Authentication (better-auth)
 
-better-auth is configured in \`auth.ts\` (email/password + sessions, backed by your scaffolded database via
-its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifrajs/better-auth\`.
+better-auth is configured in \`backend/auth.ts\` (email/password + sessions, backed by your scaffolded
+database via its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifrajs/better-auth\`.
 
 - **Mount it once** on the backend - it serves every auth endpoint under \`/api/auth/*\`:
   \`\`\`ts
@@ -201,9 +198,10 @@ its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifr
   import { auth } from "./auth"
   export const app = server().use(betterAuth(auth))
   \`\`\`
-- **Generate the auth tables** once, and after changing the config: \`bunx @better-auth/cli@latest generate\`
-  writes them into your schema (\`db/schema.ts\` for Drizzle, \`prisma/schema.prisma\` for Prisma); then
-  \`bun run db:migrate\`.
+- **Generate the auth tables** once, and after changing the config:
+  \`bunx @better-auth/cli@latest generate --config backend/auth.ts\` writes their schema (Prisma: into
+  \`prisma/schema.prisma\`; Drizzle: a \`schema.ts\` at the root unless \`--output\` names a file under
+  \`backend/db/\`); then \`bun run db:migrate\`.
 - **Read / require a session** with the typed guards (pass the raw \`Request\` - \`c.req\` in a handler, or a
   loader's \`request\`):
   \`\`\`ts
@@ -214,7 +212,8 @@ its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifr
     return { id: user.id }
   })
   \`\`\`
-- \`auth\` is **server-only** - never import it into a \`routes/\` page, and keep \`BETTER_AUTH_SECRET\` in \`.env\`.`;
+- \`backend/auth.ts\` is **backend code** - a frontend file cannot import it - and \`BETTER_AUTH_SECRET\`
+  stays in \`.env\`.`;
 }
 const SECURITY_RULES = `## Production defaults (don't ship the happy path only)
 
@@ -233,28 +232,25 @@ const SECURITY_RULES = `## Production defaults (don't ship the happy path only)
 const COMMANDS = {
     api: `- \`bun install\` - install dependencies
 - \`bun run dev\` - run the API (watch mode)
-- \`bun test\` - drive \`app.fetch\` directly; no server required
+- \`bun test\` - drive \`backend.fetch\` directly; no server required
 - \`nifra check\` - typecheck + typed-client lint (run before you call work done)`,
     site: `- \`bun install\` - install dependencies
-- \`nifra dev\` - true-HMR dev server
-- \`nifra build\` - complete Bun deploy (server + content-hashed client assets)
-- \`nifra start\` - run the generated Bun server - pairs with \`nifra build\`
-- \`nifra check\` - typecheck + typed-client lint (run before you call work done)
-
-  For a local production run use \`nifra build && nifra start\` (or \`bun run build:bun && bun run start\`). NOTE:
-  the bare \`bun run build\` script targets **Cloudflare Pages for DEPLOY** (emits \`dist/\`, a different layout)
-  - it does NOT pair with \`nifra start\`/\`bun run start\` (which serve \`dist-bun/\`). Don't mix the two.`,
+- \`bun run dev\` (\`nifra dev\`) - true-HMR dev server
+- \`bun run build\` (\`nifra build\`) - the deploy directory for the app's \`target\` in \`nifra.config.ts\`; it
+  generates the server entry, so the app has no per-runtime entry or build script
+- \`bun run start\` - run the built app locally (on targets with a local runner)
+- \`nifra target <t>\` - switch where the app deploys: bun | node | deno | cloudflare | vercel
+- \`nifra check\` - typecheck + typed-client lint (run before you call work done)`,
     isr: `- \`bun install\` - install dependencies
-- \`nifra dev\` - true-HMR dev server
-- \`nifra build\` - complete Bun deploy (server + content-hashed client assets)
-- \`nifra start\` - run the generated Bun server (SSR + ISR cache) - pairs with \`nifra build\`
-- \`nifra check\` - typecheck + typed-client lint (run before you call work done)
-
-  For a local production run use \`nifra build && nifra start\`. NOTE: the bare \`bun run build\` script targets
-  **Cloudflare Pages for DEPLOY** (\`dist/\`) and does NOT pair with \`nifra start\` - don't mix the two.`,
+- \`bun run build\` - \`build.ts\`: the client bundle into \`public/assets\`, the worker
+  (\`backend/worker.ts\`) into \`dist-server/worker.js\`
+- \`bun run dev\` - \`wrangler dev\` on real workerd with a local KV (run \`bun run build\` first)
+- \`bun run dev:bun\` - the same app on a local Bun server (\`backend/dev-server.ts\`, in-memory cache)
+- \`bun run build && bunx wrangler deploy\` - deploy (create the KV namespace first; see README)
+- \`nifra check\` - typecheck + typed-client lint (run before you call work done)`,
     batteries: `- \`bun install\` - install dependencies
-- \`bun run dev\` - run the API (watch mode); \`src/index.ts\` also starts the job worker (\`queue.start()\`)
-- \`bun test\` - drives \`app.fetch\` directly (pagination, jobs via \`queue.drain()\`, cache, storage); no server required
+- \`bun run dev\` - run the API (watch mode); \`backend/index.ts\` also starts the job worker (\`queue.start()\`)
+- \`bun test\` - drives \`backend.fetch\` directly (pagination, jobs via \`queue.drain()\`, cache, storage); no server required
 - \`bun run typecheck\` - run before you call work done
 
   Wired: cursor pagination (\`t.pageQuery\`/\`t.paginated\`/\`paginate\`), background jobs (\`@nifrajs/jobs\`),
@@ -267,8 +263,8 @@ const DONE = `## Definition of done - run \`nifra check\`
 Before considering any change complete, run **\`nifra check\`**. It (1) typechecks - the frontend↔backend
 contract is compiler-enforced, so the typed client deriving \`res.data\` from your routes turns any
 mismatch into an error; (2) flags any hand-rolled \`fetch()\` to this app's own API (which bypasses that
-check); and (3) flags a server-only import (a DB driver, \`node:\`/\`bun:\`, \`./db\`) at the top level of a
-\`routes/\` page - that ships server code to the browser. Use \`nifra check --json\` for machine-readable
+check); and (3) enforces the frontend/backend zones - a frontend file reaching backend code, or a loader
+or action without an output schema, fails it. Use \`nifra check --json\` for machine-readable
 diagnostics. A failing \`nifra check\` means the work isn't done - fix it, don't ship around it.`;
 /** Build the full `AGENTS.md` for a freshly scaffolded app. */
 export function agentsMd(opts) {