Development
How to contribute is written down once, in CONTRIBUTING.md, and the code standards in CLAUDE.md:
- Development setup — mise and the pinned toolchain, the git hooks, and the containers that run the gate with nothing installed.
- Day to day
— the tasks, and
task check, the gate, part by part. - Tests — black-box, Arrange-Act-Assert, and the coverage floors.
- Commit messages and Releases — Conventional Commits, and how they cut a release.
This page covers the one thing those leave to it: this site.
Documentation
This site is Hugo, built from Markdown in docs/:
task docs:serve # preview at http://localhost:1313
task docs:build # what CI builds and publishesThe command reference is generated from the Cobra command tree by task docs:gen. Do not edit those pages by hand — task docs:check fails when they
disagree with the code, which is what keeps a new flag from shipping
undocumented.
Images
The pictures on these pages, the recording of the terminal and the
screenshots of the web page, are files in docs/assets/images, shown with
the theme’s image shortcode, and are made, never drawn by hand. When a
screen they show changes, make them again on Linux:
task docs:media # every image in docs/assets/images, written againIt builds the demo, a made-up day’s work the terminal runs over
(cmd/demo), and plays docs/media/terminal.tape over it with
VHS into terminal.gif, and has
Playwright screenshot each section the web page describes, served over the
same demo by cmd/demo -web, and film the whole loop on it, which ffmpeg
encodes into web-walkthrough.webp. VHS comes from mise install, or is built
into tmp/ where mise cannot install it. ttyd is checked against the SHA-256
that docs/media/tool-checksums.txt pins before the task runs it, since mise
installs it unchecked: the one mise install puts on your PATH is used when it
matches, the task stops on one that does not, and with none it downloads ttyd
into tmp/ and checks that. Chromium, which films the terminal, and ffmpeg,
which encodes it, must already be on your machine: the task films with the
Chromium PLAYWRIGHT_CHROMIUM_EXECUTABLE names, or else the chromium on your
PATH, and refuses to run without one. It fails when an image is past its budget,
300 KiB a screenshot, 2 MiB the terminal’s GIF and 4 MiB the walkthrough’s WebP,
and refuses an ffmpeg that cannot write an animated WebP.
Commit the change the images are to show first: the task refuses to run while the demo, the interface, the tape or the web page has changes git has not committed, so the images committed are of the code committed with them. Run it on an idle machine, too: the task refuses one whose load is past all but one of its processors, or with a gate or a Playwright run going. VHS films in real time, and on a machine busy with a build it misses frames, so the recording skips past what the tape holds on screen; the task fails when the recording runs more than a second longer or shorter than the tape’s sleeps and typing take, and a tape that waits on the screen, which has no such length, is refused. The walkthrough is held the same way: it must run as long as its film within a second, no frame may play 10 ms or less, which a browser shows for 100 ms, no frame may last past 250 ms while the pointer glides, text is typed or the page scrolls, and every frame it holds on a step must be the film’s own, decoded as Chromium shows it. The film is captured as PNG and encoded lossless, since a lossy WebP left blocks of earlier frames on screen.
Look at the walkthrough’s keyframes as well as the WebP: the film keeps an
image of each step as it stood in tmp/walkthrough/keys, and the run fails
a step whose screen has text cut at the window’s edge or something still
moving.
Look at each image before you commit it. Nothing else will: no gate or CI job runs the task or compares the images, since fonts, Chromium and ffmpeg change their bytes from one machine to the next.