Making the Demo Video AI-Legible
This is a Technical Discussion Record (TDR) — not about a feature, but about a content decision: how a video demo becomes a usable artifact for AI coding assistants, and where that artifact lives in the docs.
What we were trying to solve
Section titled “What we were trying to solve”The demo video was finished. The docs landing page had a Vimeo embed and a human-readable timecoded chapter guide. But the blog post we’d written earlier (“Your AI Can’t Watch Your Video”) made a point worth taking seriously: chapter markers are for humans; timecode-aligned descriptions are for AI. The question was where that richer artifact belongs in the Stellar docs structure.
The deeper problem: Stellar’s entire premise is that tools should be legible to AI assistants. Releasing a demo video with no AI-legible artifact around it would be a visible contradiction.
What we considered
Section titled “What we considered”Embedding the description in the landing page — rejected. The landing page is already doing two jobs (first impression + chapter guide). A dense timecoded description would be noise for humans and harder to link to directly.
A blog post or explainer — rejected. Blog posts aren’t indexed in llms.txt. Explainers are demoted. The description isn’t design thinking — it’s reference material.
A dedicated reference/ page — chosen. The reference/ directory is autogenerated into the sidebar and promoted in llms.txt by the Starlight plugin config. A page at reference/demo-video.md is automatically available to any AI crawling the docs, and can be linked to directly in conversation.
The format decision
Section titled “The format decision”The timecoded description was sourced from a DaVinci Resolve EDL (Edit Decision List) — the marker file exported from the video editor. The EDL contains timecodes in 01:HH:MM:SS:FF format (Resolve’s default start at 01:00:00:00) with per-marker descriptions written during the edit.
The conversion to AI-legible format involved:
- Subtracting
01:00:00:00from all timecodes to produce viewer-relative times - Converting point markers to ranges (each range ends at the next marker)
- Cleaning up personal edit notes that weren’t meant for publication
- Collapsing empty markers (accidents from the keyboard shortcut) into surrounding ranges
The result is a flat prose description of what’s visible on screen at each moment — not chapter titles, not marketing copy.
Including the AI responses verbatim
Section titled “Including the AI responses verbatim”The recording session shown in the video ends with GPT-5.4 responding to the exported artifact, unprompted. Those responses are included verbatim in the description page, not summarized.
The reason: they’re genuine content, not illustration. GPT-5.4 identified the outbox happy path, the concurrent burst legibility, the dead-letter gap, the item-level diff visibility limit, and the ngrx-event node absence — all correctly, from the artifact alone. An AI reading this page gets to see what another model did with the artifact. That’s more useful than a paraphrase.
The “shortens the gap between ‘what happened?’ and ‘where is that implemented?’” line is the clearest one-sentence description of Stellar’s value proposition produced to date. It came from a model reading a recording, not from us writing copy. Preserving it verbatim and attributing it correctly (GPT-5.4, uncoached) is the honest thing to do.
The “AI description as UI feature” idea
Section titled “The “AI description as UI feature” idea”Jeff raised the idea of a button or icon in the docs UI that surfaces the timecoded AI description to human readers — used the way he uses closed captions on films. The analogy is apt: captions exist for accessibility reasons but are used broadly because they’re useful.
This is deferred. It would require a custom Starlight component, and there’s only one video right now. The condition for revisiting: more videos, or evidence that human readers are finding the description page useful enough to want in-context access.
What we deliberately deferred
Section titled “What we deliberately deferred”YouTube upload — Jeff plans a longer, more produced video for YouTube eventually. The Vimeo embed is for the short demo. No decision made on YouTube strategy yet.
AI description as inline UI — the caption-style button idea. Deferred until there’s more video content to justify the component.
Automated EDL → description conversion — the conversion from DaVinci Resolve markers to AI-legible prose is currently manual. Worth automating if this becomes a recurring workflow, but one video isn’t enough evidence.
This TDR was written from the session of 2026-04-02.