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.
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: interruptedon stderr and exits 130.
A generated section sits between two markers in the page:
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.mdholds one line*[form]: definitionfor 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 ofwatchis 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 insrc/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, thenui-monospace, monospace). Bold isfont-weight600, and faint is thedimcolour. - The colours are the tokens of the docs theme, as hex values: the background is
code-bg, the text isink,dimismutedandplanislink.ok,now,warnandbadhave the lightness and the chroma oflink, 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, atextblock gives the plain text of the frame, the frame that the code prints withNO_COLORset. 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 docswrites 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. |