agent-bios 0.18.0 → 0.19.0

package/claude/CLAUDE.md

@@ -114,4 +114,4 @@
 
 ## Session Learning
 
-- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `agent-bios learn`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).
+- `learn!` — session learning: when the user enters `learn!`, capture durable lessons from THIS session for future selected sessions and configured org curation. Read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/learning-flow.md` and follow its admission bar → type A–G → intended layer → explicit user approval → package-bound submission. The tool owns id/timestamp and private capture; it preserves native globals. A Session distill preset (`distill!`) owns its capture — do not run both flows. Never manufacture Type-G principles user-side (curator-only).

package/claude/guides/cli-multi-model-workflow.md

@@ -233,7 +233,7 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 ## Environment Binding (edit per environment)
 
-This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
+This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. Edit shipped defaults in the source repository; keep personal launch bindings in user-owned launcher configuration. Private installation stores an immutable release and preserves personal state. A new configured session resolves its bindings; existing session pins retain theirs.
 
 Binding (2026-09-08):
 

package/claude/guides/learning-flow.md

@@ -9,14 +9,15 @@ use_when:
 core_rules:
   - three gates BEFORE asking the user — admission bar, type, consumption layer
   - the user approves every recorded learning; nothing is written without it
-  - submit ONLY through `agent-bios learn`; never hand-write the record
+  - submit ONLY through the package-bound learn command below; never hand-write the record
 ---
 
 # Session learning flow (`learn!`)
 
 The **light**, per-user, single-session capture flow: turn a lesson from the
 current session into a **learning** (prose + a JSON record) that (a) applies to
-the user's own next session and (b) reaches the org for curation. This is the
+the user's future selected, activated sessions and (b) reaches the org for curation
+when transport is configured. This is the
 counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
 many sessions and is curator/power-user only. Terminology and the full routing
 framework are maintained in the agent-bios repo; the criteria this flow applies
@@ -75,6 +76,14 @@ Surface each surviving candidate compactly — lesson, type, intended layer,
 admission-bar verdict, domain (+ proposed_domain) — and record ONLY what the
 user explicitly approves.
 
+In a Codex app task using the explicit corpus bridge, use the `learn` command
+and environment returned in its `runtime` metadata, or its registered helper.
+Shell exports from an earlier app tool call do not persist into later calls.
+
+In a launcher-activated session, invoke `learn` through the supplied
+`AGENT_BIOS_PACKAGE_ROOT` as shown below. Outside an activated session, resolve
+the installed `agent-bios` executable and use its `learn` subcommand.
+
 Submit each approved learning through the deterministic submit tool. Pass your
 session's `--host` and pipe the **semantic payload only** as one JSON object on
 stdin (set the `supporting_sessions` tool prefix — `claude:` or `codex:` — to
@@ -83,16 +92,18 @@ match your host):
     echo '{"lesson":"…","domain":"builder-base","supporting_sessions":["<tool>:<session-short-id>"],
            "criteria":["recurrent_error"],
            "classification":{"type":"B","layer":"hook","meets_bar":true}}' \
-      | agent-bios learn --host <claude|codex>
-
-The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
-validates against `learn/learning.schema.json`, logs the JSON record, and writes
-the lesson prose where THIS host loads it next session:
-- **Claude**: appended to the automation-owned personal learnings file, pulled in
-  by the entry file's `@personal/learnings.md` import.
-- **Codex**: appended into a managed `agent-bios:personal-learnings` region of
-  `AGENTS.md` (Codex has no import; AGENTS.md is always loaded), kept outside the
-  central markers so re-assembly preserves it.
+      | bash "$AGENT_BIOS_PACKAGE_ROOT/install.sh" learn --host <claude|codex>
+
+The script (capability boundary) owns `learning_id` / `created` / `schema_version`
+and validates against `learn/learning.schema.json`. It appends the record to the
+private corpus's `learnings/<host>/events.jsonl`, keeping Claude and Codex captures
+separate. Selected learnings enter future activated-session snapshots through the
+private corpus. Capture preserves the user's global instruction files and the
+running session's snapshot. Upload runs after local storage when transport is configured.
+The private root is `$AGENT_BIOS_CORPUS_DIR`, defaulting to
+`~/.config/agent-bios/corpus`; native host-home settings do not relocate it.
+`--config-dir` is restricted to explicit legacy mode. Use `--no-upload` for
+local-only capture or `--dry-run` to validate without writes or uploads.
 
 **Never** hand-author `learning_id` / `created` / `schema_version`, and never
 write those files directly. If the script REJECTS a record, fix the semantic

package/claude/guides/session-distill-workflow.md

@@ -13,7 +13,7 @@ core_rules:
   - the ledger is the SSOT for state; read it before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
   - every promotion passes an explicit user-approval gate
-  - global growth per round is hard-capped (~500 tokens) by a measured gate
+  - the canonical always surface is frozen to reductions; route additions to guides, skills, or session-level injection
   - close the window by updating mirrors, parity, deployment, and the nudge baseline
 ---
 
@@ -85,10 +85,13 @@ Everything durable lives in the agent-bios repo.
    promoted, and what is still incubating are all queries against this file.
    Read state here and nowhere else: a count or a status written into prose is
    correct on the day it is written and silently wrong afterwards.
-2. `design/session-distill/versions.json` — which closed mining window maps to
-   which commit, and therefore what a rollback restores.
-3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement authority
-   (typology A–G, layers, admission bars, lifecycle).
+2. `design/session-distill/versions.json` — authoring provenance mapping each
+   closed mining window to its commit. Private rollback selects an installed
+   `baseline_ref` through the corpus plan; this registry is not that authority.
+3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement framework
+   (typology A–G, layers, admission bars, lifecycle). Apply the current
+   `AGENTS.md` reductions-only rule and `SURFACES.md` delivery contract when
+   choosing a destination; the framework does not authorize global growth.
 
 ## Stage 1 — Mine (pipeline in `session-distill/`)
 
@@ -140,15 +143,18 @@ Run in order; each stage reads the previous stage's `out/`:
   consumer check (hermetic dispatch and scripts read no prose) → admission
   bar → token estimate. Ambiguity stays PROPOSED for the user.
 - Apply canonical-first, on a branch, stepwise commits: canonical guide text
-  → global edits under the measured budget gate (net growth ≤ ~500 tokens/
-  round; overflow re-routes to guides, not silent deferral) → other guides →
+  → reductions to the canonical always surface (delete, merge, or move rules
+  out; additions belong in guides, skills, or session-level injection) → other guides →
   hooks (derive injected text from the canonical guide; read-only, never
   blocking) → enforcement in owned wrappers (loud failures; keep
   stdout/stderr channel contracts) → codex/ + ko/ mirrors.
 - Verify per layer, not just by diff: enforcement/gate fixture tests
   (non-vacuous — known-bad must fire), hook trigger positive/negative sets,
   `gates/check-parity.sh` exit 0 unpiped, prompting-target gate, then
-  `agent-bios install` to activate and re-verify.
+  `bash install.sh install` from this checkout to store the changed private
+  release and `bash install.sh verify` to verify it. Activate a new configured
+  session through `agent-launch` and check its delivery evidence separately;
+  installation does not activate content or change an existing session pin.
 
 ## Stage 4 — G-pass (principles, not directives)
 
@@ -165,10 +171,14 @@ Run in order; each stage reads the previous stage's `out/`:
 
 1. Ledger: statuses to placed (with implementation paths) / incubating;
    dated corrections for anything refuted.
-2. HANDOFF: completion record, incidental finds as next-window candidates.
+2. Write a new timestamped completion record under `design/session-distill/`
+   following `AGENTS.md`; incidental finds become next-window candidates.
 3. Register the corpus version: append {version = window end, commit = the
-   corpus-close commit} to `design/session-distill/versions.json` — this is
-   what the launcher's Versions & rollback screen offers — then run
+   corpus-close commit} to `design/session-distill/versions.json` for authoring provenance. Private rollback selects an installed `baseline_ref`
+   through `agent-bios corpus plan`; the window registry does not authorize a
+   global-file rollback. Then run
    `python3 session-distill/update-state.py --window-end <date>`
    (nudge baseline) and `corpus-state.py project` (launcher status panel).
-4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).
+4. Merge the branch, push, and confirm the private release from this checkout
+   (`bash install.sh verify`); report stored-state and session-delivery evidence
+   separately.

package/codex/AGENTS.md

@@ -115,4 +115,4 @@
 
 ## Session Learning
 
-- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CODEX_HOME:-$HOME/.codex}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `agent-bios learn`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).
+- `learn!` — session learning: when the user enters `learn!`, capture durable lessons from THIS session for future selected sessions and configured org curation. Read `${CODEX_HOME:-$HOME/.codex}/guides/learning-flow.md` and follow its admission bar → type A–G → intended layer → explicit user approval → package-bound submission. The tool owns id/timestamp and private capture; it preserves native globals. A Session distill preset (`distill!`) owns its capture — do not run both flows. Never manufacture Type-G principles user-side (curator-only).

package/codex/guides/cli-multi-model-workflow.md

@@ -233,7 +233,7 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 ## Environment Binding (edit per environment)
 
-This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
+This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. Edit shipped defaults in the source repository; keep personal launch bindings in user-owned launcher configuration. Private installation stores an immutable release and preserves personal state. A new configured session resolves its bindings; existing session pins retain theirs.
 
 Binding (2026-09-08):
 

package/codex/guides/learning-flow.md

@@ -9,14 +9,15 @@ use_when:
 core_rules:
   - three gates BEFORE asking the user — admission bar, type, consumption layer
   - the user approves every recorded learning; nothing is written without it
-  - submit ONLY through `agent-bios learn`; never hand-write the record
+  - submit ONLY through the package-bound learn command below; never hand-write the record
 ---
 
 # Session learning flow (`learn!`)
 
 The **light**, per-user, single-session capture flow: turn a lesson from the
 current session into a **learning** (prose + a JSON record) that (a) applies to
-the user's own next session and (b) reaches the org for curation. This is the
+the user's future selected, activated sessions and (b) reaches the org for curation
+when transport is configured. This is the
 counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
 many sessions and is curator/power-user only. Terminology and the full routing
 framework are maintained in the agent-bios repo; the criteria this flow applies
@@ -75,6 +76,14 @@ Surface each surviving candidate compactly — lesson, type, intended layer,
 admission-bar verdict, domain (+ proposed_domain) — and record ONLY what the
 user explicitly approves.
 
+In a Codex app task using the explicit corpus bridge, use the `learn` command
+and environment returned in its `runtime` metadata, or its registered helper.
+Shell exports from an earlier app tool call do not persist into later calls.
+
+In a launcher-activated session, invoke `learn` through the supplied
+`AGENT_BIOS_PACKAGE_ROOT` as shown below. Outside an activated session, resolve
+the installed `agent-bios` executable and use its `learn` subcommand.
+
 Submit each approved learning through the deterministic submit tool. Pass your
 session's `--host` and pipe the **semantic payload only** as one JSON object on
 stdin (set the `supporting_sessions` tool prefix — `claude:` or `codex:` — to
@@ -83,16 +92,18 @@ match your host):
     echo '{"lesson":"…","domain":"builder-base","supporting_sessions":["<tool>:<session-short-id>"],
            "criteria":["recurrent_error"],
            "classification":{"type":"B","layer":"hook","meets_bar":true}}' \
-      | agent-bios learn --host <claude|codex>
-
-The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
-validates against `learn/learning.schema.json`, logs the JSON record, and writes
-the lesson prose where THIS host loads it next session:
-- **Claude**: appended to the automation-owned personal learnings file, pulled in
-  by the entry file's `@personal/learnings.md` import.
-- **Codex**: appended into a managed `agent-bios:personal-learnings` region of
-  `AGENTS.md` (Codex has no import; AGENTS.md is always loaded), kept outside the
-  central markers so re-assembly preserves it.
+      | bash "$AGENT_BIOS_PACKAGE_ROOT/install.sh" learn --host <claude|codex>
+
+The script (capability boundary) owns `learning_id` / `created` / `schema_version`
+and validates against `learn/learning.schema.json`. It appends the record to the
+private corpus's `learnings/<host>/events.jsonl`, keeping Claude and Codex captures
+separate. Selected learnings enter future activated-session snapshots through the
+private corpus. Capture preserves the user's global instruction files and the
+running session's snapshot. Upload runs after local storage when transport is configured.
+The private root is `$AGENT_BIOS_CORPUS_DIR`, defaulting to
+`~/.config/agent-bios/corpus`; native host-home settings do not relocate it.
+`--config-dir` is restricted to explicit legacy mode. Use `--no-upload` for
+local-only capture or `--dry-run` to validate without writes or uploads.
 
 **Never** hand-author `learning_id` / `created` / `schema_version`, and never
 write those files directly. If the script REJECTS a record, fix the semantic

package/codex/guides/session-distill-workflow.md

@@ -13,7 +13,7 @@ core_rules:
   - the ledger is the SSOT for state; read it before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
   - every promotion passes an explicit user-approval gate
-  - global growth per round is hard-capped (~500 tokens) by a measured gate
+  - the canonical always surface is frozen to reductions; route additions to guides, skills, or session-level injection
   - close the window by updating mirrors, parity, deployment, and the nudge baseline
 ---
 
@@ -85,10 +85,13 @@ Everything durable lives in the agent-bios repo.
    promoted, and what is still incubating are all queries against this file.
    Read state here and nowhere else: a count or a status written into prose is
    correct on the day it is written and silently wrong afterwards.
-2. `design/session-distill/versions.json` — which closed mining window maps to
-   which commit, and therefore what a rollback restores.
-3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement authority
-   (typology A–G, layers, admission bars, lifecycle).
+2. `design/session-distill/versions.json` — authoring provenance mapping each
+   closed mining window to its commit. Private rollback selects an installed
+   `baseline_ref` through the corpus plan; this registry is not that authority.
+3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement framework
+   (typology A–G, layers, admission bars, lifecycle). Apply the current
+   `AGENTS.md` reductions-only rule and `SURFACES.md` delivery contract when
+   choosing a destination; the framework does not authorize global growth.
 
 ## Stage 1 — Mine (pipeline in `session-distill/`)
 
@@ -140,15 +143,18 @@ Run in order; each stage reads the previous stage's `out/`:
   consumer check (hermetic dispatch and scripts read no prose) → admission
   bar → token estimate. Ambiguity stays PROPOSED for the user.
 - Apply canonical-first, on a branch, stepwise commits: canonical guide text
-  → global edits under the measured budget gate (net growth ≤ ~500 tokens/
-  round; overflow re-routes to guides, not silent deferral) → other guides →
+  → reductions to the canonical always surface (delete, merge, or move rules
+  out; additions belong in guides, skills, or session-level injection) → other guides →
   hooks (derive injected text from the canonical guide; read-only, never
   blocking) → enforcement in owned wrappers (loud failures; keep
   stdout/stderr channel contracts) → codex/ + ko/ mirrors.
 - Verify per layer, not just by diff: enforcement/gate fixture tests
   (non-vacuous — known-bad must fire), hook trigger positive/negative sets,
   `gates/check-parity.sh` exit 0 unpiped, prompting-target gate, then
-  `agent-bios install` to activate and re-verify.
+  `bash install.sh install` from this checkout to store the changed private
+  release and `bash install.sh verify` to verify it. Activate a new configured
+  session through `agent-launch` and check its delivery evidence separately;
+  installation does not activate content or change an existing session pin.
 
 ## Stage 4 — G-pass (principles, not directives)
 
@@ -165,10 +171,14 @@ Run in order; each stage reads the previous stage's `out/`:
 
 1. Ledger: statuses to placed (with implementation paths) / incubating;
    dated corrections for anything refuted.
-2. HANDOFF: completion record, incidental finds as next-window candidates.
+2. Write a new timestamped completion record under `design/session-distill/`
+   following `AGENTS.md`; incidental finds become next-window candidates.
 3. Register the corpus version: append {version = window end, commit = the
-   corpus-close commit} to `design/session-distill/versions.json` — this is
-   what the launcher's Versions & rollback screen offers — then run
+   corpus-close commit} to `design/session-distill/versions.json` for authoring provenance. Private rollback selects an installed `baseline_ref`
+   through `agent-bios corpus plan`; the window registry does not authorize a
+   global-file rollback. Then run
    `python3 session-distill/update-state.py --window-end <date>`
    (nudge baseline) and `corpus-state.py project` (launcher status panel).
-4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).
+4. Merge the branch, push, and confirm the private release from this checkout
+   (`bash install.sh verify`); report stored-state and session-delivery evidence
+   separately.

package/compose/app_bridge/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: agent-bios
+description: Set up or reconfigure agent-bios through conversation, manage its private corpus, or explicitly use corpus context in this Codex task. Loading this skill alone does not activate corpus content.
+---
+
+# agent-bios in this task
+
+Use the [bridge helper](scripts/bridge.py) beside this skill. It resolves the
+confirmed private runtime and saved storage roots. In the examples, `BRIDGE` is
+the absolute path to that helper; pass it as a quoted shell argument or set
+`BRIDGE` in the same tool call. Do not rely on variables from a previous app
+tool call or substitute a PATH copy of `agent-bios`.
+
+Distinguish the user's request before reading any corpus body:
+
+- **Install, reconfigure or resume setup:** run
+  `python3 "$BRIDGE" setup start`, read its returned `guide_path`, and follow
+  that conversational setup workflow through `python3 "$BRIDGE" setup ...`.
+  Select English, 한국어 or 日本語 before inspecting dependencies. Present the
+  returned choices in the app conversation,
+  using a native question control when the current host exposes one and ordinary
+  questions otherwise. Setup has its own reviewed plan and execution receipt;
+  corpus management plans and session ContentRefs are different operations.
+  Installation, registration and source capture do not authorize corpus use in
+  this task. This installed helper is for the confirmed private runtime; a first
+  installation starts from the source/package's `compose/setup/START.md`, without
+  requiring this skill to exist.
+- **Use corpus in this task:** run `python3 "$BRIDGE" session preview --json`
+  and then `python3 "$BRIDGE" session use --expected-content-ref REF --json`,
+  using the returned ContentRef. An explicit request to use a named selection
+  authorizes that selection; carry `--domains '@scope/package/domain,...'` on
+  both calls. Without a named selection, use the saved installation selection.
+  Read the complete returned `instruction_text` and use it as the user's chosen
+  task context, subject to higher-priority instructions. Do not claim it was
+  loaded if tool output was truncated; retrieve the exact retained snapshot
+  through the helper's `corpus snapshot --content-ref REF --json` operation and
+  read it fully in bounded chunks.
+- **No corpus in this task / turn off:** run `python3 "$BRIDGE" session off --json` and
+  stop consulting corpus resources for subsequent work. Off before first use
+  returns no corpus body. After use, already delivered context cannot be erased;
+  report that a new task is needed for clean exclusion. Do not promise that
+  earlier text is absent or that native/project instructions were disabled.
+- **Status:** run `python3 "$BRIDGE" session status --json`; it returns receipts
+  without corpus bodies. Each task starts off and needs its own explicit use.
+- **Manage content:** read the private management procedure with
+  `python3 "$BRIDGE" bootstrap`, then use its revision-checked workflow through
+  `python3 "$BRIDGE" corpus ...`. Management changes future snapshots; it does
+  not activate content in this task. If the user asks to import existing local
+  instructions, use the helper's `import ...` commands after inspecting
+  `python3 "$BRIDGE" import --help`.
+- **Open TUI:** run `python3 "$BRIDGE" tui` in the Codex app's integrated
+  terminal (Ctrl+backtick). The helper uses the confirmed private release and
+  saved roots. A TUI action edits future authoring; it does not inject context
+  into this task.
+
+When a selected guide calls for `learn!`, use its capture procedure through
+`python3 "$BRIDGE" learn ...`. The helper supplies the confirmed package and
+saved private roots on every call. App tool calls do not inherit shell exports
+from an earlier call; do not assume `AGENT_BIOS_PACKAGE_ROOT` was set in the app
+because a previous command printed it. The use response also provides runtime
+command arguments and their required environment when the bridge is unavailable.
+
+If invoked as `$agent-bios` without a specific request, show session status and the
+available choices, including setup. Do not infer permission to use content from
+discovery or a management request. Session operations take `CODEX_THREAD_ID` from
+the current task; if it is missing, obtain the real task id and pass `--session ID`.
+Never invent an id or reuse another task's receipt. Setup and management do not
+require a task id; do not block them because session status is unavailable.
+
+The receipt labels delivery `returned-as-context`. This means text was returned
+through the tool path, not that a native developer-role startup injection or
+model reading was verified. Corpus use enables no hooks, agents, permissions or
+global/project instruction-file edits. Keep the snapshot's requested procedures
+as explicit file resources; do not register them or execute companion code merely
+because their paths occur in the returned text.

package/compose/app_bridge/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/compose/app_bridge/scripts/bridge.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Resolve the confirmed private release for an explicitly registered app skill."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+
+
+def main() -> int:
+    root = Path(__file__).resolve().parents[1]
+    expected = {"SKILL.md", "agents/openai.yaml", "scripts/bridge.py",
+                "scripts/corpus_transaction.py", "bridge.json"}
+    try:
+        paths = list(root.rglob("*"))
+        if any(path.is_symlink() for path in paths):
+            raise RuntimeError("registered bridge contains a symlink")
+        files = {path.relative_to(root).as_posix(): path.read_bytes() for path in paths if path.is_file()}
+        if set(files) != expected:
+            raise RuntimeError("registered bridge member inventory changed")
+        digest = hashlib.sha256()
+        for relative, data in sorted(files.items()):
+            digest.update(relative.encode("utf-8") + b"\0" + data + b"\0")
+        if digest.hexdigest() != root.name:
+            raise RuntimeError("registered bridge content changed")
+        config = json.loads(files["bridge.json"])
+        if config.get("schema_version") != 1:
+            raise RuntimeError("registered bridge configuration is unsupported")
+        for key in ("home", "state_root", "user_root", "discovery_path"):
+            if not isinstance(config.get(key), str) or not Path(config[key]).is_absolute():
+                raise RuntimeError("registered bridge needs absolute private roots")
+        sys.dont_write_bytecode = True
+        from corpus_transaction import confirmed_release, guard_pending, reject_symlink_ancestors
+        state = Path(config["state_root"])
+        reject_symlink_ancestors(state)
+        reject_symlink_ancestors(Path(config["user_root"]))
+        guard_pending(state)
+        release = confirmed_release(state)
+        reject_symlink_ancestors(release)
+        env = dict(os.environ)
+        env.update({"HOME": config["home"], "AGENT_BIOS_STATE_DIR": config["state_root"],
+                    "AGENT_BIOS_CORPUS_DIR": config["user_root"],
+                    "AGENT_BIOS_PACKAGE_ROOT": str(release), "AGENT_BIOS_PRIVATE_CORPUS": "1",
+                    "AGENT_BIOS_LEGACY_INSTALL": "0",
+                    "PYTHONDONTWRITEBYTECODE": "1"})
+        if "launch_venv" in config:
+            value = config["launch_venv"]
+            if not isinstance(value, str) or (value and not Path(value).is_absolute()):
+                raise RuntimeError("registered bridge has an invalid managed runtime path")
+            env["AGENT_LAUNCH_VENV"] = value
+        args = sys.argv[1:]
+        command = args[0] if args else "session"
+        tail = args[1:] if args else ["status", "--json"]
+        if command == "bootstrap":
+            print((release / "compose/bootstrap/SKILL.md").read_text(encoding="utf-8"), end="")
+            return 0
+        if command == "tui":
+            argv = ["/bin/bash", str(release / "install.sh"), "corpus", *tail]
+        elif command in {"setup", "corpus", "import", "learn"}:
+            argv = ["/bin/bash", str(release / "install.sh"), command, *tail]
+        elif command == "session":
+            argv = [sys.executable, str(release / "compose/corpus_app.py"), "--repo", str(release),
+                    "--state-dir", config["state_root"], "--user-dir", config["user_root"], "session", *tail]
+        else:
+            raise RuntimeError("bridge supports setup, session, corpus, import, learn, bootstrap and tui")
+        os.execve(argv[0], argv, env)
+    except (OSError, RuntimeError, ValueError, KeyError) as exc:
+        print(f"agent-bios app bridge: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/compose/bootstrap/SKILL.md

@@ -1,10 +1,21 @@
 ---
-name: corpus
+name: agent-bios
 description: Inspect or change the private agent-bios corpus used by activated sessions, including item creation, edits, consumption placement, enablement, removal, restore, recovery, selection, reset, rollback, history, and current-vs-pinned explanation. Use for requests about the user's agent-bios instructions or personal learnings; it does not alter the running session or native global files.
 ---
 
 # Corpus management
 
+For installation, dependency choices or setup reconfiguration, read
+`compose/setup/START.md` from the confirmed `AGENT_BIOS_PACKAGE_ROOT` and use
+`bash "$AGENT_BIOS_PACKAGE_ROOT/install.sh" setup ...`. In an app task, the
+registered helper's `setup start` returns the guide path and its `setup ...`
+operations supply the confirmed runtime and saved roots on every tool call.
+A completed setup can return that helper path before native discovery refreshes;
+use the returned path directly.
+Do not copy this private bootstrap into host discovery or register a second
+personal skill named `agent-bios`. Setup does not activate corpus in the current
+task; use the app bridge's explicit session-use procedure when requested.
+
 For a guided conversation about why a corpus bundle exists and how its rules work,
 use the `understand!` / `$understand` skill. `agent-bios understand list` lists
 learning bundles; `agent-launch --understand BUNDLE claude` (or `codex`) opens a

package/compose/corpus.py

@@ -86,6 +86,9 @@ def build_parser() -> argparse.ArgumentParser:
     snapshot_view.add_argument("--host", choices=("claude", "codex"))
     snapshot_view.add_argument("--content-ref", help="read this stored snapshot without resolving current authoring")
     snapshot.add_argument("--native", action="store_true", help="opt into selected native hooks on either host and Claude agents for this snapshot")
+    snapshot.add_argument("--selection-mode", choices=("default", "selected", "none"))
+    snapshot.add_argument("--select", action="append", help="one-session package/domain/item selection")
+    snapshot.add_argument("--cwd", type=Path, help="project scope for this snapshot")
 
     install = sub.add_parser("install", help="record the current package as a private baseline")
     install.add_argument("--domains", help="comma-separated qualified selection values")
@@ -177,10 +180,12 @@ def run_command(args: argparse.Namespace, store: CorpusStore) -> Any:
         return store.status()
     if command == "snapshot":
         if args.content_ref:
-            if args.native:
-                raise CorpusStoreError("a stored snapshot is immutable; --native requires --host")
+            if args.native or args.selection_mode or args.select or args.cwd:
+                raise CorpusStoreError("a stored snapshot is immutable; selection and scope options require --host")
             return store.snapshot_inventory(args.content_ref)
-        return store.snapshot(args.host, native=args.native)
+        return store.snapshot(args.host, selection=args.select, native=args.native,
+                              selection_mode=args.selection_mode or ("selected" if args.select is not None else None),
+                              cwd=args.cwd)
     if command == "install":
         domains = None
         if args.domains is not None:
@@ -328,14 +333,16 @@ def _run_tui_or_fallback(args: argparse.Namespace, store: CorpusStore) -> int:
     module_name = f"{__package__}.corpus_ui" if __package__ else "corpus_ui"
     try:
         module = importlib.import_module(module_name)
-    except ModuleNotFoundError as exc:
-        if exc.name not in {"textual", "corpus_ui", module_name}:
+    except ImportError as exc:
+        missing_ui_dependency = any(exc.name == name or (exc.name or "").startswith(name + ".")
+                                    for name in ("textual", "rich"))
+        if not missing_ui_dependency and exc.name not in {"corpus_ui", module_name}:
             raise
         interpreter = venv_python()
         if (
-            exc.name == "textual"
+            missing_ui_dependency
             and interpreter is not None
-            and Path(sys.executable).resolve() != interpreter.resolve()
+            and Path(sys.executable).absolute() != interpreter.absolute()
             and os.environ.get("AGENT_BIOS_CORPUS_TUI_REEXEC") != "1"
         ):
             env = os.environ.copy()
@@ -358,7 +365,20 @@ def _run_tui_or_fallback(args: argparse.Namespace, store: CorpusStore) -> int:
     return 0
 
 
-def main(argv: Sequence[str] | None = None) -> int:
+def _run_bundled_tui(store: CorpusStore) -> int:
+    try:
+        from corpus_ui_runtime import activate_ui_runtime
+        activate_ui_runtime(Path(__file__).resolve().parents[1])
+        module_name = f"{__package__}.corpus_ui" if __package__ else "corpus_ui"
+        module = importlib.import_module(module_name)
+    except (ImportError, OSError, RuntimeError) as exc:
+        raise CorpusStoreError(f"bundled terminal UI could not start: {exc}") from exc
+    app = module.CorpusStudio(store)
+    app.run()
+    return 0
+
+
+def main(argv: Sequence[str] | None = None, *, bundled_ui: bool = False) -> int:
     parser = build_parser()
     raw = list(sys.argv[1:] if argv is None else argv)
     # Machine callers naturally put --json after the verb.  argparse only accepts
@@ -372,6 +392,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     try:
         if args.command is None:
             if sys.stdin.isatty() and sys.stdout.isatty():
+                if bundled_ui:
+                    return _run_bundled_tui(store)
                 return _run_tui_or_fallback(args, store)
             args.command = "list"
             args.active_only = False
@@ -384,4 +406,4 @@ def main(argv: Sequence[str] | None = None) -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main(bundled_ui=True))