genesis-compiler 1.2.1 → 1.2.2

package/README.md

@@ -13,7 +13,7 @@ interaction.
 ```text
 genesis/
   blueprint.md       non-technical product intent
-  stack.md           selected technology guidance, checks, setup, and launch data
+  stack.md           selected technology guidance, checks, setup, launch, and deployment data
   stack/             optional per-component Description, Guidance, and Deslop customization
   program/           concise explanations grouped into conceptual subsystems
 .agents/skills/
@@ -131,25 +131,51 @@ Genesis does not run the recipe. Stack resources such as database variables do
 not gate dependency installation.
 
 Hosts that manage project environments can call `inspectEnvironment()`.
+Concrete Stack integrations may declare public, non-secret Environment
+defaults such as the database driver selected by that integration. Explicit
+host or user values take precedence. The built-in JSKIT MySQL and PostgreSQL
+pieces respectively declare `DB_CLIENT=mysql2` and `DB_CLIENT=pg`, so users
+provide connection values rather than restating a deterministic technology
+choice.
 An optional readable `## Environment files` section declares safe
 project-relative dotenv projections such as `.env`. A project declaration
 replaces component defaults, including with `- Nothing.`; otherwise component
-paths compose. Genesis reports resource declarations, value-free missing-input
-diagnostics, and paths. It never returns values, writes files, stores secrets,
-or decides which resolved values a host should materialize.
+paths compose. Genesis reports public defaults, resource declarations,
+value-free missing-input diagnostics, and paths. It never returns supplied
+environment values, writes files, stores secrets, or decides which resolved
+host values should be materialized.
 
 Hosts that provide previews can call the public `inspectLaunch()` API. An
 optional readable `## Launch` section in `genesis/stack.md` declares labeled
 targets, exact backticked argument tokens, relative working directories,
 abstract runtime requirements, `{host}`/`{port}` substitutions, and an optional
 application-owned Preview identity block. Concrete components may provide a
-default: `jskit` declares build followed by `npm start`; generic `nodejs` and
-`php` do not guess. Genesis starts nothing itself. It returns preview identity
+default: `jskit` declares its app-owned `npm run develop` command; generic
+`nodejs` and `php` do not guess. Genesis starts nothing itself. It returns preview identity
 command metadata and environment variable names, never their values. The host
-continues to own pinned runtimes, ports, processes, readiness, identity-command
-execution and secrets, browser binaries, Git, and credentials. See
+continues to own pinned runtimes, ports, processes, readiness probing and
+timeouts, identity-command execution and secrets, browser binaries, Git, and
+credentials. Genesis owns only the exact HTTP readiness predicate declared by
+the selected Stack. See
 [`docs/stack-components.md`](docs/stack-components.md) for the v1 contract.
 
+Hosts that publish applications can call the separate public
+`inspectDeployment()` API. An optional readable `## Deployment` section
+declares an ordered production recipe: project-relative workdir, abstract
+runtimes, exact Prepare/Build/Migrate/Serve argv, and one HTTP readiness
+predicate. A concrete component may provide the recipe; the built-in `jskit`
+piece declares production dependency installation, build, database preparation,
+`npm start`, and `/api/health`. Generic language pieces do not guess. A project
+section replaces component defaults wholesale, and `- Nothing.` explicitly
+disables publishing.
+
+Genesis only validates and reports this recipe and the Stack's abstract resource
+requirements. It does not provision a database, resolve credentials, copy a
+release, run commands, start a service, reserve a port, route traffic, issue TLS,
+or roll back. A deployment host owns all of those operational responsibilities,
+including the mapping from `mysql` or `postgresql` resources to its managed
+services.
+
 At session start, Codex receives only a short explanation of how Genesis is
 organized. After it locates the source involved in a request, it can load the
 specific explanatory and technology context with:
@@ -332,8 +358,11 @@ Run the Stack's declared checks explicitly:
 genesis verify
 ```
 
-Genesis first evaluates generic Stack resource declarations, then runs each
-declared command without a shell. A complete successful run writes only
+Genesis first waits for any technology-declared Workspace setup marker. A
+missing marker is `unconfigured`, not a failed command. Once the workspace
+exists, Genesis applies public Stack defaults beneath explicit environment
+values, evaluates generic resource declarations, and runs each declared
+command without a shell. A complete successful run writes only
 `.genesis/verification.json`, recording:
 
 - the exact Git-visible code hash;
@@ -413,10 +442,10 @@ to execute with its own pinned runtimes, caches, process isolation, and
 credentials. A configured recipe may remain unconfigured while it waits for a
 technology-declared project marker.
 `inspectEnvironment()` returns normalized Stack resource declarations,
-value-free missing-input diagnostics, and dotenv projection paths without
-returning any environment value.
+public non-secret defaults, value-free missing-input diagnostics, and dotenv
+projection paths without returning any supplied environment value.
 `inspectLaunch()` returns a validated, normalized Stack launch declaration for
-a host to execute with its own runtime, port, process, readiness, preview
+a host to execute with its own runtime, port, process, readiness probe, preview
 identity, secret, and browser policy.
 
 A host such as Vibe64 can send the generated prompt to its existing agent:

package/docs/stack-components.md

@@ -37,6 +37,10 @@ What this component contributes.
 }
 ```
 
+## Environment defaults
+
+- Default `EXAMPLE_DRIVER`: `example`
+
 ## Guidance
 
 ### Technology-specific behavior
@@ -69,6 +73,7 @@ What this component contributes.
 - Workdir: `.`
 - Preferred port: `3000`
 - URL path: `/`
+- Ready when: `GET` `/api/health` returns `200`
 - Runtimes: `nodejs`
 - Prepare `Build`: `npm` `run` `build`
 - Serve `Start`: `npm` `run` `server` `--` `--host` `{host}` `--port` `{port}`
@@ -93,7 +98,9 @@ from Genesis or from the declared npm package. Its `SKILL.md`, `references/`,
 Genesis expanding every manual into every prompt. `Resources` declares generic
 alternative environment-name sets reported by prompt generation and checked
 before verification. `allowEmpty` may name a required variable whose empty
-string is valid. `Guidance` is supplemental prose used by work, review, Program,
+string is valid. `Environment defaults` declares public non-secret constants
+owned by a concrete integration; explicit host values take precedence.
+`Guidance` is supplemental prose used by work, review, Program,
 description, and cleanup prompts, as well as path-focused context. `Deslop`
 adds cleanup-only prose to explicit cleanup and the automatic Codex cleanup
 continuation. With no selected component, only the `genesis-deslop` skill
@@ -132,6 +139,16 @@ Precedence is intentionally small and deterministic:
 General Stack resources do not gate Workspace setup. In particular, missing
 database variables do not prevent an otherwise independent dependency install.
 
+Each `Environment defaults` entry is one `Default` bullet with a backticked
+environment name and value. Selected
+component defaults compose by name; identical declarations collapse and
+different values fail rather than silently choosing one. Defaults participate
+in Stack identity, resource preflight, prompt context, Launch inspection, and
+verification execution. The JSKIT database integrations use this contract for
+their deterministic `DB_CLIENT` driver ids; generic database pieces do not.
+Secrets and deployment-specific connection values remain host inputs and must
+never be declared as defaults.
+
 `Environment files` optionally declares project-relative dotenv projections a
 host may materialize from its own resolved project environment. Genesis
 validates and returns only the format and path; it never reads environment
@@ -145,8 +162,9 @@ The declaration is useful independently of Launch and Workspace setup.
 offer a preview without guessing how a concrete technology starts. Repeat a
 ``### Target `id`: label`` block to declare several targets. Default, Workdir,
 Preferred port, URL path, and Runtimes are optional; their normalized defaults
-are false, `.`, null, `/`, and no runtime requirements. Every Prepare or Serve
-command and argument is a separate backticked value returned as an `argv`
+are false, `.`, null, `/`, and no runtime requirements. Every target declares
+one HTTP readiness predicate with a project path and an exact successful status
+from 200 through 399. Every Prepare or Serve command and argument is a separate backticked value returned as an `argv`
 array, never a shell program. A target has exactly one final Serve step; any
 earlier steps must be Prepare steps. Workdir is canonical and project-relative,
 Preferred port is only a hint from 1024 through 65535, and URL path is an
@@ -155,7 +173,8 @@ application path rather than a URL. The only substitutions are `{host}` and
 Launch section to disable component targets.
 
 Genesis validates and reports Launch data but does not select a runtime,
-reserve a port, start a process, decide readiness, or control a browser.
+reserve a port, start a process, probe readiness, or control a browser. The host
+executes the declared predicate and owns its timeout and retry policy.
 
 The optional `#### Preview identity` block is specific to hosts that implement
 the declared `vibe64.preview-identity.command.v1` protocol. Its executable is a
@@ -176,7 +195,41 @@ the ids it supports to its own pinned runtime packs; for example, it may map
 dependencies such as `composer`, or treats an unknown id as something similar.
 Declare each independently required runtime. Generic language pieces such as
 `nodejs` and `php` provide no Launch recipe. A concrete piece such as `jskit`
-may declare one; Genesis does not invent missing targets.
+may declare its app-owned `npm run develop` command; Genesis does not invent
+missing targets or supervise framework-specific subprocesses.
+
+`Deployment` is a separate optional readable production recipe. It must not be
+inferred from Launch because preview preparation and production publication have
+different safety, dependency, migration, artifact, and rollback concerns. Its
+complete form is:
+
+```markdown
+## Deployment
+
+- Workdir: `.`
+- Runtimes: `nodejs`
+- Ready when: `GET` `/api/health` returns `200`
+- Prepare `Install production dependencies`: `npm` `install` `--omit=dev`
+- Build `Build`: `npm` `run` `build`
+- Migrate `Prepare database`: `npm` `run` `db:prepare`
+- Serve `Start`: `npm` `start`
+```
+
+Every command and argument is a separate backticked value returned as an argv
+array; shell source is rejected. Workdir is canonical and project-relative.
+Prepare, Build, and Migrate steps are optional and retain their declared order.
+There is exactly one final Serve step and one exact HTTP readiness predicate
+whose successful status is from 200 through 399. Runtime ids remain abstract.
+
+A project `## Deployment` section replaces every component recipe as one unit,
+including with `- Nothing.`. Without a project section, exactly one selected
+component recipe may apply; several are blocked as ambiguous and never merged.
+Genesis returns the Stack's existing resource declarations with the recipe but
+does not check production values, provision services, execute commands, package
+artifacts, start processes, probe health, route traffic, manage TLS, or retain
+releases. Those are host responsibilities. This keeps the same project portable:
+Genesis alone explains the production requirements, while a host such as Vibe64
+Online can map `mysql` or `postgresql` to a pinned managed service.
 
 `Indexers` selects installed structural adapters for the derived Machine City.
 The shared ast-grep engine owns traversal, bounds, diagnostics, JSON, and
@@ -230,7 +283,7 @@ Replacement component description.
 Each field is optional. `Override` replaces only that installed field; `Add`
 then follows the installed or overridden value. These files cannot alter
 dependencies, conflicts, Agent Skill source, indexers, resources, environment
-files, commands, Workspace setup, or Launch declarations.
+defaults, environment files, commands, Workspace setup, or Launch declarations.
 `genesis stack add` preserves the files and composes their effective prose after
 dependency resolution.
 
@@ -248,8 +301,8 @@ rather than a prompt or controller special case.
 Description, Guidance, Agent Skill, and Deslop prose are instructions, not
 verification evidence. Changes to them do not stale an exact successful
 verification record; selected component ids, resources, environment files,
-Workspace setup, launch targets, and verification commands remain part of the
-Stack identity.
+environment defaults, Workspace setup, launch targets, and verification
+commands remain part of the Stack identity.
 
 Hosts inspect normalized environment requirements independently:
 
@@ -260,9 +313,10 @@ const projectEnvironment = await inspectEnvironment({ environment, projectRoot }
 ```
 
 The result has `status` (`ready`, `missing-inputs`, or `unconfigured`),
-`stackHash`, selected `components`, declared `resources`, value-free
-`diagnostics`, and normalized `files`. Each file contains `format`, `path`, and
-`source`. Environment values never cross this API boundary.
+`stackHash`, selected `components`, public non-secret `environmentDefaults`,
+declared `resources`, value-free `diagnostics`, and normalized `files`. Each default has
+`name`, `value`, and component `sources`; each file contains `format`, `path`,
+and `source`. Supplied environment values never cross this API boundary.
 
 Fresh-workspace hosts read setup from the package root:
 
@@ -292,11 +346,12 @@ const launch = await inspectLaunch({ projectRoot, environment });
 ```
 
 The result has `status` (`ready`, `blocked`, or `unconfigured`), `stackHash`,
-selected `components`, distinct `runtimeRequirements`, declared `resources`,
+selected `components`, public `environmentDefaults`, distinct
+`runtimeRequirements`, declared `resources`,
 normalized `targets`, and resource `diagnostics`. Each target reports its
 `source`, `available`, and `disabledReason`, plus its normalized
-`previewIdentity` declaration when present. Environment values are inspected
-but never returned. Here, `available` means only that the Stack's declared
+`previewIdentity` declaration when present. Supplied environment values are
+inspected but never returned. Here, `available` means only that the Stack's declared
 resource inputs are present: the host must still reject runtime requirements it
 cannot map. `unconfigured` means there are no targets, `blocked` means declared
 resource inputs are missing, and `ready` means neither condition applies. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/prompts/start.txt

@@ -13,6 +13,11 @@ the non-technical Blueprint from the user's answers before implementation.
 If the product direction becomes clear while Stack is still empty, do not end
 the turn after only writing or summarizing the Blueprint: present the relevant
 Stack choices in that same turn and ask the user to select one explicitly.
+This opening turn owns product direction and Stack selection, not final
+verification. Do not run `genesis verify` before implementation has created
+the selected technology's workspace substrate. If structural validation is
+useful, run `genesis check`; treat missing workspace markers as unconfigured,
+not as an implementation failure.
 
 When `projectKind` is `existing`, ask what the user wants to understand or
 change. Use the current Blueprint, Stack, Program, and code index when present.

package/skills/genesis-project/SKILL.md

@@ -48,6 +48,9 @@ Neither is authority or proof; both may be regenerated with `genesis index`.
 
 ## Verify and report
 
-Use `genesis verify` for the Stack's declared final checks. Report files
-changed, checks actually run, and anything still requiring attention. Never
-claim that an unrun check passed or that passing checks prove the whole product.
+After the selected technology's workspace substrate exists, use `genesis
+verify` for the Stack's declared final checks. An unconfigured result means the
+declared workspace or checks do not exist yet; it is not a failing check. Report
+files changed, checks actually run, and anything still requiring attention.
+Never claim that an unrun check passed or that passing checks prove the whole
+product.

package/src/index/check.js

@@ -6,6 +6,7 @@ import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 
 function invalidResult(area, error) {
   return {
@@ -55,7 +56,10 @@ export async function checkProject({ environment = process.env, projectRoot } =
   } catch (error) {
     skills = { status: 'invalid', diagnostics: [asDiagnostic(error)], skills: [] };
   }
-  const missingResources = missingStackResources({ environment, resources: stack.resources });
+  const missingResources = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const verification = await inspectVerification({ projectRoot: root, stack });
   const diagnostics = [
     ...(program.diagnostic ? [program.diagnostic] : []),

package/src/index/deployment.js

@@ -0,0 +1,31 @@
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { sha256, stableJson, uniqueSorted } from './utils.js';
+
+/** Read the Stack's production recipe without provisioning or publishing anything. */
+export async function inspectProjectDeployment({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const diagnostics = [...stack.deployment.diagnostics];
+  let status = 'unconfigured';
+  if (diagnostics.length > 0) status = 'blocked';
+  else if (stack.deployment.steps.length > 0) status = 'ready';
+  const recipe = {
+    version: stack.deployment.version,
+    workdir: stack.deployment.workdir,
+    runtimeRequirements: stack.deployment.runtimeRequirements,
+    readiness: stack.deployment.readiness,
+    steps: stack.deployment.steps,
+  };
+  return {
+    status,
+    stackHash: stack.identityHash,
+    recipeHash: status === 'ready' ? sha256(stableJson(recipe)) : '',
+    components: stack.components.map(({ id }) => id),
+    source: stack.deployment.source,
+    runtimeRequirements: uniqueSorted(stack.deployment.runtimeRequirements),
+    resources: stack.resources,
+    ...recipe,
+    diagnostics,
+  };
+}

package/src/index/environment-files.js

@@ -1,17 +1,24 @@
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 
-/** Inspect Stack environment requirements without returning or writing values. */
+/** Inspect Stack environment requirements without returning supplied host values. */
 export async function inspectProjectEnvironment({ environment = process.env, projectRoot } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = missingStackResources({ environment, resources: stack.resources });
-  const configured = stack.environmentFiles.length > 0 || stack.resources.length > 0;
+  const diagnostics = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
+  const configured = stack.environmentDefaults.length > 0
+    || stack.environmentFiles.length > 0
+    || stack.resources.length > 0;
   return {
     status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),
+    environmentDefaults: stack.environmentDefaults,
     files: stack.environmentFiles,
     resources: stack.resources,
     diagnostics,

package/src/index/launch.js

@@ -1,5 +1,6 @@
 import { gitContext } from './git.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { readStack } from './stack.js';
 import { uniqueSorted } from './utils.js';
 
@@ -10,7 +11,10 @@ export async function inspectProjectLaunch({
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = missingStackResources({ environment, resources: stack.resources });
+  const diagnostics = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const disabledReason = diagnostics.length === 0
     ? null
     : diagnostics.map(({ message }) => message).join(' ');
@@ -26,6 +30,7 @@ export async function inspectProjectLaunch({
     status,
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),
+    environmentDefaults: stack.environmentDefaults,
     runtimeRequirements: uniqueSorted(targets.flatMap((target) => target.runtimeRequirements)),
     resources: stack.resources,
     targets,

package/src/index/prompt.js

@@ -9,6 +9,7 @@ import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { isProjectContentPath } from './paths.js';
@@ -305,7 +306,10 @@ export async function generateProjectPrompt({
     buildProjectIndex({ projectRoot: root, write: false }),
     inspectProjectSkills({ projectRoot: root, stack }),
   ]);
-  const missing = missingStackResources({ environment, resources: stack.resources });
+  const missing = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const warnings = [
     ...(program.diagnostic ? [program.diagnostic] : []),
     ...missing,

package/src/index/stack-catalog.js

@@ -64,6 +64,7 @@ export async function listBuiltinStackPieces() {
       requires: piece.requires,
       conflicts: piece.conflicts,
       indexers: piece.indexers,
+      environmentDefaults: piece.environmentDefaults,
       launchTargets: piece.launchTargets.map(({ id }) => id),
       workspaceSetup: piece.workspaceSetupSteps,
       skill: piece.skill === null ? null : piece.skill.path,

package/src/index/stack-deployment.js

@@ -0,0 +1,204 @@
+import { GenesisError } from './errors.js';
+import {
+  isCanonicalProjectWorkdir,
+  isSafeProcessExecutable,
+  parseBacktickedArguments,
+} from './stack-process.js';
+
+const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const STEP_LINE = /^- (Prepare|Build|Migrate|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u;
+const STEP_ROLE_ORDER = Object.freeze({
+  prepare: 0,
+  build: 1,
+  migrate: 2,
+  serve: 3,
+});
+
+function invalid(deploymentPath, message, line, details = {}) {
+  throw new GenesisError('STACK_DEPLOYMENT_INVALID', message, {
+    path: deploymentPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function oneToken(source, prefix, deploymentPath, label, line) {
+  const values = parseBacktickedArguments(source.slice(prefix.length));
+  if (!values || values.length !== 1) {
+    invalid(deploymentPath, `${label} accepts exactly one backticked value.`, line);
+  }
+  return values[0];
+}
+
+function parseRuntimes(source, deploymentPath, line) {
+  const values = parseBacktickedArguments(source.slice('- Runtimes: '.length));
+  if (!values || values.some((value) => !RUNTIME_ID.test(value))) {
+    invalid(
+      deploymentPath,
+      'Deployment runtimes must be separate backticked technology ids.',
+      line,
+    );
+  }
+  if (new Set(values).size !== values.length) {
+    invalid(deploymentPath, 'Deployment contains a duplicate runtime.', line);
+  }
+  return values;
+}
+
+function parseUrlPath(value, deploymentPath, line) {
+  const normalized = String(value || '').trim();
+  if (!normalized.startsWith('/') || normalized.startsWith('//') || /[\\?#]/u.test(normalized)) {
+    invalid(
+      deploymentPath,
+      'Deployment readiness path must begin with one slash and contain no query or fragment.',
+      line,
+    );
+  }
+  return normalized;
+}
+
+function parseReadiness(source, deploymentPath, line) {
+  const match = source.match(/^- Ready when: `GET` `([^`\r\n]+)` returns `([0-9]{3})`$/u);
+  if (!match) {
+    invalid(
+      deploymentPath,
+      'Deployment readiness must use `- Ready when: `GET` `/path` returns `200``.',
+      line,
+    );
+  }
+  const status = Number(match[2]);
+  if (!Number.isInteger(status) || status < 200 || status > 399) {
+    invalid(deploymentPath, 'Deployment readiness status must be from 200 through 399.', line);
+  }
+  return {
+    kind: 'http',
+    method: 'GET',
+    path: parseUrlPath(match[1], deploymentPath, line),
+    status,
+  };
+}
+
+function parseStep(match, deploymentPath, line) {
+  const label = match[2].trim();
+  const argv = parseBacktickedArguments(match[3]);
+  if (!label || /[\0\r\n]/u.test(label)) {
+    invalid(deploymentPath, 'Deployment step labels must be non-empty single lines.', line);
+  }
+  if (!argv || argv.some((value) => value.includes('\0')) || !isSafeProcessExecutable(argv[0])) {
+    invalid(
+      deploymentPath,
+      'Deployment command and arguments must be separate non-empty backticked values with a safe executable.',
+      line,
+    );
+  }
+  return {
+    label,
+    argv,
+    role: match[1].toLowerCase(),
+  };
+}
+
+export function parseStackDeploymentLines(lines, {
+  path: deploymentPath = 'stack deployment',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return { version: 1, steps: [] };
+
+  const result = {
+    version: 1,
+    workdir: '.',
+    runtimeRequirements: [],
+    readiness: null,
+    steps: [],
+  };
+  const seen = new Set();
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const line = index + 1;
+    if (source.startsWith('- Workdir: ')) {
+      if (seen.has('workdir')) invalid(deploymentPath, 'Duplicate Deployment Workdir.', line);
+      seen.add('workdir');
+      const workdir = oneToken(source, '- Workdir: ', deploymentPath, 'Deployment Workdir', line);
+      if (!isCanonicalProjectWorkdir(workdir)) {
+        invalid(deploymentPath, 'Deployment workdir must be a canonical project-relative directory.', line);
+      }
+      result.workdir = workdir;
+      continue;
+    }
+    if (source.startsWith('- Runtimes: ')) {
+      if (seen.has('runtimes')) invalid(deploymentPath, 'Duplicate Deployment Runtimes.', line);
+      seen.add('runtimes');
+      result.runtimeRequirements = parseRuntimes(source, deploymentPath, line);
+      continue;
+    }
+    if (source.startsWith('- Ready when: ')) {
+      if (seen.has('readiness')) invalid(deploymentPath, 'Duplicate Deployment Ready when.', line);
+      seen.add('readiness');
+      result.readiness = parseReadiness(source, deploymentPath, line);
+      continue;
+    }
+    const step = source.match(STEP_LINE);
+    if (step) {
+      result.steps.push(parseStep(step, deploymentPath, line));
+      continue;
+    }
+    invalid(deploymentPath, `Unknown Deployment entry: ${source}.`, line);
+  }
+  if (result.steps.length === 0) {
+    invalid(deploymentPath, '## Deployment needs at least one command or exactly `- Nothing.`.');
+  }
+  const serveSteps = result.steps.filter(({ role }) => role === 'serve');
+  if (serveSteps.length !== 1 || result.steps.at(-1).role !== 'serve') {
+    invalid(deploymentPath, 'Deployment needs exactly one final Serve step.');
+  }
+  for (let index = 1; index < result.steps.length; index += 1) {
+    if (STEP_ROLE_ORDER[result.steps[index].role] < STEP_ROLE_ORDER[result.steps[index - 1].role]) {
+      invalid(
+        deploymentPath,
+        'Deployment steps must be ordered Prepare, Build, Migrate, then Serve.',
+      );
+    }
+  }
+  if (!result.readiness) {
+    invalid(deploymentPath, 'Deployment needs one Ready when entry.');
+  }
+  return result;
+}
+
+export function composeStackDeployment(components, projectDeployment) {
+  if (projectDeployment) return { ...projectDeployment, source: 'project', diagnostics: [] };
+  const declarations = components
+    .filter((component) => component.deployment?.steps?.length > 0)
+    .map((component) => ({
+      ...component.deployment,
+      source: `component:${component.id}`,
+    }));
+  if (declarations.length === 0) {
+    return {
+      version: 1,
+      workdir: '.',
+      runtimeRequirements: [],
+      readiness: null,
+      steps: [],
+      source: null,
+      diagnostics: [],
+    };
+  }
+  if (declarations.length === 1) return { ...declarations[0], diagnostics: [] };
+  const sources = declarations.map(({ source }) => source).sort();
+  return {
+    version: 1,
+    workdir: '.',
+    runtimeRequirements: [],
+    readiness: null,
+    steps: [],
+    source: null,
+    diagnostics: [{
+      code: 'STACK_DEPLOYMENT_AMBIGUOUS',
+      message: `Selected Stack components provide competing Deployment recipes: ${sources.join(', ')}. Add one project ## Deployment section to choose the exact recipe.`,
+      details: { sources },
+    }],
+  };
+}

package/src/index/stack-environment-defaults.js

@@ -0,0 +1,79 @@
+import { GenesisError } from './errors.js';
+
+const DEFAULT_LINE = /^- Default `([A-Za-z_][A-Za-z0-9_]*)`: `([^`\r\n]+)`[ \t]*$/u;
+
+function invalid(defaultsPath, message, line, details = {}) {
+  throw new GenesisError('STACK_ENVIRONMENT_DEFAULTS_INVALID', message, {
+    path: defaultsPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+export function parseStackEnvironmentDefaultLines(lines, {
+  path: defaultsPath = 'stack environment defaults',
+} = {}) {
+  if (lines === undefined) return [];
+  const defaults = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const entry = source.match(DEFAULT_LINE);
+    if (!entry) {
+      invalid(
+        defaultsPath,
+        'Every Environment defaults entry must be a Default bullet with a backticked name and value.',
+        index + 1,
+        { observed: source },
+      );
+    }
+    defaults.push({ name: entry[1], value: entry[2] });
+  }
+  if (defaults.length === 0) {
+    invalid(defaultsPath, '## Environment defaults needs at least one Default entry.');
+  }
+  if (new Set(defaults.map(({ name }) => name)).size !== defaults.length) {
+    invalid(defaultsPath, '## Environment defaults contains a duplicate name.');
+  }
+  return defaults;
+}
+
+export function composeStackEnvironmentDefaults(components) {
+  const defaults = new Map();
+  for (const component of components) {
+    for (const declaration of component.environmentDefaults) {
+      const existing = defaults.get(declaration.name);
+      if (existing && existing.value !== declaration.value) {
+        invalid(
+          `component:${component.id}`,
+          `Stack components declare incompatible defaults for ${declaration.name}.`,
+          undefined,
+          {
+            name: declaration.name,
+            sources: [...existing.sources, `component:${component.id}`],
+          },
+        );
+      }
+      if (existing) {
+        existing.sources.push(`component:${component.id}`);
+      } else {
+        defaults.set(declaration.name, {
+          ...declaration,
+          sources: [`component:${component.id}`],
+        });
+      }
+    }
+  }
+  return [...defaults.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/** Apply public Stack constants beneath explicit host or user environment. */
+export function withStackEnvironmentDefaults(environment, defaults = []) {
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)) {
+    throw new TypeError('Stack environment resolution requires an environment object.');
+  }
+  return {
+    ...Object.fromEntries(defaults.map(({ name, value }) => [name, value])),
+    ...environment,
+  };
+}

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,7 @@
 import { GenesisError } from './errors.js';
 import { parseStackCommandLines } from './stack-command.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 +220,10 @@ 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 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 +231,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 +249,10 @@ export function parseStackPieceSource(value, {
     skill: skill(all, piecePath),
     resources: resources(all, piecePath),
     commands: commands.map(({ line: _line, ...command }) => command),
+    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,11 @@ import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
 import { readBuiltinStackCatalog } from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.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 +34,7 @@ const STACK_SECTIONS = new Set([
   'Environment files',
   'Workspace setup',
   'Commands',
+  'Deployment',
   'Launch',
 ]);
 const STACK_CUSTOMIZATION_ROOT = 'genesis/stack';
@@ -97,6 +102,7 @@ function withoutOuterBlankLines(lines = []) {
 function renderStack({
   commandLines = [],
   componentIds: componentIdsValue,
+  deploymentLines = null,
   environmentFileLines = null,
   launchLines = null,
   workspaceSetupLines = null,
@@ -114,6 +120,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 +161,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 +176,7 @@ export async function addStackPieces({ pieces, projectRoot }) {
   const rendered = renderStack({
     commandLines,
     componentIds: selected,
+    deploymentLines,
     environmentFileLines,
     launchLines,
     workspaceSetupLines,
@@ -250,6 +265,7 @@ export async function readStack(projectRoot) {
   const componentCommands = components.flatMap((piece) => piece.commands);
   const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
   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 +276,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 },
@@ -270,15 +291,19 @@ export async function readStack(projectRoot) {
     identityHash: sha256(stableJson({
       components: components.map(({ id }) => id),
       commands: commands.map(({ label, argv }) => ({ label, argv })),
+      environmentDefaults,
       environmentFiles,
       launchTargets,
+      deployment,
       resources,
       workspaceSetup,
     })),
     components,
     commands,
+    environmentDefaults,
     environmentFiles,
     launchTargets,
+    deployment,
     workspaceSetup,
     resources,
     guidance: composedProse(components, 'guidance'),
@@ -295,8 +320,10 @@ export function stackPromptContext(stack) {
       requires: piece.requires,
     })),
     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/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

@@ -5,16 +5,22 @@ import { gitContext } from './git.js';
 import { readStack } from './stack.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);
+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 +42,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 +53,18 @@ 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 });
+}

package/src/index.js

@@ -7,6 +7,7 @@ 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';
@@ -77,6 +78,10 @@ export function inspectEnvironment(options) {
   return inspectProjectEnvironment(options);
 }
 
+export function inspectDeployment(options) {
+  return inspectProjectDeployment(options);
+}
+
 export function inspectWorkspaceSetup(options) {
   return inspectProjectWorkspaceSetup(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,6 +30,7 @@ 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
 
@@ -42,21 +43,30 @@ generated files, and runtime composition.
 - Default.
 - Preferred port: `3000`
 - URL path: `/`
+- Ready when: `GET` `/api/health` returns `200`
 - Runtimes: `nodejs`
-- Prepare `Build`: `npm` `run` `build`
+- Serve `Develop`: `npm` `run` `develop`
+
+## Deployment
+
+- Runtimes: `nodejs`
+- 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.