dsh-gitnexus-plus 0.1.1 → 0.1.3

package/README.md

@@ -1,484 +1,221 @@
 # 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.3](https://github.com/Moowningstar/gitnexus-plus/releases/tag/v0.1.3)** ·
+[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**,
+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
+
+- **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.
+
+## 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)
-```
-
-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 nothing here to display.
-
-## 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.
-- **Resolver confidence** — untyped receiver sites, which make `impact` and
-  `context` a lower bound rather than an exact answer.
-
-## 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:
-
-```
-npm install --prefix <DSH_HOME>/gitnexus-plus/gitnexus gitnexus@^1.6.12
+```sh
+dsh plugin add dsh-gitnexus-plus
 ```
 
-and the confirmation states what that means before anything starts:
+Restart DSH after adding it. The panel is a right-sidebar tab: open the sidebar's **+**
+→ guide page → **GitNexus 索引**.
 
-- **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.
+The `desktop` profile is managed by Electron; the CLI cannot change it. Use the Web
+sidebar's Plugins page there. From a local checkout:
 
-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.
+```sh
+dsh plugin --profile web add <absolute path to this package>
+```
 
-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
-- **panel** — a right-sidebar tab type `gitnexus`, opened from the sidebar's **+** →
-  guide page ("GitNexus 索引")
-
-The coverage route is read-only and accepts only directories that are already GitNexus
-indexes, so it cannot be turned into a filesystem probe; 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, `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.
-
-## 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 |
-
-### Two compile targets, no bundler
+The panel can also install it through DSH's shell:
 
+```sh
+npm install --prefix <DSH_HOME>/gitnexus-plus/gitnexus gitnexus@^1.6.12
 ```
-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 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)
+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.
 
-`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.
+## Usage
 
-### Runtime packages ship no type declarations
+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.
 
-`@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.
+Inside DSH:
 
-## Client half
+- tool `gitnexus_coverage`: `{ repo, includeLanguages? }`
+- 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 `POST/GET/DELETE /api/gitnexus/analyze` (the only entry that changes an index)
+- right-sidebar tab `gitnexus`
 
-`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.
+CLI:
 
-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.
+```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
+```
 
-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.
+Search has two modes:
 
-## Verified end to end
+- **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 源码关键词（回退）.
 
-Installed into the `web` profile and booted; the route answered with real data:
+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.
 
-```
-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)
-```
+## Troubleshooting
 
-## 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. Handed
-  over as text.
-
-**增量刷新 runs 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.
-- **Cancellable**, with a ten-minute ceiling by default (`analyzeTimeoutMs`).
-
-The full rebuild still has no button, because the host route does not implement
-`--force`. A button that quietly ran something other than its label would be worse than
-no button.
-
-The commands handed over are not a bare `gitnexus analyze`, because that does not work
-in every deployment:
+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.
 
+| 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 '<repo>\.gitnexus\parsedfile-store'` | GitNexus 1.6.12 creates this cache directory from the parse worker. The plugin pre-creates the cache directories before spawning; restart DSH after upgrading. If it still fails, the sandbox token cannot write `.gitnexus`; 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) |
+| 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. Repairing FTS is an upstream action. | [`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) |
+| 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>'
 ```
-$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; \
-  gitnexus analyze --index-only '<project>'
 
-$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; \
-  gitnexus analyze --index-only --force '<project>'
-```
+Add `--force` for a full rebuild.
 
-- `GITNEXUS_MEMORY=off` — the CLI otherwise re-spawns itself with a larger heap over
-  piped stdio, which a confined sandbox denies (`spawn EPERM`).
+- `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.
-- `--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 **no longer** part of either command. Measured on a 39-file repository,
-disabling a search index the store already has forces a full graph-store rebuild —
-179.22 s against 8.57 s, a 21× penalty on the transition an operator is most likely to
-hit, and the opposite of incremental. Letting FTS fail on its own costs nothing: it
-prints a warning and indexes anyway.
-
-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
-
-- **A machine without GitNexus is not detected yet.** 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. `src/gitnexus/toolchain.ts` implements a three-state probe (`ready` /
-  `library-only` / `absent`, separating "the library tree exists" from "a CLI is on
-  PATH", because they gate different promises), and the refresh runner now 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. The engine
-  also degrades correctly on its own — `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 inside the report itself.** The toolchain
-  verdict now travels with it, so the panel knows whether GitNexus is present and says so
-  — but the per-file numbers do not carry a provenance marker, so a fallback walk is not
-  labelled as one where the 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.
-- **`--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.
-- **Panel effects and re-render are untested.** `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.
-- **No incremental update yet.** This ships the read-only monitoring half of the
-  plan. Driving `analyze` is a separate concern with its own safety story — if
-  nothing else, a status check must never start a 30-second rebuild.
+- `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.
+
+## 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 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.