@mindfullabai/onda-mcp 0.1.0 → 0.3.1

package/README.md

@@ -2,7 +2,9 @@
 
 MCP server to control [Onda](https://onda.dev) terminal from AI agents (Claude Code, Cursor, Windsurf, etc.)
 
-21 tools across 5 categories let AI agents split panes, run commands, manage tabs and workspaces, and orchestrate multi-agent workflows -- all through the standard [Model Context Protocol](https://modelcontextprotocol.io/).
+31 tools across 7 categories let AI agents split panes, run commands, manage tabs and workspaces, coordinate across multiple windows, and orchestrate multi-agent workflows -- all through the standard [Model Context Protocol](https://modelcontextprotocol.io/).
+
+Since v0.2.0 Onda MCP is **multi-window aware**: agents can discover windows, locate workspaces, address terminals unambiguously (each entry carries `windowId` + `workspaceId` + `paneId`), and launch full Claude/agent sessions in one atomic call with the `onda_launch_session` macro.
 
 ## Requirements
 
@@ -62,7 +64,8 @@ Same MCP config format as above.
 |------|-------------|
 | `onda_terminal_run` | Run a command in a specific terminal (sends command + newline). |
 | `onda_terminal_send` | Send raw text to a terminal without appending a newline. Use for interactive input or key sequences. |
-| `onda_terminal_list` | List all active terminals with their IDs, PIDs, working directories, and alive status. |
+| `onda_terminal_list` | List terminals with `{id, pid, cwd, alive, workspaceId, paneId, tabId, windowId}`. Optional input filters `workspaceId` / `windowId`. |
+| `onda_terminal_spawn` | Spawn a binary inside an existing pane via `exec bin args...`, preserving multi-line/quoted argv. Use to start `claude` (or any agent) with a structured prompt in a pre-existing workspace pane. |
 | `onda_terminal_kill` | Kill a terminal process by ID. |
 
 ### Tab Management
@@ -78,11 +81,28 @@ Same MCP config format as above.
 
 | Tool | Description |
 |------|-------------|
-| `onda_workspace_list` | List all workspaces with their IDs, names, root paths, and which is active. |
+| `onda_workspace_list` | List workspaces with `{id, name, rootPath, mountedIn}` (mountedIn = windowId currently hosting that workspace, or null). |
 | `onda_workspace_create` | Create a new workspace. Workspaces group tabs by project. |
 | `onda_workspace_focus` | Switch to a workspace by ID. |
-| `onda_workspace_add_terminal` | Add a new terminal pane to a workspace (tiled mode). |
+| `onda_workspace_add_terminal` | Add a new terminal pane to a workspace (tiled mode). Returns `{terminalId, paneId, workspaceId, windowId, ready}`. PTY-ready handshake is on by default — set `waitForReady:false` to skip. |
 | `onda_workspace_tile` | Set the workspace tiling layout: `single`, `split-h`, `split-v`, or `quad`. |
+| `onda_workspace_locate` | Resolve a workspace by `id` / `name` / `rootPath` without listing them all. Returns `{workspace: {id, name, rootPath, mountedIn} | null}`. |
+
+### Window (multi-window)
+
+| Tool | Description |
+|------|-------------|
+| `onda_window_list` | List Onda main windows. Each entry: `{windowId, isFocused, title, workspaceIds[], activeWorkspaceId, uiMode}`. |
+| `onda_window_new` | Open a fresh empty main window. Returns `{windowId}`. |
+| `onda_window_focus` | Bring a window to the foreground (restore + raise + focus). When `windowId` is omitted, focuses the primary window. |
+| `onda_window_mount_workspace` | Mount a workspace in a specific window. Idempotent; orchestrates an atomic transfer if the workspace is currently owned by another window. Returns `{success, workspaceId, windowId, transferred}`. |
+| `onda_workspace_unmount` | Remove a workspace from whichever window currently hosts it. The workspace continues to exist globally — only its on-screen mounting is dropped. Returns `{success, workspaceId, windowId, alreadyUnmounted}`. |
+
+### Macro
+
+| Tool | Description |
+|------|-------------|
+| `onda_launch_session` | Atomic "ensure workspace + mount in target window + add terminal + spawn `bin` with `args`/`prompt`". Supports `placement: 'auto'` / `'current-window'` / `'window:<id>'` / `'new-window'` / `'ask-user'`. When `ask-user`, returns `{needsDecision: true, options, workspace}` so the host agent can surface the choice to the user, then re-invokes the tool with a concrete `placement`. |
 
 ### System
 
@@ -103,6 +123,39 @@ Same MCP config format as above.
 | `ONDA_WORKSPACE_ID` | Workspace ID | auto-detected |
 | `ONDA_TERMINAL` | Set to `"1"` when inside Onda | auto-detected |
 
+## Agent-bus pattern (since v0.2.0)
+
+Typical flow when an agent in window A delegates a task to another agent in workspace X (which may or may not be already mounted somewhere):
+
+```jsonc
+// 1. Try a fully-automatic launch
+onda_launch_session({
+  workspace: { name: "brandart-agentic-platform" },
+  bin: "claude",
+  prompt: "Scaffold modulo memoria — segui il brief #BAP-2026-05-20 ...",
+  placement: "ask-user"
+})
+
+// → If multiple windows exist, the tool returns without acting:
+{
+  "needsDecision": true,
+  "reason": "placement: ask-user",
+  "options": [
+    { "placement": "window:w-abc12345", "label": "Window w-abc1234 (current, focused)" },
+    { "placement": "window:w-def67890", "label": "Window w-def6789" },
+    { "placement": "new-window",        "label": "Open in a new window" }
+  ],
+  "workspace": { "id": "ws-...", "name": "brandart-agentic-platform", "rootPath": "/Users/mario/Projects/06-Brandart/brandart-agentic-platform" }
+}
+
+// 2. Host agent shows options to the human, gets choice, re-invokes:
+onda_launch_session({ /* same args */, placement: "window:w-abc12345" })
+// → { windowId, workspaceId, terminalId, paneId, pid }
+// Claude is now running in that pane with the brief as its initial prompt.
+```
+
+After launch, the caller can keep talking to the spawned agent via `onda_terminal_send` / `onda_terminal_run` using the returned `terminalId`, or use `onda_terminal_list` (now enriched with `workspaceId`/`windowId`) to disambiguate which terminal belongs to which session.
+
 ## Architecture
 
 - Communicates with Onda via **Unix domain socket**

package/bin/install-skill.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * `onda-mcp-install-skill` bin entry. Forwards to scripts/install-skill.mjs.
+ *
+ * Distributed via package.json `bin` so users can run:
+ *   npx @mindfullabai/onda-mcp install-skill
+ *
+ * (npm executes the matching `onda-mcp-install-skill` binary; we ship a
+ * minimal wrapper to allow forwarding any argv.)
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const target = resolve(__dirname, '..', 'scripts', 'install-skill.mjs');
+const result = spawnSync(process.execPath, [target, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+process.exit(result.status ?? 0);

package/dist/index.js

@@ -176,10 +176,13 @@ const TOOLS = [
     },
     {
         name: 'onda_terminal_list',
-        description: 'List all active terminals with their IDs, PIDs, working directories, and alive status. Essential for discovering which terminals exist before running commands.',
+        description: 'List active terminals. Each entry: { id, pid, cwd, alive, workspaceId, paneId, tabId, windowId }. Use the optional filters to scope the list. Essential to disambiguate which terminal belongs to which workspace/window when many are alive — no more cwd reverse-lookup.',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                workspaceId: { type: 'string', description: 'Filter: only terminals in this workspace.' },
+                windowId: { type: 'string', description: 'Filter: only terminals in this window.' },
+            },
         },
     },
     {
@@ -193,6 +196,144 @@ const TOOLS = [
             required: ['id'],
         },
     },
+    // --- Terminal Tap (read + subscribe + sendKeys + waitFor) ---
+    {
+        name: 'onda_terminal_read',
+        description: 'Read recent output of a terminal (ring buffer ~200 KB / ~1 MB if a listener is attached). Returns the current buffer content plus byte total and timestamps. Use to see what a terminal has printed without subscribing to a live stream. Lazily attaches a passive tap on first call — no impact on the terminal itself.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to read from.' },
+                lines: {
+                    type: 'number',
+                    description: 'Optional: cap returned content to the last N lines.',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'onda_terminal_subscribe',
+        description: 'Attach a long-lived listener to a terminal\'s output stream. Returns a sessionId for use with onda_terminal_poll. Also returns the current buffer snapshot so the listener has full context. Cap of 4 concurrent listeners per terminal. The listener\'s name is shown in the Onda UI as a presence indicator.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to subscribe to.' },
+                listener: {
+                    type: 'string',
+                    description: 'Display name for this listener (shown in Onda UI presence badge). e.g. "alita", "kai", "ci-watch".',
+                },
+            },
+            required: ['id', 'listener'],
+        },
+    },
+    {
+        name: 'onda_terminal_poll',
+        description: 'Long-poll a subscribed terminal session for new output. Blocks up to timeoutMs (default 15000) waiting for new chunks. Returns immediately if data is already pending. Each call advances the cursor; only data emitted after the last poll is returned. Use in a loop: subscribe -> poll -> poll -> ... -> unsubscribe.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    description: 'Session ID returned by onda_terminal_subscribe.',
+                },
+                timeoutMs: {
+                    type: 'number',
+                    description: 'Max wait in ms before returning empty. Default 15000.',
+                },
+            },
+            required: ['sessionId'],
+        },
+    },
+    {
+        name: 'onda_terminal_unsubscribe',
+        description: 'Detach a listener session. Idempotent. Always call this when done to free the ring buffer (drops back to idle size after the last subscriber leaves).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Session ID to detach.' },
+            },
+            required: ['sessionId'],
+        },
+    },
+    {
+        name: 'onda_terminal_listeners',
+        description: 'List currently attached listeners for a terminal. Returns name + sessionId + timestamps. Used to inspect who is observing a terminal (introspection / debugging).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to inspect.' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'onda_terminal_wait_for',
+        description: 'Block until a regex pattern matches new terminal output, or timeout. Useful to synchronize scripted command sequences: run command -> wait for prompt -> run next command. Pattern is a JavaScript regex string; flags default to "m" (multiline). Returns { matched: bool, match?: string }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to watch.' },
+                pattern: { type: 'string', description: 'Regex pattern (string form).' },
+                flags: { type: 'string', description: 'Regex flags. Default "m".' },
+                timeoutMs: { type: 'number', description: 'Max wait in ms. Default 30000.' },
+            },
+            required: ['id', 'pattern'],
+        },
+    },
+    // --- Spatial awareness (M+1 follow-up) ---
+    {
+        name: 'onda_workspace_layout',
+        description: 'Read the current layout of a workspace: mosaic tree, list of pane IDs, active pane, viewport dimensions, and per-pane cwd. Use this BEFORE spawning a new terminal to decide where to place it (right/down/replace) and whether the viewport has room. Returns null for `workspace` if the id is unknown. Omit workspaceId to use the active workspace.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string', description: 'Workspace ID. Omit for active workspace.' },
+            },
+        },
+    },
+    {
+        name: 'onda_window_screenshot',
+        description: 'Capture a PNG/JPEG snapshot of an Onda main window for visual debugging. Returns either a base64 dataUrl or a tempfile path. Use this when you (the agent) need to SEE what the user sees — verifying a layout change, confirming a feature renders correctly, or investigating UI glitches. Returns { dataUrl | path, width, height, windowId, capturedAt }. Defaults: focused window, PNG format, dataUrl=true.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                windowId: {
+                    type: 'string',
+                    description: 'Window ID to capture. Omit for the focused window.',
+                },
+                format: {
+                    type: 'string',
+                    enum: ['png', 'jpeg'],
+                    description: 'Output format. PNG is lossless (default), JPEG is smaller.',
+                },
+                quality: {
+                    type: 'number',
+                    description: 'JPEG quality 0..100 (default 80). Ignored for PNG.',
+                },
+                dataUrl: {
+                    type: 'boolean',
+                    description: 'When true (default), returns base64 dataUrl. When false, writes a tempfile and returns its path — useful for large captures.',
+                },
+            },
+        },
+    },
+    {
+        name: 'onda_terminal_send_keys',
+        description: 'Send semantic key sequences to a terminal (Ctrl+C, Up, Enter, Esc, F5, Tab, ...). Each entry in `keys` is mapped to the appropriate stdin bytes. Supports Ctrl+<letter>, Arrow keys, Function keys F1-F12, Enter/Tab/Esc/Backspace/Delete/Home/End/PageUp/PageDown/Insert/Space, and raw literal text as fallback. Use this for tmux-like control instead of onda_terminal_send when you need to type special keys.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to send to.' },
+                keys: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Ordered list of key names. Example: ["Ctrl+C"], ["Up", "Up", "Enter"], ["Esc", ":wq", "Enter"].',
+                },
+            },
+            required: ['id', 'keys'],
+        },
+    },
     // --- Tab ---
     {
         name: 'onda_tab_new',
@@ -234,10 +375,28 @@ const TOOLS = [
             required: ['id'],
         },
     },
+    {
+        name: 'onda_tab_exec',
+        description: 'Open a new tab and spawn a process directly with exact argv (bypasses shell parsing). Use this when you need to pass multi-line strings or special characters as a single argument — e.g. launching `claude` with a structured preamble. The process replaces the shell in the tab\'s PTY: argv is passed to execve() as-is, so embedded newlines, quotes, and dollar signs are preserved verbatim.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bin: { type: 'string', description: 'Absolute path or PATH-resolvable binary to spawn (e.g., "claude", "/usr/local/bin/aider").' },
+                args: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Arguments passed verbatim to the binary. Each element is one argv entry; no shell parsing happens.',
+                },
+                cwd: { type: 'string', description: 'Working directory for the spawned process.' },
+                workspaceId: { type: 'string', description: 'Workspace ID to host the new tab. Omit to use active workspace.' },
+            },
+            required: ['bin'],
+        },
+    },
     // --- Workspace ---
     {
         name: 'onda_workspace_list',
-        description: 'List all workspaces with their IDs, names, root paths, and which is active.',
+        description: 'List all workspaces. Each entry: { id, name, rootPath, mountedIn }. `mountedIn` is the windowId hosting that workspace, or null if not currently mounted. Use this with onda_window_list to map workspaces ↔ windows.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -269,13 +428,23 @@ const TOOLS = [
     },
     {
         name: 'onda_workspace_add_terminal',
-        description: 'Add a new terminal pane to a workspace. Works in tiled mode to create terminals within workspace layout.',
+        description: 'Add a new terminal pane to a workspace and wait for its PTY to be ready. Returns { success, terminalId, paneId, workspaceId, windowId, ready }. \n\nPlacement: by default the new pane is appended via react-mosaic\'s built-in logic (typically "split right"). For deterministic placement, pass `direction` and (optionally) `relativeToPaneId` — this routes through splitPane and gives you explicit control.\n\nCALL onda_workspace_layout FIRST when you care about placement: it returns the current mosaic tree + active pane + viewport, so you can decide whether to stack "down" (output-heavy panes) or split "right" (parallel-watch panes).',
         inputSchema: {
             type: 'object',
             properties: {
                 workspaceId: { type: 'string', description: 'Workspace ID. Omit to use active workspace.' },
                 cwd: { type: 'string', description: 'Working directory for the new terminal.' },
                 shell: { type: 'string', description: 'Shell to use (e.g., /bin/zsh).' },
+                waitForReady: { type: 'boolean', description: 'Default true. When false, returns as soon as the pane object is created (PTY may still be spawning).' },
+                direction: {
+                    type: 'string',
+                    enum: ['right', 'down', 'up', 'left', 'horizontal', 'vertical'],
+                    description: 'Optional. When set, the pane is created by splitting an existing one in this direction. "horizontal"/"down"/"up" produce a top/bottom pair; "vertical"/"right"/"left" produce a left/right pair.',
+                },
+                relativeToPaneId: {
+                    type: 'string',
+                    description: 'Optional pane ID to split. When omitted with `direction` set, the active pane is used.',
+                },
             },
         },
     },
@@ -295,6 +464,119 @@ const TOOLS = [
             required: ['layout'],
         },
     },
+    {
+        name: 'onda_workspace_locate',
+        description: 'Find a workspace by name, id, or rootPath without listing them all. Returns { workspace: { id, name, rootPath, mountedIn } } or { workspace: null }. mountedIn is the windowId currently hosting the workspace, or null if not mounted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Workspace ID to look up.' },
+                name: { type: 'string', description: 'Workspace name to look up.' },
+                rootPath: { type: 'string', description: 'Workspace rootPath to look up.' },
+            },
+        },
+    },
+    // --- Window (multi-window aware) ---
+    {
+        name: 'onda_window_list',
+        description: 'List all Onda main windows. Returns { windows: [{ windowId, isFocused, title, workspaceIds[], activeWorkspaceId, uiMode }] }. Use this before placing a new workspace/terminal to know what windows exist and which workspace lives in which window.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'onda_window_new',
+        description: 'Open a fresh empty main window (analogue of File > New Window). Returns { windowId }. Useful when an agent needs to host a workspace in a brand new window without contaminating existing ones.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'onda_window_focus',
+        description: 'Bring a specific main window to the foreground (restore if minimized, raise, focus). When windowId is omitted, focuses the primary window. Returns { success, windowId }. Use after mounting a workspace remotely, or to wake Onda from a background CLI subagent.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                windowId: { type: 'string', description: 'Target window id. Omit to focus the primary window.' },
+            },
+        },
+    },
+    {
+        name: 'onda_window_mount_workspace',
+        description: 'Mount a workspace in a specific window. Idempotent when the workspace is already there. If the workspace is currently mounted in another window, orchestrates an atomic transfer via the unmount-request flow (same path the in-app "Move workspace here?" dialog uses). Returns { success, workspaceId, windowId, transferred }. Pass `direction` to control how the new tile is spliced into the mosaic (mirrors the Cmd+P picker: Enter = down, Cmd+Enter = right).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string', description: 'Workspace to mount.' },
+                windowId: { type: 'string', description: 'Destination window id.' },
+                direction: {
+                    type: 'string',
+                    enum: ['down', 'right'],
+                    description: 'Optional. Where to splice the new tile relative to the anchor workspace in the mosaic. Default: "down".',
+                },
+                anchorWorkspaceId: {
+                    type: 'string',
+                    description: 'Optional. Workspace id to anchor the split next to. Default: currently active workspace in the target window.',
+                },
+            },
+            required: ['workspaceId', 'windowId'],
+        },
+    },
+    {
+        name: 'onda_workspace_unmount',
+        description: 'Remove a workspace from whichever window currently hosts it (drops it from that window\'s tiled mosaic and releases the mount registry slot). The workspace continues to exist in the global list — only its on-screen mounting is dropped. Returns { success, workspaceId, windowId, alreadyUnmounted }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string', description: 'Workspace to unmount.' },
+            },
+            required: ['workspaceId'],
+        },
+    },
+    // --- Advanced terminal spawn ---
+    {
+        name: 'onda_terminal_spawn',
+        description: 'Spawn a binary inside an EXISTING pane by writing `exec bin args...` into its PTY. Preserves multi-line/quoted argv elements verbatim (each one becomes a single execve argv entry after shell quoting). Use this to launch `claude` (or any agent) with a structured prompt inside a workspace pane created via onda_workspace_add_terminal. Either paneId or workspaceId is required; if workspaceId, the first terminal pane in that workspace is used.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                paneId: { type: 'string', description: 'Target pane ID (preferred).' },
+                workspaceId: { type: 'string', description: 'Workspace ID — use when paneId is not known.' },
+                bin: { type: 'string', description: 'PATH-resolvable or absolute binary (e.g., "claude").' },
+                args: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Arguments passed verbatim. Each element is one argv entry; embedded newlines/quotes are preserved.',
+                },
+            },
+            required: ['bin'],
+        },
+    },
+    // --- High-level macro ---
+    {
+        name: 'onda_launch_session',
+        description: 'High-level macro: ensure workspace exists → mount it in target window → add a terminal pane → spawn `bin` with `args` (or `prompt` as single argv). Atomic from the agent\'s point of view. Supports placement modes: "auto" (default), "current-window", "window:<windowId>", "new-window", "ask-user" (interactive — see below).\n\n**Placement "ask-user"**: the tool does NOT proceed. Instead returns { needsDecision: true, options: [{placement, label}], workspace }. The host agent must surface the choice to the human user and re-invoke this tool with placement set to a concrete value (e.g. "window:w-abc").\n\nOn success returns { windowId, workspaceId, terminalId, paneId, pid }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace: {
+                    type: 'object',
+                    description: 'Workspace reference. Provide id | name | rootPath. Set createIfMissing:true (with name+rootPath) to auto-create.',
+                    properties: {
+                        id: { type: 'string' },
+                        name: { type: 'string' },
+                        rootPath: { type: 'string' },
+                        createIfMissing: { type: 'boolean' },
+                    },
+                },
+                bin: { type: 'string', description: 'Binary to spawn (e.g., "claude").' },
+                args: { type: 'array', items: { type: 'string' }, description: 'Argv entries (preserved verbatim).' },
+                prompt: { type: 'string', description: 'Shortcut: passed as a single argv entry. Ignored if args is set.' },
+                placement: {
+                    type: 'string',
+                    description: 'auto | current-window | window:<id> | new-window | ask-user',
+                },
+                addTerminalIfNeeded: { type: 'boolean', description: 'Default true. When false, expects a pane to already exist in the workspace.' },
+            },
+            required: ['workspace', 'bin'],
+        },
+    },
     // --- System ---
     {
         name: 'onda_context',
@@ -345,10 +627,20 @@ const TOOL_MAP = {
     onda_pane_close: { method: 'pane.close' },
     onda_pane_focus: { method: 'pane.focus' },
     // Terminal
+    // Spatial awareness
+    onda_workspace_layout: { method: 'workspace.layout' },
+    onda_window_screenshot: { method: 'window.screenshot' },
     onda_terminal_run: { method: 'terminal.run' },
     onda_terminal_send: { method: 'terminal.send' },
     onda_terminal_list: { method: 'terminal.list' },
     onda_terminal_kill: { method: 'terminal.kill' },
+    onda_terminal_read: { method: 'terminal.read' },
+    onda_terminal_subscribe: { method: 'terminal.subscribe' },
+    onda_terminal_poll: { method: 'terminal.poll' },
+    onda_terminal_unsubscribe: { method: 'terminal.unsubscribe' },
+    onda_terminal_listeners: { method: 'terminal.listeners' },
+    onda_terminal_wait_for: { method: 'terminal.waitFor' },
+    onda_terminal_send_keys: { method: 'terminal.sendKeys' },
     // Tab
     onda_tab_new: {
         method: 'tab.new',
@@ -362,6 +654,13 @@ const TOOL_MAP = {
     onda_tab_list: { method: 'tab.list' },
     onda_tab_close: { method: 'tab.close' },
     onda_tab_focus: { method: 'tab.focus' },
+    onda_tab_exec: {
+        method: 'tab.exec',
+        mapParams: (args) => ({
+            ...args,
+            workspaceId: args.workspaceId || ONDA_CONTEXT.workspaceId || undefined,
+        }),
+    },
     // Workspace
     onda_workspace_list: { method: 'workspace.list' },
     onda_workspace_create: { method: 'workspace.create' },
@@ -372,9 +671,30 @@ const TOOL_MAP = {
             workspaceId: args.workspaceId || ONDA_CONTEXT.workspaceId || undefined,
             cwd: args.cwd,
             shell: args.shell,
+            waitForReady: args.waitForReady,
+            direction: args.direction,
+            relativeToPaneId: args.relativeToPaneId,
         }),
     },
     onda_workspace_tile: { method: 'workspace.setLayout' },
+    onda_workspace_locate: { method: 'workspace.locate' },
+    // Window
+    onda_window_list: { method: 'window.list' },
+    onda_window_new: { method: 'window.new' },
+    onda_window_focus: { method: 'window.focus' },
+    onda_window_mount_workspace: { method: 'window.mountWorkspace' },
+    onda_workspace_unmount: { method: 'workspace.unmount' },
+    // Advanced spawn + macro
+    onda_terminal_spawn: {
+        method: 'terminal.spawnInPane',
+        mapParams: (args) => ({
+            paneId: args.paneId || ONDA_CONTEXT.paneId || undefined,
+            workspaceId: args.workspaceId || ONDA_CONTEXT.workspaceId || undefined,
+            bin: args.bin,
+            args: args.args,
+        }),
+    },
+    onda_launch_session: { method: 'launchSession' },
     // System (onda_context handled separately - it's local, not RPC)
     onda_status: { method: 'session.current' },
     onda_app_info: { method: 'app.info' },

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@mindfullabai/onda-mcp",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "MCP server for Onda terminal - control tabs, panes, terminals from AI agents",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "onda-mcp": "./dist/index.js"
+    "onda-mcp": "./dist/index.js",
+    "onda-mcp-install-skill": "./bin/install-skill.mjs"
   },
   "exports": {
     ".": {
@@ -33,11 +34,17 @@
   "author": "Mindfull AI <hello@mindfull.ai>",
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "scripts/install-skill.mjs",
+    "skills"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
-    "dev": "tsx src/index.ts"
+    "build": "tsc && chmod +x dist/index.js bin/install-skill.mjs scripts/install-skill.mjs",
+    "dev": "tsx src/index.ts",
+    "install-skill": "node scripts/install-skill.mjs",
+    "postinstall": "node scripts/install-skill.mjs --quiet || true",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1"

package/scripts/install-skill.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Install (or update) the onda-mcp-usage Claude Code skill into
+ * `~/.claude/skills/onda-mcp-usage/`.
+ *
+ * Runs automatically as a `postinstall` step of @mindfullabai/onda-mcp,
+ * AND can be invoked manually:
+ *   npx @mindfullabai/onda-mcp install-skill
+ *   npx @mindfullabai/onda-mcp install-skill --force
+ *   npx @mindfullabai/onda-mcp install-skill --skills-dir /custom/path
+ *
+ * Idempotent + version-aware: if the installed SKILL.md has the same
+ * `metadata.version` as the bundled one, skip. Use `--force` to overwrite
+ * regardless. Honors `--quiet` for silent CI runs.
+ *
+ * Failure modes are non-fatal: if we cannot write (e.g. ~/.claude doesn't
+ * exist on a CI box), we log a hint and exit 0 so `npm install` does not
+ * abort the user's workflow.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { homedir, EOL } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const SOURCE_SKILL_PATH = resolve(PKG_ROOT, 'skills', 'onda-mcp-usage', 'SKILL.md');
+
+const argv = process.argv.slice(2);
+const FLAG_FORCE = argv.includes('--force');
+const FLAG_QUIET = argv.includes('--quiet') || process.env.ONDA_MCP_QUIET === '1';
+
+const customSkillsDirIdx = argv.findIndex((a) => a === '--skills-dir');
+const TARGET_SKILLS_DIR =
+  customSkillsDirIdx !== -1 && argv[customSkillsDirIdx + 1]
+    ? resolve(argv[customSkillsDirIdx + 1])
+    : join(homedir(), '.claude', 'skills');
+
+const TARGET_SKILL_DIR = join(TARGET_SKILLS_DIR, 'onda-mcp-usage');
+const TARGET_SKILL_PATH = join(TARGET_SKILL_DIR, 'SKILL.md');
+
+const log = (...args) => {
+  if (!FLAG_QUIET) console.log('[onda-mcp install-skill]', ...args);
+};
+
+/**
+ * Extract `metadata.version: x.y.z` from a SKILL.md frontmatter, or
+ * fall back to the top-level `version:` key. Returns null if absent.
+ */
+function extractVersion(content) {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const block = fm[1];
+  const metaVer = block.match(/^\s*version:\s*['"]?([^'"\n]+?)['"]?\s*$/m);
+  if (metaVer) return metaVer[1].trim();
+  return null;
+}
+
+function main() {
+  if (!existsSync(SOURCE_SKILL_PATH)) {
+    log(`source skill missing at ${SOURCE_SKILL_PATH} — nothing to install`);
+    return;
+  }
+
+  const sourceContent = readFileSync(SOURCE_SKILL_PATH, 'utf8');
+  const sourceVersion = extractVersion(sourceContent);
+
+  // Target dir may not exist (Claude Code not installed on this box).
+  if (!existsSync(dirname(TARGET_SKILLS_DIR))) {
+    log(
+      `~/.claude not found — Claude Code does not appear to be installed.${EOL}` +
+        '       Skipping skill install. Run `npx @mindfullabai/onda-mcp install-skill` later if needed.',
+    );
+    return;
+  }
+
+  let installedVersion = null;
+  if (existsSync(TARGET_SKILL_PATH)) {
+    try {
+      installedVersion = extractVersion(readFileSync(TARGET_SKILL_PATH, 'utf8'));
+    } catch {
+      installedVersion = null;
+    }
+  }
+
+  if (!FLAG_FORCE && installedVersion && sourceVersion && installedVersion === sourceVersion) {
+    log(`already up to date (v${installedVersion}) — skipping. Use --force to overwrite.`);
+    return;
+  }
+
+  try {
+    mkdirSync(TARGET_SKILL_DIR, { recursive: true });
+    writeFileSync(TARGET_SKILL_PATH, sourceContent, 'utf8');
+    const verLabel = sourceVersion ? `v${sourceVersion}` : '(unversioned)';
+    if (installedVersion) {
+      log(`updated ${installedVersion} -> ${sourceVersion ?? '?'} at ${TARGET_SKILL_PATH}`);
+    } else {
+      log(`installed ${verLabel} at ${TARGET_SKILL_PATH}`);
+    }
+    // Sanity: confirm write
+    const written = statSync(TARGET_SKILL_PATH);
+    if (written.size === 0) {
+      log('WARNING: wrote 0 bytes — install may have failed silently');
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    log(`install failed: ${err.message}`);
+    log('  Hint: run with --skills-dir <path> to redirect, or fix permissions on ~/.claude/skills/');
+    // Non-fatal during postinstall to avoid breaking `npm install`.
+    return;
+  }
+}
+
+main();

package/skills/onda-mcp-usage/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: onda-mcp-usage
+description: Best practices for driving Onda (terminal emulator) from Claude Code via the `onda` MCP server (`mcp__onda__*`). Covers workspaces/windows/panes/terminals + buffer reading (read/subscribe/poll/wait_for/send_keys) + spatial awareness (layout/screenshot). Use whenever you call any `mcp__onda__*` tool or the user mentions Onda, pane, workspace, terminal listener, presence badge, inception loop (Claude controlling Onda from inside Onda). Triggers — onda mcp, drive onda, control onda terminal, show pane, workspace layout, onda screenshot, kai watcher, terminal listener.
+metadata:
+  version: 0.2.0
+  source: '@mindfullabai/onda-mcp'
+---
+
+# Onda MCP usage skill
+
+This skill tells you **how to correctly use the 38 `mcp__onda__*` tools** exposed by the `onda-mcp` server. It is installed alongside the MCP server. Without this guide you hit non-obvious pitfalls (subscribe AFTER run loses output, `down`/`right` mapping inverted pre-fix, UI cache refresh).
+
+## Mental model
+
+You (Claude Code) run inside **a terminal inside Onda**. The `onda-mcp` server talks to the Onda host app via JSON-RPC over UDS at `~/.config/onda/onda.sock`. **Inception loop**: every action through `mcp__onda__*` mutates the app you're running inside. Treat pane/workspace state as **shared mutable** with the user — do not assume it stays the same.
+
+Onda has three layout primitives:
+- **Window**: Electron BrowserWindow. N workspaces can coexist in one Window in tiled mode.
+- **Workspace**: root folder + collection of panes. Mounted into a Window.
+- **Pane**: container with `contentType: terminal | editor | diff`. Terminals have a stable `terminalId` (survives split/merge).
+
+Internal workspace layout = mosaic-component tree. Read it via `onda_workspace_layout`.
+
+## When to use what — cheat sheet
+
+| Goal | Tool |
+|---|---|
+| "Which workspaces exist" | `onda_workspace_list` |
+| "Which Windows are open" | `onda_window_list` |
+| "How is workspace X laid out" | `onda_workspace_layout` |
+| "I want to see what the user sees" | `onda_window_screenshot` |
+| "Open a new terminal right/below pane X" | `onda_workspace_add_terminal` with `direction` + `relativeToPaneId` |
+| "Read what the terminal has printed so far" | `onda_terminal_read` (no subscribe needed) |
+| "I want to receive every new output chunk" | `subscribe` + `poll` loop |
+| "Wait until the build finishes" | `onda_terminal_wait_for` with regex |
+| "Press Ctrl+C / Up / Esc" | `onda_terminal_send_keys` (NOT `terminal_send` with `"\x03"`!) |
+| "Type a command and run it" | `onda_terminal_run` (text + \n) |
+| "Detach listener when done" | `onda_terminal_unsubscribe` (ALWAYS) |
+| "Spawn Claude Code in a new pane with a prompt" | `onda_terminal_spawn` with `bin=claude`, `args=[prompt]` |
+
+## Pattern: working with terminal buffer (reads)
+
+**Anti-pattern**: call `terminal.run` and THEN `terminal.read`. The tap is created lazily on first `read`/`subscribe`, and PTY data emitted before the tap exists is **lost**.
+
+```
+✗ run → read   (you lose the run's output)
+✓ read|subscribe → run → read|poll  (captures everything)
+```
+
+Ring buffer size:
+- **200 KB** when no listener (`read`-only mode)
+- **1 MB** when at least one `subscribe` is active
+
+For high-throughput output (`find /`, `tail -F` on logs) the ring saturates. Use `wait_for` with a precise pattern instead of subscribe + scan.
+
+## Pattern: subscribe + poll loop
+
+```
+sub = subscribe(id, listener="kai-watcher")
+loop {
+  res = poll(sub.sessionId, timeoutMs=15000)
+  for chunk in res.chunks: process(chunk.data)
+}
+unsubscribe(sub.sessionId)
+```
+
+`poll` is **long-poll**: unblocks on first `data` event or on timeout. Immediate wake-up on new output. Cursor advances only on successful poll — no replay.
+
+**Mandatory cleanup**: call `unsubscribe` when done. Automatic TTL is 30 min but don't rely on it.
+
+## Pattern: scriptable terminal automation (tmux-style)
+
+```
+sub = subscribe(id, "kai-script")           # optional, for log
+send_keys(id, ["echo BUILD_START", "Enter"])
+wait_for(id, /BUILD_START/)                  # sync barrier
+send_keys(id, ["npm test", "Enter"])
+wait_for(id, /PASS|FAIL|error/, timeoutMs=120000)
+send_keys(id, ["Ctrl+C"])                    # cleanup
+unsubscribe(sub.sessionId)
+```
+
+Keysyms supported by `send_keys`: `Enter`, `Tab`, `Escape`, `Space`, `Backspace`, `Delete`, `Up/Down/Left/Right`, `Home/End/PageUp/PageDown`, `Insert`, `Ctrl+<letter>`, `F1`-`F12`. Anything else is sent as literal text (useful for `["echo hello", "Enter"]`).
+
+`send_keys` ≠ `terminal_send`: the first maps semantic keysyms → ANSI bytes. The second sends raw text. For `Ctrl+C` ALWAYS use `send_keys(["Ctrl+C"])`.
+
+## Pattern: spatial-aware placement
+
+**Anti-pattern**: spawning panes via `add_terminal` blindly and letting them land randomly. The window grows rightward forever.
+
+**Correct pattern**:
+```
+layout = workspace_layout(workspaceId)
+# layout.paneIds: [...]; layout.activePaneId; layout.viewport
+# Decide: stack down for continuous output, split right for parallel-watch
+new = workspace_add_terminal(workspaceId,
+                              direction="down",
+                              relativeToPaneId=layout.activePaneId)
+```
+
+`direction` mapping:
+- `right` / `left` → side-by-side (left-right pair)
+- `down` / `up` → stacked (top-bottom pair)
+- `horizontal` = stacked (synonym of `down`)
+- `vertical` = side-by-side (synonym of `right`)
+
+Use `down` when the new pane will emit continuous output (logs, build). Use `right` for parallel work terminals.
+
+## Pattern: visual verification
+
+When you need to visually confirm an action succeeded (layout changed, badge appeared, modal opened) use `window_screenshot`:
+
+```
+screenshot = window_screenshot(windowId, format="jpeg", quality=72, dataUrl=false)
+# returns path; use Read on the image
+```
+
+Default `dataUrl=true` returns inline base64 (~1-2 MB), `dataUrl=false` writes a tempfile that `Read` mounts as multimodal image — preferred to avoid wasting context.
+
+## Pattern: launching Claude Code in a pane (inception)
+
+```
+pane = workspace_add_terminal(workspaceId="...", direction="right")
+subscribe(pane.terminalId, "kai-watcher")     # BEFORE launch
+terminal_spawn(pane.paneId, bin="claude", args=["--dangerously-skip-permissions", "prompt..."])
+# Claude TUI shows "Trust this folder?" prompt
+send_keys(pane.terminalId, ["Enter"])         # confirm default highlighted (1. Yes)
+# From here Claude works — use wait_for with expected completion pattern
+wait_for(pane.terminalId, /===KAI_CHECK_DONE===/, timeoutMs=120000)
+unsubscribe(...)
+```
+
+**Claude TUI gotcha**: the stream is VERY noisy (100+ chunks/sec of ANSI spinners). Prefer `wait_for(pattern)` over continuous `poll`. For visual debugging use `screenshot` every 30s, NOT text buffer reads.
+
+## Pattern: drive a remote Claude Code session (auto-pilot)
+
+Use case: Alita just spawned Kai in an adjacent Onda tab and wants to **guide it autonomously** without Mario clicking anything. Pattern validated 21 May 2026.
+
+```
+# 1. Spawn (tab_exec or terminal_spawn)
+tab_exec(bin="claude", args=["--model","sonnet"], cwd="~/Projects/...")
+
+# 2. Find the terminal ID (filter by workspaceId)
+terms = terminal_list(workspaceId="...")
+kai_id = terms[-1].id   # last spawned
+
+# 3. Handle trust prompt if first time in that folder
+wait_for(kai_id, "trust this folder", timeoutMs=10000)
+send_keys(kai_id, ["1", "Enter"])
+
+# 4. Wait for boot completion (welcome screen / inbox banner)
+wait_for(kai_id, "Welcome back|Inbox|MVD\\?", timeoutMs=15000)
+
+# 5. Type the prompt in the textbox
+terminal_run(kai_id, "You are Kai. Proceed like this: /read msg-... then ...")
+
+# 6. CRITICAL: submit the prompt — terminal_run adds \n but Claude TUI treats \n as newline buffer, NOT submit
+send_keys(kai_id, ["Enter"])
+
+# 7. Wait for actual work to start
+wait_for(kai_id, "tokens|reading|esc to interrupt", timeoutMs=30000)
+```
+
+**Critical submit gotcha**: `terminal_run "msg"` writes `msg\n` but Claude's TUI **interprets `\n` as newline in the multi-line buffer**, not as Submit. ALWAYS follow with `send_keys(["Enter"])` to actually submit. Without it, the prompt stays in editing mode forever.
+
+**Empty buffer gotcha**: `terminal_read` on a freshly spawned terminal returns `content:""` because the passive tap attaches lazily on first call. Use `wait_for` with regex on known output patterns (e.g. "tokens", "Welcome", "Tips") instead of assuming `read` shows everything immediately.
+
+## Pattern: observe remote session completion
+
+After `drive remote session` you need to know WHEN the remote task finishes or hits a milestone, without blocking the current session with a multi-hour `wait_for`.
+
+Decision rule for choosing the pattern:
+
+| Case | Pattern |
+|------|---------|
+| Task <5 min, can wait blocked | `terminal_wait_for` direct, single-shot |
+| Long task (>15 min) with bus available | B. Bus inbox check (target uses `/reply`) |
+| Long task, want intermediate milestones | A. Marker pattern + `ScheduleWakeup` |
+| Multi-hour task, automatic polling | D. `/loop <interval> /inbox` |
+| System-wide background daemon | C. fswatch + osascript (roadmap, not implemented) |
+
+### A. Marker pattern + ScheduleWakeup
+
+Instruct the target session to print explicit markers at milestones:
+
+```
+terminal_run(kai_id, "Print markers: ===KAI_PHASE1_DONE===, ===KAI_PHASE2_DONE===, ===KAI_ALL_DONE===")
+send_keys(kai_id, ["Enter"])
+```
+
+Then periodically:
+```
+ScheduleWakeup(delaySeconds=900, prompt="check Kai status")
+# on wakeup:
+out = terminal_read(kai_id, lines=200)
+if "===KAI_ALL_DONE===" in out: close coordination
+elif "===KAI_PHASE2_DONE===" in out: log progress, wakeup again
+```
+
+Pro: granular, intermediate milestones, no extra infra.
+Con: depends on target actually printing them; markers may fall out of the 200KB ring buffer.
+
+### B. Bus inbox check (canonical for agent-bus)
+
+Leverage the bus. Target ends task with `/reply <msg-id> response`. Lead receives in `~/.agent-bus/inboxes/<lead>/`. Lead sees the response on next `/inbox` or via SessionStart hook.
+
+```
+terminal_run(kai_id, "When done, run /reply <msg-id> response with summary + artifact_refs")
+
+# Passive check:
+# - automatic via SessionStart hook agent-bus-load.sh
+# - manual: ls ~/.agent-bus/inboxes/alita/ | grep msg-
+```
+
+Pro: native, zero infra, audit trail in thread, independent of terminal PID/buffer.
+Con: on/off only (done or not), no intermediate milestones.
+
+Combinable with A: markers in terminal for milestones + final `/reply` via bus. Best of both. (Pattern used 21 May 2026 with Kai on Vera's todoist sdk migration brief.)
+
+### D. Recurring /loop
+
+For multi-hour tasks with automatic check:
+
+```
+/loop 15m /inbox
+```
+
+The loop checks my inbox every 15 min. Combine with B.
+
+Pro: automatic, lightweight, non-blocking.
+Con: prompt cache miss every 15 min (cache threshold 5 min), non-zero token cost. For tasks <2h prefer A or passive B.
+
+### Observer anti-patterns
+
+- `terminal_wait_for` with multi-hour `timeoutMs`: blocks current session, you lose useful context.
+- Live subscribe to Claude TUI: 100 chunks/sec, saturates listener, burns budget.
+- `terminal_read` polling with sleep <60s: cache miss + noise.
+- Relying on marker pattern WITHOUT explicitly instructing the target to print them. The target doesn't produce them on its own.
+
+**Dirty ANSI buffer gotcha**: read output contains escape sequences (`[?6n`, `[H`, etc). Don't parse the buffer — only use `wait_for` with regex on known tokens, or `screenshot` if you need visual verification.
+
+## Cleanup discipline
+
+**Always**:
+- `unsubscribe(sessionId)` when done reading
+- `pane_close(id)` for panes you created as test/scratch (NOT existing user panes — assume they're Mario's)
+- Prefix listener names with your identifier (`kai-`, `alita-`, `ci-`) for UI badge legibility
+
+**Never close**:
+- The user's original panes
+- The user's workspaces (`workspace_focus` to switch is OK, but no `workspace_delete`)
+- The user's windows (`window_new` is OK, never close existing ones)
+
+## Anti-pattern catalog
+
+1. **Subscribe to Claude TUI**: nope. Generates 100 chunks/sec of spinner. Use `read` at intervals + `wait_for` for known patterns.
+2. **`terminal_send` with raw bytes** (`"\x03"` for Ctrl+C): nope. Use `send_keys(["Ctrl+C"])`.
+3. **`workspace_add_terminal` without prior `workspace_layout`**: blind placement. Append-right quickly becomes unreadable.
+4. **Listener without unsubscribe**: leak for 30 min TTL. UI badge stays. Clean up.
+5. **`window_new`** when the user just wants "one more workspace on the right": NO — the user prefers **mounting the workspace as a tile in the existing window** (today the MCP tool for this is missing → use manual click flow with `tell me when you clicked`).
+6. **Assuming `app_info.name === "Onda-dev"`** distinguishes dev vs prod: NO. Use `app_info.path` or an explicit flag.
+7. **`terminal_run` alone to submit a prompt to Claude TUI**: NO. The TUI treats `\n` as newline buffer. You must always follow with `send_keys(["Enter"])` to actually submit. (Validated 21 May 2026 spawning a dedicated Kai.)
+8. **Spawning Kai and then waiting for Mario to click and type**: anti-pattern. If you spawned the session, you drive it to "Kai is working" (pattern "drive a remote Claude Code session"). Mario shouldn't be a human postman in your agent team.
+
+## Useful knowledge
+
+- Pane header listener badge: blinks blue, click opens popover with "kick" to terminate the session
+- Onda-dev runs with bundle id `com.mariomosca.onda.dev` (sandboxed, no collision with prod)
+- Onda uses a **single UDS socket**, `~/.config/onda/onda.sock`. Only one Onda instance answers MCP at a time (the first to bind). If `app_info` shows odd data, you may be talking to a different instance.
+- The MCP server holds the socket binding until the master Onda app exits — restarting Onda via Cmd+Q + relaunch is how you "promote" another instance to master.
+
+## Tool reference (38 total)
+
+Application:
+- `onda_app_info` — version, pid, paths
+- `onda_app_ping` — health check
+
+Window (Electron BrowserWindow):
+- `onda_window_list` — N windows + workspaces[] per window
+- `onda_window_new` — opens a new empty Window (use with caution, the user prefers same window)
+- `onda_window_screenshot` — PNG/JPEG compositor snapshot (see what the user sees)
+
+Workspace:
+- `onda_workspace_list` — all workspaces + `mountedIn`
+- `onda_workspace_locate` — find by name/id/rootPath
+- `onda_workspace_create` — create new (rootPath required)
+- `onda_workspace_focus` — switch in focused window
+- `onda_workspace_layout` — mosaic tree + paneIds + activePaneId + viewport
+- `onda_workspace_add_terminal` — spawn pane with optional direction
+- `onda_workspace_tile` — set layout (split-h, split-v, quad)
+- `onda_workspace_setLayout` — set custom layout
+
+Pane:
+- `onda_pane_list` — panes in window/workspace
+- `onda_pane_focus` — focus pane
+- `onda_pane_split` / `vsplit` / `hsplit` — low-level split (prefer `workspace_add_terminal` with `direction`)
+- `onda_pane_close` — close pane
+
+Tab (legacy, before tiled-mode-first model):
+- `onda_tab_new` / `list` / `close` / `focus` / `exec`
+
+Terminal (control plane):
+- `onda_terminal_list` — active terminals
+- `onda_terminal_spawn` — exec binary (e.g. `claude`) inside existing pane
+- `onda_terminal_send` — write raw text (NO newline)
+- `onda_terminal_run` — send + newline
+- `onda_terminal_resize` — cols/rows
+- `onda_terminal_kill` — terminate PTY
+- `onda_terminal_focus` — UI focus
+
+Terminal (read/listen plane, M+1 2026-05-21):
+- `onda_terminal_read` — snapshot ring buffer
+- `onda_terminal_subscribe` — attach listener, return sessionId
+- `onda_terminal_poll` — long-poll new chunks
+- `onda_terminal_unsubscribe` — detach
+- `onda_terminal_listeners` — who is listening to this terminal
+- `onda_terminal_wait_for` — block on regex match
+- `onda_terminal_send_keys` — semantic keysym (Ctrl+C, Up, F5, ...)
+
+Session:
+- `onda_session_current` — current CLI consumer session
+- `onda_launchSession` — atomic macro "open workspace + add terminal + spawn bin"
+
+## Versioning
+
+Skill version: see `metadata.version` in frontmatter. Bump when you add/remove patterns or tools. To reinstall the latest version, run `npx @mindfullabai/onda-mcp install-skill` (TODO) or copy manually from `<onda-mcp-repo>/skills/onda-mcp-usage/`.