rrce-workflow 0.2.91 → 0.2.93

package/README.md

@@ -5,13 +5,14 @@
 [![npm version](https://badge.fury.io/js/rrce-workflow.svg)](https://www.npmjs.com/package/rrce-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-RRCE-Workflow is a tool that turns your AI coding assistant (GitHub Copilot, Claude Desktop, Antigravity IDE, etc.) into a **context-aware agent**. 
+RRCE-Workflow transforms your AI coding assistant (GitHub Copilot, OpenCode, Claude Desktop, Antigravity IDE) into a **context-aware agent** with persistent project knowledge.
 
-It standardizes how AI agents understand your project through:
-1.  **Global Knowledge Base**: Centralized context management across all your projects.
-2.  **MCP Hub**: A Model Context Protocol server that exposes your code and knowledge to any MCP-compatible client.
-3.  **Semantic Search (RAG)**: Local, privacy-first vector indexing for deep codebase understanding.
-4.  **Structured Agent Pipelines**: Reusable prompts for Research, Planning, Execution, and Documentation.
+**Key Features:**
+- **Global Knowledge Base**: Centralized context management across all your projects (`~/.rrce-workflow/`).
+- **MCP Hub**: A Model Context Protocol server exposing tools, resources, and prompts to any MCP-compatible client.
+- **Semantic Search (RAG)**: Local, privacy-first vector indexing powered by `@xenova/transformers` for deep codebase understanding.
+- **Structured Agent Pipelines**: 7 specialized agents (Init, Research, Planning, Executor, Docs, Sync, Doctor) for end-to-end development workflows.
+- **Task Management**: Built-in CRUD operations for tracking high-level tasks via MCP tools.
 
 ---
 
@@ -58,7 +59,24 @@ RRCE-Workflow uses the [Model Context Protocol](https://modelcontextprotocol.io/
 ### Features
 *   **Universal Context**: Access your project's `project-context.md`, architecture docs, and task history from *any* MCP-enabled tool.
 *   **Cross-Project References**: Your AI can read documentation from Project A while working on Project B (perfect for monorepos or microservices).
-*   **Tools & Resources**: Exposes tools like `search_knowledge` and `get_project_context` directly to the model.
+*   **12 MCP Tools**: Including `search_knowledge`, `get_project_context`, `resolve_path`, task CRUD operations, and more.
+
+### MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `resolve_path` | Resolve RRCE configuration paths (RRCE_DATA, WORKSPACE_ROOT, etc.) for a project |
+| `list_projects` | List all projects exposed via MCP |
+| `get_project_context` | Get the project-context.md for a specific project |
+| `search_knowledge` | Semantic search (RAG) across project knowledge bases |
+| `index_knowledge` | Update the semantic search index for a project |
+| `list_agents` | List available RRCE agents and their arguments |
+| `get_agent_prompt` | Get the system prompt for a specific agent with context injection |
+| `list_tasks` | List all tasks for a project |
+| `get_task` | Get details of a specific task |
+| `create_task` | Create a new task in the project |
+| `update_task` | Update an existing task's meta.json |
+| `delete_task` | Delete a task from the project |
 
 ### Connecting Your IDE
 
@@ -149,36 +167,40 @@ Stores everything in a `.rrce-workflow` folder inside your project root.
 
 ---
 
-## 🤖 The Agent Pipeline
+## The Agent Pipeline
 
-Once installed, you gain access to powerful agent workflows. Invoke them using your AI assistant's chat interface (if supported) or by pasting the prompts.
+Once installed, you gain access to 7 specialized agent workflows. Invoke them via your AI assistant's chat interface or through MCP tools.
 
-| Agent | Purpose | Recommended Use |
-|-------|---------|-----------------|
-| **Init** | **Context Establishment** | Run once at project start to analyze tech stack & architecture. |
-| **Research** | **Scope Definition** | Use when starting a complex feature to clarify requirements & risks. |
-| **Planning** | **Execution Strategy** | Generates a step-by-step implementation plan (checklist). |
-| **Execute** | **Implementation** | The "coding" phase. Implements the plan created by the Planning agent. |
-| **Docs** | **Documentation** | Generates tailored docs (API refs, guides) from code. |
-| **Sync** | **Knowledge Maintenance** | Scans code changes to update the `knowledge/` folder. |
-| **Doctor** | **Health Analysis** | Analyzes codebase for issues, tech debt, and improvement opportunities. |
+| Agent | ID | Purpose | Key Arguments |
+|-------|----|---------|---------------|
+| **Init** | `init` | Analyze codebase, establish project context and semantic index | `PROJECT_NAME` (optional) |
+| **Research** | `research_discussion` | Interactive requirements clarification through dialogue | `TASK_SLUG`, `REQUEST` |
+| **Planning** | `planning_discussion` | Transform research into actionable execution plan | `TASK_SLUG` |
+| **Executor** | `executor` | Implement the plan - the ONLY agent authorized to modify code | `TASK_SLUG`, `BRANCH` |
+| **Docs** | `documentation` | Generate project documentation (API, architecture, changelog) | `DOC_TYPE`, `TASK_SLUG` |
+| **Sync** | `sync` | Reconcile knowledge base with current codebase state | `SCOPE` (optional) |
+| **Doctor** | `doctor` | Analyze codebase health, identify issues, recommend improvements | `PROJECT_NAME`, `FOCUS_AREA` |
 
 ### Recommended Workflow
-1.  **`/init`**: "Analyze this codebase." -> Creates `project-context.md`.
-2.  **`/research`**: "I need to add user auth." -> Generates a Research Brief.
-3.  **`/plan`**: "Create a plan for user auth." -> Generates an Implementation Plan.
-4.  **`/execute`**: "Implement the auth plan." -> Writes code across files.
-5.  **`/sync`**: "Update knowledge." -> Refreshes context for the next task.
+1.  **`init`**: "Analyze this codebase." → Creates `project-context.md` and semantic index.
+2.  **`research_discussion`**: "I need to add user auth." → Interactive requirements gathering.
+3.  **`planning_discussion`**: "Create a plan for user auth." → Generates implementation checklist.
+4.  **`executor`**: "Implement the auth plan." → Writes code, runs tests.
+5.  **`documentation`**: "Generate API docs." → Produces release-ready documentation.
+6.  **`sync`**: "Update knowledge." → Refreshes context for the next task.
 
 ---
 
-## 🔍 Semantic Search (RAG)
+## Semantic Search (RAG)
 
-RRCE-Workflow includes a local, embedding-based search engine.
--   **Privacy First**: All embeddings are calculated locally on your CPU/GPU. No code leaves your machine.
--   **Smart Context**: Allows the agent to find relevant code snippets via natural language queries (e.g., "Find the authentication middleware logic") even if keywords don't match exactly.
+RRCE-Workflow includes a local, embedding-based search engine powered by `@xenova/transformers`.
 
-RAG is enabled by default in Express Setup. You can toggle it per-project in the MCP Dashboard.
+-   **Privacy First**: All embeddings are calculated locally. No code leaves your machine.
+-   **Full Codebase Indexing**: The `index_knowledge` tool scans your entire source tree (respecting skip lists like `node_modules`, `.git`).
+-   **Smart Fallback**: If RAG fails or isn't enabled, `search_knowledge` performs line-by-line text matching.
+-   **Model**: Uses `Xenova/all-MiniLM-L6-v2` by default (configurable per-project).
+
+RAG is enabled by default in Express Setup. You can toggle it per-project in the MCP Dashboard or via `config.yaml`.
 
 ---
 
@@ -187,6 +209,16 @@ RAG is enabled by default in Express Setup. You can toggle it per-project in the
 -   **Node.js 18+**
 -   **Git**
 
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| TUI Framework | Ink ^6.6.0 (React-based) |
+| MCP Server | @modelcontextprotocol/sdk ^1.25.1 |
+| Embeddings | @xenova/transformers ^2.17.2 |
+| Build | esbuild |
+| Runtime | Node.js >= 18 |
+
 ## License
 
 MIT © RRCE Team

package/dist/index.js

@@ -1,11 +1,5 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -1568,6 +1562,33 @@ var init_rag = __esm({
           logger.error(`[RAG] Failed to save index to ${this.indexPath}`, error);
         }
       }
+      /**
+       * Save index to a temp file and atomically replace
+       */
+      saveIndexAtomic() {
+        if (!this.index) return;
+        const dir = path15.dirname(this.indexPath);
+        if (!fs13.existsSync(dir)) {
+          fs13.mkdirSync(dir, { recursive: true });
+        }
+        const tmpPath = `${this.indexPath}.tmp`;
+        fs13.writeFileSync(tmpPath, JSON.stringify(this.index, null, 2));
+        fs13.renameSync(tmpPath, this.indexPath);
+      }
+      /**
+       * Save index only if enough time passed since last save
+       */
+      maybeSaveIndex(force = false) {
+        if (!this.index) return;
+        const now = Date.now();
+        const intervalMs = 1e3;
+        const last = this.index.metadata?.lastSaveAt;
+        if (force || last === void 0 || now - last >= intervalMs) {
+          this.index.metadata = { ...this.index.metadata ?? {}, lastSaveAt: now };
+          this.saveIndexAtomic();
+          logger.info(`[RAG] Saved index (atomic) to ${this.indexPath} with ${this.index.chunks.length} chunks.`);
+        }
+      }
       /**
        * Generate embedding for text
        */
@@ -1618,7 +1639,7 @@ var init_rag = __esm({
           mtime: mtime ?? Date.now(),
           chunkCount: chunks.length
         };
-        this.saveIndex();
+        this.maybeSaveIndex();
         return true;
       }
       /**
@@ -1634,7 +1655,7 @@ var init_rag = __esm({
         }
         if (this.index.chunks.length !== initialCount) {
           logger.info(`[RAG] Removed file ${filePath} from index (${initialCount - this.index.chunks.length} chunks removed)`);
-          this.saveIndex();
+          this.maybeSaveIndex(true);
         }
       }
       /**
@@ -1657,7 +1678,7 @@ var init_rag = __esm({
         this.loadIndex();
         if (!this.index) return;
         this.index.lastFullIndex = Date.now();
-        this.saveIndex();
+        this.maybeSaveIndex(true);
       }
       /**
        * Search the index
@@ -1687,9 +1708,11 @@ var init_rag = __esm({
         let normA = 0;
         let normB = 0;
         for (let i = 0; i < a.length; i++) {
-          dotProduct += a[i] * b[i];
-          normA += a[i] * a[i];
-          normB += b[i] * b[i];
+          const av = a[i] ?? 0;
+          const bv = b[i] ?? 0;
+          dotProduct += av * bv;
+          normA += av * av;
+          normB += bv * bv;
         }
         return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
       }
@@ -1722,9 +1745,87 @@ var init_rag = __esm({
   }
 });
 
+// src/mcp/services/indexing-jobs.ts
+var IndexingJobManager, indexingJobs;
+var init_indexing_jobs = __esm({
+  "src/mcp/services/indexing-jobs.ts"() {
+    "use strict";
+    init_logger();
+    IndexingJobManager = class {
+      jobs = /* @__PURE__ */ new Map();
+      getProgress(project) {
+        const existing = this.jobs.get(project);
+        if (existing) return { ...existing.progress };
+        return {
+          project,
+          state: "idle",
+          itemsDone: 0,
+          itemsTotal: void 0
+        };
+      }
+      update(project, patch) {
+        const existing = this.jobs.get(project);
+        const next = {
+          ...existing?.progress ?? this.getProgress(project),
+          ...patch,
+          project
+        };
+        this.jobs.set(project, { ...existing ?? { progress: next }, progress: next });
+      }
+      isRunning(project) {
+        return this.getProgress(project).state === "running";
+      }
+      startOrStatus(project, runner) {
+        const current = this.jobs.get(project);
+        if (current?.progress.state === "running" && current.promise) {
+          return {
+            status: "already_running",
+            state: "running",
+            progress: { ...current.progress }
+          };
+        }
+        const startedAt = Date.now();
+        const initial = {
+          project,
+          state: "running",
+          startedAt,
+          itemsDone: 0,
+          itemsTotal: void 0,
+          currentItem: void 0,
+          lastError: void 0
+        };
+        const job = { progress: initial };
+        this.jobs.set(project, job);
+        job.promise = (async () => {
+          try {
+            await runner();
+            this.update(project, { state: "complete", completedAt: Date.now(), currentItem: void 0 });
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`[RAG] Indexing job failed for '${project}'`, err);
+            this.update(project, {
+              state: "failed",
+              completedAt: Date.now(),
+              currentItem: void 0,
+              lastError: msg
+            });
+          }
+        })();
+        return {
+          status: "started",
+          state: "running",
+          progress: { ...this.getProgress(project) }
+        };
+      }
+    };
+    indexingJobs = new IndexingJobManager();
+  }
+});
+
 // src/mcp/resources.ts
 import * as fs14 from "fs";
 import * as path16 from "path";
+import * as os2 from "os";
 import * as crypto from "crypto";
 function resolveProjectPaths(project, pathInput) {
   const config = loadMCPConfig();
@@ -1892,6 +1993,8 @@ async function searchKnowledge(query, projectFilter) {
     if (projectFilter && project.name !== projectFilter) continue;
     const permissions = getProjectPermissions(config, project.name, project.sourcePath || project.path);
     if (!permissions.knowledge || !project.knowledgePath) continue;
+    const indexingInProgress = indexingJobs.isRunning(project.name);
+    const advisoryMessage = indexingInProgress ? "Indexing in progress; results may be stale/incomplete." : void 0;
     const projConfig = config.projects.find(
       (p) => p.path && normalizeProjectPath(p.path) === normalizeProjectPath(project.sourcePath || project.path) || !p.path && p.name === project.name
     );
@@ -1908,7 +2011,9 @@ async function searchKnowledge(query, projectFilter) {
             file: path16.relative(project.knowledgePath, r.filePath),
             matches: [r.content],
             // The chunk content is the match
-            score: r.score
+            score: r.score,
+            indexingInProgress: indexingInProgress || void 0,
+            advisoryMessage
           });
         }
         continue;
@@ -1933,8 +2038,10 @@ async function searchKnowledge(query, projectFilter) {
           results.push({
             project: project.name,
             file,
-            matches: matches.slice(0, 5)
+            matches: matches.slice(0, 5),
             // Limit to 5 matches per file
+            indexingInProgress: indexingInProgress || void 0,
+            advisoryMessage
           });
         }
       }
@@ -1946,20 +2053,44 @@ async function searchKnowledge(query, projectFilter) {
 async function indexKnowledge(projectName, force = false) {
   const config = loadMCPConfig();
   const projects = getExposedProjects();
-  const project = projects.find((p) => p.name === projectName || p.path && p.path === projectName);
+  const project = projects.find((p2) => p2.name === projectName || p2.path && p2.path === projectName);
   if (!project) {
-    return { success: false, message: `Project '${projectName}' not found`, filesIndexed: 0, filesSkipped: 0 };
+    return {
+      state: "failed",
+      status: "failed",
+      success: false,
+      message: `Project '${projectName}' not found`,
+      filesIndexed: 0,
+      filesSkipped: 0,
+      progress: { itemsDone: 0 }
+    };
   }
   const projConfig = config.projects.find(
-    (p) => p.path && normalizeProjectPath(p.path) === normalizeProjectPath(project.sourcePath || project.path) || !p.path && p.name === project.name
+    (p2) => p2.path && normalizeProjectPath(p2.path) === normalizeProjectPath(project.sourcePath || project.path) || !p2.path && p2.name === project.name
   ) || (project.source === "global" ? { semanticSearch: { enabled: true, model: "Xenova/all-MiniLM-L6-v2" } } : void 0);
   const isEnabled = projConfig?.semanticSearch?.enabled || project.semanticSearchEnabled;
   if (!isEnabled) {
-    return { success: false, message: "Semantic Search is not enabled for this project", filesIndexed: 0, filesSkipped: 0 };
+    return {
+      state: "failed",
+      status: "failed",
+      success: false,
+      message: "Semantic Search is not enabled for this project",
+      filesIndexed: 0,
+      filesSkipped: 0,
+      progress: { itemsDone: 0 }
+    };
   }
   const scanRoot = project.sourcePath || project.path || project.dataPath;
   if (!fs14.existsSync(scanRoot)) {
-    return { success: false, message: "Project root not found", filesIndexed: 0, filesSkipped: 0 };
+    return {
+      state: "failed",
+      status: "failed",
+      success: false,
+      message: "Project root not found",
+      filesIndexed: 0,
+      filesSkipped: 0,
+      progress: { itemsDone: 0 }
+    };
   }
   const INDEXABLE_EXTENSIONS = [
     ".ts",
@@ -2000,18 +2131,37 @@ async function indexKnowledge(projectName, force = false) {
     ".less"
   ];
   const SKIP_DIRS = ["node_modules", ".git", "dist", "build", ".next", "__pycache__", "venv", ".venv", "target", "vendor"];
-  try {
+  const runIndexing = async () => {
     const indexPath = path16.join(project.knowledgePath || path16.join(scanRoot, ".rrce-workflow", "knowledge"), "embeddings.json");
     const model = projConfig?.semanticSearch?.model || "Xenova/all-MiniLM-L6-v2";
     const rag = new RAGService(indexPath, model);
     let indexed = 0;
     let skipped = 0;
+    let itemsTotal = 0;
+    let itemsDone = 0;
+    const shouldSkipDir = (dirName) => SKIP_DIRS.includes(dirName) || dirName.startsWith(".");
+    const preCount = (dir) => {
+      const entries = fs14.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path16.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (shouldSkipDir(entry.name)) continue;
+          preCount(fullPath);
+        } else if (entry.isFile()) {
+          const ext = path16.extname(entry.name).toLowerCase();
+          if (!INDEXABLE_EXTENSIONS.includes(ext)) continue;
+          itemsTotal++;
+        }
+      }
+    };
+    preCount(scanRoot);
+    indexingJobs.update(project.name, { itemsTotal });
     const scanDir = async (dir) => {
       const entries = fs14.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
         const fullPath = path16.join(dir, entry.name);
         if (entry.isDirectory()) {
-          if (SKIP_DIRS.includes(entry.name) || entry.name.startsWith(".")) {
+          if (shouldSkipDir(entry.name)) {
             continue;
           }
           await scanDir(fullPath);
@@ -2021,6 +2171,7 @@ async function indexKnowledge(projectName, force = false) {
             continue;
           }
           try {
+            indexingJobs.update(project.name, { currentItem: fullPath, itemsDone });
             const stat = fs14.statSync(fullPath);
             const mtime = force ? void 0 : stat.mtimeMs;
             const content = fs14.readFileSync(fullPath, "utf-8");
@@ -2031,6 +2182,12 @@ async function indexKnowledge(projectName, force = false) {
               skipped++;
             }
           } catch (err) {
+          } finally {
+            itemsDone++;
+            indexingJobs.update(project.name, { itemsDone });
+            if (itemsDone % 10 === 0) {
+              await new Promise((resolve2) => setImmediate(resolve2));
+            }
           }
         }
       }
@@ -2038,22 +2195,35 @@ async function indexKnowledge(projectName, force = false) {
     await scanDir(scanRoot);
     rag.markFullIndex();
     const stats = rag.getStats();
-    return {
-      success: true,
-      message: `Indexed ${indexed} files, skipped ${skipped} unchanged. Total: ${stats.totalChunks} chunks from ${stats.totalFiles} files.`,
-      filesIndexed: indexed,
-      filesSkipped: skipped
-    };
-  } catch (error) {
-    return { success: false, message: `Indexing failed: ${error}`, filesIndexed: 0, filesSkipped: 0 };
-  }
+    const message = `Indexed ${indexed} files, skipped ${skipped} unchanged. Total: ${stats.totalChunks} chunks from ${stats.totalFiles} files.`;
+    logger.info(`[RAG] ${project.name}: ${message}`);
+    indexingJobs.update(project.name, { currentItem: void 0 });
+  };
+  const startResult = indexingJobs.startOrStatus(project.name, runIndexing);
+  const p = startResult.progress;
+  return {
+    state: startResult.state,
+    status: startResult.status,
+    success: startResult.status === "started" || startResult.status === "already_running",
+    message: startResult.status === "started" ? `Indexing started in background for '${project.name}'.` : `Indexing already running for '${project.name}'.`,
+    filesIndexed: 0,
+    filesSkipped: 0,
+    progress: {
+      itemsDone: p.itemsDone,
+      itemsTotal: p.itemsTotal,
+      currentItem: p.currentItem,
+      startedAt: p.startedAt,
+      completedAt: p.completedAt,
+      lastError: p.lastError
+    }
+  };
 }
 function getContextPreamble() {
   const projects = getExposedProjects();
   const activeProject = detectActiveProject();
   let contextPreamble = "";
   if (activeProject) {
-    const rrceHome = process.env.RRCE_HOME || path16.join(__require("os").homedir(), ".rrce-workflow");
+    const rrceHome = process.env.RRCE_HOME || path16.join(os2.homedir(), ".rrce-workflow");
     const workspaceRoot = activeProject.sourcePath || activeProject.path || activeProject.dataPath;
     const rrceData = activeProject.dataPath;
     contextPreamble += `
@@ -2123,7 +2293,7 @@ async function createTask(projectName, taskSlug, taskData) {
   fs14.mkdirSync(path16.join(taskDir, "planning"), { recursive: true });
   fs14.mkdirSync(path16.join(taskDir, "execution"), { recursive: true });
   fs14.mkdirSync(path16.join(taskDir, "docs"), { recursive: true });
-  const rrceHome = process.env.RRCE_HOME || path16.join(__require("os").homedir(), ".rrce-workflow");
+  const rrceHome = process.env.RRCE_HOME || path16.join(os2.homedir(), ".rrce-workflow");
   const templatePath = path16.join(rrceHome, "templates", "meta.template.json");
   let meta = {
     task_id: crypto.randomUUID(),
@@ -2194,6 +2364,7 @@ var init_resources = __esm({
     init_detection();
     init_detection_service();
     init_rag();
+    init_indexing_jobs();
     init_paths();
   }
 });
@@ -3445,6 +3616,7 @@ var IndexingStatus;
 var init_IndexingStatus = __esm({
   "src/mcp/ui/IndexingStatus.tsx"() {
     "use strict";
+    init_indexing_jobs();
     init_rag();
     init_resources();
     init_config_utils();
@@ -3461,9 +3633,14 @@ var init_IndexingStatus = __esm({
             }
             const enabled = projConfig?.semanticSearch?.enabled || project.semanticSearchEnabled || false;
             if (!enabled) {
+              const prog = indexingJobs.getProgress(project.name);
               newStats.push({
                 projectName: project.name,
                 enabled: false,
+                state: prog.state,
+                itemsDone: prog.itemsDone,
+                itemsTotal: prog.itemsTotal,
+                currentItem: prog.currentItem,
                 totalFiles: 0,
                 totalChunks: 0
               });
@@ -3473,17 +3650,27 @@ var init_IndexingStatus = __esm({
               const indexPath = getRAGIndexPath(project);
               const rag = new RAGService(indexPath, "dummy");
               const s = rag.getStats();
+              const prog = indexingJobs.getProgress(project.name);
               newStats.push({
                 projectName: project.name,
                 enabled: true,
+                state: prog.state,
+                itemsDone: prog.itemsDone,
+                itemsTotal: prog.itemsTotal,
+                currentItem: prog.currentItem,
                 totalFiles: s.totalFiles,
                 totalChunks: s.totalChunks,
                 lastFullIndex: s.lastFullIndex
               });
             } catch (e) {
+              const prog = indexingJobs.getProgress(project.name);
               newStats.push({
                 projectName: project.name,
                 enabled: true,
+                state: prog.state,
+                itemsDone: prog.itemsDone,
+                itemsTotal: prog.itemsTotal,
+                currentItem: prog.currentItem,
                 totalFiles: 0,
                 totalChunks: 0,
                 error: String(e)
@@ -3506,13 +3693,16 @@ var init_IndexingStatus = __esm({
           /* @__PURE__ */ jsxs8(Box9, { children: [
             /* @__PURE__ */ jsx9(Box9, { width: 25, children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "Project" }) }),
             /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "Status" }) }),
+            /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "State" }) }),
+            /* @__PURE__ */ jsx9(Box9, { width: 18, children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "Progress" }) }),
             /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "Indexed Files" }) }),
             /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "Total Chunks" }) }),
             /* @__PURE__ */ jsx9(Box9, { children: /* @__PURE__ */ jsx9(Text9, { underline: true, children: "Last Index" }) })
           ] }),
           stats.length === 0 ? /* @__PURE__ */ jsx9(Text9, { color: "dim", children: "No exposed projects found." }) : stats.map((s) => /* @__PURE__ */ jsxs8(Box9, { marginTop: 0, children: [
             /* @__PURE__ */ jsx9(Box9, { width: 25, children: /* @__PURE__ */ jsx9(Text9, { color: "white", children: s.projectName }) }),
-            /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { color: s.enabled ? "green" : "dim", children: s.enabled ? "Enabled" : "Disabled" }) }),
+            /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { color: s.state === "running" ? "yellow" : s.state === "failed" ? "red" : s.enabled ? "green" : "dim", children: s.enabled ? s.state : "disabled" }) }),
+            /* @__PURE__ */ jsx9(Box9, { width: 18, children: /* @__PURE__ */ jsx9(Text9, { children: s.state === "running" ? `${s.itemsDone}/${s.itemsTotal ?? "?"}` : "-" }) }),
             /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { children: s.enabled ? s.totalFiles : "-" }) }),
             /* @__PURE__ */ jsx9(Box9, { width: 15, children: /* @__PURE__ */ jsx9(Text9, { children: s.enabled ? s.totalChunks : "-" }) }),
             /* @__PURE__ */ jsx9(Box9, { children: /* @__PURE__ */ jsx9(Text9, { children: s.lastFullIndex ? new Date(s.lastFullIndex).toLocaleTimeString() : "-" }) })

package/docs/architecture.md

@@ -1,17 +1,19 @@
 # RRCE-Workflow Architecture
 
 > RR Context Engineering Workflow - A selection-agnostic agentic workflow system
+> 
+> **Version**: 0.2.91 | **Last Updated**: 2025-12-31
 
 ## Overview
 
 RRCE-Workflow is a TUI-based agentic code workflow generator designed to work seamlessly across:
-- **GitHub Copilot CLI**
+- **OpenCode** (Native agentic TUI environment with custom Primary Agents)
+- **GitHub Copilot** (VSCode with MCP extension)
 - **Antigravity IDE** (Google's agentic coding environment)
-- **OpenCode** (Native agentic TUI environment)
-- **VS Code** (with Copilot and other AI extensions)
-- **Claude Desktop**
+- **Claude Desktop** (MCP Server integration)
+- **Any MCP-compatible client**
 
-The system provides a structured multi-agent pipeline for software development tasks, with persistent knowledge caching and workspace-aware context management.
+The system provides a structured multi-agent pipeline (7 agents) for software development tasks, with persistent knowledge caching, semantic search (RAG), and workspace-aware context management.
 
 ## Core Principles
 
@@ -24,38 +26,79 @@ The system provides a structured multi-agent pipeline for software development t
 
 ## Directory Structure
 
+### Source Code Organization
+
+```
+rrce-workflow/
+├── agent-core/           # Agent prompts and templates (Source of Truth)
+│   ├── prompts/          # 7 agent system prompts (doctor, executor, init, etc.)
+│   ├── templates/        # Output templates for agents
+│   │   └── docs/         # Doc-type specific templates
+│   └── docs/             # Internal documentation (path-resolution.md)
+├── bin/                  # Executable entry points
+│   └── rrce-workflow.js  # NPM binary wrapper
+├── docs/                 # High-level architecture docs (this file)
+├── scripts/              # Maintenance and verification scripts
+├── src/                  # Source code
+│   ├── commands/         # CLI/TUI command implementations
+│   │   └── wizard/       # Interactive setup wizard (setup-flow, link-flow, etc.)
+│   ├── lib/              # Core utilities
+│   │   ├── detection.ts  # Project scanning and detection (DetectedProject)
+│   │   ├── detection-service.ts  # Singleton project service
+│   │   ├── git.ts        # Git utilities
+│   │   ├── paths.ts      # Path resolution (RRCE_HOME, RRCE_DATA, etc.)
+│   │   └── preferences.ts # User preference storage
+│   ├── mcp/              # MCP Server implementation
+│   │   ├── handlers/     # Decomposed request handlers
+│   │   │   ├── prompts.ts   # Prompt/agent handlers
+│   │   │   ├── resources.ts # Resource handlers
+│   │   │   └── tools.ts     # 12 MCP tools (search, index, tasks, etc.)
+│   │   ├── services/     # Backend services
+│   │   │   └── rag.ts    # Semantic search with @xenova/transformers
+│   │   ├── ui/           # TUI components (Ink/React)
+│   │   │   └── components/ # Reusable UI components
+│   │   ├── config.ts     # MCP configuration management
+│   │   ├── resources.ts  # Project data access utilities
+│   │   └── server.ts     # MCP Server entry point (Stdio transport)
+│   └── types/            # Global TypeScript definitions
+└── temp_rag_test/        # RAG testing environment
+```
+
 ### Global Installation (`~/.rrce-workflow/`)
 
 ```
 ~/.rrce-workflow/
-├── config.yaml                              # User global configuration
-├── templates/                               # Default template store
-│   ├── meta.template.json                   # Task metadata template
-│   ├── research_output.md                   # Research brief template
-│   ├── planning_output.md                   # Execution plan template
-│   ├── executor_output.md                   # Implementation log template
-│   ├── documentation_output.md              # Handover note template
-│   └── docs/                                # Doc-type specific templates
-│       └── <doc-type>.md
-└── workspaces/                              # Project-scoped cache
-    └── <workspace-hash>/                    # SHA256 of workspace path
-        ├── workspace.json                   # Workspace metadata
-        ├── knowledge/                       # Project domain knowledge
-        │   └── <domain>.md
-        └── tasks/                           # Task state and artifacts
+├── mcp.yaml                             # MCP server configuration (projects, permissions)
+├── preferences.json                     # User preferences (global path overrides)
+├── templates/                           # Default template store
+│   ├── meta.template.json               # Task metadata template
+│   └── docs/                            # Doc-type specific templates
+└── workspaces/                          # Project-scoped data (Global Mode)
+    └── <workspace-name>/                # Named by project, not hash
+        ├── config.yaml                  # Project configuration
+        ├── knowledge/                   # Project domain knowledge
+        │   ├── project-context.md       # Main context file
+        │   ├── embeddings.json          # RAG vector index
+        │   └── <topic>.md               # Additional knowledge files
+        ├── refs/                        # Reference documents
+        └── tasks/                       # Task state and artifacts
             └── <task-slug>/
-                ├── meta.json                # Task metadata and status
-                ├── research/                # Research artifacts
-                ├── planning/                # Planning artifacts
-                ├── execution/               # Execution logs
-                └── docs/                    # Generated documentation
+                ├── meta.json            # Task metadata, checklist, agent status
+                ├── research/            # Research artifacts
+                ├── planning/            # Planning artifacts
+                ├── execution/           # Execution logs
+                └── docs/                # Generated documentation
 ```
 
-### Workspace Configuration (Optional)
+### Workspace Mode (`.rrce-workflow/`)
 
 ```
 <workspace>/
-└── .rrce-workflow.yaml                      # Project-specific config
+└── .rrce-workflow/
+    ├── config.yaml                      # Project-specific config
+    ├── knowledge/                       # Project knowledge (same structure as global)
+    ├── refs/
+    └── tasks/
 ```
 
 ---
@@ -69,19 +112,28 @@ The system provides a structured multi-agent pipeline for software development t
 | `global` (default) | `~/.rrce-workflow/workspaces/<workspace-name>/` | Non-intrusive, survives repo deletion |
 | `workspace` | `<workspace>/.rrce-workflow/` | Portable, team-shareable |
 
-Configure via `.rrce-workflow.yaml`:
+Configure via `config.yaml`:
 ```yaml
-storage:
-  mode: global  # or: workspace
+mode: global  # or: workspace
+name: my-project
+sourcePath: /path/to/source  # For global mode: links data back to source
 ```
 
+### Key Path Functions (`src/lib/paths.ts`)
+
+| Function | Purpose |
+|----------|---------|
+| `getEffectiveGlobalPath()` | Returns RRCE_HOME respecting user preferences |
+| `getConfigPath(workspaceRoot)` | Finds config.yaml (local or global) |
+| `resolveDataPath(mode, name, root)` | Resolves RRCE_DATA based on storage mode |
+| `detectWorkspaceRoot()` | Walks up from CWD to find project root |
+
 ### Environment Variables
 
 | Variable | Purpose | Default |
 |----------|---------|---------|
 | `RRCE_HOME` | Global installation path | `~/.rrce-workflow` |
 | `RRCE_WORKSPACE` | Explicit workspace root | Auto-detected |
-| `RRCE_AUTHOR` | Default author name | From `config.yaml` |
 
 ### Template Variables
 
@@ -89,7 +141,7 @@ storage:
 |----------|-------------|
 | `{{RRCE_HOME}}` | Global installation path |
 | `{{RRCE_DATA}}` | Data path (based on storage mode) |
-| `{{WORKSPACE_ROOT}}` | Workspace directory |
+| `{{WORKSPACE_ROOT}}` | Workspace directory (source code location) |
 | `{{WORKSPACE_NAME}}` | Project name (from config or directory) |
 
 ### Workspace Detection Algorithm
@@ -98,10 +150,32 @@ storage:
 1. If $RRCE_WORKSPACE is set → use it
 2. Walk up from CWD, find first directory containing:
    - .git/
-   - .rrce-workflow.yaml
+   - .rrce-workflow/config.yaml (new)
+   - .rrce-workflow.yaml (legacy)
 3. Fall back to CWD
 ```
 
+### Project Detection (`src/lib/detection.ts`)
+
+The `DetectedProject` interface captures:
+```typescript
+interface DetectedProject {
+  name: string;
+  path: string;           // Absolute path to project root
+  dataPath: string;       // Path to .rrce-workflow data directory
+  source: 'global' | 'local';
+  sourcePath?: string;    // For global mode: actual source code location
+  knowledgePath?: string;
+  tasksPath?: string;
+  semanticSearchEnabled?: boolean;
+}
+```
+
+Scanning priority:
+1. Known projects from MCP config (name + path)
+2. Global storage (`~/.rrce-workflow/workspaces/`)
+3. Home directory recursive scan (up to depth 5)
+
 ### Cross-Project References
 
 Reference another project's context when needed:
@@ -125,13 +199,13 @@ Reference another project's context when needed:
                                     └────────┬────────┘
                                              │
                                              ▼
-                                  project-context.md
+                                  project-context.md + embeddings.json
                                              │
         ┌────────────────────────────────────┴────────────────────────────────────┐
         ▼                                                                          │
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
 │    Research     │────▶│    Planning     │────▶│    Executor     │────▶│  Documentation  │
-│   & Discussion  │     │  Orchestrator   │     │                 │     │                 │
+│   Discussion    │     │   Discussion    │     │ (Code Changes)  │     │                 │
 └─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │                       │
         ▼                       ▼                       ▼                       ▼
@@ -139,43 +213,74 @@ Reference another project's context when needed:
         │                       │                       │                       │
         └───────────────────────┴───────────────────────┴───────────────────────┘
                                         │
-                                        ▼
-                            {{RRCE_CACHE}}/knowledge/
-                              (Persistent Context)
+                               ┌────────┴────────┐
+                               ▼                 ▼
+                       {{RRCE_DATA}}/      ┌─────────────────┐
+                         knowledge/        │      Sync       │
+                                           │ (Reconciliation)│
+                                           └────────┬────────┘
+                                                    │
+                                           ┌────────┴────────┐
+                                           ▼                 ▼
+                                       Doctor           (Next Task)
+                                    (Health Check)
 ```
 
 ### Agent Responsibilities
 
-| Agent | Role | Input | Output |
-|-------|------|-------|--------|
-| **Init** | Analyze codebase, establish project context | Workspace files | `project-context.md` |
-| **Research & Discussion** | Clarify requirements, surface risks | User request + context | Requirements brief |
-| **Planning Orchestrator** | Create actionable execution plan | Research brief | Prioritized task breakdown |
-| **Executor** | Implement and verify | Plan + skill scope | Code + execution log |
-| **Documentation** | Synthesize and handover | All artifacts | Release-ready docs |
-| **Sync** | Reconcile knowledge | Codebase state | Updated knowledge files |
+| Agent | ID | Role | Input | Output |
+|-------|-----|------|-------|--------|
+| **Init** | `init` | Analyze codebase, establish project context, build RAG index | Workspace files | `project-context.md`, `embeddings.json` |
+| **Research** | `research_discussion` | Interactive requirements clarification, surface risks | User request + context | Research brief |
+| **Planning** | `planning_discussion` | Create actionable execution plan with checklist | Research brief | Prioritized task breakdown |
+| **Executor** | `executor` | Implement and verify - ONLY agent that modifies code | Plan + skill scope | Code + execution log |
+| **Documentation** | `documentation` | Synthesize and handover | All artifacts | Release-ready docs |
+| **Sync** | `sync` | Reconcile knowledge with codebase state | Codebase state | Updated knowledge files |
+| **Doctor** | `doctor` | Analyze codebase health using semantic search | Project + focus area | Health report, improvement tasks |
 
 ---
 
 ## Configuration
 
-### Global Config (`~/.rrce-workflow/config.yaml`)
+### MCP Configuration (`~/.rrce-workflow/mcp.yaml`)
 
 ```yaml
-version: 1
+# Projects exposed to MCP clients
+projects:
+  - name: my-project
+    path: /path/to/my-project
+    permissions:
+      knowledge: true
+      tasks: true
+      prompts: true
+    semanticSearch:
+      enabled: true
+      model: Xenova/all-MiniLM-L6-v2
+```
 
-# User identity
-author: "your-name"
-email: "your@email.com"
+### Project Config (`<workspace>/.rrce-workflow/config.yaml` or global)
 
-# Default behaviors
-defaults:
-  auto_create_workspace_cache: true
-  sync_after_execution: false
-  
-# Editor integration hints (informational)
-editor:
-  preferred: "vscode"  # vscode | antigravity | vim | etc.
+```yaml
+name: my-project
+mode: global  # or: workspace
+sourcePath: /path/to/source  # For global mode
+
+# Semantic search configuration
+semantic_search:
+  enabled: true
+
+# Cross-project linking
+linked_projects:
+  - other-project
+```
+
+### User Preferences (`~/.rrce-workflow/preferences.json`)
+
+```json
+{
+  "defaultGlobalPath": "/custom/path/.rrce-workflow",
+  "useCustomGlobalPath": true
+}
 ```
 
 ### Project Config (`<workspace>/.rrce-workflow.yaml`)
@@ -205,89 +310,78 @@ author: "maintainer-name"    # Overrides global config for this project
 
 ## Prompt Frontmatter Schema
 
-All agent prompts use YAML frontmatter for metadata and tool compatibility:
+All agent prompts in `agent-core/prompts/` use YAML frontmatter for metadata:
 
 ```yaml
 ---
-description: Brief description of the agent's purpose
-argument-hint: CLI-style argument hint for display
-agent: agent | ask | edit              # Copilot mode
-tools: ['search/codebase', ...]        # Available Copilot tools
-required-args:
-  - name: ARG_NAME
-    prompt: "Interactive prompt if arg is missing"
-optional-args:
-  - name: ARG_NAME
-    default: "default value"
-auto-identity:
-  user: "$GIT_USER"      # Auto-detect from `git config user.name`
-  model: "$AGENT_MODEL"  # Auto-detect from runtime (gemini-2.0, claude-sonnet, etc.)
+name: RRCE Executor
+description: Execute the planned tasks to deliver working code and tests.
+tools:
+  - read
+  - write
+  - edit
+  - bash
+  - glob
+  - grep
+  - search_knowledge        # MCP tool (becomes rrce_search_knowledge in OpenCode)
+  - get_project_context     # MCP tool
+  - update_task             # MCP tool
+arguments:
+  - name: TASK_SLUG
+    description: Enter the task slug to execute
+    required: true
+  - name: BRANCH
+    description: Git branch for the work
+    required: false
 ---
-```
 
-### Auto-Identity
+# Agent System Prompt Content...
+```
 
-Identity is automatically detected - no user input required:
+### Tool Categories
 
-| Variable | Source | Example |
-|----------|--------|---------|
-| `$GIT_USER` | `git config user.name` | "John Doe" |
-| `$AGENT_MODEL` | Runtime environment | "gemini-2.0-flash", "claude-sonnet-4" |
+| Category | Tools | Notes |
+|----------|-------|-------|
+| **Host Tools** | `read`, `write`, `edit`, `bash`, `grep`, `glob`, `webfetch` | Native to host environment |
+| **MCP Tools** | `search_knowledge`, `get_project_context`, `list_tasks`, etc. | Prefixed with `rrce_` in OpenCode |
 
 ---
 
 ## Multi-Tool Integration
 
-RRCE-Workflow prompts are designed to work across multiple AI coding tools:
+RRCE-Workflow prompts are designed to work across multiple AI coding tools via MCP and IDE-specific agent generation.
 
 ### Tool Support Matrix
 
-| Tool | Prompt Location | Extension | Notes |
-|------|----------------|-----------|-------|
-| **Antigravity IDE** | `.agent/workflows/` | `.md` | Native workflow support |
-| **OpenCode** | `.opencode/agent/` | `.md` | Custom Primary Agents |
-| **GitHub Copilot (VSCode)** | `.github/agents/` | `.agent.md` | Custom agents format |
-| **Copilot CLI** | Any location | `.md` | Reference via file path |
-
-### Wizard Command
+| Tool | MCP Config Location | Agent Location | Notes |
+|------|---------------------|----------------|-------|
+| **OpenCode** | `~/.config/opencode/opencode.json` | `.opencode/agent/rrce-*.md` | Custom Primary Agents (Tab to switch) |
+| **Antigravity IDE** | `~/.gemini/antigravity/mcp_config.json` | `.agent/workflows/*.md` | Native workflow support |
+| **GitHub Copilot (VSCode)** | `.vscode/mcp.json` or global settings | `.github/prompts/*.prompt.md` | Custom agents format |
+| **Claude Desktop** | `~/.config/claude/claude_desktop_config.json` | N/A | MCP Server only |
 
-The TUI provides an interactive wizard to set up prompts for your preferred tools:
+### OpenCode Agent Transformation
 
-```
-$ rrce-workflow wizard
-
-┌─────────────────────────────────────────────────────────┐
-│  RRCE-Workflow Project Setup                            │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  Which AI tools do you use?                             │
-│                                                         │
-│  [x] GitHub Copilot (VSCode)                            │
-│  [x] Antigravity IDE                                    │
-│  [ ] Copilot CLI only                                   │
-│                                                         │
-│  ─────────────────────────────────────────────────────  │
-│                                                         │
-│  ✓ Created .github/prompts/*.prompt.md                  │
-│  ✓ Created .agent/workflows/*.md                        │
-│  ✓ Initialized project context                          │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
+When generating agents for OpenCode (`src/commands/wizard/utils.ts`):
+- **Mode**: Set to `primary` (enables Tab cycling in TUI)
+- **Tools**: 
+  - Host tools (`read`, `write`, `edit`, `bash`, `grep`, `glob`, `webfetch`) pass through as-is
+  - MCP tools are prefixed with `rrce_` (e.g., `rrce_search_knowledge`)
+  - Tool list respects per-agent frontmatter restrictions
+- **Naming**: Agents prefixed with `rrce-` to avoid collisions
 
 ### Generated Files
 
-When you run `rrce-workflow wizard`, it creates:
-
-**For GitHub Copilot (VSCode):**
+**For OpenCode:**
 ```
-.github/prompts/
-├── init.prompt.md
-├── research.prompt.md
-├── planning.prompt.md
-├── executor.prompt.md
-├── documentation.prompt.md
-└── sync.prompt.md
+.opencode/agent/
+├── rrce-init.md
+├── rrce-research.md
+├── rrce-planning.md
+├── rrce-executor.md
+├── rrce-documentation.md
+├── rrce-sync.md
+└── rrce-doctor.md
 ```
 
 **For Antigravity IDE:**
@@ -298,55 +392,81 @@ When you run `rrce-workflow wizard`, it creates:
 ├── planning.md
 ├── executor.md
 ├── documentation.md
-└── sync.md
+├── sync.md
+└── doctor.md
 ```
 
-**For OpenCode:**
+**For GitHub Copilot (VSCode):**
 ```
-.opencode/agent/
-├── rrce-init.md
-├── rrce-research.md
-├── rrce-planning.md
-├── rrce-executor.md
-├── rrce-documentation.md
-└── rrce-sync.md
+.github/prompts/
+├── init.prompt.md
+├── research.prompt.md
+├── planning.prompt.md
+├── executor.prompt.md
+├── documentation.prompt.md
+├── sync.prompt.md
+└── doctor.prompt.md
 ```
 
-### Copilot-Specific Features
+---
+
+## MCP Server Architecture
+
+The MCP Server (`src/mcp/`) provides the bridge between project knowledge and AI agents.
+
+### Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **Server Entry** | `src/mcp/server.ts` | Initializes server, registers handlers, manages Stdio transport |
+| **Tool Handlers** | `src/mcp/handlers/tools.ts` | 12 MCP tools (search, index, tasks, resolve_path, etc.) |
+| **Prompt Handlers** | `src/mcp/handlers/prompts.ts` | Agent system prompts with context injection |
+| **Resource Handlers** | `src/mcp/handlers/resources.ts` | Knowledge files and project context as readable resources |
+| **RAG Service** | `src/mcp/services/rag.ts` | Semantic search with @xenova/transformers |
+| **Resources Utilities** | `src/mcp/resources.ts` | Project data access, task CRUD, context preamble generation |
+
+### Context Injection
 
-Our prompts include Copilot-compatible frontmatter:
+When an agent requests a prompt via `get_agent_prompt`, the server injects a **Context Preamble** containing:
+- **System Resolved Paths**: Pre-resolved `RRCE_DATA`, `WORKSPACE_ROOT`, `RRCE_HOME`
+- **Available Projects**: List of exposed projects with active project marked
+- **Active Workspace**: Current project context for file operations
 
-| Field | Purpose | Values |
-|-------|---------|--------|
-| `agent` | Execution mode | `agent` (full), `ask` (read-only), `edit` (code changes) |
-| `tools` | Available tools | `search/codebase`, `search/web`, `terminalLastCommand`, etc. |
+### Semantic Search (RAG)
+
+| Feature | Implementation |
+|---------|----------------|
+| **Embedding Model** | `Xenova/all-MiniLM-L6-v2` (configurable) |
+| **Index Location** | `<knowledge>/embeddings.json` |
+| **Similarity** | Cosine similarity |
+| **Indexable Extensions** | `.ts`, `.tsx`, `.js`, `.py`, `.go`, `.rs`, `.md`, etc. |
+| **Skip Directories** | `node_modules`, `.git`, `dist`, `build`, etc. |
 
 ---
 
-## Installation Flow (TUI First Run)
+## Installation Flow
 
+```bash
+# Option 1: MCP Dashboard (recommended)
+npx rrce-workflow mcp
+
+# Option 2: Project Setup Wizard
+cd your-project
+npx rrce-workflow
+
+# Option 3: Start MCP Server directly (for IDE config)
+npx rrce-workflow mcp start
 ```
-$ npx rrce-workflow
-
-┌─────────────────────────────────────────────────────────┐
-│  RRCE-Workflow Setup Wizard                             │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  Welcome! Let's configure your workflow environment.    │
-│                                                         │
-│  Your name: [_________________]                         │
-│  Email (optional): [_________________]                  │
-│                                                         │
-│  ─────────────────────────────────────────────────────  │
-│                                                         │
-│  ✓ Created ~/.rrce-workflow/config.yaml                │
-│  ✓ Installed default templates                          │
-│  ✓ Ready to use!                                        │
-│                                                         │
-│  Run `rrce-workflow help` for available commands.       │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
+
+---
+
+## Key Design Patterns
+
+1. **MCP Decoupling**: Handlers separated from server instance for maintainability
+2. **TUI/MCP Separation**: MCP runs in "interactive" mode to avoid stdio conflicts with TUI
+3. **Prompt Parsing**: Frontmatter-based prompts with variable injection
+4. **Hybrid Storage**: Global mode (clean repos) vs Workspace mode (portable)
+5. **DetectedProject.sourcePath**: For global mode, links data back to actual source location
 
 ---
 
@@ -355,5 +475,7 @@ $ npx rrce-workflow
 - [ ] Web UI for knowledge browsing
 - [ ] Cross-project knowledge sharing (opt-in)
 - [ ] Plugin system for custom agents
-- [ ] LLM-agnostic (support OpenAI, Anthropic, Gemini, local models)
+- [ ] Comprehensive test suite (Jest/Vitest)
+- [ ] CI/CD with GitHub Actions
+- [ ] Cross-platform parity (Windows/macOS)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrce-workflow",
-  "version": "0.2.91",
+  "version": "0.2.93",
   "description": "RRCE-Workflow TUI - Agentic code workflow generator for AI-assisted development",
   "author": "RRCE Team",
   "license": "MIT",
@@ -39,7 +39,10 @@
     "wizard": "npx tsx src/index.ts wizard",
     "start": "npx tsx src/index.ts",
     "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "engines": {
     "node": ">=18"
@@ -62,8 +65,10 @@
   "devDependencies": {
     "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
+    "@vitest/coverage-v8": "^4.0.16",
     "esbuild": "^0.27.2",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   }
 }