feat: manage GitNexus as an optional local code-intelligence companion

[pacphi]

Executive brief

Add first-class, opt-in management of GitNexus as a
per-repository code-intelligence companion, following the same shape as
#114 (deja-vu).

GitNexus parses a repository into a local knowledge graph (symbols, call edges, process/flow
traces) and exposes it through MCP tools (query, context, impact, trace, cypher,
detect-changes) so a coding agent can answer "who calls this," "what breaks if I change this,"
and "what changed since the last commit" without re-reading the whole tree. It is already installed
on this machine as npm:gitnexus via mise's npm backend — not plain global npm — which is the
main reason this proposal cannot simply reuse #114's install/update logic unchanged.

This complements, and must stay distinct from, the other two companion memory planes already
proposed or shipped in this repo:

• Ruflo/AgentDB remains authoritative for curated operational memory: decisions, structured
  state, outcomes, reusable patterns.
• deja-vu (feat: manage deja-vu as an optional cross-host session-memory companion #114) is the searchable evidence archive over session transcripts — what agents
  said and did across hosts.
• GitNexus is a searchable structural index over the codebase itself — what the code is and
  how its parts connect — refreshed by re-running analyze, not by watching sessions.

Agentic Kit should manage the same lifecycle shape for users who opt in:

intent → install (method-aware) → configure host wiring → index (per project) → verify
       → detect drift → sync/repair → remove owned wiring/package/index safely

The integration must follow the same ownership, dry-run, idempotence, verification, and fail-closed
rules as other managed tools (docs/MANAGED-TOOLS.md, ADR-0016, ADR-0023) — and it must extend that
contract's install-method detection beyond "npm global or bust," because GitNexus is the first
managed-companion candidate this repo would model whose primary real-world install path is a
non-npm-global backend.

Why this belongs in Agentic Kit

An agent working in a large, unfamiliar repo repeatedly pays the cost of re-deriving structure that
doesn't change between turns: who calls a function, what a rename would break, which files a diff
actually touches transitively. GitNexus is purpose-built for that gap. Its upstream CLI already
provides:

• a published npm package, gitnexus, with an interactive setup/uninstall pair that wires MCP
  entries, skills, and hooks for detected editors (Claude Code, Cursor, Codex, Antigravity, OpenCode,
  CodeBuddy, Qoder, Windsurf) — a materially larger editor set than Agentic Kit's own host registry;
• gitnexus analyze to build/refresh a per-repository index under a gitignored .gitnexus/
  directory, registered globally in ~/.gitnexus/registry.json;
• gitnexus doctor to report runtime/native-binding health (see the "Native dependency health" risk
  below — this machine's own install is currently missing its native binding);
• gitnexus check --json for structural checks (e.g. --cycles) with machine-readable output;
• gitnexus clean / gitnexus remove <target> for scoped index deletion, and a dry-run-by-default
  gitnexus uninstall that requires -f/--force to apply — the same safe-by-default shape Agentic
  Kit already expects from managed tools.

Upstream references:

• Repository (45k★, active daily release cadence —
  v1.6.10-rc.166 published the same day this proposal was drafted)
• README (install methods, MCP integration matrix, data/privacy model)
• SECURITY.md, ARCHITECTURE.md, GUARDRAILS.md, RUNBOOK.md (documented but not yet read in
  full for this proposal — Phase 0 should do a close read before implementation starts)

Current Agentic Kit architecture

The same seams #114 identified already exist and should be reused, not re-invented:

• src/commands/setup.mjs installs Ruflo, Agentic-QE, AgentDB, RuvNet Brain, and enabled hosts.
• src/commands/status.mjs emits health/drift rows and named remediations.
• src/commands/sync.mjs derives a plan from status, applies repairs, and recollects facts to prove
  convergence.
• src/commands/uninstall.mjs distinguishes footprint removal, package removal, purge, and
  project-data preservation.
• src/lib/versions.mjs owns the current drift model — but its installedVersion(pkg) (line 9-17)
  reads only path.join(globalRoot(), pkg, 'package.json'). That is correct for npm-global
  installs and is why driftReport()'s own comment (line 62-66) explains that mise/native/brew
  installs of the frontier host CLIs resolve to null and are filtered out of drift entirely —
  Agentic Kit already deliberately disowns them rather than guess.
• docs/MANAGED-TOOLS.md's hosts row (line 62) already documents this exact split in prose:
  "npm @latest — only when npm-managed... explicitly disowned if brew/mise/native... disk:
  global package.json, else --version probe." There is, however, no reusable code module that
  classifies which backend owns a given binary — today's mise-awareness is a presence/absence
  fallback, not a path-based classifier. This proposal is the first case that needs one.
• src/lib/natives.mjs is the existing pattern for verifying a package's native binding health
  (better-sqlite3 for ruflo/agentic-qe) independently of whether the package itself resolves — the
  right template for GitNexus's own native-binding check (see below).
• src/lib/adapters/lifecycle.mjs defines the shared detect → plan → apply → verify → undo
  contract; tests/kit/adapter-lifecycle-conformance.test.mjs already enforces it.
• ADR-0016 (Accepted, capability-driven adapters) and ADR-0023 (Implemented, fail-closed operations)
  govern this exactly as they governed feat: manage deja-vu as an optional cross-host session-memory companion #114.

Concrete prior art for the install-method problem this proposal raises: this machine has
already hit mise-vs-npm prefix disagreement for Agentic Kit's own package (npm prefix = mise
was a real support issue on this box). GitNexus is simply the first managed companion — as
opposed to the kit itself, or a host CLI Agentic Kit deliberately disowns — where the natural
install path is mise's generic npm: backend rather than plain global npm. That forces the
ownership question #114 didn't have to answer: should Agentic Kit only ever disown non-npm-global
installs (safe, but leaves mise users permanently unmanaged), or should it learn to drive the
backend that actually owns the artifact (mise included) so mise users get the same managed
experience npm-global users get? This proposal recommends the second, scoped narrowly (see Goals).

Goals

1. Let users opt into GitNexus during setup or through an explicit command/config change, per host
   project (GitNexus indexes are per-repository, not a single global index like deja-vu's).
2. Detect the actual install method rather than assuming npm-global: mise npm backend, plain npm
   global, pnpm global, or ephemeral npx/pnpm dlx (no install at all). Classify ownership per
   method instead of collapsing everything non-npm-global into "external."
3. Where Agentic Kit does take ownership, drive the update mechanism that backend expects
   (mise upgrade npm:gitnexus / mise use -g npm:gitnexus@latest for a mise-owned install;
   npm install -g gitnexus@latest only for an npm-global-owned install) rather than always
   shelling out to bare npm and risking a second, shim-orphaned copy.
4. Wire only the enabled/present Agentic Kit hosts selected by policy — not GitNexus's full
   supported-editor list, even though gitnexus setup is happy to configure Cursor, Antigravity,
   Windsurf, CodeBuddy, and Qoder unattended.
5. Build/refresh the index for the current project on request, show progress, and verify it via
   gitnexus status / gitnexus doctor without exposing indexed code content.
6. Surface presence, install method, ownership, version drift, native-binding health, MCP wiring
   health, and per-project index health in ak status.
7. Make ak sync converge the package (via its owning backend), host wiring, and stale indexes
   without duplicate entries or repeated re-analysis.
8. Remove only Agentic Kit-owned wiring, indexes, and package; preserve external installs, AGENTS.md/
   CLAUDE.md content GitNexus did not author, and any indexes the user built directly with the CLI.
9. Default analyze invocations to --skip-agents-md --skip-skills (or --index-only) so that
   an ak-triggered index build never mutates AGENTS.md/CLAUDE.md or drops files under
   .claude/skills/gitnexus/ without a separate, explicit opt-in — this repo has already hit
   AGENTS.md drift failing lint from an unrelated tool's auto-injection, and GitNexus's own
   analyze writes a tagged block into both files by default.
10. Disclose GitNexus's license (PolyForm Noncommercial 1.0.0, not the permissive MIT deja-vu ships
    under) before install, so a commercial user isn't opted into a noncommercial dependency by
    surprise.
11. Keep the integration local-first, zero-runtime-dependency for Agentic Kit itself, cross-platform,
    testable, and aligned with Agentic Kit's trust boundary.

Non-goals

• Replacing Ruflo/AgentDB memory or the deja-vu evidence archive (feat: manage deja-vu as an optional cross-host session-memory companion #114). GitNexus indexes code
  structure, not decisions or transcripts.
• Wiring every editor GitNexus itself supports; only Agentic Kit's own enabled host set.
• Adopting, updating, or deleting a Homebrew, Docker-only, or manually-downloaded GitNexus
  installation — those remain external/unowned, same as feat: manage deja-vu as an optional cross-host session-memory companion #114's stance on deja-vu.
• Building a generic "any npm package under mise" adapter as part of this issue. The install-method
  classifier this proposal needs should be written narrowly enough to serve GitNexus (and be
  reusable later), but generalizing it into a public "mise-aware package manager" abstraction is a
  separate, larger refactor and out of scope here.
• Running gitnexus analyze --embeddings (semantic/vector indexing, local ONNX inference) by
  default — CPU/time cost and local model download should be a separate explicit opt-in.
• Running the GitNexus web UI (gitnexus serve) or the remote HTTP MCP mode (gitnexus mcp --http)
  as part of default management; stdio MCP only, matching how Agentic Kit wires other MCP servers.
• Publishing indexes to the upstream understand-quickly registry (gitnexus publish) — that
  requires a separate user-supplied token and is explicitly opt-in upstream already.
• Adopting GitNexus's own Docker images into Agentic Kit's install surface.
• Repairing or vendoring GitNexus's native binding (@ladybugdb/core's lbugjs.node) — Agentic Kit
  should detect and report the missing-native state gitnexus doctor already surfaces and forward
  its own remediation text, not reimplement the fix.

Primary use cases

1. First-time indexing on a large, unfamiliar repo

A user opts in on a repo they didn't write. ak setup --with-gitnexus installs GitNexus via the
detected/allowed backend, wires the enabled hosts' MCP entries, and runs one analyze --skip-agents-md --skip-skills pass with progress output. The agent can now call context/impact
without the user manually running the upstream CLI.

2. Impact analysis before a risky change

Before editing a widely-called function, an agent calls GitNexus's impact/trace tools through
MCP to see blast radius, instead of grepping and hoping.

3. Diff-to-symbol mapping in review

detect-changes maps a git diff's hunks to indexed symbols and affected flows — useful both for an
agent preparing a PR description and for a reviewer agent checking coverage of a change.

4. Stale-index drift repair

The repo has moved on since the last analyze (new commits, renamed files). ak status reports the
index as stale (via gitnexus status); ak sync re-runs analyze for that project, still with
file-injection flags suppressed unless the user separately opted into them.

5. Native-binding failure surfaced honestly

lbugjs.node is missing (a real, reproduced state on this machine right now — gitnexus doctor
reports native ✗ lbugjs.node missing with exact repair commands for pnpm/bun/npm). ak status
must show this as degraded with GitNexus's own remediation text, not silently report the package as
healthy because the CLI resolves on PATH.

6. Mise-managed install, npm-global user expectations

A user who already manages Node/npm packages through mise (as this machine does, per
~/.config/mise/config.toml: "npm:gitnexus" = "latest") runs ak setup --with-gitnexus. Agentic
Kit detects the existing mise-owned install, does not shadow it with a second npm-global copy, and
if it takes ownership, updates it later via mise upgrade npm:gitnexus rather than bare npm.

7. External/manual installation

GitNexus is already installed via Homebrew-adjacent means, a manually downloaded artifact, or Docker
only (no CLI on PATH). Agentic Kit detects and can report what it finds but does not adopt, update,
or uninstall it without an explicit ownership transition — mirroring #114's "external installation"
use case.

8. Clean removal

ak uninstall removes only Agentic Kit-owned MCP wiring by default. A separate flag removes the
Agentic Kit-owned package (via its owning backend). A separate, confirmed flag removes per-project
.gitnexus/ index data; source files and any AGENTS.md/CLAUDE.md content are left untouched unless
GitNexus's own tagged block is present and Agentic Kit itself wrote it (see Goal 9).

Product principles

1. Structure, not memory. GitNexus indexes what the code is; it must not be modeled as a
   memory plane, a Ruflo/AgentDB replacement, or a deja-vu replacement.
2. Install-method truth over install-method assumption. Ownership decisions are made from what
   is actually resolvable on disk for this backend, not from an assumption that npm-global is the
   only real install.
3. Drive the backend that owns it. An owned update goes through mise, npm, or pnpm — whichever
   actually installed the artifact — never a second, competing installer.
4. Opt-in because file injection is sensitive. No MCP registration, skill install, or
   AGENTS.md/CLAUDE.md mutation happens from defaults alone; index builds default to
   --skip-agents-md --skip-skills until the user separately opts into GitNexus's own file
   injection.
5. Host intent controls wiring, same as feat: manage deja-vu as an optional cross-host session-memory companion #114: enabled Agentic Kit hosts determine eligible
   GitNexus targets, not GitNexus's full supported-editor list.
6. Presence is not ownership. External binaries, Docker-only installs, and pre-existing
   .gitnexus/ indexes remain externally owned until an explicit transition.
7. One backend update owner per install. Whichever backend Agentic Kit determined owns the
   artifact is the only one ak sync drives for it.
8. Observed truth drives status. Parse gitnexus doctor, gitnexus status, gitnexus check --json, resolved binary path, and ownership receipts; never infer healthy from exit code alone.
9. License disclosure is not optional. PolyForm Noncommercial 1.0.0 is surfaced before install,
   every time, the same way transcript-read disclosure was required for feat: manage deja-vu as an optional cross-host session-memory companion #114.
10. Unknown stays unknown. A missing native binding, an unresolvable doctor shape, or an
    unreadable index is degraded/unknown, not healthy or absent.

Proposed user experience

Setup

ak setup --with-gitnexus
ak setup --with-gitnexus --gitnexus-index-scope current-project
ak setup --no-gitnexus

Interactive setup should default to No and explain, before mutation:

• GitNexus's license (PolyForm Noncommercial 1.0.0) and what that restricts;
• that source files in the current project will be parsed into a local .gitnexus/ index;
• which enabled hosts will receive MCP entries;
• that AGENTS.md/CLAUDE.md and .claude/skills/gitnexus/ will not be touched unless the user
  separately opts into GitNexus's own file-injection behavior;
• which install backend will be used (detected mise/npm/pnpm, or a choice if more than one is
  viable) and that Agentic Kit will only update through that backend going forward;
• that embeddings/semantic indexing and the local web UI are not enabled by default.

Status

gitnexus  ok      1.6.9 mise-managed (npm:gitnexus) · MCP: claude,codex · index current
gitnexus  warn    native binding missing (lbugjs.node) · see `gitnexus doctor`
gitnexus  warn    installed externally (docker-only, no CLI on PATH) · management disabled
gitnexus  warn    mise npm:gitnexus 1.6.8 installed, 1.6.9 available · sync upgrades it
gitnexus  warn    index stale for this project · sync re-analyzes
gitnexus  info    management disabled

The collector should distinguish:

• absent;
• present and externally managed (and by which backend, where knowable);
• present and Agentic Kit-owned (and by which backend: mise, npm, pnpm);
• package update available, compared within the correct namespace for that backend;
• native-binding healthy vs missing/degraded;
• MCP wiring present/missing per enabled host;
• per-project index absent, stale, damaged, or current;
• doctor/status/check output unavailable or unparseable;
• user drift preserved (e.g. a user-run analyze --embeddings should not be silently reverted).

Status and Dashboard output must never include indexed symbol names, file contents, query strings,
or graph query results.

Sync

ak sync should:

1. install GitNexus only when enabled and absent, through the backend selected at setup time (or
   detected fresh if setup ownership wasn't recorded);
2. upgrade only an Agentic Kit-owned install, through that same backend
   (mise upgrade npm:gitnexus, npm install -g gitnexus@latest, or pnpm update -g gitnexus) —
   never mix backends for one artifact;
3. reconcile MCP wiring for enabled hosts via GitNexus's own setup/uninstall -c <agent> scoped
   to Agentic Kit's host list, not GitNexus's full editor list;
4. re-run analyze --skip-agents-md --skip-skills only for projects with a stale or missing index
   that the user has opted into indexing, never proactively across every repo on disk;
5. verify independently via gitnexus doctor, gitnexus status, and host MCP configuration
   observation;
6. recollect status and fail if required owned surfaces did not converge.

Repeated sync must be a true no-op.

Removal

ak uninstall                          # remove Agentic Kit-owned GitNexus MCP wiring
ak uninstall --remove-gitnexus        # also remove the owned package, via its owning backend
ak uninstall --purge-gitnexus-data    # also delete .gitnexus/ index data for owned projects, confirmed
ak uninstall --purge                  # include owned package; preserve index data unless requested

Rules:

• Run GitNexus's own uninstall -c <agent> --force only for hosts Agentic Kit recorded as owned.
• Preserve unrelated host configuration and any user-modified MCP entries.
• Preserve an externally-managed install and say how it remains installed (and via which backend).
• Remove the package only through the backend the ownership receipt names.
• Preserve .gitnexus/ indexes, ~/.gitnexus/registry.json, and any AGENTS.md/CLAUDE.md content by
  default; a data purge must resolve exact known paths, preview them, require confirmation, and
  never delete source files.
• If teardown is incomplete, retain the ownership receipt and return nonzero.

Configuration and ownership model

Extend the same versioned integration envelope #114 proposes, rather than adding an unrelated
top-level boolean:

{
  "integrations": {
    "version": 3,
    "tools": {
      "gitNexus": {
        "enabled": true,
        "hosts": ["claude", "codex"],
        "indexOnSetup": true,
        "fileInjection": false
      }
    },
    "ownership": {
      "gitNexus": {
        "install": {
          "method": "mise",
          "backendRef": "npm:gitnexus",
          "package": "gitnexus",
          "managedBy": "agentic-kit"
        },
        "targets": {
          "claude": "claude-code",
          "codex": "codex"
        },
        "indexedProjects": ["/abs/path/to/project-a"]
      }
    }
  }
}

The exact schema can be refined during implementation, but it must preserve these distinctions,
which extend #114's model with the install-method axis this integration specifically requires:

• desired enablement;
• desired host set;
• install method (mise | npm-global | pnpm-global | external | unknown) and enough of
  a backend reference to drive an update through it (e.g. npm:gitnexus for mise, nothing extra
  needed for plain npm-global);
• package ownership, scoped to that method;
• per-host wiring ownership;
• whether file injection (AGENTS.md/CLAUDE.md/skills) was explicitly enabled by the user;
• which projects' .gitnexus/ indexes Agentic Kit built/owns, versus ones the user built directly
  with the CLI before or outside Agentic Kit management;
• user data ownership, which remains user even when Agentic Kit built the derived index.

Configuration migration must be additive and default existing installations to disabled/unowned.

Proposed architecture

Install-method classifier (the new piece this proposal needs beyond #114)

A small, focused module — e.g. src/lib/install-method.mjs — that, given a binary name:

1. resolves it on PATH (command -v <bin> / equivalent);
2. reads the realpath and classifies it:
   • contains mise/installs/npm-<pkg>/ → mise, with the version directory itself giving the
     installed version (no package.json walk needed — mise's directory name is the version);
   • resolves under npm root -g/npm config get prefix → npm-global, same as today's
     installedVersion();
   • resolves under pnpm root -g (or a pnpm global bin dir) → pnpm-global;
   • resolves anywhere else (Homebrew cellar, hand-downloaded, another version manager's shim) →
     external;
   • unresolvable at all → absent;
3. returns { method, version, path } without mutating anything.

This directly generalizes the disowning behavior versions.mjs's installedVersion() already
performs for hosts (comment at line 62-66) and the policy docs/MANAGED-TOOLS.md already documents
in prose (line 62) — turning "presence-or-null, filtered out if null" into an actual classified
result GitNexus's adapter (and, opportunistically, the host detection in ak host) can act on
instead of just disowning.

"Latest" comparison stays in the same namespace regardless of method (npm registry view gitnexus@latest version, per MANAGED-TOOLS.md invariant #3) — only the update mechanism differs
by method, not the version-comparison source.

Native-binding health

Reuse the shape of src/lib/natives.mjs (resolve a dependency's compiled artifact from a known
subpath, report boolean-plus-location) for GitNexus's @ladybugdb/core native binding, rather than
trusting gitnexus doctor's human-formatted text alone. Parse gitnexus doctor output for the
native line as a first pass; file an upstream ask for a --json doctor mode (today only check
supports --json) as a documented open question rather than building a brittle text scraper long
term.

Managed companion adapter

• src/lib/gitnexus.mjs — install-method-aware package/version, binary path, doctor/status
  parsing, per-project index facts.
• src/lib/adapters/gitnexus.mjs — detect/plan/apply/verify/undo, built on the shared lifecycle
  contract in src/lib/adapters/lifecycle.mjs.

Do not add GitNexus to HOST_REGISTRY or PROVIDER_REGISTRY. It consumes host capabilities and
projects an index into MCP-reachable tools; it is not an execution host or inference provider.

Lifecycle contract

detect

• read desired config;
• classify install method and resolve version via the classifier above;
• parse gitnexus doctor and gitnexus status (per current project) and gitnexus list (registry
  scope);
• inspect enabled-host MCP wiring for GitNexus entries;
• return normalized facts without writing or refreshing anything.

plan

• deterministically calculate package (method-aware), host wiring, and per-project index operations;
• disclose every host config/index-build/file-injection mutation before it happens;
• produce no operation for disabled or externally-owned installs;
• classify destructive data purge separately from wiring/package removal.

apply

• install via the owning backend (mise/npm/pnpm);
• invoke GitNexus's own setup -c <agent> / uninstall -c <agent> --force scoped to Agentic Kit's
  enabled hosts;
• run analyze --skip-agents-md --skip-skills (plus --index-only where file injection was never
  opted into) for projects the plan selected;
• record exact ownership receipts, including install method, only after verified success;
• report ok/degraded/failed/skipped plus whether an older artifact remains usable.

verify

• independently re-parse doctor/status/check --json;
• observe actual host MCP configuration;
• prove expected per-project index state without retrieving or printing indexed content;
• never trust the apply result as proof.

undo

• reverse dependencies: MCP wiring → owned package (via its owning backend) → (only if separately
  confirmed) owned index data;
• preserve user drift and externally-owned installs/indexes;
• retain receipts after any incomplete undo.

Phased implementation plan

Phase 0 — ADR and domain alignment

• Add a focused ADR (or amend ADR-0016) defining GitNexus's role as a structural-index companion,
  distinct from Ruflo/AgentDB and from deja-vu.
• Read GitNexus's SECURITY.md, ARCHITECTURE.md, and GUARDRAILS.md in full and fold anything
  materially relevant (loopback defaults, auth-token requirements for non-loopback MCP HTTP, etc.)
  into this proposal before implementation.
• Decide the license-disclosure copy for setup (PolyForm Noncommercial 1.0.0) with input from
  whoever owns Agentic Kit's licensing posture.

QA gate: ADR is current and accurately scopes GitNexus against the other two memory-adjacent
companions; no document claims behavior is implemented yet.

Phase 1 — Detection and normalized facts

• Build the install-method classifier and native-binding check.
• Parse doctor/status/check --json/list output against fixtures, including the
  currently-reproducible missing-native-binding state.
• Add structured status facts and human rows.
• Keep collection read-only.

QA gate: mise, npm-global, pnpm-global, external, and absent installs are fixture-covered and
honestly classified; the missing-native-binding case is caught and reported with GitNexus's own
remediation text.

Phase 2 — Setup and installation

• Add setup flags and persisted opt-in intent, including the file-injection opt-in as a separate
  flag from the base enable flag.
• Add pre-mutation disclosure, including the license line.
• Install through the detected/chosen backend.
• Wire selected hosts via GitNexus's own scoped setup -c.
• Run one analyze --skip-agents-md --skip-skills pass with visible progress for the current
  project, if indexing was requested.
• Verify before recording success.

QA gate: clean-machine setup is hermetic across mise-present and mise-absent environments on
Linux, macOS, and Windows; a failed install cannot render green or claim ownership; AGENTS.md/
CLAUDE.md are provably untouched unless file injection was explicitly enabled.

Phase 3 — Sync, upgrades, and drift repair

• Fold the package into the managed version/drift story, driven through the owning backend.
• Reconcile per-host MCP wiring after host enable/disable changes.
• Repair stale indexes only for projects Agentic Kit was asked to manage.
• Add Dashboard card/banner integration from the same facts.

QA gate: two consecutive syncs cause zero additional writes or process mutations across every
install method; status, JSON, Dashboard, and plan agree.

Phase 4 — Safe removal and data purge

• Add owned MCP-wiring teardown via GitNexus's own uninstall command.
• Add explicit package removal through the owning backend.
• Add separately confirmed per-project index-data purge.
• Preserve externally-owned installs/indexes and any user-authored AGENTS.md/CLAUDE.md content.
• Retain receipts on partial failure.

QA gate: install → user drift (e.g. user runs analyze --embeddings manually) → uninstall
preserves the drift; uninstall on a never-managed machine creates or removes nothing.

Phase 5 — Documentation and proof

• Update README, SETUP, MANAGED-TOOLS, UPGRADING, TROUBLESHOOTING, and uninstall help.
• Document the install-method classifier as reusable infrastructure for future non-npm-global
  companions.
• Add focused verification and full regression evidence.

QA gate: pnpm run check passes and the packed CLI proves setup/status/sync/uninstall under
redirected HOME/XDG/npm roots and a mise-managed PATH fixture.

Test strategy

Adapter conformance

Same shared lifecycle harness #114 requires: read-only detection, deterministic planning,
non-mutating dry-run, idempotent apply, observed-truth verify, ownership-scoped undo, honest
degradation on malformed/unavailable surfaces.

Install-method matrix

Install state	Expected
absent	opt-in setup installs via the detected/preferred backend
mise npm backend, Agentic Kit-owned	managed and upgradeable via mise upgrade npm:gitnexus
npm-global, Agentic Kit-owned	managed and upgradeable via npm install -g gitnexus@latest
pnpm-global, Agentic Kit-owned	managed and upgradeable via pnpm update -g gitnexus
mise npm backend, pre-existing (unowned)	usable but unowned until explicitly adopted
Docker-only (no CLI on PATH)	external, MCP/host wiring management disabled
owned install, native binding missing	degraded, remediation text surfaced, never reported healthy
owned install, old version	sync upgrades via the owning backend, then verifies
failed upgrade, old artifact still usable	degraded + usable, never green

Host matrix

• Claude MCP wiring add/remove.
• Codex MCP wiring add/remove.
• OpenCode MCP wiring add/remove.
• Enabled-but-absent host produces no GitNexus config for that host.
• Host disabled after prior ownership removes only its owned GitNexus MCP entry, not entries for
  editors Agentic Kit never wired (Cursor, Antigravity, etc., if the user set those up manually with
  the bare CLI).

File-injection and data tests

• default analyze invocation from ak setup/ak sync never mutates AGENTS.md/CLAUDE.md or writes
  under .claude/skills/gitnexus/ unless file injection was explicitly opted into;
• no indexed symbol names, file contents, or query results reach status/JSON/Dashboard;
• purge refuses broad/unresolved paths and never touches source files;
• default uninstall preserves .gitnexus/ index data and ~/.gitnexus/registry.json entries for
  projects not explicitly included in a purge;
• failure messages are bounded and path/content-safe.

Acceptance criteria

• GitNexus is represented as an optional managed companion providing a structural code index,
  distinct from Ruflo/AgentDB and from deja-vu (feat: manage deja-vu as an optional cross-host session-memory companion #114).
• Existing configurations migrate additively to disabled/unowned GitNexus intent.
• Setup offers an explicit opt-in, defaults file injection to off, and discloses the
  PolyForm Noncommercial 1.0.0 license before install.
• Agentic Kit detects mise npm-backend, npm-global, and pnpm-global installs distinctly, and
  drives updates only through the backend that owns the artifact.
• External/Docker-only installs remain visible but unowned.
• Only enabled/present Agentic Kit hosts are wired, never GitNexus's full supported-editor set.
• ak status and JSON distinguish presence, install method, ownership, version drift,
  native-binding health, MCP wiring health, and per-project index health.
• ak sync --dry-run is non-mutating across every install method.
• Repeated ak sync is idempotent and produces no duplicate MCP entries or repeated re-analysis.
• Default index builds never mutate AGENTS.md/CLAUDE.md or write skill files unless the user
  separately opted into GitNexus's file injection.
• Verification observes host config, doctor/status/check facts, and native-binding state
  independently of apply.
• Default uninstall removes Agentic Kit-owned MCP wiring but preserves index data and any
  user-authored AGENTS.md/CLAUDE.md content.
• --remove-gitnexus removes only an Agentic Kit-owned package, via its owning backend, after
  confirmation.
• Data purge is separate, confirmed, exact-path guarded, and cannot delete source files.
• Partial teardown retains ownership receipts and returns nonzero.
• No indexed code content, query strings, or credentials appear in status, logs, receipts, or
  Dashboard output.
• Shared lifecycle conformance, clean-machine, cross-platform (including a mise-managed PATH
  fixture), migration, drift, and no-clobber tests pass.
• pnpm run check passes.

Success measures

1. A new opt-in installation reaches healthy verified state through one ak setup run, regardless
   of whether the user's package manager of choice is mise, npm, or pnpm.
2. A second setup/sync performs zero writes when nothing changed.
3. Claude and Codex can share one project's GitNexus index without duplicate MCP wiring or
   GitNexus's file-injection touching files the user didn't opt into.
4. Package upgrade plus wiring verification converges in one sync, through the correct backend, for
   every supported install method.
5. Uninstall leaves unrelated host configuration and AGENTS.md/CLAUDE.md content byte-equivalent,
   and preserves index data by default.
6. All degraded conditions (missing native binding, stale index, unowned backend) retain enough
   evidence for a specific remediation rather than a generic reinstall.
7. Ruflo/AgentDB and deja-vu's authority boundaries remain undisturbed; no raw code content is
   mirrored into either.

Risks and mitigations

Risk	Mitigation
Install-method assumptions (npm-global only) silently fail for mise users	Dedicated classifier (see Proposed architecture); explicit fixture coverage per method
Two update owners for one artifact (Agentic Kit + mise, or Agentic Kit + npm)	Ownership receipt records the exact backend; ak sync only ever drives that backend
AGENTS.md/CLAUDE.md drift from GitNexus's own file injection (a failure mode this repo has already hit once, from a different tool)	Default --skip-agents-md --skip-skills; file injection is a distinct, explicit opt-in
PolyForm Noncommercial 1.0.0 surprising a commercial user	Explicit pre-install disclosure; documented in README/MANAGED-TOOLS
Native binding (lbugjs.node) silently missing, package still reports "installed"	doctor-derived native-binding check, same shape as src/lib/natives.mjs; degraded, not healthy
No --json mode for doctor/status yet (only check has one)	Versioned text-parser with fixture coverage; file an upstream feature request; treat unparseable output as unknown/degraded, not healthy
Duplicate/competing MCP wiring if the user already ran gitnexus setup manually for editors Agentic Kit doesn't manage	Detect existing wiring before writing; only touch entries for Agentic Kit's own enabled hosts; never blanket-run GitNexus's unscoped setup
Expensive re-indexing on large repos	analyze only for projects explicitly enabled; stale-only repair, not proactive re-analysis
Upstream is high-velocity (multiple RC releases per day)	Track the npm latest dist-tag, not GitHub release tags, for drift comparison; document that pre-release tags are out of scope
Docker-only or non-CLI installs give false "absent" reads	Classifier reports external/unknown rather than asserting absence when a Docker image is detected but no CLI resolves

Definition of done

This issue is complete when an opted-in user can install (via the correct backend for their
environment — mise, npm, or pnpm), configure, verify, update, repair, and safely remove GitNexus
through Agentic Kit; all operations obey the shared lifecycle and ownership contracts; file injection
into AGENTS.md/CLAUDE.md stays off by default; the PolyForm Noncommercial license is disclosed before
install; external installations, index data, and user-authored context files are preserved; and
Ruflo/AgentDB, deja-vu (#114), and GitNexus have clearly documented, non-overlapping authority
boundaries.

[pacphi]

Related: #116 extracts the install-method classifier this issue's non-goals deferred ("generalizing it into a public 'mise-aware package manager' abstraction is a separate, larger refactor and out of scope here") into a reusable, mise-backend-agnostic module.

Not a hard dependency in either direction — this issue's Phase 1 can still ship a GitNexus-narrow classifier on its own schedule, with #116's shared module swapped in later via a small follow-up diff (see #116's Phase 3).

[pacphi]

Related: #117 proposes managing Graphify as a second local knowledge-graph companion. It overlaps with this issue's scope (both build a queryable graph of the repo) and includes an explicit "Relationship to #115" comparison — worth reading together before either lands, since a maintainer decision on whether both, either, or neither ships is still open.