Contributing
Start with a source build, then find the owning area and checks for your change.
Make a change
- Check the working tree. Preserve existing staged, unstaged, and untracked work.
- Find the owner in AGENTS.md and read that area's guide.
- Implement in that layer, following Coding patterns for ownership, errors, persistence, and test placement.
- Run checks for the affected behavior and inspect the diff. Update product docs when behavior changes.
- Run the full verification gate before a code PR. Report local checks, live-provider smoke, and remote CI separately.
Choose guidance for the change
| Task | Guide |
|---|---|
| Launch a local development build | Build from source |
| Look up commands | Development commands |
| Fix compilation, cache, or test failures | Build and test troubleshooting |
| Find the owner and checks | Development lanes |
| Place logic and follow runtime conventions | Coding patterns |
| Verify behavior without the desktop UI | Testing workflows |
| Bump versions, tag, and publish a release | Releasing |
| Build or publish the documentation website | Documentation website |
| Trace a run across layers | End-to-end runtime |
| Check dependency rules | Architecture contract |
| Look up engine and app vocabulary | Glossary |
Project skills in .cursor/skills/ give scoped help; Development lanes maps them to changes.
Verify and submit
Development lanes picks the checks; Development commands lists them. Docs-only edits need link, path, syntax, and diff checks. Runtime changes need execution coverage; desktop changes need the desktop lane.
Publishing tags and releases needs explicit authorization. The release guide covers versioning and publication.
Code orientation: Ports and public boundaries, UI layout, Persistence locations.
Fast checks and the full gate: verification command reference.