Skip to content

docs(website): re-shoot the docs stills on the 0.69 UI, and make the rig reproducible - #828

Closed
edspencer wants to merge 7 commits into
mainfrom
docs/media-v069
Closed

docs(website): re-shoot the docs stills on the 0.69 UI, and make the rig reproducible#828
edspencer wants to merge 7 commits into
mainfrom
docs/media-v069

Conversation

@edspencer

@edspencer edspencer commented Aug 10, 2026

Copy link
Copy Markdown
Owner

Why

Every UI-bearing asset on the site was shot before the design work landed. The
seven stills merged in the previous pass predate the first design commit (67e493f)
by 41 minutes, so they are pre-redesign exactly like the older ones. Age was never the
criterion — three of these were a day old and still wrong, because of what landed
after they were committed.

These sit under prose in the present tense, on pages a reader consults to operate
the product. A pre-redesign frame there is worse than no image: a reader who cannot
find the pictured control concludes the docs are stale everywhere.

Re-shot — 7 stills

getting-started/root-home.png · config/project-settings.png ·
using/adopt-row.png · using/adopt-modal.png · using/adopted-badge.png ·
using/promote-to-project.png · guides/trigger-tool-picker-bash.png

All at v0.69.0 in Foundation / dark / hue: null / tint: 0 — the out-of-the-box
appearance (DEFAULT_APPEARANCE; paddock:theme defaults to dark). That is what a
reader sees on first boot, which is a docs screenshot's whole job.

Two alt-text corrections ride along, and they are not cosmetic — alt text is the
only description a screen-reader user gets. getting-started.md claimed four unread
chats and named OVERVIEW.MD/CHANGELOG.MD sections; the frame shows nine unread, three
projects grouped by area, and RUNNING/UNREAD/FILES.

Not here: the theme quartet and the Appearance panel

Those five stills live in #815, which also carries the 0.67 prose that references
them. Keeping a copy here would have made them orphans on this branch and put the same
bytes in two PRs. This branch has zero orphans and zero dangling references
checked mechanically, both directions.

Making the rig reproducible

seed.mjs and serve.sh existed only on one machine and were full of its paths and
ports — so capture.mjs, which is committed, was unusable by anyone else. Both are
now committed, driven by four env vars (PADDOCK_RIG_HOME / _CLONE / _PROJECTS /
_BASE), with no box paths.

Worth reviewing rather than skimming:

  • serve.sh was retyped from a spec, not copied. The original held a live OAuth
    token in plaintext; those lines are gone rather than edited. A rig running a fake
    claude must never need a credential.
  • The projects root moved off /home. The previous rig kept it there on a box
    where only /data was a volume — a container restart destroyed every project.yaml
    and every .chats/*.jsonl while the data dir survived, leaving orphaned job records
    reporting chats whose transcripts were gone. Default is now $PADDOCK_RIG_HOME/projects.
  • It binds loopback, not 0.0.0.0. With PADDOCK_AUTH_MODE=none, binding all
    interfaces publishes an unauthenticated instance. Capture runs on the same host, so
    PADDOCK_DANGEROUSLY_ALLOW_OPEN is no longer needed at all.
  • capture.mjs pins the theme via addInitScript and asserts it applied. It has
    to be addInitScript: the three paddock:* keys are read by a pre-paint inline
    script, so a page.evaluate after goto catches a mid-swap frame — and a stale
    paddock:appearance-cache paints the previous theme's accent for one frame.
  • shots.manifest.json records the observed theme, accent, mode and app version
    beside every shot, so "which build is this frame from?" is a file read rather than
    the forensics that made this pass expensive.

Verification

  • cd website && npm install && npm run build → exits 0, 52 pages.
  • Leak check (CI has no secret scan — this is manual): exactly 46 127.0.0.1
    hits across website/src/content/docs/** + README.md, matching the recounted
    baseline. No private hostname, LAN IP, container id or box path in the diff.
  • Rig identity proven from /api/instance-config (dataDir + driveMode: batch),
    never from pm status or /api/health — both are satisfied by a stale squatter.
  • Stale-build guard: the rig was rebuilt at main and /config confirmed to
    render the Appearance section, which cannot exist before 75c3935. Without this
    every "re-shot" frame would be the old UI again, and nothing else would show it.
  • md5sum on every shot — no byte-identical pairs. Two unframed shots of one URL
    at one viewport land as the same file.
  • Every committed frame was opened and looked at. strings shot.png is not a leak
    check — rendered text is pixels.

Docs-only: no changeset, no version bump.

Not in this PR

HomeLab Agent added 5 commits August 10, 2026 13:49
root-home, adopt-row, adopt-modal, project-settings and the trigger tool
picker were all shot before the design work landed (#763/#768/#769/#780/#801).
Every one showed chrome, surfaces, type and accent the redesign replaced, on
pages whose prose is in the present tense.

Shot from the docs-media rig at v0.69.0, Foundation/dark, hue null, tint 0 —
the out-of-the-box appearance.  capture.mjs now pins the theme via
addInitScript (the keys are read by a pre-paint script, so a post-goto
evaluate catches a mid-swap frame) and asserts it applied.
… panel + theme quartet

Foundation dark at the out-of-box default (theme quartet excepted). Shot against
a rebuilt rig at main, verified post-redesign via the Appearance section.

Discover is NOT included: the rig has no discoverable Claude Code history, so
the route renders its empty state. Needs seeding.
The previous frame caught the list when tidepool held a single chat, so it
showed the adopted row alone — no contrast, which is the entire point of the
image on using/working-in-chats.md:80. Re-shot with four ordinary chats above
it, so the terminal provenance marker reads AS a distinction.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 10, 2026

Copy link
Copy Markdown

Deploying paddock with  Cloudflare Pages  Cloudflare Pages

Latest commit: f60fe9d
Status: ✅  Deploy successful!
Preview URL: https://e58fed9d.paddock-7u2.pages.dev
Branch Preview URL: https://docs-media-v069.paddock-7u2.pages.dev

View logs

HomeLab Agent added 2 commits August 10, 2026 14:06
…shot

Four runtime themes plus a free accent picker make "which theme is this?"
unanswerable from a PNG — which is most of what made this re-shoot expensive to
reason about. capture.mjs now writes <shot>.png.json observed FROM THE LIVE PAGE
(theme, light/dark, hue, tint, solved accent, app version, route, viewport), so
a silently-failed theme is detectable after the fact rather than only at capture
time. shots.manifest.json is the committed aggregate.

Immediately useful: the quartet records four distinct accent triples, which is
what proves the theme applied rather than just the label being written.
The re-shot frame names a different chat and shows four ordinary rows above
the adopted one; the alt text still described the previous capture.
edspencer pushed a commit that referenced this pull request Aug 10, 2026
git rm --cached was not enough: it left the files in the working tree, where the
next blanket `git add -A` re-staged them and silently undid the split. Removing
them from the tree on this branch is what actually holds.

They are committed on docs/media-v069 (#828), which is where #815 should take
them from — an asset and the reference to it belong in one PR, and whats-new.mdx
is on #815.
@edspencer

Copy link
Copy Markdown
Owner Author

Superseded by #829 (captures) and #830 (rig tooling + runbook), which split this into two independently reviewable changes and are a strict superset of it. Closing to keep the review queue honest — no content is lost.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant