Architecture Decision Records (ADRs)

Status: Open — Phase 1, no confirmation needed (requires Developer Reference setup first)

Problem

No ADR directory exists. Design context lives only in PR descriptions (not committed) and tool-specific spec files (not browsable). Three foundational decisions need documentation so future contributors (human and AI) understand why the current architecture exists.

Three priority ADRs

ADR-001: Single-crate vs workspace docs/src/content/docs/internal/decisions/001-single-crate.mdx Decision: stay single-crate while LOC < 150K and no external library consumers. Evidence: starship and fd-find stay single-crate at similar/larger scale. Trigger for workspace: LOC > 150K, or jackin-core types needed by external tooling.

ADR-002: Rust 1.95.0 toolchain + 1.94 MSRV docs/src/content/docs/internal/decisions/002-toolchain.mdx Decision: pin to 1.95.0 in mise.toml and CI; declare 1.94 as MSRV in Cargo.toml. Documents the dtolnay/rust-toolchain SHA encoding convention and edition = "2024" floor (≥ 1.85).

ADR-003: ratatui selection docs/src/content/docs/internal/decisions/003-ratatui.mdx Decision: use ratatui for all TUI rendering. Documents the tui-rs → ratatui fork history, why ratatui is the correct successor (actively maintained, tui-rs abandoned), and the version currently in use.

ADR frontmatter format

---
title: "ADR-NNN: Title"
status: accepted   # proposed | accepted | superseded | deprecated
date: YYYY-MM-DD
---

Steps

1. Ensure Developer Reference setup is done (directory exists).
2. Create the three ADR MDX files with Context, Decision, and Consequences sections.
3. Keep each ADR to 1–2 pages — decisions, not dissertations.