{"id":51451901,"url":"https://github.com/cardsorting/lumi","last_synced_at":"2026-07-05T22:00:40.685Z","repository":{"id":350956506,"uuid":"1208868356","full_name":"CardSorting/LUMI","owner":"CardSorting","description":"Calm VS Code coding companion — Plan/Act modes, approval-gated tools, governed parallel subagents (projection + durable receipts), MCP, BroccoliDB memory.","archived":false,"fork":false,"pushed_at":"2026-06-24T07:00:01.000Z","size":46211,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T07:30:07.809Z","etag":null,"topics":["agentic-ai","ai","ai-agent","broccolidb","coding-assistant","governed-execution","human-in-the-loop","llm","lumi","mcp","pair-programming","subagents","vscode","vscode-extension"],"latest_commit_sha":null,"homepage":"https://mariecoder.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CardSorting.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":".github/SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"CardSorting","custom":["https://dietcode.io"]}},"created_at":"2026-04-12T21:04:11.000Z","updated_at":"2026-06-24T07:00:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"23e16c96-ea20-429c-8096-5650a3ecbb29","html_url":"https://github.com/CardSorting/LUMI","commit_stats":null,"previous_names":["cardsorting/dietcodemarie","cardsorting/lumi"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CardSorting/LUMI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardSorting%2FLUMI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardSorting%2FLUMI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardSorting%2FLUMI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardSorting%2FLUMI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CardSorting","download_url":"https://codeload.github.com/CardSorting/LUMI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardSorting%2FLUMI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35170542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai","ai-agent","broccolidb","coding-assistant","governed-execution","human-in-the-loop","llm","lumi","mcp","pair-programming","subagents","vscode","vscode-extension"],"created_at":"2026-07-05T22:00:27.938Z","updated_at":"2026-07-05T22:00:40.667Z","avatar_url":"https://github.com/CardSorting.png","language":"TypeScript","funding_links":["https://github.com/sponsors/CardSorting","https://dietcode.io"],"categories":[],"sub_categories":[],"readme":"# LUMI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icons/icon.png\" alt=\"LUMI\" width=\"96\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA calm coding companion — human-in-the-loop agentic pair programming inside VS Code.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eForked from \u003ca href=\"https://github.com/cline/cline\"\u003eCline\u003c/a\u003e · evolved independently by \u003ca href=\"https://github.com/CardSorting\"\u003eCardSorting\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docs/README.md\"\u003eDocumentation\u003c/a\u003e ·\n  \u003ca href=\"#origins--acknowledgments\"\u003eCline lineage\u003c/a\u003e ·\n  \u003ca href=\"CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e ·\n  \u003ca href=\"SECURITY.md\"\u003eSecurity\u003c/a\u003e ·\n  \u003ca href=\"docs/OPENSSF_SCORECARD.md\"\u003eOpenSSF Scorecard\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/CardSorting/LUMI/issues\"\u003eIssues\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/CardSorting/LUMI/discussions\"\u003eDiscussions\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/CardSorting/LUMI\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/CardSorting/LUMI/actions/workflows/codeql.yml\"\u003e\u003cimg src=\"https://github.com/CardSorting/LUMI/actions/workflows/codeql.yml/badge.svg\" alt=\"CodeQL\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://securityscorecards.dev/viewer/?uri=github.com/CardSorting/LUMI\"\u003e\u003cimg src=\"https://api.securityscorecards.dev/projects/github.com/CardSorting/LUMI/badge\" alt=\"OpenSSF Scorecard\" /\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-2.8.1-green\" alt=\"Version\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/VS%20Code-%5E1.84.0-007ACC?logo=visualstudiocode\u0026logoColor=white\" alt=\"VS Code\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/extension-CardSorting.lumi--vscode-purple\" alt=\"VS Marketplace ID\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Open%20VSX-CardSorting.lumi-blue\" alt=\"Open VSX ID\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tools-63-orange\" alt=\"Tools\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/providers-4-blue\" alt=\"Providers\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/docs/demo.gif\" alt=\"LUMI demo — chat, approval, and file edits in VS Code\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n\u003e **Human-in-the-loop by default:** diff before write, checkpoint after tool use, completion gates before “done.”\n\n```bash\n# VS Code Marketplace (CardSorting.lumi-vscode)\ncode --install-extension CardSorting.lumi-vscode\n# Open VSX / Cursor (CardSorting.lumi)\ncode --install-extension CardSorting.lumi\n```\n\n---\n\n## Table of contents\n\n- [About](#about)\n- [Origins \u0026 acknowledgments](#origins--acknowledgments)\n- [Product evolution (full history)](docs/EVOLUTION.md)\n- [Features](#features)\n- [Installation](#installation)\n- [Quick start](#quick-start)\n- [Documentation](#documentation)\n- [Governed subagent execution](#governed-subagent-execution)\n- [Plan \u0026 Act modes](#plan--act-modes)\n- [Built-in slash commands](#built-in-slash-commands)\n- [Lifecycle hooks](#lifecycle-hooks)\n- [Key VS Code settings](#key-vs-code-settings)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [Getting help](#getting-help)\n- [Security](#security)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## About\n\n**LUMI** is a VS Code extension that reads your workspace, plans changes, runs terminal commands, connects MCP servers, and edits files — with **explicit approval at every mutating step**.\n\n| | |\n|---|---|\n| **Publisher** | CardSorting |\n| **VS Marketplace** | `CardSorting.lumi-vscode` |\n| **Open VSX** | `CardSorting.lumi` |\n| **License** | [Apache-2.0](LICENSE) |\n| **Repository** | [github.com/CardSorting/LUMI](https://github.com/CardSorting/LUMI) |\n| **Homepage** | [dietcode.io](https://dietcode.io) |\n| **Changelog** | [changelogv3.md](changelogv3.md) |\n\nTask history and cognitive memory use **BroccoliDB** (`@noorm/broccolidb`) locally. Multi-lane **governed swarms** (`use_subagents`) produce durable receipts, conditional mutation locks, and a merge gate so parallel agents do not false-positive collide on reads.\n\nDesign philosophy: [docs/papers/philosophy.md](docs/papers/philosophy.md) · Stack map: [docs/AGENT_STACK.md](docs/AGENT_STACK.md)\n\n### By the numbers\n\n| Metric | Value |\n|--------|-------|\n| Typed tools | **63** (`src/shared/tools.ts`) |\n| Read-only tools | **12** (`READ_ONLY_TOOLS`) |\n| Wired providers | **4** (`providers.json`) |\n| Slash commands | **10** |\n| Hook kinds | **8** |\n| Agent modes | **plan** · **act** |\n| Governed receipt schema | **v3** |\n\nWorkspace-verified metrics: [docs/papers/companion-brief.md](docs/papers/companion-brief.md)\n\n---\n\n## Origins \u0026 acknowledgments\n\n**LUMI** is spiritually and technically descended from **[Cline](https://github.com/cline/cline)** — the open-source VS Code agent that pioneered human-in-the-loop pair programming (diff-before-write, plan/act, MCP, checkpoints). This repository **forked the Cline VS Code extension codebase** and has since evolved independently under **[CardSorting](https://github.com/CardSorting)**.\n\n[Cline](https://cline.bot) today ships several products — VS Code extension, [CLI](https://github.com/cline/cline/tree/main/cli), [TypeScript SDK](https://github.com/cline/cline/tree/main/sdk), and [Kanban](https://github.com/cline/kanban). **LUMI is not those other repos**; it is a governance-focused fork of the **editor extension agent** lineage only.\n\n### Evolution\n\n| Stage | Name | Notes |\n|-------|------|-------|\n| Upstream | **Cline** | Original agent loop, typed tools, and VS Code integration |\n| Intermediate | **DietCode** | CardSorting fork; sovereign substrate, Spider, roadmap gates; legacy IDs remain |\n| Substrate | **BroccoliDB** | Cognitive memory and structural truth recentered into `@noorm/broccolidb` |\n| Governed lanes | **Receipts v3** | Multi-agent merge gate, per-lane roadmap projection, durable operator receipts |\n| Current | **LUMI** | User-facing brand; extension IDs `CardSorting.lumi` / `CardSorting.lumi-vscode` |\n\n**Full timeline, phase narratives, naming migration tables, and changelog map:** [docs/EVOLUTION.md](docs/EVOLUTION.md).\n\n### Inherited from Cline · built by LUMI\n\n| From Cline (kept) | LUMI additions |\n|-------------------|----------------|\n| Diff-before-write approvals · [Cline: working with files](https://docs.cline.bot/core-workflows/working-with-files) | **Governed subagents** — parallel lanes, mutation locks, merge gates, durable receipts |\n| [Plan / Act modes](https://docs.cline.bot/core-workflows/plan-and-act) | **BroccoliDB** — local cognitive memory and workspace substrate (`dietcode.db`) |\n| [MCP](https://docs.cline.bot/features/mcp) tool extension | **Roadmap \u0026 completion gates** — `ROADMAP.md` steering and `attempt_completion` audit pipeline |\n| Terminal execution with explicit user consent | **Joy-Zoning \u0026 stability policy** — architectural enforcement in the tool path |\n| `@` context mentions, browser tooling, checkpoints | **Product surface** — LUMI branding, [dietcode.io](https://dietcode.io), CardSorting extension IDs |\n\n### Coming from Cline?\n\nIf you used Cline’s VS Code extension, approvals, modes, and MCP should feel familiar. Main differences:\n\n| Cline | LUMI |\n|-------|------|\n| `.clinerules/` project rules | [`.dietcoderules/`](docs/customization/dietcode-rules.mdx) |\n| `.clineignore` | [`.dietcodeignore`](docs/customization/dietcodeignore.mdx) |\n| Cline extension IDs (e.g. `saoudrizwan.claude-dev`) | `CardSorting.lumi` / `CardSorting.lumi-vscode` |\n| CLI, SDK, Kanban (separate Cline products) | **Not bundled here** — use [upstream Cline](https://github.com/cline/cline) |\n\nLegacy identifiers (`cline`, `clineMessages`, Cline doc redirects in `docs/docs.json`) still appear in paths and types where refactors are ongoing; the user-facing product name is **LUMI**. See [legacy inventory](docs/EVOLUTION.md#legacy-inventory--refactor-status) for a full grep-backed list.\n\n### Links \u0026 license\n\n| | |\n|---|---|\n| **Upstream repo** | [github.com/cline/cline](https://github.com/cline/cline) |\n| **Cline docs** | [docs.cline.bot](https://docs.cline.bot) |\n| **Cline community** | [cline.bot](https://cline.bot) · [Discord](https://discord.gg/cline) |\n| **Upstream license** | [Apache-2.0](https://github.com/cline/cline/blob/main/LICENSE) |\n| **This fork’s attribution** | [NOTICE](NOTICE) · [License](#license) |\n\nThank you to the Cline maintainers and contributors for the foundation this project builds on. For LUMI’s design goals vs generic autonomous agents, see [How LUMI differs](docs/README.md#how-lumi-differs). For the full fork timeline and migration reference, see [Product evolution](docs/EVOLUTION.md).\n\n---\n\n## Features\n\n- **Approval gates** — diff before write; you control when mutating tools run\n- **Plan before Act** — `plan_mode_respond` for exploration; `act_mode_respond` for implementation\n- **63 typed tools** — dedicated handlers instead of ad-hoc shell access\n- **Checkpoints** — shadow Git rollback after each tool use\n- **Completion gates** — `attempt_completion` must pass `completionGatePipeline` before “done”\n- **Roadmap steering** — `ROADMAP.md` integration with validation gates\n- **MCP** — connect external tools and prompts\n- **Governed subagents** — parallel lanes with execution modes, merge gate, and durable receipts\n- **Local-first** — settings and secrets under `~/.dietcode/data/`; workspace DB at `./dietcode.db`\n- **Four providers** — OpenRouter, ChatGPT Subscription, NousResearch, Cloudflare Workers AI\n\n**@ mentions** — attach files, folders, problems, terminal output, git diffs, and URLs in chat. Guide: [working-with-files](docs/core-workflows/working-with-files.mdx)\n\n**Project files:** `.dietcoderules/`, `.dietcoderules/hooks/`, `.dietcodeignore`, `.dietcodeworkflows/`, `ROADMAP.md`. See [hooks](docs/customization/hooks.mdx) and [dietcodeignore](docs/customization/dietcodeignore.mdx).\n\n**Enterprise:** [docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md)\n\n---\n\n## Installation\n\n### Prerequisites\n\n- VS Code **1.84+** (or Cursor with extension support)\n- **Git** on `PATH` (for checkpoints)\n- API credentials for one provider (OpenRouter, ChatGPT Subscription, NousResearch, or Cloudflare)\n\n### Install\n\n| Method | Action |\n|--------|--------|\n| **Marketplace** | Extensions → search **LUMI** → install **CardSorting.lumi-vscode** (VS Code) or **CardSorting.lumi** (Open VSX) |\n| **CLI** | `code --install-extension CardSorting.lumi-vscode` |\n| **VSIX** | `npm run package:vsix` → `code --install-extension dist/*.vsix` |\n| **From source** | See [Development](#development) → press **F5** |\n\nProvider setup: [docs/getting-started/quick-start.mdx](docs/getting-started/quick-start.mdx)\n\n\u003e Disable other DietCode forks to avoid activity bar collisions.\n\n---\n\n## Quick start\n\n1. Open the LUMI activity bar panel\n2. Configure a provider in **LUMI Settings → API Configuration**\n3. Describe a task → review each tool proposal → **Approve** or **Reject**\n4. Keep checkpoints enabled for one-click rollback\n\nTutorial: [your-first-project](docs/getting-started/your-first-project.mdx) · Plan/Act guide: [plan-and-act](docs/core-workflows/plan-and-act.mdx)\n\n---\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| **[docs/README.md](docs/README.md)** | Documentation hub — reading paths by audience |\n| [Product evolution](docs/EVOLUTION.md) | Cline → DietCode → LUMI timeline, migration playbook |\n| [Companion brief](docs/papers/companion-brief.md) | Product summary with live metrics |\n| [Governed subagent execution](docs/governed-subagent-execution.md) | Swarm architecture and lifecycle |\n| [Governed execution runbook](docs/governed-execution-runbook.md) | Operator playbook |\n| [Memory \u0026 reasoning](docs/MEMORY_AND_REASONING.md) | BroccoliDB cognitive layer |\n| [Spider forensic engine](docs/architecture/spider-v20-forensic-engine.md) | BroccoliDB analysis substrate |\n| [Security best practices](docs/SECURITY_BEST_PRACTICES.md) | Trust boundaries and hardening |\n| [Roadmap steering](docs/features/roadmap-steering.mdx) | `ROADMAP.md` and completion gates |\n| [Hooks](docs/customization/hooks.mdx) | Lifecycle hook scripts |\n| [Maintainer guide](docs/MAINTAINER.md) | Doc guardrails when code changes |\n| [BroccoliDB](broccolidb/README.md) | Context store package |\n| [BroccoliDB docs](broccolidb/docs/README.md) | Substrate documentation hub |\n\n---\n\n## Governed subagent execution\n\nMulti-lane swarms via `use_subagents` run through a **governed execution harness**: the parent coordinates, lanes execute with declared intent, and a **merge gate** reconciles parallel work before declaring success.\n\n\u003e **North-star invariant:** Private roadmap state is cheap. Workspace roadmap truth is expensive. Only the coordinator may spend it.\n\n```mermaid\nflowchart LR\n  subgraph coord [\"Roadmap \u0026 audit\"]\n    AD[scheduleAdmission]\n    OL[orchestration lease]\n    PF[audit preflight]\n  end\n  subgraph execute [\"Execute\"]\n    R[SubagentRunner]\n    RC[Lane receipt]\n  end\n  subgraph commit [\"Commit\"]\n    MG[MergeGate]\n    WC[coordinator workspace commit]\n    SE[sealReceipt]\n  end\n  AD --\u003e OL --\u003e PF --\u003e R --\u003e RC --\u003e MG --\u003e WC --\u003e SE\n```\n\n| Mode | Lock | Use |\n|------|------|-----|\n| `read_only` | skipped | Code review, inspection |\n| `audit_only` | skipped | Receipt / evidence audit |\n| `mutation` | **required** | File edits, durable state changes |\n\nDeclare in lane prompts: `[execution_mode:read_only] [read_set:src/api.ts]`\n\n| Doc | Audience |\n|-----|----------|\n| [Quick reference](docs/governed-roadmap-projection-quickref.md) | Patch tags, one page |\n| [Architecture](docs/governed-subagent-execution.md) | Full lifecycle |\n| [Runbook](docs/governed-execution-runbook.md) | Violations, retry flow |\n| [Schema](docs/governed-execution-schema.md) | Receipt v3 fields |\n\n---\n\n## Plan \u0026 Act modes\n\nLUMI runs in **`plan`** or **`act`** mode. Each mode can use a different provider and model.\n\n| Mode | Response tool | Behavior |\n|------|---------------|----------|\n| **Plan** | `plan_mode_respond` | Strategy, exploration, read-only tools |\n| **Act** | `act_mode_respond` | Implementation — mutating tools with approval |\n\nTypical flow: gather context in Plan → approve direction → Act executes writes → `attempt_completion` through completion gates.\n\nGuide: [docs/core-workflows/plan-and-act.mdx](docs/core-workflows/plan-and-act.mdx)\n\n---\n\n## Built-in slash commands\n\nTyped at the start of a message (`/command`):\n\n| Command | Purpose |\n|---------|---------|\n| `/newtask` | Fresh task context |\n| `/compact` | Condense conversation history |\n| `/deep-planning` | Extended planning pass |\n| `/roadmap` | Roadmap steering actions |\n| `/explain-changes` | Summarize what changed |\n\n**10** commands total — source: `SUPPORTED_DEFAULT_COMMANDS` in `src/core/slash-commands/index.ts`. Custom workflows: `.dietcodeworkflows/`\n\n---\n\n## Lifecycle hooks\n\n**8** hook kinds in `VALID_HOOK_TYPES`. Scripts live under **`.dietcoderules/hooks/`** (workspace or global).\n\n| Hook | Fires when |\n|------|------------|\n| `PreToolUse` | Before a tool executes (can cancel) |\n| `PostToolUse` | After a tool executes |\n| `TaskStart` | Task begins |\n| `TaskComplete` | Task completes |\n\nGuide: [docs/customization/hooks.mdx](docs/customization/hooks.mdx)\n\n---\n\n## Key VS Code settings\n\n| Setting | Default | Purpose |\n|---------|---------|---------|\n| `lumi.roadmap.enabled` | `true` | Master switch for ROADMAP.md steering |\n| `lumi.roadmap.autoBootstrap` | `true` | Create `ROADMAP.md` from workspace evidence |\n| `lumi.roadmap.failClosedCompletionGates` | `true` | Block completion when gate evaluation fails |\n\nDetails: [docs/features/roadmap-steering.mdx](docs/features/roadmap-steering.mdx)\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n  subgraph ext [\"LUMI extension\"]\n    WP[webview-ui] \u003c--\u003e CT[Controller]\n    CT --\u003e TK[Task loop]\n    TK --\u003e TL[ToolExecutorCoordinator]\n    TL --\u003e GSC[GovernedSwarmCoordinator]\n    GSC --\u003e MG[MergeGate]\n  end\n  subgraph host [\"VS Code host\"]\n    HB[hostbridge]\n    TL --\u003e HB\n  end\n  subgraph store [\"Local store\"]\n    BDB[\"@noorm/broccolidb\"]\n    TK --\u003e BDB\n  end\n```\n\n| Package | Path | Role |\n|---------|------|------|\n| **LUMI extension** | repo root | VS Code agent — `CardSorting.lumi-vscode` / `CardSorting.lumi` |\n| **BroccoliDB** | `broccolidb/` | Context store, runtime, Spider |\n\n**Stack:** TypeScript extension host · React webview · Protobuf host bridge · `buildApiHandler` (4 providers) · BroccoliDB SQLite · governed receipt schema v3 · Biome · Mocha / Playwright tests · Mintlify docs.\n\nCanonical map: [docs/AGENT_STACK.md](docs/AGENT_STACK.md)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/CardSorting/LUMI.git\ncd LUMI\nnpm run install:all    # root + webview-ui\nnpm run protos         # required before first build\nnpm run dev            # watch extension + typecheck\nnpm run dev:webview    # separate terminal — webview HMR\n```\n\nPress **F5** in VS Code → Extension Development Host. Package: `npm run package` → `dist/*.vsix`.\n\n| Script | Purpose |\n|--------|---------|\n| `npm run check-types` | TypeScript — extension + webview |\n| `npm run lint` | Biome + proto lint |\n| `npm test` | Unit + integration tests |\n| `npm run ci:check-all` | Types, lint, format, roadmap audit, doc guardrails |\n| `npm run docs:check-all` | All doc guardrails + Mintlify links |\n\nGoverned execution tests: `npm run test:unit -- --grep \"governed execution\"`\n\n### Quality gates\n\n`npm run ci:check-all` runs types, lint, format, roadmap audit, and doc guardrails in parallel. Doc checks include `docs:check-root-readme`, `docs:check-readme-metrics`, and **`npm run docs:check-all`**.\n\nWhen you change tools, providers, or governed execution, update docs per [docs/MAINTAINER.md](docs/MAINTAINER.md).\n\nFull guide: [CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| Extension missing from sidebar | Install **CardSorting.lumi-vscode** or **CardSorting.lumi**; `Developer: Reload Window` |\n| Checkpoints fail | Install Git; ensure `git` is on `PATH` |\n| Slow on large repos | Add [`.dietcodeignore`](docs/customization/dietcodeignore.mdx) |\n| Provider auth errors | Re-open LUMI Settings → re-enter API key |\n| Completion blocked | Run `/roadmap validate`; check `lumi.roadmap.*` settings |\n| Subagent merge blocked | See [governed runbook](docs/governed-execution-runbook.md) |\n| Reset extension state | Close VS Code; remove `~/.dietcode/data/`; reload window |\n\n---\n\n## Getting help\n\n| Channel | Link |\n|---------|------|\n| **Documentation** | [docs/README.md](docs/README.md) |\n| **Changelog** | [CHANGELOG.md](CHANGELOG.md) |\n| **Discussions** | [GitHub Discussions](https://github.com/CardSorting/LUMI/discussions) |\n| **Bug reports** | [GitHub Issues](https://github.com/CardSorting/LUMI/issues/new?template=bug_report.yml) |\n| **Security (private)** | [SECURITY.md](SECURITY.md) |\n\nInclude VS Code version, LUMI **2.8.1**, provider used, and steps to reproduce.\n\n---\n\n## Security\n\n| Boundary | Enforcement |\n|----------|-------------|\n| Mutating tools | Approval UI + diff before write |\n| Secrets | `~/.dietcode/data/secrets.json` (mode `0600`) |\n| Settings \u0026 state | `~/.dietcode/data/` |\n| Workspace memory | `./dietcode.db` (BroccoliDB SQLite) |\n| Governed receipts | `{taskDir}/subagent_executions/` |\n| Hooks | `.dietcoderules/hooks/` — `PreToolUse` can cancel tool calls |\n\nDetails: [docs/SECURITY_BEST_PRACTICES.md](docs/SECURITY_BEST_PRACTICES.md) · Report vulnerabilities via [SECURITY.md](SECURITY.md)\n\n---\n\n## FAQ\n\n**Is LUMI fully autonomous?** No — it assumes a human approver for mutating work.\n\n**Which extension ID do I use?** `CardSorting.lumi-vscode` on VS Marketplace; `CardSorting.lumi` on Open VSX / Cursor.\n\n**Where is my data stored?** Settings and secrets in `~/.dietcode/data/`; workspace cognitive memory in `./dietcode.db`.\n\n**Can read-only subagent lanes share files?** Yes — lock collisions are write-scoped only.\n\n**How do I contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md) — squash merges on `main`, Conventional Commits for PR titles.\n\n---\n\n## Contributing\n\nWe welcome issues, docs improvements, and pull requests. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.\n\n- **Code of conduct:** be respectful in issues and discussions\n- **PRs:** squash merge only; PR title must follow Conventional Commits\n- **Docs:** run `npm run docs:check-all` when changing tools, providers, or architecture\n- **Governance:** [GOVERNANCE.md](GOVERNANCE.md)\n\n---\n\n## License\n\n[Apache-2.0](LICENSE) — Copyright CardSorting and Cline Bot Inc. (see [NOTICE](NOTICE)).\n\nThis project is a derivative work of [Cline](https://github.com/cline/cline) (Apache-2.0 © Cline Bot Inc. and contributors). See [Origins \u0026 acknowledgments](#origins--acknowledgments) above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardsorting%2Flumi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcardsorting%2Flumi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardsorting%2Flumi/lists"}