weavatrix 0.2.8 → 0.2.10

package/README.md

@@ -1,21 +1,33 @@
 # Weavatrix
 
-**Code graph & blast-radius MCP server for AI coding agents.**
-
-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. **36 tools available; 33 enabled by the default offline profile. Local-first: with
+**Local repository intelligence for AI coding agents — understand the application quickly, then change it with evidence.**
+
+Weavatrix builds a reusable living graph of any local repository: files, symbols, imports, calls,
+inheritance, health findings, clone families and Git-history coupling. It gives Claude Code, Codex,
+or any MCP client a bounded map for fast application understanding and lower repeated context, then
+reuses the same graph for change impact, Health, dead-code review, duplicates, history and intended-
+architecture safeguards. Text search is included as a supporting source check, not the product core.
+**38 tools available; 34 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)
 - npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix <repoRoot>`
 
+## One graph, many views
+
+The 38 MCP methods are not one linear workflow. They project the same reusable graph into the
+smallest view needed for a task: repository and build state; modules, communities, hubs, neighbors
+and paths; exact symbols and bounded source context; endpoint and cross-repository API flow; symbol
+and change-set blast radius; graph revision and behavioral Git history; Health, dependencies,
+vulnerabilities, dead code, clones, coverage and hot paths; proof-carrying change verification;
+intended-architecture contracts and ratchets; local multi-repository work; and explicit,
+preview-confirmed Hosted exchange.
+
 ## Why
 
-An AI agent editing code without the dependency graph is refactoring blind. Weavatrix gives it
-answers grep can't produce:
+An AI agent editing code without architecture, health and history evidence is refactoring blind.
+Weavatrix answers questions a text index cannot:
 
 - *"What breaks if I change this?"* → `change_impact` diffs your branch (staged, unstaged and
   untracked included), maps the changed files and symbols onto the graph, and lists everything that
@@ -28,6 +40,9 @@ answers grep can't produce:
 - *"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.
+- *"Where is the repo rotting or repeating itself?"* → `run_audit`, `find_dead_code`,
+  `find_duplicates`, `hot_path_review` and `git_history` combine deterministic findings, graph
+  connectivity and co-change evidence instead of treating a matching string as an architecture fact.
 
 - *"Is this change actually safe?"* -> `verified_change` accepts the task plus current diff/files and
   returns one proof-carrying `PASS`, `BLOCKED`, or `UNKNOWN`: compact edit contexts, exact-symbol
@@ -67,7 +82,7 @@ argument when a stricter repository boundary or a network feature is wanted:
 | `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 |
+| `hosted` / `full` | Yes | Yes, only when called | Only when called | `preview_sync` is local; only `sync_graph` or `pull_architecture_contract` can make a request |
 
 ```sh
 # Hard-pin one repository and expose no network tools:
@@ -125,7 +140,7 @@ confirmed by its bundled `typescript-language-server` + TypeScript runtime to `E
 `CONFLICT` means evidence disagrees. `graph_stats` reports the provenance breakdown and the semantic
 provider's `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, or `OFF` state; `OFF` means precision was explicitly
 disabled and only static evidence is active. Java and Rust language-server providers are not bundled
-in 0.2.7: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
+in 0.2.9: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
 TypeScript/JavaScript overlay.
 
 The bounded JS/TS provider is enabled by default for new graphs. Set `WEAVATRIX_PRECISION=off`
@@ -133,21 +148,28 @@ before starting the MCP server for parser-only operation from the first build, o
 `precision:"off"` to `rebuild_graph` / `open_repo`. The MCPB installer exposes the same `lsp` / `off`
 choice as **TypeScript/JavaScript semantic precision**.
 
-**search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
+**search / source** — `search_code` (ripgrep-backed, pure-Node fallback, with repository-relative
+path globs on Windows/macOS/Linux), `read_source` (a
 symbol's actual code in one hop), `context_bundle` (definition plus grouped inbound/outbound
-containers, exact re-export sites and a few bounded source excerpts), `inspect_symbol` (one exact
+containers, exact re-export sites, call-site/target provenance and bounded excerpts around decisive
+edges), `inspect_symbol` (one exact
 bounded TS/JS reference query, logical containers, impact and source excerpts), `list_endpoints` (HTTP route inventory:
-Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …)
+Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web, including nested Express
+`router.use(...)` mount composition, declaration/reachability counts and mount provenance),
+`trace_endpoint` (one exact composed route → handler → bounded production call graph with call-site excerpts)
 
 **health** — `find_dead_code` (bounded review queue for statically unreferenced and test-only files,
 functions, methods, and symbols, with evidence tiers, completed/remaining verification and explicit
 public/framework/dynamic caveats),
-`run_audit` (unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification,
+`run_audit` (unused files/exports/dependencies with per-finding manifest/indexed-source/script/config verification;
+`category:dependencies` isolates missing/unused/duplicate declarations, unresolved imports and lockfile drift,
 missing npm/Go/Python deps, runtime
 cycles, type-only/compile-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat +
 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 and can inspect strict small clones down to 12 tokens), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
+review-scoped results; production paths are the default and `include_classified:true` opts into
+test/generated/docs evidence), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even
+after renames and can inspect strict small clones down to 12 tokens; homogeneous router boilerplate
+is suppressed unless `include_boilerplate:true`), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
 ranked by connectivity — tests are never executed), `hot_path_review` (bounded local-cost evidence
 with separate graph/test risk), `verify_architecture`,
 `explain_architecture_violation`, `propose_architecture_exception`
@@ -197,24 +219,59 @@ not CFG, value-propagation, or taint analysis.
 
 `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
-question-derived seeds are also wanted. Broad bootstrap/tool-execution/routing questions now rank
+question-derived seeds are also wanted. A code-shaped identifier such as `startMitigate` is treated
+as a stronger bounded seed than surrounding words such as controller/service/flow; all exact
+same-name declarations are retained instead of adding unrelated concept seeds. Broad
+bootstrap/tool-execution/routing questions rank
 conventional executables and graph-declared production entry points ahead of site, documentation, benchmark
 and fixture matches. Production-first classification also applies during traversal, so unrelated
 tests/generated/docs/benchmarks do not leak back from a production seed; name a class in the
 question or set `include_classified:true` to include it. Unreferenced unmatched constant/field leaves
 are hidden unless `include_low_signal:true`. Broad ranking remains orientation evidence; use
-`seed_files` when the intended entry point is already known.
+`seed_files`, an exact endpoint, or `inspect_symbol` when the intended entry point is already known.
+Instruction words such as “REST”, “path”, and “inspect” do not become fuzzy code seeds.
 
 **advisories** *(network, explicit opt-in)* — `refresh_advisories`
 
-**hosted** *(network, explicit opt-in)* — `pull_architecture_contract`, `sync_graph`
+**hosted** *(explicit opt-in; preview is local, send/pull are networked)* — `preview_sync`,
+`pull_architecture_contract`, `sync_graph`. `preview_sync` performs no request and returns the destination,
+repository UUID, exact payload fields/sections/size/hash and a short-lived confirmation token for
+the cached payload. `sync_graph` sends only with both that token and `dry_run:false`; its legacy
+dry-run form remains a no-network compatibility alias.
 
 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.
+reconnect. Every MCP response also carries local, transient `_meta["weavatrix/metrics"]` with elapsed
+time, output bytes/token estimate, graph freshness/revision/update and graph-cache status. These
+metrics are not persisted or transmitted by Weavatrix.
+
+### 0.2.9 correctness, signal, and consent patch
+
+- Express endpoint inventory composes nested imported `router.use(...)` mounts, so a local route such
+  as `/:attackId/startMitigate` is reported with its reachable `/warRoom/attack` prefix, declared vs
+  reachable counts and the exact static mount chain. `trace_endpoint` continues from that route into
+  the bounded call graph and call-site excerpts.
+- `context_bundle` keeps the call-site file/line separate from the target definition and adds bounded
+  excerpts around decisive edges instead of stopping inside a long leading comment.
+- `search_code` applies documented repository-relative path globs correctly when ripgrep runs on
+  Windows. Broad `query_graph` prompts no longer turn generic REST/instruction words into noisy
+  configuration-file seeds, and code-shaped identifiers outrank generic controller/service/flow
+  concepts.
+- `run_audit` is production-first by default while retaining explicit access to classified evidence;
+  `category:dependencies` provides a focused dependency-health slice;
+  duplicate review suppresses homogeneous Express router boilerplate unless requested.
+- the separate no-network `preview_sync` produces the exact payload approval artifact; `sync_graph`
+  requires that preview followed by an exact short-lived confirmation token,
+  validates the configured destination, requires HTTPS outside loopback, and never networks during
+  preview. Contract-pull HTTP failures expose actionable auth/not-found/not-ready states.
+- Every MCP call exposes transient local execution/output/freshness metrics without collection or
+  egress. The public site, privacy/security pages, package metadata and license presentation now
+  describe the same 38-tool/34-offline surface and the same network boundary.
+
+Full patch notes: [docs/releases/v0.2.9.md](docs/releases/v0.2.9.md).
 
 ### 0.2.8 trust and precision patch
 
@@ -397,9 +454,11 @@ Java graphs:
 - Java class/interface/enum/record/annotation declarations retain their symbol kind; methods and
   constructors are linked to their declaring type with visibility metadata. Internal
   `extends`/`implements` relationships and resolvable type references link to real declarations.
-  Imports are compile-only; call/reference/heritage edges contribute impact. Maven/Gradle Java
-  trees use package-aware communities instead of one giant `src` bucket. External or synthetic
-  placeholder types are not created merely to inflate graph counts.
+  Field, parameter, local and static receiver types resolve project-internal cross-file calls;
+  overloads are selected by arity and ambiguous/external targets fail closed. Imports are
+  compile-only; call/reference/heritage edges contribute impact. Maven/Gradle Java trees use
+  package-aware communities instead of one giant `src` bucket. External or synthetic placeholder
+  types are not created merely to inflate graph counts.
 - Dependency checks resolve the nearest workspace manifest and `tsconfig`/`jsconfig` aliases,
   account for framework-owned runtime peers such as Next.js + `react-dom`, and recognize Next.js
   App Router route exports as endpoints.
@@ -492,20 +551,27 @@ Weavatrix itself initiates outbound HTTP only from three tools; all are absent f
 - `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
+- `preview_sync` — builds a bounded evidence snapshot locally without sending anything. The preview
+  shows the destination host/path, normalized repository name, opaque UUID,
+  payload version, exact top-level fields, included sections, node/link/byte counts and canonical
+  SHA-256 hash. A `sync_graph` call with `dry_run:false` and its exact short-lived `confirm_token` sends
+  the cached payload to the same destination. A token alone does not send while the default dry-run
+  remains active. It
+  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
+  The confirmed 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 that predate current typed-edge/provenance metadata must be rebuilt once before V3 sync;
   V3 also refuses a stale graph so
-  source-derived evidence cannot be mixed with old topology.
+  source-derived evidence cannot be mixed with old topology. HTTPS is required except for an
+  explicitly configured loopback endpoint; embedded URL credentials and fragments are rejected.
 
 Evidence sections carry independent `state` (`COMPLETE`, `PARTIAL`, `NOT_CHECKED`,
 `NOT_APPLICABLE`, `ERROR`) and `verdict` (`PASS`, `FAIL`, `UNKNOWN`) fields plus exact
@@ -531,7 +597,7 @@ 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; `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` |
+| 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; confirmed `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. Sync defaults to a no-network dry-run and then requires both `dry_run:false` and its exact short-lived token; hosted calls require `WEAVATRIX_SYNC_URL`, and non-loopback hosted endpoints require HTTPS |
 | Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; the bundled TLS/tsserver process supplies bounded JS/TS semantic evidence; timed-out Windows child trees may be terminated; `verified_change` can optionally run an existing package test/check/verify script | The semantic provider never invokes repository code. Test execution separately requires `run_tests:true` plus `WEAVATRIX_ALLOW_TEST_RUNS=1`, rejects arbitrary commands and shell-sensitive arguments, and should be enabled only for trusted repository scripts |
 | 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; ordinary local helpers inherit a credential-stripped environment, while TLS/tsserver receives only allowlisted OS/temp/locale values and a constrained executable path | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment. TLS/tsserver also receives no registry/proxy/cloud credentials or `NODE_OPTIONS` |
@@ -584,10 +650,10 @@ loader) behind the thin stdio entry `src/mcp-server.mjs`.
 - **Wrapper-aware API contracts** shipped in 0.2.2: persistent/ad-hoc configuration,
   conservative discovery, cross-repository handler liveness and explicit unknown states. The next
   hosted increment joins privacy-safe contract identities across separately synced services.
-- **Hosted architecture workbench** is live at
-  [app.weavatrix.com](https://app.weavatrix.com): explicit source-free sync,
-  immutable history, Flow/DSM/Map, target architecture and bounded review
-  evidence. Hosted use remains optional and owner-authenticated.
+- **Hosted architecture workbench** at
+  [app.weavatrix.com](https://app.weavatrix.com) is an access-controlled preview for
+  owner-authenticated source-free evidence and revision history. Its UI and backend evolve
+  independently from the public MCP release; local use remains fully optional.
 - **Semantic precision bridge** shipped for TypeScript/JavaScript in 0.2.4: a bounded, revision-bound
   local overlay validates references with the bundled language server while the parser graph remains
   the fallback. Java and Rust providers are not bundled yet and stay explicitly `UNAVAILABLE`.
@@ -603,4 +669,6 @@ The public alignment note for the fixed cross-product release sequence is in
 
 ## License
 
-[MIT](LICENSE) © 2026 Sergii Ziborov
+The Weavatrix source in this repository is [MIT licensed](LICENSE) © 2026 Sergii Ziborov.
+Third-party dependencies retain their own licenses. See the public
+[license page](https://weavatrix.com/license) for the same notice.

package/SECURITY.md

@@ -2,8 +2,13 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published version of Weavatrix. Upgrade to the newest
-release before reporting an issue that may already be resolved.
+| Version | Supported |
+|---|---|
+| `0.2.9.x` | Yes |
+| `0.2.8` and older | Upgrade to the latest release |
+
+Security fixes are provided for the latest published version of Weavatrix. Upgrade before reporting
+an issue that may already be resolved.
 
 ## Reporting a vulnerability
 
@@ -61,10 +66,25 @@ scripts are repository-controlled code and may have arbitrary side effects, so e
 for repositories and scripts you trust.
 
 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.
+package names and versions to OSV.dev when called. `hosted` / `full` also expose the local-only
+`preview_sync` plus networked `sync_graph` and `pull_architecture_contract`; the network tools 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.
+
+`preview_sync` is the first half of a two-step consent boundary. It constructs the strict allowlisted
+payload locally but has no network path. It displays the configured hostname/path, normalized
+repository name, opaque repository UUID, payload version, included sections, node/link/byte counts
+and canonical SHA-256 hash. Sending requires `sync_graph` with both `dry_run:false` and the exact
+confirmation token for that cached payload and destination; the token
+expires after five minutes and is stored only in process memory. A token with the default dry-run,
+or an incorrect/expired token, does not send. Sync rejects
+embedded URL credentials and fragments and requires HTTPS except for explicit loopback development
+endpoints. Query parameters may be used by a configured endpoint but are not echoed in previews or
+errors.
+
+Every MCP response includes transient local `_meta["weavatrix/metrics"]` timing, output-size/token
+estimate, graph freshness/revision/update and graph-cache status. Weavatrix does not persist, aggregate
+or transmit these measurements; they are response evidence for the caller, not product telemetry.
 
 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
@@ -77,4 +97,7 @@ remains an explicit compatibility option and is never selected as a silent fallb
 
 `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.
+file paths, or Git metadata. It applies the same HTTPS-outside-loopback and embedded-credential URL
+rules before sending bearer authentication. Authentication, forbidden, not-found and repository-not-ready responses
+are reported as distinct states so a missing registration or contract is not presented as an opaque
+HTTP failure.

package/docs/releases/v0.2.10.md

@@ -0,0 +1,53 @@
+# Weavatrix 0.2.10
+
+## Broad graph workflows without losing graph depth
+
+0.2.10 is a graph-quality, positioning and agent-routing patch. It does not narrow Weavatrix to text search, a
+single blast-radius tool, or three fixed workflows. The package, MCP registry metadata, portable
+MCPB, skill, README and public site now describe one reusable graph exposed through 38 methods and
+many task-specific projections: module/community/hub navigation, exact symbols and paths, local and
+cross-repository API flow, symbol/diff impact, structural and behavioral history, Health,
+dependencies, vulnerability evidence, dead code, clones, coverage, hot paths, proof-carrying change
+verification, intended-architecture ratchets, local multi-repository work and explicit Hosted
+governance.
+
+The skill's intent router now maps each independent scenario to the smallest sufficient graph view or
+analysis before lower-level source search. `module_map` is explicitly the first unfamiliar-repository
+orientation view, `run_audit` is the core production-first Health review, and `verified_change` is
+explicitly the pre-commit proof-carrying safeguard. Text search remains a useful source check, not the
+product center.
+
+## Java call graph and Repo Lens baseline
+
+- Java field, parameter, local and static receiver types now resolve project-internal cross-file
+  method calls. Overloads are selected by argument arity; ambiguous methods and external or
+  same-basename impostor types fail closed. Call-site lines remain available to bounded context and
+  endpoint traces, while hub ranking continues to count unique neighbors rather than occurrences.
+- A release regression test now asserts that the default offline catalog retains all 21 portable
+  repository-analysis methods inherited from Repo Lens. Its Electron-only `app_action` and
+  `app_job_status` process-control bridge is not misrepresented as an analyzer method: rebuild,
+  audit, advisory refresh, duplicate review and coverage generation/mapping retain direct bounded
+  MCP paths, while the persistent Electron job journal remains app-specific orchestration.
+- The skill routes every one of the 38 current methods into a concrete scenario, so graph, history,
+  Health, duplicates, dead code and architecture governance remain first-class product surfaces.
+- The unconfigured-architecture starter now proposes product-code territories only: tests, docs,
+  benchmarks, generated files and repository configs are filtered out, while direct source-root
+  files are grouped without overlapping deeper modules. It remains a source-free owner-review
+  proposal and is never saved or enforced automatically.
+
+## Compatibility and data boundary
+
+Tool names, MCP schemas, result envelopes and Hosted sync payloads are unchanged. Java graph nodes
+and edges gain additive local `parameter_count` and `javaResolution` evidence; existing readers can
+ignore those fields, and the Hosted payload allowlist remains unchanged. The default profile still
+exposes 34 local tools and no HTTP tools. Hosted remains separately opt-in, preview-confirmed and
+wire-compatible with payload v3.
+
+## Verification
+
+- Full Node suite: 506 tests, 503 passed, 3 platform skips, 0 failed.
+- Six-language, cross-repository, framework and MCP lifecycle benchmark: `PASS`.
+- Six available real-repository baselines, including the Java call-graph case: 6/6 `PASS`.
+- Release metadata consistency and JSON syntax: `PASS`.
+- Repo Lens portable analyzer parity: 21/21 methods present in the default offline profile.
+- Hosted API and sync-payload schemas are unchanged.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "weavatrix",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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.",
+  "description": "Local repository intelligence MCP for AI coding agents: reusable architecture graph for fast application understanding, Health, dead code, clones, history, blast radius and architecture safeguards.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
   "license": "MIT",
   "homepage": "https://weavatrix.com",
@@ -26,7 +26,7 @@
     "skill",
     "scripts/run-agent-task-benchmark.mjs",
     "docs/agent-task-benchmark.md",
-    "docs/releases/v0.2.8.md",
+    "docs/releases/v0.2.10.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weavatrix
-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.
+description: "Use the Weavatrix MCP as a reusable local repository-intelligence layer: understand unfamiliar applications with a bounded code graph, reduce repeated context, review Health, dead code, duplicates and history, trace endpoints and blast radius, enforce target architecture, and verify changes before a PR."
 ---
 
 # weavatrix MCP
@@ -16,7 +16,7 @@ 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 `refresh_advisories`, `pull_architecture_contract`, or `sync_graph` is missing, do not diagnose a
+If `refresh_advisories`, `preview_sync`, `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:
@@ -24,38 +24,89 @@ 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`.
+- `hosted` / `full`: `osv` plus local-only `preview_sync`, `pull_architecture_contract` and `sync_graph`.
 
 The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
 named profiles for new registrations.
 
 ## Intent router
 
-Start from the task, not from the complete tool list:
-
-- **Orient in a repository**: `graph_stats` -> verify `Repo`, `Graph`, and `Build mode`; if the target
-  is wrong, call `open_repo`, then `graph_stats` again -> `module_map` (production-only by default).
-- **Review a branch/diff**: `change_impact` for changed-file blast radius; add
-  `graph_diff base_ref=<merge-base>` for structural drift, then drill into exact candidates with
-  `get_dependents` and `read_source`.
-- **Plan or verify a serious change**: call `verified_change phase=plan` with the natural-language
-  task and current diff/files. After editing, call it again with `phase=verify` and an immutable
-  `base_ref`. Treat `UNKNOWN` as missing proof, not success; inspect its blockers and unknowns instead
-  of manually orchestrating the lower-level graph, context, impact, ratchet, and test tools.
-- **Trace an API across repositories**: `list_known_repos` -> `trace_api_contract` with an explicit
-  backend and client list; inspect each `graphReconciliation.buildMode` before using the verdict.
-- **Inspect exact symbol references**: start with `graph_stats`, then call `context_bundle` with an
-  exact node ID (or an unambiguous label) for a compact definition, grouped relations, exact
-  re-export sites and source workset. Use `inspect_symbol` when the raw bounded point query is needed;
-  it spends evidence beyond the broad overlay cap. Use `get_dependents` for transitive
-  graph impact and `find_dead_code` for bounded zero-reference
-  candidates. Treat `PARTIAL`, `UNAVAILABLE`, `OFF`, or zero exact edges as incomplete evidence, not
-  a compiler-exact result; `OFF` means the caller explicitly selected static-only mode. Java and Rust
-  providers are not bundled in 0.2.7, so their edges never become `EXACT_LSP` even when a mixed
-  repository has a complete TypeScript/JavaScript overlay.
-- **Explore an architectural question**: use broad `query_graph` when entry points are unknown; its
-  bootstrap/tool-execution ranking prefers production executables over docs, sites and fixtures.
-  Pass exact `seed_files` when the intended entry points are already known.
+Weavatrix is not one report or three fixed workflows. Its 38 methods expose different bounded views
+and analyses over the same reusable graph. Start from the task and choose the smallest sufficient
+projection; expand only when the answer requires it.
+
+### Graph views and application understanding
+
+- **Confirm repository, graph freshness and build mode**: `graph_stats`; use `rebuild_graph` only for
+  a reported fallback/error or an intentional mode/precision change.
+- **Switch or inventory local repositories**: `list_known_repos` -> `open_repo` -> `graph_stats`.
+- **See production module topology**: `module_map`; use this first for a large unfamiliar application.
+- **See discovered communities and their members**: `list_communities` -> `get_community`.
+- **Find high-coupling hubs**: `god_nodes`; repeated call sites do not inflate unique connectivity.
+- **Inspect one graph entity**: `get_node`; pass an exact node ID when labels are ambiguous.
+- **Inspect direct one-hop relations**: `get_neighbors`; do not confuse it with transitive impact.
+- **Prove a path between two concepts**: `shortest_path`.
+- **Explore an unknown entry point or architectural question**: `query_graph`; pin `seed_files` when
+  known, and keep its broad result as orientation evidence.
+- **Inspect one exact symbol deeply**: `context_bundle` for the bounded edit workset;
+  `inspect_symbol` for the raw point query and on-demand JS/TS reference evidence.
+- **Confirm graph evidence in source**: `read_source`; use `search_code` only for a narrow regex/glob
+  check. Search is supporting evidence, not the repository-intelligence layer.
+
+### Runtime, API and change scenarios
+
+- **Inventory HTTP routes**: `list_endpoints` for declared/reachable composed paths and mount proof.
+- **Trace one endpoint through the application**: `trace_endpoint` for route -> handler -> bounded
+  downstream call flow with edge-centered excerpts.
+- **Trace an API contract across repositories**: `list_known_repos` -> `trace_api_contract` with an
+  explicit backend/client set; inspect each graph reconciliation state before using the verdict.
+- **Measure one symbol's transitive blast radius**: `get_dependents`.
+- **Review the current branch, diff, or external patch**: `change_impact`.
+- **Compare structural graph revisions**: `graph_diff base_ref=<merge-base>` for module edges, cycles,
+  orphans and lost callers; without `base_ref`, compare the last rebuild snapshots.
+- **Use behavioral history**: `git_history` for churn x connectivity, hidden co-change and expected
+  test/source coupling from bounded local Git numstat evidence.
+- **Plan and verify a serious change or pre-commit gate**: `verified_change phase=plan` -> edit ->
+  `verified_change phase=verify base_ref=<same-ref>`. It composes exact context, impact, graph,
+  architecture, duplicate, optional API and test proof into one PASS/BLOCKED/UNKNOWN envelope.
+
+### Health, debt and testing scenarios
+
+- **Run a whole-repository Health review**: `run_audit debt=all`.
+- **Gate only newly introduced branch debt**: `run_audit base_ref=<merge-base> debt=new`; old debt in
+  a changed file remains existing.
+- **Review dependency declarations/imports**: `run_audit category=dependencies`; it includes missing,
+  unused, duplicate, unresolved-import and lockfile-drift evidence without relabelling identities.
+- **Refresh vulnerability evidence when explicitly authorized**: `refresh_advisories`, then
+  `run_audit category=vulnerability`. `NOT_CHECKED` is unknown, never clean.
+- **Review dead files, functions, methods and symbols**: `find_dead_code`; every result remains a
+  review candidate with framework/dynamic/public-API caveats, never an auto-delete verdict.
+- **Review clone families or same-name divergence**: `find_duplicates`; framework router boilerplate
+  is suppressed unless explicitly requested.
+- **Map measured coverage or honest static test reachability**: `coverage_map`; unavailable measured
+  coverage is not 0%.
+- **Prioritize local performance-review candidates**: `hot_path_review`; confirm with a profiler or
+  benchmark before changing runtime behavior.
+
+### Intended architecture and Hosted governance
+
+- **Read or establish intended architecture**: `get_architecture_contract`. A returned starter is a
+  product-code-only territory proposal (not tests, docs, benchmarks, generated output or repository
+  configs), not automatically approved policy.
+- **Select rules before editing**: `prepare_change`; **enforce the ratchet after editing**:
+  `verify_architecture`.
+- **Understand or request an exception**: `explain_architecture_violation` ->
+  `propose_architecture_exception`; proposals never mutate policy automatically.
+- **Pull an owner-approved Hosted target**: `pull_architecture_contract` only in an explicitly enabled
+  Hosted profile.
+- **Review exactly what Hosted sync would send**: `preview_sync`; only an approved
+  `sync_graph dry_run=false confirm_token=...` may send that exact bounded payload.
+
+Across every scenario, treat `PARTIAL`, `UNAVAILABLE`, `OFF`, `NOT_CHECKED`, `ERROR`, or capped
+evidence as incomplete rather than success. Java and Rust exact language-server providers are not
+bundled, so their edges never become `EXACT_LSP` even when a mixed repository has a complete
+TypeScript/JavaScript overlay. Java receiver-type call edges are parser-resolved and explicitly
+`INFERRED`; they improve cross-file flow without claiming compiler-exact overload or dynamic dispatch.
 
 ## Ground rules
 
@@ -117,8 +168,8 @@ Start from the task, not from the complete tool list:
   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
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes only
+  the exact allowlisted graph/evidence contract previously serialized by local-only `preview_sync` 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
@@ -175,7 +226,9 @@ Start from the task, not from the complete tool list:
   `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).
+- **API inventory**: `list_endpoints` (including mount provenance, Next.js App Router, Rust axum and
+  actix-web). When one exact route is known, use `trace_endpoint` for its composed mount chain,
+  handler and bounded production call graph instead of broad natural-language traversal.
 - **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`. `path` may be a segment-aligned fragment (`/query` can select
@@ -237,7 +290,10 @@ visible. `managedDependencies` documents modules provided outside the repo's Pyt
 
 ## Sync
 
-`sync_graph` defaults to payload v3: graph metadata plus deterministic architecture, health, stack,
+Call `preview_sync` first. It validates the configured destination and serializes payload v3 locally,
+returning the repository UUID, exact fields/sections, counts, bytes, hash and short-lived confirmation
+token without networking. After explicit approval, call `sync_graph dry_run=false` with that token.
+Payload v3 contains 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
@@ -257,7 +313,7 @@ the working tree, must be rebuilt first. Sync remains unavailable until the user
 - `refresh_advisories` is unavailable → with the user's approval, re-register/reconfigure the MCP
   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
+- `preview_sync` / `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`,

package/src/analysis/duplicate-groups.js

@@ -37,6 +37,13 @@ function groupPairs(data, settings) {
   }).sort((a, b) => b.tokens - a.tokens)
 }
 
+export function isFrameworkBoilerplateCloneGroup(group) {
+  const members = Array.isArray(group?.members) ? group.members : []
+  if (members.length < 2) return false
+  return members.every((member) => /(?:^|\/)\w[^/]*\.router\.[cm]?[jt]s$/i.test(String(member.file || '').replace(/\\/g, '/'))
+    && /^(?:router|routes)\(?\)?$/i.test(String(member.label || '').trim()))
+}
+
 export function analyzeDuplicateGroups(repoRoot, graphPath, args = {}) {
   const settings = {
     simMin: Math.min(100, Math.max(50, Number(args.min_similarity) || 80)),
@@ -44,11 +51,13 @@ export function analyzeDuplicateGroups(repoRoot, graphPath, args = {}) {
     mode: args.mode === 'strict' ? 'strict' : 'renamed',
     skipTests: args.include_tests !== true,
     includeClassified: args.include_classified === true || args.include_non_product === true,
+    includeBoilerplate: args.include_boilerplate === true,
   }
   const data = computeDuplicates(repoRoot, graphPath, {includeStrings: args.include_strings === true, minTokens: settings.tokMin})
-  const groups = groupPairs(data, settings)
+  const allGroups = groupPairs(data, settings)
+  const groups = settings.includeBoilerplate ? allGroups : allGroups.filter((group) => !isFrameworkBoilerplateCloneGroup(group))
   const suppressed = (data.frags || []).filter((fragment) => !eligible(fragment, settings)).length
-  return {settings, groups, suppressed}
+  return {settings, groups, suppressed, boilerplateSuppressed: allGroups.length - groups.length}
 }
 
 const digest = (value) => createHash('sha256').update(value).digest('hex').slice(0, 20)