Three documents describe the agent layer (src/, webview-ui/) the same way BroccoliDB papers describe the substrate (broccolidb/). Read them in this order:
| Order | Doc | Audience | Time |
|---|---|---|---|
| 1 | Companion brief | Executives, PMs, new contributors | 5 min |
| 2 | Philosophy | Designers, tech leads — why calm agency | 15 min |
| 3 | Whitepaper | Engineers — how it is built (incl. §8 governed execution) | 45 min |
| 4 | Knowledge brief | Designers, Leads — Workspace Knowledge brief | 5 min |
| 5 | Knowledge philosophy | Leads, Designers — Advisory memory tenets | 10 min |
| 6 | Knowledge thesis | Architects — Sovereign advisory invariant | 15 min |
| 7 | Knowledge whitepaper | Engineers — Architecture details | 30 min |
| 11 | Token buffer brief | Executives, PMs — Token Ingestion Buffer executive summary | 5 min |
| 12 | Token buffer philosophy | Leads, designers — Normative philosophy of context compaction | 15 min |
| 13 | Token buffer whitepaper | Engineers, reviewers — Formal DSL grammar & adversarial security | 30 min |
LUMI is a VS Code extension that runs an approval-gated agent loop (Plan/Act, 64 tools, 6 providers) with governed subagent swarms (lock-necessity, per-agent roadmap projection, patch reconciliation, merge gate, receipt schema v3) on top of BroccoliDB memory and structural proof.
┌─────────────────────────────────────────────────────────┐
│ LUMI (agent) docs/papers/* │
│ Session · approval · LLM · tools · governed swarms · webview │
│ src/ · webview-ui/ │
└───────────────────────────┬─────────────────────────────┘
│ @noorm/broccolidb
│ cognitive memory · Spider · kernel
┌───────────────────────────▼─────────────────────────────┐
│ BroccoliDB (substrate) broccolidb/docs/papers/* │
│ Proof · repair · runtime graph · snapshots │
└─────────────────────────────────────────────────────────┘
Do not merge the narratives. Companion UX is not substrate discipline.
# Agent workspace
npm run check-types && npm run test:unit
npm run docs:check-agent-links
# Substrate (separate package)
cd broccolidb && npm run test:guardrails| Doc | Purpose |
|---|---|
| Architecture (current) | Module map |
| Project map | 1-to-1 paths |
| All tools | Tool enum |
| Roadmap projection quick reference | Patch tags, operator legend |
| Governed subagent execution | Swarm harness architecture |
| Governed execution runbook | Operator incidents |
| Governed execution decisions | ADRs |
| BroccoliDB papers | Substrate philosophy |
| Workspace Knowledge Thesis | Invariant thesis |
| Workspace Knowledge Philosophy | Philosophy tenets |
| Workspace Knowledge Brief | Executive brief |
| Workspace Knowledge Whitepaper | Technical whitepaper |
| MoD Brief | Executive brief |
| MoD Philosophy | Philosophy paper |
| MoD Whitepaper | Technical whitepaper |