@geekmidas/cli 10.0.0-alpha.5 → 10.0.0-alpha.9

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-C21ocYNd.cjs');
-const require_workspace = require('./workspace-BcucjwvA.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-G1JwBoXH.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-CA0yJUTN.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-Cm2UnAdh.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.4";
+var version = "10.0.0-alpha.9";
 var description = "CLI tools for building Lambda handlers, server applications, and generating OpenAPI specs";
 var private$1 = false;
 var type = "module";
@@ -143,6 +143,7 @@ var dependencies = {
 	"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",
@@ -157,8 +158,8 @@ var devDependencies = {
 	"@types/node": "~24.9.1",
 	"@types/pg": "~8.23.1",
 	"@types/prompts": "~2.4.9",
-	"typescript": "^5.8.2",
-	"vitest": "^3.2.4",
+	"typescript": "~5.8.2",
+	"vitest": "~3.2.4",
 	"zod": "~4.6.5"
 };
 var peerDependencies = { "@geekmidas/telescope": "workspace:~" };
@@ -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 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);
 }
 
@@ -7352,47 +7519,47 @@ const CONSTRUCTS_GLOB = "./src/constructs/**/*.ts";
 */
 const WORKSPACE_CONSTRUCTS_GLOB = "./constructs/**/*.ts";
 /**
-* The database a project named `name` declares.
+* Where each routes structure puts an app's handlers, relative to the app.
 *
-* 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.
+* `.ts` only, never `.tsx`: a TanStack site keeps its own `src/routes/`, and
+* this glob must not import a frontend's route components.
 */
-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")
-	};
+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";
+	}
 }
-/** The mail sender a project named `name` declares. */
-function emailFor(name$1) {
-	const id = (0, __geekmidas_manifest.canonicalId)(`${name$1}-mail`);
+/**
+* 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 cache a project named `name` declares. */
-function cacheFor(name$1) {
-	const id = (0, __geekmidas_manifest.canonicalId)(`${name$1}-cache`);
+/** The database a project declares. */
+function databaseFor() {
 	return {
-		id,
-		service: (0, __geekmidas_manifest.serviceKey)(id),
-		urlKey: (0, __geekmidas_manifest.provideKey)(id, "url")
+		...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.
 *
@@ -7400,8 +7567,8 @@ function cacheFor(name$1) {
 * 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);
+function databaseFiles() {
+	const db = databaseFor();
 	return [{
 		path: "src/constructs/database.ts",
 		content: `import { KyselyDatabase } from '@geekmidas/constructs/database/kysely';
@@ -7430,7 +7597,16 @@ export interface Database {
  */
 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';
 
@@ -7458,7 +7634,18 @@ 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
@@ -7538,6 +7725,7 @@ what the OpenAPI spec says, which env vars a process needs.
 \`\`\`typescript
 export default defineWorkspace({
   name: '${name$1}',
+  stages: { local: 'dev', deployed: ['staging', 'prod'], protected: ['prod'] },
   constructs: '${constructsGlob}',
   secrets: { enabled: true },
 });
@@ -7694,11 +7882,11 @@ Crons, subscribers and functions are declared the same way endpoints are: as
 exported values the build discovers.
 
 \`\`\`typescript
-// a scheduled job
-import { c } from '@geekmidas/constructs/crons';
+// a scheduled job, built from the worker that runs it
+import { worker } from '../constructs/worker.ts';
 
-export const cleanup = c
-  .schedule('rate(1 day)')
+export const cleanup = worker
+  .cron('rate(1 day)')
   .handle(async ({ logger }) => {
     logger.info('cleaning up');
   });
@@ -7706,10 +7894,10 @@ export const cleanup = c
 
 \`\`\`typescript
 // a topic subscriber
-import { s } from '@geekmidas/constructs/subscribers';
 import { userEvents } from '../constructs/topics.ts';
+import { worker } from '../constructs/worker.ts';
 
-export const onUserCreated = s
+export const onUserCreated = worker
   .topic(userEvents)
   .subscribe(['user.created'])
   .handle(async ({ events, logger }) => {
@@ -7792,6 +7980,30 @@ ${database ? "gkm test       # starts services, injects secrets, then runs vites
 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);
@@ -7814,26 +8026,26 @@ const CLI_VERSION = `~${pkg.version}`;
 * Run: pnpm --filter @geekmidas/cli sync-versions
 */
 const GEEKMIDAS_VERSIONS = {
-	"@geekmidas/audit": "~10.0.0-alpha.4",
-	"@geekmidas/auth": "~10.0.0-alpha.4",
-	"@geekmidas/cache": "~10.0.0-alpha.4",
-	"@geekmidas/client": "~10.0.0-alpha.4",
-	"@geekmidas/cloud": "~10.0.0-alpha.4",
-	"@geekmidas/constructs": "~10.0.0-alpha.4",
-	"@geekmidas/db": "~10.0.0-alpha.4",
-	"@geekmidas/emailkit": "~10.0.0-alpha.4",
-	"@geekmidas/envkit": "~10.0.0-alpha.4",
-	"@geekmidas/errors": "~10.0.0-alpha.4",
-	"@geekmidas/events": "~10.0.0-alpha.4",
-	"@geekmidas/logger": "~10.0.0-alpha.4",
-	"@geekmidas/manifest": "~10.0.0-alpha.4",
-	"@geekmidas/rate-limit": "~10.0.0-alpha.4",
-	"@geekmidas/schema": "~10.0.0-alpha.4",
-	"@geekmidas/services": "~10.0.0-alpha.4",
-	"@geekmidas/storage": "~10.0.0-alpha.4",
-	"@geekmidas/studio": "~10.0.0-alpha.4",
-	"@geekmidas/telescope": "~10.0.0-alpha.4",
-	"@geekmidas/testkit": "~10.0.0-alpha.4",
+	"@geekmidas/audit": "~10.0.0-alpha.9",
+	"@geekmidas/auth": "~10.0.0-alpha.9",
+	"@geekmidas/cache": "~10.0.0-alpha.9",
+	"@geekmidas/client": "~10.0.0-alpha.9",
+	"@geekmidas/cloud": "~10.0.0-alpha.9",
+	"@geekmidas/constructs": "~10.0.0-alpha.9",
+	"@geekmidas/db": "~10.0.0-alpha.9",
+	"@geekmidas/emailkit": "~10.0.0-alpha.9",
+	"@geekmidas/envkit": "~10.0.0-alpha.9",
+	"@geekmidas/errors": "~10.0.0-alpha.9",
+	"@geekmidas/events": "~10.0.0-alpha.9",
+	"@geekmidas/logger": "~10.0.0-alpha.9",
+	"@geekmidas/manifest": "~10.0.0-alpha.9",
+	"@geekmidas/rate-limit": "~10.0.0-alpha.9",
+	"@geekmidas/schema": "~10.0.0-alpha.9",
+	"@geekmidas/services": "~10.0.0-alpha.9",
+	"@geekmidas/storage": "~10.0.0-alpha.9",
+	"@geekmidas/studio": "~10.0.0-alpha.9",
+	"@geekmidas/telescope": "~10.0.0-alpha.9",
+	"@geekmidas/testkit": "~10.0.0-alpha.9",
 	"@geekmidas/cli": CLI_VERSION
 };
 
@@ -7853,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"
 		}
@@ -7913,6 +8126,30 @@ dist/
 	];
 }
 
+//#endregion
+//#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 `STAGE` the scaffolded env config parses: one of the declared stages,
+* defaulting to the local one.
+*/
+function stageEnv(stages) {
+	const names = [stages.local, ...stages.deployed].map((name$1) => `'${name$1}'`).join(", ");
+	return `get('STAGE').enum([${names}]).default('${stages.local}')`;
+}
+
 //#endregion
 //#region src/init/generators/config.ts
 /**
@@ -7937,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,
@@ -7954,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.
@@ -7996,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",
@@ -8022,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"]
@@ -8048,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",
@@ -8072,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 = {
@@ -8130,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,
@@ -8139,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`
@@ -8280,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
@@ -8553,12 +8786,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",
@@ -8694,7 +8927,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: [
@@ -9252,14 +9485,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 = deployPackage(options);
+	const isSst = options.deployTarget === "sst";
 	const rootPackageJson = {
 		name: options.name,
 		version: "0.0.1",
@@ -9276,9 +9637,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.scripts
+		},
+		dependencies: {
+			zod: DEPENDENCY_VERSIONS.zod,
+			...isFullstack ? rootConstructDependencies(options) : {},
+			...deploy.dependencies
 		},
-		dependencies: { zod: "~4.1.0" },
 		devDependencies: {
 			"@biomejs/biome": "~2.3.0",
 			"@geekmidas/cli": GEEKMIDAS_VERSIONS["@geekmidas/cli"],
@@ -9286,7 +9651,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.devDependencies
 		}
 	};
 	const apiPathParts = options.apiPath.split("/");
@@ -9302,7 +9668,7 @@ function generateMonorepoFiles(options, _template) {
 			clientKind: "git",
 			useIgnoreFile: true
 		},
-		organizeImports: { enabled: true },
+		assist: { actions: { source: { organizeImports: "on" } } },
 		formatter: {
 			enabled: true,
 			indentStyle: "space",
@@ -9326,11 +9692,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 = {
@@ -9396,12 +9765,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",
@@ -9413,16 +9784,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'],
@@ -9503,7 +9879,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",
@@ -9530,12 +9907,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: '${WORKSPACE_CONSTRUCTS_GLOB}',
+  // \`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,
@@ -9564,7 +9946,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",
@@ -9630,6 +10012,7 @@ import { authDb } from './database.ts';
  * origin down.
  */
 export const auth = new BetterAuth('Auth', {
+  path: 'apps/auth',
   database: authDb,
   basePath: '/api/auth',
 });
@@ -9644,25 +10027,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';
@@ -9672,7 +10052,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.
@@ -9681,7 +10061,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';
@@ -9692,7 +10072,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';
@@ -9703,7 +10083,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';
@@ -9736,9 +10116,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",
@@ -9762,10 +10142,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}';
@@ -9799,6 +10179,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',
@@ -9821,7 +10204,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();
 `
@@ -9973,7 +10356,7 @@ export const authService = {
           headers: { cookie },
         });
         if (!res.ok) return null;
-        return res.json();
+        return (await res.json()) as Session | null;
       },
     };
   },
@@ -9986,7 +10369,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.
@@ -10044,7 +10426,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';
@@ -10194,9 +10577,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",
@@ -10220,7 +10603,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();
@@ -10240,6 +10623,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',
@@ -10262,7 +10648,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();
 `
@@ -10289,7 +10675,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';
@@ -10353,8 +10739,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",
@@ -10397,6 +10783,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',
@@ -10419,7 +10808,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();
 `
@@ -10449,19 +10838,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';
@@ -10470,7 +10867,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}',
 });
 `
 		});
@@ -10490,12 +10887,11 @@ export const telescope = new Telescope({
 * that was missing: it takes no authorizer, publishes no address, and hands out
 * factories already carrying its logger.
 *
-* It scaffolds no cron. A cron is the obvious thing to put in a worker and it
-* would not run: `CronGenerator` emits handlers for `aws-lambda` only, and
-* `.gkm/server/` has no crons file, so a scheduled job on a server target
-* deploys nothing at all. Subscribers and queues do have a server runtime,
-* which is why those are what this template teaches. The cron example returns
-* when there is a scheduler to run it.
+* 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",
@@ -10507,7 +10903,7 @@ const workerTemplate = {
 		"@geekmidas/events": GEEKMIDAS_VERSIONS["@geekmidas/events"],
 		"@geekmidas/logger": GEEKMIDAS_VERSIONS["@geekmidas/logger"],
 		"@geekmidas/schema": GEEKMIDAS_VERSIONS["@geekmidas/schema"],
-		pino: "~10.3.1"
+		pino: DEPENDENCY_VERSIONS.pino
 	},
 	devDependencies: {
 		"@biomejs/biome": "~2.3.0",
@@ -10529,7 +10925,7 @@ const workerTemplate = {
 		"fmt:check": "biome format ."
 	},
 	files: (options) => {
-		const { loggerType, name: name$1 } = options;
+		const { loggerType, name: name$1, database } = options;
 		const loggerContent = `import { createLogger } from '@geekmidas/logger/${loggerType}';
 
 export const logger = createLogger();
@@ -10538,9 +10934,9 @@ export const logger = createLogger();
 			{
 				path: "src/constructs/worker.ts",
 				content: `import { Worker } from '@geekmidas/constructs/worker';
-import { logger } from '../config/logger.ts';
+import { logger } from '../config/logger.ts';${database ? "\nimport { database } from './database.ts';" : ""}
 
-export const worker = new Worker('Jobs', { logger });
+export const worker = new Worker('Jobs', { logger })${database ? ".database(database)" : ""};
 `
 			},
 			{
@@ -10555,7 +10951,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();
 `
@@ -10608,7 +11004,7 @@ export const eventsPublisherService = {
 				content: `import { worker } from '~/constructs/worker.ts';
 import { eventsPublisherService } from '~/events/publisher.ts';
 
-export const userEventsSubscriber = worker.subscribers
+export const userEventsSubscriber = worker
   .publisher(eventsPublisherService)
   .subscribe(['user.created', 'user.updated'])
   .handle(async ({ events, logger }) => {
@@ -10630,7 +11026,22 @@ export const userEventsSubscriber = worker.subscribers
 `
 			}
 		];
-		if (options.database) files$1.push(...databaseFiles(name$1));
+		if (database) files$1.push({
+			path: "src/crons/cleanup.ts",
+			content: `import { worker } from '~/constructs/worker.ts';
+
+export const cleanup = worker
+  .cron('rate(1 day)')
+  .handle(async ({ logger }) => {
+    logger.info('Running cleanup');
+
+    // Delete old sessions, clear temp files, whatever falls out of date.
+
+    logger.info('Cleanup complete');
+  });
+`
+		});
+		if (options.database) files$1.push(...databaseFiles());
 		if (options.telescope) files$1.push({
 			path: "src/config/telescope.ts",
 			content: `import { Telescope } from '@geekmidas/telescope';
@@ -10651,7 +11062,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)
 */
@@ -10757,15 +11168,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
 */
@@ -10858,12 +11277,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) {
@@ -10883,6 +11302,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",
@@ -10920,7 +11341,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";
@@ -10956,14 +11377,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,
 });
 `
 		},
@@ -11048,10 +11471,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();
   });
 });
 `
@@ -12302,8 +12725,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,
@@ -12311,17 +12734,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,
@@ -12333,7 +12756,7 @@ export {
   DialogFooter,
   DialogTitle,
   DialogDescription,
-} from './dialog.tsx';
+} from './dialog/index.tsx';
 `;
 	const buttonIndexTsx = buttonTsx;
 	const inputIndexTsx = inputTsx;
@@ -12501,8 +12924,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"
@@ -12558,7 +12981,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"],
@@ -12571,12 +12994,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';
 
@@ -12839,10 +13257,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"
 		},
@@ -12910,7 +13328,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: [
@@ -13200,12 +13618,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",
@@ -13245,6 +13678,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",
@@ -13315,12 +13760,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);
@@ -13371,12 +13835,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",
@@ -13442,7 +13943,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 = {
@@ -13457,6 +13958,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
 	};
@@ -13532,12 +14035,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)}`
@@ -13557,8 +14060,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");
@@ -13571,11 +14074,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 {
@@ -13647,19 +14152,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
@@ -13870,19 +14402,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-B5_oHHUj.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",
@@ -14110,7 +14643,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);
@@ -14130,7 +14663,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);
@@ -14202,7 +14735,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);
@@ -14350,7 +14883,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-DdJss8I6.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);
@@ -14379,7 +14912,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-DdJss8I6.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;
@@ -14393,7 +14926,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);
@@ -14401,19 +14934,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-DdJss8I6.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));