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 and the three printed layers in ADR-0062.
  • 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 panel driven by the native framebuffer renderer (ADR-0036, superseding ADR-0027). Geometry per the Canonical Hardware Specification.
  • 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 over the three printed layers (ADR-0031, ADR-0062), 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: software/programs/

Section titled “Programs: software/programs/”

The first-party applications the operator types into (ADR-0042). One spec per program, plus the surfaces the runtime owns:

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/: the cross-module catalogs, mission types and the verb taxonomy. (The single launch-titles bible, launch-titles-capability.md, was deleted in the 2026-07 corpus prune; recover it from git history. Per-title design now lives in modules/.)
  • modules/: per-module gameplay specs covering the launch titles, the launch-adjacent title, and promoted concepts. The chain matrix in modules/README.md is the register.
  • 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.
  • 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 lives under marketing/ for historical reasons. A move to a top-level docs/narrative/ remains an open information-architecture question, not a blocker on anything.

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.