FieldWorks WinForms/WinApp Automation

Use this skill to launch, inspect, navigate, and capture evidence from the FieldWorks Language Explorer desktop app through WinForms MCP or WinApp MCP. Keep the workflow grounded in the live UI tree: inspect first, interact second, capture evidence after the target state is visible.

Scope: legacy WinForms only. This skill always runs FieldWorks in Legacy (WinForms) UI mode to scrape the legacy UI for "truth" screenshots, workflows, and behaviour (the migration parity baseline). The WinForms UIA2 MCP can only see WinForms — the Avalonia (New) UI is captured by a SEPARATE headless skill, never through this MCP. ALWAYS run scripts/Set-FieldWorksLegacyMode.ps1 before launching (see Setup First).

This skill OWNS the app lifecycle: never use it on a FieldWorks the developer is using. It launches, forces the UI mode, relaunches per tool, and closes the main window -- which takes down a session someone is working in. Before any route here, confirm the developer has no FieldWorks open (or that the instance is yours to drive). When they are exploring, either wait or ask them to capture what you need.

This skill is intentionally organized as a small index plus route-specific navigation files. Read only the route files needed for the task.

Migration-doc screenshots. Capturing the legacy "truth" PNGs for the Phase-1 migration docs — UIA2 capture limits, the launch-per-tool silfw link, the dialog screenshot harness, and before/after pairing — is documented in navigation/migration-doc-capture.md. Read that route before any bulk capture campaign.

Setup First (if winforms_* tools are missing)

If ToolSearch "winforms" finds no tools, the MCP server is not registered for Claude Code — most often because it is only in .vscode/mcp.json (VS Code's file), not the repo-root .mcp.json (Claude Code's file). Read references/mcp-setup.md, then:

1. Ensure repo-root .mcp.json registers winforms-mcp (committed here; the Windows-robust cmd /c npx form).
2. Run scripts/Preflight-WinFormsMcp.ps1 to confirm node/npx, the package, and a built Output/Debug/FieldWorks.exe.
3. Reconnect/restart Claude Code (MCP servers load at session start) and approve the project server when prompted. Confirm with claude mcp list and ToolSearch "winforms".

The MCP client launches the server — no script starts it; the preflight only verifies that launch will succeed.

Core Rules

• Prefer WinForms MCP UIA2 tools for fresh FieldWorks runtime automation because FieldWorks is currently WinForms and the workspace config (.mcp.json, HEADLESS=false) runs FieldWorks on the visible console desktop — hidden-desktop mode does not render FieldWorks (see references/headless-rendering.md).
• Use WinApp MCP UIA3 tools when WinForms MCP is unavailable, when a task needs desktop/window diagnostics (focus, foreground, window order), or when UIA2 cannot see the target window.
• Prefer UI Automation IDs and names over coordinates. Use coordinates only after snapshots and element searches fail.
• Always inspect the current tree with winforms_get_element_tree, mcp_winapp_get_snapshot, or targeted element search before assuming a dialog structure.
• Treat FieldWorks UI automation as stateful. After opening menus, dialogs, or popups, re-query the snapshot or element list.
• Capture screenshots into a task-specific evidence folder before closing the app or dialog.
• Close evidence-only dialogs with Cancel or Escape unless the user asked to change project data.
• Do not globally register COM or add registry hacks. FieldWorks uses reg-free COM from the build output.

MCP Selection

• Default to WinForms MCP for launch/test/screenshot flows. Use winforms_launch_app, winforms_wait_for_element, winforms_get_element_tree, winforms_find_element, winforms_click_element, winforms_type_text, winforms_set_value, winforms_select_item, winforms_click_menu_item, and winforms_take_screenshot.
• Prefer element-targeted operations (winforms_click_element, winforms_type_text, winforms_set_value, winforms_select_item) over winforms_send_keys, drag/drop, and double-clicks — they are more reliable. (The old blanket bans on input simulation applied to the abandoned hidden-desktop mode; see references/headless-rendering.md for the history.)
• Use WinApp MCP for desktop/window diagnostics, UIA3 comparison, fallback screenshots, or controls that WinForms MCP cannot operate.
• Read references/mcp-selection.md before changing a route from one MCP driver to the other.

How This Skill Is Organized

• SKILL.md: trigger metadata, global safety rules, and route index.
• navigation/*.md: one goal-oriented navigation path per file. These are the FieldWorks equivalent of Page Objects: each file owns the menu path, automation IDs, verification cues, and safe exit path for one user-facing destination or workflow.
• references/how-to-update.md: rules for adding or revising navigation paths.
• references/mcp-selection.md: rules for choosing WinForms MCP or WinApp MCP.
• references/mcp-setup.md: enabling the winforms_* tools for Claude Code (.mcp.json, reconnect).
• references/research.md: source-backed rationale for this structure.
• scripts/Preflight-WinFormsMcp.ps1: pre-session check (node/npx, package, build, .mcp.json).
• scripts/Set-FieldWorksLegacyMode.ps1: forces UIMode=Legacy — run before EVERY launch.
• scripts/Resolve-FieldWorksDevRegistry.ps1: aligns the dev registry (RootCodeDir/RootDataDir) to this worktree before launch; auto-realigns when the other worktree is idle, else prints RESULT=ASK_USER. A build running from inside a source tree resolves code and data from that tree and ignores these values; they govern a build launched from outside one.
• references/headless-rendering.md: why FieldWorks needs a display-bound desktop; what works/doesn't for invisible capture (winforms-mcp HEADLESS does NOT render FieldWorks; a Virtual Display Driver was tried and abandoned — see the doc for why; use visible capture, or RDP for true invisibility). Starts with the "three senses of headless" disambiguation — read that before reasoning about anything called "headless".

When a task names a destination, read the matching navigation file. When a task discovers a better route or a fragile selector, read and update references/how-to-update.md before changing the route file.

Navigation Path Index

• Launch or attach to FieldWorks: navigation/launch-or-attach.md
• Confirm or restore a sample project: navigation/project-loading.md
• Writing System Properties > Font tab: navigation/writing-system-font-options.md
• Styles dialog > Font tab: navigation/styles-font-tab.md
• Manual screenshot evidence: navigation/screenshot-evidence.md
• Migration-doc capture campaign: navigation/migration-doc-capture.md
• WinForms ↔ Avalonia parity capture: navigation/winforms-avalonia-parity.md
• Enable the MCP tools for Claude Code: references/mcp-setup.md
• MCP driver selection: references/mcp-selection.md

Screenshot Evidence

For evidence tasks, read navigation/screenshot-evidence.md — it owns the output folders (transient vs committed vs parity bundles) and the naming rules.

For target detection, descriptive filenames, inline review, annotation, and retake quality gates, also use ../smart-screenshot-capture/SKILL.md.

How To Update This Skill

Keep improving this skill as you explore FieldWorks and discover the most efficient ways to do things. When you find a reliable automation ID, keyboard route, menu path, restore flow, modal-dialog workaround, or screenshot trick, update the relevant route file in the same change set or propose the update to the user. Prefer short, verified notes over broad guesses.

Use references/how-to-update.md for the exact update checklist. In short:

• add one navigation file per distinct destination or workflow;
• keep each file task-focused and action-oriented;
• record stable automation IDs, entry state, verification cues, and exit path;
• move shared rules back to this index only when at least two route files need the same guidance;
• remove or revise stale routes when WinApp snapshots prove they changed.