Documentation for the LUMI VS Code extension and agent workspace (src/, webview-ui/). BroccoliDB has its own docs — do not duplicate substrate content here; link across via AGENT_STACK.md.
Mintlify home · Companion brief · Agent stack · Maintainer · Repository README
- At a glance
- How LUMI differs
- Product evolution
- Start here
- Project configuration
- Reading paths by audience
- Where to document what
- Release & policy
- User guide
- Features & customization
- Architecture & internals
- Papers
- Runtime API
- Local development & quality
- Principles
Workspace-verified figures from papers/companion-brief.md (v1.0.3):
| Metric | Value | Source |
|---|---|---|
| Extension ID | CardSorting.lumi |
package.json |
| Typed tools | 62 | src/shared/tools.ts |
| Wired LLM providers | 5 | src/shared/providers/providers.json |
| Built-in slash commands | 10 | src/core/slash-commands/index.ts |
| Lifecycle hook kinds | 8 | VALID_HOOK_TYPES in src/core/hooks/utils.ts |
| Roadmap VS Code settings | 5 | lumi.roadmap.* in package.json |
| Read-only tools | 12 | READ_ONLY_TOOLS in src/shared/tools.ts |
| Agent modes | 2 | plan · act |
LUMI forked the Cline VS Code extension and added governance layers (subagents, BroccoliDB, roadmap gates). For upstream credit, migration notes, and links to Cline docs, see Origins & acknowledgments in the repository README. Full timeline: EVOLUTION.md.
| Typical autonomous agent | LUMI |
|---|---|
| Runs until stopped | Approval gate per mutating tool |
| Opaque file changes | Diff view before write |
| Hard to undo | Checkpoints after each tool use |
| “Done” when model says so | Completion pipeline + roadmap gates |
flowchart TB
subgraph docs ["docs/ — LUMI session layer"]
GS[Getting started]
UG[User guide]
ARCH[Architecture]
PAP[Papers]
API[api/ touchpoints]
end
subgraph broc ["broccolidb/docs/ — substrate"]
BAPI[Public API]
BCLI[CLI]
BPAP[Papers]
end
GS --> UG
UG --> ARCH
ARCH --> PAP
ARCH --> API
API -.->|link only| BAPI
PAP -.->|separate narrative| BPAP
Cline → DietCode fork → BroccoliDB substrate → governed swarms → LUMI (current). Phase-by-phase history, dated milestones, migration playbook, and legacy inventory:
| File / directory | Doc |
|---|---|
.dietcoderules/ |
Project rules |
.dietcoderules/hooks/ |
Hooks |
.dietcodeignore |
Ignore file |
.dietcodeworkflows/ |
Workflows |
ROADMAP.md |
Roadmap steering · Auto-governance post-mortem |
@ mentions: working-with-files
| Doc | Description |
|---|---|
| Home | Mintlify landing page |
| Quick start | Install, provider, first task |
| What is LUMI? | Product overview |
| Agent stack | LUMI + BroccoliDB two-layer map |
| Project map | 1-to-1 map of src/ directories |
| Code ↔ docs | Source path → doc page lookup |
| Maintainer guide | CI checks, branding rules, update checklist |
| Audience | Recommended path | Time |
|---|---|---|
| New user | Quick start → Your first project → Task management | ~30 min |
| Power user | Auto-approve + Checkpoints → MCP overview → Hooks | ~45 min |
| Team lead | Companion brief → Evolution → Security | ~25 min |
| Designer / PM | Philosophy → User interface design | ~25 min |
| Cline / DietCode migrator | EVOLUTION.md → README origins → Project rules | ~20 min |
| Engineer (agent) | Whitepaper → Architecture (current) → Project map | ~60 min |
| Privacy / security review | SECURITY_BEST_PRACTICES → root README § Local-first | ~15 min |
| Engineer (substrate) | BroccoliDB docs → Runtime API index | varies |
| Doc contributor | MAINTAINER → DOCS_GUIDE → REWRITE_PLAN | ~15 min |
| Change | Update here (docs/) |
Update in BroccoliDB (broccolidb/docs/) |
|---|---|---|
| New LUMI tool or slash command | tools-reference/, CODE_TO_DOC_MAP |
— |
| New wired provider | provider-config/README, model guide |
— |
| Webview UX / approval flow | feature or architecture doc | — |
| Spider agent ergonomics in IDE | api/spider-agent-ergonomics.md |
cross-link only |
AgentContext / capability API |
link from api/README.md |
public-api.md, getting-started.md |
CLI broccolidb spider |
— | cli.md |
When in doubt: session behavior → docs/; durable substrate → broccolidb/docs/.
| Doc | Purpose |
|---|---|
| MAINTAINER.md | When to update docs; CI commands; branding rules |
| DOCS_GUIDE.md | Full documentation map and principles |
| REWRITE_PLAN.md | Rewrite progress and maintenance checklist |
| SECURITY_BEST_PRACTICES.md | Approval gates, ignore files, MCP trust |
| CODEBASE_STANDARDS.md | Repo layout and coding conventions |
| ../SECURITY.md | Vulnerability reporting |
| Topic | Doc |
|---|---|
| Tasks | core-workflows/task-management.mdx |
| Plan & Act modes | core-workflows/plan-and-act.mdx |
| Files & @ mentions | core-workflows/working-with-files.mdx |
| Slash commands | core-workflows/using-commands.mdx |
| Checkpoints | core-workflows/checkpoints.mdx |
| Tools index | tools-reference/README.mdx |
| All tools | tools-reference/all-dietcode-tools.mdx |
| Model selection | core-features/model-selection-guide.mdx |
| Glossary | getting-started/glossary.mdx |
| Feature | Doc |
|---|---|
| Auto-approve & YOLO | features/auto-approve.mdx |
| Focus chain | features/focus-chain.mdx |
| Subagents | features/subagents.mdx |
| Storage & cache | features/storage-and-cache-management.md |
| Roadmap steering | features/roadmap-steering.mdx · Post-mortem |
| Memory bank | features/memory-bank.mdx |
| Multi-root workspace | features/multiroot-workspace.mdx |
| Hooks | customization/hooks.mdx |
| Skills | customization/skills.mdx |
| Workflows | customization/workflows.mdx |
| Project rules | customization/dietcode-rules.mdx |
| Ignore file | customization/dietcodeignore.mdx |
| MCP | mcp/mcp-overview.mdx |
| Providers (active 5) | provider-config/README.mdx |
| Doc | Description |
|---|---|
| Agent stack | Two-layer map (LUMI + BroccoliDB) |
| Architecture (current) | Extension module structure |
| System communication | gRPC host bridge, webview messaging |
| gRPC subscription persistence | Persistent streams, idle-timeout incident, runtime architecture |
| Memory & reasoning | Context, cognitive memory tools |
| Working with subagents | Background agent delegation |
| Roadmap projection quick reference | Patch tags, invariants, operator legend — start here |
| Governed subagent execution | Lane modes, SQLite lease authority, wait-for liveness, merge gate, receipts |
| Governed execution runbook | Operator incident playbook, violation catalog, retry flow |
| Governed execution schema | Receipt schema v3 field reference |
| Governed execution decisions | ADR-style design decisions |
| Governed execution authority | SQLite authority, safe reconciliation, deadlock prevention, terminal CAS |
| Governance | Maintainer process, branch protection, release policy |
| Changelog | User-facing release notes (Keep a Changelog) |
| Support | Where to get help |
| GitHub automation | Workflows, templates, and maintainer CI map |
| Releasing | Maintainer marketplace publish runbook |
| Security best practices | Approval gates, ignore files |
| Central execution funnel | One auditable authority for admission, permits, handler dispatch, reliability, and terminal tool events |
| Task lifecycle authority | Transactional generation, cancellation, resume, parent/child propagation, and terminal state |
| Task cancellation | Cancellation request fence and settlement |
| Task resume and recovery | Generation-safe restore and explicit resume |
| Completion authority migration | Historical split-authority migration |
| Completion funnel | Semantic completion and durable handoff to lifecycle |
| ADR-001 Token Buffer Engine | Centralized context optimization, 10-stage DSL compression, vision eviction, and APC prompt cache alignment |
| ADR-002 Webview State Decoupling | Decoupled ChatMessagesContext, WeakMap projection & metrics caching, ChatView modularization, and Cerebras native fetch refactoring |
| Spider forensic engine | Policy/audit layer (BroccoliDB) |
| User interface design | Webview UX patterns |
| Doc | Audience | Purpose |
|---|---|---|
| Index | All | Reading order and two-layer context |
| Companion brief | Leads, evaluators | Executive summary · workspace-verified metrics |
| Philosophy | Builders, policy | Calm agency · approval · completion gates |
| Whitepaper | Engineers | Full technical architecture |
| Token buffer brief | Executives, PMs | Token Ingestion Buffer executive summary & 5 debunking proofs |
| Token buffer philosophy | Leads, designers | Epistemic compaction & single-turn vision duty |
| Token buffer whitepaper | Engineers, reviewers | Formal DSL grammar, Theorem 1–3 proofs & component ablation matrix |
| MEOW brief | Leads, onboarding | Executive brief for the Model-Efficient Order-aware Workflow |
| MEOW philosophy | Leads, builders | Normative reasoning and calm concurrency principles |
| MEOW whitepaper | Engineers | Canonical technical architecture for execution lane swarms |
| MEOW migration | Evaluators | Measured evidence and naming evolution |
Substrate papers: broccolidb/docs/papers/ — separate narrative.
Agent-facing substrate API notes (Spider, snapshots, replay, budgets):
| Doc | Topic |
|---|---|
| api/README.md | Index |
| api/spider-agent-ergonomics.md | Spider toolkit |
| api/runtime-snapshots.md | Snapshots |
| api/runtime-replay.md | Replay |
| api/execution-budgets.md | Execution budgets |
Package docs: broccolidb/docs/README.md
Mintlify preview:
cd docs && npm install && npm run devQuality checks (repository root):
npm run docs:check-all # all doc guardrails + Mintlify links
npm run docs:check-agent-links # 24 required docs + link resolution
npm run docs:check-agent-branding # no stale user-facing DietCode in core dirs
npm run docs:check-root-readme # README.md parity + live metrics
npm run docs:check-docs-readme # docs/README.md structure guardrails
npm run docs:check-root-readme-links # root README relative links
npm run docs:check-readme-metrics # README + companion-brief vs live codebase
npm run docs:check-links # Mintlify broken-link pass (included in docs:check-all)
npm run docs:tag-legacy-providers # after adding unwired provider pagesDoc checks in ci:check-all (except Mintlify-only docs:check-links). Run npm run docs:check-all before publishing docs.
Architecture milestone notes (archaeology only): history/architecture/
- 1-to-1 with code — Architecture pages mirror real paths under
src/andwebview-ui/. - LUMI user-facing — Product name is LUMI;
DietCodeonly for internal types and legacy filenames. - Two-layer boundary — Session UX docs live here; substrate docs live in
broccolidb/docs/. - Measured claims — Metrics cite verifiable paths (
package.json,src/shared/tools.ts, etc.).
Calm agency: approve before mutate, checkpoint after tool use, complete only through gates.