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/ or docs/marketing/dispatches/. Graduates to DEFINITIVE (by ADR) or to archive.
3. ARCHIVED — superseded by an ADR or a newer DEFINITIVE doc.

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
docs/device/hardware/canonical-spec.md	Canonical Hardware Specification table (display, grid, font, color, processor, audio, battery, case, ship target). Every other doc must match values in this table.
CLAUDE.md	Agent roles. Workflow contract. Points at the canonical spec — holds no spec values itself.
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).
aethernet.md	The world model gameplay commits to: AetherNet, visibility as the resource, the ICE classes, the canon-to-mechanism map, and each cartridge’s narrative contribution. Bridges the worldbook to the runtime.
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
clip-system.md	Pre-rendered terminal animation primitive.
lisp-paradigm.md	Lisp key semantics across the module library.
ascii-design-system.md	The composition vocabulary every visual surface draws from: slots, house kits, data displays.
screen-design-rules.md	The row contract: Row 0 and Row 74 are firmware-owned, carts draw Rows 1 through 73.
animation.md	The two sanctioned animation styles and the named motion library (ADR-0052).
maps.md	Tile maps: terrain glyphs, the .map model, fine-scroll viewport.
roguelike-design.md	Designing a roguelike or roguelite cart.
music.md	PSG-only ambient music and SFX coexistence.

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.

• 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.

Design bibles (design-bibles/)

File	Scope
verb-taxonomy-map.md	The 17-cart roster and which Tier-2 verb taxonomy each contributes.
mission-type-catalog.md	Player-facing mission types mapped onto the closed Tier-3 verb set.

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 auxiliary surface, 4-row layout, canonical Pico-driven SPI path per ADR-0015 / ADR-0017, with GWP-619 8080 bench note pending reconciliation.
audio.md	YM2149 PSG → I2S → WM8960 codec → Gikfun 2″ 4 Ω 5 W speaker + 3.5 mm stereo headphone jack. PSG synthesis lives on Pico 2 per ADR-0017; codec/speaker/jack per ADR-0054.
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.
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.

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/prose-rules.md	Prose authority for the docs tree: agency, person, punctuation, banned words and frames, and the pre-PR check. Local override of the agent-level ~/.agents/writing-rules.md.
_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 the canonical spec and ADR-0001.

---

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 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. Filenames forbid make/model tokens outside marketing/narrative/ — see audit playbook §4g.