Skip to content
KN-86 Deckline

Definitive Guide

Canonical content has migrated to per-domain pages; this document is the map.

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 canonical-spec.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 → WM8960 codec → 2″ speaker / 3.5 mm stereo headphone 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:

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, the ASCII design system, screen-design rules, animation, maps, clip system.
  • design-bibles/ — launch titles under the capability model.
  • modules/ — per-module gameplay specs (17 launch + 1 launch-adjacent).
  • samples/ — reference cartridge source.

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/ — .kn86 cart 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”
  • canonical-spec.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 in adr/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.