docs: build-your-first-harness — animated scaffold + dev:web shots, stills re-cut for lloyal-ai

[kazimali07]

Every still on Build your first harness was a v0.7.1 screenshot: the banner said harness.dev, the ready screen said Add apps:, and five alt texts named a CLI that no longer exists. This re-shoots the section against lloyal-ai@1.0.4.

What's in it

Two GIFs of real runs.

• build-your-first-harness-new.gif — the whole npx lloyal-ai@latest new wizard, from the typed command to hello-harness is ready. Sits at the top of section 1, before "Name the application". 324 KB, 286 frames, 33.7 s, loops forever.
• build-your-first-harness-dev-web.gif — cd hello-harness && npm run dev:web, from the shell prompt through Vite coming up at http://localhost:5173/, the model fetch running to 100 %, and the host reporting [serve] hello-harness serving on ws://127.0.0.1:8787 — up to 4 browser session(s) over one resident model. Replaces still 07 in "Begin a Session"; the caption is unchanged. 77 KB, 48 frames, 14.7 s.

The seven stills, re-cut from the new recordings at the same wizard moments they always showed. Same filenames. They're 1652×1058 now rather than ~1614×1006 — the CSS is width:100%; height:auto, so nothing shifts — and about 11 MB smaller in total, because the originals were screenshots over a desktop wallpaper and these are flat terminal renders.

Alt text: harness.dev → lloyal-ai, five places. That was the only remaining harness.dev on the page; the code block already said npx lloyal-ai new. Count goes 5 → 0.

How it was recorded

Same rig as the homepage scaffold GIF: a Python PTY driver runs bash --norc --noprofile -i in a 100×27 pty, types the command, and walks the wizard's real prompts confirming its own defaults. Scaffold and npm install ran to real completion — 166 MB of node_modules on disk, ✓ Dependencies installed on screen. Rendered with agg 1.9.0 in JetBrains Mono, background #0a0d18 so the GIF edges disappear into .flow-shot.

lloyal-ai@1.0.4, Node v24.18.0, Vite 7.3.6, macOS 26.5.2 on an 8 GB MacBook Air.

The only post-processing is timing. The polish pass caps any single idle gap at 1.2 s and drops the fixed macOS bash-deprecation nag. It never edits or invents output text — 2 gaps clamped on the wizard take, 1 on the dev:web take. Every pixel in both GIFs and all seven stills came off a real terminal.

One extra step on the dev:web GIF. The real run took 163 seconds, nearly all of it a percentage counter, which is a hopeless loop on a docs page. So the fetch line is thinned to its genuine decade ticks: of 742 progress events, 11 are kept (0, 10, 20 … 100 %) and 731 dropped. Each of the 742 is a pure carriage-return rewrite of the same single line carrying no other text, so dropping intermediates leaves no torn screen state. Everything before the first tick and everything after 100 % is kept verbatim, in order, at its original spacing.

Worth being plain about the trade: this compresses the apparent duration of the fetch. On screen it runs 0→100 % in about 4 seconds; the real fetch took roughly 153 s for 2.6 GB. Nothing is edited or invented and the order is exactly as recorded, but the GIF isn't evidence about download speed. The untouched full-length cast is in the source bundle. The run itself finished cleanly — no OOM, no hang.

(There's no digest-verification line in the GIF because the CLI doesn't print one; the counter hits 100 % and the serving line follows.)

Two things to look at

one reduce. The Targets prompt at 1.0.4 prints — one reduce where it should say — one required, apparently collateral from the app→ability rename inside the CLI. It's genuine output, so it's in the GIF and in still 02 verbatim. Fixing it is a CLI patch plus a re-record, not an edit to these assets.

Cache headers. build.mjs writes /assets/* → Cache-Control: public, max-age=31536000, immutable, and the stills keep their old filenames. Anyone who has already loaded the guide will keep seeing the harness.dev versions. Worth a CDN purge on deploy, or say the word and I'll add a -v2 suffix.

Second commit is separable

.flow-caption is defined in guides-theme.css for exactly this element, but no figcaption on the page carried the class, so all eight captions were rendering as near-black text on the #0a0d18 figure background — effectively invisible. The second commit adds the class. Markup only, no CSS change. Drop it if you'd rather handle contrast separately.

Still 07 is re-cut to the GIF's final frame — fetch at 100 %, host serving on ws://127.0.0.1:8787 — and is updated in the repo even though the page shows the GIF there. If you'd prefer stills only, pointing the <img src> back at -07.png is a one-line revert and you keep the payoff frame.

🤖 Generated with Claude Code