Skip to content
Back to search

nestweaver

Your codebase as a queryable graph for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kehl-io--nestweaver/badge.svg)](/listings/kehl-io--nestweaver)

HTML

<a href="/listings/kehl-io--nestweaver"><img src="/api/listings/kehl-io--nestweaver/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the CLI

Upgrading an existing database? [Stop the old daemon and back up with the previous binary first](#upgrading--re-index-before-you-trust-a-ranking).

With **Node.js 18+** on macOS 13.3+ or Linux with glibc 2.35+ (x86_64 or arm64):

npm install --global nestweaver
nestweaver --version

npm installs the matching prebuilt binary as an optional dependency; no Rust compiler or install-time script is needed. Keep optional dependencies enabled. Windows and musl/Alpine do not have published binaries. For a verified GitHub Release archive or a source build, see [Install](#install) and [INSTALL.md](INSTALL.md).

2. Index and query your repository

Run these commands **from your repository root**:

nestweaver index --repo . --db "$(pwd)/nestweaver.lbug"
nestweaver search "main" --db ./nestweaver.lbug
# Replace processPayment with a symbol name found in your search results
nestweaver context processPayment --db ./nestweaver.lbug

`search` finds symbols by name; `context` returns related symbols and their relationships around a name, UID, or repo-relative file path. The database and its sidecars stay on disk so subsequent queries can reuse the index. A local background daemon owns the database and starts automatically on first use.

Index reports its selected database target on stderr unless `--quiet` is set; the target is not a field in the `--json` payload. When querying from another directory, pass the same **absolute database path** with `--db`. The first command uses an absolute path for daemon startup. Explicit `--db` keeps these examples bound to the same graph even if you have other instances configured.

3. Connect your AI coding tool (optional)

From the same repository root:

nestweaver setup --db "$(pwd)/nestweaver.lbug"
# Or choose a specific installed integration:
nestweaver setup claude-code --db "$(pwd)/nestweaver.lbug"

`setup` detects supported tools and writes their MCP registration and instructions. Use an absolute database path so clients launched from another directory still query the same graph. It supports 16 integrations, including Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot in VS Code. Most config files are written in the repo; Windsurf uses its user-level config, and Cline gets a printed snippet to paste. `setup` attempts every tool, lists what it wrote for each, and exits non-zero if any tool failed. Restart or reload your client and check its tool list to confirm activation. Cursor gets the six-tool lite set; other MCP integrations use the full set. For a client you configure manually, launch `nestweaver mcp --db /absolute/path/to/nestweaver.lbug` as its stdio server; see [MCP Server](#mcp-server) for tool filtering and lifecycle details.

> The first interactive `index` run from inside your repo also offers setup. > The prompt is skipped in CI, scripts, and non-TTY runs; `index --setup` > explicitly requests setup at the indexed repo root. Use `setup --force` only > when you want to overwrite customized skill/guide files or rebind an existing > registration to a different `--db` (a changed `--db` is reported otherwise). > It never overwrites `.github/copilot-instructions.md`, or an `AGENTS.md` > without NestWeaver's begin/end markers.

# Keep the graph current as you edit (runs until interrupted)
nestweaver watch . --db ./nestweaver.lbug

Run `nestweaver --help` for the full command list. Most commands support `--json` for machine-readable output. Existing users should read the upgrade notes below before using an older database with a new binary.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,421 lines
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/logo-full-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/logo-full-light.svg">
  5. <img src="assets/logo-full-dark.svg" width="400" alt="NestWeaver">
  6. </picture>
  7. </p>
  8. <p align="center">
  9. <strong>Your codebase as a queryable graph — built for AI agents.</strong>
  10. </p>
  11. <p align="center">
  12. <a href="https://github.com/Kehl-io/nestweaver/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Kehl-io/nestweaver/ci.yml?branch=main&label=CI&style=flat-square" alt="CI"></a>
  13. <a href="https://github.com/Kehl-io/nestweaver/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License"></a>
  14. <a href="https://github.com/Kehl-io/nestweaver/releases"><img src="https://img.shields.io/github/v/release/Kehl-io/nestweaver?style=flat-square&label=release" alt="Latest Release"></a>
  15. <img src="https://img.shields.io/badge/rust-stable-orange?style=flat-square" alt="Stable Rust for source builds">
  16. </p>
  17. <p align="center">
  18. <a href="https://nestweaver.kehl.io">Website</a> · <a href="https://docs.nestweaver.kehl.io">Docs</a> · <a href="https://www.npmjs.com/package/nestweaver">npm</a> · <a href="https://github.com/Kehl-io/nestweaver/releases">Releases</a>
  19. </p>
  20. <p align="center">
  21. NestWeaver indexes source code and Markdown into a local knowledge graph.<br>
  22. Search symbols, trace callers and dependencies, and get task-focused context<br>
  23. from the CLI or your AI coding tool through MCP.
  24. </p>
  25. NestWeaver uses Tree-sitter to parse 32 languages and resolves cross-file
  26. references with confidence scores. Its graph helps you explore an unfamiliar
  27. repository, assess a change's impact, and give an agent relevant symbols and
  28. relationships. Indexing and structural queries run locally; semantic embeddings
  29. and shared-server connections are optional.
  30. [Quick Start](#quick-start) · [Install options](#install) ·
  31. [CLI reference](#cli-reference) · [MCP server](#mcp-server) · [Agent setup verification](docs/guide/agent-integration.md) ·
  32. [Upgrade guidance](#upgrading--re-index-before-you-trust-a-ranking)
  33. ---
  34. <p align="center">
  35. <img src="assets/demo.svg" width="700" alt="NestWeaver terminal demo">
  36. </p>
  37. <p align="center"><em>Index a repo and query it in seconds</em></p>
  38. ---
  39. <table>
  40. <tr>
  41. <td width="50%" valign="top">
  42. **32 Languages**<br>
  43. Tree-sitter parsing for JS, TS, Go, Python, Rust, Java, C/C++, Lua, Scala, Elixir, Zig, Vue, Svelte, and 18 more. Tracks CALLS, IMPORTS, USES, and ACCESSES edges. Resolves monorepo workspaces and tsconfig path aliases. As of 9.0.0 `.h` files are parsed with the **C++** grammar (they used to get C, which has no `class` keyword) and C++ `#include` resolves to real `IMPORTS` edges.
  44. </td>
  45. <td width="50%" valign="top">
  46. **Markdown Brain**<br>
  47. Index Obsidian vaults alongside code. Unified knowledge graph across notes and symbols.
  48. </td>
  49. </tr>
  50. <tr>
  51. <td width="50%" valign="top">
  52. **Intent-Aware Context**<br>
  53. Personalized PageRank with per-edge-type weights (CALLS, IMPORTS, USES, ACCESSES) and `--intent` tuning surfaces exactly the symbols relevant to your task.
  54. </td>
  55. <td width="50%" valign="top">
  56. **43-Tool MCP Server**<br>
  57. Model Context Protocol tools for AI agents. Drop-in for any MCP client, lite mode for Cursor. Daemon architecture enables concurrent access from multiple AI tools without lock contention.
  58. </td>
  59. </tr>
  60. <tr>
  61. <td width="50%" valign="top">
  62. **PR Impact & Dead Code**<br>
  63. Confidence-weighted blast radius with `impact_score` decay through edges; co-change mining from git history (Jaccard-scored file pairs); type-aware call resolution via AST-extracted type bindings; dead code detection with type exclusion and manifest-driven entry points; hub/bridge analysis and graph export.
  64. </td>
  65. <td width="50%" valign="top">
  66. **16 AI Tool Integrations**<br>
  67. One-command setup for Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot in VS Code, Aider, Kiro, and more. Also offered automatically on the first interactive in-repo `index`.
  68. </td>
  69. </tr>
  70. <tr>
  71. <td width="50%" valign="top">
  72. **Agent Interaction Memory**<br>
  73. Opt-in usage tracking that learns from what agents actually use. It re-ranks only the nodes a query's walk already reached, by at most +5%, and never adds a node the seed cannot reach. Privacy-first: local-only, records UIDs and timestamps only, no content capture. Enable with `--track-interactions`.
  74. </td>
  75. <td width="50%" valign="top">
  76. </td>
  77. </tr>
  78. </table>
  79. ## Quick Start
  80. ### 1. Install the CLI
  81. Upgrading an existing database? [Stop the old daemon and back up with the
  82. previous binary first](#upgrading--re-index-before-you-trust-a-ranking).
  83. With **Node.js 18+** on macOS 13.3+ or Linux with glibc 2.35+ (x86_64 or
  84. arm64):
  85. ```sh
  86. npm install --global nestweaver
  87. nestweaver --version
  88. ```
  89. npm installs the matching prebuilt binary as an optional dependency; no Rust
  90. compiler or install-time script is needed. Keep optional dependencies enabled.
  91. Windows and musl/Alpine do not have published binaries. For a verified GitHub
  92. Release archive or a source build, see [Install](#install) and
  93. [INSTALL.md](INSTALL.md).
  94. ### 2. Index and query your repository
  95. Run these commands **from your repository root**:
  96. ```sh
  97. nestweaver index --repo . --db "$(pwd)/nestweaver.lbug"
  98. nestweaver search "main" --db ./nestweaver.lbug
  99. # Replace processPayment with a symbol name found in your search results
  100. nestweaver context processPayment --db ./nestweaver.lbug
  101. ```
  102. `search` finds symbols by name; `context` returns related symbols and their
  103. relationships around a name, UID, or repo-relative file path. The database and
  104. its sidecars stay on disk so subsequent queries can reuse the index. A local
  105. background daemon owns the database and starts automatically on first use.
  106. Index reports its selected database target on stderr unless `--quiet` is set;
  107. the target is not a field in the `--json` payload. When querying from another
  108. directory, pass the same **absolute database path** with `--db`. The first
  109. command uses an absolute path for daemon startup. Explicit
  110. `--db` keeps these examples bound to the same graph even if you have other
  111. instances configured.
  112. ### 3. Connect your AI coding tool (optional)
  113. From the same repository root:
  114. ```sh
  115. nestweaver setup --db "$(pwd)/nestweaver.lbug"
  116. # Or choose a specific installed integration:
  117. nestweaver setup claude-code --db "$(pwd)/nestweaver.lbug"
  118. ```
  119. `setup` detects supported tools and writes their MCP registration and
  120. instructions. Use an absolute database path so clients launched from another
  121. directory still query the same graph. It supports 16 integrations, including Claude Code, Cursor,
  122. Codex, Gemini CLI, and GitHub Copilot in VS Code. Most config files are written in the repo;
  123. Windsurf uses its user-level config, and Cline gets a printed snippet to paste.
  124. `setup` attempts every tool, lists what it wrote for each, and exits non-zero
  125. if any tool failed. Restart or reload your client and check
  126. its tool list to confirm activation. Cursor gets the six-tool lite set; other
  127. MCP integrations use the full set. For a client you configure manually, launch
  128. `nestweaver mcp --db /absolute/path/to/nestweaver.lbug` as its stdio server; see
  129. [MCP Server](#mcp-server) for tool filtering and lifecycle details.
  130. > The first interactive `index` run from inside your repo also offers setup.
  131. > The prompt is skipped in CI, scripts, and non-TTY runs; `index --setup`
  132. > explicitly requests setup at the indexed repo root. Use `setup --force` only
  133. > when you want to overwrite customized skill/guide files or rebind an existing
  134. > registration to a different `--db` (a changed `--db` is reported otherwise).
  135. > It never overwrites `.github/copilot-instructions.md`, or an `AGENTS.md`
  136. > without NestWeaver's begin/end markers.
  137. ```sh
  138. # Keep the graph current as you edit (runs until interrupted)
  139. nestweaver watch . --db ./nestweaver.lbug
  140. ```
  141. Run `nestweaver --help` for the full command list. Most commands support
  142. `--json` for machine-readable output. Existing users should read the upgrade
  143. notes below before using an older database with a new binary.
  144. ## Upgrading — re-index before you trust a ranking
  145. **Upgrading an existing database?** Check compatibility before querying it:
  146. Builds with LadybugDB **0.22.3** read the 0.21.2 database format, but a
  147. writable open/checkpoint can upgrade its storage format from 47 to 49. Stop the
  148. old daemon and back up with the previous binary before upgrading. To downgrade, reinstall that
  149. binary and restore the pre-upgrade backup; do not point it at the upgraded file.
  150. See the [storage upgrade guidance](docs/guide/publication-rebuild.md#ladybugdb-022-storage-format-and-rollback).
  151. Previous release 12.2.6 uses resolver generation **22** and parsed cache **16**.
  152. LadybugDB 0.22.1 is unchanged from 12.2.5.
  153. Anonymous JavaScript/TypeScript default functions now own calls in their bodies;
  154. Svelte, Vue and Astro function spans skip destructured/default parameters.
  155. Generation 21/cache 15's PHP static-method ownership and inheritance facts and
  156. the preceding Dart/PowerShell grammar updates remain included. Force re-index each repository once after
  157. upgrading to publish the new parser facts; invalidating the parse cache alone
  158. does not replace symbols and edges already stored in the graph.
  159. 12.2.7 uses LadybugDB 0.22.3 (the same storage format 49), resolver
  160. generation **23** and parsed cache **17**. Scala grammar 0.26.9 repairs Scala 2
  161. `given`/`enum` identifiers and other grammar boundaries. Force-index each
  162. repository once after upgrading from generation 22 as well.
  163. Canonical publication PageRank now consistently covers the unified code and
  164. notes graph after indexing, watching and rebuilding. Older canonical sidecars
  165. with a code-only scope are disclosed and recomputed lazily on the first ranked
  166. query; no graph rebuild is required for this ranking migration alone. Explicit
  167. scoped ranking APIs retain their requested scope.
  168. `daemon status --json` reports both client and daemon resolver generations.
  169. An older daemon without this provenance reports `null`; differing builds with
  170. the same product version disclose skew without automatically replacing a writer.
  171. - A database from before LadybugDB 0.21 needs a **publication rebuild**, not
  172. just a forced index. Back it up and follow the error's recovery command and
  173. [storage-engine upgrade guide](docs/guide/publication-rebuild.md#storage-engine-upgrade-ladybugdb-021-rebuild-required).
  174. - For a compatible database, run `nestweaver stale-check --db <db>`. 12.2.7
  175. requires resolver generation **23** (12.2.6 used **22**). If your binary reports a generation-stale graph, run
  176. `nestweaver index --repo <path> --db <db> --force` for each repository.
  177. A plain incremental index does not repair generation-stale graphs.
  178. - Generation 16 preserves declaring-package origin through Go factory-call
  179. receiver chains and revisits unchanged importers when Go package methods are
  180. added or recreated. Existing graphs may retain missing CALLS edges until the
  181. forced index above.
  182. - Generation 17 confines Go initializer and case-clause bindings to their
  183. statement or clause, restoring valid calls after those scopes end. Cached
  184. parses are invalidated to discard the old lexical lifetimes; existing graphs
  185. need the forced repository index above. Resolution-dependency format is unchanged.
  186. - Generation 18 and parsed cache 12 invalidate Scala parses from
  187. before the grammar 0.26.3 update, which recovers declarations such as local
  188. case classes and Scala 2 `export` identifiers. After upgrading to a release
  189. containing this change, force re-index each repository using the command above.
  190. An unchanged incremental run does not repair an older graph; `stale-check`
  191. continues to report it as outdated until the forced index succeeds.
  192. - 12.2.4 generation 19 and parsed cache 13 additionally repair PHP function
  193. resolution by namespace across directories, including `use function` aliases
  194. and duplicate refusal. Existing graphs need the forced repository index above.
  195. PHP changes conservatively re-resolve repository PHP callers because a new
  196. declaration can satisfy a previously unresolved call or create ambiguity.
  197. Ordinary index/watcher scans reuse valid cached parses; Git/server incremental
  198. repair reparses PHP peers. No-change runs remain no-ops.
  199. - Markdown derivation version 3 repairs percent-encoded Markdown URL paths and
  200. proven absolute in-vault note paths. Eligible vaults disclose stale derivation
  201. until re-derived; run `nestweaver brain refresh <vault> --db <db>` after upgrading.
  202. This is separate from repository resolver generation; literal wikilinks keep
  203. their existing spelling semantics.
  204. - The current source also infers method receivers from typed Go slice range
  205. elements, including qualified types and exact factory returns. Generation 14
  206. requires the same forced repository re-index to add the missing call edges;
  207. generation15 additionally handles inferred `var` slices, parenthesized range
  208. sources and single named factory results. Parsed cache10 reparses unchanged
  209. declarations for normalized return types and complete var/const/parameter shadow guards.
  210. - **Upgrading to 12.2.7 needs a forced re-index of every repository.** Run
  211. `nestweaver index --repo <path> --force` once per repository, using your usual
  212. `--db` and `--config` bindings. Plain incremental indexing can leave an
  213. unchanged graph on its old generation. `stale-check` exits 2 until repaired.
  214. - **Refresh registered vaults if crossing the earlier Markdown derivation upgrade.** Run
  215. `nestweaver brain refresh <vault>` with the same bindings to re-derive
  216. note-to-code relationships against the rebuilt graph. If upgrading from before
  217. 12.2.2, this also repairs frontmatter wikilinks and block references.
  218. - New databases do not need migration. Vaults do not carry a code resolver
  219. generation; see the detailed notes for separate Markdown derivation changes.
  220. <details>
  221. <summary>Detailed migration notes and changes for scripts and server clients</summary>
  222. **12.2.6 uses `RESOLVER_GENERATION` 22; 12.2.5 used 21. Every
  223. graph indexed by a generation different from the running binary must be re-indexed.** Compatibility is an EXACT MATCH, not a floor, so a graph written
  224. by any other generation — older or newer — is treated as untrustworthy.
  225. 9.0.0 took it from 3 to 4, and generations 5 and 6 followed. The 9.0.0 bump
  226. changed edge SHAPE; 5 and 6 changed which symbols are persisted as ENTRY
  227. POINTS, which is what `dead-code` walks from. Generation 7 (nw-687) adds
  228. missing CALLS/definition edges for CommonJS `module.exports.X`/`exports.X`
  229. function definitions, which a stale graph is missing entirely. Generation 8
  230. (nw-688) renames JS/TS test-runner blocks so `describe('getTier')` no longer
  231. shadows the real `getTier`. Generation 9 replaces file-level import proxies with
  232. actual binding users, corrects receiver and export resolution, and persists
  233. exported executable roots. Upgrading from generation 8 requires a forced
  234. re-index of every repository; `stale-check` exits 2 and `dead-code` refuses
  235. until the graph matches. Generation 10 (nw-113) restricts a block-scoped
  236. JS/TS callable to its block, and gives the calls a JS/TS/Python/PHP file makes
  237. at its top level a per-file `<module>` owner (parsed cache 6). The same bump
  238. carries these JS/TS parser and resolver fixes:
  239. | Change | Effect on the graph |
  240. | --- | --- |
  241. | Generators (`function*`, `async function*`, `const g = function* …`, CommonJS `exports.g = function*`) are `Function` symbols (nw-791) | Their callers gain edges; their body calls are no longer top-level code |
  242. | Generators scope their parameters and `var`s | A generator's parameter no longer shadows a same-named module function |
  243. | A `.js` bare-parameter arrow (`const f = x => …`) is a function | It was a `Constant`, so its callers had no edge |
  244. | A `catch (f)` parameter and a `for` loop variable are scoped to their clause (nw-800) | `f()` inside them no longer binds a same-file `f` |
  245. | An unparenthesised arrow parameter (`f => f()`) is scoped to its arrow, like `(f) => f()` | `[1].map(g => g())` no longer gives a false edge to an imported `g` |
  246. | ESM import bindings are hoisted to the top of their scope (nw-803) | A function written above an `import` sees the binding. A function above a CommonJS `require` sees it too, including an expression-body arrow (`const fb = () => f()`); top-level code above the `require` does not |
  247. | TS `import x = require('m')` and `export import x = require('m')` bind like an import (nw-801) | Calls through `x` resolve. A bare call on a whole-module binding (`x()`) is unresolved |
  248. | `.ts` and `.tsx` keep their own type bindings (nw-805) | `type_aware` edges are deterministic; on mixed `.ts`/`.tsx` repos they may differ from 12.0.x |
  249. | A broken file with no real symbols gets no owner; a lowercase JSX tag (`<div/>`) never mints one | Such files stay disclosed as parse errors and add no empty owners |
  250. | A top-level call through an import written below a one-line function resolves (JS/TS/Python/PHP), and a sibling's nested homonym no longer hides the caller's own nested function | Those calls keep their edges |
  251. | A member access or call through an imported receiver (`Modal.latestProps` after `import { Modal }`) never binds a same-file symbol of the member's name | The false self-`ACCESSES` edge in a file named like its import (`Modal.test.js`) is gone |
  252. | `.mjs`/`.cjs` files are indexed as JavaScript and `.mts`/`.cts` as TypeScript; an extensionless import also reaches them, a directory import reaches its `index.mjs`/`.cjs`/`.mts`/`.cts`, and `index`, `main`, `app` and `server` files in those extensions are entry files like their `.js`/`.ts` twins | Those files, and the calls into them, appear in the graph |
  253. Generation 11 (nw-787, nw-789) scopes a nested JS/TS `function` declaration to
  254. where it is visible, stops a bare JS/TS call binding a method or accessor,
  255. scopes a Python `def` nested in a function to that function, and gives a nested
  256. class's members `MEMBER_OF` their own class (parsed cache 7). Graphs indexed at
  257. generation 9 or 10 need the same forced re-index.
  258. Generation 12 resolves imports by package instead of by file name, and
  259. resolves more method calls (parsed cache 8):
  260. | Change | Effect on the graph |
  261. | --- | --- |
  262. | Go imports read `go.mod`, `go.work` and local `replace` lines, map an import to every non-test file of the package, and honour import aliases. Files marked `//go:build ignore` (or `// +build ignore`) are left out of package resolution | Cross-package calls in a real Go module resolve; they did not before |
  263. | Go methods carry their receiver type (`MEMBER_OF` edges), and every build-tag variant of a function is a callee (except `ignore`-tagged files) | Typed Go method calls resolve, and `Type::method` names look up |
  264. | Python `from . import mod`, `from pkg import mod as m`, `import pkg.mod as m` and aliased re-exports through `__init__` bind the submodule or definition | Those calls gain edges |
  265. | Kotlin and Java imports resolve through the declared package (any file of it, wildcard imports, nested classes), not a file named after the symbol, with the language's precedence: a single-type import, then a type in the same package, then an on-demand (`*`) import. A single-type import brings in only the declaration it names | Imports of classes in differently named files resolve, and a same-package type is no longer shadowed by a wildcard import |
  266. | A method called on a call or `new` receiver (`new K().m()`, `K.make().m()`, chains) resolves through the declared return type. Where the receiver is not typed, a method links only when its name is unique in the repository AND every step of the receiver chain has a repository return type (or plainly returns `Name(..)`, `new Name(..)` or `cls(..)`) that is the method's owner or a subtype, so `A.find().get()` on an `Optional`, `.size()` on a `List` or `.then()` on a `Promise` does not link to a same-named repository method. Kotlin/Scala expression-body factories, Ruby implicit returns, multi-line returns and methods returning `self` are deliberately not typed | More method calls gain edges, conservatively; library-typed chains stay unlinked |
  267. | `new Foo()` links the class in Java, C#, PHP, C++, Scala, Groovy and Dart; Rust trait default methods and turbofish calls resolve; a bare TS/JS `@decorator` references its function | Constructors, trait defaults and decorators are no longer unreachable |
  268. | Duplicate JS/TS `this.x =` properties collapse to one symbol, and a bodiless Rust `mod x;` no longer owns the lines below it | Fewer duplicate symbols and no false `IMPORTS` edges |
  269. Generations 13–17 add nested Go module and receiver ownership, typed slice
  270. range elements, inferred slice and named-return forms, factory-call receiver
  271. origins, recovery when package members are recreated, and correct if/switch/case
  272. binding lifetimes. 12.2.3 includes all of these changes (parsed cache 11).
  273. Existing missing edges require the forced re-index described above.
  274. All these kinds of staleness have the same remedy and the same symptom list.
  275. Until you re-index:
  276. - **Rankings are stale.** `hubs`, `bridges`, `repo-map`, `clusters`, and every
  277. PageRank-ordered result are computed over edges the old resolver wrote.
  278. - **`MEMBER_OF` edges are missing** for C and C++ members, so reachability
  279. under-counts. `dead-code` **refuses to answer** on such a graph and exits `2`
  280. rather than printing a deletion list built from missing edges.
  281. - **C++ `IMPORTS` edges are missing.** The resolver used to extract `#include`
  282. and then discard it.
  283. - **`.h` headers were parsed with the C grammar**, which has no `class` keyword.
  284. Re-indexing routes them to C++: on a real 874-header corpus, header symbols
  285. went 7,166 → 17,872 and `class` definitions 0 → 1,373.
  286. ```sh
  287. nestweaver index --repo <path> --force # per repo — a full index, not incremental
  288. ```
  289. **`--force` is required.** A generation-stale repo is sitting exactly at git
  290. HEAD with every file unchanged, so plain `nestweaver index --repo <path>` takes
  291. the incremental path, reports `0 added, 0 modified, 0 deleted`, writes nothing,
  292. and leaves the repo on the old generation. Only a full re-index rewrites the
  293. edges.
  294. Vaults are not `Repo` nodes and carry no resolver generation, so the forced
  295. re-index does not touch them. When crossing the 12.2.4 Markdown derivation change, run one
  296. `brain refresh <vault>` per vault to re-derive links against the rebuilt code graph.
  297. **`stale-check` detects this as of 9.0.0.** A repo whose edges predate the
  298. running resolver reports `status: "outdated_resolver"`, `needs_reindex: true`,
  299. and the command exits **2** — the same code it already used for
  300. `stale`/`incomplete`/`missing`, so an existing CI gate catches the upgrade with
  301. no edit:
  302. ```sh
  303. nestweaver stale-check # [OLD-RESOLVER] rows + the remedy, exit 2
  304. nestweaver stale-check --json # "resolver_stale_repos": [...], per-repo "resolver_stale"
  305. cat <db>.resolver_generation.json # per-repo generation; anything that is not the current one is stale
  306. ```
  307. In 8.x it did not: the status ladder was `missing`/`incomplete`/SHA-behind-HEAD
  308. only, so a generation-3 graph reported `ok` and exited 0.
  309. Generations 5 and 6 turned on PERSISTED PER-SYMBOL COLUMNS rather than edge
  310. shape: `is_entry_point` and `entry_point_kind` are read straight off disk, so a
  311. symbol indexed as `false` stays `false` no matter which binary asks. Generation
  312. 6 roots bash and Python top-level calls, Swift `main.swift`/shebang files, bash
  313. `trap` handlers, and `package.json` entry points at any depth in a monorepo.
  314. Those additions can only ADD reachability roots, so they can only REMOVE
  315. symbols from a `dead-code` list — an un-re-indexed graph over-reports dead
  316. code.
  317. `hubs`, `bridges`, `repo-map`, `ranking rank` and `summary --level hub` also
  318. disclose it (`rankings_stale` / `stale_repos` on `--json`, a warning on stderr
  319. otherwise). Other ranking-derived surfaces still do not — `clusters`,
  320. `blast-radius`, `generate-guide`, PPR-backed `context`, and the whole web UI —
  321. so on those, absence of a warning is not evidence of freshness.
  322. ### `_meta` moved to the payload and lost its `nestweaver.io/` prefix
  323. **Only affects raw HTTP MCP clients that read result metadata.** The CLI, the
  324. MCP stdio server and the daemon are unchanged for callers.
  325. Through 8.x the HTTP `/mcp` boundary stamped provenance onto the **outer
  326. `tools/call` envelope** under namespaced keys — `nestweaver.io/sources`,
  327. `nestweaver.io/scope`, `nestweaver.io/stale_repos`. It is now written once, at
  328. the tool layer, as an unprefixed `_meta` object **on the result payload**:
  329. ```jsonc
  330. // 8.x — outer envelope
  331. { "result": { "_meta": { "nestweaver.io/sources": ["local"] }, "content": [...] } }
  332. // 9.0.0 — on the payload itself
  333. { "map": "...", "_meta": { "scope": "local", "sources": ["local"], "stale_repos": [] } }
  334. ```
  335. A client reading `result._meta["nestweaver.io/sources"]` gets nothing. Read
  336. `_meta.sources` on the payload instead. The payload location is what the
  337. server's own `initialize` instructions have always promised and what both CLI
  338. routes already emitted; the envelope was the odd one out, and MCP over stdio
  339. sent no provenance at all.
  340. Note that `_meta.stale_repos` is **federation** staleness (which upstreams were
  341. behind). It is a different population from the top-level `stale_repos` on
  342. `hub_nodes` / `repo_map`, which is resolver-generation staleness, and from
  343. `stale_repos` on `stale_check`, which is behind-HEAD.
  344. ### Daemon bypass is CI-only
  345. Standard development and distributed binaries cannot honor `--no-daemon`,
  346. `NESTWEAVER_NO_DAEMON`, or an explicit permit. Refused requests print a warning
  347. and keep the normal daemon route.
  348. Only a separate internal CI test artifact may enable direct-store tests. It
  349. requires the `ci-direct-tests` build feature, `NESTWEAVER_ALLOW_NO_DAEMON=1`,
  350. and a GitHub Actions runner context (`GITHUB_ACTIONS=true` plus nonempty
  351. `RUNNER_TEMP`, `RUNNER_OS`, and `GITHUB_RUN_ID`). Ambient `CI=true` never grants
  352. access, including when set locally. This artifact must never be published.
  353. Local development, fixtures, debugging, and recovery use the daemon; setting CI
  354. locally is not an exception. See [release fixture instructions](docs/testing/release-daemon-fixtures.md).
  355. Note that `hubs --json` carries two different `stale_repos`: the **top-level**
  356. one is resolver-generation staleness, and `_meta.stale_repos` is federation
  357. staleness (repos where the *local* index is behind an upstream server). They
  358. answer different questions and can disagree.
  359. Also changing behaviour in this release, in ways a script may notice:
  360. | Change | What to do |
  361. | --- | --- |
  362. | **Re-index and refresh required (12.2.2).** `RESOLVER_GENERATION` moves from 11 to 12 and the parsed cache from 7 to 8 (Go, Python, Kotlin/Java import resolution; method calls on call or `new` receivers; `new Foo()` edges; see the generation 12 table above). The filemeta and resolution-deps sidecars move from 4 to 5, so the first index after upgrading rebuilds in full. Vault link fixes (frontmatter `[[wikilink]]` relationships, `[[Note#^id]]` block references) apply only when a vault is re-derived, and the Markdown derivation version did not change, so that does not happen by itself | Run `nestweaver index --repo <path> --force` once per repo and `nestweaver brain refresh <vault>` once per vault; until the re-index `stale-check` exits 2, `dead-code` refuses and `blast-radius` misses the new edges |
  363. | `affected-tests` diffs one repository. With `--base-ref` it is the indexed repo checked out at the working directory's git root; with `--files` it is the only indexed repo, and when several are indexed the new `--repo <name or UID>` is required (exit **64** otherwise). Repo-relative paths resolve only in that repo, and `--json` names it. MCP `affected_tests` takes `repo` the same way and refuses `files`/`changed_files` together with `base_ref` (it used to ignore `base_ref`) | Pass `--repo` (MCP `repo`) when more than one repo is indexed; send either changed files or a base ref, not both |
  364. | `daemon status` exits **69** when the daemon is unhealthy (running but unreachable, or an owner it cannot verify). `setup` attempts every tool and exits non-zero if any failed. `remove-repo` with an ambiguous name exits **3**. An empty query argument exits **64**, and so do `pre-push-impact` with a bad `--format` or `--min-severity`, `list-features` without `--config` and `interactions show` with no arguments. `memory consolidate --apply` with nothing to apply exits 0. A database error under `--json` prints a JSON envelope | Treat 69 as "restart the daemon" (`nestweaver daemon --db <db> restart`), 64 as a usage error |
  365. | An explicit `read-symbols --root` (MCP `root`) must be inside an indexed repository or vault, or a linked worktree of one. A body read never follows a symlink out of the repository, and the web `/source` route walks from the repo root without following symlinks | Omit `--root`, or point it at the indexed checkout |
  366. | Git runs isolated for every repository NestWeaver reads, including `pre-push-impact --local-changes`, the code watcher and `blast-radius`. The repository's `core.fsmonitor`, hooks, clean/smudge/process filters, textconv and external-diff drivers, `core.askPass` and signature verification never run; a repository whose driver configuration cannot be listed is refused. Working-tree `status`/`diff` calls pass `--ignore-submodules=dirty`, so a submodule's own filters never run either (a moved gitlink still counts as changed; submodule contents were never indexed). A file a repo-local filter (for example Git LFS installed with `--local`) would have normalised may now show as modified in change detection | Nothing to change for normal repositories; expect LFS-tracked files to appear modified where a filter used to hide the difference |
  367. | Git metadata a repository borrows from another (a forged `.git/commondir`, a gitfile into another repo) is refused, and such a layout never takes the other repo's identity. `/proc`, `/sys`, `/dev` (at any depth) and other system roots are refused as repo or vault roots, and an instance id containing `/`, `\` or `..` is rejected | Index the real checkout, not a path through a pseudo-filesystem |
  368. | An unreadable source in a language that cannot carry API contracts is skipped and disclosed (`read_error` row, `coverage_status: "degraded"`) instead of failing the index or watcher batch. An unreadable JS/TS/Java/Kotlin source still fails closed, because skipping a controller would publish an incomplete contract set. A file that vanishes mid-scan is a deletion. A malformed OpenAPI spec that never published contracts is skipped and disclosed instead of failing every index | Gate on `coverage_status` / `--fail-on-skip`; fix the named file's permissions |
  369. | Edits to `.gitignore`, `.ignore` and `.git/info/exclude` are reconciled: newly hidden sources leave the graph and newly visible ones are indexed, at watcher time and at startup. Global-excludes patterns with a slash are anchored at the repo root. A watcher that cannot publish, an interrupted vault refresh and an interrupted embedding pass now show in `brain status` until they finish | Nothing to change |
  370. | An incremental index that was killed part-way leaves a per-repo "publication incomplete" record: `stale-check` reports the repo `incomplete` and the next index rebuilds it in full. A full index whose bulk-load checkpoint fails now fails instead of reporting success. A daemon whose database file was deleted or replaced refuses writes | Re-run `nestweaver index --repo <path>` for a repo `stale-check` reports `incomplete` |
  371. | Client-supplied lists and values are capped and stated in each MCP tool's `inputSchema`: context `seeds` at most 256 (duplicates collapsed), `kinds` 32, repo/tag filters 100 (1000 for `hub_nodes`/`bridge_nodes`), file lists 1000, `count_patterns.patterns` 64. `set_extension`: uid 1 KiB (not blank, no invisible format or bidi characters such as U+202E), key 256 bytes, value 64 KiB of JSON nested at most 64 deep, no control characters, the sidecar written as compact JSON, `last_indexed_at` reserved, node and property counts capped. `brain_add_source` names: 1-255 characters with no control characters (CLI and store too; an already-stored bad name is listed escaped and can be removed by path or UID). MCP stdio frames are capped at 64 MiB | Split oversized requests; read the limits from `tools/list` |
  372. | `brain_remove_source` refuses a target that matches sources of different kinds (a repo and a vault sharing a name) or several sources, with `candidates`; repo URLs match exactly (no suffix match). It also accepts the derived repo name the other tools use. `prune_stale` removes a source only when its root is not found; an unreadable root is kept with a warning | Retry with a UID from `candidates` |
  373. | Metadata writes (`set_extension`, `unset_extension`, `interactions forget`) wait at most `NESTWEAVER_METADATA_WRITE_WAIT_SECS` (default 15) for the write lock, then answer `write-busy`; a cancelled request is never applied. MCP `count_patterns` has one `max_millis` budget for the whole call (default 10 s), shared by all patterns, and marks a pattern it cut `truncated: true` with lower-bound counts. The CLI's `count-patterns` takes the same budget as `--max-millis` (1-600000) and, when the budget cuts any pattern, prints a stderr warning and exits **75** (`EX_TEMPFAIL`) instead of 0 | Retry a `write-busy` answer; raise `max_millis` (`--max-millis`) for a large pattern set, and treat exit 75 as lower-bound counts |
  374. | `brain_context` and `brain_search` rank an exact-case symbol match first and apply repo filters before the result cap. `regex_search` without a trigram index finds what `count_patterns` finds. `blast_radius` gives the same risk on identical calls. Concise MCP rows keep `uid` and location, so they are larger | Nothing to change; budget for slightly larger concise responses |
  375. | New response fields: `missing_sections` (`note_get`), `did_you_mean_by_target` (`read_symbols`), `changed_symbol_count`, `proposals_already_applied` (`brain_memory_consolidate`, whose `limit` is now applied before any proposal moves), `refresh_vault_paths`, `truncated` on pattern counts, and `publication_in_progress`. `note get`, `backlinks` and MCP `note_get` resolve a path-qualified title without `.md`; `[[Note#^id]]` block references resolve | Read the new fields where useful; they are additive |
  376. | `contracts diff` reports parameter and response-status changes, and `--fail-on-breaking` fails on them | Review the newly reported changes before gating |
  377. | The CLI sends the daemon absolute `--config`, root and `backup save` paths, and the daemon refuses relative ones. `watch-stop` no longer starts a daemon. Tracing respects `--no-color`, `NO_COLOR` and non-TTY stderr, and an invalid numeric `NESTWEAVER_*` value warns once instead of being silently ignored. Terminal control sequences from indexed content are escaped when stdout is a terminal. Secret env var values no longer appear in `--help` | Nothing to change |
  378. | `backup save --force` refuses a destination that is the live database or one of its files (also through a symlink or hard link), and `backup restore --force` replaces only a NestWeaver data directory. `config validate` checks that fusion weights sum to 1.0, rejects duplicate repos and caps the file size | Pick a backup path outside the database's files |
  379. | `setup` was checked against each tool's documented config location: VS Code and Copilot get `.vscode/mcp.json` under `servers`; Continue gets `.continue/mcpServers/nestweaver.json`; Kiro `.kiro/settings/mcp.json`; Cline gets a printed snippet; Aider's invalid `repo-map:` line is gone. Hook commands quote an absolute `--db`. A changed `--db` is reported and `--force` rebinds it. `setup` refuses to write through a symlinked directory outside the project. The Claude Code hooks (shipped and installed) now read `tool_input` and return `hookSpecificOutput`, so they actually fire; re-running `setup claude-code` repairs an older install | Re-run `nestweaver setup` after upgrading |
  380. | `hooks --install` takes `--db` (written into the hook as an absolute path) and never writes through a symlink. Run from a subdirectory, it binds the repository root's database. It mentions `core.hooksPath` only when that is set. `--uninstall` restores the newest backup only when the installed hook is NestWeaver's; otherwise it leaves the hooks alone | Pass `--db` when the database is not `./nestweaver.lbug` |
  381. | The code watcher now resolves each batch with the full index's resolver over the whole-repository view, so a watcher-maintained graph matches a fresh `index` (re-exports through `__init__.py` and type-aware member calls used to be lost on large batches). A file the batch cannot re-parse keeps its edges. The daemon keeps one parse cache per database in memory and refreshes it each batch | Nothing to change; expect somewhat higher daemon memory on large repositories |
  382. | Claude Code integration: the shipped search hook searches the grep/rg pattern, not the path. The Bash hook `setup` installs fires only when grep, rg, find, fd, ack or ag is the command actually invoked, and does nothing without `jq`. `setup` recognises only the exact hook commands it writes, so a user's similar-looking hook survives a re-run | Re-run `nestweaver setup claude-code` to refresh the hooks |
  383. | `setup trae`, `setup devin` and `setup hermes` write `.trae/config.json`, `devin.json` and `.hermes/config.json`. Those paths are not where the tools read MCP servers (Hermes reads `mcp_servers` in `~/.hermes/config.yaml`; Devin reads `.devin/mcp_config.json` or `~/.config/devin/mcp_config.json`), so the registrations are ignored | Register NestWeaver by hand in those tools' own config until `setup` is fixed |
  384. | Interaction memory (`--track-interactions`) is now a re-rank, not part of the walk. A node the query's walk reached is scaled by at most +5% by how often agents used it; a node the seed cannot reach stays out, however often it was used. Results a query only showed no longer count toward the three-session floor, and the end-of-session success signal reinforces only results the agent then opened (B3). Before this, interacted nodes were teleport targets, so `context` could list dozens of unrelated symbols | Optionally run `nestweaver interactions clear` once to drop sessions recorded under the old rules, whose shown-only results still carry a floor |
  385. | MCP `brain_impact` sends its dependents once, as `impact_nodes`; the duplicate `nodes` list is gone from MCP (the CLI `--json` keeps both). A cut made to fit the output budget is disclosed in `output_budget.cuts`, and `truncated_by_limit` is set only when `limit` was the cause (M3) | Read `impact_nodes` |
  386. | A repo filter that names no repo (`hubs --repo nosuch`, every `--repo` listed below) writes `"error": "not found"` in `--json`, the word every other not-found envelope uses; it was `"not_found"`. `status` still reads `"not_found"` (B6) | Branch on `status`, or on `error == "not found"` |
  387. | New exit codes: `summary --level <invalid>` exits **64** (was 1); `summary --target` matching nothing exits **2** with a not-found message and envelope (was 0, "graph may be empty"); `context --feature <name>` naming no `[[features]]` entry exits **2** and suggests declared names in `did_you_mean` (was 1); `investigate-expand` resolving none of its targets exits **2** (a partial resolution still exits 0); `investigate --scope project:<unknown>` exits **2** and a malformed `--scope` exits **64**, each reported once instead of inside an "Internal error" (B9, V4) | Treat 2 as a miss and 64 as a usage error |
  388. | `pr-impact` reviews one repo: the indexed repo checked out at the working directory's git root, or the one named by the new `--repo <name or UID>`. A repo-relative `--files` path now resolves in that repo only, not in every indexed repo with a file at the same path. When neither names exactly one repo every repo is matched, as before. `--repo` keeps its class on both routes: not found **2**, ambiguous **3** (with `candidates`), over 512 bytes **64**. An empty `--repo ''` is ignored (every repo is matched), and a selector that names nothing, such as `repo:::`, is not found (**2**) (B4) | Run `pr-impact` from the repo under review, or pass `--repo` |
  389. | Web: a `<module>` owner reads `path::<module>` in `/api/v1/symbols/top` (`name` and `display_name`), overview landmark labels, search hits (`name`, `title`, `display_name`) and `snapshot.msgpack` node names; the Cypher export keeps the raw name and adds a `display_name` property (R1, B5) | Read `display_name` where present; do not treat `name` in these responses as the raw symbol name |
  390. | `brain status` reports the daemon's manifest reconciliation as `manifest_recovery` (`state`, `attempts`, `retry_after_seconds`, `error`) and warns while it is `deferred`, `retry_scheduled` or `blocked`. A capture slowed by contention defers the rebuild and refuses no repo; a repo that runs out of its own 60 s budget on 3 passes in a row is refused with a `contention:` reason (no `index --repo` remedy needed) and the other repos publish. The write gate is held for at most 60 s of captures per reconciliation (D3). The text output shows the state too | Nothing to change; a contention refusal clears itself once the repo captures in time |
  391. | A watched vault batch that collides with another writer's transaction retries with backoff (2575 ms in all, the write lease released while it waits). If the collision outlasts the retries the batch's notes are owed and replayed on the retry backoff and at the next start, instead of the watcher exiting; `brain status` lists them under "Watcher reconciliation pending" and shows the daemon's `last_watcher_failure`, which now survives the watcher's restart (also in text) (V1) | Nothing to change; `nestweaver brain refresh` also replays owed notes |
  392. | A note-to-code relink no longer forces a PageRank recompute on every ranked read: the code-only ranks stay warm and `.pagerank.json` is rewritten at the new generation (D1) | Nothing to change |
  393. | A database error is called corruption more carefully. A write-transaction collision, an index publication in flight and a busy daemon are never corruption. A file shorter than its catalog read while another process writes says so and names the next step (if it repeats, `nestweaver daemon --db <db> stop` and re-run); an engine assertion or an unclassified corruption is corruption whether or not the daemon is up, and so is a truncation reported inside a timed-out health check or a refused publication (V2) | Follow the step the message names before restoring a backup |
  394. | `investigate` answers through a live watcher batch with `publication_in_progress`, but does not save that map as a bundle: the result carries `bundle_not_saved` (also printed in text) and its `bundle_id` cannot be expanded or hydrated (V4, I3) | Re-run `investigate` once the batch finishes to get a bundle to drill into |
  395. | A call a JS/TS/Python/PHP file makes at its top level, outside every function, class and method (a bare call, an IIFE, an Express-style route handler, a decorator, a `__main__` guard, a top-level `await`), is now owned by a per-file `<module>` symbol (`Module`, entry point `module_init`). `impact` shows it as the caller, `dead-code` treats it as a root (so a function called only at module load is no longer listed, and `<module>` itself is never listed), and a one-line function above such a call no longer owns it. An owner that calls something is its own process, named `<repo-relative path>::<module>`, so `detect-changes` lists more processes in repos with decorators, route registration or top-level test setup; an owner with no outgoing CALLS is not a process. Name search hides `<module>` unless you search for exactly `<module>`. Resolver generation 10 and parsed cache 6 (nw-113) | Run `nestweaver index --repo <path> --force` for each repo after upgrading; search `<module>` by its exact name |
  396. | Module owners are labelled `<repo-relative path>::<module>` everywhere (impact rows, `read-symbols`, `context`, `flow-trace`, `investigate` neighbours, ambiguity candidates, process names, Mermaid export, the GraphML `label`, the web UI). `symbol --json` keeps each symbol's raw `name` and adds a labelled `display_name` to the symbol and every caller and callee. A file that is only top-level code gets a `summary --level file` line with no `exports 0 symbols` clause, and no line at all when that code calls nothing indexed in another file. `read-symbols`, `impact`, `flow-trace` and `context` look one up as `path::<module>`; the path is the exact repo-relative path or a suffix on a `/` boundary (`app.js`, or `conftest` without the extension), and a suffix that several files share is ambiguous | Name an owner `path::<module>`; lengthen the path when it is ambiguous |
  397. | A qualified name now narrows every name lookup, not only owners. The segments before the name are read two ways and both readings are kept: the first as a file (an exact repo-relative path, a suffix on a `/` boundary, or that suffix without its extension, such as `conftest`) followed by a class chain, or all of them as a class chain. So `path::name` works, and `Class::method` and `path::Class::method` work when the index records the method as a member of that class. A Rust `impl` block in a different file from its struct is not recorded that way, so `Struct::method` is not found there; its `Did you mean:` line names the `path::name` that resolves. `Outer::Inner::method` works in Java and C#, where a nested class is a member of its outer class. Python nested classes and TypeScript namespaces are not recorded as containers, so there it is not found, with the same not-found message. A class name that is also a file stem (`Svc::run` with `a/Svc.ts` and a class `Svc` in `b.ts`) is ambiguous rather than answered by the file. A leading `/` is ignored and `\` reads as `/`. `impact`, `flow-trace`, `symbol`, `context`, `brain context`, `context --feature` entry points and MCP `brain_context` all resolve qualified names this way. A qualifier that names neither is not found (exit 2), where it used to resolve by the last segment. Every one of these commands answers such a miss the same way `impact` does: a `Did you mean:` line of `path::name` specs (`path::Class::method` for a member) on stderr, and `did_you_mean` in the `--json` not-found envelope and the MCP envelope. Suggestions are substring matches first, then names a small typo away (edit distance up to 2; up to 1 for a 3- or 4-letter name), and a `path::name` whose path names a file is answered from that file's members (the close ones, else all of them in source order). `read-symbols` and MCP `read_symbols` answer a miss the same way: not found (exit 2) with the `Did you mean:` line on stderr and `did_you_mean` in JSON and MCP. Before calling it a miss they try shorter readings that are still qualified, dropping the outermost qualifier each time (`zzz::Svc::run` reads as `Svc::run`), and say so when one answers. A leading qualifier that could be a file (it has a `/` or a `.`, or an indexed file has it as its stem) is never dropped: `nothere.ts::Svc::run` is not found, and the shorter reading that does answer (`Svc::run`) is the first `did_you_mean` entry, so another file's `Svc::run` is never read in its place. When one is dropped they say so: a `warning:` line on stderr and a `qualifier_ignored` entry (`query`, `note`) in JSON and MCP. They never fall back to the last segment alone, and a `path::<module>` is never shortened: a file with no top-level calls has no owner, so its `path::<module>` is not found rather than a list of every owner in the graph. Ambiguity candidates carry `file_path`, and each ambiguity carries a `hint` that only offers what tells the candidates apart: "pass a UID or path::Class::name" when each candidate has its own class, "pass a UID or path::name" for an unqualified name whose candidates are each in their own file, "pass a UID or path::Class::name" again when candidates share a file but a class tells them apart, and otherwise "pass a UID" | Qualify a name as `path::name` or `Class::method`, or pass a UID |
  398. | Module owners are callers only. They are left out of `clusters`, `repo-map` and `investigate` entries; of the changed-symbol lists and counts of `detect-changes`, `affected-tests` (including its tier-1 test count), `pr-impact`, `brain diff` and `pre-push-impact`; and of embeddings and vector search. An owner that calls a changed symbol is still reported as affected. A `detect-changes` process listed only because a member file's top-level code changed has `affected_symbol_count: 0` (owners are not changed symbols) and carries `top_level_code_changed: true` to say why | Nothing to change |
  399. | `context`, `brain context` and `context --feature` rank owners after every real symbol and list at most 3. The rest are counted in `module_owners_omitted` (JSON and MCP), printed as "+N more files' top-level code", and left out of the totals; when an owner is listed or left out, each command's `Connected (...)` heading says so and how many (`… owners listed last, N more not counted`); otherwise the heading is unchanged. Owners the `--limit` cuts are counted the same way. When owners are hidden, by the cap or because so many files call the seed at load time that the owners sink under the walk's usual relevance floor themselves, their places are refilled with real symbols the walk scored under that floor (at most as many as owners were hidden, never past `--limit`), so a helper called at load time from many files keeps its real neighbours; the totals count them | Read `module_owners_omitted` |
  400. | `summary --level symbol` and MCP `get_summary` list every real caller but at most 3 owner callers, then `+N more files' top-level code` | Nothing to change |
  401. | `dead-code` seeds its walk from owners but counts them in neither "entry points" nor "excluded"; `--json` gains `module_owner_roots`. A walk seeded only by owners is not degraded: coverage needs `entry_points + module_owner_roots > 0`. With `--repo` (MCP `repos`) both counts are that scope's own roots, like the other totals; coverage still asks whether the whole-graph walk had any root, so a library reached only from another repo is not degraded. `--json` (and MCP) carry that whole-graph count as `walk_roots`, and the text warning "no entry point was found" is printed only when `walk_roots` is 0 | Read `module_owner_roots` beside `entry_points` |
  402. | `read-symbols path::<module>` returns the file's top-level code: the lines outside every function, class and method, with each elided body shown as `⋮` | Nothing to change |
  403. | `pr-impact`, `blast-radius` and `detect-changes` report a changed source file that is only top-level code (a script, a seeder, an entry file) instead of a silent Low with nothing changed: a `changed-file-top-level-only` warning (on all three) names its `path::<module>` owner and the first 10 symbols that code calls (`+N more` after that). Files that load it only for its side effects (`import './x'`, a bare `require`) have no edge in the graph, so the warning says its importers were not assessed and the run is `partial` with gate `degraded-unknown`. In `pr-impact` and `blast-radius` JSON the callees are listed apart in `top_level_callees` (`edge_type: TOP_LEVEL_CALL`, depth 1). They are not dependents, so they stay out of `affected_symbols`, `affected_symbol_count`, the clusters and the risk level, which is Low unless the file has real dependents. The owner is still not a changed symbol | Read `top_level_callees` as what the changed top-level code calls, not as dependents; check the file's side-effect importers by hand |
  404. | `affected-tests` selects a test file whose own top level calls a changed function. When none of that file's tests was reached, its `tests` list is empty and `selected_by: "top_level_code"` (JSON and MCP) says why; it counts as one test, so the summary never reads 0 beside a selected file, and the text output shows it as `(top-level code)`. A test file that only imports the changed module, without calling it, is not selected | Nothing to change |
  405. | `affected-tests` lists each test file once, in the best tier any of its tests reached, with all of its affected tests there (nw-799). A file used to appear in both tier 1 and tier 2 | Count files per tier, not tests |
  406. | `read-symbols --token-budget` (MCP `token_budget`) cuts a first symbol larger than the budget to its leading lines, closed by a marker line, and sets `body_truncated: true`; it used to return it whole. The text output then ends with `body truncated to fit the token budget`, not `truncated: 0 symbol(s) dropped`. A budget of 0 still returns the first symbol whole | Check `body_truncated` before treating a body as complete |
  407. | After an edit, the watcher and incremental index always re-resolve a changed file's direct importers; the 200-file cap now bounds only the transitive expansion. Past 5,000 direct dependents the pass is skipped with a warning naming `index` and `index --force`; past 200 the count and time are logged. Barrel files that only re-export are re-resolved too, so their `reexport_resolved` edges survive edits | Nothing to change |
  408. | A nested JS/TS `function` declaration binds only where it is visible: inside its enclosing function (including nested functions and callbacks there) and, in strict code (TypeScript, an ES module including any `.mjs`/`.mts` file, a `"use strict"` directive in the file's or an enclosing function's prologue), only inside its block. A call before it in that scope still binds it (hoisting); a module-level declaration still binds file-wide. A Python `def` nested in a function binds only inside it. A bare JS/TS call never binds a method, getter or setter (`this.x()` and `obj.x()` are unchanged), so a same-named free function wins. A nested class's members are `MEMBER_OF` that class, not a same-named top-level one. The full index and the watcher now agree on all of these (nw-787, nw-789) | Calls that bound a sibling's nested function, a block function after its block, or a same-file method now bind the import, the caller's own function or nothing. Re-index with `--force` (generation 11) |
  409. | The index CPU budget (`NESTWEAVER_INDEX_CPU_PERCENT`) is off by default (nw-814). It was added because macOS was believed to kill a daemon using 90s of CPU in 180s; it does not. macOS's CPU usage monitor is per thread, armed only by a spawner that asks (launchd does), and non-fatal: it writes a `*.cpu_resource.diag` report ("Action taken: none") and the daemon keeps running. Parse workers still run at utility QoS on macOS, which keeps the machine responsive. An explicitly set `1`–`40` still applies the budget, with `1`–`11` raised to `12` (the smallest budget with room beyond the 20s write reserve); `41`–`99`, including an older plist's `50`, mean off | Nothing to change. To keep a budget, set `NESTWEAVER_INDEX_CPU_PERCENT` to `12`–`40` and re-run `daemon start` so the launchd plist carries it |
  410. | `daemon gc` also prunes the authority registry (`~/.local/state/nestweaver/authority`), which grew one lock record per database scope ever locked (nw-811). It removes records whose database, publication root or operation journal is gone, and empty records from earlier releases that are older than 24h, unheld and match no live database; a record some process holds is never removed. `--dry-run` reports what would go and changes nothing (it skips the launch-agent and directory sweeps). `--db X` limits the prune to X's records and leaves the older empty records alone. A registry gc cannot sweep is a warning, not a failure | Run `nestweaver daemon gc --dry-run` to preview, then `nestweaver daemon gc` |
  411. | A watcher pass over a file with a class keeps its `MEMBER_OF` edges and resolves `this.m()` / `self.m()` as `type_aware`, as a fresh index does. Before, it dropped every `MEMBER_OF` edge of the edited file, so `dead-code` on a watcher-maintained graph could list constructors | Nothing to change; graphs kept by an older watcher regain the edges on the file's next edit or a `--force` index |
  412. | A code watcher keeps running when a committed batch's evidence cannot be saved. It notifies the committed graph and discloses the outstanding repair, retaining replay paths in memory across retries. Successfully persisted replay debt also survives restart; startup repairs imports across bounded source batches. | Restore access to the reported evidence files and let the watcher retry. If replay debt itself could not be persisted, keep the watcher running until repair completes; after interruption, run `nestweaver index --repo <path> --force` to rebuild missing evidence and relationships. |
  413. | **Rebuild required.** LadybugDB 0.21 (0.21.2 in published 12.2.4) changes how text keys are hashed and its on-disk format marker did not change, so NestWeaver now refuses a database built by an earlier version before opening it: exit **1**, `nestweaver::db_rebuild_required`, the exact rebuild command, no daemon started, no byte changed. Snapshot format is now **4**; older snapshots are refused, and `backup restore` of a pre-upgrade archive warns that the result needs a rebuild | Stop the daemon, run `nestweaver backup save <file>` (it reads the old database read-only and marks the archive as pre-upgrade), then `nestweaver publication rebuild --config <instance.toml>`; the old database stays in place until the new one validates. To roll back, reinstall the previous version and restore your backup. Do not open a rebuilt database with an older NestWeaver. See `docs/guide/publication-rebuild.md` |
  414. | A daemon killed by a fatal signal (SIGSEGV, SIGBUS, SIGABRT, SIGILL) while answering is now named. A database with damaged index pages can open under LadybugDB 0.21 and fault on a later lookup; the command used to print a bare `transport error … broken pipe`, and the respawned daemon reported a healthy `brain status`. The command now exits **1** with `nestweaver::daemon_engine_crashed` and the recovery, MCP tool calls return the same message with `isError: true`, and `brain status` prints a warning (`--json`: a `warnings[]` entry of kind `daemon_unclean_exit` with `exit`, `signal`, `at_unix`, `pid`, `count`). A daemon killed from outside (`kill -9`, the OOM killer) is reported as `exited_unexpectedly`, with no claim about the storage engine. `daemon stop` (with or without `--force`), Ctrl-C on a foreground `daemon run` and an idle exit leave no warning, and the warning clears when a daemon next shuts down cleanly. Nothing in the database is changed | Restore the most recent backup with `nestweaver backup restore <archive>`, or rebuild with `nestweaver publication rebuild --config <instance.toml>`. Do not retry the request that crashed: it will crash the daemon again. See [Troubleshooting](docs/server-mode.md#the-daemon-crashed-while-answering) |
  415. | Renaming a registered vault with `--name` (`brain add <root> --name X`, `brain refresh <root> --name X`, `brain watch`, MCP `brain_add_source`) is now refused, exit 1, when another root's vault already holds that name (case-insensitively), with the same message and remedy as registering a new root under it. It used to succeed and leave two vaults answering to one name. Without `--name`, `brain refresh`, `brain watch`, `brain add` and MCP `brain_add_source` now keep a registered vault's stored name instead of renaming it to its directory's (a new vault is still named after its directory) | Pick a free `--name`, or remove the other vault first |
  416. | `brain context --kinds` and `--intent`, and `context --intent`, now refuse a value outside their fixed vocabulary at parse time with exit **64** and a message naming the valid values (they exited 1 with an internal error). MCP `brain_context`, `regex_search` and `count_patterns` report an unknown kind as an invalid argument | Fix the flag value; the message lists the accepted ones |
  417. | Every repo filter now resolves through the one repo resolver and keeps its failure class: `clusters --repo`, `dead-code --repo`, `brain context --repos`, `investigate --scope repo:<name>`, `cross-repo-contracts --repo`, `impact --repo`, `flow-trace --repo`, `contracts list --repo`, `contracts drift --repo` and `service-summary --repo` exit **2** (`status: "not_found"`) for a repo that is not indexed, **3** (`status: "ambiguous"`, with `candidates`) for a name several repos share, and **64** for a selector over 512 bytes. A malformed selector such as `repo:::` names no repo and exits **2**. An empty `--repo ''` exits **64** on `hubs`, `clusters`, `dead-code` and `affected-tests`, but `impact`, `flow-trace` and `pr-impact` ignore it and match every repo. `dead-code`, `brain context` and `cross-repo-contracts` used to exit 1 with an internal error; `clusters --repo` on the daemon route reported an ambiguous name as not found; `investigate --scope repo:<name>` matched repo UIDs by substring and merged every match, so a fragment that matched only a repo UID (not its name, URL or root) now misses; `impact`/`flow-trace --repo` fell back to substring matches on file paths and UIDs. Over MCP a repo filter that names no repo is `isError: true` with the not-found envelope, and an ambiguous one names its candidates | Branch on the exit code, or on `status` in the JSON envelope; pass a repo UID or root path to pick one of several same-named repos |
  418. | A wikilink that exactly and uniquely names a note (case-insensitive, any folder: its filename stem is unique in the vault and no other note has that title) now resolves at confidence **1.0** and is no longer reported. `brain broken-links`, MCP `brain_broken_links`, `memory lint`'s `broken_wikilinks` (and `broken_wikilinks_total`) and `doc-stats` now count only BROKEN links: unresolved (0.0) or ambiguous (several notes match; rows gain `candidate_count`). Links that resolved to one note by a fuzzier tier (a shared stem narrowed by folder, a path whose basename alone matched, an alias) move to a separate list that is not broken: `broken-links` JSON `low_confidence` is now that **array** (was a count; the count is `low_confidence_total`, with `low_confidence_truncated`), and `ambiguous` is added; `total`/`returned`/`truncated` describe broken links only, and `offset`/`limit` window both lists. `memory lint` gains `low_confidence_wikilinks` (+ `_total`); `doc-stats` gains `ambiguous_link_targets`, and `low_confidence_link_targets` no longer includes ambiguous links | Read `low_confidence_total` for the old count; gate on `total` (or `unresolved` + `ambiguous`) for broken links. Existing vaults are re-resolved automatically: the Markdown link derivation version moves to 2, so the daemon re-derives each vault once in the background (or run `brain refresh <vault>`) |
  419. | A resolver-generation-stale repository now degrades `blast-radius` / `pr-impact`, `detect-changes` and `affected-tests` only when it owns a changed file, or is reachable from a repository that does through any chain of recorded or declared repo links (any symbol-to-symbol edge, or a `[[links]]` entry, in either direction). Any other stale repository is disclosed in a `resolver-generation-stale-unrelated` warning notification (naming it and the `index --force` remedy) and no longer degrades the gate, refuses `affected-tests`, or appears in `resolver_stale_repos`, which now lists only the repositories that degrade the answer. Declared links count when the daemon or MCP server was started with `--config`, and on the direct CLI route from `--config` or else the config the database's daemon last started with | Gate on `resolver_stale_repos` / `gate_state` as before; read the `resolver-generation-stale-unrelated` notification to find stale repositories elsewhere, or run `stale-check` |
  420. | The 409 for an empty seed container on `POST /api/v1/brain/context` carries the CLI's coded body, `{"error": "seed container is empty", "status": "empty", "message"}`. The remedy fits the container: add notes to a vault, re-index a repo that has no symbols | Branch on `error: "seed container is empty"` |
  421. | `investigate-expand` / `investigate-hydrate` on an unknown or expired bundle exit **2** (was 1), and `--json` writes `{"error": "not found", "bundle_id", "message"}` | Branch on exit 2, then run `investigate` again for a new bundle |
  422. | Every web API error body is JSON `{"error": …}`: axum's own rejections (a query parameter or JSON body that does not parse, a body over the limit, a wrong method) used to answer `text/plain` (or an empty body), and an unknown `/api/…` path answered an empty 404. Statuses are unchanged. Outside server mode, `/admin/api/*` on the UI is a JSON **404**; it used to serve the SPA's HTML with 200 | Parse error bodies as JSON |
  423. | A declared project repo removed with `remove-repo` (or indexed since the last materialization) is now disclosed, or cleared, by the daemon's next code-link pass: `list-projects` and `project-context` print `Warning: declared repo not a member: …` without waiting for `materialize-projects` | Nothing to change |
  424. | `brain status` names a project whose declared repos resolve to none by its name, not its uid; `--json` `code_links` gains `unscoped_project_names` (index for index with `unscoped_projects`). `notes_changed_as_of`, printed as "as of the last pass", is now re-dated by every pass that finds changed notes; it used to keep the date of the first pass that saw them | Nothing to change |
  425. | `list-projects` lists each project's member repos: a `Repos:` line in text (`(none)` when it has none) and a `member_repos` object (project name to `[{uid, name}]`) in `--json`. The daemon's project listing carries them as `repos` on each project | Read `member_repos` instead of calling `project-context` per project |
  426. | `cluster <id>` with an id no cluster has prints a bounded hint on stderr (the count, the id range, the ten largest, and `nestweaver clusters`) instead of every cluster (2.2 MB on a large graph); still exit **2**. `ranking rank <missing> --json` now writes the `{"error": "not found", "symbol": …}` envelope on exit 2 like the other read commands, and `nestweaver --help` no longer names a nonexistent `rank` command | Run `nestweaver clusters` for the full list |
  427. | `investigate-expand` / `investigate-hydrate` without `--json` now print text on the daemon route too (they printed JSON whether or not `--json` was passed); an entry with no body prints `(body unavailable: <reason>)`. When a symbol's repo was indexed at a checkout that has since moved, the reason now names that recorded path and says it no longer exists, instead of "no recorded local_root". The bundle-cache warning of all three `investigate` commands now suggests `--root` / `--db`, not `--repo` / `--config`, which they reject | Pass `--json` for machine-readable output |
  428. | `POST /api/v1/context` and `/api/v1/brain/context` refuse a blank seed (`""` or whitespace) with **400**, as the CLI and MCP already did; `seeds: [""]` used to answer 200 with arbitrary results. `/api/v1/context` now shares the 100-seed cap, and both routes cap the request body at 64 KiB (**413** past it) | Drop blank seeds before sending |
  429. | `GET /api/v1/brain/notes?after=` must be a note uid of the listed vault (`note:<vault uid>:<hash>`, or any `note:vlt:…:<hash>` without `vault=`). Anything else, including an empty or double-encoded cursor, is **400**. It used to restart silently at page 1 or return an empty "end" page | Send back the `X-Next-After` value decoded once |
  430. | A context seed that names a vault with no notes (or a `repo:` with no indexed symbols), and nothing else, is no longer the `No seeds resolved` miss a bogus uid gets. The engine error starts `Seed container is empty:`; `brain context` exits **1** (was 2) and `--json` prints `{"status": "empty", "error": "seed container is empty", "message", "empty_seeds"}`; MCP `brain_context` is `isError: true` with that text rather than the `not_found` envelope; `POST /api/v1/brain/context` is **409** (was 404). A bogus `vlt:` uid is unchanged | Branch on `status: "empty"` (or 409) to tell an empty vault from a wrong uid |
  431. | Symlinks in a vault are still not followed (a link can point outside the vault or duplicate a note under a second path), but they are no longer silent: a symlinked directory, or a symlinked file with a Markdown name, is listed in `skipped_files` / `skipped_notes` with reason code `unsupported` and a reason starting `symlink to a …`. It is a policy skip: coverage stays `complete` and link derivation is not blocked. A `.brainignore`d link is not listed. The watcher treats a symlink event the same way; a link pointing outside the vault used to fail the whole watcher batch, and one pointing inside was indexed through the link | Move or copy the target into the vault to index it |
  432. | An indexed note that grows past `max_note_bytes` now leaves the graph and search on the watcher and `brain refresh --since` routes too, as a full refresh already did, and is disclosed once as an `oversized` skip row. It used to keep its old text (still searchable, with its old links) and, when it grew while no watcher ran, was replayed as a full batch on every watcher start | Shrink the note or raise `[indexing].max_note_bytes`, then refresh the vault |
  433. | `brain status` answers while the daemon re-derives a vault and says so: `--json` gains `vault_derivation.in_progress` (`vault_uid`, `root_path`, `phase`, `started_at_unix_seconds`, `elapsed_seconds`, `indexed_notes`; `null` when none runs) and the text prints `Vault derivation in progress: <root> (phase: …)`. A config file that cannot be reloaded for the repository-eligibility refresh is now a `repo_eligibility_unrefreshed` warning instead of failing the whole status | Read `in_progress` to see why link-graph tools refuse a vault for now |
  434. | MCP: a lookup tool whose target does not exist now returns `isError: true` with a JSON envelope in both the text and `structuredContent`: `{"status": "not_found", "error": "not found", <target key>, "message", "did_you_mean"?}`. **`brain_impact` flips from `isError: false` to `true`**; `flow_trace`, `note_get`, `backlinks`, `cross_repo_contracts`, `project_context`, `brain_context`/`code_context` (no seed resolved), `investigate_expand`/`investigate_hydrate` (unknown bundle), `brain_diff` (unknown `repo`), `clusters` (a `cluster_id` no community has; it used to return an empty list) and `brain_remove_source` return the envelope instead of prose; `brain_memory_related` and `read_symbols` with no target resolving now set `isError: true`, and `brain_impact`, `brain_memory_related` and `read_symbols` misses gain `message`. Through a daemon with an upstream, a `brain_impact` miss on both tiers (or the upstream unavailable) carries the envelope at the top of the two-tier result, and a `read_symbols` miss on both tiers keeps it after the merge. `backlinks` with a `uid` naming no note is now this miss (CLI exit 2), not an empty success. Searches that match nothing stay `isError: false` (nw-557) | Branch on `isError` and read `structuredContent.status`; retry with a `did_you_mean` entry |
  435. | MCP: `tools/call` with an unknown tool name is now a JSON-RPC error `-32602` (`Unknown tool: <name>`), the same shape as a missing name. It used to be a result with `isError: true`. Schema-invalid arguments are unchanged: still a result with `isError: true` (nw-576, nw-700) | Handle the JSON-RPC `error` for a misspelt tool name |
  436. | `clusters --json` now uses the MCP `clusters` envelope: `clusters` (was `communities`), `total` / `returned` (were `total_communities` / `returned_communities`), per-cluster `size` (was `member_count`), plus `cluster_count`, `symbol_count` and `limit` (nw-559) | Read the new keys; the member lists are unchanged |
  437. | MCP `blast_radius`, `affected_tests` and `detect_changes` accept `files`, `hub_nodes`/`bridge_nodes` accept `top`, and `read_symbols` accepts `neighbors`, the CLI flag names. Two spellings of one argument with different values (e.g. `changed_files` and `files`, `limit` and `top`, `targets` and `uids_or_fqns`, `target` and `name`) are now refused with `'X' and 'Y' are aliases`; `detect_changes` used to keep `changed_files` silently (nw-558) | Pass one spelling, or the same value in both |
  438. | An empty string for an identifier or query argument (`uid`, `title`, `name`, `target`, `project`, `symbol`, `query`, `pattern`, `bundle_id`, `key`, `tag`, `path`, `base_ref`), and an empty list or `""` entry in `seeds`, `targets`, `uids_or_fqns` or `patterns`, is now a schema error: MCP `isError: true`, CLI exit **64**. `get_summary` with `name: ""` used to return the whole catalogue, and `backlinks`/`query_extensions`/`brain_memory_related` with `uid: ""` answered success (nw-577) | Omit an argument rather than sending `""` |
  439. | `regex-search` rows gain `column` (1-based character column on `line`) and `matched` (the matched text, at most 200 characters), so several matches on one line are no longer identical rows. The text output appends `:COL` to `path:line` (nw-549) | Use `column` to tell same-line matches apart |
  440. | `brain doc-stats` text prints one `unresolved links:` line (per note and target, with the per-section count in parentheses) instead of two lines that read as a note miss and a section miss. JSON and MCP keys are unchanged (nw-554) | Update scrapers of the old two text lines, or use `--json` |
  441. | `brain context <name> --json` with no seed resolved (exit 2) now includes `status: "not_found"` and `message`, the engine's text naming the `nestweaver investigate` command to run for a question. The daemon route's text now prints that sentence rather than the RPC wrapper (nw-511) | Show `message` to the user |
  442. | `read-symbols <target> --root <dir>` with a `--root` that does not exist, cannot be read, or holds none of the indexed files (reason `no indexed file readable under it`) now exits **1** with `"error": "unreadable_root"` and an `unreadable_root` object (`path`, `reason`, `remedy`). More generally, a read where every target resolved but no body could be read now exits **1**, not **2**. Exit 2 now means only that a target did not resolve (nw-539, nw-706) | Gate on 1 for unreadable source and 2 for unresolved targets; pass the right `--root`, or omit it to read from each repo's recorded root |
  443. | `brain refresh` gains `--json` and `--fail-on-skip` (nw-196). `--json` prints one object on stdout: `vault`, `mode` (`"full"` or `"since"`), `coverage_status`, `skipped_count`, `excluded_by_request_count`, `skipped_files[]` (`path`, `reason_code`, `detail`, `observed_bytes`, `limit_bytes`, `excluded_by_request`), `frontmatter_unparsed[]` (the same fields without `excluded_by_request`) and `message` (the text summary); progress stays on stderr. `excluded_by_request` is true for a `.brainignore` match. `--fail-on-skip` exits **1** when any row is not excluded by request. A vault whose only skips are `.brainignore` exclusions now reports `coverage_status: "complete"` everywhere (daemon progress, MCP `brain_add_source`, `brain refresh --json`); it used to read `"degraded"` on the daemon and MCP routes | Use `--fail-on-skip` or the JSON rows to gate on vault coverage instead of parsing the text summary |
  444. | `summary --token-budget N` whose first matching summary alone exceeds `N` now returns that summary and flags it with `budget_exceeded_by_first_item` (`requested_tokens`, `returned_tokens`, `note`), instead of `returned: 0` and an empty list. MCP `get_summary` does the same. Later summaries are still cut by the budget (nw-644) | Check `budget_exceeded_by_first_item` if a response must stay under the budget |
  445. | `nestweaver mcp --config <file>` with an invalid config now answers the client's first request (normally `initialize`) with a JSON-RPC error naming the file and the parse error, then exits 1. It used to exit 1 with empty stdout (nw-656) | Show the JSON-RPC error; fix the config |
  446. | `summary` (text) and `generate-guide --config/--rules-from` are now served by a running daemon instead of opening the store directly, which failed while the daemon held the write lock. `generate-guide` never sends the config file: the CLI sends only the guide sections as a projection (`guide_config`: links, features, projects; no tokens, auth, git or URLs) plus the `--rules-from` contents as `rules`. Such a request goes to the local daemon only, never to a federated upstream. Each input is capped at 1 MiB (exit 1 when exceeded). MCP `brain_guide` accepts `guide_config` and `rules`; a `config` path is still refused. An explicit `--config` must match the running daemon's, as for other commands (nw-690) | Start the daemon with the same `--config` you pass to `generate-guide` |
  447. | `context <missing> --json` still exits **2**, but `message` is now the root cause only, without the `code_context RPC failed: code: 'Internal error'` wrapper and the repeated text (nw-550) | Nothing to change unless a script matched the wrapper text |
  448. | `brain refresh --since` now lists its skip rows, and the "NOT marked current" note names the paths that could not be read. A refresh refused because the vault is Blocked names the vault, the directories unreadable now, when the automatic retry is due, and the remedy (a full `brain refresh` without `--since`). `brain status` prints a `Vault BLOCKED: <root>` line, and the daemon's `vault_derivation` status gains `blocked_vaults[]` (nw-694) | Run a full `brain refresh <vault>` to clear a Blocked vault without waiting for the retry |
  449. | A config-less `brain add --instance X` no longer breaks `brain context` after a daemon restart (`ForeignRecord`): derivation records carry the live instance, and a refresh heals a record stamped with the ambient `default` (nw-693) | Run `brain refresh <vault>` once on an affected database |
  450. | The daemon now rebuilds the manifest sidecar (and clears `manifest-debt.json`) when a repo's recorded eligibility is from the superseded pre-nw-652 fingerprint version; one such repo used to block the rebuild for every repo. `suggest-links` while manifests are owed now says they are not ready and why, instead of advising `daemon start` for a daemon that is running (nw-680, nw-700) | Nothing to change; re-index a repo named in the rebuild error if the sidecar stays blocked |
  451. | The local UI rejects a non-loopback Host or mismatched Origin with **403** (nw-682) | For a deliberate local reverse proxy, set `NESTWEAVER_UI_ALLOWED_HOSTS` to its hostname and forward the browser's original Host |
  452. | UI responses now include CSP, `nosniff`, frame-denial and referrer headers (nw-625) | Allow the UI's same-origin assets when configuring a local reverse proxy |
  453. | `GET /api/v1/source` reads only indexed source paths. An unindexed path is **404** (`source_not_indexed`) and a malformed path is **400** (nw-682) | Handle the machine-readable `error` code; an arbitrary file path is no longer read from disk |
  454. | An ambiguous `/source` path is **409** (`ambiguous_file`, with repo candidates), and the web UI lets you choose a repo (nw-683) | Pass `repo=<repo uid>` when a relative path exists in more than one indexed repo |
  455. | Web UI: a deep link with scene params (`node`, `mode`, `lens`, `seeds`, `kind`, `workspace`) but no `representation` now opens the graph representation; it used to keep the JSON/table mode left in browser storage and write it back into the URL (nw-571) | Add `representation=table` (or `json`, `matrix`) to a link that needs a non-graph view |
  456. | Web UI: `?kind=repo` (or `note`, `service`, `symbol`) without a `node` now filters Overview to that landmark kind and stays in the URL; it used to be stripped to `/` and ignored. Any other `kind` without a `node` shows a warning. `GET /api/v1/overview` accepts `kind=repo|service|symbol|note`, applied before its per-kind caps (a note-only scene lists up to `limit` notes, not 12); any other value is **400**. With a `node`, `kind` is still the node's kind (nw-595) | Drop `kind=` for the unfiltered Overview; add `node=` to deep-link a single node |
  457. | Web UI: `?engine=wasm` now stays in the URL (it used to be stripped on the first state change, which quietly returned the page to the server engine), downloads `snapshot.msgpack` once per graph generation instead of four times, and the status bar shows the active engine (nw-570) | Nothing to change; drop `engine=wasm` from a link to return to the server engine |
  458. | An unreadable, invalid UTF-8 or invalid-glob `.brainignore` now refuses vault add, refresh and watch before changing indexed notes or sidecars (nw-684) | Repair the file and retry; a missing `.brainignore` still means no extra exclusions |
  459. | Note-to-code links now scope candidate definitions before preferring them (nw-685) | Expect links into the note's own project when another project defines the same name |
  460. | A new note under a project's `vault_folder` gains project membership during reconciliation (nw-679) | Expect newly created notes in `project-context` after reconciliation |
  461. | A UID seed with no text label no longer opens a semantic seed search (nw-686) | Expect structural results for the UID without unrelated semantic matches |
  462. | `read-symbols` verifies indexed spans and reports stale or relocated source instead of returning another symbol's body (nw-689) | Handle the additive stale-span/relocation fields in `read-symbols` responses |
  463. | CommonJS `module.exports.X` and `exports.X` functions are now definitions with call edges. Resolver generation 7 requires a full repo re-index before `dead-code` answers (nw-687) | Run `nestweaver index --repo <path> --force` for each repo after upgrading |
  464. | A JS/TS test block is now named `<runner> <title>` (`describe getTier`, `it returns gold`) instead of its bare title, so it no longer shadows a real definition of the same name, and `affected-tests` selects the test that calls it. Only `require('x')` is an import (any `f('x')` call was one), and a call bound from an npm package (`const { isEmpty } = require('lodash')`) no longer gets a `CROSS_REPO_LINK` to another repo's same-named symbol, unless the specifier names an indexed repo's own package (its manifest `name`, e.g. `@org/shared`), which keeps an import-corroborated link. Resolver generation 8 (nw-688) | Run `nestweaver index --repo <path> --force` for each repo after upgrading; search test blocks by the prefixed name |
  465. | `regex-search` / MCP `regex_search` / `count_patterns` now plan a pattern from every literal a match must contain, not only its prefix, so `fn\s+run_\w+_reconciler` uses the trigram index instead of a full scan that could time out empty. Case-insensitive patterns, small classes, `?` and alternations plan too. Results are unchanged; `scanned_fallback` is `false` for more patterns (nw-697) | Nothing to change; expect fewer `scanned_fallback` answers and fewer deadline-empty results |
  466. | Server mode: a code re-index no longer drops note-to-code links until the next vault fetch. After each code fetch the index worker records the debt (`brain status` shows `Note→code links: being rebuilt (code re-index of <url>)` and `code_links.pending`), then one debounced relink task (bursts coalesce; it stops on shutdown) relinks from the vaults' bare clones and clears it. A direct (`--no-daemon`) code `watch` still only records the debt; the daemon's first pass settles it (nw-677) | Gate on `code_links.pending` as before; expect it briefly after each server-side code fetch |
  467. | The daemon's manifest rebuild is now per repo: a repo it must refuse (source eligibility recorded under other settings, a missing root, a malformed manifest, the shared 32 MiB budget) no longer keeps every repo's manifests stale. The others are published and `manifest-debt.json` is cleared; each refused repo is logged and recorded inside the manifest sidecar's own envelope (so it is published, generation-bound and backed up with the manifests), re-probed alone with backoff (30 s doubling to 30 min), and named with its reason and a remedy that fits the case (`nestweaver index --repo <path>`; restore or `nestweaver remove-repo <uid>` for a missing root; re-fetch for a server-mode repo) in `brain status` (a `Manifests not current for N repo(s)` block; additive JSON `manifest_failures[]` with `repo_uid`, `repo_url`, `root`, `reason`, `remedy`), in `suggest-links` (text note; additive JSON `manifest_failures`), and in the `dead-code` manifest disclosure. A capture that exceeds its own per-repo 60 s budget (started after the write gate is held) refuses no repo: the snapshot is deferred as contention and retried, and `brain status` JSON carries the runtime state as `manifest_recovery` (`state`, `attempts`, `retry_after_seconds`, `error`), with a `manifest_recovery` warning while it is `deferred`, `retry_scheduled` or `blocked`. **This supersedes the old "malformed manifest → 503" contract:** `suggest-links` (HTTP and CLI) now answers 200 from the repos that are current and names the refused repo, instead of refusing the whole answer (nw-705) | Run the named remedy for each refused repo |
  468. | In unscoped `investigate`, an exact symbol name remains a seed while longer substring matches are connected results; partial matches remain seeds when there is no exact match (nw-529) | Treat `is_seed` as the query match indicator; results still include relevant connected symbols |
  469. | Invalid `export --format` / `--scope` now exits **64**, not 1 | Gate on 64 for usage errors; 1 still means the export itself failed |
  470. | A value a tool's schema rejects (e.g. an over-long `read-symbols` target) now exits **64**, not 1, on the daemon route, and on the `--no-daemon` route for commands that run through the shared tool layer (`brain search`, `project-context`, `clusters`, `blast-radius`, …). Direct-route commands that call the engine without the tool layer (e.g. `read-symbols --no-daemon`) never see the schema and keep their own exit codes | Gate on 64 for usage errors; 1 still means the command itself failed |
  471. | `index --repo … --fail-on-skip` now exits **1** when a subdirectory cannot be read (it used to exit 0 with `coverage_status: "complete"` and that directory's files silently missing). The directory is a `read_error` row in `skipped_files` and `coverage_status` is `"degraded"`; indexing still completes, and files already indexed under it are kept. An ignore file (`.gitignore`, `.ignore`) with a pattern that cannot be parsed is also disclosed now, as an `ignored` row naming the file | Fix the directory's permissions (or exclude it) and re-run; drop `--fail-on-skip` if a partial index is acceptable |
  472. | `brain add`, `brain refresh` without `--since` (daemon route) and MCP `brain_add_source` used to end in `[Error]` — exit 1, or an MCP tool error — on ANY vault coverage gap, e.g. one note that fails to parse or an unreadable subdirectory. They now finish `Done`: exit 0, MCP `status: "indexed"` with `coverage_status: "degraded"`, and a message saying the vault was "NOT marked current" (its derivation is recorded Blocked and counted by `brain status`) | Gate on `coverage_status` (MCP) or the skipped-file list, not the exit code, to detect a partial vault index |
  473. | `index` on a repo holding a binary file with a contract-language extension (`.ts`/`.js`/`.java`/`.kt` — an MPEG transport stream is `.ts`) used to fail with `prepare incremental contract derivation` / `prepare strict contract derivation` and record `contract_derivation_failed`. It now succeeds and discloses the file as ONE `binary` row in `skipped_files` (`coverage_status: "degraded"`, so `--fail-on-skip` exits 1). The live code watcher likewise stops skipping every batch over it, and no longer fails a batch over an unreadable file in a language that cannot contribute a contract | Nothing to change unless a script relied on the failure; gate on `skipped_files` / `coverage_status` |
  474. | Registering a vault under a name another vault at a different root already holds is now refused — compared ignoring case, so `Brain` beside `brain` is refused too. This covers `brain add`, `brain refresh` (with or without `--since`), `brain watch` and MCP `brain_add_source`; the error names the existing vault's root and the `brain remove … --instance …` step. A vault already in the graph still refreshes in place | Pass a distinct `--name` for the second vault, or remove the old one first if the vault moved |
  475. | `brain status` now reads `Watcher reconciliation pending: N file(s)` (was `note(s)`), and the count includes source files the code watcher owes as well as vault notes | Match on `file(s)`, or read `skipped_notes.reconciliation_pending` from `--json` |
  476. | Notes whose YAML frontmatter cannot be parsed are still indexed, but are now disclosed under one label, `Notes indexed without frontmatter (unparsable YAML): N`, in the `brain add` / `brain refresh` output and in `brain status`. As JSON, `brain status --json` and MCP `brain_status` gain `skipped_notes.frontmatter_unparsed` (count) and `frontmatter_unparsed_notes` (`{path, reason}` rows), MCP `brain_add_source` gains the same two fields, and daemon progress gains `IndexProgress.frontmatter_unparsed`. All additive; these notes do NOT count toward `skipped_count` or `coverage_status`, since they were indexed | Fix the YAML to restore those notes' tags and properties; nothing to change in scripts |
  477. | A `vlt:` or `repo:` UID given as a context seed (`brain context`, MCP `brain_context`) used to exit 0 with nothing connected. It now expands to the vault's notes or the repo's symbols; the most central few stay seeds and the cut is disclosed through `seeds_truncated` / `seed_matches_total`. A `vlt:` seed for a vault with no notes is its own `Seed container is empty` error (see the empty-vault row) | Expect results (and a non-empty `seeds_truncated`) for container seeds; handle the error for an empty vault |
  478. | Web API `GET /api/v1/brain/notes` now honours `?vault=` (alias `vault_uid`; an unknown vault is **404**, it used to be ignored), sends the filter's total in `X-Total-Count`, pages by uid cursor with `?after=` (the next cursor is in `X-Next-After`, form-urlencoded, absent at the end — a page can be short mid-vault when corrupt rows are dropped), and rejects `after` with `offset` as **400**. An `offset` past 1000 now returns an empty page instead of repeating rows 1000.. | Page with `after` + `X-Next-After` instead of `offset`; the body is still a plain array |
  479. | The brain watcher now discloses notes whose text landed but whose code links failed to write, as `brain watcher code links not yet written; retrying` rows under `Watcher reconciliation pending`, and replays them after a restart | Nothing to change; the rows clear once the links are written |
  480. | A full `brain refresh` (and `brain add` through the daemon) no longer leaves every note without its code links, and a code re-index no longer leaves notes without their links into the changed files: the daemon's code-link reconciler rebuilds exactly the notes whose links no longer match their text, in the background. While links are owed, `brain status` prints a `Note→code links: being rebuilt (…)` line (with progress and the last error if a pass failed), `brain status --json` / MCP `brain_status` / the daemon status RPC gain an additive `code_links` object (`pending`, `reason`, `since`, `progress`, `last_error`, `failures`, `rules_version`, `current_rules_version`, `last_reconciled_at`), and `brain_context`, `project_context` and `investigate` answers carry `code_links_incomplete: true` plus `code_links_pending`; all clear when a pass lands | Gate on `code_links.pending` or `code_links_incomplete`; expect them briefly after a refresh or re-index |
  481. | Name-inferred cross-repo call links (`CROSS_REPO_LINK` edges with `cross_repo_name_*` evidence) no longer depend on the order repositories were indexed in, and re-indexing a repository (or a code watcher batch in it) no longer drops the links other repositories had into it. `nestweaver index` (direct and through the daemon) now ends every run, including one that changed nothing, with one whole-graph inference that replaces those links (it writes only when they differ, and heals a brain indexed before this change on its next index). Code watcher batches (daemon or direct `watch`) and server-mode fetches record the debt; one debounced background pass (a 3 s quiet period, at most 60 s) pays it, and a daemon also runs one pass at startup. While it is owed, `brain status` prints `Cross-repo links: being re-inferred (…)` (with the last error if a pass refused), and `brain status --json` / MCP `brain_status` / the daemon status RPC gain an additive `cross_repo_links` object (`pending`, `reason`, `since`, `last_error`, `failures`, `last_reconciled_at`). A pass that cannot read an indexed file (not in the parse cache, and its content changed on disk) refuses and leaves the stored links alone. The parse cache gains an append-only log beside it, `<db>.parsed_cache.log`, folded into `<db>.parsed_cache.bin` by the next full index | Gate cross-repo `impact`, `blast-radius` and `affected-tests` answers on `cross_repo_links.pending`; re-index a repository named in `last_error` |
  482. | Note-to-code links (`REFERENCES_CODE`) now follow explicit code mentions and project scope: a name links when written as code (a backtick span, a code block, or an identifier-shaped `snake_case`/`camelCase` name or a `call(` in prose) and it resolves within the note's project to at most 5 defining files; plain English words, URLs, wikilinks and string literals never link, and `main` is stoplisted. Offline on a real brain this is ~700× fewer links (39 M → ~56 K) at ~97 % precision. **First start after upgrading (local daemon):** the daemon's code-link reconciler removes every old link in one step (the two link tables are dropped and recreated in one transaction and one publication — 0.11 s for 1,000,000 edges in a fixture; ranked reads fail closed only for that window) and then relinks note by note in the background, 100 notes per write. Until it finishes, `brain status` reports the pending relink and ranked reads carry a disclosure that note→code links are incomplete. The relink time on a large brain has not been measured; it is bounded by reading every note once. An interrupted migration starts over on the next start. **Server mode** has no reconciler: a vault's notes are relinked under the new rules when the worker next fetches that vault, and a code re-index there does not relink notes | To keep a link for a plain name, write it as code (`` `Processor` ``, `review()`) or put the note in the project whose repo defines it |
  483. | Project code membership is now a durable Project→Repo edge (`PROJECT_INCLUDES_REPO`), so re-indexing no longer empties `project_context` of code (nw-678). The local daemon rebuilds this membership from its config before each code-link pass, so no manual step is needed after upgrading. `materialize-projects` stops writing the per-symbol `PROJECT_INCLUDES_SYMBOL` edges and clears each project's old ones; until then, legacy edges are read alongside the new membership, so a project→symbol pair can be counted twice in ranking. The ranking graph's definition changed, so the first ranked query after upgrading recomputes PageRank once. **Downgrade:** once the new `materialize-projects` has cleared the legacy edges, an older binary sees no project code; upgrading again restores it through the daemon's startup rebuild. `project_context` reports `code_membership_gap` for a project that declares repos but has no member repo | Nothing to change; to downgrade, re-run the old binary's `materialize-projects` |
  484. | `impact --no-daemon` now caps at 50 like the daemon route; `--limit` maxes at 1000 | Pass `--limit` explicitly if you relied on an uncapped direct route |
  485. | `project-context` without `--include-components` now **includes** component sub-projects | Pass `--include-components false` to keep the old behaviour |
  486. | `_meta` moved from the MCP envelope into the payload and lost its `nestweaver.io/` prefix | Raw HTTP MCP clients must read `payload._meta`, not `envelope["nestweaver.io/sources"]` |
  487. | `hubs --json` / `bridges --json` are objects, not bare arrays | Read `.hubs` / `.bridges`, not `.[0]` |
  488. | `NESTWEAVER_NO_DAEMON` alone no longer permits a daemon bypass | Standard artifacts always use the daemon; even the unpublished CI artifact requires a GitHub Actions runner context, not a local `CI=true` |
  489. </details>
  490. ## Server Mode
  491. NestWeaver can run as a centralized server, indexing repos for your entire team and serving queries to AI agents via gRPC and MCP-over-HTTP.
  492. ### Quick Start
  493. ```bash
  494. # Start the server (TLS required for grpcs:// clients)
  495. nestweaver daemon --db ./brain.lbug run \
  496. --server \
  497. --bind 0.0.0.0:9378 \
  498. --tls-cert ./tls/server.pem \
  499. --tls-key ./tls/server-key.pem \
  500. --auth-token "$NESTWEAVER_AUTH_TOKEN"
  501. # Connect from another machine
  502. nestweaver connect grpcs://nestweaver.internal:9378 --token "$NESTWEAVER_AUTH_TOKEN"
  503. ```
  504. ### Ports
  505. | Port | Protocol | Purpose |
  506. |------|----------|---------|
  507. | 3000 | HTTP | Web UI (optional, `nestweaver ui`; 9377 in the macOS .app) |
  508. | 9378 | gRPC | Query API (TCP + TLS) |
  509. | 9379 | HTTP | MCP-over-HTTP (AI agents) + `/webhook` + `/admin/api/*` + Prometheus `/metrics` |
  510. In server mode the daemon serves Prometheus `/metrics` on the MCP HTTP port (9379) — gRPC port + 1, inheriting the `--bind` IP. `nestweaver ui` serves the same route on its own listen port (default 3000). The macOS app serves the UI, including `/metrics`, on 9377.
  511. ### Docker
  512. ```bash
  513. docker compose up -d
  514. ```
  515. See [Server Mode Guide](docs/server-mode.md) for full documentation.
  516. ## Install
  517. ### macOS app (source build)
  518. The native **NestWeaver.app** is source-build-only until a release job publishes
  519. a `.app` bundle or DMG. Build it from source (it bundles Metal-accelerated
  520. embeddings and the web UI):
  521. ```sh
  522. bash app/build.sh
  523. open target/release/NestWeaver.app
  524. ```
  525. For a frozen candidate, retain the CLI and workspace test executables from one
  526. Cargo compilation, then run those exact executables without rebuilding:
  527. ```sh
  528. bash app/build.sh --validation-artifacts /tmp/nestweaver-validation
  529. python3 scripts/test-validation-artifacts.py --manifest /tmp/nestweaver-validation/artifacts.json
  530. ```
  531. The validation mode uses the normal release/Metal profile and app packaging.
  532. It checks that the packaged CLI matches the artifact manifest. The affected Mac
  533. must validate the source build and app launch; Linux cannot establish those results.
  534. For Linux, build the frontend first, then use
  535. `python3 scripts/build-validation-artifacts.py --output /tmp/nestweaver-validation`.
  536. Both artifact commands require a clean, committed source tree. Test exclusions
  537. must be explicit and are recorded in the results; legacy direct-mode integration
  538. fixtures require the separate CI-only artifact/runner and cannot run locally.
  539. The `.app` bundle gives you a menubar status icon, Metal GPU acceleration (~5x faster embeddings via a launchd-managed daemon), a persistent daemon shared with the CLI/MCP, web UI on port 9377, and launchd-managed restart. See [macOS App](#macos-app) below.
  540. ### Supported platforms (CLI)
  541. Install the release-matched CLI wrapper from [npm](https://www.npmjs.com/package/nestweaver):
  542. ```sh
  543. npm install --global nestweaver
  544. nestweaver --version
  545. ```
  546. Alternatively, select the GitHub Release archive for your platform, verify its
  547. matching SHA-256 file, then install it as described in
  548. [INSTALL.md](INSTALL.md#pre-built-cli-recommended). Both macOS CLI
  549. archives are built with Metal support. The default `accelerator = "auto"` therefore requires Metal in
  550. those builds and reports a Metal initialization or inference-probe failure
  551. instead of retrying on CPU. To opt out explicitly, set `accelerator = "cpu"` in
  552. the `[embedding]` section of your instance configuration. Builds without Metal
  553. support select CPU for `auto`.
  554. | Platform | Release target |
  555. | --- | --- |
  556. | Linux x86_64 | `x86_64-unknown-linux-gnu` |
  557. | Linux aarch64 | `aarch64-unknown-linux-gnu` |
  558. | macOS Intel | `x86_64-apple-darwin` |
  559. | macOS Apple Silicon | `aarch64-apple-darwin` |
  560. ```sh
  561. # After cloning the source repository (current stable Rust)
  562. eval "$(scripts/fetch-lbug-source.sh)"
  563. cargo install --locked --path .
  564. ```
  565. Source builds also require CMake, a C++20 compiler, Python 3.9+, OpenSSL and zstd
  566. development files, `pkg-config`, and Protocol Buffers. The checkout builds
  567. LadybugDB from source rather than downloading a prebuilt archive; keep
  568. `.cargo/config.toml` intact. See
  569. [the source-build prerequisites](INSTALL.md#build-from-source) before
  570. building.
  571. <details>
  572. <summary>Pre-built binaries</summary>
  573. Download a pre-built CLI archive and its matching `.sha256` file from [GitHub Releases](https://github.com/Kehl-io/nestweaver/releases). Binaries are available for Linux and macOS on both x86_64 and aarch64; use the target table above and follow the checksum verification in [INSTALL.md](INSTALL.md#pre-built-cli-recommended).
  574. </details>
  575. <details>
  576. <summary>Build from source</summary>
  577. ```sh
  578. git clone https://github.com/Kehl-io/nestweaver.git
  579. cd nestweaver
  580. eval "$(scripts/fetch-lbug-source.sh)"
  581. cargo install --locked --path .
  582. # On macOS with Metal embeddings:
  583. # cargo install --locked --path . --features metal
  584. ```
  585. The first build compiles LadybugDB from source and may take several minutes.
  586. </details>
  587. ## CLI Reference
  588. <details>
  589. <summary>Core Commands</summary>
  590. | Command | Description |
  591. |---------|-------------|
  592. | `index` | Parse and index a repository (auto-detects repo root from `.git`). Use `--name` to set a custom repo name for multi-repo setups. Indexing does NOT refresh trigrams implicitly — the daemon's reconcile loop owns that (see `[indexing] trigram_reconcile_interval`). `--with-trigrams` forces an inline refresh for one run (CI, scripted reindex), `--no-trigrams` suppresses it (and conflicts with `--rebuild-trigrams`), `--rebuild-trigrams` forces a full rebuild. A direct index (no daemon) refreshes trigrams only with `--with-trigrams`, `--rebuild-trigrams`, or `[indexing] with_trigrams = true`. |
  593. | `watch` | Live re-indexing via filesystem watcher with debouncing. Runs daemon-side (no instance config required; unsafe roots are denylisted); `--force` replaces an existing watcher. Incremental reindex preserves CALLS/IMPORTS edges (reverse dependents are re-resolved) and reports per-file failures instead of dying |
  594. | `watch-stop` | Stop the daemon's active watcher. The watcher slot is global and the daemon keeps no liveness check on the CLI that registered it, so a watch killed without a clean shutdown (SIGKILL, or a closed terminal) leaves the slot occupied and every later watch refused; this releases it without restarting the daemon |
  595. | `context` | Get task-focused context via PPR (supports `--intent` for tuned retrieval) |
  596. | `search` | Symbol-name substring lookup. Notes and BM25 full-text search are `brain search` |
  597. | `symbol` | Look up a symbol by name and display its metadata |
  598. | `impact` | Trace the blast radius of a symbol through the dependency graph (fails closed on unknown/foreign UIDs, exit 2; `--depth` 1–15; `--limit` 1–1000, default 50 on **both** routes — `--no-daemon` used to be uncapped and now matches the daemon, so a symbol with more than 1000 depth-1 dependents has rows unreachable at any limit; pruning by impact-score threshold or depth is disclosed, `--min-score 0` opts out) |
  599. | `blast-radius` | Assess blast radius for a set of changed files; reports `gate_state`/`status` and blind spots, and never reports `ok` for a truncated traversal |
  600. | `detect-changes` | Run the MCP-compatible changed-file impact contract directly from the CLI, including risk, gate state, status, and blind spots |
  601. | `flow-trace` | Trace forward execution flow from a symbol — what it calls, and what those call |
  602. | `read-symbols` | Read a symbol's source span. Omitting `--root` reads each symbol from its recorded repo working tree; `--root` still pins a single filesystem root |
  603. | `regex-search` | Regex search over indexed text (scope-aware trigram pre-filter; safely scans only missing or stale scopes with `stale_index: true` — refresh now with `index --with-trigrams`, or set `[indexing] with_trigrams = true` so the daemon's reconcile loop keeps the pre-filter fresh on `trigram_reconcile_interval`) |
  604. | `count-patterns` | Count regex matches per pattern (`--max-millis` budget; exits 75 when it cuts a count) |
  605. | `investigate` | Orient on a topic in one call |
  606. | `investigate-expand` | Drill into investigate bundle entries — full body plus immediate neighbours |
  607. | `investigate-hydrate` | Fill in bodies/summaries for all un-hydrated entries of a bundle |
  608. | `affected-tests` | Select tests for changed files in one repository (tiered; carries a `recommendation` CI directive — `run-full-suite` on any degraded run or when changed files have unrecognized extensions like Makefile/CI YAML/`.sql`). `--repo <name or UID>` names the repository; it is required with `--files` when several repos are indexed (exit 64 otherwise). `--base-ref` diffs against the working tree, not the merge-base |
  609. | `repo-map` | Generate a token-budgeted map of the repository structure |
  610. | `summary` | Hierarchical code summaries at symbol, file, or cluster level |
  611. </details>
  612. <details>
  613. <summary>Brain Commands</summary>
  614. | Command | Description |
  615. |---------|-------------|
  616. | `brain add` | Add an Obsidian vault or markdown directory to the knowledge graph |
  617. | `brain search` | Search across code symbols, notes, headings, sections, and tags (`--limit` 1–1000) |
  618. | `brain context` | Get unified context spanning both code symbols and notes (skips the semantic leg entirely when the DB has no embeddings; identical concurrent calls coalesce single-flight) |
  619. | `brain list` | List all registered vaults |
  620. | `brain status` | Show vault counts, per-vault staleness, and index health |
  621. | `brain watch` | Watch vaults for changes and re-index automatically. `--force` adopts an existing watcher registration instead of being refused by it — the vault counterpart of `watch --force` |
  622. | `brain refresh` | Force a full re-index of one vault directory (`nestweaver brain refresh <path>`) |
  623. | `brain remove` | Remove a vault from the brain (cascade-deletes nodes; does not touch files on disk) |
  624. | `brain stale-check` | Check whether the indexed graph reflects reality (also available top-level as `stale-check`). **Exit 0** nothing to do · **1** the check itself failed · **2** at least one repo needs re-indexing. Gate CI on `any_needs_reindex` (or exit 2) — that is the actionable union of `stale`, `incomplete`, and `missing`. A repo that indexed successfully with **zero eligible source files** is `no_indexable_content` (human: `empty`) and does **not** pin exit 2. `any_stale` / `is_stale` mean *behind HEAD* specifically |
  625. | `brain diff <repo>` | Show what changed in the graph since a commit (`--since-sha <sha>`, `--limit` 1–1000 default 50, `--json`, `--db`, `--config`). Local repos only; the CLI twin of the MCP `brain_diff` tool |
  626. | `brain reindex-search` | Rebuild the Tantivy BM25 search index from current graph state |
  627. | `brain broken-links` | List unresolved and ambiguous wikilinks, with suggested fixes. `low_confidence` is a separate list of links that did resolve and is not counted in `total` |
  628. | `brain orphans` | List notes with zero inbound and zero outbound wikilinks |
  629. | `brain topic-clusters` | Detect topic clusters via Louvain-style local-moving community detection over note wikilinks |
  630. | `brain tag-graph` | Show a tag's note count and co-occurring tags (or dump the full tag graph) |
  631. | `brain doc-stats` | One-shot health summary: note/wikilink counts, broken links, orphans, top tags |
  632. | `backlinks` | Resolve a note by UID or title and list the notes that link to it |
  633. | `note get <target>` | Read one note by `note:` UID or by title (`--json`, `--db`, `--config`). Read-only; the CLI twin of the MCP `note_get` tool. **Exits 2** when the title or UID resolves to nothing |
  634. | `memory lint` | Health checks over the vault (stale notes, broken links, orphans). `--limit` 1–1000 (default 50) caps each category; `*_total` is always reported, and the human summary prints `N of M` when a category is truncated |
  635. | `memory consolidate` | Propose/apply tier promotions (logs → ideas → project files). `--limit` 1–1000 (default 50) caps returned proposals; human output discloses `proposals_total` when truncated |
  636. | `memory related` | Typed-edge traversal from a note (supersedes, depends-on, etc.). `--limit` 1–1000 (default 50) with `returned`/`total`/`truncated`; human output prints `N of M` when truncated |
  637. </details>
  638. <details>
  639. <summary>Publication Commands</summary>
  640. | Command | Description |
  641. |---------|-------------|
  642. | `publication rebuild --config <path>` | Build a fresh graph and every derived artifact beside the incumbent, validate it, then atomically activate it |
  643. | `publication status` | Inspect resumable operations and report corrupt/incompatible journals independently |
  644. | `publication cancel` | Request cooperative cancellation at an exact observed journal revision |
  645. | `publication discard` | Remove failed staging at an exact revision, or safely discard only an invalid journal |
  646. | `publication rollback` | Switch back one step to the retained predecessor while the daemon is stopped |
  647. | `repair` | Reconcile an index publication abandoned by a crashed indexer. While `<db>.index-dirty` exists for a full `index` publication — or a watcher marker is wedged — every ranked query fails closed; this removes the stale PageRank sidecar, advances the generation, clears the marker and recomputes. Refuses a marker it cannot prove abandoned unless `--force`, and never overrides a live writer |
  648. | `publication prune` | Reclaim slots nothing can still reach. Keeps the slot `CURRENT` selects, its retained predecessor (the one-step rollback target), and any slot an in-flight operation targets; `--dry-run` previews. Takes the publication-root lock, so it serializes against rebuild/rollback/discard |
  649. The regex-v3/embedding-v2 upgrade requires this one-time full rebuild. See the
  650. [publication rebuild and recovery guide](docs/guide/publication-rebuild.md).
  651. **Ranked reads during a publication.** Not every publication fails a ranked read
  652. closed any more. A `brain watcher batch` publication now lets ranked reads
  653. **succeed**, returning results plus a disclosure of what was in flight. A full
  654. `index` publication still fails closed, and so does a wedged watcher marker —
  655. those two are unchanged. MCP responses computed during a live publication carry
  656. four disclosure keys:
  657. | Key | Meaning |
  658. |-----|---------|
  659. | `publication_in_progress` | a publication was in flight while this answer was computed |
  660. | `marker_age_s` | age of the publication marker, in seconds |
  661. | `in_flight_note_paths` | the note paths being published, capped at 20 |
  662. | `in_flight_note_paths_truncated` | `true` when more than 20 paths were in flight |
  663. Known gap: CLI `--json` verbs that reshape the response into a typed struct —
  664. `nestweaver hubs --json` among them — drop these keys. Their absence from a CLI
  665. JSON payload is therefore not evidence that no publication was running.
  666. </details>
  667. <details>
  668. <summary>Analysis Commands</summary>
  669. | Command | Description |
  670. |---------|-------------|
  671. | `hubs` | Find most connected hub nodes (degree centrality + PageRank) |
  672. | `bridges` | Find architectural chokepoints (betweenness centrality) |
  673. | `pr-impact` | PR blast radius analysis with risk scoring (Low/Medium/High, or Unknown when a changed file could not be assessed); `--sarif` for code scanning, `--strict` to gate on contract-verified breaking changes |
  674. | `rts-eval record-truth` | Report a full-suite outcome from CI so selection quality can be measured |
  675. | `rts-eval report` | Measured file-recall / change-recall / selection-breadth of past selections (refuses percentages below 10 joined runs) |
  676. | `dead-code` | **A review aid, not a deletion list**, and it **refuses to produce one at all on a resolver-generation-stale graph** — exit `2`, `refused: true` with `reason: "outdated_resolver"` and a runnable `remedies[].command` on `--json`, on every route including MCP. A missing edge can only fail to *reach* a live symbol, so an under-resolved graph moves live code onto a deletion list; re-index with `nestweaver index --repo <path> --force` and re-run. Detects symbols no entry point *reaches*, which is not the same as "nothing references it" — a reference the parser does not capture is indistinguishable from no reference at all. Measured top-15 precision on Rust was **0/15**, and it remains poor on C++; treat *every* confidence tier as review candidates, never as proof. `unreachable_count` is the unfiltered total; `matching_count` reflects `--min-confidence`; `--limit` is 1–1000, default 50 (there is no "all"); `coverage: "degraded"` means the walk proved nothing — no entry point or module owner root (`entry_points + module_owner_roots == 0`), undecodable symbols in the store, or a language that contributed analysed symbols but zero entry points of its own (named in `languages_without_entry_points`) — so every row below is unreachable *by construction*. Rust `pub mod` Modules are never flagged. A Rust `impl` block is reachable when ANY of its members is, and a dead one now suppresses its own `Method` members instead of listing the block and every method separately (associated `Constant`s still surface). Rows are deterministically ordered with a uid tie-break, so which of them survive `--limit` no longer varies run to run |
  677. | `rerank` | Lightweight result reranker (off-by-default heuristic) |
  678. | `info` | Show hardware and configuration information |
  679. | `contracts list` | List API contracts derived from spec files + framework handlers |
  680. | `contracts drift` | Routes declared in a spec but not implemented, and vice versa (presence-level) |
  681. | `contracts diff` | Field/type-level OpenAPI breaking-change diff between two spec versions (`--base`/`--head`, `--fail-on-breaking` for CI) |
  682. | `ranking` | Inspect ranking priors |
  683. | `eval` | Offline retrieval-quality evaluation |
  684. | `export` | Export the graph in Cypher, GraphML, Mermaid, or MessagePack format (cypher/graphml/mermaid carry real PageRank scores; mermaid `--top N` ranks by PageRank; msgpack always writes to `--output`/`<db>.graph.msgpack`, never stdout). An invalid `--format` or `--scope` value now exits **64** (`EX_USAGE`), not 1 — an unsupported but valid *combination*, such as `--format cypher --scope vault`, still exits 1 |
  685. **What counts as an entry point.** Reachability is a forward walk from entry
  686. points, so what the parser accepts as one decides what `dead-code` reads as
  687. dead:
  688. - **bash** — `trap` handlers are entry points, including quoted flags and traps nested inside functions. Any command with no enclosing function also roots its same-file callee, so a script with a bare top level now has entry points at all; it used to have none, and every function in such a script read as 100% dead. **Trap handler resolution is SAME-FILE ONLY** — a handler defined in a `source`d file (`source lib.sh; trap cleanup EXIT`) is not resolved and shows as unreachable.
  689. - **Swift** — a top-level call in `main.swift`, or in a shebang-led file, roots its callee. Known gap: `swiftc foo.swift` on a file that is neither `main.swift` nor shebang-led is missed.
  690. - **Python** — a module-scope call roots a same-file function, which covers `if __name__ == "__main__":` with no special case for it. Restricted to bare identifiers (`obj.run()` roots nothing) and to functions, never methods.
  691. - **`module_init` (JS/TS/Python/PHP)** — calls a file makes at its top level, outside any function, class or method, are owned by a per-file `<module>` symbol, so the functions they call are live and show a caller in `impact`. That covers bare calls, IIFEs, Express-style handlers registered at load, decorators and `__main__` guards, and works across files (the owner calls an imported function). `require(...)` alone does not create an owner. An owner that calls something is also its own `<repo-relative path>::<module>` process, so the process list grows for files with decorators, route registration or top-level test setup. The owner is excluded from `dead-code` output and counted in `module_owner_roots`, not `entry_points`.
  692. - **C++** — an error-recovered, macro-prefixed declaration is re-anchored to its name's line, which CHANGES that symbol's UID. A local whose type is an inline anonymous struct or class is reclassified `Function` → `Variable` (the most-vexing-parse fix).
  693. - **Manifests** — `package.json` entry points are discovered at ANY depth, so a monorepo's `packages/*/package.json` counts. Paths are rebased against the manifest's own directory, and the `browser` field is now an entry file.
  694. </details>
  695. <details>
  696. <summary>Multi-Repo and Projects</summary>
  697. | Command | Description |
  698. |---------|-------------|
  699. | `list-projects` | List all projects defined in the instance config |
  700. | `project-context` | Get context scoped to a specific project. `--include-components` is now three-state: **omitting it means `true`**, which is the documented default the schema always declared — pass `--include-components false` to exclude component sub-projects. Before 9.0.0 the CLI sent an unconditional `false`, so the documented default was unreachable on this route. The MCP `kinds` filter, when it is only Symbol, does not seed or promote member notes into the walk |
  701. | `materialize-projects` | Materialize declared projects, wiki sources, and cross-repo links from instance config |
  702. | `detect-implicit-projects` | Detect implicit projects from vault structure and code patterns |
  703. | `suggest-links` | Discover potential cross-repo links between symbols |
  704. | `list-links` | List all cross-repo links in the instance |
  705. | `list-features` | List features spanning multiple repositories |
  706. | `clusters` | Detect community clusters in the dependency graph (Louvain-style local moving, single-level; results cached in a sidecar, `cluster <id\|name>` reads the cache) |
  707. | `cross-repo-contracts` | Run the MCP-compatible cross-repository contract query for a symbol name or UID |
  708. | `cross-repo-refs` | Same JSON envelope as `cross-repo-contracts` / the `cross_repo_contracts` MCP tool (including `link_type: "contract"` rows). `--limit` 1–1000 (default 50). `--repo` only disambiguates an ambiguous symbol name before that query; it is not the contracts row filter. Without `--repo`, an ambiguous name uses the same preferred match as `cross-repo-contracts` |
  709. </details>
  710. <details>
  711. <summary>Server and Admin</summary>
  712. | Command | Description |
  713. |---------|-------------|
  714. | `mcp` | Start the MCP server (43 tools; 36 in direct read-only mode; 6 with `--lite`; auto-starts daemon) |
  715. | `daemon` | Manage the background daemon (`start`, `stop`, `status`, `restart`, `gc`; `run --server` for server mode). `daemon status` exits 69 when the daemon is running but unhealthy |
  716. | `connect` | Connect to an upstream NestWeaver server (federated read/impact) |
  717. | `server` | Server management utilities (`init-tls`, `backup`, `status`) |
  718. | `ui` | Launch the interactive web UI |
  719. | `setup` | Auto-detect and configure AI tools (16 supported). Use `--force` to regenerate customized files |
  720. | `generate-guide` | Generate tool-specific instruction files (skill, cursor-rule, agents-md, claude-md) |
  721. | `completions` | Generate shell completions (bash, zsh, fish, powershell) |
  722. | `embed` | Generate vector embeddings for symbols, notes, and headings using a local model (Metal-accelerated) or external API. Reports an eligibility plan before embedding and exits successfully without loading the model when nothing is eligible; `--force` re-embeds everything |
  723. | `pull` | Pull repository source into a local workspace (sparse checkout by default; `--full`, `--pinned`, `--ephemeral`) |
  724. | `config validate` | Validate an instance config without creating files or contacting services (`--json` for a machine-readable result) |
  725. | `diagnostics capabilities` | Report embedding and Metal compile/runtime capabilities, including whether Metal was selected or fell back (`--json`) |
  726. | `instance` | Manage instance configuration. `abort-migration` clears a wedged migration journal so the daemon can boot |
  727. | `snapshot` | Manage graph snapshots (build, verify, push) |
  728. | `backup` | Backup and restore the NestWeaver database |
  729. | `list-repos` | List all indexed repositories |
  730. | `remove-repo` | Remove an indexed repository and all its data (symbols, files, services, contracts) from the graph |
  731. | `remove-project` | Remove a materialized project and its edges from the graph |
  732. | `prune-stale` | Remove repos and vaults whose source directories no longer exist on disk |
  733. | `compact-embeddings` | Reclaim embedding vectors left behind by deleted nodes (`--dry-run`, `--json`); no model load |
  734. | `list-services` | List all detected services |
  735. | `service-summary` | Display a summary of a specific service |
  736. | `admin` | Subagent guidance instructions |
  737. | `interactions` | Manage interaction memory (`status`, `show`, `clear`, and `forget <uid>` to drop one node's memory while leaving the rest intact) |
  738. | `extensions` | Read back the annotations agents write via the `set_extension` MCP tool (`list`, and `unset` to remove one property from one node) |
  739. | `hooks` | Install/remove the local pre-push blast-radius check (`--install`, `--strict`, `--uninstall`, `--db`) |
  740. | `pre-push-impact` | Analyse local changes against the org-wide graph (alias `ppi`). The `hooks` pre-push check runs `pr-impact`, not this command |
  741. | `format-comment` | Format impact analysis results as a PR/MR comment, for CI to post |
  742. </details>
  743. ### Local pre-push check
  744. Get "confidence before you push" from the same hardened blast-radius analysis CI runs — locally, on your machine:
  745. ```sh
  746. nestweaver hooks --install --db "$(pwd)/nestweaver.lbug"
  747. ```
  748. This writes a `.git/hooks/pre-push` that runs `nestweaver pr-impact` against the merge-base before every push. It is **advisory by default**: it **never blocks** your push (fail-open), stays **silent on a trivial change**, and prints a concise banner — the gate verdict, the top affected symbols, and a coverage caveat when the analysis was incomplete — only when there's something to review. A degraded/incomplete run never blocks, because an incomplete traversal can't be trusted to have found the risk.
  749. To make it block a push (exit 2) on a **contract-verified breaking change** — a decidable API-signature break, not a heuristic:
  750. ```sh
  751. nestweaver hooks --install --strict
  752. ```
  753. What `--strict` blocks on is configurable via the `[pr_impact]` section of `nestweaver-instance.toml` (`strict_block_on_breaking`, default `true`; `strict_block_on_high_risk`, default `false` — opt in to also block on a complete High-risk run). A degraded/incomplete run is never blocked on risk.
  754. Remove it (restoring any hook it backed up) with:
  755. ```sh
  756. nestweaver hooks --uninstall
  757. ```
  758. You can also run the check manually — this is exactly what the hook does:
  759. ```sh
  760. nestweaver pr-impact --base origin/main # advisory banner
  761. nestweaver pr-impact --base origin/main --strict # exit 2 on a contract-verified breaking change (default policy)
  762. ```
  763. ## Features
  764. <details>
  765. <summary>Markdown Brain</summary>
  766. Index Obsidian vaults and markdown directories alongside your code. NestWeaver builds a unified knowledge graph that connects notes, sections, and tags to code symbols — letting you query across both worlds. Wiki/HTML content is auto-converted to markdown during ingestion. Use `.brainignore` for glob exclusion patterns or `--ignore` for ad-hoc filtering.
  767. ```sh
  768. # Add a vault to the knowledge graph
  769. nestweaver brain add ~/Documents/Obsidian/MyVault
  770. # Search across code symbols and vault notes
  771. nestweaver brain search "architecture"
  772. # Get unified context spanning code and notes
  773. nestweaver brain context "MyProject"
  774. ```
  775. </details>
  776. <details>
  777. <summary>Semantic Search (Embedding Seed Layer)</summary>
  778. NestWeaver embeds symbols, notes, and headings using the configured local or
  779. external backend, then uses semantic similarity as one of the signals ranking
  780. the graph walk. Backend and device selection are explicit: failures are
  781. reported and never switch to another backend or device.
  782. ```sh
  783. # Embed all indexed content (one-time, incremental after)
  784. nestweaver embed --stats
  785. # Ask a question in plain language
  786. nestweaver investigate "how does the daemon decide when to reindex a repository"
  787. nestweaver investigate "where does the upload pipeline start"
  788. ```
  789. **Use `investigate` for a question; use `context`/`brain context` for a name
  790. you already know.** This is the one distinction worth learning up front.
  791. `context` and `brain context` RESOLVE their argument to seed nodes — as a UID,
  792. note title, tag, symbol name, or a qualified name such as `path::name`, `path::<module>` or `Class::method` — and a multi-word question resolves to none of
  793. those, so they exit 2 with `No seeds resolved` even on a fully embedded graph
  794. with a daemon running (under `--json`, the not-found envelope's `message`
  795. carries that text, including the `investigate` command to run instead). `investigate` is the natural-language entry point: when
  796. seed resolution finds nothing it falls back to BM25 over the corpus, so a
  797. question still returns an answer.
  798. Three retrieval signals are fused via Convex Combination: PPR (graph
  799. structure), BM25 (text match), and semantic (embedding similarity). Semantic
  800. similarity re-ranks and blends candidates; it is not, on its own, a
  801. natural-language front door for the seed-resolving commands.
  802. **Device policy.**
  803. | `accelerator` | Local-backend behavior |
  804. | --- | --- |
  805. | `auto` | Metal in a Metal-enabled build; CPU only when Metal is not compiled. A Metal failure is reported; `auto` does not retry on CPU. |
  806. | `metal` | Requires Metal to be compiled and the device plus full model inference probe to succeed; otherwise embedding state is `failed`. |
  807. | `cpu` | Selects CPU directly and never probes Metal. |
  808. **Model selection and cache.** The default is the light, fast
  809. `sentence-transformers/all-MiniLM-L6-v2` (384-dim, ~90MB) — a good fit for most
  810. repos and CPU-only servers. NestWeaver records the model used for each database,
  811. and the daemon loads that recorded model to avoid dimension mismatches. Daemon
  812. startup is cache-only: it never downloads model files or contacts Hugging Face.
  813. The configured `cache_dir` expands a leading `~/` against the daemon user's home
  814. directory.
  815. **A missing model cache repairs itself.** If the recorded model is absent from
  816. the cache, `nestweaver embed` recovers it in one call — no `daemon stop`, no
  817. restart. It downloads the missing artifacts, loads them, prints one line ahead
  818. of the normal summary, and exits 0:
  819. ```sh
  820. nestweaver embed --db /absolute/path/to/brain.lbug
  821. # Downloaded missing embedding model '<id>' into <cache-dir> and loaded it (device: <device>).
  822. ```
  823. The daemon repairs itself too, in a bounded background seed. When a boot load
  824. fails because the artifacts are missing, the backend is local, and the database
  825. already carries a verified embedding identity naming that model, the daemon
  826. downloads it in the background **after** the socket is bound — so boot stays
  827. cache-only and the download never delays it. It is never a first-time download:
  828. with no recorded identity there is nothing to repair and nothing is fetched. At
  829. most 5 attempts, backing off 30s / 2m / 8m / 30m (each jittered ±20%), stopping
  830. early on a permanent error (404, 401, 403, permission denied, ENOSPC). Opt out
  831. with `[embedding] auto_repair_cache = false` — it defaults to `true`.
  832. `brain status` grows a `Download:` line while a seed is running, naming who
  833. asked for it and which attempt is in flight:
  834. ```text
  835. Download: <done> of <total> (automatic repair, attempt N of M)
  836. Download: <done> of <total> (requested by nestweaver embed)
  837. Download: retry N of M in <duration>
  838. ```
  839. While a seed is active the embedding state is `"seeding"`. It takes precedence
  840. over every other state, `ready` included, and reports
  841. `degraded_components: ["semantic"]`.
  842. **External embedding endpoints.** Instead of a local model you can embed via an
  843. OpenAI-compatible endpoint:
  844. `nestweaver embed --endpoint http://localhost:11434 --model nomic-embed-text`
  845. (Ollama), or a hosted gateway. For keyed gateways (OpenAI, Azure), set
  846. `NESTWEAVER_EMBED_API_KEY` — it is sent as a bearer token and is never written
  847. to config, the graph, or a snapshot. An external endpoint is authoritative: a
  848. load or request failure is reported and does not load a local model. Switching
  849. backends requires both an explicit configuration change and re-embedding:
  850. remove `external_endpoint`, stop the daemon, and replace the recorded external
  851. model metadata/vectors with the chosen local model.
  852. **The stop/start recipe below is for an intentional model SWITCH only** — it is
  853. the one case that still needs one. It is not the repair for a missing cache:
  854. that is a single `nestweaver embed` call with the daemon left running, described
  855. above. `--force` appears here because you are deliberately discarding the
  856. recorded model and its vectors, never because a download is missing:
  857. ```sh
  858. CONFIG=/absolute/path/to/nestweaver-instance.toml
  859. DB=/absolute/path/to/brain.lbug
  860. MODEL=sentence-transformers/all-MiniLM-L6-v2
  861. CACHE="$HOME/.cache/nestweaver/models"
  862. nestweaver daemon --db "$DB" stop
  863. nestweaver embed --db "$DB" --local --model-id "$MODEL" --cache-dir "$CACHE" --force
  864. nestweaver daemon --db "$DB" start --config "$CONFIG"
  865. ```
  866. NestWeaver records the index dimension and rejects mismatched vectors, so any
  867. model/backend switch requires `--force`. The direct path
  868. (`--endpoint`/`--local`) cannot run while a daemon holds the DB write lock; stop
  869. that daemon first or, when the configured daemon backend is already ready, drop
  870. both direct-path flags.
  871. **Stopping.** `nestweaver daemon stop` drains in-flight writes with every
  872. listener still up, so reads keep working while it drains (individual reads can
  873. still stall for seconds while a write commits), and an idle daemon exits
  874. immediately. New writes over the gRPC surface are refused with `UNAVAILABLE`
  875. once shutdown starts, so the drain always finishes (the web admin routes are
  876. outside that gate — see CLAUDE.md). It never SIGKILLs on its own — if a write is still
  877. running it reports what it observed and leaves the daemon up; `daemon stop
  878. --force` or `kill -9` end it anyway, abandoning that write. Under a process supervisor (systemd
  879. `TimeoutStopSec`, launchd `ExitTimeOut`, Docker `stop_grace_period`) the
  880. supervisor's own timer still applies. See the
  881. [Daemon Shutdown Guide](docs/guide/daemon-shutdown.md).
  882. **Readiness and diagnostics.** On macOS, background start/autostart uses launchd
  883. to own a foreground daemon process; `daemon run` stays in the invoking
  884. foreground. Neither path forks or self-daemonizes. Readiness is published only
  885. after a real embedding inference succeeds. Inspect compile/runtime capability
  886. and the selected backend with:
  887. ```sh
  888. nestweaver diagnostics capabilities --json
  889. nestweaver daemon --db <path> status
  890. nestweaver brain status --db <path> --json
  891. ```
  892. The status reports `requested_device`, `selected_device`, and `fallback_used`.
  893. A local backend is ready only when `selected_device` is `metal` or `cpu` and
  894. `fallback_used` is `false`; an external backend has no local selected device.
  895. When semantic retrieval was requested but unavailable, context responses keep
  896. the graph/PPR/BM25 result and report `"semantic"` in `degraded_components`
  897. (the only value in that vocabulary today). Every path reports both fields: the
  898. direct, daemon and `brain_search` paths, and the hybrid/federated merges for
  899. `brain_search` and for `brain_context` / `project_context`. In a merge,
  900. `semantic_applied` is the AND across contributing tiers and
  901. `degraded_components` their deduplicated union; when no tier reports either
  902. field the merge omits both, so an absent field still means "not reported by any
  903. tier", never a synthesised `false`. Caveat: `semantic_applied` is one boolean,
  904. so a merge in which one tier ranked semantically and the other did not reports
  905. `false` — correct for the merged row set, which contains lexically ranked rows,
  906. but it does not say which tier was which.
  907. **Performance:** 7ms query embedding (Metal), 37ms (CPU) for all-MiniLM;
  908. heavier models trade speed for quality. Forward Push PPR replaces power
  909. iteration for sub-10ms graph walks. LRU cache makes repeated queries instant
  910. (~8ms).
  911. Configure the model and fusion weights in `instance.toml`:
  912. ```toml
  913. [embedding]
  914. # Shipped default; the model a DB was actually embedded with is recorded and
  915. # auto-loaded by the daemon. Set this to override the default for fresh instances.
  916. model_id = "sentence-transformers/all-MiniLM-L6-v2"
  917. # cache_dir defaults to the platform-native cache directory:
  918. # ~/Library/Caches/nestweaver/models on macOS, $XDG_CACHE_HOME/nestweaver/models
  919. # (or ~/.cache/nestweaver/models) on Linux. Explicit values may use ~/.
  920. # If unavailable or non-UTF-8, a UTF-8 HOME uses ~/.cache first. The final
  921. # fallback is /var/cache/nestweaver/models on Unix or C:\ProgramData\nestweaver\models
  922. # on Windows; set cache_dir explicitly if that system location is not writable.
  923. # cache_dir = "~/Library/Caches/nestweaver/models"
  924. accelerator = "auto" # auto | metal | cpu; see the policy table above
  925. weight_ppr = 0.40
  926. weight_bm25 = 0.25
  927. weight_semantic = 0.35
  928. ```
  929. </details>
  930. <a id="macos-app"></a>
  931. <details>
  932. <summary>macOS App</summary>
  933. NestWeaver can build a native macOS `.app` bundle from source. No release
  934. `.app` bundle or DMG is currently published. A source build provides:
  935. - **Menubar status icon** with quick access to the web UI and daemon status
  936. - **Metal GPU acceleration** — the app launches the daemon as a non-forking launchd Aqua agent, then the daemon proves full model inference before reporting the Metal backend ready (~5x faster: 7ms vs 37ms).
  937. - **Managed daemon lifecycle** — launches the daemon via launchd (which owns crash-restart); the daemon is a shared service (MCP/CLI/UI all use it) and persists across app quits, so the app re-attaches to it on next launch
  938. - **Daemon coexistence** — detects if a daemon is already running (via CLI or launchd) and connects to it instead of starting a second instance
  939. - **Web UI** at `http://127.0.0.1:9377` — opens automatically on launch
  940. ```sh
  941. # Build from source (requires Xcode Command Line Tools)
  942. bash app/build.sh
  943. open target/release/NestWeaver.app
  944. ```
  945. The app is menubar-only (no Dock icon). Click the NestWeaver icon in the menubar to open the web UI or quit. Database is auto-detected from `NESTWEAVER_DB`, `~/.nestweaver/instance.toml`, or `~/.local/share/nestweaver/*/brain.lbug`.
  946. **When to use the app vs CLI:**
  947. - Use the **app** for always-on daemon with Metal GPU, menubar access, and the web UI
  948. - Use the **CLI** (`nestweaver daemon start`) for headless/server environments, CI, or if you prefer terminal-only workflows
  949. </details>
  950. <details>
  951. <summary>Projects</summary>
  952. Group repositories, features, and configuration into named projects using TOML config files. Projects scope queries and context to just the code that matters.
  953. ```toml
  954. # nestweaver-instance.toml
  955. [[projects]]
  956. name = "payments"
  957. repos = ["payments-api", "payments-worker"]
  958. components = ["checkout", "refunds"]
  959. ```
  960. ```sh
  961. nestweaver project-context "payments" --token-budget 5000
  962. ```
  963. </details>
  964. <details>
  965. <summary>Multi-Repo and Instance Config</summary>
  966. Manage multiple repositories as a single graph. NestWeaver discovers cross-repo dependencies, suggests links between related symbols, and lets you query across repository boundaries.
  967. See the [Instance Config Guide](docs/guide/instance-config.md) for full configuration options. If an older database mixes instance_id conventions, the [Instance ID Migration Runbook](docs/guide/instance-id-migration.md) consolidates it.
  968. ```sh
  969. # Discover cross-repo links
  970. nestweaver suggest-links --db ./all.lbug
  971. # Get context for a feature spanning multiple repos
  972. nestweaver context --feature device-pairing --config ./nestweaver-instance.toml --db ./all.lbug
  973. ```
  974. **Runtime-configurable defaults** — set `[limits]` in your instance config to replace the builtin a command passes into `resolve_limit`. That builtin is not one number. Unset, `search` uses 10, `brain search` uses 20, and `brain context` uses 30. Commands whose builtin is `DEFAULT_RESULT_LIMIT` use 50. `code_context` is not in that set: it returns up to 500 connected symbols. `brain_context` is sized by `token_budget` (default 2000), not by a page size.
  975. ```toml
  976. [limits]
  977. default_result_limit = 100
  978. ```
  979. CLI commands (`search`, `brain search`, `brain context`) also respect this setting when `--limit` is not explicitly passed. The `[response]` section controls inline body thresholds.
  980. </details>
  981. ## MCP Server
  982. For manual installation and the proposed official registry listing, see the
  983. [MCP Registry guide](docs/guide/mcp-registry.md). Registry publication requires
  984. a separate npm release and maintainer approval.
  985. NestWeaver exposes **43 tools** via the [Model Context Protocol](https://modelcontextprotocol.io), giving any MCP-compatible AI agent structured access to your codebase graph without reading source files directly.
  986. > **Where that number comes from.** The registry is
  987. > `all_tool_schemas_undecorated()` in `crates/nestweaver-mcp/src/tools.rs`, and
  988. > `tool_doc_tests::all_tools_have_doc_categories` asserts the documented tool
  989. > table covers exactly `tool_list(false)["tools"].len()`. Do not restate the
  990. > count from memory — read it back off the wire with a `tools/list` call, or
  991. > count the registry.
  992. ```sh
  993. nestweaver mcp --db ./nestweaver.lbug
  994. nestweaver mcp --tools brain_context,brain_search,read_symbols --db ./nestweaver.lbug # allowlist specific tools
  995. # Local MCP sessions connect to the daemon; direct mode is CI-only.
  996. ```
  997. Direct read-only mode advertises **36** tools — the registry minus the seven
  998. names in `MUTATING_TOOLS` (`crates/nestweaver-mcp/src/http.rs`):
  999. `brain_add_source`, `brain_remove_source`, `brain_memory_consolidate`,
  1000. `set_extension`, `unset_extension`, `prune_stale`, `compact_embeddings` — and
  1001. rejects mutations before dispatch. Daemon-backed stdio exposes all 43.
  1002. `--lite` exposes 6. `--tools` names are
  1003. exact, case-sensitive registry names; unknown, duplicate, empty, or transport-
  1004. unavailable names fail at startup instead of silently producing an empty tool
  1005. surface.
  1006. Every tool schema now carries MCP `annotations` (`readOnlyHint`,
  1007. `destructiveHint`, `idempotentHint`, `openWorldHint`), derived from the same
  1008. `MUTATING_TOOLS` table, so a client can tell `prune_stale` from `brain_status`
  1009. on the wire.
  1010. **Wire change in 9.0.0:** result provenance (`_meta`) moved from the outer
  1011. `tools/call` envelope into the **payload**, and lost its `nestweaver.io/`
  1012. prefix. The shape is now `_meta: { scope, sources, stale_repos }` — see
  1013. `crates/nestweaver-schema/src/provenance.rs`. Raw HTTP MCP clients that read
  1014. `nestweaver.io/sources` off the envelope must be updated.
  1015. The MCP server automatically starts a background daemon that owns the database. Multiple MCP servers, CLI commands, and IDE integrations can share the same database concurrently without lock contention. The daemon exits after 1 hour of inactivity.
  1016. ```sh
  1017. nestweaver daemon status --db ./nestweaver.lbug # check daemon state
  1018. nestweaver daemon stop --db ./nestweaver.lbug # stop the daemon manually
  1019. pgrep -af "nestweaver daemon" # find running daemons (Linux)
  1020. ```
  1021. 43 tools including type-aware context retrieval, confidence-weighted impact analysis (`impact_score` shows how strongly changes propagate), investigation bundles, co-change detection, dead code analysis, community detection, and vault/notes integration. Use `--tools` to expose only the tools you need. The `--tools`/`--lite` allowlists are enforced on every transport (local stdio, daemon proxy, hybrid, and MCP-over-HTTP), and tool schemas validate their arguments — numeric bounds (e.g. `token_budget` 1–16000, `depth`/`max_depth` 1–15) are enforced and unknown argument names are rejected instead of silently ignored.
  1022. ### Key capabilities
  1023. - **Type-aware call resolution** — AST-extracted type bindings (annotations, constructors, self/this, return types) resolve `obj.method()` calls to the correct target class
  1024. - **Confidence-weighted blast radius** — `impact_score` decays multiplicatively through edges; low-confidence paths are pruned
  1025. - **Co-change mining** — Jaccard-scored file pairs from git history surface files that always change together
  1026. - **MRO walk** — inherited methods resolved via class hierarchy traversal (depth 5, cycle-safe)
  1027. External MCP servers can be configured in your instance config with `timeout_secs` (default 30):
  1028. ```toml
  1029. [[mcp_servers]]
  1030. name = "wiki-mcp"
  1031. command = "wiki-mcp"
  1032. timeout_secs = 60
  1033. ```
  1034. ## Web UI
  1035. A search-first, task-lens workspace over your code+notes graph, powered by Three.js/React-Three-Fiber. The landing view is a **repo-galaxy constellation** — one luminous cluster per repository — rendered dark-first with selective HDR bloom, in-scene SDF labels, and a procedural nebula backdrop. Everything encodes meaning: color = kind, size = importance, and Spark-green convergence rings mark betweenness bridges (architectural chokepoints).
  1036. ```sh
  1037. nestweaver ui --db ./nestweaver.lbug --port 8080
  1038. nestweaver ui --db ./nestweaver.lbug --port 8080 --watch # live re-indexing
  1039. ```
  1040. <p align="center">
  1041. <img src="assets/web-ui-screenshot.png" width="700" alt="NestWeaver Web UI — repo-galaxy constellation with glowing hubs">
  1042. </p>
  1043. <p align="center">
  1044. <img src="assets/web-ui-graph.png" width="700" alt="NestWeaver Web UI — focused symbol with tri-panel source evidence">
  1045. </p>
  1046. **Work by task, not by graph theory:**
  1047. - **Workspace scope** — switch between all indexed content, a single repo, or a vault; every view carries an honest trust chip (local-only / federated, current / stale, partial / truncated)
  1048. - **Command bar (`⌘K`) + Search Phrases** — plain-language queries resolve to typed scenes deterministically: `impact of <symbol>`, `trace flow from <symbol>`, `callers of <symbol>`, `path from <A> to <B>`, `notes about <topic>`, `backlinks for <note>`, `hubs in <repo>`, `dead code in <repo>`, `stale repos`
  1049. - **Task lenses** — Overview, Context, Impact (layered blast-radius DAG with affected tests and local/org trust states), Trace (execution stepper), Repos, Features, Local neighborhood
  1050. - **Tri-panel workspace** — activating a node opens a focused graph, synced source/note evidence, and a knowledge card (identity, role, evidence, relationships, trust, next actions), cross-highlighted
  1051. - **Graph / table / JSON parity** — every result set is inspectable as a graph, an accessible table, or raw JSON with provenance/trust `_meta`
  1052. - **Deep links** restore workspace scope, selected node, active lens, and representation mode
  1053. **Visual & motion** (all gated behind `prefers-reduced-motion`, which the UI auto-detects):
  1054. - Selective HDR bloom via Khronos PBR-Neutral tone mapping — loud only on focus, hubs, and bridges; the ambient field stays calm
  1055. - In-scene SDF text labels with collision-aware placement (labels never overlap nodes) and a landmark hierarchy that reveals detail on zoom
  1056. - Per-galaxy glowing edge web, hub coronas, and settle-and-freeze force layout that preserves spatial memory across re-indexing
  1057. - Signature moments: repo-galaxy ignition on load and a focus impact-ripple that traces blast radius
  1058. - Community overlay (Louvain), minimap, and an explicit System / Light / Dark theme control
  1059. **Accessibility:** all six task journeys have a keyboard-only path; reduced-motion preserves every static meaning channel; graph answers always have a table/JSON equivalent; a screen-reader landmark summary mirrors the canvas.
  1060. **WASM mode** — Append `?engine=wasm` to load a WebAssembly copy of the graph snapshot. The browser downloads a MessagePack snapshot and the status bar shows its node and edge counts. Queries, including PPR, run on the server. Requires building the wasm first (use `--remap-path-prefix` so the build
  1061. machine's home path isn't baked into the artifact):
  1062. `RUSTFLAGS="--remap-path-prefix=$HOME=/build" wasm-pack build crates/nestweaver-wasm --target web --out-dir ../../crates/nestweaver-web/frontend/src/wasm`.
  1063. **Keyboard shortcuts** (press `?` in the UI for the full list):
  1064. - `1`–`6` — switch task mode (Overview, Context, Impact, Repos, Features, Local)
  1065. - `⌘K` — open the ask / Search-Phrase command bar · `/` — focus search
  1066. - `⌘L` — cycle graph / list / matrix representation · `⌘⇧G` — toggle zen (canvas-only) layout
  1067. - `I` — impact of selected · `P` — path from selected · `M` / `C` / `T` — minimap / communities / tags
  1068. - `⌘Z` / `⌘⇧Z` — navigate history back / forward · `Esc` — clear selection
  1069. ## Architecture
  1070. <details>
  1071. <summary>Cargo workspace with 15 crates compiling to a single static binary + optional WASM module</summary>
  1072. | Crate | Description |
  1073. |-------|-------------|
  1074. | `nestweaver-schema` | Node/edge types, UIDs, confidence scoring, schema versioning |
  1075. | `nestweaver-parser` | Tree-sitter + regex parsing for 32 languages |
  1076. | `nestweaver-resolver` | Cross-file symbol resolution with import graphs, monorepo workspace packages, and tsconfig path aliases |
  1077. | `nestweaver-store` | LadybugDB graph store, PageRank, hybrid search |
  1078. | `nestweaver-storage` | Pluggable snapshot storage backends (local, S3, GitLab) |
  1079. | `nestweaver-engine` | Indexing pipeline, query dispatch, config, snapshots, LLM integration |
  1080. | `nestweaver-algorithms` | Pure-compute graph algorithms (PPR, impact BFS) — WASM-compatible, no I/O |
  1081. | `nestweaver-embed` | Local embedding models (candle; Metal GPU on macOS) for vector search |
  1082. | `nestweaver-proto` | gRPC service definition (protobuf) for daemon IPC |
  1083. | `nestweaver-federation` | Federation coordinator — upstream routing, health/ejection, two-tier merge, staleness (leaf; used by client + daemon-mode mcp) |
  1084. | `nestweaver-daemon` | Background daemon — owns the database, serves gRPC over Unix socket |
  1085. | `nestweaver-client` | Daemon client with auto-start, flock-based race prevention, version check |
  1086. | `nestweaver-mcp` | MCP server — proxies tool calls through the daemon |
  1087. | `nestweaver-web` | Web UI (Three.js/R3F) and Axum API backend |
  1088. | `nestweaver-wasm` | Browser-side WASM module wrapping nestweaver-algorithms |
  1089. ```
  1090. schema (zero internal deps)
  1091. <- parser
  1092. <- resolver
  1093. <- store
  1094. algorithms (zero internal deps — WASM target)
  1095. <- wasm
  1096. storage (zero internal deps)
  1097. proto (generated gRPC types)
  1098. federation (leaf: schema + proto — upstream routing/merge/staleness)
  1099. <- engine <- (parser, resolver, store, storage, algorithms)
  1100. <- daemon <- (engine, store, mcp, proto)
  1101. <- client <- (proto, daemon, federation)
  1102. <- mcp <- (engine, store, schema; proto + federation under the `daemon` feature)
  1103. <- web
  1104. ```
  1105. </details>
  1106. ## Performance
  1107. <table>
  1108. <tr>
  1109. <td width="50%" valign="top">
  1110. **71ms** query p50<br>
  1111. Next.js — 29,402 files
  1112. </td>
  1113. <td width="50%" valign="top">
  1114. **632ms** incremental re-index<br>
  1115. Tailwind CSS — no full rebuild needed
  1116. </td>
  1117. </tr>
  1118. <tr>
  1119. <td width="50%" valign="top">
  1120. **14.8M** edges extracted<br>
  1121. Elasticsearch — 511K symbols, 43K files
  1122. </td>
  1123. <td width="50%" valign="top">
  1124. </td>
  1125. </tr>
  1126. </table>
  1127. <details>
  1128. <summary>Benchmark results (NestWeaver vs Graphify)</summary>
  1129. **Query Speed (p50)**
  1130. | Repository | Files | NestWeaver | Graphify |
  1131. |---|---:|---:|---:|
  1132. | Tailwind CSS | 542 | **157ms** | 185ms |
  1133. | Deno | 14,136 | **82ms** | 1,355ms |
  1134. | Next.js | 29,402 | **71ms** | 2,440ms |
  1135. | Elasticsearch | 43,806 | **617ms** | crashed |
  1136. **Indexing Speed**
  1137. | Repository | NestWeaver | Graphify |
  1138. |---|---:|---:|
  1139. | Tailwind CSS | 3.6s | 2.5s |
  1140. | Deno | 51s | 33s |
  1141. | Next.js | **33s** | 111s |
  1142. | Elasticsearch | **3,462s** | crashed |
  1143. **Incremental re-indexing** (NestWeaver only — Graphify requires full re-index): 632ms (Tailwind), 4.0s (Next.js), 73s (Elasticsearch).
  1144. **Graph depth**: NestWeaver extracts 142K symbols / 280K edges on Deno (vs Graphify's 76K / 177K). On Elasticsearch: 511K symbols, 14.8M edges.
  1145. **Result quality**: NestWeaver returns ~30 connected symbols per query ranked by PageRank with full signatures. Graphify returns file-level nodes with 9-15% garbage stubs.
  1146. *Benchmarked in daemon mode on M3 Pro (36 GB). See [benchmarks/](benchmarks/) to reproduce.*
  1147. </details>
  1148. ## Contributing
  1149. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on building, testing, and submitting changes.
  1150. ## License
  1151. [MIT](LICENSE)
  1152. ---
  1153. <p align="center">
  1154. <a href="https://kehl.io">
  1155. <img src="assets/kehl-io/kehl-icon.png" width="56" alt="kehl.io" />
  1156. </a>
  1157. <br>
  1158. <sub>Built by <a href="https://kehl.io">kehl.io</a></sub>
  1159. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.