genesis-compiler 1.2.1 → 1.2.3

package/src/index/stack-launch.js

@@ -118,6 +118,7 @@ function targetDraft(match, launchPath, line) {
     workdir: '.',
     preferredPort: null,
     urlPath: '/',
+    readiness: null,
     runtimeRequirements: [],
     steps: [],
     previewIdentity: null,
@@ -126,6 +127,27 @@ function targetDraft(match, launchPath, line) {
   };
 }
 
+function parseReadiness(source, launchPath, line) {
+  const match = source.match(/^- Ready when: `GET` `([^`\r\n]+)` returns `([0-9]{3})`$/u);
+  if (!match) {
+    invalid(
+      launchPath,
+      'Launch target readiness must use `- Ready when: `GET` `/path` returns `200``.',
+      line,
+    );
+  }
+  const status = Number(match[2]);
+  if (!Number.isInteger(status) || status < 200 || status > 399) {
+    invalid(launchPath, 'Launch target readiness status must be from 200 through 399.', line);
+  }
+  return {
+    kind: 'http',
+    method: 'GET',
+    path: parseUrlPath(match[1], launchPath, line),
+    status,
+  };
+}
+
 function parsePreferredPort(value, launchPath, line) {
   if (!/^[0-9]+$/u.test(value)) {
     invalid(launchPath, 'Launch target preferred port must be an integer from 1024 through 65535.', line);
@@ -204,6 +226,17 @@ function parseTargetLine(draft, source, launchPath, line) {
     );
     return;
   }
+  if (source.startsWith('- Ready when: ')) {
+    setOnce(
+      draft,
+      'readiness',
+      parseReadiness(source, launchPath, line),
+      launchPath,
+      line,
+      'Launch target Ready when entry',
+    );
+    return;
+  }
   const step = source.match(/^- (Prepare|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u);
   if (step) {
     draft.steps.push({
@@ -336,6 +369,9 @@ function normalizeTarget(draft, launchPath) {
   if (serverSteps.length !== 1 || draft.steps.at(-1).role !== 'server') {
     invalid(launchPath, `Launch target ${draft.id} needs exactly one final Serve step.`, draft.line);
   }
+  if (!draft.readiness) {
+    invalid(launchPath, `Launch target ${draft.id} needs one Ready when entry.`, draft.line);
+  }
   return {
     id: draft.id,
     label: draft.label,
@@ -343,6 +379,7 @@ function normalizeTarget(draft, launchPath) {
     workdir: draft.workdir,
     preferredPort: draft.preferredPort,
     urlPath: draft.urlPath,
+    readiness: draft.readiness,
     runtimeRequirements: draft.runtimeRequirements,
     steps: draft.steps,
     ...(draft.previewIdentity

package/src/index/stack-piece.js

@@ -1,5 +1,8 @@
 import { GenesisError } from './errors.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { parseStackCityPresentationLines } from './stack-city-presentation.js';
+import { parseStackDeploymentLines } from './stack-deployment.js';
+import { parseStackEnvironmentDefaultLines } from './stack-environment-defaults.js';
 import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
 import { parseStackLaunchLines } from './stack-launch.js';
 import { parseStackWorkspaceSetupLines } from './stack-workspace-setup.js';
@@ -218,6 +221,14 @@ export function parseStackPieceSource(value, {
   const deslop = textSection(all, 'Deslop');
   if (!description) invalid(piecePath, 'Stack piece needs Description.');
   const commands = parseStackCommandLines(all.get('Commands') || [], { path: piecePath });
+  const cityPresentation = parseStackCityPresentationLines(
+    all.has('City regions') ? all.get('City regions') : undefined,
+    { path: piecePath },
+  );
+  const environmentDefaults = parseStackEnvironmentDefaultLines(
+    all.has('Environment defaults') ? all.get('Environment defaults') : undefined,
+    { path: piecePath },
+  );
   const environmentFiles = parseStackEnvironmentFileLines(
     all.has('Environment files') ? all.get('Environment files') : undefined,
     { path: piecePath },
@@ -225,6 +236,10 @@ export function parseStackPieceSource(value, {
   const launch = parseStackLaunchLines(all.has('Launch') ? all.get('Launch') : undefined, {
     path: piecePath,
   });
+  const deployment = parseStackDeploymentLines(
+    all.has('Deployment') ? all.get('Deployment') : undefined,
+    { path: piecePath },
+  );
   const workspaceSetup = parseStackWorkspaceSetupLines(
     all.has('Workspace setup') ? all.get('Workspace setup') : undefined,
     { path: piecePath },
@@ -239,8 +254,12 @@ export function parseStackPieceSource(value, {
     skill: skill(all, piecePath),
     resources: resources(all, piecePath),
     commands: commands.map(({ line: _line, ...command }) => command),
+    cityExclusions: cityPresentation.exclusions,
+    cityRegions: cityPresentation.regions,
+    environmentDefaults,
     environmentFiles: environmentFiles || [],
     launchTargets: launch?.targets || [],
+    deployment,
     workspaceSetupSteps: workspaceSetup || [],
     deslop,
   };

package/src/index/stack-workspace-setup.js

@@ -8,6 +8,7 @@ import {
 const PREPARE_LINE = /^- Prepare `([^`\r\n]+)` with (.+?):[ \t]+(.+)$/u;
 const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const READY_WHEN_SUFFIX = /^(.*?)[ \t]+when `([^`\r\n]+)` exists$/u;
+const OPTIONAL_WHEN_SUFFIX = /^(.*?)[ \t]+if `([^`\r\n]+)` exists$/u;
 const WORKDIR_SUFFIX = /^(.*?)[ \t]+in `([^`\r\n]+)`$/u;
 
 function invalid(setupPath, message, line, details = {}) {
@@ -59,7 +60,7 @@ export function parseStackWorkspaceSetupLines(lines, {
     if (!entry) {
       invalid(
         setupPath,
-        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`] [when `path` exists]: `command` `argument`...`.',
+        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`] [when|if `path` exists]: `command` `argument`...`.',
         line,
         { observed: source },
       );
@@ -69,9 +70,11 @@ export function parseStackWorkspaceSetupLines(lines, {
       invalid(setupPath, 'Workspace setup labels must be non-empty single lines.', line);
     }
     const readyEntry = entry[2].match(READY_WHEN_SUFFIX);
-    const setupSource = readyEntry ? readyEntry[1] : entry[2];
+    const optionalEntry = readyEntry ? null : entry[2].match(OPTIONAL_WHEN_SUFFIX);
+    const setupSource = readyEntry ? readyEntry[1] : optionalEntry ? optionalEntry[1] : entry[2];
     const readyWhen = readyEntry ? readyEntry[2] : '';
-    if (readyWhen && (readyWhen === '.' || !isCanonicalProjectWorkdir(readyWhen))) {
+    const runWhen = optionalEntry ? optionalEntry[2] : '';
+    if ((readyWhen || runWhen) && ((readyWhen || runWhen) === '.' || !isCanonicalProjectWorkdir(readyWhen || runWhen))) {
       invalid(
         setupPath,
         'Workspace setup readiness paths must be canonical project-relative paths.',
@@ -98,6 +101,7 @@ export function parseStackWorkspaceSetupLines(lines, {
       runtimeRequirements: parseRuntimeRequirements(runtimeSource, setupPath, line),
       workdir,
       ...(readyWhen ? { readyWhen } : {}),
+      ...(runWhen ? { runWhen } : {}),
     });
   }
   if (steps.length === 0) {

package/src/index/stack.js

@@ -5,7 +5,12 @@ import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
 import { readBuiltinStackCatalog } from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { composeStackCityPresentation } from './stack-city-presentation.js';
+import { composeStackDeployment, parseStackDeploymentLines } from './stack-deployment.js';
 import { resolveStackPieces } from './stack-composition.js';
+import {
+  composeStackEnvironmentDefaults,
+} from './stack-environment-defaults.js';
 import {
   composeStackEnvironmentFiles,
   parseStackEnvironmentFileLines,
@@ -30,6 +35,7 @@ const STACK_SECTIONS = new Set([
   'Environment files',
   'Workspace setup',
   'Commands',
+  'Deployment',
   'Launch',
 ]);
 const STACK_CUSTOMIZATION_ROOT = 'genesis/stack';
@@ -97,6 +103,7 @@ function withoutOuterBlankLines(lines = []) {
 function renderStack({
   commandLines = [],
   componentIds: componentIdsValue,
+  deploymentLines = null,
   environmentFileLines = null,
   launchLines = null,
   workspaceSetupLines = null,
@@ -114,6 +121,9 @@ function renderStack({
       : ['', '## Workspace setup', '', ...withoutOuterBlankLines(workspaceSetupLines)]),
     ...(commandLines.length > 0 ? ['', '## Commands', ...commandLines] : []),
     ...(launchLines === null ? [] : ['', '## Launch', '', ...withoutOuterBlankLines(launchLines)]),
+    ...(deploymentLines === null
+      ? []
+      : ['', '## Deployment', '', ...withoutOuterBlankLines(deploymentLines)]),
     '',
   ].join('\n');
 }
@@ -152,6 +162,11 @@ export async function addStackPieces({ pieces, projectRoot }) {
   );
   const launchLines = sections.has('Launch') ? sections.get('Launch') : null;
   parseStackLaunchLines(launchLines === null ? undefined : launchLines, { path: STACK_PATH });
+  const deploymentLines = sections.has('Deployment') ? sections.get('Deployment') : null;
+  parseStackDeploymentLines(
+    deploymentLines === null ? undefined : deploymentLines,
+    { path: STACK_PATH },
+  );
   const workspaceSetupLines = sections.has('Workspace setup')
     ? sections.get('Workspace setup')
     : null;
@@ -162,6 +177,7 @@ export async function addStackPieces({ pieces, projectRoot }) {
   const rendered = renderStack({
     commandLines,
     componentIds: selected,
+    deploymentLines,
     environmentFileLines,
     launchLines,
     workspaceSetupLines,
@@ -249,7 +265,9 @@ export async function readStack(projectRoot) {
   ).map(({ line: _line, ...command }) => command);
   const componentCommands = components.flatMap((piece) => piece.commands);
   const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
+  const cityPresentation = composeStackCityPresentation(components);
   const resources = resourceDeclarations(components);
+  const environmentDefaults = composeStackEnvironmentDefaults(components);
   const projectEnvironmentFiles = parseStackEnvironmentFileLines(
     sections.has('Environment files') ? sections.get('Environment files') : undefined,
     { path: STACK_PATH },
@@ -260,6 +278,11 @@ export async function readStack(projectRoot) {
     { path: STACK_PATH },
   );
   const launchTargets = composeStackLaunchTargets(components, projectLaunch);
+  const projectDeployment = parseStackDeploymentLines(
+    sections.has('Deployment') ? sections.get('Deployment') : undefined,
+    { path: STACK_PATH },
+  );
+  const deployment = composeStackDeployment(components, projectDeployment);
   const projectWorkspaceSetup = parseStackWorkspaceSetupLines(
     sections.has('Workspace setup') ? sections.get('Workspace setup') : undefined,
     { path: STACK_PATH },
@@ -269,16 +292,24 @@ export async function readStack(projectRoot) {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
       components: components.map(({ id }) => id),
+      cityExclusions: cityPresentation.exclusions,
+      cityRegions: cityPresentation.regions,
       commands: commands.map(({ label, argv }) => ({ label, argv })),
+      environmentDefaults,
       environmentFiles,
       launchTargets,
+      deployment,
       resources,
       workspaceSetup,
     })),
     components,
+    cityExclusions: cityPresentation.exclusions,
+    cityRegions: cityPresentation.regions,
     commands,
+    environmentDefaults,
     environmentFiles,
     launchTargets,
+    deployment,
     workspaceSetup,
     resources,
     guidance: composedProse(components, 'guidance'),
@@ -294,9 +325,13 @@ export function stackPromptContext(stack) {
       ...(piece.guidance ? { guidance: piece.guidance } : {}),
       requires: piece.requires,
     })),
+    cityExclusions: stack.cityExclusions,
+    cityRegions: stack.cityRegions,
     verifyCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
+    environmentDefaults: stack.environmentDefaults,
     environmentFiles: stack.environmentFiles,
     launchTargets: stack.launchTargets,
+    deployment: stack.deployment,
     workspaceSetup: stack.workspaceSetup,
   };
 }

package/src/index/utils.js

@@ -29,7 +29,7 @@ export function uniqueSorted(values = []) {
   return [...new Set(values)].sort();
 }
 
-export async function writeFileAtomic(filePath, source, { mode = 0o644 } = {}) {
+export async function writeFileAtomic(filePath, source, { mode = 0o666 } = {}) {
   const temporary = `${filePath}.${randomUUID()}.tmp`;
   await mkdir(path.dirname(filePath), { recursive: true });
   try {

package/src/index/verification.js

@@ -2,8 +2,10 @@ import { runProcess } from './process.js';
 import { asDiagnostic } from './errors.js';
 import { gitContext } from './git.js';
 import { clearVerification, writeVerification } from './project-state.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 import { readStack } from './stack.js';
+import { inspectWorkspaceSetupForStack } from './workspace-setup.js';
 
 async function emit(onEvent, event) {
   try { await onEvent?.(event); } catch { /* Progress observers do not control verification. */ }
@@ -17,7 +19,34 @@ export async function verifyProject({
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const missing = missingStackResources({ environment, resources: stack.resources });
+  const workspaceSetup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+  if (workspaceSetup.status === 'blocked') {
+    return {
+      status: 'blocked',
+      summary: workspaceSetup.diagnostics.map(({ message }) => message).join(' '),
+      commands: [],
+      diagnostics: workspaceSetup.diagnostics,
+    };
+  }
+  const waiting = workspaceSetup.diagnostics.filter(
+    ({ code }) => code === 'STACK_WORKSPACE_SETUP_WAITING',
+  );
+  if (waiting.length > 0) {
+    return {
+      status: 'unconfigured',
+      summary: waiting.map(({ message }) => message).join(' '),
+      commands: [],
+      diagnostics: waiting,
+    };
+  }
+  const resolvedEnvironment = withStackEnvironmentDefaults(
+    environment,
+    stack.environmentDefaults,
+  );
+  const missing = missingStackResources({
+    environment: resolvedEnvironment,
+    resources: stack.resources,
+  });
   if (missing.length > 0) {
     return {
       status: 'blocked',
@@ -47,6 +76,7 @@ export async function verifyProject({
       });
       await processRunner(command.argv[0], command.argv.slice(1), {
         cwd: root,
+        env: resolvedEnvironment,
         maxBytes: 32 * 1024 * 1024,
         code: 'VERIFICATION_FAILED',
       });

package/src/index/workspace-setup.js

@@ -1,20 +1,33 @@
 import { access } from 'node:fs/promises';
 import path from 'node:path';
 
+import { asDiagnostic } from './errors.js';
 import { gitContext } from './git.js';
+import { runProcess } from './process.js';
 import { readStack } from './stack.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
 
-/** Read the Stack's workspace preparation recipe without executing it. */
-export async function inspectProjectWorkspaceSetup({
-  projectRoot,
-} = {}) {
-  const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+async function emit(onEvent, event) {
+  try { await onEvent?.(event); } catch { /* Progress observers do not control preparation. */ }
+}
+
+export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }) {
   const diagnostics = [...stack.workspaceSetup.diagnostics];
+  const applicableSteps = [];
   if (diagnostics.length === 0) {
     const waitingFor = [];
     for (const step of stack.workspaceSetup.steps) {
+      if (step.runWhen) {
+        try {
+          await access(path.join(root, step.runWhen));
+          applicableSteps.push(step);
+        } catch (error) {
+          if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+        }
+        continue;
+      }
+      applicableSteps.push(step);
       if (!step.readyWhen) continue;
       try {
         await access(path.join(root, step.readyWhen));
@@ -36,9 +49,9 @@ export async function inspectProjectWorkspaceSetup({
   const blocked = diagnostics.some(({ code }) => code !== 'STACK_WORKSPACE_SETUP_WAITING');
   let status = 'unconfigured';
   if (blocked) status = 'blocked';
-  else if (!waiting && stack.workspaceSetup.steps.length > 0) status = 'ready';
+  else if (!waiting && applicableSteps.length > 0) status = 'ready';
   const recipeHash = status === 'ready'
-    ? sha256(stableJson({ version: 1, steps: stack.workspaceSetup.steps }))
+    ? sha256(stableJson({ version: 1, steps: applicableSteps }))
     : '';
   return {
     status,
@@ -47,9 +60,87 @@ export async function inspectProjectWorkspaceSetup({
     components: stack.components.map(({ id }) => id),
     source: stack.workspaceSetup.source,
     runtimeRequirements: uniqueSorted(
-      stack.workspaceSetup.steps.flatMap((step) => step.runtimeRequirements),
+      applicableSteps.flatMap((step) => step.runtimeRequirements),
     ),
-    steps: stack.workspaceSetup.steps,
+    steps: applicableSteps,
     diagnostics,
   };
 }
+
+/** Read the Stack's workspace preparation recipe without executing it. */
+export async function inspectProjectWorkspaceSetup({
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  return inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+}
+
+/** Execute the selected Stack's exact workspace recipe with the caller's environment. */
+export async function prepareProjectWorkspace({
+  environment = process.env,
+  onEvent,
+  processRunner = runProcess,
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const setup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+  if (setup.status !== 'ready') {
+    const summary = setup.diagnostics.map(({ message }) => message).join(' ')
+      || 'The selected Stack declares no applicable workspace preparation commands.';
+    return {
+      ...setup,
+      summary,
+      commands: [],
+    };
+  }
+
+  const resolvedEnvironment = withStackEnvironmentDefaults(
+    environment,
+    stack.environmentDefaults,
+  );
+  const commands = [];
+  try {
+    for (const step of setup.steps) {
+      await emit(onEvent, {
+        type: 'genesis.workspace-preparation',
+        code: 'WORKSPACE_PREPARATION_STARTED',
+        message: `Preparing: ${step.label}.`,
+        details: { label: step.label, argv: step.argv, workdir: step.workdir },
+      });
+      await processRunner(step.argv[0], step.argv.slice(1), {
+        cwd: path.resolve(root, step.workdir),
+        env: resolvedEnvironment,
+        maxBytes: 32 * 1024 * 1024,
+        code: 'WORKSPACE_PREPARATION_FAILED',
+      });
+      commands.push({
+        label: step.label,
+        argv: step.argv,
+        workdir: step.workdir,
+      });
+      await emit(onEvent, {
+        type: 'genesis.workspace-preparation',
+        code: 'WORKSPACE_PREPARATION_COMPLETED',
+        message: `Prepared: ${step.label}.`,
+        details: { label: step.label, argv: step.argv, workdir: step.workdir },
+      });
+    }
+    return {
+      ...setup,
+      status: 'passed',
+      summary: `Prepared the workspace with ${commands.length} command${commands.length === 1 ? '' : 's'}.`,
+      commands,
+      diagnostics: [],
+    };
+  } catch (error) {
+    return {
+      ...setup,
+      status: 'failed',
+      summary: error.message,
+      commands,
+      diagnostics: [asDiagnostic(error)],
+    };
+  }
+}

package/src/index.js

@@ -7,11 +7,15 @@ import { generateProjectPrompt } from './index/prompt.js';
 import { initializeProject } from './index/init.js';
 import { installCodexPlugin } from './index/codex-plugin.js';
 import { inspectProjectEnvironment } from './index/environment-files.js';
+import { inspectProjectDeployment } from './index/deployment.js';
 import { inspectProjectLaunch } from './index/launch.js';
 import { listBuiltinStackPieces } from './index/stack-catalog.js';
 import { addStackPieces } from './index/stack.js';
 import { verifyProject } from './index/verification.js';
-import { inspectProjectWorkspaceSetup } from './index/workspace-setup.js';
+import {
+  inspectProjectWorkspaceSetup,
+  prepareProjectWorkspace,
+} from './index/workspace-setup.js';
 
 function withIndexResult(result, index) {
   const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
@@ -77,10 +81,18 @@ export function inspectEnvironment(options) {
   return inspectProjectEnvironment(options);
 }
 
+export function inspectDeployment(options) {
+  return inspectProjectDeployment(options);
+}
+
 export function inspectWorkspaceSetup(options) {
   return inspectProjectWorkspaceSetup(options);
 }
 
+export function prepareWorkspace(options) {
+  return prepareProjectWorkspace(options);
+}
+
 export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }

package/stacks/pieces/jskit-mysql.md

@@ -13,6 +13,10 @@ JSKIT MySQL runtime, live-schema CRUD generation, and persistence conventions.
 
 - `jskit-postgresql`
 
+## Environment defaults
+
+- Default `DB_CLIENT`: `mysql2`
+
 ## Resources
 
 ```json genesis-resource
@@ -24,7 +28,7 @@ JSKIT MySQL runtime, live-schema CRUD generation, and persistence conventions.
       "required": ["DATABASE_URL"]
     },
     {
-      "required": ["DB_CLIENT", "DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
+      "required": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
       "allowEmpty": ["DB_PASSWORD"]
     }
   ]

package/stacks/pieces/jskit-postgresql.md

@@ -13,6 +13,10 @@ JSKIT PostgreSQL runtime, live-schema CRUD generation, and persistence conventio
 
 - `jskit-mysql`
 
+## Environment defaults
+
+- Default `DB_CLIENT`: `pg`
+
 ## Resources
 
 ```json genesis-resource
@@ -24,7 +28,7 @@ JSKIT PostgreSQL runtime, live-schema CRUD generation, and persistence conventio
       "required": ["DATABASE_URL"]
     },
     {
-      "required": ["DB_CLIENT", "DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
+      "required": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
       "allowEmpty": ["DB_PASSWORD"]
     }
   ]

package/stacks/pieces/jskit.md

@@ -2,8 +2,8 @@
 
 ## Description
 
-JSKIT application creation, package generators, Vue surfaces, app-owned
-generated files, and runtime composition.
+AI-first JSKIT runtime capabilities, tested source patterns, Vue surfaces, and
+application-owned composition.
 
 ## Requires
 
@@ -18,7 +18,7 @@ generated files, and runtime composition.
 
 - Before creating or modifying JSKIT Vue/Vuetify UI, load the installed
   `jskit` Agent Skill and read its `references/material-3.md` completely.
-- Implement Material 3 through JSKIT generators, shared screens, shell and
+- Implement Material 3 through JSKIT patterns, shared screens, shell and
   placement seams, app-owned theme configuration, and supported Vuetify APIs.
 - Use geometry-preserving Material skeletons for all user-visible loading;
   never use a generic spinner or circular progress indicator, or let content
@@ -30,11 +30,23 @@ generated files, and runtime composition.
 ## Workspace setup
 
 - Prepare `Install dependencies` with `nodejs` when `package.json` exists: `npm` `install`
+- Prepare `Prepare database` with `nodejs` if `scripts/prepare-database.js` exists: `npm` `run` `db:prepare`
 
 ## Environment files
 
 - Dotenv `.env`
 
+## City regions
+
+- Ignore `**/test/**`
+- Ignore `**/tests/**`
+- Ignore `**/__tests__/**`
+- Ignore `**/*.test.*`
+- Ignore `**/*.spec.*`
+- Match `packages` as `Packages`: `packages/**`
+- Match `source` as `Source`: `src/**`
+- Fallback `everything-else` as `Everything else`
+
 ## Launch
 
 ### Target `app`: Run app
@@ -42,21 +54,30 @@ generated files, and runtime composition.
 - Default.
 - Preferred port: `3000`
 - URL path: `/`
+- Ready when: `GET` `/api/health` returns `200`
+- Runtimes: `nodejs`
+- Serve `Develop`: `npm` `run` `develop`
+
+## Deployment
+
 - Runtimes: `nodejs`
-- Prepare `Build`: `npm` `run` `build`
+- Ready when: `GET` `/api/health` returns `200`
+- Prepare `Install dependencies`: `npm` `install`
+- Build `Build`: `npm` `run` `build`
+- Migrate `Prepare database`: `npm` `run` `db:prepare`
 - Serve `Start`: `npm` `start`
 
 ## Deslop
 
 - For every affected JSKIT screen, load the installed `jskit` Agent Skill,
   read `references/material-3.md`, and execute its Material 3 audit.
-- Use JSKIT generators, packages, resources, composables, screens, and
-  placement seams instead of parallel framework plumbing.
-- Treat generated output as app-owned and customizable. Adapt routes,
-  placements, and infrastructure tests coherently; when replacing a starter
+- Use JSKIT patterns, packages, resources, composables, screens, and placement
+  seams instead of parallel framework plumbing.
+- Treat copied pattern source as app-owned and customizable. Adapt routes,
+  placements, and infrastructure tests coherently; when replacing a foundation
   route, update its baseline browser coverage instead of deleting it.
 - Consolidate repeated validation, pending/error state, API access, and page
-  behavior at the generated shared resource or established JSKIT seam.
+  behavior at the shared resource or established JSKIT seam.
 - Replace transient command-error alerts that shift page content with the
   established JSKIT action feedback/snackbar seam; preserve stable in-page
   resource-load errors, retry states, and field validation.