@nanonets/graft 0.7.0 → 0.8.0

package/README.md

@@ -1,24 +1,30 @@
 <div align="center">
 
-<!-- placeholder: swap for the Graft logo asset when ready -->
-<!-- <img src="assets/graft.png" alt="Graft" width="220"/> -->
+<img src="assets/graft-hero.png" alt="Graft — open-source context layer for large codebases" width="100%"/>
 
-# Graft
-
-**Your coding agent reads 30 files to change 3.**
-**Graft gives it the map it should have read first.**
+### Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
 
 <p>
+  <a href="https://graft.nanonets.ai"><img src="https://img.shields.io/badge/website-graft.nanonets.ai-546FFF?style=for-the-badge" /></a>
   <a href="https://www.npmjs.com/package/@nanonets/graft"><img src="https://img.shields.io/npm/v/%40nanonets%2Fgraft?style=for-the-badge&logo=npm&logoColor=white&label=npm" /></a>
   <a href="https://www.npmjs.com/package/@nanonets/graft"><img src="https://img.shields.io/npm/dm/%40nanonets%2Fgraft?style=for-the-badge&logo=npm&logoColor=white&label=downloads" /></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/%40nanonets%2Fgraft?style=for-the-badge&logo=nodedotjs&logoColor=white" /></a>
   <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
   <img src="https://img.shields.io/badge/License-MIT-20C997?style=for-the-badge" />
   <img src="https://img.shields.io/badge/telemetry-none-546FFF?style=for-the-badge" />
+  <a href="https://scorecard.dev/viewer/?uri=github.com/NanoNets/Graft"><img src="https://img.shields.io/ossf-scorecard/github.com/NanoNets/Graft?style=for-the-badge&label=openssf%20scorecard" /></a>
 </p>
 
-<!-- numbers from the committed run in bench/results/ (2026-07-22, 162 agent runs, 2 repos) — see Benchmark below -->
-**32% less cost · 46% fewer tool calls · 60% lower latency** with the graph bundle pushed up front, at equal correctness — or **16% less cost with correctness up 5 points** when the agent pulls from the graph on demand. Measured against the same agent going in cold.
+### Up to **4× cheaper** and **3× faster**, with better or no loss of correctness.
+
+| vs. a standard session, no Graft | With Graft |
+|---|---|
+| Tool calls | **46% fewer** |
+| Tokens | **42% fewer** |
+| Time | **60% less** |
+| Correctness | **equal** |
+
+<sub>The table is a 162-run controlled benchmark (same agent, same file tools, only the context differs). The "up to 4× cheaper / 3× faster" figures are the biggest single-task wins from a separate real-repo sweep (PocketBase, ollama, Excalidraw). [Full method & per-repo numbers ↓](#tested-on-your-popular-repos)</sub>
 
 </div>
 
@@ -28,6 +34,26 @@
 
 ---
 
+## Contents
+
+- [Quick start](#quick-start)
+- [The problem](#the-problem)
+- [What Graft does](#what-graft-does)
+- [How the graph gets built](#how-the-graph-gets-built)
+- [What's in a node](#whats-in-a-node)
+- [What runs where](#what-runs-where)
+- [Agent integration](#agent-integration) — [MCP server](#mcp-server) · [Claude Code (deep integration)](#claude-code-deep-integration)
+- [CLI](#cli)
+- [Search & orient](#search--orient-graft-grep--graft-map) (`graft grep` / `graft map`)
+- [Monorepos & multi-repo folders](#monorepos--multi-repo-folders)
+- [Visualize it](#visualize-it-graft-viz) (`graft viz`)
+- [Benchmark](#benchmark)
+- [Tested on your popular repos](#tested-on-your-popular-repos)
+- [Development](#development)
+- [License](#license)
+
+---
+
 ## Quick start
 
 ```bash
@@ -37,64 +63,16 @@ graft init                       # build the graph + wire it into Claude Code
 
 That is the whole setup. `graft init` builds `graft/` from your code and drops a statusline and hooks into `.claude/`, so from the next session on Graft rides along in Claude Code: it pulls the matching nodes into each prompt and rebuilds the graph in the background after every turn. No daemon, no re-indexing to remember, nothing to run or maintain by default — the graph is just files.
 
-Commit `graft/` so everyone who clones the repo (and their agents) gets the map:
+`graft build` adds `graft/` to your `.gitignore` automatically — the graph is a local, regenerable cache (like `node_modules`), not something you commit. What you share is the wiring `init` dropped into `.claude/`; each teammate runs `graft build` to generate their own graph:
 
 ```bash
-git add graft && git commit -m "add context graph"
+git add .claude && git commit -m "wire in graft"
 ```
 
 Prefer not to install globally? `npx @nanonets/graft init` works the same way.
 
 ---
 
-## Agent integration
-
-One command wires Graft into the coding agents you use:
-
-```bash
-npx @nanonets/graft init
-# detects your agents and writes each one's native instruction file;
-# Claude Code additionally gets the live statusline + hooks below
-```
-
-`init` auto-detects which agents are present (via their config directories) and writes a marker-fenced Graft section into each one's shared instruction file — `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md` — or a wholly-owned rule file for the agents that use one — `.cursor/rules/graft.mdc`, `.kiro/steering/graft.md`, `.windsurf/rules/graft.md`. Re-running only updates Graft's own section (or replaces the owned file) and never touches the rest of your content.
-
-| Flag | Effect |
-|---|---|
-| `--agents <ids...>` | wire only these — ids: `agents`, `cursor`, `gemini`, `copilot`, `kiro`, `windsurf`, `claude` |
-| `--all-agents` | write instruction files for every known agent, detected or not |
-| `--no-agents` | Claude Code wiring only; skip other agents |
-| `--list-agents` | print the known agent ids and exit |
-| `--no-mcp` | skip MCP server registration |
-| `--no-hooks` | skip hook installation |
-
-### MCP server
-
-`graft init` also registers Graft's MCP server with agents that support it, so
-`graft_ask`, `graft_callers`, `graft_grep`, `graft_skeleton`, `graft_map`, and
-`graft_check` appear as native tools — no shell required. Claude Code now gets
-this too: `graft init` writes the server into the project's `.mcp.json` (restart
-Claude Code to load it). Skip with `--no-mcp`. Run it manually with
-`graft mcp [dir]`, or register it by hand:
-
-```json
-{ "mcpServers": { "graft": { "command": "npx", "args": ["-y", "@nanonets/graft", "mcp"] } } }
-```
-
-Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's post-edit hook — blast-radius warnings and automatic `$0` graph re-sync after edits (skip with `--no-hooks`).
-
-### Claude Code (deep integration)
-
-`graft init` always wires up Claude Code, and Claude Code gets more than an instruction file. From then on, any Claude Code session opened in the repo gets:
-
-- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph
-- **auto-sync** — after you edit code, Graft rebuilds the graph in the background at the end of the turn (structural, `$0` — it never calls the LLM on its own)
-- **context on tap** — each prompt pulls the matching nodes into the session; editing a file surfaces what depends on it ("blast radius"); new sessions start with the repo map
-
-`graft init` is idempotent and never clobbers your existing `.claude/settings.json` — it merges its blocks and leaves the rest alone. Want the LLM summaries too? Run `graft build --deep` (with a key) whenever you like; auto-sync will never do it for you.
-
----
-
 ## The problem
 
 Every task, your coding agent starts blind. Before it changes anything, it re-explores the repo: grep a term, open a file, follow an import, back out, try again. It is rebuilding a picture of a codebase it mapped an hour ago and threw away. That rediscovery burns most of a run's tool calls, tokens, and latency, and it is pure overhead:
@@ -105,6 +83,10 @@ Every task, your coding agent starts blind. Before it changes anything, it re-ex
 
 Humans onboard to a codebase once. Agents onboard every single time.
 
+<p align="center">
+  <img src="assets/graft-site-act-demo.gif" alt="A no-map agent's exploration trail wandering file to file before it finds what it needs" width="820"/>
+</p>
+
 ---
 
 ## What Graft does
@@ -126,7 +108,16 @@ Graft builds the graph in two passes, both powered by a language model:
 1. **Read each file.** Every source file is summarized once into a short description of what it does.
 2. **Group into nodes.** Those summaries are grouped into a curated set of nodes (subsystems, key files, and concepts) with typed links between them. Graft chooses the right level of detail for you instead of making one node per file, so a big repo becomes a few dozen readable nodes.
 
-Both passes are cached by content hash. Re-running only touches the files that changed, so the second build is fast and cheap.
+```mermaid
+flowchart LR
+    S[Source files] --> T["Tier 1 — tree-sitter<br/>no model, no key"]
+    S --> P1["Pass 1 — LLM summarizes<br/>each file (--deep)"]
+    T --> W["graft/.graph/wiring.json<br/>per-symbol code graph"]
+    P1 --> P2["Pass 2 — group into nodes<br/>+ typed links"]
+    P2 --> N["graft/*.md<br/>markdown node graph"]
+```
+
+Both LLM passes are cached by content hash. Re-running only touches the files that changed, so the second build is fast and cheap.
 
 Alongside the markdown graph, `graft build` builds `graft/.graph/wiring.json` — a per-symbol code graph — plus a per-file wiring card mirroring your source tree. Tier 1 is pure tree-sitter (every function, class, and call edge; deterministic, no model, no network), which is why plain `graft build` needs no key. The `--deep` pass adds a one-line summary and a crux excerpt per symbol, cached by body hash.
 
@@ -154,29 +145,72 @@ _Summary, sources, links, and notes ship today in markdown nodes. The crux ships
 
 ---
 
-## Keeping it honest (CI)
+## What runs where
+
+- **On your machine, no key, no network:** the structural code graph. `graft build` (wiring graph + per-file cards), `graft check`, and `graft ask` are deterministic tree-sitter — they never call a model.
+- **Through your provider key:** the LLM-written parts — `graft build --deep` adds the concept nodes (file summaries + node synthesis) and the per-symbol summaries and cruxes. graft is vendor-neutral: set `GRAFT_PROVIDER` (`openai` for any OpenAI-compatible endpoint, or `anthropic` for the native API), your `GRAFT_API_KEY`, `GRAFT_MODEL`, and — for the `openai` wire format — `GRAFT_BASE_URL` to point at OpenRouter, Fireworks, Groq, a LiteLLM proxy, a local server, or OpenAI itself. Or pass `--provider/--model/--api-key/--base-url` on the command line. (`OPENROUTER_API_KEY` still works as a deprecated fallback.)
+- **No telemetry** and no analytics — the only network calls are the LLM requests you configured.
+
+See [`.env.example`](.env.example) for the full list of settings (model, base URL, graph directory).
+
+---
 
-A graph that has drifted from the code is worse than no graph. `graft check` compares each node's tracked source hashes against the current files and fails if the graph is stale. Drop it in CI so a pull request cannot merge with an out-of-date map.
+## Agent integration
+
+One command wires Graft into the coding agents you use:
 
 ```bash
-graft check          # exits non-zero if graft/ has drifted
-graft check --json   # machine-readable drift report
+npx @nanonets/graft init
+# detects your agents and writes each one's native instruction file;
+# Claude Code additionally gets the live statusline + hooks below
 ```
 
-When the wiring graph exists, `graft check` validates it too — structural drift (symbols added, removed, or changed since the last `graft build`) and stale summaries both fail the check. A repo without a wiring graph is not penalized; the markdown graph stands alone.
+`init` auto-detects which agents are present (via their config directories) and writes a marker-fenced Graft section into each one's shared instruction file — `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md` — or a wholly-owned rule file for the agents that use one — `.cursor/rules/graft.mdc`, `.kiro/steering/graft.md`, `.windsurf/rules/graft.md`. Re-running only updates Graft's own section (or replaces the owned file) and never touches the rest of your content.
 
-<!-- placeholder: planned, not yet in the CLI -->
-> **Planned: auto-regen on PR.** A single CI bot will regenerate changed nodes on a pull request and push the update, so the graph stays current without anyone remembering to run `build`. Until then, regenerate with `graft build --deep` and commit it alongside your code.
+| Flag | Effect |
+|---|---|
+| `--agents <ids...>` | wire only these — ids: `agents`, `cursor`, `gemini`, `copilot`, `kiro`, `windsurf`, `claude` |
+| `--all-agents` | write instruction files for every known agent, detected or not |
+| `--no-agents` | Claude Code wiring only; skip other agents |
+| `--list-agents` | print the known agent ids and exit |
+| `--no-mcp` | skip MCP server registration |
+| `--no-hooks` | skip hook installation |
 
----
+### MCP server
 
-## What runs where
+`graft init` also registers Graft's MCP server with agents that support it, so these six tools appear natively, no shell required. Claude Code gets this too: `graft init` writes the server into the project's `.mcp.json` (restart Claude Code to load it). Skip with `--no-mcp`; run it manually with `graft mcp [dir]`.
 
-- **On your machine, no key, no network:** the structural code graph. `graft build` (wiring graph + per-file cards), `graft check`, and `graft ask` are deterministic tree-sitter — they never call a model.
-- **Through your provider key:** the LLM-written parts — `graft build --deep` adds the concept nodes (file summaries + node synthesis) and the per-symbol summaries and cruxes. graft is vendor-neutral: set `GRAFT_PROVIDER` (`openai` for any OpenAI-compatible endpoint, or `anthropic` for the native API), your `GRAFT_API_KEY`, `GRAFT_MODEL`, and — for the `openai` wire format — `GRAFT_BASE_URL` to point at OpenRouter, Fireworks, Groq, a LiteLLM proxy, a local server, or OpenAI itself. Or pass `--provider/--model/--api-key/--base-url` on the command line. (`OPENROUTER_API_KEY` still works as a deprecated fallback.)
-- **No telemetry** and no analytics — the only network calls are the LLM requests you configured.
+| Tool | Takes | What it's for |
+|---|---|---|
+| `graft_ask` | a question | Ranked nodes with file:line, source inlined — usually the full answer, no follow-up read needed. |
+| `graft_skeleton` | a file path | Every signature in that file, no bodies — the API surface for a tenth of the tokens. |
+| `graft_callers` | a symbol | Who depends on it, or what it depends on with `direction: out`, N levels deep for blast radius. |
+| `graft_grep` | a regex | Every hit, grouped by enclosing symbol, ranked by how coupled that symbol is. |
+| `graft_map` | nothing | A first look at an unfamiliar repo: directory clusters, hubs, hotspots. |
+| `graft_check` | nothing | Whether the local graph has drifted from the code. |
 
-See [`.env.example`](.env.example) for the full list of settings (model, base URL, graph directory).
+Register it by hand if your agent needs it explicit:
+
+```json
+{ "mcpServers": { "graft": { "command": "npx", "args": ["-y", "@nanonets/graft", "mcp"] } } }
+```
+
+Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's post-edit hook — blast-radius warnings and automatic `$0` graph re-sync after edits (skip with `--no-hooks`).
+
+### Claude Code (deep integration)
+
+`graft init` always wires up Claude Code, and Claude Code gets more than an instruction file. From then on, any Claude Code session opened in the repo gets:
+
+- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph
+- **auto-sync** — after you edit code, Graft rebuilds the graph in the background at the end of the turn (structural, `$0` — it never calls the LLM on its own)
+- **context on tap** — each prompt pulls the matching nodes into the session; editing a file surfaces what depends on it ("blast radius"); new sessions start with the repo map
+
+<p align="center">
+  <img src="assets/graft-hook-blast-radius-demo.gif" alt="graft's post-edit hook: editing node-file.ts prints its blast radius (who depends on it) inline, the statusline flips stale → syncing → synced on its own, and the same dependents light up in graft viz" width="820"/>
+  <br/><sub>edit a file → blast radius appears inline → graph auto-resyncs → confirmed in <code>graft viz</code></sub>
+</p>
+
+`graft init` is idempotent and never clobbers your existing `.claude/settings.json` — it merges its blocks and leaves the rest alone. Want the LLM summaries too? Run `graft build --deep` (with a key) whenever you like; auto-sync will never do it for you.
 
 ---
 
@@ -191,6 +225,8 @@ graft ask "<task>" [dir]             # query the graph — ranked nodes + exact
 graft ask "<task>" --json            # machine-readable result
 graft ask "<task>" --in <scope>      # narrow to one sub-project of a monorepo/multi-repo folder (see below)
 
+graft skeleton <file> [dir]          # every signature in one file, no bodies — the API surface for ~1/10th the tokens (no LLM, no key)
+
 graft callers <symbol> [dir]         # who calls/references/imports/implements/extends a symbol (no LLM, no key)
 graft callers <symbol> --direction out  # the reverse: what the symbol itself calls/references (was `graft callees`)
 graft callers <symbol> -d N          # walk transitively out to depth N — full blast radius (was `graft impact`)
@@ -249,15 +285,14 @@ with file/symbol counts, each dir's local hubs, and the global hotspots —
 all ranked by in-degree, no LLM, no key:
 
 ```
-repo map — 105 files · 582 symbols · 1815 edges · typescript
+repo map — 113 files · 687 symbols · 2186 edges · typescript
 
-src/                54 files · 414 symbols   hubs: set (bindings.ts, 38←), contextDirFor (node-file.ts, 11←), wiringPath (write.ts, 10←)
-test/               36 files · 68 symbols   hubs: edge (graph-traverse.test.ts, 4←), graphOf (graph-traverse.test.ts, 4←), nodeStub (graph-traverse.test.ts, 3←)
+src/                63 files · 527 symbols   hubs: contextDirFor (node-file.ts, 21←), wiringPath (write.ts, 14←), buildGraph (build.ts, 11←)
+test/               43 files · 102 symbols   hubs: edge (graph-traverse.test.ts, 4←), graphOf (graph-traverse.test.ts, 4←), fileNode (graph-map.test.ts, 3←)
 viewer/             5 files · 58 symbols   hubs: $ (main.ts, 9←), activeGraph (main.ts, 5←), cvar (data.ts, 5←)
-bench/              8 files · 42 symbols   hubs: makeClient (llm.ts, 3←), buildMarkdown (report.ts, 2←), judge (judge.ts, 2←)
 scripts/            2 files · 0 symbols
 
-hotspots: set · method · src/graph/bindings.ts:L21-L23 · 38←  contextDirFor · function · src/context/node-file.ts:L100-L103 · 11←  wiringPath · function · src/graph/write.ts:L20-L22 · 10←  ...
+hotspots: contextDirFor · function · src/context/node-file.ts:L100-L103 · 21←  wiringPath · function · src/graph/write.ts:L20-L22 · 14←  buildGraph · function · src/graph/build.ts:L104-L218 · 11←  ...
 ```
 
 ## Monorepos & multi-repo folders
@@ -271,7 +306,7 @@ Graft handles two shapes without any config:
   sub-project can't drown a small one; hits carry `[scope/]` labels, and
   `graft map` groups its directory clusters by scope first.
 - **A folder of separate git repos** (no `.git` at the top) — `graft build`
-  auto-splits: each child keeps its own committable `graft/`, and the parent
+  auto-splits: each child gets its own (git-ignored) `graft/`, and the parent
   gets a `graft/workspace.json` index. Queries from the parent federate across
   every child, always labeled `<child>/`. Run `graft build` inside a child to
   work on just that repo.
@@ -284,6 +319,11 @@ once you know where you're working.
 `graft viz` opens a local, interactive view of both graphs — no install, no dev
 server; the viewer ships prebuilt inside the package.
 
+<p align="center">
+  <img src="assets/graft-viz-demo.gif" alt="graft viz — searching a symbol and jumping to it lights up its dependency graph: amber edges are what it depends on, teal is what depends on it" width="820"/>
+  <br/><sub>search → jump to a node → dependency graph lights up</sub>
+</p>
+
 - **Context** tab — the architecture graph from `graft/*.md`. Nodes colored by
   type, sized by connectedness.
 - **Code** tab — the per-symbol graph from `graft/.graph/wiring.json` (run `graft build` first).
@@ -312,26 +352,77 @@ normalized on load — no regeneration needed.
 
 ## Benchmark
 
-The claim Graft has to earn is simple: an agent that gets its context from the graph is cheaper and faster without getting more answers wrong. The harness runs every task through three arms of the same Claude Sonnet 5 agent with the same file tools: **cold** (explores from zero), **graph (push)** (a `graft ask --source` bundle injected up front), and **graft (pull)** (graft_ask/graft_skeleton tools, nothing injected — context paid for only when asked). An Opus 4.8 judge scores correctness with a required-keyword floor so a fast-but-wrong answer cannot win. Cost is cache-aware (reads ≈0.1×, writes 1.25×) — the billing model agents actually run under.
+An agent that reads the graph should be cheaper and faster without getting more answers wrong. That's the whole claim, so we measured it instead of asserting it.
 
-Committed run: `bench/results/2026-07-22T13-19-14-246Z` — 162 runs across two repos (graft itself and a real Node/Express auth service), 3 trials each, tasks split between localized (single-file) and multi-file questions.
+The harness ran three variants of the same Claude Sonnet 5 agent with the same file tools: **cold** (explores from zero), **Graft** (a `graft ask --source` bundle pushed up front), and **pull** (graft_ask/graft_skeleton tools, nothing injected — context paid for only when asked). An Opus 4.8 judge scored correctness with a required-keyword floor, so a fast-but-wrong answer couldn't win by being fast. Cost is cache-aware: reads ≈0.1×, writes 1.25×, the billing model agents actually run under.
 
-| Metric (mean/task) | Cold | Graph (push) | Graft (pull) |
+162 runs, two repos (graft itself and a real Node/Express auth service), 3 trials each, tasks split between single-file and multi-file questions.
+
+| Metric (mean/task) | Cold | Graft |
+|---|---|---|
+| Cost ($) | 0.0429 | **0.0292 (−32%)** |
+| Uncached input tokens | 8,070 | **4,650 (−42%)** |
+| Tool calls | 4.2 | **2.3 (−46%)** |
+| Latency (s) | 39.8 | **15.8 (−60%)** |
+| Correctness | 93% | 93% (equal) |
+
+Graft never answered worse than cold, on any corpus. The pull variant gave up most of that speed for something bigger: correctness jumped to 98%, +5 points over cold, the strongest single result in the sweep. Push when speed is what you need; pull when being right matters more.
+
+---
+
+## Tested on your popular repos
+
+The sweep above measures the mechanism. The real test is whether graft helps an agent **ship real changes** on code people actually run, not just answer questions. So we benchmark it on popular open-source repos: **15 tasks each**, 10 real developer questions plus **5 actual implementation tasks** (real merged pull requests, each re-implemented from its base commit and scored against the files the maintainers actually changed). Same agent (Claude Opus), same file tools; the only difference is whether graft is wired in.
+
+Across these repos graft runs **up to 4× cheaper and 3× faster**, with better or no loss of correctness: it reproduces the real merged PRs by touching the same files the maintainers did. Per-repo detail below.
+
+### PocketBase (Go, ~350 files)
+
+| Aggregate over 15 tasks | Standard Claude Code | With graft |
+|---|---|---|
+| Cost | $13.91 | **$11.02 (−21%)** |
+| Wall-clock | 2,044s | **1,762s (−14%)** |
+| PRs reproduced | 5 / 5 | **5 / 5 (same files as the maintainers)** |
+
+Cheaper and faster with no loss of correctness: graft reproduced all five merged PRs, touching the same files the maintainers did. The gap is widest on cross-file understanding — "how does auth work across OAuth2 providers" dropped from $2.19 to $0.84.
+
+<details>
+<summary><b>The 10 questions we asked</b></summary>
+
+1. **Orientation** — Give me a map of PocketBase's architecture: the main subsystems and how an HTTP request flows through to the database.
+2. **Entry-point trace** — Trace end-to-end what happens when a client creates a record via the REST API, from route handler to database write.
+3. **Feature location** — I want to add a brand-new collection field type. Where do I hook it in, and which pieces must change?
+4. **Bug localization** — Realtime subscriptions silently stop delivering events after a while. Where would you start looking, and why?
+5. **Blast radius** — If I change the signature of the record-validation logic, what depends on it and what could break?
+6. **Cross-file synthesis** — How does auth work across OAuth2 providers: where are tokens issued, validated, stored, and refreshed?
+7. **Extensibility** — How do I use PocketBase as a Go framework to register a custom route plus an on-record-create hook?
+8. **Security discovery** — Where is user input validated, and where are collection API access rules enforced before a query runs?
+9. **Public API** — As an external app, how do I authenticate and then list and filter records over the REST API?
+10. **Test verification** — Where are the tests for the record CRUD API, and what do they assert about access rules?
+
+</details>
+
+<details>
+<summary><b>The 5 merged PRs we re-implemented</b></summary>
+
+Each PR was reset to its base commit; graft's diff was scored against the files the merged PR changed.
+
+| PR | Type | What it does | Files the maintainers touched |
 |---|---|---|---|
-| Cost ($) | 0.0429 | **0.0292 (−32%)** | 0.0362 (−16%) |
-| Uncached input tokens | 8,070 | **4,650 (−42%)** | 5,965 (−26%) |
-| Tool calls | 4.2 | **2.3 (−46%)** | 4.2 (−1%) |
-| Latency (s) | 39.8 | **15.8 (−60%)** | 39.5 (−1%) |
-| Correctness | 93% | 93% | **98% (+5 pts)** |
+| [#6744](https://github.com/pocketbase/pocketbase/pull/6744) | feat | Generate & serve WebP thumbnails | `apis/file.go`, `tools/filesystem/filesystem.go` |
+| [#6947](https://github.com/pocketbase/pocketbase/pull/6947) | fix | Uniform char distribution in regex random strings | `tools/security/random_by_regex.go` |
+| [#6690](https://github.com/pocketbase/pocketbase/pull/6690) | refactor | Patreon OAuth2 to use `x/oauth2/endpoints` | `tools/auth/patreon.go` |
+| [#2726](https://github.com/pocketbase/pocketbase/pull/2726) | perf | Drop a redundant admin-count query on a hot middleware path | `apis/middlewares.go` |
+| [#3192](https://github.com/pocketbase/pocketbase/pull/3192) | fix | Restore prior API rules on automigration rollback | `plugins/migratecmd/templates.go` |
 
-Push is the cost/latency win; pull is the correctness win (and never lost to cold anywhere, including single-file tasks). On one corpus push traded 3 correctness points for its savings — the per-corpus and per-locality splits are in the committed results, not averaged away. Reproduce it yourself:
+</details>
 
-```bash
-npm run bench -- --smoke   # 1 corpus, 1 task, all arms — a quick plumbing check
-npm run bench              # full: all corpora, all tasks, 3 arms × 3 trials
-```
+<details>
+<summary><b>Method</b></summary>
+
+Two clones of PocketBase at the same commit: one wired with `graft init`, one untouched and verified graft-free. Each task run headless (`claude -p`, Claude Opus) with an empty MCP config. Understanding questions were graded by whether the answer pointed to the right files and functions; PR tasks were scored on whether the agent's diff touched the same files as the merged PR. Every transcript was audited to confirm graft was actually used in the graft arm and absent from the standard arm.
 
-See [`bench/README.md`](bench/README.md) for the method and how to add your own repo.
+</details>
 
 ---
 

package/dist/ai/llm/types.d.ts

@@ -2,7 +2,7 @@
  * Provider-neutral chat transport.
  *
  * Every LLM call in graft — the engine's single-shot summarize/synthesize/crux
- * ops AND the benchmark's multi-turn ReAct loop — goes through one interface,
+ * ops, and any multi-turn tool-use loop built on top — goes through one interface,
  * {@link ChatModel}. Adapters translate this neutral shape to a concrete SDK
  * (OpenAI-compatible or native Anthropic). Nothing above this layer knows which
  * provider is in play, so adding a provider is a new adapter, never a change to
@@ -37,7 +37,7 @@ export interface Message {
     /**
      * Request a provider cache marker (`cache_control: ephemeral`) on THIS message.
      * The transport only understands this per-message flag; any sliding/rotation
-     * policy lives in the caller (see the bench loop).
+     * policy lives in the caller.
      */
     cacheBreakpoint?: boolean;
     /**

package/dist/ai/llm/types.js

@@ -2,7 +2,7 @@
  * Provider-neutral chat transport.
  *
  * Every LLM call in graft — the engine's single-shot summarize/synthesize/crux
- * ops AND the benchmark's multi-turn ReAct loop — goes through one interface,
+ * ops, and any multi-turn tool-use loop built on top — goes through one interface,
  * {@link ChatModel}. Adapters translate this neutral shape to a concrete SDK
  * (OpenAI-compatible or native Anthropic). Nothing above this layer knows which
  * provider is in play, so adding a provider is a new adapter, never a change to

package/dist/ask/ask.d.ts

@@ -58,6 +58,20 @@ export interface AskResult {
         }[];
     };
 }
+/** Score a document's token counts against the query counts (name field
+ * pre-weighted by caller). Each shared term is weighted by its inverse document
+ * frequency (`idf`), so a word that appears in many nodes — "overlay" across a
+ * whole widget subsystem, or a repeated word in a pasted issue body — counts for
+ * far less than a rare, discriminating identifier ("scrolling"). Without idf,
+ * pure term-frequency lets an incidental common word dominate the ranking; this
+ * is the lexical half of the keyword-collision fix (graph-rank is the other). */
+/** Test files rarely answer "how does X work" / "where is Y" — they mirror the
+ * real symbol's tokens, so a test can out-score the definition on a lexical tie
+ * and land as the top hit (observed: an `ask` returning a `Test…` function first,
+ * sending the agent to the wrong file). A multiplicative de-rank keeps tests in
+ * the results (they still matter for "where are the tests") but below the real
+ * definition. Covers Go (`_test.go`), JS/TS (`.test.` / `.spec.`), and test dirs. */
+export declare function isTestPath(path: string): boolean;
 /** Idf-weighted share (0..1) of the query a document matches: each query term
  * counts by its rarity, so this separates task prompts from chatter in a way a
  * raw term count can't. A conversational prompt's words are either off-corpus

package/dist/ask/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/ask/ask.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/ask/ask.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAiD,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIpG,OAAO,KAAK,EAAmB,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAK3E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd;;qFAEiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;2EAEuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;IACzC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;sFAEkF;IAClF,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;oFAIgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;8EAM0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;kEAG8D;IAC9D,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;CACpF;AAgDD;;;;;;iFAMiF;AACjF;;;;;qFAKqF;AACrF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAsMD;;;;;;6DAM6D;AAC7D;;;;;;;;yCAQyC;AACzC,wBAAgB,WAAW,CACzB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE;IAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAClC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AA2UD,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;qFACiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;sFAEkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;6EAIyE;IACzE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;yEAIqE;IACrE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AA0ED,wEAAwE;AACxE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,SAAS,CA6ChF;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;2EAE2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CA8BtG;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAUxD;AAOD,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CA0C9C"}

package/dist/ask/ask.js

@@ -17,7 +17,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import matter from "gray-matter";
 import { contextDirFor } from "../context/node-file.js";
-import { savingsFooter, savingsFor } from "../context/savings.js";
+import { savingsFooter, savingsFor, SAVINGS_TURN_NUDGE } from "../context/savings.js";
 import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";
 import { pathUnderPrefix, scopeLabel, scopeOf, scopesHereClause, scopesOfGraph } from "../graph/scopes.js";
 import { resolveSymbol } from "../graph/traverse.js";
@@ -71,6 +71,16 @@ function loadCorpus(outDir) {
  * far less than a rare, discriminating identifier ("scrolling"). Without idf,
  * pure term-frequency lets an incidental common word dominate the ranking; this
  * is the lexical half of the keyword-collision fix (graph-rank is the other). */
+/** Test files rarely answer "how does X work" / "where is Y" — they mirror the
+ * real symbol's tokens, so a test can out-score the definition on a lexical tie
+ * and land as the top hit (observed: an `ask` returning a `Test…` function first,
+ * sending the agent to the wrong file). A multiplicative de-rank keeps tests in
+ * the results (they still matter for "where are the tests") but below the real
+ * definition. Covers Go (`_test.go`), JS/TS (`.test.` / `.spec.`), and test dirs. */
+export function isTestPath(path) {
+    return /(^|\/)(tests?|__tests__|spec)\/|(_test|\.test|\.spec)\.[a-z]+$/i.test(path || "");
+}
+const TEST_RANK_PENALTY = 0.35;
 function score(query, doc, idf) {
     let s = 0;
     for (const [t, qn] of query) {
@@ -169,7 +179,7 @@ function findSubjectNodes(query, graph, inPrefix) {
 }
 function fallthroughNoteFor(subject) {
     return (`structural index: no entries for '${subject}' — showing lexical matches; ` +
-        `for exhaustive callers use grep -rn '${subject}'`);
+        `for precise edges try graft callers '${subject}', or graft grep '${subject}' for every reference (loosen the pattern if it returns nothing)`);
 }
 function structural(query, graph, limit, inPrefix) {
     const wantsIn = INCOMING.test(query);
@@ -275,6 +285,13 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
     // ranty description can't linearly amplify an incidental word.
     const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));
     const graph = corpus.graph;
+    // Test-file de-ranking is query-aware: a query that ASKS about tests wants test
+    // files on top, so it gets no penalty; every other query wants the real
+    // definition first. This stops a test that merely contains the query's literals
+    // (e.g. `TestDownloadStall` matching "download stall") from outranking the
+    // source it exercises — the "tests ranked above the actual code" trap.
+    const wantsTests = /\b(tests?|specs?|coverage|assert(?:ion)?s?|fixtures?|mocks?)\b/i.test(query);
+    const testFactor = (path) => (!wantsTests && isTestPath(path) ? TEST_RANK_PENALTY : 1);
     // ── Pass 1: tokenize every scored field once, and collect per-document token
     // bags so IDF can down-weight words that occur across the whole corpus. `--in`
     // drops a concept unless at least one of its sources falls under the prefix —
@@ -429,9 +446,10 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
                 const avg = docs.reduce((a, d) => a + bodyLen(d.body), 0) / docs.length;
                 const out = new Map();
                 for (const { n, name, path, body } of docs) {
-                    const total = score(q, name, sIdf) * 3 +
+                    const total = (score(q, name, sIdf) * 3 +
                         score(q, path, sIdf) * 2 +
-                        bm25(q, body, sIdf, bodyLen(body), avg);
+                        bm25(q, body, sIdf, bodyLen(body), avg)) *
+                        testFactor(n.path);
                     if (total > 0)
                         out.set(n.id, total);
                 }
@@ -501,9 +519,10 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
         for (const { n, name, path, body } of symbolDocs) {
             // Name and path are short identifiers → plain idf-weighted overlap; the body
             // is length-normalized via BM25 so long definitions don't win on bulk.
-            const total = score(q, name, idf) * 3 +
+            const total = (score(q, name, idf) * 3 +
                 score(q, path, idf) * 2 +
-                bm25(q, body, idf, bodyLen(body), avgBodyLen);
+                bm25(q, body, idf, bodyLen(body), avgBodyLen)) *
+                testFactor(n.path);
             if (total > 0) {
                 lex.set(n.id, total);
                 maxLex = Math.max(maxLex, total);
@@ -813,7 +832,8 @@ function askSavingsFooter(r, body) {
     const pct = Math.round((saved / base) * 100);
     return (`\n\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` +
         `${pack.toLocaleString()} tok vs reading the ${r.saved.files} source file(s) whole ≈ ` +
-        `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).`);
+        `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).` +
+        SAVINGS_TURN_NUDGE);
 }
 /** Multi-scope footer: answers a reviewer's two questions — "which
  * sub-projects did this pack come from?" (`matched in:`, displayed-hit counts,