@next-friday/create-app 2.1.6 → 2.1.8

package/README.md

@@ -65,7 +65,7 @@ The name must:
 ## What the CLI does
 
 1. Copies the template into the project directory and replaces the template's package name with the project name.
-2. Writes `.env` from `.env.example`. For Payload, it sets `PAYLOAD_SECRET` to a random secret.
+2. Writes `.env` from `.env.example`. For Payload and Turborepo, it sets `PAYLOAD_SECRET` to a random secret.
 3. Runs `git init --initial-branch=main`, unless the directory is already in a Git repository.
 4. Runs `pnpm install`, which also installs the Git hooks.
 5. Prints the next steps, for example:
@@ -75,7 +75,7 @@ The name must:
    pnpm start:dev
    ```
 
-   The development script is `pnpm dev` for Next.js and Payload, and `pnpm start:dev` for Node.js and NestJS.
+   The development script is `pnpm dev` for Next.js, Payload, and Turborepo, and `pnpm start:dev` for Node.js and NestJS.
 
 Then follow **After creating a project from this template** in the project's `README.md` to make the first commit and set up the repository.
 

package/package.json

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

package/templates/base/.claude/settings.json

@@ -49,7 +49,7 @@
         ]
       },
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell|Monitor",
         "hooks": [
           {
             "type": "command",

package/templates/base/.github/workflows/deploy.yml

@@ -33,6 +33,7 @@ concurrency:
 jobs:
   verify:
     name: Verify the requested commit
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -66,13 +67,14 @@ jobs:
             prod)
               previous=uat
               export EXPECTED_TITLE="Deploy $COMMIT_SHA to uat"
-              deployed="$(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?event=workflow_dispatch&status=success&per_page=100" --jq '.workflow_runs[] | select(.display_title == env.EXPECTED_TITLE) | .id' | wc -l)"
+              deployed="$(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?event=workflow_dispatch&status=success&branch=main&per_page=100" --jq '.workflow_runs[] | select(.display_title == env.EXPECTED_TITLE) | .id' | wc -l)"
               ;;
           esac
           [[ "$deployed" -gt 0 ]] || { echo "::error::$COMMIT_SHA has no successful $previous deployment; promote through $previous first"; exit 1; }
 
   deploy:
     name: Deploy to ${{ inputs.environment }}
+    if: github.ref == 'refs/heads/main'
     needs: verify
     runs-on: ubuntu-latest
     timeout-minutes: 30

package/templates/nestjs/AGENTS.md

@@ -1,7 +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.
-- 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 writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+
+## Related documentation
+
+- [README.md](README.md): scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests

package/templates/nestjs/README.md

@@ -68,7 +68,7 @@ On Vercel, the zero-configuration NestJS preset takes precedence over the `Docke
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/nextjs/AGENTS.md

@@ -1,10 +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.
-- 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 writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+
+## Related documentation
+
+- [README.md](README.md): scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/templates/nextjs/README.md

@@ -64,7 +64,7 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/nodejs/AGENTS.md

@@ -1,7 +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.
-- 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 writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+
+## Related documentation
+
+- [README.md](README.md): scripts, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests

package/templates/nodejs/README.md

@@ -64,7 +64,7 @@ docker run --env PORT=3000 --publish 3000:3000 app
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/payload/AGENTS.md

@@ -1,11 +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.
-- 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 writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+
+## 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/payload/README.md

@@ -88,7 +88,7 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
    - the `RAILWAY_SERVICE` variable: the service name;
    - the `APP_URL` variable: the public `https://` URL.
 
-   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.

package/templates/turborepo/.github/workflows/ci.yml

@@ -214,37 +214,46 @@ jobs:
             done
           } >> "$GITHUB_OUTPUT"
       - name: Lint Dockerfile
+        env:
+          AFFECTED_APP: ${{ steps.affected.outputs.app }}
+          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
         run: |
           curl --silent --show-error --fail --location --output hadolint \
             "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-linux-x86_64"
           echo "${HADOLINT_SHA256}  hadolint" | sha256sum --check --strict
           chmod +x hadolint
           files=()
-          if [[ "${{ steps.affected.outputs.app }}" == "true" ]]; then
+          if [[ "$AFFECTED_APP" == "true" ]]; then
             files+=(apps/app/Dockerfile)
           fi
-          if [[ "${{ steps.affected.outputs.backoffice }}" == "true" ]]; then
+          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
             files+=(apps/backoffice/Dockerfile)
           fi
           if [[ "${#files[@]}" -gt 0 ]]; then
             ./hadolint "${files[@]}"
           fi
       - name: Build images
+        env:
+          AFFECTED_APP: ${{ steps.affected.outputs.app }}
+          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
         run: |
-          if [[ "${{ steps.affected.outputs.app }}" == "true" ]]; then
+          if [[ "$AFFECTED_APP" == "true" ]]; then
             docker build --file apps/app/Dockerfile --tag app:ci .
           fi
-          if [[ "${{ steps.affected.outputs.backoffice }}" == "true" ]]; then
+          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
             docker build --file apps/backoffice/Dockerfile --tag backoffice:ci .
           fi
       - name: Smoke test images
+        env:
+          AFFECTED_APP: ${{ steps.affected.outputs.app }}
+          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
         id: smoke
         run: |
-          if [[ "${{ steps.affected.outputs.app }}" == "true" ]]; then
+          if [[ "$AFFECTED_APP" == "true" ]]; then
             docker run --detach --name app --env PORT=3000 --publish 3000:3000 app:ci
             curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3000/health
           fi
-          if [[ "${{ steps.affected.outputs.backoffice }}" == "true" ]]; then
+          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
             docker run --detach --name backoffice --env PORT=3001 --env DATABASE_URL=postgres://build-only@localhost/build-only --env PAYLOAD_SECRET=ci-only-secret --env APP_URL=http://localhost:3001 --publish 3001:3001 backoffice:ci
             curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3001/health
           fi
@@ -258,16 +267,19 @@ jobs:
             docker logs backoffice
           fi
       - name: Scan images for vulnerabilities
+        env:
+          AFFECTED_APP: ${{ steps.affected.outputs.app }}
+          AFFECTED_BACKOFFICE: ${{ steps.affected.outputs.backoffice }}
         run: |
           archive="trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz"
           curl --silent --show-error --fail --location --output "$archive" \
             "https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/${archive}"
           echo "${TRIVY_SHA256}  ${archive}" | sha256sum --check --strict
           tar --extract --gzip --file "$archive" trivy
-          if [[ "${{ steps.affected.outputs.app }}" == "true" ]]; then
+          if [[ "$AFFECTED_APP" == "true" ]]; then
             ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
           fi
-          if [[ "${{ steps.affected.outputs.backoffice }}" == "true" ]]; then
+          if [[ "$AFFECTED_BACKOFFICE" == "true" ]]; then
             ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress backoffice:ci
           fi
 

package/templates/turborepo/.github/workflows/deploy.yml

@@ -33,6 +33,7 @@ concurrency:
 jobs:
   verify:
     name: Verify the requested commit
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -66,13 +67,14 @@ jobs:
             prod)
               previous=uat
               export EXPECTED_TITLE="Deploy $COMMIT_SHA to uat"
-              deployed="$(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?event=workflow_dispatch&status=success&per_page=100" --jq '.workflow_runs[] | select(.display_title == env.EXPECTED_TITLE) | .id' | wc -l)"
+              deployed="$(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?event=workflow_dispatch&status=success&branch=main&per_page=100" --jq '.workflow_runs[] | select(.display_title == env.EXPECTED_TITLE) | .id' | wc -l)"
               ;;
           esac
           [[ "$deployed" -gt 0 ]] || { echo "::error::$COMMIT_SHA has no successful $previous deployment; promote through $previous first"; exit 1; }
 
   deploy:
     name: Deploy to ${{ inputs.environment }}
+    if: github.ref == 'refs/heads/main'
     needs: verify
     runs-on: ubuntu-latest
     timeout-minutes: 40
@@ -134,7 +136,7 @@ jobs:
               latest="$completed"
               previous="$candidate"
             fi
-          done < <(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?status=success&per_page=50" --jq '.workflow_runs[] | [.id, .display_title] | @tsv')
+          done < <(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?status=success&branch=main&per_page=50" --jq '.workflow_runs[] | [.id, .display_title] | @tsv')
           while IFS=$'\t' read -r run_id head_sha; do
             [[ -z "$run_id" || "$head_sha" == "$COMMIT_SHA" ]] && continue
             completed="$(gh api "repos/$REPOSITORY/actions/runs/$run_id/jobs" | jq -r --arg env "$RAILWAY_ENVIRONMENT" '[.jobs[] | select(.conclusion == "success" and .name == "Deploy to \($env) / Deploy to \($env)") | .completed_at] | max // empty')"

package/templates/turborepo/AGENTS.md

@@ -1,19 +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.
-- 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 --filter ./apps/app 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 writes to a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`. It is a convenience, not a security boundary: CI and code-owner review are the boundary.
+
+## Related documentation
+
+- [README.md](README.md): environment variables, scripts, CI caching, container, deploy
+- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests

package/templates/turborepo/README.md

@@ -94,7 +94,7 @@ On Vercel, deploy an app without its image. The Next.js preset takes precedence
    - the `APP_URL` variable: the public Next.js `https://` URL;
    - the `BACKOFFICE_URL` variable: the public backoffice `https://` URL.
 
-   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+   Limit `dev`, `uat`, and `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
 
 3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`. The workflow compares the commit with the last GitHub deployment to that environment and runs `railway up` only for services whose packages changed. A promotion through `uat` or `prod` uses the same comparison against the commit last deployed there, so several commits still ship every changed service. The first deploy to an environment ships both services.
 4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health` on each service it uploaded.