Architecture Decision Records

Architecture Decision Records (ADRs) document significant design choices — what was decided, why, what alternatives were considered, and what the trade-offs are.

Active ADRs

• ADR-001: Single-crate vs Cargo workspace — why jackin❯ started as a single crate, the threshold that triggered workspace adoption, and the current workspace structure.
• ADR-002: Latest stable Rust toolchain policy — how the only supported toolchain is pinned via rust-toolchain.toml and advanced with stable Rust releases.
• ADR-003: Ratatui as the TUI rendering library — why ratatui over tui-rs, raw ANSI, or cursive, and how it is used across all three TUI surfaces.
• ADR-004: Capsule pane-body rendering mechanism — why the capsule renders pane bodies through a custom cell widget rather than tui-term.
• ADR-005: Capsule single render path — why every capsule frame is one Terminal::draw written by one ClientWriter inside ?2026 brackets, and how derived rendering replaced the repaint tiers.
• ADR-006: EditorState owns concrete workspace config — why the editor state concretizes workspace config while keeping the remaining generic test seams.
• ADR-007: Container backend lifecycle trait — why persisted instance lifecycle commands dispatch through a backend trait while launch remains backend-specific.
• ADR-008: Launch never reconnects to a live instance — why launch creates or restores dead instances but never silently attaches to a healthy live one.
• ADR-009: Role hooks are the role author's domain — why role hooks run exactly as authored and startup-speed policy stays in role documentation.
• ADR-010: Cleanup requires explicit operator approval — why dirty or unpushed isolated work is preserved unless the operator explicitly deletes or discards it.
• ADR-011: Native macOS agent-usage menu bar — Rust owns probes/views via UniFFI; Swift is display-only; host credential roots and hard Agent::ALL / UsageSurface scope.