kb-init - map the codebase once, cheaply

The knowledge base is defined in protocol/kb.md at the plugin root, ../../protocol/kb.md from this skill's directory. Read it first. This skill is the run that creates it, or rebuilds it after the code drifted away from it. kb.py below means python3 <plugin root>/protocol/kb/kb.py, run from the project root.

The User runs this in their own session. It is not a spec: no roles, no review. The User is the reviewer.

The run

1. Modules. Run kb.py modules. It lists a module for every source in the project: build-file modules where Maven or Gradle lay them out, directory modules for the rest. If it finds no source, stop and tell the User that kb.py recognises code by its extension, and that a + <pattern> line in fondue/kb/parts.txt (protocol/kb.md) names the project's source when its language is not on the list. Otherwise show the User the module list, with each module's size, when it looks wrong: too few, a module that is really two, or a directory module that is not code at all. parts.txt fixes each: a <card id> <directory> line gives a directory inside a module a card of its own, so a module that is really two keeps its build and still gets two cards; a - <pattern> line excludes what is not source, e.g. old specs or benchmarks; a + <pattern> line includes what the defaults miss. The User picks the lines.
2. What is already there. If fondue/kb/cards/ exists, this is a refresh. kb.py status shows how far each card has drifted. Offer kb.py write --since <the oldest verified-at> for the drifted modules, or --all to rebuild every card. A card that exists goes into its rewrite, so a rebuild changes only what the code changed.
3. The cost, before spending it. Run kb.py estimate for what step 4 will write: no argument for --all, the same --since <sha> for a refresh. Tell the User the figure and the model (sonnet unless they name one), and ask for their go, as a question with the AskUserQuestion tool when the session has one. A card costs about the same whatever the language, $0.01-0.15 on Sonnet for most modules (design-notes.md). Why: cost is the User's call, and this is the one step that spends tokens.
4. Write. Note the time as date +%Y-%m-%dT%H:%M:%S prints it. Run kb.py write --all, or the refresh from step 2, with --model if the User named one. It packs each module, makes one tool-less call per card, six at a time, and writes index.md. A run of 30-40 modules takes a few minutes, so give the command a long timeout. A card that fails is named at the end. Run kb.py write <those ids> once more.
5. Check. Run kb.py status until it reads clean.
   • A dead name means the writer quoted a name the code does not have. Fix it in the card by hand, lowercase names the same way: drop the backticks if it is a library's name, or correct the name, a path to its repo path. A quoted name that is neither declared in the code nor a file's name, e.g. a build option or a command-line tool, loses its backticks too.
   • A card over the limit belongs to a module that does too much for one card. Tell the User. Splitting it, the module or only its card through parts.txt, is their call.
6. Report.
   • Give the User the real cost: kb.py usage --since <the time from step 4>.
   • Ask them to check the extension points of two or three cards for modules they know well. Those are the entries most likely to be incomplete, and the ones a wrong card costs most on.
   • Offer one line in the project's CLAUDE.md, so sessions outside fondue use the knowledge base too: Before designing a change, read fondue/kb/index.md and the cards it points to.
7. Commit only when the User asks: git add fondue/kb, on its own. The .gitignore that write created keeps .packs/ and .runs/ out.

What this skill does not do

• Write or change project skills. A card points to the skills that cover its module, and index.md lists them all, but what a skill says is the User's to change.
• Read code itself. Every card comes from the packed input, so the run costs one call per card and nothing more. Opening files to "improve" a card turns the run into the agent loop the tool exists to avoid.