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 publishes

The 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 again

It 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.