genesis-compiler 1.2.2 → 1.2.4

package/README.md

@@ -14,7 +14,7 @@ interaction.
 genesis/
   blueprint.md       non-technical product intent
   stack.md           selected technology guidance, checks, setup, launch, and deployment data
-  stack/             optional per-component Description, Guidance, and Deslop customization
+  stack/             optional per-component Description, Guidance, Adoption, and Deslop customization
   program/           concise explanations grouped into conceptual subsystems
 .agents/skills/
   genesis-*          Genesis workflow skills
@@ -60,11 +60,13 @@ genesis adopt "Optional product guidance"
 ```
 
 It preserves the implementation, initializes the Genesis files and local
-hooks, and prints the `describe` prompt that creates the first useful Blueprint
-and Program. Give that prompt to the agent already working in the repository.
-For a large codebase, the prompt explicitly lets that agent decide whether to
-delegate inspection to subagents and requires it to synthesize one coherent
-result. “Adopt” is intentional: Genesis neither imports nor moves the project.
+hooks, and prints the `adopt` prompt. That prompt imports the existing
+application's factual Stack contract—including setup, environment/resources,
+database preparation and seed, Launch/readiness, Preview identity,
+verification, and deployment—then creates the first useful 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:
 
@@ -83,10 +85,12 @@ genesis codex install
 ```
 
 When Codex opens a nonempty Git project without `genesis/blueprint.md`, the
-plugin's `SessionStart` hook runs before the first user prompt and adds a strong
-instruction to recommend `genesis adopt`. Codex cannot display an ordinary
-assistant reply until the user speaks, so the recommendation appears in its
-first reply. It never runs adoption without approval and does nothing in an
+plugin's `SessionStart` hook runs before the first user prompt and asks the
+assistant to recommend preparing the existing project for guided editing in
+product language. Codex cannot display an ordinary assistant reply until the
+user speaks, so the recommendation appears in its first reply. If approved, the
+assistant runs `genesis adopt`; the person need not know Genesis terminology or
+type a command. It never runs adoption without approval and does nothing in an
 empty or already-adopted project.
 
 `genesis init` creates an empty Blueprint, an empty optional Stack, three
@@ -116,8 +120,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,8 +136,9 @@ 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
@@ -137,6 +147,10 @@ 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.
+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.
 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
@@ -176,6 +190,20 @@ or roll back. A deployment host owns all of those operational responsibilities,
 including the mapping from `mysql` or `postgresql` resources to its managed
 services.
 
+Standalone and non-Node hosts can inspect these same normalized contracts
+without importing the JavaScript API or parsing Markdown:
+
+```bash
+genesis inspect workspace --json
+genesis inspect environment --json
+genesis inspect launch --json
+genesis inspect deployment --json
+```
+
+Without `--json`, the commands print concise human-readable summaries. They
+never execute setup, start a process, probe a server, materialize environment
+files, or deploy.
+
 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:
@@ -284,6 +312,7 @@ genesis prompt "Add filtering by note title"
 ```bash
 genesis prompt                                      # implementation work
 genesis prompt --task start                        # open a new or existing project conversation
+genesis prompt --task adopt                        # import an existing project's complete contract
 genesis prompt "Add filtering by note title"
 genesis prompt --task deslop                        # explicit cleanup
 genesis prompt --task deslop "Only review billing"
@@ -293,12 +322,15 @@ genesis prompt --task describe                      # create/refresh Blueprint a
 genesis prompt --task review                        # compare intent, code, and explanation
 ```
 
-The seven task types are deliberately explicit:
+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.
+- `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.
 - `work` implements the Blueprint and optional request using current code,
   Program, selected Stack context, and progressively loaded Agent Skills.
 - `deslop` requests cleanup explicitly. Codex projects also receive a bounded
@@ -335,6 +367,7 @@ 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;
+- existing-project Adoption requirements used only while importing a codebase;
 - one authoritative Agent Skill directory when the component owns one;
 - generic external-resource requirements;
 - cleanup advice used by explicit and automatic Deslop prompts;
@@ -343,9 +376,9 @@ JSKIT, and JSKIT database integrations. Components may contribute:
 
 Technology-specific supplemental rules intentionally remain in Stack pieces.
 General `Guidance` enriches implementation, review, Program, description, and
-cleanup tasks; `Deslop` adds cleanup-only rules. Neither shadows an official
-generic technology skill nor assumes that an upstream skill contains every rule
-Genesis needs.
+cleanup tasks; `Adoption` adds import-only requirements; `Deslop` adds
+cleanup-only rules. None shadows an official generic technology skill or
+assumes that an upstream skill contains every rule Genesis needs.
 
 Genesis core contains no database, framework, language, or platform-specific
 controller behavior. See [Stack components](docs/stack-components.md).
@@ -370,7 +403,7 @@ command without a shell. A complete successful run writes only
 - the commands that passed.
 
 The evidence becomes stale when code, selected components, declared resources,
-or verification commands change. Description, Guidance, Agent Skill, and Deslop
+or verification commands change. Description, Guidance, Adoption, 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.
@@ -419,6 +452,7 @@ import {
   getContext,
   indexCodebase,
   initialize,
+  inspectDeployment,
   inspectEnvironment,
   inspectLaunch,
   inspectWorkspaceSetup,
@@ -430,7 +464,7 @@ import {
 
 `initialize()` installs the project files, Genesis workflow skills, selected
 Stack skills, and local Codex hooks.
-`adoptProject()` also returns the initial `describe` prompt for an existing
+`adoptProject()` also returns the initial `adopt` prompt for an existing
 codebase. `installCodex()` installs the optional global discovery plugin.
 `getContext()` resolves source paths to the Program modules that cite them,
 the functions already declared there, selected Stack guidance, available Agent
@@ -447,6 +481,8 @@ 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 probe, preview
 identity, secret, and browser policy.
+`inspectDeployment()` returns the separate normalized production recipe without
+executing or provisioning it.
 
 A host such as Vibe64 can send the generated prompt to its existing agent:
 

package/docs/assurance-model.md

@@ -17,10 +17,25 @@ Genesis reports only facts it can establish mechanically:
    City projects the Program modules and source citations that exist. Neither
    proves semantic equivalence, complete dynamic dispatch, or true duplication.
 
-Prompt text, Stack Description/Guidance/Deslop prose, Program prose, Agent Skill
+Prompt text, Stack Description/Guidance/Adoption/Deslop prose, Program prose, Agent Skill
 content, and agent output are not assurance evidence. Genesis does not claim
 that product intent and code have converged, that Program is complete or
 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/preview-identity-command.md

@@ -0,0 +1,113 @@
+# Preview identity command protocol
+
+`genesis.preview-identity.command.v1` lets an application expose its ordinary
+development sign-in and sign-out behavior to any preview host. It is language-
+and framework-neutral: `tools/preview-identity` may be a native C/C++ binary, a
+script, or another committed executable supported by the target's declared
+runtimes.
+
+Genesis only validates and reports the declaration. The preview host resolves
+the command beneath the project root, rejects traversal and symlinks, supplies
+the declared runtime and environment policy, enforces the declared timeout,
+and controls the browser. The application owns user lookup and its normal
+session cookies.
+
+## Invocation
+
+The host runs the exact declared argv with the project root as the working
+directory. Standard input contains exactly one UTF-8 JSON object followed by a
+newline and EOF. Standard output contains exactly one JSON object; diagnostic
+logs belong on standard error. There is no streaming or multi-message framing.
+
+The host supplies a fresh opaque `requestId`. A sign-in request is:
+
+```json
+{
+  "protocol": "genesis.preview-identity.command.v1",
+  "requestId": "opaque-request-id",
+  "operation": "login-as",
+  "subject": {
+    "kind": "selector",
+    "selector": {
+      "type": "email",
+      "value": "person@example.com"
+    }
+  },
+  "target": {
+    "href": "http://127.0.0.1:4100/home",
+    "origin": "http://127.0.0.1:4100"
+  }
+}
+```
+
+`subject.selector.type` must be one of the identity types advertised by the
+Launch declaration: `email`, `login`, or `user-id`. The application treats the
+selector as an existing application identity; a preview host does not create
+users, memberships, roles, or seed data.
+
+Sign-out uses the same envelope with `operation` set to `logout` and omits
+`subject`.
+
+## Responses
+
+Every protocol response repeats the exact `protocol` and `requestId` and exits
+with status zero. A successful sign-in response is:
+
+```json
+{
+  "protocol": "genesis.preview-identity.command.v1",
+  "requestId": "opaque-request-id",
+  "ok": true,
+  "signedOut": false,
+  "identity": {
+    "displayName": "Person",
+    "email": "person@example.com",
+    "userId": "42"
+  },
+  "setCookie": [
+    "app_session=opaque; Path=/; HttpOnly; SameSite=Lax"
+  ]
+}
+```
+
+`identity` contains at least one non-empty application identifier. Supported
+descriptive fields are `displayName`, `email`, `login`, `userId`, and
+`username`. `setCookie` contains the application's ordinary Set-Cookie header
+values. Cookies must contain no CR/LF or `Domain` attribute; the host may reject
+additional cookie names reserved by its own preview transport.
+
+A successful logout sets `signedOut` to true, omits `identity`, and returns the
+cookie expirations needed to clear the application's session. A structured
+application rejection still exits zero and uses:
+
+```json
+{
+  "protocol": "genesis.preview-identity.command.v1",
+  "requestId": "opaque-request-id",
+  "ok": false,
+  "code": "user_not_found",
+  "error": "User not found.",
+  "statusCode": 404,
+  "signedOut": true,
+  "setCookie": []
+}
+```
+
+`statusCode` is an integer from 400 through 599. A malformed request, command
+crash, timeout, nonzero exit, invalid JSON, mismatched request ID, oversized
+output, or invalid cookie is a command/transport failure rather than an
+application rejection. Hosts should bound output to 512 KiB, at most 64
+cookies, and at most 16 KiB per cookie.
+
+## Environment and safety
+
+The optional Enabled and Secret environment entries in the Launch declaration
+are application-owned variable names, never values. A host that offers identity
+switching supplies `true` through the enabled name and a fresh launch-scoped
+secret through the secret name. The helper and any private application endpoint
+it calls must remain disabled unless those values are present and valid.
+
+The command is a development-preview control, not a production sign-in API.
+Genesis does not store selectors, generate credentials, materialize environment
+files, execute the helper, or decide which identities a host is allowed to
+offer.

package/docs/prompt-integration.md

@@ -15,7 +15,7 @@ const work = await generatePrompt({
 await currentAgent.send(work.prompt);
 ```
 
-Tasks are `start`, `work`, `deslop`, `program`, `blueprint`, `describe`, and `review`.
+Tasks are `start`, `adopt`, `work`, `deslop`, `program`, `blueprint`, `describe`, and `review`.
 `start` is the host-independent first conversation: it classifies an initialized
 project from current Genesis facts, asks what a new app is about, exposes the
 live Stack catalog for an explicit user choice, or asks what the person wants
@@ -33,10 +33,10 @@ Genesis keeps each instruction at one useful level:
 - `skills/genesis-project/`, `skills/genesis-program/`, and
   `skills/genesis-deslop/` are the reusable workflow sources copied into each
   project's `.agents/skills/` directory.
-- `prompts/<task>.txt` is a short task launcher. It selects the relevant
+- `prompts/<task>.txt` is a task launcher. It selects the relevant
   workflow skill and states only that turn's edit boundary.
 - `stacks/pieces/<component>.md` supplies concise Description, supplemental
-  Guidance, Resources, Deslop overlays, structural Indexers, verification
+  Guidance, Adoption requirements, Resources, Deslop overlays, structural Indexers, verification
   Commands, 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.
@@ -51,19 +51,26 @@ 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 a `describe` prompt for the current agent to
-follow. The description prompt may direct a large-project agent to use
-subagents at its discretion, but the primary agent must reconcile their work
-into one Blueprint and one subsystem-oriented Program.
+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
+different applications receive complete project-owned declarations for setup,
+environment/resources, Launch and Preview identity, verification, and
+deployment as applicable, so a host never executes a newly selected
+component's current command against source that does not provide it.
 
 Codex users can run `genesis codex install` once to install the packaged
 Genesis discovery plugin. Its `SessionStart` hook executes before the first
 user prompt. In a nonempty Git repository without `genesis/blueprint.md`, it
-injects an instruction that the first assistant reply strongly recommend
-`genesis adopt`. It does not perform adoption automatically. If the user
-accepts, Codex can run the command and follow its returned prompt in the same
-conversation. Other hosts can call `adoptProject()` and send its `prompt`
-directly.
+asks the assistant to recommend project preparation in product language. It
+does not perform adoption automatically. If the user accepts, Codex runs the
+command itself and follows its returned prompt in the same conversation. Other
+hosts can call `adoptProject()` and send its `prompt` directly.
 
 Codex can instead use the project-local hooks installed by `genesis init`.
 Those hooks inject a short operating guide, record whether the current turn
@@ -92,7 +99,8 @@ This follows Agent Skills progressive disclosure and keeps official or
 user-installed generic technology skills independent.
 
 Matching files under `genesis/stack/<component>.md` may add to or override that
-selected component's Description, Guidance, and Deslop fields. Effective
+selected component's Description, Guidance, Adoption, and Deslop fields. Effective
 Guidance is used by work, review, Program, describe, Deslop, and path-context
 generation. The Codex continuation flow also carries it into reconciliation and
-cleanup; effective Deslop guidance remains cleanup-only.
+cleanup; effective Deslop guidance remains cleanup-only. Effective Adoption
+guidance is included only in the adoption workflow.

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
@@ -48,6 +59,11 @@ What this component contributes.
 - Concise supplemental guidance used during implementation, explanation,
   review, and cleanup.
 
+## Adoption
+
+- Evidence and technology-specific contracts an agent must reconcile when
+  importing an existing application.
+
 ## Environment files
 
 - Dotenv `.env`
@@ -80,8 +96,8 @@ What this component contributes.
 
 #### Preview identity
 
-- Command: `.vibe64/bin/preview-identity`
-- Protocol: `vibe64.preview-identity.command.v1`
+- Command: `tools/preview-identity`
+- Protocol: `genesis.preview-identity.command.v1`
 - Identity types: `email` `login` `user-id`
 - Enabled environment: `APP_PREVIEW_IDENTITY_ENABLED`
 - Secret environment: `APP_PREVIEW_IDENTITY_SECRET`
@@ -101,12 +117,21 @@ before verification. `allowEmpty` may name a required variable whose empty
 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`
+description, and cleanup prompts, as well as path-focused context. `Adoption`
+adds technology-specific evidence and contract requirements to the dedicated
+existing-application import prompt. `Deslop`
 adds cleanup-only prose to explicit cleanup and the automatic Codex cleanup
 continuation. With no selected component, only the `genesis-deslop` skill
 applies. `Commands` accepts only argument-safe `Verify` entries and runs only
 through `genesis verify`.
 
+A project may own a complete `## Resources` section in `genesis/stack.md` using
+the same fenced `json genesis-resource` objects, or `- Nothing.` to declare
+none. Its presence replaces every selected component Resource declaration.
+This lets an existing application preserve its real queue, database, mail,
+object-storage, or service environment names rather than inherit a framework's
+vocabulary. Without a project section, component Resources compose as before.
+
 `Workspace setup` is an optional exact, ordered recipe for a host preparing a
 fresh workspace. Each entry uses this readable, shell-free form:
 
@@ -149,6 +174,13 @@ 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.
 
+A project `## Environment defaults` section in `genesis/stack.md` likewise
+replaces every component default and accepts `- Nothing.` as a complete empty
+declaration. It is the complete declaration of public, non-secret constants
+expected by the actual application; Genesis never keeps a framework default
+beside it implicitly. `genesis stack add` preserves both project-owned sections
+while changing component selection.
+
 `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
@@ -177,8 +209,8 @@ 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
-committed, application-owned file immediately below `.vibe64/bin`; the
+the declared `genesis.preview-identity.command.v1` protocol. Its executable is
+a committed, application-owned project-relative file; the
 normalized command is an argv array, not a shell program. Identity types may
 contain `email`, `login`, and `user-id`. Enabled environment and Secret
 environment are optional variable
@@ -187,7 +219,9 @@ never reads or returns their values. Runtimes lists opaque runtimes required
 to execute this command, independently of the server target requirements, and
 Timeout ms defaults to 10000 with a maximum of 30000. Genesis does not execute
 the command, select identities, provide secrets, authenticate users, or control
-the browser. Those remain host responsibilities.
+the browser. Those remain host responsibilities. The complete transport
+contract is defined in
+[`preview-identity-command.md`](preview-identity-command.md).
 
 `runtimeRequirements` contains opaque technology ids. A host explicitly maps
 the ids it supports to its own pinned runtime packs; for example, it may map
@@ -239,11 +273,31 @@ 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
 authoritative directory this Stack component selects; put concise supplemental
-rules in `## Guidance` and cleanup-only additions in `## Deslop`.
+rules in `## Guidance`, existing-project import requirements in `## Adoption`,
+and cleanup-only additions in `## Deslop`.
 
 A selected component may have one project customization at
 `genesis/stack/<id>.md`:
@@ -261,6 +315,10 @@ Additional project context.
 
 - Additional implementation, explanation, review, and cleanup guidance.
 
+### Adoption
+
+- Additional existing-project import requirements.
+
 ### Deslop
 
 - Additional cleanup guidance.
@@ -275,30 +333,35 @@ Replacement component description.
 
 - Replacement installed general guidance.
 
+### Adoption
+
+- Replacement existing-project import requirements.
+
 ### Deslop
 
 - Replacement cleanup guidance.
 ```
 
 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
-defaults, environment files, commands, Workspace setup, or Launch declarations.
+then follows the installed or overridden value. These customization files
+cannot alter dependencies, conflicts, Agent Skill source, indexers, resources,
+environment defaults, environment files, commands, Workspace setup, or Launch declarations.
 `genesis stack add` preserves the files and composes their effective prose after
 dependency resolution.
 
-A project may select component ids in `genesis/stack.md`, replace component
-environment-file declarations, replace component Workspace setup defaults
-with one project recipe, replace component Verify defaults with its own
-`## Commands`, and replace every component Launch target with one project
-`## Launch` contract. With no project Launch section, selected component
-targets compose; duplicate ids or multiple defaults are rejected rather than
-guessed. `genesis stack add` preserves existing project Environment files,
-Workspace setup, and Launch sections. Adding another language, framework,
-database, or integration is therefore an isolated Stack/indexer contribution
-rather than a prompt or controller special case.
-
-Description, Guidance, Agent Skill, and Deslop prose are instructions, not
+A project may select component ids in `genesis/stack.md`; replace component
+Resources and Environment defaults with complete application-owned contracts;
+replace component environment-file declarations; replace component Workspace
+setup defaults with one project recipe; replace component Verify defaults with
+its own `## Commands`; and replace every component Launch target with one
+project `## Launch` contract. With no corresponding project section, selected
+component declarations compose; conflicts are rejected rather than guessed.
+`genesis stack add` preserves every existing project-owned contract section.
+Adding another language, framework, database, or integration is therefore an
+isolated Stack/indexer contribution rather than a prompt or controller special
+case.
+
+Description, Guidance, Adoption, 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,
 environment defaults, Workspace setup, launch targets, and verification
@@ -318,6 +381,19 @@ declared `resources`, value-free `diagnostics`, and normalized `files`. Each def
 `name`, `value`, and component `sources`; each file contains `format`, `path`,
 and `source`. Supplied environment values never cross this API boundary.
 
+Shell and non-Node hosts can inspect the same normalized contracts without
+importing the JavaScript API or parsing Markdown:
+
+```bash
+genesis inspect environment --json
+genesis inspect workspace --json
+genesis inspect launch --json
+genesis inspect deployment --json
+```
+
+These are projections of the same public inspectors. They do not create a
+second parser or take ownership of execution.
+
 Fresh-workspace hosts read setup from the package root:
 
 ```js
@@ -337,6 +413,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -25,9 +25,11 @@
     ".agents/plugins/marketplace.json",
     "bin",
     "docs/assurance-model.md",
+    "docs/preview-identity-command.md",
     "docs/stack-components.md",
     "docs/prompt-integration.md",
     "prompts/blueprint.txt",
+    "prompts/adopt.txt",
     "prompts/describe.txt",
     "prompts/deslop.txt",
     "prompts/program.txt",
@@ -56,7 +58,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"
   }
 }