Skip to content

feat: manage Graphify as an optional multi-modal knowledge-graph companion #117

Open
Open
feat: manage Graphify as an optional multi-modal knowledge-graph companion#117
Labels
enhancementNew feature or request

Description

@pacphi
pacphi
opened on Aug 5, 2026

Executive brief

Add first-class, opt-in management of Graphify as a
per-repository knowledge-graph companion, following the same shape as
#115 (GitNexus) and reusing
#116 (mise-backend classifier) where it applies.

Graphify parses a corpus — code, docs, SQL schemas, configs, PDFs, images, and audio/video — into a
local knowledge graph (graph.json) with a token-efficiency pitch (the project claims up to 71.5x
fewer tokens per query on mixed corpora vs. reading raw files) and exposes it via an MCP stdio
server plus a /graphify skill installed across a very wide set of AI coding agents. It is Apache-2.0
licensed, actively maintained (102k★, pushed same day as this draft), and installs via Python
packaging (pip/pipx/uv tool) rather than npm — a genuinely new install ecosystem for Agentic
Kit, not just a new mise backend.

This proposal surfaces one finding sharp enough to be load-bearing for the whole design: Graphify's
own installer writes "always-on" instruction blocks directly into CLAUDE.md, AGENTS.md, and
GEMINI.md via a marker-delimited section it owns (_replace_or_append_section /
_remove_marker_section, boundary ## ) — and Agentic Kit already owns and manages
sentinel-marked sections of those exact files (<!-- BEGIN <slug> --> … <!-- END <slug> -->,
src/lib/blocks.mjs, confirmed live via ak status's blocks row: "CLAUDE.md managed blocks in
sync (9 in registry)"). Two independent section-owners writing to the same physical files with
different marker syntax is not a hypothetical risk — it is the exact shape of collision
docs/MANAGED-TOOLS.md's invariants exist to prevent, just at file-section granularity instead of
package-version granularity. This proposal cannot be approved as written from #115's template alone;
it needs an explicit mediation strategy for this before Phase 2.

Relationship to #115 (GitNexus) — read before approving scope

Graphify and GitNexus are both "build a local knowledge graph from this repo, expose it to agents"
companions, and if both land, Agentic Kit would manage two tools with overlapping value
propositions. This proposal does not resolve that question — it names it explicitly so a maintainer
decides deliberately rather than by default:

GitNexus (#115) Graphify (this issue)
Scope Code structure: symbols, call graphs, impact/blast-radius, diff-to-symbol mapping Code + docs + papers + images + audio/video + SQL schemas — broader corpus, shallower per-domain query depth
Cost model Fully local, deterministic parsing (tree-sitter + LadybugDB); no LLM calls, no per-run token cost Pass 1 (code, tree-sitter) and Pass 2 (audio/video, faster-whisper) are free/local; Pass 3 (docs/papers/images) dispatches parallel Claude subagents and costs tokens on every build that touches non-code files
Query surface Purpose-built MCP tools (query, context, impact, trace, cypher, detect-changes) plus raw Cypher graph.json + MCP stdio server + generated Obsidian vault / wiki / HTML / GraphML / Neo4j Cypher export
Install ecosystem npm (already the subject of #115/#116) Python (pip/pipx/uv tool) — new ecosystem for Agentic Kit
Host file injection AGENTS.md/CLAUDE.md tagged block (off by default per #115's design), .claude/skills/gitnexus/ CLAUDE.md/AGENTS.md/GEMINI.md/VS Code Copilot instructions/Antigravity rules/Kiro steering "always-on" blocks, plus per-host SKILL.md under 15+ platform-specific directories
License PolyForm Noncommercial 1.0.0 Apache-2.0 (relicensed from MIT; both texts retained in-repo)
Auto-update mechanism None. A PostToolUse Claude Code hook does a cheap git rev-parse HEAD check after git-mutating tool calls and injects a text nudge ("index is stale, run gitnexus analyze") — it never rebuilds on its own, and the nudge only fires inside a live agent session Opt-in, and free where it applies. graphify hook install (git post-commit/post-checkout, detached background process) or --watch (real-time, 3s debounce) auto-rebuild code changes via _rebuild_code — pure AST extraction, zero LLM cost. Non-code changes still only flag + nudge (/graphify --update required) — the costly Pass 3 is never auto-triggered by either mechanism

A reasonable disposition once both are read together: GitNexus is the cheaper, always-safe default
for "code structure" questions; Graphify is the opt-in choice specifically when a user's corpus
genuinely spans docs/papers/images/audio and the token-cost tradeoff is acceptable. Nothing in this
proposal requires picking one over the other, but Setup should not silently let a user enable both
and pay to build two overlapping graphs of the same code without understanding why.

On freshness specifically: Graphify's opt-in git-hook/--watch auto-rebuild is a strict upgrade over
GitNexus's nudge-only model for the code-structure portion both tools cover — it costs nothing (code
extraction is local/free either way), requires no agent to notice and act on a nudge, and — unlike
GitNexus's hook, which only fires from a live agent tool call — it also catches changes made with no
agent session running at all (a teammate's commit, a manual git pull + checkout). GitNexus's
advantage is architectural minimalism: nothing to opt into, no background process or git-hook side
effects to reason about across worktrees. Since Graphify's auto-path is free and off by default, this
is not a hard tradeoff — Goal/Non-goals below keep it opt-in-only on "don't install background
processes a user didn't ask for" grounds, not cost-risk grounds, and note it as a freshness upgrade
worth surfacing once a user opts into Graphify at all.

Why this belongs in Agentic Kit

Graphify's upstream CLI already provides the same shape of managed-companion primitives #115 and
#114 established as the pattern:

  • a published PyPI package, graphifyy (note: package name ≠ binary name — the installed CLI is
    invoked as graphify, a real trap for any naive "does pip show <binary-name> exist" detection);
  • graphify install/uninstall (and per-host functions: claude_uninstall, codex via
    _uninstall_codex_hook, opencode via _uninstall_opencode_plugin, plus gemini/cursor/vscode/
    antigravity/kiro/devin/kilo/amp/codebuddy/agents-generic — an even larger host matrix than
    GitNexus's) with a top-level uninstall_all(project_dir, purge=False) — the same "purge" vocabulary
    Agentic Kit already uses;
  • diagnostics.py with a format_diagnostic_json function (JSON-capable health/diagnostic
    summary — whether this is exposed via a documented CLI flag needs confirming in Phase 0, same
    open-question shape feat: manage GitNexus as an optional local code-intelligence companion #115 flagged for GitNexus's doctor --json);
  • documented security mitigations (SECURITY.md): stdio-only MCP (no network listener), SSRF
    protection and a 50MB stream-abort on the one command that does fetch URLs (ingest), path-traversal
    and XSS/label-sanitization protections, no shell=True subprocess usage, no telemetry;
  • a SHA256-based cache (graphify-out/cache/) so re-runs skip unchanged files, and a --watch mode
    and graphify hook install (git post-commit) for continuous re-indexing.

Upstream references:

  • Repository (Apache-2.0; org created 2026-06-28 after
    transfer from the original author's personal account, safishamsi/graphify — same project,
    confirmed via GitHub's repo-rename redirect, not a fork or hijack)
  • SECURITY.md, ARCHITECTURE.md, docs/how-it-works.md (three-pass pipeline, confidence tagging,
    Leiden community detection)
  • PyPI: graphifyy (201 releases as of this draft; license_expression: Apache-2.0)

Current Agentic Kit architecture

The same seams #114/#115/#116 identified apply, plus one this proposal adds:

Goals

  1. Let users opt into Graphify during setup or through an explicit command/config change, scoped per
    project like feat: manage GitNexus as an optional local code-intelligence companion #115's GitNexus indexing.
  2. Detect Python install method honestly. Support pip (global/user site-packages), pipx
    (isolated venv — the upstream-recommended path on externally-managed macOS Pythons), uv tool
    (the reinstall remediation the upstream installer itself prints), and a mise pipx:-backend
    install (delegate to feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116's mise ls --json classifier for the mise case; add fresh detection
    for the three non-mise cases, since none exist today).
  3. Mediate the block-injection collision before any Graphify install runs. At minimum: detect
    whether Graphify's always-on blocks are already present in a guidance file Agentic Kit also
    manages, surface both systems' markers in status, and never let ak sync silently interleave
    Agentic Kit's <!-- BEGIN/END --> sentinels with Graphify's ## -boundary sections in a way that
    makes either system's parser miscount or corrupt the file. See "Proposed architecture" for the
    candidate strategies this issue needs a maintainer decision on.
  4. Wire only Agentic Kit's own enabled hosts (Claude, Codex, OpenCode) — never Graphify's full
    15+-platform skill matrix, mirroring feat: manage GitNexus as an optional local code-intelligence companion #115's Goal 4.
  5. Disclose, before every graph build that would touch non-code files, that Pass 3 dispatches Claude
    subagents and costs tokens — this is a recurring per-run cost, not a one-time install cost like
    GitNexus's native binary or deja-vu's index.
  6. Build/refresh the index for the current project on request, surface progress, and verify via
    Graphify's diagnostics output without exposing indexed content (code, doc excerpts, transcript
    text) in status/logs/Dashboard.
  7. Surface presence, install method (pip/pipx/uv-tool/mise-pipx/external), ownership, version drift,
    skill-file wiring health per enabled host, always-on block state, and per-project graph health in
    ak status.
  8. Make ak sync converge the package (via its owning method), host skill wiring, and stale graphs
    without duplicate entries, duplicate always-on blocks, or repeated full rebuilds (respect the
    SHA256 cache — never force --mode deep or full re-extraction by default).
  9. Remove only Agentic Kit-owned wiring, skill files, always-on block contributions, and package;
    preserve external installs, user-authored guidance-file content, and any graph the user built
    directly with the CLI.
  10. Disclose Graphify's license (Apache-2.0 — permissive, materially simpler than GitNexus's
    PolyForm Noncommercial 1.0.0) as part of setup, for consistency with feat: manage GitNexus as an optional local code-intelligence companion #115's disclosure pattern
    even though there is no commercial-use restriction here.
  11. Keep the integration testable and aligned with Agentic Kit's trust boundary; do not add a
    runtime dependency to Agentic Kit's own zero-dependency package.

Non-goals

  • Resolving the GitNexus/Graphify overlap question. This proposal names it (see "Relationship to
    feat: manage GitNexus as an optional local code-intelligence companion #115") but does not decide it. A maintainer call on whether both, either, or neither ships as a
    default-recommended companion is a separate, smaller decision this issue's Phase 0 should force,
    not something this issue's author should presume.
  • Wiring Graphify's full host matrix. Gemini CLI, Cursor, VS Code Copilot, Antigravity, Kiro,
    Devin, Kilo, Amp, CodeBuddy, Trae, Hermes, Pi, Aider, OpenClaw, Factory Droid, and the generic
    Agent-Skills target are all upstream-supported; only Claude, Codex, and OpenCode are in scope,
    matching Agentic Kit's own host registry.
  • Enabling --google-workspace (requires an authenticated external gws CLI) or any other
    optional external-service integration by default.
  • Building a general "Python package install-method classifier" as its own extracted module in
    this issue    , the way feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116 did for mise/npm. Detect what Graphify itself needs (pip/pipx/uv-tool/
    mise-pipx); a feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116-style general Python-ecosystem extraction is a future issue if a second Python
    companion ever needs it — building it speculatively now would repeat the mistake feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116's own
    non-goals warned against (generalizing before a second evidenced consumer exists).
  • Adopting, updating, or deleting an externally-installed Graphify (Homebrew-adjacent, manual
    clone, or a uv tool/pipx install the user set up before enabling Agentic Kit management).
  • Running --watch mode or the graphify hook install git post-commit/post-checkout hooks as
    part of default management. Correction after reading graphify/watch.py: both mechanisms are
    cost-safe by design — they auto-rebuild only the free, local code pass (_rebuild_code, pure AST
    extraction) and merely write a needs_update flag plus a nudge for non-code changes, never
    auto-dispatching Pass 3. So this is not a cost-risk non-goal; it stays opt-in-only because
    Agentic Kit does not install background processes or git hooks a user did not explicitly request,
    the same principle that already governs deja-vu's (feat: manage deja-vu as an optional cross-host session-memory companion #114) auto-recall opt-in and GitNexus's (feat: manage GitNexus as an optional local code-intelligence companion #115)
    default-off file injection. Once opted into, this is a strict freshness upgrade over GitNexus,
    which has no auto-rebuild mechanism at all (see the auto-update row in "Relationship to feat: manage GitNexus as an optional local code-intelligence companion #115"
    above).
  • Enabling semantic exports (--neo4j, --graphml, --svg) or the Obsidian/wiki output by
    default — these are presentation formats a user requests explicitly, not part of baseline index
    management.
  • Resolving Graphify's own always-on block content itself. This proposal's job is to decide
    whether and how Agentic Kit lets that injection happen safely, not to audit or rewrite
    Graphify's own instruction text.

Primary use cases

1. Multi-modal onboarding to an unfamiliar corpus

A user opts in on a repo whose knowledge lives partly in PDFs, design docs, and recorded
walkthroughs, not just code. ak setup --with-graphify installs it via the detected/allowed Python
backend, wires the enabled hosts' skill files, and runs one build with progress output and an
explicit token-cost disclosure before Pass 3 starts.

2. Cross-format semantic query

An agent asks "what does this SQL schema have to do with the onboarding doc," a question GitNexus's
code-only graph cannot answer. Graphify's semantically_similar_to edges (Claude-extracted) connect
a code file to a paper to a schema.

3. Cost-aware rebuild after edits

The repo changed since the last build. ak status reports the graph as stale; ak sync re-runs
Graphify's incremental (--update, SHA256-cached) mode, not a full rebuild, and still discloses that
any newly-touched non-code file goes through Pass 3.

4. Always-on block collision caught, not silently corrupted

A user who already ran Graphify's own installer manually has always-on blocks in CLAUDE.md.
ak status detects both marker systems present in the same file and reports a warn/degraded
state with a specific remediation, instead of ak sync writing a new Agentic Kit block adjacent to
(or inside) Graphify's marker-delimited section and corrupting either parser's section boundaries.

5. External installation

Graphify is already installed via uv tool or pipx outside Agentic Kit's management. Agentic Kit
detects and reports what it finds but does not adopt, update, or uninstall it without an explicit
ownership transition — the same stance #114 and #115 take.

6. Clean removal

ak uninstall removes only Agentic Kit-owned skill wiring and always-on block contributions (if any
were ever added under Agentic Kit ownership) for the enabled hosts. A separate flag removes the
owned package via its owning method. A separate, confirmed flag removes per-project graphify-out/
data; source files and any pre-existing user content in guidance files are left untouched.

Product principles

  1. Two block-owners on one file is a defect waiting to happen, not a coexistence problem to
    shrug at.     This is the single principle this proposal adds beyond feat: manage deja-vu as an optional cross-host session-memory companion #114/feat: manage GitNexus as an optional local code-intelligence companion #115's list, and it
    governs everything else: no phase of implementation may write an Agentic Kit-owned block into a
    file with active Graphify markers (or vice versa, where Agentic Kit has taken ownership) without
    an explicit mediation strategy proven safe by test.
  2. Corpus, not memory. Graphify indexes a broad multi-modal corpus; it must not be modeled as a
    Ruflo/AgentDB replacement, a deja-vu replacement, or (silently) a GitNexus replacement.
  3. Cost disclosure is not optional. Any operation that would dispatch Claude subagents (Pass 3)
    is disclosed before it runs, every time, the way feat: manage deja-vu as an optional cross-host session-memory companion #114 disclosed transcript reads.
  4. Install-method truth over install-method assumption, extended to a new ecosystem: pip, pipx,
    uv tool, and mise's pipx: backend are distinct, and ownership/update mechanics must match
    whichever actually owns the artifact — the same principle feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116 established for npm/mise, applied
    fresh to Python.
  5. Host intent controls wiring. Enabled Agentic Kit hosts determine eligible Graphify skill
    targets, never Graphify's full platform list.
  6. Presence is not ownership. An externally-installed Graphify, or always-on blocks a user added
    by running the upstream installer directly, remain externally owned until an explicit transition.
  7. Observed truth drives status. Parse Graphify's diagnostics output, resolved binary path, and
    guidance-file marker state directly; never infer healthy from exit code alone.
  8. Unknown stays unknown. An unparseable diagnostics shape, an ambiguous block-ownership state,
    or an unresolvable install method is degraded/unknown, not healthy or absent.

Proposed user experience

Setup

ak setup --with-graphify
ak setup --with-graphify --graphify-install-method pipx
ak setup --no-graphify

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

  • Graphify's license (Apache-2.0) and that it dispatches Claude subagents (token cost) for
    docs/papers/images during a build — an ongoing cost, not a one-time install cost;
  • which install method will be used (detected pipx/uv-tool/mise-pipx, or a choice) and that Agentic
    Kit will only update through that method going forward;
  • which enabled hosts will receive skill-file wiring;
  • whether always-on blocks will be written into CLAUDE.md/AGENTS.md/GEMINI.md, and — if the
    target file already carries Agentic Kit-owned sentinel blocks — the specific conflict-avoidance
    behavior that will be used     (see Proposed architecture; this disclosure line cannot be generic,
    it must name the resolved strategy);
  • that --watch, git hooks, semantic exports, and Google Workspace ingestion are not enabled by
    default.

Status

graphify  ok    0.9.33 pipx-managed · skills: claude,codex · graph current
graphify  warn  always-on block conflict: Graphify markers present in CLAUDE.md alongside
                Agentic Kit-owned blocks · see remediation
graphify  warn  installed externally (uv tool, unmanaged) · management disabled
graphify  warn  pip 0.9.30 installed, 0.9.33 available · sync upgrades it
graphify  warn  graph stale for this project (12 files changed since last build)
graphify  info  management disabled

The collector should distinguish presence, install method (pip/pipx/uv-tool/mise-pipx/external),
ownership, version drift compared in the correct namespace (PyPI, not npm), per-host skill wiring
health, always-on block ownership/conflict state, and per-project graph health (absent/stale/
damaged/current). Status and Dashboard output must never include graph node labels, source excerpts,
transcript text, or query results.

Sync

ak sync should:

  1. install Graphify only when enabled and absent, through the resolved Python install method;
  2. upgrade only an Agentic Kit-owned install, through that same method — never mix pip, pipx,
    uv tool, and mise's pipx: backend for one artifact;
  3. reconcile skill-file wiring for enabled hosts only;
  4. apply the resolved always-on-block mediation strategy — reconciling, never blindly overwriting;
  5. re-run graphify --update (incremental) only for projects with a stale graph the user opted into,
    never a full --mode deep rebuild proactively;
  6. verify independently via Graphify's diagnostics output and guidance-file marker inspection;
  7. 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 Graphify skill wiring + owned blocks
ak uninstall --remove-graphify        # also remove the owned package, via its owning method
ak uninstall --purge-graphify-data    # also delete graphify-out/ for owned projects, confirmed
ak uninstall --purge                  # include owned package; preserve graph data unless requested

Rules mirror #115: run Graphify's own per-host uninstall functions only for Agentic Kit-owned
targets; remove the package only through the method the ownership receipt names; preserve
graphify-out/ and any pre-existing guidance-file content by default; a data purge resolves exact
paths, previews them, and requires confirmation.

Configuration and ownership model

{
  "integrations": {
    "version": 3,
    "tools": {
      "graphify": {
        "enabled": true,
        "hosts": ["claude", "codex"],
        "indexOnSetup": true,
        "alwaysOnBlocks": false
      }
    },
    "ownership": {
      "graphify": {
        "install": {
          "method": "pipx",
          "package": "graphifyy",
          "managedBy": "agentic-kit"
        },
        "targets": { "claude": "claude", "codex": "codex" },
        "blockOwnership": { "claude.md": "coexisting" },
        "indexedProjects": ["/abs/path/to/project-a"]
      }
    }
  }
}

blockOwnership is the new field this proposal adds beyond #115's schema: it records, per guidance
file, which mediation state applies (e.g. none / agentic-kit-only / graphify-only /
coexisting / conflict) so status and sync can react without re-parsing the file from scratch
every time.

Proposed architecture

Python install-method detection

New, narrow detection (not a #116-style generalized module, per Non-goals): resolve graphify on
PATH, then classify:

Version comparison uses PyPI's namespace (pip index versions graphifyy or the PyPI JSON API), never
npm's — a fresh instance of the "same-namespace comparison" invariant docs/MANAGED-TOOLS.md already
states, just for a package manager Agentic Kit hasn't spoken to before.

Always-on block mediation (the decision this issue cannot skip)

Three candidate strategies, to be decided in Phase 0 with a maintainer, not assumed by this issue:

  1. Never let Agentic Kit enable alwaysOnBlocks for Graphify at all (default false, shown in
    the config model above). Graphify's skill file alone (installed under its own per-host directory)
    still works without the always-on block; the block is an upstream optimization, not a hard
    requirement. This is the lowest-risk starting point and the recommended Phase 2 default.
  2. If a user explicitly opts in, detect Agentic Kit's own sentinel blocks and Graphify's
    marker-delimited sections in the same file before either system writes, and refuse to mutate
    with a specific error if both would claim overlapping byte ranges, rather than attempting a
    speculative merge.
  3. Longer-term, propose (in a separate follow-up, not this issue) that Agentic Kit's own
    blocks.mjs registry become the place third-party managed companions declare guidance-file
    content, so there is exactly one writer per file regardless of how many companions want a
    presence in it — analogous to how feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116 makes Agentic Kit the single reader of mise's backend
    truth instead of guessing. Out of scope to build here; scoped only as a named direction so Phase 0
    doesn't have to invent it from nothing.

Managed companion adapter

Phased implementation plan

Phase 0 — ADR, block-mediation decision, and GitNexus-relationship call

  • Add a focused ADR (or amend ADR-0016) defining Graphify's role, explicitly resolving the
    "Relationship to feat: manage GitNexus as an optional local code-intelligence companion #115" question (both supported? one recommended? user's free choice with a
    disclosed tradeoff?) and the always-on block mediation strategy from the three candidates above.
  • Read ARCHITECTURE.md and the full docs/how-it-works.md in detail before implementation.
  • Decide the license-disclosure copy (Apache-2.0 is simple, but still stated) and the token-cost
    disclosure copy for Pass 3.

QA gate: ADR is current, names a specific block-mediation strategy (not "TBD"), and states
Graphify's relationship to #115 rather than leaving it implicit.

Phase 1 — Detection and normalized facts

  • Build Python install-method detection (pip/pipx/uv-tool) plus delegation to feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116 for the
    mise-pipx: case.
  • Parse Graphify's diagnostics output against fixtures; confirm whether format_diagnostic_json is
    CLI-exposed and document the finding either way.
  • Add guidance-file marker inspection: detect Agentic Kit's own blocks, detect Graphify's
    marker-delimited sections, and classify the blockOwnership state per file.
  • Keep collection read-only.

QA gate: all install-method and block-ownership-state classifications are fixture-covered,
including the conflict case (both marker systems present, overlapping); a case that doesn't match a
known shape returns external/unknown.

Phase 2 — Setup and installation (always-on blocks OFF by default)

  • Add setup flags and persisted opt-in intent, with alwaysOnBlocks: false as the shipped default
    per the Phase 0 decision.
  • Add pre-mutation disclosure covering license, install method, host wiring, and per-run token cost.
  • Install through the resolved method; wire only enabled hosts' skill files.
  • Run one build with visible progress and an explicit Pass-3 cost note before it starts, if
    non-code files are present.

QA gate: clean-machine setup is hermetic across pip/pipx/uv-tool/mise-pipx fixtures on Linux,
macOS, and Windows; guidance files are provably byte-unchanged unless a user explicitly enabled
always-on blocks and the Phase 0 mediation strategy was applied without corrupting existing content.

Phase 3 — Sync, upgrades, and drift repair

  • Fold the package into the managed version/drift story, driven through the resolved method.
  • Reconcile per-host skill wiring after host enable/disable changes.
  • Repair stale graphs (incremental, never a proactive full rebuild) only for opted-in projects.

QA gate: two consecutive syncs cause zero additional writes, zero additional token spend, and
zero duplicate blocks/skill files.

Phase 4 — Safe removal and data purge

  • Add owned skill-wiring and (if ever enabled) always-on-block teardown via the mediation strategy's
    reverse.
  • Add explicit package removal through the owning method.
  • Add separately confirmed per-project graphify-out/ purge.

QA gate: install → user drift (manual always-on block edit, manual --neo4j export) → 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, including an
    explicit "Graphify vs. GitNexus" note pointing at this issue's relationship table.
  • pnpm run check passes; packed CLI proves setup/status/sync/uninstall under redirected HOME/XDG
    and each Python install-method fixture.

Test strategy

Install-method matrix

Install state Expected
absent opt-in setup installs via the resolved method
pipx, Agentic Kit-owned managed and upgradeable via pipx upgrade graphifyy
uv tool, Agentic Kit-owned managed and upgradeable via uv tool upgrade graphifyy
plain pip, Agentic Kit-owned managed and upgradeable via pip install -U graphifyy (only where not externally-managed-environment blocked)
mise pipx: backend detected via #116's classifier; updatable per #116's existing npm-only scope — not updatable by this issue unless #116's scope is separately revisited
externally installed (any method, unowned) visible, never adopted/updated

Block-mediation matrix

Guidance-file state Expected
no blocks from either system alwaysOnBlocks stays off; no write unless explicitly opted in
Agentic Kit blocks only Graphify install proceeds with alwaysOnBlocks: false; no conflict
Graphify blocks only (user ran upstream installer directly) detected as graphify-only; Agentic Kit's own future block writes to that file must not corrupt Graphify's section
both present, non-overlapping coexisting; both preserved
both present, overlapping byte range conflict; sync refuses to mutate and reports a specific remediation

Cost and privacy tests

  • no graph node labels, source excerpts, transcript text, or query strings reach status/JSON/
    Dashboard;
  • Pass-3 cost disclosure appears before any build that would touch non-code files, every time;
  • --watch, git hooks, and Google Workspace ingestion are never enabled by default;
  • purge refuses broad/unresolved paths and never touches source files.

Acceptance criteria

  • Graphify is represented as an optional managed companion; its relationship to feat: manage GitNexus as an optional local code-intelligence companion #115 (GitNexus)
    is explicitly documented, not left implicit.
  • Setup offers an explicit opt-in, discloses license + per-run token cost, and ships
    alwaysOnBlocks: false as the default.
  • Python install-method detection (pip/pipx/uv-tool) exists and correctly delegates the
    mise-pipx: case to feat: reusable mise-backend-aware install-method classifier for managed/companion tools #116's classifier rather than duplicating it.
  • No write ever produces overlapping/corrupted marker sections between Agentic Kit's own
    blocks.mjs sentinels and Graphify's marker-delimited sections in the same file — proven by
    the block-mediation test matrix above.
  • Only enabled/present Agentic Kit hosts are wired, never Graphify's full platform list.
  • ak status and JSON distinguish presence, install method, ownership, version drift (PyPI
    namespace), skill-wiring health, always-on block ownership/conflict state, and per-project
    graph health.
  • ak sync --dry-run is non-mutating; repeated ak sync is idempotent and never triggers
    unplanned Pass-3 token spend.
  • Default uninstall removes Agentic Kit-owned wiring and (if ever enabled) owned block
    contributions, but preserves graphify-out/ data and pre-existing guidance-file content.
  • No indexed content, transcript text, or credentials appear in status, logs, receipts, or
    Dashboard output.
  • pnpm run check passes.

Success measures

  1. A new opt-in installation reaches healthy verified state through one ak setup run, regardless
    of pip/pipx/uv-tool/mise-pipx.
  2. A second setup/sync performs zero writes and zero additional token spend when nothing changed.
  3. No guidance file is ever left with corrupted or ambiguous section boundaries as a result of
    Agentic Kit's involvement, whether or not always-on blocks were ever enabled.
  4. A user can read this issue's relationship table and make an informed choice about GitNexus vs.
    Graphify vs. both, rather than discovering the overlap after paying to build two graphs.
  5. Uninstall leaves unrelated host configuration and guidance-file content byte-equivalent, and
    preserves graph data by default.

Risks and mitigations

Risk Mitigation
Two block-owners corrupt CLAUDE.md/AGENTS.md Phase 0 names a specific mediation strategy before any code ships; alwaysOnBlocks defaults off; conflict state refuses to mutate
Unbounded token spend from Pass 3 on large/mixed corpora explicit cost disclosure before every build touching non-code files; incremental-only sync, never proactive full rebuilds
Package-name/binary-name mismatch (graphifyy vs graphify) causing false-absent detection classifier resolves the graphify binary first, then confirms package identity via the resolved install's own metadata, never by string-matching the binary name against a package name
Redundant value with GitNexus (#115), confusing users into running both explicit relationship table in this issue; Phase 0 forces a maintainer decision; setup discloses the overlap if both are enabled
Very broad host skill-footprint (15+ platforms) tempts wiring beyond Agentic Kit's own hosts Goal 4 / Non-goals are explicit; adapter only ever calls per-host functions for hosts Agentic Kit itself enables
Externally-managed Python environments block bare pip install (as upstream's own README already warns for macOS) pipx is the primary recommended path in setup's default suggestion, not bare pip
Upstream is very high open-issue-count (816) relative to project age not a blocker, but Phase 0 should sample recent issue activity for install/uninstall-relevant regressions before committing to specific marker/path assumptions

Definition of done

This issue is complete when an opted-in user can install (via the correct Python method for their
environment), configure, verify, update, repair, and safely remove Graphify through Agentic Kit;
always-on block injection is off by default and, when enabled, never corrupts or silently overwrites
Agentic Kit's own or a user's existing guidance-file content; only enabled hosts receive skill
wiring; every graph build that would cost tokens is disclosed first; external installations and
graph/guidance-file content are preserved; and Graphify's relationship to GitNexus (#115) is
documented clearly enough that a user can choose deliberately rather than by accident.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions