weavatrix 0.1.4 → 0.2.0

package/README.md

@@ -5,8 +5,8 @@
 Grep sees text. Weavatrix sees structure. It builds a dependency graph of any local repository —
 files, symbols, and the imports/calls/inheritance connecting them — and serves it to Claude Code,
 Codex, or any MCP client: change impact, transitive dependents, health audit, clone detection,
-coverage mapping. **23 tools available; 21 offline tools enabled by default, including one-call
-repository switching. Local-first: with the defaults, no repository data leaves your machine.**
+coverage mapping. **32 tools available; 29 enabled by the default offline profile. Local-first: with
+the defaults, no repository data leaves your machine.**
 
 - Website: [weavatrix.com](https://weavatrix.com)
 - Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
@@ -23,16 +23,16 @@ answers grep can't produce:
   out before you ship.
 - *"Who calls this function?"* → `get_dependents` walks reverse edges transitively: every caller,
   importer and subclass that can feel the refactor, ranked by proximity × connectivity.
-- *"Did my refactor actually decouple anything?"* → `rebuild_graph` + `graph_diff` report the
-  structural delta: new module dependencies, broken or introduced import cycles, symbols that lost
-  their last caller.
+- *"Did my refactor actually decouple anything?"* → `graph_diff base_ref=HEAD~1` builds an immutable
+  baseline graph without checking it out, then reports the structural delta: new module
+  dependencies, broken or introduced import cycles, and symbols that lost their last caller.
 
 ## Quick start
 
 Requires Node ≥ 18. One command:
 
 ```sh
-# Claude Code — offline default; open_repo can switch local repositories:
+# Claude Code — offline default; local repository switching is available explicitly:
 claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>
 ```
 
@@ -51,20 +51,33 @@ startup_timeout_sec = 20
 tool_timeout_sec = 60
 ```
 
-The default includes offline repository switching but excludes every network tool. Pass a final
-comma-separated capability list only to restrict or extend it:
+The package has one binary and several explicit security profiles. The omitted profile is `offline`:
+all local analysis plus `open_repo`, with every HTTP tool absent. Pass one profile as the final
+argument when a stricter repository boundary or a network feature is wanted:
+
+| Profile | Local repository switching | Cross-repo graph reads | OSV requests | Hosted sync / contract pull |
+|---|---:|---:|---:|---:|
+| `offline` (default) | Yes, only through `open_repo` | Yes, only through `trace_api_contract` | No | No |
+| `pinned` | No | No | No | No |
+| `osv` | Yes | Yes, only when called | Only when `refresh_advisories` is called | No |
+| `hosted` / `full` | Yes | Yes, only when called | Only when called | Only when `sync_graph` or `pull_architecture_contract` is called |
 
 ```sh
-# Pin the registration to one repository (hide open_repo/list_known_repos):
-claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build
+# Hard-pin one repository and expose no network tools:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> pinned
 
-# Add network tools while pinning one repository:
-claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build,online
+# Add only explicit OSV refresh:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> osv
 
-# Add network tools and keep the default repository switching:
-claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build,retarget,online
+# Enable the owner-authenticated hosted workflow:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> hosted
 ```
 
+Advanced registrations may still pass an exact comma-separated capability set:
+`graph,search,source,health,build,retarget,crossrepo,advisories,hosted`. The former `online` capability remains
+a compatibility alias for `advisories,hosted`; new registrations should use the named profiles or
+the narrower capability names.
+
 Or clone it:
 
 ```sh
@@ -73,16 +86,18 @@ cd weavatrix && npm install
 claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.mjs <repoRoot>
 ```
 
-- `<repoRoot>` — the repository to start with; the graph location is derived automatically
-  (`<repoRoot-parent>/weavatrix-graphs/<repoName>/graph.json`). Pass an explicit
+- `<repoRoot>` — the repository to start with; the graph location is derived automatically in the
+  per-user registry (`~/.weavatrix/graphs/<repository-storage-key>/graph.json`; its stable UUID is
+  stored beside it in `.repository-id`). Pass an explicit
   `<graph.json> <repoRoot>` pair instead if you keep graphs elsewhere.
 
 No graph yet? Ask the agent to call `rebuild_graph`; it builds the missing graph locally.
-`open_repo` can change the active repository and builds a missing graph automatically. A normal
+With the default `offline` profile (or an explicit capability set containing `retarget`),
+`open_repo` can change the active repository
+and builds a missing graph automatically. A normal
 `open_repo` call also upgrades graphs created before `0.1.4` to edge metadata v2; `build:false`
 probes without building and refuses a legacy graph. Retargeting is offline but intentionally changes
-the filesystem boundary for subsequent tools; omit `retarget` from an explicit capability list when
-a registration must stay pinned to one repository.
+the filesystem boundary for subsequent tools; select `pinned` when that boundary must not move.
 
 An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install as
 `~/.claude/skills/weavatrix/SKILL.md`.
@@ -91,7 +106,8 @@ An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — instal
 
 **graph** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`,
 `shortest_path`, `get_community`, `list_communities`, `module_map`, `get_dependents`,
-`change_impact`, `graph_diff`. Runtime dependencies, TypeScript type-only coupling and language
+`change_impact`, `git_history`, `graph_diff`, `get_architecture_contract`,
+`prepare_change`. Runtime dependencies, TypeScript type-only coupling and language
 compile-only edges (Rust module/use, Java imports) are reported separately where that distinction
 changes the result.
 
@@ -99,32 +115,74 @@ changes the result.
 symbol's actual code in one hop), `list_endpoints` (HTTP route inventory:
 Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …)
 
-**health** — `run_audit` (dead code, unused exports, missing/unused npm/Go/Python deps, runtime
+**health** — `find_dead_code` (bounded review queue for statically unreferenced files, functions,
+methods, and symbols, with confidence/evidence and explicit public/framework/dynamic caveats),
+`run_audit` (unused files/exports/dependencies, missing npm/Go/Python deps, runtime
 cycles, type-only/compile-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat +
-lockfile drift), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even
+lockfile drift; accepts an immutable `base_ref`, `changed_files`, and `debt: new|existing|all` for
+review-scoped results), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even
 after renames), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
-ranked by connectivity — tests are never executed)
+ranked by connectivity — tests are never executed), `verify_architecture`,
+`explain_architecture_violation`, `propose_architecture_exception`
 
 **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as
 `graph.prev.json`)
 
-**retarget** *(enabled by default, offline, explicit tool call)* — `open_repo`, `list_known_repos`;
-changes the active repository boundary
+For dead functions/methods/symbols, call `find_dead_code` first. Its default production-only queue
+shows high/medium-confidence candidates and excludes tests, generated code, mocks, stories and docs;
+use `kinds:["method"]` or a `path` prefix to narrow it. `min_confidence:"low"` explicitly includes
+public APIs and framework/dynamic/reflection-sensitive candidates with their warnings. For repository
+maintenance or branch debt, pair it with `run_audit category=unused debt=all` (or add an immutable
+`base_ref` with `debt=new`) to cover unused files, exports and dependencies. Neither tool authorizes
+deletion: inspect `read_source`, `get_dependents`, exact search, manifests/configuration and tests first.
+
+`graph_diff` accepts `base_ref` (`HEAD~1`, `main`, `origin/main`, or another local Git ref) for a
+fresh baseline comparison. Without it, the tool compares against `graph.prev.json` saved by the last
+full rebuild. Either mode can be narrowed with `path`.
+
+Graph and health calls reconcile the working graph before answering. Safe JS/TS body-only changes
+reparse only the changed files plus bounded reverse importers; add/delete, export-surface, barrel,
+manifest, alias, ignore/config, non-JS/TS, or unsafe merge cases deliberately fall back to a full
+rebuild. The result says whether freshness was `none`, `incremental`, or `full`. Graph artifacts stay
+in the per-user cache and never need to be committed to Git.
+
+**retarget** *(included in `offline`; absent from `pinned`; every switch is an explicit local call)* —
+`open_repo`, `list_known_repos`; changes the active repository boundary
+
+**crossrepo** *(included in `offline`; absent from `pinned`; reads only registered local graphs)* —
+`trace_api_contract`; reconciles the selected backend/client graphs and joins routes to client callsites
+
+`query_graph` accepts optional `seed_files` when an architectural question must start from exact
+entry points. Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when
+fuzzy question-derived seeds are also wanted. Broad bootstrap/routing/authentication questions
+without explicit seeds rank conventional entry points and high-level modules ahead of incidental matches.
+
+**advisories** *(network, explicit opt-in)* — `refresh_advisories`
 
-**online** *(explicit opt-in — see Privacy)* — `refresh_advisories`, `sync_graph`
+**hosted** *(network, explicit opt-in)* — `pull_architecture_contract`, `sync_graph`
 
-Quality of life: graph tools self-report staleness vs the repo HEAD; ambiguous name lookups are
+Quality of life: graph/health reads auto-reconcile and expose `none` / `incremental` / `full`
+freshness, with a short clean-read debounce to avoid rescanning the repository for every tool call;
+ambiguous name lookups are
 disclosed instead of silently guessed; and the server **hot-reloads its watched MCP tool entry
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
 reconnect.
 
 ## Signal quality and repository configuration
 
-Weavatrix `0.1.4` reduces the most common sources of static-analysis noise while deepening Rust and
+Weavatrix `0.2.0` reduces the most common sources of static-analysis noise while deepening Rust and
 Java graphs:
 
 - In Git repositories, graph and clone scans use tracked plus non-ignored untracked files, so
   `.gitignore`-excluded build outputs such as packaged applications do not dominate findings.
+- Add a repository-root `.weavatrixignore` for analysis-only exclusions that should remain tracked
+  in Git. It supports `*`, `**`, `?`, root-anchored `/patterns`, directory suffixes and ordered `!`
+  re-includes. The same file universe is used by graph building, audits and clone scanning.
+- `mode: "no-tests"` and `find_duplicates(include_tests:false)` classify `test-e2e`, Cypress,
+  Playwright, acceptance and integration roots as tests, not only `*.test`/`*.spec` filenames.
+- `benchmarks/**` and any `**/__temp/**` root are classified as non-production review surfaces and
+  suppressed from dead-code/clone/audit queues by default. If a benchmark is deliberate production
+  source, opt its narrow path back in with `.weavatrix.json` `classify.product` patterns.
 - TypeScript `import type` and type-only re-exports remain visible as compile-time coupling but do
   not inflate runtime-cycle severity. `module_map`, `change_impact` and structural diffs preserve
   that distinction. `god_nodes` ranks unique neighbors with runtime connectivity first and reports
@@ -150,6 +208,13 @@ Java graphs:
 - Duplicate output is a review queue, not a verdict: near-identical bodies are clone candidates;
   same-name/different-body pairs are divergence candidates. Read both sources and confirm the
   shared contract before consolidating code.
+- `run_audit base_ref=... debt=new` compares stable finding fingerprints against a graph rebuilt
+  from that immutable commit. Existing debt and fixed findings are counted separately. Supplying
+  only `changed_files` is honestly labeled changed scope—it is never presented as proof that a
+  finding is new.
+- `find_dead_code` exposes the symbol-level liveness evidence already used by the audit as a bounded
+  agent review queue. Public/exported methods, framework entries, decorators, dynamic loading and
+  reflection lower confidence; the result always says `REVIEW_REQUIRED` and `autoDelete:false`.
 
 `run_audit` makes incomplete security coverage explicit. OSV state is `OK` only after every
 supported pinned package/version for this repository was queried successfully. `PARTIAL` means
@@ -184,29 +249,48 @@ they change audit interpretation, not the repository or its dependency installat
 ## Privacy: local-first, offline by design
 
 Graph queries, audits, clone scans and repository switching run locally. The default capability set
-is `graph,search,source,health,build,retarget`: no Weavatrix HTTP requests. `open_repo` changes the
-active local boundary only when called. Weavatrix itself initiates outbound HTTP only from two
-tools; both require the explicit `online` group and a tool call:
+is `graph,search,source,health,build,retarget,crossrepo`: no Weavatrix HTTP requests. `open_repo`
+changes the active local boundary only when called. Select `pinned` to remove repository switching,
+global repository listing, and cross-repository graph tracing too.
+Weavatrix itself initiates outbound HTTP only from three tools; all are absent from `offline` and
+`pinned`, and none runs merely because a profile is enabled:
 
 - `refresh_advisories` — queries [OSV.dev](https://osv.dev) with your lockfile's package
   **names + versions** (that is what an OSV query is; never source code) and caches the advisories
   in `~/.weavatrix/advisories.json`. `run_audit` then matches against that store fully offline.
-- `sync_graph` — constructs a versioned, allowlisted payload from `graph.json`: relative paths,
-  symbol names and line ranges, import/dependency identifiers, edges and numeric metrics. Unknown
-  fields are discarded; source file bodies are never read for sync or included in the payload. The
-  endpoint is **yours**, configured via `WEAVATRIX_SYNC_URL` / `WEAVATRIX_SYNC_TOKEN`. Off by default.
-  Sync payload v2 preserves type-only and compile-only edge metadata. Graphs built before `0.1.4` must be rebuilt
-  once before syncing; a normal `open_repo` call performs that upgrade automatically.
-
-If `refresh_advisories` is not listed by the MCP client, that is the expected default: the
-registration does not include `online`. Only with the user's approval, add `online` to the final
-capability list (for example `graph,search,source,health,build,retarget,online`), restart/reconnect
-the MCP server, and then invoke `refresh_advisories`. Enabling the group does not trigger a request
-by itself.
-
-Capability groups (`graph`, `search`, `source`, `health`, `build`, `retarget`, `online`) are
-selectable through the final positional argument. Omitted caps use the safe default above; an
-explicit list exposes exactly the named groups.
+- `pull_architecture_contract` — sends the active repository's opaque stable UUID with bearer
+  authentication, downloads the owner-approved target-architecture contract, validates it, and
+  stores the contract in the local graph cache. It sends no source, symbol, or repository path.
+- `sync_graph` — builds a bounded evidence snapshot locally, then sends payload v3: the v2 graph
+  allowlist plus module dependencies, runtime/compile-time cycles, declared boundary violations,
+  health findings, complexity-threshold breaches, stack identifiers, a bounded direct/transitive
+  dependency graph, direct package usage, and bounded clone/divergence review candidates. Local
+  analyzers may read repository source and manifests to derive those
+  facts. The wire contract has no fields for file bodies, snippets, absolute host paths, environment
+  values or Git remotes; unknown fields are discarded and unsafe optional path metadata is omitted.
+  The request also carries the normalized repository display name used by the
+  hosted list. The endpoint is **yours**, configured through `WEAVATRIX_SYNC_URL` and the optional
+  `WEAVATRIX_SYNC_TOKEN`; the feature is off by default. Pass `payload_version: 2` only for an
+  intentional graph-only compatibility sync—there is no silent downgrade that discards evidence.
+  Graphs built before `0.1.4` must be rebuilt once before syncing; V3 also refuses a stale graph so
+  source-derived evidence cannot be mixed with old topology.
+
+Evidence sections carry independent `state` (`COMPLETE`, `PARTIAL`, `NOT_CHECKED`,
+`NOT_APPLICABLE`, `ERROR`) and `verdict` (`PASS`, `FAIL`, `UNKNOWN`) fields plus exact
+`total/returned/truncated` counts. An incomplete check is never converted into a clean zero. V3 is
+deterministic: volatile timestamps are excluded and the allowlisted snapshot has a canonical SHA-256
+fingerprint, so identical evidence does not manufacture a hosted revision. The client mirrors the
+hosted 8 MiB / 25,000-node / 100,000-edge / 50,000-external-import safety limits before networking.
+
+If a network tool is not listed by the MCP client, that is the expected offline default. With the
+user's approval, select `osv` for advisory refresh only or `hosted` for the hosted workflow,
+restart/reconnect the MCP server, and then invoke the intended tool. Enabling a profile does not
+trigger a request by itself.
+
+Profiles (`offline`, `pinned`, `osv`, `hosted`, `full`) or exact capability groups (`graph`,
+`search`, `source`, `health`, `build`, `retarget`, `crossrepo`, `advisories`, `hosted`) are selectable through
+the final positional argument. Omitted caps use `offline`; an explicit capability list exposes
+exactly the named groups. Legacy `online` expands to `advisories,hosted` for compatibility.
 
 ## Security model
 
@@ -215,12 +299,12 @@ vulnerability findings. This is where each capability comes from and how it is c
 
 | Capability alert | Why it exists | Activation and boundary |
 |---|---|---|
-| Network access | `refresh_advisories` sends pinned package names and versions to OSV; `sync_graph` sends a versioned allowlist of graph metadata (relative paths, symbols and line ranges, import/dependency identifiers, edges and numeric metrics). It discards unknown graph fields and does not read source file bodies | `online` is disabled by default; each request requires a tool call, and sync additionally requires `WEAVATRIX_SYNC_URL` |
+| Network access | `refresh_advisories` sends pinned package names and versions to OSV; `pull_architecture_contract` sends an opaque repository UUID and receives an owner-approved contract; `sync_graph` sends a normalized repository label plus an allowlisted graph/evidence payload. Evidence is derived locally from source and manifests, but source bodies, snippets, absolute paths, environment values, credentials and Git remotes are excluded | `offline` and `pinned` expose no network tools. `osv` exposes only advisory refresh. `hosted`/`full` expose all three; every request still requires an explicit tool call, and hosted calls require `WEAVATRIX_SYNC_URL` |
 | Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; timed-out Windows child processes may be terminated | Used only by the corresponding local operation; it does not imply network access |
 | Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool entry modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` |
-| Environment access | Reads `WEAVATRIX_*` configuration; local child processes inherit the normal host environment | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment and read only by `sync_graph` |
-| Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory cache | Realpath containment blocks traversal and symlink/junction escapes. `open_repo` is an explicit offline call that changes the active boundary; omit `retarget` in a custom capability list to pin one repository. The optional malware dependency scan may inspect installed dependency caches such as GOPATH |
-| URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the two `online` tools perform requests |
+| Environment access | Reads `WEAVATRIX_*` configuration; local child processes inherit the normal host environment | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment and read only by `sync_graph` / `pull_architecture_contract` |
+| Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory/architecture caches | Realpath containment blocks traversal and symlink/junction escapes. The `pinned` profile removes `open_repo`; the default `offline` profile permits only explicit local switching. The optional malware dependency scan may inspect installed dependency caches such as GOPATH |
+| URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the three network-profile tools perform requests |
 
 `read_source` accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or
 realpath escapes. Graph-derived paths pass through the same boundary before analysis tools read
@@ -234,8 +318,9 @@ native compilation.
 
 ## On-disk layout
 
-Graphs are derived data and never live inside your repo: they go to a `weavatrix-graphs/` folder
-**next to** it (one folder per repo, holding `graph.json` + `graph.prev.json`).
+Graphs are derived data and never live inside your repo: the global per-user registry stores them at
+`~/.weavatrix/graphs/<repository-storage-key>/` (including `.repository-id`, `graph.json`, and
+`graph.prev.json`).
 
 ## Development
 

package/SECURITY.md

@@ -21,11 +21,28 @@ mitigation is available so users have a reasonable opportunity to update.
 
 ## Security boundaries
 
-The default MCP registration is offline. Every standard source, manifest, configuration and coverage
-read is canonical-path-contained within the active repository and rejects traversal plus symlink or
-junction escapes. The optional malware dependency scan may inspect installed dependency caches such
-as GOPATH. The default `retarget` capability exposes `open_repo`, an explicit offline tool call that
-intentionally changes the active repository; omit that group in a custom capability list to pin one
-boundary. The optional `online` capability contains Weavatrix's HTTP tools; `sync_graph`
-additionally requires a user-configured endpoint and sends only a versioned metadata allowlist,
-discarding unknown fields from the local graph cache.
+The default `offline` MCP profile exposes no HTTP tools. Every standard source, manifest,
+configuration and coverage read is canonical-path-contained within the active repository and rejects
+traversal plus symlink or junction escapes. The optional malware dependency scan may inspect installed
+dependency caches such as GOPATH. `offline` permits repository switching only through an explicit
+local `open_repo` call; select `pinned` to remove that tool, the global repository listing, and
+cross-repository API tracing, holding a hard startup-repository boundary.
+
+Network capabilities are split by purpose. `osv` adds only `refresh_advisories`, which sends pinned
+package names and versions to OSV.dev when called. `hosted` / `full` also expose `sync_graph` and
+`pull_architecture_contract`; both require a user-configured endpoint, and contract pull requires
+bearer authentication. The legacy `online` capability remains an alias for advisory plus hosted
+networking so existing registrations do not break.
+
+Payload v3 runs bounded local analyzers over the active repository, then sends only a strict
+graph/evidence allowlist plus a normalized repository display name. That evidence can include a
+bounded direct/transitive lockfile dependency graph and stable clone/divergence candidates. The
+contract has no source-body,
+snippet, absolute-host-path, environment, credential, Git-remote or analyzer-error fields; unknown
+fields are discarded and unsafe optional path metadata is omitted. V3 rejects stale graphs,
+duplicate node IDs, dangling edges and oversized payloads before any request. Graph-only payload v2
+remains an explicit compatibility option and is never selected as a silent fallback.
+
+`pull_architecture_contract` sends only the active repository's opaque stable UUID, receives an
+owner-approved target contract, validates it, and caches it locally. It never sends source, symbols,
+file paths, or Git metadata.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "weavatrix",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
-  "author": "Sergii Ziborov <sergii@edgehawk.io>",
+  "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
   "license": "MIT",
   "homepage": "https://weavatrix.com",
   "repository": {

package/skill/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: weavatrix
-description: Drive the weavatrix MCP — code graph, blast-radius (get_dependents/change_impact), health audit, duplicates, coverage, endpoints — over any local repo. Use when analyzing code structure, refactor risk, dead code, dependency health, or before opening a PR.
+description: Drive the weavatrix MCP — code graph, blast-radius (get_dependents/change_impact), dead-code review, health audit, duplicates, coverage, endpoints — over any local repo. Use when analyzing code structure, refactor risk, dead code, dependency health, or before opening a PR.
 ---
 
 # weavatrix MCP
 
 Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. The default
-is offline and includes `open_repo` for one-call switching between local Git repositories. A custom
-capability list that omits `retarget` pins the registration to its initial repository.
+`offline` profile has every HTTP tool disabled and permits repository switching only through an
+explicit local `open_repo` call. Use `pinned` when a shared MCP process must never change or inspect
+outside its startup repository.
 
 ## Step 0 — if the tools are missing
 
@@ -15,17 +16,30 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 (`claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>`; Codex:
 `codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
 
-If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broken installation:
-`online` is intentionally absent from the default capability list.
+If `refresh_advisories`, `pull_architecture_contract`, or `sync_graph` is missing, do not diagnose a
+broken installation: network tools are intentionally absent from `offline` and `pinned`.
+
+Profiles use the same npm package and binary:
+
+- `offline` (default): all local analysis and explicit `open_repo`; no HTTP tools.
+- `pinned`: local analysis with no `open_repo`, no global/cross-repository graph access, and no HTTP tools.
+- `osv`: `offline` plus explicit `refresh_advisories`.
+- `hosted` / `full`: `osv` plus `pull_architecture_contract` and `sync_graph`.
+
+The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
+named profiles for new registrations.
 
 ## Ground rules
 
 - **Evidence, not verdicts**: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a
   finding in source and check framework/runtime conventions before deleting, merging or redesigning
   code. A same-name/different-body pair is a divergence candidate, not proof of duplication.
-- **Freshness**: every graph tool appends a staleness warning when the repo has commits newer than
-  the graph. Act on it: `rebuild_graph`. A normal `open_repo` builds missing graphs and upgrades
-  pre-`0.1.4` graphs to edge metadata v2; `build:false` deliberately refuses that upgrade.
+- **Freshness**: graph/health calls automatically reconcile the active graph, while cross-repository
+  tracing reconciles every selected registered graph. Read the structured `refresh` /
+  `graphReconciliation` status: `none`, `incremental`, `full`, or explicitly `PARTIAL`. Use
+  `rebuild_graph` only when automatic reconciliation reports a fallback/error or when intentionally
+  changing build mode. A normal `open_repo` builds missing graphs and upgrades legacy schemas;
+  `build:false` deliberately refuses that upgrade.
 - **Ambiguity**: `get_node`/`get_neighbors`/`get_dependents` disclose `matched N nodes; using the
   best-connected` — read that note before trusting the answer; pass an exact node id to pin it.
 - **Runtime versus compile time**: keep runtime cycles separate from TypeScript type-only and
@@ -35,26 +49,38 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
   compile-time-only edges.
 - **Repository universe**: in Git repositories, graph and duplicate scans include tracked plus
   non-ignored untracked files. If an old graph still contains packaged/generated output, rebuild it
-  before interpreting the result.
+  before interpreting the result. Repository-root `.weavatrixignore` applies the same tracked-file
+  exclusions to graph, audit and duplicate passes; use it for generated/e2e fixtures that must stay
+  committed. `no-tests` also recognizes Cypress, Playwright, `test-e2e`, acceptance and integration
+  roots. Dead-code/clone/audit review also suppresses `benchmarks/**` and `**/__temp/**` as classified
+  non-production surfaces. A verified production benchmark can opt back in narrowly through
+  `.weavatrix.json` `classify.product`, for example `{"classify":{"product":["benchmarks/core/**"]}}`.
+- **Architectural queries**: for bootstrap/routing/authentication questions, inspect the returned
+  seeds before trusting the traversal. Pass exact repository-relative `seed_files` to `query_graph`
+  when the intended entry points are already known.
 - **Coverage**: `coverage_map` reads an existing report. `unavailable` means no supported report was
   found, not 0% coverage; do not rank testing risk from that state.
 - **Audit completeness**: read `checks.osv.status` and `checks.malware.status`. For OSV, `OK` is
   complete for the recorded dependency fingerprint; `PARTIAL` is incomplete or stale,
   `NOT_CHECKED` has no repository-specific result, and `ERROR` means the local check failed. Treat
   the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
-  authorized adding the optional `online` capability group to the MCP registration and then
+  authorized selecting the optional `osv` profile (or `advisories` capability) and then
   invoking `refresh_advisories`; enabling the group alone sends nothing.
 - **Offline by design**: scans and graph queries run in-process against local files; coverage tools
-  read existing reports and never run tests. The ONLY network-touching tools live in the `online`
-  capability group and run solely when explicitly called: `refresh_advisories` (queries OSV.dev with
-  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes a
-  versioned allowlist of graph metadata, discarding unknown fields and never reading source file
-  bodies for sync, to a user-configured endpoint; disabled until
-  `WEAVATRIX_SYNC_URL` is set). `online` is
-  absent from the default capability set and must be enabled explicitly.
+  read existing reports and never run tests. The ONLY network-touching tools live in the optional
+  `advisories` / `hosted` capabilities and run solely when explicitly called:
+  `refresh_advisories` (queries OSV.dev with
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (derives a
+  bounded evidence snapshot locally, then pushes only an allowlisted graph/evidence contract to a
+  user-configured endpoint; analyzers may read local source, but the wire contract has no body,
+  snippet, absolute-host-path or environment fields, and unknown fields are discarded; disabled until
+  `WEAVATRIX_SYNC_URL` is set). `pull_architecture_contract` sends only the active repository's opaque
+  stable UUID, downloads the owner-approved contract, validates it, and caches it locally; it requires
+  `WEAVATRIX_SYNC_URL` and `WEAVATRIX_SYNC_TOKEN`. All three are absent from the default profile.
 - **Repository boundary**: source reads and graph-derived paths are realpath-contained. `open_repo`
-  intentionally changes the active boundary through an explicit offline tool call. It is available
-  by default; omit `retarget` from a custom capability list to hide it.
+  intentionally changes the active boundary through an explicit offline tool call. It is included in
+  `offline`, absent from `pinned`, and available in a custom registration only when `retarget` is
+  named. Concurrent non-mutating calls retain the graph/root snapshot with which they started.
 
 ## Recipes
 
@@ -65,12 +91,37 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
   and untracked work, coverage attached, untested hotspots called out) → drill with `get_dependents`.
 - **Impact of a PR that is NOT checked out**: pass its changed-file list explicitly —
   `change_impact files=[…]` — same blast-radius + coverage view, no checkout.
-- **Validate a refactor structurally**: edit → `rebuild_graph` — it reports the structural delta
-  (cycle broken? new module dependency introduced? symbols orphaned?); re-query later with
-  `graph_diff` (optionally scoped by `path`). The semantic complement to the textual git diff.
-- **Health sweep**: `run_audit` (filter by `category`/`min_severity`) → `find_duplicates` →
-  `coverage_map`. Inspect the source behind shortlisted findings before proposing edits.
+- **Validate a refactor structurally**: call `graph_diff base_ref=HEAD~1` (or `main` / `origin/main`)
+  to build an immutable baseline without checkout and compare it with the current graph. Alternatively,
+  edit → `rebuild_graph`, then use `graph_diff` without `base_ref` to compare `graph.prev.json` with
+  the rebuilt graph. Either route can be scoped by `path`; look for cycle, module-dependency and
+  orphan drift rather than raw edge counts.
+- **Health sweep**: for a branch/PR review prefer
+  `run_audit base_ref=<merge-base> debt=new changed_files=[…]`; for repository maintenance use
+  `run_audit debt=all`. Then call `find_dead_code`, `find_duplicates` and `coverage_map`. A changed-file-only audit is
+  scope, not proof of new debt. Inspect the source behind shortlisted findings before proposing edits.
+- **Dead-code and dead-method review**: call `find_dead_code` for a bounded production-code queue of
+  files, functions, methods and symbols. Narrow with `path` or `kinds=["method"]`; keep the default
+  `min_confidence=medium` for actionable internal candidates. Use `min_confidence=low` only when the
+  task explicitly needs public/exported, framework, dynamic-loading or reflection-sensitive review,
+  and carry each returned caveat into the recommendation. Pair it with
+  `run_audit category=unused debt=all` (or `base_ref=<merge-base> debt=new`) for unused exports and
+  dependencies. Before deletion, run `read_source`, `get_dependents`, exact `search_code`, inspect
+  framework discovery/annotations, package scripts, CLI/Docker/manifests, generated consumers and
+  test-only use, then run the repository tests. `REVIEW_REQUIRED` and `autoDelete:false` are hard
+  safety semantics, not boilerplate. Use `.weavatrix-deps.json` entrypoints/nonRuntimeRoots only for
+  verified conventions.
 - **API inventory**: `list_endpoints` (including Next.js App Router, Rust axum and actix-web).
+- **Cross-repository API impact**: ensure both repositories are in `list_known_repos`, then call
+  `trace_api_contract backend=<uuid-or-label> clients=[<uuid-or-label>]`; narrow with `method`, `path`,
+  or backend `changed_files`. Treat unresolved/dynamic URLs as incomplete evidence, not a clean result.
+- **Target architecture before editing**: `get_architecture_contract` → `prepare_change` with the
+  intended files → edit and rebuild → `verify_architecture`. A missing contract returns a starter
+  proposal, not an automatically approved architecture. Pull an owner-approved hosted contract only
+  when the user selected `hosted` and explicitly asks for it.
+- **Behavioral architecture**: `git_history` ranks churn × connectivity hotspots and hidden
+  co-change coupling from bounded local numstat history. Use it as review evidence, not proof that two
+  files must be merged.
 - **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
 - **Another repo**: `list_known_repos` → `open_repo <path>`
   (builds or upgrades the graph when needed; `build:false` probes without building).
@@ -102,18 +153,29 @@ visible. `managedDependencies` documents modules provided outside the repo's Pyt
 
 ## Sync
 
-`sync_graph` uses allowlisted payload v2, including type-only/compile-only edge metadata but no
-source bodies. A graph built before `0.1.4` must be rebuilt first; normal `open_repo` does this
-automatically. Sync remains
-unavailable until the user opts into `online` and configures `WEAVATRIX_SYNC_URL`.
+`sync_graph` defaults to payload v3: graph metadata plus deterministic architecture, health, stack,
+package-dependency and clone-review evidence. Read each section's `state`, `verdict` and completeness counts; `PARTIAL`,
+`NOT_CHECKED` and `ERROR` are unknown/incomplete, never a clean result. Architecture evidence
+contains concrete runtime versus compile-time cycles, declared boundary violations and separated
+runtime/type-only/compile-only module dependencies. Package evidence contains a bounded lockfile
+graph with direct/transitive runtime, dev, optional and peer edges plus explicit resolution counts.
+Duplicate evidence contains stable, source-free clone/divergence candidates; it never sends method
+bodies or snippets. Use `payload_version: 2` only when the user explicitly wants graph-only
+compatibility—Weavatrix never silently downgrades. A graph built before `0.1.4`, or one stale against
+the working tree, must be rebuilt first. Sync remains unavailable until the user selects `hosted`
+(or the exact `hosted` capability) and configures `WEAVATRIX_SYNC_URL`.
 
 ## Troubleshooting
 
-- `Graph unavailable` → `rebuild_graph`; `open_repo` can select another valid repository path unless
+- `Graph unavailable` → `rebuild_graph`; normal graph/health calls automatically refresh an existing
+  graph and report `none`, `incremental`, or `full`. `open_repo` can select another valid repository path unless
   the registration deliberately omitted `retarget`.
 - `refresh_advisories` is unavailable → with the user's approval, re-register/reconfigure the MCP
-  capability list to include `online`, reconnect it, and then invoke the tool. Do not enable network
+  with the `osv` profile, reconnect it, and then invoke the tool. Do not enable network
   access merely to turn `NOT_CHECKED` into a cosmetic green state.
+- `pull_architecture_contract` / `sync_graph` is unavailable → use the `hosted` profile only after
+  the user chooses hosted integration; configure `WEAVATRIX_SYNC_URL` and a bearer token for contract
+  pull. Profile selection alone never performs a request.
 - `No coverage report` → run the repo's own tests with coverage (`vitest run --coverage`,
   `jest --coverage`, `pytest --cov --cov-report=json`, `go test -coverprofile=coverage.out`),
   then re-call.