RoadRaven

Push a status update to a node. Requires the desktop app to be running and a roadmap loaded. Routes through the agent dispatcher so the change appears in the event-log drawer (Ctrl+Shift+L).

Returns the current Event API URL, PID, and startedAt — or an error if the app is not running.

無需輸入參數。

Return the full schema tree from the desktop app, with live-event statuses merged in, plus the current `revision` (pass it as expectedRevision on writes to detect stale reads). Long roadmaps can exceed the tool-result limit, so trim the answer: for a long roadmap or for polling, pass omitNotes: true and hideCompleted: true; to read one phase, pass rootId (that node's id) and depth. A stub is one line { id, title, status, type, childCount } standing in for a node whose children are left out; read those children with rootId set to the stub's id. Notes can also be fetched with getNode/findNodes. Requires the app to be running and a file to be loaded.

Return a node by UUID, with its immediate parent ID, full ancestor chain (root-to-parent), and the current roadmap `revision`. Status reflects the live overlay if a recent event landed.

Search nodes by AND-combined filter: titleContains (case-insensitive substring), status (one status, or a list of statuses to get e.g. all open work in one call), type, metaKey + metaValue, parentId. All fields optional. Set omitNotes for a short list without notes and timestamps. Returns matching nodes (without their children; use parentId or getNode for those) with their parent IDs.

Return the loaded roadmap's statusConfig array (display labels/colors for statuses). Agent mutations accept only core node statuses.

無需輸入參數。

Return the loaded roadmap's typeConfig array (the valid node-type IDs and their visual configuration).

無需輸入參數。

Return filePath (or null if untitled), isUntitled flag, document title, and total nodeCount. Works even when no file is loaded — returns null filePath and isUntitled=false.

無需輸入參數。

Add a child node under parentId with the given title. Optional: id (UUID or slug — supply it when recovering/recreating a node so its identity stays stable and history/metadata continuity survives file churn; duplicate_id if it already exists), type, core status (defaults to not-started), notes (markdown), metadata. Returns the new node's id. Requires a loaded roadmap.

Initialize an in-memory untitled schema (mirrors File > New). Optional: title, statusConfig, typeConfig. The agent must call saveFileAs to persist the new roadmap to disk.

Change a node's title.

Change a node's type string. Use getTypeConfig to discover valid types.

Set a node's notes string (markdown). mode "replace" (default) overwrites the entire notes field — pass an empty string to clear. mode "append" adds a blank line then your text after the existing notes; recommended for agent progress lines.

Shallow-PATCH a node's metadata. Each key in `patch` overwrites the same key in node.metadata; null value deletes that key. Unlisted keys are preserved. Returns the final metadata object.

Apply up to 100 node updates (status, notes, metadata patch) in ONE atomic call — the roadmap revision advances exactly once for the whole batch and the response returns the final `revision` so you can chain further writes without re-reading. All-or-nothing: every item is validated first (node exists, status id in statusConfig); any failure returns batch_validation_failed with per-item {index, nodeId, code} and NOTHING is applied. Ideal for replaying a set of changes after stale_write: call getRoadmap once, rebuild all updates against the fresh tree, and resend the whole batch with expectedRevision.

Re-parent a node to newParentId at optional position (0 = first child; omit = last child). Blocks cycles (cannot move into own subtree) and cross-$ref-boundary moves.

Delete a node. Leaf nodes delete immediately; non-leaf nodes require cascade:true (returns cascade_required with childCount otherwise). Cannot delete the last remaining root.

Force-flush the autosave debouncer immediately. Returns ok or save_error. For untitled schemas, call saveFileAs first.

無需輸入參數。

Save the loaded roadmap to a new file path. Path must satisfy the same allowlist as user actions (within the loaded directory, or previously user-picked).

Flush any pending autosave, then load a roadmap file by path. Path must satisfy the path-allowlist (same as user actions). The agent may need to ask the user to open the target directory first.

Compute a zoom + pan that fits all nodes into the viewport with margin. No-op when no roadmap is loaded. Used by automated demos / recordings to pull-back the camera; safe for live agent use too.

無需輸入參數。

Select a node, centre the camera on it, open its side panel and bring the RoadRaven window to the front. Where the window manager refuses to raise the window, the node is still selected. Use it to show the human the node you are on.