@mc1global/opencode-jarvis 0.13.0 → 0.13.1

package/README.md

@@ -1,539 +1,499 @@
-# @mc1global/opencode-jarvis
+# JARVIS Framework - OpenCode Edition
 
-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.
+**A production-ready framework for multi-agent LLM development with semantic code search, SOLID/DDD architecture, and 90-98% token optimization.**
 
-Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
+[![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)
 
----
-
-## Prerequisites
-
-- **[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
+## 🚀 Quick Start
 
-### Step 1 — Install prerequisites
+### Prerequisites
 
-Choose your operating system below. Each section includes both **manual commands** and a link to an **automated setup script** that handles everything.
+- Python 3.11+
+- Node.js 18+ and npm
+- Git
+- 8GB RAM minimum
+- macOS, Windows, or Linux
 
-#### macOS
-
-**Automated** (recommended):
+### Installation
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-macos.sh | bash
+# Clone from Azure DevOps
+git clone https://dev.azure.com/MC1Innovation/JARVIS/_git/jarvis-opencode
+cd jarvis-opencode
+
+# Run automated installer (25-45 minutes)
+python scripts/setup/jarvis_automated_installer.py --workspace-name=JARVIS --yes
+
+# 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
 ```
 
-Or download `scripts/setup/setup-macos.sh` from the repository and run it locally.
+### Platform-Specific Instructions
 
-**Manual:**
+<details>
+<summary><b>🍎 macOS</b></summary>
 
 ```bash
-# Bun (required — SQLite runtime)
-curl -fsSL https://bun.sh/install | bash
-
-# Ollama + embedding model (required for RAG)
-brew install ollama
-ollama serve                    # start the server (keep running)
-ollama pull embeddinggemma      # download the embedding model
-
-# Optional: Azure DevOps sync
-brew install azure-cli && az login
+# Prerequisites
+brew install python@3.11 node git
 
-# Optional: CI/CD pipeline execution
-brew install dagger/tap/dagger
+# 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
 ```
 
-#### Linux (Ubuntu/Debian/Fedora/Arch)
+</details>
 
-**Automated** (recommended):
+<details>
+<summary><b>🪟 Windows</b></summary>
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-linux.sh | 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
+
+# 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 download `scripts/setup/setup-linux.sh` from the repository and run it locally.
+</details>
 
-**Manual:**
+<details>
+<summary><b>🐧 Linux (Ubuntu/Debian)</b></summary>
 
 ```bash
-# Bun (required)
-curl -fsSL https://bun.sh/install | bash
+# Prerequisites
+sudo apt update
+sudo apt install python3.11 python3.11-venv nodejs npm git
+
+# 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
+```
 
-# 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
+</details>
 
-# 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
-```
+### OpenCode Integration Setup
 
-#### Windows (WSL)
+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.
 
-> OpenCode recommends Windows Subsystem for Linux (WSL) for the best experience.
-> See the [OpenCode WSL guide](https://opencode.ai/docs/windows-wsl) for details.
+#### 1. Install the NPM Package
 
-**Step 0 — Install WSL** (if you haven't already):
+First, check for the latest version and install:
 
-Open **PowerShell as Administrator** and run:
+```bash
+# Check latest version available
+npm view @mc1global/opencode-jarvis version
 
-```powershell
-wsl --install
+# Install latest version globally
+npm install -g @mc1global/opencode-jarvis@latest
 ```
 
-Restart your computer, then open the **Ubuntu** terminal app.
-
-**Step 1 — Run the setup script inside WSL:**
+#### 2. Configure OpenCode
 
-```bash
-# From your WSL terminal (Ubuntu):
-curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-wsl.sh | bash
-```
+Create or update your OpenCode configuration file. The location depends on your operating system:
 
-Or download `scripts/setup/setup-wsl.sh` from the repository and run it inside WSL.
+**Configuration File Locations:**
+- **macOS**: `~/.config/opencode/opencode.json`
+- **Linux**: `~/.config/opencode/opencode.json` 
+- **Windows**: `%APPDATA%\opencode\opencode.json`
 
-**Manual (inside WSL terminal):**
+**Add JARVIS Framework to your `opencode.json`:**
 
-```bash
-# OpenCode CLI
-curl -fsSL https://opencode.ai/install | bash
+```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
+    }
+  }
+}
+```
 
-# Bun (required)
-curl -fsSL https://bun.sh/install | bash
+#### 3. Restart OpenCode
 
-# 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
+After updating the configuration:
 
-# Optional: Azure CLI
-curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
+```bash
+# Restart OpenCode to load the new MCP server
+opencode --restart
 ```
 
-> **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.
+#### 4. Verify Integration
 
----
+Once OpenCode restarts, you should have access to all JARVIS Framework tools:
 
-### Step 2 — Add the plugin to your project
+**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...
 
-Create an `opencode.json` file **in your project root directory**:
+**Test the integration:**
 
-```
-your-project/              <-- your project root
-  opencode.json            <-- CREATE THIS FILE HERE
-  package.json
-  src/
-  ...
+```bash
+# In OpenCode, try these commands:
+user-story-manager workspace-stats
+workspace-manager list
+kanban-card-list workspace=JARVIS limit=5
 ```
 
-Content of `opencode.json`:
+#### 5. Advanced Configuration (Optional)
 
 ```json
-{
-  "$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"
-    }
-  }
+"jarvis-framework": {
+  "type": "local", 
+  "command": ["npx", "-y", "@mc1global/opencode-jarvis@latest"],
+  "enabled": true,
+  "environment": {
+    "JARVIS_WORKSPACE": "JARVIS",
+    "OLLAMA_HOST": "http://localhost:11434"
+  },
+  "timeout": 10000
 }
 ```
 
-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.
+#### Troubleshooting
 
-OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
+**Common Issues:**
 
-#### Where exactly does `opencode.json` go?
+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`
 
-OpenCode supports config files at **two levels**. Choose one (or both — they merge):
+**Get Help:**
 
-**Project-level** (recommended for teams):
+```bash
+# Check package installation
+npm list -g @mc1global/opencode-jarvis
 
-```
-/home/you/code/my-project/opencode.json       # Linux/WSL
-/Users/you/code/my-project/opencode.json       # macOS
+# Verify OpenCode configuration  
+opencode --version
+opencode mcp list
 ```
 
-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.
+## 🎯 Key Features
 
-> **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.
+### 🔥 NEW in OpenCode Edition
 
----
+- **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
 
-### Step 3 — First launch (automatic)
+### Core Capabilities
 
-Run `opencode` in your project directory. JARVIS initializes everything:
+| 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           |
 
-```bash
-cd /path/to/your/project    # must contain opencode.json (or have one globally)
-opencode
-```
+## 📚 Documentation
 
-On first load, JARVIS creates these files and directories automatically:
+### Getting Started
 
-```
-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)
-```
+- **[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
 
-On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
+### Architecture & Design
 
-### Step 4 — First session recommended steps
+- **[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 agent should run these on first use (JARVIS prompts automatically):
+### Development Workflow
 
-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
+- **[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
 
-### Step 5 — Verify your setup
+### Agents & Skills
 
-The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
+- **[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
 
-```
-[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
-```
+### Deployment & Operations
 
----
+- **[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
 
-## File Locations Reference
+## 🛠️ OpenCode Tools
 
-### In your project (committed to git, shared with team)
+The framework includes 36 custom tools for OpenCode:
 
-```
-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
-```
+### Domain & Architecture
 
-### Local per machine (NOT committed — add to .gitignore)
+- `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
 
-```
-your-project/
-  .jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
-  .jarvis/rag/               Vectra vector store (RAG embeddings)
-```
+### Code Management
 
-### Global (shared across all your projects)
+- `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
 
-```
-~/.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)
-```
+### File Operations
 
----
+- `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
 
-## Setup Scripts
+### RAG & Search
 
-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:
+- `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
 
-- **`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)
+### Workspace & Kanban
 
-Each script is interactive, checks for existing installations, and clearly reports what it does.
+- `workspace-*` - Workspace management
+- `kanban-*` - Card and epic management
+- `context-*` - Context memory operations
 
----
+## 💡 Problem & Solution
 
-## Available Commands
+### The Problem
 
-Commands are available in any OpenCode session:
+Modern multi-agent workflows face critical constraints:
 
-- **`/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
+- **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
 
-## Available Skills (loaded on demand via `skill()` tool)
+### The Solution
 
-- **`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
+JARVIS Framework combines:
 
----
+- **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
 
-## Features
-
-### 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.
+## 📊 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**    |
 
-## 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
-```
+### Cost Example
 
-Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
+**10 file operations:**
 
----
+- Traditional: 20,000 tokens → ~$0.60 (Claude Sonnet)
+- JARVIS: 400 tokens → ~$0.01
+- **Annual savings (1000 sessions): ~$590/developer**
 
-## MCP Server Mode
+## 🏗️ Architecture
 
-JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
+### DDD Bounded Contexts
 
-```bash
-bun run src/mcp-server.ts --directory /path/to/project
+```
+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
 ```
 
-Configure tool filtering in `config/jarvis.yaml` under `mcp-server`.
-
----
-
-## Architecture
+### Layer Architecture
 
 ```
-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/                   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
+┌─────────────────────────────────────────────────┐
+│            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)              │
+└─────────────────────────────────────────────────┘
 ```
 
-**Key constraints:**
+## 🗂️ Working with Workspaces and Smart RAG
 
-- 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
+### Creating and Indexing External Projects
 
----
+```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
+
+# 3. Search your indexed project
+python scripts/rag/rag_cli.py search "viewDidLoad" -w MyiOSApp
+```
 
-## Storage
+### Workspace Commands
 
-All data is stored locally:
+```bash
+# List all workspaces
+python scripts/workspace_manager.py list
 
-- `.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)
+# Index a workspace (uses configured external path)
+python scripts/rag_index_smart.py WORKSPACE_NAME
 
-The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
+# Index with specific path override
+python scripts/rag_index_smart.py WORKSPACE_NAME -d /different/path
 
----
+# Detect project type without indexing
+python scripts/rag/project_type_detector.py /path/to/project --estimate-size
+```
 
-## Local Development
+## 🧪 Testing & Validation
 
 ```bash
-# Clone
-git clone <repo-url> jarvis-plugin
-cd jarvis-plugin
-
-# Install dependencies
-npm install
+# Validate installation
+uv run python scripts/setup/validate_installation.py
 
-# Build
-npm run build
+# Test Smart RAG detection
+python scripts/rag/project_type_detector.py . --estimate-size
 
-# Run all tests
-npm test
+# Test RAG search
+python scripts/rag/oracle_rag_cli.py search "governance"
+python scripts/rag/rag_cli.py search "workspace"
 
-# Type check (zero errors required)
-npm run lint
+# Test Domain Map V2
+python src/application/domain_maps/domain_map_service_v2.py JARVIS
 
-# Single test file
-node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
-
-# Watch mode
-npm run dev
-
-# Configure for local plugin development in OpenCode:
-# Add to your project's opencode.json:
-{
-  "plugin": {
-    "jarvis": {
-      "path": "/absolute/path/to/jarvis-plugin"
-    }
-  }
-}
+# Test OpenCode tools (in OpenCode)
+# Cmd+Shift+P → rag-smart-index
 ```
 
----
+## 🤝 Contributing
 
-## Troubleshooting
+Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
 
-**Ollama connection refused**
-- Ensure Ollama is running: `ollama serve`
-- Check URL in `config/jarvis.yaml` under `rag.ollama.url` (default: `http://localhost:11434`)
+### Development Setup
 
-**Embedding model not found**
-- Pull the model: `ollama pull embeddinggemma`
-- Verify: `ollama list` should show `embeddinggemma`
+```bash
+# Setup development environment
+python scripts/setup/setup_dev_environment.py
 
-**RAG index empty after rag-index**
-- Run `jarvis-healthcheck` to verify Ollama connectivity
-- Try full reindex: use `rag-index` tool with `clear: true`
+# Run tests
+pytest tests/
 
-**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)
+# Run linters
+flake8 src/
+mypy src/
+```
 
-**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)
+## 📝 License
 
-**MCP server fails to start**
-- Ensure Bun is installed: `bun --version`
-- Run manually: `bun run src/mcp-server.ts --directory .`
+This project is proprietary software. See [LICENSE](LICENSE) file for details.
 
-**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
+## 🙏 Acknowledgments
 
----
+- **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
 
-## Dependencies
+## 📞 Support
 
-- `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)
+- **Documentation**: [Full docs](docs/)
+- **Issues**: [Azure DevOps](https://dev.azure.com/MC1Innovation/JARVIS/_workitems)
+- **Wiki**: [Internal Wiki](https://dev.azure.com/MC1Innovation/JARVIS/_wiki)
 
 ---
 
-## License
+**Built with ❤️ by MC1 Innovation Team**
 
-Copyright (c) 2026 MC1 Global. All rights reserved.
-Developed by Julio Fabio de O. Chagas. See [LICENSE](LICENSE) for details.
+_Transform AI coding assistants into super assistants with 90%+ token optimization_