Problem
`wiki.py`'s `to_wiki()` already produces one markdown article per community plus an `index.md` — great as a reference you jump around in, but it doesn't answer "where do I even start reading this codebase." A new engineer (or an AI assistant onboarding onto an unfamiliar repo) still has to decide their own reading order across N independent community pages.
Proposal
An `onboard` mode (CLI: `graphify onboard`, or an option on `wiki`/`report`) that synthesizes one linear narrative instead of N independent pages: entry points first (what actually gets executed/imported from outside), then the communities reached by walking outward from them in dependency order, each with a short "why you'd care about this next" transition. Conceptually it's a guided traversal over the same graph + community + cohesion data `report.py` and `wiki.py` already compute — just re-sequenced and connected as a single document instead of independent per-community write-ups.
Every claim in it should stay traceable the same way GRAPH_REPORT.md already is — pointing back to real nodes/edges with EXTRACTED/INFERRED confidence, not freeform prose disconnected from the graph.
Why this fits now
It's a genuinely different consumption mode of data graphify already computes, not a new extraction/analysis capability — low risk to the extraction pipeline, and it plays to the "explained, not a black box" positioning already true of the EXTRACTED/INFERRED edge labeling.
Note
This is a proposal, not a commitment to implement — happy to discuss shape/scope first.
Problem
`wiki.py`'s `to_wiki()` already produces one markdown article per community plus an `index.md` — great as a reference you jump around in, but it doesn't answer "where do I even start reading this codebase." A new engineer (or an AI assistant onboarding onto an unfamiliar repo) still has to decide their own reading order across N independent community pages.
Proposal
An `onboard` mode (CLI: `graphify onboard`, or an option on `wiki`/`report`) that synthesizes one linear narrative instead of N independent pages: entry points first (what actually gets executed/imported from outside), then the communities reached by walking outward from them in dependency order, each with a short "why you'd care about this next" transition. Conceptually it's a guided traversal over the same graph + community + cohesion data `report.py` and `wiki.py` already compute — just re-sequenced and connected as a single document instead of independent per-community write-ups.
Every claim in it should stay traceable the same way GRAPH_REPORT.md already is — pointing back to real nodes/edges with EXTRACTED/INFERRED confidence, not freeform prose disconnected from the graph.
Why this fits now
It's a genuinely different consumption mode of data graphify already computes, not a new extraction/analysis capability — low risk to the extraction pipeline, and it plays to the "explained, not a black box" positioning already true of the EXTRACTED/INFERRED edge labeling.
Note
This is a proposal, not a commitment to implement — happy to discuss shape/scope first.