This file is the rename map artifact for the docs reorganization landed on 2026-04-25. Future agents tracing a path that no longer exists should consult this file.
The reorg restructured docs/ around device / software / marketing (per Josh’s direction), removed make/model names from filenames, hoisted ADRs to top-level adr/, separated design from API reference, and added README hubs to every domain.
Phases (commits on claude/elastic-colden-041e8e):
39f595f — bulk git mv (134 renames, history preserved)599d239 — link rewrites + archive banners + _meta/build/compile.py manifest update79c9040 — README hubs (18) + stub files for new gaps (13)- (this commit) — CLAUDE.md Key Documents table + audit playbook + this file +
_meta/definitive-articles.md
| Removed top-level dir | What happened to its contents |
|---|
docs/architecture/ | ADRs hoisted to docs/adr/; rest dispersed into docs/software/runtime/, docs/software/cartridges/authoring/, docs/software/api-reference/. |
docs/architecture/adr/ | → docs/adr/. ADR-0011 slug renamed (pi-zero → device). |
docs/architecture/spikes/ | kn86clip-format-spec.md → docs/software/api-reference/grammars/clip-format.md. icebreaker.lsp → docs/software/cartridges/samples/icebreaker.lsp. |
docs/hardware/ | → docs/device/hardware/. |
docs/ui-design/ | Split between docs/software/runtime/ (input dispatch, bare-deck terminal, key-test utility) and docs/software/cartridges/authoring/ (UI patterns, screen-design rules). Marty Glitch visual prompt → docs/software/cartridges/modules/marty-glitch-visual-brief.md. |
docs/game-design/ | Module specs → docs/software/cartridges/authoring/; launch-titles design bibles → docs/software/cartridges/design-bibles/. |
docs/gameplay-specs/ | → docs/software/cartridges/modules/ (lowercase-kebab filenames). Drafts: Round-1 playtests + MUD designs archived; Round-2 playtests retained at docs/software/cartridges/modules/drafts/. |
docs/guides/ | ICE Breaker manual → docs/software/cartridges/operator-manuals/; Voice-bark recording guide → docs/marketing/voice-bark-recording-guide.md. |
docs/business/ | PR-FAQ + Product Evaluation → docs/marketing/; dispatches → docs/marketing/dispatches/. |
docs/writing/ | → docs/marketing/narrative/. Subtree preserved (synopses, stories, changelogs, build, skills). |
docs/ops/ | → docs/device/os/. |
docs/build/ | → docs/_meta/build/. |
| New top-level dir | What’s there |
|---|
docs/device/ | Hardware (BOM/sourcing/mechanical/electrical) + OS (system image, kiosk, systemd, coprocessor firmware, update path). |
docs/software/ | Runtime (nOSh) + cartridges (authoring + per-module + operator manuals + design bibles + samples) + API reference (KEC Lisp, NoshAPI, grammars, editor tools). |
docs/adr/ | All 19 ADRs hoisted out of architecture/adr/. |
docs/_meta/ | The doc system itself: definitive-articles index, this rename map, build artifacts. |
| Old path | New path |
|---|
docs/KN-86-Definitive-Guide.md | docs/definitive-guide.md |
docs/KN-86-Platform-Design-Master-Index.md | Moved temporarily to docs/_meta/platform-design-master-index.md as a transition aid, then deleted per follow-up #7 below. The navigation surface is now docs/README.md + docs/definitive-guide.md + per-domain READMEs. |
docs/KN-Deckline-Future-Concepts.md | docs/future-concepts.md |
docs/DEFINITIVE-ARTICLES.md | docs/_meta/definitive-articles.md |
docs/KN-86-Marketing-Deck.pptx | docs/marketing/marketing-deck.pptx |
docs/KN-86-Product-Spec-1-Pager.pdf | docs/marketing/product-spec-one-pager.pdf |
docs/KN-86-Product-Spec-6-Pager.pdf | docs/marketing/product-spec-six-pager.pdf |
docs/KN-86_Deckline_Spec.pdf | docs/marketing/deckline-spec.pdf |
docs/KN-86-Shopping-List.xlsx | docs/device/hardware/shopping-list.xlsx |
All docs/architecture/adr/ADR-*.md → docs/adr/ADR-*.md. The only slug rename:
| Old slug | New slug |
|---|
ADR-0011-pi-zero-firmware-update-system.md | ADR-0011-device-firmware-update-system.md |
Plus README.md and _TEMPLATE.md moved with them.
All docs/gameplay-specs/KN-86-*-Gameplay-Spec.md → docs/software/cartridges/modules/<slug>.md. Filename pattern: lowercase-kebab, drop KN-86- and -Gameplay-Spec suffix. Examples:
…and the remaining 9 (depthcharge, drift, nodespace, null, pathfinder, relay, shellfire, takezo, threshold) follow the same pattern.
| Old path | New path |
|---|
docs/gameplay-specs/drafts/playtest-round1-{corwin,mae,vex}.md | ARCHIVED → docs/_archive/software/cartridges/modules/drafts/ |
docs/gameplay-specs/drafts/MUD-Design-Round{1,2}.md | ARCHIVED → docs/_archive/software/cartridges/modules/drafts/ |
docs/gameplay-specs/drafts/playtest-round2-{corwin,mae,vex}.md | docs/software/cartridges/modules/drafts/ (retained — pending Josh’s call on whether to archive) |
Whole subtree moved with structure preserved:
docs/writing/CLAUDE.md → docs/marketing/narrative/CLAUDE.md (editorial governance)docs/writing/README.md → docs/marketing/narrative/README.mddocs/writing/*-Synopsis.md → docs/marketing/narrative/synopses/docs/writing/*-v3.md (story drafts) → docs/marketing/narrative/stories/docs/writing/changelogs/* → docs/marketing/narrative/changelogs/docs/writing/build/amber-circuit/* → docs/marketing/narrative/build/amber-circuit/docs/writing/skills/short-story-writing/SKILL.md → docs/marketing/narrative/skills/short-story-writing/SKILL.mddocs/writing/KN86_AMBER_CIRCUIT-*.png → docs/marketing/narrative/stories/
docs/build/* → docs/_meta/build/. The compile.py manifest and ROOT path were also updated to reflect the new depth.
docs/plans/ — kept at the top level (working dated artifacts).docs/reviews/ — kept at the top level (design-history evals).docs/_archive/ — pre-existing 33 archived files unchanged.
- Filenames are
lowercase-kebab.md. KN-86- prefix dropped from every active file.
- Folders are function-named, not make/model-named.
- Banned tokens in filenames (outside
_archive/ and marketing/narrative/): pi-zero, pico, rp2350, ssd1322, elecrow, pelican, max98357, ym2149, kailh, choc, mbk. Audit playbook §4g enforces.
- ADR slugs reviewed; only ADR-0011 carried a banned token (
pi-zero → device). Other ADR slugs passed inspection.
All 10 items have been resolved. Status as of the docs-reorg-followups branch:
- ✅ Fill device/os/ stubs — done. All 6 files (
system-image-build.md, boot-and-systemd.md, device-tree-overlays.md, kiosk-mode.md, power-idle.md, coprocessor-firmware.md) populated with platform-engineering content grounded in CLAUDE.md + ADR-0011 / ADR-0015 / ADR-0017 / ADR-0018 / ADR-0019. Bring-up TBDs are flagged inline.
- ✅ Fill api-reference stubs — done. All 7 files (
fe-lisp/{language-reference,builtins,memory-model}.md, nosh-api/primitives-by-category.md, editor-tools/{nemacs,repl,token-prediction}.md) populated from the named ADRs + relevant runtime docs.
- ✅ Capability Model split — done.
software/runtime/deck-state.md and software/runtime/cartridge-lifecycle.md extracted; orchestration.md reduced to the orchestration loop / mission board / phase chain / capability curve / Cipher integration.
- ✅ CIPHER-LINE design vs grammar split — done. Wire grammar extracted to
software/api-reference/grammars/cipher-line-grammar.md; runtime/cipher-voice.md §7 reduced to a summary + pointer.
- ✅ Cartridge format spec — done.
.kn86 container format extracted to software/api-reference/grammars/cartridge-format.md. ADR-0006 untouched.
- ✅ kn86-docs sync update — done in companion repo via Kinoshita-Electronics-Consortium/kn86-docs#5 (merged).
- ✅ Retire
_meta/platform-design-master-index.md — done. README.md hub + definitive-guide.md synthesis + per-domain READMEs cover the navigation surface; the 513-line legacy doc is deleted.
- ✅ Body-text sweep — done. 68 files updated (261 substitutions, balanced) to swap old paths/filenames for the new tree. ADRs and plans/ skipped (immutable historical snapshots).
- ✅ compile.py output renaming — done. Compendium artifacts renamed
KN-86-Deckline-Design-Compendium.{pdf,epub} → deckline-design-compendium.{pdf,epub}. The metadata.yaml book TITLE is unchanged (brand name appropriate on the deliverable cover).
- ✅ Pre-existing broken links — done.
interaction-plan.md sibling refs updated to date-prefixed names; marketing/narrative/README.md rewritten as a narrative-focused hub.
The docs accuracy audit’s next twice-daily run should report a clean sweep against the new tree. The remaining backlog (post-this-PR) is genuine new design / spec work, not reorg debt:
- Per-component hardware subfiles (display, keyboard, enclosure, audio, coprocessor board, cartridge interface, power) noted as planned follow-ups in
device/hardware/README.md.
- Cart-grammar arena scope clarification (ADR-0016 KU#5) — touches both
editor-tools/token-prediction.md and runtime/cipher-voice.md if it lands.
- Bring-up TBDs in
device/os/ (pi-gen tag pin, Pico GPIO assignments, hub IC selection, Stage 1c power measurements, etc.) — naturally close as bring-up progresses.
- Plan:
.claude/plans/already-super-pissed-off-calm-newt.md (working plan in the parent tree at the time of the reorg; since removed — phase commits preserve the history).
- Audit playbook:
prompts/docs-accuracy-audit.md
- Corpus state machine:
_meta/definitive-articles.md
- Original reorg PR: jschairb/kn86-deckline#95 (merged) — the 4-commit phase reorg.
- Companion kn86-docs PR: Kinoshita-Electronics-Consortium/kn86-docs#5 (merged) — the engineer-facing site sync.
- Phase 1 commit:
git show 39f595f (the 134 renames)
- Phase 2 commit:
git show 599d239 (link rewrites + archive banners + compile.py)
- Phase 3 commit:
git show 79c9040 (READMEs + stubs)