walkabout

Walkabout

Your app demos itself.

Walkabout is a pattern (not a library) for giving any web app three connected capabilities:

1. A guided voice tour — a floating guide card walks the real app page by page with AI voice narration. The spotlight scrolls to each section as the voice reaches it, auto-advance makes it hands-free, and the user can wander off mid-step (the guide politely pauses and waits). ~250 owned lines of React; no tour library.
2. An ask-the-app AI guide — the same corner button hosts a question box answered by an LLM grounded in a hand-written app guide. Every question is logged: what users ask is your roadmap.
3. One-command demo videos — headless recorders turn the tour (or any scripted click-path) into narrated MP4s. Change the app, re-run the script, get a fresh video. Stale demos become a choice.

Born on FieldProof (Jezweb, 2026) because the founder didn't want to give demos anymore. Now the app gives them.

Why no tour library?

Tour libraries fight your router and your styles, and none of them do the thing that matters: voice synced to a moving spotlight. The trick that makes Walkabout work is that nothing is hand-timed — narration is generated through ElevenLabs' with-timestamps endpoint, so the exact second each sentence starts is known. The spotlight moves on the audio's own clock (ontimeupdate), demo-video actions fire at narration offsets, and re-recording the voice regenerates every timing. Sync is correct by construction, not by validation.

What's in this repo

Path	What
templates/Tour.tsx	The tour component: navigate → narrate → moving spotlight → auto-advance, pause-on-wander, keyboard, ?tour=N deep links
templates/steps.ts	Steps config + localStorage helpers
templates/halo.css	The spotlight halo (3 rules, incl. reduced-motion)
templates/gen-tour-audio.py	Segmented scripts → ElevenLabs with-timestamps → MP3s + generated cue timings
templates/record-tour.mjs	Tour → narrated MP4, fully headless (lossless CDP screencast + ffmpeg muxes the source MP3s at measured offsets)
templates/record-demo.mjs	Scripted feature demos: {say, do} segments — the harness types/clicks on narration cue
templates/Assist.tsx + assist-routes.ts + assist-knowledge.ts + questions.sql	The ask-the-app guide: widget, endpoint, app-guide content, question log schema
skills/walkabout/SKILL.md	A Claude Code skill that walks an AI agent through adopting the whole pattern
docs/pattern.md	The deep reference: design rationale and every gotcha earned in production
.claude-plugin/	Plugin + marketplace manifests so this repo installs via /plugin

The templates are real production files, not scaffolds — copy them into your app and adapt names, styling, and the auth bootstrap. The gotchas in docs/pattern.md are the hard-won part: the React effect-dependency trap that replays audio on every click, the z-index war with Leaflet, why getDisplayMedia tab-capture is the wrong way to record, and a dozen more.

Prerequisites

• An ElevenLabs API key (ELEVENLABS_API_KEY)
• For videos: Node, Playwright, ffmpeg/ffprobe
• Seeded demo data that looks good on camera

The three content tiers

One engine, three script lengths:

Tier	Length	Audience
Quick highlights	30–45s	socials, home page
Promo tour	2–3 min	first-time users, prospects
Training demos	30–60s each	users learning a feature

Using with Claude Code

Install it as a plugin (recommended) — this repo is its own marketplace:

/plugin marketplace add jezweb/walkabout
/plugin install walkabout@walkabout

Then ask Claude Code to "add a walkabout to this app" (or run /walkabout:walkabout). The skill carries the build order, the verification gates ("test by wandering, not by watching"), and the traps; templates/ and docs/pattern.md ride along in the plugin.

Prefer a manual skill install? Copy the skill folder instead:

cp -R skills/walkabout ~/.claude/skills/walkabout   # then restart Claude Code

License

MIT © Jezweb