Ikenga iyke (control bridge)

Patch fields on an existing project. Only the fields you pass in `patch` are touched — omit a field to leave it as is. Pass `null` to clear a nullable field (root_path, icon, color, description). `position` controls the project ordering in the activity-bar switcher (lower = earlier). Cannot change `id`; create a new project and migrate instead.

Dump the TanStack Query cache: queryKey, status, fetchStatus, isStale, dataUpdatedAt, errorUpdatedAt, error, and a 200-char data preview for each entry. Useful for diagnosing stale data or failed fetches.

Append to a scratchpad without overwriting. Creates it if missing. `with_separator=true` (default) inserts a horizontal rule + timestamp between the prior body and the new content.

Delete a scratchpad by scope+name. Idempotent.

List scratchpads in a scope (defaults to active project). Each entry has id, name, updated_at, and a 200-char preview.

Read a scratchpad by scope+name. 404 if missing. Returns id, body, updated_at.

Create or replace a project-scoped Markdown scratchpad. Use for plans, handoffs, working context that should outlive a chat. `scope` defaults to the active project (project:<active_id>); pass "workspace" or "pkg:<id>" to opt out. `name` is a slug unique within scope. Body cap 1 MB.

Capture a PNG screenshot of either the full window or a specific pane. Returns the saved path, dimensions, and byte count. Default writes to ~/.local/share/ikenga/screenshots/.

Delete a secret from the given scope. Same scope semantics as iyke_secret_get. Returns ok even if the key did not exist. Does not touch the legacy unscoped key — to clean up legacy entries, delete the value at the unscoped key directly.

Read a secret from the vault. The scope arg partitions the read: omit it (or pass an empty string) to read from the active project; pass "workspace" to read a cross-project shared secret; pass "project:<id>" or "pkg:<id>" to target a specific partition. Returns the value as a string, or null when the key does not exist in the chosen scope. Falls back transparently to the legacy unscoped key when a scoped value is missing (with a deprecation log on the host).

List secret KEY NAMES (not values) in a scope. Same scope semantics as iyke_secret_get. Returns sorted bare key names — the scope prefix is stripped. Use to inventory what secrets are stored in a project without revealing values.

Write a secret to the vault under the given scope (same scope semantics as iyke_secret_get). Triggers a re-dump of the runtime env-vault file so sidecars and per-call MCP children pick up the new value on next spawn. Use this sparingly — secrets are sensitive and the values land in the user's encrypted Stronghold snapshot.

List Claude chat sessions. Filter by project (defaults to active); pass include_all=true to list across all projects. Returns at most 50 threads by default (max 200). Each entry has id, title, cwd, project_id, claude_session_id, created_at, updated_at.

Move a chat thread between projects. Metadata-only — does not restart the claude subprocess. The cwd captured at spawn time stays whatever it was. Fails if the target project is unknown or archived.

Mint a new Claude chat thread attached to a project. The shell resolves the project root as the session cwd, builds the layered Claude-config overlay dir (skills + agents + commands + merged .mcp.json) for the spawn, and routes the request through the ACP `session/new` handler. Returns the new thread_id; the actual subprocess spawns lazily on the first prompt — fire `acp_prompt` or open `/sessions/$threadId` in the UI to send the initial message. `initial_prompt` is currently informational only (the bridge does not forward it yet).

Split the focused pane (or a specific pane via pane_id) into two. "horizontal" splits side-by-side; "vertical" splits top-bottom. Subject to the in-app MAX_LEAVES cap (currently 6).

Get the current state of the Ikenga desktop app — sidebar mode, focused pane route, and the full pane tree under shell.panes. shell.panes has shape { leaves: [{ id, focused, activeTabIdx, tabs: [{kind,title}] }], tree: <recursive PaneNode> }; use leaves[].id with iyke_focus or iyke_close (pane_id) to operate on a specific pane. Call this before iyke_go / iyke_mode / iyke_focus / iyke_close to check what the user is currently looking at.

Cancel a pending timer by id. No-op if already fired or cancelled. Returns { cancelled: bool }.

List timers in a scope (defaults to active project). Optional status filter: pending | fired | cancelled. Returns timers sorted by fire_at ascending.

Schedule a one-shot timer in the active project (or specified scope). Pass either fire_at (absolute epoch-ms) or delay_ms (relative from now), not both. When the timer fires the shell emits an OS notification; if agent_id is set, an entry also lands in that agent's inbox (delivered on its next tool call, 24h TTL).

Mark a todo as done and stamp completed_at. Equivalent to iyke_todo_update with status=done.

Create a project-scoped todo. Tags are free-form strings; assignee is a free-form name (agent or user). Set blocker_id to mark this todo as blocked by another.

List todos in a scope (defaults to active project). Filter by status, tag, assignee.

Partial update of a todo. Only supplied fields are changed. Pass status="done" or use iyke_todo_complete for the common case.

Type text into an input/textarea/contenteditable element. Specify exactly one of `ref` or `selector`. By default appends; pass `replace=true` to overwrite the existing value.

Wait until a predicate is satisfied or timeout. Use this after iyke_click / iyke_go to wait for the new state to render, instead of fixed sleeps. Returns { satisfied, elapsed_ms, message? }.