codebase-explorer 2.2.0__py3-none-any.whl

cbe_install/cli.py

@@ -0,0 +1,434 @@
+"""Small, ownership-aware installer for the skills shipped inside this wheel."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import json
+import os
+import shlex
+import shutil
+import sys
+import tempfile
+from importlib import resources
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path, PurePosixPath
+
+from . import (AGENTS_RESOURCE, BUSINESS_MODULE, PRODUCT, RUNTIME_MODULES, RUNTIME_SKILLS, SKILLS,
+               SOURCE_AGENT_BASE, SOURCE_PARENT_LEVEL, SOURCE_SKILL_BASE)
+
+MANIFEST = ".skill-install.json"
+HOSTS = ("codex", "claude-code", "dsh", "opencode", "pi")
+PROJECT_DIRS = {
+    "codex": (".agents", "skills"),
+    "claude-code": (".claude", "skills"),
+    "dsh": (".dsh", "skills"),
+    "opencode": (".opencode", "skills"),
+    "pi": (".pi", "skills"),
+}
+USER_DIRS = {
+    "codex": (".agents", "skills"),
+    "claude-code": (".claude", "skills"),
+    "dsh": (".dsh", "skills"),
+    "opencode": (".config", "opencode", "skills"),
+    "pi": (".pi", "agent", "skills"),
+}
+
+
+class InstallError(Exception):
+    """An actionable input, dependency, or ownership conflict."""
+
+
+def _digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _runtime_python() -> Path:
+    return Path(sys.executable).absolute()
+
+
+def _with_runtime(skill_bytes: bytes) -> bytes:
+    python = str(_runtime_python())
+    command = shlex.quote(python)
+    lines = [
+        "\n## Installed runtime (generated by cbe-install)",
+        f"Python executable: `{python}`. Use it as one argument, even when its path contains spaces.",
+        "Replace bare CLI names in the examples below with these absolute entry points; no PATH or source checkout is required:",
+        *(f"- `{module}`: `{command} -m {module}`" for module in RUNTIME_MODULES),
+        "Each entry point is several words, so write the whole command in every call. Do not store it in a shell variable: zsh does not split an unquoted variable into words. A shell function that runs it also works if you define it in the same call that uses it.",
+        "Re-run `cbe-install upgrade` after moving or reinstalling the tool environment.\n",
+    ]
+    note = ("\n".join(lines) + "\n").encode("utf-8")
+    closing = skill_bytes.find(b"\n---\n", 4) if skill_bytes.startswith(b"---\n") else -1
+    position = closing + len(b"\n---\n") if closing >= 0 else 0
+    return skill_bytes[:position] + note + skill_bytes[position:]
+
+
+def _release_version() -> str:
+    try:
+        return version(PRODUCT)
+    except PackageNotFoundError:
+        return "source"
+
+
+def _runtime_check() -> None:
+    try:
+        importlib.import_module(BUSINESS_MODULE)
+    except (ImportError, OSError) as exc:
+        missing = getattr(exc, "name", None) or BUSINESS_MODULE
+        raise InstallError(
+            f"runtime dependency {missing!r} is unavailable ({exc}); "
+            f"reinstall {PRODUCT} with dependencies using uv tool install --reinstall <package-or-wheel>"
+        ) from exc
+
+
+def _checkout_root() -> Path | None:
+    """The author checkout this module runs from, or None inside an installed wheel."""
+    location = Path(__file__).resolve()
+    candidate = location.parents[SOURCE_PARENT_LEVEL]
+    if (
+        not {"site-packages", "dist-packages"}.intersection(location.parts)
+        and (candidate / "pyproject.toml").is_file()
+    ):
+        return candidate
+    return None
+
+
+def _agent_files() -> dict[str, bytes]:
+    """The Claude Code subagent definitions that ship with the skill, by file name."""
+    root = resources.files(__package__).joinpath("resources", AGENTS_RESOURCE)
+    if not root.is_dir() and (checkout := _checkout_root()) is not None:
+        root = checkout / SOURCE_AGENT_BASE
+    if not root.is_dir():
+        raise InstallError(f"wheel is missing the agent resources; rebuild {PRODUCT} from its release source")
+    found = {child.name: child.read_bytes() for child in root.iterdir() if child.is_file()}
+    if not found:
+        raise InstallError(f"wheel has no agent definitions; rebuild {PRODUCT} from its release source")
+    return found
+
+
+def _resource_files(skill: str) -> dict[str, bytes]:
+    root = resources.files(__package__).joinpath("resources", skill)
+    if not root.is_dir() and (checkout := _checkout_root()) is not None:
+        # Development checkouts use the same canonical files as the wheel build.
+        # A wheel without embedded resources never reaches into an author checkout.
+        root = checkout / SOURCE_SKILL_BASE / skill
+    if not root.is_dir():
+        raise InstallError(f"wheel is missing skill resource {skill!r}; rebuild {PRODUCT} from its release source")
+    found: dict[str, bytes] = {}
+
+    def collect(node, prefix: PurePosixPath) -> None:
+        for child in node.iterdir():
+            rel = prefix / child.name
+            if child.is_dir():
+                collect(child, rel)
+            elif child.is_file():
+                found[rel.as_posix()] = child.read_bytes()
+
+    collect(root, PurePosixPath())
+    if "SKILL.md" not in found:
+        raise InstallError(f"wheel skill {skill!r} has no SKILL.md; rebuild the release")
+    if skill in RUNTIME_SKILLS:
+        found["SKILL.md"] = _with_runtime(found["SKILL.md"])
+    return found
+
+
+def _valid_file_list(files: object) -> bool:
+    return isinstance(files, dict) and not any(
+        not isinstance(name, str)
+        or not isinstance(digest, str)
+        or digest != digest.lower()
+        or len(digest) != 64
+        or not name
+        or "\\" in name
+        or PurePosixPath(name).is_absolute()
+        or ".." in PurePosixPath(name).parts
+        or PurePosixPath(name).as_posix() != name
+        or name == MANIFEST
+        for name, digest in files.items()
+    )
+
+
+def _read_manifest(destination: Path, skill: str) -> dict | None:
+    path = destination / MANIFEST
+    if not path.exists():
+        return None
+    if path.is_symlink():
+        raise InstallError(f"refusing symlinked ownership manifest: {path}")
+    try:
+        manifest = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise InstallError(f"cannot read ownership manifest {path}: {exc}") from exc
+    if not isinstance(manifest, dict) or manifest.get("product") != PRODUCT or manifest.get("skill") != skill:
+        raise InstallError(f"{path} belongs to another product or is invalid; inspect it before changing this skill")
+    if not _valid_file_list(manifest.get("files")) or not _valid_file_list(manifest.get("agents", {})):
+        raise InstallError(f"invalid file list in {path}; inspect it before changing this skill")
+    return manifest
+
+
+def _check_existing(base: Path, tracked: dict[str, str], *, allow_missing: bool = False,
+                    guard_parents: bool = True) -> None:
+    """Every tracked file under ``base`` is the one this installer wrote.
+
+    A skill directory must not sit behind a symlink (``guard_parents``); the shared agents directory may."""
+    for rel, expected in tracked.items():
+        path = base / rel
+        if path.is_symlink() or (guard_parents and any(
+                parent.is_symlink() for parent in path.parents if parent != base.parent)):
+            raise InstallError(f"refusing symlinked installed path: {path}")
+        if not path.exists():
+            if allow_missing:
+                continue
+            raise InstallError(f"installed file was removed: {path}; restore it or resolve ownership manually")
+        if not path.is_file() or _digest(path.read_bytes()) != expected:
+            raise InstallError(f"user-modified installed file: {path}; save your edits before upgrading or uninstalling")
+
+
+def _check_symlinks(destination: Path) -> None:
+    if destination.is_symlink():
+        raise InstallError(f"refusing symlinked skill directory: {destination}")
+    if destination.exists():
+        for path in destination.rglob("*"):
+            if path.is_symlink():
+                raise InstallError(f"refusing symlink within skill directory: {path}")
+
+
+def _recover_backup(destination: Path) -> None:
+    backup = destination.with_name(f".{destination.name}.{PRODUCT}.backup")
+    if not backup.exists():
+        return
+    if destination.exists():
+        raise InstallError(
+            f"both {destination} and recovery backup {backup} exist; inspect them before retrying"
+        )
+    backup.rename(destination)
+
+
+def _agents_dir(root: Path) -> Path | None:
+    """Claude Code reads subagent definitions from the ``agents`` directory beside its ``skills`` directory."""
+    return root.parent / "agents" if root.name == "skills" and root.parent.name == ".claude" else None
+
+
+def _write_agent_files(agents_dir: Path, agents: dict[str, bytes]) -> list[str]:
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    lines = []
+    for name, data in agents.items():
+        path = agents_dir / name
+        if path.is_file() and path.read_bytes() == data:
+            continue
+        staged = agents_dir / f".{name}.{PRODUCT}.stage"
+        staged.write_bytes(data)
+        os.replace(staged, path)
+        lines.append(f"installed {path}")
+    return lines
+
+
+def _install_one(root: Path, skill: str) -> str:
+    root.mkdir(parents=True, exist_ok=True)
+    destination = root / skill
+    _recover_backup(destination)
+    _check_symlinks(destination)
+    desired = _resource_files(skill)
+    agents_dir = _agents_dir(root)
+    agents = _agent_files() if agents_dir else {}
+    prior = _read_manifest(destination, skill) if destination.exists() else None
+    if destination.exists() and prior is None:
+        raise InstallError(f"{destination} already exists without a {PRODUCT} ownership manifest; choose another directory")
+    tracked = prior["files"] if prior else {}
+    tracked_agents = prior.get("agents", {}) if prior else {}
+    if prior:
+        _check_existing(destination, tracked)
+    for rel in desired:
+        path = destination / rel
+        if path.exists() and rel not in tracked:
+            raise InstallError(f"unowned file conflicts with release: {path}; move it before installing")
+    if agents_dir:
+        _check_existing(agents_dir, tracked_agents, allow_missing=True, guard_parents=False)
+        for name in agents.keys() - tracked_agents.keys():
+            path = agents_dir / name
+            if path.exists() or path.is_symlink():
+                raise InstallError(f"unowned file conflicts with release: {path}; move it before installing")
+    hashes = {name: _digest(data) for name, data in desired.items()}
+    agent_hashes = {name: _digest(data) for name, data in agents.items()}
+    if (prior and tracked == hashes and tracked_agents == agent_hashes
+            and prior.get("version") == _release_version()
+            and all((agents_dir / name).is_file() for name in agents)):
+        return f"unchanged {destination}"
+
+    stage = Path(tempfile.mkdtemp(prefix=f".{skill}.stage-", dir=root))
+    backup = destination.with_name(f".{skill}.{PRODUCT}.backup")
+    try:
+        if destination.exists():
+            shutil.copytree(destination, stage, dirs_exist_ok=True)
+            for rel in tracked.keys() - hashes.keys():
+                (stage / rel).unlink()
+        for rel, data in desired.items():
+            target = stage / rel
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+        manifest = {
+            "product": PRODUCT,
+            "skill": skill,
+            "version": _release_version(),
+            "runtime_python": str(_runtime_python()),
+            "files": hashes,
+            **({"agents": agent_hashes} if agent_hashes else {}),
+        }
+        (stage / MANIFEST).write_text(json.dumps(manifest, sort_keys=True, indent=2) + "\n", encoding="utf-8")
+        if destination.exists():
+            destination.rename(backup)
+            try:
+                stage.rename(destination)
+            except OSError:
+                backup.rename(destination)
+                raise
+            shutil.rmtree(backup)
+        else:
+            stage.rename(destination)
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage)
+    written = _write_agent_files(agents_dir, agents) if agents_dir else []
+    return "\n".join([f"installed {destination}", *written])
+
+
+def _uninstall_one(root: Path, skill: str) -> str:
+    destination = root / skill
+    _recover_backup(destination)
+    if not destination.exists():
+        return f"absent {destination}"
+    _check_symlinks(destination)
+    prior = _read_manifest(destination, skill)
+    if prior is None:
+        raise InstallError(f"{destination} has no {PRODUCT} ownership manifest; refusing to remove it")
+    _check_existing(destination, prior["files"], allow_missing=True)
+    agents_dir = _agents_dir(root)
+    tracked_agents = prior.get("agents", {}) if agents_dir else {}
+    if agents_dir:
+        _check_existing(agents_dir, tracked_agents, allow_missing=True, guard_parents=False)
+    for rel in prior["files"]:
+        path = destination / rel
+        if path.exists():
+            path.unlink()
+    for name in tracked_agents:
+        (agents_dir / name).unlink(missing_ok=True)
+    (destination / MANIFEST).unlink()
+    for directory in sorted((p for p in destination.rglob("*") if p.is_dir()), key=lambda p: len(p.parts), reverse=True):
+        if not any(directory.iterdir()):
+            directory.rmdir()
+    if not any(destination.iterdir()):
+        destination.rmdir()
+    agents = f" and {len(tracked_agents)} agent file(s)" if tracked_agents else ""
+    return f"uninstalled {destination}{agents}; user files preserved"
+
+
+def _targets(args: argparse.Namespace) -> list[Path]:
+    if args.dir:
+        return [Path(args.dir).expanduser().resolve()]
+    hosts = args.host or []
+    if not hosts:
+        raise InstallError("choose --host codex|claude-code|dsh|opencode|pi|all, or --dir PATH; use --interactive for prompts")
+    if "all" in hosts:
+        hosts = list(HOSTS)
+    hosts = list(dict.fromkeys(hosts))
+    if args.scope == "project":
+        project = Path(args.project or Path.cwd()).expanduser().resolve()
+        if not project.is_dir():
+            raise InstallError(f"project directory does not exist: {project}")
+        bases = [project.joinpath(*PROJECT_DIRS[host]) for host in hosts]
+    else:
+        bases = []
+        for host in hosts:
+            if host == "dsh" and os.environ.get("DSH_HOME"):
+                bases.append(Path(os.environ["DSH_HOME"]).expanduser() / "skills")
+            elif host == "opencode" and os.environ.get("XDG_CONFIG_HOME"):
+                bases.append(Path(os.environ["XDG_CONFIG_HOME"]).expanduser() / "opencode" / "skills")
+            else:
+                bases.append(Path.home().joinpath(*USER_DIRS[host]))
+    return list(dict.fromkeys(bases))
+
+
+def _prompt(args: argparse.Namespace) -> None:
+    choice = input("Host (codex/claude-code/dsh/opencode/pi/all/custom): ").strip().lower()
+    if choice == "custom":
+        args.dir = input("Skill parent directory: ").strip()
+        if not args.dir:
+            raise InstallError("custom directory cannot be empty")
+        return
+    if choice not in (*HOSTS, "all"):
+        raise InstallError(f"unknown host {choice!r}")
+    args.host = [choice]
+    scope = input("Scope (project/user) [project]: ").strip().lower() or "project"
+    if scope not in ("project", "user"):
+        raise InstallError(f"unknown scope {scope!r}")
+    args.scope = scope
+    if scope == "project":
+        args.project = input(f"Project directory [{Path.cwd()}]: ").strip() or str(Path.cwd())
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=f"{PRODUCT}-install",
+        description=f"Install {PRODUCT} wheel-bundled agent skills, and the Claude Code subagent beside .claude/skills, without changing host configuration",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    for command in ("install", "upgrade", "doctor", "uninstall"):
+        part = sub.add_parser(command)
+        part.add_argument("--host", action="append", choices=(*HOSTS, "all"), help="Repeat for multiple hosts")
+        part.add_argument("--scope", choices=("project", "user"), default="project")
+        part.add_argument("--project", help="Project root; used only with project scope")
+        part.add_argument("--dir", help="Explicit parent directory for skills; overrides host and scope. A directory named .claude/skills also gets the agents directory beside it")
+        part.add_argument("--interactive", action="store_true", help="Ask for host and path even when stdin is redirected")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command in ("install", "upgrade", "doctor"):
+            _runtime_check()
+        for skill in SKILLS:
+            _resource_files(skill)
+        _agent_files()
+        if args.interactive or (args.command != "doctor" and not args.host and not args.dir and sys.stdin.isatty()):
+            _prompt(args)
+        if args.command == "doctor" and not args.host and not args.dir:
+            print(f"OK {PRODUCT} {_release_version()}: runtime, {len(SKILLS)} bundled skill(s), and {len(_agent_files())} Claude Code agent(s)")
+            return 0
+        for root in _targets(args):
+            for skill in SKILLS:
+                if args.command == "doctor":
+                    destination = root / skill
+                    _check_symlinks(destination)
+                    manifest = _read_manifest(destination, skill)
+                    if manifest is None:
+                        raise InstallError(f"skill is not installed: {destination}; run {PRODUCT}-install install")
+                    _check_existing(destination, manifest["files"])
+                    runtime = manifest.get("runtime_python")
+                    if isinstance(runtime, str) and runtime and not Path(runtime).is_file():
+                        raise InstallError(f"installed runtime no longer exists: {runtime}; reinstall the tool and upgrade this skill")
+                    print(f"OK {destination} ({manifest.get('version', 'unknown')})")
+                    if agents_dir := _agents_dir(root):
+                        tracked_agents = manifest.get("agents", {})
+                        if tracked_agents.keys() != _agent_files().keys():
+                            raise InstallError(f"agent files are not installed in {agents_dir}; run {PRODUCT}-install upgrade")
+                        _check_existing(agents_dir, tracked_agents, guard_parents=False)
+                        for name in tracked_agents:
+                            print(f"OK {agents_dir / name}")
+                elif args.command == "uninstall":
+                    print(_uninstall_one(root, skill))
+                else:
+                    print(_install_one(root, skill))
+        if args.command in ("install", "upgrade"):
+            command = shlex.quote(str(_runtime_python()))
+            for module in RUNTIME_MODULES:
+                print(f"runtime {module}: {command} -m {module}")
+        return 0
+    except (InstallError, OSError, EOFError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cbe_install/resources/agents/cbe-writer.md

@@ -0,0 +1,16 @@
+---
+name: cbe-writer
+description: Completes exactly one Codebase Explorer task from a CBE instruction file and writes the JSON result file. Use only for tasks handed out by `cbe host next`.
+tools: Read, Write
+---
+
+You complete one Codebase Explorer task. The message names an instruction file. Read it, follow it exactly, and write the one JSON object it asks for to the path it gives.
+
+The task kind decides the result shape:
+
+- A structured-detail batch lists its symbols as numbered lines, and either the source files with their line ranges or the source text itself. Read each listed file completely (page through long files). Return `{"units": [{"h": [12], "explain": "..."}, {"h": [20, 21], "title": "...", "explain": "..."}]}`, naming symbols only by their number (`h` with several numbers is a group). Leave out constants, imports and trivial accessors; group the tests that pin one behavior into one unit and say what they pin. Do not write ids, kinds, dispositions, line numbers or a source field: the program derives them. A re-ask lists only the gaps; return only the additional units.
+- The responsibility-tree task lists the accepted detail units and no raw source. Return `{"nodes": [...], "depends_on": [...]}`; every unit id must appear in exactly one node.
+- A review task shows one batch's units and its source. Return `{"decision": "accepted"|"needs_repair", "issues": [...]}`.
+- The naming and overview tasks return the short JSON shapes their instruction file states.
+
+Read only the source the instruction file lists. Do not run commands, edit other files, or add commentary to the JSON. Reply with the single line the instruction file specifies.

cbe_install/resources/codebase-explorer/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: codebase-explorer
+description: Generate a navigable, source-grounded documentation map (INDEX, a semantic responsibility tree, node pages with structured detail units and program-derived source anchors, and a symbol catalogue) for a code repository. Inside Claude Code, Codex, or another agent harness with subagents, the host agent runs `cbe host` and dispatches one subagent per reading task on the user's own subscription; with an OpenAI-compatible endpoint, run `cbe generate`. Also use it to query a generated map, resume an interrupted run, or report a run's token usage and cost.
+---
+
+# Codebase Explorer
+
+CBE splits documentation generation into deterministic CLI steps and model work. The CLI freezes one source snapshot (and validates an optional analyzed graph against it), builds the symbol inventory and reading batches, hands out tasks, checks every JSON result, builds the module tree from the call and import edges, renders node pages with program-derived source anchors, and builds the catalogue for `cbe find`. The model work is one fresh completion per task: one structured-detail payload per batch, the names of the modules in the tree (`tree_name_<k>` for the leaf modules, `tree_top` for the groups above them; the program decides the structure and the model cannot change it), optional reviews, and the system overview. Each detail unit has exactly one primary owner in the tree; the program, never the model, writes the published line ranges.
+
+Pick the path by where you run:
+
+| You are | Use | Model work runs on |
+|---|---|---|
+| Claude Code, Codex, or another harness that can start subagents | `cbe host ...` (below) | your subagents, on the user's subscription |
+| A shell or service that reaches an OpenAI-compatible endpoint, with no harness login | `cbe generate` (end of this file) | that endpoint, one tool-free request per task |
+
+## Runtime
+
+Use the absolute `cbe` command from the "Installed runtime" note if `cbe-install` added one above. Otherwise try `cbe --version`, then `"$(uv tool dir --bin)/cbe" --version`. If CBE is missing, ask the user before installing it.
+
+The `cbe` CLI and this Skill are **one build**: the structured-detail, responsibility-tree, `cbe graph` and `cbe context` protocol above exists only in a build that ships with this Skill. An older `cbe` will plan a different run and reject new flags, so install a build matching this Skill, not a remembered version number.
+
+- Published release: install the wheel or tag that ships with this Skill. Do not assume a tag name; use whatever the Skill's release page names.
+- Development build from a checkout (use this while the build is unpublished). Point `uv` at the checkout so the CLI and this Skill come from the same commit:
+
+  ```sh
+  uv tool install --python 3.13 /path/to/codebase-explorer
+  ```
+
+After installing, confirm `cbe --version` and that the newest surface is present, for example `cbe context --help` and `cbe graph capabilities --help`; a CLI without those commands predates this Skill.
+
+## Host-driven generation
+
+1. **Plan.** From the repository root:
+
+   ```sh
+   cbe host plan . --review sample --jobs 4 --host claude-code   # or --host codex
+   cbe host plan . --graph /abs/path/graph.json                  # analyzed graph for the same source
+   ```
+
+   `.` is the repository root; the CLI turns it into an absolute path. `--run-dir`, `--repo`, and `--graph` need absolute paths. The command freezes `context.json` (the source snapshot), builds the symbol inventory and reading batches, and prints `run_dir`, `run_tag`, and the file, token, module, and task counts. `RUN` in the commands below is that `run_dir`, written out in full. Tell the user these counts before dispatching, and that the `tasks` count is only the planned tasks: each review finding queues one more repair task later, so the run can finish with more. `--review` is `none`, `sample` (default: one review of the largest batch), or `all` (one review per batch; each finding queues one repair). `--jobs` caps concurrent subagents; keep it within the user's subscription capacity. `--graph` is optional: without it the run records the graph as not provided; with it, CBE rejects a graph whose `source_manifest` does not match the frozen source.
+
+2. **Dispatch.** Run `cbe host next --run-dir RUN`. It leases every task it returns to you, including a re-ask of a task whose answer `submit` rejected. Start one fresh subagent for each returned task, re-asks included, whose whole prompt is the task's `dispatch_message`. Label it with the task's `description` (Claude Code) or `codex_task_name` (Codex), copied exactly; the label lets CBE find that subagent's exact usage later. Attempts at one task share its label, and `import-usage` adds them together. Start the subagents for one `next` batch concurrently. The host page says how you learn that a subagent has finished: in Claude Code its hand-back message starts your next turn, in Codex you wait with `wait_agent`. Do not poll the run directory or sleep in a loop while subagents run. The host-specific calls are in [claude-code.md](references/claude-code.md) and [codex.md](references/codex.md).
+
+3. **Submit.** When a subagent has finished, run `cbe host submit --run-dir RUN --task TASK`, adding the usage numbers the harness showed for that subagent when it shows any. Do not wait for usage that arrives later: a task submitted without usage still gets exact usage from `import-usage`. Submit every finished task before you call `next` again: `next` counts a task as running until `submit` settles it, and a free slot appears only then. The CLI reads the JSON file that the subagent wrote. Module and repair detail tasks allow 3 answers; other tasks allow 2. A detail answer names symbols by the short numbers in its instruction file. CBE keeps every usable unit and re-asks with only the gaps: functions, methods or classes with logic that no unit explains, and rejected units. After the last answer, symbols that are still unexplained are indexed without prose and flagged `unexplained` (STATUS, summary and RUN.md list them), and the task still completes. Other tasks go back to the queue with the exact error and a correction request; on their final invalid answer, usable content is normalized, accepted, and flagged, or the task is marked `failed`. If no answer of a detail task is a JSON object with a `units` list, the task fails and requires resume; the rest of the run continues.
+
+   `submit` prints one JSON object and exits 0 whether it accepts or rejects, so read `accepted` first. With `accepted: true`, `normalized` and `flags` say whether CBE corrected the answer; a repeated submit of a finished task returns `already: true` and neither key. With `accepted: false` there is no `normalized` or `flags`: `error` holds the checker's message, `attempts` counts the answers so far, and `task_status` is `pending` (a re-ask is queued and `next` returns it) or `failed` (the attempts are used up; see step 4). Both outcomes also add a line to `RUN/progress.log`. The `error` text and that log line are enough to tell the user why an answer was rejected; do not open the instruction files for it. The re-asked subagent finds the same error in its own instruction file.
+
+4. **Repeat** `next` and `submit` until `status` is `complete` or `partial`. Structured-detail batches come first. Reviews may run as their batches finish, alongside other detail work; findings queue repairs. When all detail and review has settled, the program freezes the module tree and the naming tasks appear (`tree_name_<k>` in parallel, then `tree_top`); an accepted repair or late batch makes the tree again. A node the model cannot name gets a program-made title and a note. The overview comes last. Follow `next` for the current dependency order. CBE renders the docs when the overview arrives or when nothing more can run. With `partial`, every finished batch is rendered, the pending work is named in the notes of `docs/RUN.md`, and failed parts stay pending. Report the failed tasks and their errors to the user (the `failed` list in `next`, `submit`, and `status` output names each task with its last error); after the cause is fixed, `cbe host resume` gives them fresh attempts.
+
+5. **Verify.** `cbe host verify --run-dir RUN` runs the deterministic structural and coverage checks: every task is done, the sources did not change, every file is in exactly one reading batch, every detail unit has exactly one primary owner, the responsibility tree is single-rooted and acyclic, every unit's published range is present and in bounds, relative links resolve, the catalogue covers every file, and symbol/unit queries resolve to their actual primary page anchors (or explicitly explain an index-only disposition). These checks do not judge whether an explanation is true. Truth of the prose stays with the separate `review_*` task (one fresh subagent) and the final independent verification, so a run that reports `complete` with passing checks is structurally sound, not thereby semantically reviewed. Report any failed check and say which of the three states applies: run finished, structure valid, semantic review done.
+
+Rules for the host agent:
+- Do not read the instruction files or the source yourself, and do not write or edit result JSON. The subagent does that work; the CLI checks it. This keeps your own context and cost small.
+- Do not run more than `--jobs` subagents at once. `next` never hands out more.
+- Never mark a task done by hand. Only `submit` accepts work.
+
+## Progress and resume
+
+The run records where it is while it runs: `RUN/progress.log` (one line per claim, acceptance, re-ask, normalization, failure, retry, and render, with timings), `RUN/STATUS.md` (every task's state, attempts, seconds, and output path), and `RUN/host/state.json`. `cbe host status` prints the same table. Any host can continue from these records: `cbe host resume --run-dir RUN` (or `--repo /abs/path/to/repo`, which picks the repository's latest run) accepts results that subagents finished writing before an interruption, returns lost leases to the queue, gives failed tasks fresh attempts (`--keep-failed` skips that), and prints the next action. Then continue at step 2. If it reports changed sources, start a new plan: the old plan no longer matches the code.
+
+## Cost and usage
+
+Report cost after every run. The rule: **use the harness's exact numbers when it records them; otherwise estimate, and say clearly that it is an estimate.**
+
+1. Run `cbe host import-usage --run-dir RUN --harness claude-code` (or `codex`). It reads the per-subagent usage that the harness already wrote to disk.
+2. Run `cbe host cost --run-dir RUN`. Rows with imported usage are `exact` and are priced by the model recorded in their transcript; the rest are `estimate`, computed from instruction, source, and result sizes. Add `--model MODEL` (for example `claude-sonnet-5-5`) only when `import-usage` listed `tasks_without_exact_usage`: it prices those estimated rows, which otherwise show `null` dollars. Token certainty and pricing are separate: unknown model prices produce `null` dollar values in JSON and `unknown` in the report. Supply current rates with `--price INPUT,OUTPUT,CACHE_WRITE,CACHE_READ` when needed; CBE does not silently substitute a comparison price. It writes `host/COST.md` and `host/cost.json`.
+3. Tell the user: the number of subagent runs, the wall time (from the `plan` line to the last `render` line in `RUN/progress.log`), the token totals and whether they are exact or estimated, and the API-list-price equivalent. Say that the dollar figure is not a bill: a subscription spends plan quota. Your own orchestration turns are not included. The harness shows their total with a command that only the user can type (`/usage` in Claude Code, `/status` in Codex); ask the user to run it if they want that total.
+
+## Read and query the result
+
+Start at `RUN/docs/INDEX.md`: the overview, then the module tree, one line per module saying what it is responsible for. Pick the module that matches the maintenance question and open its node page; if the tree is not enough, use `cbe find --run-dir RUN --term WORD` to locate a symbol, `cbe query` to read one unit and `cbe source` for its frozen source. `DEPENDENCIES.md` holds the dependency view and `RUN.md` the graph coverage and generation notes. On a node page select a unit. The page keeps the explanation, necessary boundary notes, uncertainties, and compact relation links. Its footer shows how to find the selected title's ID and then query it.
+
+The dependency view uses **graph-confirmed** for pairs found in both the tree and resolved call/import edges, **model-inferred** for tree-only pairs, and **graph-only** for graph-only pairs. The first two count edges between subtrees; graph-only counts direct node owners. **Containment** rows show ancestor direct units versus a descendant subtree as `→ N / ← M`, relative to the listed pair. **Within containment** rows list direct owner pairs separately. Both containment categories stay out of Mermaid and the three dependency totals. Graph-only and within containment each keep up to 40 pairs, ranked by edge count, with independent omitted counts. `summary.json` reports the full within containment count in `within_containment`. If the model supplies no key flows, the report shows the first five **Program candidates, not selected by the model**. Program labels and navigation use English; model prose keeps its original language.
+
+`RUN` is the absolute run directory. Find an ID, then retrieve its complete explanation and evidence:
+
+```sh
+cbe find --run-dir RUN --term SEARCH_TERM
+cbe query --run-dir RUN --id ID
+cbe query --run-dir RUN --id ID --json
+cbe query --run-dir RUN --id ID --edges cfg,dataflow
+cbe query --run-dir RUN --id ID --edges all --json
+cbe source --run-dir RUN --id ID --context 2
+```
+
+`ID` can be a unit ID, inventory symbol ID, or file path. `query` returns explanation text, full signatures, all source ranges, folded members, relation evidence, and incoming and outgoing call/import edges with their original statuses. CFG/dataflow edges are counted by default; use `--edges cfg,dataflow` or `--edges all` to expand original outgoing edges from the frozen graph. Dataflow is only in graphs built with `cbe graph build --with-dataflow`; on other graphs `--edges dataflow` says so and `internal_edge_counts` has no `dataflow` entry. Use `--json` for the machine-readable object. A grouped symbol retains its own source range; take `unit_id` from `query --json` and query that ID for the owning unit and all its ranges. A file query lists its symbols and associated units. An index-only symbol returns its recorded reason instead of invented prose.
+
+`source` prints numbered code from `RUN/context.json`. It verifies each selected file's SHA-256 before printing any code. It reports a digest mismatch as an error. `--context N` adds N surrounding lines and must be nonnegative. Use this command to inspect the precise code behind an explanation.
+
+`catalog.json` preserves the unit records and indexes graph edges. Complete graph evidence stays once in the frozen context and `query` expands it on demand. `summary.json` reports token ratios and their scope. Graph evidence describes static analysis; it does not prove runtime behavior. Confirm that the explanations answer the maintenance question before claiming semantic quality.
+
+## Script-driven generation (OpenAI-compatible API)
+
+```sh
+cbe generate . --model gpt-oss-120b \
+  --base-url https://api.example.com/v1 --api-key-env MY_API_KEY
+```
+
+`cbe generate` speaks the OpenAI-compatible `POST {base-url}/chat/completions` shape. The API key comes from the named environment variable (default `OPENAI_API_KEY`) or a standard config file, never from a flag, and CBE never writes it to the run log or any durable artifact. The command runs every completion itself on the same run state as `cbe host`, prints `run_dir`, `index`, status, token totals, and elapsed time, and records each physical call in `calls.csv`. It exits 0 when complete and 3 when the docs are rendered with pending parts; continue with `cbe generate . --resume`. Review modes are `none`, `sample`, and `all`.
+

cbe_install/resources/codebase-explorer/references/claude-code.md

@@ -0,0 +1,63 @@
+# Claude Code host
+
+## Install
+
+Install a CBE build that ships with this Skill (the CLI and Skill are one build; an older CLI lacks the `cbe graph`/`cbe context` surface), then install the skill. From an unpublished checkout:
+
+```sh
+uv tool install --python 3.13 /path/to/codebase-explorer
+"$(uv tool dir --bin)/cbe-install" install --host claude-code --scope project   # .claude/skills/codebase-explorer and .claude/agents/cbe-writer.md
+```
+
+Use `--scope user` for `~/.claude/skills` and `~/.claude/agents`. `cbe-install` installs the skill and the `cbe-writer` subagent (Read and Write tools only, so a writing subagent cannot run commands). It does not overwrite a `cbe-writer.md` or skill directory that it did not install; `cbe-install uninstall` removes both. Alternatively install the plugin, which carries the same two parts:
+
+```sh
+claude plugin marketplace add zlxdengtianhei/codebase-explorer
+claude plugin install codebase-explorer@codebase-explorer
+```
+
+The plugin does not install the Python CLI; the skill's Runtime section covers that.
+
+## Dispatch with the Agent tool
+
+For each task from `cbe host next`, call the Agent tool with:
+
+- `description`: the task's `description` field, exactly (`cbe <run_tag> <task>`). `import-usage` matches transcripts by it.
+- `prompt`: the task's `dispatch_message`, exactly.
+- `subagent_type`: `cbe-writer` once `cbe-install` (or the plugin) has installed it; the plugin's copy may be listed as `codebase-explorer:cbe-writer`. If the Agent tool does not list it, use `general-purpose`.
+- `model`: the model the user chose. If the user did not choose, `sonnet` is enough for module, naming, and overview tasks.
+
+Issue one Agent call per task of a `next` batch, all in a single message, so the subagents run concurrently. `next` also returns a re-ask of a rejected task: start a new subagent for it too, with the same `description` and `prompt`.
+
+## Submit when a subagent hands back
+
+Claude Code runs these Agent calls in the background: each call returns at once with `Async agent launched`, whether or not you asked for background mode. After you start the batch, end your turn. Each subagent finishes with one line, `DONE <task>`. It reaches you in a new message that starts your next turn. Depending on the Claude Code session, that message is a hand-back (sometimes wrapped as a message from another Claude session) or a task notification that also carries a usage block. Act on the first message that names the task:
+
+1. Submit that task at once, without the usage flags: `cbe host submit --run-dir RUN --task module_3`. `import-usage` below adds exact usage after the run.
+2. Call `next` and start the subagents it returns.
+3. End your turn again.
+
+Do not poll `host/outbox/` or sleep in a loop while subagents run. The outbox file can exist before its subagent has ended, and a polling command asks the user for permission. Do not wait for a second message about a task you can already submit: in some sessions the later completion notification did not start a new turn, so a run that waited for it stopped there. If one does arrive after you submitted, it needs no action. Calling `next` before you submit a finished task leaves its slot taken.
+
+If an Agent call returns the subagent's result instead (the result ends with a usage block, `<usage>` with `subagent_tokens`, `tool_uses`, `duration_ms`), submit from that result and you may add its usage:
+
+```sh
+cbe host submit --run-dir RUN --task module_3 --usage-tokens 21480 --tool-uses 5 --duration-ms 48210 --usage-source claude-code-agent-result
+```
+
+`subagent_tokens` is the size of that subagent's final context (input, cache, and output of its last turn), not the total it processed across turns. Keep it as a quick check only.
+
+## Permission prompts
+
+The run commands in this skill (everything after the install step) do not use quotes, for example `cbe host plan . ...` instead of `cbe host plan "$PWD" ...`. Claude Code cannot check quoted text before a command runs, so a command with a quoted variable asks for confirmation even when `cbe` is on the allow list. Without quotes, the user can allow `cbe` as a command prefix and the run goes through without prompts. If a runtime note at the top of the skill gives the command as `/path/to/python -m cbe`, that whole prefix is what the user allows.
+
+## Exact usage
+
+Claude Code writes every subagent transcript to `~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl`, with a `usage` object on each model message (input, cache write, cache read, output tokens) and the model ID. The `.meta.json` next to it keeps the Agent `description`.
+
+```sh
+cbe host import-usage --run-dir RUN --harness claude-code
+cbe host cost --run-dir RUN
+```
+
+`import-usage` sums every turn of every subagent whose description is `cbe <run_tag> <task>`, so the token counts are exact; the attempts at one task add up. `cost` prices them at the Anthropic list price of the model in each transcript. Add `--model MODEL` (for example `claude-sonnet-5-5`) only when `import-usage` lists `tasks_without_exact_usage`: it prices those estimated rows. For the whole session, including your orchestration turns, ask the user to run `/usage`: it is a command only the user can type (a subscription shows plan usage, not dollars).