Definitive Guide
The KN-86 Deckline is a fictional 1988 cyberpunk handheld terminal, reconstructed in 2026 as a real prototype + desktop emulator. This guide is the entry point — a brief map of what the platform is and where the canonical documentation lives for each part.
For canonical hardware values (the only source of truth), see CLAUDE.md. For decisions, see docs/adr/. For everything else, follow the three pillars below.
Device
Section titled “Device”The physical KN-86 — atoms, traces, foam, and the Linux system image that runs on top of them.
device/hardware/
Section titled “device/hardware/”Per-component hardware specs. One page per subsystem:
- Audio — YM2149 PSG → I2S → MAX98357A → speaker / 3.5 mm jack.
- Auxiliary Display — CIPHER-LINE 3.12” SSD1322 OLED, 256×64 yellow.
- Build Specification — system-level topology + assembly plan.
- Cartridge Interface — full-size SD card in custom clamshell sled, USB-MSC bridge IC behind the slot.
- Coprocessor — Pi Pico 2 (RP2350) realtime I/O for audio + auxiliary display.
- Enclosure — Pelican 1170 hardcase + 3D-printed inset panels (no shell modification).
- Keyboard — Ferris Sweep 34-key split (David Barr design via holykeebs Soldered kit), TRRS bridge, 2× KB2040, QMK-flashed. Context-sensitive TERM on right outer thumb. See ADR-0031.
- Power — Waveshare UPS Module 3S on 3× 18650, 12.6 V barrel-jack charge → 5 V/5 A rail powering the whole device incl. the 7” display; INA219 battery monitor (ADR-0038).
- Primary Display — Elecrow 7” IPS, 1024×600 panel rendering a 128×75 amber monochrome grid (native 8×8 cells, ADR-0027).
- Primary Processor — Raspberry Pi Zero 2 W.
- Sourcing Guide — bill of materials, suppliers, lead times, supply risk.
device/os/
Section titled “device/os/”The Linux system image and how it’s built, deployed, and updated:
- Boot and systemd — kiosk-grade boot, service supervision.
- Coprocessor Firmware — Pico 2 firmware build + flash flow.
- Device Tree Overlays — SPI / I2S / GPIO config for displays and audio.
- Kiosk Mode — auto-login, read-only root, hardened runtime.
- Power Idle — soft-idle backlight dim + audio pause + render-rate drop.
- Release Setup — emulator binary release pipeline.
- System Image Build — pi-gen-based image construction.
- Update System — A/B-partitioned firmware update model.
Software
Section titled “Software”The code that runs on the device. Three layers: the runtime that owns orchestration, the user-facing programs the operator types into, and the cartridges the operator slots in.
Runtime — software/runtime/
Section titled “Runtime — software/runtime/”DeckRunner — the engine tier of nOSh — running on the Pi. (The Platform floor drives the hardware and owns the clock; DeckRunner owns the run loop, the apps, and contains Mission Control + Mission Runner. See DeckRunner architecture and ADR-0040.)
- Orchestration — capability model, phase chain, Universal Deck State, the run loop. Primary architecture doc (the engine tier is now named DeckRunner, ADR-0040).
- Mission Control — Capability Registry, schema-driven contract generation, TTL/decay, the Mission Runner handoff. Owns the mission board.
- Deck State — the persistent operator profile (handle, credits, reputation, cartridge history).
- Cipher Voice — generative voice on the auxiliary display; events, modes, coherence, grammar.
- Cartridge Lifecycle — hot-swap detection, cart-load + unload, state preservation.
- Input Dispatch — 34-key event model (see ADR-0031; legacy doc references “31-key” pending sweep), hold detection, multi-tap, context-polymorphic dispatch.
- Prototype Architecture — how the desktop emulator and the prototype share one codebase.
- Plus runtime ancillaries: PCM voice bark, haptic feedback, key test utility.
Programs — user-facing applications
Section titled “Programs — user-facing applications”What the operator actually types into. These ride on top of the runtime; specs cross several files:
- Bare Deck Terminal — the home surface when no cartridge is loaded.
- REPL — Lisp prompt for interactive evaluation. See ADR-0002, ADR-0007, and ADR-0016.
- nEmacs — structural Lisp editor. See ADR-0008, ADR-0009, and ADR-0016.
Cartridges (capability modules) — software/cartridges/
Section titled “Cartridges (capability modules) — software/cartridges/”Interchangeable capability modules. A cartridge carries program code (KEC Lisp), capability registration metadata, contract schemas (defcontract-schema forms consumed by Mission Control), behavior tables, vocabulary, and per-cart save data:
authoring/— how to write a cartridge. Lisp paradigm, screen-design rules, UI patterns, campaign + economy spec, clip system.design-bibles/— launch titles under the capability model.modules/— per-module gameplay specs (17 launch + 1 launch-adjacent).samples/— reference cartridge source.operator-manuals/— in-fiction operator-facing manuals.
API reference — software/api-reference/
Section titled “API reference — software/api-reference/”Technical reference for cartridge authors:
- KEC Lisp — the KEC Lisp language reference (its own site).
nosh-api/— NoshAPI FFI surface + versioning contract.grammars/—.kn86cart format, character set, CIPHER-LINE grammar, coprocessor protocol.editor-tools/— nEmacs and REPL authoring surfaces.
Narrative
Section titled “Narrative”The fiction the device sits inside. Kinoshita Electronics, the 1988 setting, the Cipher voice’s character, the in-fiction publishers, and operator stories.
marketing/narrative/ ¹
Section titled “marketing/narrative/ ¹”- Worldbook — universe canon: corporations, places, factions, technology, history. (Pending consolidation; canon currently lives across stories, synopses, and build.)
- Stories — first-person dispatches and short fiction set in the KN-86 world.
- Synopses — story summaries for fast lookup.
- Skills — Claude skills authored against this universe (book / dispatch / changelog generation).
- Build — narrative compendium build pipeline.
- Changelogs — in-fiction changelog dispatches.
¹ Narrative content currently lives under marketing/ for historical reasons. Promoting it to a top-level docs/narrative/ is queued; no IA move is blocking this PR.
Cross-cutting
Section titled “Cross-cutting”CLAUDE.md— Canonical Hardware Specification. The only source of truth for hardware values; never restate them downstream.docs/README.md— top-level documentation hub with the full per-section index.docs/adr/— every architectural decision (chronological inadr/README.md).docs/future-concepts.md— KN-xx Deckline catalog parking lot for future ideas.
This guide is intentionally short — a frontmatter index. Deep dives live in the linked subdirectories. If a doc is missing or stale, fix the linked source rather than letting this index drift.