conventions

# Repository conventions Keep behavior reusable across clients and environments. Give state, dependencies, and lifecycle explicit owners. Prefer composition and direct consumer flows over layers that send work back and forth. ## Find the relevant page Read the pages relevant to the change before editing: | When changing | Read | | ------------------------------------------------------------- | ------------------------------------------ | | Package boundaries, exports, or file organization | [Packages](references/packages.md) | | Services, host interfaces, startup, cleanup, or client access | [Services](references/services.md) | | Mutable state, streams, derived views, or operation ordering | [State](references/state.md) | | TypeScript implementation or error handling | [TypeScript](references/typescript.md) | | Tests, fixtures, or test review | [Testing](references/testing.md) | | Development hosts, environment setup, CI, or deployment | [Environments](references/environments.md) | Read multiple pages when the change crosses boundaries, not the entire handbook for every task. Testing guidance applies to Vitest and Playwright alike. Examples use simplified TypeScript adapted from real code, not complete implementations. Imports and unrelated setup are omitted; “avoid” shows the counterexample, “prefer” shows the intended shape. ## Apply it to the change at hand Apply these principles practically. Improve the changed area without turning a small task into a full migration. Do not add wrappers, packages, or tests merely to satisfy a diagram. Keep project commands and exceptions in `AGENTS.md`, and current architecture and migration progress in the implementation spec. Update that spec as work lands; do not describe planned APIs as available.