| name | grok |
| description | Understand a repository — a black-and-white, table-first Load-Bearing Ledger that ranks every file by structural importance and explains why. Personalized PageRank over the bash-call + python-import graph (utility-down-weighted, entry-point-seeded) is the rank; each row carries a reason vector (imported-by, churn/hotspot, ownership, entry-point, cycle) so no number is bare. Deterministic, reproducible, no LLM — the same parse→JSON→fixed-template→~/.anu/grok/<repo> pattern as scene/trail/git. Use when the user runs `grok` or asks to understand/see the shape of a repo, what files matter, what's load-bearing, what's linked most, or what to read first. |
grok — understand a repository
grok answers the newcomer's first question about a codebase — what matters, what's linked
most, what do I read first — as a dense, trustworthy, black-and-white ledger, not a diagram.
It is the synchronic twin of git/scene (which show how the repo got here): grok shows
what the repo is right now.
Run it
grok # build + render + open ~/.anu/grok/<repo>/index.html
grok open # re-open the last render without rebuilding
grok watch # live: re-render as the repo changes
What it computes (all deterministic — no LLM in v1)
The Load-Bearing Ledger: every tracked file, ranked by personalized PageRank over the
repo's real dependency graph — bash source/function-call edges (anu's backbone) + python
import edges — reversed so depended-upon infrastructure floats up, seeded on entry points, and
utility-down-weighted so log/util helpers don't crown the list. Alongside the rank (never
fused into it, so structurally important stays separate from historically risky): fan-in/out,
hotspots (churn × complexity) and temporal coupling from git log, and ownership.
Every row carries a reason vector — imported by 19 · 42 commits/12mo · owns entrypoint 'pane' · couples with swarm,viz — so the rank explains itself. The bar: the top 20 rows are trustworthy.
The principle
The ledger is the deterministic skeleton — computed, reproducible, always-true. Model-authored
meaning (naming subsystems, the reason a file matters in prose, the reading-order narrative) is
a later slice and will always be visibly separate from the computed facts and anchored to a
file:line — the same anti-rot discipline as trail/git. v1 ships only the skeleton, so
everything built on top rides on numbers you can trust.
Pattern
build.py (parse → metrics → grok.json) → render.py (inject __GROK__) → fixed B&W
template.html → ~/.anu/grok/<repo>/index.html. Pure stdlib (python ast, regex, hand-rolled
PageRank/Tarjan) — zero new dependencies.
