docs: add FleetTools — an agent-family-agnostic index of fleet capability
Every agent on nh3-dev — Claude, Codex, Grok, Aider — needs the same answers: what runs here, how do I call it, what will bite me. Until now that lived in ~/.claude/CLAUDE.md, which only Claude sessions load, and it was interleaved with operator preferences that other families have no use for. Two-tier by design, matching the persistent-memory split: FLEETTOOLS.md is a 135-line index an agent reads whole, and each entry links to a detail file it opens only when it actually needs that tool. Reading the index costs about a fifth of reading the tree. Detail paths are absolute so they resolve from any working directory, since a non-Claude agent will cat the path rather than follow a markdown link. ~/FLEETTOOLS.md symlinks to the index for discovery. Rule zero is that live inventories get queried, not transcribed: Homepage /api/services, asset-engine /api/v1/services, LiteLLM /v1/models, and every FastAPI seat's /openapi.json. A copied service table would be stale within a month and this repo already has a standing rule against second copies that drift. Contents verified against the running fleet rather than copied from existing docs: binaries resolved on PATH, seven endpoints probed live, the LiteLLM roster counted at 40 models where the old note said ~30. No credentials are included; the vault and its CLI are pointed at instead.
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# graphify — repo knowledge graph
|
||||
|
||||
**CLI:** `graphify` (on PATH; `uv tool install graphifyy`) · **MCP:** `graphify-mcp`
|
||||
|
||||
```sh
|
||||
graphify update <path> # build/refresh: writes graphify-out/{graph.json,GRAPH_REPORT.md}
|
||||
graphify explain <symbol> # callers + neighbours
|
||||
graphify query <...> # traversal over EXTRACTED call edges
|
||||
graphify affected <symbol> # blast radius
|
||||
graphify path <a> <b> # reach between two symbols
|
||||
```
|
||||
|
||||
`graphify update` is the **free, deterministic path**: tree-sitter AST extraction plus
|
||||
Leiden clustering, **zero LLM, zero tokens**, roughly 25 s for ~900 files. Highest-value
|
||||
free output is the **God Nodes** list (core-abstraction surfacing).
|
||||
|
||||
The LLM layer is optional and points at any backend via `~/.graphify/providers.json` —
|
||||
pair community *labeling* (low-caliber) with the free LiteLLM `summarizer` endpoint.
|
||||
Leave deep semantic extraction **off** unless you need it: its INFERRED/AMBIGUOUS edges
|
||||
fight the explicit-over-implicit floor.
|
||||
|
||||
## ⚠ Graphify alone under-counts a blast radius — always cross-check with grep
|
||||
|
||||
Graphify is blind to **function-local and DI-injected imports** (`from .x import y`
|
||||
inside a function body, store objects passed through constructors) — exactly the
|
||||
pattern that hides cross-module callers. Graphify confirms call structure; grep catches
|
||||
what its AST extraction misses; **neither alone is sufficient** (graphify-only
|
||||
under-counts, grep-only misses transitive reach).
|
||||
|
||||
Run both before writing any contract that touches existing code. A contract that names
|
||||
3 files when the rip touches 6 is a scope miss the up-front pass would have caught.
|
||||
|
||||
Complements a hand-authored `docs/CODEBASE.md` (curated geography); does not replace it.
|
||||
Reference in New Issue
Block a user