Architecture Decision Records
ADRs capture the context, options considered, decision, and consequences for one architectural choice. Once accepted, an ADR is immutable — superseding changes are made by adding a new ADR and marking the prior one Superseded by ADR-NNNN.
| # | Title | Status | Scope |
|---|---|---|---|
| 0042 | First-Party On-Device Programs — the canonical thirteen | Accepted | DeckRunner content tier, nOSh runtime, NoshAPI |
| 0041 | Consolidate the product repos into a single kn-86 monorepo | Accepted (supersedes ADR-0039) | Repo topology, monorepo, build, CI |
| 0040 | DeckRunner — the named engine layer | Accepted | nOSh runtime, engine layer, player-facing FFI |
| 0039 | Repository topology — split the monorepo into seven focused repos | Superseded by ADR-0041 | Repo topology, build, packaging |
| 0038 | Power subsystem — Waveshare UPS Module 3S (3× 18650) | Accepted (supersedes TP4056 + PowerBoost + bare LiPo) | Hardware, BOM, power, primary display supply |
| 0037 | KEC Lisp — the named language standard (Fe kernel + core + stdlib + cart grammar) | Accepted | KEC Lisp, cart authoring, runtime, FFI |
| 0036 | KN-86 native framebuffer renderer (supersedes termbox2 display layer) | Accepted | Display, framebuffer, nOSh runtime, cart FFI |
| 0035 | Trackpoint cart-FFI surface — v0.1 cursor + event API | Accepted (supersedes ADR-0032 §5) | Cart FFI, input, nOSh runtime |
| 0034 | Aesthetic mode mechanism — AMBER / WHITE / GREEN phosphor schemes | Accepted | Display, nOSh runtime, deck-state persistence |
| 0033 | Reveal NoshAPI primitive — project-wide ASCII visual language | Accepted | NoshAPI, display, cart FFI, grammars |
| 0032 | Sweep peripheral commitment — 2× trackpoint + LIS3DH I²C re-pinning | Accepted (supersedes ADR-0031 §3/§6/§7) | Hardware, keyboard firmware, BOM |
| 0031 | Ferris Sweep keyboard adoption (34-key split, supersedes custom 31-key path) | Accepted | Hardware, keyboard firmware, input dispatch |
| 0030 | Runtime-tier launch baselines (System tier + TERMINAL / GRID / AUDIT / SONAR) | Accepted | nOSh runtime, Capability Registry, launch carts |
| 0029 | The Mission Runner | Accepted | nOSh runtime, mission orchestration, phase chain |
| 0028 | Mission Control & the Capability Registry | Accepted (amended 2026-05-05 per ADR-0030) | nOSh runtime, mission generation, cart format |
| 0027 | termbox2 as the primary display + input layer (spike-gated) | Accepted (display layer superseded by ADR-0036; authoring shape retained) | Display, input, nOSh runtime, cart FFI |
| 0026 | Pin Pi OS base release to Debian Trixie (13) | Accepted | System image, deployment |
| 0025 | SDL2 → SDL3 migration | Accepted | Emulator, system image, build pipeline |
| 0024 | Keyboard MCU selection — RP2040-class (Adafruit KB2040) | Accepted (§3 pin map superseded by ADR-0031) | Hardware, keyboard firmware, BOM |
| 0023 | Accelerometer integration for ambient CRT glitches (LIS3DH on keyboard MCU) | Accepted | Hardware, keyboard firmware, nOSh runtime |
| 0022 | Keyboard layout finalization (legends, shifts, multi-tap) | Accepted (§2 numpad, §4 bottom row, §7 delete binding superseded by ADR-0031) | Hardware, keyboard firmware, input dispatch |
| 0021 | Legacy Terminal mode (system-image escape hatch) | Accepted | nOSh runtime, kiosk, system image |
| 0020 | Update model across three surfaces (system image, coprocessor, cartridges) | Accepted | Deployment, coprocessor, cartridges |
| 0019 | Cartridge storage and form factor (SD-card sled) | Accepted | Hardware, BOM, cart format, capability model |
| 0018 | Custom mechanical keyboard build for 30-key input | Accepted (§3 preferred PCB path superseded by ADR-0031) | Hardware, BOM, input construction model |
| 0017 | Realtime I/O coprocessor (Pico 2 / RP2350) | Approved (cart-bus partially superseded by ADR-0019) | Hardware, Pico firmware, BOM, runtime envelope |
| 0016 | nEmacs + REPL + input model (post-CIPHER-LINE) | Approved (amended by ADR-0031 — phone-shape framing relaxed) | nEmacs, REPL, input, cart FFI, keypad layout |
| 0015 | CIPHER-LINE auxiliary OLED display | Approved | Hardware, Cipher voice, NoshAPI, Universal Deck State |
| 0014 | Display profile redesign (12×24 / 960×600) | Accepted (superseded by ADR-0027 on ratification) | Display, framebuffer, font |
| 0013 | Cartridge physical format (shell + pinout) | Superseded by ADR-0019 | Hardware, BOM, fiction |
| 0012 | Lisp handler slot table widening | Draft | Runtime, cartridge authoring |
| 0011 | Pi Zero 2 W system image update system | Draft | nOSh runtime, deployment |
| 0010 | ICE Breaker Lisp re-expression (reference) | Accepted | Reference implementation |
| 0009 | Token prediction v1 ranking model | Accepted (extended by ADR-0016) | nEmacs editor |
| 0008 | nEmacs structural editor UX | Partially superseded by ADR-0016 | On-device authoring |
| 0007 | Lisp-scripted mission FFI & contract model | Accepted | Missions, runtime |
| 0006 | Cartridge format v2.0 | Accepted (amended 2026-04-24) | Cart format, tooling |
| 0005 | NoshAPI FFI surface enumeration (54 prims) | Accepted (amended 2026-04-24) | Runtime, cartridge authoring |
| 0004 | Bytecode VM selection (Fe) | Accepted | Runtime |
| 0002 | Player-facing Lisp — REPL, nEmacs, scripted missions | Accepted (slip canceled by ADR-0016) | UX, runtime |
| 0001 | Embedded Lisp as cartridge scripting layer | Accepted & Shipped | Runtime, cartridges |
Archived
Section titled “Archived”Documents kept for history, not on the active decision path. The archived source files were removed from the repo; recover them from git history if needed.
| # | Title | Reason for archive |
|---|---|---|
| 0003 | nOSh runtime update mechanism (Pico 2) | Pico / RP2350 target dropped. Pi Zero 2 W is the sole hardware target; see ADR-0011. |
Numbering
Section titled “Numbering”ADRs are numbered monotonically. Drafts and spike outputs are assigned their final ADR number before landing on main. Numbers are never reused; an archived ADR keeps its number.