Build Log

The ForgeKit OS History Deck — and a Real Full-Screen Narrated-Deck Player

July 18, 2026

Built a sourced, chronological narrated slideshow of ForgeKit OS's own evolution, and rebuilt forgekit-narrated-deck's player from a scrolling document into a real full-screen slideshow with chapter-level image inheritance along the way.

OSDocsExtractionNarrated Deck

narrated slides across 12 chapters

generated chapter motif images

real bugs found and fixed in the player

package.json/README/player changes to forgekit-narrated-deck

Timeline

Start

Charge received: tell ForgeKit OS's own history

Explicitly product-free — the origin story of the engine, not Forge/Leashline/Known

Early

Mined real sources before drafting anything

git log, anvils.md, strikes.md, engine-health.md, patterns.md — every claim in the deck traces to one of these

Early

Drafted content twice, reviewed both times before building

v1 thematic draft, then restructured to strict chronological order per Zeb's feedback, before any generation ran

Mid

Extended forgekit-narrated-deck to support images

Optional per-slide image field, generate-images.mjs script, proven non-regressive against Aalok's existing deck

Mid

Generated 45 narration audio files and 10 chapter images

OpenAI TTS + OpenAI images, sourcing the API key via node --env-file (never read directly)

Mid

Rebuilt the player as a full-screen slideshow

Zeb: 'it scrolls down, it should be a full page slideshow like Flyback' — adapted Flyback's absolute-position/crossfade mechanics

Mid

Debugged a real, hard-to-find rendering bug

Images silently not requesting at all — traced through console (clean), Network tab (zero image requests), and finally a real headless Chromium probe that caught a quote-collision in a template literal

Late

Fixed a second real gap: only 12 of 45 slides had images

Moved image/imagePrompt from slide-level to chapter-level with inheritance, so every slide in a chapter shares one consistent background

Removed superseded draft docs, staged specific files, wrote retro

37MB of generated audio/images committed by Zeb's explicit choice — self-contained deck, no separate hosting step

What shipped

docs/forgekit-os-history/deck/ — the finished, self-contained narrated deck: manifest.json, index.html player, 45 audio files, 12 images (10 generated + 2 real ForgeKit brand assets)

packages/forgekit-narrated-deck/player/deck.html — rewritten from a scrolling document into a full-screen slideshow (Flyback-style: absolute-position slides, opacity crossfade, chapter nav pills, auto-advance play)

packages/forgekit-narrated-deck/scripts/generate-images.mjs — new script, OpenAI images API, content-hash skip, mirrors generate-audio.mjs's pattern

packages/forgekit-narrated-deck/scripts/build-deck.mjs — updated to copy images/ alongside audio/

packages/forgekit-narrated-deck/README.md — documents chapter-level vs slide-level image inheritance and the full-screen player behavior

docs/aalok/ — rebuilt (not content-changed) under the new player to stay current with the package's own default

“still no images displaying”
— Zeb, after the first fix attempt, prompting a switch from guessing to real headless-browser verification