helmor-debug-operate

# Helmor Debug Operate

Use this skill to operate and debug a running Helmor dev build through Tauri MCP with the least possible exploration. It is the visual/runtime counterpart to `helmor-cli`: prefer Tauri MCP for webview UI, screenshots, CSS, accessibility, and IPC tracing; prefer `helmor-cli` for terminal-first data inspection or workspace orchestration.

Examples below use bare tool names such as `driver_session`; call the same tool through whatever namespace the runtime exposes.

## References

Read these only when needed:

- `references/verified-recipes.md` for action-specific recipes that have passed three consecutive Tauri MCP verification attempts.
- `references/ui-map.md` for selectors, Settings panels, Inspector/Editor preconditions, and destructive-action boundaries.

## Ground Rules

- Treat every action as real user input against the active app. Do not send prompts, close sessions, archive/delete workspaces, stop streams, or mutate settings unless the user asked for that outcome or it is necessary for the verification.
- Use the Tauri MCP bridge only for Helmor desktop debugging. Do not switch to Chrome DevTools, Browser, Playwright, or `/agent-browser` unless the user explicitly asks for another surface.
- Require a debug Tauri build. The bridge is absent in release builds. If connection fails, ask the user to run `bun run dev` or call `get_setup_instructions` only when bridge setup itself is suspect.
- Default to `port: 9223` and `windowId: "main"`.
- Re-run `webview_dom_snapshot` after every meaningful UI change. `ref=eN` handles are per-snapshot and expire after DOM changes.
- Prefer accessibility snapshots for finding controls, but fall back to structure snapshots and read-only DOM rect inspection when accessibility support is unavailable.
- Prefer UI operations for end-to-end validation. Do not use the Tauri MCP tool `ipc_execute_command` for Helmor app commands such as `list_workspace_groups`, `reveal_workspace_in_main_window`, or `debug_list_terminal_buffers`: the current bridge returns `Unsupported Tauri command` because dynamic app-command execution is not implemented there. Use the verified app-command helper in **Call App Commands** instead.
- Do not use `webview_execute_js` to dispatch synthetic user events. Use it only for read-only, JSON-serializable inspection when MCP tools cannot answer the question.
- Exception: Helmor's composer is a Lexical `contenteditable`, not a native input. If `webview_keyboard type` fails with the current bridge, `document.execCommand("insertText", false, text)` after real MCP focus/click is the last-resort smoke-test input path. Label it as a fallback and verify visible state afterward.
- If you start `ipc_monitor`, always stop it before finishing, even if the task fails.
- Save screenshots or scratch logs under `.agent-contexts/<task-slug>/` when working inside this repository.
- If a Settings dialog appears stuck visible with `data-state="closed"`, press `Cmd+,` to reopen it, then `Escape` to close. Verify `document.querySelectorAll('[role="dialog"]').length === 0` and `main[aria-hidden]` is absent.
- If `webview_execute_js` or console log reads start timing out while screenshots and `driver_session status` still work, restart only the MCP driver session (`driver_session stop appIdentifier=9223`, then `driver_session start port=9223`). Do not restart the Helmor dev build unless the bridge cannot reconnect.
- If you launch a disposable app with `HELMOR_DATA_DIR` for validation, create both the data dir and its `run/` subdir first. Missing `run/` can make the UI sync socket fail to bind, leaving backend mutations invisible until you force a reveal or restart.
- Treat this skill as an operation hint, not an authoritative source of truth. The local UI can drift ahead of these recipes. If a recipe fails three times, stop repeating it mechanically: take a fresh screenshot/snapshot, reason from the visible UI, and inspect the relevant code if needed.
- Keep this skill self-improving by proposal, not silent mutation. When you discover a better path, missing pitfall, stale selector, or unverified workaround, record a candidate update under `.agent-contexts/<task-slug>/skill-update-candidates.md` with the scenario, failing attempts, evidence, proposed recipe, and verification status. Ask the user before editing this skill unless the current user request explicitly asks you to update it.

## Connect

1. Check the bridge:

```json
driver_session { "action": "status", "port": 9223 }
```

2. Start only when not connected:

```json
driver_session { "action": "start", "port": 9223 }
```

3. Sanity-check the target:

```json
ipc_get_backend_state {}
manage_window { "action": "list" }
```

Expect `app.identifier` to be `ai.helmor.desktop`, `app.name` to be `Helmor`, `environment.debug` to be `true`, and a visible `main` window. If multiple apps are connected, pass the returned port or bundle id as `appIdentifier` on later calls.

## Baseline Snapshot

Start every UI task with both a visual and semantic read:

```json
webview_screenshot { "windowId": "main", "format": "png" }
webview_dom_snapshot { "windowId": "main", "type": "accessibility" }
```

If accessibility fails with `aria-api library not loaded`, immediately use:

```json
webview_dom_snapshot { "windowId": "main", "type": "structure" }
```

Avoid taking screenshots with `maxWidth` when you need click coordinates. A scaled screenshot changes the coordinate space; direct `webview_interact { "x": ..., "y": ... }` expects the webview's real coordinates from `getBoundingClientRect()` or `manage_window info`.

Use this stable mental map:

- Shell: `Application shell`, `Workspace sidebar`, `Workspace panel`, `Workspace viewport`.
- Sidebar buttons: `Workspace location`, `Filter and sort sidebar`, `Add repository`, `New workspace`, `Collapse left sidebar`.
- Workspace rows: role `button` with the displayed workspace title. Nested actions include `Archive workspace`, `Confirm archive workspac