Add WinForms MCP and skills

.github/skills/fieldworks-winapp/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: fieldworks-winapp
+description: >
+  Control and document the FieldWorks desktop application with WinForms MCP or WinApp MCP.
+  Use this skill whenever a task requires launching FieldWorks, restoring or
+  opening a FieldWorks project, walking WinForms UI flows, collecting manual
+  screenshots, reproducing UI bugs, or verifying a fix inside the live FLEx
+  application.
+license: MIT
+compatibility: >
+  Requires a Windows/x64 FieldWorks workspace. Prefer WinForms MCP
+  for hidden-desktop UIA2 automation when available; use WinApp MCP as the UIA3
+  fallback and for visible desktop/window diagnostics.
+metadata:
+  author: FieldWorks team
+  version: "1.0"
+---
+
+# 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.
+
+This skill is intentionally organized as a small index plus route-specific
+navigation files. Read only the route files needed for the task.
+
+## Core Rules
+
+- Prefer WinForms MCP UIA2 tools for fresh FieldWorks runtime automation because
+  FieldWorks is currently WinForms and the workspace config runs WinForms MCP in
+  hidden-desktop mode.
+- Use WinApp MCP UIA3 tools when WinForms MCP is unavailable, when a task needs
+  visible desktop/window diagnostics, or when UIA2 cannot see the target
+  surface.
+- 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`.
+- Use WinForms MCP headless-safe operations only. Avoid `winforms_send_keys`,
+  drag/drop, and double-clicks on hidden-desktop processes.
+- Use WinApp MCP for visible 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/research.md`: source-backed rationale for this structure.
+
+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`
+- MCP driver selection: `references/mcp-selection.md`
+
+## Screenshot Evidence
+
+For evidence tasks, read `navigation/screenshot-evidence.md`. Prefer committed
+OpenSpec evidence only when the screenshot should be part of review history;
+otherwise use `Output/ManualEvidence/<ticket-or-change-id>/`.
+
+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.

.github/skills/fieldworks-winapp/navigation/launch-or-attach.md

@@ -0,0 +1,66 @@
+# Launch Or Attach To FieldWorks
+
+Use this path when a task needs the live FieldWorks Language Explorer app.
+Choose WinForms MCP first for fresh FieldWorks launches, and use WinApp MCP for
+visible desktop diagnostics or fallback.
+
+## Entry State
+
+- Workspace is a Windows/x64 FieldWorks checkout.
+- Prefer an existing debug build at `Output/Debug/FieldWorks.exe`.
+
+## Preferred Steps: WinForms MCP UIA2
+
+1. Launch debug FieldWorks with `winforms_launch_app`:
+   - `path`: `<workspace>\\Output\\Debug\\FieldWorks.exe`
+2. Keep the returned `pid`; pass it to later process-scoped calls when the MCP
+   client exposes a process parameter.
+3. Wait for a recognizable app window or menu with `winforms_wait_for_element`.
+4. Inspect the tree with `winforms_get_element_tree` before interacting.
+5. Use `winforms_click_menu_item`, `winforms_find_element`,
+   `winforms_click_element`, `winforms_type_text`, `winforms_set_value`, and
+   `winforms_select_item` for headless-safe interaction.
+6. Capture screenshots with `winforms_take_screenshot`. Prefer passing the
+   FieldWorks `pid` so the server can use the hidden-desktop window directly.
+
+## Fallback Steps: WinApp MCP UIA3
+
+1. If FieldWorks is already running, attach to the existing process with
+   `mcp_winapp_attach_to_app` or `mcp_winapp_attach_to_pid`.
+2. Otherwise launch debug FieldWorks with `mcp_winapp_launch_app`:
+   - `exePath`: `<workspace>\\Output\\Debug\\FieldWorks.exe`
+3. If `mcp_winapp_wait_for_input_idle` is not implemented or fails, continue
+   with direct window discovery.
+4. Use `mcp_winapp_list_windows` and `mcp_winapp_list_desktop_windows` to verify
+   the app is visible.
+5. Use `mcp_winapp_get_snapshot` to confirm FieldWorks has a main window and a
+   recognizable UI tree.
+6. If screenshots capture VS Code or another foreground app, press `ALT+ESCAPE`
+   with `mcp_winapp_press_key_combo` until FieldWorks is first in desktop window
+   order or a FieldWorks element has focus.
+
+## Expected Signals
+
+- WinForms MCP launch returns a process ID and can operate on a hidden desktop
+  because `.vscode/mcp.json` sets `HEADLESS=true`.
+- Main window title may initially appear as `The Window` in UI Automation.
+- A loaded project window title may include a project name such as `Sena 3`.
+- The side pane often contains `Lexicon`, `Texts & Words`, `Grammar`,
+  `Notebook`, and `Lists` groups.
+
+## Known Workarounds
+
+- In WinForms MCP headless mode, avoid `winforms_send_keys`, drag/drop, and
+  double-click. Use UIA pattern operations such as `winforms_type_text`,
+  `winforms_set_value`, `winforms_select_item`, and single
+  `winforms_click_element` calls.
+- `mcp_winapp_wait_for_input_idle` may return `not implemented` for
+  FieldWorks. Use snapshots and desktop-window order instead.
+- `mcp_winapp_take_screenshot` captures the foreground surface. Bring
+  FieldWorks forward before relying on screenshots.
+
+## Exit
+
+Close only the FieldWorks instance you launched for the task, using
+`winforms_close_app` or `mcp_winapp_close_app`. Do not close a user's
+pre-existing app instance unless the user asked for cleanup.

.github/skills/fieldworks-winapp/navigation/project-loading.md

@@ -0,0 +1,40 @@
+# Confirm Or Restore A Sample Project
+
+Use this path after launching FieldWorks when a task needs a repeatable project.
+
+## Entry State
+
+- FieldWorks is launched or attached.
+- You have an app ID from WinApp MCP.
+
+## Steps
+
+1. Get a snapshot with `mcp_winapp_get_snapshot`.
+2. Treat the project as loaded if the snapshot contains a root document such as
+   `Root - Sena 3`, or if the desktop title contains the expected project name.
+3. For repeatable manual evidence, use the current project if `Sena 3` is
+   already loaded.
+4. If no project is loaded, restore from the sample backup at the repository
+   root:
+   - `Sena 3 2018-09-11 1145.fwbackup`
+5. Use the File menu and inspect the menu tree for restore/project-management
+   commands before clicking.
+6. If a file chooser opens, select the backup path and proceed through restore.
+7. Re-inspect the app and capture a loaded-project screenshot.
+
+## Expected Signals
+
+- Project loaded: `Root - Sena 3` document in the snapshot.
+- Common loaded side pane: `Lexicon Edit`, `Browse`, `Dictionary`,
+  `Collect Words`, `Classified Dictionary`, `Bulk Edit Entries`.
+
+## Safety
+
+- Do not restore over an existing loaded project unless the task requires it.
+- Prefer evidence-only screenshots over changing project data.
+
+## Exit
+
+Continue to the requested navigation path. If project restore was only a setup
+step and the user did not ask to keep the app open, close the launched app at
+the end of the task.

.github/skills/fieldworks-winapp/navigation/screenshot-evidence.md

@@ -0,0 +1,72 @@
+# Capture Manual Screenshot Evidence
+
+Use this path when the task needs before/after images, Jira evidence, OpenSpec
+evidence, or visual proof that a FieldWorks UI flow works.
+
+For general screenshot quality rules, target inference, sorted filenames,
+annotations, and retake criteria, read `../../smart-screenshot-capture/SKILL.md`
+alongside this route.
+
+## Entry State
+
+- FieldWorks is launched and foregrounded.
+- The target UI state is visible or reachable through another navigation path.
+
+## Steps
+
+1. Create a deterministic evidence folder:
+   - transient: `Output/ManualEvidence/<ticket-or-change-id>/`
+   - committed OpenSpec evidence:
+     `openspec/changes/<change-id>/evidence/manual-winapp/`
+2. Confirm the target FieldWorks process, window, dialog, or tab before capture.
+3. Capture the initial loaded-project state when it helps reviewers orient
+   themselves.
+4. Capture the broken/reproduced state from an unfixed build when available.
+5. Capture the fixed state from the current build.
+6. Inspect each saved image and retake if it is blank, wrong-window, covered,
+  unreadable, or missing the intended state.
+7. Capture related canonical surfaces when the issue spans more than one UI
+   path.
+8. Use an image sequence or GIF when the issue involves timing, redraw, focus,
+   modal transitions, or steps that a single screenshot cannot communicate.
+
+## MCP Choice
+
+- Prefer `winforms_take_screenshot` for fresh FieldWorks launches; hidden
+  desktop screenshots should not steal focus or require foregrounding.
+- Prefer passing the FieldWorks `pid` to WinForms MCP screenshots when the
+  client exposes a process parameter.
+- Prefer `mcp_winapp_take_screenshot_optimized` for visible-desktop fallback
+  captures when image size or token budget matters.
+- Use `mcp_winapp_take_screenshot` when WinForms MCP is unavailable, when the
+  task is explicitly about the visible desktop, or when comparing UIA3 behavior.
+- Use `mcp_winapp_annotate_screenshot` when reviewers need specific controls or
+  changed regions called out.
+- Use `mcp_winapp_screenshot_diff` for before/after comparisons when pixel
+  changes are the evidence.
+
+## Naming
+
+Use names that tell the story in sorted order:
+
+- `01-initial-<state>.png`
+- `02-before-<screen>.png`
+- `03-after-<screen>.png`
+- `04-after-<related-screen>.png`
+- `sequence-<scenario>-001.png`, `sequence-<scenario>-002.png`, ...
+
+## Expected Signals
+
+- Screenshots should show FieldWorks, not VS Code or another foreground app.
+- WinForms MCP screenshots can capture headless FieldWorks windows through
+  `PrintWindow`; foreground-window order should not matter for that path.
+- If `mcp_winapp_take_screenshot` captures the wrong surface, use the launch
+  route's `ALT+ESCAPE` foregrounding workaround and capture again.
+- If a true before-state is not available in the current worktree, document why
+  and describe how to capture it from an unfixed build.
+
+## Exit
+
+Copy only review-worthy screenshots into committed evidence folders. Leave
+scratch captures under `Output/ManualEvidence` unless the user asks to commit
+them.

.github/skills/fieldworks-winapp/navigation/styles-font-tab.md

@@ -0,0 +1,52 @@
+# Navigate To Styles Font Tab
+
+Use this path to inspect or document the shared Font Features control in the
+Styles dialog.
+
+## Entry State
+
+- FieldWorks is launched and a project is loaded.
+- If screenshots are needed, FieldWorks is foregrounded.
+
+## Steps
+
+1. Click the `Format` menu item.
+2. Click `Styles...`.
+3. In `FwStylesDlg`, click the `Font` tab.
+4. Select the target style in `m_lstStyles` if the task requires a specific
+   style. For general evidence, `Normal` is usually sufficient.
+5. Capture or inspect the Font Features state.
+
+## Stable Elements Observed
+
+- Dialog: `FwStylesDlg`
+- Styles list: `m_lstStyles`
+- List filter combo: `m_cboTypes`
+- Tab control: `m_tabControl`
+- Font tab pane: `m_tbFont`
+- Font attributes pane: `m_FontAttributes`
+- Writing systems list: `m_lstWritingSystems`
+- Font combo: `m_cboFontNames`
+- Font Features button: `m_btnFontFeatures`
+- OK button: `m_btnOk`
+- Cancel button: `m_btnCancel`
+
+## Expected Signals
+
+- The Font tab shows `Font features` in the Attributes area.
+- The writing-system list includes `<default settings>` and project writing
+  systems such as `English`, `Portuguese`, `Sena`, and `Sena (Phonetic)` for
+  the Sena 3 sample project.
+
+## Known Workarounds
+
+- The `Styles...` menu item appears only after the `Format` menu is open; if a
+  first click does not expose submenu items, click `Format` again and re-query
+  menu items.
+- Use `mcp_winapp_invoke_element` for `m_btnCancel` when a normal click does not
+  close the dialog.
+
+## Exit
+
+Use `Cancel` for evidence-only sessions. Use `OK` only when the task requires a
+style change.