Skip to content

Write the operator guide - #124

Merged
iderex merged 1 commit into
mainfrom
documents/the-operator-guide
Aug 11, 2026
Merged

Write the operator guide#124
iderex merged 1 commit into
mainfrom
documents/the-operator-guide

Conversation

@iderex

@iderex iderex commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

The operator guide, docs/operator-guide.md, which is issue #42, and the two
clauses that were waiting on it: the exit-code pointer #52 stays open on, and
the compatibility position #64 stays open on. Part of #44 lands here as well,
in the section that states the compatibility position, since #44 allows it to
live in the changelog or in this guide and there is no changelog.

The means is Markdown prose under docs/, which is what every other document
on this board is made of. It fits because the artefact is read by a person
rather than executed, and because the checks that already exist over this
repository's prose, its named paths and its formatting reach it without a
parallel apparatus: the run below is the same gate every other document here
passes.

What it says

The three questions somebody decides on in half a minute are near the top, and
each one is written as a limit with the test or the record behind it. The
runner changes nothing in the tree it reads, and TestWalkWritesNothing is
named with the bound on what it covers. It sends nothing anywhere, pointing at
docs/privacy.md rather than restating the claim. It needs no privileges and
no display, pointing at record 0007.

The exit codes are explained by pointing at
docs/decisions/0011-the-exit-codes.md and not by restating it. What the page
adds is the half that record cannot show: which invocation produces each code,
with the command and its output, and that lab returns three of the four codes
the record fixes while the fourth is declared where its producer is under
internal/hardware.

The compatibility position points at docs/decisions/0013-how-the-record-format-changes.md
for what happens to records already on the default branch when the format
changes, and states that a change is announced by the record that decides it,
there being no changelog in the tree.

What it does not say, deliberately

There is nothing to download, so nothing on the page walks a download or a
checksum. That is stated in the section where a reader looks for it rather than
being left as a gap, together with the fact that whether anything is ever
published is not decided.

There is no licence file, so the page names its absence where a reader would
otherwise look for permission to reuse what they find.

Both absences are why #42 is not closed by this pull request. Its done-condition
asks for a walk through download and checksum, and neither exists to be walked.

The evidence

Every output quoted in the guide was produced by running the command against a
fresh clone at bbfab50, built from that clone, rather than against a working
tree.

go build ./...
go vet ./...
gofmt -l .
go test -count=1 ./...
ok  	github.com/Flowfin/lab/cmd/lab	16.066s
ok  	github.com/Flowfin/lab/cmd/pullrequest	6.308s
?   	github.com/Flowfin/lab/experiments/reading-a-tree-of-records	[no test files]
ok  	github.com/Flowfin/lab/internal/check	3.751s
ok  	github.com/Flowfin/lab/internal/hardware	2.351s
ok  	github.com/Flowfin/lab/internal/invariants	2.019s
ok  	github.com/Flowfin/lab/internal/prose	2.448s
ok  	github.com/Flowfin/lab/internal/pullrequest	6.302s

go build, go vet and gofmt -l printed nothing, which is the passing
result for all three. The lines between the suite command and its results are
the per-package output and nothing else is cut.

The two checks this change is most likely to break, run on their own so the
report each prints is readable:

go test ./internal/prose -run TestThisRepositorySatisfiesTheProseFormat -count=1 -v
    prose_test.go:279:
        examined ../..
        29 prose files read, and testdata is not read
        0 refused
--- PASS: TestThisRepositorySatisfiesTheProseFormat (0.81s)

go test ./internal/invariants -run 'TestThisRepositorySatisfiesTheInvariants|TestTheLicenceLegSaysWhetherItWasAsked' -count=1 -v
    invariants_test.go:373:
        examined ../..
        87 text files read
          the intended-use notice: 2 examined
          the licence: NOT ASKED, no licence is declared, so there is nothing to compare LICENSE against.
          credential shapes in tracked text: 87 examined
          attribution markers in tracked text: 87 examined
          paths this repository's own documents name: 30 examined
        0 refused
--- PASS: TestThisRepositorySatisfiesTheInvariants (0.61s)
--- PASS: TestTheLicenceLegSaysWhetherItWasAsked (0.09s)

The licence leg reports that it was not asked, which is its ordinary state
while that question is open, and the rest of its message names what asking
would cost. That sentence is cut after the first line and nothing else is.

The path leg is the one that matters here: it read 30 documents, one more than
before this change, and every path the new page names resolves in this tree.

go run ./cmd/lab check .
examined .
1 experiment directory walked, 1 record read
16 decision records read
the time this run read is 2026-08-11T21:00:10Z
0 refused

Reading

This change has had no second reader, and the evidence above stands in place of
one rather than alongside it.

The page somebody who has never seen this board reads before running anything
from it. It walks getting the runner, a first run with its exact output, a run
over a tree with no experiments, the listing, and what a refusal looks like,
and it carries the three questions somebody decides in half a minute on: that
the runner changes nothing, sends nothing anywhere, and needs no privileges.
Each of the three is written as a limit with the test or the record behind it
rather than as an assurance.

The exit codes are explained by pointing at record 0011 rather than by
restating it, and what the page adds is the half a record cannot show: which
invocation produces each code, with the command and the output. It also says
that the runner returns three of the four the record fixes and where the fourth
one's producer is.

Two absences are stated rather than papered over. There is nothing to download,
so nothing here walks a download or a checksum, and whether anything is ever
published is not decided. There is no licence file, so the page names its
absence where a reader would otherwise look for permission to reuse what they
find.

The compatibility position lands here because it has nowhere else to live yet.
It points at record 0013 for what happens to records already on the default
branch when the format changes, and says that a change is announced by the
record that decides it, there being no changelog in the tree.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
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