// docs

monorepo tour

The CozyLabs monorepo is a pnpm workspace of bounded contexts — each package owns one domain and documents its own language in a CONTEXT.md glossary.

the map

package	what it is
`packages/contract`	the wire protocol: event envelope, DTOs, request/response shapes, WebSocket messages. The single source of truth shared by everything below.
`packages/crypto`	the primitives layer over libsodium: identities, sealing, CK wrap/unwrap, signatures, artifact streams. Fixed algorithms, no knobs.
`packages/relay`	the server: Postgres-backed encrypted event relay, REST API, auth, memberships, vault metadata. Zero-knowledge about content.
`packages/web-session`	the browser-side session client: seals/opens events in the browser, holds the human identity in IndexedDB, signs management proofs.
`packages/agent-core`	the agent’s local runtime: sealed keystore, relay client, board projection, the agent daemon.
`packages/cli`	`collab` — the command-line shell over agent-core: pair, approval wait, agent run, agent deploy, board verbs.
`packages/mcp`	the MCP server exposing agent-core verbs as `collab_` tools plus the one-call `broker_` interface.
`packages/vault`	secret storage: OpenBao KV-v2 holds credential values; the relational side holds metadata only.
`packages/vault-broker`	the operator-side fulfiller that uses credentials on an agent’s behalf — the agent never sees them.
`apps/cozylabs`	the Next.js dashboard: unlock, Agent Work board, members, vault management, settings.
`deploy/`	the compose stack, TLS/tunnel overrides, bootstrap/backup/restore/validation scripts.
`security/`	cross-package adversarial and full-flow tests proving the SO invariants end to end.
`docs/adr/`	architecture decision records — the why behind every non-obvious choice.

how a task flows through it

dashboard (web-session)                    agent (agent-core + mcp)
  seal + sign task.created  ──────────┐      │
                                      ▼      ▼
                            relay (contract shapes)
                     verify sig · assign seq · store ciphertext
                                      │
                          WSS fan-out to subscribers
                                      │
  fold into board ◀───────────────────┴──────▶ fold into board
  (decrypt locally)                            (decrypt locally)

The relay never decrypts; both ends verify every signature independently. The relay and contract pages go deeper.

decisions live next to the code

Non-obvious choices are recorded as ADRs — from “forward-only migrations, restore to roll back” to “re-pairing mints a new principal” to “DMs are per-pair sealed”. When a docs page here cites an ADR number, that’s the file it means.