@geekmidas/cli 10.0.0-alpha.1 → 10.0.0-alpha.10

package/dist/index.cjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env -S npx tsx
 const require_chunk = require('./chunk-CUT6urMc.cjs');
 const require_discover = require('./discover-DTmFeloL.cjs');
-const require_config = require('./config-DbPE1KXF.cjs');
-const require_workspace = require('./workspace-XvqO9jIv.cjs');
+const require_config = require('./config-BZ1F0WuA.cjs');
+const require_workspace = require('./workspace-C6VJQVtG.cjs');
 const require_credentials = require('./credentials-BapzjyV5.cjs');
-const require_credentials$1 = require('./credentials-K961ThG3.cjs');
+const require_credentials$1 = require('./credentials-Xamqe_NJ.cjs');
 const require_generator = require('./generator-CNzBw7g5.cjs');
 const require_storage = require('./storage-BJmzYxt8.cjs');
-const require_openapi = require('./openapi-CljONd_M.cjs');
+const require_openapi = require('./openapi-SjsgARie.cjs');
 const require_emit = require('./emit-CbcRolsa.cjs');
 const require_dokploy_api = require('./dokploy-api-BsVH0y_s.cjs');
 const require_encryption = require('./encryption-C6jaU0hE.cjs');
@@ -15,7 +15,7 @@ const require_CachedStateProvider = require('./CachedStateProvider-CqPdW7CB.cjs'
 const require_fullstack_secrets = require('./fullstack-secrets-C-GGohke.cjs');
 const require_openapi_react_query = require('./openapi-react-query-CmJ1xDbn.cjs');
 require('./sync-SizaChmC.cjs');
-const require_setup = require('./setup-CJiQM2pX.cjs');
+const require_setup = require('./setup-hC6hI86f.cjs');
 const node_fs = require_chunk.__toESM(require("node:fs"));
 const node_path = require_chunk.__toESM(require("node:path"));
 const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
@@ -43,7 +43,7 @@ const prompts = require_chunk.__toESM(require("prompts"));
 
 //#region package.json
 var name = "@geekmidas/cli";
-var version = "10.0.0-alpha.0";
+var version = "10.0.0-alpha.10";
 var description = "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs";
 var private$1 = false;
 var type = "module";
@@ -124,12 +124,12 @@ var repository = {
 	"url": "https://github.com/geekmidas/toolbox"
 };
 var dependencies = {
-	"@apidevtools/swagger-parser": "^10.1.0",
-	"@aws-sdk/client-iam": "~3.992.0",
-	"@aws-sdk/client-route-53": "~3.992.0",
-	"@aws-sdk/client-s3": "~3.992.0",
-	"@aws-sdk/client-ssm": "~3.992.0",
-	"@aws-sdk/credential-providers": "~3.992.0",
+	"@apidevtools/swagger-parser": "~13.1.0",
+	"@aws-sdk/client-iam": "~3.1136.0",
+	"@aws-sdk/client-route-53": "~3.1136.0",
+	"@aws-sdk/client-s3": "~3.1136.0",
+	"@aws-sdk/client-ssm": "~3.1136.0",
+	"@aws-sdk/credential-providers": "~3.1136.0",
 	"@geekmidas/cache": "workspace:*",
 	"@geekmidas/constructs": "workspace:~",
 	"@geekmidas/db": "workspace:*",
@@ -138,28 +138,29 @@ var dependencies = {
 	"@geekmidas/logger": "workspace:~",
 	"@geekmidas/manifest": "workspace:*",
 	"@geekmidas/schema": "workspace:~",
-	"chokidar": "~4.0.3",
-	"commander": "^12.1.0",
-	"dotenv": "~17.2.3",
-	"esbuild": "^0.28.2",
-	"fast-glob": "^3.3.2",
-	"hono": "~4.8.0",
-	"lodash.kebabcase": "^4.1.1",
-	"openapi-typescript": "^7.4.2",
-	"pg": "~8.17.1",
+	"chokidar": "~5.0.0",
+	"commander": "~15.0.0",
+	"dotenv": "~18.0.1",
+	"esbuild": "~0.28.2",
+	"fast-glob": "~3.3.3",
+	"get-tsconfig": "~4.10.1",
+	"hono": "~4.13.8",
+	"lodash.kebabcase": "~4.1.1",
+	"openapi-typescript": "~7.13.0",
+	"pg": "~8.23.0",
 	"prompts": "~2.4.2",
 	"tsx": "~4.20.3",
-	"yaml": "~2.8.2"
+	"yaml": "~2.9.1"
 };
 var devDependencies = {
 	"@geekmidas/testkit": "workspace:*",
-	"@types/lodash.kebabcase": "^4.1.9",
+	"@types/lodash.kebabcase": "~4.1.9",
 	"@types/node": "~24.9.1",
-	"@types/pg": "~8.16.0",
+	"@types/pg": "~8.23.1",
 	"@types/prompts": "~2.4.9",
-	"typescript": "^5.8.2",
-	"vitest": "^3.2.4",
-	"zod": "~4.1.13"
+	"typescript": "~5.8.2",
+	"vitest": "~3.2.4",
+	"zod": "~4.6.5"
 };
 var peerDependencies = { "@geekmidas/telescope": "workspace:~" };
 var peerDependenciesMeta = { "@geekmidas/telescope": { "optional": true } };
@@ -415,11 +416,16 @@ var CronGenerator = class extends require_discover.ConstructGenerator {
 		const provider = options?.provider || "aws-lambda";
 		const logger$12 = console;
 		const cronInfos = [];
+		if (provider === "server") {
+			await this.generateServerCronsFile(outputDir, constructs);
+			logger$12.log(`Generated server crons file with ${constructs.length} crons`);
+			return cronInfos;
+		}
 		if (constructs.length === 0 || provider !== "aws-lambda") return cronInfos;
 		const cronsDir = (0, node_path.join)(outputDir, "crons");
 		await (0, node_fs_promises.mkdir)(cronsDir, { recursive: true });
 		for (const { key, construct, path } of constructs) {
-			const handlerFile = await this.generateCronHandler(cronsDir, path.relative, key, context);
+			const handlerFile = await this.generateCronHandler(cronsDir, path.relative, key, context, construct.owner);
 			cronInfos.push({
 				name: key,
 				handler: (0, node_path.relative)(process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
@@ -436,17 +442,173 @@ var CronGenerator = class extends require_discover.ConstructGenerator {
 	isConstruct(value) {
 		return __geekmidas_constructs_crons.Cron.isCron(value);
 	}
-	async generateCronHandler(outputDir, sourceFile, exportName, context) {
+	/**
+	* The crons file a server entry imports.
+	*
+	* Shaped after `generateServerSubscribersFile`: one module, every cron, a
+	* `setupCrons` the generated entry calls beside `setupSubscribers`.
+	*
+	* It picks its scheduler from what the process can reach. With a Postgres it
+	* uses pg-boss, whose schedules live in the database — so a deployment
+	* running four replicas fires each job once, which is the thing a timer in
+	* every process gets wrong and does not report. With no database it falls
+	* back to timers and says plainly that it is doing so.
+	*/
+	async generateServerCronsFile(outputDir, crons) {
+		await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+		const cronsPath = (0, node_path.join)(outputDir, "crons.ts");
+		const importsByFile = /* @__PURE__ */ new Map();
+		for (const { path, key } of crons) {
+			const relativePath = (0, node_path.relative)((0, node_path.dirname)(cronsPath), path.relative);
+			const importPath = relativePath.replace(/\.ts$/, ".js");
+			if (!importsByFile.has(importPath)) importsByFile.set(importPath, []);
+			importsByFile.get(importPath)?.push(key);
+		}
+		const imports = Array.from(importsByFile.entries()).map(([importPath, exports$2]) => `import { ${exports$2.join(", ")} } from '${importPath}';`).join("\n");
+		const entries = crons.map(({ key }) => `  { name: '${key}', cron: ${key} }`).join(",\n");
+		const content = `/**
+ * Generated cron setup.
+ *
+ * Schedules every cron this app declares, in the process that serves it.
+ *
+ * The schedule lives in Postgres, through pg-boss, in the database the worker
+ * named with \`.database(db)\`. That is what makes running several replicas
+ * safe: each job fires once, where a timer in every process fires it once per
+ * replica and reports nothing.
+ *
+ * No connection string appears here. The construct that owns the database is
+ * the only thing that knows its key, and it is resolved through service
+ * discovery like any other dependency.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { toCronExpression } from '@geekmidas/constructs/crons';
+import { ServiceDiscovery } from '@geekmidas/services';
+${imports}
+
+const crons = [
+${entries}
+];
+
+type Stoppable = { stop: () => Promise<void> | void };
+const running: Stoppable[] = [];
+
+export async function setupCrons(
+  envParser: EnvironmentParser<any>,
+  logger: Logger,
+): Promise<void> {
+  if (crons.length === 0) {
+    return;
+  }
+
+  const serviceDiscovery = ServiceDiscovery.getInstance(envParser);
+
+  // Resolved once per cron rather than per firing: registering services on
+  // every tick would reconnect a database every minute.
+  const prepared = [];
+  for (const { name, cron } of crons) {
+    try {
+      const schedule = toCronExpression(cron.schedule);
+      const services = cron.services.length > 0
+        ? await serviceDiscovery.register(cron.services)
+        : {};
+
+      prepared.push({ name, cron, schedule, services });
+    } catch (error) {
+      // An unrepresentable schedule is a build-time mistake, and failing the
+      // process for it would take the HTTP server down with it.
+      logger.error({ error, cron: name }, 'Cron has no runnable schedule, skipping');
+    }
+  }
+
+  const run = async (entry: (typeof prepared)[number]) => {
+    try {
+      await entry.cron.handler({
+        input: undefined,
+        services: entry.services,
+        logger: entry.cron.logger,
+      });
+    } catch (error) {
+      logger.error({ error, cron: entry.name }, 'Cron failed');
+    }
+  };
+
+  // Declared once on the worker, carried onto every cron it built — so this
+  // reads it from any of them rather than from config or the environment.
+  const scheduleStore = prepared.find(({ cron }) => cron.scheduleStore)?.cron
+    .scheduleStore;
+
+  if (!scheduleStore) {
+    // Declared, not discovered. A worker says where its schedules live with
+    // \`.database(db)\`; inferring one from whatever database happened to be
+    // around would move the schedules the day an app declared a second.
+    logger.error(
+      { crons: prepared.map(({ name }) => name) },
+      'These crons have nowhere to keep their schedule. A server fires its own ' +
+        'crons, and a process scheduling in memory fires each job once per ' +
+        'replica — so the schedule lives in Postgres. Say where with ' +
+        '\`new Worker(…).database(db)\`.',
+    );
+    return;
+  }
+
+  const [store] = await serviceDiscovery
+    .register([scheduleStore])
+    .then((s) => Object.values(s));
+
+  const { PgBoss } = await import('pg-boss');
+  // The pool the construct already opened — no connection string is read here,
+  // and none is named anywhere outside the construct that owns it.
+  const boss = new PgBoss({ db: store as never });
+  await boss.start();
+
+  // What this app declares now. Anything else under the prefix belonged to a
+  // cron since renamed or deleted, and would keep firing at a handler that has
+  // gone.
+  //
+  // The prefix is \`cron.\` rather than \`cron:\`: pg-boss accepts
+  // alphanumerics, underscores, hyphens, periods and slashes in a queue name,
+  // and rejects a colon outright.
+  const declared = new Set(prepared.map(({ name }) => \`cron.\${name}\`));
+  for (const existing of await boss.getSchedules()) {
+    if (existing.name.startsWith('cron.') && !declared.has(existing.name)) {
+      await boss.unschedule(existing.name);
+      logger.info({ cron: existing.name }, 'Removed a schedule nothing declares');
+    }
+  }
+
+  for (const entry of prepared) {
+    const queue = \`cron.\${entry.name}\`;
+    await boss.createQueue(queue);
+    // UTC, so this agrees with the schedule a deploy target would have made.
+    await boss.schedule(queue, entry.schedule, undefined, { tz: 'UTC' });
+    await boss.work(queue, () => run(entry));
+
+    logger.info({ cron: entry.name, schedule: entry.schedule }, 'Cron scheduled');
+  }
+
+  running.push({ stop: () => boss.stop() });
+  logger.info({ count: prepared.length }, 'Crons scheduled');
+}
+
+export async function stopCrons(): Promise<void> {
+  await Promise.all(running.map((r) => r.stop()));
+  running.length = 0;
+}
+`;
+		await (0, node_fs_promises.writeFile)(cronsPath, content);
+		return cronsPath;
+	}
+	async generateCronHandler(outputDir, sourceFile, exportName, context, owner) {
 		const handlerFileName = `${exportName}.ts`;
 		const handlerPath = (0, node_path.join)(outputDir, handlerFileName);
 		const relativePath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile);
 		const importPath = relativePath.replace(/\.ts$/, ".js");
-		const relativeEnvParserPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), context.envParserPath);
-		const relativeLoggerPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), context.loggerPath);
-		const content = `import { AWSScheduledFunction } from '@geekmidas/constructs/crons';
+		const runtime = require_openapi.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
+		const content = `import { AWSScheduledFunction } from '@geekmidas/constructs/aws';
 import { ${exportName} } from '${importPath}';
-import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
-import ${context.loggerImportPattern} from '${relativeLoggerPath}';
+${runtime.imports}
+${runtime.bindings}
 
 const adapter = new AWSScheduledFunction(envParser, ${exportName});
 
@@ -562,7 +724,7 @@ var FunctionGenerator = class extends require_discover.ConstructGenerator {
 		const functionsDir = (0, node_path.join)(outputDir, "functions");
 		await (0, node_fs_promises.mkdir)(functionsDir, { recursive: true });
 		for (const { key, construct, path } of constructs) {
-			const handlerFile = await this.generateFunctionHandler(functionsDir, path.relative, key, context);
+			const handlerFile = await this.generateFunctionHandler(functionsDir, path.relative, key, context, construct.owner);
 			functionInfos.push({
 				name: key,
 				handler: (0, node_path.relative)(process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
@@ -575,17 +737,16 @@ var FunctionGenerator = class extends require_discover.ConstructGenerator {
 		}
 		return functionInfos;
 	}
-	async generateFunctionHandler(outputDir, sourceFile, exportName, context) {
+	async generateFunctionHandler(outputDir, sourceFile, exportName, context, owner) {
 		const handlerFileName = `${exportName}.ts`;
 		const handlerPath = (0, node_path.join)(outputDir, handlerFileName);
 		const relativePath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile);
 		const importPath = relativePath.replace(/\.ts$/, ".js");
-		const relativeEnvParserPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), context.envParserPath);
-		const relativeLoggerPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), context.loggerPath);
+		const runtime = require_openapi.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
 		const content = `import { AWSLambdaFunction } from '@geekmidas/constructs/aws';
 import { ${exportName} } from '${importPath}';
-import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
-import ${context.loggerImportPattern} from '${relativeLoggerPath}';
+${runtime.imports}
+${runtime.bindings}
 
 const adapter = new AWSLambdaFunction(envParser, ${exportName});
 
@@ -624,7 +785,7 @@ var QueueGenerator = class extends require_discover.ConstructGenerator {
 		const queuesDir = (0, node_path.join)(outputDir, "queues");
 		await (0, node_fs_promises.mkdir)(queuesDir, { recursive: true });
 		for (const { key, construct, path } of constructs) {
-			const handlerFile = await this.generateQueueHandler(queuesDir, path.relative, key, context);
+			const handlerFile = await this.generateQueueHandler(queuesDir, path.relative, key, context, construct.owner);
 			queueInfos.push({
 				name: construct.name,
 				handler: (0, node_path.relative)(process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
@@ -638,13 +799,14 @@ var QueueGenerator = class extends require_discover.ConstructGenerator {
 		}
 		return queueInfos;
 	}
-	async generateQueueHandler(outputDir, sourceFile, exportName, context) {
+	async generateQueueHandler(outputDir, sourceFile, exportName, context, owner) {
 		const handlerPath = (0, node_path.join)(outputDir, `${exportName}.ts`);
 		const importPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile).replace(/\.ts$/, ".js");
-		const relativeEnvParserPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), context.envParserPath);
+		const runtime = require_openapi.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
 		const content = `import { AWSLambdaQueue } from '@geekmidas/constructs/aws';
 import { ${exportName} } from '${importPath}';
-import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
+${runtime.imports}
+${runtime.bindings}
 
 const adapter = new AWSLambdaQueue(envParser, ${exportName});
 
@@ -787,7 +949,7 @@ var SubscriberGenerator = class extends require_discover.ConstructGenerator {
 		const subscribersDir = (0, node_path.join)(outputDir, "subscribers");
 		await (0, node_fs_promises.mkdir)(subscribersDir, { recursive: true });
 		for (const { key, construct, path } of constructs) {
-			const handlerFile = await this.generateSubscriberHandler(subscribersDir, path.relative, key, construct, context);
+			const handlerFile = await this.generateSubscriberHandler(subscribersDir, path.relative, key, construct, context, construct.owner);
 			subscriberInfos.push({
 				name: key,
 				handler: (0, node_path.relative)(process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
@@ -805,15 +967,16 @@ var SubscriberGenerator = class extends require_discover.ConstructGenerator {
 		}
 		return subscriberInfos;
 	}
-	async generateSubscriberHandler(outputDir, sourceFile, exportName, _subscriber, context) {
+	async generateSubscriberHandler(outputDir, sourceFile, exportName, _subscriber, context, owner) {
 		const handlerFileName = `${exportName}.ts`;
 		const handlerPath = (0, node_path.join)(outputDir, handlerFileName);
 		const relativePath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile);
 		const importPath = relativePath.replace(/\.ts$/, ".js");
-		const relativeEnvParserPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), context.envParserPath);
+		const runtime = require_openapi.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
 		const content = `import { AWSLambdaSubscriber } from '@geekmidas/constructs/aws';
 import { ${exportName} } from '${importPath}';
-import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
+${runtime.imports}
+${runtime.bindings}
 
 const adapter = new AWSLambdaSubscriber(envParser, ${exportName});
 
@@ -1196,13 +1359,7 @@ async function devCommand(options) {
 	}
 	const resolved = resolveProviders(config, { provider: "server" });
 	logger$9.log("🚀 Starting development server...");
-	logger$9.log(`Loading routes from: ${config.routes}`);
-	if (config.functions) logger$9.log(`Loading functions from: ${config.functions}`);
-	if (config.crons) logger$9.log(`Loading crons from: ${config.crons}`);
-	if (config.subscribers) logger$9.log(`Loading subscribers from: ${config.subscribers}`);
-	logger$9.log(`Using envParser: ${config.envParser}`);
-	const { path: envParserPath, importPattern: envParserImportPattern } = require_config.parseModuleConfig(config.envParser, "envParser");
-	const { path: loggerPath, importPattern: loggerImportPattern } = require_config.parseModuleConfig(config.logger, "logger");
+	logger$9.log(`Loading constructs from: ${config.constructs}`);
 	const telescope = normalizeTelescopeConfig(config.telescope);
 	if (telescope) logger$9.log(`🔭 Telescope enabled at ${telescope.path}`);
 	const studio = normalizeStudioConfig(config.studio);
@@ -1213,21 +1370,17 @@ async function devCommand(options) {
 	const enableOpenApi = openApiConfig.enabled || resolved.enableOpenApi;
 	if (enableOpenApi) logger$9.log(`📄 OpenAPI output: ${require_openapi.OPENAPI_OUTPUT_PATH}`);
 	const buildContext = {
-		envParserPath,
-		envParserImportPattern,
-		loggerPath,
-		loggerImportPattern,
 		telescope,
 		studio,
 		hooks
 	};
 	await buildServer(config, buildContext, resolved.providers[0], enableOpenApi, appRoot);
-	if (enableOpenApi) await require_openapi.generateOpenApi(config);
+	if (enableOpenApi) await require_openapi.generateOpenApiFrom(config.constructs, { openapi: config.openapi });
 	const runtime = config.runtime ?? "node";
 	let secretsJsonPath;
-	const appSecrets = await require_credentials$1.loadSecretsForApp(secretsRoot, workspaceAppName);
+	const appSecrets = await require_credentials$1.loadSecretsForApp(secretsRoot, config.stages.local, workspaceAppName);
 	if (workspace && require_credentials$1.usesConstructs(workspace)) {
-		const reconciled = await require_credentials$1.reconcileWorkspace(workspace, { stage: "development" });
+		const reconciled = await require_credentials$1.reconcileWorkspace(workspace, { stage: workspace.stages.local });
 		if (reconciled.changed && reconciled.plan.containers.length > 0) {
 			logger$9.log(`🐳 Services: ${reconciled.plan.containers.join(", ")}`);
 			for (const [container, address] of Object.entries(reconciled.addresses)) logger$9.log(`   ${container}: ${address}`);
@@ -1255,19 +1408,9 @@ async function devCommand(options) {
 	}
 	const devServer = new DevServer(resolved.providers[0], options.port ?? workspaceAppPort ?? 3e3, options.portExplicit ?? false, enableOpenApi, telescope, studio, runtime, appRoot, secretsJsonPath);
 	await devServer.start();
-	const envParserFile = config.envParser.split("#")[0] ?? config.envParser;
-	const loggerFile = config.logger.split("#")[0] ?? config.logger;
 	const hooksFileParts = config.hooks?.server?.split("#");
 	const hooksFile = hooksFileParts?.[0];
-	const watchPatterns = [
-		config.routes,
-		...config.functions ? [config.functions] : [],
-		...config.crons ? [config.crons] : [],
-		...config.subscribers ? [config.subscribers] : [],
-		envParserFile.endsWith(".ts") ? envParserFile : `${envParserFile}.ts`,
-		loggerFile.endsWith(".ts") ? loggerFile : `${loggerFile}.ts`,
-		...hooksFile ? [hooksFile.endsWith(".ts") ? hooksFile : `${hooksFile}.ts`] : []
-	].flat().filter((p) => typeof p === "string");
+	const watchPatterns = [config.constructs, ...hooksFile ? [hooksFile.endsWith(".ts") ? hooksFile : `${hooksFile}.ts`] : []].flat().filter((p) => typeof p === "string");
 	const normalizedPatterns = watchPatterns.map((p) => p.startsWith("./") ? p.slice(2) : p);
 	logger$9.log(`👀 Watching for changes in: ${normalizedPatterns.join(", ")}`);
 	const resolvedFiles = await (0, fast_glob.default)(normalizedPatterns, {
@@ -1300,7 +1443,8 @@ async function devCommand(options) {
 			try {
 				logger$9.log("🔄 Rebuilding...");
 				await buildServer(config, buildContext, resolved.providers[0], enableOpenApi, appRoot, true);
-				if (enableOpenApi) await require_openapi.generateOpenApi(config, {
+				if (enableOpenApi) await require_openapi.generateOpenApiFrom(config.constructs, {
+					openapi: config.openapi,
 					silent: true,
 					bustCache: true
 				});
@@ -1518,15 +1662,15 @@ async function validateFrontendApps(workspace) {
 */
 async function loadDevSecrets(workspace) {
 	if (!workspace.secrets.enabled) return {};
-	const stages = ["dev", "development"];
-	for (const stage of stages) if (require_storage.secretsExist(stage, workspace.root)) {
+	const stage = workspace.stages.local;
+	if (require_storage.secretsExist(stage, workspace.root)) {
 		const secrets = await require_storage.readStageSecrets(stage, workspace.root);
 		if (secrets) {
 			logger$9.log(`🔐 Loading secrets from stage: ${stage}`);
 			return require_storage.toEmbeddableSecrets(secrets);
 		}
 	}
-	logger$9.warn("⚠️  Secrets enabled but no dev/development secrets found. Run \"gkm setup\" to initialize your development environment");
+	logger$9.warn(`⚠️  Secrets enabled but no "${stage}" secrets found. Run "gkm setup" to initialize the local stage`);
 	return {};
 }
 /**
@@ -1570,7 +1714,7 @@ async function workspaceDevCommand(workspace, options) {
 	const rawSecrets = await loadDevSecrets(workspace);
 	let secretsEnv;
 	if (require_credentials$1.usesConstructs(workspace)) {
-		const reconciled = await require_credentials$1.reconcileWorkspace(workspace, { stage: "development" });
+		const reconciled = await require_credentials$1.reconcileWorkspace(workspace, { stage: workspace.stages.local });
 		if (reconciled.changed && reconciled.plan.containers.length > 0) {
 			logger$9.log(`🐳 Services: ${reconciled.plan.containers.join(", ")}`);
 			for (const [container, address] of Object.entries(reconciled.addresses)) logger$9.log(`   ${container}: ${address}`);
@@ -1714,7 +1858,7 @@ async function buildServer(config, context, provider, enableOpenApi, appRoot = p
 	const queueGenerator = new QueueGenerator();
 	const topicGenerator = new TopicGenerator();
 	const [allEndpoints, allFunctions, allCrons, allSubscribers, allQueues, allTopics] = await Promise.all([
-		endpointGenerator.load(config.routes, appRoot, bustCache),
+		endpointGenerator.load(config.constructs, appRoot, bustCache),
 		config.functions ? functionGenerator.load(config.functions, appRoot, bustCache) : [],
 		config.crons ? cronGenerator.load(config.crons, appRoot, bustCache) : [],
 		config.subscribers ? subscriberGenerator.load(config.subscribers, appRoot, bustCache) : [],
@@ -2302,18 +2446,36 @@ export default app;
 `);
 }
 const logger$7 = console;
+/**
+* What a build run at the workspace root reads.
+*
+* One backend app there, and it is that app's config, so its own `openapi`
+* and `telescope` settings still apply. Otherwise it is the workspace's: every
+* construct glob, and the backends they resolve to.
+*/
+function rootGkmConfig(workspace) {
+	const backends = Object.entries(workspace.apps).filter(([, app]) => app.type === "backend");
+	const only = backends.length === 1 ? backends[0] : void 0;
+	const own = only ? require_workspace.getAppGkmConfig(workspace, only[0]) : void 0;
+	return own ?? {
+		services: workspace.services,
+		stages: workspace.stages,
+		constructs: require_workspace.allConstructGlobs(workspace)
+	};
+}
 async function buildCommand(options) {
 	const loadedConfig = await require_config.loadWorkspaceConfig();
 	if (loadedConfig.type === "workspace") {
 		const cwd = (0, node_path.resolve)(process.cwd());
-		const workspaceRoot = (0, node_path.resolve)(loadedConfig.workspace.root);
-		const isAtWorkspaceRoot = cwd === workspaceRoot;
-		if (isAtWorkspaceRoot) {
+		const workspaceRoot$1 = (0, node_path.resolve)(loadedConfig.workspace.root);
+		const isAtWorkspaceRoot = cwd === workspaceRoot$1;
+		const someAppIsElsewhere = Object.values(loadedConfig.workspace.apps).some((app) => (0, node_path.resolve)(workspaceRoot$1, app.path) !== workspaceRoot$1);
+		if (isAtWorkspaceRoot && someAppIsElsewhere) {
 			logger$7.log("📦 Detected workspace configuration");
 			return workspaceBuildCommand(loadedConfig.workspace, options);
 		}
 	}
-	const config = loadedConfig.type === "workspace" ? (await require_config.loadAppConfig()).gkmConfig : await require_config.loadConfig();
+	const config = loadedConfig.type !== "workspace" ? await require_config.loadConfig() : (0, node_path.resolve)(process.cwd()) === (0, node_path.resolve)(loadedConfig.workspace.root) ? rootGkmConfig(loadedConfig.workspace) : (await require_config.loadAppConfig()).gkmConfig;
 	const resolved = resolveProviders(config, options);
 	const backendConfig = config.services ?? loadedConfig.workspace?.services;
 	const cacheBackend = require_credentials$1.cacheBackendOf(backendConfig?.cache);
@@ -2321,13 +2483,7 @@ async function buildCommand(options) {
 	const production = normalizeProductionConfig(options.production ?? false, productionConfigFromGkm);
 	if (production) logger$7.log(`🏭 Building for PRODUCTION`);
 	logger$7.log(`Building with providers: ${resolved.providers.join(", ")}`);
-	logger$7.log(`Loading routes from: ${formatRoutes(config.routes)}`);
-	if (config.functions) logger$7.log(`Loading functions from: ${formatRoutes(config.functions)}`);
-	if (config.crons) logger$7.log(`Loading crons from: ${formatRoutes(config.crons)}`);
-	if (config.subscribers) logger$7.log(`Loading subscribers from: ${formatRoutes(config.subscribers)}`);
-	logger$7.log(`Using envParser: ${config.envParser}`);
-	const { path: envParserPath, importPattern: envParserImportPattern } = require_config.parseModuleConfig(config.envParser, "envParser");
-	const { path: loggerPath, importPattern: loggerImportPattern } = require_config.parseModuleConfig(config.logger, "logger");
+	logger$7.log(`Loading constructs from: ${formatRoutes(config.constructs)}`);
 	const telescope = production ? void 0 : normalizeTelescopeConfig(config.telescope);
 	if (telescope) logger$7.log(`🔭 Telescope enabled at ${telescope.path}`);
 	const studio = production ? void 0 : normalizeStudioConfig(config.studio);
@@ -2352,10 +2508,23 @@ async function buildCommand(options) {
 		sources: constructSources
 	}) : {};
 	const surfaces = Object.values(declared).filter((d) => d.kind === "rest-api");
-	const primary = surfaces.find((d) => d.endpoints.length === 0) ?? surfaces[0];
+	const workspaceRoot = loadedConfig.workspace.root;
+	const served = surfaces.find((d) => (0, node_path.resolve)(workspaceRoot, d.path) === (0, node_path.resolve)(process.cwd()));
+	const primary = served ?? surfaces.find((d) => d.endpoints.length === 0) ?? surfaces[0];
 	const browsable = Object.entries(declared).find(([, d]) => d.kind === "database");
 	const browsableSource = browsable ? constructSources[browsable[0]] : void 0;
+	const owners = {};
+	for (const [id, declaration] of Object.entries(declared)) {
+		if (declaration.kind !== "rest-api" && declaration.kind !== "worker") continue;
+		const source = constructSources[id];
+		if (!source) continue;
+		owners[id] = {
+			specifier: source.file,
+			exportName: source.exportName
+		};
+	}
 	const buildContext = {
+		owners,
 		...primary ? { surface: {
 			id: primary.id,
 			trustedOriginsKey: (0, __geekmidas_manifest.provideKey)(primary.id, "trustedOrigins"),
@@ -2365,10 +2534,6 @@ async function buildCommand(options) {
 				exportName: constructSources[primary.id].exportName
 			} } : {}
 		} } : {},
-		envParserPath,
-		envParserImportPattern,
-		loggerPath,
-		loggerImportPattern,
 		telescope,
 		studio: studio && browsableSource ? {
 			...studio,
@@ -2395,14 +2560,16 @@ async function buildCommand(options) {
 	const subscriberGenerator = new SubscriberGenerator();
 	const queueGenerator = new QueueGenerator();
 	const topicGenerator = new TopicGenerator();
-	const [allEndpoints, allFunctions, allCrons, allSubscribers, allQueues, allTopics] = await Promise.all([
-		endpointGenerator.load(config.routes),
-		config.functions ? functionGenerator.load(config.functions) : [],
-		config.crons ? cronGenerator.load(config.crons) : [],
-		config.subscribers ? subscriberGenerator.load(config.subscribers) : [],
-		config.queues ? queueGenerator.load(config.queues) : [],
-		config.topics ? topicGenerator.load(config.topics) : []
+	const code = constructGlobs$1;
+	const [loadedEndpoints, allFunctions, allCrons, allSubscribers, allQueues, allTopics] = await Promise.all([
+		endpointGenerator.load(code),
+		functionGenerator.load(code),
+		cronGenerator.load(code),
+		subscriberGenerator.load(code),
+		queueGenerator.load(code),
+		topicGenerator.load(code)
 	]);
+	const allEndpoints = primary ? loadedEndpoints.filter(({ construct }) => !construct.surface || construct.surface.id === primary.id) : loadedEndpoints;
 	logger$7.log(`Found ${allEndpoints.length} endpoints`);
 	logger$7.log(`Found ${allFunctions.length} functions`);
 	logger$7.log(`Found ${allCrons.length} crons`);
@@ -2410,7 +2577,7 @@ async function buildCommand(options) {
 	logger$7.log(`Found ${allQueues.length} queues`);
 	logger$7.log(`Found ${allTopics.length} topics`);
 	if (allEndpoints.length === 0 && allFunctions.length === 0 && allCrons.length === 0 && allSubscribers.length === 0 && allQueues.length === 0 && allTopics.length === 0) {
-		const selfServing = Object.entries(declared).find(([id, d]) => d.kind === "rest-api" && d.endpoints.length > 0 && constructSources[id] !== void 0 && (0, node_path.resolve)(loadedConfig.workspace.root, require_config.resolveAppSpec(id, d.app ?? {}, loadedConfig.workspace.root, "rest-api").path) === (0, node_path.resolve)(process.cwd()));
+		const selfServing = served && served.endpoints.length > 0 && constructSources[served.id] !== void 0 ? [served.id, served] : void 0;
 		if (selfServing) {
 			const [id] = selfServing;
 			await writeSurfaceEntry((0, node_path.join)(process.cwd(), ".gkm", "server"), constructSources[id]);
@@ -2427,7 +2594,7 @@ async function buildCommand(options) {
 		const providerResult = await buildForProvider(provider, buildContext, rootOutputDir, endpointGenerator, functionGenerator, cronGenerator, subscriberGenerator, queueGenerator, topicGenerator, allEndpoints, allFunctions, allCrons, allSubscribers, allQueues, allTopics, resolved.enableOpenApi, options.skipBundle ?? false, options.stage);
 		if (providerResult.masterKey) result = providerResult;
 	}
-	await require_openapi.generateOpenApi(config, { bustCache: true });
+	await require_openapi.generateOpenApi(allEndpoints.map(({ construct }) => construct), { openapi: config.openapi });
 	return result;
 }
 async function buildForProvider(provider, context, rootOutputDir, endpointGenerator, functionGenerator, cronGenerator, subscriberGenerator, queueGenerator, topicGenerator, endpoints, functions, crons, subscribers, queues, topics, enableOpenApi, skipBundle, stage) {
@@ -2681,7 +2848,6 @@ async function workspaceBuildCommand(workspace, options) {
 			});
 		}
 		logger$7.log(`\n✅ Workspace build complete!`);
-		await require_openapi.openapiCommand({ cwd: workspace.root });
 		logger$7.log(`\n📋 Build Summary:`);
 		for (const result of results) {
 			const icon = result.type === "backend" ? "⚙️" : result.type === "mobile" ? "📱" : "🌐";
@@ -3051,7 +3217,7 @@ function minioCompose(options) {
 	return [
 		"services:",
 		`  ${service}:`,
-		"    image: quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z",
+		"    image: pgsty/minio:RELEASE.2026-08-04T00-00-00Z",
 		`    command: server /data --console-address ":9001"`,
 		"    environment:",
 		`      MINIO_ROOT_USER: ${user}`,
@@ -3870,7 +4036,7 @@ const DEFAULT_SERVICE_IMAGES = {
 	postgres: "postgres",
 	redis: "redis",
 	rabbitmq: "rabbitmq",
-	minio: "quay.io/minio/minio",
+	minio: "pgsty/minio",
 	mailpit: "axllent/mailpit",
 	localstack: "floci/floci"
 };
@@ -3879,7 +4045,7 @@ const DEFAULT_SERVICE_VERSIONS = {
 	postgres: `${__geekmidas_manifest.DEFAULT_POSTGRES_VERSION}-alpine`,
 	redis: "7-alpine",
 	rabbitmq: "3-management-alpine",
-	minio: "RELEASE.2025-09-07T16-13-09Z",
+	minio: "RELEASE.2026-08-04T00-00-00Z",
 	mailpit: "latest",
 	localstack: "latest"
 };
@@ -4331,7 +4497,7 @@ function getInfraServiceImage(serviceName$1, pin) {
 	const defaults = {
 		postgres: "postgres:18-alpine",
 		redis: "redis:7-alpine",
-		minio: "quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z"
+		minio: "pgsty/minio:RELEASE.2026-08-04T00-00-00Z"
 	};
 	return pin || defaults[serviceName$1];
 }
@@ -5531,7 +5697,7 @@ async function workspaceDockerCommand(workspace, options) {
 	logger$5.log(`\n   Generated: .dockerignore (workspace root)`);
 	const dockerCompose = generateWorkspaceCompose(workspace, {
 		registry: options.registry,
-		containers: await require_credentials$1.derivedContainers(workspace, "development")
+		containers: await require_credentials$1.derivedContainers(workspace, workspace.stages.local)
 	});
 	const composePath = (0, node_path.join)(dockerDir, "docker-compose.yml");
 	await (0, node_fs_promises.writeFile)(composePath, dockerCompose);
@@ -6977,6 +7143,7 @@ async function workspaceDeployCommand(configured, options) {
 */
 async function deployCommand(options) {
 	const loadedConfig = await require_config.loadWorkspaceConfig();
+	require_workspace.assertDeployedStage(loadedConfig.workspace.stages, options.stage);
 	return workspaceDeployCommand(loadedConfig.workspace, options);
 }
 
@@ -7342,6 +7509,501 @@ function printStateDetails(state) {
 	}
 }
 
+//#endregion
+//#region src/init/constructs.ts
+/** The glob every generated config points at. One glob, every kind. */
+const CONSTRUCTS_GLOB = "./src/constructs/**/*.ts";
+/**
+* Where a workspace keeps its constructs: at the root, beside the apps that
+* share them, rather than inside any one of them.
+*/
+const WORKSPACE_CONSTRUCTS_GLOB = "./constructs/**/*.ts";
+/**
+* Where each routes structure puts an app's handlers, relative to the app.
+*
+* `.ts` only, never `.tsx`: a TanStack site keeps its own `src/routes/`, and
+* this glob must not import a frontend's route components.
+*/
+function routesGlob(structure) {
+	switch (structure) {
+		case "centralized-endpoints": return "./src/endpoints/**/*.ts";
+		case "centralized-routes": return "./src/routes/**/*.ts";
+		case "domain-based": return "./src/**/routes/*.ts";
+	}
+}
+/**
+* Plain ids — `Database`, not `Beetlefit`.
+*
+* The workspace `name` already scopes every physical name
+* (`production-beetlefit-database`), so an id that carried the project too
+* would say it twice: `production-beetlefit-beetlefit-cache`. Within a
+* workspace the constructs are declared once, at its root, so there is no
+* second app's `Database` to collide with.
+*/
+function scaffolded(id) {
+	return {
+		id,
+		service: (0, __geekmidas_manifest.serviceKey)(id),
+		urlKey: (0, __geekmidas_manifest.provideKey)(id, "url")
+	};
+}
+/** The database a project declares. */
+function databaseFor() {
+	return {
+		...scaffolded("Database"),
+		ownerUrlKey: (0, __geekmidas_manifest.provideKey)("Database", "ownerUrl")
+	};
+}
+/** The bucket a project declares. */
+const storageFor = () => scaffolded("Uploads");
+/** The mail sender a project declares. */
+const emailFor = () => scaffolded("Mail");
+/** The cache a project declares. */
+const cacheFor = () => scaffolded("Cache");
+/**
+* The files a project's declared database needs.
+*
+* Shared by every template, so a worker and an API declare the same database
+* the same way — and so the schema type, the migration, and the id the test
+* setup reads all come from one place.
+*/
+function databaseFiles() {
+	const db = databaseFor();
+	return [{
+		path: "src/constructs/database.ts",
+		content: `import { KyselyDatabase } from '@geekmidas/constructs/database/kysely';
+import type { Generated } from 'kysely';
+
+/** Your database schema. Add tables here. */
+export interface Database {
+  users: {
+    id: Generated<string>;
+    name: string;
+    email: string;
+    created_at: Generated<Date>;
+  };
+}
+
+/**
+ * The app's database, declared once.
+ *
+ * The container, the database inside it, its roles and schema, and
+ * \`${db.urlKey}\` all derive from this line — \`gkm dev\` reconciles them
+ * before the server starts, which is why nothing lists \`postgres\` anywhere.
+ *
+ * Both type arguments or neither: TypeScript has no partial type-argument
+ * inference, so passing only \`Database\` would leave the name at \`string\`
+ * and widen the service key away from \`${db.service}\`.
+ */
+export const database = new KyselyDatabase<Database, '${db.id}'>('${db.id}');
+`
+	}, usersMigration()];
+}
+/**
+* The table the scaffolded endpoints and factories expect.
+*
+* Its own function because a workspace's API needs it without the database
+* construct beside it — that one lives at the workspace root.
+*/
+function usersMigration() {
+	return {
+		path: "src/db/migrations/001_create_users.ts",
+		content: `import type { Kysely } from 'kysely';
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+  await db.schema
+    .createTable('users')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(db.fn('gen_random_uuid')),
+    )
+    .addColumn('name', 'varchar(255)', (col) => col.notNull())
+    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(db.fn('now')),
+    )
+    .execute();
+
+  await db.schema
+    .createIndex('users_email_idx')
+    .on('users')
+    .column('email')
+    .execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+  await db.schema.dropTable('users').execute();
+}
+`
+	};
+}
+/**
+* What a workspace's `constructs` glob reaches: the root constructs, and the
+* handlers of every app laid out the way `init` was told.
+*
+* Every app in `appsDir` (`apps/*`) rather than the API's own directory.
+* Endpoints are split by the surface they were built from, so naming one app
+* here would only decide which apps' endpoints are silently never loaded.
+*/
+function workspaceConstructsGlobs(structure, appsDir) {
+	return [WORKSPACE_CONSTRUCTS_GLOB, `./${appsDir}/*/${routesGlob(structure).replace(/^\.\//, "")}`];
+}
+
+//#endregion
+//#region src/init/generators/agents.ts
+/**
+* `AGENTS.md` and `CLAUDE.md` for a scaffolded project.
+*
+* A generated project is the first thing an agent sees, and without this it
+* sees only the output: a `gkm.config.ts` naming three keys, a `constructs/`
+* directory, and a build step that reads both. None of that says what the
+* shape *is*, so an agent reconstructs it from the framework it recognises —
+* and writes an Express app beside a `RestApi`, or restates in config what a
+* construct already declared, which is the exact mistake v10 exists to make
+* impossible.
+*
+* Instructions live in `AGENTS.md` because that is the file every tool reads.
+* `CLAUDE.md` points at it rather than copying it: two files saying the same
+* thing is two files to keep in step, and the copy that drifts is always the
+* one nobody opened.
+*
+* Content is derived from the same `TemplateOptions` the rest of the scaffold
+* is built from, so a project with no database gets no database section, and a
+* worker gets no endpoint guide. A guide that documents what was not generated
+* teaches the reader to distrust it.
+*/
+function generateAgentFiles(options, template) {
+	return [{
+		path: "AGENTS.md",
+		content: agentsContent(options, template)
+	}, {
+		path: "CLAUDE.md",
+		content: claudeContent()
+	}];
+}
+/**
+* The pointer.
+*
+* Deliberately short and deliberately not a summary — a summary is a second
+* copy of the conventions that ages independently of the first.
+*/
+function claudeContent() {
+	return `# CLAUDE.md
+
+The conventions for this project live in [AGENTS.md](./AGENTS.md).
+
+Read that file before writing code here. It is the single copy, kept that way
+on purpose: anything repeated here would be a second thing to keep in step, and
+the stale one is always the copy nobody opened.
+`;
+}
+function agentsContent(options, template) {
+	const { name: name$1, monorepo, database, telescope, studio, packageManager, services } = options;
+	const constructsGlob = monorepo ? WORKSPACE_CONSTRUCTS_GLOB : CONSTRUCTS_GLOB;
+	const isWorker = template.name === "worker";
+	const isServerless = template.name === "serverless";
+	const run = packageManager === "npm" ? "npx" : `${packageManager} exec`;
+	const sections = [];
+	sections.push(`# Agent conventions — ${name$1}
+
+Rules for anyone, human or agent, writing code in this project. Built with
+[\`@geekmidas/toolbox\`](https://github.com/geekmidas/toolbox).
+
+Read this before adding a file. Most of what follows exists because the obvious
+approach from another framework produces something that compiles, runs, and is
+wrong in a way nothing catches.`);
+	sections.push(`## The one idea
+
+**Constructs declare; config does not restate.**
+
+A construct — a \`RestApi\`, a database, a bucket, a topic — is the single
+declaration of a thing. The build reads those declarations and derives
+everything downstream from them: which containers exist, which apps get built,
+what the OpenAPI spec says, which env vars a process needs.
+
+\`gkm.config.ts\` holds only what no construct can answer:
+
+\`\`\`typescript
+export default defineWorkspace({
+  name: '${name$1}',
+  stages: { local: 'dev', deployed: ['staging', 'prod'], protected: ['prod'] },
+  constructs: '${constructsGlob}',
+  secrets: { enabled: true },
+});
+\`\`\`
+
+If you find yourself adding a key to config that names something already
+declared in a construct — a path, a port, a route, a container — stop. That is
+the drift this design removes. The second copy is the one that goes wrong.`);
+	sections.push(`## Layout
+
+\`\`\`
+${layoutBlock(options, template)}
+\`\`\`
+
+Handlers are found by **one glob**, and what kind a file exports is decided by
+the value it exports, not by the directory it sits in.`);
+	sections.push(`## Commands
+
+\`\`\`bash
+${run} gkm dev            # dev server, hot reload, services up, secrets injected
+${run} gkm build          # production build
+${run} gkm test           # tests, with secrets injected
+${run} gkm exec -- <cmd>  # run any command with secrets injected
+${run} gkm openapi        # regenerate the OpenAPI spec
+\`\`\`
+
+Secrets are encrypted at rest and injected at run time:
+
+\`\`\`bash
+${run} gkm secrets:set DATABASE_URL postgres://...
+${run} gkm secrets:show
+\`\`\`
+
+**Never run a tool that needs project env vars directly.** It will see an empty
+environment and fail in a way that looks like a config bug. Go through
+\`gkm exec --\`, which is what injects them.`);
+	if (!isWorker) sections.push(endpointSection(options));
+	if (isWorker || isServerless || services.events) sections.push(backgroundSection(template));
+	if (database) sections.push(databaseSection());
+	sections.push(`## Environment
+
+Environment is parsed once, through \`envkit\`, and never read from
+\`process.env\` directly:
+
+\`\`\`typescript
+import { EnvironmentParser } from '@geekmidas/envkit';
+import { Credentials } from '@geekmidas/envkit/credentials';
+
+export const envParser = new EnvironmentParser({
+  ...process.env,
+  ...Credentials,
+});
+
+export const config = envParser
+  .create((get) => ({
+    port: get('PORT').string().transform(Number).default(3000),
+  }))
+  .parse();
+\`\`\`
+
+\`Credentials\` is what \`gkm dev\` and \`gkm exec\` inject. A bare
+\`process.env.FOO\` bypasses both the decryption and the validation, so it reads
+as \`undefined\` in exactly the environments that matter.`);
+	sections.push(conventionsSection());
+	sections.push(testingSection(database));
+	if (telescope || studio) {
+		const tools = [telescope && "**Telescope** — request and exception monitoring", studio && "**Studio** — dev dashboard and database browser"].filter(Boolean);
+		sections.push(`## Dev tools
+
+${tools.map((t) => `- ${t}`).join("\n")}
+
+Both are derived from declared constructs. Neither needs wiring up by hand.`);
+	}
+	sections.push(`## Before you say it works
+
+\`\`\`bash
+${run} gkm build
+\`\`\`
+
+A build is the only thing that proves the manifest still resolves. Code that
+typechecks can still declare two constructs with one id, or a handler no glob
+reaches — and neither shows up until something reads the graph.`);
+	return `${sections.join("\n\n")}\n`;
+}
+function layoutBlock(options, template) {
+	const { monorepo, apiPath, database } = options;
+	const isWorker = template.name === "worker";
+	if (monorepo) return `constructs/          # every construct: the surface, the database, topics
+${apiPath}/            # the API app
+gkm.config.ts        # name, constructs glob, secrets`;
+	const lines = ["src/constructs/      # the surface, and anything it declares", "src/config/          # env parser, logger"];
+	if (!isWorker) lines.push("src/endpoints/       # HTTP handlers");
+	if (isWorker) {
+		lines.push("src/crons/           # scheduled work");
+		lines.push("src/subscribers/     # topic consumers");
+	}
+	if (database) lines.push("src/db/              # migrations, schema");
+	lines.push("gkm.config.ts        # name, constructs glob, secrets");
+	return lines.join("\n");
+}
+function endpointSection(options) {
+	const { database } = options;
+	return `## Adding an endpoint
+
+An endpoint is built **from the surface that serves it**. That is where its
+logger, environment parser and authorizers come from, so none of them is passed
+per endpoint:
+
+\`\`\`typescript
+import { z } from 'zod';
+import { router } from '../constructs/router.ts';
+
+export const createUser = router
+  .post('/users')
+  .body(z.object({ name: z.string(), email: z.email() }))
+  .output(z.object({ id: z.uuid() }))
+  .handle(async ({ body, logger${database ? ", services" : ""} }) => {
+    logger.info({ name: body.name }, 'creating user');
+${database ? `    const user = await services.database
+      .insertInto('users')
+      .values({ name: body.name, email: body.email })
+      .returningAll()
+      .executeTakeFirstOrThrow();
+
+    return { id: user.id };` : `    return { id: crypto.randomUUID() };`}
+  });
+\`\`\`
+
+**Export it.** An endpoint that is never exported is never found — the glob
+loads the module and filters by value, so a handler assigned to a local
+\`const\` simply does not exist as far as the build is concerned.
+
+**Do not write an HTTP server.** No \`express()\`, no \`new Hono()\`, no
+\`app.listen\`. The entry is generated from the surface; a hand-written server
+beside it is a second app that shadows the real one.
+
+### Branching the factory
+
+Share what a *group* of endpoints needs by branching once, in its own file:
+
+\`\`\`typescript
+export const router = api.endpoints${database ? ".database(database)" : ""};
+export const sessionRouter = router.session(/* … */);
+\`\`\`
+
+Branch for a group, never for a single endpoint — a one-endpoint branch is
+indirection with nothing on the other side of it.`;
+}
+function backgroundSection(template) {
+	const isWorker = template.name === "worker";
+	return `## Background work
+
+Crons, subscribers and functions are declared the same way endpoints are: as
+exported values the build discovers.
+
+\`\`\`typescript
+// a scheduled job, built from the worker that runs it
+import { worker } from '../constructs/worker.ts';
+
+export const cleanup = worker
+  .cron('rate(1 day)')
+  .handle(async ({ logger }) => {
+    logger.info('cleaning up');
+  });
+\`\`\`
+
+\`\`\`typescript
+// a topic subscriber
+import { userEvents } from '../constructs/topics.ts';
+import { worker } from '../constructs/worker.ts';
+
+export const onUserCreated = worker
+  .topic(userEvents)
+  .subscribe(['user.created'])
+  .handle(async ({ events, logger }) => {
+    logger.info({ count: events.length }, 'handling user events');
+  });
+\`\`\`
+
+Handlers receive a **batch**, not one event. Both transports deliver in
+batches, so a per-event round trip is a round trip per event for no reason.
+
+${isWorker ? `This project is background work and nothing else — there is no HTTP surface
+to add routes to.` : `Declaring a topic is what makes the broker exist. Nothing lists it in config.`}`;
+}
+function databaseSection() {
+	return `## Database
+
+The database is a **construct**, not a hand-rolled service. Declaring it is what
+makes a Postgres exist locally and a database exist on deploy — nothing names
+\`postgres\` in config.
+
+An endpoint reaches it by declaring the dependency, and gets it typed:
+
+\`\`\`typescript
+export const listUsers = router
+  .get('/users')
+  .output(z.array(z.object({ id: z.uuid() })))
+  .handle(async ({ services }) => {
+    return services.database.selectFrom('users').selectAll().execute();
+  });
+\`\`\`
+
+Queries go through Kysely. Never open your own connection pool — the one the
+construct provides is the one that gets credentials, pooling and shutdown.`;
+}
+function conventionsSection() {
+	return `## Conventions
+
+**Zod formats are top-level schemas.**
+
+\`\`\`typescript
+// yes
+z.email()
+z.url()
+z.uuid()
+
+// no
+z.string().email()
+z.string().url()
+\`\`\`
+
+Zod 4 made each format a schema in its own right. The chained form still runs,
+but it types as a \`ZodString\` carrying a check, so it cannot be composed or
+narrowed — and it emits different JSON Schema, which means a published API
+contract would depend on which spelling someone reached for.
+
+\`envkit\` is not affected: \`get('ADMIN_EMAIL').string().email()\` is its own
+builder, not Zod's. Leave it alone.
+
+**Style.** Two-space indent, single quotes, semicolons, trailing commas, 80
+columns. \`import type\` for type-only imports. Run the formatter rather than
+matching it by hand.
+
+**Construct ids are unique.** Two constructs sharing an id fails discovery for
+the whole project, not just the second one.`;
+}
+function testingSection(database) {
+	return `## Testing
+
+**Integration over unit.** Prefer the real dependency to a mock — a real
+database, a real cache. Mocks are for things you genuinely cannot run:
+the filesystem, the clock, external HTTP (use MSW for that).
+
+**Test behaviour, not implementation.** Assert what the code did, not which
+functions it called on the way.
+
+\`\`\`bash
+${database ? "gkm test       # starts services, injects secrets, then runs vitest" : "gkm test"}
+\`\`\`
+
+Run tests through \`gkm test\`, not \`vitest\` directly${database ? " — it is what starts the database and injects the secrets the suite needs" : ""}.`;
+}
+
+//#endregion
+//#region src/init/dependencies.ts
+/**
+* Third-party ranges a scaffold installs beside the `@geekmidas` packages.
+*
+* Held to the peer ranges those packages declare, in one place, because a
+* template that pinned its own copy drifted below them: `kysely ~0.28` against
+* a `~0.29.6` peer is two copies of Kysely and a `Kysely<DB>` from one that is
+* not assignable to the other's.
+*
+* Hand-maintained, unlike `versions.ts`, which `sync-versions` rewrites whole.
+*/
+const DEPENDENCY_VERSIONS = {
+	"@tanstack/react-query": "~5.80.0",
+	"better-auth": "~1.7.5",
+	hono: "~4.13.8",
+	kysely: "~0.29.6",
+	"kysely-ctl": "~0.21.0",
+	pg: "~8.23.0",
+	pino: "~10.3.1",
+	sst: "~4.17.1",
+	zod: "~4.6.5"
+};
+
 //#endregion
 //#region src/init/versions.ts
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
@@ -7364,26 +8026,26 @@ const CLI_VERSION = `~${pkg.version}`;
 * Run: pnpm --filter @geekmidas/cli sync-versions
 */
 const GEEKMIDAS_VERSIONS = {
-	"@geekmidas/audit": "~10.0.0-alpha.0",
-	"@geekmidas/auth": "~10.0.0-alpha.0",
-	"@geekmidas/cache": "~10.0.0-alpha.0",
-	"@geekmidas/client": "~10.0.0-alpha.0",
-	"@geekmidas/cloud": "~10.0.0-alpha.0",
-	"@geekmidas/constructs": "~10.0.0-alpha.0",
-	"@geekmidas/db": "~10.0.0-alpha.0",
-	"@geekmidas/emailkit": "~10.0.0-alpha.0",
-	"@geekmidas/envkit": "~10.0.0-alpha.0",
-	"@geekmidas/errors": "~10.0.0-alpha.0",
-	"@geekmidas/events": "~10.0.0-alpha.0",
-	"@geekmidas/logger": "~10.0.0-alpha.0",
-	"@geekmidas/manifest": "~10.0.0-alpha.0",
-	"@geekmidas/rate-limit": "~10.0.0-alpha.0",
-	"@geekmidas/schema": "~10.0.0-alpha.0",
-	"@geekmidas/services": "~10.0.0-alpha.0",
-	"@geekmidas/storage": "~10.0.0-alpha.0",
-	"@geekmidas/studio": "~10.0.0-alpha.0",
-	"@geekmidas/telescope": "~10.0.0-alpha.0",
-	"@geekmidas/testkit": "~10.0.0-alpha.0",
+	"@geekmidas/audit": "~10.0.0-alpha.10",
+	"@geekmidas/auth": "~10.0.0-alpha.10",
+	"@geekmidas/cache": "~10.0.0-alpha.10",
+	"@geekmidas/client": "~10.0.0-alpha.10",
+	"@geekmidas/cloud": "~10.0.0-alpha.10",
+	"@geekmidas/constructs": "~10.0.0-alpha.10",
+	"@geekmidas/db": "~10.0.0-alpha.10",
+	"@geekmidas/emailkit": "~10.0.0-alpha.10",
+	"@geekmidas/envkit": "~10.0.0-alpha.10",
+	"@geekmidas/errors": "~10.0.0-alpha.10",
+	"@geekmidas/events": "~10.0.0-alpha.10",
+	"@geekmidas/logger": "~10.0.0-alpha.10",
+	"@geekmidas/manifest": "~10.0.0-alpha.10",
+	"@geekmidas/rate-limit": "~10.0.0-alpha.10",
+	"@geekmidas/schema": "~10.0.0-alpha.10",
+	"@geekmidas/services": "~10.0.0-alpha.10",
+	"@geekmidas/storage": "~10.0.0-alpha.10",
+	"@geekmidas/studio": "~10.0.0-alpha.10",
+	"@geekmidas/telescope": "~10.0.0-alpha.10",
+	"@geekmidas/testkit": "~10.0.0-alpha.10",
 	"@geekmidas/cli": CLI_VERSION
 };
 
@@ -7403,27 +8065,28 @@ function generateAuthAppFiles(options) {
 		private: true,
 		type: "module",
 		scripts: {
-			dev: "gkm dev --entry ./src/index.ts",
-			build: "tsc",
-			start: "node dist/index.js",
-			typecheck: "tsc --noEmit",
+			dev: "gkm dev",
+			build: "gkm build",
 			"db:migrate": "gkm exec -- npx @better-auth/cli migrate",
 			"db:generate": "gkm exec -- npx @better-auth/cli generate"
 		},
 		dependencies: {
 			[modelsPackage]: "workspace:*",
+			"@geekmidas/auth": GEEKMIDAS_VERSIONS["@geekmidas/auth"],
+			"@geekmidas/constructs": GEEKMIDAS_VERSIONS["@geekmidas/constructs"],
+			"@geekmidas/db": GEEKMIDAS_VERSIONS["@geekmidas/db"],
 			"@geekmidas/envkit": GEEKMIDAS_VERSIONS["@geekmidas/envkit"],
 			"@geekmidas/logger": GEEKMIDAS_VERSIONS["@geekmidas/logger"],
-			"@hono/node-server": "~1.13.0",
-			"better-auth": "~1.2.0",
-			hono: "~4.8.0",
-			kysely: "~0.27.0",
-			pg: "~8.13.0"
+			"@hono/node-server": "~1.14.1",
+			"better-auth": DEPENDENCY_VERSIONS["better-auth"],
+			hono: DEPENDENCY_VERSIONS.hono,
+			kysely: DEPENDENCY_VERSIONS.kysely,
+			pg: DEPENDENCY_VERSIONS.pg
 		},
 		devDependencies: {
 			"@geekmidas/cli": GEEKMIDAS_VERSIONS["@geekmidas/cli"],
 			"@types/node": "~22.0.0",
-			"@types/pg": "~8.11.0",
+			"@types/pg": "~8.23.1",
 			tsx: "~4.20.0",
 			typescript: "~5.8.2"
 		}
@@ -7464,117 +8127,27 @@ dist/
 }
 
 //#endregion
-//#region src/init/constructs.ts
-/** The glob every generated config points at. One glob, every kind. */
-const CONSTRUCTS_GLOB = "./src/constructs/**/*.ts";
+//#region src/init/generators/stages.ts
+/** The `stages` block a generated gkm.config.ts declares, indented two spaces. */
+function stagesBlock(stages) {
+	const list = (names) => `[${names.map((name$1) => `'${name$1}'`).join(", ")}]`;
+	return `
+  // Named by this project and read by every command: \`gkm dev\`, \`exec\` and
+  // \`test\` run as \`local\`, and \`gkm deploy --stage\` accepts only \`deployed\`.
+  stages: {
+    local: '${stages.local}',
+    deployed: ${list(stages.deployed)},${stages.protected?.length ? `
+    // Retained and protected on removal.
+    protected: ${list(stages.protected)},` : ""}
+  },`;
+}
 /**
-* The database a project named `name` declares.
-*
-* Named after the project rather than `Db`, so two apps in one workspace can
-* declare one each without colliding on an id or on an env key.
+* The `STAGE` the scaffolded env config parses: one of the declared stages,
+* defaulting to the local one.
 */
-function databaseFor(name$1) {
-	const id = (0, __geekmidas_manifest.canonicalId)(name$1);
-	return {
-		id,
-		service: (0, __geekmidas_manifest.serviceKey)(id),
-		urlKey: (0, __geekmidas_manifest.provideKey)(id, "url"),
-		ownerUrlKey: (0, __geekmidas_manifest.provideKey)(id, "ownerUrl")
-	};
-}
-/** The bucket a project named `name` declares. */
-function storageFor(name$1) {
-	const id = (0, __geekmidas_manifest.canonicalId)(`${name$1}-uploads`);
-	return {
-		id,
-		service: (0, __geekmidas_manifest.serviceKey)(id),
-		urlKey: (0, __geekmidas_manifest.provideKey)(id, "url")
-	};
-}
-/** The mail sender a project named `name` declares. */
-function emailFor(name$1) {
-	const id = (0, __geekmidas_manifest.canonicalId)(`${name$1}-mail`);
-	return {
-		id,
-		service: (0, __geekmidas_manifest.serviceKey)(id),
-		urlKey: (0, __geekmidas_manifest.provideKey)(id, "url")
-	};
-}
-/** The cache a project named `name` declares. */
-function cacheFor(name$1) {
-	const id = (0, __geekmidas_manifest.canonicalId)(`${name$1}-cache`);
-	return {
-		id,
-		service: (0, __geekmidas_manifest.serviceKey)(id),
-		urlKey: (0, __geekmidas_manifest.provideKey)(id, "url")
-	};
-}
-/**
-* The files a project's declared database needs.
-*
-* Shared by every template, so a worker and an API declare the same database
-* the same way — and so the schema type, the migration, and the id the test
-* setup reads all come from one place.
-*/
-function databaseFiles(name$1) {
-	const db = databaseFor(name$1);
-	return [{
-		path: "src/constructs/database.ts",
-		content: `import { KyselyDatabase } from '@geekmidas/constructs/database/kysely';
-import type { Generated } from 'kysely';
-
-/** Your database schema. Add tables here. */
-export interface Database {
-  users: {
-    id: Generated<string>;
-    name: string;
-    email: string;
-    created_at: Generated<Date>;
-  };
-}
-
-/**
- * The app's database, declared once.
- *
- * The container, the database inside it, its roles and schema, and
- * \`${db.urlKey}\` all derive from this line — \`gkm dev\` reconciles them
- * before the server starts, which is why nothing lists \`postgres\` anywhere.
- *
- * Both type arguments or neither: TypeScript has no partial type-argument
- * inference, so passing only \`Database\` would leave the name at \`string\`
- * and widen the service key away from \`${db.service}\`.
- */
-export const database = new KyselyDatabase<Database, '${db.id}'>('${db.id}');
-`
-	}, {
-		path: "src/db/migrations/001_create_users.ts",
-		content: `import type { Kysely } from 'kysely';
-
-export async function up(db: Kysely<unknown>): Promise<void> {
-  await db.schema
-    .createTable('users')
-    .addColumn('id', 'uuid', (col) =>
-      col.primaryKey().defaultTo(db.fn('gen_random_uuid')),
-    )
-    .addColumn('name', 'varchar(255)', (col) => col.notNull())
-    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
-    .addColumn('created_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(db.fn('now')),
-    )
-    .execute();
-
-  await db.schema
-    .createIndex('users_email_idx')
-    .on('users')
-    .column('email')
-    .execute();
-}
-
-export async function down(db: Kysely<unknown>): Promise<void> {
-  await db.schema.dropTable('users').execute();
-}
-`
-	}];
+function stageEnv(stages) {
+	const names = [stages.local, ...stages.deployed].map((name$1) => `'${name$1}'`).join(", ");
+	return `get('STAGE').enum([${names}]).default('${stages.local}')`;
 }
 
 //#endregion
@@ -7601,13 +8174,7 @@ function generateConfigFiles(options, template) {
 	const isServerless = template.name === "serverless";
 	const hasWorker = template.name === "worker";
 	const isFullstack = options.template === "fullstack";
-	const getRoutesGlob = () => {
-		switch (routesStructure) {
-			case "centralized-endpoints": return "./src/endpoints/**/*.ts";
-			case "centralized-routes": return "./src/routes/**/*.ts";
-			case "domain-based": return "./src/**/routes/*.ts";
-		}
-	};
+	const getRoutesGlob = () => routesGlob(routesStructure);
 	if (isFullstack) return generateSingleAppConfigFiles(options, template, {
 		telescope,
 		studio,
@@ -7618,7 +8185,7 @@ function generateConfigFiles(options, template) {
 	});
 	let gkmConfig = `import { defineConfig } from '@geekmidas/cli/config';
 
-export default defineConfig({${options.monorepo ? "" : `
+export default defineConfig({${stagesBlock(options.stages)}${options.monorepo ? "" : `
   // One glob, every kind. What reconcile reads to derive the containers this
   // app needs: a declared database is why a Postgres exists at all, so nothing
   // lists \`postgres\` anywhere.
@@ -7660,21 +8227,7 @@ export default defineConfig({${options.monorepo ? "" : `
 	gkmConfig += `
 });
 `;
-	const tsConfig = options.monorepo ? {
-		extends: "../../tsconfig.json",
-		compilerOptions: {
-			noEmit: true,
-			allowImportingTsExtensions: true,
-			baseUrl: ".",
-			paths: {
-				"~/*": ["./src/*"],
-				[`@${options.name}/constructs/*`]: ["../../constructs/*"],
-				[`@${options.name}/*`]: ["../../packages/*/src"]
-			}
-		},
-		include: ["src/**/*.ts"],
-		exclude: ["node_modules", "dist"]
-	} : {
+	const tsConfig = options.monorepo ? workspaceApiTsConfig(options.name) : {
 		compilerOptions: {
 			target: "ES2022",
 			module: "NodeNext",
@@ -7686,7 +8239,9 @@ export default defineConfig({${options.monorepo ? "" : `
 			forceConsistentCasingInFileNames: true,
 			resolveJsonModule: true,
 			noEmit: true,
-			allowImportingTsExtensions: true
+			allowImportingTsExtensions: true,
+			baseUrl: ".",
+			paths: { "~/*": ["./src/*"] }
 		},
 		include: ["src/**/*.ts"],
 		exclude: ["node_modules", "dist"]
@@ -7712,7 +8267,7 @@ export default defineConfig({${options.monorepo ? "" : `
 			clientKind: "git",
 			useIgnoreFile: true
 		},
-		organizeImports: { enabled: true },
+		assist: { actions: { source: { organizeImports: "on" } } },
 		formatter: {
 			enabled: true,
 			indentStyle: "space",
@@ -7736,11 +8291,13 @@ export default defineConfig({${options.monorepo ? "" : `
 				style: { noNonNullAssertion: "off" }
 			}
 		},
-		files: { ignore: [
-			"node_modules",
-			"dist",
-			".gkm",
-			"coverage"
+		css: { parser: { tailwindDirectives: true } },
+		files: { includes: [
+			"**",
+			"!**/node_modules",
+			"!**/dist",
+			"!**/.gkm",
+			"!**/coverage"
 		] }
 	};
 	const turboConfig = {
@@ -7794,8 +8351,16 @@ export default defineConfig({${options.monorepo ? "" : `
 	});
 	return files$1;
 }
-function generateSingleAppConfigFiles(options, _template, _helpers) {
-	const tsConfig = {
+/**
+* The tsconfig of an API inside a workspace.
+*
+* One definition for both ways of getting one — the fullstack template and
+* `--monorepo` — because the two copies had drifted: only one of them mapped
+* the root constructs, so in the other `@<name>/constructs/api.ts` fell through
+* to the `packages/` mapping and nothing could load the surface.
+*/
+function workspaceApiTsConfig(name$1) {
+	return {
 		extends: "../../tsconfig.json",
 		compilerOptions: {
 			noEmit: true,
@@ -7803,12 +8368,16 @@ function generateSingleAppConfigFiles(options, _template, _helpers) {
 			baseUrl: ".",
 			paths: {
 				"~/*": ["./src/*"],
-				[`@${options.name}/*`]: ["../../packages/*/src"]
+				[`@${name$1}/constructs/*`]: ["../../constructs/*"],
+				[`@${name$1}/*`]: ["../../packages/*/src"]
 			}
 		},
 		include: ["src/**/*.ts"],
 		exclude: ["node_modules", "dist"]
 	};
+}
+function generateSingleAppConfigFiles(options, _template, _helpers) {
+	const tsConfig = workspaceApiTsConfig(options.name);
 	const files$1 = [{
 		path: "tsconfig.json",
 		content: `${JSON.stringify(tsConfig, null, 2)}\n`
@@ -7944,7 +8513,7 @@ function generateDockerFiles(options, template, dbApps) {
       MP_SMTP_AUTH: \${SMTP_USER:-${options.name}}:\${SMTP_PASS:-${options.name}}`);
 	if (options.services?.storage) {
 		services.push(`  minio:
-    image: quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z
+    image: pgsty/minio:RELEASE.2026-08-04T00-00-00Z
     container_name: ${options.name}-minio
     restart: unless-stopped
     entrypoint: sh
@@ -8185,6 +8754,327 @@ coverage/
 	return files$1;
 }
 
+//#endregion
+//#region src/init/generators/github.ts
+/** How each package manager is set up, installs, and runs a script. */
+const TOOLING = {
+	pnpm: {
+		setup: `      - uses: pnpm/action-setup@v4
+PNPM_VERSION
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+`,
+		install: "pnpm install --frozen-lockfile",
+		run: "pnpm run",
+		exec: "pnpm exec"
+	},
+	npm: {
+		setup: `      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+`,
+		install: "npm ci",
+		run: "npm run",
+		exec: "npx --no-install"
+	},
+	yarn: {
+		setup: `      - run: corepack enable
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
+`,
+		install: "yarn install --immutable",
+		run: "yarn run",
+		exec: "yarn"
+	},
+	bun: {
+		setup: `      - uses: oven-sh/setup-bun@v2
+`,
+		install: "bun install --frozen-lockfile",
+		run: "bun run",
+		exec: "bunx"
+	}
+};
+/** The package manager's steps, with pnpm pinned where package.json does not. */
+function tooling(options) {
+	const pm = TOOLING[options.packageManager];
+	return {
+		...pm,
+		setup: pm.setup.replace("PNPM_VERSION\n", options.monorepo ? "" : "        with:\n          version: 10\n")
+	};
+}
+function ci(options) {
+	const pm = tooling(options);
+	return `name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+${pm.setup}
+      - name: Install
+        run: ${pm.install}
+
+      - name: Build
+        run: ${pm.run} build
+
+      - name: Lint
+        run: ${pm.run} lint
+
+      - name: Typecheck
+        run: ${pm.run} typecheck
+
+      # \`gkm test\` starts the containers the declared constructs need (the
+      # runner has Docker) and, with GKM_AUTO_SETUP, generates throwaway
+      # secrets for the test stage — there is no key to share with CI.
+      - name: Test
+        timeout-minutes: 15
+        run: ${pm.run} test:once
+        env:
+          CI: true
+          GKM_AUTO_SETUP: 1
+`;
+}
+const releaseDrafterWorkflow = `name: Release Drafter
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, reopened, synchronize, edited]
+
+permissions:
+  contents: read
+
+jobs:
+  draft:
+    name: Update release draft
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        with:
+          commitish: main
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+`;
+function releaseDrafterConfig(options) {
+	const mobile = options.frontendFramework === "expo" ? `  - title: "📱 Mobile"
+    labels: [mobile, ios, android]
+    collapse-after: 10
+` : "";
+	return `name-template: "v$RESOLVED_VERSION"
+tag-template: "v$RESOLVED_VERSION"
+
+categories:
+  - title: "✨ New Features"
+    labels: [feature, enhancement]
+    collapse-after: 10
+  - title: "🐛 Bug Fixes"
+    labels: [bug, fix]
+    collapse-after: 10
+${mobile}  - title: "🏗 Infrastructure"
+    labels: [infrastructure, ci]
+    collapse-after: 10
+  - title: "📦 Dependencies"
+    labels: [dependencies]
+    collapse-after: 5
+  - title: "🔒 Security"
+    labels: [security]
+  - title: "🧹 Maintenance"
+    labels: [chore, refactor]
+    collapse-after: 5
+
+change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
+change-title-escapes: '\\<*_&'
+
+version-resolver:
+  major:
+    labels: [breaking-change, major]
+  minor:
+    labels: [feature, enhancement, minor]
+  patch:
+    labels: [bug, fix, chore, dependencies, patch]
+  default: patch
+
+# Labelled from the conventional-commit prefix of the pull request title.
+autolabeler:
+  - label: feature
+    title: ["/^feat/i"]
+  - label: bug
+    title: ["/^fix/i"]
+  - label: chore
+    title: ["/^chore/i", "/^refactor/i"]
+  - label: dependencies
+    title: ["/^deps/i", "/^chore\\\\(deps\\\\)/i"]
+  - label: ci
+    title: ["/^ci/i"]
+  - label: breaking-change
+    title: ["/^\\\\w+(\\\\(.+\\\\))?!:/"]
+
+template: |
+  ## What's Changed
+
+  $CHANGES
+
+  **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION
+`;
+}
+function deploy(options) {
+	const pm = tooling(options);
+	const sst = options.deployTarget === "sst";
+	const credentials = sst ? `
+      # An IAM role GitHub assumes through OIDC — no long-lived AWS keys. Set
+      # AWS_ROLE_ARN as a variable on each environment.
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${options.region}
+` : "";
+	const deployEnv = sst ? "" : `
+          DOKPLOY_API_TOKEN: \${{ secrets.DOKPLOY_API_TOKEN }}
+          DOKPLOY_ENDPOINT: \${{ vars.DOKPLOY_ENDPOINT }}`;
+	return `name: Deploy
+
+# Which stages exist, and which are protected, is read from \`stages\` in
+# gkm.config.ts — nothing here names one:
+#
+#   push to main       every deployed stage that is not protected
+#   release published  the protected stages (publish the drafted release)
+#   run workflow       the one stage you name
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      stage:
+        description: A deployed stage from gkm.config.ts
+        required: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  stages:
+    name: Pick stages
+    runs-on: ubuntu-latest
+    outputs:
+      stages: \${{ steps.pick.outputs.stages }}
+    steps:
+      - uses: actions/checkout@v4
+
+${pm.setup}
+      - name: Install
+        run: ${pm.install}
+
+      - name: Read stages from gkm.config.ts
+        id: pick
+        run: |
+          ${pm.exec} tsx -e "
+            import config from './gkm.config.ts';
+            const { deployed, protected: kept = [] } = config.stages;
+            const event = process.env.EVENT;
+            if (event === 'workflow_dispatch' && !deployed.includes(process.env.STAGE)) {
+              console.error('Not a deployed stage: ' + process.env.STAGE + ' (deployed: ' + deployed.join(', ') + ')');
+              process.exit(1);
+            }
+            const stages =
+              event === 'workflow_dispatch' ? [process.env.STAGE]
+              : event === 'release' ? kept
+              : deployed.filter((stage) => !kept.includes(stage));
+            console.log('stages=' + JSON.stringify(stages));
+          " >> "$GITHUB_OUTPUT"
+        env:
+          EVENT: \${{ github.event_name }}
+          STAGE: \${{ inputs.stage }}
+
+  deploy:
+    name: Deploy \${{ matrix.stage }}
+    needs: stages
+    if: needs.stages.outputs.stages != '[]'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        stage: \${{ fromJSON(needs.stages.outputs.stages) }}
+    # One GitHub environment per stage: its secrets and variables, and any
+    # approval rule you put on a protected one.
+    environment: \${{ matrix.stage }}
+    concurrency:
+      group: deploy-\${{ matrix.stage }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+
+${pm.setup}
+      - name: Install
+        run: ${pm.install}
+
+      # The stage's secrets are committed encrypted; the key never is. Each
+      # environment holds its own as GKM_SECRETS_KEY.
+      # Owner-only, as the CLI writes its own keys. The stage reaches the shell
+      # as a variable, never pasted into the script: on a manual run it is
+      # whatever was typed.
+      - name: Stage secrets key
+        run: |
+          mkdir -p -m 700 ~/.gkm/${options.name}
+          (umask 077 && printf '%s' "$KEY" > ~/.gkm/${options.name}/"$STAGE".key)
+        env:
+          KEY: \${{ secrets.GKM_SECRETS_KEY }}
+          STAGE: \${{ matrix.stage }}
+${credentials}
+      - name: Deploy
+        run: ${pm.run} "deploy:$STAGE"
+        env:
+          STAGE: \${{ matrix.stage }}${deployEnv}
+`;
+}
+function generateGithubFiles(options) {
+	const files$1 = [
+		{
+			path: ".github/workflows/ci.yml",
+			content: ci(options)
+		},
+		{
+			path: ".github/workflows/release-drafter.yml",
+			content: releaseDrafterWorkflow
+		},
+		{
+			path: ".github/release-drafter.yml",
+			content: releaseDrafterConfig(options)
+		}
+	];
+	if (options.monorepo && options.deployTarget !== "none") files$1.push({
+		path: ".github/workflows/deploy.yml",
+		content: deploy(options)
+	});
+	return files$1;
+}
+
 //#endregion
 //#region src/init/generators/mobile-expo.ts
 /**
@@ -8217,12 +9107,12 @@ function generateExpoAppFiles(options) {
 		dependencies: {
 			[apiPackage]: "workspace:*",
 			[modelsPackage]: "workspace:*",
-			"@better-auth/expo": "~1.2.0",
+			"@better-auth/expo": DEPENDENCY_VERSIONS["better-auth"],
 			"@geekmidas/client": GEEKMIDAS_VERSIONS["@geekmidas/client"],
 			"@geekmidas/envkit": GEEKMIDAS_VERSIONS["@geekmidas/envkit"],
 			"@react-navigation/native": "^7.1.0",
-			"@tanstack/react-query": "~5.80.0",
-			"better-auth": "~1.2.0",
+			"@tanstack/react-query": DEPENDENCY_VERSIONS["@tanstack/react-query"],
+			"better-auth": DEPENDENCY_VERSIONS["better-auth"],
 			expo: "~55.0.0",
 			"expo-constants": "~55.0.0",
 			"expo-dev-client": "~55.0.0",
@@ -8358,7 +9248,7 @@ module.exports = withNativeWind(config, { input: './global.css' });
 				"@/*": ["./*"],
 				[modelsPackage]: ["../../packages/models/src"],
 				[`${modelsPackage}/*`]: ["../../packages/models/src/*"],
-				[`${apiPackage}/client`]: ["../../apps/api/.gkm/openapi.ts"]
+				[`${apiPackage}/client`]: ["../../apps/api/.gkm/openapi/api.ts"]
 			}
 		},
 		include: [
@@ -8916,14 +9806,142 @@ export type ListUsersResponse = z.infer<typeof ListUsersResponseSchema>;
 	];
 }
 
+//#endregion
+//#region src/init/generators/deploy.ts
+/** One `deploy:<stage>` script per deployed stage. */
+const perStage = (options, command) => Object.fromEntries(options.stages.deployed.map((stage) => [`deploy:${stage}`, command(stage)]));
+function deployPackage(options) {
+	switch (options.deployTarget) {
+		case "dokploy": return {
+			scripts: perStage(options, (stage) => `gkm deploy --provider dokploy --stage ${stage}`),
+			dependencies: {},
+			devDependencies: {}
+		};
+		case "sst": {
+			const v = GEEKMIDAS_VERSIONS;
+			return {
+				scripts: perStage(options, (stage) => `gkm build --provider aws && sst deploy --stage ${stage}`),
+				dependencies: {
+					"@geekmidas/cloud": v["@geekmidas/cloud"],
+					"@geekmidas/db": v["@geekmidas/db"],
+					"@geekmidas/envkit": v["@geekmidas/envkit"],
+					"@geekmidas/events": v["@geekmidas/events"],
+					"@geekmidas/manifest": v["@geekmidas/manifest"],
+					"@geekmidas/storage": v["@geekmidas/storage"],
+					pg: DEPENDENCY_VERSIONS.pg
+				},
+				devDependencies: { sst: DEPENDENCY_VERSIONS.sst }
+			};
+		}
+		default: return {
+			scripts: {},
+			dependencies: {},
+			devDependencies: {}
+		};
+	}
+}
+function generateDeployFiles(options) {
+	if (options.deployTarget !== "sst") return [];
+	if (!options.region) throw new Error("An SST deploy needs a region.");
+	const db = databaseFor();
+	const mail = emailFor();
+	const hasDatabase = options.template === "fullstack" || options.services.db;
+	const inputs = [...hasDatabase ? [`        // RDS needs a network. Created here rather than assumed, because a
+        // VPC with NAT is a monthly cost in an account that may already
+        // have one — replace it with \`sst.aws.Vpc.get(…)\` if so.
+        ${db.id}: { vpc },`] : [], ...options.services.mail ? [`        // Every provider rejects an unverified sender, so there is no
+        // default; the synth stops with \`EmailNeedsSender\` until it is set.
+        ${mail.id}: { from: process.env.MAIL_FROM as string },`] : []];
+	return [{
+		path: "sst.config.ts",
+		content: `/// <reference path="./.sst/platform/config.d.ts" />
+
+/**
+ * ${options.name} on AWS.
+ *
+ * No bucket, cluster, queue or IAM is listed here: they come from the
+ * constructs the application declares, through \`fromManifest\`. What is here
+ * is what varies by stage, and the inputs a declaration cannot carry.
+ *
+ * Deploy with \`pnpm run deploy:<stage>\`, which builds the manifest first.
+ */
+const region = '${options.region}';
+
+/** From \`stages.protected\` in gkm.config.ts. */
+const PROTECTED: string[] = ${JSON.stringify(options.stages.protected ?? []).replace(/"/g, "'")};
+
+export default $config({
+  app(input) {
+    return {
+      name: '${options.name}',
+      // Any other stage is disposable; a protected one's database should not
+      // vanish because somebody removed a stack.
+      removal: PROTECTED.includes(input?.stage) ? 'retain' : 'remove',
+      protect: PROTECTED.includes(input?.stage),
+      home: 'aws',
+      providers: { aws: { region } },
+    };
+  },
+
+  async run() {
+    const { App, fromManifest, Stack } = await import('@geekmidas/cloud/sst');
+    // Written by \`gkm build --provider aws\`. Imported rather than discovered,
+    // so SST's toolchain never evaluates the application's own modules.
+    const { backends, constructs } = await import('./.gkm/manifest/aws.js');
+
+${hasDatabase ? "    const vpc = new sst.aws.Vpc('Vpc', { nat: 'ec2' });\n\n" : ""}    const app = new App({
+      name: $app.name,
+      stage: $app.stage,
+      domain: '',
+      region,
+      hostedZoneId: '',
+    });
+
+    return fromManifest(
+      new Stack(app, '${(0, __geekmidas_manifest.canonicalId)(options.name)}'),
+      constructs,
+      {
+${inputs.join("\n")}
+      },
+      backends,
+    );
+  },
+});
+`
+	}];
+}
+
 //#endregion
 //#region src/init/generators/monorepo.ts
 /**
+* What the root `constructs/` folder imports, and the peers each construct
+* needs, for the services this workspace was scaffolded with.
+*/
+function rootConstructDependencies(options) {
+	const v = GEEKMIDAS_VERSIONS;
+	return {
+		"@geekmidas/constructs": v["@geekmidas/constructs"],
+		"@geekmidas/logger": v["@geekmidas/logger"],
+		...options.loggerType === "pino" ? { pino: DEPENDENCY_VERSIONS.pino } : {},
+		"@geekmidas/telescope": v["@geekmidas/telescope"],
+		"@geekmidas/auth": v["@geekmidas/auth"],
+		"better-auth": DEPENDENCY_VERSIONS["better-auth"],
+		"@geekmidas/db": v["@geekmidas/db"],
+		kysely: DEPENDENCY_VERSIONS.kysely,
+		pg: DEPENDENCY_VERSIONS.pg,
+		...options.services.storage ? { "@geekmidas/storage": v["@geekmidas/storage"] } : {},
+		...options.services.mail ? { "@geekmidas/emailkit": v["@geekmidas/emailkit"] } : {},
+		...options.services.cache ? { "@geekmidas/cache": v["@geekmidas/cache"] } : {}
+	};
+}
+/**
 * Generate monorepo root files (pnpm-workspace.yaml, root package.json, etc.)
 */
 function generateMonorepoFiles(options, _template) {
 	if (!options.monorepo) return [];
 	const isFullstack = options.template === "fullstack";
+	const deploy$1 = deployPackage(options);
+	const isSst = options.deployTarget === "sst";
 	const rootPackageJson = {
 		name: options.name,
 		version: "0.0.1",
@@ -8940,9 +9958,13 @@ function generateMonorepoFiles(options, _template) {
 			fmt: "biome format . --write",
 			"fmt:check": "biome format .",
 			...isFullstack ? { storybook: "pnpm --filter ./packages/ui storybook" } : {},
-			...options.deployTarget === "dokploy" ? { deploy: "gkm deploy --provider dokploy --stage production" } : {}
+			...deploy$1.scripts
+		},
+		dependencies: {
+			zod: DEPENDENCY_VERSIONS.zod,
+			...isFullstack ? rootConstructDependencies(options) : {},
+			...deploy$1.dependencies
 		},
-		dependencies: { zod: "~4.1.0" },
 		devDependencies: {
 			"@biomejs/biome": "~2.3.0",
 			"@geekmidas/cli": GEEKMIDAS_VERSIONS["@geekmidas/cli"],
@@ -8950,7 +9972,8 @@ function generateMonorepoFiles(options, _template) {
 			tsx: "~4.20.0",
 			turbo: "~2.3.0",
 			typescript: "~5.8.2",
-			vitest: "~4.0.0"
+			vitest: "~4.0.0",
+			...deploy$1.devDependencies
 		}
 	};
 	const apiPathParts = options.apiPath.split("/");
@@ -8966,7 +9989,7 @@ function generateMonorepoFiles(options, _template) {
 			clientKind: "git",
 			useIgnoreFile: true
 		},
-		organizeImports: { enabled: true },
+		assist: { actions: { source: { organizeImports: "on" } } },
 		formatter: {
 			enabled: true,
 			indentStyle: "space",
@@ -8990,11 +10013,14 @@ function generateMonorepoFiles(options, _template) {
 				style: { noNonNullAssertion: "off" }
 			}
 		},
-		files: { ignore: [
-			"node_modules",
-			"dist",
-			".gkm",
-			"coverage"
+		css: { parser: { tailwindDirectives: true } },
+		files: { includes: [
+			"**",
+			"!**/node_modules",
+			"!**/dist",
+			"!**/.gkm",
+			"!**/coverage",
+			...isSst ? ["!**/.sst", "!sst-env.d.ts"] : []
 		] }
 	};
 	const turboConfig = {
@@ -9060,12 +10086,14 @@ coverage/
 
 # Turbo
 .turbo/
-`;
+${isSst ? "\n# SST\n.sst/\n" : ""}`;
 	const tsConfig = {
 		compilerOptions: {
 			...isFullstack ? {
 				baseUrl: ".",
-				paths: { [`@${options.name}/constructs/*`]: ["./constructs/*"] }
+				paths: { [`@${options.name}/constructs/*`]: ["./constructs/*"] },
+				allowImportingTsExtensions: true,
+				noEmit: true
 			} : {},
 			target: "ES2022",
 			module: "NodeNext",
@@ -9077,16 +10105,21 @@ coverage/
 			forceConsistentCasingInFileNames: true,
 			resolveJsonModule: true
 		},
-		exclude: ["node_modules", "dist"]
+		exclude: [
+			"node_modules",
+			"dist",
+			...isSst ? ["sst.config.ts", ".sst"] : []
+		]
 	};
 	const vitestConfig = `import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    globals: true,
-    environment: 'node',
-    include: ['apps/**/*.{test,spec}.ts', 'packages/**/*.{test,spec}.ts'],
-    exclude: ['**/node_modules/**', '**/dist/**'],
+    // Each app and package is its own project, so its own config — an app's
+    // \`globalSetup\`, its path aliases — applies to its own tests.
+    projects: ['apps/*', 'packages/*'],
+    // The shared packages ship without tests of their own.
+    passWithNoTests: true,
     coverage: {
       provider: 'v8',
       reporter: ['text', 'json', 'html'],
@@ -9167,7 +10200,8 @@ export default defineConfig({
 		{
 			path: ".vscode/extensions.json",
 			content: `${JSON.stringify(vscodeExtensions, null, "	")}\n`
-		}
+		},
+		...generateDeployFiles(options)
 	];
 	if (isFullstack) files$1.push({
 		path: "gkm.config.ts",
@@ -9194,12 +10228,17 @@ export default defineWorkspace({
   // The scope every physical name is built from: \`Database\` becomes
   // \`production-${options.name}-database\` on Dokploy and on AWS alike.
   name: '${options.name}',
+${stagesBlock(options.stages)}
 
-  // One glob, every kind. A declared database is why a Postgres exists, a
+  // Every kind, in every app. A declared database is why a Postgres exists, a
   // declared bucket is why MinIO does, a declared topic is why a broker does —
   // none of it listed here. It is also where the apps come from: a
-  // \`StaticSite\` is an app, and so is every \`RestApi\`.
-  constructs: './constructs/**/*.ts',
+  // \`StaticSite\` is an app, and so is every \`RestApi\`. And it finds each
+  // app's endpoints, crons and subscribers: an endpoint belongs to the surface
+  // it was built from, not to the directory it sits in.
+  constructs: [
+${workspaceConstructsGlobs(options.routesStructure, (0, node_path.dirname)(options.apiPath)).map((glob) => `    '${glob}',`).join("\n")}
+  ],
 
   secrets: {
     enabled: true,
@@ -9228,7 +10267,7 @@ export default defineWorkspace({
 function generateRootConstructs(options) {
 	if (!options.monorepo || options.template !== "fullstack") return [];
 	const { name: name$1, services, frontendFramework } = options;
-	const db = databaseFor(name$1);
+	const db = databaseFor();
 	const files$1 = [];
 	files$1.push({
 		path: "constructs/logger.ts",
@@ -9294,6 +10333,7 @@ import { authDb } from './database.ts';
  * origin down.
  */
 export const auth = new BetterAuth('Auth', {
+  path: 'apps/auth',
   database: authDb,
   basePath: '/api/auth',
 });
@@ -9308,25 +10348,22 @@ import { logger } from './logger.ts';
 /**
  * The application's HTTP surface — one RestApi, one container.
  *
- * No \`app\`: \`Api\` means \`apps/api\`, which the id already said. The
- * \`code\` glob is here only because this scaffold puts its endpoints under
- * \`src/\`, where the conventional layout has them at the app root.
+ * \`path\` is where its app lives. Its handlers are found by the workspace's
+ * \`constructs\` glob, and belong to it because they were built from it.
  */
 export const api = new RestApi('Api', {
+  path: '${options.apiPath}',
+
   // Typed out rather than omitted: an API that ships open because a field was
   // left off is the one default worth refusing to have.
   defaultAuthorizer: 'none',
 
   // The actual logger, not a path to one.
   logger,
-
-  app: {
-    code: './src/{endpoints,functions,crons,queues,topics,subscribers}/**/*.ts',
-  },
 }).auth(auth);
 `
 	});
-	const variant = frontendFramework === "tanstack-start" ? "{ variant: 'tanstack' }" : frontendFramework === "expo" ? void 0 : "{ variant: 'next' }";
+	const variant = frontendFramework === "tanstack-start" ? "{ path: 'apps/web', variant: 'tanstack' }" : frontendFramework === "expo" ? void 0 : "{ path: 'apps/web', variant: 'next' }";
 	if (variant !== void 0) files$1.push({
 		path: "constructs/site.ts",
 		content: `import { StaticSite } from '@geekmidas/constructs/site';
@@ -9336,7 +10373,7 @@ import { auth } from './auth.ts';
 /**
  * The frontend — a construct like any other, which is what makes it an app.
  *
- * No \`path\`: \`Web\` means \`apps/web\`. \`.dependsOn()\` is the single fact
+ * \`path\` is where it lives. \`.dependsOn()\` is the single fact
  * behind four things that are hand-maintained otherwise: this site's
  * build-time API URL, the API's CORS origins, the auth server's trusted
  * origins, and which generated client lands here.
@@ -9345,7 +10382,7 @@ export const web = new StaticSite('Web', ${variant}).dependsOn([api, auth]);
 `
 	});
 	if (services.storage) {
-		const bucket = storageFor(name$1);
+		const bucket = storageFor();
 		files$1.push({
 			path: "constructs/storage.ts",
 			content: `import { ObjectStorage } from '@geekmidas/constructs/object-storage';
@@ -9356,7 +10393,7 @@ export const uploads = new ObjectStorage('${bucket.id}');
 		});
 	}
 	if (services.mail) {
-		const mail = emailFor(name$1);
+		const mail = emailFor();
 		files$1.push({
 			path: "constructs/email.ts",
 			content: `import { Email } from '@geekmidas/constructs/email';
@@ -9367,7 +10404,7 @@ export const email = new Email('${mail.id}', { templates: {} });
 		});
 	}
 	if (services.cache) {
-		const kv = cacheFor(name$1);
+		const kv = cacheFor();
 		files$1.push({
 			path: "constructs/cache.ts",
 			content: `import { Cache } from '@geekmidas/constructs/cache';
@@ -9400,9 +10437,9 @@ const apiTemplate = {
 		"@geekmidas/errors": GEEKMIDAS_VERSIONS["@geekmidas/errors"],
 		"@geekmidas/auth": GEEKMIDAS_VERSIONS["@geekmidas/auth"],
 		"@hono/node-server": "~1.14.1",
-		hono: "~4.8.2",
-		pino: "~9.6.0",
-		zod: "~4.1.0"
+		hono: DEPENDENCY_VERSIONS.hono,
+		pino: DEPENDENCY_VERSIONS.pino,
+		zod: DEPENDENCY_VERSIONS.zod
 	},
 	devDependencies: {
 		"@biomejs/biome": "~2.3.0",
@@ -9426,10 +10463,10 @@ const apiTemplate = {
 	},
 	files: (options) => {
 		const { loggerType, routesStructure, monorepo, name: name$1, services } = options;
-		const bucket = storageFor(name$1);
-		const kv = cacheFor(name$1);
-		const db = databaseFor(name$1);
-		const mail = emailFor(name$1);
+		const bucket = storageFor();
+		const kv = cacheFor();
+		const db = databaseFor();
+		const mail = emailFor();
 		const src = (path) => monorepo ? `~/${path}` : `./${path}`;
 		const declares = !monorepo;
 		const loggerContent = `import { createLogger } from '@geekmidas/logger/${loggerType}';
@@ -9463,6 +10500,9 @@ export const logger = createLogger();
 import { logger } from '../config/logger.ts';
 
 export const api = new RestApi('Api', {
+  // The project is the app.
+  path: '.',
+
   // Typed out rather than omitted: an API that ships open because a field was
   // left off is the one default worth refusing to have.
   defaultAuthorizer: 'none',
@@ -9485,7 +10525,7 @@ export const envParser = new EnvironmentParser({ ...process.env, ...Credentials
 export const config = envParser
   .create((get) => ({
     nodeEnv: get('NODE_ENV').enum(['development', 'test', 'production']).default('development'),
-    stage: get('STAGE').enum(['development', 'staging', 'production']).default('development'),
+    stage: ${stageEnv(options.stages)},
   }))
   .parse();
 `
@@ -9637,7 +10677,7 @@ export const authService = {
           headers: { cookie },
         });
         if (!res.ok) return null;
-        return res.json();
+        return (await res.json()) as Session | null;
       },
     };
   },
@@ -9650,7 +10690,6 @@ export const authService = {
 import { api } from '${constructsImport("api")}';${options.database ? `
 import { database } from '${constructsImport("database")}';` : ""}
 import { authService, type Session } from './services/auth.ts';
-import { logger } from './config/logger.ts';
 
 /**
  * The shared endpoint factory — no session required.
@@ -9708,7 +10747,8 @@ import { database } from '${constructsImport("database")}';` : ""}
 export const router = api.endpoints${options.database ? ".database(database)" : ""};
 `
 		});
-		if (options.database && declares) files$1.push(...databaseFiles(name$1));
+		if (options.database && declares) files$1.push(...databaseFiles());
+		else if (options.database) files$1.push(usersMigration());
 		if (services.storage && declares) files$1.push({
 			path: "src/constructs/storage.ts",
 			content: `import { ObjectStorage } from '@geekmidas/constructs/object-storage';
@@ -9858,9 +10898,9 @@ const minimalTemplate = {
 		"@geekmidas/rate-limit": GEEKMIDAS_VERSIONS["@geekmidas/rate-limit"],
 		"@geekmidas/schema": GEEKMIDAS_VERSIONS["@geekmidas/schema"],
 		"@hono/node-server": "~1.14.1",
-		hono: "~4.8.2",
-		pino: "~9.6.0",
-		zod: "~4.1.0"
+		hono: DEPENDENCY_VERSIONS.hono,
+		pino: DEPENDENCY_VERSIONS.pino,
+		zod: DEPENDENCY_VERSIONS.zod
 	},
 	devDependencies: {
 		"@biomejs/biome": "~2.3.0",
@@ -9884,7 +10924,7 @@ const minimalTemplate = {
 	},
 	files: (options) => {
 		const { loggerType, routesStructure, name: name$1 } = options;
-		const db = databaseFor(name$1);
+		const db = databaseFor();
 		const loggerContent = `import { createLogger } from '@geekmidas/logger/${loggerType}';
 
 export const logger = createLogger();
@@ -9904,6 +10944,9 @@ export const logger = createLogger();
 import { logger } from '../config/logger.ts';
 
 export const api = new RestApi('Api', {
+  // The project is the app.
+  path: '.',
+
   // Typed out rather than omitted: an API that ships open because a field was
   // left off is the one default worth refusing to have.
   defaultAuthorizer: 'none',
@@ -9926,7 +10969,7 @@ export const envParser = new EnvironmentParser({ ...process.env, ...Credentials
 export const config = envParser
   .create((get) => ({
     nodeEnv: get('NODE_ENV').enum(['development', 'test', 'production']).default('development'),
-    stage: get('STAGE').enum(['development', 'staging', 'production']).default('development'),
+    stage: ${stageEnv(options.stages)},
   }))
   .parse();
 `
@@ -9953,7 +10996,7 @@ export const healthEndpoint = api
 `
 			}
 		];
-		if (options.database) files$1.push(...databaseFiles(name$1));
+		if (options.database) files$1.push(...databaseFiles());
 		if (options.telescope) files$1.push({
 			path: "src/config/telescope.ts",
 			content: `import { Telescope } from '@geekmidas/telescope';
@@ -10017,8 +11060,8 @@ const serverlessTemplate = {
 		"@geekmidas/rate-limit": GEEKMIDAS_VERSIONS["@geekmidas/rate-limit"],
 		"@geekmidas/schema": GEEKMIDAS_VERSIONS["@geekmidas/schema"],
 		"@hono/node-server": "~1.14.1",
-		hono: "~4.8.2",
-		pino: "~9.6.0"
+		hono: DEPENDENCY_VERSIONS.hono,
+		pino: DEPENDENCY_VERSIONS.pino
 	},
 	devDependencies: {
 		"@biomejs/biome": "~2.3.0",
@@ -10061,6 +11104,9 @@ export const logger = createLogger();
 import { logger } from '../config/logger.ts';
 
 export const api = new RestApi('Api', {
+  // The project is the app.
+  path: '.',
+
   // Typed out rather than omitted: an API that ships open because a field was
   // left off is the one default worth refusing to have.
   defaultAuthorizer: 'none',
@@ -10083,7 +11129,7 @@ export const envParser = new EnvironmentParser({ ...process.env, ...Credentials
 export const config = envParser
   .create((get) => ({
     nodeEnv: get('NODE_ENV').enum(['development', 'test', 'production']).default('development'),
-    stage: get('STAGE').enum(['dev', 'staging', 'prod']).default('dev'),
+    stage: ${stageEnv(options.stages)},
   }))
   .parse();
 `
@@ -10113,19 +11159,27 @@ export const healthEndpoint = api
 			},
 			{
 				path: "src/functions/hello.ts",
-				content: `import { f } from '@geekmidas/constructs/functions';
-import { z } from 'zod';
+				content: `import { z } from 'zod';
+import { worker } from '~/constructs/worker.ts';
 
-export const helloFunction = f
+export const helloFunction = worker
   .input(z.object({ name: z.string() }))
   .output(z.object({ message: z.string() }))
   .handle(async ({ input }) => ({
     message: \`Hello, \${input.name}!\`,
   }));
+`
+			},
+			{
+				path: "src/constructs/worker.ts",
+				content: `import { Worker } from '@geekmidas/constructs/worker';
+import { logger } from '../config/logger.ts';
+
+export const worker = new Worker('Jobs', { logger });
 `
 			}
 		];
-		if (options.database) files$1.push(...databaseFiles(name$1));
+		if (options.database) files$1.push(...databaseFiles());
 		if (options.telescope) files$1.push({
 			path: "src/config/telescope.ts",
 			content: `import { Telescope } from '@geekmidas/telescope';
@@ -10134,7 +11188,7 @@ import { InMemoryStorage } from '@geekmidas/telescope/storage/memory';
 // Note: For production Lambda, consider using a persistent storage
 export const telescope = new Telescope({
   storage: new InMemoryStorage({ maxEntries: 50 }),
-  enabled: process.env.STAGE === 'dev',
+  enabled: process.env.STAGE === '${options.stages.local}',
 });
 `
 		});
@@ -10144,6 +11198,22 @@ export const telescope = new Telescope({
 
 //#endregion
 //#region src/init/templates/worker.ts
+/**
+* A project that is background work and nothing else.
+*
+* It used to scaffold a `RestApi` with no endpoints on it — an HTTP surface
+* declared by a project whose premise is that nothing calls it over HTTP —
+* because a surface was the only construct that made an app exist and the only
+* way to get a logger into the generated runtime. `Worker` is the construct
+* that was missing: it takes no authorizer, publishes no address, and hands out
+* factories already carrying its logger.
+*
+* It scaffolds a cron when the project has a database, and not otherwise. A
+* server fires its own crons, and the schedule lives in Postgres so that
+* running more than one replica still fires each job once — so a worker names
+* the database it keeps schedules in. Without one there is nowhere to keep
+* them, and an example that could not run is worse than none.
+*/
 const workerTemplate = {
 	name: "worker",
 	description: "Background job processing",
@@ -10153,11 +11223,8 @@ const workerTemplate = {
 		"@geekmidas/envkit": GEEKMIDAS_VERSIONS["@geekmidas/envkit"],
 		"@geekmidas/events": GEEKMIDAS_VERSIONS["@geekmidas/events"],
 		"@geekmidas/logger": GEEKMIDAS_VERSIONS["@geekmidas/logger"],
-		"@geekmidas/rate-limit": GEEKMIDAS_VERSIONS["@geekmidas/rate-limit"],
 		"@geekmidas/schema": GEEKMIDAS_VERSIONS["@geekmidas/schema"],
-		"@hono/node-server": "~1.14.1",
-		hono: "~4.8.2",
-		pino: "~9.6.0"
+		pino: DEPENDENCY_VERSIONS.pino
 	},
 	devDependencies: {
 		"@biomejs/biome": "~2.3.0",
@@ -10179,34 +11246,18 @@ const workerTemplate = {
 		"fmt:check": "biome format ."
 	},
 	files: (options) => {
-		const { loggerType, routesStructure, name: name$1 } = options;
+		const { loggerType, name: name$1, database } = options;
 		const loggerContent = `import { createLogger } from '@geekmidas/logger/${loggerType}';
 
 export const logger = createLogger();
 `;
-		const getRoutePath = (file) => {
-			switch (routesStructure) {
-				case "centralized-endpoints": return `src/endpoints/${file}`;
-				case "centralized-routes": return `src/routes/${file}`;
-				case "domain-based": return `src/${file.replace(".ts", "")}/routes/index.ts`;
-			}
-		};
-		const apiImport = routesStructure === "domain-based" ? "../../constructs/api.js" : "../constructs/api.js";
 		const files$1 = [
 			{
-				path: "src/constructs/api.ts",
-				content: `import { RestApi } from '@geekmidas/constructs/rest-api';
-import { logger } from '../config/logger.ts';
+				path: "src/constructs/worker.ts",
+				content: `import { Worker } from '@geekmidas/constructs/worker';
+import { logger } from '../config/logger.ts';${database ? "\nimport { database } from './database.ts';" : ""}
 
-export const api = new RestApi('Api', {
-  // Typed out rather than omitted: an API that ships open because a field was
-  // left off is the one default worth refusing to have.
-  defaultAuthorizer: 'none',
-
-  // The actual logger, not a path to one. Every endpoint built from this
-  // surface runs with it, and so does the generated entry.
-  logger,
-});
+export const worker = new Worker('Jobs', { logger })${database ? ".database(database)" : ""};
 `
 			},
 			{
@@ -10221,7 +11272,7 @@ export const envParser = new EnvironmentParser({ ...process.env, ...Credentials
 export const config = envParser
   .create((get) => ({
     nodeEnv: get('NODE_ENV').enum(['development', 'test', 'production']).default('development'),
-    stage: get('STAGE').enum(['development', 'staging', 'production']).default('development'),
+    stage: ${stageEnv(options.stages)},
   }))
   .parse();
 `
@@ -10230,23 +11281,6 @@ export const config = envParser
 				path: "src/config/logger.ts",
 				content: loggerContent
 			},
-			{
-				path: getRoutePath("health.ts"),
-				content: `import { z } from 'zod';
-import { api } from '${apiImport}';
-
-export const healthEndpoint = api
-  .get('/health')
-  .output(z.object({
-    status: z.string(),
-    timestamp: z.string(),
-  }))
-  .handle(async () => ({
-    status: 'ok',
-    timestamp: new Date().toISOString(),
-  }));
-`
-			},
 			{
 				path: "src/events/types.ts",
 				content: `import type { PublishableMessage } from '@geekmidas/events';
@@ -10288,46 +11322,47 @@ export const eventsPublisherService = {
 			},
 			{
 				path: "src/subscribers/user-events.ts",
-				content: `import { s } from '@geekmidas/constructs/subscribers';
+				content: `import { worker } from '~/constructs/worker.ts';
 import { eventsPublisherService } from '~/events/publisher.ts';
 
-export const userEventsSubscriber = s
+export const userEventsSubscriber = worker
   .publisher(eventsPublisherService)
   .subscribe(['user.created', 'user.updated'])
-  .handle(async ({ event, logger }) => {
-    logger.info({ type: event.type, payload: event.payload }, 'Processing user event');
-
-    switch (event.type) {
-      case 'user.created':
-        // Handle user creation
-        logger.info({ userId: event.payload.userId }, 'New user created');
-        break;
-      case 'user.updated':
-        // Handle user update
-        logger.info({ userId: event.payload.userId }, 'User updated');
-        break;
+  .handle(async ({ events, logger }) => {
+    // A batch, not a single event. Both transports deliver in batches, so
+    // handling them one at a time is a round trip per event for no reason.
+    logger.info({ count: events.length }, 'Processing user events');
+
+    for (const event of events) {
+      switch (event.type) {
+        case 'user.created':
+          logger.info({ userId: event.payload.userId }, 'New user created');
+          break;
+        case 'user.updated':
+          logger.info({ userId: event.payload.userId }, 'User updated');
+          break;
+      }
     }
   });
 `
-			},
-			{
-				path: "src/crons/cleanup.ts",
-				content: `import { cron } from '@geekmidas/constructs/crons';
+			}
+		];
+		if (database) files$1.push({
+			path: "src/crons/cleanup.ts",
+			content: `import { worker } from '~/constructs/worker.ts';
 
-// Run every day at midnight
-export const cleanupCron = cron('0 0 * * *')
+export const cleanup = worker
+  .cron('rate(1 day)')
   .handle(async ({ logger }) => {
-    logger.info('Running cleanup job');
+    logger.info('Running cleanup');
 
-    // Add your cleanup logic here
-    // e.g., delete old sessions, clean up temp files, etc.
+    // Delete old sessions, clear temp files, whatever falls out of date.
 
-    logger.info('Cleanup job completed');
+    logger.info('Cleanup complete');
   });
 `
-			}
-		];
-		if (options.database) files$1.push(...databaseFiles(name$1));
+		});
+		if (options.database) files$1.push(...databaseFiles());
 		if (options.telescope) files$1.push({
 			path: "src/config/telescope.ts",
 			content: `import { Telescope } from '@geekmidas/telescope';
@@ -10348,7 +11383,7 @@ export const telescope = new Telescope({
 /**
 * OpenAPI output path (fixed, not configurable)
 */
-const OPENAPI_OUTPUT_PATH$1 = "./.gkm/openapi.ts";
+const OPENAPI_OUTPUT_PATH$1 = "./.gkm/openapi/api.ts";
 /**
 * Endpoints output path (generated by gkm dev/build)
 */
@@ -10454,15 +11489,23 @@ const packageManagerChoices = [
 /**
 * Deploy target choices for prompts
 */
-const deployTargetChoices = [{
-	title: "Dokploy",
-	value: "dokploy",
-	description: "Deploy to Dokploy (Docker-based hosting)"
-}, {
-	title: "Configure later",
-	value: "none",
-	description: "Skip deployment setup for now"
-}];
+const deployTargetChoices = [
+	{
+		title: "Dokploy",
+		value: "dokploy",
+		description: "Deploy to Dokploy (Docker-based hosting)"
+	},
+	{
+		title: "AWS (SST)",
+		value: "sst",
+		description: "Deploy to your AWS account through SST"
+	},
+	{
+		title: "Configure later",
+		value: "none",
+		description: "Skip deployment setup for now"
+	}
+];
 /**
 * Services choices for multi-select prompt
 */
@@ -10555,12 +11598,12 @@ function generatePackageJson(options, template) {
 	if (declares && services.mail) dependencies$1["@geekmidas/emailkit"] = GEEKMIDAS_VERSIONS["@geekmidas/emailkit"];
 	if (database) {
 		dependencies$1["@geekmidas/db"] = GEEKMIDAS_VERSIONS["@geekmidas/db"];
-		dependencies$1.kysely = "~0.28.2";
-		dependencies$1.pg = "~8.16.0";
-		devDependencies$1["@types/pg"] = "~8.15.0";
+		dependencies$1.kysely = DEPENDENCY_VERSIONS.kysely;
+		dependencies$1.pg = DEPENDENCY_VERSIONS.pg;
+		devDependencies$1["@types/pg"] = "~8.23.1";
 		devDependencies$1["@geekmidas/testkit"] = GEEKMIDAS_VERSIONS["@geekmidas/testkit"];
 		devDependencies$1["@faker-js/faker"] = "~9.8.0";
-		devDependencies$1["kysely-ctl"] = "~0.10.0";
+		devDependencies$1["kysely-ctl"] = DEPENDENCY_VERSIONS["kysely-ctl"];
 		devDependencies$1["vite-tsconfig-paths"] = "~5.1.0";
 	}
 	if (monorepo) {
@@ -10580,6 +11623,8 @@ function generatePackageJson(options, template) {
 		const appName = pathParts[pathParts.length - 1] || "api";
 		packageName = `@${name$1}/${appName}`;
 	}
+	dependencies$1["@geekmidas/client"] = GEEKMIDAS_VERSIONS["@geekmidas/client"];
+	dependencies$1["@tanstack/react-query"] = DEPENDENCY_VERSIONS["@tanstack/react-query"];
 	const packageJson = {
 		name: packageName,
 		version: "0.0.1",
@@ -10617,7 +11662,7 @@ function generateSourceFiles(options, template) {
 */
 function generateTestFiles(options, _template) {
 	if (!options.database) return [];
-	const db = databaseFor(options.name);
+	const db = databaseFor();
 	const declares = !options.monorepo;
 	const schema = declares ? "../src/constructs/database.ts" : "~/services/database.ts";
 	const runtimeUrl = declares ? db.urlKey : "DATABASE_URL";
@@ -10653,14 +11698,16 @@ import pg from 'pg';
 import { wrapVitestKyselyTransaction } from '@geekmidas/testkit/kysely';
 import type { Database } from '${schema}';
 
-const connection = new Kysely<Database>({
+const db = new Kysely<Database>({
   dialect: new PostgresDialect({
     pool: new pg.Pool({ connectionString: process.env.${runtimeUrl} }),
   }),
 });
 
 export const it = wrapVitestKyselyTransaction<Database>(itVitest, {
-  connection,
+  // A function, or a construct: an instance is taken for a construct and has
+  // no service to register.
+  connection: () => db,
 });
 `
 		},
@@ -10745,10 +11792,10 @@ export const usersBuilder = KyselyFactory.createBuilder<Database, 'users'>(
 import { it } from './config.ts';
 
 describe('example', () => {
-  it('should have a working test setup', async ({ db }) => {
-    // db is a transaction-wrapped Kysely instance
-    // All changes are automatically rolled back after the test
-    expect(db).toBeDefined();
+  it('should have a working test setup', async ({ trx }) => {
+    // trx is a Kysely transaction; everything in it is rolled back after the
+    // test
+    expect(trx).toBeDefined();
   });
 });
 `
@@ -11999,8 +13046,8 @@ export const Alert: Story = {
   ),
 };
 `;
-	const componentsUiIndex = `export { Button, type ButtonProps, buttonVariants } from './button.tsx';
-export { Input } from './input.tsx';
+	const componentsUiIndex = `export { Button, type ButtonProps, buttonVariants } from './button/index.tsx';
+export { Input } from './input/index.tsx';
 export {
   Card,
   CardHeader,
@@ -12008,17 +13055,17 @@ export {
   CardTitle,
   CardDescription,
   CardContent,
-} from './card.tsx';
-export { Label } from './label.tsx';
-export { Badge, type BadgeProps, badgeVariants } from './badge.tsx';
-export { Separator } from './separator.tsx';
-export { Tabs, TabsList, TabsTrigger, TabsContent } from './tabs.tsx';
+} from './card/index.tsx';
+export { Label } from './label/index.tsx';
+export { Badge, type BadgeProps, badgeVariants } from './badge/index.tsx';
+export { Separator } from './separator/index.tsx';
+export { Tabs, TabsList, TabsTrigger, TabsContent } from './tabs/index.tsx';
 export {
   Tooltip,
   TooltipTrigger,
   TooltipContent,
   TooltipProvider,
-} from './tooltip.tsx';
+} from './tooltip/index.tsx';
 export {
   Dialog,
   DialogPortal,
@@ -12030,7 +13077,7 @@ export {
   DialogFooter,
   DialogTitle,
   DialogDescription,
-} from './dialog.tsx';
+} from './dialog/index.tsx';
 `;
 	const buttonIndexTsx = buttonTsx;
 	const inputIndexTsx = inputTsx;
@@ -12198,8 +13245,8 @@ function generateWebAppFiles(options) {
 			[uiPackage]: "workspace:*",
 			"@geekmidas/client": GEEKMIDAS_VERSIONS["@geekmidas/client"],
 			"@geekmidas/envkit": GEEKMIDAS_VERSIONS["@geekmidas/envkit"],
-			"@tanstack/react-query": "~5.80.0",
-			"better-auth": "~1.2.0",
+			"@tanstack/react-query": DEPENDENCY_VERSIONS["@tanstack/react-query"],
+			"better-auth": DEPENDENCY_VERSIONS["better-auth"],
 			next: "~16.1.0",
 			react: "~19.2.0",
 			"react-dom": "~19.2.0"
@@ -12255,7 +13302,7 @@ export default nextConfig;
 			baseUrl: ".",
 			paths: {
 				"~/*": ["./src/*", "../../packages/ui/src/*"],
-				[`${apiPackage}/client`]: ["../../apps/api/.gkm/openapi.ts"],
+				[`${apiPackage}/client`]: ["../../apps/api/.gkm/openapi/api.ts"],
 				[`${modelsPackage}`]: ["../../packages/models/src"],
 				[`${modelsPackage}/*`]: ["../../packages/models/src/*"],
 				[`${uiPackage}`]: ["../../packages/ui/src"],
@@ -12268,12 +13315,7 @@ export default nextConfig;
 			"**/*.tsx",
 			".next/types/**/*.ts"
 		],
-		exclude: ["node_modules"],
-		references: [
-			{ path: "../../apps/api" },
-			{ path: "../../packages/ui" },
-			{ path: "../../packages/models" }
-		]
+		exclude: ["node_modules"]
 	};
 	const queryClientTs = `import { QueryClient } from '@tanstack/react-query';
 
@@ -12536,10 +13578,10 @@ function generateTanStackWebFiles(options) {
 			[uiPackage]: "workspace:*",
 			"@geekmidas/client": GEEKMIDAS_VERSIONS["@geekmidas/client"],
 			"@geekmidas/envkit": GEEKMIDAS_VERSIONS["@geekmidas/envkit"],
-			"@tanstack/react-query": "~5.80.0",
+			"@tanstack/react-query": DEPENDENCY_VERSIONS["@tanstack/react-query"],
 			"@tanstack/react-router": "^1.87.0",
 			"@tanstack/react-start": "^1.87.0",
-			"better-auth": "~1.2.0",
+			"better-auth": DEPENDENCY_VERSIONS["better-auth"],
 			react: "~19.2.0",
 			"react-dom": "~19.2.0"
 		},
@@ -12607,7 +13649,7 @@ export default defineConfig({
 				[`${modelsPackage}/*`]: ["../../packages/models/src/*"],
 				[uiPackage]: ["../../packages/ui/src"],
 				[`${uiPackage}/*`]: ["../../packages/ui/src/*"],
-				[`${apiPackage}/client`]: ["../../apps/api/.gkm/openapi.ts"]
+				[`${apiPackage}/client`]: ["../../apps/api/.gkm/openapi/api.ts"]
 			}
 		},
 		include: [
@@ -12897,12 +13939,27 @@ function detectPackageManager(cwd = process.cwd()) {
 	if (userAgent.includes("bun")) return "bun";
 	return "npm";
 }
+/** `gkm init`'s flags, which a name can swallow when a space goes missing. */
+const INIT_FLAGS = [
+	"yes",
+	"name",
+	"template",
+	"monorepo",
+	"api-path",
+	"pm",
+	"skip-install"
+];
 /**
 * Validate project name for npm package naming conventions
 */
 function validateProjectName(name$1) {
 	if (!name$1) return "Project name is required";
 	if (!/^[a-z0-9-_@/.]+$/i.test(name$1)) return "Project name can only contain letters, numbers, hyphens, underscores, @, /, and .";
+	const flag = name$1.match(/--(\w[\w-]*)$/)?.[1];
+	if (flag && INIT_FLAGS.includes(flag)) {
+		const intended = name$1.slice(0, -(flag.length + 2));
+		return `"${name$1}" ends in the --${flag} flag. Did you mean \`${intended} --${flag}\`?`;
+	}
 	const reserved = [
 		"node_modules",
 		".git",
@@ -12942,6 +13999,18 @@ function getRunCommand(pkgManager, script) {
 		default: return `npm run ${script}`;
 	}
 }
+/**
+* Run a binary the project installed, through its package manager — so it is
+* the project's own version, not whatever \`npx\` would fetch.
+*/
+function getExecCommand(pkgManager, command) {
+	switch (pkgManager) {
+		case "pnpm": return `pnpm exec ${command}`;
+		case "yarn": return `yarn ${command}`;
+		case "bun": return `bunx ${command}`;
+		default: return `npx --no-install ${command}`;
+	}
+}
 const lockfileByPm = {
 	pnpm: "pnpm-lock.yaml",
 	yarn: "yarn.lock",
@@ -13012,12 +14081,31 @@ function findWorkspacePackages(cwd, pm) {
 
 //#endregion
 //#region src/init/index.ts
+/** `' staging, prod '` → `['staging', 'prod']`. */
+const stageList = (value) => value.split(",").map((name$1) => name$1.trim()).filter(Boolean);
+/** `eu-west-1`, `us-gov-west-1`, `ap-southeast-2`. */
+const AWS_REGION = /^[a-z]{2}(-gov)?-[a-z]+-\d$/;
 /**
 * Main init command - scaffolds a new project
 */
 async function initCommand(projectName, options = {}) {
 	const cwd = process.cwd();
 	const detectedPkgManager = detectPackageManager(cwd);
+	if (options.deploy && !deployTargetChoices.some((choice) => choice.value === options.deploy)) throw new Error(`Unknown deploy target "${options.deploy}". Use ${deployTargetChoices.map((c) => c.value).join(", ")}.`);
+	if (options.region && !AWS_REGION.test(options.region)) throw new Error(`"${options.region}" is not an AWS region. Use one like eu-west-1.`);
+	if (options.stages || options.localStage || options.protectedStage) {
+		const deployed = stageList(options.stages ?? "");
+		const problems = [
+			...require_workspace.deployedProblems(deployed),
+			...options.localStage ? require_workspace.stageProblems({
+				local: options.localStage,
+				deployed
+			}) : [],
+			...options.protectedStage && !deployed.includes(options.protectedStage) ? [`--protected-stage "${options.protectedStage}" is not in --stages`] : []
+		];
+		if (problems.length) throw new Error([...new Set(problems)].join("\n"));
+	}
+	let deployedSoFar = [];
 	prompts.default.override({});
 	const onCancel = () => {
 		process.exit(0);
@@ -13068,12 +14156,49 @@ async function initCommand(projectName, options = {}) {
 			initial: packageManagerChoices.findIndex((c) => c.value === detectedPkgManager)
 		},
 		{
-			type: options.yes ? null : "select",
+			type: options.yes || options.deploy ? null : "select",
 			name: "deployTarget",
 			message: "Deployment target:",
 			choices: deployTargetChoices,
 			initial: 0
 		},
+		{
+			type: (_prev, values) => !options.yes && !options.region && (options.deploy ?? values.deployTarget) === "sst" ? "text" : null,
+			name: "region",
+			message: "AWS region (e.g. eu-west-1):",
+			validate: (value) => AWS_REGION.test(value.trim()) || "An AWS region, like eu-west-1"
+		},
+		{
+			type: options.yes || options.stages ? null : "text",
+			name: "deployedStages",
+			message: "Deployed stages, comma-separated (e.g. staging, prod):",
+			validate: (value) => {
+				const deployed = stageList(value);
+				if (deployed.length === 0) return "At least one stage";
+				return require_workspace.deployedProblems(deployed)[0] ?? true;
+			}
+		},
+		{
+			type: (_prev, values) => options.yes || options.protectedStage ? null : stageList(options.stages ?? values.deployedStages ?? "").length > 1 ? "select" : null,
+			name: "protectedStage",
+			message: "Which one is production (retained and protected)?",
+			choices: (_prev, values) => stageList(options.stages ?? values.deployedStages ?? "").map((name$2) => ({
+				title: name$2,
+				value: name$2
+			}))
+		},
+		{
+			type: (_prev, values) => {
+				deployedSoFar = stageList(options.stages ?? values.deployedStages ?? "");
+				return options.yes || options.localStage ? null : "text";
+			},
+			name: "localStage",
+			message: "Local stage, what gkm dev runs as (e.g. dev):",
+			validate: (value) => require_workspace.stageProblems({
+				local: value.trim(),
+				deployed: deployedSoFar
+			})[0] ?? true
+		},
 		{
 			type: options.yes ? null : "confirm",
 			name: "telescope",
@@ -13139,7 +14264,7 @@ async function initCommand(projectName, options = {}) {
 	};
 	if (services.events === "pgboss") services.db = true;
 	const pkgManager = options.pm ? options.pm : options.yes ? "pnpm" : answers.packageManager ?? detectedPkgManager;
-	const deployTarget = options.yes ? "dokploy" : answers.deployTarget ?? "dokploy";
+	const deployTarget = options.deploy ?? (options.yes ? "none" : answers.deployTarget ?? "none");
 	const database = services.db;
 	const frontendFramework = isFullstack ? options.yes ? "nextjs" : answers.frontendFramework ?? "nextjs" : void 0;
 	const templateOptions = {
@@ -13154,6 +14279,8 @@ async function initCommand(projectName, options = {}) {
 		apiPath: monorepo ? options.apiPath ?? "apps/api" : "",
 		packageManager: pkgManager,
 		deployTarget,
+		stages: resolveStages(options, answers),
+		...deployTarget === "sst" ? { region: options.region ?? (options.yes ? "eu-west-1" : answers.region?.trim()) } : {},
 		services,
 		frontendFramework
 	};
@@ -13183,6 +14310,8 @@ async function initCommand(projectName, options = {}) {
 	] : [];
 	const dockerFiles = isMonorepo$1 && baseTemplate ? generateDockerFiles(templateOptions, baseTemplate, dbApps) : [];
 	const rootFiles = baseTemplate ? [
+		...generateAgentFiles(templateOptions, baseTemplate),
+		...generateGithubFiles(templateOptions),
 		...generateMonorepoFiles(templateOptions, baseTemplate),
 		...generateRootConstructs(templateOptions),
 		...generateModelsPackage(templateOptions)
@@ -13228,12 +14357,12 @@ async function initCommand(projectName, options = {}) {
 	if (services.mail) secretServices.push("mailpit");
 	if (services.events === "sns") secretServices.push("localstack");
 	if (services.events === "rabbitmq") secretServices.push("rabbitmq");
-	const devSecrets = require_generator.createStageSecrets("development", secretServices, {
+	const local = templateOptions.stages.local;
+	const devSecrets = require_generator.createStageSecrets(local, secretServices, {
 		projectName: name$1,
 		eventsBackend: services.events
 	});
 	const customSecrets = {
-		NODE_ENV: "development",
 		PORT: "3000",
 		LOG_LEVEL: "debug",
 		JWT_SECRET: `dev-${Date.now()}-${Math.random().toString(36).slice(2)}`
@@ -13253,8 +14382,8 @@ async function initCommand(projectName, options = {}) {
 	}
 	devSecrets.custom = customSecrets;
 	await require_storage.writeStageSecrets(devSecrets, targetDir);
-	const keyPath = require_storage.getKeyPath("development", name$1);
-	console.log(`  Secrets: .gkm/secrets/development.json (encrypted)`);
+	const keyPath = require_storage.getKeyPath(local, name$1);
+	console.log(`  Secrets: .gkm/secrets/${local}.json (encrypted)`);
 	console.log(`  Key: ${keyPath}\n`);
 	if (!options.skipInstall) {
 		console.log("\n📦 Installing dependencies...\n");
@@ -13267,11 +14396,13 @@ async function initCommand(projectName, options = {}) {
 			console.error("Failed to install dependencies");
 		}
 		try {
-			(0, node_child_process.execSync)("npx @biomejs/biome format --write --unsafe .", {
+			(0, node_child_process.execSync)(getExecCommand(pkgManager, "biome check --write ."), {
 				cwd: targetDir,
 				stdio: "inherit"
 			});
-		} catch {}
+		} catch {
+			console.warn(`\n⚠️  Formatting did not finish cleanly. Run ${getRunCommand(pkgManager, "fmt")} to see why.`);
+		}
 	}
 	console.log("\n📦 Initializing git repository...\n");
 	try {
@@ -13343,19 +14474,46 @@ function printNextSteps(projectName, options, pkgManager) {
 		console.log(`  └── turbo.json        # Turbo config`);
 		console.log("");
 	}
+	const { local, deployed } = options.stages;
 	console.log("🔐 Secrets management:");
-	console.log(`  gkm secrets:show --stage development  # View secrets`);
-	console.log(`  gkm secrets:set KEY VALUE --stage development  # Add secret`);
-	console.log(`  gkm secrets:init --stage production  # Create production secrets`);
+	console.log(`  gkm secrets:show --stage ${local}  # View secrets`);
+	console.log(`  gkm secrets:set KEY VALUE --stage ${local}  # Add secret`);
+	for (const stage of deployed) console.log(`  gkm secrets:init --stage ${stage}  # Create ${stage} secrets`);
 	console.log("");
 	if (options.deployTarget === "dokploy") {
 		console.log("🚀 Deployment:");
-		console.log(`  ${getRunCommand(pkgManager, "deploy")}`);
+		for (const stage of deployed) console.log(`  ${getRunCommand(pkgManager, `deploy:${stage}`)}`);
+		console.log("");
+	}
+	if (options.deployTarget === "sst") {
+		console.log("🚀 Deployment (AWS, through SST):");
+		for (const stage of deployed) console.log(`  ${getRunCommand(pkgManager, `deploy:${stage}`)}  # gkm build --provider aws, then sst deploy`);
+		console.log(`  Uses your AWS credentials, in ${options.region}.`);
+		if (options.services.mail) console.log("  Set MAIL_FROM to a sender verified in SES first.");
 		console.log("");
 	}
 	console.log("📚 Documentation: https://geekmidas.github.io/toolbox/");
 	console.log("");
 }
+/**
+* The stages the project declares, from the answers or the flags.
+*
+* `--yes` with no stage flags has nobody to ask and needs an answer, so it
+* takes `local`, and one deployed stage, `production`, that is protected.
+*/
+function resolveStages(options, answers) {
+	const deployed = stageList(options.stages ?? answers.deployedStages ?? (options.yes ? "production" : ""));
+	const kept = options.protectedStage ?? answers.protectedStage ?? (deployed.length === 1 || options.yes ? deployed[0] : void 0);
+	const local = (options.localStage ?? answers.localStage ?? (options.yes ? "local" : "")).trim();
+	const stages = {
+		local,
+		deployed,
+		...kept ? { protected: [kept] } : {}
+	};
+	const problems = require_workspace.stageProblems(stages);
+	if (problems.length) throw new Error(problems.join("\n"));
+	return stages;
+}
 
 //#endregion
 //#region src/secrets/index.ts
@@ -13566,19 +14724,20 @@ function maskUrl(url) {
 * Environment variables are sniffed to inject only what the app needs.
 */
 async function testCommand(options = {}) {
-	const stage = options.stage ?? "development";
 	const cwd = process.cwd();
+	const stage = options.stage ?? await require_config.loadWorkspaceConfig(cwd).then((loaded) => loaded.workspace.stages.local).catch(() => void 0);
+	if (!stage) throw new Error("No stage to test with: add `stages` to gkm.config.ts, or pass --stage.");
 	console.log(`\n🧪 Running tests with ${stage} environment...\n`);
 	const autoSetup = options.autoSetup || Boolean(process.env.GKM_AUTO_SETUP);
 	if (autoSetup) {
-		const { ensureStageSecrets } = await Promise.resolve().then(() => require("./setup-DMtU3p41.cjs"));
+		const { ensureStageSecrets } = await Promise.resolve().then(() => require("./setup-BsZvZP6f.cjs"));
 		const generated = await ensureStageSecrets(stage, cwd);
 		if (generated) console.log(`  🔐 Generated fresh ${stage} secrets (auto-setup)`);
 	}
 	const defaultEnv = require_credentials$1.loadEnvFiles(".env");
 	if (defaultEnv.loaded.length > 0) console.log(`  📦 Loaded env: ${defaultEnv.loaded.join(", ")}`);
 	const result = await require_credentials$1.prepareEntryCredentials({
-		stages: [stage],
+		stage,
 		startDocker: true,
 		secretsFileName: "test-secrets.json",
 		resolveDockerPorts: "full",
@@ -13659,145 +14818,305 @@ function rewriteDatabaseUrlForTests(env) {
 	return result;
 }
 
+//#endregion
+//#region src/upgrade/version.ts
+/**
+* Just enough semver for `gkm upgrade`: ordering versions, and reading the
+* floor out of a simple range. The same ordering the release pipeline uses to
+* decide what is published (`scripts/release-state.mjs`).
+*/
+const VERSION = /(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
+function parse(version$1) {
+	const match = version$1.match(VERSION);
+	if (!match) return void 0;
+	const [, major, minor, patch, pre] = match;
+	return {
+		core: [
+			Number(major),
+			Number(minor),
+			Number(patch)
+		],
+		ids: pre ? pre.split(".").map((id) => /^\d+$/.test(id) ? Number(id) : id) : []
+	};
+}
+/** Negative, zero or positive, as `a` is below, equal to or above `b`. */
+function compareVersions(a, b) {
+	const x = parse(a);
+	const y = parse(b);
+	if (!x || !y) return 0;
+	for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
+	if (!x.ids.length || !y.ids.length) return y.ids.length - x.ids.length;
+	for (let i = 0; i < Math.max(x.ids.length, y.ids.length); i++) {
+		const p = x.ids[i];
+		const q = y.ids[i];
+		if (p === void 0) return -1;
+		if (q === void 0) return 1;
+		if (p === q) continue;
+		if (typeof p === "number" && typeof q === "number") return p - q;
+		if (typeof p === "number") return -1;
+		if (typeof q === "number") return 1;
+		return p < q ? -1 : 1;
+	}
+	return 0;
+}
+/** `alpha` for `10.0.0-alpha.6`; undefined for a release. */
+function prereleaseTag(version$1) {
+	const id = parse(version$1)?.ids[0];
+	return typeof id === "string" ? id : void 0;
+}
+/**
+* A range that is one operator and one version — `~1.2.3`, `^1.2.3`, `>=1.2.3`,
+* `1.2.3` — split into the two. Anything else (`>=8 <10`, `a || b`) is not
+* something to rewrite mechanically.
+*/
+function simpleRange(range) {
+	const match = range.trim().match(/^(\^|~|>=|)v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/);
+	return match ? {
+		operator: match[1],
+		version: match[2]
+	} : void 0;
+}
+
 //#endregion
 //#region src/upgrade/index.ts
 const logger = console;
+const SCOPE = "@geekmidas/";
+const DEP_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+async function packument(name$1) {
+	const res = await fetch(`https://registry.npmjs.org/${name$1.replace("/", "%2F")}`, { headers: { accept: "application/vnd.npm.install-v1+json" } });
+	if (!res.ok) throw new RegistryUnavailable(name$1, res.status);
+	return await res.json();
+}
+/** Every registry range in the workspace's package.json files. */
+function packageOccurrences(paths) {
+	const found = [];
+	for (const file of paths) {
+		const pkg$1 = JSON.parse((0, node_fs.readFileSync)(file, "utf-8"));
+		for (const field of DEP_FIELDS) for (const [name$1, range] of Object.entries(pkg$1[field] ?? {})) found.push({
+			name: name$1,
+			range,
+			file,
+			field
+		});
+	}
+	return found;
+}
+/** pnpm catalog entries, which is where `catalog:` references resolve. */
+function catalogOccurrences(root) {
+	const file = (0, node_path.join)(root, "pnpm-workspace.yaml");
+	if (!(0, node_fs.existsSync)(file)) return [];
+	const doc = (0, yaml.parseDocument)((0, node_fs.readFileSync)(file, "utf-8")).toJS() ?? {};
+	const found = [];
+	for (const [name$1, range] of Object.entries(doc.catalog ?? {})) found.push({
+		name: name$1,
+		range: String(range),
+		file,
+		field: "catalog"
+	});
+	for (const [catalog, entries] of Object.entries(doc.catalogs ?? {})) for (const [name$1, range] of Object.entries(entries ?? {})) found.push({
+		name: name$1,
+		range: String(range),
+		file,
+		field: "catalog",
+		catalog
+	});
+	return found;
+}
+/** Not a registry range: resolved elsewhere, so not ours to move. */
+const isIndirect = (range) => /^(workspace|catalog|link|file|npm|git|github|https?):/.test(range);
+/**
+* The version every `@geekmidas` package moves to.
+*
+* All of them share one version, so the CLI's line answers for the rest. The
+* tag is the one the project is already on — a project on `10.0.0-alpha.6`
+* follows `alpha` — because `latest` names a different major while a new one
+* is in prerelease, and following it would move the project backwards.
+*/
+function resolveTarget(distTags, installed, tag) {
+	const highest = [...installed].sort(compareVersions).at(-1);
+	const chosen = tag ?? (highest && prereleaseTag(highest)) ?? "latest";
+	const version$1 = distTags[chosen];
+	if (!version$1) throw new NoReleaseOnTag(chosen, Object.keys(distTags));
+	return {
+		tag: chosen,
+		version: version$1
+	};
+}
+/** The same operator on the new version — `^`, `~`, `>=` or none, as written. */
+function withVersion(range, version$1) {
+	return `${simpleRange(range)?.operator ?? ""}${version$1}`;
+}
 async function upgradeCommand(options = {}) {
 	const cwd = process.cwd();
-	logger.log("\n📦 Scanning workspace for @geekmidas packages...\n");
 	const pm = detectPackageManager(cwd);
+	const root = findWorkspaceRoot(cwd, pm);
+	logger.log("\n📦 Scanning workspace for @geekmidas packages...\n");
 	logger.log(`  Package manager: ${pm}`);
-	const packageJsonPaths = findWorkspacePackages(cwd, pm);
-	logger.log(`  Found ${packageJsonPaths.length} package(s) in workspace\n`);
-	const dependencies$1 = scanForGeekmidasDeps(packageJsonPaths);
-	if (dependencies$1.length === 0) {
+	const packageJsons = findWorkspacePackages(cwd, pm);
+	const occurrences = [...packageOccurrences(packageJsons), ...catalogOccurrences(root)];
+	logger.log(`  Found ${packageJsons.length} package(s) in workspace\n`);
+	const ours = occurrences.filter((o) => o.name.startsWith(SCOPE) && !isIndirect(o.range));
+	if (ours.length === 0) {
 		logger.log("  No @geekmidas packages found.\n");
 		return;
 	}
-	const uniquePackages = [...new Set(dependencies$1.map((d) => d.packageName))];
-	logger.log(`  Checking ${uniquePackages.length} unique @geekmidas package(s) on npm...\n`);
-	const latestVersions = await fetchLatestVersions(uniquePackages);
-	const upgradeInfos = dependencies$1.map((dep) => resolveUpgradeInfo(dep, latestVersions));
-	printUpgradeTable(upgradeInfos);
-	const upgradable = upgradeInfos.filter((info) => info.needsUpgrade && !info.isWorkspaceRef);
-	if (upgradable.length === 0) {
-		logger.log("\n  All @geekmidas packages are up to date!\n");
+	const installed = ours.map((o) => simpleRange(o.range)?.version).filter((v) => Boolean(v));
+	const cli = await packument(`${SCOPE}cli`);
+	const target = resolveTarget(cli["dist-tags"], installed, options.tag);
+	logger.log(`  Target: ${target.version} (npm "${target.tag}")\n`);
+	const highest = installed.sort(compareVersions).at(-1);
+	if (compareVersions(target.version, highest) < 0) throw new WouldDowngrade(highest, target.tag, target.version);
+	const moving = options.all ? ours : ours.filter((o) => o.name === `${SCOPE}cli`);
+	const changes = [];
+	for (const o of moving) {
+		if (!simpleRange(o.range)) {
+			logger.log(`  ⚠ ${o.name} ${o.range} is not a simple range; left as is (target ${target.version}).`);
+			continue;
+		}
+		const next = withVersion(o.range, target.version);
+		if (next !== o.range) changes.push({
+			...o,
+			next
+		});
+	}
+	if (options.all) changes.push(...await peerChanges(occurrences, ours, target.version));
+	if (changes.length === 0) {
+		logger.log("  Everything is already on the target version.\n");
 		return;
 	}
-	logger.log(`\n  ${upgradable.length} package(s) can be upgraded.\n`);
+	printChanges(changes, root);
+	if (!options.all && ours.some((o) => o.name !== `${SCOPE}cli`)) logger.log("\n  Only @geekmidas/cli moves without --all. Afterwards, run `gkm upgrade --all` with the new CLI.");
 	if (options.dryRun) {
-		logger.log("  --dry-run: No changes made.\n");
-		printUpgradeCommands(upgradable, pm);
+		logger.log("\n  --dry-run: no changes made.\n");
 		return;
 	}
-	executeUpgrade(upgradable, pm, cwd);
-	logger.log("\n  ✅ Upgrade complete! Run your tests to verify.\n");
+	applyChanges(changes);
+	install(pm, root);
+	logger.log("\n  ✅ Upgrade complete. Run your tests to verify.\n");
 }
-function scanForGeekmidasDeps(packageJsonPaths) {
-	const results = [];
-	const depTypes = [
-		"dependencies",
-		"devDependencies",
-		"peerDependencies"
-	];
-	for (const pkgJsonPath of packageJsonPaths) {
-		const pkg$1 = JSON.parse((0, node_fs.readFileSync)(pkgJsonPath, "utf-8"));
-		const workspaceName = pkg$1.name ?? pkgJsonPath;
-		for (const depType of depTypes) {
-			const deps = pkg$1[depType];
-			if (!deps) continue;
-			for (const [name$1, version$1] of Object.entries(deps)) {
-				if (!name$1.startsWith("@geekmidas/")) continue;
-				results.push({
-					packageName: name$1,
-					currentVersion: version$1,
-					depType,
-					packageJsonPath: pkgJsonPath,
-					workspaceName
-				});
-			}
+/**
+* Third-party packages the project already lists, raised to the floor of the
+* peer range the target `@geekmidas` versions declare.
+*
+* Only raised, never lowered, and only where both the peer range and the
+* project's range are one operator and one version; anything else is reported
+* for a person to decide.
+*/
+async function peerChanges(occurrences, ours, version$1) {
+	const floors = /* @__PURE__ */ new Map();
+	const names = [...new Set(ours.map((o) => o.name))];
+	const docs = await Promise.all(names.map(packument));
+	for (const doc of docs) {
+		const peers = doc.versions[version$1]?.peerDependencies ?? {};
+		for (const [peer, range] of Object.entries(peers)) {
+			if (peer.startsWith(SCOPE)) continue;
+			const floor = simpleRange(range)?.version;
+			if (!floor) continue;
+			const known = floors.get(peer);
+			if (!known || compareVersions(floor, known) > 0) floors.set(peer, floor);
+		}
+	}
+	const changes = [];
+	for (const o of occurrences) {
+		const floor = floors.get(o.name);
+		if (!floor || isIndirect(o.range) || o.field === "peerDependencies") continue;
+		const current = simpleRange(o.range);
+		if (!current) {
+			logger.log(`  ⚠ ${o.name} ${o.range} is not a simple range; @geekmidas needs at least ${floor}.`);
+			continue;
 		}
+		if (compareVersions(current.version, floor) < 0) changes.push({
+			...o,
+			next: withVersion(o.range, floor)
+		});
 	}
-	return results;
-}
-async function fetchLatestVersions(packageNames) {
-	const versions = /* @__PURE__ */ new Map();
-	const results = await Promise.allSettled(packageNames.map(async (name$1) => {
-		const res = await fetch(`https://registry.npmjs.org/${name$1}/latest`);
-		if (!res.ok) throw new Error(`HTTP ${res.status}`);
-		const data = await res.json();
-		return {
-			name: name$1,
-			version: data.version
-		};
-	}));
-	for (const result of results) if (result.status === "fulfilled") versions.set(result.value.name, result.value.version);
-	return versions;
-}
-function resolveUpgradeInfo(dep, latestVersions) {
-	const isWorkspaceRef = dep.currentVersion.startsWith("workspace:");
-	const latestVersion = latestVersions.get(dep.packageName) ?? "unknown";
-	const currentBare = dep.currentVersion.replace(/^[\^~>=<]*/g, "");
-	const needsUpgrade = !isWorkspaceRef && latestVersion !== "unknown" && currentBare !== latestVersion;
-	return {
-		...dep,
-		latestVersion,
-		isWorkspaceRef,
-		needsUpgrade
-	};
-}
-function printUpgradeTable(infos) {
-	const byPackage = /* @__PURE__ */ new Map();
-	for (const info of infos) if (!byPackage.has(info.packageName)) byPackage.set(info.packageName, info);
-	const nameWidth = 33;
-	const verWidth = 14;
-	const statusWidth = 14;
-	const hr = `  ${"─".repeat(nameWidth + verWidth * 2 + statusWidth + 5)}`;
-	logger.log(hr);
-	logger.log(`  ${"Package".padEnd(nameWidth)} ${"Current".padEnd(verWidth)} ${"Latest".padEnd(verWidth)} ${"Status".padEnd(statusWidth)}`);
-	logger.log(hr);
-	for (const [, info] of byPackage) {
-		const name$1 = info.packageName.padEnd(nameWidth);
-		const current = info.currentVersion.padEnd(verWidth);
-		const latest = info.latestVersion.padEnd(verWidth);
-		let status;
-		if (info.isWorkspaceRef) status = "workspace";
-		else if (info.needsUpgrade) status = "⬆ upgrade";
-		else status = "✓ up-to-date";
-		logger.log(`  ${name$1} ${current} ${latest} ${status}`);
-	}
-	logger.log(hr);
-}
-function printUpgradeCommands(upgradable, pm) {
-	logger.log("  Commands that would be run:\n");
-	const uniquePackages = [...new Set(upgradable.map((i) => i.packageName))];
-	const cmd = getWorkspaceUpgradeCommand(pm, uniquePackages);
-	logger.log(`    ${cmd}\n`);
-}
-function getWorkspaceUpgradeCommand(pm, packages) {
-	const pkgList = packages.join(" ");
-	switch (pm) {
-		case "pnpm": return `pnpm update -r ${pkgList} --latest`;
-		case "yarn": return `yarn upgrade ${pkgList}`;
-		case "bun": return `bun update ${pkgList}`;
-		case "npm": return `npm update ${pkgList} --workspaces`;
-		default: return `npm update ${pkgList}`;
+	return changes;
+}
+function printChanges(changes, root) {
+	logger.log("  Changes:\n");
+	for (const c of changes) {
+		const where = c.field === "catalog" ? `pnpm-workspace.yaml (${c.catalog ? `catalogs.${c.catalog}` : "catalog"})` : `${(0, node_path.relative)(root, c.file) || "package.json"} (${c.field})`;
+		logger.log(`  ${c.name.padEnd(34)} ${c.range} → ${c.next}   ${where}`);
+	}
+}
+function applyChanges(changes) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const c of changes) byFile.set(c.file, [...byFile.get(c.file) ?? [], c]);
+	for (const [file, fileChanges] of byFile) {
+		const text = (0, node_fs.readFileSync)(file, "utf-8");
+		if (file.endsWith(".yaml")) {
+			const doc = (0, yaml.parseDocument)(text);
+			for (const c of fileChanges) {
+				const path = c.catalog ? [
+					"catalogs",
+					c.catalog,
+					c.name
+				] : ["catalog", c.name];
+				doc.setIn(path, c.next);
+			}
+			(0, node_fs.writeFileSync)(file, doc.toString());
+			continue;
+		}
+		const pkg$1 = JSON.parse(text);
+		for (const c of fileChanges) pkg$1[c.field][c.name] = c.next;
+		const indent = text.match(/^[ \t]+(?=")/m)?.[0] ?? "  ";
+		(0, node_fs.writeFileSync)(file, `${JSON.stringify(pkg$1, null, indent)}\n`);
 	}
 }
-function executeUpgrade(upgradable, pm, cwd) {
-	const uniquePackages = [...new Set(upgradable.map((i) => i.packageName))];
-	const cmd = getWorkspaceUpgradeCommand(pm, uniquePackages);
-	logger.log(`  Running: ${cmd}\n`);
+function install(pm, cwd) {
+	const command = getInstallCommand(pm);
+	logger.log(`\n  Running: ${command}\n`);
 	try {
-		(0, node_child_process.execSync)(cmd, {
+		(0, node_child_process.execSync)(command, {
 			cwd,
 			stdio: "inherit",
-			timeout: 12e4
+			timeout: 3e5
 		});
 	} catch {
-		throw new Error("Package upgrade failed. Check the output above for details.");
+		throw new InstallFailed(command);
 	}
 }
+/** npm did not answer for a package, so there is no version to compare. */
+var RegistryUnavailable = class extends Error {
+	constructor(packageName, status) {
+		super(`npm answered ${status} for ${packageName}. Check the name and your network.`);
+		this.packageName = packageName;
+		this.status = status;
+		this.name = "RegistryUnavailable";
+	}
+};
+/** A dist-tag npm does not have, e.g. `--tag beta` before any beta. */
+var NoReleaseOnTag = class extends Error {
+	constructor(tag, tags) {
+		super(`npm has no "${tag}" release of @geekmidas/cli. Tags: ${tags.join(", ")}.`);
+		this.tag = tag;
+		this.tags = tags;
+		this.name = "NoReleaseOnTag";
+	}
+};
+/** The line asked for is behind what is installed; upgrade never goes back. */
+var WouldDowngrade = class extends Error {
+	constructor(installed, tag, target) {
+		super(`The project is already on ${installed}, ahead of npm's "${tag}" (${target}). Pass --tag to follow another line.`);
+		this.installed = installed;
+		this.tag = tag;
+		this.target = target;
+		this.name = "WouldDowngrade";
+	}
+};
+/** The install after rewriting versions failed; its own output says why. */
+var InstallFailed = class extends Error {
+	constructor(command) {
+		super(`\`${command}\` failed. Check the output above for details.`);
+		this.command = command;
+		this.name = "InstallFailed";
+	}
+};
 
 //#endregion
 //#region src/index.ts
@@ -13806,7 +15125,7 @@ program.name("gkm").description("GeekMidas backend framework CLI").version(packa
 	const opts = program.opts();
 	if (opts.debug) enableDebug();
 });
-program.command("init").description("Scaffold a new project").argument("[name]", "Project name").option("--template <template>", "Project template (minimal, api, serverless, worker)").option("--skip-install", "Skip dependency installation", false).option("-y, --yes", "Skip prompts, use defaults", false).option("--monorepo", "Setup as monorepo with packages/models", false).option("--api-path <path>", "API app path in monorepo (default: apps/api)").option("--pm <manager>", "Package manager (pnpm, npm, yarn, bun)").action(async (name$1, options) => {
+program.command("init").description("Scaffold a new project").argument("[name]", "Project name").option("--template <template>", "Project template (minimal, api, serverless, worker)").option("--skip-install", "Skip dependency installation", false).option("-y, --yes", "Skip prompts, use defaults", false).option("--monorepo", "Setup as monorepo with packages/models", false).option("--api-path <path>", "API app path in monorepo (default: apps/api)").option("--pm <manager>", "Package manager (pnpm, npm, yarn, bun)").option("--deploy <target>", "Where it deploys (dokploy, sst, none)").option("--region <region>", "AWS region for an SST deploy (e.g. eu-west-1)").option("--stages <names>", "Deployed stages, comma-separated (e.g. staging,prod)").option("--protected-stage <name>", "Which deployed stage is production").option("--local-stage <name>", "What gkm dev runs as (e.g. dev)").option("--region <region>", "AWS region for an SST deploy (e.g. eu-west-1)").action(async (name$1, options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -13826,7 +15145,7 @@ program.command("trust").description("Trust the local edge's certificate authori
 		process.exit(1);
 	}
 });
-program.command("setup").description("Reconcile declared constructs — containers, databases, buckets, secrets").option("--stage <stage>", "Stage name", "development").option("--force", "Regenerate secrets even if they exist").option("--skip-docker", "Skip starting Docker services").option("-y, --yes", "Skip prompts").action(async (options) => {
+program.command("setup").description("Reconcile declared constructs — containers, databases, buckets, secrets").option("--stage <stage>", "Stage name (default: stages.local)").option("--force", "Regenerate secrets even if they exist").option("--skip-docker", "Skip starting Docker services").option("-y, --yes", "Skip prompts").action(async (options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -13898,7 +15217,7 @@ program.command("exec").description("Run a command with secrets injected into Cr
 		process.exit(1);
 	}
 });
-program.command("test").description("Run tests with secrets loaded from environment").option("--stage <stage>", "Stage to load secrets from", "development").option("--run", "Run tests once without watch mode").option("--watch", "Enable watch mode").option("--coverage", "Generate coverage report").option("--ui", "Open Vitest UI").option("--auto-setup", "Generate a fresh stage (secrets + key) from the workspace config when none exists (for CI; also via GKM_AUTO_SETUP)").argument("[pattern]", "Pattern to filter tests").action(async (pattern, options) => {
+program.command("test").description("Run tests with secrets loaded from environment").option("--stage <stage>", "Stage to load secrets from (default: stages.local)").option("--run", "Run tests once without watch mode").option("--watch", "Enable watch mode").option("--coverage", "Generate coverage report").option("--ui", "Open Vitest UI").option("--auto-setup", "Generate a fresh stage (secrets + key) from the workspace config when none exists (for CI; also via GKM_AUTO_SETUP)").argument("[pattern]", "Pattern to filter tests").action(async (pattern, options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -14046,7 +15365,7 @@ program.command("secrets:push").description("Push secrets to remote provider (SS
 		const { workspace } = await loadWorkspaceConfig$1();
 		const secrets = await readStageSecrets$1(options.stage, workspace.root);
 		if (secrets) {
-			const { derivedContainers: derivedContainers$1 } = await Promise.resolve().then(() => require("./workspace-8acupeaI.cjs"));
+			const { derivedContainers: derivedContainers$1 } = await Promise.resolve().then(() => require("./workspace-XXtNhqJl.cjs"));
 			const result = reconcileMissingSecrets(secrets, workspace, await derivedContainers$1(workspace, options.stage));
 			if (result) {
 				await writeStageSecrets$1(result.secrets, workspace.root);
@@ -14075,7 +15394,7 @@ program.command("secrets:pull").description("Pull secrets from remote provider (
 			console.error(`No remote secrets found for stage "${options.stage}".`);
 			process.exit(1);
 		}
-		const { derivedContainers: derivedContainers$1 } = await Promise.resolve().then(() => require("./workspace-8acupeaI.cjs"));
+		const { derivedContainers: derivedContainers$1 } = await Promise.resolve().then(() => require("./workspace-XXtNhqJl.cjs"));
 		const result = reconcileMissingSecrets(secrets, workspace, await derivedContainers$1(workspace, options.stage));
 		if (result) {
 			secrets = result.secrets;
@@ -14089,7 +15408,7 @@ program.command("secrets:pull").description("Pull secrets from remote provider (
 		process.exit(1);
 	}
 });
-program.command("secrets:reconcile").description("Backfill missing custom secrets from workspace config").option("--stage <stage>", "Stage name", "development").action(async (options) => {
+program.command("secrets:reconcile").description("Backfill missing custom secrets from workspace config").option("--stage <stage>", "Stage name (default: stages.local)").action(async (options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -14097,19 +15416,20 @@ program.command("secrets:reconcile").description("Backfill missing custom secret
 		const { reconcileMissingSecrets } = await Promise.resolve().then(() => require("./reconcile-D0pimNiy.cjs"));
 		const { readStageSecrets: readStageSecrets$1, writeStageSecrets: writeStageSecrets$1 } = await Promise.resolve().then(() => require("./storage-BM9hGpgv.cjs"));
 		const { workspace } = await loadWorkspaceConfig$1();
-		const secrets = await readStageSecrets$1(options.stage, workspace.root);
+		const stage = options.stage ?? workspace.stages.local;
+		const secrets = await readStageSecrets$1(stage, workspace.root);
 		if (!secrets) {
-			console.error(`No secrets found for stage "${options.stage}". Run "gkm secrets:init --stage ${options.stage}" first.`);
+			console.error(`No secrets found for stage "${stage}". Run "gkm secrets:init --stage ${stage}" first.`);
 			process.exit(1);
 		}
-		const { derivedContainers: derivedContainers$1 } = await Promise.resolve().then(() => require("./workspace-8acupeaI.cjs"));
-		const result = reconcileMissingSecrets(secrets, workspace, await derivedContainers$1(workspace, options.stage));
+		const { derivedContainers: derivedContainers$1 } = await Promise.resolve().then(() => require("./workspace-XXtNhqJl.cjs"));
+		const result = reconcileMissingSecrets(secrets, workspace, await derivedContainers$1(workspace, stage));
 		if (!result) {
-			console.log(`\n✓ Secrets for stage "${options.stage}" are up-to-date`);
+			console.log(`\n✓ Secrets for stage "${stage}" are up-to-date`);
 			return;
 		}
 		await writeStageSecrets$1(result.secrets, workspace.root);
-		console.log(`\n✓ Reconciled ${result.addedKeys.length} missing secret(s) for stage "${options.stage}":`);
+		console.log(`\n✓ Reconciled ${result.addedKeys.length} missing secret(s) for stage "${stage}":`);
 		for (const key of result.addedKeys) console.log(`    + ${key}`);
 	} catch (error) {
 		console.error(formatError(error));
@@ -14263,7 +15583,7 @@ program.command("state:diff").description("Compare local and remote deployment s
 		process.exit(1);
 	}
 });
-program.command("upgrade").description("Upgrade all @geekmidas packages to their latest versions").option("--dry-run", "Show what would be upgraded without making changes").action(async (options) => {
+program.command("upgrade").description("Upgrade @geekmidas/cli (with --all, every @geekmidas package) along the release line the project is on").option("--dry-run", "Show what would be upgraded without making changes").option("--all", "Every @geekmidas package, and the third-party packages their peers require").option("--tag <tag>", "npm dist-tag to follow (default: the line you are on)").action(async (options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);