@mc1global/opencode-jarvis 0.13.1 → 0.14.1

package/README.md

@@ -1,499 +1,1025 @@
-# 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.14.0** — LLM comment intent processing, SRP enforcement, typed port interfaces, Azure sync bug fixes. 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 that brings **multi-agent development infrastructure** to any project: session memory, kanban project management, governance guardrails, token cost tracking, RAG semantic search, Obsidian vault documentation, domain-map analysis, Azure DevOps synchronization, CI/CD pipelines, and more.
 
-## 🚀 Quick Start
+Built entirely in **TypeScript** with Domain-Driven Design, SOLID principles, and strict type safety. No Python. No Bun. Runs on Node.js.
 
-### Prerequisites
+---
 
-- Python 3.11+
-- Node.js 18+ and npm
-- Git
-- 8GB RAM minimum
-- macOS, Windows, or Linux
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Install OpenCode CLI](#install-opencode-cli)
+3. [Install the Plugin](#install-the-plugin)
+4. [Configure the Plugin](#configure-the-plugin)
+5. [First Launch](#first-launch)
+6. [Verify Setup](#verify-setup)
+7. [Quick Guide — JARVIS Methodology](#quick-guide--jarvis-methodology)
+8. [Azure DevOps Integration](#azure-devops-integration)
+9. [File Locations Reference](#file-locations-reference)
+10. [Local Development](#local-development)
+11. [Troubleshooting](#troubleshooting)
+12. [Configuration Reference](#configuration-reference)
+13. [Dependencies](#dependencies)
+14. [License](#license)
 
-### Installation
+---
 
-```bash
-# Clone from Azure DevOps
-git clone https://dev.azure.com/MC1Innovation/JARVIS/_git/jarvis-opencode
-cd jarvis-opencode
+## Prerequisites
 
-# Run automated installer (25-45 minutes)
-python scripts/setup/jarvis_automated_installer.py --workspace-name=JARVIS --yes
+| Requirement | Purpose | Install |
+|---|---|---|
+| **Node.js >= 20** | Plugin runtime and test runner | [nodejs.org](https://nodejs.org) |
+| **OpenCode CLI** | Host that loads and runs the plugin | See below |
+| **Ollama** + `embeddinggemma` | Local embeddings for RAG semantic search | [ollama.ai](https://ollama.ai) |
+| **Ollama** + `llama3.2` | LLM for Azure comment intent classification | Same Ollama install |
+| **Azure CLI** _(optional)_ | Azure DevOps board sync authentication | [learn.microsoft.com/cli/azure](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) |
+| **Dagger CLI** _(optional)_ | CI/CD gate execution via containers | [docs.dagger.io/install](https://docs.dagger.io/install) |
 
-# 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
-```
+---
+
+## Install OpenCode CLI
 
-### Platform-Specific Instructions
+Full documentation: [opencode.ai/docs](https://opencode.ai/docs)
 
-<details>
-<summary><b>🍎 macOS</b></summary>
+### macOS
 
 ```bash
-# Prerequisites
-brew install python@3.11 node git
+# Via install script (recommended)
+curl -fsSL https://opencode.ai/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
+# Or via Homebrew
+brew install anomalyco/tap/opencode
 ```
 
-</details>
+### Linux (Ubuntu / Debian / Fedora / Arch)
 
-<details>
-<summary><b>🪟 Windows</b></summary>
+```bash
+# Via install script
+curl -fsSL https://opencode.ai/install | bash
 
-```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
+# Arch Linux
+sudo pacman -S opencode           # Stable
+paru -S opencode-bin              # Latest (AUR)
+```
+
+### Windows
 
-# 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
+> **Recommendation:** Use [Windows Subsystem for Linux (WSL)](https://opencode.ai/docs/windows-wsl) for the best experience. The JARVIS plugin requires WSL — it does not run in native Windows PowerShell or cmd.
+
+**Step 1 — Install WSL** (PowerShell as Administrator):
+
+```powershell
+wsl --install
 ```
 
-</details>
+Restart, then open the Ubuntu terminal.
 
-<details>
-<summary><b>🐧 Linux (Ubuntu/Debian)</b></summary>
+**Step 2 — Install OpenCode inside WSL:**
 
 ```bash
-# Prerequisites
-sudo apt update
-sudo apt install python3.11 python3.11-venv nodejs npm git
+curl -fsSL https://opencode.ai/install | bash
+```
+
+If you prefer to use OpenCode natively on Windows (without WSL), the CLI itself supports Chocolatey and Scoop — but the JARVIS plugin must still run inside WSL:
 
-# 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
+```powershell
+choco install opencode   # or: scoop install opencode
 ```
 
-</details>
+### Configure an LLM provider
 
+After installing OpenCode, connect a provider:
 
-### OpenCode Integration Setup
+```
+/connect
+```
+
+Select your provider and paste your API key. See [opencode.ai/docs/providers](https://opencode.ai/docs/providers) for the full list of supported providers.
 
-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.
+---
 
-#### 1. Install the NPM Package
+## Install the Plugin
 
-First, check for the latest version and install:
+### Option A — From npm (recommended)
+
+OpenCode installs npm plugins automatically. You only need to reference the package in your `opencode.json` (see [Configure the Plugin](#configure-the-plugin)).
+
+Requires access to the `@mc1global` scope on npm. If you have access, OpenCode installs it automatically on first launch — no manual `npm install` needed.
+
+### Option B — From Azure DevOps repository (private access)
 
 ```bash
-# Check latest version available
-npm view @mc1global/opencode-jarvis version
+# Clone the repository
+git clone https://dev.azure.com/MC1Innovation/IA/_git/AgenticCoding jarvis-plugin
+cd jarvis-plugin
+
+# Install dependencies and build
+npm install
+npm run build
+
+# Link as a local OpenCode plugin (creates symlink to dist/index.js)
+npm run link:local
+```
 
-# Install latest version globally
-npm install -g @mc1global/opencode-jarvis@latest
+After `link:local`, the plugin is active globally — no `opencode.json` change needed. Any OpenCode project on this machine will load it.
+
+To update after pulling changes:
+
+```bash
+git pull
+npm run build     # the symlink stays valid, just rebuild
 ```
 
-#### 2. Configure OpenCode
+To remove the local link:
 
-Create or update your OpenCode configuration file. The location depends on your operating system:
+```bash
+npm run unlink:local
+```
+
+---
 
-**Configuration File Locations:**
-- **macOS**: `~/.config/opencode/opencode.json`
-- **Linux**: `~/.config/opencode/opencode.json` 
-- **Windows**: `%APPDATA%\opencode\opencode.json`
+## Configure the Plugin
 
-**Add JARVIS Framework to your `opencode.json`:**
+Create an `opencode.json` file in your **project root** (or at `~/.config/opencode/opencode.json` to enable globally):
 
 ```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": {
+    "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"
+    },
+    "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"
     }
   }
 }
 ```
 
-#### 3. Restart OpenCode
+**Where does `opencode.json` go?**
+
+| Location | Effect |
+|---|---|
+| `your-project/opencode.json` | Plugin active only in this project — commit to git for team sharing |
+| `~/.config/opencode/opencode.json` | Plugin active in **all** your projects on this machine |
 
-After updating the configuration:
+Both files can coexist. Project config overrides global config for conflicting keys; non-conflicting settings merge. See [opencode.ai/docs/config](https://opencode.ai/docs/config) for details.
+
+---
+
+## First Launch
+
+Run OpenCode in your project directory:
 
 ```bash
-# Restart OpenCode to load the new MCP server
-opencode --restart
+cd /path/to/your/project
+opencode
 ```
 
-#### 4. Verify Integration
+On first load, JARVIS automatically creates:
 
-Once OpenCode restarts, you should have access to all JARVIS Framework tools:
+```
+your-project/
+  AGENTS.md                 Agent operational guide — commit this
+  config/jarvis.yaml        Default configuration — commit this
+  obsidian-vault/           Documentation vault skeleton — commit this
+  .jarvis/                  SQLite database + RAG indexes — add to .gitignore
+
+~/.config/opencode/commands/jarvis-agents-md-file.md   (once per machine)
+~/.jarvis/registry.db                                   Workspace registry
+```
 
-**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...
+The global command `jarvis-agents-md-file` is installed once per machine, making the `/jarvis-agents-md-file` slash command available in every OpenCode project without any per-project configuration.
 
-**Test the integration:**
+**First session — run these in order:**
 
-```bash
-# In OpenCode, try these commands:
-user-story-manager workspace-stats
-workspace-manager list
-kanban-card-list workspace=JARVIS limit=5
+```
+/healthcheck              Verify all subsystems and get fix guidance
+rag-index                 Index the codebase for semantic search
+rag-oracle-index          Index the JARVIS documentation (dir="obsidian-vault")
+kanban-board-view         See the kanban board
 ```
 
-#### 5. Advanced Configuration (Optional)
+---
 
-```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
-}
+## Verify Setup
+
+The `/healthcheck` command shows all dependencies with copy-paste fix commands:
+
+```
+[PASS] Node.js Runtime: Node.js v20.x is available
+[PASS] Ollama Connectivity: Ollama is reachable at http://localhost:11434
+[PASS] Embedding Model: Model "embeddinggemma" is available
+[PASS] LLM Model: Model "llama3.2" 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: 7 pass, 2 warn, 0 fail (9 total)
+Status: HEALTHY
 ```
 
-#### Troubleshooting
+---
+
+## Quick Guide — JARVIS Methodology
 
-**Common Issues:**
+### What is the JARVIS methodology?
 
-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`
+JARVIS enforces a structured development methodology on top of OpenCode. It is not a code generator — it is a **governance and project management layer** that ensures AI agents follow the same standards a senior engineer would enforce in code review.
 
-**Get Help:**
+The methodology is built on four pillars:
 
-```bash
-# Check package installation
-npm list -g @mc1global/opencode-jarvis
+**1. Domain-Driven Design (DDD)**
+Code is organized into 13 bounded contexts. Each context owns its domain logic, use cases, infrastructure adapters, and tools. No direct imports between contexts — cross-context communication uses port interfaces wired at the composition root.
+
+**2. SOLID principles**
+Every class and module must satisfy all five SOLID principles. The Single Responsibility Principle is enforced at the file level with a hard limit of **500 lines per file**. Files approaching this limit must be split by responsibility.
 
-# Verify OpenCode configuration  
-opencode --version
-opencode mcp list
+**3. Kanban lifecycle**
+All non-trivial work (estimated > 15 minutes) follows a mandatory pipeline:
+
+```
+backlog → grooming → ready → doing → review → tested → done
 ```
 
+Skipping stages is a governance violation. Each stage has gate tasks that must be met with evidence before promotion.
+
+**4. Context memory**
+Every work session is tracked. The agent records decisions, discoveries, and blockers. When the context window compacts, JARVIS injects the active session state back — the agent never loses track of what it was doing.
+
 ---
 
-## 🎯 Key Features
+### Guardrails
 
-### 🔥 NEW in OpenCode Edition
+Guardrails are runtime policies enforced on **every tool invocation** via the `tool.execute.before` hook. Violations with `error` severity throw immediately and abort the call — the agent cannot bypass them.
 
-- **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
+**File access guardrails:**
 
-### Core Capabilities
+| Forbidden action | Correct alternative |
+|---|---|
+| Read `.csv` files directly | `data-csv-query` tool |
+| Read `.yaml` / `.yml` files directly | `data-yaml-get` or `config-read` |
+| Read `.env`, `.pem`, `.key`, `credentials.*` | Blocked — never allowed |
+| Read `.aws/credentials`, `.npmrc`, `.kube/config` | Blocked — never allowed |
 
-| 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           |
+**Shell safety guardrails:**
 
-## 📚 Documentation
+| Forbidden command | Reason |
+|---|---|
+| `git push --force` | History rewriting on shared branches |
+| `sqlite3 ...` | Bypasses repository abstraction and domain invariants |
+| `env`, `printenv`, `echo $SECRET` | Leaks secrets into AI provider context |
+| `cat .env`, `source .env` | Same as above via shell |
 
-### Getting Started
+**Kanban guardrails:**
+- Gate tasks must be met before promoting a card to `review`, `tested`, or `done`
+- Minimum 30 seconds between status transitions (configurable)
+- All grooming requirements must be satisfied before moving to `ready`
 
-- **[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
+Pre-check any operation before executing:
 
-### Architecture & Design
+```
+governance-validate tool_name="bash" tool_args={"command": "git push --force origin main"}
+governance-policies   # list all 13 active policies
+```
 
-- **[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
+---
 
-### Development Workflow
+### Obsidian Vault — Documentation
 
-- **[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
+JARVIS creates and maintains an [Obsidian](https://obsidian.md)-compatible vault in `obsidian-vault/`. This vault serves two purposes:
 
-### Agents & Skills
+**1. Project documentation** (managed by the agent, committed to git):
 
-- **[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
+| Folder | Contents |
+|---|---|
+| `09-Dashboards/` | Project status dashboard — version, active card, test counts |
+| `11-Domain-Reference/` | Per-context architecture docs — one file per bounded context |
+| `12-Scope-Docs/` | Grooming scope documents — one file per kanban card (`CD-NNN-title.md`) |
 
-### Deployment & Operations
+**2. ORACLE documentation** (indexed for semantic search):
 
-- **[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
+| Folder | Contents |
+|---|---|
+| `governance/` | Policy rules and security guidelines |
+| `workflows/` | Step-by-step workflow guides (kanban, Azure sync, pipelines) |
+| `patterns/` | Architecture patterns (DDD, hooks, RAG, config system) |
+| `quick_reference/` | Tool reference, guardrails checklist, setup guide |
 
-## 🛠️ OpenCode Tools
+The ORACLE is the agent's reference library. It is indexed separately from the codebase using `rag-oracle-index` and queried with `rag-oracle-search`. Before starting an unfamiliar workflow, the agent searches ORACLE first.
 
-The framework includes 36 custom tools for OpenCode:
+**Vault tools:**
 
-### Domain & Architecture
+```
+vault-inspect                                    Overview of vault structure
+vault-manage path="..." operation="read/write"   Read or write sections
+vault-create-document path="..."                 Create a new document
+vault-search query="..."                         Full-text search across vault
+```
 
-- `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
+### RAG Index — Why It Matters
 
-- `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
+The RAG index is a local vector database of your codebase and documentation. It enables the agent to find relevant code semantically — "find the function that validates card transitions" — without reading every file.
 
-### File Operations
+**Without the RAG index**, the agent falls back to file search and grep: slower, less accurate, and heavier on context window.
 
-- `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
+**With the RAG index**, the agent can:
+- Find relevant code by meaning with `rag-search query="..."`
+- Get code snippets with surrounding context with `rag-snippet query="..."`
+- Search ORACLE documentation with `rag-oracle-search query="..." domain="workflows"`
 
-### RAG & Search
+**When to reindex:**
 
-- `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
+| Situation | Action |
+|---|---|
+| First setup | `rag-index` (full index) |
+| After large refactor or many new files | `rag-index clear=true` (full reindex) |
+| After modifying a single file | `rag-update file_path="src/..."` |
+| After deleting a file | `rag-delete file_path="src/..."` |
+| After updating vault docs | `rag-oracle-index directory="obsidian-vault"` |
 
-### Workspace & Kanban
+Check index status:
 
-- `workspace-*` - Workspace management
-- `kanban-*` - Card and epic management
-- `context-*` - Context memory operations
+```
+rag-status workspace="WORKSPACE" include_oracle=true
+```
 
-## 💡 Problem & Solution
+---
 
-### The Problem
+### Migrating a Legacy Project to JARVIS Standards
 
-Modern multi-agent workflows face critical constraints:
+If your project does not follow SOLID, DDD, or the 500-line limit, use JARVIS to plan and execute the migration incrementally — one bounded context at a time.
 
-- **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
+**Step 1 — Analyze the current state**
 
-### The Solution
+```
+domain-map-analyze directory="src"
+domain-map-view directory="src"
+```
 
-JARVIS Framework combines:
+This produces a DDD structure report: detected bounded contexts, entity relationships, SRP violations (files over 500 lines), and cross-context coupling issues.
 
-- **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
+**Step 2 — Index the codebase**
 
-## 📊 Results & Economics
+```
+rag-index workspace="WORKSPACE" data_dir="src"
+```
 
-| 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**    |
+After indexing, all subsequent work uses semantic search to find relevant code before modifying it.
 
-### Cost Example
+**Step 3 — Create an epic and sprint for the migration**
 
-**10 file operations:**
+```
+kanban-epic-create title="Legacy Migration — DDD + SOLID + 500-line enforcement"
+kanban-sprint-create name="SP-001" goal="Migration phase 1"
+kanban-sprint-activate sprint_id="SP-001"
+```
 
-- Traditional: 20,000 tokens → ~$0.60 (Claude Sonnet)
-- JARVIS: 400 tokens → ~$0.01
-- **Annual savings (1000 sessions): ~$590/developer**
+**Step 4 — Create one card per bounded context or violation cluster**
 
-## 🏗️ Architecture
+For each area of work:
 
-### DDD Bounded Contexts
+```
+kanban-card-create title="Extract UserAuth bounded context" priority="high"
+kanban-card-move card_id="CD-001" status="grooming"
+kanban-card-assign-epic card_id="CD-001" epic_id="EP-001"
+vault-create-document path="obsidian-vault/12-Scope-Docs/CD-001-user-auth-extraction.md"
+kanban-card-scope-doc card_id="CD-001" path="12-Scope-Docs/CD-001-user-auth-extraction.md"
+kanban-card-criteria card_id="CD-001" description="All files in the UserAuth context are under 500 lines"
+kanban-card-criteria card_id="CD-001" description="No direct imports from UserAuth to OrderProcessing context"
+kanban-card-estimate card_id="CD-001" points=5
+kanban-grooming-validate card_id="CD-001"
+kanban-card-move card_id="CD-001" status="ready"
+```
+
+**Step 5 — Work the card**
 
 ```
-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
+kanban-card-assign card_id="CD-001" agent="opencode"
+kanban-card-assign-sprint card_id="CD-001" sprint_id="SP-001"
+kanban-card-move card_id="CD-001" status="doing"
+context-session-start purpose="CD-001: Extract UserAuth bounded context"
 ```
 
-### Layer Architecture
+Before modifying any file, always search first:
 
 ```
-┌─────────────────────────────────────────────────┐
-│            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)              │
-└─────────────────────────────────────────────────┘
+rag-search query="user authentication logic"
+rag-snippet query="login validation"
+rag-oracle-search query="DDD bounded context extraction" domain="patterns"
 ```
 
-## 🗂️ Working with Workspaces and Smart RAG
+**Step 6 — Meet gate tasks and promote**
+
+```
+kanban-gate-list card_id="CD-001"
+kanban-gate-meet card_id="CD-001" gate_index=0 evidence="commit abc123 — zero tsc errors"
+kanban-card-move card_id="CD-001" status="review"
+```
 
-### Creating and Indexing External Projects
+Repeat for each area of the codebase. Use `domain-map-analyze` again after each phase to track remaining violations.
 
-```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
+---
 
-# 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
+### All 121 Tools — Reference
+
+#### Context Memory (8)
+
+| Tool | Description |
+|---|---|
+| `context-session-start` | Start a tracked work session for a card or task |
+| `context-session-finish` | Close session with a summary |
+| `context-session-list` | List all sessions for the workspace |
+| `context-todo-add` | Add a TODO item to track a task |
+| `context-todo-list` | List TODOs, optionally filtered by status |
+| `context-todo-complete` | Mark a TODO as completed |
+| `context-note-add` | Record a decision, discovery, or blocker |
+| `context-search` | Full-text semantic search across all context memory |
+
+#### Kanban — Cards (14)
+
+| Tool | Description |
+|---|---|
+| `kanban-card-create` | Create a new card in backlog |
+| `kanban-card-update` | Update card description or priority |
+| `kanban-card-move` | Move card to a new status (enforces state machine + WIP limits) |
+| `kanban-card-assign` | Assign an agent to a card |
+| `kanban-card-assign-sprint` | Assign card to an active sprint |
+| `kanban-card-assign-epic` | Assign card to an epic |
+| `kanban-card-estimate` | Set story points (Fibonacci: 1,2,3,5,8,13,21) |
+| `kanban-card-criteria` | Add an acceptance criterion |
+| `kanban-card-criteria-meet` | Mark an acceptance criterion as met |
+| `kanban-card-scope-doc` | Link a vault scope document to a card |
+| `kanban-card-depends-on` | Add or remove a depends-on relationship |
+| `kanban-card-blocked-by` | Add or remove a blocked-by relationship |
+| `kanban-card-unblock` | Unblock a card (moves back to doing or backlog) |
+| `kanban-card-delete` | Delete a card (only backlog or done status) |
+
+#### Kanban — Query (3)
+
+| Tool | Description |
+|---|---|
+| `kanban-card-list` | List cards, optionally filtered by status |
+| `kanban-card-get` | Get detailed card information |
+| `kanban-card-brief` | Generate a full context briefing for handoff to another agent |
+
+#### Kanban — Sprints & Epics (11)
+
+| Tool | Description |
+|---|---|
+| `kanban-sprint-create` | Create a sprint in planning status |
+| `kanban-sprint-get` | Get sprint details |
+| `kanban-sprint-list` | List all sprints |
+| `kanban-sprint-activate` | Activate a sprint (required before cards can move to doing) |
+| `kanban-sprint-close` | Close a sprint with actual velocity |
+| `kanban-sprint-cancel` | Cancel an active sprint |
+| `kanban-epic-create` | Create an epic |
+| `kanban-epic-list` | List all epics |
+| `kanban-epic-update` | Update epic description, owner, or priority |
+| `kanban-epic-start` | Mark epic as in-progress |
+| `kanban-epic-complete` | Mark epic as completed |
+
+#### Kanban — Board, Grooming & Gates (6)
+
+| Tool | Description |
+|---|---|
+| `kanban-board-view` | Full board view with all columns and cards |
+| `kanban-board-stats` | Card count per status column |
+| `kanban-board-wip` | Check WIP limit violations |
+| `kanban-grooming-validate` | Validate all grooming requirements for a card |
+| `kanban-gate-list` | List all gate tasks for a card with evidence |
+| `kanban-gate-meet` | Mark a gate task as met with evidence |
+
+#### Governance (2)
+
+| Tool | Description |
+|---|---|
+| `governance-validate` | Pre-check if an operation is allowed before executing |
+| `governance-policies` | List all 13 active governance policies |
+
+#### Token Metrics (6)
+
+| Tool | Description |
+|---|---|
+| `token-record` | Record a token usage event |
+| `token-history` | Get usage history with optional filters |
+| `token-agent-report` | Report by agent — total tokens, cost, operation breakdown |
+| `token-card-report` | Report by card — cost attribution per feature |
+| `token-sprint-report` | Report by sprint — budget vs actual with alerts |
+| `token-summary` | High-level workspace cost summary |
+
+#### RAG — Semantic Search (8)
+
+| Tool | Description |
+|---|---|
+| `rag-index` | Index workspace files into the local vector store |
+| `rag-search` | Semantic search by meaning across indexed files |
+| `rag-snippet` | Search with surrounding code context and line numbers |
+| `rag-update` | Re-index a single file after modification |
+| `rag-delete` | Remove a file from the index |
+| `rag-status` | Show index status — document count, model, store info |
+| `rag-oracle-index` | Index ORACLE governance documentation |
+| `rag-oracle-search` | Semantic search across ORACLE docs, with domain filter |
+
+#### Data (5)
+
+| Tool | Description |
+|---|---|
+| `data-yaml-get` | Read a value from a YAML file using dot-notation path |
+| `data-yaml-set` | Write a value to a YAML file |
+| `data-json-get` | Read a value from a JSON file using dot-notation path |
+| `data-json-set` | Write a value to a JSON file |
+| `data-csv-query` | Query rows from a CSV file with filter expressions |
+
+#### Vault — Obsidian Docs (12)
+
+| Tool | Description |
+|---|---|
+| `vault-inspect` | Smart inspection — overview of vault or specific document |
+| `vault-manage` | High-level read/write with intelligent defaults |
+| `vault-read-section` | Read a specific section by heading path |
+| `vault-write-section` | Write or update a section (replace or append) |
+| `vault-read-frontmatter` | Read YAML frontmatter from a document |
+| `vault-write-frontmatter` | Update YAML frontmatter |
+| `vault-create-document` | Create a new vault document |
+| `vault-list-documents` | List documents in a vault folder |
+| `vault-search` | Full-text search across vault documents |
+| `vault-read-table` | Read a markdown table from a document |
+| `vault-add-table-row` | Append a row to a markdown table |
+| `vault-update-table-row` | Update a table row by matching a column value |
+
+#### Agent Registry (7)
+
+| Tool | Description |
+|---|---|
+| `agent-register` | Register an agent profile with role, system prompt, and tool access |
+| `agent-profile` | Get detailed information about a registered agent |
+| `agent-list` | List all registered agent profiles |
+| `agent-spawn` | Spawn a new OpenCode session configured with an agent's profile |
+| `agent-send` | Send a message or task to another agent session |
+| `agent-handoff` | Hand off a work item to another agent |
+| `agent-status` | Check status of work items assigned to or by this agent |
+
+#### Domain Map (2)
+
+| Tool | Description |
+|---|---|
+| `domain-map-analyze` | Analyze a directory for DDD structure, SRP violations, and recommendations |
+| `domain-map-view` | View the cached domain map from the most recent analysis |
+
+#### Workspace Registry (4)
+
+| Tool | Description |
+|---|---|
+| `workspace-info` | Get workspace metadata, tech stack, and dependencies |
+| `workspace-list` | List all registered workspaces |
+| `workspace-update` | Update workspace metadata, status, or tech stack |
+| `workspace-link` | Manage dependency links between workspaces |
+
+#### Environment (6)
+
+| Tool | Description |
+|---|---|
+| `env-init` | Analyze a project directory and suggest environment config |
+| `env-create` | Create an isolated development environment |
+| `env-list` | List environments for the workspace |
+| `env-status` | Get or update environment status |
+| `env-merge` | Merge environment changes back to the main branch |
+| `env-delete` | Delete an environment |
+
+#### Pipeline — CI/CD (9)
+
+| Tool | Description |
+|---|---|
+| `pipeline-init` | Create a pipeline from a stack template (`typescript-app`, `python-lib`, etc.) |
+| `pipeline-activate` | Activate a draft pipeline |
+| `pipeline-cancel` | Cancel a draft or active pipeline |
+| `pipeline-retry` | Retry a failed pipeline |
+| `pipeline-query` | Query pipelines or list available templates |
+| `gate-run` | Execute a gate via Dagger |
+| `gate-pass` | Manually pass a gate with evidence |
+| `gate-fail` | Manually fail a gate |
+| `gate-skip` | Skip a gate with a reason |
+
+#### Azure DevOps Sync (13)
+
+| Tool | Description |
+|---|---|
+| `azure-discover` | Discover Azure project config — process template, work item types, iterations |
+| `azure-push` | Push local cards/epics/sprints to Azure (create or update work items) |
+| `azure-pull` | Pull Azure work items into local kanban |
+| `azure-sync` | Bidirectional sync (push then pull) |
+| `azure-status` | Show sync mapping status — mapped, unmapped, sync timestamps |
+| `azure-pr-create` | Create a Pull Request in Azure Repos |
+| `azure-pr-list` | List Pull Requests or get a single PR |
+| `azure-comment` | Add a structured comment to an Azure work item |
+| `azure-poll-start` | Start background polling for Azure changes |
+| `azure-poll-stop` | Stop background polling |
+| `azure-poll-status` | Check polling service status |
+| `azure-events-list` | List detected sync events (field changes, state transitions, comments) |
+| `azure-process-comment` | Process a comment via LLM — classify intent, execute action, post reply |
+
+#### Bootstrap & Config (6)
+
+| Tool | Description |
+|---|---|
+| `bootstrap` | Initialize JARVIS project structure (AGENTS.md + directories) |
+| `healthcheck` | Diagnose environment readiness with copy-paste fix guidance |
+| `terminal-commands` | Get terminal commands for long-running operations (RAG index, etc.) |
+| `config-read` | Read current JARVIS configuration (any section or all) |
+| `config-write` | Update configuration values for a section |
+| `config-reset` | Reset a section back to built-in defaults |
 
-# 3. Search your indexed project
-python scripts/rag/rag_cli.py search "viewDidLoad" -w MyiOSApp
+---
+
+### ORACLE — Searching the Documentation
+
+The ORACLE is the semantic search index over the `obsidian-vault/` documentation. It covers workflows, governance, patterns, and quick reference guides.
+
+**Index the ORACLE** (required on first setup, repeat after vault updates):
+
+```
+rag-oracle-index directory="obsidian-vault"
 ```
 
-### Workspace Commands
+**Search the ORACLE** before starting any unfamiliar workflow:
+
+```
+rag-oracle-search query="how to groom a card" domain="workflows"
+rag-oracle-search query="DDD bounded context" domain="patterns"
+rag-oracle-search query="azure sync setup" domain="workflows"
+rag-oracle-search query="governance policies" domain="governance"
+rag-oracle-search query="first time setup" domain="quick_reference"
+```
+
+Supported `domain` values: `workflows`, `patterns`, `governance`, `quick_reference`. Omit `domain` for cross-domain search.
+
+---
+
+## Azure DevOps Integration
+
+JARVIS can synchronize the local kanban board with **Azure DevOps Boards** bi-directionally. Cards become work items, sprints become iterations, epics become Azure Epics, and acceptance criteria become child Task items.
+
+Additionally, when the background poll service is active, Azure work item **comments are detected in real-time** and can be classified by an LLM (`llama3.2` via Ollama) to trigger JARVIS actions automatically.
+
+### Prerequisites
+
+**1. Install and authenticate Azure CLI:**
 
 ```bash
-# List all workspaces
-python scripts/workspace_manager.py list
+# macOS
+brew install azure-cli && az login
+
+# Linux (Debian / Ubuntu)
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
 
-# Index a workspace (uses configured external path)
-python scripts/rag_index_smart.py WORKSPACE_NAME
+# Windows (inside WSL)
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
+```
 
-# Index with specific path override
-python scripts/rag_index_smart.py WORKSPACE_NAME -d /different/path
+**2. Configure your Azure project:**
 
-# Detect project type without indexing
-python scripts/rag/project_type_detector.py /path/to/project --estimate-size
+```
+config-write section="azure-sync" values={"organization": "MyOrg", "project": "MyProject", "repository": "MyRepo", "authMethod": "az-cli"}
+```
+
+Or edit `config/jarvis.yaml` directly:
+
+```yaml
+azure-sync:
+  organization: "MyOrg"
+  project: "MyProject"
+  repository: "MyRepo"
+  authMethod: "az-cli"   # or "pat" — requires AZURE_DEVOPS_PAT env var
 ```
 
-## 🧪 Testing & Validation
+**3. Pull Ollama model for comment intent processing** (optional):
 
 ```bash
-# Validate installation
-uv run python scripts/setup/validate_installation.py
+ollama pull llama3.2
+```
 
-# Test Smart RAG detection
-python scripts/rag/project_type_detector.py . --estimate-size
+---
 
-# Test RAG search
-python scripts/rag/oracle_rag_cli.py search "governance"
-python scripts/rag/rag_cli.py search "workspace"
+### Step 1 — Discover the Azure project
 
-# Test Domain Map V2
-python src/application/domain_maps/domain_map_service_v2.py JARVIS
+```
+azure-discover org="MyOrg" project="MyProject"
+```
+
+Returns: process template (Scrum / Agile / CMMI), existing work item types, and current iterations. JARVIS uses this to automatically map local entities to the correct Azure work item types.
+
+---
+
+### Step 2 — Push the local kanban to Azure
+
+Push in this order — sprints (iterations) must exist before cards can reference them:
+
+```
+azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="sprint"
+azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="epic"
+azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="card"
+```
+
+Or push all at once:
+
+```
+azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="all"
+```
+
+Preview without committing:
+
+```
+azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="all" dry_run=true
+```
+
+---
+
+### Step 3 — Check sync status
+
+```
+azure-status workspace="WORKSPACE" org="MyOrg" project="MyProject"
+```
+
+Shows which local entities are mapped to Azure work items, which are unmapped on either side, and sync timestamps.
+
+---
+
+### Step 4 — Pull changes from Azure
+
+When team members update work items directly in Azure Boards:
+
+```
+azure-pull workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="card"
+```
+
+Or run a full bidirectional sync:
+
+```
+azure-sync workspace="WORKSPACE" org="MyOrg" project="MyProject"
+```
+
+---
+
+### Background Polling — Real-time Change Detection
+
+Enable polling in `config/jarvis.yaml` to detect Azure changes automatically:
+
+```yaml
+azure-sync:
+  pollEnabled: true
+  pollIntervalSecs: 60   # minimum 30
+```
+
+Control polling manually:
+
+```
+azure-poll-start
+azure-poll-status          # check if running and last poll time
+azure-events-list workspace="WORKSPACE"   # view detected events
+azure-poll-stop
+```
+
+---
+
+### Comment Intent Processing
+
+When polling is active and a new comment is posted to an Azure work item, JARVIS stores it as a `comment_added` `SyncEvent`. Process it on demand:
+
+```
+azure-process-comment event_id="EVT-NNN"
+```
 
-# Test OpenCode tools (in OpenCode)
-# Cmd+Shift+P → rag-smart-index
+This pipeline:
+1. Loads the comment text from the stored event
+2. Sends it to `llama3.2` via Ollama with a structured JSON schema prompt
+3. Classifies the intent: `create-card`, `move-card`, `add-ac`, `add-note`, or `unknown`
+4. Executes the resolved action against the local kanban
+5. Posts a `[JARVIS] ...` reply comment back to the Azure work item
+
+**Example intents:**
+
+| Comment posted in Azure | Intent detected | Action taken |
+|---|---|---|
+| `"Create a card to fix the login timeout"` | `create-card` | New kanban card created |
+| `"Move this to in review"` | `move-card` | Card status updated |
+| `"Add AC: login must complete in under 2s"` | `add-ac` | Acceptance criterion added |
+| `"Note: we decided to use JWT tokens"` | `add-note` | Context memory note recorded |
+| Anything unrecognised | `unknown` | LLM generates a helpful reply |
+
+---
+
+### Creating Pull Requests from JARVIS
+
+```
+azure-pr-create org="MyOrg" project="MyProject" repository="MyRepo"
+  title="CD-005: Add LLM comment processing"
+  description="Implements on-demand comment classification..."
+  source_branch="cd-005-feature"
+  target_branch="main"
+  work_item_ids=[42]
 ```
 
-## 🤝 Contributing
+---
+
+## File Locations Reference
 
-Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+### In your project (commit to git — shared with team)
 
-### Development Setup
+```
+your-project/
+  opencode.json              Plugin declaration
+  config/jarvis.yaml         Configuration (auto-created, then customized)
+  AGENTS.md                  Agent operational guide (auto-generated)
+  obsidian-vault/            Documentation vault
+```
+
+### Local per machine (do NOT commit — add to .gitignore)
+
+```
+your-project/
+  .jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
+  .jarvis/rag/               Vectra vector store (RAG embeddings)
+```
+
+### Global (shared across all your projects on this machine)
+
+```
+~/.config/opencode/opencode.json                      Global OpenCode config (optional)
+~/.config/opencode/commands/jarvis-agents-md-file.md  Auto-installed global command
+~/.jarvis/registry.db                                 Workspace registry (cross-project)
+```
+
+---
+
+## Local Development
 
 ```bash
-# Setup development environment
-python scripts/setup/setup_dev_environment.py
+# Clone
+git clone https://dev.azure.com/MC1Innovation/IA/_git/AgenticCoding jarvis-plugin
+cd jarvis-plugin
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
 
-# Run tests
-pytest tests/
+# Run all tests
+npm test
 
-# Run linters
-flake8 src/
-mypy src/
+# Type check only (zero errors required)
+npm run lint
+
+# Watch mode
+npm run dev
 ```
 
-## 📝 License
+### Test the plugin locally before publishing
 
-This project is proprietary software. See [LICENSE](LICENSE) file for details.
+```bash
+# Build + create symlink to ~/.config/opencode/plugins/jarvis.js
+npm run link:local
 
-## 🙏 Acknowledgments
+# After each code change — symlink stays valid, just rebuild
+npm run build
 
-- **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
+# Remove the symlink when done
+npm run unlink:local
+```
+
+Restart OpenCode in any project to pick up the new build.
+
+---
+
+## Troubleshooting
+
+**Ollama connection refused**
+- Start Ollama: `ollama serve`
+- Check the URL in `config/jarvis.yaml` under `rag.ollama.url` (default: `http://localhost:11434`)
+
+**Embedding model not found**
+- Pull the model: `ollama pull embeddinggemma`
+- Verify: `ollama list` should show `embeddinggemma`
+
+**llama3.2 not found** (comment intent processing)
+- Pull the model: `ollama pull llama3.2`
+
+**RAG index empty after rag-index**
+- Run `/healthcheck` to verify Ollama connectivity
+- Try full reindex: use `rag-index` with `clear=true`
+
+**Plugin not loading in OpenCode**
+- Verify `opencode.json` exists and contains `"plugin": ["@mc1global/opencode-jarvis"]`
+- Check `~/.cache/opencode/node_modules/` for the installed package
+- Run OpenCode with `--verbose` to see plugin load errors
+
+**Windows: Plugin not loading**
+- JARVIS must run inside WSL — it does not run in native Windows PowerShell or cmd
+- Install prerequisites inside WSL
+- Run `opencode` from your WSL terminal
+- Keep project files in the WSL filesystem (`~/code/`) for best performance
+- See [OpenCode Windows docs](https://opencode.ai/docs/windows-wsl)
+
+**Azure sync: authentication error**
+- Ensure Azure CLI is authenticated: `az login`
+- Test connectivity: `azure-discover org="MyOrg" project="MyProject"`
+- If using PAT auth: set the `AZURE_DEVOPS_PAT` environment variable
+
+**Kanban card won't move to done**
+- Check gate tasks: `kanban-gate-list card_id="CD-XXX"`
+- All required gates must be met with evidence before promotion
+
+---
+
+## Configuration Reference
+
+All settings live in `config/jarvis.yaml`. Values are deep-merged over built-in defaults — only overrides need to be present:
+
+```yaml
+# RAG embedding settings
+rag:
+  ollama:
+    url: "http://localhost:11434"
+    model: "embeddinggemma"
+    dimensions: 768
+  markdownSplitByHeaders: true
+
+# Azure DevOps integration
+azure-sync:
+  organization: ""
+  project: ""
+  repository: ""
+  authMethod: "az-cli"   # or "pat"
+  pollEnabled: false
+  pollIntervalSecs: 60
+
+# Kanban workflow enforcement
+kanban:
+  minTransitionIntervalSecs: 30
+
+# Token metrics and cost tracking
+token-metrics:
+  sprintBudgetUsd: null          # e.g. 50.0 — alerts when budget exceeded
+  budgetAlertThreshold: 0.8      # alert at 80% utilization
+
+# Pipeline CI/CD
+pipeline:
+  defaultTimeoutMs: 300000
+```
+
+Read current config:
+
+```
+config-read section="azure-sync"
+config-read   # all sections
+```
+
+Update config:
+
+```
+config-write section="azure-sync" values={"organization": "MyOrg", "project": "MyProject"}
+config-write section="token-metrics" values={"sprintBudgetUsd": 50.0}
+```
+
+---
 
-## 📞 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)
+| Package | Purpose |
+|---|---|
+| `better-sqlite3` | SQLite database — kanban, sessions, metrics, sync mappings |
+| `js-yaml` | YAML parsing for config and vault files |
+| `vectra` | Local vector store for RAG semantic search |
+| `ollama` | Embedding generation and LLM classification via local Ollama |
+| `@langchain/textsplitters` | Code-aware text chunking for RAG indexing |
+| `@clack/prompts` | Interactive terminal prompts |
+| `@modelcontextprotocol/sdk` | MCP protocol implementation |
+| `@opencode-ai/plugin` | OpenCode plugin SDK (peer dependency) |
 
 ---
 
-**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.