agent-bios 0.9.8 → 0.9.9

package/{scripts/install.sh → install.sh}

@@ -25,7 +25,14 @@ set -euo pipefail
 # CI, pipes, and background runs, where stdin stays open but never delivers.
 # `learn` is the one subcommand whose payload IS stdin, so keep the caller's on
 # fd 3 first and hand it back only there; every other path still sees /dev/null.
-exec 3<&0 2>/dev/null || exec 3</dev/null   # tolerate a caller that closed fd 0
+# The braces matter. `exec` with redirections and no command applies them to the
+# SHELL, permanently — so the bare `exec 3<&0 2>/dev/null` this used to be sent
+# every later error message on this script's stderr to /dev/null: bash's own
+# set -e diagnostics, python tracebacks from deployed steps, and any `>&2` an
+# author writes. Only stdout survived, which is why a failing install could stop
+# with no reason on screen. The group scopes the suppression to the one command
+# whose error is expected when a caller closed fd 0.
+{ exec 3<&0; } 2>/dev/null || exec 3</dev/null   # tolerate a caller that closed fd 0
 exec </dev/null
 
 # Resolve this script through symlinks before locating the package: npm links the
@@ -42,7 +49,7 @@ while [ -L "$SOURCE" ]; do
   esac
 done
 SELF="$(cd -P "$(dirname "$SOURCE")" && pwd)"
-REPO="$(cd "$SELF/.." && pwd)"
+REPO="$SELF"
 
 CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
@@ -52,6 +59,11 @@ BIN_DIR="$HOME/.local/bin"
 STATE_DIR="$HOME/.local/share/agent-bios"
 LEGACY_STATE_DIR="$HOME/.local/share/agent-dotfiles"  # pre-rename state; migrated on first run
 MANIFEST="$STATE_DIR/manifest.txt"
+# The manifest is truncated at the start of every install, so what the PREVIOUS one deployed
+# must be preserved before that happens. It is the only record that a file now on disk was
+# written by us rather than authored by the user, and seed_entry needs exactly that to tell a
+# previous release's deployed entry from someone's own CLAUDE.md.
+PRIOR_MANIFEST="$STATE_DIR/manifest.prev.txt"
 ZSHRC="${ZDOTDIR:-$HOME}/.zshrc"
 ZSH_HOOK='[ -r "$HOME/.config/agent-launch/shell.zsh" ] && source "$HOME/.config/agent-launch/shell.zsh"'
 HOOK_MARK='agent-launch/shell.zsh'
@@ -105,35 +117,129 @@ deploy_glob() {
   done
 }
 
-# ---- packaged (domain-selected) corpus deploy ----------------------------
-# Active when --domains is passed or a prior selection exists in STATE_DIR.
-# assemble.py owns the corpus surfaces (central tree, entry seeding, codex
-# marker region, settings merge); the entry CLAUDE.md and AGENTS.md are NOT
-# manifested — the entry is user-owned after seeding, AGENTS.md holds a
-# personal region — so uninstall never deletes them.
-# Full mode never runs the assembler, so nothing registered the hooks it
-# deployed — the files landed and never fired. Reuse the assembler's own merge
-# so both install paths register identically, under one ownership rule.
-register_hooks_full() {
-  [ "$DRY_RUN" = 1 ] && { info "[dry-run] register central hooks"; return 0; }
-  python3 "$REPO/scripts/register-hooks.py" "$REPO" "$CLAUDE_DIR" \
-    || log "note: hook registration failed; the deployed hooks will not fire"
+# Backups are made on every install and every uninstall, and nothing used to remove them — 23
+# directories in two weeks on the first machine measured, plus loose `.bak-*` files sitting in
+# the user's own config dirs. Pruning runs AFTER the new copy exists, never before, so a failed
+# run cannot leave the user with neither the change nor its backup.
+prune_backups() {
+  [ -f "$REPO/compose/prune-backups.py" ] || return 0
+  python3 "$REPO/compose/prune-backups.py" --state-dir "$STATE_DIR" \
+    --claude-dir "$CLAUDE_DIR" --codex-dir "$CODEX_DIR" \
+    $([ "$DRY_RUN" = 1 ] && echo --dry-run) || log "note: backup pruning skipped"
 }
 
-packaged_mode() { [ "${DOMAINS_SET:-0}" = 1 ] || [ -f "$STATE_DIR/selection.json" ]; }
+# Guides whose frontmatter declares `audience: author`. They document steps only
+# the corpus author can perform and name paths that exist in a checkout and
+# nowhere else, so they are never installed. compose/assemble.py owns the
+# declaration and withholds them from the destinations it writes; this asks it
+# rather than keeping a second parser. Both callers below need that same answer
+# for ground the assembler never writes — the sweep of the pre-unification
+# $CLAUDE_DIR/guides, and verify's check that the absence holds in all three
+# directories. Absence of the assembler degrades to withholding nothing.
+# Fails LOUD, never open. An empty answer here means "withhold nothing", so
+# swallowing an unreadable declaration would deploy exactly the guides this rule
+# exists to hold back — the fail-open shape of every other degrade-on-absence
+# fallback in this file, but inverted. compose/assemble.py ships, so its absence
+# is a broken payload rather than a configuration a user might have.
+author_only_guides() {
+  local out
+  if ! out=$(python3 - "$REPO" <<'PY'
+import pathlib, sys
+root = pathlib.Path(sys.argv[1])
+sys.path.insert(0, str(root / "compose"))
+try:
+    from assemble import author_only
+except ImportError as exc:
+    raise SystemExit(f"compose/assemble.py owns the audience declaration and "
+                     f"could not be imported ({exc})")
+guides = root / "claude" / "guides"
+if not guides.is_dir():
+    raise SystemExit(f"{guides} is missing; the payload is incomplete")
+for p in sorted(guides.glob("*.md")):
+    if author_only(p):
+        print(p.name)
+PY
+  ); then
+    # stderr, not stdout: every caller reads this function through a command
+    # substitution, so anything printed normally would be captured INTO the
+    # variable instead of reaching the operator — and `exit` here would leave
+    # only the subshell, letting the caller proceed with the error text as its
+    # list of withheld guides. The caller checks the status and exits itself.
+    log "cannot read which guides are author-only — refusing to deploy rather than" >&2
+    log "  shipping them by default. compose/assemble.py owns that declaration and" >&2
+    log "  must be present; reinstall the package." >&2
+    return 1
+  fi
+  printf '%s\n' "$out"
+}
 
-assemble_packaged() {
+# Remove a withheld guide from a directory this installer deploys into, backing it
+# up first exactly as deploy_file backs up a file it is about to overwrite. An
+# unconditional rm would delete a same-named file this installer never wrote, and
+# a shared or symlinked guides directory makes that somebody's own file.
+prune_withheld() {
+  local dstdir="$1" base
+  printf '%s\n' "$WITHHELD_GUIDES" | while IFS= read -r base; do
+    [ -n "$base" ] || continue
+    [ -f "$dstdir/$base" ] || continue
+    if [ -n "$BACKUP_DIR" ]; then
+      run mkdir -p "$(dirname "$BACKUP_DIR$dstdir/$base")"
+      run cp "$dstdir/$base" "$BACKUP_DIR$dstdir/$base"
+    fi
+    run rm -f "$dstdir/$base"
+    [ "$DRY_RUN" = 1 ] || info "withheld (audience: author), removed stale copy: $dstdir/$base"
+  done
+}
+
+# ---- corpus deploy -------------------------------------------------------
+# assemble.py owns the corpus surfaces (central tree, entry seeding, codex marker region,
+# settings merge). The entry CLAUDE.md and AGENTS.md are NOT manifested — the entry is
+# user-owned after seeding and AGENTS.md holds a personal region — so uninstall removes our
+# central tree and marked regions and leaves the user's file itself alone.
+# There is ONE install shape. There used to be two: a "full" deploy that wrote the corpus into
+# the entry file, and a packaged one that assembled selected domains under `central/` and left the
+# entry file to the user. They differed in the thing that matters most — who owns the entry file —
+# so the same path was ours in one mode and theirs in the other, and no rule about user-owned
+# content could be true of both. Full mode is now "every domain selected": the same assembly, the
+# same ownership, one set of answers.
+#
+# What this buys, in the order the questions were asked: the user's own additions live in a file
+# we never rewrite, so they are separately versioned by construction; a package can be added or
+# dropped later by re-assembling, with no need to know which bytes came from where; and uninstall
+# can take everything of ours because nothing of theirs is mixed into it.
+assemble_corpus() {
   local args=(--claude-dir "$CLAUDE_DIR" --codex-dir "$CODEX_DIR" --state-dir "$STATE_DIR") rc=0
-  [ "${DOMAINS_SET:-0}" = 1 ] && args+=(--domains "$DOMAINS_ARG")
+  if [ "${DOMAINS_SET:-0}" = 1 ]; then
+    args+=(--domains "$DOMAINS_ARG")
+  elif [ ! -f "$STATE_DIR/selection.json" ]; then
+    # No flag and no saved selection: install everything. This is what "full" meant, expressed as
+    # a selection so it goes down the same path as every other one.
+    args+=(--domains "$(python3 -c "import json,sys;print(','.join(sorted(json.load(open(sys.argv[1]))['domains'])))" "$REPO/compose/domains.json")")
+  fi
   [ "$DRY_RUN" = 1 ] && args+=(--dry-run)
-  python3 "$REPO/scripts/assemble.py" "${args[@]}" || rc=$?
+  # A dry run never truncated the manifest, so the live one still describes the last install.
+  local prior="$PRIOR_MANIFEST"
+  [ "$DRY_RUN" = 1 ] && prior="$MANIFEST"
+  [ -f "$prior" ] && args+=(--prior-manifest "$prior")
+  python3 "$REPO/compose/assemble.py" "${args[@]}" || rc=$?
   if [ "$rc" = 2 ]; then
-    log "packaged: entry file needs user action (import line missing); central content will not load until it is added"
+    log "entry file needs user action (import line missing); central content will not load until it is added"
   elif [ "$rc" != 0 ]; then
     return 1
   fi
   if [ "$DRY_RUN" != 1 ]; then
-    find "$CLAUDE_DIR/central" "$CODEX_DIR/guides" -type f 2>/dev/null >> "$MANIFEST"
+    # `central/` is ours whole, so scanning it is right. `$CODEX_DIR/guides` is SHARED — the
+    # user and other tools keep files there, and the assembler deliberately leaves any name it
+    # did not deploy alone. Scanning that directory claimed those files anyway, and uninstall
+    # removes whatever the manifest names, so the protection was undone one step later. The
+    # ownership rule is the assembler's: the name exists in our source tree.
+    find "$CLAUDE_DIR/central" -type f 2>/dev/null >> "$MANIFEST"
+    local g dst
+    for g in "$REPO"/codex/guides/*.md; do
+      [ -f "$g" ] || continue
+      dst="$CODEX_DIR/guides/$(basename "$g")"
+      [ -f "$dst" ] && printf '%s\n' "$dst" >> "$MANIFEST"
+    done
   fi
 }
 
@@ -309,13 +415,25 @@ PY
 
 # ---- optional dependencies -----------------------------------------------
 # Capabilities are optional: a missing one only degrades the review routes that
-# need it. config/agent-launch.toml is the single source for both the command
+# need it. launch/agent-launch.toml is the single source for both the command
 # that gates a route and the install line offered here.
 capability_table() {
-  python3 - "$REPO/config/agent-launch.toml" <<'PY'
+  python3 - "$REPO/launch/agent-launch.toml" <<'PY'
 import sys, tomllib
-for name, cap in tomllib.load(open(sys.argv[1], "rb")).get("capabilities", {}).items():
-    print("\t".join((name, cap.get("command", ""), cap.get("install", ""))))
+# `${backend}` means "the CLI of the host this capability offers on". Resolved HERE because
+# the probe below runs `command -v` on whatever this prints, and the literal sentinel is not
+# a command: the built-in workflow capability reported as unavailable while the launcher ran
+# it perfectly well.
+data = tomllib.load(open(sys.argv[1], "rb"))
+backends = data.get("backends", {})
+for name, cap in data.get("capabilities", {}).items():
+    command = cap.get("command", "")
+    if command == "${backend}":
+        hosts = sorted({h for offer in cap.get("offers", []) for h in offer.get("hosts", [])})
+        command = next(
+            (backends[h]["command"] for h in hosts if backends.get(h, {}).get("command")), ""
+        )
+    print("\t".join((name, command, cap.get("install", ""))))
 PY
 }
 
@@ -339,6 +457,16 @@ handle_capabilities() {
     [ -n "$name" ] || continue
     if command -v "$command" >/dev/null 2>&1; then
       info "capability present  $name ($command)"
+      # Explicitly requested, already there, and nothing to install: say so, because after
+      # the rename `--with ultracode` names the claude-backed reviewer — which needs no
+      # install — while the tool the user probably meant stays missing and is only hinted
+      # at further down. The request silently no-opped and install still exited 0.
+      if [ -z "$line" ] && printf '%s\n' "${requested//,/ }" | tr ' ' '\n' | grep -qx "$name"; then
+        log "note: $name needs no install (it is the host CLI); nothing was installed for it"
+        local installable
+        installable=$(capability_table | awk -F'\t' -v me="$name" '$1 != me && $3 != "" { print $1 }' | tr '\n' ' ')
+        [ -n "$installable" ] && log "      capabilities that DO install: ${installable% }"
+      fi
       continue
     fi
     if printf '%s\n' "${requested//,/ }" | tr ' ' '\n' | grep -qx "$name"; then
@@ -362,7 +490,7 @@ EOF
 # Presets the launcher saved into the deployed profiles.toml (pre-split, or by hand)
 # would be lost to the cp below; move them into the user-owned presets file first.
 migrate_user_presets() {
-  local src="$REPO/config/agent-launch.toml"
+  local src="$REPO/launch/agent-launch.toml"
   local dst="$LAUNCH_DIR/profiles.toml"
   local user="$LAUNCH_DIR/$USER_PRESETS_NAME"
   [ -f "$dst" ] || return 0
@@ -429,10 +557,10 @@ remove_zsh_hook() {
 # corpus AND are in this user's assembled bundle. Best-effort: a prune failure
 # (or an absent manifest/script) never fails the install. Runs per host.
 migrate_learnings() {
-  local script="$REPO/scripts/migrate-learnings.py"
-  { [ -f "$script" ] && [ -f "$REPO/config/promotions.json" ]; } || return 0
+  local script="$REPO/learn/migrate-learnings.py"
+  { [ -f "$script" ] && [ -f "$REPO/learn/promotions.json" ]; } || return 0
   local -a sel dry
-  if packaged_mode; then sel=(--selection-file "$STATE_DIR/selection.json"); else sel=(--full); fi
+  sel=(--selection-file "$STATE_DIR/selection.json")
   [ "$DRY_RUN" = 1 ] && dry=(--dry-run) || dry=()
   # ${dry[@]+...}: expanding an empty array as "${dry[@]}" is an unbound-variable
   # error under `set -u` on bash 3.2 (macOS default) and would abort the install.
@@ -449,32 +577,31 @@ cmd_install() {
   if [ "$DRY_RUN" != 1 ]; then
     mkdir -p "$STATE_DIR"
     BACKUP_DIR="$STATE_DIR/backups/$(date +%Y%m%d-%H%M%S)"
+    [ -f "$MANIFEST" ] && cp "$MANIFEST" "$PRIOR_MANIFEST"
     : > "$MANIFEST"
   fi
   log "Deploying agent-bios from $REPO"
-  if packaged_mode; then
-    log "packaged mode: assembling selected domains (state: $STATE_DIR/selection.json)"
-    assemble_packaged || exit 1
-  else
-    deploy_file "$REPO/claude/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md"
-    deploy_glob "$REPO/claude/guides" "*.md" "$CLAUDE_DIR/guides"
-    deploy_glob "$REPO/claude/agents" "*.md" "$CLAUDE_DIR/agents"
-    # Our hooks go under central/: <claude>/hooks is shared with other tools
-    # files, caches, and state, and we must not own a directory we share.
-    deploy_glob "$REPO/claude/hooks" "*.py" "$CLAUDE_DIR/central/hooks" "+x"
-    register_hooks_full
-    deploy_file "$REPO/codex/AGENTS.md" "$CODEX_DIR/AGENTS.md"
-    deploy_glob "$REPO/codex/guides" "*.md" "$CODEX_DIR/guides"
-  fi
+  # Refuse loudly before doing any work: an unreadable declaration must not degrade
+  # into withholding nothing, which is the fail-open shape this rule exists to avoid.
+  WITHHELD_GUIDES="$(author_only_guides)" || exit 1
+  assemble_corpus || exit 1
+  # assemble.py withholds author-only guides and prunes the destinations it writes.
+  # $CLAUDE_DIR/guides is not one of them — it is where the pre-unification full
+  # install put guides, so a machine that installed then would keep its copy for good.
+  prune_withheld "$CLAUDE_DIR/guides"
   migrate_learnings   # Phase 4: clear personal copies now absorbed by the corpus
   deploy_glob "$REPO/codex/agents" "*.toml" "$CODEX_DIR/agents"
   codex_config_additions merge || exit 1
-  deploy_file "$REPO/scripts/codex-run.sh"  "$CODEX_DIR/bin/codex-run"  "+x"
-  deploy_file "$REPO/scripts/codex-helm.sh" "$CODEX_DIR/bin/codex-helm" "+x"
+  deploy_file "$REPO/wrappers/codex-run.sh"  "$CODEX_DIR/bin/codex-run"  "+x"
+  deploy_file "$REPO/wrappers/codex-helm.sh" "$CODEX_DIR/bin/codex-helm" "+x"
+  # The claude-side adapter lands under CLAUDE_DIR for the same reason its codex twin
+  # lands under CODEX_DIR: each is that host's, and a single shared bin would make the
+  # two families' review routes indistinguishable from their install paths.
+  deploy_file "$REPO/wrappers/claude-run.sh" "$CLAUDE_DIR/bin/claude-run" "+x"
   migrate_user_presets || exit 1   # must precede the deploy below, which overwrites profiles.toml
-  deploy_file "$REPO/config/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"
-  deploy_file "$REPO/shell/agent-launch.zsh"   "$LAUNCH_DIR/shell.zsh"
-  deploy_file "$REPO/scripts/agent-launch.py"  "$BIN_DIR/agent-launch" "+x"
+  deploy_file "$REPO/launch/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"
+  deploy_file "$REPO/launch/agent-launch.zsh"   "$LAUNCH_DIR/shell.zsh"
+  deploy_file "$REPO/launch/agent-launch.py"  "$BIN_DIR/agent-launch" "+x"
   log ""
   log "Optional dependencies (missing ones only degrade the routes that need them)..."
   handle_capabilities "$WITH" || exit 1
@@ -482,11 +609,11 @@ cmd_install() {
   if [ "$DRY_RUN" = 1 ]; then
     info "[dry-run] provision managed Textual venv"
   else
-    bash "$REPO/scripts/provision-venv.sh" && info "managed venv OK" \
+    bash "$REPO/launch/provision-venv.sh" && info "managed venv OK" \
       || log "warning: venv provisioning failed (numbered-prompt fallback applies)"
   fi
   add_zsh_hook
-  if python3 "$REPO/scripts/session-distill/corpus-state.py" project --repo "$REPO" >/dev/null 2>&1; then
+  if python3 "$REPO/compose/corpus-state.py" project --repo "$REPO" >/dev/null 2>&1; then
     info "corpus-status projected"
   else
     log "note: corpus-status projection unavailable (versions.json/ledger missing?)"
@@ -517,6 +644,7 @@ PY
     # An untouched backup dir means nothing was replaced; that healthy state
     # must not become a nonzero exit under set -e.
     { [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ] && log "Replaced files were backed up under $BACKUP_DIR"; } || true
+    prune_backups
   else
     log "VERIFY FAILED after install — see messages above"
     exit 1
@@ -527,37 +655,60 @@ verify_match()   { if cmp -s "$1" "$2"; then info "match    $2"; else log "MISMA
 verify_present() { if [ -f "$1" ]; then return 0; else log "missing  $1"; return 1; fi; }
 
 cmd_verify() {
-  local fail=0 gp
+  local fail=0 gp gb
   if [ ! -d "$REPO/.git" ] && [ "$(drift_state)" = "drift" ]; then
     log "deploy drift: deployed $(deployed_version), package $(source_version) — run: agent-bios install"
     fail=1
   fi
-  if packaged_mode; then
-    # Packaged: corpus surfaces are selection-derived, not repo-identical.
-    # The entry file is user-owned — READ-check the import line, never rewrite.
-    python3 "$REPO/scripts/check-domains.py" >/dev/null 2>&1 && info "domains gate OK" || { log "domains gate FAILED"; fail=1; }
-    verify_present "$CLAUDE_DIR/central/bundle.md" || fail=1
-    if grep -qF '@central/bundle.md' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null; then
-      info "entry import line present"
-    else
-      log "entry $CLAUDE_DIR/CLAUDE.md lacks '@central/bundle.md' — central corpus is NOT loading"; fail=1
-    fi
-    if grep -qF 'agent-bios:central:start' "$CODEX_DIR/AGENTS.md" 2>/dev/null; then
-      info "codex central region present"
-    else
-      log "codex AGENTS.md central region missing"; fail=1
-    fi
+  # Not mode-specific: an author-only guide must be absent from EVERY directory any
+  # install writes, including the one the pre-unification full install owned.
+  local verify_withheld
+  verify_withheld="$(author_only_guides)" || return 1
+  for gb in $verify_withheld; do
+    for gp in "$CLAUDE_DIR/guides/$gb" "$CLAUDE_DIR/central/guides/$gb" "$CODEX_DIR/guides/$gb"; do
+      if [ -f "$gp" ]; then
+        log "author-only guide is still installed: $gp"; fail=1
+      fi
+    done
+  done
+  [ -n "$verify_withheld" ] && info "author-only guides withheld: $(printf '%s' "$verify_withheld" | tr '\n' ' ')"
+  # Corpus surfaces are selection-derived, not repo-identical, so verify reads the assembled
+  # shape rather than byte-comparing against the repo. The entry file is user-owned — READ-check
+  # the import line, never rewrite it.
+  python3 "$REPO/compose/check-domains.py" >/dev/null 2>&1 && info "domains gate OK" || { log "domains gate FAILED"; fail=1; }
+  verify_present "$CLAUDE_DIR/central/bundle.md" || fail=1
+  if grep -qF '@central/bundle.md' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null; then
+    info "entry import line present"
+  else
+    log "entry $CLAUDE_DIR/CLAUDE.md lacks '@central/bundle.md' — central corpus is NOT loading"; fail=1
+  fi
+  if grep -qF 'agent-bios:central:start' "$CODEX_DIR/AGENTS.md" 2>/dev/null; then
+    info "codex central region present"
+  else
+    log "codex AGENTS.md central region missing"; fail=1
+  fi
+  # Every capability must probe as a real command. `${backend}` reaching this table means
+  # the sentinel was not resolved, and the probe below would then report a capability the
+  # launcher can run perfectly well as unavailable.
+  if capability_table | awk -F'\t' '$2 == "" || $2 == "${backend}" { print; found=1 } END { exit !found }' >/dev/null 2>&1; then
+    log "capability table has an unresolved or empty command — the installer would misreport it"; fail=1
   else
-    verify_match "$REPO/claude/CLAUDE.md"        "$CLAUDE_DIR/CLAUDE.md"        || fail=1
-    verify_match "$REPO/codex/AGENTS.md"         "$CODEX_DIR/AGENTS.md"         || fail=1
-    for gp in "$REPO"/claude/guides/*.md; do verify_present "$CLAUDE_DIR/guides/$(basename "$gp")" || fail=1; done
-    for gp in "$REPO"/claude/agents/*.md; do verify_present "$CLAUDE_DIR/agents/$(basename "$gp")" || fail=1; done
-    for gp in "$REPO"/claude/hooks/*.py;  do verify_present "$CLAUDE_DIR/central/hooks/$(basename "$gp")"  || fail=1; done
-    for gp in "$REPO"/codex/guides/*.md;  do verify_present "$CODEX_DIR/guides/$(basename "$gp")"  || fail=1; done
-  fi
-  verify_match "$REPO/scripts/agent-launch.py" "$BIN_DIR/agent-launch"        || fail=1
-  verify_match "$REPO/config/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"   || fail=1
-  verify_match "$REPO/shell/agent-launch.zsh"  "$LAUNCH_DIR/shell.zsh"        || fail=1
+    info "capability commands resolve"
+  fi
+  # The help's --with list must BE the capability table, not a copy of it: the copy went
+  # stale on the first rename and advertised a name that selects a different capability
+  # than the one carrying the install line.
+  local advertised table
+  advertised=$(usage 2>/dev/null | sed -n 's/^ *--with names: //p')
+  table=$(capability_table 2>/dev/null | cut -f1 | tr '\n' ' ')
+  if [ "$advertised" = "${table% }" ]; then
+    info "--with help matches the capability table"
+  else
+    log "--with help advertises '$advertised' but the capabilities are '${table% }'"; fail=1
+  fi
+  verify_match "$REPO/launch/agent-launch.py" "$BIN_DIR/agent-launch"        || fail=1
+  verify_match "$REPO/launch/agent-launch.toml" "$LAUNCH_DIR/profiles.toml"   || fail=1
+  verify_match "$REPO/launch/agent-launch.zsh"  "$LAUNCH_DIR/shell.zsh"        || fail=1
   python3 - "$CODEX_DIR/agents" <<'PY' && info "agent TOMLs OK" || fail=1
 import sys, pathlib, tomllib
 root = pathlib.Path(sys.argv[1])
@@ -575,6 +726,24 @@ PY
       log "codex-helm dry-run FAILED"; fail=1
     fi
   fi
+  # Existence first, because the guard below is written as `if executable` and a MISSING
+  # adapter would satisfy it by never running — a deploy target whose only check skips
+  # itself when the deploy failed is not checked at all.
+  verify_present "$CLAUDE_DIR/bin/claude-run" || fail=1
+  # Then WHICH version landed, because this file is on the panel's dispatch path now and
+  # an older copy would dispatch reviews that quietly emit nothing. The earlier check
+  # here asserted that an unpinned dispatch is refused; that guard was deliberately
+  # removed when the adapter went live — refusing turned "the review ran unpinned" into
+  # "the review did not run" — so asserting it would now fail against correct behaviour.
+  # `--help` is the only probe that reaches no network: an unpinned run warns and then
+  # dispatches for real.
+  if [ -x "$CLAUDE_DIR/bin/claude-run" ]; then
+    if "$CLAUDE_DIR/bin/claude-run" --help 2>/dev/null | grep -q 'REVIEW_RECEIPT_DIR'; then
+      info "claude-run is receipt-aware"
+    else
+      log "claude-run predates the receipt contract — reviews through it emit nothing"; fail=1
+    fi
+  fi
   local vpy="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}/bin/python"
   if [ -x "$vpy" ] && "$vpy" -c 'import textual' 2>/dev/null; then
     info "managed venv (textual) OK"
@@ -583,25 +752,25 @@ PY
   fi
   # A file this installer executes but never ships is invisible from a clone and
   # fatal on npm, so the payload gate runs wherever it exists (maintainer-side).
-  if [ -x "$REPO/scripts/check-package.sh" ]; then
-    if "$REPO/scripts/check-package.sh" >/dev/null 2>&1; then
+  if [ -x "$REPO/gates/check-package.sh" ]; then
+    if "$REPO/gates/check-package.sh" >/dev/null 2>&1; then
       info "npm payload OK"
     else
-      log "npm payload incomplete; run scripts/check-package.sh"
+      log "npm payload incomplete; run gates/check-package.sh"
       fail=1
     fi
   fi
   # Repo-internal mirror parity is a maintainer gate; only meaningful from a clone.
-  if [ -d "$REPO/ko" ] && [ -x "$REPO/scripts/check-parity.sh" ]; then
-    if "$REPO/scripts/check-parity.sh" >/dev/null 2>&1; then info "repo mirror parity OK"; else log "repo mirror parity FAILED"; fail=1; fi
+  if [ -d "$REPO/ko" ] && [ -x "$REPO/gates/check-parity.sh" ]; then
+    if "$REPO/gates/check-parity.sh" >/dev/null 2>&1; then info "repo mirror parity OK"; else log "repo mirror parity FAILED"; fail=1; fi
   fi
   # Prompting guides name concrete models, so they go stale on a model change
   # rather than degrading quietly; this checks them against the launch config.
-  if [ -x "$REPO/scripts/check-prompting-targets.sh" ]; then
-    if "$REPO/scripts/check-prompting-targets.sh" >/dev/null 2>&1; then
+  if [ -x "$REPO/launch/check-prompting-targets.sh" ]; then
+    if "$REPO/launch/check-prompting-targets.sh" >/dev/null 2>&1; then
       info "prompting targets OK"
     else
-      log "prompting guides do not cover a configured model; run scripts/check-prompting-targets.sh"
+      log "prompting guides do not cover a configured model; run launch/check-prompting-targets.sh"
       fail=1
     fi
   fi
@@ -611,38 +780,149 @@ PY
 cmd_uninstall() {
   migrate_state
   codex_config_additions remove || log "warning: could not remove codex config additions"
+  # The assembler's two spans in files we do not own — settings registrations and the AGENTS.md
+  # central region — are merged in and were never removed here, so uninstall used to leave hooks
+  # invoking deleted files and instructions pointing at deleted guides. It reads ownership the
+  # same way the merge wrote it, so it cannot reach past what we put there.
+  if [ -f "$REPO/compose/assemble.py" ]; then
+    python3 "$REPO/compose/assemble.py" --remove-owned --claude-dir "$CLAUDE_DIR" \
+      --codex-dir "$CODEX_DIR" --state-dir "$STATE_DIR" ${DRY_RUN:+} \
+      $([ "$DRY_RUN" = 1 ] && echo --dry-run) \
+      || log "warning: could not remove assembler-owned regions"
+  fi
   if [ -f "$MANIFEST" ]; then
+    # Back up before deleting, the way install backs up before overwriting. Full mode deploys the
+    # entry CLAUDE.md/AGENTS.md as ordinary targets, so they are manifested and removed here —
+    # correct, since in that mode the entry file IS the corpus. What was wrong is that anything a
+    # user added to it disappeared with no copy, while the same file overwritten during install
+    # would have been backed up. Removal is symmetric with deployment; recoverability now is too.
+    [ "$DRY_RUN" = 1 ] || { mkdir -p "$STATE_DIR"; BACKUP_DIR="$STATE_DIR/backups/uninstall-$(date +%Y%m%d-%H%M%S)"; }
     local f
     while IFS= read -r f; do
       [ -n "$f" ] || continue
+      if [ -f "$f" ] && [ -n "$BACKUP_DIR" ] && [ "$DRY_RUN" != 1 ]; then
+        mkdir -p "$(dirname "$BACKUP_DIR$f")" && cp "$f" "$BACKUP_DIR$f"
+      fi
       [ -f "$f" ] && { run rm -f "$f"; [ "$DRY_RUN" = 1 ] || info "removed  $f"; }
     done < "$MANIFEST"
+    { [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ] && info "staged for the archive: $BACKUP_DIR"; } || true
     [ "$DRY_RUN" = 1 ] || rm -f "$MANIFEST"
   else
     log "no manifest at $MANIFEST; removing known deploy targets"
+    # The two entry files are deliberately NOT in this list. `$CLAUDE_DIR/CLAUDE.md` is seeded
+    # once and the user's thereafter, and `$CODEX_DIR/AGENTS.md` is ours only between the central
+    # markers, which --remove-owned above already took. This branch runs precisely when state is
+    # missing or agent-bios was never installed here, so nothing says we wrote either file —
+    # and deleting them whole destroyed personal instructions with no copy at all, since
+    # BACKUP_DIR is set only on the manifest path above.
     local p
-    for p in "$CLAUDE_DIR/CLAUDE.md" "$CODEX_DIR/AGENTS.md" \
-             "$CODEX_DIR/bin/codex-run" "$CODEX_DIR/bin/codex-helm" \
+    for p in "$CODEX_DIR/bin/codex-run" "$CODEX_DIR/bin/codex-helm" \
+             "$CLAUDE_DIR/bin/claude-run" \
              "$LAUNCH_DIR/profiles.toml" "$LAUNCH_DIR/shell.zsh" "$BIN_DIR/agent-launch"; do
       [ -f "$p" ] && { run rm -f "$p"; [ "$DRY_RUN" = 1 ] || info "removed  $p"; }
     done
   fi
   local d
-  for d in "$CLAUDE_DIR/guides" "$CLAUDE_DIR/agents" "$CODEX_DIR/guides" "$CODEX_DIR/agents" "$CODEX_DIR/bin" "$LAUNCH_DIR"; do
+  # `central/` and its subdirectories are entirely ours — the assembler creates them and the
+  # manifest covers every file inside — so they belong in this sweep. They were missing from it,
+  # which left three empty directories in the user's config dir after a "leave no trace" removal.
+  # rmdir, never rm -rf: a directory that is not empty is one we did not fully account for, and
+  # the right answer then is to leave it and be visibly incomplete.
+  for d in "$CLAUDE_DIR/central/guides" "$CLAUDE_DIR/central/hooks" "$CLAUDE_DIR/central/agents" \
+           "$CLAUDE_DIR/central" \
+           "$CLAUDE_DIR/guides" "$CLAUDE_DIR/agents" "$CLAUDE_DIR/bin" \
+           "$CODEX_DIR/guides" "$CODEX_DIR/agents" "$CODEX_DIR/bin" "$LAUNCH_DIR"; do
     [ -d "$d" ] && rmdir "$d" 2>/dev/null && info "removed empty  $d" || true
   done
   remove_zsh_hook
+  archive_and_purge
   log ""
-  log "Uninstalled deployed files and the zsh hook."
-  log "Kept: managed venv + backups under $STATE_DIR (rm -rf \"$STATE_DIR\" to purge)."
+  log "Uninstalled: deployed files, the zsh hook, state, backups, cache, and the managed venv."
+}
+
+# Uninstall is a SECURITY operation — nothing of ours may survive it on the machine. That
+# conflicts with never destroying what a user added, because full mode writes the corpus into an
+# entry file they then edit, so removal takes their work with it. One artifact settles both:
+# everything removed leaves as a single archive that can be handed off or deleted in one act,
+# and every managed location is then purged. The archive lands in $HOME, outside every path we
+# manage, because a copy inside a directory we are about to delete is not a copy.
+#
+# Order is the safety property: archive first, verify the archive exists, purge only then. A
+# failed archive leaves the machine untouched rather than clean and empty-handed.
+archive_and_purge() {
+  local ts stage rel out list staged skipped
+  ts="$(date +%Y%m%d-%H%M%S)"
+  out="${AGENT_BIOS_UNINSTALL_ARCHIVE:-$HOME}/agent-bios-uninstall-$ts.tar.gz"
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] archive removed content to $out, then purge $STATE_DIR, the cache and the venv"
+    return 0
+  fi
+  stage="$(mktemp -d)" || { log "warning: no temp dir; leaving state in place"; return 0; }
+  list="$(mktemp)" || { rm -rf "$stage"; log "warning: no temp file; leaving state in place"; return 0; }
+  [ -d "$STATE_DIR" ] && cp -R "$STATE_DIR" "$stage/state" 2>/dev/null
+  # WHICH loose copies are ours is compose/prune-backups.py's question — it deletes them too, on
+  # the retention path, and a rule written in both places drifts on one side. `*.bak-*` was the
+  # match here, which also claims a `notes.bak-old` the user saved by hand; these sit in
+  # directories we share with them and with other tools, so the name must carry the ownership.
+  if [ -f "$REPO/compose/prune-backups.py" ]; then
+    python3 "$REPO/compose/prune-backups.py" --list-owned \
+      --claude-dir "$CLAUDE_DIR" --codex-dir "$CODEX_DIR" >"$list" 2>/dev/null || : >"$list"
+  else
+    log "note: compose/prune-backups.py is absent, so loose backup copies are left where they are"
+  fi
+  # Staged UNDER their absolute path, the way deploy_file backs up to "$BACKUP_DIR$dst".
+  # Flattening them into one directory let two same-named copies from the two host trees
+  # collide, and the loser was then deleted with nothing in the archive to restore it from.
+  # Only what verifiably reached the stage may be deleted later. Every failure mode here is
+  # silent — a full temp filesystem, an unreadable source, a directory that cannot be created —
+  # and purging from the ORIGINAL list removed files the archive does not contain. Size equality
+  # rather than cp's exit status alone, because the question is whether the archive can restore
+  # it, not whether the copy was attempted.
+  staged="$(mktemp)" || { rm -f "$list"; rm -rf "$stage"
+                          log "warning: no temp file; leaving state in place"; return 0; }
+  skipped=0
+  while IFS= read -r -d '' rel; do
+    if mkdir -p "$(dirname "$stage/loose$rel")" 2>/dev/null \
+       && cp "$rel" "$stage/loose$rel" 2>/dev/null \
+       && [ "$(wc -c <"$rel" 2>/dev/null)" = "$(wc -c <"$stage/loose$rel" 2>/dev/null)" ]; then
+      printf '%s\0' "$rel" >> "$staged"
+    else
+      skipped=$((skipped + 1))
+      rm -f "$stage/loose$rel" 2>/dev/null   # a partial copy must not look archived
+      log "warning: could not stage $rel — leaving it in place"
+    fi
+  done <"$list"
+  if tar czf "$out" -C "$stage" . 2>/dev/null && [ -s "$out" ]; then
+    # Only here, with the archive written and non-empty, is removing the originals recoverable.
+    # Deleting them before the tar meant a failed archive took the backups with it — while the
+    # warning below told the operator they had been left in place.
+    while IFS= read -r -d '' rel; do rm -f "$rel" 2>/dev/null; done <"$staged"
+    rm -f "$list" "$staged"
+    rm -rf "$stage"
+    rm -rf "$STATE_DIR" "$HOME/.cache/agent-launch" \
+           "${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch}"
+    log ""
+    log "Everything removed is in ONE archive:  $out"
+    if [ "$skipped" -gt 0 ]; then
+      log "Move it somewhere central or delete it. $skipped backup copy(ies) could not be staged,"
+      log "so they were LEFT ON DISK rather than deleted with nothing to restore them from."
+    else
+      log "Move it somewhere central or delete it — nothing of ours is left on this machine."
+    fi
+  else
+    rm -f "$list" "$staged"
+    rm -rf "$stage"
+    log "warning: could not write $out — state, backups and the venv were left in place rather"
+    log "         than deleted with no copy. Re-run once the archive path is writable."
+  fi
 }
 
 cmd_onboard() {
   log "agent-bios onboarding — pick your domain packages (core + infra always install)"
   local names=() line i=1 choice sel="" n picks
   while IFS= read -r line; do names+=("$line"); done \
-    < <(python3 -c "import json;print('\n'.join(sorted(json.load(open('$REPO/config/domains.json'))['domains'])))")
-  [ "${#names[@]}" -ge 1 ] || { log "no domains found in config/domains.json"; exit 1; }
+    < <(python3 -c "import json;print('\n'.join(sorted(json.load(open('$REPO/compose/domains.json'))['domains'])))")
+  [ "${#names[@]}" -ge 1 ] || { log "no domains found in compose/domains.json"; exit 1; }
   if [ "$DOMAINS_SET" = 1 ]; then
     # Non-interactive path, per this installer's input contract (stdin is
     # detached at the top of the script): selection arrives as domain names.
@@ -674,10 +954,13 @@ cmd_onboard() {
   log ""
   log "Activation canary (proves the bundle loads in a live session)..."
   if [ "$DRY_RUN" = 1 ]; then info "[dry-run] skip canary probe"; return; fi
-  bash "$REPO/scripts/canary.sh" || {
+  bash "$REPO/compose/canary.sh" || {
     log "ONBOARDING INCOMPLETE: the bundle is installed but not loading — fix the cause above and re-run: agent-bios verify"
     exit 1
   }
+  # The prune is authorized by the canary's proof, and cmd_install ran before the canary existed
+  # for this bundle rev — so it kept everything. Now that loading is proven, run it for real.
+  migrate_learnings
 }
 
 # ---- deploy-chain drift ---------------------------------------------------
@@ -750,7 +1033,7 @@ usage() {
 agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
 
   agent-bios install     deploy into this environment (backs up + verifies)
-  agent-bios onboard     interactive domain selection + packaged install + activation canary
+  agent-bios onboard     interactive domain selection + install + activation canary
   agent-bios verify      check the deployed state matches the source
   agent-bios learn       submit a session learning (reads the JSON record on
                          stdin; this is what the learn! flow calls, and it
@@ -761,20 +1044,34 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
   agent-bios help
 
 Flags: --dry-run       print actions without changing anything
-       --domains a,b  packaged mode (install/onboard): assemble ONLY the named
-                      domain packages (plus core+infra) instead of the full
-                      corpus; with onboard, 'none' means core+infra only. The
-                      selection persists in the state dir, so later
-                      installs/updates stay packaged until the selection file
-                      is removed. Default (no flag, no saved selection) keeps
-                      today's full-corpus deploy.
+       --domains a,b  assemble ONLY the named domain packages (plus core+infra);
+                      with onboard, 'none' means core+infra only. The selection
+                      persists in the state dir and later installs/updates reuse
+                      it. Default (no flag, no saved selection) selects every
+                      domain — one install shape, "full" is just everything
+                      selected.
        --with a,b     also install the named optional dependencies (install only).
                       Without it, install offers each missing one when the terminal
                       is interactive, and otherwise just prints its install line.
-                      Known: onto, ultracode. Missing ones are not fatal — they only
-                      degrade the review routes that need them.
+                      Missing ones are not fatal — they only degrade the review
+                      routes that need them.
 Env:   CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR
 EOF
+  # DERIVED, not typed: the hardcoded pair went stale the moment a capability was renamed,
+  # and the name it still advertised selected a different capability than the one that
+  # carries the install line.
+  local known; known=$(capability_table 2>/dev/null | cut -f1 | tr '\n' ' ')
+  [ -n "$known" ] && printf '       --with names: %s\n' "${known% }"
+
+  # Recovery exists in both modes at different granularity, and naming the wrong one is worse
+  # than naming none: a clone can roll the corpus back to a registered mining window, while an
+  # npm install has no git history to read and rolls the whole package back by version instead.
+  # Derived from which install this is, for the same reason --with names is.
+  if [ -d "$REPO/.git" ]; then
+    printf '\nRecover: python3 %s/compose/corpus-state.py list, then rollback --version V\n' "$REPO"
+  else
+    printf '\nRecover: npm install -g agent-bios@<older-version> && agent-bios install\n'
+  fi
 }
 
 # ---- dispatch ------------------------------------------------------------
@@ -784,10 +1081,10 @@ if [ $# -gt 0 ]; then shift; fi
 # `learn` forwards its arguments and stdin straight to the collector, so it must
 # bypass the flag parser below (which rejects anything it does not know). This
 # subcommand is the only PATH-reachable entry to capture: the corpus guide used
-# to invoke scripts/collect-learning.py relative to the cwd, which works from a
+# to invoke learn/collect-learning.py relative to the cwd, which works from a
 # clone and silently fails for every other install.
 if [ "$CMD" = "learn" ]; then
-  collector="$REPO/scripts/collect-learning.py"
+  collector="$REPO/learn/collect-learning.py"
   [ -f "$collector" ] || { log "learn: collector missing at $collector"; exit 1; }
   exec python3 "$collector" "$@" <&3
 fi