@next-friday/create-app 9.6.0 → 9.7.0

package/README.md

@@ -31,7 +31,7 @@ Every stack is built from [`templates/base`](templates/base), which holds the sh
 - **Code quality:** TypeScript, ESLint and Prettier with the Next Friday configs, Vitest with coverage, fast-check, Knip, dependency-cruiser, editorconfig-checker, and sort-package-json.
 - **Git hooks:** Husky runs gitleaks, `pnpm rules:check`, and lint-staged before each commit, commitlint on each message, and `pnpm check` before each push. After the first commit, commits to `main` are blocked, and local merges into `main` always are; pushes to `main` are blocked once it exists on the remote.
 - **CI:** GitHub Actions run the static checks, tests with patch coverage, the build, end-to-end tests for Next.js and Payload, a container build and vulnerability scan, Semgrep, OSV-Scanner, CodeQL, dependency review, OpenSSF Scorecard, gitleaks, TruffleHog, zizmor, and pull request title validation. Dependabot keeps dependencies current.
-- **Deployment:** a `Dockerfile` that runs as the `node` user, and a Railway workflow that promotes one commit through `dev`, `uat`, and `prod`.
+- **Deployment:** a `Dockerfile` that runs as the `node` user. With `--deploy railway`, also a Railway workflow that promotes one commit through `dev`, `uat`, and `prod`.
 - **Agent rules:** `CLAUDE.md` imports `AGENTS.md`. Shared rules live in `.agents/rules`, with hooks that enforce them in Claude Code and Cursor.
 
 ## Requirements
@@ -44,17 +44,18 @@ Every stack is built from [`templates/base`](templates/base), which holds the sh
 ## Options
 
 ```text
-pnpm create @next-friday/app [name] [--stack nodejs|nestjs|nextjs|payload|turborepo]
+pnpm create @next-friday/app [name] [--stack nodejs|nestjs|nextjs|payload|turborepo] [--deploy none|railway]
 ```
 
-| Option           | Description                                                                   |
-| :--------------- | :---------------------------------------------------------------------------- |
-| `name`           | Project directory and package name. Asked when left out.                      |
-| `--stack`        | `nodejs`, `nestjs`, `nextjs`, `payload`, or `turborepo`. Asked when left out. |
-| `--skip-git`     | Do not run `git init`.                                                        |
-| `--skip-install` | Do not run `pnpm install`.                                                    |
-| `-v, --version`  | Print the version.                                                            |
-| `-h, --help`     | Print the usage.                                                              |
+| Option           | Description                                                                               |
+| :--------------- | :---------------------------------------------------------------------------------------- |
+| `name`           | Project directory and package name. Asked when left out.                                  |
+| `--stack`        | `nodejs`, `nestjs`, `nextjs`, `payload`, or `turborepo`. Asked when left out.             |
+| `--deploy`       | Deploy target: `none` or `railway`. The default is `none`, which adds no deploy workflow. |
+| `--skip-git`     | Do not run `git init`.                                                                    |
+| `--skip-install` | Do not run `pnpm install`.                                                                |
+| `-v, --version`  | Print the version.                                                                        |
+| `-h, --help`     | Print the usage.                                                                          |
 
 The name must:
 

package/dist/main.mjs

@@ -117,6 +117,16 @@ function validateProjectName(name, cwd) {
 function ownEntries(directory) {
 	return readdirSync(directory).filter((entry) => entry !== ".git");
 }
+// src/deploy-targets.ts
+const deployTargets = ["none", "railway"];
+/**
+* Check whether a string names a supported deploy target.
+* @param value - Deploy target from the command line.
+* @returns Whether `value` is a supported deploy target.
+*/
+function isDeployTarget(value) {
+	return deployTargets.some((target) => target === value);
+}
 // src/stacks.ts
 const stacks = [
 	{
@@ -173,10 +183,11 @@ function templateName(stack) {
 	return `next-friday-template-${stack}`;
 }
 // src/arguments.ts
-const usage = `Usage: pnpm create @next-friday/app [name] [--stack ${stacks.map((stack) => stack.id).join("|")}]
+const usage = `Usage: pnpm create @next-friday/app [name] [--stack ${stacks.map((stack) => stack.id).join("|")}] [--deploy ${deployTargets.join("|")}]
 
   name            Project directory and package name, or . for the current directory. Asked when left out.
   --stack         Template stack. Asked when left out.
+  --deploy        Deploy target: ${deployTargets.join(" or ")}. The default is none.
   --skip-git      Do not run git init.
   --skip-install  Do not run pnpm install.
   -v, --version   Show the version.
@@ -192,6 +203,10 @@ function parseCliArguments(cliArguments) {
 		allowPositionals: true,
 		options: {
 			stack: { type: "string" },
+			deploy: {
+				type: "string",
+				default: "none"
+			},
 			"skip-git": {
 				type: "boolean",
 				default: false
@@ -212,23 +227,33 @@ function parseCliArguments(cliArguments) {
 			}
 		}
 	});
-	const { help, stack, version } = values;
+	const { deploy, help, stack, version } = values;
 	const isInformational = help || version;
 	if (!isInformational && positionals.length > 1) throw new Error(`Pass one project name, not ${positionals.length}: ${positionals.join(" ")}.`);
 	const [name] = positionals;
-	if (!isInformational && stack !== void 0 && !isStackId(stack)) {
-		const ids = stacks.map((supported) => supported.id).join(", ");
-		throw new Error(`Unknown stack "${stack}". Use one of: ${ids}.`);
-	}
+	if (!isInformational) assertKnownChoices(stack, deploy);
 	return {
 		help,
 		name,
 		version,
+		deploy: isDeployTarget(deploy) ? deploy : "none",
 		stack: stack !== void 0 && isStackId(stack) ? stack : void 0,
 		skipGit: values["skip-git"],
 		skipInstall: values["skip-install"]
 	};
 }
+/**
+* Throw when the stack or the deploy target is not one the CLI supports.
+* @param stack - Stack from the command line, or `undefined` when left out.
+* @param deploy - Deploy target from the command line.
+*/
+function assertKnownChoices(stack, deploy) {
+	if (stack !== void 0 && !isStackId(stack)) {
+		const ids = stacks.map((supported) => supported.id).join(", ");
+		throw new Error(`Unknown stack "${stack}". Use one of: ${ids}.`);
+	}
+	if (!isDeployTarget(deploy)) throw new Error(`Unknown deploy target "${deploy}". Use one of: ${deployTargets.join(", ")}.`);
+}
 // src/rename.ts
 /**
 * Replace the template name with the project name in every text file.
@@ -245,6 +270,45 @@ async function renameProject(directory, from, to) {
 		await writeFile(file, text.replaceAll(from, () => to));
 	}));
 }
+// src/deploy-sections.ts
+const marker = /^\s*(?:#|\/\/|<!--)\s*deploy:(?<name>[a-z]+)\s*(?:-->\s*)?$/u;
+const endName = "end";
+/**
+* Keep the sections of a template file marked for the chosen deploy target and remove the others.
+* A section starts at a comment line that holds `deploy:<target>` and ends at one that holds `deploy:end`.
+* Every marker line is removed, with a blank line that directly follows it.
+* @param content - Text of a copied template file.
+* @param target - Chosen deploy target.
+* @returns The text for the chosen deploy target.
+*/
+function resolveDeploySections(content, target) {
+	const kept = [];
+	let section;
+	let isAfterMarker = false;
+	for (const line of content.split("\n")) {
+		const name = marker.exec(line)?.groups?.name;
+		if (name === void 0) {
+			if (!(isAfterMarker && line.trim() === "") && (section ?? target) === target) kept.push(line);
+		} else section = sectionAfterMarker(name, section);
+		isAfterMarker = name !== void 0;
+	}
+	if (section !== void 0) throw new Error(`The deploy:${section} section has no deploy:end marker.`);
+	return kept.join("\n");
+}
+/**
+* Give the section a marker line leaves open, or throw when the marker is out of place.
+* @param name - Deploy target the marker names, or `end`.
+* @param section - Deploy target of the section the marker sits in, or `undefined` outside a section.
+* @returns The deploy target of the section now open, or `undefined` after an end marker.
+*/
+function sectionAfterMarker(name, section) {
+	if (name === endName) {
+		if (section === void 0) throw new Error("A deploy:end marker has no deploy target section to close.");
+		return;
+	}
+	if (section !== void 0) throw new Error(`A deploy:${name} marker starts inside the deploy:${section} section.`);
+	return name;
+}
 // src/create.ts
 const templatesDirectory = fileURLToPath(new URL("../templates", import.meta.url));
 const interruptSignals = [
@@ -276,7 +340,7 @@ async function create(cliArguments) {
 		const target = path.resolve(cwd, name);
 		const directory = existsSync(target) ? realpathSync(target) : target;
 		log.step(`Copying the ${stack} template.`);
-		await writeProject(stack, directory, manifestName);
+		await writeProject(stack, options.deploy, directory, manifestName);
 		log.success(`Created ${manifestName} from the ${stack} template.`);
 		const { git, isInstalled } = setUpProject(directory, options);
 		outro(nextSteps(name, stack, git, isInstalled));
@@ -294,10 +358,11 @@ async function create(cliArguments) {
 * Copy, rename, and write `.env`, removing what was written when a step fails or Ctrl+C, SIGTERM, or SIGHUP arrives.
 * An interrupt waits for the running step, so the removal does not race the copy.
 * @param stack - Supported stack id.
+* @param deploy - Supported deploy target.
 * @param directory - Project directory.
 * @param manifestName - Package name for `package.json`.
 */
-async function writeProject(stack, directory, manifestName) {
+async function writeProject(stack, deploy, directory, manifestName) {
 	const kept = existsSync(directory) ? readdirSync(directory) : void 0;
 	let isInterrupted = false;
 	const interrupt = () => {
@@ -305,7 +370,7 @@ async function writeProject(stack, directory, manifestName) {
 	};
 	for (const signal of interruptSignals) process.on(signal, interrupt);
 	try {
-		await copyTemplate(stack, directory);
+		await copyTemplate(stack, deploy, directory);
 		await renameProject(directory, templateName(stack), manifestName);
 		await writeEnvironmentFile(directory);
 		if (isInterrupted) throw new CancelledError();
@@ -382,19 +447,49 @@ function existingGit(directory) {
 	return existsSync(path.join(directory, ".git")) ? "existing" : void 0;
 }
 /**
-* Copy the shared template files, then the stack's files, into the project directory.
+* Copy the shared template files, the stack's files, and the deploy target's files into the project directory.
 * npm leaves `.gitignore` out of published packages, so the template keeps it as `_gitignore`.
 * @param stack - Supported stack id.
+* @param deploy - Supported deploy target.
 * @param directory - Project directory.
 */
-async function copyTemplate(stack, directory) {
-	for (const template of ["base", stack]) if (!existsSync(path.join(templatesDirectory, template))) throw new Error(`The ${template} template is missing from ${templatesDirectory}. Reinstall @next-friday/create-app.`);
-	await cp(path.join(templatesDirectory, "base"), directory, { recursive: true });
-	await cp(path.join(templatesDirectory, stack), directory, { recursive: true });
+async function copyTemplate(stack, deploy, directory) {
+	const deployLayer = deploy === "none" ? void 0 : `deploy-${deploy}`;
+	const required = [
+		"base",
+		stack,
+		...deployLayer === void 0 ? [] : [`${deployLayer}/base`]
+	];
+	for (const template of required) if (!existsSync(path.join(templatesDirectory, template))) throw new Error(`The ${template} template is missing from ${templatesDirectory}. Reinstall @next-friday/create-app.`);
+	const copyLayer = async (layer) => {
+		await cp(path.join(templatesDirectory, layer), directory, { recursive: true });
+	};
+	await copyLayer("base");
+	await copyLayer(stack);
+	if (deployLayer !== void 0) {
+		await copyLayer(`${deployLayer}/base`);
+		if (existsSync(path.join(templatesDirectory, deployLayer, stack))) await copyLayer(`${deployLayer}/${stack}`);
+	}
 	await rename(path.join(directory, "_gitignore"), path.join(directory, ".gitignore"));
+	await resolveDeployTarget(directory, deploy);
 	await markScriptsExecutable(directory);
 }
 /**
+* Resolve the deploy target sections of every copied file that holds a marker.
+* @param directory - Project directory.
+* @param deploy - Supported deploy target.
+*/
+async function resolveDeployTarget(directory, deploy) {
+	const files = await listProjectFiles(directory);
+	await Promise.all(files.map(async (file) => {
+		const content = await readFile(file);
+		if (!content.includes("deploy:")) return;
+		const template = content.toString();
+		const resolved = resolveDeploySections(template, deploy);
+		if (resolved !== template) await writeFile(file, resolved);
+	}));
+}
+/**
 * Make every file that starts with a shebang executable. `pnpm pack` drops the executable bit,
 * and the Git and agent hooks run these scripts directly.
 * @param directory - Project directory.

package/package.json

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

package/templates/base/SETUP.md

@@ -64,7 +64,10 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 
   Rulesets in a private repository need GitHub Pro, Team, or Enterprise; on GitHub Free, make the repository public or upgrade.
 
-- **Secrets and variables → Actions → Variables:** in a private repository, set `CODE_SCANNING` to `true` to run CodeQL, Scorecard, and Dependency Review, which need GitHub Code Security there; public repositories run them without it. Set `DEPLOY_ENABLED` to `true` when each push to `main` that passes CI should deploy to `dev`; the README's deploy section sets up the environments.
+- **Secrets and variables → Actions → Variables:** in a private repository, set `CODE_SCANNING` to `true` to run CodeQL, Scorecard, and Dependency Review, which need GitHub Code Security there; public repositories run them without it. Set `CONTAINER_IMAGE` to `false` to skip the job that builds and scans the container image, for a project that ships no image.
+<!-- deploy:railway -->
+- **Secrets and variables → Actions → Variables:** set `DEPLOY_ENABLED` to `true` when each push to `main` that passes CI should deploy to `dev`; the README's deploy section sets up the environments.
+<!-- deploy:end -->
 - Create the `needs triage` label, which the issue forms apply: `gh label create "needs triage"`.
 
 **Check:** a test pull request shows the two required checks and asks for a code owner's review.
@@ -94,7 +97,12 @@ Replace `security@example.com` in `SECURITY.md` with the contact the security po
 - **Sources of truth (engineering lead):** for each artifact, name one system as the source of truth: this repository, an existing tool such as Jira, or, as the minimum, a link both ways (the record id in the file and the commit SHA in the record).
 - **Higher risk (engineering lead):** decide which changes count as higher risk. A tech lead or architect approves their specs and plans.
 - **Policies (each policy owner, with an engineer):** the plugin ships a default for each area, `plugins/sdlc/claude-code/skills/<area>-policy/SKILL.md` (security: OWASP ASVS 5.0.0 Level 1; UX: WCAG 2.2 Level AA; compliance: the OECD privacy principles; brand: one declared source for every brand value). Review it. To replace a default, add the organization's own rules in `.agents/skills/<area>-policy/SKILL.md` in the project: that file wins over the plugin's default, and the `CODEOWNERS` line of step 2 for that area makes the policy owner its code owner. Do not edit the plugin's copy. Then run `pnpm rules:sync`, which renders the project's own policy skill for Claude Code and Cursor. Test that the skill triggers: ask for the relevant task in different ways and confirm the skill loads each time.
+<!-- deploy:railway -->
 - **Production gate (engineering leadership, with change management and compliance):** name the release managers and add them as required reviewers on the `prod` environment, as the README's deploy section describes. `.agents/hooks/agent-production-gate.sh` blocks an agent's shell commands that dispatch a `prod` deploy, run a Railway command with `prod` as its environment, or push a release tag. It does not read MCP tools. A release manager whose own agent session must do one of these starts the agent with `RELEASE_APPROVAL` set to the approval record, for example `RELEASE_APPROVAL=CHG-123 claude`. The value lifts the gate only when it matches the extended regular expression on the first line of `.agents/release-approval-form`, shipped as `^[A-Z]+-[0-9]+$`; set that line to the form of your organization's approval records. Each gate hook appends its decisions to `.agents/logs/gate-decisions.jsonl`, which git ignores: the time, the hook, the decision, the session, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name. A record holds no command text and no path.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate (engineering leadership, with change management and compliance):** name the release managers and add them as required reviewers on the `prod` environment, as the README's deploy section describes. `.agents/hooks/agent-production-gate.sh` blocks an agent's shell commands that dispatch a `prod` deploy or push a release tag. It does not read MCP tools. A release manager whose own agent session must do one of these starts the agent with `RELEASE_APPROVAL` set to the approval record, for example `RELEASE_APPROVAL=CHG-123 claude`. The value lifts the gate only when it matches the extended regular expression on the first line of `.agents/release-approval-form`, shipped as `^[A-Z]+-[0-9]+$`; set that line to the form of your organization's approval records. Each gate hook appends its decisions to `.agents/logs/gate-decisions.jsonl`, which git ignores: the time, the hook, the decision, the session, and the reason for a block, and, when the production gate is lifted, the approval value and the Git user name. A record holds no command text and no path.
+<!-- deploy:end -->
 - **Review (tech lead):** `.agents/review.md` names this stack's generated files to skip; add a path when the project gains a generated file, then run `pnpm rules:sync`, which renders it to `REVIEW.md` for Claude Code Review. Once a month, rate the review findings and tune `.agents/review.md`.
 - **People without Git experience:** connect GitHub to Claude (claude.ai or Cowork), so Claude commits `intent.md` for them.
 

package/templates/deploy-railway/turborepo/turbo.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://turborepo.dev/schema.json",
+  "futureFlags": {
+    "affectedUsingTaskInputs": true
+  },
+  "globalDependencies": [
+    ".dockerignore",
+    ".env",
+    "package.json",
+    "pnpm-workspace.yaml",
+    "railway.json"
+  ],
+  "globalPassThroughEnv": [
+    "APP_URL",
+    "CI",
+    "DATABASE_URL",
+    "NEXT_TELEMETRY_DISABLED",
+    "PAYLOAD_SECRET"
+  ],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
+      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**"]
+    },
+    "depcruise": {
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "start": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test": {
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test:changed": {
+      "cache": false,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test:coverage": {
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
+      "outputs": ["coverage/**"]
+    },
+    "test:e2e": {
+      "cache": false,
+      "dependsOn": ["build"],
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "test:watch": {
+      "cache": false,
+      "persistent": true,
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
+    },
+    "typecheck": {
+      "dependsOn": ["^typecheck"],
+      "inputs": ["$TURBO_DEFAULT$", "!README.md"],
+      "outputs": [".next/types/**", "next-env.d.ts"]
+    }
+  }
+}

package/templates/nestjs/AGENTS.md

@@ -45,7 +45,12 @@ The `verifier` subagent starts the app with `pnpm start:dev`. It exercises the c
 
 When Claude makes a mistake twice, add the correction here.
 
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nestjs/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). The platform sets `PORT`.
+# Runs on any OCI container platform. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS base

package/templates/nestjs/README.md

@@ -34,13 +34,15 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
-The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`; Railway sets it automatically. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
+The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
 
 ```sh
 docker build -t app .
 docker run --env PORT=3000 --publish 3000:3000 app
 ```
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -56,6 +58,18 @@ docker run --env PORT=3000 --publish 3000:3000 app
 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`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/nextjs/AGENTS.md

@@ -46,7 +46,12 @@ The `verifier` subagent starts the app with `pnpm dev`. It exercises the changed
 When Claude makes a mistake twice, add the correction here.
 
 - **First end-to-end run**: run `pnpm exec playwright install chromium` once. `pnpm test:e2e` starts the development server unless one is already running.
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nextjs/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/nextjs/README.md

@@ -32,7 +32,7 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
-The `Dockerfile` builds a standalone production image that runs as the `node` user, for platforms such as Railway. The server listens on `PORT`, or 3000 when it is unset.
+The `Dockerfile` builds a standalone production image that runs as the `node` user for a container platform. The server listens on `PORT`, or 3000 when it is unset.
 
 ```sh
 docker build -t app .
@@ -41,6 +41,8 @@ docker run --publish 3000:3000 app
 
 On Vercel, deploy without the image; the Next.js preset takes precedence over the `Dockerfile`.
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -56,6 +58,18 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
 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`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/nodejs/AGENTS.md

@@ -44,7 +44,12 @@ The `verifier` subagent starts the app with `pnpm start:dev`. It exercises the c
 
 When Claude makes a mistake twice, add the correction here.
 
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/nodejs/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). The platform sets `PORT`.
+# Runs on any OCI container platform. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS base

package/templates/nodejs/README.md

@@ -32,13 +32,15 @@ CI also runs the build, the container image scan, and the security scans, includ
 
 ## Container
 
-The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`; Railway sets it automatically. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
+The `Dockerfile` builds a production image that runs as a non-root user (UID 1000). The platform must set `PORT`. The build needs `pnpm-lock.yaml`, so run `pnpm install` once before the first `docker build`.
 
 ```sh
 docker build -t app .
 docker run --env PORT=3000 --publish 3000:3000 app
 ```
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -54,6 +56,18 @@ docker run --env PORT=3000 --publish 3000:3000 app
 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`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/payload/AGENTS.md

@@ -49,7 +49,12 @@ The `verifier` subagent starts the app with `pnpm dev`, which needs a PostgreSQL
 When Claude makes a mistake twice, add the correction here.
 
 - **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`.
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/payload/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/payload/README.md

@@ -48,7 +48,7 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
-The `Dockerfile` builds a standalone production image that runs as the `node` user, for platforms such as Railway. The server listens on `PORT`, or 3000 when it is unset, and needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`, the public URL that Payload accepts cookie-authenticated and cross-origin requests from.
+The `Dockerfile` builds a standalone production image that runs as the `node` user for a container platform. The server listens on `PORT`, or 3000 when it is unset, and needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`, the public URL that Payload accepts cookie-authenticated and cross-origin requests from.
 
 ```sh
 docker build -t app .
@@ -61,6 +61,8 @@ The config sets no `email` adapter, so Payload writes every email, including pas
 
 On Vercel, deploy without the image; the Next.js preset takes precedence over the `Dockerfile`.
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
@@ -82,6 +84,18 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
 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`.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/turborepo/AGENTS.md

@@ -52,7 +52,12 @@ When Claude makes a mistake twice, add the correction here.
 
 - **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`.
+<!-- deploy:railway -->
 - **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod`, runs a Railway CLI command that names `prod`, or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool or a Railway command without `-e` or `--environment` passes it.
+<!-- deploy:end -->
+<!-- deploy:none -->
+- **Production gate**: `.agents/hooks/agent-production-gate.sh` blocks a shell command that deploys to `prod` or pushes a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set. Any value lifts the gate except an empty value, `0`, `false`, and `no`, in any letter case. Report what is ready to promote instead. When a gated command appears only inside a message, write the text to a file with your file-editing tool, not a shell heredoc, and pass it with `git commit -F <file>` or `gh pr create --body-file <file>`. The gate reads only shell commands, so an MCP tool passes it.
+<!-- deploy:end -->
 - **Issues**: open an issue only to hand work to another person, never to give a pull request a number to close. A pull request closes an issue that already exists with `Closes #<issue>`.
 - **What belongs in the repository**: files, commit messages, and pull requests hold the change, its reason, and the checks. Write no date, log, history, mistake count, token figure, or session note into a file.
 - **Sourced requirements**: add a requirement to an intent, spec, or plan only when a person decided it or a named source says it. This includes a requirement a review bot suggests. When no person decided it and no source says it, leave it out and answer the thread with that.

package/templates/turborepo/README.md

@@ -61,6 +61,8 @@ Uploaded images, up to 10 MB each, are written to the backoffice container files
 
 On Vercel, deploy an app without its image. The Next.js preset takes precedence over the Dockerfile.
 
+<!-- deploy:railway -->
+
 ## Deploy
 
 `.github/workflows/deploy.yml` deploys both apps and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. Create one Railway service per app, with that service's Dockerfile path set to `apps/app/Dockerfile` or `apps/backoffice/Dockerfile`. The workflow stays off until you configure it:
@@ -84,7 +86,19 @@ On Vercel, deploy an app without its image. The Next.js preset takes precedence
 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 commit of the last successful deploy to that environment, found from the successful `deploy.yml` and `ci.yml` runs on `main`, 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.
 
-Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+## Deploy
+
+The project has no deploy step yet. A deploy step needs:
+
+- a workflow under `.github/workflows/` that deploys;
+- the `prod` environment under **Settings → Environments**, with the release managers as its required reviewers;
+- the image the `Dockerfile` builds.
+
+<!-- deploy:end -->
 
 ## Mobile app
 
@@ -94,6 +108,6 @@ To add an Expo app, create it under `apps/mobile`:
 2. Use `@expo/fingerprint` with `expo-github-action/fingerprint` so a pull request requests a native build only when the native layer changed ([Expo fingerprint](https://docs.expo.dev/versions/latest/sdk/fingerprint/)).
 3. Keep a single `react-native` version in the workspace. Duplicate React Native versions in one monorepo are not supported ([Expo: Monorepos](https://docs.expo.dev/guides/monorepos/)).
 
-EAS Build and Submit replace Railway for that app. CI `--affected` already includes `apps/*` and `packages/*`, so an Expo app is skipped when it did not change.
+EAS Build and Submit deploy that app, in place of the project's deploy step. CI `--affected` already includes `apps/*` and `packages/*`, so an Expo app is skipped when it did not change.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/turborepo/apps/app/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/turborepo/apps/backoffice/Dockerfile

@@ -1,4 +1,4 @@
-# Runs on any OCI platform (Railway, Fly.io, Cloud Run). On Vercel, deploy without it. The platform sets `PORT`.
+# Runs on any OCI container platform. A platform that builds Next.js itself deploys without it. The platform sets `PORT`.
 FROM \
   node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 \
   AS build

package/templates/turborepo/turbo.json

@@ -3,13 +3,7 @@
   "futureFlags": {
     "affectedUsingTaskInputs": true
   },
-  "globalDependencies": [
-    ".dockerignore",
-    ".env",
-    "package.json",
-    "pnpm-workspace.yaml",
-    "railway.json"
-  ],
+  "globalDependencies": [".dockerignore", ".env", "package.json", "pnpm-workspace.yaml"],
   "globalPassThroughEnv": [
     "APP_URL",
     "CI",