docs: describe external runtime setup

Author: jaromil

README.md

@@ -37,7 +37,7 @@ upward as concise summaries; raw test and inspection logs stay outside
 conversational context. The root gives brief user-facing updates such as
 `L1 2/5 — Validate release metadata: in review`.
 
-Context-mode is used to transport evidence.
+Context-mode transports evidence; it does not spawn agents.
 
 ## 🎮 Quick setup
 
@@ -70,12 +70,16 @@ different marketplace snapshot configured, the script continues from that
 snapshot automatically and preserves its arguments.
 
 The script defaults `CODEX_HOME` to `~/.codex-gestalt`, installs both plugins,
-prepares context-mode, generates `org-plan-reviewer` and `org-plan-executor`,
-and removes the retired `org-plan-supervisor`. It does not create, validate, or
-rewrite `config.toml`; `codex plugin add` only records the installed plugins.
+and prepares context-mode under `~/.gestalt`. Setup generates `org-plan-reviewer` and `org-plan-executor`,
+then removes the obsolete
+`~/.codex-gestalt/agents/org-plan-supervisor.toml`. It does not create,
+validate, or rewrite `config.toml`; `codex plugin add` only records the installed
+plugins.
 Current Codex already defaults the V1 agent depth to one and enables stable
 lifecycle hooks. The former `features.plugin_hooks` flag has been removed, so
-Gestalt needs no configuration override.
+Gestalt needs no configuration override. On an older installation, remove an
+`agents.max_depth = 2` override; setup does not create, validate, or rewrite
+Codex configuration.
 
 Start or restart Codex with that home, verify the effective installation, and
 run `ctx-doctor` in a new session:
@@ -89,14 +93,29 @@ codex
 ### Runtime preparation details
 
 Run `./gestalt-setup.sh` again after a marketplace upgrade. Use
-`./gestalt-setup.sh --prepare-only` to prepare a source checkout without
+`./gestalt-setup.sh --prepare-only` to install the external runtime without
 installing plugins or changing the isolated Codex home, and `--force` to replace
-an invalid prepared runtime. Set `CODEX_HOME` explicitly only to test or install
-an additional isolated Gestalt profile.
+an invalid prepared runtime. Runtime versions are isolated by operating system,
+CPU architecture, and Node ABI under
+`${GESTALT_HOME:-$HOME/.gestalt}/runtime/context-mode/`. Set `CODEX_HOME`
+explicitly only to test or install an additional isolated Gestalt profile.
+Use `./gestalt-setup.sh --force` to rebuild and atomically replace that runtime.
+
+Marketplace installation does not execute setup automatically. On an existing
+installation, upgrade the marketplace and rerun its setup script:
+
+```sh
+export CODEX_HOME="$HOME/.codex-gestalt"
+codex plugin marketplace upgrade dyne-gestalt-agents
+"$CODEX_HOME/.tmp/marketplaces/dyne-gestalt-agents/gestalt-setup.sh"
+```
 
 Do not add duplicate MCP or hook configuration. If startup still fails after
 forced preparation, confirm that another context-mode marketplace variant is
-not also enabled.
+not also enabled. `CONTEXT_MODE_NOT_PREPARED` identifies a missing, incompatible,
+or damaged external runtime; rerun setup with `--force` and restart Codex. MCP
+and hook startup are side-effect free: only setup installs, builds, or repairs
+the external runtime.
 
 ## 🧪 Testing (only for developers of this repo)
 

USAGE.md

@@ -8,7 +8,8 @@ and the `context-mode` runtime plugin.
 Context-mode requires Node.js 22.5 or newer, npm, network access during setup,
 and the native toolchain needed by `better-sqlite3` (`python3`, `make`, and a
 C/C++ compiler). A working Bun installation is used for dependencies when
-available.
+available. Set `CONTEXT_MODE_PACKAGE_MANAGER=npm` or `bun` to override automatic
+selection during setup.
 
 ```sh
 export CODEX_HOME="$HOME/.codex-gestalt"
@@ -22,15 +23,16 @@ When setup is launched from another checkout, it automatically continues from
 the marketplace snapshot configured in `~/.codex-gestalt`.
 
 Marketplace installation does not run the setup script automatically. The
-script installs both plugins, prepares the exact installed context-mode cache,
-verifies its artifact manifest, generates the reviewer and executor profiles,
-and removes the retired supervisor profile. It does not create, validate, or
-rewrite `config.toml`. Run setup again after a marketplace upgrade.
+script installs both plugins, prepares a stable context-mode runtime under
+`${GESTALT_HOME:-$HOME/.gestalt}`, verifies its artifact manifest, generates the
+reviewer and executor profiles, and removes the retired supervisor profile. It
+does not create, validate, or rewrite `config.toml`. Run setup again after a
+marketplace upgrade.
 
 Useful modes:
 
 ```sh
-./gestalt-setup.sh --prepare-only  # prepare this source tree only
+./gestalt-setup.sh --prepare-only  # install only the external runtime
 ./gestalt-setup.sh --force         # reinstall dependencies and rebuild
 ./gestalt-setup.sh --dry-run       # print mutations without running them
 ```
@@ -110,35 +112,44 @@ registry, or writes generated files. Startup follows this path:
 
 ```text
 Codex MCP start
-  -> start.mjs
+  -> start.mjs in the replaceable Codex plugin cache
+  -> resolve version + platform + architecture + Node ABI
   -> runtime-preflight.mjs (read only)
-  -> server.bundle.mjs
+  -> ~/.gestalt/runtime/context-mode/<version>/<target>/server.bundle.mjs
 ```
 
 `runtime-preflight.mjs` verifies the package version and SHA-256 artifact
-manifest. An incomplete cache exits with code 78,
+manifest, including the native `better-sqlite3` binding. An incomplete external
+runtime exits with code 78,
 `CONTEXT_MODE_NOT_PREPARED`, the invalid paths, and the setup command.
 
 Preparation is explicit:
 
 ```text
 gestalt-setup.sh
-  -> codex plugin add
-  -> prepare-runtime.mjs in the installed cache
+  -> install-runtime.mjs
+     -> copy source into a versioned external staging directory
      -> locked dependency install
      -> TypeScript check and bundle build
      -> bundle assertions
      -> versioned SHA-256 manifest
+     -> atomic publication under ~/.gestalt
+  -> codex plugin add
 ```
 
-The setup lock only prevents concurrent preparation from corrupting the cache;
-MCP and hook startup do not acquire it. The manifest covers the server, CLI,
-and hook bundles plus runtime dependency metadata.
+Runtime directories use the package version and
+`<platform>-<architecture>-node-<modules ABI>` as their identity. They survive
+Codex plugin-cache replacement and can be shared by profiles running the same
+Node ABI. `GESTALT_HOME` must be absolute when set. The setup lock prevents
+concurrent installers from publishing a partial runtime; MCP and hook startup
+are read-only and do not acquire it. Codex hooks use a cache-local launcher that
+loads their implementations from the same external runtime.
 
 `package.json` is a private dependency and build manifest. Codex marketplace
 installation does not use npm publication metadata or npm lifecycle scripts.
 The repository-level setup script is the required pre-flight because Codex has
-no marketplace install-build hook and generated bundles are not committed.
+no marketplace install-build hook, generated bundles are not committed, and
+Codex may rematerialize its plugin cache when a session starts.
 
 The context-mode plugin exposes only its Codex MCP and hook surfaces. Hooks use
 Codex's auto-discovered `hooks/hooks.json` path, so the plugin manifest does not
@@ -159,7 +170,7 @@ Startup coverage verifies that:
    write path;
 2. an incomplete runtime fails quickly with the stable diagnostic;
 3. explicit preparation is concurrency-safe and produces a valid MCP
-   `initialize` and `tools/list` exchange;
+   `initialize` and `tools/list` exchange after the plugin cache is recreated;
 4. Codex hooks do not invoke preparation;
 5. plugin manifests, runtime artifacts, skill metadata, and skill discovery
    remain consistent.

plugins/context-mode/README.md

@@ -22,26 +22,30 @@ From the `dyne-gestalt-agents` marketplace checkout, run:
 ./gestalt-setup.sh
 ```
 
-The setup command installs both marketplace plugins, installs locked
-context-mode dependencies in the installed cache, type-checks the TypeScript,
-builds the runtime bundles, and writes a SHA-256 preparation manifest. It
+The setup command installs both marketplace plugins and creates a versioned
+runtime under `${GESTALT_HOME:-$HOME/.gestalt}`. It installs locked dependencies,
+type-checks the TypeScript, builds the runtime bundles, verifies the native
+SQLite binding, and writes a SHA-256 preparation manifest. It
 requires Node.js 22.5 or newer, npm, network access, and a native toolchain for
-`better-sqlite3`.
+`better-sqlite3`. Set `CONTEXT_MODE_PACKAGE_MANAGER=npm` or `bun` to override
+automatic dependency-installer selection.
 
-Run setup again after an upgrade. Use `--prepare-only` for the source checkout,
+Run setup again after an upgrade. Use `--prepare-only` for only the external runtime,
 `--force` to rebuild, or `--dry-run` to inspect mutations.
 
 ## Startup contract
 
 Codex starts `node ./start.mjs`. The launcher only:
 
 1. records the project directory and selects the Codex platform;
-2. verifies the prepared artifact manifest;
-3. imports `server.bundle.mjs`.
+2. resolves the external runtime from its version and the current Node ABI;
+3. verifies the prepared artifact manifest;
+4. imports the external `server.bundle.mjs`.
 
 It never installs, compiles, repairs, or rewrites files. An incomplete runtime
 exits with code 78 and `CONTEXT_MODE_NOT_PREPARED` so the failure is immediate
-instead of timing out during the MCP handshake.
+instead of timing out during the MCP handshake. Codex may replace its plugin
+cache without affecting the prepared runtime.
 
 The plugin manifest registers `.mcp.json`, while Codex discovers lifecycle
 hooks from the conventional `hooks/hooks.json` path. Do not add duplicate MCP