A wiki written by our AI brain

I've never sat down and written a wiki for this repo. That doesn't mean there isn't one. The brain wrote it for me.

This is the 2nd post in the series about pks brain. The first post went through why the brain exists and how it's structured. This one opens the drawer and shows what it actually produces when you let it read half a year of Claude sessions.

How a wiki page gets made

The wiki pipeline runs in four steps, each with its own pks brain command and its own checkpoint (a fifth phase, pks brain adr, sits outside the wiki pipeline — it gets its own post another time):

1. ingest — deterministic dump of every session JSONL into compact firehoses (prompts.jsonl, tools.jsonl, files.jsonl, errors.jsonl)
2. extract — AI-generated markdown summary per session, driven by an editable brain-extract skill
3. synth — thematic clustering across sessions
4. wiki — one page per detected cluster, synthesised from extracts and firehoses

My pks brain status says 7,000 prompts, 88,000 tool calls, and 2,940 AI extracts right now. Those extracts collapse into 436 wiki pages under .pks/brain/wiki/, one per detected theme. Here are four of them, picked because they demonstrate four different kinds of precision.

auth.md — 103 sessions condensed

The heaviest topic in my repo. The brain scanned 103 sessions that touched authentication and distilled them into 84 lines. It opens like this:

The Agentic Live authentication system orchestrates Keycloak (OIDC identity provider), NextAuth.js (browser session layer), and Graph API integration (Entra ID B2B guest management) to enable passwordless sign-in, federated OAuth (Microsoft, GitHub, LinkedIn), email-first guest invitations, and role-based access control.

The important bit: that sentence appears nowhere in my code. No comment, no README, no ADR phrases it that way. The brain derived it from what I actually built across 103 sessions — it's synthesis, not stitching.

It also pulled out user stories:

Email-first B2B guest onboarding — As a coworker from a partner tenant, I want to sign in with my email and be automatically invited as an Entra ID guest if I'm not in the tenant, so onboarding is instant without manual admin provisioning. From: 1c9f68e2-b33c.

Every user story has a source citation pointing to the session it was reconstructed from. Traceable AI synthesis. And — what almost no wiki has — a section called Open threads & known issues with concrete things still broken: "Keycloak resource lifecycle: Stop/start/restart commands fail in Aspire", "Session validation gap: User remains signed in after Keycloak reset". That isn't anything I'd write into a wiki. It's something the brain could see as a pattern across my sessions and extract.

agentic-live.md — the big picture

34 sessions about the platform itself. The brain identifies the architecture as three layers — CLI, relay, viewer — and names the hot files: metadata/route.ts, lives/[streamId]/page.tsx, ws-relay.mjs. That kind of overview doesn't exist in any single commit, but if you've worked on a project for half a year a model can distil it from where you've edited most often and where you've stopped to debug.

One of the most useful items the brain found:

metadata/route.ts hotspot — 36 edits required due to complex fanout logic combining sessionId/broadcastId; needs refactoring or isolation.

That isn't gut feeling. That's 36 measured edits in one file. The brain can surface that kind of signal because it has the full tool-call history across every session — not just the most recent commit.

design-system.md — design too

One of the more surprising outputs. The brain hasn't only worked on code topics. It found 23 sessions about visual identity and synthesised them into a design-system page with palette, typography, tone, and component list:

Aesthetic: Dark, minimal, developer-grade. Inspired by Linear, Vercel, Raycast — but warmer and more human.

That's a phrasing I've used in conversations with Claude more than once. The brain pulled those repetitions together and canonised them into the design system's current defining line. That kind of emergent consistency is exactly what I'd want to be hand-maintained, but never get myself to actually sit down and write.

devcontainer.md — infrastructure too

73 sessions about devcontainers — how I spawn remote dev environments, which images I use, where it goes wrong. This is pure infrastructure, not features. It's also not the first thing I'd have chosen to document. But the brain wrote pages about it because the pattern was there: 73 sessions store more reusable decisions than most single-purpose features.

That's the value of automatic wiki generation: it documents what you did, not what you planned to document.

How accurate is it?

Honest answer: about 85% right, maybe 10% imprecise, 5% outright wrong. Examples of what I've seen:

• Correct and surprisingly sharp: the open-threads sections. The brain finds things I've forgotten I left half-solved in the codebase. The hot-files section is measurably true — it counts actual edits.
• Imprecise but useful: user stories often read a bit too generic ("As a user, I want to sign in"). They capture intent, not nuance.
• Outright wrong: rare, but happens — typically when the brain conflates two sessions that use the same term for two different things and incorrectly merges them.

The pattern: the brain is better at what was built and where it's broken than at why it was built. That makes sense — the source material is tool calls and prompts, not whiteboards.

Next post

The 3rd post goes down into the graph that makes all this possible: the nodes (Session, Prompt, ToolCall, File), the edges, what's stored deterministically, what's AI-synthesised. That's the architecture sitting under all 436 wiki pages you've now seen four of.