genesis-compiler 1.2.1 → 1.2.3

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/
@@ -116,8 +116,13 @@ Genesis never overwrites an unmanaged skill and preserves locally modified
 managed skills. Run `genesis init` after manually editing `genesis/stack.md`,
 or use `genesis stack add`, to synchronize selected skills.
 
-Hosts that create dependency-empty workspaces can call the public
-`inspectWorkspaceSetup()` API. A concrete Stack piece may declare one exact,
+Run `genesis prepare` to execute the selected Stack's exact workspace recipe
+directly with the caller's environment and installed toolchain. It executes
+argument arrays without a shell, honors declared project-relative working
+directories and conditional paths, stops on the first failure, and never
+returns environment values. Hosts that need their own runtime, permission, or
+process policy can instead call the public `inspectWorkspaceSetup()` API and
+execute the same normalized recipe themselves. A concrete Stack piece may declare one exact,
 ordered `## Workspace setup` recipe with labels, argument arrays expressed as
 backticked tokens, abstract runtimes, and optional project-relative working
 directories and readiness paths. A recipe whose declared project marker does
@@ -127,29 +132,56 @@ piece waits for `package.json` and then declares `npm install`; generic
 `genesis/stack.md` replaces all component defaults, including with
 `- Nothing.`. Without that override, exactly one component recipe is used;
 multiple component recipes are reported as ambiguous and never merged.
-Genesis does not run the recipe. Stack resources such as database variables do
-not gate dependency installation.
+The standalone command does not provision declared resources: callers provide
+their own database, credentials, compilers, and other infrastructure. 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 +364,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 +448,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/assurance-model.md

@@ -24,3 +24,18 @@ semantically current, or that passing checks prove the whole product correct.
 
 Git remains the review and recovery boundary. The host running the generated
 prompt owns the agent and its interaction.
+
+## Filesystem ownership
+
+Genesis does not copy package-file ownership or broad source modes into a
+project. It creates ordinary project files with mode `0666`, directories and
+executable skill files with mode `0777`, and lets the invoking process umask
+and the destination directory's inherited ACL establish the effective mode and
+group. Atomic replacements are created beside their destination so they inherit
+the same filesystem policy before becoming visible. Private hook continuation
+state remains explicitly `0600`.
+
+This keeps ordinary single-user projects conventional while allowing a managed
+host to require shared-group writes and no access for other users. The host is
+responsible for establishing and verifying that umask, setgid directory, ACL,
+and cross-identity contract before Genesis or an agent starts.

package/docs/stack-components.md

@@ -24,6 +24,17 @@ What this component contributes.
 
 - `javascript`
 
+## 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`
+
 ## Resources
 
 ```json genesis-resource
@@ -37,6 +48,10 @@ What this component contributes.
 }
 ```
 
+## Environment defaults
+
+- Default `EXAMPLE_DRIVER`: `example`
+
 ## Guidance
 
 ### Technology-specific behavior
@@ -69,6 +84,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 +109,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 +150,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 +173,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 +184,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 +206,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
@@ -186,6 +250,25 @@ may contribute indexers, and duplicates are collapsed. Index output is
 navigation data, not proof that every dynamic callable or framework edge was
 discovered.
 
+`City regions` is an optional complete presentation contract for Machine City.
+Leading `Ignore` entries are canonical project-relative glob patterns using
+only `*` within a path segment and `**` across segments. Genesis excludes their
+matching files before it emits Machine City buildings or functions. This keeps
+test/spec source out of the product City without requiring a host-side filter.
+Each subsequent ordered `Match` entry declares one canonical project-relative
+`path/**` prefix, stable id, and human title. Exactly one final `Fallback` entry
+owns every remaining indexed path. Ignore patterns, ids, and prefixes must be
+unique, prefixes must not overlap, and no more than one selected component may
+declare the contract. Genesis resolves every indexed file and structural
+district to a region and a campus while generating
+`.genesis/machine-city.json`; a City renderer consumes those emitted facts and
+must not reclassify or filter paths. Under a matched prefix, the first directory
+is a campus, while files directly below the prefix belong to the prefix campus.
+Under the fallback, each top-level directory is a campus and project-root files
+belong to the project-root campus. The built-in JSKIT piece excludes exact
+`test`, `tests`, and `__tests__` path segments plus `*.test.*` and `*.spec.*`
+files, then declares `Packages`, `Source`, and `Everything else`.
+
 Do not create a Genesis-owned generic skill merely because a component is
 named `nodejs`, `php`, or another common technology. Official, user, and host
 skills with those names must coexist normally. Use `## Skill` only for an
@@ -230,7 +313,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 +331,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 +343,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:
 
@@ -283,6 +367,20 @@ blocked result.
 The optional environment object is accepted for a consistent host inspection
 boundary, but Workspace setup v1 neither reads nor returns its values.
 
+Standalone users may execute the same normalized recipe with their own
+environment and installed toolchain:
+
+```bash
+genesis prepare
+```
+
+`genesis prepare` runs each declared argv directly without a shell, in order,
+and stops at the first failure. It honors project-relative workdirs and
+conditional paths. It does not provision databases, compilers, credentials,
+runtimes, or other resources. Managed hosts remain free to consume
+`inspectWorkspaceSetup()` and enforce their own execution, identity, runtime,
+and permission policies.
+
 Preview hosts read the normalized Launch contract independently:
 
 ```js
@@ -292,11 +390,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.3",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -56,7 +56,7 @@
     "@ast-grep/lang-ruby": "^0.0.7",
     "@ast-grep/lang-rust": "^0.0.7",
     "@ast-grep/napi": "^0.45.1",
-    "@jskit-ai/agent-docs": "0.1.131",
+    "@jskit-ai/agent-docs": "0.1.132",
     "yaml": "^2.9.0"
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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/cli.js

@@ -11,6 +11,7 @@ import {
   initialize,
   installCodex,
   listStackPieces,
+  prepareWorkspace,
   verify,
 } from './index.js';
 import {
@@ -30,6 +31,7 @@ const USAGE = `Usage:
   genesis stack add <piece...>
   genesis context <path...>
   genesis index [function-or-path...]
+  genesis prepare
   genesis prompt [request...]
   genesis prompt --task <start|work|deslop|program|blueprint|describe|review> [request...]
   genesis verify
@@ -46,7 +48,7 @@ prompt to the agent you already use. Review all edits through the ordinary Git
 diff, then run genesis verify for the Stack's concrete checks.
 `;
 
-const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'hook', 'index', 'init', 'prompt', 'stack', 'verify']);
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'hook', 'index', 'init', 'prepare', 'prompt', 'stack', 'verify']);
 
 function parseCommand(argv) {
   if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
@@ -165,6 +167,19 @@ function writeResult(command, result) {
     line(process.stdout, `index: ${result.status}`);
     return;
   }
+  if (command === 'prepare') {
+    if (result.summary) line(process.stdout, result.summary);
+    namedItems('Commands', result.commands?.map(({ label, argv }) => `${label}: ${argv.join(' ')}`));
+    for (const item of result.diagnostics || []) {
+      line(process.stdout, `${item.code}: ${item.message}`);
+      for (const field of ['stdout', 'stderr']) {
+        const output = item.details?.[field]?.trim();
+        if (output) line(process.stdout, output);
+      }
+    }
+    line(process.stdout, `prepare: ${result.status}`);
+    return;
+  }
   if (command === 'hook') {
     if (['discover', 'session'].includes(result.kind) && result.output) line(process.stdout, result.output);
     else if (result.kind === 'stop') line(process.stdout, JSON.stringify(result.output));
@@ -226,6 +241,14 @@ async function execute({ command, operands, options }) {
   }
   if (command === 'context') return getContext({ paths: operands, projectRoot });
   if (command === 'index') return indexCodebase({ projectRoot, queries: operands });
+  if (command === 'prepare') {
+    return prepareWorkspace({
+      projectRoot,
+      onEvent: (event) => {
+        if (!options.json) line(process.stderr, event.message);
+      },
+    });
+  }
   if (command === 'hook') {
     if (operands[0] === 'discover') {
       return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };

package/src/index/agent-skills.js

@@ -1,13 +1,13 @@
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import {
-  cp,
   lstat,
   mkdir,
   readFile,
   readdir,
   rename,
   rm,
+  writeFile,
 } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -92,7 +92,7 @@ async function skillTree(directory, relative = '') {
     files.push({
       path: child,
       hash: sha256(content),
-      mode: (info.mode & 0o111) === 0 ? 0o100644 : 0o100755,
+      mode: (info.mode & 0o100) === 0 ? 0o100644 : 0o100755,
     });
   }
   return files;
@@ -251,7 +251,7 @@ async function replaceSkill(source, target) {
   await mkdir(path.dirname(target), { recursive: true });
   let replaced = false;
   try {
-    await cp(source, temporary, { recursive: true, errorOnExist: true });
+    await copySkillTree(source, temporary);
     try {
       await rename(target, backup);
       replaced = true;
@@ -271,6 +271,23 @@ async function replaceSkill(source, target) {
   }
 }
 
+async function copySkillTree(source, target) {
+  const info = await lstat(source);
+  if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) {
+    invalidSkill(`Agent Skill contains a non-ordinary entry: ${source}.`);
+  }
+  if (info.isDirectory()) {
+    await mkdir(target, { mode: 0o777 });
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      await copySkillTree(path.join(source, entry.name), path.join(target, entry.name));
+    }
+    return;
+  }
+  const mode = (info.mode & 0o100) === 0 ? 0o666 : 0o777;
+  await writeFile(target, await readFile(source), { flag: 'wx', mode });
+}
+
 function targetFiles(skill) {
   return skill.files.map(({ path: file }) => `${SKILLS_ROOT}/${skill.name}/${file}`);
 }
@@ -304,6 +321,10 @@ export async function syncProjectSkills({ projectRoot, stack } = {}) {
       continue;
     }
     if (installed.hash !== managed.hash) {
+      if (installed.hash === skill.hash) {
+        manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
+        continue;
+      }
       diagnostics.push({
         code: 'AGENT_SKILL_CUSTOMIZED',
         message: `Preserved locally modified Agent Skill ${skill.name}.`,
@@ -388,7 +409,7 @@ export async function inspectProjectSkills({ projectRoot, stack } = {}) {
         message: `Project Agent Skill ${expected.name} is externally managed; Genesis preserved it.`,
         details: { name: expected.name, path: `${SKILLS_ROOT}/${expected.name}/SKILL.md` },
       });
-    } else if (installed.hash !== managed.hash) {
+    } else if (installed.hash !== managed.hash && installed.hash !== expected.hash) {
       customized = true;
       diagnostics.push({
         code: 'AGENT_SKILL_CUSTOMIZED',

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/city-presentation.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+
+function presentationRegionForPath(filePath, regions) {
+  return regions.find((region) => (
+    !region.fallback
+    && (filePath === region.pathPrefix || filePath.startsWith(`${region.pathPrefix}/`))
+  )) || regions.find(({ fallback }) => fallback) || null;
+}
+
+function parentDirectory(filePath) {
+  const parent = path.posix.dirname(filePath);
+  return parent === '.' ? '' : parent;
+}
+
+function presentationCampusPath(filePath, region, { file = false } = {}) {
+  const ownershipPath = file ? parentDirectory(filePath) : filePath;
+  if (!region || region.fallback) {
+    return ownershipPath.split('/').filter(Boolean)[0] || '';
+  }
+  if (ownershipPath === region.pathPrefix) return region.pathPrefix;
+  const relative = ownershipPath.slice(region.pathPrefix.length + 1);
+  const child = relative.split('/').filter(Boolean)[0];
+  return child ? `${region.pathPrefix}/${child}` : region.pathPrefix;
+}
+
+function campusId(regionId, campusPath) {
+  return `presentation-campus:${regionId}:${campusPath || '.'}`;
+}
+
+/** Resolves Stack-declared City regions and campus roots into Machine City facts. */
+export function buildCityPresentation({ districts = [], files = [], regions = [] } = {}) {
+  if (regions.length === 0) {
+    return {
+      campuses: [],
+      placementForPath: () => ({ presentationCampusId: null, presentationRegionId: null }),
+      regions: [],
+    };
+  }
+  const districtsByPath = new Map(districts.map((district) => [district.path, district]));
+  const placements = new Map();
+  const mutableCampuses = new Map();
+  const mutableRegions = new Map(regions.map((region) => [region.id, {
+    ...region,
+    buildingCount: 0,
+  }]));
+
+  function resolvePlacement(filePath = '', { file = false } = {}) {
+    if (placements.has(filePath)) return placements.get(filePath);
+    const region = presentationRegionForPath(filePath, regions);
+    const campusPath = presentationCampusPath(filePath, region, { file });
+    const placement = {
+      presentationCampusId: campusId(region.id, campusPath),
+      presentationRegionId: region.id,
+    };
+    placements.set(filePath, placement);
+    if (!mutableCampuses.has(placement.presentationCampusId)) {
+      mutableCampuses.set(placement.presentationCampusId, {
+        id: placement.presentationCampusId,
+        regionId: region.id,
+        path: campusPath,
+        title: campusPath ? path.posix.basename(campusPath) : 'Project root',
+        districtId: districtsByPath.get(campusPath)?.id || null,
+        buildingCount: 0,
+      });
+    }
+    return placement;
+  }
+
+  for (const file of files) {
+    const placement = resolvePlacement(file.path, { file: true });
+    mutableRegions.get(placement.presentationRegionId).buildingCount += 1;
+    mutableCampuses.get(placement.presentationCampusId).buildingCount += 1;
+  }
+  for (const district of districts) resolvePlacement(district.path);
+
+  return {
+    campuses: [...mutableCampuses.values()]
+      .filter(({ buildingCount }) => buildingCount > 0)
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    placementForPath: (filePath = '') => placements.get(filePath) || resolvePlacement(filePath),
+    regions: [...mutableRegions.values()],
+  };
+}