For contributors

Birch’s developer documentation lives in the repository, not on this site. This page is the pointer: the three commands you need, and links to the in-repo guides for architecture, release process, and the roadmap.

Build, test, run

You need the .NET 10 SDK (global.json pins 10.0.101, rolling forward to the latest feature band). Then:

terminal

# Build
dotnet build Birch.sln

# Run all tests
dotnet test Birch.sln

# Run the app
dotnet run --project src/Birch.App

Run dotnet tool restore once per checkout before using the pinned dotnet-ef or vpk tools. CI builds and tests on Windows + macOS but is manual-only — run the test suite locally before submitting changes.

Developer documentation in the repo

• CLAUDE.md — the architecture and developer guide: layer rules, key services, patterns, and gotchas. Also AGENTS.md.
• docs/RELEASE.md — the release and rollback process (releases are cut from v*.*.* tags).
• docs/ROADMAP.md — the live backlog.

Bugs and feature requests go to the issue tracker.

Where things live in the source tree

Path	What it is
src/Birch.App	The Avalonia desktop app (Views, ViewModels)
src/Birch.Cli	The birch command-line tool
src/Birch.Application	Use-case services shared by the UI and the CLI
src/Birch.Git	Git operations (CLI-based engine)
src/Birch.Integrations	GitHub / GitLab / Azure DevOps / Jira / Linear / YouTrack providers + the Anthropic AI adapter
src/Birch.Persistence	EF Core + SQLite storage and migrations
integrations/claude-code-plugin	The birch-status plugin for Claude Code
plugins/birch-status	The birch-status plugin for Codex
tests/	xUnit test projects (Application, Git, Integrations, App headless UI, Cli)

How this documentation is organized

The docs site sources live under docs-site/ in the same repository (currently on the claude/app-documentation-structure-x6f7nm branch — the directory has not landed on main yet):

• docs-site/STRUCTURE.md defines the navigation — every page, its section, and its priority.
• docs-site/CONVENTIONS.md defines the authoring rules — terminology, linking, admonitions, and honesty callouts.

To add a page: create it under docs-site/content/, register it in the navigation per STRUCTURE.md, and follow the rules in CONVENTIONS.md.