# Design documents

These documents explain the implementation and its contracts for contributors
and reviewers. They describe current behavior; earlier proposals and review
rounds are in the Git history. To use marsh, read the [manual](https://runmar.sh/docs/index.md).

Read in order:

1. [Local product contract](https://github.com/mcavage/marsh/blob/main/docs/plan/local-product-contract.md): the
   user-visible contract
2. [Architecture](https://runmar.sh/docs/architecture.md): crates, data flow, trust boundaries
3. [TLA+ model](https://github.com/mcavage/marsh/blob/main/docs/model/README.md): cross-component state, invariants, and
   where each action lives in the code
4. [Acceptance contract](https://github.com/mcavage/marsh/blob/main/tests/acceptance/CONTRACT.md): black-box
   observations a release must pass

By topic:

| Document | Subject |
|---|---|
| [processes.md](https://runmar.sh/docs/design/processes.md) | Nested jobs: lineage, admission, the job capability socket ([acceptance](https://runmar.sh/docs/design/processes-acceptance.md)) |
| [workspaces.md](https://runmar.sh/docs/design/workspaces.md) | Daemon-owned splits and forks ([acceptance](https://runmar.sh/docs/design/workspaces-acceptance.md)) |
| [stock-sbx-adapter.md](https://runmar.sh/docs/design/stock-sbx-adapter.md) | The only boundary to `sbx`: ownership map, mounts, workers |
| [shell-attachments.md](https://runmar.sh/docs/design/shell-attachments.md) | Attaching a shell, interruption, cleanup evidence |
| [command-registry.md](https://runmar.sh/docs/design/command-registry.md) | Command-to-Kit mappings and their rules |
| [results.md](https://runmar.sh/docs/design/results.md) | Job records behind `marsh results`, and scope configuration |
| [bash-compatibility.md](https://runmar.sh/docs/design/bash-compatibility.md) | Known Bash differences and the differential tests |
| [mcp.md](https://runmar.sh/docs/design/mcp.md) | The host MCP server and published-command export ([test contract](https://github.com/mcavage/marsh/blob/main/tests/mcp/CONTRACT.md)) |
| [ACP acceptance](https://github.com/mcavage/marsh/blob/main/tests/acceptance/ACP.md) | ACP sessions and their publication |
| [kit-publication.md](https://runmar.sh/docs/design/kit-publication.md) | Building and publishing Kits |
| [supply-chain.md](https://runmar.sh/docs/design/supply-chain.md) | Build inputs, published images, notices |
| [self-development.md](https://runmar.sh/docs/design/self-development.md) | `marsh --dev` and the dev broker |
| [Brush patch record](https://github.com/mcavage/marsh/blob/main/docs/upstream/brush/README.md) | The upstream Brush revision and marsh's patch queue |

Plans: [bring your own agent Kit](https://github.com/mcavage/marsh/blob/main/docs/plan/custom-agent-kit.md).