Skip to content
KN-86 Deckline

Diegetic Firmware Update UX — Design Spike

Cross-reference: tools/kn86fw/format/kn86fw.h for what a .kn86fw image is

The Fiction Angle: Recommissioning, Not Patching

Section titled “The Fiction Angle: Recommissioning, Not Patching”

A KN-86 firmware update is not an iOS modal. It is a recommissioning ceremony.

The Kinoshita Electronics Consortium built the KN-86 to carry operator identity. The deck knows its own handle, credit balance, and mission history. It has a voice — CIPHER — that evolves with every session. An update patches the nOSh runtime that owns all of this. From the fiction’s perspective, the operator is not installing software; they are submitting their deck to the Consortium for re-registration under a new runtime identity.

The deck consents. The deck may resist a corrupted image. The deck announces the result.

This framing earns its place. It is not flavor bolted onto a progress bar. It changes what every state in the flow communicates: the attention gesture is the operator’s petition to enter Consortium mode; validation is the deck reading the image against its own known-good signature; the reboot is the new runtime taking its first breath. Every UI element follows from this stance, not from “we should make the progress bar look cool.”

1. Pre-Update State: Entering Consortium Mode

Section titled “1. Pre-Update State: Entering Consortium Mode”

The update path begins with the attention gesture: SYS+LINK held for ~1.5 seconds during boot (per ADR-0011). The key combination is load-bearing fiction: LINK signals host connection; SYS signals system authority. Held together at boot, they read as “I am connecting this deck to a system above the nOSh runtime.”

The operator does not see a generic “Updater Mode” screen. They see the Consortium surface.

Main grid (80×25):

Row 0:  ─────────────────────────────────────────────────────────────────────────────
Row 1:
Row 2:  KINOSHITA ELECTRONICS CONSORTIUM
Row 3:  SERVICE REGISTRATION TERMINAL
Row 4:  ─────────────────────────────────────────────────────────────────────────────
Row 5:
Row 6:  OPERATOR:  GHOSTWIRE
Row 7:  DECK S/N:  KN86-0047
Row 8:  RUNTIME:   nOSh v2.4  ·  INSTALLED 2026-03-15
Row 9:
Row 10: CONSORTIUM LINK:  AWAITING HOST
Row 11:
Row 12:
Row 23: DROP A .KN86FW IMAGE ON THE CONSORTIUM DRIVE TO PROCEED.
Row 24: ──────────────────────────────────────────────── [SYS: CANCEL]

CIPHER-LINE (OLED, 4 rows):

Row 1:  SVC · KN86-0047 · GHOSTWIRE
Row 2:  consortium mode. awaiting.
Row 3:  ·
Row 4:  SYS: EXIT CONSORTIUM MODE

Row 10 (CONSORTIUM LINK: AWAITING HOST) updates to CONSORTIUM LINK: HOST CONNECTED once the USB-MSC volume mounts. The operator knows the cable is live without any separate system dialog.

CIPHER-LINE stays at await mode during the wait: drift-heavy, low certainty. Fragments like waiting. the link is open. or the desk is quiet. are appropriate. Silence is appropriate. The deck is patient.

2. In-Update Behavior: The Validation Sequence

Section titled “2. In-Update Behavior: The Validation Sequence”

Once the operator drops a .kn86fw image and the deck detects write completion, validation begins. This is where diegesis matters most.

The deck does not show a generic progress bar labeled “Installing…”. It reads itself aloud.

The validation pass uses real structure from kn86fw.h. The .kn86fw header has: magic bytes (KN86FWv1), firmware version, nOSh version, SHA-256 of the payload. These are not implementation details to hide — they are the deck reading an identity document. They should be visible.

Main grid during validation:

Row 0:  ─────────────────────────────────────────────────────────────────────────────
Row 2:  KINOSHITA ELECTRONICS CONSORTIUM
Row 3:  SERVICE REGISTRATION TERMINAL
Row 4:  ─────────────────────────────────────────────────────────────────────────────
Row 6:  VALIDATING REGISTRATION DOCUMENT
Row 7:
Row 8:  READING CONSORTIUM MARK ...  KN86FWv1           [OK]
Row 9:  READING TARGET RUNTIME  ...  nOSh v2.5          [OK]
Row 10: VERIFYING PAYLOAD SEAL  ...  (SHA-256 running)
Row 11:
Row 12:   ████████████████████████░░░░░░░░░░░░░░░░░░░░░░  48%
Row 13:
Row 14: OPERATOR:   GHOSTWIRE
Row 15: DECK S/N:   KN86-0047
Row 16: CURRENT:    nOSh v2.4
Row 17: INCOMING:   nOSh v2.5
Row 24: ─────────────────────────────────────────── [DO NOT REMOVE CABLE]

The progress bar at Row 12 is the SHA-256 streaming hash — it advances as firmware_validate_run() reads the payload in 8 KB chunks (the actual read loop in firmware_validate.c). This is not theater: the bar reflects real work.

CIPHER-LINE during validation:

Row 2:  reading. sector by sector.
Row 3:  payload seal. checking.

CIPHER-LINE uses observe mode with high terseness. It is not narrating for drama; it is logging. The voice heuristic applies: clipped, present-tense, under eight words. Good: seal. holding. Bad: The payload SHA-256 digest is being verified.

After SHA-256 completes cleanly, the display holds for ~1 second before flashing to the write sequence. The CIPHER-LINE fragment at that moment: verified. — one word, no coda.

3. Failure Modes: The Deck Knowing

Section titled “3. Failure Modes: The Deck Knowing”

A KN-86 that rejects a corrupted image should feel like a deck that read the image and made a decision — not like a machine that errored.

Magic mismatch (wrong file dropped):

Row 6:  VALIDATION FAILED
Row 7:  ─────────────────────────────────────────────────────────────────────────────
Row 8:  CONSORTIUM MARK NOT RECOGNIZED.
Row 9:  THIS FILE IS NOT A REGISTERED UPDATE IMAGE.
Row 10:
Row 11: EXPECTED:  KN86FWv1
Row 12: RECEIVED:  (not shown — not consortium-format)
Row 14: YOUR DECK STATE IS UNCHANGED.
Row 23: REMOVE AND RETRY WITH A .KN86FW IMAGE.
Row 24: ─────────────────────────────────────────────────────── [SYS: EXIT]

CIPHER-LINE: not consortium-format. rejected. — the deck refused, not failed. These are different things.

SHA-256 mismatch (corrupted image):

Row 6:  VALIDATION FAILED
Row 8:  PAYLOAD SEAL BROKEN.
Row 9:  THIS IMAGE WAS MODIFIED OR IS INCOMPLETE.
Row 11: EXPECTED SEAL:  [first 16 chars of expected hex]...
Row 12: RECEIVED SEAL:  [first 16 chars of actual hex]...
Row 14: YOUR DECK STATE IS UNCHANGED. NO WRITE OCCURRED.
Row 23: DO NOT USE THIS IMAGE. OBTAIN A CLEAN COPY.

CIPHER-LINE: seal broken. not this one.

Unsupported format version:

Row 8:  RUNTIME VERSION NOT SUPPORTED BY THIS DECK.
Row 9:  THIS IMAGE REQUIRES A NEWER SERVICE TERMINAL.

CIPHER-LINE: version mismatch. wrong era.

In all failure cases: the p6 saves partition is never touched (per ADR-0011). CIPHER-LINE makes this implicit — “your deck state is unchanged” on the main grid, silence or a drift fragment on CIPHER-LINE. The deck doesn’t panic. It turns the image away.

4. Success Surfacing: The New Runtime Takes Its First Breath

Section titled “4. Success Surfacing: The New Runtime Takes Its First Breath”

After successful write and tryboot reboot:

The first boot under the new nOSh runtime shows a modified boot sequence.

Row 2:  KINOSHITA ELECTRONICS CONSORTIUM
Row 3:  RE-REGISTRATION CONFIRMED
Row 4:  ─────────────────────────────────────────────────────────────────────────────
Row 6:  OPERATOR:  GHOSTWIRE
Row 7:  DECK S/N:  KN86-0047
Row 8:  RUNTIME:   nOSh v2.5  ·  REGISTERED 2026-04-26
Row 9:
Row 10: PREVIOUS:  nOSh v2.4

This is shown for ~3 seconds, then the normal nOSh boot continues to the bare-deck STATUS tab. The 60-second sentinel window (ADR-0011) runs silently in the background.

CIPHER-LINE on the first post-update boot:

Row 2:  new runtime. same operator.
Row 3:  ghostwire. still here.

This is the correct emotional register. The deck updated. The operator’s identity is continuous. CIPHER noticed.

Status bar on the bare-deck STATUS tab after update:

Row 22: RUNTIME: nOSh v2.5 | REGISTERED: 2026-04-26 | CIPHER: ONLINE

The REGISTERED date replaces UPTIME on first boot after an update. On subsequent boots it reverts to uptime. This is a one-session acknowledgment, not a permanent badge.

If the tryboot window expires without the sentinel being written (boot loop, display failure), the deck auto-reverts per ADR-0011. The reverted boot shows:

Row 8:  RUNTIME:   nOSh v2.4  ·  RE-REGISTRATION REVERTED

CIPHER-LINE: revert. previous runtime restored. No alarm, no apology. The Consortium auto-revert is a designed safety net; CIPHER treats it as routine.

5. UX Guardrails: Diegetic Does Not Mean Obscure

Section titled “5. UX Guardrails: Diegetic Does Not Mean Obscure”

Three hard rules:

  1. The operator must always know the outcome. Success, failure, and revert must each produce a clear text statement on the main grid — not just CIPHER-LINE. CIPHER supplements; the main grid decides. No state ends without the operator knowing what happened.

  2. Version is always visible. Current version, incoming version, and (after update) previous version must be shown on screen at the relevant moment. Operators need to know what they’re running. The fiction earns this: re-registration documents name the new runtime.

  3. Revert is always possible by design. ADR-0011’s tryboot auto-revert is the mechanism; this UX makes it legible. The deck explains: if the new runtime does not confirm health within 60 seconds, it will revert automatically. This is in the CONSORTIUM MODE entry screen at Row 23:

Row 23: A/B SLOTS PROTECTED. AUTO-REVERT ENABLED IF RUNTIME FAILS TO CONFIRM.

No manual “undo” button needed. The protection is structural, and the UI names it.

6. Worked Examples

Section titled “6. Worked Examples”

Example A — Clean update, veteran operator

Section titled “Example A — Clean update, veteran operator”

Operator powers on holding SYS+LINK. Consortium mode appears showing their handle (SIGNAL), deck serial, nOSh v2.4. CIPHER-LINE: consortium mode. awaiting. They plug the cable; CONSORTIUM LINK: HOST CONNECTED appears. They drag kn86-nosh-2.5.kn86fw onto the drive. Validation begins. Magic check passes. nOSh version shows v2.5 incoming. SHA-256 progress bar advances. CIPHER-LINE: reading. sector by sector. — then verified. Deck writes, reboots. First boot: RE-REGISTRATION CONFIRMED. nOSh v2.5. REGISTERED TODAY. CIPHER-LINE: new runtime. same operator.

Total time felt: under 2 minutes. One deliberate action (drop the file). Zero confirmation dialogs.

Example B — Corrupted image

Section titled “Example B — Corrupted image”

Same setup. SHA-256 fails at 100% (image was corrupted mid-download). Main grid: PAYLOAD SEAL BROKEN. NO WRITE OCCURRED. Expected and received SHA-256 prefixes displayed. CIPHER-LINE: seal broken. not this one. Operator re-downloads, retries. Deck state unchanged throughout.

Example C — Post-update boot loop

Section titled “Example C — Post-update boot loop”

New nOSh v2.5 has a display initialization bug. Device boots, display flickers, reboots again. This repeats until the tryboot window lapses. Pi firmware auto-reverts to slot A (nOSh v2.4). On next boot: RUNTIME: nOSh v2.4 · RE-REGISTRATION REVERTED. CIPHER-LINE: revert. previous runtime restored. Operator’s credits, reputation, and save state are on p6 — untouched. They lost nothing but a failed update attempt.

Implementation Notes for the Engineer

Section titled “Implementation Notes for the Engineer”

Design-only. No UART format, no partition commands, no code.

  • Consortium Mode is a separate display surface from the nOSh bare-deck UI. It runs inside the updater-image kexec environment per ADR-0011, before nOSh is exec’d.
  • CIPHER-LINE in Consortium Mode is firmware-owned, not engine-driven. The Cipher grammar engine (cipher-voice.md) is a nOSh runtime concern. During the updater kexec, a simplified renderer writes 5–8 pre-written fragment strings to the OLED at defined trigger points. Keep it simple.
  • The progress bar at Row 12 maps directly to firmware_validate_run()’s streaming 8 KB read loop. The bar advances per chunk. No additional tracking needed.
  • CONSORTIUM LINK: AWAITING HOST / HOST CONNECTED derives from USB gadget enumeration state, not nOSh API.
  • The post-update REGISTERED date on the STATUS tab is a one-session flag. Store in a firmware_update_flag in Universal Deck State; nOSh clears it after displaying once on the first clean boot.