dsh-gitnexus-plus 0.1.2 → 0.1.4

package/README.md

@@ -1,632 +1,254 @@
 # dsh-gitnexus-plus
 
-A DeepSeek Harness plugin for **GitNexus index visibility** — starting with the part
-GitNexus itself cannot tell you: **what the index left out**.
+**English** · [简体中文](README-CN.md)
+
+**Current release: [0.1.4](https://github.com/Moowningstar/gitnexus-plus/releases/tag/v0.1.4)** ·
+[npm](https://www.npmjs.com/package/dsh-gitnexus-plus) ·
+[Issues](https://github.com/Moowningstar/gitnexus-plus/issues)
+
+[What it does](#what-it-does) · [Install](#install) · [Troubleshooting](#troubleshooting) ·
+[Upstream GitNexus docs](#upstream-gitnexus-documentation)
+
+A DeepSeek Harness plugin: see what a GitNexus index **covers and what it leaves out**,
+decide whether a refresh is worth running, browse the graph, refresh it from the sidebar,
+and search its symbols by keyword.
+
+It does not fork GitNexus, rewrite its parser, or bundle/redistribute it. `gitnexus` is a
+**peer**; you provide it.
+
+## What it does
+
+- **Refresh gate (Tier 0)** — before offering a refresh, the panel compares the working
+  tree with the sha256 hashes the index recorded in `.gitnexus/gitnexus.json` and reports
+  what actually differs: modified / added / deleted, plus files the index's own policy
+  excludes. A clean tree answers in milliseconds without starting the analyzer, and the
+  button says so instead of running a minutes-long rebuild. The verdict is only called
+  "up to date" when it is anchored to the commit the index recorded; an index that
+  recorded none falls back to comparing the working tree with `HEAD` and says it cannot
+  confirm instead of claiming freshness.
+- **Graph view** — the index's communities drawn on a canvas, with aggregated
+  cross-community edges; click a community to see its member symbols and the relations
+  among them, click a symbol to open its file at the line. Node and edge budgets are
+  applied by the host, and the view states what it left out.
+- **Index coverage** — lists the oversized files `gitnexus analyze` skipped, with size,
+  language share, and generated/minified signals.
+- **Index freshness** — indexed commit vs `HEAD`, classified `current` / `behind` /
+  `diverged` / `unknown`, plus the uncommitted-change count.
+- **Graph composition** — nodes, edges, communities, processes, embeddings, edges per node.
+- **Git activity × index** — recent commits, authors, branches and most-changed files,
+  each file marked **indexed**, **excluded by design**, or **missing from the index**.
+  Includes an activity × index cross-tab, a baseline review against the indexed commit
+  (or the activity-window start when the index recorded none), a 7/14/30-day commit
+  timeline, and a per-file timeline when a file row is clicked.
+- **Language distribution** — bytes split into languages GitNexus can parse, formats it
+  only recognizes, and everything else. Without GitNexus, a built-in extension map keeps
+  the breakdown useful and marks it `builtin`, never "parsed".
+- **Keyword search** — matches graph node `name` / `filePath`, returns kind, path and line;
+  clicking a hit opens the file at that line, and a separate Copy button copies
+  `path:line`.
+- **Source fallback** — when the graph helper cannot start (no usable shell sandbox,
+  DLL/ABI, busy index), a bounded line search over the indexed files returns
+  `mode: "text"` instead of pretending to be the graph.
+- **No-index visibility** — a git project without an index shows a scan overview,
+  language split and the initialize command instead of an empty panel.
+- **Maintenance** — initialize, incremental refresh and full rebuild (`--force`) run
+  through DSH's shell executor, with no self-escalation. When the index reports FTS as
+  unavailable, a **修复搜索索引（FTS）** action runs `analyze --repair-fts` — the search
+  indexes only, without re-analysing the repository.
+
+## Install
+
+Requirements:
+
+- DSH `>=0.2.0-rc.2 <0.3.0`
+- Node `>=22`
+- GitNexus `>=1.6.0 <2.0.0` (peer; not installed by this plugin)
 
-## The problem it solves
-
-`gitnexus analyze` silently drops files. Its entire surface for saying so is one
-line on stderr, printed once:
-
-```
-  Skipped 3 large files (>512KB, likely generated/vendored)
-    - dist/app.min.js
-    ...and 2 more (set GITNEXUS_VERBOSE=1 to list them all)
+```sh
+dsh plugin add dsh-gitnexus-plus
 ```
 
-That line is not returned, not persisted, not queryable, and gone when the terminal
-scrolls. Meanwhile the files it names can be the difference between an index that
-represents your codebase and one that does not — measured on this machine,
-`material-ui` skips 4.4 MB (12.4 % of scanned bytes), and those files contribute
-**zero** symbols to the graph.
-
-This plugin turns that line into data, a tool, and a route.
-
-## What this project is, and what it is not
-
-[GitNexus](https://github.com/abhigyanpatwari/GitNexus) is a code-intelligence engine by
-**Abhigyan Patwari**. It parses a repository into symbols, relationships and execution
-flows and writes them to a local graph database. It is a genuinely good piece of work,
-and this project would have nothing to show without it.
-
-What GitNexus does not give an everyday user is **visibility** and **automation**:
-
-- **Visibility** — how much of the repository does the index actually cover? Which files
-  were skipped for being too large? Has the index fallen behind `HEAD`, and by how much?
-  The CLI does not answer those unasked, and the answer is invisible exactly when it
-  matters.
-- **Automation** — once an index is stale, somebody has to remember to refresh it.
-
-**This project is a layer that adds those two things and nothing else.** It reads the
-index GitNexus wrote, reports what the index left out, and can start an incremental
-refresh through GitNexus's own CLI.
-
-It does **not**:
-
-- fork GitNexus, patch it, or reimplement its parser or graph database;
-- redistribute GitNexus source. Nothing from that project is inside this package's
-  tarball. `gitnexus` is declared as a **peer**, not a dependency, so installing this
-  plugin installs nothing from it — the operator supplies GitNexus, by whatever means,
-  and the two stay separate;
-- claim authorship of, or any contribution to, GitNexus. All rights in GitNexus belong
-  to its author;
-- replace GitNexus. With no GitNexus index there is no graph to display — only a
-  working-tree scan (file counts, bytes, languages), which is useful but is not a
-  substitute for the graph.
-
-## Licence — read this before a commercial use
-
-This project is **MIT** (see [LICENSE](LICENSE)).
-
-**It depends on GitNexus, which is `PolyForm-Noncommercial-1.0.0`.** That licence grants
-noncommercial use and restricts commercial use. GitNexus is **not** a dependency of this
-package — it is a peer, so installing this plugin does not install it, and the plugin
-never bundles or redistributes it. Installing this plugin's package therefore installs
-nothing under that licence. But every GitNexus-backed feature — reading an index,
-refreshing one, installing one on request — puts your use of *GitNexus* under
-*GitNexus's* licence:
-
-- **your use of this plugin's GitNexus-backed features is subject to GitNexus's
-  licence**, not to this project's MIT grant;
-- **commercial use requires a separate grant from GitNexus's author.** If your use is
-  commercial, read
-  <https://github.com/abhigyanpatwari/GitNexus/blob/main/LICENSE> or contact the author
-  before relying on any of it.
-
-This project cannot and does not change that: it only calls the interfaces GitNexus
-provides. The read-only half — reading `.gitnexus/gitnexus.json` and reporting on it —
-is this project's own code and carries no GitNexus code, but it also has nothing to
-report on unless GitNexus produced that file.
-
-A one-line summary: **the MIT licence here covers my code; GitNexus's licence covers
-GitNexus, and installing this plugin installs GitNexus.**
-
-## What it reports
-
-- **Skipped large files** — path, size, share of its language, and two independent
-  signals for *why* it is not source: a single-line (minified) heuristic, and a
-  build-output path heuristic. Binary assets are detected separately and never
-  called minified.
-- **Index freshness** — the indexed commit against HEAD, classified `current` /
-  `behind` / `diverged` / `unknown` the same way `gitnexus status` does, plus the
-  uncommitted-change count.
-- **Graph composition** — nodes, edges, communities, processes, embeddings, and
-  edges-per-node, all read from the manifest.
-- **Query surfaces** — which of graph / keyword search / semantic search are
-  actually available, with the reason when one is not. An index with no FTS cannot
-  answer keyword queries, and hiding that is how a reader concludes otherwise.
-- **Git activity, crossed with the index** — recent commits, authors (bots marked),
-  branches, most-changed files and most-recent files, each carrying a three-way
-  verdict: *indexed*, *excluded by design*, or **missing from the index**. That last
-  one is the point: of the files people are actively editing, which does the graph
-  not see?
-- **Language distribution by bytes**, split three ways: languages GitNexus can
-  *parse* into the graph, formats it merely *recognizes*, and everything else. When
-  GitNexus is absent, a built-in extension map keeps the breakdown useful; those
-  rows are marked `detector: "builtin"` and are never presented as *parsed*.
-- **Resolver confidence** — untyped receiver sites, which make `impact` and
-  `context` a lower bound rather than an exact answer.
-- **A scan-only report when there is no index** — file count, selected count, bytes
-  and language split are readable from the working tree alone. The panel shows them
-  under "尚未索引" instead of an empty state, and the initialize command sits beside
-  them.
-- **Keyword search with click-to-open** — the panel's search box asks the graph for
-  nodes whose `name` or `filePath` contains the query, and returns the graph node
-  kind, name, path and line. **Clicking a hit opens that file in the platform's file
-  viewer at that line** through `ctx.sidebarRight.openResource` and a
-  `dsh-resource://file/session/...` address; a separate 复制 button copies
-  `path:line`. When the graph helper cannot start, the bounded source-text fallback
-  is used instead and the card is labelled 源码关键词（回退）.
-
-## Why the git three-way split matters
-
-A two-way "indexed / not indexed" count is misleading. Measured on a real
-repository, 1 635 files had been touched in 90 days: 491 indexed, 1 143 absent, and
-reporting that as "70 % missing" is wrong — 1 143 of them are lockfiles, dotfiles
-and binary assets that no scan would select either. Exactly **one** was a genuine
-gap (`src/stores/windowModeStore.ts`). The panel reports the three numbers
-separately, and only the third raises a warning.
-
-
-## Design commitments
-
-**Reuse, don't reimplement.** "Which files did GitNexus skip?" has exactly one
-correct answer: the set `walkRepositoryPaths` produced. This plugin deep-imports
-GitNexus's own `createIgnoreFilter`, `glob` call and `getLanguageFromFilename`
-rather than approximating them, and `test/run.mjs` cross-checks its scan against
-`walkRepositoryPaths` on real repositories. If upstream reshapes those modules the
-plugin degrades to a documented fallback scan (`ScanReport.primitives === 'fallback'`)
-instead of reporting a wrong number.
-
-**Absent is reported as absent.** The size cap an index was built under is read from
-that index. Legacy indexes (`meta.json`, no `indexCoverage`) are reported with the
-cap *unknown* and a note — never defaulted to today's value, which would misattribute
-covered files as skipped.
-
-**Read-only.** Nothing here triggers `analyze`, writes to `.gitnexus/`, or takes the
-index lock. A status check must never start a 30-second rebuild.
-
-## Getting GitNexus — the prerequisite, and the two ways to satisfy it
-
-This plugin reads an index. **Only GitNexus produces one.** So the plugin checks
-whether GitNexus is present, and when it is not, the panel says so above everything else
-rather than letting you wonder why the numbers are missing.
-
-Two ways out, in the order the panel offers them:
-
-**① Install it yourself.** The panel shows a copyable `npm install -g gitnexus`, and
-that is the recommendation. You know your network, your registry and your toolchain; a
-command you can run is more useful than a download this plugin performs on your behalf,
-and it works behind whatever mirror or feed your machine actually reaches.
-
-**② Let the plugin install it.** Second in the list and behind a confirmation, because
-it is a much larger decision. It runs, through the host's shell executor:
+Restart DSH after adding it. The panel is a right-sidebar tab: open the sidebar's **+**
+→ guide page → **GitNexus 索引**.
 
-```
-npm install --prefix <DSH_HOME>/gitnexus-plus/gitnexus gitnexus@^1.6.12
+The `desktop` profile is managed by Electron; the CLI cannot change it. Use the Web
+sidebar's Plugins page there. From a local checkout:
+
+```sh
+dsh plugin --profile web add <absolute path to this package>
 ```
 
-and the confirmation states what that means before anything starts:
-
-- **about 500 MB to 1 GB** downloaded, from whatever registry your `.npmrc` already
-  names — this plugin hardcodes none, because a hardcoded one breaks exactly the users
-  whose network is why they need this path;
-- **several minutes**, longer on a slow link or when the native modules have to compile;
-- **this machine's build toolchain is used** — `@ladybugdb/core`, `tree-sitter` and
-  `tree-sitter-*` compile on install. That is why this is `npm` and not `pnpm`: pnpm 10+
-  refuses dependency build scripts by default, and the failure it produces is one you
-  cannot act on. GitNexus's own message names the grants it needs:
-  `--allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter`;
-- it installs into a **plugin-owned directory**, never your global prefix, so it needs no
-  elevation and cannot collide with a GitNexus you already have.
-
-Everything runs through `ctx.shell`, so a sandboxed deployment confines it exactly as it
-confines your own commands. **A refusal is reported as a refusal and never retried
-wider** — the plugin never asks for more scope than the session already granted.
-
-**The installed copy is the one every later step uses.** The install prefix is resolved
-once and passed to all three consumers: the coverage engine's own scan primitives, the
-language detector, and the `analyze` runner. This wiring was missing in 0.1.1 — the
-installer wrote a plugin-owned tree, while the reader and runner probed only PATH and
-the declared dependency, so the install succeeded and *nothing used it*. A machine with
-no global GitNexus still reported "absent" after a successful install.
-
-**Install → initialize is one authorised step.** If the current project has no index,
-a successful install continues with a single `gitnexus analyze --index-only` for that
-project, so the operator gets from "no GitNexus" to a visible index without a second
-click. The install confirmation says this before anything starts. The chain is gated on
-the install having been started from this panel and on the project still having no
-index; it never silently refreshes an index that already exists.
-
-If your GitNexus lives somewhere unusual, name it directly and none of this applies:
+GitNexus can be installed by you or by the panel. For a custom location:
 
 ```sh
 GITNEXUS_CLI=/path/to/gitnexus/dist/cli/index.js
 ```
 
-That path is checked first, and it is the answer for an offline or air-gapped machine:
-put a copy anywhere, point at it, done.
+### Getting GitNexus
 
-## Usage
+Installing it yourself is recommended:
 
 ```sh
-# CLI, no install
-npm run build                       # tsc (host) + tsc (client) + wrap
-node lib/bin/gitnexus-coverage.js <repo-path>
-node lib/bin/gitnexus-coverage.js -r material-ui     # by registry alias
-node lib/bin/gitnexus-coverage.js --all --json       # every indexed repository
-node lib/bin/gitnexus-coverage.js <repo> --fail-on-large   # exit 2 — CI gate
-
-# type check
-npm run check
-
-# tests
-npm test
+npm install -g gitnexus
 ```
 
-In DSH the plugin exposes:
-
-- **tool** `gitnexus_coverage` — `{ repo, includeLanguages? }`
-- **route** `GET /api/gitnexus/coverage?repo=<project>` — one report, plus the
-  maintenance commands for that project
-- **route** `GET /api/gitnexus/search?repo=<project>&q=<keyword>&limit=20` —
-  read-only keyword search over the graph's symbol names and file paths
-- **panel** — a right-sidebar tab type `gitnexus`, opened from the sidebar's **+** →
-  guide page ("GitNexus 索引")
-
-The coverage route is read-only. Its bound is a **project root** — a directory with a
-`.gitnexus` index or a `.git` marker — so it cannot be turned into a filesystem probe.
-An index is no longer required: a git project without one gets the engine's scan-only
-report, which is what makes "no index yet" informative. It is additionally restricted
-to loopback peers because a third-party DSH route is unauthenticated by default on a
-bare `dsh web` profile.
-
-There is now a **second** route, `/api/gitnexus/analyze`, and it is the only one that
-can change anything. It answers `POST` to start an incremental refresh (`?force=1`
-selects a full rebuild), `GET` to report where that got to, and `DELETE` to stop it. It is a separate module from the coverage
-route so the read-only half keeps a method policy that cannot mutate — the shared guard
-takes the accepted methods from the route rather than hard-coding one set for both. The
-mutating verbs additionally pass the write guard, which refuses cross-origin requests;
-loopback alone is not enough, because any page the operator visits can reach
-`127.0.0.1`. See **Maintenance** below for what it will and will not do.
-
-A **third** route, `/api/gitnexus/search`, is read-only like coverage but queries the
-LadybugDB graph instead of the manifest. It opens the database read-only and searches
-node names and file paths; it does **not** use FTS, which is why it works on an index
-built with `--skip-fts` and on a machine where the FTS extension fails to load. The
-response carries the node kind, name, path and line, plus an honest warning when
-content-level FTS is unavailable.
-
-**Two tiers, because the host shell can be unavailable.** The normal path is the
-graph query. If the helper cannot start — a Windows sandbox backend that cannot create
-its own temp directory, no shell executor, a busy database — the route falls back to a
-bounded source-text search over the files listed in the index manifest. That fallback
-needs neither a shell nor the native addon; it returns `mode: "text"`, searches code
-files before documentation, caps files/bytes/matches, and says so in `warning` and in
-the panel's card title. A silent swap between "graph" and "source text" would be a
-dishonest answer, so the mode is part of the response.
-
-**The graph query runs in a Node helper subprocess, not in the DSH host.** The host runs on
-Electron's Node, and GitNexus's LadybugDB addon is built for the system Node ABI.
-Loading it in-process fails with `A dynamic link library (DLL) initialization routine
-failed ... lbugjs.node`; the same addon loads under the system Node 24 that the CLI
-uses. The host therefore starts:
+The panel can also install it through DSH's shell:
 
-```
-node lib/bin/search-helper.js <repo> <keyword> <limit> <managed-prefix>
+```sh
+npm install --prefix <DSH_HOME>/gitnexus-plus/gitnexus gitnexus@^1.6.12
 ```
 
-and parses one JSON object. That is the same execution boundary the analyze runner
-already uses, and it keeps the panel process free of native state it cannot load.
-Consequently the graph path needs a shell executor and `node` on the shell's PATH;
-without them it falls back to source text, not an empty result list.
-
-**Clicking a hit opens the file, not a copy.** The row calls
-`ctx.sidebarRight.openResourceIn(sessionId, address, { params: { line } })` (or the
-public `openResource` when the targeted variant is unavailable) with
-`dsh-resource://file/session/<session>/<path>`. That is the same address and line
-parameter the built-in file strip and the chat's file links use, so the platform's
-own file viewer/editor handles the navigation. A separate 复制 button remains for the
-`path:line` text. A profile without a right-sidebar controller falls back to copying
-and says so.
-
-## TypeScript, and why the build looks the way it does
-
-The source is TypeScript under `strict`, including `noImplicitAny`. That is not
-decoration: an implicit `any` is a **silent** failure — it does not report an error,
-it just makes the checker stop working exactly where it was needed. Migrating this
-codebase from JS+JSDoc to real types surfaced six places where the documentation and
-the code disagreed, none of which produced a runtime error until the affected branch
-was reached:
-
-| Where | JSDoc claimed | Actually |
-| --- | --- | --- |
-| `LargeFile.generatedHint` | `string \| null` | `boolean` — consumed as `if (x)` |
-| `LargeFile.minified` | non-null | nullable, when the probe budget runs out |
-| `analyzer.primitives` | `number` | a **string**, compared against `'gitnexus'` |
-| `MinifiedVerdict` | a type name | **the type did not exist** |
-| `activityView()` result | — | missing `truncated`, which callers read |
-| `analyzeCoverage` options | 3 fields | 5 — two were undocumented |
+That downloads roughly 500 MB–1 GB and needs a C++ toolchain; no registry is hardcoded.
+Treat the first install as unverified and fall back to the manual command if it fails.
 
-### Two compile targets, no bundler
+## Usage
 
-```
-src/index.ts ───────────┐
-src/gitnexus/*.ts ──────┤ tsc  (NodeNext)   → lib/**/*.js + *.d.ts    ESM
-src/routes/*.ts ────────┤
-src/bin/*.ts ───────────┘
-
-src/client/index.ts ────→ tsc  (CommonJS)   → build/client/index.js
-                                             ↓ text wrap (scripts/build-client.mjs)
-                                             lib/client.js
-```
+The panel reports the project the current workspace points at; it has no global
+repository list. Its bound is a project root (a `.gitnexus` index or a `.git` marker), so
+it cannot become a filesystem probe.
 
-The browser half needs no bundler because it **is** one module: its only imports are
-platform baseline modules (`react`, the UI primitives) supplied by the loader's own
-`require` at runtime, and it has no relative imports at all. `tsc --module commonjs`
-therefore emits exactly one self-contained file, and the wrap is a text operation. A
-bundler would add a dependency and a resolution graph to solve a problem this package
-does not have.
-
-`esModuleInterop` is **off** for the client target on purpose: it makes
-`import * as React from 'react'` compile to a bare `const React = require("react")`,
-which is precisely what the loader factory provides. With interop on, tsc injects an
-`__importStar` helper that would ride along in every page load.
-
-### `scripts/*.mjs` stays JavaScript (deliberate)
-
-`scripts/link-runtime.mjs` runs from `postinstall`, and `scripts/build-client.mjs` is
-the build driver itself. A bootstrap script **must not depend on the build it
-bootstraps** — if those needed compiling, a fresh clone's `npm install` would fail
-because `lib/` does not exist yet. `src/**` and `bin/**` are TypeScript; `scripts/`
-is plain ESM, and that line is intentional rather than unfinished.
-
-### Runtime packages ship no type declarations
-
-`@deepseek-ai/schemastery`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/cordis` and
-`@deepseek-ai/dsh-client-ui-primitives` each declare `"types": "lib/types/index.d.ts"`
-in their manifest and ship no such file. Every plugin author has to write these
-declarations; `types/` holds the four, with the surface limited to what this plugin
-actually uses. The primitive **props** were read off real call sites in shipped
-plugins rather than guessed, because a wrong prop name fails silently at runtime —
-the control renders with a default and nothing reports anything.
-
-## Client half
-
-`src/client/index.ts` is one CommonJS module using nothing but baseline modules
-(`react`), so `scripts/build-client.mjs` wraps it into the loader's factory
-artifact with no bundler at all — a text wrap cannot drift from its source the way
-a bundle can.
-
-The panel splits fetching (`CoveragePanel`) from presentation (`CoverageView`).
-That is not stylistic: a component that fetches cannot be rendered against a
-fixture, and the states worth asserting on — a report with skipped files, one
-without, an error, missing language data — are exactly the ones a fixture supplies.
-`test/client.mjs` renders each of them through a minimal single-pass hooks shim.
-Keyword search follows the same split: `CoveragePanel` owns the request and
-`SearchSection` is a pure function of its props, so the empty, error and result
-states are all fixture-testable without a graph database.
-
-Styling is theme-agnostic by construction: host elements only, `color` inherited,
-every border derived from `currentColor`. `@deepseek-ai/dsh-client-ui-primitives` is
-a baseline module but ships no JS in the installed runtime, so its exports cannot
-be verified from outside — guessing at component props would fail at mount time in
-a browser, where no test in this repository can see it.
-
-## Verified end to end
-
-Installed into the `web` profile and booted; the route answered with real data:
+Inside DSH:
 
-```
-GET /api/gitnexus/coverage?repo=D:\Project\material-ui     HTTP 200
-  manifest meta.json · scanned 28927 · selected 28924 · large 3 · 11 languages
-  2.3 MB  packages/mui-icons-material/lib/index.js   generated
-  1.4 MB  CHANGELOG.old.md
-  739.9 KB packages/mui-icons-material/lib/index.mjs  generated
-GET /api/gitnexus/coverage?repo=C:\Windows                 HTTP 404 (refused)
-```
+- tool `gitnexus_coverage`: `{ repo, includeLanguages? }`
+- tool `gitnexus_delta`: `{ repo }` — would a refresh change anything?
+- route `GET /api/gitnexus/coverage?repo=<project>`
+- route `GET /api/gitnexus/search?repo=<project>&q=<keyword>&limit=20`
+- route `GET /api/gitnexus/file-history?repo=<project>&path=<file>&days=7` — one file's
+  bounded commit timeline
+- route `GET /api/gitnexus/delta?repo=<project>` — Tier 0 comparison against the index
+- route `GET /api/gitnexus/graph?repo=<project>&view=communities|community&id=<community>`
+  — a bounded graph projection
+- route `POST/GET/DELETE /api/gitnexus/analyze` (the only entry that changes an index;
+  `force=1` for a full rebuild, `mode=repair-fts` for the search indexes only)
+- right-sidebar tab `gitnexus`
 
-The search engine and its route were exercised over a loopback harness against this
-repository's real index (the same database the panel reads):
+CLI:
 
-```
-GET /api/gitnexus/search?repo=D:\Project\gitnexus-plus&q=analyzeCoverage  HTTP 200
-  Function analyzeCoverage src/gitnexus/coverage.ts:507
-GET /api/gitnexus/search?repo=D:\Project\gitnexus-plus&q=client/index&limit=3  HTTP 200
-  File index.ts src/client/index.ts
-GET /api/gitnexus/search?repo=C:\Windows\System32&q=x                     HTTP 404 (refused)
+```sh
+npm run build
+node lib/bin/gitnexus-coverage.js <repo-path>
+node lib/bin/gitnexus-coverage.js -r material-ui         # by registry alias
+node lib/bin/gitnexus-coverage.js --all --json           # every indexed repository
+node lib/bin/gitnexus-coverage.js <repo> --fail-on-large # CI gate, exit 2
+npm run check
+npm test
 ```
 
-The helper boundary itself, run under the system Node 24, returns the JSON the host
-parses (the host's Electron Node cannot load the native addon):
+Search has two modes:
 
-```
-node lib/bin/search-helper.js D:\Project\gitnexus-plus analyzeCoverage 5
-{"ok":true,"report":{"query":"analyzecoverage","mode":"graph",
- "results":[{"kind":"Function","name":"analyzeCoverage",
- "filePath":"src/gitnexus/coverage.ts","startLine":507,"endLine":864}],
- "ftsAvailable":false,"total":1,...}}
-```
+- **graph** — the normal path. The host does not load native `lbug`; it starts
+  `lib/bin/search-helper.js` under system Node and searches node names and file paths. It
+  does not search bodies, so it works on an index built with `--skip-fts`.
+- **text** — the fallback when the graph query cannot start. It reads the files listed in
+  the index manifest, matches lines, searches code before docs, and caps files/bytes/
+  matches. The panel labels it 源码关键词（回退）.
 
-## Scope: the project you are in, not a global list
-
-The panel reports **the project the session's workspace points at**. It does not
-list indexed repositories and has no picker.
-
-That is a deliberate reversal. The first design read `~/.gitnexus/registry.json`
-and offered a dropdown, which made a global file a hard dependency — so a fresh
-clone, a second working tree, or an index built with `GITNEXUS_HOME` redirected
-could not be shown at all, which is exactly when a coverage panel is most useful.
-The workspace comes from the slot's session-scoped props (`useWorkspaces` matched
-by `sessionId`); the host route accepts any directory **that is already a GitNexus
-index**, which is the bound that keeps it from being a filesystem probe.
-
-## Maintenance: the refresh runs here, the escape hatches do not
-
-Two situations the read-only half cannot resolve on its own:
-
-- **初始化索引 / 增量刷新** — the index is missing or behind HEAD. This one the plugin
-  runs for you.
-- **强制全量重构** — the incremental refresh has hung. GitNexus's update path is not
-  reliably terminating, and when it wedges a full rebuild is the only way out. This
-  one also has a button, behind its own destructive confirmation: the route implements
-  `--force`, and the dialog says what it rebuilds, how long it can take, and that the
-  index may be briefly unavailable.
-
-**Both maintenance actions run through the host's shell executor.** An earlier revision
-handed over every command as text, justified by "a plugin that spawns processes
-bypasses the permission system". That reasoning was wrong, and the correction is worth
-stating precisely:
-
-DSH's approval service governs **sandbox escalation** — widening the scope a session was
-granted. Its audit pair must be turn-enclosed, which is why `ApprovalService.request()`
-throws outside an open turn; a panel route has no turn, so it cannot ask. It also has
-nothing to ask about here: this command writes `.gitnexus/` **inside the workspace**,
-already within the granted scope.
-
-Confinement is not something a caller opts into. It is what `ctx.shell` *is* in a given
-deployment — `dsh-pwsh-local` exposes the argv seam that `dsh-pwsh-sandbox` wraps
-through `ctx.sandbox.confine`. So routing through the executor gives this plugin exactly
-the isolation your own shell commands get.
-
-What the plugin commits to, and what is tested:
-
-- **It never sets `sandboxPolicy`.** Requesting one would be this plugin choosing its
-  own confinement — escalation, asked for through a door that cannot ask. A denial comes
-  back as `denied` and **is never retried wider**.
-- **One run per repository.** Two concurrent `analyze` processes contend for the same
-  store, and the second reports a failure that says nothing about the repository.
-- **`--index-only` always.** Without it `analyze` rewrites `AGENTS.md`, `CLAUDE.md` and
-  the agent skill files in your tree — a far larger change than "refresh the index".
-- **A confirmation before it starts**, stating the exact command, what it touches and
-  how long it takes.
-- **The full rebuild is a separate confirmation.** It runs only when the request carries
-  `force=1`, its confirmation says it rebuilds the graph and FTS and may take minutes,
-  and its button is labelled 全量重建 rather than borrowing the incremental one.
-- **Cancellable**, with a ten-minute ceiling by default (`analyzeTimeoutMs`).
-
-The full rebuild used to have no button because the host route did not implement
-`--force`. The route does now, and the button runs exactly the command its dialog
-shows — a button that quietly ran something other than its label would still be worse
-than no button.
-
-The commands shown and executed are not a bare `gitnexus analyze`, because that does not
-work in every deployment:
+Clicking a hit calls
+`ctx.sidebarRight.openResourceIn(sessionId, address, { params: { line } })` to open the
+platform file viewer at that line; without that service it falls back to copying the path.
 
-```
-$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; \
-  $env:GITNEXUS_HOME='<project>\.gitnexus\plugin-home'; \
-  gitnexus analyze --index-only '<project>'
+## Troubleshooting
 
-$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; \
-  $env:GITNEXUS_HOME='<project>\.gitnexus\plugin-home'; \
-  gitnexus analyze --index-only --force '<project>'
-```
+Start with the state the panel reports: `GitNexus absent`, `no index`, `index stale`,
+`FTS unavailable`. The rows below cover this plugin's boundary; the linked upstream
+GitNexus path owns the rest.
 
-- `GITNEXUS_MEMORY=off` — the CLI otherwise re-spawns itself with a larger heap over
-  piped stdio, which a confined sandbox denies (`spawn EPERM`).
+| Symptom | What to do here | Upstream GitNexus path |
+| --- | --- | --- |
+| The panel says GitNexus is absent | Install it yourself, or use the panel's install. For a non-standard location set `GITNEXUS_CLI=/path/to/gitnexus/dist/cli/index.js`. | [`gitnexus/README.md` — Requirements](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#requirements), [Quick Start](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#quick-start) |
+| The project has no index | Use **初始化索引** in the panel, or run `gitnexus analyze --index-only <repo>`. | [`README.md` — CLI Reference](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#cli-reference), [`RUNBOOK.md` — Index out of date](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#index-out-of-date--stale-tools) |
+| Refresh fails, `spawn EPERM`, or the index stays `incremental-in-progress` | The panel's command already sets `GITNEXUS_MEMORY=off`, `NODE_OPTIONS=--max-old-space-size=8192`, `GITNEXUS_HOME=<repo>/.gitnexus/plugin-home` and `--index-only`. If the sandbox still refuses, run the copied command in your own shell; the plugin will not escalate. | [`RUNBOOK.md` — LadybugDB / lock errors](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#ladybugdb--lock-errors), [Memory / analyze crashes](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#memory--analyze-crashes) |
+| Refresh fails with `EPERM … mkdir` or `rmdir '<repo>\.gitnexus\parsedfile-store'` | GitNexus deletes this run-scoped store at the start of every parse, and a parse worker creates it again during the parse — both directions can be refused. Two causes, both addressed in 0.1.4: the plugin no longer pre-creates the directory (that was 0.1.3's `rmdir`), and the analyzer's shell call now carries the **repository** as its sandbox workspace root. A panel route has no session, so the sandbox used to fall back to the DSH application directory, whose write capability is a different identity — the repository's write grant never applied. If it still fails, the deployment's mode is read-only: run the copied command in a normal terminal. | [`RUNBOOK.md` — LadybugDB / lock errors](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#ladybugdb--lock-errors), [`RUNBOOK.md` — Clean slate](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#clean-slate-corrupt-or-huge-gitnexus) |
+| Incremental analyze hangs, or the database reports `Maximum database size … has been reached` | Use **全量重建** (`--force`), or the clean-slate steps. | [`RUNBOOK.md` — Clean slate](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#clean-slate-corrupt-or-huge-gitnexus), [`gitnexus/README.md` — Troubleshooting](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#troubleshooting) |
+| Refresh fails with `EPERM … open '<repo>\.gitnexus\lbug.init.lock'` or `unable to acquire init lock` | A transient file lock, not a permissions problem: the ACL for `.gitnexus` was checked on the machine that reported it and came back healthy. GitNexus's first write is that lock, and a scanner, the indexer, or a crashed run can hold it. The plugin clears a stale lock and retries once automatically (the run shows `attempts: 2`). If it still fails, wait a moment and retry, or run the copied command in a normal terminal. | This plugin's retry plus the analyzer's own lock file; no upstream GitNexus path. |
+| Search fails with `A dynamic link library (DLL) initialization routine failed` / `lbugjs.node` | Graph search runs in `lib/bin/search-helper.js`, never in the Electron host. Restart DSH after upgrading and keep `node` on the shell PATH. If the helper cannot start at all, search falls back to source text. | [`gitnexus/README.md` — Troubleshooting](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#troubleshooting) |
+| Windows search returns very few hits, or the panel warns FTS is unavailable | The index was built with `--skip-fts`, or the FTS extension cannot load. Keyword search still matches names and paths; the source fallback matches lines. The panel then offers **修复搜索索引（FTS）**, which runs `analyze --repair-fts` and leaves the graph alone. Two ways it still fails, and the panel names which: the repair must install/load the extension **out of process**, which a confined shell refuses (`spawn EPERM` — run the copied command in a terminal), or the extension file exists but cannot load, which is a missing Windows runtime (VC++ 2015-2022 x64 and OpenSSL 3), not an index problem. | [`gitnexus/README.md` — Windows: full-text search unavailable](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#windows-full-text-search-unavailable), [Analyze warns about unavailable FTS](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#analyze-warns-about-unavailable-fts-or-vector-extensions) |
+| The refresh button says 无需刷新 and is disabled | That is the Tier 0 verdict, not a failure: every file the index recorded still hashes the same, so re-running the analyzer would change nothing. **仍然刷新** forces it anyway (useful after a schema or GitNexus upgrade). If the index recorded no commit baseline, the panel does **not** claim 无需刷新 — it says it cannot confirm and leaves the button enabled. | This plugin's delta engine; no upstream GitNexus path. |
+| The gate says 无法确认 instead of 无需刷新 | The index recorded no commit, so the comparison can only see the working tree. A confined analyze cannot start `git`, which is how the manifest ends up with an empty `lastCommit` — measured here: the same command writes it in a normal terminal and leaves it empty under the sandbox. Run the copied command outside the sandbox once if you want the stronger verdict; the refresh button stays usable either way. | This plugin's delta engine plus the analyzer's git access; no upstream GitNexus path. |
+| The graph card is empty, or fails with 404 | A 404 means the host predates `/api/gitnexus/graph` — restart DSH, not just the page. An empty canvas with a message means the index has no communities yet (an old index), or the store is busy: refresh the index. Nodes are capped by design; the card states how much it left out. | This plugin's host route; graph data itself comes from the GitNexus index. |
+| Clicking a search hit does not open a file | The click uses `ctx.sidebarRight.openResourceIn`; a profile without that service falls back to copying `path:line`. Restart DSH; if it persists, use the Copy button. | This panel/DSH boundary; no upstream GitNexus path. |
+| The file timeline fails with 404/401 | The client hot-reloaded before the host did, so `/api/gitnexus/file-history` is not mounted yet. Restart DSH (not just refresh the page). | This plugin's host route; no upstream GitNexus path. |
+| Analyze runs out of memory | Keep the panel's `NODE_OPTIONS` / `GITNEXUS_MEMORY` settings, or raise the heap manually; the index may need a full rebuild. | [`gitnexus/README.md` — Analysis runs out of memory](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#analysis-runs-out-of-memory), [`RUNBOOK.md` — Memory / analyze crashes](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md#memory--analyze-crashes) |
+| A large file is missing from the graph | This is what the panel reports: size/share, generated/minified heuristics, binary detection. Raising the cap is an upstream analyze option; this plugin only reports the skip. | [`gitnexus/README.md` — Large files are being skipped](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#large-files-are-being-skipped) |
+| Native install fails (`@ladybugdb/core`, `tree-sitter-*`) | The plugin runs `npm install --prefix …`; it needs a C++ toolchain and a reachable registry. Run the manual command from **Getting GitNexus** to see the compiler error. | [`gitnexus/README.md` — Installation fails with native module errors](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md#installation-fails-with-native-module-errors) |
+| The panel does not appear at all | Check that `dsh plugin add` succeeded and DSH was restarted; open it from the sidebar's **+** guide page. For the `desktop` profile, use the Web Plugins page. | This plugin's install path; no upstream GitNexus path. |
+
+## Upstream GitNexus documentation
+
+This README describes the plugin, not GitNexus. GitNexus behavior follows its source docs.
+Repository: [`abhigyanpatwari/GitNexus`](https://github.com/abhigyanpatwari/GitNexus)
+(branch `main`).
+
+| Topic | Path |
+| --- | --- |
+| Install, CLI, environment variables, MCP | [`README.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md) |
+| CLI package, requirements, full Troubleshooting | [`gitnexus/README.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md) |
+| Index stale, clean slate, locks, memory | [`RUNBOOK.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md) |
+| Architecture and data flow | [`ARCHITECTURE.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/ARCHITECTURE.md) |
+| Tests and guardrails | [`TESTING.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/TESTING.md), [`GUARDRAILS.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/GUARDRAILS.md) |
+| CLI command reference | [`gitnexus/skills/gitnexus-cli.md`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/skills/gitnexus-cli.md) |
+| Language-specific notes | [`docs/languages/`](https://github.com/abhigyanpatwari/GitNexus/tree/main/docs/languages) |
+
+Local `.docs/` notes are gitignored; the links above are the published source of truth.
+
+## Maintenance commands
+
+The panel shows and runs more than a bare `gitnexus analyze`:
+
+```powershell
+$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; `
+  $env:GITNEXUS_HOME='<repo>/.gitnexus/plugin-home'; `
+  gitnexus analyze --index-only '<repo>'
+```
+
+Add `--force` for a full rebuild, or `--repair-fts` alone to rebuild the search indexes
+without touching the graph (the panel offers that as **修复搜索索引（FTS）** when the index
+reports FTS as unavailable).
+
+- `GITNEXUS_MEMORY=off` — stops the CLI from re-spawning itself over piped stdio, which a
+  confined sandbox denies (`spawn EPERM`).
 - `NODE_OPTIONS=--max-old-space-size=8192` — supplies the heap that respawn wanted.
-- `GITNEXUS_HOME=<project>\.gitnexus\plugin-home` — the global registry write would
-  otherwise go to `~/.gitnexus`, outside a confined host's writable scope. A failed
-  registry write leaves the index marked `incremental-in-progress` and incomplete.
-  The plugin defaults this redirect to the project's own `.gitnexus/plugin-home`;
-  `gitnexusHome` overrides it.
-- `--index-only` — the default `analyze` also rewrites `AGENTS.md`, `CLAUDE.md` and
-  agent skill files inside your repository. A maintenance action must not edit the
-  working tree.
-
-`--skip-fts` is **adaptive**, not a static default. An index whose manifest says
-`capabilities.fts.status: available` gets no flag; an index without FTS gets
-`--skip-fts`, because the extension's install is an out-of-process step a confined
-host denies (`spawn EPERM`), and that failure aborts the refresh. This matters in both
-directions: measured on a 39-file repository, putting `--skip-fts` on an index that
-already has FTS forces a full graph-store rebuild — 179.22 s against 8.57 s, a 21×
-penalty — while omitting it on an index without FTS makes the refresh fail outright.
-Setting `skipFts: true` forces the flag; there is no config that forces FTS on, because
-enabling it is a repair (`gitnexus analyze --repair-fts`), not an incremental refresh.
-
-The panel prints these rationales next to the commands, so they do not look
-arbitrary. `src/gitnexus/commands.js` is pure and asserted verbatim by tests.
-
-
-The CLI cannot manage the `desktop` profile — Electron owns it. Use the Web
-sidebar's Plugins page there. `web` is CLI-managed:
-
-```sh
-dsh plugin --profile web add <absolute path to this package>
-dsh --profile web --dump-config | grep gitnexus-plus    # layer composes
-dsh --profile web                                        # restart (bundle set changed)
-```
-
-`dsh plugin add` also adds the package to `dsh.profile.bundles` automatically,
-because this package declares `dsh.bundle`.
-
-## Known limits
-
-- **Detection is a filesystem probe, not an execution check.** The plugin declares no
-  runtime dependencies and never imports `gitnexus`; it reads an index another tool
-  produced and, when it can, deep-imports the upstream scan primitives at runtime. That
-  design keeps it a pure observer, but it makes "the operator has no GitNexus" a
-  reachable state — so `src/gitnexus/toolchain.ts` probes it in three states (`ready` /
-  `library-only` / `absent`), separating "the library tree exists" from "a CLI is on
-  PATH" because they gate different promises. The refresh runner consults it **before
-  spawning anything**: with no CLI it reports `unavailable` and tells the operator to
-  install one, rather than starting a process that cannot work. Spawning the CLI to ask
-  its version would be the direct test, but a confined process denies piped stdio, so
-  the probe only stats the filesystem. The engine degrades on its own too — `scan.ts`
-  falls back to its own walker and reports `primitives: 'fallback'`, and the built-in
-  size caps apply.
-- **A report that reused GitNexus's scan rules and one that fell back to an
-  approximation are still not distinguished per file.** The toolchain verdict travels
-  with the report, the language breakdown carries `detector: "gitnexus" | "builtin"`,
-  and the fallback rows are never labelled *parsed* — but the remaining per-file numbers
-  do not carry a provenance marker, so a fallback walk is not labelled as one where
-  those numbers are shown. The built-in walker deliberately does **not** implement
-  upstream's ignore rules faithfully, and its uncovered-file count can therefore carry
-  false positives.
-- **Installing GitNexus from the panel has never been run against a real network.** The
-  command shape is verified (`npm install --prefix … --no-audit --no-fund`, no hardcoded
-  registry), the runner's state machine is covered by fourteen assertions, and the
-  failure paths name the two likely causes — unreachable registry, missing C++ toolchain.
-  What is **not** verified is the download and compile itself: it is several hundred
-  megabytes and was never executed from inside a confined DSH process. Treat the first
-  authorised install on any machine as untested, and fall back to the manual command if
-  it fails — which is why that command is offered first. What *is* verified by tests is
-  that the installed prefix is the one the reader, the language detector and the analyze
-  runner all resolve; the download and compile remain unverified.
-- **`--omit=optional` saves about 486 MB of that install, and is not used by default.**
-  Measured: a full GitNexus tree is 998.9 MB, and omitting the optional dependencies
-  gives 513.2 MB by dropping `onnxruntime-node` (287 MB), `onnxruntime-web` (139 MB) and
-  `@huggingface/transformers`. Those serve vector search and embeddings, which this
-  plugin never enables and reports as `unavailable`. The default does not pass the flag
-  because the plugin cannot verify that analysis still succeeds without them on every
-  platform, and a refresh that fails in an unexplained way is worse than one that is
-  large. A deployment that wants the smaller tree can set `gitnexusInstallDir` aside and
-  install by hand with `--omit=optional`.
-- **The refresh runs outside the conversation, and that has a real consequence.** A
-  command started from the panel goes through `ctx.shell` and is confined exactly as
-  your own shell commands are, but it is **not** a tool call: it writes no
-  `approval/asked` + `approval/decided` pair into the session log, and it does not
-  appear in the transcript. That pair could not be written even if it were wanted —
-  `ApprovalService.request()` requires an open turn and throws without one, which is
-  also why there is nothing to approve: the command does not escalate. The audit record
-  is the run state the panel holds, which is per-process and is not persisted. If you
-  want a refresh on the conversation's record, run the handed-over command in the
-  session instead; that path is unchanged.
-- **Walk cost scales with file count.** ~29 000 files takes ~1.4 s warm, ~13 s on a
-  cold filesystem cache. The host half caches reports for 15 s; a panel that polls
-  faster than that gains nothing.
-- **The minified heuristic reads a 64 KB head and extrapolates.** It flags
-  single-line bundles reliably and correctly *declines* generated-but-multi-line
-  output (verified: a 2.3 MB, 75 263-line file averages 31 chars/line). The
-  generated-path heuristic covers that gap, as a hint rather than a verdict.
-- **Binary assets are detected and reported separately, and that is not cosmetic.**
-  A first revision tested only "no newlines ⇒ one enormous line", so a real 380 MB
-  `.glb` was reported as *"single-line ≈ 399 230 584 chars — probably minified
-  rather than source"*. The number was absurd; the conclusion was worse, because it
-  implied that 97 % of one repository's skipped bytes were compressed **source**
-  when 414 of 417 MB were 3D models that could never hold a symbol. Detection is
-  git's own rule (a NUL byte in the head means binary), plus a control-byte ratio;
-  binary short-circuits both the minified and generated claims, and the headline
-  warning now separates binary from text so the figure worth acting on is visible.
-  Verified end to end on the repository that exposed it: the actionable remainder
-  went from an implied 416.9 MB to **2.6 MB**.
-- **`git ls-tree` is not used.** An earlier design compared the index against
-  git-tracked files; real data killed it — 8 of the "missing" tracked files in a
-  37-file repo were dotfiles excluded by the walker's `dot: false`, and 2 indexed
-  files were untracked. The walker's own rules are the only honest denominator.
-- **Keyword search is graph name/path first, with a source-text fallback.** The graph
-  mode finds symbols and files whose *names* or *paths* contain the query; it does not
-  search function bodies, comments or descriptions. The fallback (`mode: "text"`) does
-  search line text, but only in the files the index manifest lists, and only when the
-  graph helper cannot start. Content-level search as a first-class mode is GitNexus's
-  FTS surface, and on this machine the FTS extension fails to load
-  (`libfts.lbug_extension` missing) and the current index was built with `--skip-fts`.
-  The panel labels the two modes separately (符号名 / 文件路径 vs 源码关键词（回退）) and
-  never presents a text hit as a graph hit.
-- **Search needs a child Node process for the graph path.** The host's Electron Node
-  cannot load the LadybugDB addon (ABI mismatch), so the query is delegated to
-  `lib/bin/search-helper.js` under the system Node 24. This is deliberate, not a
-  workaround to remove: an in-process search fails on the host with the DLL
-  initialization error above. If the shell executor is unavailable (measured on this
-  machine: the Windows `windows-acl-run` sandbox cannot create its temp directory),
-  search does **not** fail — it falls back to the bounded source-text scan and labels
-  the result `text`. The graph query remains the preferred path when the helper can
-  start.
-- **The source fallback is not the graph.** It searches line text in the files the
-  index manifest lists, not symbol relationships; code paths are searched before
-  documentation, and the file/byte/match caps can truncate a large repository. The
-  panel's card title changes to 源码关键词（回退） and the warning names the fallback,
-  so a text hit is never presented as a graph hit.
-- **Panel effects and re-render are still not automated.** `react-dom` is not installed
-  on this machine, so rendering uses a single-pass shim: `useState` yields its initial
-  value and `useEffect` never runs. The pure view is covered; the fetch lifecycle is
-  not. The panel has now been checked once against the real right sidebar, and that
-  check is what exposed the two-column layout clipping the language card at a narrow
-  pane edge, the grey single-bucket chart, the invented `--dsw-color-*` tokens, the
-  raw English `index` cap source, and the `--skip-fts` config default. Those are
-  fixed, but a future prop or layout change can still pass every test here without
-  being seen in a browser.
-- **Install → initialize has not been exercised end to end against a real npm install.**
-  The managed-prefix wiring, the auto-chain gate, and the analyze command are covered by
-  tests; the several-hundred-megabyte download and native compile are not.
+- `GITNEXUS_HOME` — redirects the global registry write into the project, so a failed
+  write to `~/.gitnexus` cannot leave the index stuck at `incremental-in-progress`.
+- `--index-only` — otherwise `analyze` rewrites `AGENTS.md`, `CLAUDE.md` and skill files
+  inside the repository.
+
+`--skip-fts` is **adaptive per index**: no flag when the manifest says FTS is available,
+and the flag when it is not. `skipFts: true` can force the flag; there is no config that
+forces FTS on, because enabling it is a repair (`gitnexus analyze --repair-fts`), not an
+incremental refresh — so the panel exposes it as its own action, and a repair run never
+carries `--skip-fts` (the CLI accepts that pair and exits 0 having done nothing).
+
+## License (read before commercial use)
+
+This plugin is **MIT** (see [LICENSE](LICENSE)).
+
+**GitNexus is `PolyForm-Noncommercial-1.0.0`**: noncommercial use is granted, commercial
+use is restricted. `gitnexus` is a **peer**; this package does not install, bundle or
+redistribute it. But using this plugin's GitNexus-backed features (reading an index,
+refreshing it, installing it) puts **your use of GitNexus** under GitNexus's license;
+commercial use needs a separate grant from GitNexus's author:
+
+<https://github.com/abhigyanpatwari/GitNexus/blob/main/LICENSE>
+
+In one line: **MIT covers this plugin's code; GitNexus's license covers GitNexus, and using
+the related features puts that use under it.**
+
+## Boundaries
+
+- Coverage and search are read-only; maintenance is a separately confirmed write and
+  never starts by itself.
+- The refresh gate compares content hashes of the files the index recorded. It cannot
+  see a change the analyzer would make for its own reasons (a schema upgrade, a new
+  feature mode); **仍然刷新** exists for exactly that case.
+- The graph view draws communities, not every symbol: the overview is the community
+  graph, and a drill-down shows at most the configured node budget of one community's
+  members. Both say when they are truncated.
+- The plugin reports facts about a GitNexus index; it does not rewrite the parser or
+  reimplement the graph database.
+- Graph search matches names/paths, not bodies; the text fallback matches lines and is
+  capped.
+- The source fallback only covers files in the index manifest; refresh the index for new
+  files.
+- Deeper design/build notes are kept out of the public README; this file stays at the
+  "what it does" and "how to fix it" level.