@mc1global/opencode-jarvis 0.10.0 → 0.12.0

package/README.md

@@ -4,31 +4,44 @@ A native [OpenCode](https://opencode.ai) plugin providing multi-agent developmen
 
 Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
 
+---
+
 ## Prerequisites
 
-| Requirement | Purpose | Required? |
-|---|---|---|
-| [OpenCode](https://opencode.ai) CLI | Host runtime for the plugin | **Yes** |
-| [Bun](https://bun.sh) >= 1.0 | Production runtime (bun:sqlite, MCP server) | **Yes** |
-| Node.js >= 20 | Test runner (Jest + ESM) | Dev only |
-| [Ollama](https://ollama.ai) | Local embedding generation for RAG | For RAG features |
-| `embeddinggemma` model | Default embedding model (768 dims) | For RAG features |
-| [Dagger CLI](https://docs.dagger.io/install) | Container-based CI/CD gate execution | Optional |
-| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | Azure DevOps board sync | Optional |
+- **[OpenCode](https://opencode.ai) CLI** — Host runtime for the plugin (**required**)
+- **[Bun](https://bun.sh) >= 1.0** — Production runtime for bun:sqlite (**required**)
+- **[Ollama](https://ollama.ai)** + `embeddinggemma` model — Local embeddings for RAG semantic search (**required for RAG**)
+- **Node.js >= 20** — Test runner only (dev)
+- **[Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** — Azure DevOps board sync (optional)
+- **[Dagger CLI](https://docs.dagger.io/install)** — Container CI/CD gate execution (optional)
+
+---
 
 ## Quick Start
 
-### 1. Install prerequisites
+### Step 1 — Install prerequisites
+
+Choose your operating system below. Each section includes both **manual commands** and a link to an **automated setup script** that handles everything.
+
+#### macOS
+
+**Automated** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-macos.sh | bash
+```
+
+Or download `scripts/setup/setup-macos.sh` from the repository and run it locally.
 
-**macOS:**
+**Manual:**
 
 ```bash
 # Bun (required — SQLite runtime)
 curl -fsSL https://bun.sh/install | bash
 
-# Ollama (required — RAG semantic search)
+# Ollama + embedding model (required for RAG)
 brew install ollama
-ollama serve                    # start the server
+ollama serve                    # start the server (keep running)
 ollama pull embeddinggemma      # download the embedding model
 
 # Optional: Azure DevOps sync
@@ -38,42 +51,174 @@ brew install azure-cli && az login
 brew install dagger/tap/dagger
 ```
 
-**Linux:**
+#### Linux (Ubuntu/Debian/Fedora/Arch)
+
+**Automated** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-linux.sh | bash
+```
+
+Or download `scripts/setup/setup-linux.sh` from the repository and run it locally.
+
+**Manual:**
+
+```bash
+# Bun (required)
+curl -fsSL https://bun.sh/install | bash
+
+# Ollama + embedding model (required for RAG)
+curl -fsSL https://ollama.ai/install.sh | sh
+ollama serve                    # start the server (keep running)
+ollama pull embeddinggemma      # download the embedding model
+
+# Optional: Azure CLI (Debian/Ubuntu)
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
+
+# Optional: Dagger CLI
+curl -fsSL https://dl.dagger.io/dagger/install.sh | sh
+```
+
+#### Windows (WSL)
+
+> OpenCode recommends Windows Subsystem for Linux (WSL) for the best experience.
+> See the [OpenCode WSL guide](https://opencode.ai/docs/windows-wsl) for details.
+
+**Step 0 — Install WSL** (if you haven't already):
+
+Open **PowerShell as Administrator** and run:
+
+```powershell
+wsl --install
+```
+
+Restart your computer, then open the **Ubuntu** terminal app.
+
+**Step 1 — Run the setup script inside WSL:**
+
+```bash
+# From your WSL terminal (Ubuntu):
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-wsl.sh | bash
+```
+
+Or download `scripts/setup/setup-wsl.sh` from the repository and run it inside WSL.
+
+**Manual (inside WSL terminal):**
 
 ```bash
+# OpenCode CLI
+curl -fsSL https://opencode.ai/install | bash
+
+# Bun (required)
 curl -fsSL https://bun.sh/install | bash
+
+# Ollama + embedding model (required for RAG)
 curl -fsSL https://ollama.ai/install.sh | sh
-ollama serve && ollama pull embeddinggemma
+ollama serve                    # start the server (keep running in a separate terminal)
+ollama pull embeddinggemma      # download the embedding model
+
+# Optional: Azure CLI
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
 ```
 
-### 2. Add the plugin to your project
+> **WSL performance tip:** For best results, keep your project files in the WSL
+> filesystem (`~/code/my-project`) rather than on `/mnt/c/`. See
+> [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl) for more.
+
+---
 
-Create `opencode.json` in your project root:
+### Step 2 — Add the plugin to your project
+
+Create an `opencode.json` file **in your project root directory**:
+
+```
+your-project/              <-- your project root
+  opencode.json            <-- CREATE THIS FILE HERE
+  package.json
+  src/
+  ...
+```
+
+Content of `opencode.json`:
 
 ```json
 {
-  "plugin": ["@mc1global/opencode-jarvis"]
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@mc1global/opencode-jarvis"],
+  "command": {
+    "config": {
+      "template": "Use JARVIS config tools to view and modify configuration. Run config-read to show current settings, then config-write to apply changes. $ARGUMENTS",
+      "description": "View or modify JARVIS configuration"
+    },
+    "healthcheck": {
+      "template": "Run the JARVIS healthcheck diagnostic and provide actionable guidance for any issues found. $ARGUMENTS",
+      "description": "Run JARVIS environment diagnostics"
+    },
+    "sync-azure": {
+      "template": "Execute the JARVIS Azure DevOps sync workflow — check connectivity, review sync status, and synchronize cards/epics/sprints. $ARGUMENTS",
+      "description": "Sync kanban board with Azure DevOps"
+    },
+    "start-card": {
+      "template": "Start working on a JARVIS kanban card. Handle the full lifecycle: check status, assign agent and sprint, move to doing, and start a context session. $ARGUMENTS",
+      "description": "Start working on a kanban card"
+    }
+  }
 }
 ```
 
+The `"command"` block registers JARVIS slash commands (`/config`, `/healthcheck`, `/sync-azure`, `/start-card`) so OpenCode shows them in the command list. The plugin's `command.execute.before` hook enriches the prompt with detailed JARVIS-specific instructions when executed.
+
 OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
 
-### 3. First launch (automatic)
+#### Where exactly does `opencode.json` go?
+
+OpenCode supports config files at **two levels**. Choose one (or both — they merge):
+
+**Project-level** (recommended for teams):
+
+```
+/home/you/code/my-project/opencode.json       # Linux/WSL
+/Users/you/code/my-project/opencode.json       # macOS
+```
+
+This is committed to git so your whole team gets the plugin. OpenCode looks for this file in the current directory or traverses up to the nearest git root.
+
+**Global-level** (applies to ALL your projects):
+
+```
+~/.config/opencode/opencode.json               # Linux/macOS/WSL
+```
+
+Use this if you want JARVIS active on every project without adding `opencode.json` to each one.
+
+> **Precedence:** Project config overrides global config for conflicting keys.
+> Non-conflicting settings from both are merged. See the
+> [OpenCode config docs](https://opencode.ai/docs/config#locations) for details.
+
+---
+
+### Step 3 — First launch (automatic)
 
 Run `opencode` in your project directory. JARVIS initializes everything:
 
+```bash
+cd /path/to/your/project    # must contain opencode.json (or have one globally)
+opencode
 ```
-What JARVIS creates automatically on first load:
 
-  .jarvis/                SQLite database + RAG indexes (local, gitignored)
-  config/jarvis.yaml      Default configuration (commit this)
-  obsidian-vault/         Documentation skeleton (commit this)
-  AGENTS.md               Agent operational guide (commit this)
+On first load, JARVIS creates these files and directories automatically:
+
+```
+your-project/
+  .jarvis/                  SQLite database + RAG indexes (local, gitignored)
+  config/jarvis.yaml        Default configuration (commit this)
+  obsidian-vault/           Documentation skeleton (commit this)
+  AGENTS.md                 Agent operational guide (commit this)
 ```
 
 On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
 
-### 4. First session — recommended steps
+### Step 4 — First session recommended steps
 
 The agent should run these on first use (JARVIS prompts automatically):
 
@@ -82,7 +227,7 @@ The agent should run these on first use (JARVIS prompts automatically):
 3. **`rag-oracle-index`** tool with `directory="obsidian-vault"` — Index documentation
 4. **`kanban-board-view`** tool — See the kanban board
 
-### 5. Verify your setup
+### Step 5 — Verify your setup
 
 The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
 
@@ -102,130 +247,108 @@ Summary: 6 pass, 2 warn, 0 fail (8 total)
 Status: HEALTHY
 ```
 
-## What Lives Where
+---
+
+## File Locations Reference
 
-### In Git (committed, shared with team)
+### In your project (committed to git, shared with team)
 
 ```
-opencode.json              Plugin declaration
-config/jarvis.yaml         Configuration (auto-created, then customized)
-AGENTS.md                  Agent operational guide (auto-generated)
-obsidian-vault/            Documentation vault
-.opencode/skills/          Workflow skills for the agent
-.opencode/commands/        Slash commands (/healthcheck, /sync-azure, /start-card)
+your-project/
+  opencode.json              Plugin declaration (Step 2 above)
+  config/jarvis.yaml         Configuration (auto-created, then customized)
+  AGENTS.md                  Agent operational guide (auto-generated)
+  obsidian-vault/            Documentation vault
 ```
 
-### Local per machine (NOT in git)
+### Local per machine (NOT committed — add to .gitignore)
 
 ```
-.jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
-.jarvis/rag/               Vectra vector store (RAG embeddings)
+your-project/
+  .jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
+  .jarvis/rag/               Vectra vector store (RAG embeddings)
 ```
 
-### Global (shared across all projects)
+### Global (shared across all your projects)
 
 ```
-~/.jarvis/registry.db      Workspace registry (cross-project)
-~/.cache/opencode/         Plugin npm cache (managed by OpenCode)
+~/.config/opencode/opencode.json   Global OpenCode config (optional)
+~/.jarvis/registry.db              Workspace registry (cross-project)
+~/.cache/opencode/node_modules/    Plugin npm cache (managed by OpenCode)
 ```
 
-## Available Skills and Commands
+---
 
-### Skills (loaded on demand via `skill()` tool)
+## Setup Scripts
 
-| Skill | Description |
-|---|---|
-| `jarvis-onboarding` | Setup, healthcheck, RAG indexing, tool reference |
-| `jarvis-kanban` | Card lifecycle, grooming, sprints, gate tasks |
-| `jarvis-azure-sync` | Azure DevOps push/pull/sync, PR creation |
+Automated setup scripts are available in the `scripts/setup/` directory of this repository. Each script installs all non-npm prerequisites for JARVIS (Bun, Ollama, embedding model) and optionally Azure CLI and Dagger:
 
-### Commands (slash commands in any session)
+- **`scripts/setup/setup-macos.sh`** — macOS with Homebrew
+- **`scripts/setup/setup-linux.sh`** — Ubuntu, Debian, Fedora, Arch Linux
+- **`scripts/setup/setup-wsl.sh`** — Windows Subsystem for Linux (includes OpenCode CLI install + WSL detection)
 
-| Command | Description |
-|---|---|
-| `/healthcheck` | Run diagnostics with actionable fix guidance |
-| `/sync-azure` | Execute Azure DevOps sync workflow |
-| `/start-card CD-XXX` | Start working on a kanban card (full lifecycle) |
+Each script is interactive, checks for existing installations, and clearly reports what it does.
 
-## Installation (Local Development)
+---
 
-```bash
-# Clone
-git clone <repo-url> jarvis-plugin
-cd jarvis-plugin
+## Available Commands
 
-# Install dependencies
-npm install
+Commands are available in any OpenCode session:
 
-# Build
-npm run build
+- **`/healthcheck`** — Run diagnostics with actionable fix guidance
+- **`/sync-azure`** — Execute Azure DevOps sync workflow
+- **`/start-card CD-XXX`** — Start working on a kanban card (full lifecycle)
+- **`/config`** — Agent-guided configuration wizard
 
-# Configure in OpenCode (add to your opencode.json)
-{
-  "plugin": {
-    "jarvis": {
-      "path": "/path/to/jarvis-plugin"
-    }
-  }
-}
-```
-
-## MCP Server Mode
-
-JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
-
-```bash
-bun run src/mcp-server.ts --directory /path/to/project
-```
+## Available Skills (loaded on demand via `skill()` tool)
 
-Configure tool filtering in `config/jarvis.yaml`:
+- **`jarvis-kanban`** — Card lifecycle, grooming, sprints, gate tasks
+- **`jarvis-azure-sync`** — Azure DevOps push/pull/sync, PR creation
+- **`jarvis-onboarding`** — Setup, healthcheck, RAG indexing, tool reference
 
-```yaml
-mcp-server:
-  transport: "stdio"
-  enabledTools: null  # null = all tools, or list specific tool names
-```
+---
 
 ## Features
 
-### 113 Tools across 14 categories
-
-| Category | Count | Key Tools |
-|---|---|---|
-| **Context Memory** | 8 | `context-session-*`, `context-todo-*`, `context-note-*`, `context-search` |
-| **Kanban Cards** | 12 | `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief` |
-| **Kanban Board** | 15 | `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check` |
-| **Kanban Grooming** | 4 | `kanban-grooming-validate`, `kanban-card-scope-doc/criteria/estimate`, `kanban-card-gate` |
-| **Governance** | 2 | `governance-validate`, `governance-policies` |
-| **Token Metrics** | 7 | `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate` |
-| **RAG** | 8 | `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index` |
-| **Data** | 3 | `data-yaml-get`, `data-json-get`, `data-csv-query` |
-| **Vault** | 11 | `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage` |
-| **Agent** | 8 | `agent-sessions/send/notify/dispatch`, `agent-register/profile/list/spawn` |
-| **Domain Map** | 2 | `domain-map-analyze`, `domain-map-view` |
-| **Workspace** | 4 | `workspace-info/list/update/link` |
-| **Environment** | 6 | `env-init/create/list/status/merge/delete` |
-| **Pipeline** | 10 | `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold` |
-| **Azure Sync** | 10 | `azure-sync-*`, `azure-pr-*` |
-| **Bootstrap** | 3 | `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands` |
-
-### 5 Hooks
-
-| Hook | Type | Description |
-|---|---|---|
-| **Context Compacting** | `experimental.session.compacting` | Injects session context when context window compacts |
-| **First-Run Guide** | `experimental.chat.system.transform` | Injects setup instructions on first session |
-| **Shell Environment** | `shell.env` | Injects JARVIS env vars into shell sessions |
-| **Guardrails** | `tool.execute.before` | Governance policy enforcement on tool invocations |
-| **Event Handlers** | `event` | Token usage tracking and cross-context event handling |
+### 115 Tools across 15 categories
+
+- **Context Memory** (8) — `context-session-*`, `context-todo-*`, `context-note-*`, `context-search`
+- **Kanban Cards** (12) — `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief`
+- **Kanban Board** (15) — `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check`
+- **Kanban Grooming** (4) — `kanban-grooming-validate`, `kanban-card-scope-doc/criteria/estimate`, `kanban-card-gate`
+- **Governance** (2) — `governance-validate`, `governance-policies`
+- **Token Metrics** (7) — `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate`
+- **RAG** (8) — `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index`
+- **Data** (3) — `data-yaml-get`, `data-json-get`, `data-csv-query`
+- **Vault** (11) — `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage`
+- **Agent** (8) — `agent-sessions/send/notify/dispatch`, `agent-register/profile/list/spawn`
+- **Domain Map** (2) — `domain-map-analyze`, `domain-map-view`
+- **Workspace** (4) — `workspace-info/list/update/link`
+- **Environment** (6) — `env-init/create/list/status/merge/delete`
+- **Pipeline** (10) — `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold`
+- **Azure Sync** (10) — `azure-sync-*`, `azure-pr-*`
+- **Bootstrap** (3) — `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands`
+
+### 8 Hooks
+
+- **Context Compacting** — Injects session context when context window compacts
+- **First-Run Guide** — Injects setup instructions on first session
+- **Shell Environment** — Injects JARVIS env vars into shell sessions
+- **Guardrails** — Governance policy enforcement on tool invocations
+- **Event Handlers** — Token usage tracking and cross-context event handling
+- **Execution Journal** — Crash recovery via tool execution state tracking
+- **Slash Commands** — `/healthcheck`, `/sync-azure`, `/start-card`, `/config`
+- **Config Command** — Agent-guided configuration editing
 
 ### 13 Governance Policies
 
 Runtime-enforced via `tool.execute.before` hook. Covers: CSV/YAML/env file access, force push protection, SQLite CLI blocking, destructive shell ops, credential file protection, and more.
 
+---
+
 ## Configuration
 
-All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults. Available sections:
+All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults:
 
 ```yaml
 # RAG embedding settings
@@ -267,32 +390,35 @@ pipeline:
 
 Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
 
+---
+
+## MCP Server Mode
+
+JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
+
+```bash
+bun run src/mcp-server.ts --directory /path/to/project
+```
+
+Configure tool filtering in `config/jarvis.yaml` under `mcp-server`.
+
+---
+
 ## Architecture
 
 ```
 jarvis-plugin/
   src/
-    domain/                  # Pure business logic, zero external deps
-      shared/                # WorkspaceId, EntityId, Result<T>
-      context-memory/        # Session, Todo, Note entities + services
-      kanban/                # Card state machine, Sprint, Epic, Grooming
-      governance/            # 13 policy rules, validation service
-      token-metrics/         # Token usage tracking, cost-per-card/sprint, budget alerts
-      rag/                   # RAG value objects, domain services
-      vault/                 # Vault document, section, table entities
-      domain-map/            # Bounded context detection, domain analysis
-      workspace-registry/    # Cross-project workspace registration
-      environment/           # Container-use environment management
-      agent-registry/        # Agent profile management
-      pipeline/              # CI/CD pipeline entities, gate enforcement
-      config/                # Configuration value objects + defaults
-    application/             # Use cases with DTOs (11 bounded contexts)
-    infrastructure/          # SQLite repos, Vectra, Ollama, FS adapters
-    tools/                   # 20 tool modules (113 tools total)
-    hooks/                   # 5 hooks (guardrails, compacting, first-run, events, shell-env)
-    tests/                   # 2,520+ tests across 85 test suites
-  obsidian-vault/            # Structured documentation
-  config/                    # jarvis.yaml configuration
+    domain/                  Pure business logic, zero external deps (11 bounded contexts)
+    application/             Use cases with DTOs
+    infrastructure/          SQLite repos, Vectra, Ollama, FS adapters
+    tools/                   20 tool modules (115 tools total)
+    hooks/                   8 hooks
+    tests/                   2,670+ tests across 93 test suites
+  scripts/setup/             Per-OS automated setup scripts
+  obsidian-vault/            Structured documentation
+  config/                    jarvis.yaml configuration
+  templates/                 AGENTS.md template engine
 ```
 
 **Key constraints:**
@@ -304,6 +430,8 @@ jarvis-plugin/
 - 11 bounded contexts with strict DDD boundaries
 - Production runtime: Bun (`bun:sqlite`); Tests: Node.js + Jest
 
+---
+
 ## Storage
 
 All data is stored locally:
@@ -313,30 +441,48 @@ All data is stored locally:
 - `.jarvis/rag/<workspace>/index-manifest.json` — File index registry (incremental indexing)
 - `~/.jarvis/registry.db` — Central workspace registry (cross-project)
 
-The `JARVIS_HOME` environment variable overrides `~/.jarvis/` default.
+The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
+
+---
 
-## Development
+## Local Development
 
 ```bash
+# Clone
+git clone <repo-url> jarvis-plugin
+cd jarvis-plugin
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
 # Run all tests
 npm test
 
 # Type check (zero errors required)
 npm run lint
 
-# Build
-npm run build
-
 # Single test file
 node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
 
 # Watch mode
 npm run dev
 
-# RAG index (standalone, bypasses MCP timeouts)
-npx tsx scripts/rag-index.ts --clear
+# Configure for local plugin development in OpenCode:
+# Add to your project's opencode.json:
+{
+  "plugin": {
+    "jarvis": {
+      "path": "/absolute/path/to/jarvis-plugin"
+    }
+  }
+}
 ```
 
+---
+
 ## Troubleshooting
 
 **Ollama connection refused**
@@ -352,10 +498,17 @@ npx tsx scripts/rag-index.ts --clear
 - Try full reindex: use `rag-index` tool with `clear: true`
 
 **Plugin not loading in OpenCode**
-- Verify `opencode.json` has `"plugin": ["@mc1global/opencode-jarvis"]`
+- Verify `opencode.json` exists in your project root (or globally at `~/.config/opencode/opencode.json`)
+- Verify it contains `"plugin": ["@mc1global/opencode-jarvis"]`
 - Check `~/.cache/opencode/node_modules/` for the installed package
 - Ensure Bun is installed (required for production runtime)
 
+**Windows: Plugin not loading**
+- JARVIS must run inside WSL, not native Windows PowerShell/cmd
+- Install prerequisites inside WSL using `setup-wsl.sh`
+- Run `opencode` from your WSL terminal
+- See [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl)
+
 **MCP server fails to start**
 - Ensure Bun is installed: `bun --version`
 - Run manually: `bun run src/mcp-server.ts --directory .`
@@ -365,30 +518,20 @@ npx tsx scripts/rag-index.ts --clear
 - Ensure Azure CLI is authenticated: `az login`
 - Test connectivity: use `azure-sync-config` tool
 
-**tsc errors in development**
-- Remember: `exactOptionalPropertyTypes` requires conditional spreading for optional props
-- Use `import type` for type-only imports (`verbatimModuleSyntax`)
-- Array indexing returns `T | undefined` (`noUncheckedIndexedAccess`)
+---
 
 ## Dependencies
 
-| Dependency | Purpose |
-|---|---|
-| `bun:sqlite` | Local SQLite database (production) |
-| `better-sqlite3` | SQLite for tests (Node.js) |
-| `js-yaml` | YAML file parsing |
-| `vectra` | Local vector store for RAG |
-| `ollama` | Embedding generation via local Ollama |
-| `@langchain/textsplitters` | Code-aware text chunking for RAG |
-| `@opencode-ai/plugin` | OpenCode plugin SDK (peer dependency) |
-| `@modelcontextprotocol/sdk` | MCP server protocol (optional) |
-
-## Test Coverage
-
-- **2,520+ tests** across 85 test suites
-- Domain, application, infrastructure, and tools layers tested
-- In-memory SQLite for fast, isolated integration tests
-- `tsc --noEmit` zero errors with all strict flags
+- `bun:sqlite` — Local SQLite database (production)
+- `better-sqlite3` — SQLite for tests (Node.js)
+- `js-yaml` — YAML file parsing
+- `vectra` — Local vector store for RAG
+- `ollama` — Embedding generation via local Ollama
+- `@langchain/textsplitters` — Code-aware text chunking for RAG
+- `@opencode-ai/plugin` — OpenCode plugin SDK (peer dependency)
+- `@modelcontextprotocol/sdk` — MCP server protocol (optional)
+
+---
 
 ## License
 

package/dist/application/bootstrap/use-cases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/bootstrap/use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAI5E,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AA8DD;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,UAAQ,GAAG,eAAe;IAiDrF;;OAEG;IACH,WAAW,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe;CAUhE;AAiCD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBhE"}
+{"version":3,"file":"use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/bootstrap/use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAI5E,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AA8DD;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,UAAQ,GAAG,eAAe;IAiDrF;;OAEG;IACH,WAAW,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe;CAUhE;AAkCD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBhE"}