cc-os/docs/graphify/09-best-practices-checklist.md

# 09 — Best-Practices Checklist & Quick Reference

The page to keep open while using Graphify (v0.8.30): a scannable do/don't list, a command quick-reference, a "many projects" setup mini-guide, and the common mistakes to avoid. Detail lives in the sibling docs — this card cross-links to them.

> Provenance tags: `[interview]` (creator's intent/sales claims), `[github]` (verified repo facts), `[community]` (third-party), `[unverified claim]`.

---

## Do / Don't

**Do**

- **Index code freely — it's local AST, no tokens.** Code (33 languages, tree-sitter) parses on your machine with no model calls. Run `graphify .` on any repo without fear. `[github]` `[interview]` — see [03-ingesting-code-ast.md](03-ingesting-code-ast.md)
- **Reserve the model (tokens) for documents/images/audio/video only.** This split is the #1 cost rule. `[interview]` — see [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md)
- **Use a local backend (`--backend ollama`) for documents** to keep extraction free and private. `[interview]` — see [05-local-models-and-backends.md](05-local-models-and-backends.md)
- **Ask for god nodes FIRST, then scalpel down.** Read the top of `GRAPH_REPORT.md` for the architecture spine, then `explain` / `path` / bounded `query` into specifics. `[interview]` — see [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md)
- **Prompt the graph, don't make the LLM read the corpus.** The graph IS the memory; have the assistant *extract from* it, not traverse it. `[interview]`
- **Always `--update` when adding data.** SHA-256 hashing + dedup re-process only changed files and merge in, instead of rebuilding. `[interview]` `[github]` — see [07-token-economics-and-updates.md](07-token-economics-and-updates.md)
- **Split large corpora and re-ingest in pieces** rather than dumping one giant chunk — cheaper and less hallucination/dilution. `[interview]`
- **Tune for local/small models:** smaller `--token-budget` (chunk size), lower `--max-concurrency`, raise `--api-timeout` if it stalls. `[github]`
- **Automate freshness for code:** `graphify hook install` (commit hook) or `--watch` — both AST-only, free. `[github]`
- **Measure your own savings with `graphify benchmark`** instead of trusting any headline multiplier. `[github]`

**Don't**

- **Don't quote a token multiplier as a promise.** "70x / 90x / 71.5x" are corpus-dependent marketing figures; independent testing shows ~1–49x, and net-*negative* on small repos (<100 files ≈ 1–3x; some users measure *more* tokens). Say "measure with `graphify benchmark`." `[unverified claim]` `[community]` — see [07](07-token-economics-and-updates.md) and [external-tips.md](external-tips.md)
- **Don't run your first build on a big doc pile with a cloud backend** — that's the way to burn your daily limit (one user burned theirs + $25–30 extra). Start on code, then add docs locally. `[interview]`
- **Don't expect `graphify query "god nodes"` to return the ranking** — `query` is semantic search; the structural god-node list lives at the top of `GRAPH_REPORT.md`. `[github]`
- **Don't confuse `--budget` with `--token-budget`.** `--budget N` caps a **query answer**; `--token-budget N` sets the **extraction chunk size**. Different stages. `[github]`
- **Don't expect the commit hook (or `--watch`) to refresh docs** — they handle **code only**. Re-run `--update` on docs manually (they cost tokens). `[github]`
- **Don't rebuild from scratch to add data** — use `--update`. Use `--force` only to overwrite/clear ghost nodes after deletions. `[github]`
- **Don't treat Obsidian as a substitute.** It's a nice visual pairing, but it can't cluster or surface cross-community links the way Graphify does. `[interview]` — see [01-overview-concepts.md](01-overview-concepts.md)
- **Don't get the package name wrong** — it's `graphifyy` (double-y), the binary is `graphify`. The single most common install mistake. `[community]`

---

## Command quick-reference (v0.8.30)

> **Invocation forms.** In-IDE uses the slash form (`/graphify ./path --update`) and borrows your session's model for docs. Headless uses `graphify extract ./path` and needs an explicit `--backend`. The `query` / `path` / `explain` verbs work both ways (drop the slash in a terminal; always use the no-slash form on Windows PowerShell). `[github]`

**Install & register**

```bash
uv tool install graphifyy        # recommended (or: pip install graphifyy)
graphify install                 # register the skill with your assistant
graphify claude install          # optional: make Claude consult the graph automatically
```

**Build / update**

| Goal | Command | Cost |
|---|---|---|
| First build | `/graphify ./path` — or headless `graphify extract ./path --backend ollama` | code free; docs/images cost tokens |
| Add / changed data | `/graphify ./path --update` | only changed files re-processed |
| Rebuild, clear ghost nodes after deletions | `graphify extract . --force` (or `GRAPHIFY_FORCE=1`) | as a full rebuild |
| Richer inference | `/graphify ./path --mode deep` | higher (more LLM passes) |
| Auto-rebuild on commit (code only) | `graphify hook install` | free (AST) |
| Live auto-rebuild (code only) | `/graphify ./path --watch` | free (AST) |
| Measure savings | `graphify benchmark` | free |

**Query (start at god nodes in `GRAPH_REPORT.md`, then drill down)**

| Goal | Command |
|---|---|
| Semantic search, bounded answer | `graphify query "..." --dfs --budget 1500` |
| Connect two named nodes | `graphify path "A" "B"` |
| Deep-dive one node | `graphify explain "Node"` |
| Visual call-flow | `graphify export callflow-html` |
| Re-cluster (free, no re-extract) | `graphify cluster-only . --resolution 1.5` |
| De-noise god-node ranking | `... --exclude-hubs 99` |
| PR impact / review queue | `graphify prs` (`prs 42`, `--triage`, `--conflicts`) |

**Local-model tuning flags** (extraction stage; see [05](05-local-models-and-backends.md))

```bash
graphify extract ./docs --backend ollama \
  --token-budget 4000 --max-concurrency 2 --api-timeout 900
# Ollama env: OLLAMA_BASE_URL, OLLAMA_MODEL,
#             GRAPHIFY_OLLAMA_NUM_CTX, GRAPHIFY_OLLAMA_KEEP_ALIVE
```

**Outputs** land in `graphify-out/`: `graph.html`, `GRAPH_REPORT.md`, `graph.json`, `cache/`. Backends: `ollama` (local), `bedrock`, `claude`, `gemini`, `openai`, `deepseek`, `kimi`.

---

## Setting up across many projects (code + docs + KB)

The pattern: **one graph per project, folded into one global view.** Keeps each `--update` cheap and isolated while giving you a single place to query across everything. Full playbook in [08-workflows-and-use-cases.md](08-workflows-and-use-cases.md) (Playbook 4) and the global-graph mechanics in [03-ingesting-code-ast.md](03-ingesting-code-ast.md).

1. **Build a graph in each repo / doc folder / KB vault.** Code is free (AST); route documents through a local backend to keep them free and private (see [05-local-models-and-backends.md](05-local-models-and-backends.md)):
   ```bash
   /graphify .                                    # in a code repo (free)
   graphify extract ./notes --backend ollama      # in a docs/KB folder (local model)
   ```
2. **Register each into the global graph** (lives at `~/.graphify/global.json`):
   ```bash
   graphify global add graphify-out/graph.json my-api
   graphify global add graphify-out/graph.json my-notes
   graphify global list                           # node/edge counts per repo
   graphify global remove my-api                  # unregister
   ```
3. **Set a freshness cadence by content type:**
   - **Code → automate:** `graphify hook install` per repo (rebuilds on commit, free). `[github]`
   - **Docs/KB → on demand:** `--update` deliberately after adding/editing material (costs tokens; the hook won't touch docs). `[github]`
   - **Re-register after a doc refresh** so the global view picks up new nodes: `graphify global add graphify-out/graph.json my-notes`.
4. **Pull in external knowledge** (papers, lectures — videos transcribed locally):
   ```bash
   /graphify add https://arxiv.org/abs/1706.03762
   /graphify add <youtube-url>
   ```

---

## Common mistakes

- **Wrong package name.** Install `graphifyy` (double-y); the binary is `graphify`. `[community]`
- **First run = big docs + cloud backend → token burn.** Start on code (free), add docs with a local Ollama backend. `[interview]`
- **Expecting `query` to return god nodes.** It's semantic search — read the ranking at the top of `GRAPH_REPORT.md`. `[github]`
- **Mixing up `--budget` (query answer) and `--token-budget` (extraction chunk).** `[github]`
- **Expecting the commit hook / `--watch` to refresh docs.** Code only; re-run `--update` on docs yourself. `[github]`
- **Stale-node drift.** `--update` is known to leak stale nodes (removed symbols aren't always pruned); use `--force` to rebuild clean when the graph drifts. `[community]` `[github]`
- **Quoting a savings multiplier.** Corpus-dependent — measure your own with `graphify benchmark`. `[unverified claim]`

---

Index: [00-README.md](00-README.md) · Concepts: [01-overview-concepts.md](01-overview-concepts.md) · Install: [02-installation-setup.md](02-installation-setup.md) · Community/skeptical notes: [external-tips.md](external-tips.md)