agent-bios 0.19.0 → 0.19.2

package/docs/setup.md

@@ -1,6 +1,6 @@
 # Setup, app connection, and personal instructions
 
-[← Overview](../README.md) · [Corpus](corpus.md) · [Sessions](session-model.md) · [Recovery](recovery.md)
+[← Overview](../README.md) · [Instructions](instructions.md) · [Sessions](session-model.md) · [Recovery](recovery.md)
 
 Install `agent-bios@0.19.0` through the [README quick start](../README.md#quick-start)
 to use the guided installer, conversation setup, app bridge and instruction import.
@@ -43,24 +43,33 @@ For the source alternative, obtain the repository through its Code menu and run
 `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. App registration is optional.
+1. **Instructions:** no active instructions, all available instructions, 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 and select supported installation
-   recipes. Leaving them unselected installs none.
+   global/project instruction files for capture. This is independent of instructions 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
+The fresh wizard starts with no active instructions. Reinstalling keeps saved choices
+unless you change them. Selecting **No active instructions** retains the library privately but delivers
+no agent-bios 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.
 
-The installer, launcher and Corpus Studio use a verified UI bundle without downloading or installing
+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 instructions policy or new installation
+choices. Selecting **No active instructions** preserves them. Use Instructions 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 Instructions 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,
+bundled UI fails explicitly. Language changes presentation, not instructions text,
 identifiers or host settings.
 
 Back preserves your choices. Cancelling before Apply performs no planned setup
@@ -72,8 +81,8 @@ 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 --instructions none
+agent-bios install --instructions selected --select '@agent-bios/core/builder-base'
 agent-bios install --dry-run
 ```
 
@@ -81,15 +90,15 @@ agent-bios install --dry-run
 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'
+agent-bios install --non-interactive --instructions none
+agent-bios install --non-interactive --instructions all
+agent-bios install --non-interactive --instructions 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`.
+meaning; `--domains none` is different from `--instructions none`.
 
 ## Setup through conversation or automation
 
@@ -110,11 +119,19 @@ 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,
+engine-issued review. It shows the selected commands, destinations, instructions 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. These
+serialized names remain for [compatibility](instructions-compatibility.md). 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.
@@ -123,9 +140,9 @@ 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
+## Use instructions in a Codex app task
 
-Choose app registration during setup, or explicitly run:
+Choose **Connect to the Codex app** during setup, or explicitly run:
 
 ```bash
 agent-bios app register --dry-run
@@ -139,7 +156,7 @@ 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.
+change setup, show task status, or explicitly use selected instructions 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.
 
@@ -149,13 +166,13 @@ Use previews a `ContentRef` and then returns the exact snapshot's
 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
+Ask `$agent-bios` to turn instructions 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
+prior task context or personal instructions data. Instructions Studio can also run in the app's
 integrated terminal; editing it changes future snapshots, not current task context.
 
 ## Import existing instructions
@@ -174,14 +191,14 @@ 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.
+privately. It is pending review, not an automatically optimized personal instructions.
 
 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.
+applicable hosts, even when all instructions 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

package/docs/understand.md

@@ -1,8 +1,8 @@
-# Understand why the corpus works this way
+# Understand why the instructions work 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)
+[← Overview](../README.md) · [Setup](setup.md) · [Instructions](instructions.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.
+Understand! is learning for the person using the instructions, not model training. It explores reasons and limits through a conversation rather than asking you to memorize files.
 
 ## Start a learning session
 
@@ -16,14 +16,57 @@ 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
+domain and personal bundles come from the effective instructions. 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. Each active learning turn ends with one goal-relevant question and
-waits for the user. Incidental ambiguity does not force a detour; pause and stop
-requests end the questioning. `understand!` also works through the shared skill in
+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
@@ -31,10 +74,15 @@ ordering, and asks for a later exact save confirmation. Unsupported provenance l
 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
+requested-only personal instructions 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.
+instructions 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.