better-ts-stack 2.1.1 → 2.2.0

package/templates/frontend/tanstack/src/routes/index.tsx.hbs

@@ -1,9 +1,16 @@
 import { createFileRoute{{#if useAuth}}, Link{{/if}} } from "@tanstack/react-router";
 import { ArrowRight } from "lucide-react";
 
-import { buttonVariants } from "~/components/ui/button";
-import { Card, CardContent, CardHeader, CardTitle } from "~/components/ui/card";
-import { cn } from "~/lib/utils";
+import { Alert, AlertDescription } from "~/components/ui/alert";
+import { Badge } from "~/components/ui/badge";
+import { Button } from "~/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "~/components/ui/card";
 
 export const Route = createFileRoute("/")({
   component: Home,
@@ -13,7 +20,7 @@ const featureList = [
   "TanStack Start SSR",
   "TanStack Router and Query",
   "React 19 and TypeScript",
-  "Tailwind CSS v4",
+  "Tailwind CSS v4 and shadcn/ui on Base UI",
   {{#if useAuth}}"Better Auth-ready session flow",{{/if}}
   {{#if (eq database "prisma")}}"Prisma database tooling",{{/if}}
   {{#if (eq database "drizzle")}}"Drizzle database tooling",{{/if}}
@@ -22,66 +29,74 @@ const featureList = [
 
 function Home() {
   return (
-    <main className="min-h-screen bg-background text-foreground">
-      <div className="mx-auto flex min-h-screen max-w-6xl flex-col justify-center gap-12 px-6 py-16 sm:px-10 lg:px-12">
+    <main className="min-h-svh">
+      <div className="mx-auto flex min-h-svh max-w-6xl flex-col justify-center gap-12 px-6 py-16 sm:px-10 lg:px-12">
         <section className="grid gap-10 lg:grid-cols-[1.2fr_0.8fr] lg:items-center">
-          <div className="space-y-6">
-            <span className="inline-flex w-fit items-center rounded-full border border-border bg-card px-3 py-1 text-xs font-medium uppercase tracking-[0.24em] text-muted-foreground shadow-sm">
-              Created with better-ts-stack
-            </span>
-            <div className="space-y-4">
+          <div className="flex flex-col gap-6">
+            <Badge variant="outline">Created with better-ts-stack</Badge>
+            <div className="flex flex-col gap-4">
               <h1 className="max-w-3xl text-4xl font-semibold tracking-tight sm:text-5xl">
                 Ship your stack faster with a polished TypeScript foundation.
               </h1>
               <p className="max-w-2xl text-base leading-7 text-muted-foreground sm:text-lg">
                 Your project already includes the core app shell, database wiring,
-                and a shadcn-compatible UI foundation so you can keep building
-                instead of setting up boilerplate.
+                and shadcn/ui components so you can keep building instead of
+                setting up boilerplate.
               </p>
             </div>
             <div className="flex flex-col gap-3 sm:flex-row">
               {{#if useAuth}}
-              <Link
-                to="/sign-up"
-                className={cn(buttonVariants({ size: "lg" }), "gap-2")}
-              >
+              <Button size="lg" nativeButton={false} render={<Link to="/sign-up" />}>
                 Create an account
-                <ArrowRight className="size-4" />
-              </Link>
-              <Link
-                to="/sign-in"
-                className={buttonVariants({ variant: "outline", size: "lg" })}
+                <ArrowRight data-icon="inline-end" />
+              </Button>
+              <Button
+                size="lg"
+                variant="outline"
+                nativeButton={false}
+                render={<Link to="/sign-in" />}
               >
                 Login
-              </Link>
+              </Button>
               {{else}}
-              <a
-                href="https://better-ts-stack.abdullahtech.me/docs"
-                target="_blank"
-                rel="noreferrer"
-                className={cn(buttonVariants({ size: "lg" }), "gap-2")}
+              <Button
+                size="lg"
+                nativeButton={false}
+                render={
+                  <a
+                    href="https://better-ts-stack.abdullahtech.me/docs"
+                    target="_blank"
+                    rel="noreferrer"
+                  />
+                }
               >
                 Explore the docs
-                <ArrowRight className="size-4" />
-              </a>
-              <a
-                href="https://tanstack.com/start/latest"
-                target="_blank"
-                rel="noreferrer"
-                className={buttonVariants({ variant: "outline", size: "lg" })}
+                <ArrowRight data-icon="inline-end" />
+              </Button>
+              <Button
+                size="lg"
+                variant="outline"
+                nativeButton={false}
+                render={
+                  <a
+                    href="https://tanstack.com/start/latest"
+                    target="_blank"
+                    rel="noreferrer"
+                  />
+                }
               >
                 TanStack guide
-              </a>
+              </Button>
               {{/if}}
             </div>
           </div>
 
-          <Card className="border-border bg-card shadow-sm">
+          <Card>
             <CardHeader>
               <CardTitle>Included in this starter</CardTitle>
             </CardHeader>
-            <CardContent className="space-y-4">
-              <ul className="space-y-3 text-sm text-muted-foreground">
+            <CardContent>
+              <ul className="flex flex-col gap-3 text-muted-foreground">
                 {featureList.map((feature) => (
                   <li key={feature} className="flex items-center gap-3">
                     <span className="size-2 rounded-full bg-primary" />
@@ -89,15 +104,19 @@ function Home() {
                   </li>
                 ))}
               </ul>
-              <div className="rounded-2xl border border-border bg-muted px-4 py-3 text-sm text-muted-foreground">
-                Start editing{" "}
-                <code className="font-mono">src/routes/index.tsx</code> and
-                shape the project around your product instead of setup chores.
-              </div>
             </CardContent>
+            <CardFooter>
+              <Alert>
+                <AlertDescription>
+                  Start editing{" "}
+                  <code className="font-mono">src/routes/index.tsx</code> and
+                  shape the project around your product instead of setup chores.
+                </AlertDescription>
+              </Alert>
+            </CardFooter>
           </Card>
         </section>
       </div>
     </main>
   );
-}
+}

package/templates/frontend/tanstack/src/styles/app.css

@@ -1,49 +1,95 @@
 @import "tailwindcss" source("../");
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/inter";
+
+@custom-variant dark (&:is(.dark *));
 
 @theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
+    --font-heading: var(--font-sans);
+    --font-sans: 'Inter Variable', sans-serif;
+    --color-sidebar-ring: var(--sidebar-ring);
+    --color-sidebar-border: var(--sidebar-border);
+    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+    --color-sidebar-accent: var(--sidebar-accent);
+    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+    --color-sidebar-primary: var(--sidebar-primary);
+    --color-sidebar-foreground: var(--sidebar-foreground);
+    --color-sidebar: var(--sidebar);
+    --color-chart-5: var(--chart-5);
+    --color-chart-4: var(--chart-4);
+    --color-chart-3: var(--chart-3);
+    --color-chart-2: var(--chart-2);
+    --color-chart-1: var(--chart-1);
+    --color-ring: var(--ring);
+    --color-input: var(--input);
+    --color-border: var(--border);
+    --color-destructive: var(--destructive);
+    --color-accent-foreground: var(--accent-foreground);
+    --color-accent: var(--accent);
+    --color-muted-foreground: var(--muted-foreground);
+    --color-muted: var(--muted);
+    --color-secondary-foreground: var(--secondary-foreground);
+    --color-secondary: var(--secondary);
+    --color-primary-foreground: var(--primary-foreground);
+    --color-primary: var(--primary);
+    --color-popover-foreground: var(--popover-foreground);
+    --color-popover: var(--popover);
+    --color-card-foreground: var(--card-foreground);
+    --color-card: var(--card);
+    --color-foreground: var(--foreground);
+    --color-background: var(--background);
+    --radius-sm: calc(var(--radius) * 0.6);
+    --radius-md: calc(var(--radius) * 0.8);
+    --radius-lg: var(--radius);
+    --radius-xl: calc(var(--radius) * 1.4);
+    --radius-2xl: calc(var(--radius) * 1.8);
+    --radius-3xl: calc(var(--radius) * 2.2);
+    --radius-4xl: calc(var(--radius) * 2.6);
 }
 
 :root {
-  --background: oklch(0.985 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.205 0 0);
+    --primary-foreground: oklch(0.985 0 0);
+    --secondary: oklch(0.97 0 0);
+    --secondary-foreground: oklch(0.205 0 0);
+    --muted: oklch(0.97 0 0);
+    --muted-foreground: oklch(0.556 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    --chart-1: oklch(0.87 0 0);
+    --chart-2: oklch(0.556 0 0);
+    --chart-3: oklch(0.439 0 0);
+    --chart-4: oklch(0.371 0 0);
+    --chart-5: oklch(0.269 0 0);
+    --radius: 0.625rem;
+    --sidebar: oklch(0.985 0 0);
+    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar-primary: oklch(0.205 0 0);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.97 0 0);
+    --sidebar-accent-foreground: oklch(0.205 0 0);
+    --sidebar-border: oklch(0.922 0 0);
+    --sidebar-ring: oklch(0.708 0 0);
 }
 
-@media (prefers-color-scheme: dark) {
-  :root {
+.dark {
     --background: oklch(0.145 0 0);
     --foreground: oklch(0.985 0 0);
     --card: oklch(0.205 0 0);
     --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
     --primary: oklch(0.922 0 0);
     --primary-foreground: oklch(0.205 0 0);
     --secondary: oklch(0.269 0 0);
@@ -56,30 +102,29 @@
     --border: oklch(1 0 0 / 10%);
     --input: oklch(1 0 0 / 15%);
     --ring: oklch(0.556 0 0);
-  }
-}
-
-@layer base {
-  *,
-  ::after,
-  ::before,
-  ::backdrop,
-  ::file-selector-button {
-    border-color: var(--color-gray-200, currentcolor);
-  }
+    --chart-1: oklch(0.87 0 0);
+    --chart-2: oklch(0.556 0 0);
+    --chart-3: oklch(0.439 0 0);
+    --chart-4: oklch(0.371 0 0);
+    --chart-5: oklch(0.269 0 0);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.488 0.243 264.376);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.556 0 0);
 }
 
 @layer base {
-  html {
-    color-scheme: light dark;
-  }
-
   * {
-    @apply border-gray-200 dark:border-gray-800;
-  }
-
-  html,
+    @apply border-border outline-ring/50;
+    }
   body {
-    @apply bg-gray-50 text-gray-900 dark:bg-gray-950 dark:text-gray-200;
-  }
+    @apply bg-background text-foreground;
+    }
+  html {
+    @apply font-sans;
+    }
 }

package/templates/frontend/tanstack/tsconfig.json

@@ -1,22 +1,22 @@
-{
-  "include": ["**/*.ts", "**/*.tsx"],
-  "compilerOptions": {
-    "strict": true,
-    "esModuleInterop": true,
-    "jsx": "react-jsx",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "lib": ["DOM", "DOM.Iterable", "ES2022"],
-    "isolatedModules": true,
-    "resolveJsonModule": true,
-    "skipLibCheck": true,
-    "target": "ES2022",
-    "allowJs": true,
-    "noEmit": true,
-    "forceConsistentCasingInFileNames": true,
-    "paths": {
-      "~/*": ["./src/*"]
-    }
-  },
-  "exclude": ["node_modules"]
-}
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "target": "ES2022",
+    "allowJs": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "exclude": ["node_modules"]
+}

package/templates/modules/agents/AGENTS.md.hbs

@@ -0,0 +1,245 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in {{projectName}}. Read this before making changes.
+
+## Stack
+
+{{#if (eq framework 'express')}}
+- Express 5 REST API in TypeScript, compiled to CommonJS with `tsc`
+{{/if}}
+{{#if (eq framework 'nestjs')}}
+- NestJS 12 REST API in TypeScript, using ES modules
+{{/if}}
+{{#if (eq framework 'nextjs')}}
+- Next.js 16 with the App Router, React 19, Tailwind CSS 4, and shadcn/ui on Base UI
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- TanStack Start with Vite, Nitro, React 19, Tailwind CSS 4, and shadcn/ui on Base UI
+{{/if}}
+{{#if (eq database 'prisma')}}
+- PostgreSQL through Prisma 7
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- PostgreSQL through Drizzle ORM
+{{/if}}
+{{#if (eq database 'mongoose')}}
+- MongoDB through Mongoose
+{{/if}}
+{{#if useAuth}}
+- Better Auth: email and password, email verification, password reset, and GitHub and Google sign-in when their keys are set. Emails go through Resend when `RESEND_API_KEY` is set and are printed to the log otherwise
+{{#if (eq framework 'express')}}
+- Auth routes under `/api/auth` (`POST /api/auth/sign-up/email`, `POST /api/auth/sign-in/email`, ...). Clients without cookies send `Authorization: Bearer <token>`, using the `set-auth-token` header from sign-in
+{{/if}}
+{{#if (eq framework 'nestjs')}}
+- Auth routes under `/api/auth` (`POST /api/auth/sign-up/email`, `POST /api/auth/sign-in/email`, ...). Clients without cookies send `Authorization: Bearer <token>`, using the `set-auth-token` header from sign-in
+{{/if}}
+{{/if}}
+{{#if useRateLimit}}
+- Rate limiting on every route except `/health`
+{{/if}}
+{{#if useDocker}}
+- Docker: `Dockerfile` and `docker-compose.yml`
+{{/if}}
+{{#if useCi}}
+- GitHub Actions CI in `.github/workflows/ci.yml`
+{{/if}}
+- Package manager: {{packageManager}}. Do not use another one or add its lockfile
+- Node.js 24 or later
+
+## Commands
+
+- Install: `{{packageManager}} install`
+- Dev server: `{{docker.run}} dev`
+- Build: `{{docker.run}} build`
+- Type-check: `{{docker.run}} type:check`
+- Lint: `{{docker.run}} lint`
+{{#if (eq database 'prisma')}}
+- After changing `prisma/schema.prisma`: `{{docker.run}} prisma:migrate` creates and applies a migration and regenerates the client
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- After changing the schema: `{{docker.run}} db:generate` writes a migration, then `{{docker.run}} db:migrate` applies it
+{{/if}}
+
+## Before you finish
+
+Run type-check and lint, and fix every error they report. Run the build too when you changed config, dependencies, or anything the build reads. Do not report a task as done while any of them fails.
+
+## Layout
+
+{{#if (eq framework 'express')}}
+- `src/index.ts`: creates the app, adds middleware, and mounts the routers
+- `src/env.ts`: checks the environment variables with Zod at startup, so a missing one stops the server with a clear message
+- `src/routes/`: one router per resource, mounted in `src/index.ts`
+{{#if useAuth}}
+- `src/lib/auth.ts`: the Better Auth server, mounted on `/api/auth` in `src/index.ts`
+- `src/lib/email.ts`: sends the verification and password reset emails
+- `src/middleware/requireAuth.ts`: add it to a route to require a session; `getSession(res)` returns it. `src/routes/me.ts` is an example
+{{/if}}
+{{#if useRateLimit}}
+- `src/middleware/rateLimit.ts`: the rate limiters
+{{/if}}
+{{#if (eq database 'prisma')}}
+- `src/lib/prisma.ts`: the shared Prisma client. Do not create another one
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- `src/lib/db.ts`, `src/lib/schema.ts`: the database client and the tables
+{{/if}}
+{{#if (eq database 'mongoose')}}
+- `src/lib/db.ts`, `src/models/`: the connection and the Mongoose models
+{{/if}}
+{{/if}}
+{{#if (eq framework 'nestjs')}}
+- `src/main.ts`: starts the app
+- `src/app.module.ts`: the root module. Register new modules and controllers here
+- `src/env.ts`: checks the environment variables with Zod at startup, so a missing one stops the server with a clear message
+- `src/health/`: `GET /health`
+{{#if useAuth}}
+- `src/auth/`: the Better Auth server (`auth.ts`), the emails it sends (`email.ts`), and the module that mounts it on `/api/auth` (`auth.module.ts`)
+- Every route needs a session unless it has `@AllowAnonymous()` (or `@OptionalAuth()`). Read the session with `@Session()`, as `src/me/me.controller.ts` does
+{{/if}}
+{{#if (eq database 'prisma')}}
+- `src/prisma/`: `PrismaService`, injected wherever the database is needed
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- `src/database/`: the database module and the tables in `schema.ts`
+{{/if}}
+{{#if (eq database 'mongoose')}}
+- `src/users/user.schema.ts`: the Mongoose schema for users
+{{/if}}
+{{/if}}
+{{#if (eq framework 'nextjs')}}
+- `app/`: routes, layouts, and route handlers. Pages are Server Components unless they need state, effects, or event handlers
+- `components/ui/`: shadcn/ui components built on Base UI (`@base-ui/react`). Add new ones with the shadcn CLI instead of writing them by hand. Use the `render` prop to change the rendered element, not Radix's `asChild`
+- `lib/utils.ts`: the `cn()` class name helper
+- `app/globals.css`: the shadcn theme. Style with its tokens (`bg-primary`, `text-muted-foreground`), not raw Tailwind colors, and space with `flex` + `gap-*`, not `space-y-*`
+{{#if useAuth}}
+- `lib/auth.ts`: the Better Auth server. `lib/auth-client.ts`: the client for components. `lib/email.ts`: sends the verification and password reset emails
+- `lib/session.ts`: `getSession()` reads the session on the server, once per request
+- `app/api/auth/[...all]/route.ts`: the Better Auth endpoints. Do not rename it
+- `proxy.ts`: sends signed-out visitors from `/dashboard` to `/sign-in`. Add other protected paths to its `matcher`
+{{/if}}
+{{#if (eq database 'prisma')}}
+- `lib/prisma.ts`: the shared Prisma client. Do not create another one
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- `lib/db.ts`, `lib/schema.ts`: the database client and the tables
+{{/if}}
+{{#if (eq database 'mongoose')}}
+- `lib/db.ts`, `models/`: the connection and the Mongoose models
+{{/if}}
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- `src/routes/`: file-based routes. A new file becomes a route
+- `src/routeTree.gen.ts`: generated by the dev server and the build. Never edit it
+- `src/router.tsx`, `src/routes/__root.tsx`: the router and the root layout
+- `src/components/ui/`: shadcn/ui components built on Base UI (`@base-ui/react`). Add new ones with the shadcn CLI instead of writing them by hand. Use the `render` prop to change the rendered element, not Radix's `asChild`
+- `src/lib/utils.ts`: the `cn()` class name helper
+- `src/styles/app.css`: the shadcn theme. Style with its tokens (`bg-primary`, `text-muted-foreground`), not raw Tailwind colors, and space with `flex` + `gap-*`, not `space-y-*`
+{{#if useAuth}}
+- `src/lib/auth.ts`: the Better Auth server. `src/lib/auth-client.ts`: the client for components. `src/lib/email.ts`: sends the verification and password reset emails
+- `src/routes/api/auth/$.ts`: the Better Auth endpoints. Do not rename it
+- `src/routes/dashboard.tsx`: an example of a protected route that redirects in `beforeLoad`
+{{/if}}
+{{#if (eq database 'prisma')}}
+- `src/lib/prisma.ts`: the shared Prisma client. Do not create another one
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- `src/lib/db.ts`, `src/lib/schema.ts`: the database client and the tables
+{{/if}}
+{{#if (eq database 'mongoose')}}
+- `src/lib/db.ts`, `src/models/`: the connection and the Mongoose models
+{{/if}}
+{{/if}}
+
+## Rules
+
+- TypeScript is strict. Do not use `any` or `@ts-ignore` to silence an error; fix the type
+{{#if (eq framework 'nestjs')}}
+- Relative imports end in `.js`, as ES modules require: `import { AuthModule } from "./auth/auth.module.js"`
+{{/if}}
+- Keep `.env` out of git. When you add an environment variable, add it to `.env.example` too{{#if (eq framework 'express')}}, and to `src/env.ts`{{/if}}{{#if (eq framework 'nestjs')}}, and to `src/env.ts`{{/if}}
+{{#if (eq database 'prisma')}}
+- The Prisma client is generated into {{#if (eq framework 'express')}}`src/generated/`{{/if}}{{#if (eq framework 'nestjs')}}`src/generated/`{{/if}}{{#if (eq framework 'nextjs')}}`generated/`{{/if}}{{#if (eq framework 'tanstack')}}`generated/`{{/if}}. Never edit or commit it
+{{/if}}
+- Match the existing code style. ESLint settings are in `eslint.config.mjs`{{#if (eq framework 'express')}} and Prettier settings in `.prettierrc`{{/if}}{{#if (eq framework 'nestjs')}} and Prettier settings in `.prettierrc`{{/if}}
+{{#if (eq framework 'nextjs')}}
+- Write Tailwind classes in their canonical form. Use the theme utility when one exists (`rounded-4xl`, not `rounded-[2rem]`), and in an arbitrary value write `_` only where CSS needs a space, never after a comma: `bg-[linear-gradient(180deg,#f8fafc_0%,#eef2ff_100%)]`. The Tailwind CSS VS Code extension warns about the long forms
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- Write Tailwind classes in their canonical form. Use the theme utility when one exists (`rounded-4xl`, not `rounded-[2rem]`), and in an arbitrary value write `_` only where CSS needs a space, never after a comma: `bg-[linear-gradient(180deg,#f8fafc_0%,#eef2ff_100%)]`. The Tailwind CSS VS Code extension warns about the long forms
+{{/if}}
+- Add a dependency only when the task needs it, and install it with {{packageManager}}
+
+## Production rules
+
+- Validate every input from outside the app (request bodies, query strings, form data) with Zod before you use it{{#unless useAuth}}{{#if (eq framework 'nextjs')}} (add `zod` with {{packageManager}} first){{/if}}{{#if (eq framework 'tanstack')}} (add `zod` with {{packageManager}} first){{/if}}{{/unless}}
+- Never log or return secrets, tokens, or passwords. Error responses get a short message and the right status code, never a stack trace
+{{#unless (eq database 'none')}}
+- Query the database through {{#if (eq database 'prisma')}}Prisma{{/if}}{{#if (eq database 'drizzle')}}Drizzle{{/if}}{{#if (eq database 'mongoose')}}Mongoose{{/if}}, never with SQL or queries built from strings
+{{/unless}}
+{{#if (eq framework 'express')}}
+- Keep the security middleware in `src/index.ts` (`helmet`, `cors`{{#if useRateLimit}}, the rate limiter{{/if}}) in place. Set `CORS_ORIGIN` to your real origins in production
+{{/if}}
+{{#if (eq framework 'nestjs')}}
+- Keep the security setup in `src/main.ts` and `src/app.module.ts` in place. Set `CORS_ORIGIN` to your real origins in production
+{{/if}}
+{{#if (eq framework 'nextjs')}}
+- Server first: do not `await` data at the top of a page or layout, which holds back the whole page. Move each `await` into the component that needs the data and wrap that component in `<Suspense>` with a fallback, so the rest of the page is sent at once{{#if useAuth}}. `app/dashboard/page.tsx` shows the pattern with `getSession()`{{/if}}
+- Code that reads secrets or the database stays on the server. Only variables prefixed with `NEXT_PUBLIC_` reach the browser, so never put a secret in one
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- Code that reads secrets or the database runs in server functions or server routes. Only variables prefixed with `VITE_` reach the browser, so never put a secret in one
+{{/if}}
+{{#if useAuth}}
+{{#if (eq framework 'nextjs')}}
+- Check the session on the server in every protected page, route handler, and server action. Hiding a button in the UI does not protect anything
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- Check the session on the server in every protected route and server function. Hiding a button in the UI does not protect anything
+{{/if}}
+{{/if}}
+{{#if (eq framework 'express')}}
+{{#if useAuth}}
+- Check the session on the server in every protected route with `requireAuth`
+{{/if}}
+- Keep `GET /health` fast and free of auth{{#if useRateLimit}} and rate limiting{{/if}}, so hosts can check that the app is up
+{{/if}}
+{{#if (eq framework 'nestjs')}}
+- Keep `GET /health` fast and free of auth{{#if useRateLimit}} and rate limiting{{/if}}, so hosts can check that the app is up
+{{/if}}
+- Keep changes small and focused on the task. Do not add layers, abstractions, or files the task does not need
+
+## When you are unsure
+
+The libraries here may be newer than what you know. When you are not sure how an API works, read the official docs for the version in `package.json` instead of guessing:
+
+{{#if (eq framework 'express')}}
+- Express 5: https://expressjs.com/en/5x/api.html
+{{/if}}
+{{#if (eq framework 'nestjs')}}
+- NestJS: https://docs.nestjs.com
+{{/if}}
+{{#if (eq framework 'nextjs')}}
+- Next.js: https://nextjs.org/docs
+{{/if}}
+{{#if (eq framework 'tanstack')}}
+- TanStack Start: https://tanstack.com/start/latest/docs
+{{/if}}
+{{#if (eq database 'prisma')}}
+- Prisma: https://www.prisma.io/docs
+{{/if}}
+{{#if (eq database 'drizzle')}}
+- Drizzle: https://orm.drizzle.team/docs/overview
+{{/if}}
+{{#if (eq database 'mongoose')}}
+- Mongoose: https://mongoosejs.com/docs
+{{/if}}
+{{#if useAuth}}
+- Better Auth: https://www.better-auth.com/docs
+{{#if (eq framework 'nestjs')}}
+- NestJS Better Auth integration: https://github.com/ThallesP/nestjs-better-auth
+{{/if}}
+{{/if}}
+- Zod: https://zod.dev
+
+If the docs and this file disagree, follow the docs and say so.

package/templates/modules/agents/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/modules/agents/config.json

@@ -0,0 +1,10 @@
+{
+  "id": "agents",
+  "name": "AI agent instructions",
+  "description": "An AGENTS.md that tells AI coding agents how this project is built, run, and checked, and a CLAUDE.md that points Claude Code to it",
+  "type": "feature",
+  "dependencies": {},
+  "devDependencies": {},
+  "scripts": {},
+  "envVars": {}
+}