---
name: graphify-bootstrap
effort: medium
description: >
  Install, verify, and wire the Graphify code-knowledge-graph layer for this
  project. Installs the Graphify CLI (pipx install graphifyy), builds the graph
  offline (graphify update .), installs the native post-commit auto-rebuild git
  hook, wires Graphify's always-on mode into the enabled AI tools, and optionally
  registers the graphify-mcp MCP server. Use when the user says /graphify-bootstrap,
  "install graphify", "set up the code graph", or after enabling
  features.has_code_graph for the first time. Idempotent — re-running re-verifies
  and rebuilds a stale graph.
---

# Graphify Bootstrap

Set up the code knowledge graph that lets agents answer **structural / relational**
questions (what connects X to Y, blast-radius, clusters) and feeds the LLM-wiki
overlay (Karpathy loop) from Graphify's native `GRAPH_REPORT.md`. This is the
explicit install path — `baldart configure` only installs Graphify in its
interactive branch, so this skill (and `baldart doctor`) cover CI / first-run.

## Project Context

**Reads from `baldart.config.yml`:** `features.has_code_graph`, `graph.output_dir`, `graph.auto_rebuild_hook`, `graph.register_mcp`, `tools.enabled`.
**Gated by features:** `features.has_code_graph` — this skill refuses to run when the flag is `false`, prompting the user to flip it via `npx baldart configure` first.
**Overlay:** loads `.baldart/overlays/graphify-bootstrap.md` if present — project-specific build flags (e.g. `--mode deep`, a non-default output dir, an LLM backend for `--wiki`/community naming).
**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.

## What This Skill Does

Graphify is a SINGLE language-agnostic tool (tree-sitter, 28 languages,
local/offline) — there is no per-language step. This skill composes Graphify's
own native commands via `src/utils/graphify-installer.js`:

1. Confirms `features.has_code_graph: true`.
2. Installs the CLI: `pipx install graphifyy` (fallback `pip install --user graphifyy`).
   Provides binaries `graphify` + `graphify-mcp`.
3. Builds the graph **offline** (no API cost): `graphify update .` →
   `${graph.output_dir}/{graph.json, GRAPH_REPORT.md, graph.html}`.
4. Wires Graphify's **always-on mode** into each tool in `tools.enabled`
   (`graphify claude install`, `graphify codex install`, …) — writes a graph-first
   section to the tool's instruction file + a pre-tool hook.
5. Installs the native **post-commit git hook** (`graphify hook install`) when
   `graph.auto_rebuild_hook: true`, so the graph never goes stale.
6. Optionally registers the MCP server (`graph.register_mcp: true`) via
   best-effort `claude mcp add graphify -- graphify-mcp <graph.json>`.
7. Confirms `graphify-out/` is in `.gitignore` (generated artifact, never versioned).

## Workflow

1. **Refusal check.** If `features.has_code_graph: false` (or missing):
   ```
   This project hasn't opted in to the code graph layer yet.
   Run `npx baldart configure` and answer YES to "Enable Graphify code-knowledge-graph layer?"
   then re-run /graphify-bootstrap.
   ```
   Stop here. Do not proceed.

2. **Probe + install.** Use the BALDART installer (internally
   `src/utils/graphify-installer.js`):
   ```
   node -e 'const G=require("./.framework/src/utils/graphify-installer"); const g=new G(); if(!g.detect()){console.log(JSON.stringify(g.install()))} else {console.log(JSON.stringify(g.verify()))}'
   ```
   If install fails, print `pipx install graphifyy` for the user and stop with a
   clear message (do not proceed to build).

3. **Build the graph.** `graphify update .` (offline). For LLM-named communities /
   wiki pages, `graphify label .` or `graphify update . --wiki` (needs an LLM key;
   optional — skip silently if no key).

4. **Wire always-on + hook.** Run `graphify <tool> install` for each enabled tool
   and `graphify hook install` (when `auto_rebuild_hook`). Capture failures into a
   "Skipped" bucket — never abort the whole skill on one failure.

5. **Optional MCP.** When `graph.register_mcp: true` and the `claude` CLI is
   present, register `graphify-mcp`; otherwise note the CLI path works without it.

6. **Confirm `.gitignore`.** Ensure `graphify-out/` is ignored; add it if missing.

7. **Output.** A compact one-line status block, in the project's
   `identity.language` from `baldart.config.yml` (English default).

## Output Contract

A single short status block — never a multi-page report. Format:

```
Graphify bootstrap:
  ✓ graphify 0.8.x installed (pipx) — binaries graphify + graphify-mcp
  ✓ graph built — 571 nodes · 873 edges · 24 communities (graphify-out/, offline)
  ✓ always-on wired: claude, codex
  ✓ git hook installed (auto-rebuild on commit)
  · MCP: CLI path active (register_mcp: false)
  ✓ .gitignore covers graphify-out/
Next: codebase-architect prefers the graph for structural queries; wiki-curator
feeds synthesis candidates from GRAPH_REPORT.md. See code-graph-protocol.md.
```

## Notes

- The structural graph is **offline / 0 API cost**. Only `--wiki` /
  community-naming (`label`) need an LLM API key — both optional.
- This skill never edits source code. Side effects: a Python package install,
  the `graphify-out/` artifact, Graphify's own instruction-file sections + hooks,
  and a `.gitignore` line.
- Re-run safely. `graphify update .` is incremental; always-on / hook installs are
  idempotent.
- If the graph goes stale later (built from an older commit), `baldart doctor`
  flags it and offers `graph-rebuild` — or the post-commit hook handles it.

## See Also

- `framework/agents/code-graph-protocol.md` — runtime retrieval + fallback rules
- `framework/docs/CODE-GRAPH-LAYER.md` — lifecycle, schema, invariants
- `src/utils/graphify-installer.js` — the native-command wrapper this skill drives
- `src/commands/configure.js` — same install flow when first enabling the flag
