@mc1global/opencode-jarvis 0.13.1 → 0.14.0

package/README.md

@@ -1,499 +1,565 @@
-# JARVIS Framework - OpenCode Edition
+# @mc1global/opencode-jarvis
 
-**A production-ready framework for multi-agent LLM development with semantic code search, SOLID/DDD architecture, and 90-98% token optimization.**
+> **v0.15.0** — SRP enforcement: 9 oversized files split, enum-values facade across all 13 bounded contexts, composition root extracted. See [CHANGELOG.md](CHANGELOG.md)
 
-[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![OpenCode](https://img.shields.io/badge/editor-OpenCode-green.svg)](https://github.com/opencode-ai/opencode)
-[![License](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)
-[![Status](https://img.shields.io/badge/status-production-success.svg)](https://github.com/MC1Innovation/jarvis-opencode)
+A native [OpenCode](https://opencode.ai) plugin providing multi-agent development infrastructure: session memory, kanban project management, governance guardrails, automatic token-per-card cost tracking with budget alerts, RAG semantic search, Obsidian vault management, domain map analysis, workspace registry, environment management, CI/CD pipelines, Azure DevOps sync, and structured data tools.
 
-## 🚀 Quick Start
+Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
 
-### Prerequisites
+---
 
-- Python 3.11+
-- Node.js 18+ and npm
-- Git
-- 8GB RAM minimum
-- macOS, Windows, or Linux
+## Prerequisites
 
-### Installation
+- **[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)
 
-```bash
-# Clone from Azure DevOps
-git clone https://dev.azure.com/MC1Innovation/JARVIS/_git/jarvis-opencode
-cd jarvis-opencode
+---
+
+## Quick Start
+
+### 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.
 
-# Run automated installer (25-45 minutes)
-python scripts/setup/jarvis_automated_installer.py --workspace-name=JARVIS --yes
+#### macOS
 
-# This will:
-# ✅ Setup Python environment with uv
-# ✅ Install all dependencies
-# ✅ Configure Ollama and models
-# ✅ Index ORACLE governance documents
-# ✅ Smart index JARVIS codebase (auto-detect Python project)
-# ✅ Setup Domain Map V2 (multi-language)
-# ✅ Configure 36 OpenCode tools
-# ✅ Initialize Context Memory database
-# ✅ Setup Command Intelligence
-# ✅ Validate installation
+**Automated** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-macos.sh | bash
 ```
 
-### Platform-Specific Instructions
+Or download `scripts/setup/setup-macos.sh` from the repository and run it locally.
 
-<details>
-<summary><b>🍎 macOS</b></summary>
+**Manual:**
 
 ```bash
-# Prerequisites
-brew install python@3.11 node git
+# Bun (required — SQLite runtime)
+curl -fsSL https://bun.sh/install | bash
 
-# Clone and setup
-git clone https://dev.azure.com/MC1Innovation/JARVIS/_git/jarvis-opencode
-cd jarvis-opencode
-python scripts/setup/jarvis_automated_installer.py --workspace-name=JARVIS --yes
-```
+# Ollama + embedding model (required for RAG)
+brew install ollama
+ollama serve                    # start the server (keep running)
+ollama pull embeddinggemma      # download the embedding model
 
-</details>
+# Optional: Azure DevOps sync
+brew install azure-cli && az login
 
-<details>
-<summary><b>🪟 Windows</b></summary>
+# Optional: CI/CD pipeline execution
+brew install dagger/tap/dagger
+```
 
-```powershell
-# Prerequisites (use Windows Terminal or PowerShell)
-# Install Python 3.11+ from python.org
-# Install Node.js from nodejs.org
-# Install Git from git-scm.com
+#### Linux (Ubuntu/Debian/Fedora/Arch)
 
-# Clone and setup
-git clone https://dev.azure.com/MC1Innovation/JARVIS/_git/jarvis-opencode
-cd jarvis-opencode
-python scripts\setup\jarvis_automated_installer.py --workspace-name=JARVIS --yes
+**Automated** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-linux.sh | bash
 ```
 
-</details>
+Or download `scripts/setup/setup-linux.sh` from the repository and run it locally.
 
-<details>
-<summary><b>🐧 Linux (Ubuntu/Debian)</b></summary>
+**Manual:**
 
 ```bash
-# Prerequisites
-sudo apt update
-sudo apt install python3.11 python3.11-venv nodejs npm git
+# 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
 
-# Clone and setup
-git clone https://dev.azure.com/MC1Innovation/JARVIS/_git/jarvis-opencode
-cd jarvis-opencode
-python3 scripts/setup/jarvis_automated_installer.py --workspace-name=JARVIS --yes
+# 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
 ```
 
-</details>
+#### 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.
 
-### OpenCode Integration Setup
+**Step 0 — Install WSL** (if you haven't already):
 
-After installing the JARVIS Framework, configure it as an MCP (Model Context Protocol) server in OpenCode to access all tools and features directly from your editor.
+Open **PowerShell as Administrator** and run:
 
-#### 1. Install the NPM Package
+```powershell
+wsl --install
+```
 
-First, check for the latest version and install:
+Restart your computer, then open the **Ubuntu** terminal app.
+
+**Step 1 — Run the setup script inside WSL:**
 
 ```bash
-# Check latest version available
-npm view @mc1global/opencode-jarvis version
+# 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.
 
-# Install latest version globally
-npm install -g @mc1global/opencode-jarvis@latest
+**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                    # 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. Configure OpenCode
+> **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 or update your OpenCode configuration file. The location depends on your operating system:
+---
 
-**Configuration File Locations:**
-- **macOS**: `~/.config/opencode/opencode.json`
-- **Linux**: `~/.config/opencode/opencode.json` 
-- **Windows**: `%APPDATA%\opencode\opencode.json`
+### Step 2 — Add the plugin to your project
 
-**Add JARVIS Framework to your `opencode.json`:**
+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
 {
   "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "ollama": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "Ollama",
-      "options": {
-        "baseURL": "http://localhost:11434/v1"
-      },
-      "models": {
-        "llama3.2:3b": {
-          "name": "Llama 3.2 3B"
-        },
-        "qwen2.5-coder:7b": {
-          "name": "Qwen 2.5 Coder 7B"
-        }
-      }
-    }
-  },
-  "mcp": {
-    "jarvis-framework": {
-      "type": "local",
-      "command": ["npx", "-y", "@mc1global/opencode-jarvis@latest"],
-      "enabled": true
+  "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"
     }
   }
 }
 ```
 
-#### 3. Restart OpenCode
+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.
 
-After updating the configuration:
+OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
 
-```bash
-# Restart OpenCode to load the new MCP server
-opencode --restart
-```
+#### Where exactly does `opencode.json` go?
 
-#### 4. Verify Integration
+OpenCode supports config files at **two levels**. Choose one (or both — they merge):
 
-Once OpenCode restarts, you should have access to all JARVIS Framework tools:
+**Project-level** (recommended for teams):
 
-**Available Tools:**
-- `workspace-manager` - Manage your 27+ workspaces
-- `kanban-card-*` - Create and manage Kanban cards 
-- `user-story-manager` - Manage features and user stories
-- `rag-search` - Semantic search across your codebase
-- `oracle-query` - Query JARVIS governance documentation
-- `domain-map-*` - Architecture and domain analysis
-- And 30+ more specialized tools...
-
-**Test the integration:**
-
-```bash
-# In OpenCode, try these commands:
-user-story-manager workspace-stats
-workspace-manager list
-kanban-card-list workspace=JARVIS limit=5
+```
+/home/you/code/my-project/opencode.json       # Linux/WSL
+/Users/you/code/my-project/opencode.json       # macOS
 ```
 
-#### 5. Advanced Configuration (Optional)
+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.
 
-```json
-"jarvis-framework": {
-  "type": "local", 
-  "command": ["npx", "-y", "@mc1global/opencode-jarvis@latest"],
-  "enabled": true,
-  "environment": {
-    "JARVIS_WORKSPACE": "JARVIS",
-    "OLLAMA_HOST": "http://localhost:11434"
-  },
-  "timeout": 10000
-}
+**Global-level** (applies to ALL your projects):
+
+```
+~/.config/opencode/opencode.json               # Linux/macOS/WSL
 ```
 
-#### Troubleshooting
+Use this if you want JARVIS active on every project without adding `opencode.json` to each one.
 
-**Common Issues:**
+> **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.
 
-1. **Command not found**: Ensure Node.js and npm are installed
-2. **Permission errors**: Try installing with appropriate permissions
-3. **Version conflicts**: Always use `@latest` to get the newest version
-4. **OpenCode won't restart**: Check JSON syntax in `opencode.json`
+---
 
-**Get Help:**
+### Step 3 — First launch (automatic)
 
-```bash
-# Check package installation
-npm list -g @mc1global/opencode-jarvis
+Run `opencode` in your project directory. JARVIS initializes everything:
 
-# Verify OpenCode configuration  
-opencode --version
-opencode mcp list
+```bash
+cd /path/to/your/project    # must contain opencode.json (or have one globally)
+opencode
 ```
 
----
-
-## 🎯 Key Features
+On first load, JARVIS creates these files and directories automatically:
 
-### 🔥 NEW in OpenCode Edition
+```
+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)
 
-- **Domain Map V2**: Multi-language support (Python, JS, TS, Go, Rust, Swift, Kotlin, Java, C/C++)
-- **34 Custom OpenCode Tools**: Native TypeScript tools for efficient development
-- **LSP Integration**: Language Server Protocol for accurate code analysis
-- **Architecture Detection**: AI-powered pattern recognition (DDD, MVC, etc.)
-- **Comprehensive RAG**: ORACLE governance + codebase indexing
-- **Automated Setup**: Single command installation with all features
+~/.config/opencode/commands/jarvis-agents-md-file.md   (once per machine)
+```
 
-### Core Capabilities
+The global command `~/.config/opencode/commands/jarvis-agents-md-file.md` is written **once per machine** on first plugin load. It registers the `/jarvis-agents-md-file` slash command globally, available in every OpenCode project without any per-project configuration.
 
-| Feature                        | Description                                    | Token Savings |
-| ------------------------------ | ---------------------------------------------- | ------------- |
-| **Semantic Code Search**       | Find code by meaning, not filenames            | 94.6%         |
-| **Smart RAG Indexing**         | Auto-detects project type, excludes build/deps | 10-30x faster |
-| **Domain Mapping**             | Multi-language DDD analysis                    | 90%           |
-| **Token-Optimized Operations** | Smart file operations                          | 98%           |
-| **Hybrid Execution**           | Claude API + Ollama local                      | 75-80% cost   |
-| **Context Memory**             | Persistent TODOs, sessions, notes              | N/A           |
-| **Workspace Governance**       | Multi-project isolation                        | N/A           |
+On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
 
-## 📚 Documentation
+### Step 4 — First session recommended steps
 
-### Getting Started
+The agent should run these on first use (JARVIS prompts automatically):
 
-- **[Installation Guide](docs/installation/INSTALLATION_GUIDE.md)** - Complete setup instructions
-- **[Quick Start](docs/QUICKSTART_NEW_DEVS.md)** - For new developers
-- **[Migration from Legacy](docs/MIGRATION_FROM_LEGACY.md)** - Upgrade from claude_agents/jarvis
-- **[OpenCode Tools Guide](docs/opencode/TOOLS_GUIDE.md)** - Using the 36 custom tools
+1. **`/healthcheck`** — Verify all subsystems
+2. **`rag-index`** tool — Index the codebase for semantic search
+3. **`rag-oracle-index`** tool with `directory="obsidian-vault"` — Index documentation
+4. **`kanban-board-view`** tool — See the kanban board
 
-### Architecture & Design
+### Step 5 — Verify your setup
 
-- **[System Architecture](docs/architecture/DDD_DOMAINS.md)** - 10 DDD bounded contexts
-- **[Domain Map V2](docs/installation/DOMAIN_MAP_V2_SETUP.md)** - Multi-language analysis
-- **[SOLID Principles](docs/governance/SOLID_ENFORCEMENT.md)** - Architecture compliance
-- **[Token Economics](docs/guides/TOKEN_ECONOMICS.md)** - Cost optimization strategies
+The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
 
-### Development Workflow
+```
+[PASS] Bun Runtime: Bun is available (v1.1.38)
+[PASS] Ollama Connectivity: Ollama is reachable at http://localhost:11434
+[PASS] Embedding Model: Model "embeddinggemma" is available
+[PASS] SQLite Database: Database file exists
+[PASS] Configuration: config/jarvis.yaml exists
+[PASS] RAG Index: RAG index contains 42006 documents
+[WARN] Dagger CLI (optional): Dagger is not installed
+  FIX: brew install dagger/tap/dagger
+[WARN] Azure CLI (optional): Azure CLI is not installed
+  FIX: brew install azure-cli && az login
+
+Summary: 6 pass, 2 warn, 0 fail (8 total)
+Status: HEALTHY
+```
 
-- **[Kanban Pipeline](docs/guides/DEVELOPMENT_METHODOLOGY.md#pipeline-kanban)** - Agile workflow
-- **[Scrum Master Guide](OPENCODE.md)** - Agent coordination patterns
-- **[Guardrails System](docs/governance/GUARDRAILS.md)** - Enforcement and compliance
-- **[RAG System](docs/tools/RAG_SYSTEM.md)** - Semantic search guide
+---
 
-### Agents & Skills
+## File Locations Reference
 
-- **[Core Agents](docs/agents/CORE_AGENTS.md)** - Specialized AI agents
-- **[Skills System](docs/skills/OVERVIEW.md)** - 45+ token-optimized skills
-- **[Agent Integration](.opencode/agents/agent-integration.md)** - Multi-agent orchestration
+### In your project (committed to git, shared with team)
 
-### Deployment & Operations
+```
+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
+```
 
-- **[Azure DevOps](docs/deployment/AZURE_DEVOPS_DEPLOYMENT.md)** - CI/CD pipeline
-- **[Production Process](docs/deployment/PRODUCTION_PROCESS.md)** - Deployment workflow
-- **[Monitoring](docs/operations/MONITORING.md)** - System health and metrics
+### Local per machine (NOT committed — add to .gitignore)
 
-## 🛠️ OpenCode Tools
+```
+your-project/
+  .jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
+  .jarvis/rag/               Vectra vector store (RAG embeddings)
+```
 
-The framework includes 36 custom tools for OpenCode:
+### Global (shared across all your projects)
 
-### Domain & Architecture
+```
+~/.config/opencode/opencode.json                      Global OpenCode config (optional)
+~/.config/opencode/commands/jarvis-agents-md-file.md  /jarvis-agents-md-file command (auto-installed)
+~/.config/opencode/plugins/jarvis.js                  Symlink — local dev only (see below)
+~/.jarvis/registry.db                                 Workspace registry (cross-project)
+~/.cache/opencode/node_modules/                       Plugin npm cache (managed by OpenCode)
+```
 
-- `domain-map-generate` - Generate comprehensive domain maps
-- `domain-map-analyze` - Analyze existing maps
-- `domain-map-compare` - Compare between workspaces
-- `domain-map-update` - Update or regenerate maps
+---
 
-### Code Management
+## Setup Scripts
 
-- `code-get-function` - Extract specific functions
-- `code-get-class` - Extract class definitions
-- `code-list-functions` - List all functions in file
-- `code-list-classes` - List all classes in file
-- `code-get-imports` - Extract import statements
-- `code-update-function` - Update function code
+Automated setup scripts are available in the `scripts/setup/` directory of this repository:
 
-### File Operations
+- **`scripts/setup/setup-macos.sh`** — macOS with Homebrew — installs Bun, Ollama, embeddinggemma, optionally Azure CLI and Dagger
+- **`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)
+- **`scripts/setup/link-local.js`** — Local development helper (see [Local Development](#local-development))
 
-- `markdown-*` - 8 tools for Markdown operations
-- `yaml-*` - 7 tools for YAML operations
-- `json-*` - 5 tools for JSON operations
-- `csv-manager` - CSV analysis and queries
-- `file-manager` - File system operations
+Each OS script is interactive, checks for existing installations, and clearly reports what it does.
 
-### RAG & Search
+---
 
-- `rag-smart-index` - Smart indexing with auto project detection
-- `rag-detect-project` - Detect project type and exclusions
-- `rag-index` - Standard index documents
-- `rag-search` - Semantic search
-- `rag-update` - Update index
-- `rag-delete` - Remove from index
-- `rag-status` - System status
-- `rag-snippet` - Get code snippets
+## Available Commands
 
-### Workspace & Kanban
+Commands are available in any OpenCode session:
 
-- `workspace-*` - Workspace management
-- `kanban-*` - Card and epic management
-- `context-*` - Context memory operations
+- **`/jarvis-agents-md-file`** — Regenerate AGENTS.md with the canonical JARVIS template (global, auto-installed)
+- **`/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
 
-## 💡 Problem & Solution
+## Available Skills (loaded on demand via `skill()` tool)
 
-### The Problem
+- **`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
 
-Modern multi-agent workflows face critical constraints:
+---
 
-- **Code Duplication**: Agents create similar functions independently
-- **Token Waste**: Reading 2000+ tokens when only 40 are needed
-- **Inconsistent Naming**: No semantic discovery
-- **Monolithic Files**: 2000+ line files exceed LLM capacity
-- **Lost Context**: No memory between sessions
-- **Runaway Costs**: Full cloud API usage for mechanical tasks
+## Features
+
+### 108 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 Sprint/Epic** (9) — `kanban-sprint-create/get/list/activate/close/cancel`, `kanban-epic-create/list/update`
+- **Kanban Board & Grooming** (4) — `kanban-board-view/stats/wip`, `kanban-grooming-validate`
+- **Kanban Gates** (2) — `kanban-gate-list`, `kanban-gate-meet`
+- **Governance** (2) — `governance-validate`, `governance-policies`
+- **Token Metrics** (6) — `token-record/history/agent-report/card-report/sprint-report/summary`
+- **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** (12) — `vault-manage`, `vault-inspect`, `vault-read/write-section`, `vault-read/write-frontmatter`, `vault-create-document`, `vault-list-documents`, `vault-search`, `vault-read/add/update-table`
+- **Agent** (7) — `agent-register/profile/list/spawn`, `agent-send/handoff/status`
+- **Domain Map** (2) — `domain-map-analyze`, `domain-map-view`
+- **Workspace** (4) — `workspace-info/list/update/link`
+- **Environment** (5) — `env-init/create/list/status/merge`
+- **Pipeline** (9) — `pipeline-init/activate/cancel/retry/query`, `gate-run/pass/fail/skip`
+- **Azure Sync** (12) — `azure-discover/push/pull/sync/status/pr-create/pr-list/comment`, `azure-poll-start/stop/status`, `azure-events-list`
+- **Bootstrap & Config** (5) — `bootstrap`, `healthcheck`, `terminal-commands`, `config-read`, `config-write`
+
+### 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.
 
-### The Solution
+---
 
-JARVIS Framework combines:
+## Configuration
+
+All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults:
+
+```yaml
+# RAG embedding settings
+rag:
+  ollama:
+    url: "http://localhost:11434"
+    model: "embeddinggemma"
+    dimensions: 768
+  markdownSplitByHeaders: true
+
+# Azure DevOps integration
+azure-sync:
+  organization: ""      # Set to enable Azure sync
+  project: ""
+  repository: ""
+  authMethod: "az-cli"
+  pollEnabled: false
+  pollIntervalSecs: 60
+
+# Kanban workflow enforcement
+kanban:
+  minTransitionIntervalSecs: 30
+  gateTasks:              # Per-phase gate definitions
+
+# Token metrics & cost tracking
+token-metrics:
+  sprintBudgetUsd: null         # Set a USD budget per sprint (e.g. 50.0)
+  budgetAlertThreshold: 0.8     # Alert when utilization exceeds 80%
+
+# MCP server settings
+mcp-server:
+  transport: "stdio"
+  enabledTools: null      # null = all tools
+
+# Pipeline CI/CD
+pipeline:
+  defaultTimeoutMs: 300000
+```
 
-- **SOLID + DDD**: 10 bounded contexts, max 487 lines per file
-- **Semantic RAG**: 13,557+ chunks with metadata
-- **Hybrid Execution**: Claude (reasoning) + Ollama (analysis)
-- **Pre-Creation Search**: Prevent duplicates before coding
-- **Context Memory**: SQLite-backed persistence
-- **Guardrails**: Runtime enforcement of best practices
+Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
 
-## 📊 Results & Economics
+---
 
-| Metric               | Traditional   | JARVIS Framework | Improvement         |
-| -------------------- | ------------- | ---------------- | ------------------- |
-| Token usage per file | 2000          | 40               | **98% savings**     |
-| Code discovery       | Manual search | Semantic instant | **10× faster**      |
-| File size (avg)      | 2000 lines    | 150-400 lines    | **80% smaller**     |
-| Setup time           | Hours         | 25-45 minutes    | **95% faster**      |
-| Code duplication     | Common        | Prevented        | **Zero duplicates** |
-| API token cost       | Full cloud    | Hybrid           | **75-80% lower**    |
+## MCP Server Mode
 
-### Cost Example
+JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
 
-**10 file operations:**
+```bash
+bun run src/mcp-server.ts --directory /path/to/project
+```
 
-- Traditional: 20,000 tokens → ~$0.60 (Claude Sonnet)
-- JARVIS: 400 tokens → ~$0.01
-- **Annual savings (1000 sessions): ~$590/developer**
+Configure tool filtering in `config/jarvis.yaml` under `mcp-server`.
 
-## 🏗️ Architecture
+---
 
-### DDD Bounded Contexts
+## Architecture
 
 ```
-src/domain/
-├── code_management/     # Code analysis & extraction
-├── context_memory/      # Sessions, TODOs, notes
-├── domain_maps/         # Architecture metadata
-├── file_governance/     # Access control & policies
-├── git_repository/      # Git lifecycle management
-├── rag/                 # Semantic search
-├── shared/              # TOON formatter & utils
-├── user_stories/        # Story tracking
-├── user_story_chat/     # Interactive PO
-└── workspace/           # Multi-project management
+jarvis-plugin/
+  src/
+    domain/                  Pure business logic, zero external deps (11 bounded contexts)
+    application/             Use cases with DTOs
+    infrastructure/          SQLite repos, Vectra, Ollama, FS adapters
+    tools/                   21 tool modules (108 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 + global OpenCode command templates
 ```
 
-### Layer Architecture
+**Key constraints:**
 
-```
-┌─────────────────────────────────────────────────┐
-│            PRESENTATION LAYER                    │
-│     (OpenCode tools, CLI, Web UI)               │
-├─────────────────────────────────────────────────┤
-│            APPLICATION LAYER                     │
-│     (Use cases, DTOs, orchestration)            │
-├─────────────────────────────────────────────────┤
-│              DOMAIN LAYER                        │
-│     (Entities, value objects, logic)            │
-├─────────────────────────────────────────────────┤
-│          INFRASTRUCTURE LAYER                    │
-│     (Chroma, SQLite, Ollama, LSP)              │
-└─────────────────────────────────────────────────┘
-```
+- Max 500 lines per file (no exceptions)
+- Domain layer has zero external dependencies
+- ESM modules (`"type": "module"`)
+- `exactOptionalPropertyTypes: true` + `verbatimModuleSyntax: true`
+- 11 bounded contexts with strict DDD boundaries
+- Production runtime: Bun (`bun:sqlite`); Tests: Node.js + Jest
 
-## 🗂️ Working with Workspaces and Smart RAG
+---
 
-### Creating and Indexing External Projects
+## Storage
 
-```bash
-# 1. Create a workspace for your project
-python scripts/workspace_manager.py create \
-    --name=MyiOSApp \
-    --context-type=project \
-    --language=swift \
-    --external-path=/Users/you/xcode/MyiOSApp
+All data is stored locally:
 
-# 2. Smart index the workspace (auto-detects Xcode project)
-python scripts/rag_index_smart.py MyiOSApp
-# This will:
-# - Detect it's an Xcode project
-# - Create .gitignore with iOS exclusions (DerivedData, Pods, etc)
-# - Index 10-30x faster by skipping build artifacts
+- `.jarvis/jarvis.db` — SQLite database (sessions, todos, notes, kanban, metrics, environments, pipelines)
+- `.jarvis/rag/<workspace>/` — Vectra vector stores (RAG indexes)
+- `.jarvis/rag/<workspace>/index-manifest.json` — File index registry (incremental indexing)
+- `~/.jarvis/registry.db` — Central workspace registry (cross-project)
 
-# 3. Search your indexed project
-python scripts/rag/rag_cli.py search "viewDidLoad" -w MyiOSApp
-```
+The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
+
+---
 
-### Workspace Commands
+## Local Development
 
 ```bash
-# List all workspaces
-python scripts/workspace_manager.py list
+# Clone
+git clone <repo-url> jarvis-plugin
+cd jarvis-plugin
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
 
-# Index a workspace (uses configured external path)
-python scripts/rag_index_smart.py WORKSPACE_NAME
+# Run all tests
+npm test
 
-# Index with specific path override
-python scripts/rag_index_smart.py WORKSPACE_NAME -d /different/path
+# Type check (zero errors required)
+npm run lint
 
-# Detect project type without indexing
-python scripts/rag/project_type_detector.py /path/to/project --estimate-size
+# Single test file
+node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
+
+# Watch mode
+npm run dev
 ```
 
-## 🧪 Testing & Validation
+### Testing the plugin locally (before publishing to npm)
+
+JARVIS loads as a global plugin via a symlink in `~/.config/opencode/plugins/`. No changes to any `opencode.json` are needed.
 
 ```bash
-# Validate installation
-uv run python scripts/setup/validate_installation.py
+# Build + create symlink (once)
+npm run link:local
 
-# Test Smart RAG detection
-python scripts/rag/project_type_detector.py . --estimate-size
+# After each code change — the symlink stays valid, just rebuild
+npm run build
 
-# Test RAG search
-python scripts/rag/oracle_rag_cli.py search "governance"
-python scripts/rag/rag_cli.py search "workspace"
+# Remove the symlink when done
+npm run unlink:local
+```
 
-# Test Domain Map V2
-python src/application/domain_maps/domain_map_service_v2.py JARVIS
+`npm run link:local` runs `npm run build` first, then creates:
 
-# Test OpenCode tools (in OpenCode)
-# Cmd+Shift+P → rag-smart-index
 ```
+~/.config/opencode/plugins/jarvis.js  →  dist/index.js
+```
+
+When Bun follows the symlink it resolves relative imports from `dist/` and finds external dependencies (`vectra`, `js-yaml`, etc.) in this repository's `node_modules/` — no additional configuration required.
 
-## 🤝 Contributing
+Restart OpenCode in any project to pick up the plugin or any new build.
 
-Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+---
 
-### Development Setup
+## Troubleshooting
 
-```bash
-# Setup development environment
-python scripts/setup/setup_dev_environment.py
+**Ollama connection refused**
+- Ensure Ollama is running: `ollama serve`
+- Check URL in `config/jarvis.yaml` under `rag.ollama.url` (default: `http://localhost:11434`)
 
-# Run tests
-pytest tests/
+**Embedding model not found**
+- Pull the model: `ollama pull embeddinggemma`
+- Verify: `ollama list` should show `embeddinggemma`
 
-# Run linters
-flake8 src/
-mypy src/
-```
+**RAG index empty after rag-index**
+- Run `jarvis-healthcheck` to verify Ollama connectivity
+- Try full reindex: use `rag-index` tool with `clear: true`
 
-## 📝 License
+**Plugin not loading in OpenCode**
+- 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)
 
-This project is proprietary software. See [LICENSE](LICENSE) file for details.
+**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)
 
-## 🙏 Acknowledgments
+**MCP server fails to start**
+- Ensure Bun is installed: `bun --version`
+- Run manually: `bun run src/mcp-server.ts --directory .`
 
-- **OpenCode Team** - For the excellent editor and plugin system
-- **Anthropic** - For Claude API
-- **Ollama Team** - For local LLM infrastructure
-- **Community Contributors** - For feedback and improvements
+**Azure sync not working**
+- Set `organization` and `project` in `config/jarvis.yaml` under `azure-sync`
+- Ensure Azure CLI is authenticated: `az login`
+- Test connectivity: use `azure-sync-config` tool
+
+---
 
-## 📞 Support
+## Dependencies
 
-- **Documentation**: [Full docs](docs/)
-- **Issues**: [Azure DevOps](https://dev.azure.com/MC1Innovation/JARVIS/_workitems)
-- **Wiki**: [Internal Wiki](https://dev.azure.com/MC1Innovation/JARVIS/_wiki)
+- `bun:sqlite` — Local SQLite database (Bun production runtime)
+- `better-sqlite3` — SQLite runtime (Node.js — tests and npm-installed production)
+- `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)
 
 ---
 
-**Built with ❤️ by MC1 Innovation Team**
+## License
 
-_Transform AI coding assistants into super assistants with 90%+ token optimization_
+Copyright (c) 2026 MC1 Global. All rights reserved.
+Developed by Julio Fabio de O. Chagas. See [LICENSE](LICENSE) for details.