genesis-compiler 1.2.27 → 1.2.28

package/README.md

@@ -8,6 +8,16 @@ user request into a complete prompt for the coding agent you already use.
 Genesis outputs text. The agent or host you already use owns execution and
 interaction.
 
+The useful mental model is:
+
+- **Genesis describes** the product, selected technology, project operations,
+  existing code, and checks.
+- **Your coding agent implements** the application and follows the prompts
+  Genesis returns.
+- **The relevant tool or host executes** setup, run, preview, deployment, and
+  other consumer-owned operations. Genesis itself executes only the commands
+  explicitly listed under `## Verification`.
+
 ## Project files
 
 ```text
@@ -15,7 +25,7 @@ genesis/
   version            project-file format version used for deterministic migrations
   blueprint.md       non-technical product intent
   engineering.md     selected engineering profile and project-specific requirements
-  stack.md           selected technology guidance, verification, declarations, and opaque extensions
+  stack.md           selected components, resources, verification, and project-owned operation contracts
   stack/             optional per-component Description, Guidance, Adoption, Post-change, and Deslop customization
   program/           concise explanations grouped into conceptual subsystems
 .agents/skills/
@@ -50,7 +60,7 @@ prove it current. Program omits incidental framework glue, generated files,
 tests, fixtures, and migrations. It is useful documentation, not proof that it
 completely or correctly explains the implementation.
 
-## Start
+## Quick start
 
 Genesis requires Node.js 22 or newer and Git.
 
@@ -66,6 +76,67 @@ The catalog is static Markdown and contains the complete curated set of
 language, database, UI, and framework pieces. A host may supply another catalog
 through the same contract.
 
+### Try a new project with Codex or OpenCode
+
+Create an ordinary empty Git repository:
+
+```bash
+mkdir genesis-jskit-test
+cd genesis-jskit-test
+git init
+genesis init
+```
+
+Start Codex or OpenCode in that directory. For a useful discovery test, begin
+with a deliberately incomplete request:
+
+> I want to build something with JSKIT.
+
+The agent should not start surveying frameworks or creating source. It should
+first ask what is being built, who or what will use it, and the first useful
+observable outcome. When it recognizes `jskit` in the live Stack catalog, it
+should ask before adding it.
+
+For a faster end-to-end test, give it the important product facts directly:
+
+> Build a private contact manager with JSKIT and MySQL. Signed-in people can
+> create, edit, search, and delete their own contacts. The first useful outcome
+> is registering, signing in, and saving one contact.
+
+The agent should propose the matching Stack selection and wait for confirmation.
+After you answer yes, it should run `genesis stack add`, receive the preparation
+prompt as command output, and continue that prompt in the same task. There is no
+synthetic follow-up turn.
+
+If you prefer to drive the CLI yourself, the equivalent shortest selection is:
+
+```bash
+genesis stack list
+genesis stack add jskit-mysql
+```
+
+`jskit-mysql` brings in its declared dependencies: `mysql`, `jskit`, and
+`nodejs`. The second command changes `genesis/stack.md`, synchronizes any
+component-declared Agent Skills, and prints one preparation prompt. Genesis
+does not execute that prompt or start an AI. Paste it into your agent if you ran
+the command yourself; if the agent ran the command, it already has the output.
+
+Review the resulting source and contracts, then inspect and verify them:
+
+```bash
+git diff
+genesis check
+genesis inspect environment
+genesis inspect section Outputs
+genesis verify
+```
+
+`check` reports structure and recorded evidence. `verify` runs only the finite
+commands recorded under the project's `## Verification` section; neither
+command claims that the whole product is correct.
+
+### Adopt an existing codebase
+
 For an existing codebase, `adopt` is the direct entry point:
 
 ```bash
@@ -82,15 +153,9 @@ Blueprint and Program. Give it to the agent already working in the repository.
 Adoption edits Genesis metadata only; implementation modernization remains a
 separate, explicitly approved port. “Adopt” never moves the project.
 
-For a new or empty project, initialize first and write the product intent:
-
-```bash
-cd my-project
-git init                         # if needed
-genesis init
-vi genesis/blueprint.md
-codex
-```
+You may write `genesis/blueprint.md` yourself, but normal new-project use can
+let the opening conversation establish it from your answers before source is
+created.
 
 Codex users may also install Genesis's optional discovery plugin once:
 
@@ -114,12 +179,17 @@ and project-local guidance adapters for Codex and OpenCode. The skills are ordin
 and `genesis-deslop`, each with standard `SKILL.md` and `agents/openai.yaml`
 metadata. Open `/hooks` once in Codex to review and trust the guidance hook;
 OpenCode discovers its local project plugin automatically. Both use the same
-Genesis-owned operating guide for new sessions and after compaction. No
-technology is assumed until you explicitly select Stack components:
+Genesis-owned operating guide for new sessions and after compaction. When the
+optional first-party catalog is installed beside Genesis, that guide includes
+only its current component ids. If a named technology exactly matches an
+unselected component, the agent asks before selecting it, then loads its Stack
+context and any skill it declares. No technology is assumed until you confirm
+Stack selection:
 
 ```bash
-genesis stack add --stack-package genesis-stack nodejs
-# or: genesis stack add --stack-package genesis-stack jskit jskit-mysql
+genesis stack add nodejs
+# or, with dependencies resolved automatically:
+genesis stack add jskit-mysql
 ```
 
 Genesis does not install substitute generic `nodejs`, `vue`, `php`, or similar
@@ -141,6 +211,32 @@ 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.
 
+## Commands at a glance
+
+| Command | What it does |
+| --- | --- |
+| `genesis init` | Initializes Genesis files, workflow skills, code indexes, and local Codex/OpenCode guidance in a new or current-format project. It selects no technology. |
+| `genesis adopt [guidance...]` | Initializes an existing codebase and prints the prompt for describing its real product and operational contracts without moving or modernizing source. |
+| `genesis codex install` | Installs the optional Codex discovery plugin that recommends adoption for nonempty projects without Genesis. |
+| `genesis engineering list` | Lists the installed engineering profiles. |
+| `genesis engineering show [profile]` | Shows one profile, or the current project profile when omitted. |
+| `genesis engineering set <profile>` | Records the selected engineering profile while preserving project-specific requirements. |
+| `genesis stack list` | Lists technology components from the installed Stack catalog. |
+| `genesis stack add <piece...>` | Resolves component dependencies/conflicts, records the selection, materializes missing project contracts, synchronizes declared skills, and prints the one-time preparation prompt. It does not install application packages or run an agent. |
+| `genesis context <path...>` | Returns path-focused Program explanations, indexed functions, selected technology guidance, exact project contracts, and relevant skills. |
+| `genesis index [function-or-path...]` | Regenerates the derived code indexes and optionally searches the existing function/method inventory. |
+| `genesis inspect environment` | Reports declared resources, public defaults, missing input names, and environment-file paths without returning secret values. |
+| `genesis inspect section <name>` | Returns one exact consumer-owned Stack section without interpreting or executing it. |
+| `genesis prompt [request...]` | Generates the ordinary implementation prompt. Use `--task` for opening, adoption, Deslop, explanation, review, and other explicit prompt tasks. |
+| `genesis verify` | Executes only the ordered finite commands in `## Verification` and records exact evidence. |
+| `genesis check` | Performs a read-only structural check of project format, Blueprint, Stack, skills, Program, resources, and verification evidence. |
+| `genesis migrate` | Advances recognized older Genesis project files deterministically and refreshes managed skills, hooks, and indexes. |
+
+Project-scoped options follow the command, for example
+`genesis check --project-root /path/to/project`. Commands support `--json` when
+a host or script needs the normalized result. Run `genesis --help` for the
+compact CLI synopsis.
+
 ## Engineering approach
 
 Every profile inherits one universal rule: implementation must remain easy to
@@ -190,30 +286,35 @@ approach. A project upgraded from an older Genesis release safely uses
 records the file.
 
 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 catalog's 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.
-A project may instead declare complete `## Resources` and
-`## Environment defaults` sections in `genesis/stack.md`; their presence
-replaces component declarations so an imported C++, PHP, Python, or older
-application keeps its own real names and public constants.
+Concrete Stack integrations may propose public, non-secret Environment
+defaults such as the database driver selected by that integration. `genesis
+stack add` copies those proposals into the project's `## Environment defaults`
+contract; explicit host or user values still take precedence. The catalog's
+JSKIT MySQL and PostgreSQL pieces propose `DB_CLIENT=mysql2` and
+`DB_CLIENT=pg`. Laravel database integrations also propose their conventional
+connection, host, port, database, and username while leaving passwords and
+other secrets unset.
+A project may edit its complete `## Resources` and `## Environment defaults`
+sections in `genesis/stack.md` so an imported C++, PHP, Python, older, or
+deliberately customized application keeps its real names and public constants.
 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 public defaults, resource declarations,
+project-relative dotenv projections such as `.env`. Selection materializes
+the component proposal once, after which the project declaration is
+authoritative and may use `- Nothing.`. 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.
 
-Consumers may define additional `##` sections in a project or component Stack.
-Genesis composes each section by name, includes its exact text in Stack identity
-and prompt context, and exposes it through `inspectStackSection()`. The body is
-opaque: Genesis does not parse its commands, infer its purpose, or execute it.
-A project section replaces a component default of the same name; competing
-component declarations are reported mechanically instead of merged.
+Consumers may define additional `##` sections in a project Stack, while Stack
+components may propose initial bodies for them. Selection materializes each
+unambiguous proposal into `genesis/stack.md` and returns one preparation prompt
+that asks the current agent to make every heading true. Existing project
+sections are preserved and identified for evidence-based review. Thereafter
+the exact project text is durable across catalog upgrades, participates in
+Stack identity and prompt context, and is exposed through
+`inspectStackSection()`. The body is opaque: Genesis does not parse its
+commands, infer its purpose, or execute it. Competing proposals are reported
+mechanically unless the project already records its decision.
 
 This is the boundary for every consumer-specific operation. The consumer that
 names a section owns its schema, validation, runtime mapping, execution, and
@@ -249,6 +350,19 @@ genesis index normalizeNote
 genesis index src/notes
 ```
 
+This is not merely a README suggestion. The new-session and post-compaction
+guide, generated work prompts, and the installed `genesis-project` skill tell
+the agent to run `genesis context` after locating relevant source and to run
+`genesis index` before adding another helper or public operation. Genesis
+cannot force a model to obey a prompt, so this is not a hidden command gate.
+The delivered prompt is tested, and the transcript plus ordinary Git review
+remain the way to confirm that a particular agent followed it.
+
+`genesis index` answers a structural question—what indexed functions or methods
+already exist by name or path. It does not prove semantic equivalence. The
+agent must still inspect the implementation and direct call sites before
+reusing or consolidating behavior.
+
 `genesis index` regenerates two deterministic projections. Machine City is the
 detailed physical view: indexed files, line and byte weights, public and
 internal functions or methods, signatures, source/test role, language, and
@@ -280,6 +394,44 @@ amending history. Genesis supplies the behavior-preserving boundary and Git
 scope rules. Selected Stack components add technology-specific Deslop guidance
 without weakening or broadening that contract.
 
+### Deslop committed work
+
+Inside Codex, OpenCode, or another skill-aware coding agent, ask directly:
+
+```text
+Deslop
+Deslop the last 5 commits
+Deslop commit a1b2c3d
+```
+
+The installed `genesis-deslop` skill generates the canonical project prompt
+once when the request was not already generated by Genesis. It follows that
+prompt in the same agent turn; it does not start another agent or create a
+synthetic follow-up turn.
+
+For a host integration, shell workflow, or agent without automatic skill
+selection, generate the same complete prompt explicitly:
+
+```bash
+genesis prompt --task deslop
+genesis prompt --task deslop "Deslop the last 5 commits"
+genesis prompt --task deslop "Deslop commit a1b2c3d"
+```
+
+Give the printed prompt to the coding agent that has access to the repository.
+Genesis packages four relevant layers: the explicit scope request; the
+portable behavior-preserving contract from `genesis-deslop`; the selected
+engineering approach; and the effective `Deslop` prose from every selected
+Stack component. Project additions or overrides from
+`genesis/stack/<component>.md` are applied before that Stack prose is composed.
+The main `genesis/stack.md` records component selection and durable project
+operations; it intentionally does not duplicate installed guidance bodies.
+
+Deslop refuses to mix cleanup with an existing dirty worktree. Its result is a
+normal uncommitted diff for review and a later commit. It never amends the
+selected commit, silently fixes newly discovered defects, or runs as an
+automatic completion phase.
+
 Projects can customize a selected technology through its matching file, such
 as `genesis/stack/jskit.md`:
 
@@ -363,10 +515,11 @@ genesis prompt --task review                        # compare intent, code, and
 
 The eight task types are deliberately explicit:
 
-- `start` opens the project conversation. For a new project it asks what the
-  app is about, presents relevant choices from the live Stack catalog, and
-  waits for the person to select technology. For an existing project it asks
-  what the person wants to understand or change.
+- `start` opens the project conversation. For a new project it establishes what
+  is being built, who or what will use or invoke it, and the first useful
+  observable outcome before presenting relevant choices from the live Stack
+  catalog. A partial reply resolves only what it explicitly answers. For an
+  existing project it asks what the person wants to understand or change.
 - `adopt` imports an existing application's factual operational and product
   contracts into Genesis metadata. It composes technology-specific Adoption
   requirements from the selected Stack and does not change application code.
@@ -398,19 +551,77 @@ object.
 List and select pieces from the installed optional catalog:
 
 ```bash
-genesis stack list --stack-package genesis-stack
-genesis stack add --stack-package genesis-stack jskit jskit-mysql
+genesis stack list
+genesis stack add jskit jskit-mysql
 ```
 
-The explicit package flag bootstraps an unconfigured project. Once a Stack
-selection records `genesis-stack` in `genesis/stack.md`, ordinary commands use
-that recorded package directly; `genesis stack list` needs no host flag.
+### What `stack add` actually does
+
+`genesis stack add` is deterministic project preparation, not an application
+installer. It:
+
+1. reads the explicitly installed Stack catalog;
+2. resolves requested components, declared dependencies, and conflicts;
+3. records the owning Stack package and complete resolved component selection;
+4. copies every missing operation proposal into `genesis/stack.md` as a
+   project-owned contract;
+5. synchronizes any authoritative Agent Skill explicitly declared by those
+   components; and
+6. prints one heading-by-heading preparation prompt.
+
+That final prompt asks the current agent to make the materialized contracts
+true: create the necessary source and scripts for a new project, or replace a
+complete project section when existing source proves that a proposal is wrong.
+Genesis does not execute the prompt. If the agent ran `stack add`, the prompt is
+already visible as its command result and the Genesis project instructions tell
+it to continue in the same task. If a person ran the command, they give the
+printed prompt to their agent. Repeating an already-complete selection prints no
+second preparation prompt.
+
+`stack add` itself does **not** run `npm install`, Composer, CMake, a database
+migration, a development server, or deployment. Those operations belong to the
+application and the consumer named by the relevant project contract.
+
+For the ordinary naked CLI, an explicitly installed first-party
+`genesis-stack` package bootstraps an unconfigured project without exposing
+catalog package plumbing to the agent. Genesis enumerates component ids from
+that package; it does not hard-code technology names or scan arbitrary npm
+packages. A host can instead supply another catalog explicitly with
+`--stack-package`. Once a selection records its owning package in
+`genesis/stack.md`, ordinary commands use that recorded package directly.
+
+`genesis/stack.md` records the owning Stack package, component ids, and the
+project-owned operation contracts proposed during selection. After the first
+selection, ordinary commands resolve the recorded package without another
+flag, but later catalog releases never silently rewrite those contracts.
+Selecting no components is valid. `genesis-stack` currently contains C/C++,
+C#, Go, Java, Kotlin, Node.js, PHP, Python, Ruby, Rust, and Shell, plus Vue,
+MySQL, PostgreSQL, JSKIT, JSKIT database integrations, Laravel, and Laravel
+database integrations.
+
+### Why `genesis/stack.md` is deliberately small
+
+The project Stack is a durable contract, not a copy of every framework manual.
+It contains only:
+
+- the catalog package that owns the selected component definitions;
+- the resolved component ids;
+- Genesis-owned `Resources`, `Environment defaults`, `Environment files`, and
+  `Verification` contracts that are relevant to this project; and
+- exact consumer-owned sections such as `Workspace setup`, `Outputs`, or
+  `Deployment` when selected components propose them.
+
+Concise technology Guidance, Adoption, Post-change, and Deslop prose stays in
+the installed catalog, while larger authoritative instructions remain in
+technology-owned Agent Skills or official documentation. Genesis composes the
+relevant guidance into prompts and path-focused context on demand. Application
+source remains the authority for what actually exists.
+
+Selection copies operation proposals once. From that point onward, the complete
+project sections in `genesis/stack.md` win: upgrading `genesis-stack` can improve
+guidance for future work but cannot silently change how this application is
+installed, checked, run, or deployed.
 
-`genesis/stack.md` records the owning Stack package, component ids, and optional
-project verification commands. After the first selection, ordinary commands
-resolve the recorded package without another flag. Selecting no components is
-valid. `genesis-stack` contains the eleven common language families listed
-above, plus Vue, MySQL, PostgreSQL, JSKIT, and JSKIT database integrations.
 Components may contribute:
 
 - a concise description and supplemental Guidance used across relevant tasks;
@@ -422,6 +633,13 @@ Components may contribute:
 - structural code indexers used by Machine City and function lookup;
 - default verification commands.
 
+Resources, environment declarations, Verification, and opaque consumer
+sections are proposals, not live inherited behavior. `genesis stack add`
+materializes them into `genesis/stack.md`, prints a one-time
+heading-by-heading preparation prompt, and expects the implementation or the
+complete project section to be made truthful in that same task. Repeating the
+same selection emits no second preparation prompt.
+
 Technology-specific supplemental rules intentionally remain in Stack pieces.
 General `Guidance` enriches implementation, review, Program, description, and
 cleanup tasks; `Adoption` adds import-only requirements; `Post-change` adds
@@ -433,6 +651,58 @@ upstream skill contains every rule Genesis needs.
 Genesis core contains no Stack pieces and no database, framework, language, or
 platform dependency. See [Stack components](docs/stack-components.md).
 
+### The current JSKIT command contract
+
+Selecting `jskit` currently proposes the following operations. These are the
+only commands in the base JSKIT Stack proposal; an application may deliberately
+add or replace complete project sections when its real scripts differ.
+
+| Project contract | Command or probe | Purpose | Executor |
+| --- | --- | --- | --- |
+| `Workspace setup` | `npm install` | Install development dependencies when `package.json` exists. | The operator or host preparing a workspace, such as Vibe64. |
+| `Outputs` | `npm run develop` | Start the interactive development web application. | The operator or output host. |
+| `Outputs` readiness | `GET /api/health` → `200` | Decide when the development output is ready; preferred port is `3000`. | The output host. |
+| `Verification` | `npm run verify` | Run the application's finite declared checks. | `genesis verify` executes this one directly. |
+| `Deployment` prepare | `npm ci` | Recreate production dependencies from the lockfile. | The deployment consumer. |
+| `Deployment` build | `npm run build` | Produce the deployable application build. | The deployment consumer. |
+| `Deployment` serve | `npm start` | Start the built production application. | The deployment consumer. |
+| `Deployment` readiness | `GET /api/health` → `200` | Prove that the deployed service is ready. | The deployment consumer. |
+
+The JSKIT proposal also declares `.env` as its environment projection and says
+that inactive deployment workspaces may recreate `node_modules`; it deliberately
+does not mark built output disposable.
+
+Selecting `jskit-mysql` additionally selects `mysql`, `jskit`, and `nodejs`,
+sets the public default `DB_CLIENT=mysql2`, and declares either
+`DB_HOST`/`DB_PORT`/`DB_NAME`/`DB_USER`/`DB_PASSWORD` or `DATABASE_URL` as the
+database input contract, with optional `TEST_DB_NAME`. It does **not** invent a
+database-preparation command. If the application implements a real migration or
+seed script, the agent records that exact command in the complete project
+sections whose consumers need it. Local authentication similarly requires the
+application to declare `AUTH_LOCAL_SESSION_SECRET` without committing its
+value.
+
+### How the Stack contract is enforced
+
+Enforcement deliberately stops at ownership boundaries:
+
+- Genesis strictly parses component ids, dependencies, conflicts, resources,
+  public defaults, environment-file paths, and Verification commands.
+- Current-format projects must contain every project-owned section required by
+  their selected components. Missing materialized contracts make Stack reads
+  and `genesis check` invalid instead of falling back to a newer catalog.
+- `genesis check` validates structure, reports missing declared input names, and
+  reports verification evidence as current, stale, missing, or unconfigured.
+- `genesis verify` executes only the exact argv recorded under
+  `## Verification`, without a shell, and records the passing code and Stack
+  identity.
+- Consumer-owned sections are intentionally opaque to Genesis. The consumer
+  that names `Workspace setup`, `Outputs`, `Deployment`, packaging, signing, or
+  another operation owns its grammar, execution, and proof.
+- The one-time preparation prompt tells the agent to make every heading true,
+  but prompt compliance is not mechanical proof. Source, focused tests, the
+  consumer's validator, runtime behavior, and Git review remain the evidence.
+
 ## Verification
 
 Run the Stack's declared checks explicitly:
@@ -456,7 +726,7 @@ Agent Skill, and Deslop prose do not rewrite what an already-run command proved.
 A failed verification removes prior passing evidence before running.
 Verification does not claim whole-product correctness.
 
-A project can replace component defaults in `genesis/stack.md`:
+The project owns the commands in `genesis/stack.md`:
 
 ```markdown
 ## Verification
@@ -500,12 +770,13 @@ files to the running CLI's project format:
 genesis migrate
 ```
 
-Migration is deterministic and forward-only. It updates only recognized
-Genesis formats, synchronizes managed skills and hooks, regenerates derived
-indexes, and then returns a fresh `check` result. A newer project is never
-downgraded. Every project-scoped CLI invocation warns when the recorded format
-does not match the running CLI, and ordinary project operations stop until the
-migration is resolved.
+Migration is deterministic and forward-only. The format 2 migration snapshots
+the previously effective Stack operations into project-owned sections before
+removing component-runtime fallback. Migration also synchronizes managed skills
+and hooks, regenerates derived indexes, and then returns a fresh `check`
+result. A newer project is never downgraded. Every project-scoped CLI
+invocation warns when the recorded format does not match the running CLI, and
+ordinary project operations stop until the migration is resolved.
 
 ## Public API
 

package/docs/prompt-integration.md

@@ -36,8 +36,8 @@ Genesis keeps each instruction at one useful level:
 - `prompts/<task>.txt` is a task launcher. It selects the relevant
   workflow skill and states only that turn's edit boundary.
 - a declared Stack package's `stacks/pieces/<component>.md` supplies concise Description, supplemental
-  Guidance, Adoption requirements, Resources, Deslop overlays, structural Indexers, verification
-  commands, opaque consumer sections, and an optional authoritative Agent Skill source.
+  Guidance, Adoption requirements, initial operation proposals, Deslop overlays,
+  structural Indexers, and an optional authoritative Agent Skill source.
 - `genesis/blueprint.md`, `genesis/program/`, and `genesis/stack.md` are the
   project's own intent, explanation, and selected technical composition.
 - `profiles/engineering/*.md` owns the installed versioned engineering
@@ -57,17 +57,18 @@ composed without creating a colliding generic skill.
 `genesis adopt [product guidance...]` is the explicit starting point for a
 nonempty project. It preserves source, calls the same idempotent initialization
 used by `genesis init`, and prints an `adopt` prompt for the current agent to
-follow. Adoption first records observed Stack components, regenerates itself so
-their technology-specific `## Adoption` requirements are present, translates
-the application's real operational contracts into project Stack sections, and
-then creates one Blueprint and subsystem-oriented Program.
-
-Adoption does not upgrade an application's technology foundation. Component
-defaults apply only when direct source evidence matches. Older or otherwise
+follow. Adoption first records observed Stack components, follows the
+preparation prompt returned by selection so their technology-specific `##
+Adoption` requirements and proposed project contracts are visible, translates
+those contracts to match the application's evidenced reality, and then creates
+one Blueprint and subsystem-oriented Program.
+
+Adoption does not upgrade an application's technology foundation. Materialized
+component proposals are starting candidates, not evidence. Older or otherwise
 different applications receive complete project-owned environment/resource,
-Verification, and consumer-owned opaque declarations as applicable. Genesis
-does not interpret those opaque bodies; the consumer's schema and technology
-skill determine what must be preserved.
+Verification, and consumer-owned opaque declarations that match source reality.
+Genesis does not interpret those opaque bodies; the consumer's schema and
+technology skill determine what must be preserved.
 
 Codex users can run `genesis codex install` once to install the packaged
 Genesis discovery plugin. Its `SessionStart` hook executes before the first
@@ -87,16 +88,35 @@ requests another model turn. Selected `Post-change` contributions are included
 in the original implementation prompt, whose project skill also keeps
 intentional Blueprint and affected Program changes aligned.
 
+The operating guide dynamically lists only the component ids in the currently
+available Stack catalogs. The naked CLI uses an explicitly installed
+first-party `genesis-stack` package as its initial catalog without exposing the
+package name to the agent or scanning arbitrary packages. When the user names
+an unselected technology that exactly matches a listed component, the agent
+confirms before adding it. A confirmed selection uses the ordinary `stack add`
+operation, applies dependency closure, synchronizes any component-declared
+skill, materializes missing operation proposals into the project Stack, and
+prints a one-time preparation prompt. The agent follows that prompt in the same
+task, satisfying every heading or replacing a complete section with evidenced
+reality. It then uses `genesis context` for exact project contracts and
+path-local guidance. Genesis never infers an install command from a component
+id. A declined or unmatched choice continues with authoritative technology
+documentation.
+
 Deslop is an explicit prompt task available to any host or command-line user.
 It resolves the latest commit by default, a requested first-parent count, or an
 exact commit/range; requires a clean worktree; and leaves cleanup as ordinary
 uncommitted work. Genesis owns that invariant contract. Selected Stack
 `Deslop` prose and applicable technology skills enrich the cleanup without
-changing its scope or behavior-preserving boundary.
+changing its scope or behavior-preserving boundary. When the installed Deslop
+skill is invoked by a direct agent request, it generates this canonical prompt
+once in the same turn so those effective Stack instructions are present. A
+prompt whose Genesis context already identifies the Deslop task is followed
+directly and never generated recursively.
 
 Once Codex identifies relevant source, `genesis context <path...>` returns only
-Program modules citing those paths plus the effective engineering approach and
-concise selected Stack context, the
+Program modules citing those paths plus the effective engineering approach,
+concise selected Stack guidance, exact project-owned Stack contracts, the
 functions structurally indexed in those paths, available Agent Skill catalog,
 and verification commands. `genesis index <name-or-path>` searches the complete
 current function inventory and refreshes `.genesis/machine-city.json` and