Skip to content

Reference: delegate docs

NAME
delegate-docs — write the generated sections of the reference pages
SYNOPSIS
delegate docs [--root <root>] [--check]

The reference pages of this repository hold hand-written prose and generated sections. delegate docs writes the generated sections from the code, so a page cannot drift from the parsers, the exit codes, the renderer constants or the validator. This is the one command that regenerates every generated page.

delegate docs [--root <dir>] [--check]

Run it from the root of the repository, or give the root with --root. After a change to a flag, an exit code, a guard command or a finding code, run delegate docs and commit the pages that it changed.

On a terminal, delegate docs sets the title of the terminal to delegate docs. See the terminal title.

Option Meaning
--root <root> The repository root, which holds docs/ and skills/; default is the current directory.
--check Write nothing; exit 1 and name each section and file that differs from the code.

What the command does

  • With no option, the command rewrites each generated section and prints updated <file> for each page or file that changed, also for the abbreviations file and the glossary map. It leaves the prose outside the sections as it is.
  • With --check, the command writes nothing. For each section that differs from the code, it prints a line on stderr that names the page and the section, and it exits 1. For each terminal figure file that is missing or differs from the code, it prints a line that names the file. It exits 0 when each section and each file is current.
  • A page that is missing, or a page that does not have exactly one pair of markers for one of its sections, is an error: the command names the page and the section on stderr and exits 2. An option with no help text is also an error. The command never adds a section to a page.
  • After Ctrl-C, the command prints delegate: interrupted on stderr and exits 130.

A generated section sits between two markers in the page:

<!-- generated:begin <section> -->
...
<!-- generated:end <section> -->

Do not edit the text between the markers. To change a flag description, change the help text of the parser. To change a page, change the prose outside the markers.

The abbreviations file and the glossary map

delegate docs also writes two files from docs/glossary.md. The docs site adds includes/abbreviations.md to every page, so each term of the glossary shows its definition as a tooltip. And docs/javascripts/glossary.js maps each form of each term to the anchor of its entry, so the site links each term to the glossary.

  • Each ## heading of the glossary is a term. The first sentence of the first paragraph under it is the definition, as plain text. A link keeps its label, and an inline-code mark is removed.
  • An abbreviation matches its exact text, so each term has more than one form: the glossary form and its plural, and the lowercase of both when the term starts with a capital and then a lowercase letter. A term in code, such as assure, has no plural.
  • A pointer entry, and a term that is also an everyday word (blind, brief, built, finding, report, resume, run, skill, skip, step), keeps only its glossary form. "I run the tests" is not the term run.
  • includes/abbreviations.md holds one line *[form]: definition for each form, in the order of the glossary. With no glossary, the file holds only its header.
  • An entry with no text is an error. A term that appears twice is an error. The command names the term on stderr, exits 2, and writes nothing.
  • With --check, a missing file or a file that differs from the glossary makes the command exit 1. It names the file on stderr.

The abbreviations file is outside docs/, so the site does not show it as a page. On the site, a short script wraps each term in a link to its entry, except a term in a heading, a term in a link, and a term on the glossary page.

The terminal figures

delegate docs also writes the terminal figures: frames of delegate watch and delegate status as SVG files in docs/assets/terminal/. Each figure has two files, <figure>-light.svg and <figure>-dark.svg, for the light and the dark scheme of the site. The two files differ only in their colours.

  • A figure is the output of the code, not a picture of a design. The command copies the journals of the figure from src/delegate/docs/figures/ into a temporary state directory, and renders the frame on the path of the command, with a fixed clock, a fixed terminal size, a UTF-8 locale, the UTC time zone and the SGR codes on. A frame of watch is the first frame that the live view draws. The path of the temporary state directory shows as the state directory of a repository under the default state root, ~/.local/state/delegate/project-3f9a1c0b7d42.
  • The journals use neutral ticket ids, agent names and paths. A journal names its files in the directory of its run as $RUN/.... Its event streams are in src/delegate/docs/figures/streams/, and each gate log is an empty file. Each file of a run has the time of the newest event of its journal.
  • The SVG has one <text> row for each line of the frame, and one <tspan> for each run of one paint role. Each character is one cell of the code font of the site (Noto Sans Mono, then ui-monospace, monospace). Bold is font-weight 600, and faint is the dim colour.
  • The colours are the tokens of the docs theme, as hex values: the background is code-bg, the text is ink, dim is muted and plan is link. ok, now, warn and bad have the lightness and the chroma of link, with the oklch hues 145, 210, 85 and 25.
  • Each file has role="img", a <title> that names the frame, and a <desc> that tells what the frame shows. It has no script and no external reference.
  • A page shows a figure with two image lines: the light file with the fragment #gh-light-mode-only, then the dark file with #gh-dark-mode-only. Directly under them, a text block gives the plain text of the frame, the frame that the code prints with NO_COLOR set. It is the text alternative of the figure. The image lines and the block are prose that a writer puts on the page: a figure is never in a generated section. Do not edit a figure file by hand: delegate docs writes it.
Files Frame Command Terminal and clock (UTC) Journals
docs/assets/terminal/watch-live-light.svg docs/assets/terminal/watch-live-dark.svg 3a delegate watch 120 × 24, 2026-03-02 09:24:30 src/delegate/docs/figures/watch-live/20260302T090000Z-7c1e.jsonl
docs/assets/terminal/watch-picker-light.svg docs/assets/terminal/watch-picker-dark.svg 2b delegate watch, the run picker 120 × 24, 2026-03-02 09:06:00 src/delegate/docs/figures/watch-picker/20260302T081500Z-2d4f.jsonl, src/delegate/docs/figures/watch-picker/20260302T084000Z-9a0b.jsonl, src/delegate/docs/figures/watch-picker/20260302T090500Z-c3e8.jsonl
docs/assets/terminal/status-table-light.svg docs/assets/terminal/status-table-dark.svg 1i delegate status 120 × 24, 2026-03-02 09:52:50 src/delegate/docs/figures/status-table/20260302T090000Z-58c2.jsonl
docs/assets/terminal/watch-fixup-light.svg docs/assets/terminal/watch-fixup-dark.svg 1d delegate watch 120 × 24, 2026-03-02 09:31:45 src/delegate/docs/figures/watch-fixup/20260302T090000Z-4b9d.jsonl
docs/assets/terminal/watch-paused-light.svg docs/assets/terminal/watch-paused-dark.svg 1f delegate watch 120 × 24, 2026-03-02 09:31:00 src/delegate/docs/figures/watch-paused/20260302T090000Z-e05a.jsonl
docs/assets/terminal/watch-fit-light.svg docs/assets/terminal/watch-fit-dark.svg 3b delegate watch 120 × 24, 2026-03-02 13:06:46 src/delegate/docs/figures/watch-fit/20260302T090000Z-6e2b.jsonl

The test

The test suite holds one drift test for each generated section, one for the abbreviations file and the glossary map, and one for each terminal figure file. The test fails when the section in the committed page, or the committed file, differs from the text that the code builds, and its message tells the reader to run delegate docs. A change to a flag or to a frame with no regeneration therefore fails the suite. Another test checks that the text of each row of a figure is the line of the frame that the code prints with NO_COLOR set. A third test checks each page that shows a figure: it names the light and the dark file, the text block under the figure is the plain text of the frame, and no page names a file in docs/assets/terminal/ that delegate docs does not write. When a frame changes, run delegate docs, and then copy the text that the failure message gives under each figure of that frame.

The generated sections

Page Section Built from
docs/reference/run.md run-options The argument parser of delegate run.
docs/reference/commands.md stop-options The argument parser of delegate stop.
docs/reference/run.md pause-options The argument parser of delegate pause.
docs/reference/status-and-watch.md status-options The argument parser of delegate status.
docs/reference/runs.md runs-options The argument parser of delegate runs.
docs/reference/status-and-watch.md watch-options The argument parser of delegate watch.
docs/reference/status-and-watch.md watch-exit-codes The exit codes of delegate watch.
docs/reference/commands.md agent-definitions-options The options of agent-definitions before its subcommand.
docs/reference/commands.md render-options The render parser of agent-definitions.
docs/reference/commands.md declaration-keys The declaration schema of agent-definitions schema.
docs/reference/commands.md validate-options The validate parser of agent-definitions.
docs/reference/commands.md bootstrap-options The bootstrap parser of agent-definitions.
docs/reference/commands.md brief-full-options The full parser of verifier-brief.
docs/reference/commands.md brief-fixup-options The fixup parser of verifier-brief.
docs/reference/commands.md clean-options The argument parser of delegate clean.
docs/reference/commands.md verifier-guard-commands The command constants of the renderer.
skills/agent-definitions/SKILL.md verifier-guard-commands The command constants of the renderer.
docs/reference/commands.md finding-codes The finding codes of the validator.
skills/agent-definitions/SKILL.md finding-codes The finding codes of the validator.
docs/reference/docs.md docs-options The argument parser of delegate docs.
docs/reference/docs.md generated-sections The list of sections in this module.
docs/reference/docs.md terminal-figures The list of figures in delegate.docs.figures.

Version main