Skip to content

Repository structure

.
├── AGENTS.md                notes for coding agents; points at fixing-issues.md
├── ARCHITECTURE.md          the map of the design: the apps, their boundaries, the transports, where state lives
├── PROTOCOL.md              the normative wire document for client authors
├── README.md                the front door
├── VERSION                  the one version of everything released (Decision 668)
├── mkdocs.yml               the documentation site: docs/ and the documents its nav names (Decision 739)
├── .github/                 the workflows (ci.md) and Dependabot
├── apps/                    the umbrella: eight Mix projects (ARCHITECTURE.md §2)
├── charts/troupe/           the Helm chart (platform and GUI), its CRDs, values.small/example
├── clients/tui/             the terminal client: its own Mix project, the harness by path
├── clients/gui/             the graphical client: a pnpm workspace (client, bench, desktop)
├── clients/vscode/          the VS Code extension that opens the TUI in a VS Code terminal: a pnpm project
├── config/                  config.exs (compile time) and runtime.exs (prod only)
├── dev/                     docker-compose.yml, kind/ (dependencies, values), toolbox/, known-local-failures
├── docker/Dockerfile        the four server images
├── docs/                    the user, admin and developer tracks, decisions/ (a file per decision), design/; overrides/ is the site's theme and hooks
├── fixtures/sample_repo/    a small Mix project the core's workspace tests read
├── install.sh, install.ps1  install troupe and troupe-daemon from a release
├── mix.exs, mix.lock        the umbrella: the check alias, four releases, credo
├── protocol/schema/v1/      GENERATED JSON Schema (commands/, events/, index.json)
├── scripts/                 dev-up, toolbox, remote-up, build-images, release, pitr-drill, version.exs, locks-agree.exs, doc-links.exs, doc-size.exs, check-neutral.exs, decision-citations.exs, console-rig.exs, …
└── test/fixtures/logs/      recorded log fixtures, one directory per released version

Gitignored and local: .local/ (a person's own kubeconfigs and values, never committed), /.worktrees/, apps/troupe_core/priv/reaper/, and site/, what mkdocs build writes.

The root holds what somebody arriving at the repository needs, and what a tool reads from there; everything else is under a directory (Decision 739). Documents that code, CI or GitHub read where they are stay where they are, and the site shows them from there: the nav of mkdocs.yml names them by their path from the root, and docs/overrides/hooks.py puts them on the site and points their links at it.

Apps

Each has lib/, test/troupe/**/*_test.exs, test/support/ (compiled only in test) and priv/ where it ships data, and shares the root's _build, deps, mix.lock and config/. Notable locations:

Where What
apps/troupe_core/priv/agents/*.md the built-in agent definitions
apps/troupe_core/native/reaper/reaper.zig the process-tree reaper, one source for every target
apps/troupe_core/lib/mix/tasks/ compile.reaper, troupe.boundaries, troupe.fixtures.record, troupe.bench, troupe.prefix, troupe.config.schema
apps/troupe_protocol/lib/mix/tasks/ troupe.schema.gen, troupe.schema.diff, troupe.egress, troupe.release.check, troupe.decisions, compile.troupe_version
apps/troupe_plane/lib/mix/tasks/ troupe.theme, troupe.index.rebuild, troupe.ledger.reconcile
apps/troupe_plane/priv/repo/migrations/ the database
apps/troupe_plane/priv/static/ the front page's assets, mostly generated
apps/troupe_plane/lib/troupe/plane/admin/api.ex the admin method table; the plane has no administrative pages of its own, and web/admin_moved.ex sends /admin to the console (clients/gui/apps/console/)
apps/troupe_plane/lib/troupe/plane/breakglass.ex the break-glass door behind POST /auth/breakglass
apps/troupe_operator/lib/mix/tasks/troupe.e2e.ex the cluster suite
apps/troupe_gateway/test/conformance/ the Python conformance client, a test fixture
apps/troupe_daemon/ its own config/runtime.exs and README
charts/troupe/crds/ WorkerProfile, TeamVolume, TroupePolicy, Trigger, hand-written; the admission policy is a template
clients/gui/docs/design/themes/*.tokens.json the four themes: the GUI's and the TUI's, and the front page's (Signal), one copy

Generated files and what writes them: build.md §3.

What the image build sees

docker/Dockerfile copies mix.exs, mix.lock, each apps/*/mix.exs, config/ and apps/. .dockerignore removes clients/, _build, deps, priv/reaper, every test/, fixtures, docs, charts, dev, scripts and *.md — which is why theme.css is generated into the plane's priv/ rather than read from docs/.