agent-bios 0.1.0 → 0.2.0

package/scripts/agent-launch.py

@@ -40,6 +40,15 @@ EFFORT_DESCRIPTIONS = {
 }
 CUSTOM_PRESET = "__custom__"
 OTHER_MODEL = "__other_model__"
+# User-saved presets live beside the deployed config, in a file the installer
+# neither deploys nor verifies, so they survive `agent-bios install`.
+USER_PRESETS_NAME = "presets.local.toml"
+USER_PRESETS_HEADER = (
+    "# agent-launch user presets, written by the launcher's save action.\n"
+    "# agent-bios install never deploys or verifies this file, so presets here\n"
+    "# survive upgrades. Shipped presets live in the deployed profiles.toml and\n"
+    "# are overridden by a preset of the same name here.\n"
+)
 
 
 @dataclass(frozen=True)
@@ -55,21 +64,55 @@ REVIEW_SETUPS = {
     "none": {
         "label": "None",
         "requirements": {"codex": (), "claude": ()},
+        "description": "No review route. Fastest; you review it yourself.",
         "contract": "No additional review route requested.",
     },
     "native-panel": {
         "label": "Native panel",
         "requirements": {"codex": (), "claude": ()},
+        "description": (
+            "Subagents review from different angles. Broad coverage, no dependency; "
+            "same-model reviewers share the main's blind spots."
+        ),
         "contract": "Use native multi-perspective subagents when review gates fire.",
     },
+    "slash-review": {
+        "label": "Slash review",
+        "requirements": {"codex": (), "claude": ()},
+        "description": {
+            "claude": (
+                "The built-in /code-review command (add `ultra` for the deep cloud pass). "
+                "Cheapest good diff review; same-family, so it is a weaker check than cross."
+            ),
+            "codex": (
+                "The built-in /review command. Cheapest good diff review; same-family, "
+                "so it is a weaker check than cross."
+            ),
+        },
+        "contract": {
+            "claude": (
+                "Use Claude Code's built-in /code-review when review gates fire; use "
+                "/code-review ultra for a deep multi-agent pass on high-risk changes."
+            ),
+            "codex": "Use Codex's built-in /review when review gates fire.",
+        },
+    },
     "onto": {
         "label": "onto-mcp",
         "requirements": {"codex": ("onto",), "claude": ("onto",)},
+        "description": (
+            "Structured multi-lens review through onto-mcp. Best for concept/ontology "
+            "and design work; needs onto installed."
+        ),
         "contract": "Use onto-mcp as the structured review lens when review gates fire.",
     },
     "ultracode": {
         "label": "Ultracode",
         "requirements": {"codex": ("ultracode",), "claude": ("ultracode",)},
+        "description": (
+            "Workflow-orchestrated review fanned out over many agents. Best for "
+            "exhaustive audits; slowest and most expensive."
+        ),
         "contract": (
             "Run the configured Ultracode CLI as a Codex-backed review route when "
             "review gates fire."
@@ -81,6 +124,10 @@ REVIEW_SETUPS = {
             "codex": ("onto", "ultracode"),
             "claude": ("onto", "ultracode"),
         },
+        "description": (
+            "onto + native + Ultracode together, acting on their union. Widest net for "
+            "risky work; missing routes degrade rather than fail."
+        ),
         "contract": {
             "codex": "Use onto plus native and Codex-backed Ultracode review kinds; act on their union.",
             "claude": "Use onto plus native multi-perspective and Codex-backed Ultracode review kinds; act on their union.",
@@ -96,12 +143,18 @@ REVIEW_SETUPS = {
 REVIEW_ROUTES = {
     "none": (),
     "native-panel": ("native",),
+    "slash-review": ("slash",),
     "onto": ("onto",),
     "ultracode": ("ultracode",),
     "hybrid": ("onto", "native", "ultracode"),
 }
+# Routes that are host-native review commands: they always resolve (no capability
+# to install) but run on the main's own family, so cross-family mode cannot dispatch
+# them to the opposite family and labels them PROPOSED instead.
+SAME_FAMILY_ROUTES = {"slash"}
 ROUTE_LABELS = {
     "native": "native same-model multi-perspective review",
+    "slash": "host-native slash-command review",
     "onto": "onto structured-lens review",
     "ultracode": "Codex-backed Ultracode review",
 }
@@ -153,6 +206,28 @@ def default_config_path() -> pathlib.Path:
     return pathlib.Path(__file__).resolve().parent.parent / "config/agent-launch.toml"
 
 
+def user_presets_path(config_path: pathlib.Path) -> pathlib.Path:
+    return config_path.with_name(USER_PRESETS_NAME)
+
+
+def load_user_presets(path: pathlib.Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise LaunchError(f"cannot load user presets {path}: {exc}") from exc
+    unexpected = sorted(set(data) - {"presets"})
+    if unexpected:
+        raise LaunchError(
+            f"{path} may only define [presets.*]; found: {', '.join(unexpected)}"
+        )
+    presets = data.get("presets", {})
+    if not isinstance(presets, dict):
+        raise LaunchError(f"[presets] must be a table in {path}")
+    return presets
+
+
 def load_config(path: pathlib.Path) -> dict[str, Any]:
     try:
         data = tomllib.loads(path.read_text())
@@ -163,12 +238,17 @@ def load_config(path: pathlib.Path) -> dict[str, Any]:
     for key in ("backends", "hosts", "presets"):
         if not isinstance(data.get(key), dict) or not data[key]:
             raise LaunchError(f"config requires non-empty [{key}]")
+    # Merged before the preset checks below so user presets face the same validation.
+    data["presets"].update(load_user_presets(user_presets_path(path)))
     capabilities = data.get("capabilities", {})
     if not isinstance(capabilities, dict):
         raise LaunchError("[capabilities] must be a table")
     for name, capability in capabilities.items():
         if not isinstance(capability, dict):
             raise LaunchError(f"capability must be a table: {name}")
+        hint = capability.get("install")
+        if hint is not None and (not isinstance(hint, str) or not hint):
+            raise LaunchError(f"capabilities.{name}.install must be a non-empty string")
     onto = capabilities.get("onto")
     if onto is not None and (
         not isinstance(onto.get("command"), str) or not onto["command"]
@@ -304,7 +384,7 @@ def route_availability(plan: dict[str, Any]) -> dict[str, bool]:
     a mounted onto plus a review_onto pin to flip its family."""
     capabilities = plan.get("capabilities", {})
     if plan.get("review_family", "cross") == "same":
-        available = {"native": bool(plan["delegation"])}
+        available = {"native": bool(plan["delegation"]), "slash": True}
         for route, capability in (("onto", "onto"), ("ultracode", "ultracode")):
             available[route] = _resolves(capabilities.get(capability, {}).get("command", ""))
         return available
@@ -313,11 +393,26 @@ def route_availability(plan: dict[str, Any]) -> dict[str, bool]:
     )
     return {
         "native": cross_native_command(plan) is not None,
+        # The host's own review command exists, but only for its own family; the
+        # cross branch of effective_review routes it to the PROPOSED floor.
+        "slash": True,
         "onto": onto_ok,
         "ultracode": cross_ultracode_command(plan) is not None,
     }
 
 
+def install_hint(plan: dict[str, Any], routes: list[str]) -> str:
+    """One-line install guidance for the capability-backed routes that are missing.
+    Empty when a route has no capability, no configured install, or is already there."""
+    capabilities = plan.get("capabilities", {})
+    hints = []
+    for route in routes:
+        hint = capabilities.get(route, {}).get("install")
+        if hint and hint not in hints:
+            hints.append(hint)
+    return f"; install: {' && '.join(hints)}" if hints else ""
+
+
 def effective_review(plan: dict[str, Any]) -> tuple[list[str], list[str], str | None]:
     """Resolve the requested review setup to the routes that can actually run.
 
@@ -325,9 +420,11 @@ def effective_review(plan: dict[str, Any]) -> tuple[list[str], list[str], str |
     reproduces the earlier degrade-to-native behavior (floor None; a dropped
     external route degrades to native in effective; native requires delegation).
     In cross-family mode the effective routes run on the opposite family; when no
-    cross route resolves and delegation is on, floor='native' marks a same-family
-    PROPOSED fallback, and a requested non-none setup with no cross route and no
-    fallback (delegation off) fails closed."""
+    cross route resolves the floor names the same-family route that runs instead,
+    labeled PROPOSED — a SAME_FAMILY_ROUTES route floors as itself (it needs no
+    delegation, being the host's own command), otherwise 'native' when delegation
+    is on. A requested non-none setup with no cross route and no fallback
+    (delegation off) fails closed."""
     requested = plan["review_setup"]
     if requested not in REVIEW_ROUTES:
         raise LaunchError(f"unknown review setup: {requested!r}")
@@ -341,11 +438,24 @@ def effective_review(plan: dict[str, Any]) -> tuple[list[str], list[str], str |
         if dropped and "native" not in effective and plan["delegation"]:
             effective.append("native")
         return effective, dropped, None
-    effective = [route for route in wanted if available[route]]
+    # A same-family route cannot be dispatched cross-family, so it is never
+    # "effective" here; it becomes the PROPOSED floor below instead.
+    effective = [
+        route
+        for route in wanted
+        if available[route] and route not in SAME_FAMILY_ROUTES
+    ]
     dropped = [route for route in wanted if not available[route]]
     floor = None
     if not effective and requested != "none":
-        if plan["delegation"]:
+        same_family = [
+            route
+            for route in wanted
+            if route in SAME_FAMILY_ROUTES and available[route]
+        ]
+        if same_family:
+            floor = same_family[0]
+        elif plan["delegation"]:
             floor = "native"
         else:
             raise LaunchError(
@@ -882,8 +992,10 @@ def build_plan(config: dict[str, Any], host: str, preset_name: str) -> dict[str,
 
 
 def review_description(host: str, name: str) -> str:
-    contract = REVIEW_SETUPS[name]["contract"]
-    return contract[host] if isinstance(contract, dict) else contract
+    """The user-facing one-liner for the menu: what the setup is for and what it
+    costs. Distinct from ["contract"], which is the instruction sent to the agent."""
+    description = REVIEW_SETUPS[name]["description"]
+    return description[host] if isinstance(description, dict) else description
 
 
 def effort_options(host: str, model: str) -> list[MenuOption]:
@@ -1001,13 +1113,19 @@ def save_preset(
         )
     fields, tier_overrides = preset_from_plan(plan, config, name)
     block = render_preset_block(name, fields, tier_overrides)
-    text = remove_preset_block(config_path.read_text(), name).rstrip("\n") + "\n\n" + block
-    temporary = config_path.with_name(f".{config_path.name}.{os.getpid()}.tmp")
+    target = user_presets_path(config_path)
     try:
+        kept = remove_preset_block(target.read_text(), name).rstrip("\n")
+    except FileNotFoundError:
+        kept = USER_PRESETS_HEADER.rstrip("\n")
+    text = kept + "\n\n" + block
+    temporary = target.with_name(f".{target.name}.{os.getpid()}.tmp")
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
         temporary.write_text(text)
-        os.replace(temporary, config_path)
+        os.replace(temporary, target)
     except OSError as exc:
-        raise LaunchError(f"cannot save preset to {config_path}: {exc}") from exc
+        raise LaunchError(f"cannot save preset to {target}: {exc}") from exc
 
 
 def customize(
@@ -1033,7 +1151,10 @@ def customize(
         ]
         if missing:
             note = "degrades to same-family native (PROPOSED)" if cross else "degrades to native"
-            description = f"{description} ({', '.join(missing)} unavailable now; {note})"
+            description = (
+                f"{description} ({', '.join(missing)} unavailable now; {note}"
+                f"{install_hint(plan, missing)})"
+            )
         review_options.append(MenuOption(name, spec["label"], description))
     if plan["host"] == "codex":
         policies = [
@@ -1471,6 +1592,15 @@ def _cross_review_route(
             "No cross-family route resolved at launch; using same-family native "
             "subagent review labeled PROPOSED (family collapse)."
         )
+    elif floor:
+        setup_contract = REVIEW_SETUPS[plan["review_setup"]]["contract"]
+        if isinstance(setup_contract, dict):
+            setup_contract = setup_contract[plan["host"]]
+        parts.append(
+            f"This review route runs on this main's own family, so it cannot be "
+            f"dispatched cross-family; its verdicts are PROPOSED (family collapse). "
+            f"{setup_contract}"
+        )
     parts.append(
         "Cross-family reviewers are dispatched as read-only subprocesses, not "
         "CLI-native subagents; spawning them needs this main's execution policy to "
@@ -1615,13 +1745,13 @@ def print_summary(
         if effective:
             review_display += f" via {'+'.join(effective)}"
         if dropped:
-            review_display += f" (dropped {','.join(dropped)})"
-        if floor == "native":
-            review_display += " → same-family native PROPOSED"
+            review_display += f" (dropped {','.join(dropped)}{install_hint(plan, dropped)})"
+        if floor:
+            review_display += f" → same-family {floor} PROPOSED"
     elif dropped:
         review_display += (
             f" → effective {'+'.join(effective) or 'none'} "
-            f"({','.join(dropped)} unavailable)"
+            f"({','.join(dropped)} unavailable{install_hint(plan, dropped)})"
         )
     print(
         f"  Review setup   {review_display} · "

package/scripts/check-parity.sh

@@ -1585,7 +1585,8 @@ if launcher.is_file() and launch_profile:
             unavailable,
             "agent-launch codex degrade-to-native review",
             (
-                "Review setup   hybrid → effective native (onto,ultracode unavailable)",
+                "Review setup   hybrid → effective native (onto,ultracode unavailable;"
+                " install: npm i -g onto-mcp && npm i -g ultracode-for-codex)",
                 "degraded to native same-model",
                 "fall back to native same-model subagent review",
             ),
@@ -1600,7 +1601,8 @@ if launcher.is_file() and launch_profile:
             unavailable_claude,
             "agent-launch claude degrade-to-native review",
             (
-                "Review setup   hybrid → effective native (onto,ultracode unavailable)",
+                "Review setup   hybrid → effective native (onto,ultracode unavailable;"
+                " install: npm i -g onto-mcp && npm i -g ultracode-for-codex)",
                 "fall back to native same-model subagent review",
             ),
             ("--mcp-config",),
@@ -1637,8 +1639,11 @@ if launcher.is_file() and launch_profile:
             ):
                 mark_fail("saved codex tier override leaked into the claude host")
             launcher_module.save_preset(round_trip, reloaded, save_target, "mysetup")
-            if save_target.read_text().count("[presets.mysetup]") != 1:
+            saved_file = launcher_module.user_presets_path(save_target)
+            if saved_file.read_text().count("[presets.mysetup]") != 1:
                 mark_fail("re-saving a preset duplicated its block")
+            if "[presets.mysetup]" in save_target.read_text():
+                mark_fail("save_preset wrote a user preset into the installer-owned config")
 
         # The Custom hub 'save' action persists the named preset then launches.
         ui_save_target = tmp / "ui-save.toml"

package/scripts/check-prompting-targets.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Prompting guides are model-version-bound: unlike the rest of the guide set,
+# their rules change when the model changes (the current generation inverted the
+# previous one's advice). So they name concrete models, and this gate keeps that
+# naming honest — it fails when the launch config binds a model no prompting
+# guide covers, which is exactly when the guidance needs re-deriving from the
+# vendor's current docs.
+set -u
+cd "$(dirname "$0")/.." || exit 2
+
+python3 - "$@" <<'PY'
+import pathlib, re, sys, tomllib
+
+config = pathlib.Path("config/agent-launch.toml")
+hosts = tomllib.loads(config.read_text())["hosts"]
+
+# host -> the guide that owns prompting guidance for that host's model family
+OWNERS = {"codex": "gpt-prompting", "claude": "claude-prompting"}
+
+def targets(guide_id):
+    path = pathlib.Path(f"codex/guides/{guide_id}.md")
+    if not path.is_file():
+        sys.exit(f"FAIL: missing prompting guide: {path}")
+    front = re.match(r"---\n(.*?)\n---\n", path.read_text(), re.S)
+    if not front:
+        sys.exit(f"FAIL: missing YAML frontmatter: {path}")
+    block = re.search(r"^targets:\n((?:\s+-\s+\S+\n)+)", front.group(1), re.M)
+    if not block:
+        sys.exit(f"FAIL: {path} declares no targets:")
+    return {line.strip().lstrip("- ").strip() for line in block.group(1).splitlines()}
+
+fail = 0
+for host, guide_id in OWNERS.items():
+    configured = set(hosts.get(host, {}).get("models", []))
+    for tier in hosts.get(host, {}).get("tiers", {}).values():
+        if tier.get("model"):
+            configured.add(tier["model"])
+    if not configured:
+        print(f"FAIL: no models configured for host {host}; nothing to check")
+        fail = 1
+        continue
+    declared = targets(guide_id)
+    stale = sorted(configured - declared)
+    if stale:
+        print(
+            f"FAIL: {guide_id}.md does not cover configured {host} model(s): "
+            f"{', '.join(stale)} — re-derive it from current vendor guidance and "
+            f"update its targets:"
+        )
+        fail = 1
+    else:
+        print(f"  {guide_id}: covers all {len(configured)} configured {host} model(s)")
+    unused = sorted(declared - configured)
+    if unused:
+        print(f"  note: {guide_id} also targets unbound model(s): {', '.join(unused)}")
+
+sys.exit(fail)
+PY
+status=$?
+[ $status -eq 0 ] && echo "PROMPTING TARGETS OK: every configured model is covered" \
+                  || echo "PROMPTING TARGETS FAILED"
+exit $status

package/scripts/install.sh

@@ -44,6 +44,7 @@ REPO="$(cd "$SELF/.." && pwd)"
 CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
 LAUNCH_DIR="$HOME/.config/agent-launch"
+USER_PRESETS_NAME="presets.local.toml"  # user-owned; never deployed or verified
 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
@@ -125,6 +126,113 @@ migrate_state() {
   mv "$LEGACY_STATE_DIR" "$STATE_DIR" && info "migrated state  $LEGACY_STATE_DIR -> $STATE_DIR"
 }
 
+# ---- 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
+# that gates a route and the install line offered here.
+capability_table() {
+  python3 - "$REPO/config/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", ""))))
+PY
+}
+
+install_capability() {
+  local name="$1" line="$2"
+  log "Installing optional dependency $name: $line"
+  if [ "$DRY_RUN" = 1 ]; then info "[dry-run] $line"; return 0; fi
+  if sh -c "$line"; then info "installed  $name"; else log "warning: installing $name failed; routes needing it stay degraded"; fi
+}
+
+handle_capabilities() {
+  local requested="$1" name command line
+  # Fail on a typo rather than silently installing nothing.
+  local known; known=$(capability_table | cut -f1)
+  local want
+  for want in ${requested//,/ }; do
+    printf '%s\n' "$known" | grep -qx "$want" || {
+      log "unknown --with capability: $want (known: $(printf '%s' "$known" | tr '\n' ' '))"; return 1; }
+  done
+  while IFS=$'\t' read -r name command line; do
+    [ -n "$name" ] || continue
+    if command -v "$command" >/dev/null 2>&1; then
+      info "capability present  $name ($command)"
+      continue
+    fi
+    if printf '%s\n' "${requested//,/ }" | tr ' ' '\n' | grep -qx "$name"; then
+      [ -n "$line" ] && install_capability "$name" "$line" \
+        || log "note: $name has no configured install line"
+    elif [ -n "$line" ] && [ -t 0 ] && [ "$DRY_RUN" != 1 ]; then
+      printf '  Install optional dependency %s? (%s) [y/N] ' "$name" "$line"
+      local answer=""; read -r answer </dev/tty || answer=""
+      case "$answer" in
+        [yY]*) install_capability "$name" "$line" ;;
+        *) info "skipped  $name — install later: $line" ;;
+      esac
+    else
+      info "optional  $name unavailable; routes needing it degrade${line:+ — install: $line}"
+    fi
+  done <<EOF
+$(capability_table)
+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 dst="$LAUNCH_DIR/profiles.toml"
+  local user="$LAUNCH_DIR/$USER_PRESETS_NAME"
+  [ -f "$dst" ] || return 0
+  python3 - "$src" "$dst" "$user" "$DRY_RUN" <<'PY' || { log "user preset migration failed; not overwriting $LAUNCH_DIR/profiles.toml"; return 1; }
+import os, pathlib, re, sys, tomllib
+
+src, dst, user, dry_run = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2]), pathlib.Path(sys.argv[3]), sys.argv[4] == "1"
+dst_text = dst.read_text()
+shipped = set(tomllib.loads(src.read_text()).get("presets", {}))
+extra = set(tomllib.loads(dst_text).get("presets", {})) - shipped
+if not extra:
+    sys.exit(0)
+existing_text = user.read_text() if user.is_file() else ""
+already = set(tomllib.loads(existing_text).get("presets", {})) if existing_text else set()
+move = sorted(extra - already)
+for name in sorted(extra & already):
+    print(f"  kept in {user.name}  {name} (already saved there)")
+if not move:
+    sys.exit(0)
+
+header = re.compile(r'^\[presets\.(?:"([^"]+)"|([A-Za-z0-9][A-Za-z0-9_-]*))(?:[.\]])')
+blocks, current = {}, None
+for line in dst_text.splitlines(keepends=True):
+    stripped = line.strip()
+    if stripped.startswith("["):
+        found = header.match(stripped)
+        current = (found.group(1) or found.group(2)) if found else None
+    if current in move:
+        blocks.setdefault(current, []).append(line)
+# Refuse to deploy over a preset we could not carry across, rather than drop it.
+missing = [name for name in move if name not in blocks]
+if missing:
+    sys.exit(f"cannot extract preset block(s) from {dst}: {', '.join(missing)}")
+
+out = existing_text.rstrip("\n") or (
+    "# agent-launch user presets, moved out of profiles.toml by agent-bios install.\n"
+    "# The installer never deploys or verifies this file, so presets here survive upgrades."
+)
+for name in move:
+    out += "\n\n" + "".join(blocks[name]).strip("\n")
+for name in move:
+    print(f"  {'[dry-run] ' if dry_run else ''}moved preset  {name} -> {user}")
+if dry_run:
+    sys.exit(0)
+user.parent.mkdir(parents=True, exist_ok=True)
+temporary = user.with_name(f".{user.name}.{os.getpid()}.tmp")
+temporary.write_text(out + "\n")
+os.replace(temporary, user)
+PY
+}
+
 remove_zsh_hook() {
   if [ ! -f "$ZSHRC" ] || ! grep -qF "$HOOK_MARK" "$ZSHRC"; then
     info "no zsh hook to remove"
@@ -152,9 +260,14 @@ cmd_install() {
   deploy_glob "$REPO/codex/agents" "*.toml" "$CODEX_DIR/agents"
   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"
+  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"
+  log ""
+  log "Optional dependencies (missing ones only degrade the routes that need them)..."
+  handle_capabilities "$WITH" || exit 1
+  log ""
   if [ "$DRY_RUN" = 1 ]; then
     info "[dry-run] provision managed Textual venv"
   else
@@ -212,6 +325,16 @@ PY
   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
   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
+      info "prompting targets OK"
+    else
+      log "prompting guides do not cover a configured model; run scripts/check-prompting-targets.sh"
+      fail=1
+    fi
+  fi
   return $fail
 }
 
@@ -284,7 +407,12 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
   agent-bios uninstall   remove deployed files and the zsh hook
   agent-bios help
 
-Flags: --dry-run   print actions without changing anything
+Flags: --dry-run       print actions without changing anything
+       --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.
 Env:   CLAUDE_CONFIG_DIR, CODEX_HOME, AGENT_LAUNCH_VENV, ZDOTDIR
 EOF
 }
@@ -292,11 +420,15 @@ EOF
 # ---- dispatch ------------------------------------------------------------
 CMD="${1:-help}"
 if [ $# -gt 0 ]; then shift; fi
-for a in "$@"; do
-  case "$a" in
+WITH=""
+while [ $# -gt 0 ]; do
+  case "$1" in
     --dry-run) DRY_RUN=1 ;;
-    *) log "unknown flag: $a"; exit 2 ;;
+    --with) shift; WITH="${1:-}"; [ -n "$WITH" ] || { log "--with needs a comma-separated capability list"; exit 2; } ;;
+    --with=*) WITH="${1#--with=}"; [ -n "$WITH" ] || { log "--with needs a comma-separated capability list"; exit 2; } ;;
+    *) log "unknown flag: $1"; exit 2 ;;
   esac
+  shift
 done
 
 case "$CMD" in