baldart 4.18.0 → 4.21.0

package/framework/docs/CODE-GRAPH-LAYER.md

@@ -0,0 +1,104 @@
+# Code Graph Layer (Graphify) — Operator Guide
+
+> Since v4.21.0. Opt-in, gated on `features.has_code_graph`. The **runtime**
+> protocol (when to use the graph vs LSP vs Grep) lives in
+> [`framework/agents/code-graph-protocol.md`](../agents/code-graph-protocol.md);
+> this document covers the *plumbing* — install, config, lifecycle, fallback.
+
+## 1. Why this exists
+
+After removing the (unused, costly) RAG engine in v4.20.0, BALDART needed a
+retrieval tier for **structural / relational** code questions — "what connects X
+to Y", blast-radius of a change, which modules cluster — that Grep and even LSP
+answer poorly. [Graphify](https://github.com/safishamsi/graphify) builds a code
+knowledge graph (tree-sitter, 28 languages, **local/offline**) with native Leiden
+community detection. The same graph also **re-activates the Karpathy LLM-wiki
+auto-learning loop**: its native `GRAPH_REPORT.md` (god nodes, communities,
+suggested questions) is the gap signal that feeds synthesis candidates.
+
+## 2. What BALDART adds vs what Graphify already ships
+
+Graphify is a complete tool on its own — it installs its **own** skill, an
+always-on pre-tool hook, a post-commit git hook, and an MCP server. BALDART does
+**not** reimplement any of that. It adds only:
+
+- **Gating + config** (`features.has_code_graph` + `graph:` block).
+- **Opt-in install** (`configure` interactive branch, `/graphify-bootstrap`, `doctor` backfill).
+- **A retrieval protocol** telling BALDART's own agents *when* the graph is the right tier.
+- **The wiki rebind** (wiki-curator / capture / `doc-graph-align` consume `GRAPH_REPORT.md`).
+- **Fallback discipline** (silent degrade to LSP→Grep→Git).
+
+Everything mutating is a thin wrapper over Graphify's native commands in
+[`src/utils/graphify-installer.js`](../../src/utils/graphify-installer.js).
+There is **no per-language adapter registry** (unlike LSP) — Graphify is one
+language-agnostic tool.
+
+## 3. The moving parts
+
+| Part | Where | Role |
+|------|-------|------|
+| Config flag + block | `framework/templates/baldart.config.template.yml` | `features.has_code_graph` + `graph.{output_dir,auto_rebuild_hook,register_mcp}` |
+| Installer wrapper | `src/utils/graphify-installer.js` | `detect/install/verify/buildGraph/installGitHook/installAlwaysOn/registerMcp/isStale` |
+| Configure | `src/commands/configure.js` | autodetect (binary on PATH) + prompt + interactive install/build/wire |
+| Update detector | `src/commands/update.js` | diffs the `graph:` block → offers `configure` (extended to diff nested top-level blocks) |
+| Doctor | `src/commands/doctor.js` | `Code graph` line + `graph-install` / `graph-rebuild` / `graph-hook` actions |
+| Retrieval protocol | `framework/agents/code-graph-protocol.md` | when to use the graph; budget; fallback |
+| Wiki rebind | `llm-wiki-methodology.md`, `wiki-curator.md`, `wiki-review.routine.yml`, `capture` | GRAPH_REPORT.md → synthesis candidates |
+| Nightly command | agent `doc-graph-aligner` + routine `doc-graph-align` + skill `/graph-align` | doc↔graph alignment |
+| Bootstrap skill | `/graphify-bootstrap` | explicit install path (CI-safe backfill) |
+
+## 4. Install lifecycle
+
+```
+features.has_code_graph: true
+        │
+        ├─ baldart configure (INTERACTIVE) ─→ pipx install graphifyy
+        │      → graphify update .          (build, offline)
+        │      → graphify <tool> install    (always-on per tools.enabled)
+        │      → graphify hook install       (auto-rebuild, if auto_rebuild_hook)
+        │      → claude mcp add … graphify-mcp (if register_mcp)
+        │
+        ├─ baldart configure --yes / CI ──→ writes the flag ONLY (no silent
+        │      Python install) → doctor backfills
+        │
+        ├─ /graphify-bootstrap ───────────→ the explicit, full install path
+        │
+        └─ baldart doctor ────────────────→ graph-install (binary missing)
+               graph-rebuild (stale: built_at_commit ≠ HEAD) · graph-hook (hook missing)
+```
+
+**CI behavior is deliberate**: a Python tool is never installed silently in
+`--yes`/non-interactive runs. The flag is written from autodetect; `doctor` and
+`/graphify-bootstrap` own the actual install.
+
+## 5. Native commands BALDART relies on (all offline, 0 API cost)
+
+| Purpose | Command |
+|---------|---------|
+| Build / refresh graph | `graphify update <root>` → `<root>/graphify-out/{graph.json, GRAPH_REPORT.md, graph.html}` |
+| Auto-rebuild on commit | `graphify hook install` (post-commit + graph.json union merge-driver) |
+| Always-on per tool | `graphify claude install` / `graphify codex install` / … |
+| Query (relational) | `graphify query "…"`, `graphify path "A" "B"`, `graphify explain "X"`, `graphify affected "X"` |
+| MCP server | `graphify-mcp [graph.json]` (stdio default; `--transport http` available) |
+| Staleness (cron-safe) | `graphify check-update <root>`, or compare `graph.json.built_at_commit` to `git rev-parse HEAD` |
+
+LLM API keys are needed **only** for `--wiki` / community naming (`graphify label`)
+/ URL & vision ingestion — all optional. The structural graph + report are free.
+
+## 6. Invariants
+
+- **The graph is never canonical.** Synthesis candidates it produces cite repo
+  SSOT and carry `canonicality: derived`.
+- **Silent fallback.** No task aborts because the graph is missing — degrade to
+  LSP→Grep→Git; surface setup gaps via `baldart doctor`, never mid-task.
+- **`graphify-out/` is generated** — must be in `.gitignore`, never versioned.
+- **No per-language registry.** Add nothing per language; Graphify handles 28 via
+  tree-sitter. The wrapper composes native commands, never reimplements them.
+- **Schema-change propagation** applies to `features.has_code_graph` + `graph.*`.
+
+## 7. Adding capability later
+
+The retrieval tier ships CLI-first; the MCP path is opt-in. To deepen the
+integration (e.g. wire `graphify-mcp` as a first-class MCP tool, or use `--wiki`
+community pages directly as wiki concept pages), extend `graphify-installer.js`
+and the protocol module — do not fork Graphify's native behavior.

package/framework/docs/LSP-LAYER.md

@@ -13,7 +13,7 @@ A complete operator + agent reference for the LSP retrieval tier introduced in
 - a contributor wants to add a new language adapter or change the fallback
   rules.
 
-For the *runtime* protocol (RAG → LSP → Grep → Git, query-type
+For the *runtime* protocol (LSP → Grep → Git, query-type
 discrimination, budget) read [`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md).
 This document covers the *plumbing*: how the layer is installed, configured,
 verified, and wired into agents/skills.
@@ -24,7 +24,7 @@ verified, and wired into agents/skills.
 
 Pre-v3.10, every BALDART code-exploration flow ran:
 
-> RAG hybrid → `git log` → **Grep** → read files.
+> canonical-doc routing → `git log` → **Grep** → read files.
 
 Grep collapses semantically distinct symbols that share a name. A search for
 `handleSubmit` in a medium repo dumps every form handler, every CLI utility,
@@ -41,7 +41,7 @@ unrelated `handleSubmit` is filtered out before any file is read.
 The layer is **opt-in** (some consumers don't want a global npm install for a
 language server, some target languages we don't have an adapter for yet) and
 **degrades gracefully** (when
-LSP is unavailable, agents silently fall back to the legacy RAG → Grep flow,
+LSP is unavailable, agents silently fall back to the Grep flow,
 so existing behavior is preserved).
 
 ---
@@ -217,14 +217,14 @@ When `codebase-architect` or one of the code-exploration skills (`bug`,
 `prd`, `new`, `simplify`, `context-primer`) is invoked:
 
 1. Read `baldart.config.yml`. If `features.has_lsp_layer !== true`, behave
-   exactly as v3.9.x (RAG → Grep → Git).
+   as the Grep → Git flow.
 2. Otherwise: classify the query.
    - Identifier-shaped (function name, type name, class, exported symbol) →
      **LSP first** (`ToolSearch("LSP")` → `find-references` / `definition`).
    - Free text / phrase / comment / path / regex → **Grep first**, LSP is
      useless here.
-   - Mixed (e.g. "refactor function X used in 5 places") → RAG hybrid for
-     conceptual context, then LSP for the structural part.
+   - Mixed (e.g. "refactor function X used in 5 places") → Grep to disambiguate
+     the conceptual context, then LSP for the structural part.
 3. Budget: max **3 LSP calls per task**. After 3 calls without convergence,
    escalate to direct file reads — don't ping-pong references.
 4. If LSP tool isn't loaded / plugin missing / timeout > 8s / zero

package/framework/docs/MCP-INTEGRATION.md

@@ -27,8 +27,8 @@ Non è un'imposizione: BALDART non installa MCP, non li valida, non li richiede.
 ### Browser automation
 - **Playwright MCP** (`@modelcontextprotocol/server-playwright`) — usato da [bug](../.claude/skills/bug/SKILL.md) e [webapp-testing](../.claude/skills/webapp-testing/SKILL.md) per cattura visiva, network, console.
 
-### Documentation retrieval (RAG)
-- **doc-rag MCP** (interno o `@modelcontextprotocol/server-everything-search` come stand-in) — usato da [codebase-architect](../.claude/agents/codebase-architect.md) e [code-search-protocol.md](../agents/code-search-protocol.md) per ricerca semantica nei doc + knowledge graph.
+### Code knowledge graph (Graphify)
+- **Graphify** (`pipx install graphifyy` → CLI `graphify` + MCP server `graphify-mcp`) — code knowledge graph (tree-sitter, locale/offline, Leiden nativo). Gatato da `features.has_code_graph`. Usato da [codebase-architect](../.claude/agents/codebase-architect.md) e dalle skill di esplorazione per query **strutturali/relazionali** (`graphify query`/`path`/`explain`/`affected`), e dal layer wiki (`wiki-curator`, `/capture`, routine `doc-graph-align`) che si alimenta del `GRAPH_REPORT.md` nativo. **CLI-first** (sempre disponibile post-install); l'MCP `graphify-mcp` è opt-in (`graph.register_mcp`, best-effort `claude mcp add`). Fallback: degrada a LSP→Grep→Git. Vedi [code-graph-protocol.md](../agents/code-graph-protocol.md) e [CODE-GRAPH-LAYER.md](CODE-GRAPH-LAYER.md).
 
 ### Database
 - **Firebase MCP** (`@modelcontextprotocol/server-firebase` — già integrato come plugin BALDART quando `stack.database.primary` è Firestore) — ispezione documenti, query collection, transazioni.
@@ -86,8 +86,8 @@ Subito dopo la sezione `## Project Context` (o, in mancanza, subito dopo il fron
 ### Esempi nel framework corrente
 
 Vedi le seguenti dichiarazioni per pattern di riferimento:
-- [framework/.claude/agents/codebase-architect.md](../.claude/agents/codebase-architect.md) — `## MCP dependencies` con doc-rag required + LSP-related optional.
-- [framework/.claude/skills/bug/SKILL.md](../.claude/skills/bug/SKILL.md) — Playwright required per UI bug, doc-rag + Firestore optional.
+- [framework/.claude/agents/codebase-architect.md](../.claude/agents/codebase-architect.md) — `## MCP dependencies` con Graphify (code graph) + LSP-related optional.
+- [framework/.claude/skills/bug/SKILL.md](../.claude/skills/bug/SKILL.md) — Playwright required per UI bug, Firestore optional.
 - [framework/.claude/skills/playwright-skill/SKILL.md](../.claude/skills/playwright-skill/SKILL.md) — esempio di sezione "None" (la skill usa Playwright Test CLI, non MCP).
 
 ---

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -209,6 +209,7 @@ Every flag MUST be present as `true` or `false` once `baldart configure` has run
 | `has_prd_workflow` | PRD workflow (`paths.prd_dir`). `/prd` and `/prd-add` skills refuse to run without it. |
 | `has_wiki_overlay` | LLM-wiki overlay (`paths.wiki_dir`). `/capture` skill refuses to run without it. |
 | `has_lsp_layer` | LSP symbol-search layer (since v3.10.0). When `true`, `codebase-architect`, `context-primer`, `bug`, `prd`, `new`, and `simplify` prefer LSP `find-references` / `go-to-definition` over Grep for identifier queries. Wired by `framework/agents/code-search-protocol.md`. The flag also triggers `baldart configure` (and the `/lsp-bootstrap` skill) to install the matching language servers. |
+| `has_code_graph` | Code knowledge graph layer (Graphify, since v4.21.0). When `true`, agents prefer the graph for **structural/relational** queries (`graphify query`/`path`/`affected`) via `framework/agents/code-graph-protocol.md`, and the LLM-wiki overlay is fed by Graphify's native `GRAPH_REPORT.md`. Triggers `baldart configure` / `/graphify-bootstrap` to install Graphify (`pipx install graphifyy`). Install is never silent in CI — `baldart doctor` backfills. Falls back silently to LSP→Grep→Git. |
 
 ### 4.6 `lsp` — installed language servers (since v3.10.0)
 
@@ -219,6 +220,16 @@ Populated by `baldart configure` and the `/lsp-bootstrap` skill when `features.h
 | `lsp.installed_servers` | List of language IDs (`typescript`, `python`, `go`, `rust`, `ruby`, …) whose server BALDART has recorded for this project. Identifiers map 1:1 to adapter files under `src/utils/lsp-adapters/`. |
 | `lsp.auto_verify` | When `true` (default), `baldart doctor` re-verifies the binaries are reachable **on `$PATH`** (via `command -v`, mirroring how the Claude Code LSP tool spawns them) on every run. Disable on CI if the verify step is too noisy. |
 
+### 4.7 `graph` — code knowledge graph state (since v4.21.0)
+
+Populated by `baldart configure` / the `/graphify-bootstrap` skill when `features.has_code_graph: true`. Scalars only (no arrays) by design. See `framework/docs/CODE-GRAPH-LAYER.md`.
+
+| Key | Meaning |
+|---|---|
+| `graph.output_dir` | Directory Graphify writes the graph + report to (relative to the graphed root). Graphify's native default is `graphify-out`. Add it to `.gitignore` — generated artifact, never versioned. |
+| `graph.auto_rebuild_hook` | When `true` (default), `configure` / `/graphify-bootstrap` run Graphify's native `graphify hook install` (post-commit hook that rebuilds the graph, no API cost). `baldart doctor` restores it if missing. |
+| `graph.register_mcp` | When `true`, register Graphify's MCP server (`graphify-mcp`) with the AI tool (best-effort `claude mcp add`). Opt-in: the CLI path (`graphify query`) works without it. |
+
 **Install modes per adapter:**
 
 - `typescript`, `python` — installed globally via npm (`npm install -g typescript-language-server typescript` / `pyright`). Global on purpose: the consumer spawns the server by name from `$PATH`, so a project-local devDep under `node_modules/.bin/` would never be reachable. A binary present only in `node_modules` is reported `installed-but-unreachable`, not `verified`.

package/framework/routines/doc-graph-align.routine.yml

@@ -0,0 +1,53 @@
+name: doc-graph-align
+description: Nightly documentation alignment via the Graphify code knowledge graph — rebuilds the graph offline and surfaces uncovered core code, stale docs, and registry drift.
+since_version: 4.21.0
+
+schedule:
+  cron: "0 4 * * *"            # 04:00 UTC daily (after wiki-review at 02:00)
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: nightly
+
+agent: doc-graph-aligner
+
+prompt: |
+  Run the nightly doc–graph alignment pass (only if `features.has_code_graph: true`
+  AND the `graphify` CLI is installed — otherwise emit
+  `doc-graph-align skipped: graphify not installed` and exit cleanly):
+
+  1. Refresh the graph offline: `graphify update .` (rebuilds
+     `${graph.output_dir}/graph.json` + `GRAPH_REPORT.md`, no API cost).
+  2. Read `${graph.output_dir}/GRAPH_REPORT.md` (god nodes, Leiden communities,
+     surprising connections, suggested questions, freshness).
+  3. Cross-check graph → docs and flag:
+     - Uncovered core code: god nodes / communities with no page under
+       `${paths.wiki_dir}/syntheses/` and no canonical reference doc → append a
+       synthesis candidate to `${paths.wiki_dir}/log.md`
+       (`entry_type: synthesis_candidate`, cite the graph node/community id).
+     - Stale docs: doc files referencing symbols/files absent from the graph
+       (deleted/renamed code) → drift finding for doc-reviewer follow-up.
+     - Registry drift: large graph communities with no
+       `${paths.references_dir}/ssot-registry.md` entry, or registry features whose
+       code cluster is unrecognizable in the graph.
+  4. Emit a consolidated report under
+     `docs/reports/{{YYYYMMDD}}-doc-graph-align.md`.
+
+  Propose, don't author: do NOT rewrite canonical SSOT or wiki pages. The graph
+  is never canonical — synthesis candidates must cite repo SSOT.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-doc-graph-align.md
+  commit:
+    enabled: true
+    prefix: "[DOC-GRAPH-ALIGN]"
+    branch: main
+
+required_artifacts:
+  - .claude/agents/doc-graph-aligner.md
+
+optional: true   # routine is silently skipped when the agent / graph layer is absent
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/index.yml

@@ -5,7 +5,7 @@
 # RemoteTrigger, GitHub Actions, cron, …) is chosen at install time via
 # `npx baldart routines install <name>`.
 #
-# Routines are designed to make the framework's auto-learning and drift-
+# Routines are designed to make the framework's maintenance and drift-
 # detection loops actually run. Without these schedules, agents like
 # wiki-curator or skill-improver are dormant.
 #
@@ -37,9 +37,19 @@ routines:
     cadence: nightly
     since_version: 2.1.0
     summary: |
-      Nightly wiki review — drives the LLM-wiki auto-learning loop.
-      Surfaces synthesis candidates and validates anchors. Required for
-      the LLM Wiki Overlay methodology to actually run.
+      Nightly wiki review — maintains the derived LLM-wiki overlay.
+      Surfaces synthesis candidates (from recent ADRs/PRDs), validates
+      anchors, and checks frontmatter discipline.
+
+  - name: doc-graph-align
+    file: doc-graph-align.routine.yml
+    cadence: nightly
+    since_version: 4.21.0
+    summary: |
+      Nightly documentation alignment via the Graphify code knowledge graph —
+      rebuilds the graph offline and surfaces uncovered core code, stale docs,
+      and registry drift. Optional (only runs when features.has_code_graph is
+      true and Graphify is installed).
 
   # Weekly cadence ----------------------------------------------------------
   - name: skill-improve

package/framework/routines/wiki-review.routine.yml

@@ -17,13 +17,16 @@ prompt: |
      (provider swap, schema change, auth change, API contract, multi-card
      epic) propose a synthesis page candidate and append it to
      `${paths.wiki_dir}/log.md` with `entry_type: synthesis_candidate`.
-  2. Read `${paths.wiki_dir}/log.md` for RAG queries with verdict=weak|empty
-     repeated ≥3 times. These are documentation gaps — propose a synthesis.
-  3. Validate anchor slugs across all wiki pages (internal and cross-file).
+  1b. (only if `features.has_code_graph: true` AND `${graph.output_dir}/GRAPH_REPORT.md`
+     exists) Cross-check the code graph: god nodes / Leiden communities / suggested
+     questions in GRAPH_REPORT.md with no corresponding page under
+     `${paths.wiki_dir}/syntheses/` → propose a synthesis candidate (cite the graph
+     node/community id as provenance). Skip silently if Graphify is absent.
+  2. Validate anchor slugs across all wiki pages (internal and cross-file).
      Flag `WIKI_ANCHOR_BROKEN` and fix in-place when possible.
-  4. Verify frontmatter discipline on every wiki page. Run the project's
+  3. Verify frontmatter discipline on every wiki page. Run the project's
      frontmatter validator if it exists.
-  5. Emit a consolidated report under `docs/reports/{{YYYYMMDD}}-wiki-review.md`.
+  4. Emit a consolidated report under `docs/reports/{{YYYYMMDD}}-wiki-review.md`.
 
   Do NOT create canonical truth in the wiki layer. SSOT always wins.
 

package/framework/templates/baldart.config.template.yml

@@ -50,11 +50,6 @@ paths:
   # Default convention is "docs/metrics" — set explicitly to override.
   metrics: ""                 # e.g. docs/metrics
 
-  # Optional telemetry tap for the wiki auto-learning loop. When set, skills
-  # append retrieval signal here; when empty, the tap is skipped with a
-  # WARNING (never a silent no-op). Only meaningful with has_wiki_overlay.
-  wiki_log: ""                # e.g. tools/doc-rag/wiki_log.py
-
   # High-risk module paths used by RISK DETECTORS (review-profile escalation,
   # security/perf signal detection). A portable list of repo-relative globs
   # the project considers sensitive (auth, payments, billing, core engines).
@@ -162,6 +157,18 @@ features:
   # `baldart configure` installs the relevant language servers when enabled.
   has_lsp_layer: false
 
+  # Code knowledge graph layer (Graphify) — since v4.21.0. When true, agents and
+  # skills that explore code prefer Graphify for STRUCTURAL / RELATIONAL queries
+  # ("what connects X to Y", neighbours, communities, impact) over LSP/Grep, and
+  # the LLM-wiki overlay (capture/wiki-curator) is fed by Graphify's native
+  # GRAPH_REPORT.md (god nodes, communities, suggested questions). Falls back
+  # silently to LSP -> Grep -> Git when the graph is unavailable. Graphify is a
+  # single language-agnostic tool (tree-sitter, local/offline; pip pkg
+  # `graphifyy`, CLI `graphify`). `baldart configure` / `/graphify-bootstrap`
+  # install it. See framework/agents/code-graph-protocol.md and
+  # framework/docs/CODE-GRAPH-LAYER.md.
+  has_code_graph: false
+
   # End-to-end review BLOCKING gate (since v3.18.0). When true, /new Phase 2.6
   # invokes the /e2e-review skill, which combines functional E2E (Playwright
   # spec written by `coder`, executed via playwright-skill) with visual
@@ -214,6 +221,26 @@ lsp:
   # every run. Disable on CI if the verify step is too noisy.
   auto_verify: true
 
+# ─── CODE GRAPH ────────────────────────────────────────────────────────────
+# State of the Graphify code-knowledge-graph layer. Populated by
+# `baldart configure` / the `/graphify-bootstrap` skill. Only meaningful when
+# `features.has_code_graph: true`. Scalars only (no arrays) by design.
+graph:
+  # Directory Graphify writes the graph + report to (relative to the graphed
+  # root). Graphify's own default is `graphify-out`. Add it to `.gitignore` —
+  # it is a generated artifact, never versioned.
+  output_dir: graphify-out
+
+  # When true, `baldart configure` / `/graphify-bootstrap` run Graphify's
+  # NATIVE `graphify hook install` (post-commit git hook that rebuilds the
+  # graph after each commit, no API cost) so the graph never goes stale.
+  auto_rebuild_hook: true
+
+  # When true, register Graphify's MCP server (`graphify-mcp`) with the AI tool
+  # (best-effort `claude mcp add`). Opt-in: the CLI path (`graphify query`) works
+  # without it, so this is an enhancement, not a requirement.
+  register_mcp: false
+
 # ─── GIT ─────────────────────────────────────────────────────────────────
 # Controls how worktree-manager (`/mw`) integrates a worktree's feature
 # branch back into the integration trunk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.18.0",
+  "version": "4.21.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -5,6 +5,7 @@ const UI = require('../utils/ui');
 const toolAdapters = require('../utils/tool-adapters');
 const LspInstaller = require('../utils/lsp-installer');
 const lspAdapters = require('../utils/lsp-adapters');
+const GraphifyInstaller = require('../utils/graphify-installer');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -375,7 +376,6 @@ function detect(cwd = process.cwd()) {
       wiki_dir: exists('docs/wiki') ? 'docs/wiki' : '',
       e2e_tests_dir: e2eTestsDir,
       metrics: exists('docs/metrics') ? 'docs/metrics' : '',
-      wiki_log: exists('tools/doc-rag/wiki_log.py') ? 'tools/doc-rag/wiki_log.py' : '',
       high_risk_modules: [],
     },
     identity: {
@@ -428,6 +428,10 @@ function detect(cwd = process.cwd()) {
       // LSP recommended when any supported language server adapter would
       // detect this project. Drives the default for the configure prompt.
       has_lsp_layer: lspAdapters.detectAll(cwd).length > 0,
+      // Code graph recommended when the Graphify CLI is already on PATH.
+      // Drives the default for the configure prompt; the install/build side
+      // effects only run in the interactive branch (see below).
+      has_code_graph: new GraphifyInstaller(cwd).detect(),
     },
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
@@ -595,6 +599,7 @@ async function interactivePrompts(merged, detected) {
     ['has_prd_workflow', 'Project uses PRD workflow (docs/prd/)?'],
     ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
     ['has_lsp_layer', 'Enable LSP symbol-search layer? (recommended for large codebases)'],
+    ['has_code_graph', 'Enable Graphify code-knowledge-graph layer? (structural queries + wiki feed; recommended for large codebases)'],
     ['has_e2e_review', 'Enable BLOCKING end-to-end review (Phase 2.6 of /new invokes /e2e-review — functional + visual fidelity gate)?'],
   ]) {
     const [key, question] = flag;
@@ -817,6 +822,67 @@ async function interactivePrompts(merged, detected) {
     merged.lsp.installed_servers = [];
   }
 
+  // ---- Code graph layer (Graphify, since v4.21.0) -----------------------
+  // Single language-agnostic tool — no per-language adapters. This block lives
+  // inside interactivePrompts (so it only runs in the interactive path; CI /
+  // `--yes` writes the flag from autodetect and `baldart doctor` backfills the
+  // install). Everything is a thin wrapper over Graphify's native commands.
+  merged.graph = merged.graph || { output_dir: 'graphify-out', auto_rebuild_hook: true, register_mcp: false };
+  if (merged.features.has_code_graph === true) {
+    UI.section('Code graph layer (Graphify — structural retrieval + wiki feed)');
+    const gi = new GraphifyInstaller(process.cwd());
+    let present = gi.detect();
+
+    if (!present) {
+      const want = await UI.confirm('Graphify CLI not found. Install it now (`pipx install graphifyy`)?', true);
+      if (want) {
+        const res = gi.install();
+        if (res.ok) { UI.success(`Graphify installed (${res.method}).`); present = true; }
+        else { UI.warning(`Graphify install failed: ${res.error}`); UI.info('Run `/graphify-bootstrap` or `pipx install graphifyy` later, then `baldart doctor`.'); }
+      } else {
+        UI.info('Skipping install. Run `/graphify-bootstrap` later — `baldart doctor` will flag the missing binary.');
+      }
+    } else {
+      const v = gi.verify();
+      UI.info(`Graphify present (${v.version || 'version unknown'}).`);
+    }
+
+    if (present) {
+      // Initial offline graph build (no API cost).
+      if (await UI.confirm('Build the code graph now (`graphify update .`, offline)?', true)) {
+        const b = gi.buildGraph(process.cwd());
+        if (!b.ok) UI.warning(`Graph build failed: ${b.error}`);
+      }
+      // Always-on wiring for each enabled AI tool (graph-first instructions + pre-tool hook).
+      const aw = gi.installAlwaysOn(merged.tools.enabled || ['claude']);
+      if (aw.wired.length) UI.success(`Graphify always-on wired for: ${aw.wired.join(', ')}`);
+      for (const s of aw.skipped) UI.info(`Always-on skipped for ${s.tool}: ${s.reason}`);
+      // Native post-commit git hook (auto-rebuild) when opted in.
+      if (merged.graph.auto_rebuild_hook !== false) {
+        const h = gi.installGitHook();
+        if (h.ok) UI.success('Graphify git hook installed (auto-rebuild on commit).');
+        else UI.info(`Git hook not installed: ${h.error}`);
+      }
+      // Optional MCP registration (CLI path works without it).
+      if (merged.graph.register_mcp === true) {
+        const m = gi.registerMcp(process.cwd(), merged.graph.output_dir || 'graphify-out');
+        if (m.ok) UI.success('Graphify MCP server registered (`graphify-mcp`).');
+        else UI.info(`MCP registration skipped: ${m.reason}`);
+      }
+
+      // Certification — attest binary + first run + freshness + hook in one shot.
+      const cert = gi.certify(process.cwd(), {
+        outputDir: merged.graph.output_dir || 'graphify-out',
+        expectHook: merged.graph.auto_rebuild_hook !== false,
+      });
+      if (cert.ok && cert.fresh && cert.hook) {
+        UI.success(`Code graph CERTIFIED: graphify ${cert.version || ''} present, first graph built (${cert.builtAtCommit || 'commit n/a'}), auto-rebuild hook active.`);
+      } else {
+        UI.warning(`Code graph NOT fully certified — ${cert.details}${cert.hook ? '' : ' · auto-rebuild hook missing'}. Run \`baldart doctor\` or \`/graphify-bootstrap\` to finish.`);
+      }
+    }
+  }
+
   UI.section('Stack (autodetected from package.json — confirm or override)');
   const charting = merged.stack.charting;
   const chartingCanonical = await promptForKey(

package/src/commands/doctor.js

@@ -32,6 +32,7 @@ const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
 const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
+const GraphifyInstaller = require('../utils/graphify-installer');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
 
@@ -363,6 +364,30 @@ async function detectState(cwd, opts = {}) {
         }
       }
     } catch (_) { /* never block doctor on LSP probe */ }
+
+    // ---- Code graph layer (Graphify, since v4.21.0) --------------------
+    state.graphEnabled = false;
+    state.graphBinaryMissing = false;
+    state.graphStale = false;
+    state.graphNotBuilt = false;
+    state.graphHookMissing = false;
+    try {
+      if (config && !config.__malformed && config.features && config.features.has_code_graph === true) {
+        state.graphEnabled = true;
+        const gi = new GraphifyInstaller(cwd);
+        if (!gi.detect()) {
+          state.graphBinaryMissing = true;
+        } else {
+          const outDir = (config.graph && config.graph.output_dir) || 'graphify-out';
+          const st = gi.isStale(cwd, outDir);
+          state.graphNotBuilt = !st.built;
+          state.graphStale = st.stale === true;
+          if (config.graph && config.graph.auto_rebuild_hook !== false) {
+            state.graphHookMissing = gi.hookStatus(cwd).installed === false;
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on graph probe */ }
   }
 
   return state;
@@ -702,6 +727,60 @@ function planActions(state) {
     });
   }
 
+  // ---- Code graph layer (Graphify, since v4.21.0) ----------------------
+  // The install side effects of `configure` only run interactively (a Python
+  // tool is never installed silently in CI). So doctor is the backfill: it
+  // installs the binary, (re)builds a stale/missing graph, and restores the
+  // native auto-rebuild git hook.
+  if (state.graphEnabled && state.graphBinaryMissing) {
+    actions.push({
+      key: 'graph-install',
+      label: 'Install Graphify code-graph tool',
+      why: 'features.has_code_graph is true but the `graphify` CLI is not on $PATH. Agents fall back to LSP/Grep and the wiki feed is dormant until it is installed (`pipx install graphifyy`).',
+      autoOk: false, // installs a Python package; let the user confirm
+      run: async () => {
+        const gi = new GraphifyInstaller(state.cwd);
+        const res = gi.install();
+        if (res.ok) {
+          UI.success(`Graphify installed (${res.method}).`);
+          const b = gi.buildGraph(state.cwd);
+          if (!b.ok) UI.warning(`Initial graph build failed: ${b.error}`);
+        } else {
+          UI.warning(`Install failed: ${res.error}`);
+        }
+      },
+    });
+  }
+  if (state.graphEnabled && !state.graphBinaryMissing && (state.graphStale || state.graphNotBuilt)) {
+    actions.push({
+      key: 'graph-rebuild',
+      label: state.graphNotBuilt ? 'Build the code graph (not built yet)' : 'Rebuild the stale code graph',
+      why: state.graphNotBuilt
+        ? 'features.has_code_graph is true but no graph.json exists yet. Build it (`graphify update .`, offline, no API cost).'
+        : 'The code graph was built from an older commit than HEAD (built_at_commit ≠ HEAD). Rebuild so structural queries and the wiki feed reflect current code.',
+      autoOk: true, // offline, idempotent, no API cost
+      run: async () => {
+        const gi = new GraphifyInstaller(state.cwd);
+        const b = gi.buildGraph(state.cwd);
+        if (!b.ok) UI.warning(`Graph build failed: ${b.error}`);
+      },
+    });
+  }
+  if (state.graphEnabled && !state.graphBinaryMissing && state.graphHookMissing) {
+    actions.push({
+      key: 'graph-hook',
+      label: 'Install Graphify auto-rebuild git hook',
+      why: 'graph.auto_rebuild_hook is true but Graphify\'s native post-commit hook is not installed, so the graph will drift after commits. `graphify hook install` restores it.',
+      autoOk: true,
+      run: async () => {
+        const gi = new GraphifyInstaller(state.cwd);
+        const h = gi.installGitHook(state.cwd);
+        if (h.ok) UI.success('Graphify git hook installed.');
+        else UI.warning(`Hook install failed: ${h.error}`);
+      },
+    });
+  }
+
   // v3.25.0+: drift detection is authoritative via VERSION compare (isAligned).
   // The HEAD...FETCH_HEAD commit count is subtree-merge noise and never reaches
   // 0, so we MUST NOT use it as the "needs update" signal.
@@ -946,6 +1025,18 @@ function renderDiagnostic(state) {
     console.log(statusLine('LSP layer', 'disabled', 'ok'));
   }
 
+  if (state.graphEnabled) {
+    let value, severity;
+    if (state.graphBinaryMissing) { value = 'enabled but graphify CLI missing'; severity = 'warn'; }
+    else if (state.graphNotBuilt) { value = 'enabled, graph not built yet'; severity = 'warn'; }
+    else if (state.graphStale) { value = 'enabled, graph stale (behind HEAD)'; severity = 'warn'; }
+    else if (state.graphHookMissing) { value = 'enabled, verified (auto-rebuild hook missing)'; severity = 'warn'; }
+    else { value = 'enabled, graph fresh'; severity = 'ok'; }
+    console.log(statusLine('Code graph', value, severity));
+  } else {
+    console.log(statusLine('Code graph', 'disabled', 'ok'));
+  }
+
   console.log();
 }
 

package/src/commands/update.js

@@ -1291,11 +1291,17 @@ async function update(options = {}, unknownArgs = []) {
             const missingStack = Object.keys(tpl.stack || {})
               .filter((k) => typeof tpl.stack[k] === 'string')
               .filter((k) => !(k in (cur2.stack || {})));
+            // Top-level nested config namespaces (e.g. `graph:` since v4.21.0).
+            // Unlike `lsp:` (which propagates only via its `has_lsp_layer` flag),
+            // diff the block's own scalar keys so a new sub-key surfaces too.
+            const missingGraph = Object.keys(tpl.graph || {})
+              .filter((k) => !(k in (cur2.graph || {})));
             const allMissing = [
               ...missingPaths,
               ...missingFeatures,
               ...missingGit.map((k) => `git.${k}`),
               ...missingStack.map((k) => `stack.${k}`),
+              ...missingGraph.map((k) => `graph.${k}`),
             ];
             if (allMissing.length) {
               UI.newline();