codeterrain 0.3.0__tar.gz → 0.3.1__tar.gz

{codeterrain-0.3.0 → codeterrain-0.3.1}/AGENTS.md

@@ -1,8 +1,9 @@
 # codeterrain: instructions for coding agents and contributors
 
-codeterrain is a local, LLM-free, network-free command line tool (`terrain`) that answers questions about
-a repository's code from a cache, in under a second. Python first: pytest fixture order, FastAPI routes,
-definitions and references; plus the HTTP calls of a JavaScript or TypeScript front end. See
+codeterrain is a local, LLM-free, network-free command line tool (`codeterrain`, also installed as
+`terrain`) that answers questions about a repository's code from a cache, in under a second. Python
+first: pytest fixture order, FastAPI routes, definitions and references; plus the HTTP calls of a
+JavaScript or TypeScript front end. See
 [README.md](README.md) for what it does and [docs/extractor-protocol.md](docs/extractor-protocol.md) for
 the extractor protocol.
 

{codeterrain-0.3.0 → codeterrain-0.3.1}/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
-## 0.3.0 (unreleased)
+## 0.3.1 (2026-11-02)
+
+- The README's diagram of how it works is an image, as the charts are: PyPI does not render
+  Mermaid, so the 0.3.0 page showed its source.
+- `codeterrain` is the command the docs use; `terrain` stays installed as a shorter name. Another
+  tool on PyPI installs a `terrain` command, and with both installed the last one wins.
+- `codeterrain-terraform` 0.2.1 and `codeterrain-typescript` 0.1.1: their READMEs, which are their
+  PyPI pages, install from PyPI instead of saying the packs are not published. No code change.
+- The README leads with `uv tool install codeterrain` from PyPI, and has a starting point for an
+  agent's instructions. Its claims are narrowed to what is measured: no "exact answers" headline;
+  `impact` lists the tests that statically reach a name, not the tests that would catch a change;
+  character counts measure an answer, not a session; the import tier's safeguards stop accidents,
+  not hostile code, so it is for code you trust. The field figures cover all 160 logged lookups,
+  with their period and how they were judged, two marked wrong among them.
+- SECURITY.md and the rationale no longer describe the repository as private or a public release
+  as future work. SECURITY.md's third guarantee says what it covers: pytest and its known plugins
+  do not write into the repository by default; target code that opens a file by absolute path still
+  can.
+- A prior-art page, `docs/prior-art.md`: what twelve comparable tools document answering, read from
+  their READMEs, with a chart. None documents pytest fixture resolution, front-end calls matched to
+  routes, or routes read from the application. It is a reading of their docs, not a benchmark.
+
+## 0.3.0 (2026-11-02)
 
 - `terrain refs` following an alias counts a read after an assignment on the same line
   (`ALIAS = VALUE; print(ALIAS)`), and still not one inside the assignment's right-hand side.

{codeterrain-0.3.0 → codeterrain-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeterrain
-Version: 0.3.0
+Version: 0.3.1
 Summary: terrain: answers about your code in under a second. Local, LLM-free structure facts for coding agents; Python first.
 Project-URL: Homepage, https://github.com/benchli-sports/codeterrain
 Project-URL: Issues, https://github.com/benchli-sports/codeterrain/issues
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 <h1 align="center">codeterrain</h1>
 
 <p align="center">
-  <b><code>terrain</code>: exact answers about your code, in under a second.</b><br>
+  <b><code>codeterrain</code>: answers about your code, in under a second.</b><br>
   For coding agents, and the people working beside them.
 </p>
 
@@ -63,34 +63,40 @@ Description-Content-Type: text/markdown
 ---
 
 A coding agent spends most of its reading on structure it has to rediscover every session: which
-fixtures a test really gets, where a route is handled, who calls a function, which tests would catch a
-change to it. The answers are in the code, but finding them takes rounds of grep and file reads, and a
+fixtures a test really gets, where a route is handled, who calls a function, which tests reach
+it. The answers are in the code, but finding them takes rounds of grep and file reads, and a
 wrong guess costs a review round.
 
-`terrain` answers those questions from a cache, the way the framework itself would answer them.
+`codeterrain` answers those questions from a cache, the way the framework itself would answer them.
 
 | | |
 |:---|:---|
-| **Exact** | Setup order equals `pytest --setup-plan` on every node tested. `refs` follows imports and re-exports, so an alias counts and a same-named function elsewhere does not. |
+| **Accurate where it counts** | Setup order and routes come from pytest and FastAPI themselves: setup order equals `pytest --setup-plan` on every node tested. `refs`, `def` and `impact` read the code statically: they follow imports and re-exports, so an alias counts and a same-named function elsewhere does not, and a name whose meaning depends on run time is left unresolved rather than guessed ([limits](docs/limits.md)). |
 | **Fast** | Most warm answers take 0.3 to 0.5 s on a large backend, Python start-up included. |
-| **Cheaper to read** | 4.4x to 8.8x fewer characters than the grep-and-read it replaces, on code bases with a real fixture graph. |
-| **Safe to point at a repo** | The static tier never runs the target's code. The tier that has to import it runs in a sandbox with no credentials, and by default it cannot write into the repository. |
+| **Shorter to read** | 4.4x to 8.8x fewer characters than the grep-and-read it replaces, on code bases with a real fixture graph. That measures the answer, not a whole session's tokens, cost or time. |
+| **Careful with your repo** | The static tier never runs the target's code. Setup order and routes have to import it: they run in a subprocess with an allowlisted environment, dummy cloud credentials and a best-effort network guard, which stop accidents, not hostile code. Run those two on code you trust ([SECURITY.md](SECURITY.md)). |
 
 ## Quick start
 
 ```sh
-uv tool install <path-to-this-checkout>     # Python 3.12+; the only dependency is pluggy
-# or "<path-to-this-checkout>[terraform]" to add the Terraform language pack, "[typescript]"
-# to read front-end calls with tree-sitter, "[terraform,typescript]" for both
+uv tool install codeterrain     # Python 3.12+; the only dependency is pluggy
+# or "codeterrain[terraform]" to add the Terraform language pack, "codeterrain[typescript]"
+# to read front-end calls with tree-sitter, "codeterrain[terraform,typescript]" for both
 cd your-repo
-terrain doctor                              # what it found, and which config it used
+codeterrain doctor              # what it found, and which config it used
+codeterrain fixtures            # every pytest fixture, and which definition wins where
 ```
 
+The same command is also installed as `terrain`, a shorter name. Another tool on PyPI installs a
+`terrain` command too; with both installed, the last one wins, while `codeterrain` is always this
+one. To work on codeterrain itself, install from a checkout instead:
+`uv tool install --editable <path-to-checkout>`.
+
 Ask about a function: where it is called, how each call passes its arguments, and which tests patch it.
-This is `terrain` run on its own source:
+This is `codeterrain` run on its own source:
 
 ```console
-$ terrain refs is_test_module
+$ codeterrain refs is_test_module
 function codeterrain.fixtures_static.is_test_module(rel)  src/codeterrain/fixtures_static.py:327
 6 calls (6 in code, 0 in tests), 0 with a shape problem, 0 used as a value, 0 patched
 file:line                                 in                             shape         note
@@ -102,11 +108,12 @@ src/codeterrain/impact.py:272             _Fixtures.__init__             1 posit
 src/codeterrain/impact.py:424             _inherited_tests               1 positional
 ```
 
-Ask which tests would catch a change to it, through its callers and the fixtures that call them
-(abridged):
+Ask which tests statically reach it, through its callers and the fixtures that call them
+(abridged). A test that reaches a function does not necessarily check what you change, and an
+empty list does not prove the change is untested:
 
 ```console
-$ terrain impact is_test_module --depth 2
+$ codeterrain impact is_test_module --depth 2
 17 tests reach codeterrain.fixtures_static.is_test_module (0 directly), through 15 callers within 2 levels; 2 tests patch it …
 test                                                 depth  how                               via
 tests/test_cli.py::test_a_handler_is_matched_by_…    2      call at tests/test_cli.py:1186    …update <- …is_test_module
@@ -117,7 +124,7 @@ tests/test_cli.py::test_a_route_text_that_matches_…  2      call at tests/test
 Ask what a fixture is and what depends on it (from the sample repository in `tests/sample_repo`):
 
 ```console
-$ terrain fixture db
+$ codeterrain fixture db
 name: db
 scope: session
 autouse: no
@@ -137,21 +144,44 @@ The commands that import your application (`setup-order`, `routes`) run in the *
 interpreter: pass `--python .venv/bin/python` or set `CODETERRAIN_PYTHON`. Add `--json` to any command
 for the full data.
 
+## Telling your agent
+
+An agent uses `codeterrain` when its instructions say when to. A starting point for `AGENTS.md` or
+`CLAUDE.md`:
+
+```markdown
+## Code structure: ask codeterrain first
+
+Before grepping or reading files for one of these, run `codeterrain` in the repository root
+(local, under a second when warm; add `--json` for the full data):
+
+- where a name is defined: `codeterrain def NAME`
+- who calls, passes or patches it: `codeterrain refs NAME`
+- which tests statically reach it: `codeterrain impact NAME` (a starting point, not proof of coverage)
+- which fixtures a test gets, in order: `codeterrain setup-order NODEID`
+- a fixture and what depends on it: `codeterrain fixture NAME`
+- where a route is handled: `codeterrain route METHOD PATH`
+- a front end's HTTP calls, and the backend routes they hit: `codeterrain calls`, `codeterrain callers`
+
+When codeterrain says it cannot resolve something, fall back to grep. `setup-order` and the route
+commands import the code: use them only on code you trust.
+```
+
 ## What it answers
 
 | Question | Command | What grep can't tell you |
 |:---|:---|:---|
-| Where is this defined? | `terrain def NAME` | Resolves a re-export to the real definition |
-| Who calls it, passes it, patches it? | `terrain refs NAME` | Follows imports and aliases, flags calls that don't fit the signature, and separates tests that patch it out |
-| Who imports this module, and what does it import? | `terrain importers MODULE`, `terrain imports MODULE` | Every import of it or of a name from it, relative imports resolved |
-| Which tests would catch a change? | `terrain impact NAME` | Walks callers and fixtures the way pytest resolves them |
-| Which fixtures does a test get, in what order? | `terrain setup-order NODEID` | pytest's own resolution, overrides and scopes included |
-| What fixtures exist, and who uses one? | `terrain fixtures`, `terrain fixture NAME` | Which definition wins where, and every dependent |
-| Where is a route handled, with what access? | `terrain routes`, `terrain route METHOD PATH` | Prefixes from router calls in other files, joined to your access manifest |
-| Which HTTP calls does a front end make? | `terrain calls` | Paths built from templates, constants and concatenation |
-| Which backend route does each call hit? | `terrain callers` | Front-end calls matched to backend routes across repositories |
-| Where is a Terraform resource, variable or module, and who reads it? | `terrain def NAME`, `terrain refs NAME` (Terraform pack) | Terraform's own names (`aws_s3_bucket.logs`, `var.region`, `module.vpc`) and the block each reference sits in |
-| What is the module tree, and which providers are pinned? | `terrain def --kind module`, `terrain def --kind required_provider` | Every module call with its source and version; provider aliases and what selects them |
+| Where is this defined? | `codeterrain def NAME` | Resolves a re-export to the real definition |
+| Who calls it, passes it, patches it? | `codeterrain refs NAME` | Follows imports and aliases, flags calls that don't fit the signature, and separates tests that patch it out |
+| Who imports this module, and what does it import? | `codeterrain importers MODULE`, `codeterrain imports MODULE` | Every import of it or of a name from it, relative imports resolved |
+| Which tests statically reach it? | `codeterrain impact NAME` | Walks callers and fixtures the way pytest resolves them; what it cannot follow statically is listed, not dropped |
+| Which fixtures does a test get, in what order? | `codeterrain setup-order NODEID` | pytest's own resolution, overrides and scopes included |
+| What fixtures exist, and who uses one? | `codeterrain fixtures`, `codeterrain fixture NAME` | Which definition wins where, and every dependent |
+| Where is a route handled, with what access? | `codeterrain routes`, `codeterrain route METHOD PATH` | Prefixes from router calls in other files, joined to your access manifest |
+| Which HTTP calls does a front end make? | `codeterrain calls` | Paths built from templates, constants and concatenation |
+| Which backend route does each call hit? | `codeterrain callers` | Front-end calls matched to backend routes across repositories |
+| Where is a Terraform resource, variable or module, and who reads it? | `codeterrain def NAME`, `codeterrain refs NAME` (Terraform pack) | Terraform's own names (`aws_s3_bucket.logs`, `var.region`, `module.vpc`) and the block each reference sits in |
+| What is the module tree, and which providers are pinned? | `codeterrain def --kind module`, `codeterrain def --kind required_provider` | Every module call with its source and version; provider aliases and what selects them |
 
 Every option is in **[docs/commands.md](docs/commands.md)**.
 
@@ -165,7 +195,7 @@ smaller Python code bases, an analytics project with a large fixture graph, and
 <td align="center" width="25%"><h2>11 / 11</h2>test nodes where setup order equals <code>pytest --setup-plan</code></td>
 <td align="center" width="25%"><h2>0.35 s</h2>median warm <code>fixtures</code> answer on the large backend</td>
 <td align="center" width="25%"><h2>up to 8.8x</h2>fewer characters for an agent to read</td>
-<td align="center" width="25%"><h2>0</h2>answers marked wrong in agents' logged lookups</td>
+<td align="center" width="25%"><h2>160</h2>field lookups logged by coding agents; agent-assessed, not independently validated</td>
 </tr>
 </table>
 
@@ -195,18 +225,27 @@ than the grep; there the gain is the exact order, which grep can't show.
 
 ### In the field
 
-Coding agents working on real tasks logged each `terrain` lookup: what they asked, whether the answer
-was right, and what they would have done instead.
+Coding agents working on real tasks logged each `codeterrain` lookup: what they asked, whether the answer
+was right, and what they would have done instead. 160 lookups, 26 October to 2 November 2026, across
+the code bases above. Each agent judged its own answer against what it then read or ran; nobody
+checked the judgements independently. Every lookup has one outcome; the shares are rounded, so they
+can add up to 101%.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/field-dark.svg">
-  <img src="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/field-light.svg" alt="Outcomes of logged lookups: answered 79%, partly answered 12%, no help 2%, error 7% (mostly the wrong command), wrong answer 0%" width="760">
+  <img src="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/field-light.svg" alt="Outcomes of 160 lookups agents logged from 26 October to 2 November 2026, one outcome each, as they judged them: answered 118 (74%), partly answered 16 (10%), no help 12 (8%), error 12 (8%, mostly the wrong command), wrong answer 2 (1%)" width="760">
 </picture>
 
-- Each fully answered lookup saved the agent **about 1.3 tool calls**, by its own count.
-- **No answer was marked wrong.** The partial answers came from output cut by the token budget, a cache
-  built from a different checkout than the one being edited, and a value read through a module alias.
-- Most errors were the wrong command: `callers`, which is for routes, where `refs` was meant.
+- Each fully answered lookup saved the agent **about 1.8 tool calls**, by its own count.
+- **Two answers were marked wrong.** In one, `fixture` answered a fixture of a live-test folder it
+  did not read with a unit-test fixture of the same name; `fixtures`, `fixture` and `doctor` now name
+  such a folder. The other, `routes` missing an app's support routes, was misjudged: a later lookup
+  found them in the view, below the token budget's cut, whose "more" notice a `grep` had removed.
+- The partial answers came mostly from output cut by the token budget; the rest from a cache built
+  from a different checkout than the one being edited, reads `refs` does not see (through a module
+  alias, as a dict key), duck-typed calls, and route filters that matched less than expected.
+- Most errors were the wrong command or arguments: `callers`, which is for routes, where `refs` was
+  meant.
 
 ## Inferred token savings
 
@@ -214,41 +253,30 @@ An estimate from the two measurements above, not an A/B experiment:
 
 | Step | Figure |
 |:---|---:|
-| Reading saved on a question `terrain` answers, large backend (4.4x to 6.9x fewer characters) | 77% to 86% |
-| Lookups answered fully, in the field | 79% |
-| Lookups answered partly (counted at half the saving) | 12% |
-| **Inferred share of lookup reading saved on a large Python backend** | **about 65% to 73%** |
+| Reading saved on a question `codeterrain` answers, large backend (4.4x to 6.9x fewer characters) | 77% to 86% |
+| Lookups answered fully, in the field | 74% |
+| Lookups answered partly (counted at half the saving) | 10% |
+| **Inferred share of lookup reading saved on a large Python backend** | **about 61% to 68%** |
 
 Lookups are only part of a session: reasoning, editing and test runs are untouched, and small code
 bases save little. Tokens here are characters divided by four. A session-level A/B, the same lane run
-with and without `terrain`, is the next measurement. The method and the per-repository results are in
+with and without `codeterrain`, is the next measurement. The method and the per-repository results are in
 [docs/why-codeterrain.md](docs/why-codeterrain.md).
 
 ## How it works
 
-```mermaid
-flowchart LR
-    ask(["agent or you: terrain refs NAME"]) --> cache[("cache per repository,<br/>keyed on content")]
-    cache -->|warm| answer(["answer in under a second"])
-    subgraph static ["Static tier: reads files, never runs them"]
-        fixtures["fixtures and tests<br/>(ast)"]
-        code["code index<br/>(ast, SQLite)"]
-        calls["front-end HTTP calls<br/>(tree-sitter, or the JS/TS tokenizer)"]
-    end
-    subgraph sandbox ["Import tier: sandboxed subprocess"]
-        order["setup order<br/>(pytest --collect-only)"]
-        routes["routes<br/>(imports the apps)"]
-    end
-    static -->|incremental, changed files only| cache
-    sandbox -->|on refresh; served stamped stale| cache
-```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/architecture-dark.svg">
+  <img src="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/architecture-light.svg" alt="How it works: a codeterrain question is answered from a cache per repository, keyed on content, in under a second when warm. The static tier (fixtures and tests and the code index with Python's ast, front-end calls with tree-sitter or a tokenizer) fills it from changed files only and never runs the code. The import tier runs the code in a guarded subprocess and fills it on refresh with the setup order and the routes." width="760">
+</picture>
 
 - **The static tier** reads source with Python's `ast`, and front-end files with tree-sitter when the
   TypeScript pack is installed (chosen for speed and accuracy) or a tokenizer written in Python when
   it is not. It never imports or runs the target, and re-reads only the files that changed.
 - **The import tier** needs the real framework: pytest's fixture resolution, FastAPI's route table. It
   runs in a subprocess using the target's own interpreter, with an allowlisted environment, dummy cloud
-  credentials, no proxy and a best-effort network guard.
+  credentials, no proxy and a best-effort network guard. Those stop accidents, not hostile code: it
+  imports and runs the target, so use it on code you trust.
 - **The cache** lives outside the checkout, in the git common directory or your user cache, and is
   keyed on content hashes.
 
@@ -279,6 +307,7 @@ knowledge-graph tool, are in [docs/why-codeterrain.md](docs/why-codeterrain.md).
 | [TypeScript pack](packages/codeterrain-typescript/README.md) | Front-end calls read with tree-sitter, and why it is the reader to install |
 | [Design notes](docs/design-v0.2.md) | The decisions behind the front-end calls and the language packs |
 | [Why codeterrain](docs/why-codeterrain.md) | The origin, the measurements, what is not proven yet |
+| [Prior art](docs/prior-art.md) | What twelve comparable tools document answering, read from their docs |
 | [Changelog](CHANGELOG.md) | What changed, release by release |
 
 ## Development

{codeterrain-0.3.0 → codeterrain-0.3.1}/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">codeterrain</h1>
 
 <p align="center">
-  <b><code>terrain</code>: exact answers about your code, in under a second.</b><br>
+  <b><code>codeterrain</code>: answers about your code, in under a second.</b><br>
   For coding agents, and the people working beside them.
 </p>
 
@@ -25,34 +25,40 @@
 ---
 
 A coding agent spends most of its reading on structure it has to rediscover every session: which
-fixtures a test really gets, where a route is handled, who calls a function, which tests would catch a
-change to it. The answers are in the code, but finding them takes rounds of grep and file reads, and a
+fixtures a test really gets, where a route is handled, who calls a function, which tests reach
+it. The answers are in the code, but finding them takes rounds of grep and file reads, and a
 wrong guess costs a review round.
 
-`terrain` answers those questions from a cache, the way the framework itself would answer them.
+`codeterrain` answers those questions from a cache, the way the framework itself would answer them.
 
 | | |
 |:---|:---|
-| **Exact** | Setup order equals `pytest --setup-plan` on every node tested. `refs` follows imports and re-exports, so an alias counts and a same-named function elsewhere does not. |
+| **Accurate where it counts** | Setup order and routes come from pytest and FastAPI themselves: setup order equals `pytest --setup-plan` on every node tested. `refs`, `def` and `impact` read the code statically: they follow imports and re-exports, so an alias counts and a same-named function elsewhere does not, and a name whose meaning depends on run time is left unresolved rather than guessed ([limits](docs/limits.md)). |
 | **Fast** | Most warm answers take 0.3 to 0.5 s on a large backend, Python start-up included. |
-| **Cheaper to read** | 4.4x to 8.8x fewer characters than the grep-and-read it replaces, on code bases with a real fixture graph. |
-| **Safe to point at a repo** | The static tier never runs the target's code. The tier that has to import it runs in a sandbox with no credentials, and by default it cannot write into the repository. |
+| **Shorter to read** | 4.4x to 8.8x fewer characters than the grep-and-read it replaces, on code bases with a real fixture graph. That measures the answer, not a whole session's tokens, cost or time. |
+| **Careful with your repo** | The static tier never runs the target's code. Setup order and routes have to import it: they run in a subprocess with an allowlisted environment, dummy cloud credentials and a best-effort network guard, which stop accidents, not hostile code. Run those two on code you trust ([SECURITY.md](SECURITY.md)). |
 
 ## Quick start
 
 ```sh
-uv tool install <path-to-this-checkout>     # Python 3.12+; the only dependency is pluggy
-# or "<path-to-this-checkout>[terraform]" to add the Terraform language pack, "[typescript]"
-# to read front-end calls with tree-sitter, "[terraform,typescript]" for both
+uv tool install codeterrain     # Python 3.12+; the only dependency is pluggy
+# or "codeterrain[terraform]" to add the Terraform language pack, "codeterrain[typescript]"
+# to read front-end calls with tree-sitter, "codeterrain[terraform,typescript]" for both
 cd your-repo
-terrain doctor                              # what it found, and which config it used
+codeterrain doctor              # what it found, and which config it used
+codeterrain fixtures            # every pytest fixture, and which definition wins where
 ```
 
+The same command is also installed as `terrain`, a shorter name. Another tool on PyPI installs a
+`terrain` command too; with both installed, the last one wins, while `codeterrain` is always this
+one. To work on codeterrain itself, install from a checkout instead:
+`uv tool install --editable <path-to-checkout>`.
+
 Ask about a function: where it is called, how each call passes its arguments, and which tests patch it.
-This is `terrain` run on its own source:
+This is `codeterrain` run on its own source:
 
 ```console
-$ terrain refs is_test_module
+$ codeterrain refs is_test_module
 function codeterrain.fixtures_static.is_test_module(rel)  src/codeterrain/fixtures_static.py:327
 6 calls (6 in code, 0 in tests), 0 with a shape problem, 0 used as a value, 0 patched
 file:line                                 in                             shape         note
@@ -64,11 +70,12 @@ src/codeterrain/impact.py:272             _Fixtures.__init__             1 posit
 src/codeterrain/impact.py:424             _inherited_tests               1 positional
 ```
 
-Ask which tests would catch a change to it, through its callers and the fixtures that call them
-(abridged):
+Ask which tests statically reach it, through its callers and the fixtures that call them
+(abridged). A test that reaches a function does not necessarily check what you change, and an
+empty list does not prove the change is untested:
 
 ```console
-$ terrain impact is_test_module --depth 2
+$ codeterrain impact is_test_module --depth 2
 17 tests reach codeterrain.fixtures_static.is_test_module (0 directly), through 15 callers within 2 levels; 2 tests patch it …
 test                                                 depth  how                               via
 tests/test_cli.py::test_a_handler_is_matched_by_…    2      call at tests/test_cli.py:1186    …update <- …is_test_module
@@ -79,7 +86,7 @@ tests/test_cli.py::test_a_route_text_that_matches_…  2      call at tests/test
 Ask what a fixture is and what depends on it (from the sample repository in `tests/sample_repo`):
 
 ```console
-$ terrain fixture db
+$ codeterrain fixture db
 name: db
 scope: session
 autouse: no
@@ -99,21 +106,44 @@ The commands that import your application (`setup-order`, `routes`) run in the *
 interpreter: pass `--python .venv/bin/python` or set `CODETERRAIN_PYTHON`. Add `--json` to any command
 for the full data.
 
+## Telling your agent
+
+An agent uses `codeterrain` when its instructions say when to. A starting point for `AGENTS.md` or
+`CLAUDE.md`:
+
+```markdown
+## Code structure: ask codeterrain first
+
+Before grepping or reading files for one of these, run `codeterrain` in the repository root
+(local, under a second when warm; add `--json` for the full data):
+
+- where a name is defined: `codeterrain def NAME`
+- who calls, passes or patches it: `codeterrain refs NAME`
+- which tests statically reach it: `codeterrain impact NAME` (a starting point, not proof of coverage)
+- which fixtures a test gets, in order: `codeterrain setup-order NODEID`
+- a fixture and what depends on it: `codeterrain fixture NAME`
+- where a route is handled: `codeterrain route METHOD PATH`
+- a front end's HTTP calls, and the backend routes they hit: `codeterrain calls`, `codeterrain callers`
+
+When codeterrain says it cannot resolve something, fall back to grep. `setup-order` and the route
+commands import the code: use them only on code you trust.
+```
+
 ## What it answers
 
 | Question | Command | What grep can't tell you |
 |:---|:---|:---|
-| Where is this defined? | `terrain def NAME` | Resolves a re-export to the real definition |
-| Who calls it, passes it, patches it? | `terrain refs NAME` | Follows imports and aliases, flags calls that don't fit the signature, and separates tests that patch it out |
-| Who imports this module, and what does it import? | `terrain importers MODULE`, `terrain imports MODULE` | Every import of it or of a name from it, relative imports resolved |
-| Which tests would catch a change? | `terrain impact NAME` | Walks callers and fixtures the way pytest resolves them |
-| Which fixtures does a test get, in what order? | `terrain setup-order NODEID` | pytest's own resolution, overrides and scopes included |
-| What fixtures exist, and who uses one? | `terrain fixtures`, `terrain fixture NAME` | Which definition wins where, and every dependent |
-| Where is a route handled, with what access? | `terrain routes`, `terrain route METHOD PATH` | Prefixes from router calls in other files, joined to your access manifest |
-| Which HTTP calls does a front end make? | `terrain calls` | Paths built from templates, constants and concatenation |
-| Which backend route does each call hit? | `terrain callers` | Front-end calls matched to backend routes across repositories |
-| Where is a Terraform resource, variable or module, and who reads it? | `terrain def NAME`, `terrain refs NAME` (Terraform pack) | Terraform's own names (`aws_s3_bucket.logs`, `var.region`, `module.vpc`) and the block each reference sits in |
-| What is the module tree, and which providers are pinned? | `terrain def --kind module`, `terrain def --kind required_provider` | Every module call with its source and version; provider aliases and what selects them |
+| Where is this defined? | `codeterrain def NAME` | Resolves a re-export to the real definition |
+| Who calls it, passes it, patches it? | `codeterrain refs NAME` | Follows imports and aliases, flags calls that don't fit the signature, and separates tests that patch it out |
+| Who imports this module, and what does it import? | `codeterrain importers MODULE`, `codeterrain imports MODULE` | Every import of it or of a name from it, relative imports resolved |
+| Which tests statically reach it? | `codeterrain impact NAME` | Walks callers and fixtures the way pytest resolves them; what it cannot follow statically is listed, not dropped |
+| Which fixtures does a test get, in what order? | `codeterrain setup-order NODEID` | pytest's own resolution, overrides and scopes included |
+| What fixtures exist, and who uses one? | `codeterrain fixtures`, `codeterrain fixture NAME` | Which definition wins where, and every dependent |
+| Where is a route handled, with what access? | `codeterrain routes`, `codeterrain route METHOD PATH` | Prefixes from router calls in other files, joined to your access manifest |
+| Which HTTP calls does a front end make? | `codeterrain calls` | Paths built from templates, constants and concatenation |
+| Which backend route does each call hit? | `codeterrain callers` | Front-end calls matched to backend routes across repositories |
+| Where is a Terraform resource, variable or module, and who reads it? | `codeterrain def NAME`, `codeterrain refs NAME` (Terraform pack) | Terraform's own names (`aws_s3_bucket.logs`, `var.region`, `module.vpc`) and the block each reference sits in |
+| What is the module tree, and which providers are pinned? | `codeterrain def --kind module`, `codeterrain def --kind required_provider` | Every module call with its source and version; provider aliases and what selects them |
 
 Every option is in **[docs/commands.md](docs/commands.md)**.
 
@@ -127,7 +157,7 @@ smaller Python code bases, an analytics project with a large fixture graph, and
 <td align="center" width="25%"><h2>11 / 11</h2>test nodes where setup order equals <code>pytest --setup-plan</code></td>
 <td align="center" width="25%"><h2>0.35 s</h2>median warm <code>fixtures</code> answer on the large backend</td>
 <td align="center" width="25%"><h2>up to 8.8x</h2>fewer characters for an agent to read</td>
-<td align="center" width="25%"><h2>0</h2>answers marked wrong in agents' logged lookups</td>
+<td align="center" width="25%"><h2>160</h2>field lookups logged by coding agents; agent-assessed, not independently validated</td>
 </tr>
 </table>
 
@@ -157,18 +187,27 @@ than the grep; there the gain is the exact order, which grep can't show.
 
 ### In the field
 
-Coding agents working on real tasks logged each `terrain` lookup: what they asked, whether the answer
-was right, and what they would have done instead.
+Coding agents working on real tasks logged each `codeterrain` lookup: what they asked, whether the answer
+was right, and what they would have done instead. 160 lookups, 26 October to 2 November 2026, across
+the code bases above. Each agent judged its own answer against what it then read or ran; nobody
+checked the judgements independently. Every lookup has one outcome; the shares are rounded, so they
+can add up to 101%.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/field-dark.svg">
-  <img src="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/field-light.svg" alt="Outcomes of logged lookups: answered 79%, partly answered 12%, no help 2%, error 7% (mostly the wrong command), wrong answer 0%" width="760">
+  <img src="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/field-light.svg" alt="Outcomes of 160 lookups agents logged from 26 October to 2 November 2026, one outcome each, as they judged them: answered 118 (74%), partly answered 16 (10%), no help 12 (8%), error 12 (8%, mostly the wrong command), wrong answer 2 (1%)" width="760">
 </picture>
 
-- Each fully answered lookup saved the agent **about 1.3 tool calls**, by its own count.
-- **No answer was marked wrong.** The partial answers came from output cut by the token budget, a cache
-  built from a different checkout than the one being edited, and a value read through a module alias.
-- Most errors were the wrong command: `callers`, which is for routes, where `refs` was meant.
+- Each fully answered lookup saved the agent **about 1.8 tool calls**, by its own count.
+- **Two answers were marked wrong.** In one, `fixture` answered a fixture of a live-test folder it
+  did not read with a unit-test fixture of the same name; `fixtures`, `fixture` and `doctor` now name
+  such a folder. The other, `routes` missing an app's support routes, was misjudged: a later lookup
+  found them in the view, below the token budget's cut, whose "more" notice a `grep` had removed.
+- The partial answers came mostly from output cut by the token budget; the rest from a cache built
+  from a different checkout than the one being edited, reads `refs` does not see (through a module
+  alias, as a dict key), duck-typed calls, and route filters that matched less than expected.
+- Most errors were the wrong command or arguments: `callers`, which is for routes, where `refs` was
+  meant.
 
 ## Inferred token savings
 
@@ -176,41 +215,30 @@ An estimate from the two measurements above, not an A/B experiment:
 
 | Step | Figure |
 |:---|---:|
-| Reading saved on a question `terrain` answers, large backend (4.4x to 6.9x fewer characters) | 77% to 86% |
-| Lookups answered fully, in the field | 79% |
-| Lookups answered partly (counted at half the saving) | 12% |
-| **Inferred share of lookup reading saved on a large Python backend** | **about 65% to 73%** |
+| Reading saved on a question `codeterrain` answers, large backend (4.4x to 6.9x fewer characters) | 77% to 86% |
+| Lookups answered fully, in the field | 74% |
+| Lookups answered partly (counted at half the saving) | 10% |
+| **Inferred share of lookup reading saved on a large Python backend** | **about 61% to 68%** |
 
 Lookups are only part of a session: reasoning, editing and test runs are untouched, and small code
 bases save little. Tokens here are characters divided by four. A session-level A/B, the same lane run
-with and without `terrain`, is the next measurement. The method and the per-repository results are in
+with and without `codeterrain`, is the next measurement. The method and the per-repository results are in
 [docs/why-codeterrain.md](docs/why-codeterrain.md).
 
 ## How it works
 
-```mermaid
-flowchart LR
-    ask(["agent or you: terrain refs NAME"]) --> cache[("cache per repository,<br/>keyed on content")]
-    cache -->|warm| answer(["answer in under a second"])
-    subgraph static ["Static tier: reads files, never runs them"]
-        fixtures["fixtures and tests<br/>(ast)"]
-        code["code index<br/>(ast, SQLite)"]
-        calls["front-end HTTP calls<br/>(tree-sitter, or the JS/TS tokenizer)"]
-    end
-    subgraph sandbox ["Import tier: sandboxed subprocess"]
-        order["setup order<br/>(pytest --collect-only)"]
-        routes["routes<br/>(imports the apps)"]
-    end
-    static -->|incremental, changed files only| cache
-    sandbox -->|on refresh; served stamped stale| cache
-```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/architecture-dark.svg">
+  <img src="https://raw.githubusercontent.com/benchli-sports/codeterrain/main/docs/img/architecture-light.svg" alt="How it works: a codeterrain question is answered from a cache per repository, keyed on content, in under a second when warm. The static tier (fixtures and tests and the code index with Python's ast, front-end calls with tree-sitter or a tokenizer) fills it from changed files only and never runs the code. The import tier runs the code in a guarded subprocess and fills it on refresh with the setup order and the routes." width="760">
+</picture>
 
 - **The static tier** reads source with Python's `ast`, and front-end files with tree-sitter when the
   TypeScript pack is installed (chosen for speed and accuracy) or a tokenizer written in Python when
   it is not. It never imports or runs the target, and re-reads only the files that changed.
 - **The import tier** needs the real framework: pytest's fixture resolution, FastAPI's route table. It
   runs in a subprocess using the target's own interpreter, with an allowlisted environment, dummy cloud
-  credentials, no proxy and a best-effort network guard.
+  credentials, no proxy and a best-effort network guard. Those stop accidents, not hostile code: it
+  imports and runs the target, so use it on code you trust.
 - **The cache** lives outside the checkout, in the git common directory or your user cache, and is
   keyed on content hashes.
 
@@ -241,6 +269,7 @@ knowledge-graph tool, are in [docs/why-codeterrain.md](docs/why-codeterrain.md).
 | [TypeScript pack](packages/codeterrain-typescript/README.md) | Front-end calls read with tree-sitter, and why it is the reader to install |
 | [Design notes](docs/design-v0.2.md) | The decisions behind the front-end calls and the language packs |
 | [Why codeterrain](docs/why-codeterrain.md) | The origin, the measurements, what is not proven yet |
+| [Prior art](docs/prior-art.md) | What twelve comparable tools document answering, read from their docs |
 | [Changelog](CHANGELOG.md) | What changed, release by release |
 
 ## Development

{codeterrain-0.3.0 → codeterrain-0.3.1}/SECURITY.md

@@ -11,16 +11,16 @@ What codeterrain does guarantee is about its own, parent process:
 1. **It never executes target code.** The static tier (`fixtures`, `fixture`) reads files with `ast`
    only. Every program it starts (`git`, the target interpreter) is resolved to an absolute path from
    the absolute `PATH` entries, never from the current directory, never a `.bat` or `.cmd` on Windows,
-   and never a program a bare name finds inside the target repository or, for `terrain callers`,
+   and never a program a bare name finds inside the target repository or, for `codeterrain callers`,
    inside any front-end checkout it reads, whichever checkout it is asking about. The `git status` that
-   `terrain callers` runs in each checkout switches `core.fsmonitor` off, so a command named in that
+   `codeterrain callers` runs in each checkout switches `core.fsmonitor` off, so a command named in that
    checkout's `.git/config` is not run, and takes no optional locks, so it writes nothing there.
-   A language pack runs in terrain's own process. Before any pack is looked up, every import-path
+   A language pack runs in codeterrain's own process. Before any pack is looked up, every import-path
    entry inside the repository being read (and an empty or relative one) is removed, so neither a
    pack, the parts of a namespace package nor anything a pack imports later resolves there; a pack
-   whose distribution or module still lies inside it is refused before it is imported. What terrain
+   whose distribution or module still lies inside it is refused before it is imported. What codeterrain
    itself runs from is the exception, when it lies inside the checkout: its virtual environment and
-   the folder its own code is imported from. A checkout inside terrain's environment is not trusted.
+   the folder its own code is imported from. A checkout inside codeterrain's environment is not trusted.
 2. **It never hands the child anything you did not opt into.** The child's environment is an allowlist;
    proxies, `PYTEST_ADDOPTS` and `PYTEST_PLUGINS` are dropped; AWS credentials are dummies; the home and
    per-user data directories point at an empty directory; git reads no system or global config and has
@@ -28,10 +28,12 @@ What codeterrain does guarantee is about its own, parent process:
    `pytest_args` and `respect_addopts` are honoured only from `--config` or your user config, and
    ignored, with a warning, when the repository's `pyproject.toml` sets them. A user-config `pass_env`
    applies to every repository you run on, trusted or not; a `--config` file scopes it to one run.
-3. **It never lets the child write into the repository by default.** `addopts` are switched off,
+3. **It does not have pytest write into the repository by default.** `addopts` are switched off,
    `log_file` is blanked, and the known file-writing options of pytest and common plugins are refused,
    from the project's options and from `pytest_args`. The child runs in a private temp directory,
-   outside the cache, which is removed afterwards.
+   outside the cache, which is removed afterwards. This stops reports and logs landing in the
+   checkout; it does not stop target code that opens a file by absolute path, which can write
+   anywhere you can.
 4. **It ends the child and what it started.** A timeout kills the whole process tree. On Windows a job
    object also kills what the child left behind after a normal exit; on POSIX its process group is.
 
@@ -76,12 +78,11 @@ passes the check.
 
 | | |
 |---|---|
-| **Guaranteed** (each has a regression test) | the parent never runs target code or a repository-shipped executable; the environment allowlist; repository config cannot widen it; git in the child has no credential helper; no default writes into the target; tree kill on timeout and of stragglers after exit (except a POSIX grandchild that started its own session); redaction of the values codeterrain knows; terminal escaping; path confinement |
+| **Guaranteed** (each has a regression test) | the parent never runs target code or a repository-shipped executable; the environment allowlist; repository config cannot widen it; git in the child has no credential helper; no default writes into the target by pytest or its known plugins; tree kill on timeout and of stragglers after exit (except a POSIX grandchild that started its own session); redaction of the values codeterrain knows; terminal escaping; path confinement |
 | **Best-effort** | the network guard. It blocks accidental network calls from Python code in the child, and is not a boundary against hostile code: non-Python subprocesses, isolated-mode Python children, a freshly loaded `_socket`, target code that undoes the patch, `getfqdn`, the C socket class and C extensions are not covered. [docs/sandbox.md](docs/sandbox.md) lists every gap. |
-| **Not covered** | secrets codeterrain does not know (a value the target reads from a file and echoes); loopback services, which are reachable by design; a POSIX grandchild that started its own session; hostile code reading the real home by absolute path or an OS credential store; a child that rewrites the cache it worked out from the root; a crash of a native parser a language pack uses (the TypeScript pack's tree-sitter parses front-end source in terrain's process: it runs nothing from that source, and a file over 2,000,000 bytes is not read, but a parser fault would end the command rather than report the file) |
+| **Not covered** | secrets codeterrain does not know (a value the target reads from a file and echoes); loopback services, which are reachable by design; a POSIX grandchild that started its own session; hostile code reading the real home by absolute path or an OS credential store; a child that rewrites the cache it worked out from the root; a crash of a native parser a language pack uses (the TypeScript pack's tree-sitter parses front-end source in codeterrain's process: it runs nothing from that source, and a file over 2,000,000 bytes is not read, but a parser fault would end the command rather than report the file) |
 
 ## Reporting a vulnerability
 
-The repository is private for now. Open a private security advisory on the repository
-(Security, then Advisories, then "Report a vulnerability"), with a reproduction if you have one. Do not
-open a public issue.
+Report it privately on GitHub: on the repository's Security tab, choose "Report a vulnerability", and
+include a reproduction if you have one. Do not open a public issue.