genesis-compiler 1.2.2 → 1.2.4

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

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

package/prompts/adopt.txt

@@ -0,0 +1,62 @@
+Read and follow `.agents/skills/genesis-project/SKILL.md` and
+`.agents/skills/genesis-program/SKILL.md` completely.
+
+This is an existing-project adoption turn. Import the codebase's factual
+product and operational contracts into Genesis without changing application
+behavior. The user has already approved adoption; do not ask them to approve
+Genesis again or require them to understand Genesis terminology.
+
+Application source, dependencies, migrations, runtime behavior, and deployment
+files are read-only in this turn. You may edit `genesis/blueprint.md`,
+`genesis/stack.md`, explanatory Markdown below `genesis/program/`, and
+Genesis-managed skills/indexes produced by `genesis stack add` or Genesis
+inspection commands. Do not install dependencies, prepare a database, run
+migrations or seeds, start a server, deploy, or add compatibility code.
+
+If Stack has no components, inspect direct evidence such as manifests,
+lockfiles, build files, entrypoints, package scripts, tests, configuration,
+database and migration code, and existing project-tool metadata. Record only
+technologies the implementation already uses with `genesis stack add
+<piece...>`; this is factual import, not a new-technology choice. Ask a concise
+product-language question only when evidence is genuinely ambiguous. Then run
+`genesis prompt --task adopt "Continue the approved existing-project import."`
+and follow the regenerated prompt so every selected Stack piece contributes its
+Adoption requirements.
+
+Read every selected technology skill named by the regenerated prompt and its
+relevant existing-application migration reference. Apply all SELECTED STACK
+ADOPTION GUIDANCE. Component defaults describe current foundations and are
+hypotheses until they match this source. They do not upgrade an older project.
+
+Build one evidence-backed import inventory covering, where applicable:
+
+- package manager, install/build commands, runtimes, workdirs, and generated
+  prerequisites;
+- environment files, public defaults, required resources, and alternative
+  environment names, without reading or returning secret values;
+- database engine, migration ownership and ledger, preparation command,
+  idempotent seed behavior, and fresh versus existing-database safety;
+- every long-running target's exact argv, host/port placeholders, URL path,
+  readiness predicate, and shutdown ownership;
+- application-owned Preview identity helper, protocol, supported selectors,
+  environment names, runtime, and timeout when authenticated preview exists;
+- concrete verification commands, browser-test assumptions, and deployment
+  preparation/build/migration/serve/readiness declarations.
+
+Translate observed contracts into exact project-owned Stack sections whenever
+the selected components' defaults differ. A project section replaces the
+component declaration for that concern, so it must be complete. Inspect retired
+or tool-specific manifests as evidence and carry every still-valid fact into
+Genesis; never add a permanent legacy reader or shim. Do not delete an old
+manifest until all of its live facts have been accounted for.
+
+Create the non-technical Blueprint and useful subsystem-oriented Program from
+current source and tests. Do not cite archive internals or Git object storage as
+implementation source; Program sources must be current Git-visible files.
+
+Run `genesis check` only for structural validation. Missing environment values,
+workspace markers, commands, helpers, seeds, or readiness evidence are honest
+import findings, not permission to invent or execute them. Finish with a clear
+inventory of what was imported, what remains unconfigured or blocked, and what
+would require a separately approved implementation port. Never claim the
+project is ready merely because Stack components were selected.

package/prompts/start.txt

@@ -23,12 +23,25 @@ When `projectKind` is `existing`, ask what the user wants to understand or
 change. Use the current Blueprint, Stack, Program, and code index when present.
 If the existing implementation is not yet explained, recommend the Genesis
 description/adoption path instead of pretending its intent is known.
+When an existing implementation has no selected Stack yet, inspect its actual
+package scripts, build files, setup commands, server entrypoint, and readiness
+route before recording the user's technology choice. Component Workspace setup
+and Launch declarations describe that component's current foundation; selecting
+the component does not port an older implementation to it. If the existing
+commands differ, add exact project-owned `## Workspace setup` and `## Launch`
+sections that replace the component defaults and match the code that exists.
+Never report the inherited setup or Launch as usable merely because the
+component was selected, and never add compatibility implementation without the
+user asking for a port.
 
 When `projectKind` is `existing-uninitialized`, ask what the user wants to
-understand or change and strongly recommend `genesis adopt` before substantial
-work. Explain that adoption preserves the implementation and prepares the
-Blueprint and Program prompt. Do not run it without the user's approval. If the
-user declines, continue normally and do not repeat the recommendation.
+understand or change and strongly recommend preparing the existing project for
+guided editing before substantial work. Explain in product language that this
+preserves the implementation while importing its current setup, run, database,
+preview, verification, and product context. Do not require the user to know
+Genesis terminology or type a command. If they approve, run `genesis adopt`
+yourself and follow its adoption prompt. If they decline, continue normally and
+do not repeat the recommendation.
 
 If the request already contains an unambiguous product description and an
 explicit Stack choice, you may apply that choice and establish the Blueprint.

package/prompts/work.txt

@@ -10,7 +10,7 @@ and reuse an existing function when it already owns the behavior.
 This is the implementation turn. Do not edit the Blueprint, Program, or
 `.genesis/`; the separate reconciliation turn owns explanatory changes. Keep an
 exact Stack `## Launch` declaration aligned when the implementation establishes
-or intentionally changes how the project is started or how Vibe64 may request
+or intentionally changes how the project is started or how a preview host may request
 an application preview identity. Declare only command paths, protocol, supported
 identity types, environment variable names, runtimes, and timeout policy; never
 put an environment value or secret in Stack. Never invent missing external-resource

package/skills/genesis-project/SKILL.md

@@ -21,6 +21,14 @@ codebase, tests, Git review, or the coding agent.
 6. Load applicable technology skills from `.agents/skills/` or from the
    agent's own installed skill catalog.
 
+For an existing application's first Stack selection, inspect its real setup,
+build, and launch commands before relying on component defaults. A selected
+component describes its current foundation; it does not silently port older
+source. When the existing commands differ, keep the implementation unchanged
+and declare exact project-owned `## Workspace setup` and `## Launch` overrides.
+Do not claim the inherited component recipe is usable until it matches the
+source.
+
 Program is concise, fallible explanation. Its Sources and optional
 Implementation maps aid navigation but never substitute for reading code,
 tests, and runtime behavior.
@@ -36,7 +44,7 @@ Neither is authority or proof; both may be regenerated with `genesis index`.
 - Do not edit the Blueprint, Program, or `.genesis/` during implementation; the
   separate reconciliation turn owns explanatory updates. Keep an exact Stack
   `## Launch` declaration aligned when the implementation establishes or
-  intentionally changes how the project is started or how Vibe64 may request
+  intentionally changes how the project is started or how a preview host may request
   an application preview identity. Record only capability metadata and
   environment variable names there, never environment values or secrets.
 - Follow established project and technology seams instead of creating parallel

package/src/cli.js

@@ -9,8 +9,13 @@ import {
   getContext,
   indexCodebase,
   initialize,
+  inspectDeployment,
+  inspectEnvironment,
+  inspectLaunch,
+  inspectWorkspaceSetup,
   installCodex,
   listStackPieces,
+  prepareWorkspace,
   verify,
 } from './index.js';
 import {
@@ -30,8 +35,10 @@ const USAGE = `Usage:
   genesis stack add <piece...>
   genesis context <path...>
   genesis index [function-or-path...]
+  genesis inspect <workspace|environment|launch|deployment>
+  genesis prepare
   genesis prompt [request...]
-  genesis prompt --task <start|work|deslop|program|blueprint|describe|review> [request...]
+  genesis prompt --task <start|adopt|work|deslop|program|blueprint|describe|review> [request...]
   genesis verify
   genesis check
 
@@ -46,7 +53,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', 'inspect', 'prepare', 'prompt', 'stack', 'verify']);
 
 function parseCommand(argv) {
   if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
@@ -94,9 +101,16 @@ function parseCommand(argv) {
     }
   } else if (command === 'context' && operands.length === 0) {
     fail('CONTEXT_PATH_REQUIRED', 'Command context requires at least one project path.');
+  } else if (command === 'inspect') {
+    if (operands.length !== 1 || !['workspace', 'environment', 'launch', 'deployment'].includes(operands[0])) {
+      fail(
+        'CLI_INSPECT_TARGET_REQUIRED',
+        'Command inspect requires exactly one of: workspace, environment, launch, deployment.',
+      );
+    }
   } else if (command === 'hook' && (operands.length !== 1 || !['begin', 'discover', 'end', 'session', 'stop'].includes(operands[0]))) {
     fail('CLI_HOOK_ACTION_REQUIRED', 'Command hook requires exactly one of: discover, session, begin, stop, end.');
-  } else if (!['adopt', 'context', 'hook', 'index', 'prompt'].includes(command) && operands.length > 0) {
+  } else if (!['adopt', 'context', 'hook', 'index', 'inspect', 'prompt'].includes(command) && operands.length > 0) {
     fail('CLI_EXTRA_ARGUMENT', `Command ${command} accepts no arguments.`);
   }
   return { command, operands, options };
@@ -126,6 +140,31 @@ function writeCheck(result) {
   line(process.stdout, `Check: ${result.status}`);
 }
 
+function writeInspection(result) {
+  const title = result.inspection[0].toUpperCase() + result.inspection.slice(1);
+  line(process.stdout, `${title}: ${result.status}`);
+  namedItems('Components', result.components);
+  namedItems('Runtimes', result.runtimeRequirements);
+  if (result.inspection === 'workspace') {
+    namedItems('Preparation steps', result.steps.map(({ label, argv, workdir }) => (
+      `${label} in ${workdir}: ${argv.join(' ')}`
+    )));
+  } else if (result.inspection === 'environment') {
+    namedItems('Public defaults', result.environmentDefaults.map(({ name, value }) => `${name}=${value}`));
+    namedItems('Environment files', result.files.map(({ format, path: filePath }) => `${format}: ${filePath}`));
+  } else if (result.inspection === 'launch') {
+    namedItems('Targets', result.targets.map(({ id, label, urlPath, steps }) => (
+      `${id} (${label}) ${urlPath}: ${steps.map(({ argv }) => argv.join(' ')).join(' -> ')}`
+    )));
+  } else {
+    namedItems('Deployment steps', result.steps.map(({ label, argv }) => `${label}: ${argv.join(' ')}`));
+  }
+  namedItems('Resources', result.resources.map(({ component, resource }) => (
+    `${resource.id} (${resource.kind}, ${component})`
+  )));
+  for (const item of result.diagnostics || []) line(process.stdout, `${item.code}: ${item.message}`);
+}
+
 function writeResult(command, result) {
   if (command === 'prompt') {
     process.stdout.write(result.prompt.endsWith('\n') ? result.prompt : `${result.prompt}\n`);
@@ -165,6 +204,23 @@ function writeResult(command, result) {
     line(process.stdout, `index: ${result.status}`);
     return;
   }
+  if (command === 'inspect') {
+    writeInspection(result);
+    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 +282,23 @@ async function execute({ command, operands, options }) {
   }
   if (command === 'context') return getContext({ paths: operands, projectRoot });
   if (command === 'index') return indexCodebase({ projectRoot, queries: operands });
+  if (command === 'inspect') {
+    const inspections = {
+      workspace: inspectWorkspaceSetup,
+      environment: inspectEnvironment,
+      launch: inspectLaunch,
+      deployment: inspectDeployment,
+    };
+    return { inspection: operands[0], ...await inspections[operands[0]]({ projectRoot }) };
+  }
+  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/assets.js

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 const root = new URL('../../', import.meta.url);
 const assets = {
   start: new URL('prompts/start.txt', root),
+  adopt: new URL('prompts/adopt.txt', root),
   work: new URL('prompts/work.txt', root),
   describe: new URL('prompts/describe.txt', root),
   reconcile: new URL('prompts/reconcile.txt', root),

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()],
+  };
+}

package/src/index/code-index.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 
 import { astGrepCodeIndexers } from './code-indexers/ast-grep.js';
 import { asDiagnostic } from './errors.js';
+import { buildCityPresentation } from './city-presentation.js';
+import { cityPathExcluded } from './stack-city-presentation.js';
 import { gitContext } from './git.js';
 import { isProjectContentPath } from './paths.js';
 import { inspectProgram } from './program.js';
@@ -128,8 +130,14 @@ function mergeIndexedFiles(contributions) {
   };
 }
 
-function machineCity({ components, contributions, diagnostics, indexers }) {
+function machineCity({ cityRegions, components, contributions, diagnostics, indexers }) {
   const merged = mergeIndexedFiles(contributions);
+  const structuralDistricts = directoryRecords(merged.files.map(({ path: filePath }) => filePath));
+  const presentation = buildCityPresentation({
+    districts: structuralDistricts,
+    files: merged.files,
+    regions: cityRegions,
+  });
   const visibility = new Map(merged.functions.map((entry) => [entry.id, entry.visibility]));
   const codeHash = sha256(stableJson(merged.files.map(({ path: filePath, hash, mode }) => ({
     path: filePath,
@@ -141,13 +149,19 @@ function machineCity({ components, contributions, diagnostics, indexers }) {
     schemaVersion: 1,
     status: indexers.length === 0 ? 'unconfigured' : diagnostics.length > 0 ? 'completed-with-warning' : 'current',
     codeHash,
+    presentationRegions: presentation.regions,
+    presentationCampuses: presentation.campuses,
     stackComponents: components,
     indexers,
     diagnostics,
     functions: merged.functions,
-    districts: directoryRecords(merged.files.map(({ path: filePath }) => filePath)),
+    districts: structuralDistricts.map((district) => ({
+      ...district,
+      ...presentation.placementForPath(district.path),
+    })),
     buildings: merged.files.map((file) => ({
       ...file,
+      ...presentation.placementForPath(file.path),
       districtId: directoryId(parentDirectory(file.path)),
       title: path.posix.basename(file.path),
       publicFunctionCount: file.functionIds.filter((id) => visibility.get(id) === 'public').length,
@@ -229,7 +243,13 @@ export async function buildProjectIndex({ projectRoot, queries = [], write = tru
   const stack = await readStack(root);
   const states = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
   const files = [...states]
-    .filter(([, state]) => state.exists && !state.symlink && !state.special && state.hash)
+    .filter(([filePath, state]) => (
+      state.exists
+      && !state.symlink
+      && !state.special
+      && state.hash
+      && !cityPathExcluded(filePath, stack.cityExclusions)
+    ))
     .map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
   const indexers = [...new Set(stack.components.flatMap((component) => component.indexers || []))].sort();
   const contributions = [];
@@ -249,6 +269,7 @@ export async function buildProjectIndex({ projectRoot, queries = [], write = tru
     }
   }
   const machine = machineCity({
+    cityRegions: stack.cityRegions,
     components: stack.components.map(({ id }) => id),
     contributions,
     diagnostics,

package/src/index/codex-hooks.js

@@ -156,8 +156,9 @@ export async function codexAdoptionRecommendation({ projectRoot = process.cwd()
     output: [
       'IMPORTANT GENESIS RECOMMENDATION:',
       'This existing project has no Genesis explanatory layer.',
-      'In your first response, strongly recommend that the user run `genesis adopt` before substantial work.',
-      '`genesis adopt` preserves the implementation and returns the prompt for creating its initial Blueprint and Program.',
+      'In your first response, strongly recommend preparing this existing project for guided editing before substantial work.',
+      'Explain in product language that preparation preserves the implementation while importing its current operational and product context. Do not require the user to know Genesis terminology or type a command.',
+      'If the user approves, run `genesis adopt` yourself and follow the returned adoption prompt.',
       'Do not run it without the user\'s approval. If they agree, run it and follow the returned prompt in this conversation.',
       'If the user declines, continue normally and do not repeat the recommendation in this session.',
     ].join('\n'),

package/src/index/init.js

@@ -12,7 +12,7 @@ async function createIfMissing(projectRoot, relativePath, source) {
   const location = path.join(projectRoot, relativePath);
   await mkdir(path.dirname(location), { recursive: true });
   try {
-    await writeFile(location, source, { flag: 'wx', mode: 0o644 });
+    await writeFile(location, source, { flag: 'wx', mode: 0o666 });
     return relativePath;
   } catch (error) {
     if (error?.code === 'EEXIST') return null;

package/src/index/prompt.js

@@ -14,9 +14,10 @@ import { stableJson } from './utils.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { isProjectContentPath } from './paths.js';
 
-const TASKS = new Set(['start', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
+const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
   start: 'Start a conversation about this project.',
+  adopt: 'Import the existing project into a truthful Genesis project contract.',
   work: 'Implement the product intent expressed by the current Blueprint.',
   deslop: 'Simplify the current Git-visible work without making unrelated changes.',
   program: 'Refresh the complete useful Program for the code that exists now.',
@@ -97,6 +98,7 @@ function renderPrompt({
   skills = '',
   guidance = '',
   cleanup = '',
+  adoption = '',
 }) {
   return [
     instructions.trim(),
@@ -111,12 +113,58 @@ function renderPrompt({
     stableJson(context).trimEnd(),
     '```',
     ...(guidance ? ['', 'SELECTED STACK GUIDANCE', '', guidance] : []),
+    ...(adoption ? ['', 'SELECTED STACK ADOPTION GUIDANCE', '', adoption] : []),
     ...(skills ? ['', 'AVAILABLE AGENT SKILLS', '', skills] : []),
     ...(cleanup ? ['', 'SELECTED STACK CLEANUP GUIDANCE', '', cleanup] : []),
     '',
   ].join('\n');
 }
 
+async function generateAdoptionPrompt({ environment, instructions, program, request, root }) {
+  const blueprint = await readBlueprint(root, { required: true });
+  const [stack, index, catalog] = await Promise.all([
+    readStack(root),
+    buildProjectIndex({ projectRoot: root, write: false }),
+    listBuiltinStackPieces(),
+  ]);
+  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
+  const missing = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
+  return {
+    status: 'ready',
+    task: 'adopt',
+    prompt: renderPrompt({
+      instructions,
+      request,
+      context: {
+        task: 'adopt',
+        projectRoot: root,
+        projectKind: 'existing',
+        blueprint: { path: blueprint.path, source: blueprint.source },
+        stack: stackPromptContext(stack),
+        availableStackPieces: stackCatalogContext(catalog),
+        program: programContext(program),
+        resourceInputs: missing.length > 0
+          ? { status: 'missing', diagnostics: missing }
+          : { status: 'present' },
+        codeIndex: codeIndexContext(index),
+      },
+      guidance: stack.guidance,
+      adoption: stack.adoption,
+      skills: renderAgentSkillCatalog(projectSkills.skills),
+    }),
+    warnings: [
+      ...(program.diagnostic ? [program.diagnostic] : []),
+      ...missing,
+      ...projectSkills.diagnostics,
+      ...index.diagnostics,
+    ],
+    verificationCommands: [],
+  };
+}
+
 async function generateExplanationPrompt({ instructions, program, request, root, task }) {
   const blueprint = await readBlueprint(root, {
     required: true,
@@ -268,6 +316,15 @@ export async function generateProjectPrompt({
       root,
     });
   }
+  if (task === 'adopt') {
+    return generateAdoptionPrompt({
+      environment,
+      instructions,
+      program,
+      request: userRequest,
+      root,
+    });
+  }
   let stack;
   if (task === 'work') {
     try {

package/src/index/stack-catalog.js

@@ -61,8 +61,11 @@ export async function listBuiltinStackPieces() {
       id: piece.id,
       description: piece.description,
       guidance: piece.guidance,
+      adoption: piece.adoption,
       requires: piece.requires,
       conflicts: piece.conflicts,
+      cityExclusions: piece.cityExclusions,
+      cityRegions: piece.cityRegions,
       indexers: piece.indexers,
       environmentDefaults: piece.environmentDefaults,
       launchTargets: piece.launchTargets.map(({ id }) => id),