Skip to content

Developer track

For whoever changes Troupe itself. Start with CONTRIBUTING.md and the tour, then ARCHITECTURE.md; the rest is here to be looked things up in.

File What it covers
tour.md Where things live, running the suite, adding a tool, how the event log works
architecture.md The harness and its clients: a session, the agent, tools, the failure matrix, the wire, lifecycle, the core's and the daemon's trees, the TUI and GUI internals
architecture-remote.md The plane, the pods, the operator and the admin surface; bundles, triggers, cost, entitlements, what belongs to a person; their trees
repo-structure.md The tree, where things live, what the image build sees
tech-stack.md Every runtime, library and binary, and why
local-setup.md Prerequisites, the toolbox, development services, a plane on kind, development variables
testing.md Running the suites, what each needs, fixtures, the checks that are tests in all but name
bench.md troupe bench: what a turn costs and does, held to budgets; reading the report, moving a budget, the report's schema; the live bench against a real model, its cap and its history
build.md The images, the native builds, the reaper, generated files, VERSION
ci.md CI, pre-releases, releases, the nightly, and the documentation site
deployment.md What a release publishes, what a roll does, rolling back
conventions.md The gate, boundaries, the formatter's blind spot, commit style, naming, recipes
fixing-issues.md Working through GitHub issues in chunks: triage, fix, install locally, verify, pull request
stage-1-gate.yml The Stage 1 gate: the issue template a release's walk is recorded in, its eight rows, and scripts/gate-check for the half a desk runs
code-signing.md Buying and setting up OS code signing (Apple Developer ID, a Windows signing service) and the secrets a release needs

The design: ../../ARCHITECTURE.md (the map: the apps, the boundaries, the transports, where state lives), the decisions, ../../PROTOCOL.md. The clients: clients/tui (and its decisions), clients/gui, and the daemon's decisions.