Sprint 4 Design Pack — GWP-236

Story narrative

Three small UI polish items spotted during the GWP-226 dev overlay landing:

1. F11 is undocumented in --help. kn86-emulator/src/cli.c:109 prints "F12 = Debug overlay ESC = Quit" and stops there. The new F11 dev overlay (the cart-author-facing tab strip with KEYSTROKES / RECENCY / NOKIA / etc.) is one of the strongest cart-author affordances in the platform, and it’s only discoverable through git blame main.c. Fix: add an F11 line.
2. (wave3) implementation-phase nomenclature leaks into operator-facing strings. dev_overlay.c’s CURSOR section header surfaces position=ARGUMENT(wave3) index=N parent=.... The (wave3-default) and (wave3) suffixes are implementation-pass labels that should never appear in operator-visible UI — they’re sprint-tracking metadata, not UX. Spec Hygiene Rule 3 (when a wave changes a value, sweep stale references) catches this; the cleanup is a string edit.
3. Empty-state placeholders alternate across three idioms. KEYSTROKES uses (none yet), RECENCY uses (empty), NOKIA uses (nemacs not initialized). Three surfaces, three voices. The dev overlay is otherwise exemplary engineer-tool voice — fixing three placeholder strings closes the loop. Recommended convention: (none) for both ring-empty and pool-empty cases. (none yet) implies temporality the operator may not have signaled (the ring may legitimately stay empty during the entire session — it’s not “yet” empty, it’s just empty). (nemacs not initialized) is a reasonable special case (it’s a state, not an emptiness) but still benefits from a unified verb pattern — recommend (no nemacs session) to match the (none) family without losing the diagnostic specificity.

This is pure polish — no behavior change, no architecture, three narrow string edits + one cli line. Trivial PR. The reason it earns a design pack at all is to lock in the empty-state convention so the next eight sections aren’t a free-for-all again.

Acceptance criteria expanded (≥4 testable items with file paths)

1. kn86-emulator/src/cli.c:109 print line updated to:

   F11 = Dev overlay     F12 = PSG/FPS debug    ESC = Quit

   Spacing chosen to match the existing two-space-between-items rhythm. The exact text is the task body’s recommendation; if the cli surface uses a different spacing or color convention, match it but keep both keys present.
2. kn86-emulator/src/dev_overlay.c CURSOR section painter scrubbed of all (wave3) / (wave3-default) references. Two known sites: the position label (position=ARGUMENT(wave3)) and the bottom-of-section default-value annotation ((wave3-default)). Replace position=ARGUMENT(wave3) → position=ARGUMENT. Replace (wave3-default) → (default) or remove entirely if the surrounding context already implies “default” (TBD by the implementing engineer; both options are fine). Grep dev_overlay.c for any other wave[0-9] substrings before declaring done — there may be others.
3. kn86-emulator/src/dev_overlay.c empty-state strings unified to the (none) convention:
   • KEYSTROKES (none yet) → (none)
   • RECENCY (empty) → (none)
   • NOKIA (nemacs not initialized) → (no nemacs session) (special case: state, not emptiness, but matches the verb-pattern rhythm)
   • Any other section with an empty-state placeholder gets the same treatment in the same PR. Grep dev_overlay.c for parenthesized lowercase strings (\(none\|empty\|no\|not\)) to find them.
4. kn86-emulator/src/dev_overlay.c gains a header comment documenting the empty-state convention so the next section author follows it: /* Empty-state convention: "(none)" for ring/pool emptiness; "(no <noun> session)" for uninitialized subsystems. See GWP-236. */
5. tests/test_dev_overlay.c (if it exists; otherwise a new file) gains assertions that:
   • The KEYSTROKES section renders (none) when the keystroke ring is empty.
   • The RECENCY section renders (none) when the recency table is empty.
   • The CURSOR section header does not contain the substring wave3 for any input.
   • --help output (whatever capture mechanism the project uses for cli tests) contains both F11 and F12 substrings.
6. No behavior change. No new sections, no new dispatch logic, no new keystrokes. Just strings + one cli line.

Edge cases (≥2)

1. --help is a stable CLI surface. If kn86emu has man-page generation, packaged release notes, or any downstream consumer that parses --help output, the F11 line is an additive change — should be backward-safe but worth a quick check during implementation. (None expected at v0.1; emulator is an internal tool.)
2. The NOKIA empty-state special case. “(nemacs not initialized)” is a state string, not an emptiness string — there’s a real distinction. The recommendation (no nemacs session) preserves the diagnostic intent (operator can tell nemacs hasn’t been opened) while matching the (none) family’s rhythm. If the implementer prefers (none) flat, that’s fine too — but document the call in the PR description so the next section author has guidance.
3. (wave3) may appear in test fixtures. tests/test_dev_overlay.c may have asserted the literal string position=ARGUMENT(wave3) in earlier passes. Update the test alongside the source change — Acceptance #5 covers this implicitly but worth flagging.

Engineering hand-off notes

• Files owned: kn86-emulator/src/cli.c (additive — one line), kn86-emulator/src/dev_overlay.c (string edits + header comment).
• Files added-to: kn86-emulator/tests/test_dev_overlay.c (additive — assertions). --help test surface (whatever exists).
• Files NOT touched: any cart code, any architecture-level files. This is pure UX polish.
• Expected PR size: ~10 lines in cli.c, ~15 lines in dev_overlay.c, ~30 lines in test_dev_overlay.c. Tiny PR.
• Test strategy: TDD-light. Add failing assertions first (substring-not-present for wave3; substring-present for (none) in empty-state cases; --help contains both F11 and F12), then make them pass. The cleanup is mechanical.
• Dispatch shape: single C engineer, additive. Pairs naturally with GWP-265 (T9 ranker explain) — both touch dev_overlay/debug surfaces and could land in the same PR if Josh wants to bundle. Independent of every other Sprint 4 candidate.
• Watch for: none. This is the safest task in the batch.

Open questions

1. Bundle with GWP-265? Both touch the F11 dev overlay and could land in one PR (~30 minutes saved on review overhead). Recommendation: bundle them in a single agent dispatch but keep separate commits inside the branch so the tasks track 1:1. Confirm preference.
2. NOKIA empty-state phrasing. (no nemacs session) vs flat (none) — call before merging. Recommendation: (no nemacs session) for diagnostic specificity.