@next-friday/create-app 2.1.5 → 2.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next-friday/create-app",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "Create a Next Friday project from a template.",
   "keywords": [
     "create",

package/templates/base/.agents/rules/agent-owned-work.md

@@ -0,0 +1,3 @@
+# Agent-Owned Work
+
+Do the work that an agent, a script, or an API can do; do not hand it to the user. Before you ask the user, check the code, data, docs, and tools that already exist. Ask only for what no one else can provide, such as payment, legal identity, or a business fact recorded nowhere. Constitution edits follow `constitution-changes.md`.

package/templates/base/.agents/rules/constitution-changes.md

@@ -0,0 +1,5 @@
+# Constitution Changes
+
+The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
+
+A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.

package/templates/base/.agents/rules/dependency-security.md

@@ -1,5 +1,5 @@
 # Dependencies
 
-Add a dependency when active code, tests, build tooling, or a documented contract uses it, and native or existing project capabilities do not. Assess cadence, license, advisories, compatibility, and transitives first. Place it in the manifest of the project that imports it, in the ecosystem category that matches its role.
+Add a dependency when active code, tests, build tooling, or a documented contract uses it, and neither the platform nor existing project code covers the need. A maintained library that replaces custom code meets this test; `platform-and-library-first.md` sets the order. Assess cadence, license, advisories, compatibility, and transitives first. Place it in the manifest of the project that imports it, in the ecosystem category that matches its role.
 
 Resolve a vulnerability that Dependabot or OSV-Scanner reports by upgrading the dependency. For a transitive dependency, add a pnpm override in `pnpm-workspace.yaml`. When no fix exists, record the accepted risk as `no-suppression.md` describes.

package/templates/base/.agents/rules/evidence-before-claims.md

@@ -0,0 +1,3 @@
+# Evidence
+
+Verify a claim about files, commands, APIs, versions, or limits before you state or write it, and cite its source: `path:line`, command output, or an official documentation URL. Do not write a value without a source into code or docs; state it as unverified and give the reason.

package/templates/base/.agents/rules/platform-and-library-first.md

@@ -0,0 +1,9 @@
+# Platform and Library First
+
+Meet a need with the first option that covers it:
+
+1. A built-in feature of the framework or platform.
+2. A maintained library or an official template.
+3. Custom code. State in the pull request why the first two fall short.
+
+Add a library as `dependency-security.md` describes.

package/templates/base/.agents/rules/structured-logging.md

@@ -0,0 +1,3 @@
+# Logging
+
+Application code logs through the stack's logging library or the framework's logger, never `console.*`. Write structured records, and send them to a store that keeps them longer than the host does.

package/templates/base/.claude/rules/agent-owned-work.md

@@ -0,0 +1 @@
+@../../.agents/rules/agent-owned-work.md

package/templates/base/.claude/rules/constitution-changes.md

@@ -0,0 +1 @@
+@../../.agents/rules/constitution-changes.md

package/templates/base/.claude/rules/dependency-security.md

@@ -7,6 +7,6 @@ paths:
 
 # Dependencies
 
-Add a dependency when active code, tests, build tooling, or a documented contract uses it, and native or existing project capabilities do not. Assess cadence, license, advisories, compatibility, and transitives first. Place it in the manifest of the project that imports it, in the ecosystem category that matches its role.
+Add a dependency when active code, tests, build tooling, or a documented contract uses it, and neither the platform nor existing project code covers the need. A maintained library that replaces custom code meets this test; `platform-and-library-first.md` sets the order. Assess cadence, license, advisories, compatibility, and transitives first. Place it in the manifest of the project that imports it, in the ecosystem category that matches its role.
 
 Resolve a vulnerability that Dependabot or OSV-Scanner reports by upgrading the dependency. For a transitive dependency, add a pnpm override in `pnpm-workspace.yaml`. When no fix exists, record the accepted risk as `no-suppression.md` describes.

package/templates/base/.claude/rules/evidence-before-claims.md

@@ -0,0 +1 @@
+@../../.agents/rules/evidence-before-claims.md

package/templates/base/.claude/rules/platform-and-library-first.md

@@ -0,0 +1 @@
+@../../.agents/rules/platform-and-library-first.md

package/templates/base/.claude/rules/structured-logging.md

@@ -0,0 +1 @@
+@../../.agents/rules/structured-logging.md

package/templates/base/.cursor/BUGBOT.md

@@ -3,17 +3,22 @@
 Review pull requests against the project's agent guide and rules:
 
 - [Agent guide](../AGENTS.md)
+- [Agent-Owned Work](../.agents/rules/agent-owned-work.md)
 - [Owned Checks](../.agents/rules/automation-owned-checks.md)
 - [Required Comments](../.agents/rules/code-comments.md)
 - [Codebase Hygiene](../.agents/rules/codebase-hygiene.md)
+- [Constitution Changes](../.agents/rules/constitution-changes.md)
 - [Current State](../.agents/rules/current-state-authority.md)
 - [Demand-Driven Configuration](../.agents/rules/demand-driven-configuration.md)
 - [Dependencies](../.agents/rules/dependency-security.md)
 - [Descriptive Naming](../.agents/rules/descriptive-naming.md)
 - [Test Admission](../.agents/rules/deterministic-testing.md)
 - [Diagnostics](../.agents/rules/diagnostics-and-error-handling.md)
+- [Evidence](../.agents/rules/evidence-before-claims.md)
 - [Git Workflow](../.agents/rules/git-workflow.md)
 - [Findings](../.agents/rules/no-suppression.md)
+- [Platform and Library First](../.agents/rules/platform-and-library-first.md)
 - [Scripts](../.agents/rules/script-driven-changes.md)
 - [Sibling Style](../.agents/rules/single-author-style.md)
+- [Logging](../.agents/rules/structured-logging.md)
 - [TypeScript-First](../.agents/rules/typescript-first.md)

package/templates/base/.cursor/rules/agent-owned-work.mdc

@@ -0,0 +1,8 @@
+---
+description: "Agent-owned work: do what an agent, script, or API can do instead of asking the user"
+alwaysApply: true
+---
+
+# Agent-Owned Work
+
+Do the work that an agent, a script, or an API can do; do not hand it to the user. Before you ask the user, check the code, data, docs, and tools that already exist. Ask only for what no one else can provide, such as payment, legal identity, or a business fact recorded nowhere. Constitution edits follow `constitution-changes.md`.

package/templates/base/.cursor/rules/constitution-changes.mdc

@@ -0,0 +1,10 @@
+---
+description: "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+alwaysApply: true
+---
+
+# Constitution Changes
+
+The constitution is the set of files that agent settings deny to agents: rules, hooks, lint, format, and commit configuration, and the agent settings themselves. It is company policy.
+
+A developer changes the constitution through a dedicated issue, never inside a feature pull request. When a task needs a constitution change, propose it to the user, reference that issue, and wait for it to merge before the task depends on it.

package/templates/base/.cursor/rules/dependency-security.mdc

@@ -6,6 +6,6 @@ alwaysApply: false
 
 # Dependencies
 
-Add a dependency when active code, tests, build tooling, or a documented contract uses it, and native or existing project capabilities do not. Assess cadence, license, advisories, compatibility, and transitives first. Place it in the manifest of the project that imports it, in the ecosystem category that matches its role.
+Add a dependency when active code, tests, build tooling, or a documented contract uses it, and neither the platform nor existing project code covers the need. A maintained library that replaces custom code meets this test; `platform-and-library-first.md` sets the order. Assess cadence, license, advisories, compatibility, and transitives first. Place it in the manifest of the project that imports it, in the ecosystem category that matches its role.
 
 Resolve a vulnerability that Dependabot or OSV-Scanner reports by upgrading the dependency. For a transitive dependency, add a pnpm override in `pnpm-workspace.yaml`. When no fix exists, record the accepted risk as `no-suppression.md` describes.

package/templates/base/.cursor/rules/evidence-before-claims.mdc

@@ -0,0 +1,8 @@
+---
+description: "Evidence: verify and cite a claim before stating or writing it"
+alwaysApply: true
+---
+
+# Evidence
+
+Verify a claim about files, commands, APIs, versions, or limits before you state or write it, and cite its source: `path:line`, command output, or an official documentation URL. Do not write a value without a source into code or docs; state it as unverified and give the reason.

package/templates/base/.cursor/rules/platform-and-library-first.mdc

@@ -0,0 +1,14 @@
+---
+description: "Platform and library first: use built-in features, then maintained libraries, then custom code"
+alwaysApply: true
+---
+
+# Platform and Library First
+
+Meet a need with the first option that covers it:
+
+1. A built-in feature of the framework or platform.
+2. A maintained library or an official template.
+3. Custom code. State in the pull request why the first two fall short.
+
+Add a library as `dependency-security.md` describes.

package/templates/base/.cursor/rules/structured-logging.mdc

@@ -0,0 +1,8 @@
+---
+description: "Logging: log through a logging library in structured, durable records"
+alwaysApply: true
+---
+
+# Logging
+
+Application code logs through the stack's logging library or the framework's logger, never `console.*`. Write structured records, and send them to a store that keeps them longer than the host does.

package/templates/nestjs/.agents/rules.json

@@ -1,4 +1,7 @@
 {
+  "agent-owned-work": {
+    "description": "Agent-owned work: do what an agent, script, or API can do instead of asking the user"
+  },
   "automation-owned-checks": {
     "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
   },
@@ -8,6 +11,9 @@
   "codebase-hygiene": {
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
+  "constitution-changes": {
+    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+  },
   "current-state-authority": {
     "description": "Current state: implement from user requirements and the working tree"
   },
@@ -28,18 +34,27 @@
   "diagnostics-and-error-handling": {
     "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
   },
+  "evidence-before-claims": {
+    "description": "Evidence: verify and cite a claim before stating or writing it"
+  },
   "git-workflow": {
     "description": "Git workflow: trunk-based branches, commits, and pull requests"
   },
   "no-suppression": {
     "description": "Findings: fix scanner and linter reports without inline suppressions"
   },
+  "platform-and-library-first": {
+    "description": "Platform and library first: use built-in features, then maintained libraries, then custom code"
+  },
   "script-driven-changes": {
     "description": "Scripts: apply a repeated edit across many files with a script"
   },
   "single-author-style": {
     "description": "Sibling style: match layout, naming, and composition in the same project"
   },
+  "structured-logging": {
+    "description": "Logging: log through a logging library in structured, durable records"
+  },
   "typescript-first": {
     "description": "TypeScript-first: write source, tests, and scripts as .ts",
     "globs": ["**/*.ts", "**/*.js"]

package/templates/nestjs/AGENTS.md

@@ -1,8 +1,36 @@
 # Agent guide
 
-NestJS service on pnpm. Source lives in `src/`, end-to-end tests in `test/`.
+NestJS HTTP API in TypeScript on pnpm and Node.js `>=24.15.0 <25`.
 
-- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
-- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
-- Put unit tests next to the code as `*.test.ts`; put end-to-end tests in `test/` as `*.e2e.test.ts`.
-- Read configuration from environment variables and fail when one is missing; document each variable in `.env.example`.
+## Commands
+
+| Task                        | Command                                             |
+| :-------------------------- | :-------------------------------------------------- |
+| Start with reload           | `pnpm start:dev`                                    |
+| One test                    | `pnpm vitest run src/port.test.ts -t "<test name>"` |
+| Unit tests                  | `pnpm test`, or `pnpm test:coverage`                |
+| End-to-end tests            | `pnpm test:e2e`                                     |
+| What `pre-push` runs        | `pnpm check`                                        |
+| Every check                 | `pnpm verify`                                       |
+| Render rules after a change | `pnpm rules:sync`                                   |
+
+## How it fits together
+
+- `src/main.ts` creates the app from `AppModule` on `parsePort(process.env.PORT)` with Nest's `ConsoleLogger`, which writes JSON lines when `NODE_ENV` is `production`.
+- `AppModule` imports `HealthModule`, whose Terminus controller serves `/health`. Add a feature as its own module and import it in `AppModule`.
+
+## Mandatory rules
+
+1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
+2. **Put unit tests next to the code as `src/**/*.test.ts` and end-to-end tests in `test/` as `*.e2e.test.ts`.** `vitest.config.ts` and `vitest.e2e.config.ts` collect only those patterns.
+3. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`.
+4. **Log through Nest's `Logger`.** It goes to the `ConsoleLogger` set in `src/main.ts`.
+
+## Known pitfalls
+
+- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
+
+## Related documentation
+
+- [README.md](README.md): scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests

package/templates/nextjs/.agents/rules.json

@@ -1,4 +1,7 @@
 {
+  "agent-owned-work": {
+    "description": "Agent-owned work: do what an agent, script, or API can do instead of asking the user"
+  },
   "automation-owned-checks": {
     "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
   },
@@ -8,6 +11,9 @@
   "codebase-hygiene": {
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
+  "constitution-changes": {
+    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+  },
   "current-state-authority": {
     "description": "Current state: implement from user requirements and the working tree"
   },
@@ -28,18 +34,27 @@
   "diagnostics-and-error-handling": {
     "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
   },
+  "evidence-before-claims": {
+    "description": "Evidence: verify and cite a claim before stating or writing it"
+  },
   "git-workflow": {
     "description": "Git workflow: trunk-based branches, commits, and pull requests"
   },
   "no-suppression": {
     "description": "Findings: fix scanner and linter reports without inline suppressions"
   },
+  "platform-and-library-first": {
+    "description": "Platform and library first: use built-in features, then maintained libraries, then custom code"
+  },
   "script-driven-changes": {
     "description": "Scripts: apply a repeated edit across many files with a script"
   },
   "single-author-style": {
     "description": "Sibling style: match layout, naming, and composition in the same project"
   },
+  "structured-logging": {
+    "description": "Logging: log through a logging library in structured, durable records"
+  },
   "typescript-first": {
     "description": "TypeScript-first: write source, tests, and scripts as .ts or .tsx",
     "globs": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]

package/templates/nextjs/AGENTS.md

@@ -1,11 +1,40 @@
 # Agent guide
 
-Next.js App Router application on pnpm. Routes live in `app/`.
+Next.js App Router web app with React and Tailwind CSS, in TypeScript on pnpm and Node.js `>=24.15.0 <25`.
 
-- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
-- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
-- Put unit tests next to the code as `*.test.ts`; put Playwright end-to-end tests in `test/` as `*.e2e.test.ts`. Component tests need a DOM test environment, which is not set up yet; ask the user before adding one.
-- Read configuration from environment variables and fail when one is missing; document each variable in `.env.example`.
+## Commands
+
+| Task                        | Command                                                     |
+| :-------------------------- | :---------------------------------------------------------- |
+| Start with reload           | `pnpm dev`                                                  |
+| One test                    | `pnpm vitest run app/health/route.test.ts -t "<test name>"` |
+| Unit tests                  | `pnpm test`, or `pnpm test:coverage`                        |
+| End-to-end tests            | `pnpm test:e2e`                                             |
+| What `pre-push` runs        | `pnpm check`                                                |
+| Every check                 | `pnpm verify`                                               |
+| Render rules after a change | `pnpm rules:sync`                                           |
+
+## How it fits together
+
+- Routes live in `app/`. `app/health/route.ts` serves `/health`.
+- `next.config.ts` builds `output: "standalone"`, enables Cache Components, and sets the security headers. `pnpm start` copies the static assets into `.next/standalone` and serves it.
+
+## Mandatory rules
+
+1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
+2. **Put unit tests next to the code as `app/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
+3. **Ask the user before adding component tests.** They need a DOM test environment, and Vitest runs in Node.js.
+4. **Read configuration from environment variables and fail when one is missing.** Document each variable in `.env.example`.
+
+## Known pitfalls
+
+- **First end-to-end run**: run `pnpm exec playwright install chromium` once. `pnpm test:e2e` starts the development server unless one is already running.
+- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
+
+## Related documentation
+
+- [README.md](README.md): scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/templates/nodejs/.agents/rules.json

@@ -1,4 +1,7 @@
 {
+  "agent-owned-work": {
+    "description": "Agent-owned work: do what an agent, script, or API can do instead of asking the user"
+  },
   "automation-owned-checks": {
     "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
   },
@@ -8,6 +11,9 @@
   "codebase-hygiene": {
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
+  "constitution-changes": {
+    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+  },
   "current-state-authority": {
     "description": "Current state: implement from user requirements and the working tree"
   },
@@ -28,18 +34,27 @@
   "diagnostics-and-error-handling": {
     "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
   },
+  "evidence-before-claims": {
+    "description": "Evidence: verify and cite a claim before stating or writing it"
+  },
   "git-workflow": {
     "description": "Git workflow: trunk-based branches, commits, and pull requests"
   },
   "no-suppression": {
     "description": "Findings: fix scanner and linter reports without inline suppressions"
   },
+  "platform-and-library-first": {
+    "description": "Platform and library first: use built-in features, then maintained libraries, then custom code"
+  },
   "script-driven-changes": {
     "description": "Scripts: apply a repeated edit across many files with a script"
   },
   "single-author-style": {
     "description": "Sibling style: match layout, naming, and composition in the same project"
   },
+  "structured-logging": {
+    "description": "Logging: log through a logging library in structured, durable records"
+  },
   "typescript-first": {
     "description": "TypeScript-first: write source, tests, and scripts as .ts",
     "globs": ["**/*.ts", "**/*.js"]

package/templates/nodejs/AGENTS.md

@@ -1,8 +1,34 @@
 # Agent guide
 
-Node.js HTTP service on pnpm, without a framework. Source lives in `src/`.
+TypeScript HTTP service on `node:http`, without a framework, on pnpm and Node.js `>=24.15.0 <25`.
 
-- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
-- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
-- Put tests next to the code as `*.test.ts`.
-- Read configuration from environment variables and fail when one is missing; document each variable in `.env.example`.
+## Commands
+
+| Task                        | Command                                             |
+| :-------------------------- | :-------------------------------------------------- |
+| Start with reload           | `pnpm start:dev`                                    |
+| One test                    | `pnpm vitest run src/port.test.ts -t "<test name>"` |
+| Unit tests                  | `pnpm test`, or `pnpm test:coverage`                |
+| What `pre-push` runs        | `pnpm check`                                        |
+| Every check                 | `pnpm verify`                                       |
+| Render rules after a change | `pnpm rules:sync`                                   |
+
+## How it fits together
+
+- `src/main.ts` starts `createAppServer()` from `src/server.ts` on `parsePort(process.env.PORT)`, and on `SIGTERM` or `SIGINT` stops accepting connections and closes any left after 10 seconds.
+- `src/server.ts` answers `GET` and `HEAD` `/health` and returns 404 for every other request. Routes go there.
+
+## Mandatory rules
+
+1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
+2. **Put tests next to the code as `src/**/*.test.ts`.** Vitest collects only that pattern.
+3. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`; `pnpm start` and `pnpm start:dev` load `.env`.
+
+## Known pitfalls
+
+- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
+
+## Related documentation
+
+- [README.md](README.md): scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests

package/templates/payload/.agents/rules.json

@@ -1,4 +1,7 @@
 {
+  "agent-owned-work": {
+    "description": "Agent-owned work: do what an agent, script, or API can do instead of asking the user"
+  },
   "automation-owned-checks": {
     "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
   },
@@ -8,6 +11,9 @@
   "codebase-hygiene": {
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
+  "constitution-changes": {
+    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+  },
   "current-state-authority": {
     "description": "Current state: implement from user requirements and the working tree"
   },
@@ -28,18 +34,27 @@
   "diagnostics-and-error-handling": {
     "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
   },
+  "evidence-before-claims": {
+    "description": "Evidence: verify and cite a claim before stating or writing it"
+  },
   "git-workflow": {
     "description": "Git workflow: trunk-based branches, commits, and pull requests"
   },
   "no-suppression": {
     "description": "Findings: fix scanner and linter reports without inline suppressions"
   },
+  "platform-and-library-first": {
+    "description": "Platform and library first: use built-in features, then maintained libraries, then custom code"
+  },
   "script-driven-changes": {
     "description": "Scripts: apply a repeated edit across many files with a script"
   },
   "single-author-style": {
     "description": "Sibling style: match layout, naming, and composition in the same project"
   },
+  "structured-logging": {
+    "description": "Logging: log through a logging library in structured, durable records"
+  },
   "typescript-first": {
     "description": "TypeScript-first: write source, tests, and scripts as .ts or .tsx",
     "globs": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]

package/templates/payload/AGENTS.md

@@ -1,12 +1,43 @@
 # Agent guide
 
-Payload CMS on Next.js App Router and PostgreSQL, on pnpm. Source lives in `src/`: the site in `src/app/(frontend)/`, collections in `src/collections/`, and the Payload config in `src/payload.config.ts`.
+Payload CMS on Next.js App Router and PostgreSQL, in TypeScript on pnpm and Node.js `>=24.22.1 <25`. The API is REST at `/api`.
 
-- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
-- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
-- Put unit tests next to the code as `*.test.ts`; put Playwright end-to-end tests in `test/` as `*.e2e.test.ts`. Component tests need a DOM test environment, which is not set up yet; ask the user before adding one.
-- Payload generates `src/app/(payload)/`, `src/payload-types.ts`, and `src/migrations/`. After changing a collection, regenerate them with `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`, and commit the results.
-- Read configuration through `requireEnvironment` in `src/environment.ts`; document each variable in `.env.example`.
+## Commands
+
+| Task                          | Command                                                    |
+| :---------------------------- | :--------------------------------------------------------- |
+| Start with reload             | `pnpm dev`                                                 |
+| One test                      | `pnpm vitest run src/environment.test.ts -t "<test name>"` |
+| Unit tests                    | `pnpm test`, or `pnpm test:coverage`                       |
+| End-to-end tests              | `pnpm test:e2e`                                            |
+| Regenerate after a collection | `pnpm generate:types`, `pnpm generate:importmap`           |
+| Create a migration            | `pnpm migrate:create <name>`                               |
+| What `pre-push` runs          | `pnpm check`                                               |
+| Every check                   | `pnpm verify`                                              |
+| Render rules after a change   | `pnpm rules:sync`                                          |
+
+## How it fits together
+
+- `src/payload.config.ts` wires the collections in `src/collections/` to PostgreSQL. The site lives in `src/app/(frontend)/`, and `src/app/health/route.ts` serves `/health`.
+- In development, Payload applies collection changes to the database directly. In production, the server applies the migrations in `src/migrations/` when it starts.
+
+## Mandatory rules
+
+1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
+2. **Change the schema only through collections, then regenerate and commit.** Payload generates `src/app/(payload)/`, `src/payload-types.ts`, and `src/migrations/`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
+3. **Put unit tests next to the code as `src/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
+4. **Ask the user before adding component tests.** They need a DOM test environment, and Vitest runs in Node.js.
+5. **Read configuration through `requireEnvironment` in `src/environment.ts`.** Document each variable in `.env.example`.
+
+## Known pitfalls
+
+- **Database for `pnpm dev` and end-to-end tests**: both need a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm exec playwright install chromium` once before the first `pnpm test:e2e`.
+- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
+
+## Related documentation
+
+- [README.md](README.md): environment variables, scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/templates/turborepo/.agents/rules.json

@@ -1,4 +1,7 @@
 {
+  "agent-owned-work": {
+    "description": "Agent-owned work: do what an agent, script, or API can do instead of asking the user"
+  },
   "automation-owned-checks": {
     "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
   },
@@ -8,6 +11,9 @@
   "codebase-hygiene": {
     "description": "Codebase hygiene: modify existing code instead of accumulating new code"
   },
+  "constitution-changes": {
+    "description": "Constitution changes: change rules, hooks, and agent settings only through a dedicated issue"
+  },
   "current-state-authority": {
     "description": "Current state: implement from user requirements and the working tree"
   },
@@ -28,18 +34,27 @@
   "diagnostics-and-error-handling": {
     "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
   },
+  "evidence-before-claims": {
+    "description": "Evidence: verify and cite a claim before stating or writing it"
+  },
   "git-workflow": {
     "description": "Git workflow: trunk-based branches, commits, and pull requests"
   },
   "no-suppression": {
     "description": "Findings: fix scanner and linter reports without inline suppressions"
   },
+  "platform-and-library-first": {
+    "description": "Platform and library first: use built-in features, then maintained libraries, then custom code"
+  },
   "script-driven-changes": {
     "description": "Scripts: apply a repeated edit across many files with a script"
   },
   "single-author-style": {
     "description": "Sibling style: match layout, naming, and composition in the same project"
   },
+  "structured-logging": {
+    "description": "Logging: log through a logging library in structured, durable records"
+  },
   "typescript-first": {
     "description": "TypeScript-first: write source, tests, and scripts as .ts or .tsx",
     "globs": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]

package/templates/turborepo/AGENTS.md

@@ -1,20 +1,43 @@
 # Agent guide
 
-Turborepo workspace on pnpm. `apps/app` is the Next.js site. `apps/backoffice` is the Payload CMS. Root scripts run the same checks as the other Next Friday templates and delegate framework commands with Turborepo.
+Turborepo workspace in TypeScript on pnpm and Node.js `>=24.22.1 <25`. `apps/app` is a Next.js site on port 3000. `apps/backoffice` is a Payload CMS on PostgreSQL on port 3001, with a REST API at `/api`.
 
-- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
-- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
-- Put unit tests next to the code as `*.test.ts`. Put Playwright end-to-end tests in `apps/app/test/` and `apps/backoffice/test/` as `*.e2e.test.ts`. Component tests need a DOM test environment, which is not set up yet; ask the user before adding one.
-- The Next.js site lives in `apps/app/app/`. The backoffice site lives in `apps/backoffice/src/app/(frontend)/`, collections in `apps/backoffice/src/collections/`, and the Payload config in `apps/backoffice/src/payload.config.ts`.
-- Payload generates `apps/backoffice/src/app/(payload)/`, `apps/backoffice/src/payload-types.ts`, and `apps/backoffice/src/migrations/`. After changing a collection, regenerate them with `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`, and commit the results.
-- Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`. Document each variable in `.env.example`.
+## Commands
 
-<!-- BEGIN:nextjs-agent-rules -->
+| Task                          | Command                                                                                    |
+| :---------------------------- | :----------------------------------------------------------------------------------------- |
+| Start both apps with reload   | `pnpm dev`                                                                                 |
+| One test                      | `pnpm --filter ./apps/backoffice exec vitest run src/environment.test.ts -t "<test name>"` |
+| Tests in one app              | `TURBO_FILTER=--filter=./apps/app pnpm test`                                               |
+| Unit tests                    | `pnpm test`, or `pnpm test:coverage`                                                       |
+| End-to-end tests              | `pnpm test:e2e`                                                                            |
+| Regenerate after a collection | `pnpm generate:types`, `pnpm generate:importmap`                                           |
+| Create a migration            | `pnpm migrate:create <name>`                                                               |
+| What `pre-push` runs          | `pnpm check`                                                                               |
+| Every check                   | `pnpm verify`                                                                              |
+| Render rules after a change   | `pnpm rules:sync`                                                                          |
 
-## This is NOT the Next.js you know
+## How it fits together
 
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+- Root scripts run lint, format, Knip, and the agent checks once for the workspace, and hand `build`, `test`, `typecheck`, and `depcruise` to Turborepo for each app. `TURBO_FILTER` narrows them; the default is every app.
+- The site lives in `apps/app/app/`. The backoffice site lives in `apps/backoffice/src/app/(frontend)/`, its collections in `apps/backoffice/src/collections/`, and its config in `apps/backoffice/src/payload.config.ts`. The root `generate:*` and `migrate*` scripts run in the backoffice.
+- In development, Payload applies collection changes to the database directly. In production, the backoffice applies the migrations in `apps/backoffice/src/migrations/` when it starts.
 
-This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+## Mandatory rules
 
-<!-- END:nextjs-agent-rules -->
+1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
+2. **Change the backoffice schema only through collections, then regenerate and commit.** Payload generates `apps/backoffice/src/app/(payload)/`, `apps/backoffice/src/payload-types.ts`, and `apps/backoffice/src/migrations/`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
+3. **Put unit tests next to the code and Playwright end-to-end tests in `apps/app/test/` and `apps/backoffice/test/` as `*.e2e.test.ts`.** Vitest collects `apps/app/app/**/*.test.{ts,tsx}` and `apps/backoffice/src/**/*.test.{ts,tsx}`.
+4. **Ask the user before adding component tests.** They need a DOM test environment, and Vitest runs in Node.js.
+5. **Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`.** Document each variable in `.env.example`.
+
+## Known pitfalls
+
+- **Next.js docs live per app**: this Next.js version differs from your training data. Read the guide in `apps/app/node_modules/next/dist/docs/` or `apps/backoffice/node_modules/next/dist/docs/` before writing Next.js code; the workspace root has no `next` package.
+- **Database for `pnpm dev` and end-to-end tests**: the backoffice needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm exec playwright install chromium` once before the first `pnpm test:e2e`.
+- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
+
+## Related documentation
+
+- [README.md](README.md): environment variables, scripts, CI caching, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests