@next-friday/create-app 9.6.0 → 9.7.1

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,46 @@ 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;
+	const lines = content.split("\n");
+	for (const [index, line] of lines.entries()) {
+		const name = marker.exec(line)?.groups?.name;
+		if (name === void 0) {
+			if (!(isAfterMarker && line.trim() === "" && index < lines.length - 1) && (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 +341,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 +359,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 +371,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 +448,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.1",
   "description": "Create a Next Friday project from a template.",
   "keywords": [
     "create",

package/templates/base/.agents/hooks/agent-production-gate.sh

@@ -45,9 +45,9 @@ release_gate="A release manager runs prod deploys, commands against prod, and re
 
 # The gate reads the command line as text, joining continued lines and dropping quotes,
 # backslashes, and fd redirections, so wrappers such as bash -c, eval, or npx and split words such
-# as pr''od do not hide the common forms. A dispatch input or Railway environment the gate cannot
-# read (a variable, a command substitution, a file, or stdin) counts as prod. It is a convenience,
-# not a security boundary: the prod environment's required reviewers and Railway credentials are.
+# as pr''od do not hide the common forms. A dispatch input the gate cannot read (a variable, a
+# command substitution, a file, or stdin) counts as prod. It is a convenience, not a security
+# boundary: the prod environment's required reviewers and the deploy credentials are.
 text=${command//'\\'/}
 text=${text//$'\\\n'/}
 text=$(sed -E 's/([0-9]*[<>]&[0-9-]*|&>>?)//g' <<< "${text//[\"\'\\]/}")
@@ -56,16 +56,21 @@ prod="(prod([^[:alnum:]_-]|$)|[\$\`@])"
 dispatch="(workflow[[:space:]]+run|/dispatches)"
 environment_field="environment[]]*[=:][[:space:]]*$prod"
 unreadable_inputs="--(json|input)([[:space:]=]|$)"
+# deploy:railway
+# A Railway environment the gate cannot read counts as prod too.
 railway="(^|[^[:alnum:]_.-])(railway|@railway/cli(@[^[:space:]]*)?)([[:space:]]$simple)?"
+# deploy:end
 git_push="(^|[^[:alnum:]_.-])git([[:space:]]+(-[Cc][[:space:]]+[^[:space:]]+|--(git-dir|work-tree|namespace|config-env)[[:space:]]+[^[:space:]]+|--?[^[:space:]]+))*[[:space:]]+push([[:space:]]$simple)?"
 tag_ref="([[:space:]:+]((refs/)?tags/|v[0-9])|[[:space:]]--((follow-)?tags|mirror)([[:space:]=]|$))"
 
 if [[ $text =~ $dispatch$simple($environment_field|$unreadable_inputs) || $text =~ $environment_field$simple$dispatch ]]; then
   block "$release_gate"
 fi
+# deploy:railway
 if [[ $text =~ $railway[[:space:]](-[[:alpha:]]*e([[:space:]]+|=)?|--environment([[:space:]]+|=))$prod || $text =~ $railway[[:space:]](env|environment)([[:space:]]+[[:alpha:]]+)?[[:space:]]+$prod ]]; then
   block "$release_gate"
 fi
+# deploy:end
 if [[ $text =~ $git_push$tag_ref || $(tr '[:upper:]' '[:lower:]' <<< "$text") == *push.followtags* ]]; then
   block "$release_gate"
 fi

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/base/scripts/check-agent-gates.ts

@@ -137,7 +137,7 @@ const allowedCommands = [
   'gh api repos/next-friday/example/issues/1/comments -f body="APPROVED by QA"',
 ];
 
-const railwayProductionCommand = "railway up -e prod";
+const sampleProductionCommand = "gh workflow run deploy.yml -f environment=prod";
 
 const productionCommands = [
   "gh workflow run deploy.yml -f environment=prod -f commit_sha=abc",
@@ -158,8 +158,30 @@ const productionCommands = [
   "gh api repos/o/r/actions/workflows/1/dispatches --input body.json",
   "gh api repos/o/r/actions/workflows/1/dispatches -f inputs[environment]=$E",
   "bash -c 'gh workflow run deploy.yml -f environment=prod'",
+  sampleProductionCommand,
+  "git push origin v1.0.0",
+  "git push origin HEAD:refs/tags/v1.0.0",
+  "git push --tags",
+  "git push --follow-tags origin main",
+  "git -C . push origin v2.3.4",
+  "gh workflow run deploy.yml -f environment=pr''od",
+  "gh workflow run deploy.yml -f environment=p\\rod",
+  'gh workflow run deploy.yml -f "envi"ronment=prod',
+  "git push origin 'refs/tags/*'",
+  'git push origin "refs/tags/v*"',
+  "git push --mirror",
+  "git -c push.followTags=true push origin main",
+  "git config push.followTags true && git push",
+  "gh workflow run deploy.yml 2>&1 -f environment=prod",
+  "git push origin tags/v1.0.0",
+  "git --git-dir .git push origin v1.0.0",
+  "gh workflow run deploy.yml \\\n  -f environment=prod \\\n  -f commit_sha=abc",
+  "git push \\\n  origin v1.0.0",
+  "git push &>/dev/null origin v1.0.0",
+  "cd a\\\\\ngit push origin v1.0.0",
+  // deploy:railway
   "railway up --ci --environment prod",
-  railwayProductionCommand,
+  "railway up -e prod",
   "railway up -e=prod",
   "railway up -eprod",
   "railway up -ce prod",
@@ -181,32 +203,13 @@ const productionCommands = [
   "/usr/local/bin/railway up -e prod",
   "timeout 60 railway up -e prod",
   "eval railway up -e prod",
-  "git push origin v1.0.0",
-  "git push origin HEAD:refs/tags/v1.0.0",
-  "git push --tags",
-  "git push --follow-tags origin main",
-  "git -C . push origin v2.3.4",
   "npx @railway/cli@5.71.0 up -e prod",
   "npx @railway/cli@latest up --environment prod",
   "railway up -e pr''od",
-  "gh workflow run deploy.yml -f environment=pr''od",
-  "gh workflow run deploy.yml -f environment=p\\rod",
-  'gh workflow run deploy.yml -f "envi"ronment=prod',
-  "git push origin 'refs/tags/*'",
-  'git push origin "refs/tags/v*"',
-  "git push --mirror",
-  "git -c push.followTags=true push origin main",
-  "git config push.followTags true && git push",
-  "gh workflow run deploy.yml 2>&1 -f environment=prod",
   "railway up 2>&1 -e prod",
-  "git push origin tags/v1.0.0",
-  "git --git-dir .git push origin v1.0.0",
-  "gh workflow run deploy.yml \\\n  -f environment=prod \\\n  -f commit_sha=abc",
   "railway up \\\n  --environment prod",
-  "git push \\\n  origin v1.0.0",
   "railway up &>/dev/null -e prod",
-  "git push &>/dev/null origin v1.0.0",
-  "cd a\\\\\ngit push origin v1.0.0",
+  // deploy:end
 ];
 
 const approvalLiftsGate = ["CHG-123", "CHG-1"];
@@ -229,10 +232,6 @@ const approvalKeepsGate = [
 const nonProductionCommands = [
   "gh workflow run deploy.yml -f environment=uat -f commit_sha=abc",
   "gh api repos/o/r/actions/workflows/deploy.yml/dispatches -f 'inputs[environment]=uat'",
-  "railway up -e uat",
-  "railway up -e prod-eu",
-  "railway environment uat",
-  "railway status",
   "gh workflow list",
   "gh run list --workflow deploy.yml",
   "gh api repos/o/r/environments/prod",
@@ -241,14 +240,20 @@ const nonProductionCommands = [
   'git commit -m "release v1.0" && git push',
   'git commit -m "docs(x): deploy to production"',
   'gh pr create --title "ci(x): promote to prod" --body "run gh workflow run later"',
-  "echo railway",
   "git tag v1.0.0",
   'git stash push -m "wip v2"',
   'git commit -m "fix(ci): push v2 images"',
-  'git commit -m "fix: railway env uat and prod split"',
   "git push -u origin HEAD",
   "git push origin feature/push-v2",
   "pnpm verify 2>&1 | tail && git push",
+  // deploy:railway
+  "railway up -e uat",
+  "railway up -e prod-eu",
+  "railway environment uat",
+  "railway status",
+  "echo railway",
+  'git commit -m "fix: railway env uat and prod split"',
+  // deploy:end
 ];
 
 const mcpTools = {
@@ -461,11 +466,11 @@ const cases: GateCase[] = [
     expectedApproval: releaseApproval,
     input: {
       tool_input: {
-        command: railwayProductionCommand,
+        command: sampleProductionCommand,
       },
     },
     expectedPermission: "allow" as const,
-    name: `production with RELEASE_APPROVAL="${releaseApproval}": ${railwayProductionCommand}`,
+    name: `production with RELEASE_APPROVAL="${releaseApproval}": ${sampleProductionCommand}`,
     expectedExit: 0 as const,
   })),
   ...approvalKeepsGate.map(releaseApproval => ({
@@ -473,10 +478,10 @@ const cases: GateCase[] = [
     releaseApproval,
     input: {
       tool_input: {
-        command: railwayProductionCommand,
+        command: sampleProductionCommand,
       },
     },
-    name: `production with RELEASE_APPROVAL="${releaseApproval}": ${railwayProductionCommand}`,
+    name: `production with RELEASE_APPROVAL="${releaseApproval}": ${sampleProductionCommand}`,
     expectedExit: 2 as const,
   })),
   ...nonProductionCommands.map(command => ({
@@ -590,7 +595,7 @@ const cases: GateCase[] = [
     name: "record: the conversation of a Cursor hook input",
     expectedExit: 2,
     input: {
-      command: railwayProductionCommand,
+      command: sampleProductionCommand,
       conversation_id: "cursor-conversation",
     },
   },
@@ -617,7 +622,7 @@ const cases: GateCase[] = [
     releaseApproval: "CHG-123",
     expectedExit: 2,
     input: {
-      command: railwayProductionCommand,
+      command: sampleProductionCommand,
     },
   },
   {
@@ -636,7 +641,7 @@ const cases: GateCase[] = [
     expectedExit: 2,
     isRecordUnwritable: true,
     input: {
-      command: railwayProductionCommand,
+      command: sampleProductionCommand,
     },
   },
 ];

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/.github/workflows/ci.yml

@@ -118,7 +118,7 @@ jobs:
   image:
     name: Container Image
     needs: changes
-    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && vars.CONTAINER_IMAGE != 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
@@ -157,6 +157,7 @@ jobs:
           tar --extract --gzip --file "$archive" trivy
           ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
 
+  # deploy:railway
   deploy-dev:
     name: Deploy to dev
     needs:
@@ -171,6 +172,7 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  # deploy:end
   triage:
     name: Triage failed build
     needs:

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,25 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
+<!-- deploy:railway -->
+
 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`.
 
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+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`.
+
+<!-- deploy:end -->
+
 ```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:
@@ -58,4 +70,18 @@ docker run --env PORT=3000 --publish 3000:3000 app
 
 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/.github/workflows/ci.yml

@@ -124,7 +124,7 @@ jobs:
   image:
     name: Container Image
     needs: changes
-    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && vars.CONTAINER_IMAGE != 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
@@ -163,6 +163,7 @@ jobs:
           tar --extract --gzip --file "$archive" trivy
           ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
 
+  # deploy:railway
   deploy-dev:
     name: Deploy to dev
     needs:
@@ -177,6 +178,7 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  # deploy:end
   triage:
     name: Triage failed build
     needs:

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,8 +32,18 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
+<!-- deploy:railway -->
+
 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.
 
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+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.
+
+<!-- deploy:end -->
+
 ```sh
 docker build -t app .
 docker run --publish 3000:3000 app
@@ -41,6 +51,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:
@@ -58,4 +70,18 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
 
 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/.github/workflows/ci.yml

@@ -116,7 +116,7 @@ jobs:
   image:
     name: Container Image
     needs: changes
-    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && vars.CONTAINER_IMAGE != 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
@@ -155,6 +155,7 @@ jobs:
           tar --extract --gzip --file "$archive" trivy
           ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
 
+  # deploy:railway
   deploy-dev:
     name: Deploy to dev
     needs:
@@ -169,6 +170,7 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  # deploy:end
   triage:
     name: Triage failed build
     needs:

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,25 @@ CI also runs the build, the container image scan, and the security scans, includ
 
 ## Container
 
+<!-- deploy:railway -->
+
 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`.
 
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+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`.
+
+<!-- deploy:end -->
+
 ```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,4 +68,18 @@ docker run --env PORT=3000 --publish 3000:3000 app
 
 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/.github/workflows/ci.yml

@@ -141,7 +141,7 @@ jobs:
   image:
     name: Container Image
     needs: changes
-    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && vars.CONTAINER_IMAGE != 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 15
     services:
@@ -196,6 +196,7 @@ jobs:
           tar --extract --gzip --file "$archive" trivy
           ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
 
+  # deploy:railway
   deploy-dev:
     name: Deploy to dev
     needs:
@@ -210,6 +211,7 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  # deploy:end
   triage:
     name: Triage failed build
     needs:

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,8 +48,18 @@ CI also runs the build, the end-to-end tests, the container image scan, and the
 
 ## Container
 
+<!-- deploy:railway -->
+
 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.
 
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+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.
+
+<!-- deploy:end -->
+
 ```sh
 docker build -t app .
 docker run --publish 3000:3000 --env DATABASE_URL --env PAYLOAD_SECRET --env APP_URL app
@@ -61,6 +71,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:
@@ -84,4 +96,18 @@ On Vercel, deploy without the image; the Next.js preset takes precedence over th
 
 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/.github/workflows/ci.yml

@@ -212,7 +212,7 @@ jobs:
     needs:
       - changes
       - affected-apps
-    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && needs.affected-apps.outputs.apps != '[]'
+    if: (needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule') && needs.affected-apps.outputs.apps != '[]' && vars.CONTAINER_IMAGE != 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 20
     strategy:
@@ -272,6 +272,7 @@ jobs:
           tar --extract --gzip --file "$archive" trivy
           ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress "$APP:ci"
 
+  # deploy:railway
   deploy-dev:
     name: Deploy to dev
     needs:
@@ -286,6 +287,7 @@ jobs:
       environment: dev
       commit_sha: ${{ github.sha }}
 
+  # deploy:end
   triage:
     name: Triage failed build
     needs:

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:
@@ -86,6 +88,20 @@ On Vercel, deploy an app without its image. The Next.js preset takes precedence
 
 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
 
 To add an Expo app, create it under `apps/mobile`:
@@ -94,6 +110,16 @@ 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/)).
 
+<!-- deploy:railway -->
+
 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.
 
+<!-- deploy:end -->
+
+<!-- deploy:none -->
+
+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.
+
+<!-- deploy:end -->
+
 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",