This directory holds long-form contributor and maintainer guides. TERAX.md at the repo root is the living architecture doc and the source of truth; these guides elaborate on specific areas without duplicating it.
If a guide conflicts with TERAX.md, TERAX.md wins.
- TERAX.md - the architecture source of truth; read this first
- CONTRIBUTING.md - how to contribute, quality bar, project layout
- Two-process model and IPC command reference - Rust owns all OS access; the webview talks through
invoke(). Command catalog and how to add a new command. - PTY shell integration - PTY sessions, shell init scripts, OSC 7 / 133, ConPTY, SPAWN_LOCK, Job Object, WSL.
- Security model - deny-list, SSRF guard, workspace authorization, AI tool approval, IPC allowlist, OSC trust, keychain handling.
- AI subsystem - providers, agent, sub-agents, sessions, composer, tools, edit diffs, live context bridge. Includes a walkthrough for adding a new provider.
- Terminal renderer pool - slot pooling, the DormantRing, and the never-serialize-mid-command invariant.
- Testing - the testing contract, how to run checks, and what makes a good core-subsystem test.