@fodx/codelens 2.0.1 → 2.1.1

package/docs/routing.md

@@ -25,6 +25,12 @@ reads from disk — never stale), and `cl_save`/`cl_load` to persist working
 context across compaction. If a query result has `stale:true`, read that file
 from disk before relying on indexed snippets/edges.
 
+If `cl_current.inGitRepo` is false or `repo` points outside the current
+workspace, CodeLens is not attached to this workspace. Report the setup issue and
+ask the user to run `codelens install --target cursor --location local --yes`
+from the workspace root (or restart the MCP server after roots attach). Do not
+silently fall back to raw `find`/`grep` for discovery.
+
 ## When raw grep/find/read is fine (or better)
 
 - you already know an exact string/symbol/path
@@ -42,7 +48,9 @@ you're looking for.
 Results are scoped to the **current branch/worktree index only** by default.
 After `git checkout`, results will not leak from the old branch. If you switch
 branches mid-task, call `cl_current` again; the tool activates/creates the new
-branch's index automatically.
+branch's index automatically. MCP clients that provide Roots let CodeLens attach
+to the active workspace even from a global MCP config; otherwise use `--cwd` or
+project-local MCP config.
 
 ## Freshness
 

package/docs/tools.md

@@ -24,8 +24,8 @@ JSON-serialized text content.
 - **Line-range format**: `cl_search` reports `lines` as a `"start-end"` string for compact display; `cl_map` and `cl_expand` use numeric `startLine`/`endLine` for programmatic use. This difference is intentional.
 
 ## cl_explore
-- **Input**: `{ query: string, limit?: number=8, cursor?: string, contentType?: "code"|"prose", snippet?: "none"|"headline"|"compact"|"full", relatedDepth?: number=1 }`
-- **Returns**: `{ indexId, query, count, files:[{path, stale?, results:[{handle,lines,score,why,preview,signature?,collapsed?,stale?}]}], related:[{sourcePath,path,edgeType,hops,confidence,stale?}], freshness, pendingFiles?, nextCursor? }`
+- **Input**: `{ query: string, limit?: number=8, cursor?: string, contentType?: "code"|"prose", snippet?: "none"|"headline"|"compact"|"full", relatedDepth?: number=1, maxFiles?: number=6, maxResultsPerFile?: number=3, maxRelated?: number=20 }`
+- **Returns**: `{ indexId, query, count, files:[{path, stale?, results:[{handle,lines,score,why,preview,signature?,collapsed?,stale?}]}], related:[{sourcePath,path,edgeType,hops,confidence,stale?}], freshness, pendingFiles?, nextCursor?, truncated? }`
 - **Use**: broad orientation in one call — "how does X work?", "show the flow around Y", or surveying an unfamiliar area. It fuses `cl_search` + grouped previews + graph relationships; use `cl_search` when you only need to locate handles.
 
 ## cl_related
@@ -35,8 +35,8 @@ JSON-serialized text content.
 
 ## cl_impact
 - **Input**: `{ symbol?: string, path?: string, depth?: number=2, includeTests?: boolean=true }`
-- **Returns**: `{ indexId, target?, candidates?, callers, callees, affectedFiles, affectedTests, depth, confidenceNote, freshness?, pendingFiles? }`
-- **Use**: before changing shared code. Pass `symbol` plus `path` when possible; if a symbol is ambiguous, CodeLens returns `candidates` instead of guessing. Impact is edge-derived and includes confidence/hop counts; use `cl_expand` to inspect exact current code before editing.
+- **Returns**: `{ indexId, target?, candidates?, callers, callees, affectedFiles, affectedTests, depth, summary?, confidenceNote, freshness?, pendingFiles? }`
+- **Use**: before changing shared code. Pass `symbol` plus `path` when possible; if a symbol is ambiguous, CodeLens returns `candidates` instead of guessing. Impact is edge-derived and includes confidence/hop counts plus provenance labels (`graph` or conservative `path-heuristic`); use `cl_expand` to inspect exact current code before editing.
 
 ## cl_map
 - **Input**: `{ path?: string, limit?: number=50, all?: boolean }`

package/docs/usage-metrics.md

@@ -0,0 +1,89 @@
+# Usage metrics — how "saved" is calculated
+
+`cl_usage` reports per-tool call counts, bytes served, and an **estimated**
+context-window saving. The saving is an *estimate*, not a measurement — this
+page explains exactly how it's computed and its limits.
+
+## Which tools are tracked
+
+Only the agent's **retrieval + context-management** tools are tracked as
+"usage" — the ones that represent the agent actually using CodeLens to
+find/read/save code:
+
+| Tool | tracked | calls | bytes_served | bytes_saved |
+|------|---------|-------|--------------|-------------|
+| `cl_search` | ✅ | ✅ | ✅ | ✅ (discovery) |
+| `cl_explore` | ✅ | ✅ | ✅ | ✅ (discovery) |
+| `cl_related` | ✅ | ✅ | ✅ | ✅ (discovery) |
+| `cl_impact` | ✅ | ✅ | ✅ | ✅ (discovery) |
+| `cl_expand` | ✅ | ✅ | ✅ | 0 (it *is* the scoped read step) |
+| `cl_save` / `cl_load` | ✅ | ✅ | ✅ | 0 (context management) |
+
+**Operational tools are NOT tracked** (they're maintenance, not usage):
+`cl_refresh`, `cl_doctor`, `cl_stats`, `cl_prune`, `cl_drop`, `cl_current`,
+`cl_usage`. So `cl_refresh` (building the index) does not appear in the usage
+report, and checking `cl_usage` never inflates the numbers.
+
+Only the **discovery** tools (`cl_search`, `cl_explore`, `cl_related`, `cl_impact`) accrue `bytes_saved` —
+the ones that replace "grep + read a bunch of files" with compact indexed context.
+
+## The formula (refined — actual file sizes)
+
+For a discovery call, CodeLens computes savings from the **real sizes of the
+files in the results**, which it already indexes (`files.size`):
+
+```
+saved = max(0, Σ(distinct result files' indexed sizes) − bytesServed)
+```
+
+- `distinct result files` = the unique paths among the returned handles/files
+  (`cl_search`/`cl_related` carry `results[].path`; `cl_explore` carries
+  `files[].path`; `cl_impact` carries paths in target/candidates/callers/callees/affected lists).
+- `indexed sizes` = `files.size` for those paths in the current branch index.
+- `bytesServed` = bytes of the JSON actually sent to the model.
+- **Capped at 50 distinct files** so a `cl_related` result returning 100
+  importers doesn't inflate the total (the agent wouldn't read all 100
+  without the tool).
+
+**Counterfactual being modeled:** without the index, the agent would `grep` +
+`read` the relevant files (whole-file reads at their real sizes); with the tool
+it got compact handles. The difference is the saved context.
+
+### Fallback (flat proxy)
+
+If the size lookup fails (e.g. index not ready, paths not yet indexed), CodeLens
+falls back to a flat proxy:
+
+```
+saved = max(0, handles × 4096 − bytesServed)
+```
+
+where `4096` is a rough average file size and `handles` = number of result
+entries. This is the older, less-accurate estimate, kept only as a graceful
+fallback.
+
+## Honest limits
+
+1. **It's a counterfactual estimate, not a measurement.** We don't know exactly
+   which files the agent *would have* read without the tool — we assume the
+   result files, whole.
+2. **Whole-file assumption.** We credit the full file size, but a raw `read`
+   might be partial, or the agent might read only the relevant part — so the
+   estimate can overstate for large files with small relevant regions.
+3. **No grep-output cost.** It ignores the bytes `grep` itself would have dumped
+   into context, which would make the real saving *larger*.
+4. **No multi-round exploration.** It counts one call, not the exploration
+   rounds the agent avoids.
+5. The 50-file cap is a judgment call to curb broad relationship/impact results.
+
+Net: treat `saved(est)` as an order-of-magnitude indicator of how much context
+the index tools are sparing, not an audited figure.
+
+## Storage
+
+Usage is **global** (`~/.codelens/usage.db`), aggregated across all repos, with
+a `(tool, repo_id)` key so `cl_usage` can break it down per repo. It survives
+restarts and core-index rebuilds (it's separate from the per-branch index DBs).
+
+Reset with `cl_usage` is not exposed as a tool; from code, `UsageTracker.reset()`
+clears it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fodx/codelens",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Local, branch-aware code search & relation graph. SQLite FTS5 + tree-sitter symbols + source-graph edges, exposed as an MCP server and CLI. No chat LLM required.",
   "license": "MIT",
   "type": "module",
@@ -39,8 +39,10 @@
     "adapters/pi",
     "README.md",
     "docs/agent-guide.md",
+    "docs/how-it-works.md",
     "docs/routing.md",
     "docs/tools.md",
+    "docs/usage-metrics.md",
     "docs/codelens-preview.png"
   ],
   "pi": {
@@ -58,7 +60,8 @@
     "mcp:smoke": "node build/src/server.js --smoke",
     "start": "node build/src/server.js",
     "benchmark": "npx tsx bench/run.ts",
-    "quality": "npx tsx bench/quality.ts"
+    "quality": "npx tsx bench/quality.ts",
+    "eval:agent": "npx tsx bench/agent-eval.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",