agent-bios 0.18.0 → 0.19.1

package/docs/recovery.md

@@ -0,0 +1,201 @@
+# Installation, migration, and recovery
+
+[← Overview](../README.md) · [Setup](setup.md) · [Corpus](corpus.md) · [Sessions](session-model.md) · [Recovery](recovery.md) · [Launch](advanced-launch.md) · [Understand!](understand.md)
+
+Start with `agent-bios status`. Commands use the installed `agent-bios@0.19.1` CLI;
+from a source checkout use `bash install.sh <command>`. For first installation and app
+setup recovery, see [Setup](setup.md). Commands below are **operation references, not a sequence to paste and run**. Preview the specific action you need; do not delete an ownership conflict just to make installation succeed.
+
+## Command reference
+
+The npm package and command are both named `agent-bios`. Installation is always
+explicit—never a package-manager postinstall side effect—and the default path stores
+an immutable release and baseline under agent-bios-owned state. It installs the
+`agent-launch` entrypoint and its own profile/catalog files, but does not change native
+Claude/Codex globals, settings or hooks. Optional app registration adds only its
+owned discovery link, and optional shell connection changes only its owned startup
+wiring. Neither activates corpus in a task.
+
+| Command | Purpose |
+| --- | --- |
+| `npm install -g agent-bios@0.19.1` | install the CLI package; private setup is a separate explicit command |
+| `agent-bios install` | open the guided installation UI |
+| `agent-bios install --non-interactive --corpus none` | store runtime with no active corpus |
+| `agent-bios onboard --non-interactive --domains builder-base,multi-agent-orchestration` | store the named domains with compatibility core/infra selection |
+| `agent-bios setup status --review-id ID` / `resume --review-id ID` | inspect the setup receipt / prepare a safe continuation without executing it |
+| `agent-bios verify` | verify stored bytes/catalog/baseline; not host activation |
+| `agent-bios status` | show the private release, baseline, conflicts, and evidence state |
+| `agent-bios corpus` | rich Corpus Studio in a TTY; list in a non-TTY |
+| `agent-launch claude` | open the launch TUI for Claude |
+| `agent-launch codex` | open the launch TUI for Codex |
+| `agent-bios shell restore` | opt in: bare claude/codex opens the TUI |
+| `agent-bios shell remove` | remove only that optional shell connection |
+| `agent-bios reset` | preview reset; keep sources, snapshots, and pins |
+| `agent-bios reset --apply --yes --expected-revision REV` | use the revision returned by preview |
+| `agent-bios migrate` | preview legacy global cleanup; --apply --yes performs it |
+| `agent-bios update` | git pull + reinstall (clone), or print the npm update line |
+| `agent-bios uninstall` | remove owned runtime entries; retain user corpus and pinned sessions |
+
+`agent-launch` examples assume `~/.local/bin` is on `PATH`; otherwise use `"$HOME/.local/bin/agent-launch"`. From a checkout, deploy with `bash install.sh install` at its root, not the globally installed CLI. A blocked npm postinstall message does not deploy the corpus; the explicit `install` command remains necessary.
+
+## Ownership and legacy migration
+
+`install`, `onboard`, `reset`, `migrate`, and `uninstall` expose dry-run or preview
+paths appropriate to their mutations. A pre-existing owned launcher/profile path whose
+bytes no longer match the recorded copy is reported as an owned-path conflict rather than
+overwritten. `migrate` is the separate recovery-backed operation for a legacy global
+installation: preview is the default, applying requires `--apply --yes`, ambiguous
+ownership refuses the apply, and later private operations do not fall through to a
+global writer. Setting `AGENT_BIOS_LEGACY_INSTALL=1` selects the old deployer only for
+compatibility and migration regression work; it is not the user default.
+
+The legacy compatibility deployer preserves guide paths named only by a previous
+manifest when the current source no longer establishes their ownership. It names
+these remnants for manual inspection and leaves them out of the new ownership
+manifest, so later uninstall does not claim them. Current source-owned members
+retain normal backup and selection cleanup; private snapshot installation uses its
+own authoritative inventory.
+
+After updating a legacy global installation, run `agent-bios migrate` before the
+first private `install`. Its preview identifies exact managed regions, legacy
+manifest paths and learning sources. `agent-bios migrate --apply --yes` backs up
+the originals, transfers and verifies learning records, retires the legacy paths,
+then installs the private release. A central-only Codex file and the unmodified
+empty Claude learning seed do not require a learning JSONL file; actual learning
+content without its source still requires attention.
+
+An interrupted migration is visible in `status` and blocks configuration readers
+and unrelated writes. Re-run `agent-bios migrate --apply --yes` to resume its
+pinned release and recorded path versions. A completed private installation is
+not repeated, and later cleanup cannot delete its replacement launcher/profile.
+Intervening edits are preserved and reported instead of overwritten. Older
+incomplete journals without replay evidence require reconciliation from their
+backups rather than a guessed replay. Existing private-session replay retains the
+previous confirmed release until migration completes.
+
+Before applying or resuming, stop the old global collectors that can still append a native
+learning JSONL or rewrite its native prose/entry file. The migration checks the
+recorded native state immediately before commit, but no filesystem check can make
+a noncooperating writer atomic after that final observation. If it reports a
+changed native target, preserve only the affected paths and restore only those
+paths to the journal's recorded `after` state before resuming the old migration.
+Do not replace a whole native directory or edit the journal.
+
+For a validated late-input recovery, set `JOURNAL` to the one `NEEDS_RECOVERY`
+migration journal and pass only the specific changed JSONL, prose, or entry paths
+that its error named. This makes a new durable copy under that journal's existing
+`backup_root`, verifies the copy, and then restores a changed target from its
+recorded `after` bytes/existence/mode or an input-only path to its recorded
+unchanged existence. It rejects a path absent from the journal, symlinks, and
+non-regular files before writing any backup. New private journals retain exact
+bytes for input-only native files, so the command can restore an originally
+present input while preserving its current mode (or using `0600` if it is
+absent). Historic digest-only journals still need an external byte-identical
+backup; the command refuses to invent their missing bytes.
+
+```sh
+JOURNAL="${AGENT_BIOS_STATE_DIR:-$HOME/.local/share/agent-bios}/runtime/migrations/<migration-id>/journal.json"
+python3 - "$JOURNAL" \
+  "$HOME/.codex/personal/learnings.jsonl" <<'PY'
+import base64, hashlib, json, os, sys, tempfile
+from pathlib import Path
+
+journal = Path(sys.argv[1])
+data = json.loads(journal.read_text(encoding="utf-8"))
+backup_root = Path(data.get("backup_root", ""))
+if data.get("kind") != "migrate" or data.get("state") != "NEEDS_RECOVERY" or backup_root != journal.parent / "backup":
+    raise SystemExit("expected one validated NEEDS_RECOVERY migration journal")
+targets = {Path(entry["path"]): entry for entry in data["paths"]}
+inputs = {Path(path): version for path, version in data["inputs"].items()}
+selected = [Path(value).expanduser() for value in sys.argv[2:]]
+unknown = [str(path) for path in selected if path not in targets and path not in inputs]
+if not selected or unknown:
+    raise SystemExit("name one or more exact journal paths; unknown: " + ", ".join(unknown))
+
+planned = []
+for path in selected:
+    entry = targets.get(path)
+    version = entry["after"] if entry is not None else inputs[path]
+    if path.is_symlink() or (path.exists() and not path.is_file()):
+        raise SystemExit(f"refusing unsafe native path: {path}")
+    root = next((parent for parent in (path.parent, *path.parents)
+                 if parent.name in {".claude", ".codex"}), None)
+    if root is None or root.is_symlink():
+        raise SystemExit(f"recovery supports an exact Claude/Codex native path, not: {path}")
+    current = root
+    for part in path.relative_to(root).parts:
+        current /= part
+        if current.is_symlink():
+            raise SystemExit(f"refusing symlink ancestor: {current}")
+    planned.append((path, entry, version))
+
+if backup_root.is_symlink() or (backup_root.exists() and not backup_root.is_dir()):
+    raise SystemExit(f"refusing unsafe recovery root: {backup_root}")
+backup_root.mkdir(parents=True, exist_ok=True, mode=0o700)
+recovery = Path(tempfile.mkdtemp(prefix="recovery-before-resume-", dir=backup_root)) / "files"
+for path, entry, version in planned:
+    if path.exists():
+        saved = recovery / str(path).lstrip("/")
+        saved.parent.mkdir(parents=True, exist_ok=True)
+        before = path.read_bytes()
+        saved.write_bytes(before)
+        saved.chmod(path.stat().st_mode & 0o777)
+        if saved.read_bytes() != before:
+            raise SystemExit(f"backup did not verify: {saved}")
+    if not version["exists"]:
+        path.unlink(missing_ok=True)
+        continue
+    encoded = version.get("bytes_b64")
+    if not isinstance(encoded, str):
+        raise SystemExit(f"journal records only a digest for existing input; restore it from an exact external backup: {path}")
+    body = base64.b64decode(encoded.encode("ascii"), validate=True)
+    if hashlib.sha256(body).hexdigest() != version["sha256"]:
+        raise SystemExit(f"journal after bytes are invalid: {path}")
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(body)
+            output.flush()
+            os.fsync(output.fileno())
+        mode = entry["mode"] if entry is not None else (path.stat().st_mode & 0o777 if path.exists() else 0o600)
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+print(recovery)
+PY
+```
+
+Resume the old journal with `agent-bios migrate --apply --yes`. After it commits,
+restore only the preserved late record (`B`) from the printed recovery directory
+to its original native path, then run a fresh `agent-bios migrate` preview and
+`agent-bios migrate --apply --yes`. The new migration imports `B` through the
+normal learning-id deduplication path. Leave every other recovery copy in place
+as evidence; it is not an instruction to restore all saved native files.
+
+```sh
+RECOVERY_BACKUP='<the directory printed above>'
+B="$HOME/.codex/personal/learnings.jsonl"  # the one path you deliberately preserved
+cp "$RECOVERY_BACKUP/${B#/}" "$B"
+agent-bios migrate
+agent-bios migrate --apply --yes
+```
+
+## Installation and rollback
+
+Installation and rollback validate the target baseline and personal field/member
+changes together. Conflicts preserve the current selection rather than dropping
+items from a successful snapshot. Installation publishes a complete corpus/config
+association under the same lock used by readers. Pending publication is disclosed
+by status and prevents a new configured launch from reading mixed state; bare and
+pinned replay can use the last confirmed immutable release.
+
+## Full reset
+
+Full reset returns an `expected_revision` in its preview. Pass that value with
+`--apply --yes`; a changed preview is refused. Retry the accepted revision to finish
+an interrupted reset, or review and accept a fresh revision to replace a stale
+reset intent. Later user changes and replacement credentials are not overwritten
+by the old intent. Nonsecret settings are archived; token bytes never are.
+
+Reset also clears individual on/off overrides and the active trophy display generation. It is not a deletion of uploaded learning records. See [corpus controls](corpus.md) and [learning discoveries](understand.md).

package/docs/session-model.md

@@ -0,0 +1,120 @@
+# Sessions, storage, and verification
+
+[← Overview](../README.md) · [Setup](setup.md) · [Corpus](corpus.md) · [Sessions](session-model.md) · [Recovery](recovery.md) · [Launch](advanced-launch.md) · [Understand!](understand.md)
+
+**Library → selection and edits → immutable snapshot → configured session**
+
+## Corpus ownership
+
+Single source of truth for the instructions and scoped guides supplied to activated
+Claude Code or Codex CLI sessions, or explicitly chosen Codex app tasks. Edit once;
+the private corpus compiler projects the selected content through the chosen delivery route.
+
+A deployable instruction corpus for coding agents, plus the CLI that
+installs, verifies, and evolves it. The npm package ships the corpus; `install.sh` is both the
+`agent-bios` CLI entry and the deployer.
+
+## Authored layers
+
+Two authored layers:
+
+- **Always-in-an-activated-session instructions** — `claude/CLAUDE.md` is the English canonical and `codex/AGENTS.md` its generated host projection. They hold compact invariants, decision principles, and guide pointers. A clean private install does not copy either file into a host's global discovery path; `compose/corpus_catalog.py` inventories their registered items and compiles the selected rules into an immutable session snapshot.
+- **Scoped guides** — `claude/guides/`, with generated Codex mirrors. The snapshot compiler copies selected guides to private generation-qualified paths and emits their router. Procedures, tables, numbers, and environment-specific content live here.
+
+## Activation and Vanilla
+
+The private install does not replace the `codex` or `claude` shell commands by default. Run
+`agent-launch claude` or `agent-launch codex` explicitly to open the preflight, or pass `--preset NAME HOST` for a
+configured non-interactive launch. Software Engineer / Vanilla structurally projects
+no agent-bios snapshot, launch contract, tier binding, or permission flag. After a
+fresh private install—or after an explicit legacy migration—the native CLI therefore
+receives no automatic agent-bios content; the user's own native global and project
+instructions still follow the host's normal loading rules. `--resume-session ID`
+loads the recorded host/session pin rather than resolving current defaults.
+
+Per-item on/off overrides take precedence over default-mode launch-domain selection.
+No-corpus mode emits no corpus. Explicit selected mode keeps inclusion within its
+targets; disabled items stay excluded and unrelated enabled overrides do not leak in.
+Imported items also respect their host/project scope. See [corpus selection](corpus.md#manage-the-library). Existing host globals are loaded by default; [selective exclusion](advanced-launch.md#global-instruction-files) is a separate host-specific option.
+
+## Codex app tasks
+
+App tasks have an explicit [use/off workflow](setup.md#use-corpus-in-a-codex-app-task).
+Use returns a selected snapshot through the tool/context path and records a
+`returned-as-context` receipt separately from native CLI pins. Stored registration
+and returned text do not prove native app discovery or model reading. Off stops
+further managed use, but cannot retract earlier context; a new task is needed for
+clean exclusion. Management and instruction capture do not activate task context.
+
+## Storage layout
+
+From a clone, `bash install.sh install` is the same default path. The release lives
+under `~/.local/share/agent-bios/runtime/releases/`; baseline tuples and transaction
+journals live under that runtime root, immutable snapshots and pins under
+`~/.local/share/agent-bios/sessions/`, and user packages, overlays, tombstones,
+learnings, history, and trash under `~/.config/agent-bios/corpus/`. The corresponding
+`AGENT_BIOS_STATE_DIR` and `AGENT_BIOS_CORPUS_DIR` environment variables relocate
+those private roots; `AGENT_LAUNCH_VENV` relocates the managed dependency environment.
+The UI entrypoints use their verified process-temporary bundle without
+requiring a preinstalled Textual runtime.
+The owned `agent-launch` entrypoint exports `AGENT_BIOS_PRIVATE_CORPUS=1` and the
+immutable `AGENT_BIOS_PACKAGE_ROOT`; the launcher also recognizes the private install
+record when the explicit marker is absent. These select the private runtime and do not
+claim that any host session has loaded a snapshot.
+
+## Verification and limits
+
+`agent-bios verify` checks the recorded immutable release file-by-file, reloads a
+non-empty catalog from that release, matches the store's last successful baseline to
+the install record, and verifies the owned launcher/profile/status projections. Its
+result says `activation: unverified`: neither stored bytes nor a dry-run argv proves a
+host loaded the snapshot.
+
+Corpus selection seeds future activated sessions, not plain CLI/Vanilla. A one-off
+`--corpus-domains` selection applies only to that launch. The store composes an
+immutable `ContentRef`; Codex startup preserves the effective native developer
+instructions, injects the private corpus and dynamic launch contract, creates and
+reads back a durable host thread, then records its pin. Claude uses the per-call
+append and requested session id and records a pin only after observing that id in the
+native session log. Real-host probes cover Codex and Claude first-turn delivery,
+including corpus propagation to a launcher-generated Claude workhorse. Claude
+resume restores the pin's exact environment provenance rather than changing an unset
+config-home variable into an explicit default. Post-fix authenticated resume remains
+unverified. Snapshot pin integrity alone does
+not establish that a resumed model request succeeded.
+
+The native Claude plugin bootstrap has advertised selected plugin roots and
+qualified corpus agents. An edited corpus `SessionStart` hook ran automatically
+through its generated plugin. Codex 0.153.4 discovery retains user, project and session
+hooks alongside the selected corpus. A real-host test with a local transport verifies
+that a generated `SessionStart` hook runs and injects context after its exact definition
+is trusted; the untrusted control does neither. This test uses no external model.
+Authenticated corpus-agent execution and native skill-menu registration remain
+unverified; they are separate from hook delivery and launcher-tier child evidence.
+
+Pins preserve environment provenance rather than reconstructing it: the host's
+config-home variable, and `HOME` when needed for default lookup, retain their
+recorded unset, set, or explicitly empty state. A relative native home is resolved
+from the recorded canonical cwd. Pins lacking that context fail explicitly at resume;
+it is never inferred from the caller's environment.
+
+Named native Codex profiles (`--profile` / `-p`) are not supported for private
+activation by the verified 0.153.4 adapter: that host exposes profiles on runtime
+commands but not its effective-config app-server surface. The launcher refuses
+this combination before creating a session rather than substituting base settings.
+Plain CLI/Vanilla profile use is unchanged. Activated private Codex sessions also
+refuse native `--cd`/`-C` cwd overrides before delivery; change to the target project
+first so snapshot scope and native execution agree. Ordinary CLI/Vanilla forwarding
+keeps its native behavior.
+
+Snapshots outside no-corpus mode retain the immutable private management bootstrap
+and put its exact path in the injected startup text, so `$agent-bios` has private
+procedure access even without native skill discovery. Selected requested procedures are exposed the same
+way. This is not a claim that either host registered them in its native skill menu;
+native skill registration remains unverified.
+
+## Scope
+
+The repository and npm package contain corpus sources and private runtime machinery,
+not a user's authoring state, learning events, snapshots, pins, activation journals,
+credentials, native settings, or generated temporary files.

package/docs/setup.md

@@ -0,0 +1,206 @@
+# Setup, app connection, and personal instructions
+
+[← Overview](../README.md) · [Corpus](corpus.md) · [Sessions](session-model.md) · [Recovery](recovery.md)
+
+Install `agent-bios@0.19.1` through the [README quick start](../README.md#quick-start)
+to use the guided installer, conversation setup, app bridge and instruction import.
+Commands below use the installed `agent-bios` CLI. From a source checkout, run
+`bash install.sh <command>` at its root instead.
+
+## Choose where to start
+
+| Route | Requirements | Interface |
+| --- | --- | --- |
+| Codex app | A local task with command/file access on the intended machine, Bash, Python 3.11+ | Questions and effect review in the conversation; no extra Codex CLI or model login |
+| Terminal | macOS or Linux, Bash, Python 3.11+, an input/output terminal; Node.js 18+/npm for package installation | Included Textual wizard |
+| Automation | Bash, Python 3.11+, explicit machine commands | JSON inspection, review and results |
+
+Host CLIs and their authentication are needed when you choose to launch them.
+Node/npm are needed to obtain the npm package and for any selected capability that
+uses them. Source acquisition through the app does not require npm. The app and
+storage routes do not require every host CLI. Full versions,
+purposes and provisioning boundaries are in [Dependencies](../DEPENDENCIES.md).
+
+For first installation in the app, use the one-line request in the README. The
+agent follows [INSTALL.md](../INSTALL.md), asks for English, 한국어 or 日本語, and
+obtains one fixed source revision. It handles the local paths. Downloads and
+retained acquisition artifacts are disclosed before setup Apply. If that revision
+lacks the required setup files, the agent reports this instead of invoking an
+older installation mode.
+
+## Guided terminal installation
+
+Install the exact package version, then start setup:
+
+```bash
+npm install -g agent-bios@0.19.1
+agent-bios install
+```
+
+For the source alternative, obtain the repository through its Code menu and run
+`bash install.sh install` at its root.
+
+`install` and `onboard` open the wizard by default. After the language choice,
+four stages collect the choices:
+
+1. **Corpus:** no active corpus, all available corpus, selected packages/domains,
+   or saved policy on an existing installation. **Connect to the Codex app** is
+   an independent option for adding `$agent-bios` to app conversations.
+2. **Personal instructions:** optionally add project folders and select detected
+   global/project instruction files for capture. This is independent of corpus use.
+3. **Dependencies:** inspect the full inventory. Ready dependencies are checked
+   and cannot be toggled; only missing dependencies with a supported recipe can
+   be selected for installation. Leaving those unselected installs none.
+4. **Review:** inspect the effects and, when useful, expand exact commands and
+   paths before Apply.
+
+The fresh wizard starts with no active corpus. Reinstalling keeps saved choices
+unless you change them. No active corpus retains the library privately but delivers
+no corpus instruction text or management bootstrap. Explicit selected mode includes
+only its targets within applicable host/project scope; it does not add unrelated
+enabled items or implicit core content.
+
+Personal instructions and host learning records already on this device appear in
+a separate checked, read-only list with stored item counts. These entries describe
+retained content across project scopes, not the active corpus policy or new installation
+choices. No active corpus preserves them. Use Corpus Studio for personal content and
+selection changes; merely displaying stored content does not activate it. The list
+can also show retained content after private runtime removal.
+
+The installer, launcher and Corpus Studio use a verified UI bundle without downloading or installing
+Textual. Its extraction is temporary and removed on exit. Missing or damaged
+bundled UI fails explicitly. Language changes presentation, not corpus text,
+identifiers or host settings.
+
+Back preserves your choices. Cancelling before Apply performs no planned setup
+effects. During Apply, cancellation requests a stop at an execution boundary;
+completed package installations remain and are reported. A dependency, runtime,
+app-registration or capture failure can leave completed effects. Review the result
+before retrying rather than assuming everything rolled back.
+
+Selection flags seed the wizard; they do not skip it:
+
+```bash
+agent-bios install --corpus none
+agent-bios install --corpus selected --select '@agent-bios/core/builder-base'
+agent-bios install --dry-run
+```
+
+`--dry-run` permits review but no Apply. A non-TTY caller must explicitly use a
+machine route. Direct storage-only examples are:
+
+```bash
+agent-bios install --non-interactive --corpus none
+agent-bios install --non-interactive --corpus all
+agent-bios install --non-interactive --corpus selected --select '@agent-bios/core/builder-base'
+```
+
+Those direct commands do not collect dependency, app or import choices. Use the
+shared conversation protocol below for a complete machine setup plan. The legacy
+`--domains` flag requires `--non-interactive` and retains its implicit core/infra
+meaning; `--domains none` is different from `--corpus none`.
+
+## Setup through conversation or automation
+
+The app asks questions and displays the review using its available controls. It
+does not require a custom settings panel or a terminal UI. The same controller
+validates and executes terminal and conversation choices.
+
+```bash
+agent-bios setup start
+agent-bios setup inspect --language ko
+agent-bios setup discover --project-root /absolute/project
+agent-bios setup plan --language ko --input setup-choices.json > reviewed-setup.json
+agent-bios setup apply --input reviewed-setup.json --review-id REVIEW_ID --yes
+agent-bios setup status --review-id REVIEW_ID
+agent-bios setup resume --review-id REVIEW_ID
+```
+
+`start` returns the supported languages, execution target and guide without
+dependency probes or private setup writes. Choose the language before `inspect`.
+The agent produces the six choice fields from your answers and saves the entire
+engine-issued review. It shows the selected commands, destinations, corpus policy,
+app change and capture sources before applying authorized effects. The engine
+rejects a changed source, environment, plan or state; `--yes` alone is not evidence
+that the effects were reviewed.
+
+Dependency readiness and installation intent are separate: an already available
+dependency never belongs in the requested `dependencies` list or new install actions.
+The separate `retained_corpus` inventory contains `{target, label, item_count}` rows,
+with localized labels in `display.retained_corpus`, and no instruction bodies. Source
+package choices and the selected activation policy remain independent of that storage
+view; retained entries are not added to `targets` by being displayed.
+
+Status and resume are read-only. An old completed receipt describes that attempt;
+current runtime/helper readiness is reported separately. A running operation can
+defer readiness checks and return null fields while still showing recorded progress.
+Resume returns a fresh nested review only when remaining effects can be determined;
+it does not replay uncertain operations. The agent follows the full procedure in
+[START.md](../compose/setup/START.md), including exact review preservation and verified
+entrypoint handoff. Source and reviewed artifacts remain available for recovery.
+
+## Use corpus in a Codex app task
+
+Choose **Connect to the Codex app** during setup, or explicitly run:
+
+```bash
+agent-bios app register --dry-run
+agent-bios app register
+agent-bios app status --json
+```
+
+Registration creates the owned `~/.agents/skills/agent-bios` discovery link to a
+private immutable helper. Implicit invocation is disabled. An unrelated or edited
+entry is preserved. Registration on disk does not prove the app discovered it;
+setup can return a usable helper path to continue before discovery refreshes.
+
+Once discovered, use `$agent-bios` in the chosen task. Ask it to manage the library,
+change setup, show task status, or explicitly use selected corpus in this task.
+A setup or management request does not activate content. Each task starts with
+managed delivery off and requires its own explicit use.
+
+Use previews a `ContentRef` and then returns the exact snapshot's
+`instruction_text` through the task's tool/context path. The receipt says
+`returned-as-context`; it proves neither native startup injection nor model reading.
+Session operations require the real task ID, normally `CODEX_THREAD_ID`. Setup and
+management do not require that ID. App use enables no hooks, agents or permissions.
+
+Ask `$agent-bios` to turn corpus delivery off to stop consulting it in subsequent
+work. Text already returned cannot be erased; a fresh task is needed for clean
+exclusion. A resumed or forked conversation can carry earlier content independently
+of the new task's receipt. Native global/project instructions still follow host rules.
+
+`agent-bios app unregister` removes only the owned discovery link. It does not erase
+prior task context or personal corpus data. Corpus Studio can also run in the app's
+integrated terminal; editing it changes future snapshots, not current task context.
+
+## Import existing instructions
+
+Setup can capture selected native global/project files for later model review.
+You can also use the explicit import workflow:
+
+```bash
+agent-bios import discover --project /absolute/project --json
+agent-bios import capture --project /absolute/project --path /absolute/project/AGENTS.md --json
+agent-bios import prompt CAPTURE_ID
+agent-bios import plan --input reviewed-import.json --json
+agent-bios import apply PLAN_ID --expected-revision REV --json
+```
+
+Discovery checks known global locations and fixed filenames in chosen project
+roots. It does not crawl the home directory or follow instruction references.
+Capture preserves originals and stores redacted evidence with source digests
+privately. It is pending review, not an automatically optimized personal corpus.
+
+In an app task, ask `$agent-bios` to review the returned capture ID. The agent
+proposes content, `always`/`relevant`/`requested` placement, rationale, and source-line
+coverage or exclusions. The runtime checks the evidence and structure, and Apply
+requires the reviewed revision. Changed originals or conflicting edits require
+fresh review. Project-scoped imports remain limited to their recorded root and
+applicable hosts, even when all corpus or an enable override is selected.
+
+Native hosts may still read the untouched originals. Importing a procedure as
+requested content does not suppress the same rule in a native file, and changing
+placement is not a guarantee of optimal model behavior. Review duplication and
+tradeoffs as part of the proposal. Installation, capture, import and task activation
+have separate outcomes; the result tells you which actually completed.

package/docs/understand.md

@@ -0,0 +1,88 @@
+# Understand why the corpus works this way
+
+[← Overview](../README.md) · [Setup](setup.md) · [Corpus](corpus.md) · [Sessions](session-model.md) · [Recovery](recovery.md) · [Launch](advanced-launch.md) · [Understand!](understand.md)
+
+Understand! is learning for the person using the corpus, not model training. It explores reasons and limits through a conversation rather than asking you to memorize files.
+
+## Start a learning session
+
+Choose **Understand!** in the root TUI, or run:
+
+```bash
+agent-bios understand list
+agent-bios understand show core-purpose
+agent-launch --understand core-purpose claude   # or codex
+```
+
+The selection is a coherent bundle, not an individual file: core groups cover goals
+and scope, decision support, adaptation, evidence/safety, and retained learning;
+domain and personal bundles come from the effective corpus. A session freezes its
+selected source references and edited content. The tutor explains the purpose,
+background, mechanisms, tradeoffs, and limits, distinguishing documented rationale
+from inference. The tutor chooses a small finite set of core points and tracks their
+coverage and question counts. It uses fewer questions when understanding is sufficient,
+with at most 10 tutor questions per source bullet including all followups and
+clarifications. Ten is a ceiling, not a target. At the limit it explains remaining
+gaps instead of extending the quiz. Supporting guides supply context, not a list of
+implementation details to examine one by one.
+
+Questions are optional when explaining, answering or summarizing. Once the core
+points are covered, the tutor summarizes and ends without a compulsory followup.
+If it asks a useful question, it waits for your answer. Pause and stop requests end
+the questioning immediately. This is the tutoring contract; the runtime does not
+claim to measure understanding or independently count semantic questions.
+`understand!` also works through the shared skill in
+an activated session. Learning excerpts are data, not permission to run their commands.
+
+## Read pinned material in bounded pages
+
+Startup contains a small tutoring prompt, not the full source bundle. `show` gives
+bundle metadata, and `start`/`session` return a compact entry with the pinned source
+reference. The full source stays in private session storage. Read it on demand:
+
+```bash
+agent-bios understand read SESSION
+agent-bios understand read SESSION --ref '@agent-bios/core:rule-004'
+agent-bios understand read SESSION --ref REF --member MEMBER --offset NEXT --expected-sha256 DIGEST
+```
+
+Without `--ref`, the reader pages a manifest of items and member names without their
+bodies. With a reference it reads the exact effective body, or the named member.
+Each response includes `text`, `source_ref`, `resource_sha256`, `total_bytes`,
+`next_offset` and `eof`. Follow offsets until the needed resource is complete;
+partial output is never a complete-source claim. Offsets count UTF-8 bytes and stay
+on character boundaries, including for a large guide written on one line.
+
+`--limit-bytes` accepts 256–16384 bytes, default 8192. The entire JSON response,
+including escaping and metadata, is capped at 32768 bytes. Transcript inspection
+through `turns SESSION` uses the same page format; later transcript pages require
+the preceding digest and restart if the transcript changed. All prior assistant
+turns must still be reviewed before proposing a discovery.
+
+Existing pinned sessions and older full-bundle prompt files are not rewritten.
+Use `session SESSION` for the current compact entry and the reader for their exact
+retained source. This does not erase earlier instructions from an already running
+conversation. A resumed old host still needs the current reader and tutoring skill
+to follow this workflow.
+
+## Personal discoveries
+
+A meaningful flaw or alternative first introduced by the user can unlock a persistent
+pixel trophy. Tutor-originated ideas, leading hints, and echoes do not qualify. The
+discovery flow binds the native human session, checks recorded turn provenance and
+ordering, and asks for a later exact save confirmation. Unsupported provenance leaves
+the award pending, without blocking learning. Significance and semantic originality
+remain explicit tutor/user judgments; transcript validation does not prove them or
+authenticate against an owner who can edit local files. Only a successfully saved
+requested-only personal corpus note can unlock the trophy. The CLI prints it, and the
+TUI shows it when there is room. Retries do not duplicate the note; updates and note
+deletion retain the trophy. Full reset archives the active unlock generation and clears
+the display; older discovery records cannot reactivate it. Native global files and
+corpus source rules are not rewritten by learning.
+
+The runtime checks a new proposal's complete review-response size before storing
+its candidate. An oversized proposal can be shortened and retried without leaving
+an unreachable candidate; required provenance IDs must remain complete. Award
+responses contain a compact receipt, so the saved note body is not echoed in full.
+
+Turning an item off for ordinary activated sessions does not remove it from the learning library. On/off preferences and the inventory read revision are not learning content, so they do not repin otherwise unchanged learning bundles.