clawmatrix 0.5.1 → 0.6.1

package/cli/skills/clawmatrix/SKILL.md

@@ -3,102 +3,58 @@ name: clawmatrix
 description: Use the clawmatrix CLI to interact with remote devices (phones, computers, servers) in a mesh cluster — run tools, check location, get battery status, read/write files, execute commands, and more on any connected node.
 ---
 
-Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers. You can invoke any tool available on remote nodes — including getting device location, battery status, running shell commands, reading/writing files, and more.
+Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers.
 
-All commands output LLM-friendly text (no ANSI colors) when stdout is not a TTY.
+Run `clawmatrix --help` or `clawmatrix <command> --help` for detailed usage.
 
-## Quick Start
+## Capabilities
 
-1. Run `clawmatrix status` to see connected nodes and their capabilities
-2. Run `clawmatrix tools <nodeId>` to see what tools a node offers
-3. Run `clawmatrix call <nodeId> <tool> '<params>'` to invoke a tool
+**Cluster & Discovery**
+- View cluster topology, peer status, node config, and uptime/availability
+- Check reachability of specific nodes with latency
+- Approve/deny/revoke peer connections
 
-## Cluster Status
+**Remote Tool Execution**
+- Discover tools across all nodes (filter by keyword, describe params)
+- Invoke single tools or batch multiple in one round-trip
+- Tools include device-specific capabilities: location, battery, camera, clipboard, contacts, calendar, health data, HomeKit, etc.
 
-```bash
-clawmatrix status          # Cluster topology: peers, agents, models, tags
-clawmatrix status --json   # Structured JSON output
-clawmatrix check <nodeId>  # Quick reachability check with latency
-```
+**Models**
+- List all LLM models available across the cluster, filterable by node
 
-Always start with `clawmatrix status` to understand the current topology before performing other operations.
+**Agent Delegation**
+- `handoff` — delegate tasks to remote agents with streaming output and failover
+- `send` — fire-and-forget messages to remote nodes
+- `acp` — manage persistent coding agent sessions (Claude Code, Codex, Gemini) with prompt/resume/cancel/close
 
-## Remote Tools
+**Events & Automations**
+- Query, consume, and ingest events from external sources (iOS Shortcuts, webhooks, etc.)
+- Manage automation rules: list, create/save, manually trigger, replay historical executions
 
-```bash
-clawmatrix tools                        # List all remote tools (compact)
-clawmatrix tools <nodeId>               # Tools on a specific node
-clawmatrix tools --describe <tool>      # Full usage and parameter schema
-clawmatrix tools --filter <keyword>     # Search by name or description
-```
+**Infrastructure**
+- `diagnostic` — sentinel-based diagnostics (works even when gateway is down)
+- `terminal` — interactive PTY sessions on remote nodes
+- `transfer` — push/pull files up to 100MB between nodes with integrity verification
+- `notify` — push Dynamic Island / Live Activity notifications to iOS devices
 
-Use `--describe` to understand a tool's parameters before calling it.
+**Knowledge Sync (CRDT)**
+- List synced workspace files, view change history, line-by-line blame, read file content
+- All knowledge is CRDT-based and mesh-synced across nodes
 
-## Invoke Tools
+**Kanban Board**
+- Distributed task board: create, list, get, update, claim, move, annotate, delete cards
+- Filter by stage/priority/label/node; stages flow from `backlog` → `done` → `archived`
 
-```bash
-clawmatrix call <nodeId> <tool> '<json-params>'    # Single tool invocation
-clawmatrix call <nodeId> <tool> '<json-params>' -t 30000  # With timeout (ms)
-```
+**Config Management**
+- View runtime config summary
+- Read/write config files under `~/.openclaw/` (for remote node configuration)
 
-```bash
-clawmatrix batch <nodeId> '[{"tool":"t1","params":{}},{"tool":"t2","params":{}}]'
-clawmatrix batch <nodeId> --no-stop-on-error '[...]'  # Continue on failure
-```
+## Important Notes
 
-Batch supports stdin: `echo '<json>' | clawmatrix batch <nodeId>`
-
-## Models
-
-```bash
-clawmatrix models                   # All cluster models
-clawmatrix models --node <nodeId>   # Filter by node
-```
-
-## Events
-
-```bash
-clawmatrix events                       # Unconsumed events
-clawmatrix events --type <type>         # Filter by type
-clawmatrix events --source <nodeId>     # Filter by source node
-clawmatrix events --consume <id1,id2>   # Mark events as consumed
-clawmatrix events --all                 # Include consumed events
-```
-
-## Peer Approval
-
-```bash
-clawmatrix approve <approvalId>         # Approve a pending peer
-clawmatrix deny <approvalId>            # Deny a pending peer
-clawmatrix approval list                # List pending/approved/denied peers
-clawmatrix approval revoke <nodeId>     # Revoke an approved peer
-```
-
-## Notifications (Dynamic Island / Live Activity)
-
-Push progress notifications to the user's iPhone via `clawmatrix notify`. This triggers the Dynamic Island and lock screen Live Activity.
-
-**Use this proactively when running long tasks** (iOS builds, large refactors, test suites, batch operations) so the user can track progress without watching the terminal.
-
-```bash
-# Start a notification
-clawmatrix notify "iOS 构建" --detail "正在编译..."
-# Returns: {"taskId":"<id>", "action":"start", "targets":1}
-
-# Update progress
-clawmatrix notify "iOS 构建" --action update --task-id <id> --detail "链接中..." --progress 80
-
-# End (success)
-clawmatrix notify "iOS 构建" --action end --task-id <id>
-```
-
-Options: `--detail <text>`, `--progress <0-100>`, `--action start|update|end`, `--task-id <id>`, `--tool <name>`
-
-## Workflow
-
-1. Run `clawmatrix status` to see the cluster topology
-2. Use `clawmatrix tools --filter <keyword>` to find relevant tools
-3. Use `clawmatrix tools --describe <tool>` to check parameters
-4. Use `clawmatrix call` or `clawmatrix batch` to invoke tools
-5. If a call fails, run `clawmatrix check <nodeId>` to verify connectivity
-6. For long-running tasks, use `clawmatrix notify` to push progress to the user's phone
+- **Always start with `clawmatrix status`** to understand the cluster topology before other operations
+- **Use `clawmatrix tools --describe <tool>`** to check a tool's parameter schema before calling it
+- **Use `clawmatrix notify` proactively during long tasks** (builds, tests, large refactors) so the user can track progress on their phone without watching the terminal
+- Output is **LLM-optimized**: no ANSI colors and compact format when stdout is not a TTY; add `--json` for structured output
+- Target nodes by exact `nodeId` or by tag expression `tags:<tag>`
+- Most commands support `--json` for structured output
+- `batch` and `automations save` support stdin for piping data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/api.ts

@@ -10,6 +10,9 @@ import type { KnowledgeSync } from "./knowledge-sync.ts";
 import { nanoid } from "nanoid";
 import { timingSafeEqual } from "./auth.ts";
 import { readBody } from "./http-utils.ts";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
 
 const COOKIE_NAME = "clawmatrix_token";
 const SESSION_MAX_AGE = 86400 * 7; // 7 days
@@ -27,6 +30,255 @@ const CLUSTER_TOOLS = [
   "cluster_notify", "cluster_query",
 ];
 
+/** Full tool definitions for /api/tools endpoint. */
+const CLUSTER_TOOL_DEFS: Array<{ name: string; description: string; inputSchema: Record<string, unknown> }> = [
+  {
+    name: "cluster_peers",
+    description: "List all peers in the cluster with their agents, models, tools, tags, and connection status. Call this first to discover what's available before using other cluster tools.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "cluster_exec",
+    description: "Execute a shell command on a remote cluster node. Returns {stdout, stderr, exitCode}. Use nodeId or 'tags:<tag>' to specify the target.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId or \"tags:<tag>\"" },
+        command: { type: "string", description: "Shell command to execute" },
+        workdir: { type: "string", description: "Working directory (optional)" },
+        timeout: { type: "number", description: "Timeout in seconds (default 1800)" },
+      },
+      required: ["node", "command"],
+    },
+  },
+  {
+    name: "cluster_read",
+    description: "Read a file from a remote cluster node. Returns {content} with the file text.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId or \"tags:<tag>\"" },
+        path: { type: "string", description: "File path to read" },
+      },
+      required: ["node", "path"],
+    },
+  },
+  {
+    name: "cluster_write",
+    description: "Write content to a file on a remote cluster node (creates or overwrites).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId or \"tags:<tag>\"" },
+        path: { type: "string", description: "File path to write" },
+        content: { type: "string", description: "Content to write" },
+      },
+      required: ["node", "path", "content"],
+    },
+  },
+  {
+    name: "cluster_edit",
+    description: "Edit a file on a remote cluster node by replacing exact text. Use cluster_read first to get exact file content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId or \"tags:<tag>\"" },
+        path: { type: "string", description: "File path to edit" },
+        oldText: { type: "string", description: "Exact text to find and replace" },
+        newText: { type: "string", description: "New text to replace with" },
+      },
+      required: ["node", "path", "oldText", "newText"],
+    },
+  },
+  {
+    name: "cluster_handoff",
+    description: "Hand off a complex task to another agent in the cluster and wait for the result. Use for multi-step tasks that require the remote agent's full capabilities.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Agent ID or \"tags:<tag>\" expression" },
+        task: { type: "string", description: "Task description for the remote agent" },
+        context: { type: "string", description: "Additional context for the task" },
+      },
+      required: ["target", "task"],
+    },
+  },
+  {
+    name: "cluster_handoff_reply",
+    description: "Reply to a remote agent that requested more input during a handoff. Use the handoff_id returned by cluster_handoff.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        handoff_id: { type: "string", description: "The handoff ID from cluster_handoff's response" },
+        message: { type: "string", description: "Your reply to the remote agent's question" },
+      },
+      required: ["handoff_id", "message"],
+    },
+  },
+  {
+    name: "cluster_send",
+    description: "Send a one-way notification to a remote agent. Fire-and-forget: does not wait for a response.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "Agent ID or \"tags:<tag>\" expression" },
+        message: { type: "string", description: "Message content to send" },
+      },
+      required: ["target", "message"],
+    },
+  },
+  {
+    name: "cluster_batch",
+    description: "Execute multiple tools on a remote node in a single round-trip. Tools run sequentially (supports dependencies like read→edit).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId or \"tags:<tag>\"" },
+        items: { type: "array", description: "Array of { tool, params } to execute in order", items: { type: "object", properties: { tool: { type: "string" }, params: { type: "object" } }, required: ["tool", "params"] } },
+        stopOnError: { type: "boolean", description: "Stop on first error (default true)" },
+      },
+      required: ["node", "items"],
+    },
+  },
+  {
+    name: "cluster_tool",
+    description: "Invoke any tool on a remote cluster node by name. Preferred for device-specific tools (screenshot, battery, location, clipboard, etc.).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId or \"tags:<tag>\"" },
+        tool: { type: "string", description: "Remote tool name to invoke" },
+        params: { type: "object", description: "Parameters to pass to the remote tool" },
+        timeout: { type: "number", description: "Timeout in seconds (default 30)" },
+      },
+      required: ["node", "tool"],
+    },
+  },
+  {
+    name: "cluster_terminal",
+    description: "Interactive terminal (PTY) on a remote cluster node. Actions: open, input, read, resize, list, close. Prefer cluster_exec for one-shot commands.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["open", "input", "read", "resize", "list", "close"], description: "Action to perform (default: open)" },
+        node: { type: "string", description: "Target node ID (required for open)" },
+        sessionId: { type: "string", description: "Session ID (required for input/read/resize/close)" },
+        data: { type: "string", description: "Input data to send (for input action)" },
+        shell: { type: "string", description: "Shell to use (default: $SHELL)" },
+        cols: { type: "number", description: "Terminal columns (default: 80)" },
+        rows: { type: "number", description: "Terminal rows (default: 24)" },
+      },
+    },
+  },
+  {
+    name: "cluster_transfer",
+    description: "Transfer a file between local and remote nodes. Supports up to 100MB with chunked transfer and SHA-256 integrity check.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_path: { type: "string", description: "File path on the source node" },
+        target_path: { type: "string", description: "File path on the target node" },
+        source_node: { type: "string", description: "Source nodeId (omit for local)" },
+        target_node: { type: "string", description: "Target nodeId (omit for local)" },
+      },
+      required: ["source_path", "target_path"],
+    },
+  },
+  {
+    name: "cluster_events",
+    description: "Query and consume events from external sources (iOS Shortcuts, webhooks, etc.). Events are persistent until consumed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["query", "consume"], description: "\"query\" to list events, \"consume\" to mark as processed" },
+        type: { type: "string", description: "Filter by event type" },
+        source: { type: "string", description: "Filter by source" },
+        unconsumed: { type: "boolean", description: "Only unconsumed events (default true)" },
+        limit: { type: "number", description: "Max events to return (default 20)" },
+        ids: { type: "array", items: { type: "string" }, description: "Event IDs to consume" },
+      },
+      required: ["action"],
+    },
+  },
+  {
+    name: "cluster_diagnostic",
+    description: "Diagnose or execute commands on a remote node's sentinel process. Works even when the gateway is down.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        node: { type: "string", description: "Target nodeId" },
+        action: { type: "string", enum: ["status", "exec"], description: "\"status\" to check health, \"exec\" to run a command" },
+        command: { type: "string", description: "Shell command (required for exec)" },
+        timeout: { type: "number", description: "Timeout in seconds (default 30)" },
+      },
+      required: ["node", "action"],
+    },
+  },
+  {
+    name: "cluster_acp",
+    description: "Run a task on a remote coding agent (Claude Code, Codex, Gemini CLI) via ACP protocol. Supports one-shot and persistent sessions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["prompt", "list", "resume", "cancel", "set_mode", "get_modes", "close"], description: "Action to perform (default: prompt)" },
+        node: { type: "string", description: "Target node ID or \"tags:<tag>\"" },
+        agent: { type: "string", description: "ACP agent name: \"claude\", \"codex\", \"gemini\"" },
+        task: { type: "string", description: "Task or prompt to send" },
+        sessionId: { type: "string", description: "Session ID for follow-up or management" },
+        mode: { type: "string", enum: ["oneshot", "persistent"], description: "Session mode (default: oneshot)" },
+        cwd: { type: "string", description: "Working directory on the remote node" },
+      },
+      required: ["node"],
+    },
+  },
+  {
+    name: "cluster_kanban",
+    description: "Manage the distributed kanban board for tracking work items across the cluster. Supports create, list, get, claim, move, annotate, update, delete, summary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["create", "list", "get", "claim", "move", "annotate", "update", "delete", "summary"], description: "Action to perform (default: list)" },
+        cardId: { type: "string", description: "Card ID for get/claim/move/annotate/update/delete" },
+        title: { type: "string", description: "Card title (for create or update)" },
+        description: { type: "string", description: "Card description in Markdown" },
+        stage: { type: "string", enum: ["backlog", "claimed", "in_progress", "review", "done", "archived"], description: "Target stage or filter" },
+        priority: { type: "string", enum: ["low", "medium", "high", "urgent"], description: "Card priority" },
+        labels: { type: "array", items: { type: "string" }, description: "Labels" },
+      },
+    },
+  },
+  {
+    name: "cluster_notify",
+    description: "Push a notification to mobile devices in the cluster (Dynamic Island / Live Activity on iOS). Track long-running task progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["start", "update", "end"], description: "Action to perform (default: start)" },
+        taskId: { type: "string", description: "Task ID for update/end actions" },
+        title: { type: "string", description: "Activity title" },
+        detail: { type: "string", description: "Activity detail text" },
+        progress: { type: "number", description: "Progress 0.0 to 1.0" },
+        tool: { type: "string", description: "Current tool being executed" },
+        success: { type: "boolean", description: "For end: true=completed, false=failed" },
+      },
+    },
+  },
+  {
+    name: "cluster_query",
+    description: "Query replicated data from SQLite: audit_log, health_events, handoff_history. Data is replicated across peers for cluster-wide view.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        table: { type: "string", enum: ["audit_log", "health_events", "handoff_history"], description: "Which table to query" },
+        since: { type: "number", description: "Events after this unix timestamp (ms). Negative for relative." },
+        node_id: { type: "string", description: "Filter by node ID" },
+        limit: { type: "number", description: "Max rows (default 50)" },
+      },
+      required: ["table"],
+    },
+  },
+];
+
 interface SatelliteEvent {
   ts: number;
   type: "peer_online" | "peer_offline" | "handoff_done" | "context_update" | "event_ingested" | "kanban";
@@ -216,6 +468,11 @@ export class ApiHandler {
       return;
     }
 
+    if (path === "/api/tools" && req.method === "GET") {
+      this.handleToolsList(res);
+      return;
+    }
+
     if (path === "/api/chat" && req.method === "POST") {
       this.handleChat(req, res);
       return;
@@ -267,6 +524,16 @@ export class ApiHandler {
       return;
     }
 
+    if (path === "/api/config/read" && req.method === "GET") {
+      this.handleConfigRead(req, res);
+      return;
+    }
+
+    if (path === "/api/config/write" && req.method === "POST") {
+      this.handleConfigWrite(req, res);
+      return;
+    }
+
     if (path === "/api/availability" && req.method === "GET") {
       this.handleAvailability(req, res);
       return;
@@ -298,6 +565,11 @@ export class ApiHandler {
       return;
     }
 
+    if (path === "/api/knowledge/content" && req.method === "GET") {
+      this.handleKnowledgeContent(req, res);
+      return;
+    }
+
     // Board / Kanban API
     if (path === "/api/board" && req.method === "GET") {
       this.handleBoardSummary(res);
@@ -434,9 +706,112 @@ export class ApiHandler {
       return;
     }
 
-    const result = this.healthTracker.getAvailability(range);
+    try {
+      const result = this.healthTracker.getAvailability(range);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result));
+    } catch (err) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: String((err as Error)?.message ?? err) }));
+    }
+  }
+
+  // ── Config file API (local node) ────────────────────────────────
+
+  /** Resolve config path, restricted to ~/.openclaw/ for safety. */
+  private resolveConfigPath(configPath: string): string | null {
+    const home = homedir();
+    const openclawDir = `${home}/.openclaw`;
+    // Normalize: replace ~ with home dir
+    const resolved = configPath.startsWith("~")
+      ? configPath.replace(/^~/, home)
+      : configPath;
+    // Security: only allow files under ~/.openclaw/
+    if (!resolved.startsWith(openclawDir)) return null;
+    // Prevent path traversal
+    if (resolved.includes("..")) return null;
+    return resolved;
+  }
+
+  /** GET /api/config/read?path=<configPath> — read a local config file. */
+  private async handleConfigRead(req: IncomingMessage, res: ServerResponse) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const configPath = url.searchParams.get("path");
+    if (!configPath) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing required query param: path" }));
+      return;
+    }
+
+    const resolved = this.resolveConfigPath(configPath);
+    if (!resolved) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Path must be under ~/.openclaw/" }));
+      return;
+    }
+
+    try {
+      const content = await readFile(resolved, "utf-8");
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ success: true, content }));
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: true, content: "{}" }));
+      } else {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Failed to read config" }));
+      }
+    }
+  }
+
+  /** POST /api/config/write — write a local config file. Body: { path, content } */
+  private async handleConfigWrite(req: IncomingMessage, res: ServerResponse) {
+    try {
+      const body = await readBody(req);
+      const { path: configPath, content } = JSON.parse(body);
+      if (!configPath || typeof content !== "string") {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "path and content required" }));
+        return;
+      }
+
+      const resolved = this.resolveConfigPath(configPath);
+      if (!resolved) {
+        res.writeHead(403, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Path must be under ~/.openclaw/" }));
+        return;
+      }
+
+      // Ensure directory exists
+      await mkdir(dirname(resolved), { recursive: true });
+      await writeFile(resolved, content, "utf-8");
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ success: true }));
+    } catch (err) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Failed to write config" }));
+    }
+  }
+
+  /** GET /api/tools — list cluster tools with descriptions and input schemas. */
+  private handleToolsList(res: ServerResponse) {
+    // Build per-node tool info: local node tools + remote peer tools
+    const nodes: Array<{ nodeId: string; tools: typeof CLUSTER_TOOL_DEFS }> = [];
+
+    // Local node
+    nodes.push({ nodeId: this.config.nodeId, tools: CLUSTER_TOOL_DEFS });
+
+    // Remote peers — include cluster tools for each online peer with toolProxy
+    const peers = this.peerManager.router.getAllPeers();
+    for (const p of peers) {
+      if (!this.peerManager.canReach(p.nodeId)) continue;
+      if (!p.toolProxy?.enabled) continue;
+      nodes.push({ nodeId: p.nodeId, tools: CLUSTER_TOOL_DEFS });
+    }
+
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify(result));
+    res.end(JSON.stringify({ nodes }));
   }
 
   private handleStatus(res: ServerResponse) {
@@ -1251,8 +1626,9 @@ export class ApiHandler {
       return;
     }
     const files = this.knowledgeSync.listSyncedFiles();
+    const workspacePath = this.knowledgeSync.workspacePath;
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ success: true, files }));
+    res.end(JSON.stringify({ success: true, files, workspacePath }));
   }
 
   /** GET /api/knowledge/history?path=<relPath> — file change history from CRDT. */
@@ -1292,6 +1668,37 @@ export class ApiHandler {
     res.end(JSON.stringify({ success: true, path: filePath, history }));
   }
 
+  /** GET /api/knowledge/content?path=<relPath> — read synced file content from CRDT. */
+  private handleKnowledgeContent(req: IncomingMessage, res: ServerResponse) {
+    if (!this.knowledgeSync) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Knowledge sync not enabled" }));
+      return;
+    }
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const filePath = url.searchParams.get("path");
+    if (!filePath) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing required query param: path" }));
+      return;
+    }
+    const content = this.knowledgeSync.getFileContent(filePath);
+    if (content === null) {
+      // Distinguish between "not in registry" and "in registry but content not yet synced"
+      const listed = this.knowledgeSync.listSyncedFiles().find(f => f.path === filePath);
+      if (listed) {
+        res.writeHead(202, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "File content not yet synced", syncing: true }));
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "File not found" }));
+      }
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ success: true, path: filePath, content }));
+  }
+
   // ── Board / Kanban API handlers ─────────────────────────────────
 
   private handleBoardSummary(res: ServerResponse) {