A Narrated Tour of the Handover Menu
A live screencast that drives the real menu, one item at a time, with narration timed to the motion.
Gantry documents itself with screencasts. One kind replays a recorded build run; this job built a different kind. Gantry has an interactive terminal menu for handing a run over to another operator, and until now there was no way to show it working — no narrated walkthrough, and nothing that proved the menu on screen still matched what the docs described. This job built a live tour: a video that drives the actual menu, moving a pointer to each item in turn while spoken narration keeps pace with the motion. Alongside the video it built the scripts that produce it and a runbook for regenerating it, so the tour stays honest instead of drifting out of date the moment a row is added to the menu.
Build
The build split into three layers: prove the real menu can be driven and pin down where each item sits, compile an item-anchored script into an exact sequence and timing, then record and document the result. The middle layer is where the difficulty concentrated.
The order is a dependency chain. A tour script can only anchor its narration to menu items once something has established where those items are and proved the menu responds to a driven pointer, so the first milestone built that ground: an interaction proof, the demo state the tour runs against, a model of the menu's inventory, and a validated coordinate model. Its review recorded what the rest of the run had to honour — build the script from the validated coordinate model, move by bare hover with no keyboard fallback, and treat disabled or conditional rows as non-highlightable rather than forcing them on. Two of its sprints were sent back by the gate before they landed, the coordinate-model work among them.
The middle milestone, compiling an item-anchored script into the exact tour sequence and timing, is where the run worked hardest. Every one of its sprints ended in a re-plan that reshaped the sprints still ahead, as the choreography contract kept learning what it actually needed: required item-map fields for dynamic groups, and a distinction between answering a run prompt and answering a chat prompt. That the contract had to be firmed up sprint by sprint is the clearest sign of where the design's real uncertainty lived.
By the time the final milestone built the recorder, the choreography driver, the narration check, the artifact metadata, and the runbook, the contract beneath it had stopped moving, and those sprints ran through the gate without a repair. The load had already been spent upstream.
Feature
Before this job, Gantry could replay a recorded run as a screencast but had no way to demonstrate its interactive handover menu, and nothing that verified the on-screen menu still matched its documentation. The job left a live menu-tour pipeline, still standing at HEAD though reorganized since.
Gantry's screencast pipeline could take a recorded build run and turn it into a narrated replay, but the handover menu is interactive, and a passive replay cannot show it responding. There was also nothing that caught the menu drifting away from its documentation — add a row, and the tour would silently be wrong.
What the job left is a pipeline built around that problem. The tour logic lives in a menu-tour module; a set of shell scripts prove the menu responds to a driven pointer, compile the item-anchored script and its narration into a choreography of pointer steps, record the tour with and without narration, and check the finished bundle. A screencast script holds the spoken words, and a section of the screencast runbook documents how to produce the video and regenerate it when the menu changes — including a validate command that rejects a stale item map once the menu's row count no longer matches.
Standing in the tree today, the pipeline is intact but has been reorganized since. The tour implementation no longer lives under the TUI code where the job first put it; a later change folded it into the engine module that carries it now, and the original file is gone. The standalone integration tests the job wrote — the interaction proof, and the workflow, record, and narrated-record suites — are no longer present as separate files. The scripts, the screencast script, and the runbook remain, and the runbook still names the validate and item-map commands, so the capability the job set out to build is still the one a reader would find.