Build Log

Aalok Onboarding — Narrated Deck & the forgekit-narrated-deck Package

July 16, 2026

Built a real onboarding book for ForgeKit's first tech partner — book-style, first-person, narrated in Zeb's own voice — and extracted the narration engine that produced it into a genuine reusable package.

OnboardingOSExtractionDocs

new packages/apps produced

narrated slides generated

chapters in the narrated deck

artifacts shipped for Aalok (deck, plain-text backup, cheat sheet)

Timeline

Start

Audit what exists for Aalok

Found docs/bick-onboarding-guide.md (wrong audience) and a dead reference to a non-existent USER_GUIDE_OS.md

Early

Wrote a technical review brief

Mechanism-first doc, evidence-led from engine-health.md, named the real weak spots (AI Route Gate theater, spin-recording drop)

Mid

Redirected to book-style + narration

Zeb wanted first-person voice, chapter structure, and floated reusing Flyback's narration capability

Mid

Investigated Flyback narration — found it wasn't reusable as-is

Two disconnected prototypes: SlideShow.jsx (no audio) and static voice-kit HTML (real TTS, but hand-authored per deck, not data-driven at runtime)

Mid

Built packages/forgekit-narrated-deck

Generic manifest -> OpenAI TTS generation (content-hash skip) -> data-driven HTML player

Late

Wrote and generated the actual deck

10 chapters, 22 slides, real OpenAI TTS audio, first-person Zeb voice

Late

Wrote the cheat sheet, then expanded it twice on request

Added engine-health-check walkthrough, Anvil Check explainer, Crucible explainer, and an honest section on how triggers actually fire (behavioral, not mechanical)

Staged only this session's files, wrote retro

Left pre-existing modified/untracked files (ignition.md, anvils.md, strikes.md, experiments/arcade/) untouched — not this session's work

What shipped

docs/aalok-onboarding-guide.md — technical review brief (plain-text backup, now points to the deck as primary)

docs/aalok/ — the narrated onboarding deck: manifest.json, index.html player, audio/*.mp3 (22 files), cheat-sheet.md

packages/forgekit-narrated-deck — new reusable package: generate-audio.mjs, build-deck.mjs, player/deck.html, README.md

forgekit-os/patterns.md — added Narrated Slide Deck Engine entry (marked LIVE) and updated Last Updated date

“The right thing to do always trumps any fear of session scope creep or time concerns.”
— Zeb, deciding to build the real forgekit-narrated-deck package rather than a one-off script