create-apollo-suite-monorepo 1.0.1

package/index.mjs

@@ -0,0 +1,2021 @@
+#!/usr/bin/env node
+
+// create-apollo-suite-monorepo — Zero-dependency scaffolder for an Apollo CMS monorepo
+// Usage: npx create-apollo-suite-monorepo <directory> [flags]
+//
+// Produces:
+//   <directory>/
+//   ├── apps/
+//   │   ├── frontend/        ← your app (pnpm workspace member)
+//   │   └── backend/         ← git submodule → apollo-cms
+//   ├── package.json
+//   ├── pnpm-workspace.yaml
+//   ├── .env.local
+//   ├── .gitmodules
+//   └── .gitignore
+
+import { execSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { createInterface } from "node:readline";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const BACKEND_REPO_URL = "https://github.com/5Lab-Group-Co-Ltd/apollo-cms.git";
+const BACKEND_BRANCH = "main";
+const BACKEND_PATH = "apps/backend";
+const FRONTEND_PATH = "apps/frontend";
+const PROXY_PATH = "apps/proxy";
+const MIN_NODE_MAJOR = 22;
+
+// Default dev ports. Kept in sync with scripts/with-env.mjs and the proxy
+// template. .env.local is the runtime source of truth — these are the
+// installer-side fallbacks for computing initial URL defaults.
+const DEFAULT_PROXY_PORT = 3030;
+const DEFAULT_FRONTEND_PORT = 3001;
+const DEFAULT_BACKEND_PORT = 3002;
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+};
+
+const HELP_TEXT = `
+${COLORS.bold}create-apollo-suite-monorepo${COLORS.reset} — Scaffold a monorepo with Apollo CMS as a git submodule backend
+
+${COLORS.bold}Usage:${COLORS.reset}
+  npx create-apollo-suite-monorepo <directory> [flags]
+
+${COLORS.bold}Examples:${COLORS.reset}
+  npx create-apollo-suite-monorepo my-site
+  npx create-apollo-suite-monorepo my-site --frontend-name "@my-site/frontend"
+  npx create-apollo-suite-monorepo my-site --backend-branch develop --skip-install
+
+${COLORS.bold}Flags:${COLORS.reset}
+      --frontend-name <name>   Frontend package name (default: "@<dir>/frontend")
+      --backend-url <url>      Backend git URL (default: ${BACKEND_REPO_URL})
+      --backend-branch <name>  Backend branch to track (default: ${BACKEND_BRANCH})
+  -d, --db <url>               DATABASE_URL for backend
+  -u, --url <url>              NEXT_PUBLIC_SITE_URL (optional — left blank so the CMS
+                               respects the incoming request origin. Set this only when
+                               you need a fixed origin for background jobs / cron / emails.)
+  -l, --locale <code>          NEXT_PUBLIC_DEFAULT_LOCALE (default: en)
+      --admin-prefix <path>    Backend prefix in single-origin mode — sets Next.js
+                               assetPrefix on the backend AND the path the frontend
+                               rewrites to it. Defaults to /admin so backend chunks
+                               sit alongside admin pages under one rewrite.
+                               Pass "none" to disable single-origin (separate origins).
+                               Alias: --asset-prefix
+      --skip-install           Skip dependency installation
+      --skip-submodule         Skip git submodule add (you'll add it later)
+  -h, --help                   Show this help message
+
+${COLORS.bold}Single-origin model:${COLORS.reset}
+  The frontend is the public entry point. It rewrites these paths to the
+  backend so both apps live under one domain without /_next/* collisions:
+    /admin/*           → backend (admin pages + chunks via APOLLO_ASSET_PREFIX=/admin)
+    /api/*             → backend (REST API + auth)
+    /uploads/*         → backend (media)
+  Frontend MUST NOT define routes at /admin or /api/auth or /api/v1.
+`;
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function log(msg) {
+  console.log(msg);
+}
+
+function step(num, msg) {
+  log(`\n${COLORS.cyan}[${num}]${COLORS.reset} ${msg}`);
+}
+
+function success(msg) {
+  log(`    ${COLORS.green}✓${COLORS.reset} ${msg}`);
+}
+
+function warn(msg) {
+  log(`    ${COLORS.yellow}⚠${COLORS.reset} ${msg}`);
+}
+
+function fatal(msg) {
+  console.error(`\n${COLORS.red}Error:${COLORS.reset} ${msg}\n`);
+  process.exit(1);
+}
+
+function run(cmd, opts = {}) {
+  return execSync(cmd, { stdio: "inherit", ...opts });
+}
+
+function runSilent(cmd, opts = {}) {
+  try {
+    return execSync(cmd, { stdio: "pipe", ...opts }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  return runSilent(process.platform === "win32" ? `where ${cmd}` : `which ${cmd}`) !== null;
+}
+
+// ─── Arg Parsing ─────────────────────────────────────────────────────────────
+
+// Flag dispatch table. Each entry: aliases → either { key } (takes a value)
+// or { key, value } (boolean flag). `--asset-prefix` is a legacy alias.
+const FLAG_TABLE = {
+  "-h": { key: "help", value: true },
+  "--help": { key: "help", value: true },
+  "--skip-install": { key: "skipInstall", value: true },
+  "--skip-submodule": { key: "skipSubmodule", value: true },
+  "--frontend-name": { key: "frontendName" },
+  "--backend-url": { key: "backendUrl" },
+  "--backend-branch": { key: "backendBranch" },
+  "-d": { key: "db" },
+  "--db": { key: "db" },
+  "-u": { key: "url" },
+  "--url": { key: "url" },
+  "-l": { key: "locale" },
+  "--locale": { key: "locale" },
+  "--admin-prefix": { key: "adminPrefix" },
+  "--asset-prefix": { key: "adminPrefix" },
+};
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    directory: null,
+    frontendName: null,
+    backendUrl: BACKEND_REPO_URL,
+    backendBranch: BACKEND_BRANCH,
+    db: null,
+    url: null,
+    locale: null,
+    adminPrefix: "/admin",
+    skipInstall: false,
+    skipSubmodule: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const spec = FLAG_TABLE[arg];
+    if (spec) {
+      flags[spec.key] = "value" in spec ? spec.value : args[++i];
+      continue;
+    }
+    if (arg.startsWith("-")) fatal(`Unknown flag: ${arg}\nRun with --help for usage.`);
+    if (flags.directory) fatal(`Unexpected argument: ${arg}\nOnly one directory name is allowed.`);
+    flags.directory = arg;
+  }
+
+  return flags;
+}
+
+// ─── Validation ──────────────────────────────────────────────────────────────
+
+function isValidDbUrl(url) {
+  return /^postgres(ql)?:\/\/.+/.test(url);
+}
+
+function isValidUrl(url) {
+  return /^https?:\/\/.+/.test(url);
+}
+
+function isValidLocale(code) {
+  return /^[a-z]{2,5}$/i.test(code);
+}
+
+// Normalize the admin/asset prefix:
+//  - empty string / "none" / "off" / "false"  → "" (single-origin disabled, fallback to separate origins)
+//  - "/foo"                                    → "/foo"
+//  - "foo"                                     → "/foo"
+//  - "/foo/"                                   → "/foo"
+//
+// The same value drives both Next.js `adminPrefix` on the backend AND the
+// path the frontend rewrites at. Defaulting to "/admin" makes backend chunks
+// sit under the admin path so a single `/admin/:path*` rewrite covers
+// everything (admin pages + their JS chunks).
+function normalizeAdminPrefix(value) {
+  if (!value) return "";
+  const trimmed = String(value).trim();
+  if (trimmed === "" || /^(none|off|false|disabled)$/i.test(trimmed)) return "";
+  let p = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+$/, "");
+  if (!/^\/[a-z0-9._-]+(\/[a-z0-9._-]+)*$/i.test(p)) {
+    fatal(`Invalid --admin-prefix: ${value}\n  Use a path like /admin, or "none" to disable single-origin.`);
+  }
+  return p;
+}
+
+// ─── Pre-flight ──────────────────────────────────────────────────────────────
+
+function preflight(flags) {
+  step(1, "Pre-flight checks");
+
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  if (nodeMajor < MIN_NODE_MAJOR) {
+    fatal(
+      `Node.js ${MIN_NODE_MAJOR}+ is required (found ${process.versions.node}).\n  Install: https://nodejs.org/`,
+    );
+  }
+  success(`Node.js ${process.versions.node}`);
+
+  // bun is required at runtime by apps/backend (apollo-cms): db:push, db:seed,
+  // plugins:build, the upgrade pipeline, and pre-commit hooks all
+  // shell out to `bun`. The scaffold itself works without bun, but `pnpm dev`,
+  // `pnpm backend:setup`, and `pnpm backend:upgrade` will fail without it.
+  const TOOLS = [
+    { cmd: "git",  required: true,  missing: "git is required but not found.\n  Install: https://git-scm.com/" },
+    { cmd: "pnpm", required: false, missing: "pnpm not found — install with: npm i -g pnpm  (required for workspaces)" },
+    { cmd: "bun",  required: false, missing:
+        "bun not found — required by apps/backend for db:push, db:seed,\n" +
+        "       plugins:build, and the upgrade pipeline.\n" +
+        "       Install: curl -fsSL https://bun.sh/install | bash  (or: brew install bun)" },
+  ];
+  for (const t of TOOLS) {
+    if (commandExists(t.cmd)) success(`${t.cmd} found`);
+    else if (t.required) fatal(t.missing);
+    else warn(t.missing);
+  }
+
+  const targetDir = resolve(flags.directory);
+  if (existsSync(targetDir)) {
+    fatal(`Directory already exists: ${targetDir}\n  Choose a different name or remove it first.`);
+  }
+  success(`Target: ${targetDir}`);
+
+  return targetDir;
+}
+
+// ─── Prompts ─────────────────────────────────────────────────────────────────
+
+function createPrompt() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((res) => rl.question(q, (a) => res(a.trim())));
+  const close = () => rl.close();
+  return { ask, close };
+}
+
+async function gatherEnv(flags) {
+  let dbUrl = flags.db;
+  // NEXT_PUBLIC_SITE_URL is intentionally NOT prompted. Apollo CMS resolves
+  // the public origin in this priority order: NEXT_PUBLIC_SITE_URL >
+  // incoming request origin. Leaving it blank lets the runtime respect the
+  // actual request origin (works for localhost, preview URLs, prod domains,
+  // and reverse proxies without any reconfiguration). Override with --url
+  // only when you need a fixed origin for background jobs (cron / triggered
+  // emails) that run outside a request scope.
+  let siteUrl = flags.url ?? "";
+  let locale = flags.locale ?? "en";
+
+  if (flags.db && !isValidDbUrl(flags.db)) fatal("--db must start with postgresql:// or postgres://");
+  if (flags.url && !isValidUrl(flags.url)) fatal("--url must start with http:// or https://");
+  if (flags.locale && !isValidLocale(flags.locale)) fatal("--locale must be a 2-5 character code (e.g., en, th)");
+
+  const needsPrompt = !dbUrl || !flags.locale;
+  if (!needsPrompt) return { dbUrl, siteUrl, locale };
+
+  const { ask, close } = createPrompt();
+
+  if (!dbUrl) {
+    log("");
+    while (!dbUrl) {
+      const ans = await ask(
+        `    ${COLORS.bold}DATABASE_URL${COLORS.reset} ${COLORS.dim}(postgresql://user:pass@host:5432/dbname)${COLORS.reset}\n    > `,
+      );
+      if (isValidDbUrl(ans)) dbUrl = ans;
+      else warn("Must start with postgresql:// or postgres://");
+    }
+  }
+
+  if (!flags.locale) {
+    const ans = await ask(
+      `\n    ${COLORS.bold}Default locale${COLORS.reset} ${COLORS.dim}[${locale}]${COLORS.reset}\n    > `,
+    );
+    if (ans) {
+      if (isValidLocale(ans)) locale = ans;
+      else warn(`Invalid locale code, using default: ${locale}`);
+    }
+  }
+
+  close();
+  return { dbUrl, siteUrl, locale };
+}
+
+// ─── Scaffolding ─────────────────────────────────────────────────────────────
+
+function writeRootPackageJson(targetDir, dirName) {
+  const pkg = {
+    name: dirName,
+    version: "0.0.0",
+    private: true,
+    description: `${dirName} monorepo (frontend + apollo-cms backend submodule)`,
+    scripts: {
+      // We bypass apollo-cms's own `dev` script ("bun install && bun run
+      // plugins:build && next dev") because the bash-`&`-then-foreground
+      // pattern exits with SIGHUP (129) under pnpm's parallel runner. Instead
+      // we explicitly run plugins:build (both ours and apollo-cms's) and
+      // `next dev` directly. Nothing extra to start for scheduled jobs — the
+      // backend drives its scheduler queue in-process (dev and production).
+      "predev:setup":
+        "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build",
+      // `pnpm dev` runs FE + BE Next.js dev servers (which watch their own
+      // src/) plus a parallel cms-plugins watcher, so editing
+      // apps/cms-plugins/<slug>/index.ts triggers an esbuild incremental
+      // rebuild and the backend's plugin loader picks up the fresh
+      // dist/server.mjs on next request.
+      dev:
+        "pnpm predev:setup && concurrently -k -n FE,BE,PL -c blue,magenta,yellow \"pnpm dev:frontend\" \"pnpm dev:backend\" \"pnpm cms-plugins:dev\"",
+      // Optional single-origin dev: same as `pnpm dev` but adds a Node.js
+      // reverse proxy on :3030 (PROXY_PORT) that fronts FE :3001 (FRONTEND_PORT)
+      // + BE :3002 (BACKEND_PORT). Ports come from .env.local; override there.
+      "dev:rp":
+        "pnpm predev:setup && concurrently -k -n FE,BE,PL,PX -c blue,magenta,yellow,cyan \"pnpm dev:frontend\" \"pnpm dev:backend\" \"pnpm cms-plugins:dev\" \"pnpm dev:proxy\"",
+      "dev:proxy": "node scripts/with-env.mjs node apps/proxy/server.mjs",
+      "dev:frontend":
+        "node scripts/with-env.mjs --port=FRONTEND_PORT pnpm --filter ./apps/frontend exec next dev",
+      "dev:backend":
+        "pnpm predev:setup && node scripts/with-env.mjs --port=BACKEND_PORT pnpm --filter ./apps/backend exec next dev",
+      // Build pipeline: cms-plugins → apollo-cms's own plugins → backend → frontend.
+      // `prebuild` runs first (npm/pnpm convention) and fails fast if the
+      // backend's required env vars are missing.
+      prebuild: "node scripts/check-env.mjs",
+      build:
+        "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build && pnpm --filter ./apps/backend build && pnpm --filter ./apps/frontend build",
+      "build:backend":
+        "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build && pnpm --filter ./apps/backend build",
+      "build:frontend": "pnpm --filter ./apps/frontend build",
+      // Production start. Runs FE :FRONTEND_PORT + BE :BACKEND_PORT (defaults
+      // 3001 + 3002 from .env.local). Run \`pnpm backend:upgrade\` BEFORE this —
+      // start does NOT run migrations on boot (zero-downtime restart safety).
+      start:
+        "concurrently -k -n FE,BE -c blue,magenta \"pnpm start:frontend\" \"pnpm start:backend\"",
+      // Single-origin production: FE + BE + Node reverse proxy on :PROXY_PORT.
+      "start:rp":
+        "concurrently -k -n FE,BE,PX -c blue,magenta,cyan \"pnpm start:frontend\" \"pnpm start:backend\" \"pnpm start:proxy\"",
+      "start:proxy": "NODE_ENV=production node scripts/with-env.mjs node apps/proxy/server.mjs",
+      "start:frontend":
+        "node scripts/with-env.mjs --port=FRONTEND_PORT pnpm --filter ./apps/frontend exec next start",
+      "start:backend":
+        "node scripts/with-env.mjs --port=BACKEND_PORT pnpm --filter ./apps/backend exec next start",
+      "cms-plugins:build":
+        "pnpm --filter './apps/cms-plugins/*' --parallel --if-present build",
+      "cms-plugins:dev":
+        "pnpm --filter './apps/cms-plugins/*' --parallel --if-present dev",
+      "cms-plugin:new": "node scripts/new-cms-plugin.mjs",
+      lint: "pnpm -r lint",
+      typecheck: "pnpm -r typecheck",
+      // Stash any local changes inside the submodule so the fast-forward
+      // merge can't conflict, then update, then run `pnpm install` at the
+      // root so workspace deps pick up any package.json changes pulled in
+      // from the new apollo-cms commit. The stash is restored if it was
+      // created; otherwise this is a no-op.
+      "backend:update":
+        "node -e \"const {execSync:e}=require('child_process');const r=s=>e(s,{stdio:'inherit'});const has=e('git -C apps/backend status --porcelain',{encoding:'utf8'}).trim().length>0;if(has)r('git -C apps/backend stash push -u -m backend-update-auto');r('git submodule update --remote --merge apps/backend');r('pnpm install');if(has){try{r('git -C apps/backend stash pop');}catch(_){console.error('[backend:update] stash pop had conflicts — resolve manually with: git -C apps/backend stash list');}}\"",
+      // `pnpm setup` is pnpm's CLI bootstrap built-in — must use `run` to
+      // forward to the workspace's setup script (apollo-cms's db:push + db:seed).
+      "backend:setup": "pnpm --filter ./apps/backend run setup",
+      // Full apollo-cms upgrade pipeline: drizzle push + replay
+      // src/upgrades/0.1.*.ts data migrations + seed. Run this after
+      // `pnpm backend:update` so any data-migration step from the new
+      // apollo-cms version is applied — `backend:setup` alone skips it.
+      "backend:upgrade": "pnpm --filter ./apps/backend exec bun run upgrade",
+    },
+    devDependencies: {
+      concurrently: "^9.0.0",
+      // Optional peer of `next` (and `@better-auth/core`). Nothing imports it
+      // eagerly at runtime, but `bun build` resolves every `require()` it can
+      // see — including the guarded one in next/dist/server/lib/trace/tracer.js
+      // — so an uninstalled optional peer fails the plugin bundle with
+      // `error: Could not resolve: "@opentelemetry/api"`. bun install pulls
+      // optional peers in automatically, which is why apollo-cms standalone
+      // never hits this; pnpm skips them, so the monorepo must ask for it.
+      "@opentelemetry/api": "^1.9.0",
+    },
+    // Pin to pnpm 11 because `pnpm-workspace.yaml` uses the `allowBuilds`
+    // map format introduced in v11 (deprecated `onlyBuiltDependencies` is
+    // silently ignored on v11 — sharp/esbuild postinstalls then no-op and
+    // /admin/media crashes at runtime with "Cannot find module sharp-…").
+    // Corepack uses this field to auto-fetch the right pnpm.
+    packageManager: "pnpm@11.0.0",
+    engines: { node: ">=22", pnpm: ">=11" },
+  };
+  writeFileSync(resolve(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  // .npmrc — keep peer-deps lenient and hoist esbuild's platform binaries so
+  // its postinstall version check resolves the correct one across nested
+  // dependency trees.
+  writeFileSync(
+    resolve(targetDir, ".npmrc"),
+    [
+      "auto-install-peers=true",
+      "strict-peer-dependencies=false",
+      "public-hoist-pattern[]=*esbuild*",
+      "public-hoist-pattern[]=*types*",
+      "shell-emulator=true",
+      "",
+    ].join("\n"),
+  );
+}
+
+// Link an app's .env.local to the monorepo root .env.local so the root file
+// stays the single source of truth. Next.js only reads .env.local from its
+// own CWD, so this symlink lets `cd apps/<app> && next dev|build` see the
+// shared config. Falls back to a regular copy (with a warning) on platforms
+// where symlink creation requires elevation (Windows non-admin).
+function linkRootEnvLocal(targetDir, appRelPath, fallbackLines) {
+  const envPath = resolve(targetDir, appRelPath, ".env.local");
+  // appRelPath is `apps/<name>` (2 segments deep) → `../../.env.local`.
+  const depth = appRelPath.split("/").filter(Boolean).length;
+  const linkTarget = "../".repeat(depth) + ".env.local";
+  if (existsSync(envPath)) rmSync(envPath);
+  try {
+    symlinkSync(linkTarget, envPath);
+    success(`${appRelPath}/.env.local → ${linkTarget} (symlink)`);
+  } catch {
+    writeFileSync(envPath, [...fallbackLines, ""].join("\n"));
+    warn(
+      `symlink failed — wrote a copy at ${appRelPath}/.env.local (keep it in sync with the root file manually).`,
+    );
+  }
+}
+
+function writePnpmWorkspace(targetDir) {
+  // pnpm 11 replaced `onlyBuiltDependencies` (list) with `allowBuilds`
+  // (map of package -> bool). apollo-cms transitively pulls multiple
+  // esbuild versions (0.18, 0.25, 0.27); pnpm's binary symlink can pick
+  // the wrong platform binary for esbuild's postinstall version check,
+  // failing with "Expected X.Y.Z but got A.B.C". Allow listed packages
+  // to run their build/postinstall scripts; the rest are skipped
+  // (pnpm 11 default is `strictDepBuilds: true`, empty allow-map).
+  // See https://pnpm.io/blog/releases/11.0.
+  const yaml = [
+    "packages:",
+    "  - 'apps/*'",
+    "  - 'apps/cms-plugins/*'",
+    // apollo-cms declares `plugins/*` in its own pnpm-workspace.yaml, but a
+    // nested workspace file is ignored once the submodule is itself a package
+    // of an outer workspace. Without this glob pnpm never installs the
+    // built-in plugins' dependencies, and `plugins:build` dies with
+    // `error: Could not resolve: "ioredis"` (apollo-api-cache) before the
+    // backend can start.
+    "  - 'apps/backend/plugins/*'",
+    "",
+    "allowBuilds:",
+    "  '@parcel/watcher': true",
+    "  '@rolldown/binding-darwin-arm64': true",
+    "  '@rolldown/binding-linux-arm64-gnu': true",
+    "  '@rolldown/binding-linux-x64-gnu': true",
+    "  '@swc/core': true",
+    "  '@swc/core-darwin-arm64': true",
+    "  '@swc/core-darwin-x64': true",
+    "  '@swc/core-linux-arm64-gnu': true",
+    "  '@swc/core-linux-x64-gnu': true",
+    "  'better-sqlite3': true",
+    "  'core-js': true",
+    "  'core-js-pure': true",
+    "  'esbuild': true",
+    "  'msw': true",
+    "  'sharp': true",
+    "  'unrs-resolver': true",
+    "",
+  ].join("\n");
+  writeFileSync(resolve(targetDir, "pnpm-workspace.yaml"), yaml);
+}
+
+// Single-origin nginx reference. Only emitted when adminPrefix is set, since
+// in separate-origins mode the two apps live on their own domains/ports and
+// don't need the prefix-aware location ordering.
+function writeNginxSample(targetDir, adminPrefix) {
+  const prefix = adminPrefix || "/admin";
+  const conf = `# Apollo CMS — single-origin nginx sample.
+# Mirrors apps/frontend/next.config.ts rewrites (frontend :3001 / backend :3000).
+# No caching headers — Next.js sets its own. Add SSL + HTTP→HTTPS in production.
+
+upstream apollo_frontend { server 127.0.0.1:3001; }
+upstream apollo_backend  { server 127.0.0.1:3000; }
+
+server {
+    listen      80;
+    server_name _;
+
+    client_max_body_size 50m;
+
+    proxy_http_version 1.1;
+    proxy_set_header   Host              $host;
+    proxy_set_header   X-Real-IP         $remote_addr;
+    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+    proxy_set_header   X-Forwarded-Proto $scheme;
+    proxy_set_header   X-Forwarded-Host  $host;
+
+    # Backend — admin UI + chunks (APOLLO_ASSET_PREFIX=${prefix}), media
+    location =  ${prefix}    { proxy_pass http://apollo_backend; }
+    location ^~ ${prefix}/   { proxy_pass http://apollo_backend; }
+    location ^~ /uploads/    { proxy_pass http://apollo_backend; }
+
+    # Backend SSE — long-lived, no buffering
+    location ^~ /api/editing-presence/ {
+        proxy_pass         http://apollo_backend;
+        proxy_buffering    off;
+        proxy_read_timeout 24h;
+    }
+
+    # Backend APIs (mirror the list in apps/frontend/next.config.ts).
+    # \`editing-presence\` is included so the bare path also routes to backend;
+    # streaming sub-paths still match the \`^~\` block above first.
+    location ~ ^/api/(auth|v1|email|health|mcp|admin|editing-presence)(/|$) {
+        proxy_pass http://apollo_backend;
+    }
+
+    # Frontend — everything else
+    location / { proxy_pass http://apollo_frontend; }
+}
+`;
+  writeFileSync(resolve(targetDir, "nginx.conf.sample"), conf);
+}
+
+// Optional Node.js reverse proxy. Mirrors nginx.conf.sample routing rules
+// but runs in-process — opt in via `pnpm dev:rp`. Zero deps, ~80 LOC.
+function writeProxyApp(targetDir, dirName, adminPrefix) {
+  const dir = resolve(targetDir, PROXY_PATH);
+  mkdirSync(dir, { recursive: true });
+
+  const prefix = adminPrefix || "/admin";
+  const server = `// ${dirName} — single-origin reverse proxy (zero deps).
+// Mirrors ../../nginx.conf.sample. Run via \`pnpm dev:rp\` from the repo root.
+//
+// Routes (in order):
+//   ${prefix}, ${prefix}/*, /uploads/*                       → backend
+//   /api/editing-presence/*                                  → backend (SSE)
+//   /api/{auth,v1,email,health,mcp,admin,...}/*              → backend
+//   /__proxy/health                                          → 200 OK (proxy itself)
+//   everything else                                          → frontend
+//
+// Production note: this proxy doesn't terminate TLS. For HTTPS, sit behind a
+// load balancer (Caddy, Cloudflare, ALB) or use \`nginx.conf.sample\` instead.
+
+import http from "node:http";
+import net from "node:net";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Load root .env.local so the proxy honors PROXY_PORT/FRONTEND_PORT/BACKEND_PORT
+// alongside the frontend & backend. Process env still wins (12-factor friendly).
+(function loadRootEnv() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const envPath = resolve(here, "../../.env.local");
+    if (!existsSync(envPath)) return;
+    for (const raw of readFileSync(envPath, "utf8").split(/\\r?\\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq < 0) continue;
+      const key = line.slice(0, eq).trim();
+      if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) continue;
+      if (process.env[key] !== undefined) continue;
+      let val = line.slice(eq + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      process.env[key] = val;
+    }
+  } catch {
+    // Best-effort. The proxy still runs on its hardcoded fallbacks.
+  }
+})();
+
+// Backward-compatible: PROXY_PORT/FRONTEND_PORT/BACKEND_PORT are the new names;
+// PORT/FRONTEND/BACKEND are still honored if explicitly set in process.env.
+const PORT = Number(process.env.PROXY_PORT ?? process.env.PORT ?? 3030);
+const BACKEND_HOST = process.env.BACKEND ?? \`http://127.0.0.1:\${process.env.BACKEND_PORT ?? 3002}\`;
+const FRONTEND_HOST = process.env.FRONTEND ?? \`http://127.0.0.1:\${process.env.FRONTEND_PORT ?? 3001}\`;
+const BACKEND = parseTarget(BACKEND_HOST);
+const FRONTEND = parseTarget(FRONTEND_HOST);
+
+const ADMIN_PREFIX = process.env.ADMIN_PREFIX ?? "${prefix}";
+// Pipe-separated list of /api/<segment> paths that route to the backend.
+const BACKEND_API_SEGMENTS = (
+  process.env.BACKEND_API_PATHS ??
+  "auth|v1|email|health|mcp|admin|editing-presence"
+).trim();
+const BACKEND_API = new RegExp(\`^/api/(\${BACKEND_API_SEGMENTS})(/|$)\`);
+
+// 50MB matches nginx.conf.sample's client_max_body_size and Next.js's
+// Server Actions body limit. Override via MAX_BODY_BYTES (0 = unlimited).
+const MAX_BODY_BYTES = Number(process.env.MAX_BODY_BYTES ?? 50 * 1024 * 1024);
+const UPSTREAM_TIMEOUT_MS = Number(process.env.UPSTREAM_TIMEOUT_MS ?? 60_000);
+// When false (default), strip incoming X-Forwarded-* before adding our own —
+// prevents header spoofing when the proxy faces the public internet directly.
+// Set TRUST_PROXY=1 only when behind another trusted reverse proxy (CDN, LB).
+const TRUST_PROXY = process.env.TRUST_PROXY === "1";
+
+// Hop-by-hop headers (RFC 7230 §6.1) — must not be forwarded.
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+// Reuse TCP connections to upstreams — eliminates ~1ms per request.
+const backendAgent = new http.Agent({ keepAlive: true });
+const frontendAgent = new http.Agent({ keepAlive: true });
+
+function pickUpstream(url) {
+  if (url === ADMIN_PREFIX || url.startsWith(\`\${ADMIN_PREFIX}/\`))
+    return { ...BACKEND, agent: backendAgent };
+  if (url.startsWith("/uploads/")) return { ...BACKEND, agent: backendAgent };
+  if (BACKEND_API.test(url)) return { ...BACKEND, agent: backendAgent };
+  return { ...FRONTEND, agent: frontendAgent };
+}
+
+function sanitizeHeaders(req, clientIp) {
+  const out = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    const lower = k.toLowerCase();
+    if (HOP_BY_HOP.has(lower)) continue;
+    // Strip client-supplied X-Forwarded-* unless TRUST_PROXY is set.
+    if (!TRUST_PROXY && lower.startsWith("x-forwarded-")) continue;
+    out[k] = v;
+  }
+  // Always set X-Forwarded-* with our own values (append client IP).
+  const existingFor = TRUST_PROXY ? req.headers["x-forwarded-for"] : undefined;
+  out["x-forwarded-for"] = existingFor ? \`\${existingFor}, \${clientIp}\` : clientIp;
+  out["x-forwarded-proto"] = TRUST_PROXY
+    ? req.headers["x-forwarded-proto"] ?? "http"
+    : "http";
+  out["x-forwarded-host"] = TRUST_PROXY
+    ? req.headers["x-forwarded-host"] ?? req.headers.host ?? ""
+    : req.headers.host ?? "";
+  return out;
+}
+
+function logError(scope, err, extra) {
+  const ts = new Date().toISOString();
+  const detail = extra ? \` \${JSON.stringify(extra)}\` : "";
+  console.error(\`[\${ts}] proxy:\${scope} \${err.code ?? ""} \${err.message}\${detail}\`);
+}
+
+const server = http.createServer((req, res) => {
+  // Health check (proxy itself, never forwarded).
+  if (req.url === "/__proxy/health") {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ status: "ok", uptime: process.uptime() }));
+    return;
+  }
+
+  // Enforce body size limit (DoS protection).
+  if (MAX_BODY_BYTES > 0) {
+    const declared = Number(req.headers["content-length"] ?? 0);
+    if (declared > MAX_BODY_BYTES) {
+      res.writeHead(413, { "content-type": "text/plain" });
+      res.end("Payload Too Large");
+      return;
+    }
+    let received = 0;
+    req.on("data", (chunk) => {
+      received += chunk.length;
+      if (received > MAX_BODY_BYTES) {
+        req.destroy(new Error("Body exceeded MAX_BODY_BYTES"));
+      }
+    });
+  }
+
+  const upstream = pickUpstream(req.url);
+  const proxyReq = http.request(
+    {
+      host: upstream.host,
+      port: upstream.port,
+      method: req.method,
+      path: req.url,
+      headers: sanitizeHeaders(req, req.socket.remoteAddress ?? ""),
+      agent: upstream.agent,
+      timeout: UPSTREAM_TIMEOUT_MS,
+    },
+    (proxyRes) => {
+      // Strip hop-by-hop headers from upstream response too.
+      const safe = {};
+      for (const [k, v] of Object.entries(proxyRes.headers)) {
+        if (!HOP_BY_HOP.has(k.toLowerCase())) safe[k] = v;
+      }
+      res.writeHead(proxyRes.statusCode ?? 502, safe);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on("timeout", () => {
+    logError("upstream-timeout", new Error("upstream timeout"), { url: req.url });
+    proxyReq.destroy(new Error("Upstream timeout"));
+  });
+  proxyReq.on("error", (err) => {
+    logError("upstream", err, { url: req.url });
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain" });
+      res.end("Bad Gateway");
+    }
+    if (!req.destroyed) req.destroy();
+  });
+  req.on("error", (err) => {
+    logError("client", err, { url: req.url });
+    if (!proxyReq.destroyed) proxyReq.destroy();
+  });
+  req.pipe(proxyReq);
+});
+
+// WebSocket / HTTP upgrade passthrough — required for Next.js HMR.
+server.on("upgrade", (req, clientSocket, head) => {
+  const upstream = pickUpstream(req.url);
+  const upstreamSocket = net.connect(upstream.port, upstream.host, () => {
+    const headers = sanitizeHeaders(req, req.socket.remoteAddress ?? "");
+    // Re-add Connection: Upgrade & Upgrade headers stripped by sanitizeHeaders.
+    headers["connection"] = "Upgrade";
+    if (req.headers.upgrade) headers["upgrade"] = req.headers.upgrade;
+    const headerLines = [];
+    for (const [k, v] of Object.entries(headers)) {
+      const values = Array.isArray(v) ? v : [v];
+      for (const single of values) {
+        const str = String(single);
+        // Defense-in-depth: reject CRLF in header values (header injection).
+        if (/[\\r\\n]/.test(str)) continue;
+        headerLines.push(\`\${k}: \${str}\`);
+      }
+    }
+    upstreamSocket.write(
+      \`\${req.method} \${req.url} HTTP/\${req.httpVersion}\\r\\n\` +
+        headerLines.join("\\r\\n") +
+        "\\r\\n\\r\\n",
+    );
+    if (head?.length) upstreamSocket.write(head);
+    upstreamSocket.pipe(clientSocket);
+    clientSocket.pipe(upstreamSocket);
+  });
+  upstreamSocket.on("error", (err) => {
+    logError("ws-upstream", err, { url: req.url });
+    clientSocket.destroy();
+  });
+  clientSocket.on("error", (err) => {
+    logError("ws-client", err, { url: req.url });
+    upstreamSocket.destroy();
+  });
+});
+
+server.listen(PORT, () => {
+  console.log(\`apollo-proxy → http://localhost:\${PORT}\`);
+  console.log(\`  \${ADMIN_PREFIX}/*, /uploads/*, /api/*  → \${BACKEND.host}:\${BACKEND.port}\`);
+  console.log(\`  /*  → \${FRONTEND.host}:\${FRONTEND.port}\`);
+  console.log(\`  TRUST_PROXY=\${TRUST_PROXY}  MAX_BODY_BYTES=\${MAX_BODY_BYTES}  UPSTREAM_TIMEOUT_MS=\${UPSTREAM_TIMEOUT_MS}\`);
+});
+
+// Graceful shutdown — let in-flight requests finish, then exit.
+let shuttingDown = false;
+function shutdown(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(\`\\napollo-proxy: \${signal} received, draining...\`);
+  server.close(() => {
+    backendAgent.destroy();
+    frontendAgent.destroy();
+    process.exit(0);
+  });
+  // Hard exit after 10s if connections refuse to drain.
+  setTimeout(() => process.exit(1), 10_000).unref();
+}
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+
+function parseTarget(input) {
+  const url = new URL(input.startsWith(":") ? \`http://127.0.0.1\${input}\` : input);
+  return { host: url.hostname, port: Number(url.port || 80) };
+}
+`;
+  writeFileSync(resolve(dir, "server.mjs"), server);
+
+  const pkg = {
+    name: `@${dirName}/proxy`,
+    private: true,
+    version: "0.0.0",
+    description: "Optional Node.js reverse proxy fronting frontend + backend on a single origin",
+    type: "module",
+    main: "server.mjs",
+    scripts: {
+      start: "node server.mjs",
+    },
+    engines: { node: ">=22" },
+  };
+  writeFileSync(resolve(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  const readme = `# @${dirName}/proxy
+
+Optional single-origin reverse proxy. Routes \`${prefix}/*\`, \`/api/*\`, and
+\`/uploads/*\` to the backend; everything else to the frontend. Zero deps.
+
+## When to use
+
+- You want **one URL** for FE + BE locally (shared cookies, no CORS).
+- You don't want to install nginx for local dev.
+
+## Usage
+
+From the repo root:
+
+\`\`\`bash
+pnpm dev:rp        # runs FE :3001 + BE :3000 + plugins watcher + proxy :3030
+\`\`\`
+
+Then open http://localhost:3030.
+
+For best results, set \`NEXT_PUBLIC_SITE_URL=http://localhost:3030\` in your
+\`.env.local\` so Better Auth, OAuth callbacks, and email links all use the
+single-origin URL.
+
+## Configuration
+
+| Env var               | Default                          | Notes                                                          |
+| --------------------- | -------------------------------- | -------------------------------------------------------------- |
+| \`PORT\`                | \`3030\`                            | Public port                                                    |
+| \`BACKEND\`             | \`http://127.0.0.1:3000\`           | apps/backend dev server                                        |
+| \`FRONTEND\`            | \`http://127.0.0.1:3001\`           | apps/frontend dev server                                       |
+| \`ADMIN_PREFIX\`        | \`${prefix}\`                          | Backend admin path prefix                                      |
+| \`BACKEND_API_PATHS\`   | \`auth\\|v1\\|email\\|health\\|mcp\\|admin\\|editing-presence\` | Pipe-separated /api/* segments routed to backend |
+| \`MAX_BODY_BYTES\`      | \`52428800\` (50MB)                 | Reject larger bodies. \`0\` = unlimited                          |
+| \`UPSTREAM_TIMEOUT_MS\` | \`60000\`                           | Request timeout to upstream                                    |
+| \`TRUST_PROXY\`         | \`1\`                               | Honors inbound X-Forwarded-* from upstream TLS terminator (nginx/Caddy/CF/LB). Set \`0\` if proxy is directly internet-facing |
+
+## Health check
+
+\`GET /__proxy/health\` returns \`{"status":"ok","uptime":<seconds>}\`. Use it for
+liveness probes; the path is reserved by the proxy and never forwarded.
+
+## Better Auth interaction
+
+Apollo CMS's Better Auth derives the request origin from \`x-forwarded-host\` /
+\`x-forwarded-proto\`. This proxy sets both correctly, so \`trustedOrigins\` keeps
+working through the proxy. The recent fix in \`src/lib/auth/server.ts\` ensures
+the actual request origin (e.g. \`localhost:3030\`) is added to trusted origins
+even when \`NEXT_PUBLIC_SITE_URL\` points elsewhere.
+
+## Production
+
+This proxy doesn't terminate TLS. For HTTPS, either:
+
+- Sit it behind a TLS-terminating load balancer (Caddy, Cloudflare, ALB), **or**
+- Use \`nginx.conf.sample\` at the repo root instead — nginx handles TLS, gzip,
+  and large-scale traffic better.
+
+The Node proxy is intended for dev and small self-hosted deploys.
+`;
+  writeFileSync(resolve(dir, "README.md"), readme);
+}
+
+function writeRootGitignore(targetDir) {
+  // NOTE: .env.local is intentionally NOT ignored — it holds shared dev port
+  // defaults (PROXY_PORT/FRONTEND_PORT/BACKEND_PORT) and other non-secret
+  // workspace knobs that should travel with the repo. Keep real secrets in
+  // .env (ignored) or apps/backend/.env.local (ignored by the submodule).
+  const ignore = [
+    "node_modules",
+    ".pnpm-store",
+    ".turbo",
+    ".next",
+    "dist",
+    "build",
+    ".env",
+    "*.log",
+    ".DS_Store",
+    "",
+  ].join("\n");
+  writeFileSync(resolve(targetDir, ".gitignore"), ignore);
+}
+
+function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl, pm2Namespace }) {
+  const header = adminPrefix
+    ? [
+        "# Single-origin monorepo dev env",
+        `# Public origin = frontend (apps/frontend on :${DEFAULT_FRONTEND_PORT}). Frontend rewrites /admin/*,`,
+        `# /api/*, /uploads/*, and the asset prefix to the backend (apps/backend on :${DEFAULT_BACKEND_PORT}).`,
+      ]
+    : [
+        "# Separate-origins monorepo dev env",
+        `# Backend runs at http://localhost:${DEFAULT_BACKEND_PORT}, frontend at http://localhost:${DEFAULT_FRONTEND_PORT}.`,
+        "# To switch to single-origin: set APOLLO_ASSET_PREFIX (default: /admin) and",
+        "# BACKEND_INTERNAL_URL, then add rewrites() to apps/frontend/next.config.ts.",
+      ];
+
+  const lines = [
+    ...header,
+    "",
+    "# ── Dev server ports ─────────────────────────────────────────────",
+    "# Single source of truth for local ports. Consumed by:",
+    "#   • apps/proxy/server.mjs  (PROXY_PORT, FRONTEND_PORT, BACKEND_PORT)",
+    "#   • scripts/with-env.mjs   (maps FRONTEND_PORT/BACKEND_PORT → PORT",
+    "#                             when launching apps/frontend & apps/backend,",
+    "#                             and derives NEXT_PUBLIC_SITE_URL /",
+    "#                             BACKEND_INTERNAL_URL when those are unset)",
+    "# Override any of these; the proxy/frontend/backend will follow.",
+    `PROXY_PORT=${DEFAULT_PROXY_PORT}`,
+    `FRONTEND_PORT=${DEFAULT_FRONTEND_PORT}`,
+    `BACKEND_PORT=${DEFAULT_BACKEND_PORT}`,
+    "# Honor inbound X-Forwarded-* headers from an upstream TLS terminator",
+    "# (nginx / Caddy / Cloudflare / load balancer). Required so Better Auth,",
+    "# rate limiting, and audit logs see the real client origin & IP instead",
+    "# of the LB's. Set to 0 only if the proxy is directly internet-facing.",
+    "TRUST_PROXY=1",
+    "",
+    "# ── Shared (consumed by both apps) ───────────────────────────────",
+    `DATABASE_URL=${dbUrl}`,
+    `APOLLO_SECRET=${authSecret}`,
+    `CRON_SECRET=${cronSecret}`,
+    "# Public origin. Leave blank so the CMS respects the incoming request",
+    "# origin (works for localhost, preview URLs, and prod domains automatically).",
+    "# Set this ONLY when background jobs (cron / triggered emails) need a fixed",
+    "# origin outside a request scope — e.g. NEXT_PUBLIC_SITE_URL=https://cms.example.com",
+    `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
+    `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
+    "",
+  ];
+
+  lines.push("# ── Backend (apps/backend) ───────────────────────────────────────");
+  if (adminPrefix) {
+    lines.push(
+      "# Single-origin admin/asset prefix. The frontend rewrites this path",
+      "# to the backend, so backend chunks (served at <prefix>/_next/static)",
+      "# and admin pages share one rewrite.",
+      `APOLLO_ASSET_PREFIX=${adminPrefix}`,
+    );
+  }
+  lines.push(
+    "# Project-specific plugins — keeps the apollo-cms submodule clean.",
+    `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
+    "# PM2 namespace — groups this project's processes so you can",
+    "# `pm2 stop <namespace>` / `pm2 restart <namespace>` independently of",
+    "# other projects on the same host. Consumed by ecosystem.config.cjs.",
+    `PM2_NAMESPACE=${pm2Namespace}`,
+    "",
+    "# ── Frontend (apps/frontend) ─────────────────────────────────────",
+  );
+  if (adminPrefix) {
+    lines.push(
+      "# Where the frontend's rewrites point internally. In dev, leave blank",
+      "# to auto-derive http://127.0.0.1:${BACKEND_PORT} via scripts/with-env.mjs.",
+      "# In prod set to a private hostname (e.g. http://backend.internal:3000).",
+      `BACKEND_INTERNAL_URL=${backendInternalUrl}`,
+    );
+  } else {
+    lines.push(
+      "# Where the frontend reaches the backend in separate-origins mode.",
+      "# Defaults to the backend's dev port; override in prod to the real CMS host.",
+      `NEXT_PUBLIC_BACKEND_URL=${siteUrl || `http://localhost:${DEFAULT_BACKEND_PORT}`}`,
+    );
+  }
+  lines.push("");
+
+  writeFileSync(resolve(targetDir, ".env.local"), lines.join("\n"));
+}
+
+function writeFrontendApp(targetDir, frontendName, siteUrl, adminPrefix, backendInternalUrl) {
+  const dir = resolve(targetDir, FRONTEND_PATH);
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(resolve(dir, "src/app"), { recursive: true });
+  mkdirSync(resolve(dir, "public"), { recursive: true });
+
+  const pkg = {
+    name: frontendName,
+    version: "0.0.0",
+    private: true,
+    scripts: {
+      // No -p flag: Next.js reads PORT from env. The repo-root scripts use
+      // scripts/with-env.mjs --port=FRONTEND_PORT to inject the right value
+      // from .env.local (default 3001).
+      dev: "next dev",
+      build: "next build",
+      start: "next start",
+      lint: "next lint",
+      typecheck: "tsc --noEmit",
+    },
+    dependencies: {
+      next: "^16.0.0",
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
+    },
+    devDependencies: {
+      "@types/node": "^22.0.0",
+      "@types/react": "^19.0.0",
+      "@types/react-dom": "^19.0.0",
+      typescript: "^5.6.0",
+    },
+  };
+  writeFileSync(resolve(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  writeFileSync(
+    resolve(dir, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          lib: ["dom", "dom.iterable", "esnext"],
+          allowJs: true,
+          skipLibCheck: true,
+          strict: true,
+          noEmit: true,
+          esModuleInterop: true,
+          module: "esnext",
+          moduleResolution: "bundler",
+          resolveJsonModule: true,
+          isolatedModules: true,
+          jsx: "preserve",
+          incremental: true,
+          plugins: [{ name: "next" }],
+          paths: { "@/*": ["./src/*"] },
+        },
+        include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+        exclude: ["node_modules"],
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  // Frontend Next.js config:
+  //  - Single-origin mode (adminPrefix set): rewrite backend paths to apps/backend.
+  //    The chosen prefix is baked into the file at scaffold time — no
+  //    NEXT_PUBLIC_* env mirror, just `BACKEND_INTERNAL_URL` for the proxy target.
+  //  - Separate-origins mode (adminPrefix empty): no rewrites; the two apps
+  //    are reachable on their own ports/subdomains.
+  //
+  // When adminPrefix === "/admin" the explicit admin rewrite already covers
+  // backend chunks served under /admin/_next/static (via APOLLO_ASSET_PREFIX
+  // on the backend), so no separate prefix rewrite is emitted. For any other
+  // prefix the script also emits a rewrite for the assets path.
+  const isDefaultAdmin = adminPrefix === "/admin";
+  const extraPrefixRewrite = adminPrefix && !isDefaultAdmin
+    ? `      // Backend's namespaced Next.js chunks (set via APOLLO_ASSET_PREFIX)\n      { source: "${adminPrefix}/:path*", destination: \`\${BACKEND}${adminPrefix}/:path*\` },\n`
+    : "";
+  const nextConfigContent = adminPrefix
+    ? `import type { NextConfig } from "next";
+
+const BACKEND = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:3000";
+
+const config: NextConfig = {
+  reactStrictMode: true,
+  async rewrites() {
+    return [
+      // Apollo CMS admin UI (and its chunks when APOLLO_ASSET_PREFIX is /admin)
+      { source: "/admin/:path*", destination: \`\${BACKEND}/admin/:path*\` },
+      // Apollo CMS APIs (REST + auth + email + health + mcp + …)
+      { source: "/api/auth/:path*", destination: \`\${BACKEND}/api/auth/:path*\` },
+      { source: "/api/v1/:path*",   destination: \`\${BACKEND}/api/v1/:path*\` },
+      { source: "/api/email/:path*", destination: \`\${BACKEND}/api/email/:path*\` },
+      { source: "/api/health",      destination: \`\${BACKEND}/api/health\` },
+      { source: "/api/mcp",         destination: \`\${BACKEND}/api/mcp\` },
+      { source: "/api/editing-presence/:path*", destination: \`\${BACKEND}/api/editing-presence/:path*\` },
+      { source: "/api/admin/:path*", destination: \`\${BACKEND}/api/admin/:path*\` },
+      // Media uploads
+      { source: "/uploads/:path*",  destination: \`\${BACKEND}/uploads/:path*\` },
+${extraPrefixRewrite}    ];
+  },
+};
+
+export default config;
+`
+    : `import type { NextConfig } from "next";
+
+// Separate-origins mode: backend runs at http://localhost:3000, frontend here.
+// Switch to single-origin by setting APOLLO_ASSET_PREFIX in apps/backend/.env.local
+// and adding rewrites() — see this monorepo's README for the recipe.
+const config: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default config;
+`;
+  writeFileSync(resolve(dir, "next.config.ts"), nextConfigContent);
+
+  const envLocalLines = adminPrefix
+    ? [
+        `# Internal backend URL (used by Next.js rewrites — not exposed to browser)`,
+        `BACKEND_INTERNAL_URL=${backendInternalUrl}`,
+        "",
+      ]
+    : [
+        `# Public URL of the backend (used by your client code)`,
+        `NEXT_PUBLIC_BACKEND_URL=${siteUrl || `http://localhost:${DEFAULT_BACKEND_PORT}`}`,
+        "",
+      ];
+  writeFileSync(resolve(dir, ".env.local.example"), envLocalLines.join("\n"));
+
+  writeFileSync(
+    resolve(dir, "src/app/layout.tsx"),
+    `export const metadata = { title: "Frontend", description: "Apollo CMS frontend" };\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang="en">\n      <body>{children}</body>\n    </html>\n  );\n}\n`,
+  );
+
+  writeFileSync(
+    resolve(dir, "src/app/page.tsx"),
+    `export default function Page() {\n  return (\n    <main style={{ padding: 40, fontFamily: "system-ui" }}>\n      <h1>Frontend</h1>\n      <p>\n        Admin: <a href="/admin">/admin</a>\n      </p>\n    </main>\n  );\n}\n`,
+  );
+
+  writeFileSync(
+    resolve(dir, ".gitignore"),
+    // .env.local is intentionally committed — it only contains dev port hints.
+    ["node_modules", ".next", "dist", ""].join("\n"),
+  );
+}
+
+// ─── Custom plugins scaffold ─────────────────────────────────────────────────
+
+function writeExampleCmsPlugin(targetDir, dirName) {
+  const slug = "example-plugin";
+  const pkgName = `@${dirName}/cms-${slug}`;
+  const pluginDir = resolve(targetDir, "apps/cms-plugins", slug);
+  mkdirSync(pluginDir, { recursive: true });
+
+  const manifest = {
+    name: slug,
+    version: "0.1.0",
+    title: "Example Plugin",
+    description: "Project-specific plugin scaffold for the monorepo",
+    author: "you",
+  };
+  writeFileSync(resolve(pluginDir, "plugin.json"), JSON.stringify(manifest, null, 2) + "\n");
+
+  const pkg = {
+    name: pkgName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    exports: {
+      "./server": "./dist/server.mjs",
+    },
+    scripts: {
+      build: "node ./build.mjs",
+      // `dev` is the watcher entry — `pnpm dev` from the monorepo root fans
+      // out to it via `cms-plugins:dev`, so editing index.ts triggers an
+      // incremental rebuild and the backend's plugin loader picks up the new
+      // dist/server.mjs on the next request.
+      dev: "node ./build.mjs --watch",
+    },
+    devDependencies: {
+      esbuild: "^0.24.0",
+    },
+  };
+  writeFileSync(resolve(pluginDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  // Tiny zero-config build: bundle index.ts → dist/server.mjs as ESM Node.
+  // Pass --watch to keep esbuild's context alive and rebuild on file changes.
+  const buildMjs = `import { context, build } from "esbuild";
+
+const watch = process.argv.includes("--watch");
+
+const options = {
+  entryPoints: ["./index.ts"],
+  outfile: "./dist/server.mjs",
+  format: "esm",
+  platform: "node",
+  target: "node20",
+  bundle: true,
+  // Mark Apollo CMS internals as external — they're provided by the host
+  // backend at runtime via the loader's dynamic import().
+  external: ["@/*", "next", "react", "react-dom"],
+  logLevel: "info",
+};
+
+if (watch) {
+  const ctx = await context(options);
+  await ctx.watch();
+  console.log("[cms-plugin] watching index.ts → dist/server.mjs");
+} else {
+  await build(options);
+}
+`;
+  writeFileSync(resolve(pluginDir, "build.mjs"), buildMjs);
+
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2022",
+      module: "esnext",
+      moduleResolution: "bundler",
+      esModuleInterop: true,
+      skipLibCheck: true,
+      strict: true,
+      noEmit: true,
+      jsx: "preserve",
+      // Resolve `@/...` against the apollo-cms backend so plugin code can
+      // type-check against the real types from the submodule.
+      baseUrl: "../../backend",
+      paths: { "@/*": ["src/*"] },
+    },
+    include: ["**/*.ts", "**/*.tsx"],
+    exclude: ["dist", "node_modules"],
+  };
+  writeFileSync(resolve(pluginDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n");
+
+  const indexTs = `// Example Apollo CMS plugin — runs inside apps/backend at boot.
+//
+// The plugin loader picks up this file via package.json#exports["./server"]
+// → dist/server.mjs (built by \`pnpm cms-plugins:build\`).
+//
+// In dev under Bun the loader can also import index.ts directly (with a
+// warning); in production (next start) the dist file is required.
+
+import type { PluginDefinition } from "@/lib/plugins/types";
+
+const plugin: PluginDefinition = {
+  // Register hooks — see apollo-cms's HOOKS export for the full surface.
+  registerHooks(hooks, HOOKS) {
+    hooks.action(HOOKS.auth.afterLogin, async (ctx) => {
+      console.log("[example-plugin] login:", ctx.authUserId);
+    });
+  },
+
+  // Register UI slots — inject components into the admin shell.
+  // registerUiSlots(slots) { ... }
+
+  // Register API routes under /api/v1/<your-route>.
+  // registerApiRoutes(router) { ... }
+};
+
+export default plugin;
+`;
+  writeFileSync(resolve(pluginDir, "index.ts"), indexTs);
+
+  writeFileSync(
+    resolve(pluginDir, ".gitignore"),
+    ["node_modules", "dist", ""].join("\n"),
+  );
+
+  const readme = `# ${pkgName}
+
+Project-specific plugin loaded by the apollo-cms backend via
+\`APOLLO_EXTRA_PLUGINS_DIR\`.
+
+## Develop
+
+Run from the **monorepo root** (not this folder):
+
+\`\`\`bash
+pnpm dev                     # builds plugins + starts backend & frontend
+pnpm cms-plugins:build       # rebuild after editing
+\`\`\`
+
+## Author a new hook
+
+Open \`index.ts\` and add to \`registerHooks\`. The full hook surface lives in
+\`apps/backend/src/lib/plugins/hook-registry.ts\`.
+
+## Add another plugin
+
+\`\`\`bash
+pnpm cms-plugin:new my-plugin
+\`\`\`
+`;
+  writeFileSync(resolve(pluginDir, "README.md"), readme);
+}
+
+function writeNewCmsPluginScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+
+  const script = `#!/usr/bin/env node
+// Scaffold a new project-specific apollo-cms plugin under apps/cms-plugins/<slug>.
+// Usage: pnpm cms-plugin:new <slug>
+
+import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const monorepoRoot = resolve(__dirname, "..");
+const pluginsRoot = resolve(monorepoRoot, "apps/cms-plugins");
+const template = resolve(pluginsRoot, "example-plugin");
+
+const slug = (process.argv[2] ?? "").trim();
+if (!slug) {
+  console.error("Usage: pnpm cms-plugin:new <slug>");
+  process.exit(1);
+}
+if (!/^[a-z][a-z0-9-]*$/.test(slug)) {
+  console.error(\`Invalid slug "\${slug}" — use kebab-case (lowercase, digits, hyphens).\`);
+  process.exit(1);
+}
+if (!existsSync(template)) {
+  console.error(\`Template not found: \${template}\\nRecreate apps/cms-plugins/example-plugin or restore from a fresh \\\`npx create-apollo-suite-monorepo\\\` scaffold.\`);
+  process.exit(1);
+}
+
+const target = resolve(pluginsRoot, slug);
+if (existsSync(target)) {
+  console.error(\`Plugin already exists: \${target}\`);
+  process.exit(1);
+}
+
+cpSync(template, target, { recursive: true, filter: (src) => !/[\\\\\\/](node_modules|dist)([\\\\\\/]|$)/.test(src) });
+
+// Patch plugin.json
+const manifestPath = resolve(target, "plugin.json");
+const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+manifest.name = slug;
+manifest.title = slug.replace(/-/g, " ").replace(/\\b\\w/g, (c) => c.toUpperCase());
+manifest.description = \`Project plugin: \${slug}\`;
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\\n");
+
+// Patch package.json
+const pkgPath = resolve(target, "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+const rootPkg = JSON.parse(readFileSync(resolve(monorepoRoot, "package.json"), "utf-8"));
+pkg.name = \`@\${rootPkg.name}/cms-\${slug}\`;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\\n");
+
+console.log(\`Created apps/cms-plugins/\${slug}\`);
+console.log(\`Run: pnpm install && pnpm cms-plugins:build && pnpm dev:backend\`);
+`;
+  writeFileSync(resolve(scriptsDir, "new-cms-plugin.mjs"), script);
+}
+
+// Small launcher that loads root .env.local, applies port defaults
+// (PROXY_PORT=3030 / FRONTEND_PORT=3001 / BACKEND_PORT=3002), optionally maps
+// one of them onto PORT (Next.js reads PORT), and execs the rest of argv.
+//
+// Usage:
+//   node scripts/with-env.mjs [--port=VAR_NAME] <command> [args...]
+function writeWithEnvScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+  const script = `#!/usr/bin/env node
+// Loads <repo-root>/.env.local so frontend / backend / proxy all share one
+// source of truth for ports. Process env still wins.
+//
+// Usage:
+//   node scripts/with-env.mjs [--port=VAR_NAME] <command> [args...]
+// --port=FRONTEND_PORT copies process.env.FRONTEND_PORT onto PORT before exec,
+// so \`next dev\` and \`next start\` pick up the right port without --port flags.
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(here, "../.env.local");
+
+if (existsSync(envPath)) {
+  for (const raw of readFileSync(envPath, "utf8").split(/\\r?\\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const k = line.slice(0, eq).trim();
+    if (!/^[A-Z_][A-Z0-9_]*$/i.test(k)) continue;
+    if (process.env[k] !== undefined) continue;
+    let v = line.slice(eq + 1).trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    process.env[k] = v;
+  }
+}
+
+// Fallbacks — keep in sync with apps/proxy/server.mjs and PM2 config.
+process.env.PROXY_PORT ||= "3030";
+process.env.FRONTEND_PORT ||= "3001";
+process.env.BACKEND_PORT ||= "3002";
+
+// Derive URL vars from PORTs when unset. Dev-friendly: edit a port and
+// everything follows. Prod-friendly: set these explicitly to real hostnames
+// (e.g. https://cms.example.com, http://backend.internal:3000) and the
+// derivation is bypassed.
+//
+// NEXT_PUBLIC_SITE_URL is the public origin — defaults to the frontend port
+// (frontend rewrites /admin, /api, /uploads to the backend). For \`pnpm dev:rp\`
+// set it to http://localhost:\${PROXY_PORT} so Better Auth / OAuth callbacks
+// land on the unified origin.
+process.env.NEXT_PUBLIC_SITE_URL ||= \`http://localhost:\${process.env.FRONTEND_PORT}\`;
+process.env.BACKEND_INTERNAL_URL ||= \`http://127.0.0.1:\${process.env.BACKEND_PORT}\`;
+
+const args = process.argv.slice(2);
+if (args[0]?.startsWith("--port=")) {
+  const name = args.shift().slice(7);
+  if (process.env[name]) process.env.PORT = process.env[name];
+}
+
+if (!args.length) {
+  console.error("Usage: node scripts/with-env.mjs [--port=VAR] <command> [args...]");
+  process.exit(2);
+}
+
+const [cmd, ...rest] = args;
+const child = spawn(cmd, rest, {
+  stdio: "inherit",
+  env: process.env,
+  shell: process.platform === "win32",
+});
+child.on("exit", (code, sig) => process.exit(sig ? 1 : code ?? 0));
+`;
+  writeFileSync(resolve(scriptsDir, "with-env.mjs"), script);
+}
+
+// Pre-build env check. Fails the build before \`next build\` runs if backend
+// required vars are missing, so users don't sit through a 30s build only to
+// hit a runtime error on first request.
+function writeCheckEnvScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+  const script = `#!/usr/bin/env node
+// Pre-build sanity check. Reads apps/backend/.env.local and verifies that
+// required vars are present and non-empty. Skipped when SKIP_ENV_CHECK=1.
+//
+// In CI where envs come from the platform (not files), set
+// SKIP_ENV_CHECK=1 and rely on the platform's own validation.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.env.SKIP_ENV_CHECK === "1") process.exit(0);
+
+const REQUIRED = ["DATABASE_URL", "APOLLO_SECRET", "NEXT_PUBLIC_DEFAULT_LOCALE"];
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(__dirname, "../apps/backend/.env.local");
+
+if (!existsSync(envPath)) {
+  // Allow build to proceed if env vars are coming from process.env directly.
+  const fromProcess = REQUIRED.every((k) => process.env[k]);
+  if (fromProcess) process.exit(0);
+  console.error(
+    \`✗ Missing apps/backend/.env.local and required vars not in process.env.\\n  Required: \${REQUIRED.join(", ")}\\n  Hint: re-run the installer or copy apps/backend/.env.local.example\`,
+  );
+  process.exit(1);
+}
+
+const env = Object.fromEntries(
+  readFileSync(envPath, "utf-8")
+    .split("\\n")
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const i = line.indexOf("=");
+      return i === -1 ? [line, ""] : [line.slice(0, i).trim(), line.slice(i + 1).trim()];
+    }),
+);
+
+const missing = REQUIRED.filter((k) => !env[k] && !process.env[k]);
+if (missing.length) {
+  console.error(\`✗ Missing required env vars: \${missing.join(", ")}\\n  Edit apps/backend/.env.local or set them in process.env.\`);
+  process.exit(1);
+}
+console.log("✓ env check passed");
+`;
+  writeFileSync(resolve(scriptsDir, "check-env.mjs"), script);
+}
+
+// PM2 ecosystem config — production process supervision for self-hosted deploys.
+// Includes FE, BE, and optional proxy in fork mode (no clustering
+// since Next.js handles that internally and the proxy is single-threaded by design).
+function writePm2Config(targetDir, dirName, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
+  // The proxy `env` block conditionally includes ADMIN_PREFIX in single-origin
+  // mode. Built outside the template so we don't emit a stray comma or blank line.
+  const proxyEnv = [
+    "NODE_ENV: 'production',",
+    "PROXY_PORT,",
+    "FRONTEND_PORT,",
+    "BACKEND_PORT,",
+    ...(singleOrigin ? [`ADMIN_PREFIX: '${adminPrefix}',`] : []),
+  ].map((l) => "        " + l).join("\n");
+
+  const config = `// PM2 ecosystem config for ${dirName}.
+//
+// Loads .env.local at the top so PM2 picks up PROXY_PORT / FRONTEND_PORT /
+// BACKEND_PORT / PM2_NAMESPACE without a shell wrapper. The .env.local file
+// is the single source of truth — edit ports there, not here.
+//
+// Usage:
+//   pnpm install
+//   pnpm backend:upgrade
+//   pnpm build
+//   pm2 start ecosystem.config.cjs                    # FE + BE + proxy
+//   pm2 start ecosystem.config.cjs --only proxy       # only the reverse proxy
+//   pm2 stop  \${PM2_NAMESPACE}                         # stop everything in this project
+//   pm2 save && pm2 startup                           # persist across reboots
+
+const fs = require('fs');
+const path = require('path');
+
+// Inline .env.local parser. Kept tiny (no dotenv dep) so the ecosystem file
+// stays runnable before \`pnpm install\` finishes.
+const envPath = path.resolve(__dirname, '.env.local');
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\\n')) {
+    const m = line.match(/^\\s*([A-Z0-9_]+)\\s*=\\s*(.*?)\\s*$/i);
+    if (!m) continue;
+    const k = m[1];
+    let v = m[2];
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    if (process.env[k] === undefined) process.env[k] = v;
+  }
+}
+
+const NAMESPACE     = process.env.PM2_NAMESPACE || '${dirName}';
+const FRONTEND_PORT = Number(process.env.FRONTEND_PORT) || 3001;
+const BACKEND_PORT  = Number(process.env.BACKEND_PORT)  || 3002;
+const PROXY_PORT    = Number(process.env.PROXY_PORT)    || 3030;
+
+// Backend's internal URL (loopback). Server-to-server callers MUST target
+// this, never the proxy or frontend — going through the FE just adds a failure
+// mode (an HTML error page where JSON was expected).
+const BACKEND_INTERNAL_URL = process.env.BACKEND_INTERNAL_URL || \`http://127.0.0.1:\${BACKEND_PORT}\`;
+
+module.exports = {
+  apps: [
+    {
+      name: \`frontend:\${FRONTEND_PORT}\`,
+      namespace: NAMESPACE,
+      cwd: './apps/frontend',
+      script: 'node_modules/next/dist/bin/next',
+      args: 'start',
+      env: {
+        NODE_ENV: 'production',
+        PORT: FRONTEND_PORT,
+        // Next.js rewrites read this at request time. Without it the FE
+        // falls back to http://localhost:3000 and every /admin, /api, and
+        // /uploads request returns ECONNREFUSED.
+        BACKEND_INTERNAL_URL,
+      },
+      max_memory_restart: '1G',
+      autorestart: true,
+    },
+    {
+      name: \`backend:\${BACKEND_PORT}\`,
+      namespace: NAMESPACE,
+      cwd: './apps/backend',
+      script: 'node_modules/next/dist/bin/next',
+      args: 'start',
+      env: { NODE_ENV: 'production', PORT: BACKEND_PORT },
+      max_memory_restart: '1G',
+      autorestart: true,
+    },
+    {
+      name: \`proxy:\${PROXY_PORT}\`,
+      namespace: NAMESPACE,
+      script: './apps/proxy/server.mjs',
+      env: {
+${proxyEnv}
+      },
+      max_memory_restart: '256M',
+      autorestart: true,
+    },
+  ],
+};
+`;
+  writeFileSync(resolve(targetDir, "ecosystem.config.cjs"), config);
+}
+
+function writeClaudeMd(targetDir, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
+  const prefix = adminPrefix || "/admin";
+  const singleOriginSection = singleOrigin
+    ? `## Single-origin routing
+
+Frontend is the public entry point. It rewrites these paths to the backend (do **not** create matching routes in the frontend):
+
+- \`/admin/*\`, \`/uploads/*\`
+- \`/api/auth/*\`, \`/api/v1/*\`, \`/api/email/*\`, \`/api/health\`, \`/api/mcp\`, \`/api/admin/*\`, \`/api/editing-presence/*\`
+- \`/_next/static\` under \`APOLLO_ASSET_PREFIX=${prefix}\` (backend chunks)
+
+Custom frontend APIs must be namespaced (e.g. \`/api/internal/*\`).
+
+To disable single-origin: remove \`APOLLO_ASSET_PREFIX\` from \`apps/backend/.env.local\` and delete the \`rewrites()\` block in \`apps/frontend/next.config.ts\`.
+
+Known gotcha: backend's \`/_next/image\` is not rewritten — custom admin code using \`<Image>\` on \`/uploads/*\` will 404. Use plain \`<img>\` or \`unoptimized\`.
+`
+    : `## Routing model — separate origins
+
+Frontend and backend run on independent origins. No rewrites; talk to the backend over its public URL.
+`;
+
+  const content = `# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repo shape
+
+pnpm workspace monorepo. Three workspaces under \`apps/\`:
+
+- \`apps/frontend\` — public Next.js site${singleOrigin ? " (the public origin in single-origin mode)" : ""}.
+- \`apps/backend\` — **git submodule** pointing at \`apollo-cms\`. Treat as read-only; do not edit files in here. Open PRs upstream.
+- \`apps/cms-plugins/<slug>\` — project-specific Apollo CMS plugins. Loaded by the backend via \`APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins\`. Each plugin is built with esbuild to \`dist/server.mjs\` before the backend builds.
+- \`apps/proxy/server.mjs\` — zero-dep Node reverse proxy used for single-origin dev and self-hosted deploys.
+
+Built-in plugins in \`apps/backend/plugins/\` always win on slug collisions with \`apps/cms-plugins/\`.
+
+${singleOriginSection}
+## Common commands
+
+\`\`\`bash
+pnpm install
+pnpm backend:setup          # first-time: db:push + db:seed
+pnpm backend:upgrade        # release-time: db:push + replay src/upgrades/0.1.*.ts + seed
+pnpm backend:update         # fast-forward the apollo-cms submodule
+
+pnpm dev                    # FE + BE + plugin watcher (parallel)
+pnpm dev:rp                 # same + reverse proxy on :3030 (single origin, shared cookies)
+pnpm dev:frontend           # FE only
+pnpm dev:backend            # BE only (runs predev:setup to build plugins first)
+
+pnpm build                  # cms-plugins → backend plugins → backend → frontend
+pnpm build:backend
+pnpm build:frontend
+
+pnpm start                  # FE + BE
+pnpm start:rp               # FE + BE + proxy
+
+pnpm lint                   # recursive
+pnpm typecheck              # recursive
+
+pnpm cms-plugin:new <slug>  # scaffold a new plugin from example-plugin
+\`\`\`
+
+\`pnpm dev\` and \`pnpm build\` both run \`cms-plugins:build\` first (via \`predev:setup\` / build script chain) — plugins must compile to \`dist/server.mjs\` before the backend resolves them in production. In dev under Bun the loader also accepts \`index.ts\` directly.
+
+Release flow on a server: \`pnpm install && pnpm backend:upgrade && pnpm build && pm2 reload all\`. \`pnpm start\` does **not** run migrations.
+
+## Ports
+
+Configured in \`ecosystem.config.cjs\` (PM2) and consumed by \`apps/proxy/server.mjs\` via env:
+
+| Service  | Port |
+| -------- | ---- |
+| proxy    | 3030 |
+| backend  | 3000 |
+| frontend | 3001 |
+
+Proxy reads \`PORT\`, \`BACKEND\`, \`FRONTEND\`, \`ADMIN_PREFIX\` from env. When using the proxy locally, set \`NEXT_PUBLIC_SITE_URL=http://localhost:3030\` so Better Auth / OAuth callbacks land on the unified origin.
+
+## Deploy
+
+- Self-hosted: build on a runner, rsync to the server, then \`pm2 startOrReload ecosystem.config.cjs --update-env\`. If the backend submodule is private, the deploy runner needs a token with read access.
+
+## Submodule discipline
+
+- Do not edit files under \`apps/backend\` — they belong to the upstream \`apollo-cms\` repo.
+- After \`pnpm backend:update\`, run \`pnpm install\` (in case package.json changed) then \`pnpm backend:upgrade\` (replays data migrations that \`backend:setup\` skips).
+`;
+  writeFileSync(resolve(targetDir, "CLAUDE.md"), content);
+}
+
+function writeReadme(targetDir, dirName, frontendName, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
+
+  const originSection = singleOrigin
+    ? `## Routing model — single origin
+
+Both apps share one public origin (the frontend). The frontend rewrites these
+paths to the backend so /_next/* doesn't collide:
+
+| Path                        | Goes to            |
+| --------------------------- | ------------------ |
+| \`/\` and other frontend routes | \`apps/frontend\`     |
+| \`/admin/*\`                  | \`apps/backend\`      |
+| \`/api/auth/*\`, \`/api/v1/*\`, \`/api/email/*\`, \`/api/health\`, \`/api/mcp\`, \`/api/admin/*\`, \`/api/editing-presence/*\` | \`apps/backend\` |
+| \`/uploads/*\`                | \`apps/backend\` (media) |
+| \`${adminPrefix}/*\`              | \`apps/backend\` (chunks via \`APOLLO_ASSET_PREFIX\`) |
+
+The frontend MUST NOT define routes at \`/admin\`, \`/api/auth\`, \`/api/v1\`, etc.
+If you need your own API, namespace it under \`/api/internal/*\` or similar.
+
+### Reverse proxy
+
+Two options ship out of the box:
+
+- **\`apps/proxy\`** (Node.js, zero deps) — opt in with \`pnpm dev:rp\`. Runs FE,
+  BE, plugins watcher, and a reverse proxy on **:3030** so everything sits on
+  one origin (shared cookies, no CORS). Best for local dev and small self-hosted
+  deploys. Configure via \`PORT\`, \`BACKEND\`, \`FRONTEND\`, \`ADMIN_PREFIX\`.
+- **\`nginx.conf.sample\`** (production) — same routing baked in (frontend on
+  :3001, backend on :3000). Use it when fronting both apps behind a single
+  TLS-terminating proxy — drop in your domain and SSL certs.
+
+To **disable** single-origin and run the backend on its own subdomain,
+delete \`APOLLO_ASSET_PREFIX\` from \`apps/backend/.env.local\` and remove the
+\`rewrites()\` block from \`apps/frontend/next.config.ts\`.
+
+### Known limitations
+
+- The backend's \`/_next/image\` (Next.js Image optimization endpoint) is **not**
+  rewritten — only \`/_next/static\` moves under \`APOLLO_ASSET_PREFIX\`. If your
+  backend admin uses \`<Image>\` to render \`/uploads/*\` media, those will fall
+  back to the frontend's image optimizer and 404. Apollo CMS's stock admin uses
+  plain \`<img>\` for uploaded media so this rarely matters; if you customize the
+  admin and need optimized images, switch to separate-origins mode or set
+  \`unoptimized\` on those \`<Image>\` instances.
+`
+    : `## Routing model — separate origins
+
+The two apps run on separate origins. Default ports:
+
+- Backend (apps/backend): http://localhost:3000
+- Frontend (apps/frontend): http://localhost:3001
+
+\`NEXT_PUBLIC_SITE_URL\` should point at whichever origin you treat as the
+public CMS URL (typically the backend). To switch to **single-origin** later,
+re-run the installer with \`--admin-prefix /admin\` or set
+\`APOLLO_ASSET_PREFIX\` in \`apps/backend/.env.local\` and add the matching
+\`rewrites()\` block to \`apps/frontend/next.config.ts\`.
+`;
+
+  const readme = `# ${dirName}
+
+Monorepo with a custom frontend and Apollo CMS as a git submodule backend.
+
+## Layout
+
+\`\`\`
+${dirName}/
+├── apps/
+│   ├── frontend/   ← ${frontendName}
+│   └── backend/    ← git submodule → apollo-cms (read-only, pull updates)
+├── package.json
+└── pnpm-workspace.yaml
+\`\`\`
+
+## Quick start
+
+\`\`\`bash
+pnpm install
+pnpm backend:setup       # push schema + seed apollo-cms
+pnpm dev                 # runs frontend (3001) + backend (3000) in parallel
+# or:
+pnpm dev:rp              # same + reverse proxy on :3030 (single-origin, shared cookies)
+\`\`\`
+
+When using \`pnpm dev:rp\`, set \`NEXT_PUBLIC_SITE_URL=http://localhost:3030\`
+in your \`.env.local\` so Better Auth, OAuth callbacks, and email links use
+the unified origin.
+
+${originSection}
+## Custom plugins
+
+Project-specific plugins live in \`apps/cms-plugins/<slug>/\` and are loaded by
+the apollo-cms backend via \`APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins\` (set
+automatically in \`apps/backend/.env.local\`). The submodule stays clean —
+\`pnpm backend:update\` won't conflict with your plugins.
+
+### Author a new plugin
+
+\`\`\`bash
+pnpm cms-plugin:new my-plugin
+pnpm install
+pnpm dev
+\`\`\`
+
+The scaffolder copies \`apps/cms-plugins/example-plugin/\` to
+\`apps/cms-plugins/my-plugin/\` and renames it. Edit \`index.ts\` to register
+hooks, UI slots, and API routes — see
+\`apps/backend/docs/plugin-system.md\` for the full surface.
+
+### Build pipeline
+
+\`pnpm dev\` and \`pnpm build\` run \`pnpm cms-plugins:build\` first to compile
+each plugin's \`index.ts\` → \`dist/server.mjs\` (via esbuild). The backend's
+plugin loader resolves \`dist/server.mjs\` in production; in dev under Bun it
+also accepts \`index.ts\` directly.
+
+### Slug collisions
+
+Built-in plugins under \`apps/backend/plugins/\` always win on slug collision.
+If you see *"Plugin slug collision"* in the backend logs, rename your plugin's
+folder + \`plugin.json#name\`.
+
+## Updating the backend
+
+Apollo CMS is tracked as a git submodule. Full upgrade flow:
+
+\`\`\`bash
+pnpm backend:update    # auto-stash, fast-forward apps/backend, run pnpm install
+pnpm backend:upgrade   # drizzle push + replay version migrations + seed
+\`\`\`
+
+| Script | What it does |
+| --- | --- |
+| \`pnpm backend:update\`  | Auto-stashes local submodule changes, fast-forwards \`apps/backend\`, runs \`pnpm install\` so new backend deps are picked up, then restores the stash. |
+| \`pnpm backend:setup\`   | First-time bootstrap: \`db:push\` + \`db:seed\` only |
+| \`pnpm backend:upgrade\` | Full pipeline: \`db:push\` + replay \`src/upgrades/0.1.*.ts\` data migrations + \`db:seed\`. **Use this** after \`backend:update\` — \`backend:setup\` skips the data-migration phase. |
+
+Do **not** edit files inside \`apps/backend\`. Open issues / PRs in the
+\`apollo-cms\` repository upstream.
+
+## Environment variables
+
+Shared dev env lives in the root \`.env.local\`. The backend reads its own
+\`apps/backend/.env.local\` (already populated by the installer).
+
+## Deploy (self-hosted)
+
+Standard sequence on a VPS / Docker host / bare metal:
+
+\`\`\`bash
+pnpm install
+pnpm backend:upgrade   # db push + replay data migrations + seed (run ONCE per release)
+pnpm build             # builds plugins → backend → frontend
+pnpm start             # FE :3001 + BE :3000  — or:
+pnpm start:rp          # adds Node reverse proxy on :3030 (single origin)
+\`\`\`
+
+\`pnpm start\` does **not** run migrations on boot — that lets you restart
+processes without re-running \`drizzle-kit push\` every time. Always run
+\`pnpm backend:upgrade\` once per release before \`pnpm start\`.
+
+| Script              | What it does                                                        |
+| ------------------- | ------------------------------------------------------------------- |
+| \`pnpm build\`        | Full pipeline: cms-plugins → backend plugins → backend → frontend   |
+| \`pnpm start\`        | FE + BE (parallel \`next start\`)                                     |
+| \`pnpm start:rp\`     | FE + BE + reverse proxy on :3030                                    |
+| \`pnpm start:proxy\`  | Reverse proxy alone (already running FE/BE separately)              |
+
+### PM2 (recommended for VPS)
+
+The installer scaffolds \`ecosystem.config.cjs\`. To supervise everything:
+
+\`\`\`bash
+pm2 start ecosystem.config.cjs                  # FE + BE + proxy (all three)
+pm2 start ecosystem.config.cjs --only proxy     # only the reverse proxy
+pm2 save && pm2 startup                         # persist across reboots
+pm2 logs \${PM2_NAMESPACE:-${dirName}}             # tail just this project's logs
+pm2 reload \${PM2_NAMESPACE:-${dirName}}            # zero-downtime restart (namespace-scoped)
+pm2 stop   \${PM2_NAMESPACE:-${dirName}}            # stop only this project
+\`\`\`
+
+All three processes are grouped under the \`PM2_NAMESPACE\` set in \`.env.local\`
+(defaults to \`${dirName}\`), so namespace commands target only this project
+even when other PM2 apps share the host. Process names embed the bound port
+(\`frontend:3001\`, \`backend:3002\`, \`proxy:3030\`) for quick \`pm2 ls\` triage.
+
+The proxy process can be omitted with \`--only\` if you front the apps with
+nginx/Caddy. Scheduled jobs need no extra process — the backend drives its
+scheduler queue in-process.
+
+### Docker / k8s
+
+For containerized deploys:
+- Bake the build into the image (\`pnpm install && pnpm build\`)
+- Set entrypoint to \`pnpm start\` or \`pnpm start:rp\`
+- Run \`pnpm backend:upgrade\` as a separate init container / Job before app pods start
+- No cron sidecar needed — the backend drives its scheduler queue in-process
+`;
+  writeFileSync(resolve(targetDir, "README.md"), readme);
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const flags = parseArgs(process.argv);
+
+  if (flags.help) {
+    log(HELP_TEXT);
+    process.exit(0);
+  }
+
+  if (!flags.directory) {
+    log(HELP_TEXT);
+    fatal("Please provide a directory name.\n  Example: npx create-apollo-suite-monorepo my-site");
+  }
+
+  log(`\n${COLORS.bold}${COLORS.cyan}  Apollo CMS Monorepo Installer${COLORS.reset}\n`);
+
+  // ── Step 1: Pre-flight ──
+  const targetDir = preflight(flags);
+  const dirName = basename(targetDir);
+  const frontendName = flags.frontendName ?? `@${dirName}/frontend`;
+
+  // ── Step 2: Gather env ──
+  step(2, "Configuring environment");
+  const adminPrefix =normalizeAdminPrefix(flags.adminPrefix);
+  const { dbUrl, siteUrl, locale } = await gatherEnv(flags);
+  const authSecret = randomBytes(48).toString("base64");
+  // Authenticates trusted callers of apollo-cms's /api/health?check=ready.
+  // Without it that readiness check answers 403 "CRON_SECRET not configured".
+  const cronSecret = randomBytes(24).toString("hex");
+  const backendInternalUrl = `http://localhost:${DEFAULT_BACKEND_PORT}`;
+  success(`Frontend pkg name: ${frontendName}`);
+  success(`Admin prefix: ${adminPrefix || "(disabled — separate origins)"}`);
+
+  // ── Step 3: Scaffold root ──
+  step(3, "Scaffolding monorepo root");
+  mkdirSync(targetDir, { recursive: true });
+  mkdirSync(resolve(targetDir, "apps"), { recursive: true });
+  writeRootPackageJson(targetDir, dirName);
+  writePnpmWorkspace(targetDir);
+  writeRootGitignore(targetDir);
+  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl, pm2Namespace: dirName });
+  writeReadme(targetDir, dirName, frontendName, adminPrefix);
+  writeClaudeMd(targetDir, adminPrefix);
+  if (adminPrefix) writeNginxSample(targetDir, adminPrefix);
+  writeProxyApp(targetDir, dirName, adminPrefix);
+  writeCheckEnvScript(targetDir);
+  writeWithEnvScript(targetDir);
+  writePm2Config(targetDir, dirName, adminPrefix);
+  success(
+    `package.json, pnpm-workspace.yaml, .gitignore, .env.local, README.md, CLAUDE.md${
+      adminPrefix ? ", nginx.conf.sample" : ""
+    }, apps/proxy, ecosystem.config.cjs, scripts/check-env.mjs, scripts/with-env.mjs`,
+  );
+
+  // ── Step 4: git init ──
+  step(4, "Initializing git");
+  run("git init -b main", { cwd: targetDir, stdio: "pipe" });
+  success("git repo initialized");
+
+  // ── Step 5: Frontend skeleton ──
+  step(5, "Creating frontend app");
+  writeFrontendApp(targetDir, frontendName, siteUrl, adminPrefix, backendInternalUrl);
+  success(`apps/frontend (${frontendName})`);
+
+  // ── Step 5b: Custom plugins workspace + example ──
+  step("5b", "Scaffolding apps/cms-plugins/example-plugin");
+  writeExampleCmsPlugin(targetDir, dirName);
+  writeNewCmsPluginScript(targetDir);
+  success("apps/cms-plugins/example-plugin + scripts/new-cms-plugin.mjs");
+
+  // ── Step 6: Backend submodule ──
+  if (flags.skipSubmodule) {
+    step(6, "Skipping git submodule (--skip-submodule)");
+    warn(
+      `Add it later:\n      cd ${dirName}\n      git submodule add -b ${flags.backendBranch} ${flags.backendUrl} ${BACKEND_PATH}`,
+    );
+  } else {
+    step(6, `Adding apollo-cms as git submodule (${BACKEND_PATH})`);
+    try {
+      run(
+        `git submodule add -b ${flags.backendBranch} ${flags.backendUrl} ${BACKEND_PATH}`,
+        { cwd: targetDir },
+      );
+      run(`git submodule update --init --recursive`, { cwd: targetDir });
+      success("submodule added");
+    } catch {
+      fatal(
+        `Failed to add submodule.\n  Check the URL and your network, then run:\n  cd ${dirName} && git submodule add -b ${flags.backendBranch} ${flags.backendUrl} ${BACKEND_PATH}`,
+      );
+    }
+
+    const backendFallback = [
+      `DATABASE_URL=${dbUrl}`,
+      `APOLLO_SECRET=${authSecret}`,
+      `CRON_SECRET=${cronSecret}`,
+      `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
+      `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
+      `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
+      `PM2_NAMESPACE=${dirName}`,
+    ];
+    if (adminPrefix) backendFallback.push(`APOLLO_ASSET_PREFIX=${adminPrefix}`);
+    linkRootEnvLocal(targetDir, BACKEND_PATH, backendFallback);
+  }
+
+  // Frontend gets the same treatment — Next.js running in apps/frontend
+  // can't see the root file otherwise, and next.config.ts references
+  // BACKEND_INTERNAL_URL for the rewrites destination.
+  const frontendFallback = adminPrefix
+    ? [`BACKEND_INTERNAL_URL=${backendInternalUrl}`]
+    : [`NEXT_PUBLIC_BACKEND_URL=${siteUrl || `http://localhost:${DEFAULT_BACKEND_PORT}`}`];
+  linkRootEnvLocal(targetDir, FRONTEND_PATH, frontendFallback);
+
+  // ── Step 7: Install ──
+  if (flags.skipInstall) {
+    step(7, "Skipping dependency installation (--skip-install)");
+    warn(`Run later:\n      cd ${dirName} && pnpm install`);
+  } else if (!commandExists("pnpm")) {
+    step(7, "Skipping dependency installation (pnpm not installed)");
+    warn(`Install pnpm and run:\n      npm i -g pnpm && cd ${dirName} && pnpm install`);
+  } else {
+    step(7, "Installing dependencies (pnpm)");
+    try {
+      run("pnpm install", { cwd: targetDir });
+      success("dependencies installed");
+    } catch {
+      warn(`Install failed — run manually: cd ${dirName} && pnpm install`);
+    }
+  }
+
+  // ── Done ──
+  log(`
+${COLORS.green}${COLORS.bold}  Monorepo created!${COLORS.reset}
+
+  ${COLORS.bold}cd${COLORS.reset} ${dirName}
+  ${COLORS.bold}pnpm backend:setup${COLORS.reset}   ${COLORS.dim}# push schema + seed apollo-cms${COLORS.reset}
+  ${COLORS.bold}pnpm dev${COLORS.reset}             ${COLORS.dim}# frontend :3001 + backend :3000${COLORS.reset}
+
+  ${COLORS.dim}APOLLO_SECRET=${authSecret}${COLORS.reset}
+`);
+}
+
+main().catch((err) => {
+  fatal(err.message ?? String(err));
+});