KN-86 Deckline — Definitive Articles

Last ratified: 2026-04-25 (post-reorg — paths updated to the device / software / marketing tree).

---

Purpose

This file answers one question: which documents in this repo are canonical, and which are historical?

Every file under docs/ is in exactly one of three states:

1. DEFINITIVE — listed in the tables below. The live source of truth for its domain. Agents and humans read these and trust them.
2. WORKING — dated design plans, spike notes, drafts, dispatches in progress. Lives under docs/plans/ (including docs/plans/sprints/), docs/marketing/dispatches/, or docs/software/cartridges/modules/drafts/. Graduates to DEFINITIVE (by ADR) or to archive.
3. ARCHIVED — superseded by an ADR or a newer DEFINITIVE doc. Lives under docs/_archive/<original-path> with a > **ARCHIVED:** …superseded by … banner prepended.

No document may live outside these three states. If the audit finds one, it classifies it and fixes the state.

The narrative subtree at docs/marketing/narrative/ is out of scope for this state machine — it’s creative/fiction governed by docs/marketing/narrative/CLAUDE.md and editorial review.

---

Tier 0 — Sources of truth (do not deviate)

File	What it owns
CLAUDE.md	Canonical Hardware Specification table (display, grid, font, color, processor, audio, battery, case, ship target). Agent roles. Workflow contract. Every other doc must match values in this table.
docs/adr/ADR-*.md	Every architectural decision. Supersedes any prior spec doc.
docs/adr/README.md	ADR index (chronological).

---

Tier 1 — Definitive specs

Architecture (docs/architecture/)

File	Scope
deckrunner-engine-architecture.md	DeckRunner — the engine layer. Platform / DeckRunner / Content layers; the engine that owns the run loop and contains Mission Control + Mission Runner; three-tier state model; the two FFI surfaces (NoshAPI + the player-facing DeckRunner interface); keyboard anchors + layers; capability baseline-vs-deepened; Lambda Slots. Backs ADR-0040.
kec-lisp-runtime-architecture.md	The C-substrate ← Lisp-userland inversion (L0–L3). Direction ratified by ADR-0036 (renderer) + ADR-0040 (engine layer / DeckRunner naming).
ui-design-language.md	The kn86-ui component-kit design language.

Software — Runtime (docs/software/runtime/)

File	Scope
orchestration.md	nOSh orchestration, capability model, Phase Chain. Mission Board treatment reduced to a pointer at mission-control.md per PR #30 (2026-05-03).
mission-control.md	Mission Control & the Mission Board — capability registry, schema-driven contract generation, mission board, Mission Runner handoff. Promoted from draft KN86-MCMB-001 (2026-05-03). Companion to ADR-0028 and ADR-0029.
deck-state.md	Universal Deck State schema. Extracted from the orchestration spec on 2026-04-25. cartridge_history is the Capability Registry’s persistent backing per PR #30.
cartridge-lifecycle.md	Cartridge load / unload / hot-swap lifecycle. Extracted from the orchestration spec on 2026-04-25.
phase-chain-format.md	Phase chain on-disk format and replay semantics. Companion to orchestration.md.
cipher-voice.md	CIPHER-LINE auxiliary OLED engine — event stream, memory store, five utterance modes, mode selector, coherence stack. Companion to ADR-0015. Grammar productions extracted to ../software/api-reference/grammars/cipher-line-grammar.md on 2026-04-25.
cipher-voice-style-guide.md	CIPHER voice authoring contract — voice principles, vocabulary rules, cadence/length budgets, per-launch-cart tone targets, anti-patterns, and the CI grammar-compliance merge gate spec (GWP-321). Mitigates PR-FAQ Risk #3.
bare-deck-terminal.md	nOSh runtime UI when no cartridge is loaded.
bare-deck-content-brief.md	Per-tab content design + bounty contracts (STATUS / CIPHER / LAMBDA / LINK / SYS). Gate doc for GWP-317.
repl.md	Onboard Lisp REPL — release-default first-class utility. Invocation, permanent surface advertising, per-deck history persistence, boundaries with bare deck / nEmacs / CIPHER. Companion to ADR-0002 and ADR-0016. (GWP-315.)
input-dispatch.md	34-key Ferris Sweep event model (per ADR-0031 / ADR-0032; legacy “31-key” phrasing pending sweep), hold detection, anchors + layers (ADR-0040).
key-test-utility.md	nOSh runtime SYS-mode screen (BD_MODE_SYS_KEY_TEST).
prototype-architecture.md	Pi Zero 2 W prototype software layout.
haptic-feedback.md	Haptic design (Status: Proposed).
pcm-voice-bark.md	Voice-bark audio path (Status: Proposed).

Software — Cartridges (docs/software/cartridges/)

Authoring (authoring/)

File	Scope
campaign-economy.md	Multi-phase campaigns, credits, reputation, phase chain semantics.
clip-system.md	Pre-rendered terminal animation primitive.
lisp-paradigm.md	Lisp key semantics across all 14 + 1 modules.
ui-patterns.md	Reusable screen patterns, audio-as-data.
screen-design-rules.md	Row 0 / 1–23 / 24 layout contract.
commerce-navigation-modules.md	Commerce + Navigation module patterns.
operations-modules.md	Operations module patterns.
strategy-passive-modules.md	Strategy + passive-system module patterns.

Modules (modules/)

One canonical spec per launch title (17 launch + 1 launch-adjacent). All in docs/software/cartridges/modules/ — see the directory README for the full list.

• DEFINITIVE asymmetric link-cable defender: sysop-mode.md — defender side of ICE Breaker linked play. v1.0 spec landed via GWP-323. Companion to ice-breaker.md; link-cable wire-protocol details deferred to GWP-330.

• DEFINITIVE launch-adjacent (the “+1”): threshold.md — Pacific Rim Dynamics, multiplayer text MUD.

• DEFINITIVE outside-tier: marty-glitch-broadcast-piracy.md — Setec Astronomy / Terminal Transmissions. Action item: draft an ADR formalizing Capability Model §“Outside Tier” clause (flagged, not blocking).

• Standalone Black Ledger spec: black-ledger.md is the canonical v1.0 spec; supersedes Part Two of the combined neongrid-blackledger-campaign.md. The combined file is retained as design-history for the paired-module pattern. The launch-time Corporate Espionage campaign archetype (ICE Breaker → Black Ledger) is specified in campaigns/corporate-espionage.md.

• Visual brief: marty-glitch-visual-brief.md — visual-generation seed prompt for the Marty Glitch cartridge.

• NeonGrid 45-minute first-session arc: neon-grid-onboarding-arc.md — companion to neon-grid.md; specifies the new-operator on-ramp (boot → handle → tutorial → first contract → first credit payout → handoff). Sprint 4 deliverable for product-evaluation.md.

Campaigns (campaigns/)

File	Scope
corporate-espionage.md	2-phase ICE Breaker → Black Ledger campaign archetype. Sprint-4 platform-proof multi-phase deliverable. Canonical spec for Archetype 1 of authoring/campaign-economy.md.

Operator manuals (operator-manuals/)

File	Scope
ice-breaker-manual.md	In-fiction operator + technical manual for ICE Breaker (Zaibatsu Digital Form ZD-86-IB-001, Rev A, April 2026). Companion to modules/ice-breaker.md.

Design bibles (design-bibles/)

File	Scope
launch-titles-capability.md	Launch titles under the capability model.

Software — API Reference (docs/software/api-reference/)

KEC Lisp — the language reference lives at its own site.

File	Scope
benchmarks.md	Empirical validation of ADR-0004 (Fe VM) and ADR-0001 perf budgets.

The KEC Lisp language reference, built-ins, and memory model now live at the KEC Lisp site; only benchmarks.md (Fe VM perf data) remains here.

NoshAPI (nosh-api/)

File	Scope
versioning.md	FFI versioning rules.

primitives-by-category.md is a STUB pending follow-up; canonical 54-primitive list is in adr/ADR-0005.

Grammars (grammars/)

File	Scope
character-set.md	KN-86 Code Page, CP437, Press Start 2P, Unicode path.
cartridge-format.md	.kn86 container format (Lisp source + static data; AOT bytecode deferred per ADR-0006 2026-06-14 amendment). Extracted from the runtime spec tree on 2026-04-25. Companion to ADR-0006.
cipher-line-grammar.md	CIPHER-LINE s-expression grammar productions. Extracted from ../software/runtime/cipher-voice.md on 2026-04-25. Companion to ADR-0015.
coprocessor-protocol.md	Pi ↔ Pico UART wire-format spec. Companion to ADR-0017. Cart-bus frame types obsoleted by ADR-0019; PSG + OLED + session-control remain canonical.
clip-format.md	Clip binary format.

Editor tools (editor-tools/)

../software/programs/nemacs.md is the canonical landing page for nEmacs as it ships in v1.0 (GWP-316) — capability inventory, persistence (serialize/load) contract, ADR cross-refs, and full test surface.

File	Scope
editor-tools/repl.md	Implementer-facing REPL reference — loop semantics, history walking, error handling, output formatting, Tier 3 FFI access policy. Operator-facing canonical doc lives at ../software/programs/repl.md. Companion to ADR-0002 and ADR-0016.

token-prediction.md is a STUB pending follow-up (canonical in ADR-0009).

Device — Hardware (docs/device/hardware/)

File	Scope
build-specification.md	BOM, assembly plan, electrical.
sourcing-guide.md	Component sourcing research.
processor.md	Raspberry Pi Zero 2 W primary-processor subsystem spec — Linux + nOSh runtime + HDMI + USB hub host.
primary-display.md	Elecrow 7” IPS subsystem spec — 1024×600 RGB565 native framebuffer, per-region cell density via integer-scaled 8×8 glyphs (128×75 = 1× cell ceiling), Press Start 2P + CP437, AMBER #E6A020 default with WHITE / GREEN selectable, Row 0/74 firmware vs. Rows 1–73 cartridge at 1× scale. Per ADR-0036 (superseding ADR-0027 / ADR-0014).
auxiliary-display.md	CIPHER-LINE OLED subsystem spec — SSD1322 256×64 yellow, 4-row layout, 4-wire SPI on SPI0. Per ADR-0015.
audio.md	YM2149 PSG → I2S → MAX98357A → 28 mm 8 Ω 2 W speaker. PSG synthesis lives on Pico 2 per ADR-0017.
coprocessor.md	Pi Pico 2 (RP2350) realtime I/O coprocessor — PSG + OLED only after cart-bus removal. Per ADR-0017 + ADR-0019.
cartridge-interface.md	Full-size SD card via USB mass storage, ~58 × 65 × 8 mm clamshell sled. Per ADR-0019.
keyboard.md	Ferris Sweep 34-key split + 2 trackpoints — Kailh Choc v1 hot-swap, MBK caps, 2× KB2040 (QMK), USB HID via internal hub. Per ADR-0031 / ADR-0032 (supersede the custom 31-key path); legend per ADR-0022 + the ADR-0040 anchors+layers refinement.
enclosure.md	Pelican 1170 Protector Case + 3D-printed inset panels (display bezel, CIPHER-LINE bezel, keyplate, cart-slot retainer).
power.md	Waveshare UPS Module 3S (3× 18650) + 12.6 V barrel-jack charging + rail layout (5 V/5 A main powering the whole device incl. display, plus 3.3 V domains). INA219 battery monitor; ~4–5 h display-active / ~10–12 h electronics-only envelope per ADR-0038.

Device — OS (docs/device/os/)

File	Scope
release-setup.md	Release infrastructure / CI/CD.
update-system.md	Firmware update path (per ADR-0011 + ADR-0020 multi-surface model).

system-image-build.md, boot-and-systemd.md, device-tree-overlays.md, kiosk-mode.md, power-idle.md, coprocessor-firmware.md are STUBS pending follow-up.

Research (docs/research/)

File	Scope
KN-86-DOS-Easter-Egg-Research.md	GWP-269 feasibility memo: title candidates, mode-swap architecture, seven open questions. Conclusions ratified by ADR-0021.
KN-86-DOS-Easter-Egg-bench-test-plan.md	Bench-test plan for the Legacy Terminal mode entry/exit gestures and DOSBox-on-Pi performance envelope.

Marketing (docs/marketing/)

File	Scope
marketing-plan.md	GTM strategy, positioning, channels. Refresh queued per plans/2026-04-23-marketing-plan-refresh.md.
pr-faq.md	Working-backwards launch doc (press release dated 2027-11-11 + external FAQ + internal FAQ).
product-evaluation.md	Expert assessment, priorities, 90-day sprint plan.
voice-bark-recording-guide.md	Operational how-to for the kn86bark tool. Child of software/runtime/pcm-voice-bark.md.

Reviews (docs/reviews/)

Per-module Round-1 / Round-2 evaluations remain as reference artifacts. The multi-module summary is canonical:

File	Scope
ROUND-2-SUMMARY.md	Cross-module Round-2 evaluation summary.

Top-level indices (docs/)

File	Scope
README.md	Documentation hub — top-level entry point.
definitive-guide.md	Synthesis across fiction, specification, decisions.
_meta/definitive-articles.md	This file.
_meta/reorg-2026-04-25.md	Phase-by-phase rename map for the 2026-04-25 reorg (the artifact future agents need when they trace a path that no longer exists).
future-concepts.md	Catalog-wide parking lot for KN-xx Deckline concepts. Companion skill: .claude/skills/kn86-deckline-brainstorming/.
concepts/kn-9x/	Sibling-device concept annex: kn90s-statline.md, kn90t-toneline.md, kn92-gridline.md. Forward-looking hardware variants. Relocated from docs/ top-level on 2026-04-27 per E21 resolution. Awaits ADR placement before promotion to Tier 1.

Root

File	Scope
README.md	Public-facing orientation. Must match CLAUDE.md canonical spec and ADR-0001.

---

Archive ledger

The 2026-04-21 first-run batch (16 files) was drained per Josh’s ratification. The 2026-04-25 reorg added:

• _archive/software/api-reference/grammars/cartridge-grammar-spec-v1.md — superseded by ADR-0001 (Lisp/Fe authoring).
• _archive/software/cartridges/modules/drafts/playtest-round1-{corwin,mae,vex}.md — pre-unification playtests; data folded into Round 2.
• _archive/software/cartridges/modules/drafts/MUD-Design-Round{1,2}.md — pre-ADR-0019 cartridge format; no MUD module in launch roster.
• _archive/software/cartridges/design-bibles/launch-titles-traditional.md — superseded by launch-titles-capability.md. Documented the standalone cartridge model retired in favor of the capability model on 2026-04-02; the file’s own banner self-identifies as “DESIGN ARCHAEOLOGY” and the 2026-04-25 reorg moved but did not flip its state.

Pre-existing archives (33 files) at docs/_archive/ are immutable and must not be re-archived.

---

Doc-update audit log

Date	ADRs swept	File touched	Task
2026-04-26	ADR-0001, ADR-0017, ADR-0019	docs/software/runtime/orchestration.md	GWP-261
2026-04-27	ADR-0015	docs/software/runtime/cipher-voice-style-guide.md (new)	GWP-321
2026-05-03	ADR-0028, ADR-0029, amends ADR-0005 + ADR-0006	docs/software/runtime/mission-control.md (new); orchestration.md, deck-state.md, campaign-economy.md, cipher-voice.md, repl.md, bare-deck-terminal.md, launch-titles-capability.md, definitive-guide.md harmonized	PR #30 (KN86-MCMB-001)

---

Rules of the road

1. ADRs are the narrative spine. Every supersession cites an ADR number. If a spec change doesn’t have an ADR, the audit opens a draft and flags it.
2. Every DEFINITIVE doc must match CLAUDE.md’s Canonical Hardware Specification. Any drifted value is corrected in place by the audit.
3. WORKING docs are dated (YYYY-MM-DD-*.md) when they land in docs/plans/. Undated WIP in DEFINITIVE folders is a smell.
4. No file lives in docs/_archive/ without a supersession banner. The banner format is fixed — see audit playbook.
5. Archived paths collide? If docs/_archive/<path> already exists, append -retired-N.md to the new archive.
6. Filenames forbid make/model tokens outside _archive/ and marketing/narrative/ — see audit playbook §4g.