GeezerVison

New to FieldWorks development? Start here:

• Contributing Guide - How to set up your development environment and contribute code
• Visual Studio Setup - Detailed Visual Studio configuration (2026 or 2022)
• Core Developer Setup - Additional setup for team members
• AI-Assisted PR Workflow - Canonical core-developer path from Jira to worktree setup, branch preflight, and review response

Note: We are migrating documentation from the FwDocumentation wiki into this repository. Some wiki content may be more recent until migration is complete.

This repository can be opened on Linux or macOS for editing, code search, documentation, specs, and agent-assisted review.

Builds, tests, installer work, and developer-environment setup are Windows-only and are intentionally disabled on non-Windows hosts.

If you need runnable output, use a Windows machine and run ./build.ps1 or ./test.ps1 there.

See Contributing.

FieldWorks uses the MSBuild Traversal SDK for declarative, dependency-ordered builds:

Windows (PowerShell):

.\build.ps1                    # Debug build
.\build.ps1 -Configuration Release

For detailed build instructions, see .github/instructions/build.instructions.md.

build.ps1 and test.ps1 use worktree-aware process cleanup, so running scripted builds/tests in different git worktrees does not kill each other.

Within a single worktree, builds and tests run one at a time: scripts acquire a worktree lock and fail fast if another scripted workflow is active.

You can tag lock ownership for diagnostics with FW_BUILD_STARTED_BY=user|agent (or -StartedBy user|agent).

Installer builds default to WiX 3 (legacy batch pipeline) using inputs in FLExInstaller/ and PatchableInstaller/. Use -InstallerToolset Wix6 to opt into the WiX 6 SDK-style path (restored via NuGet; no setup required).

WiX 3.11 can be installed with Chocolatey:

choco install wixtoolset --version 3.11.2

• Ensure tools (heat.exe etc.) are available in %WIX%\bin or on the PATH.
• Install the Visual Studio WiX Toolset v3 extension so Wix.CA.targets is available to MSBuild.

Installer builds include the additional utilities (UnicodeCharEditor, LCMBrowser, MigrateSqlDbs, etc.). To skip them, pass -BuildAdditionalApps:$false.

# Build the installer (WiX 3 default)
.\build.ps1 -BuildInstaller

# Build the installer (WiX 6)
.\build.ps1 -BuildInstaller -InstallerToolset Wix6

WiX 3 artifacts are produced under FLExInstaller/bin/x64/<Config>/ (MSI under en-US/).

WiX 6 artifacts are produced under FLExInstaller/wix6/bin/x64/<Config>/ (MSI under en-US/).

For more details, see specs/001-wix-v6-migration/quickstart.md.

Signing is optional for local builds. By default, local installer builds do not sign and instead record files to sign later.

To enable signing for a local installer build, pass -SignInstaller to build.ps1.

Required for signing:

• Either sign (SIL signing tool) or signtool.exe on PATH.
• If using signtool.exe, set CERTPATH (PFX path) and CERTPASS (password) in the environment.

If you want to control the capture file, set FILESTOSIGNLATER to a file path before building. The build will append files needing signatures to that file.

This repo ships an mcp.json workspace configuration so MCP-aware editors can spin up the GitHub and Serena servers automatically. See Docs/mcp.md for requirements and troubleshooting tips.

We maintain a shared AGENTS model (AGENTS.md, CLAUDE.md, .github/AGENTS.md, Src/AGENTS.md, FLExInstaller/AGENTS.md, openspec/AGENTS.md) and a minimal, requirement-focused guidance model.

GitHub Copilot custom instructions remain under .github/instructions/*.instructions.md because GitHub requires those paths. Claude Code workflows live under .claude/skills/.

See .github/AI_GOVERNANCE.md for the documentation taxonomy and “source of truth” rules.