codebase-explorer 2.2.0__tar.gz

codebase_explorer-2.2.0/.gitignore

@@ -0,0 +1,19 @@
+# Local-only / generated (added at in-repo migration; original tree had no .gitignore)
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+.cc_test_logs/
+claude_mcp_list.txt
+.claude/
+.DS_Store
+experiments/**/node_modules/
+experiments/**/.work/
+.codebase-analysis/
+
+# evaluation scratch (clones, raw model answers)
+.eval/
+evaluation/tree/commits/
+evaluation/tree/results/*.json
+evaluation/tree/results/*.jsonl

codebase_explorer-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zlxdengtianhei and Codebase Explorer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codebase_explorer-2.2.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: codebase-explorer
+Version: 2.2.0
+Summary: Source-grounded, navigable documentation for software repositories
+Project-URL: Homepage, https://github.com/zlxdengtianhei/codebase-explorer
+Project-URL: Documentation, https://github.com/zlxdengtianhei/codebase-explorer/blob/main/docs/running.md
+Project-URL: Online example, https://zlxdengtianhei.github.io/codebase-explorer/?data=flask
+Project-URL: Changelog, https://github.com/zlxdengtianhei/codebase-explorer/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/zlxdengtianhei/codebase-explorer/issues
+Author: zlxdengtianhei
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,call-graph,claude-code,code-documentation,code-understanding,developer-tools,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.12
+Requires-Dist: networkx>=3.2
+Requires-Dist: tiktoken<1,>=0.9
+Requires-Dist: tree-sitter-c==0.24.2
+Requires-Dist: tree-sitter-cpp==0.23.4
+Requires-Dist: tree-sitter-go==0.25.0
+Requires-Dist: tree-sitter-java==0.23.5
+Requires-Dist: tree-sitter-javascript==0.25.0
+Requires-Dist: tree-sitter-python==0.25.0
+Requires-Dist: tree-sitter-typescript==0.23.2
+Requires-Dist: tree-sitter==0.26.0
+Provides-Extra: graphs
+Requires-Dist: grimp==3.17; extra == 'graphs'
+Provides-Extra: languages
+Requires-Dist: tree-sitter-c-sharp==0.23.5; extra == 'languages'
+Requires-Dist: tree-sitter-php==0.25.1; extra == 'languages'
+Requires-Dist: tree-sitter-ruby==0.23.1; extra == 'languages'
+Requires-Dist: tree-sitter-rust==0.24.2; extra == 'languages'
+Provides-Extra: languages-community
+Requires-Dist: tree-sitter-kotlin==1.1.0; extra == 'languages-community'
+Requires-Dist: tree-sitter-swift==0.7.4; extra == 'languages-community'
+Description-Content-Type: text/markdown
+
+<h1 align="center"><img src="https://raw.githubusercontent.com/zlxdengtianhei/codebase-explorer/v2.2.0/docs/media/logo.svg" width="40" height="40" alt="" align="absmiddle">&nbsp;Codebase Explorer</h1>
+<p align="center">Codebase Explorer turns a source repository into a one-page module map and per-module explanations that people and coding agents can read and query.</p>
+<p align="center"><b>English</b> | <a href="https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/README.zh-CN.md">简体中文</a></p>
+<p align="center">
+<a href="https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+<a href="https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/pyproject.toml"><img alt="Python 3.12 and 3.13" src="https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg"></a>
+<a href="https://github.com/zlxdengtianhei/codebase-explorer/actions/workflows/wheel-install.yml"><img alt="CI" src="https://github.com/zlxdengtianhei/codebase-explorer/actions/workflows/wheel-install.yml/badge.svg"></a>
+</p>
+
+https://github.com/user-attachments/assets/f0c3cc47-d0c2-4727-820e-65508c19408c
+
+<p align="center">Two minutes, narrated: Flask from its source files to the module map, the eight top-level modules, one module page, then <code>cbe find</code> and <code>cbe source</code>.<br><a href="https://zlxdengtianhei.github.io/codebase-explorer/?data=flask">Try the interactive map</a> · <a href="https://zlxdengtianhei.github.io/codebase-explorer/film.html">The same video with its transcript (English and Chinese)</a></p>
+
+A file tree shows where files are, not what each part is for. CBE (Codebase Explorer) reads a repository and writes what the tree lacks: one page that lists the whole module tree with a line on what each module is responsible for, and a page per module that explains each function and class and links to the exact source lines. You read it. A coding agent can look things up in it with three commands.
+
+**To try it:** `uv tool install codebase-explorer` (Python 3.12 or 3.13). Then generate inside Claude Code on your own subscription, or from the command line with any OpenAI-compatible endpoint (you name the model with `--model`). The steps are in [Quickstart](#quickstart).
+
+## What you get
+
+- **A one-page map.** `docs/INDEX.md` shows the whole module tree, one line per module. Its size is capped at the larger of 2,000 tokens and 3% of the source's token count.
+- **A tree without gaps, the same every time.** A program builds it: units that call or import each other, sit close together and use similar words are grouped. The same input gives the same tree. There are no empty nodes and no duplicate modules.
+- **A page per module.** Each unit has its signature, a source link, and an explanation written by a model. The explanations are written for people to read.
+- **Facts from commands, not from the model.** Signatures, calls and source lines come from `cbe find`, `cbe query` and `cbe source`. `cbe source` prints from the frozen snapshot and checks each file's SHA-256 against the digest recorded at freeze time before printing anything.
+
+The start of a real `docs/INDEX.md`, generated for flask (unedited):
+
+```markdown
+## Modules
+
+- [**Request Serving Application Runtime**](nodes/request-serving-application-runtime.md) — Combines the concrete WSGI Flask application with request and response wrappers, templating, context lifecycle, and view-facing helpers needed to serve live requests. (136 units; `flask/app.py`, `helpers.py`, `wrappers.py`)
+  - [**Request Helper Utilities and Tests**](nodes/request-helper-utilities-and-tests.md) — Provides view-facing helpers for files, flashing, redirects, streaming, and URL building, plus proxy globals and signal definitions, with focused behavioral tests. (42 units; `helpers.py`, `test_helpers.py`, `flask/blueprints.py`)
+    - [**Helpers, globals, and signals**](nodes/helpers-globals-and-signals.md) — Provides view-facing helpers for sending files, flashing messages, redirecting, streaming, and URL building, plus proxy globals and Flask's blinker signal definitions. (26 units; `helpers.py`, `flask/blueprints.py`, `globals.py`)
+    - [**Helper behavior tests**](nodes/helper-behavior-tests.md) — Verifies aborter selection and dispatch, app redirect delegation, open_resource read modes and encoding, and context-free redirect fallback behavior. (11 units; `test_helpers.py`)
+    - [**File and URL tests**](nodes/file-and-url-tests.md) — Tests custom URL converters, send_file family behavior with path-like objects, stream_with_context lifetime, and url_for inside request contexts. (5 units; `test_helpers.py`, `test_converters.py`)
+  - [**WSGI Request Dispatch Core**](nodes/wsgi-request-dispatch-core.md) — Implements the WSGI-callable Flask class and its pipeline: request entry, URL-to-view matching, response finalization, error handler resolution, and test and async wiring. (35 units; `flask/app.py`, `test_async.py`, `sansio/app.py`)
+```
+
+Full example: [flask](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/flask/docs/INDEX.md). More in [Examples and docs](#examples-and-docs).
+
+## Quickstart
+
+CBE is on PyPI as `codebase-explorer`. It needs Python 3.12 or 3.13. There are two ways to run it. Both end in the same `docs/` folder. The usual one is A: your coding agent loads the skill and does the work on your own subscription. B is for scripts and batch runs.
+
+**A. The usual way: inside your coding agent, on your own subscription.** The steps below use Claude Code; the skill makes its subagents write the explanations.
+
+1. Install CBE: `uv tool install codebase-explorer` (or `pipx install codebase-explorer`).
+2. Optional, for the call graph: `cbe graph setup` downloads Joern and a Java runtime into your user cache directory (about 1.9 GB; Linux x86_64 and macOS).
+3. In your project, install the skill: `cbe-install install --host claude-code`.
+4. Start Claude Code there and ask: "Use the codebase-explorer skill to generate documentation for this repository."
+5. The agent prints the planned file, token, module and task counts, runs the subagents, and verifies the result.
+6. Open `<run_dir>/docs/INDEX.md`. The agent reports `run_dir`.
+
+Other agents load the same skill: `cbe-install install --host` takes `claude-code`, `opencode`, `pi`, `codex` and `dsh`. What has run end to end: Claude Code (see [What it costs](#what-it-costs)); OpenCode and Pi, once each on a 22-file sample repository (in the Pi run the tasks were handed to separate Pi sessions by a dispatch skill on our machine; Pi has no subagents of its own). `codex` and `dsh` install the skill, and we have not run them end to end. Details: [docs/running.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/running.md#generate-through-a-host-agent).
+
+**B. For scripts and batch runs: from the command line, with any OpenAI-compatible endpoint.** There is no default model: you must pass `--model`.
+
+1. Install CBE as in step 1 above.
+2. Put the key in an environment variable: `export CBE_API_KEY=...`
+3. Optional: build the call graph (`cbe graph setup`, then `cbe graph build /abs/repo --output /abs/graph.json`).
+4. Generate. Paths must be absolute:
+
+   ```sh
+   cbe generate /abs/repo --model MODEL --base-url https://your-endpoint.example/v1 \
+     --api-key-env CBE_API_KEY --graph /abs/graph.json --run-dir /abs/run
+   ```
+
+5. Open `/abs/run/docs/INDEX.md`. Drop `--graph` to run without a call graph.
+
+Then look things up. `RUN` is the absolute run directory, and the ID is the second column of the `find` output:
+
+```sh
+cbe find   --run-dir "$RUN" --term url_for
+cbe query  --run-dir "$RUN" --id 'src/flask/helpers.py::function::url_for::6511'
+cbe source --run-dir "$RUN" --id 'src/flask/helpers.py::function::url_for::6511' --context 2
+```
+
+Every other command and option is in [docs/reference.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/reference.md).
+
+## How it works
+
+```mermaid
+flowchart LR
+  A["Freeze the source"] --> B["Tree-sitter splits it at syntax boundaries"]
+  B --> C["Joern builds call and import graph (optional)"]
+  C --> D["Model explains each code unit"]
+  D --> E["Program groups units into a module tree"]
+  E --> F["Model names each module"]
+  F --> G["Render INDEX.md, module pages, catalog.json"]
+  classDef program fill:#dff7f3,stroke:#0f9b8e,color:#0f1b2d
+  classDef model fill:#fff0cc,stroke:#c98a00,color:#0f1b2d
+  class A,B,C,E,G program
+  class D,F model
+```
+
+Teal steps are ordinary code and make no model call. Amber steps are model calls.
+
+- **Freeze.** CBE keeps a hashed copy of the source, so every line number and quote can be checked later.
+- **Split.** Tree-sitter cuts each file at syntax boundaries. Every byte lands in some chunk.
+- **Explain.** The model writes the explanations batch by batch. It names symbols by the short numbers in a list, so it cannot invent an ID. The program asks again only for the symbols the model skipped.
+- **Check.** A second model reads one batch's source and checks its explanations against it: wrong behaviour, a wrong condition or error, or an explanation of the wrong symbol. It does not judge style. Findings are sent back for one rewrite. `--review` chooses how many batches are read: `none`; `sample` (the default: the largest batch, and every batch if that one has any finding); or `all`. On flask a sampled review was 14% of the run's input tokens; reading every batch adds about 80%. Where batches have many errors the rewrites cost more than the reading: on six examples whose sample had findings, reviewing every batch and rewriting the flagged ones added 51–176% to the run's input tokens and made its output tokens 4 to 10 times as large, because a flagged batch is written again in full. A clean sample leaves the other batches unread, so use `--review all` for a repository that matters. `RUN.md` says which batches were read and what was found. A rewrite after review, like any new run, can regroup the map: module pages and their names may change. Symbol IDs (`cbe find`, `cbe query`) depend only on the source, so link to code by ID, not by page name.
+- **Group.** The program, not the model, builds the module tree from calls and imports, location, and wording. The same input gives the same tree.
+- **Name.** The model gives each module a name, one line on what it is responsible for, and two or three sentences on how to read it. It cannot add, drop or move a node.
+- **Render.** The program writes `docs/INDEX.md`, one page per module, `DEPENDENCIES.md` and `RUN.md`, and the `catalog.json` that `find`, `query` and `source` read.
+
+## Code graph
+
+Without a graph, CBE still works. With one, the explanation tasks and the dependency view also get static import, call and control-flow evidence. The graph comes from [Joern](https://joern.io/), which needs Java 21 or newer. `cbe graph setup` downloads the pinned Joern and, if no suitable Java is found, a Java runtime into your user cache directory (about 1.9 GB in total). `cbe graph setup --check` downloads nothing and reports what is installed. `cbe graph build` then writes the graph file that `--graph` takes. It does not export dataflow unless you pass `--with-dataflow`, because a generation run does not read it and it was over half of the graph file on flask (23 of 41 MB). To install Joern by hand, see [docs/reference.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/reference.md#optional-graph-analyzers).
+
+| Status | Languages | Conditions |
+|---|---|---|
+| Works on real repositories | C, C++, Python, JavaScript, TypeScript, Java, Go, Ruby | Python imports use Grimp (the `graphs` extra); JavaScript and TypeScript imports use dependency-cruiser (Node.js). Go calls across packages can stay unresolved. Ruby's dynamic dispatch can bind a call to a method of the same name on another class: CBE marks such calls ambiguous, and some wrong bindings remain. |
+| Needs an extra tool | Rust, PHP | Rust needs `cargo` and a Cargo project layout. PHP needs `php` (7 or later). |
+| Builds, calls partly resolved | C# | On a 55-file repository the graph builds (declarations, control flow, imports). Of its 2,322 calls, 689 resolve to one repository method and 394 to a set of overloads (Joern's C# frontend does not type arguments well enough to pick the overload); 246 point outside the repository and 993 stay unresolved. |
+| Fails on real repositories | Kotlin | Joern 4.0.654 failed on a 146-file Kotlin repository. Two-file examples work, so small inputs may succeed. |
+| Not tested | Swift, TSX | |
+
+`cbe languages` prints the same status for each language as `call_graph`. Source parsing and chunking work for every language in the table whatever the call-graph status is. Tree-sitter grammars for 13 languages come with the default install and two extras. More on analyzers and graph options: [docs/reference.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/reference.md#optional-graph-analyzers).
+
+## What it costs
+
+Measured on flask, tests included: 65 files, 125k tokens. Model: GLM-5.3-Flash, called through `cbe generate`. One run to completion.
+
+| Measure | Reading |
+|---|---|
+| Prompt tokens | 3.2–3.4 times the source tokens |
+| Output tokens | about 0.9 times the source tokens |
+| Explanation text the model wrote | about 30% of the source tokens |
+| Prompt tokens spent on re-asks after a rejected answer | about 22% (43% before the answer-format change; that earlier run also stopped midway on upstream rate limiting) |
+
+These readings come from calls through an OpenAI-compatible gateway to GLM-5.3-Flash. CBE ships default settings (for example `reasoning_effort: low`) only for model names it knows. For any other model name, pass the settings you need with `--config`; [docs/running.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/running.md#api-configuration-keys) lists every key.
+
+The host-agent path, measured once on flask's `src/` (24 files, about 75k tokens) with headless Claude Code (`claude -p`) and Sonnet subagents:
+
+| Measure | Reading |
+|---|---|
+| Subagent tasks | 8: 4 explanation batches, 1 sampled review, 2 tree-naming tasks, 1 overview. All were accepted on the first answer |
+| Wall clock | 293 seconds |
+| `cbe host verify` | all 15 checks passed |
+| Tokens | not collected for this run |
+
+Each table is one repository and one run. A host-agent run uses your subscription instead of an API key. Building the graph makes no model call. An older cost table for repositories up to 1.7 million tokens is in [docs/running.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/running.md#what-a-run-costs-the-earlier-table); it was measured before the answer-format change, so do not compare it with the table above.
+
+## How well does it work
+
+What we measured, and what it shows. Everything here has conditions; the files in [`evaluation/tree/results/`](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/evaluation/tree/results/) hold the tables.
+
+The page you read first got smaller. Size of that page in `o200k_base` tokens, on three full runs (the earlier version's tree is in the "before" column):
+
+| Repository | Before | Now | Empty tree nodes before / now |
+|---|---:|---:|---:|
+| flask | 16,076 | 3,078 | 22 / 0 |
+| ruby_llm | 15,938 | 2,074 | 8 / 0 |
+| gson | 12,643 | 2,514 | 16 / 0 |
+
+- **Tree structure.** The new trees have no empty nodes and no duplicate modules on the three repositories above. The earlier trees had 22, 8 and 16 empty nodes.
+- **Call labels.** In seven repositories we took 10 edges of each status and checked them back against the source. For example, all 307 "unresolved" calls in cJSON were macros; they are no longer counted as calls. In fmt, "external" calls fell from 2,748 to 22.
+- **Does the tree help find the code to read?** We took 30 real commits from each of five repositories and asked three models which three modules to look at for the change. The new tree and the earlier tree could not be told apart. Against a plain directory listing, the module tree made no clear difference in repositories whose directories already have levels. It narrowed the reading only where directories are flat (flask, fmt): the three chosen modules held about 40% of the source and about 0.75–0.8 of the changed lines.
+- **How far to trust that ruler.** It is noisy: asked the same question again, the model gave an identical answer in only 9 to 23 of 30 cases.
+- **Earlier question-answering rounds** (CBE before the program-built tree). On flask and pytest (48 questions each), an agent with CBE documents and commands scored no differently from a source-only agent, and rarely ran the commands. One exploratory reading on curl scored higher with CBE (+5.60 rubric points, interval [+0.90, +10.82]) and comes with caveats listed in [evaluation/README.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/evaluation/README.md).
+
+What we do not claim: that grouping by function lets an agent locate code more accurately than a directory tree does, or that CBE improves an agent's answers. The measurements above do not show either.
+
+## Known limitations
+
+- The call graph needs Joern and Java 21 or newer. `cbe graph setup` downloads both (about 1.9 GB).
+- C# calls to overloaded methods resolve only to the set of overloads, and about 43% of the calls in the one real repository measured stay unresolved. Kotlin graphs fail on real repositories under the pinned Joern version; two-file examples work.
+- Ruby's dynamic dispatch can bind a call to the wrong class's method. CBE marks many of these as ambiguous, and some wrong bindings remain.
+- C and C++ files are not preprocessed. A header with many macros is cut into coarse chunks, and a macro can be taken for a function name.
+- A model writes the explanations. `cbe host verify` passing shows that the structure and references are consistent. It does not show that an explanation is correct. Check explanations against the source (`cbe source`).
+- There are no incremental updates: when the source changes, generate again.
+
+## Examples and docs
+
+- Generated documents: [flask](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/flask/docs/INDEX.md), [cJSON](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/cjson/), [fmt](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/fmt/), [gson](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/gson/), [ruby_llm](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/ruby_llm/), [tsdown](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/tsdown/), [polyglot](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/examples/polyglot/). Each example's README names the CBE commit that generated it; most were generated by an earlier version.
+- [docs/reference.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/reference.md): install options, languages, graph analyzers, `find`, `query`, `source`, named declaration coverage.
+- [docs/running.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/running.md): host-agent and API runs, the run directory, resume and verify, cost details, troubleshooting.
+- [docs/videos.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/docs/videos.md): walkthrough videos.
+- [evaluation/README.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/evaluation/README.md) and [CHANGELOG.md](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/CHANGELOG.md).
+
+## Development and license
+
+```sh
+uv sync --python 3.13 --group dev
+uv run pytest -q
+```
+
+Tests that need a real analyzer need that analyzer configured. The product license is [MIT](https://github.com/zlxdengtianhei/codebase-explorer/blob/v2.2.0/LICENSE); external analyzers and grammar packages keep their own licenses.

codebase_explorer-2.2.0/README.md

@@ -0,0 +1,187 @@
+<h1 align="center"><img src="docs/media/logo.svg" width="40" height="40" alt="" align="absmiddle">&nbsp;Codebase Explorer</h1>
+<p align="center">Codebase Explorer turns a source repository into a one-page module map and per-module explanations that people and coding agents can read and query.</p>
+<p align="center"><b>English</b> | <a href="README.zh-CN.md">简体中文</a></p>
+<p align="center">
+<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+<a href="pyproject.toml"><img alt="Python 3.12 and 3.13" src="https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg"></a>
+<a href="https://github.com/zlxdengtianhei/codebase-explorer/actions/workflows/wheel-install.yml"><img alt="CI" src="https://github.com/zlxdengtianhei/codebase-explorer/actions/workflows/wheel-install.yml/badge.svg"></a>
+</p>
+
+https://github.com/user-attachments/assets/f0c3cc47-d0c2-4727-820e-65508c19408c
+
+<p align="center">Two minutes, narrated: Flask from its source files to the module map, the eight top-level modules, one module page, then <code>cbe find</code> and <code>cbe source</code>.<br><a href="https://zlxdengtianhei.github.io/codebase-explorer/?data=flask">Try the interactive map</a> · <a href="https://zlxdengtianhei.github.io/codebase-explorer/film.html">The same video with its transcript (English and Chinese)</a></p>
+
+A file tree shows where files are, not what each part is for. CBE (Codebase Explorer) reads a repository and writes what the tree lacks: one page that lists the whole module tree with a line on what each module is responsible for, and a page per module that explains each function and class and links to the exact source lines. You read it. A coding agent can look things up in it with three commands.
+
+**To try it:** `uv tool install codebase-explorer` (Python 3.12 or 3.13). Then generate inside Claude Code on your own subscription, or from the command line with any OpenAI-compatible endpoint (you name the model with `--model`). The steps are in [Quickstart](#quickstart).
+
+## What you get
+
+- **A one-page map.** `docs/INDEX.md` shows the whole module tree, one line per module. Its size is capped at the larger of 2,000 tokens and 3% of the source's token count.
+- **A tree without gaps, the same every time.** A program builds it: units that call or import each other, sit close together and use similar words are grouped. The same input gives the same tree. There are no empty nodes and no duplicate modules.
+- **A page per module.** Each unit has its signature, a source link, and an explanation written by a model. The explanations are written for people to read.
+- **Facts from commands, not from the model.** Signatures, calls and source lines come from `cbe find`, `cbe query` and `cbe source`. `cbe source` prints from the frozen snapshot and checks each file's SHA-256 against the digest recorded at freeze time before printing anything.
+
+The start of a real `docs/INDEX.md`, generated for flask (unedited):
+
+```markdown
+## Modules
+
+- [**Request Serving Application Runtime**](nodes/request-serving-application-runtime.md) — Combines the concrete WSGI Flask application with request and response wrappers, templating, context lifecycle, and view-facing helpers needed to serve live requests. (136 units; `flask/app.py`, `helpers.py`, `wrappers.py`)
+  - [**Request Helper Utilities and Tests**](nodes/request-helper-utilities-and-tests.md) — Provides view-facing helpers for files, flashing, redirects, streaming, and URL building, plus proxy globals and signal definitions, with focused behavioral tests. (42 units; `helpers.py`, `test_helpers.py`, `flask/blueprints.py`)
+    - [**Helpers, globals, and signals**](nodes/helpers-globals-and-signals.md) — Provides view-facing helpers for sending files, flashing messages, redirecting, streaming, and URL building, plus proxy globals and Flask's blinker signal definitions. (26 units; `helpers.py`, `flask/blueprints.py`, `globals.py`)
+    - [**Helper behavior tests**](nodes/helper-behavior-tests.md) — Verifies aborter selection and dispatch, app redirect delegation, open_resource read modes and encoding, and context-free redirect fallback behavior. (11 units; `test_helpers.py`)
+    - [**File and URL tests**](nodes/file-and-url-tests.md) — Tests custom URL converters, send_file family behavior with path-like objects, stream_with_context lifetime, and url_for inside request contexts. (5 units; `test_helpers.py`, `test_converters.py`)
+  - [**WSGI Request Dispatch Core**](nodes/wsgi-request-dispatch-core.md) — Implements the WSGI-callable Flask class and its pipeline: request entry, URL-to-view matching, response finalization, error handler resolution, and test and async wiring. (35 units; `flask/app.py`, `test_async.py`, `sansio/app.py`)
+```
+
+Full example: [flask](examples/flask/docs/INDEX.md). More in [Examples and docs](#examples-and-docs).
+
+## Quickstart
+
+CBE is on PyPI as `codebase-explorer`. It needs Python 3.12 or 3.13. There are two ways to run it. Both end in the same `docs/` folder. The usual one is A: your coding agent loads the skill and does the work on your own subscription. B is for scripts and batch runs.
+
+**A. The usual way: inside your coding agent, on your own subscription.** The steps below use Claude Code; the skill makes its subagents write the explanations.
+
+1. Install CBE: `uv tool install codebase-explorer` (or `pipx install codebase-explorer`).
+2. Optional, for the call graph: `cbe graph setup` downloads Joern and a Java runtime into your user cache directory (about 1.9 GB; Linux x86_64 and macOS).
+3. In your project, install the skill: `cbe-install install --host claude-code`.
+4. Start Claude Code there and ask: "Use the codebase-explorer skill to generate documentation for this repository."
+5. The agent prints the planned file, token, module and task counts, runs the subagents, and verifies the result.
+6. Open `<run_dir>/docs/INDEX.md`. The agent reports `run_dir`.
+
+Other agents load the same skill: `cbe-install install --host` takes `claude-code`, `opencode`, `pi`, `codex` and `dsh`. What has run end to end: Claude Code (see [What it costs](#what-it-costs)); OpenCode and Pi, once each on a 22-file sample repository (in the Pi run the tasks were handed to separate Pi sessions by a dispatch skill on our machine; Pi has no subagents of its own). `codex` and `dsh` install the skill, and we have not run them end to end. Details: [docs/running.md](docs/running.md#generate-through-a-host-agent).
+
+**B. For scripts and batch runs: from the command line, with any OpenAI-compatible endpoint.** There is no default model: you must pass `--model`.
+
+1. Install CBE as in step 1 above.
+2. Put the key in an environment variable: `export CBE_API_KEY=...`
+3. Optional: build the call graph (`cbe graph setup`, then `cbe graph build /abs/repo --output /abs/graph.json`).
+4. Generate. Paths must be absolute:
+
+   ```sh
+   cbe generate /abs/repo --model MODEL --base-url https://your-endpoint.example/v1 \
+     --api-key-env CBE_API_KEY --graph /abs/graph.json --run-dir /abs/run
+   ```
+
+5. Open `/abs/run/docs/INDEX.md`. Drop `--graph` to run without a call graph.
+
+Then look things up. `RUN` is the absolute run directory, and the ID is the second column of the `find` output:
+
+```sh
+cbe find   --run-dir "$RUN" --term url_for
+cbe query  --run-dir "$RUN" --id 'src/flask/helpers.py::function::url_for::6511'
+cbe source --run-dir "$RUN" --id 'src/flask/helpers.py::function::url_for::6511' --context 2
+```
+
+Every other command and option is in [docs/reference.md](docs/reference.md).
+
+## How it works
+
+```mermaid
+flowchart LR
+  A["Freeze the source"] --> B["Tree-sitter splits it at syntax boundaries"]
+  B --> C["Joern builds call and import graph (optional)"]
+  C --> D["Model explains each code unit"]
+  D --> E["Program groups units into a module tree"]
+  E --> F["Model names each module"]
+  F --> G["Render INDEX.md, module pages, catalog.json"]
+  classDef program fill:#dff7f3,stroke:#0f9b8e,color:#0f1b2d
+  classDef model fill:#fff0cc,stroke:#c98a00,color:#0f1b2d
+  class A,B,C,E,G program
+  class D,F model
+```
+
+Teal steps are ordinary code and make no model call. Amber steps are model calls.
+
+- **Freeze.** CBE keeps a hashed copy of the source, so every line number and quote can be checked later.
+- **Split.** Tree-sitter cuts each file at syntax boundaries. Every byte lands in some chunk.
+- **Explain.** The model writes the explanations batch by batch. It names symbols by the short numbers in a list, so it cannot invent an ID. The program asks again only for the symbols the model skipped.
+- **Check.** A second model reads one batch's source and checks its explanations against it: wrong behaviour, a wrong condition or error, or an explanation of the wrong symbol. It does not judge style. Findings are sent back for one rewrite. `--review` chooses how many batches are read: `none`; `sample` (the default: the largest batch, and every batch if that one has any finding); or `all`. On flask a sampled review was 14% of the run's input tokens; reading every batch adds about 80%. Where batches have many errors the rewrites cost more than the reading: on six examples whose sample had findings, reviewing every batch and rewriting the flagged ones added 51–176% to the run's input tokens and made its output tokens 4 to 10 times as large, because a flagged batch is written again in full. A clean sample leaves the other batches unread, so use `--review all` for a repository that matters. `RUN.md` says which batches were read and what was found. A rewrite after review, like any new run, can regroup the map: module pages and their names may change. Symbol IDs (`cbe find`, `cbe query`) depend only on the source, so link to code by ID, not by page name.
+- **Group.** The program, not the model, builds the module tree from calls and imports, location, and wording. The same input gives the same tree.
+- **Name.** The model gives each module a name, one line on what it is responsible for, and two or three sentences on how to read it. It cannot add, drop or move a node.
+- **Render.** The program writes `docs/INDEX.md`, one page per module, `DEPENDENCIES.md` and `RUN.md`, and the `catalog.json` that `find`, `query` and `source` read.
+
+## Code graph
+
+Without a graph, CBE still works. With one, the explanation tasks and the dependency view also get static import, call and control-flow evidence. The graph comes from [Joern](https://joern.io/), which needs Java 21 or newer. `cbe graph setup` downloads the pinned Joern and, if no suitable Java is found, a Java runtime into your user cache directory (about 1.9 GB in total). `cbe graph setup --check` downloads nothing and reports what is installed. `cbe graph build` then writes the graph file that `--graph` takes. It does not export dataflow unless you pass `--with-dataflow`, because a generation run does not read it and it was over half of the graph file on flask (23 of 41 MB). To install Joern by hand, see [docs/reference.md](docs/reference.md#optional-graph-analyzers).
+
+| Status | Languages | Conditions |
+|---|---|---|
+| Works on real repositories | C, C++, Python, JavaScript, TypeScript, Java, Go, Ruby | Python imports use Grimp (the `graphs` extra); JavaScript and TypeScript imports use dependency-cruiser (Node.js). Go calls across packages can stay unresolved. Ruby's dynamic dispatch can bind a call to a method of the same name on another class: CBE marks such calls ambiguous, and some wrong bindings remain. |
+| Needs an extra tool | Rust, PHP | Rust needs `cargo` and a Cargo project layout. PHP needs `php` (7 or later). |
+| Builds, calls partly resolved | C# | On a 55-file repository the graph builds (declarations, control flow, imports). Of its 2,322 calls, 689 resolve to one repository method and 394 to a set of overloads (Joern's C# frontend does not type arguments well enough to pick the overload); 246 point outside the repository and 993 stay unresolved. |
+| Fails on real repositories | Kotlin | Joern 4.0.654 failed on a 146-file Kotlin repository. Two-file examples work, so small inputs may succeed. |
+| Not tested | Swift, TSX | |
+
+`cbe languages` prints the same status for each language as `call_graph`. Source parsing and chunking work for every language in the table whatever the call-graph status is. Tree-sitter grammars for 13 languages come with the default install and two extras. More on analyzers and graph options: [docs/reference.md](docs/reference.md#optional-graph-analyzers).
+
+## What it costs
+
+Measured on flask, tests included: 65 files, 125k tokens. Model: GLM-5.3-Flash, called through `cbe generate`. One run to completion.
+
+| Measure | Reading |
+|---|---|
+| Prompt tokens | 3.2–3.4 times the source tokens |
+| Output tokens | about 0.9 times the source tokens |
+| Explanation text the model wrote | about 30% of the source tokens |
+| Prompt tokens spent on re-asks after a rejected answer | about 22% (43% before the answer-format change; that earlier run also stopped midway on upstream rate limiting) |
+
+These readings come from calls through an OpenAI-compatible gateway to GLM-5.3-Flash. CBE ships default settings (for example `reasoning_effort: low`) only for model names it knows. For any other model name, pass the settings you need with `--config`; [docs/running.md](docs/running.md#api-configuration-keys) lists every key.
+
+The host-agent path, measured once on flask's `src/` (24 files, about 75k tokens) with headless Claude Code (`claude -p`) and Sonnet subagents:
+
+| Measure | Reading |
+|---|---|
+| Subagent tasks | 8: 4 explanation batches, 1 sampled review, 2 tree-naming tasks, 1 overview. All were accepted on the first answer |
+| Wall clock | 293 seconds |
+| `cbe host verify` | all 15 checks passed |
+| Tokens | not collected for this run |
+
+Each table is one repository and one run. A host-agent run uses your subscription instead of an API key. Building the graph makes no model call. An older cost table for repositories up to 1.7 million tokens is in [docs/running.md](docs/running.md#what-a-run-costs-the-earlier-table); it was measured before the answer-format change, so do not compare it with the table above.
+
+## How well does it work
+
+What we measured, and what it shows. Everything here has conditions; the files in [`evaluation/tree/results/`](evaluation/tree/results/) hold the tables.
+
+The page you read first got smaller. Size of that page in `o200k_base` tokens, on three full runs (the earlier version's tree is in the "before" column):
+
+| Repository | Before | Now | Empty tree nodes before / now |
+|---|---:|---:|---:|
+| flask | 16,076 | 3,078 | 22 / 0 |
+| ruby_llm | 15,938 | 2,074 | 8 / 0 |
+| gson | 12,643 | 2,514 | 16 / 0 |
+
+- **Tree structure.** The new trees have no empty nodes and no duplicate modules on the three repositories above. The earlier trees had 22, 8 and 16 empty nodes.
+- **Call labels.** In seven repositories we took 10 edges of each status and checked them back against the source. For example, all 307 "unresolved" calls in cJSON were macros; they are no longer counted as calls. In fmt, "external" calls fell from 2,748 to 22.
+- **Does the tree help find the code to read?** We took 30 real commits from each of five repositories and asked three models which three modules to look at for the change. The new tree and the earlier tree could not be told apart. Against a plain directory listing, the module tree made no clear difference in repositories whose directories already have levels. It narrowed the reading only where directories are flat (flask, fmt): the three chosen modules held about 40% of the source and about 0.75–0.8 of the changed lines.
+- **How far to trust that ruler.** It is noisy: asked the same question again, the model gave an identical answer in only 9 to 23 of 30 cases.
+- **Earlier question-answering rounds** (CBE before the program-built tree). On flask and pytest (48 questions each), an agent with CBE documents and commands scored no differently from a source-only agent, and rarely ran the commands. One exploratory reading on curl scored higher with CBE (+5.60 rubric points, interval [+0.90, +10.82]) and comes with caveats listed in [evaluation/README.md](evaluation/README.md).
+
+What we do not claim: that grouping by function lets an agent locate code more accurately than a directory tree does, or that CBE improves an agent's answers. The measurements above do not show either.
+
+## Known limitations
+
+- The call graph needs Joern and Java 21 or newer. `cbe graph setup` downloads both (about 1.9 GB).
+- C# calls to overloaded methods resolve only to the set of overloads, and about 43% of the calls in the one real repository measured stay unresolved. Kotlin graphs fail on real repositories under the pinned Joern version; two-file examples work.
+- Ruby's dynamic dispatch can bind a call to the wrong class's method. CBE marks many of these as ambiguous, and some wrong bindings remain.
+- C and C++ files are not preprocessed. A header with many macros is cut into coarse chunks, and a macro can be taken for a function name.
+- A model writes the explanations. `cbe host verify` passing shows that the structure and references are consistent. It does not show that an explanation is correct. Check explanations against the source (`cbe source`).
+- There are no incremental updates: when the source changes, generate again.
+
+## Examples and docs
+
+- Generated documents: [flask](examples/flask/docs/INDEX.md), [cJSON](examples/cjson/), [fmt](examples/fmt/), [gson](examples/gson/), [ruby_llm](examples/ruby_llm/), [tsdown](examples/tsdown/), [polyglot](examples/polyglot/). Each example's README names the CBE commit that generated it; most were generated by an earlier version.
+- [docs/reference.md](docs/reference.md): install options, languages, graph analyzers, `find`, `query`, `source`, named declaration coverage.
+- [docs/running.md](docs/running.md): host-agent and API runs, the run directory, resume and verify, cost details, troubleshooting.
+- [docs/videos.md](docs/videos.md): walkthrough videos.
+- [evaluation/README.md](evaluation/README.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## Development and license
+
+```sh
+uv sync --python 3.13 --group dev
+uv run pytest -q
+```
+
+Tests that need a real analyzer need that analyzer configured. The product license is [MIT](LICENSE); external analyzers and grammar packages keep their own licenses.

codebase_explorer-2.2.0/plugin/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.

codebase_explorer-2.2.0/plugin/skills/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`.
+