cairns

An entry written in one command, prose on stdin

2026-09-24T00:00:00Z

Writing an entry was two steps: cairns new made a stub, then the prose went into it by editing the file. A model doing this got the second step wrong often enough to matter - looking for the file, rewriting the front matter, or repeating the heading. And the **Still unknown:** line was the part it got wrong most: left blank, written twice, or put somewhere other than the end.

cairns new now takes the prose directly:

cairns new "Title" --area cli --unknown "what is open" --body - <<'EOF2'
The prose.
EOF2

--body - reads stdin, and --body "text" takes it inline. The command writes the front matter, the # N. Title heading and the trailer, so nothing has to be opened afterwards. Without --body it writes the stub exactly as before - without_a_body_the_stub_is_unchanged.

One way for the trailer to arrive

The trailer comes from --unknown, or from a **Still unknown:** line already at the end of the body. Never both, and never neither:

body has a trailer	`--unknown`	result
yes	absent	the body as written
yes	given	refused - two trailers
no	given	appended
no	absent	refused, naming `--unknown nothing`

Refusing the last case rather than defaulting to nothing is deliberate. A default of nothing would close out every entry whose writer forgot, which is the silent hole 17 made check close. The refusal happens before a number is taken, so a refused body leaves no stub behind.

"Has a trailer" means the marker begins a line, as the spec requires. The first version of the MCP check used contains, which counts a sentence that merely mentions the marker - this entry is one. Both paths now share has_trailer.

A body that starts with a # heading loses it, because the command writes the entry's own and a repeated heading is the most common thing handed over with the prose. Tests: a_body_takes_its_trailer_from_unknown, a_body_that_ends_with_a_trailer_keeps_it, a_body_with_no_trailer_at_all_is_refused_with_the_fix, a_body_that_repeats_the_heading_loses_it.

The MCP tool

worklog_new already took a body, but always appended its own trailer, so a body that ended with one got two. It now goes through the same compose_body. Its default is unchanged - an absent still_unknown still means nothing, because its schema has always said so - except that a trailer in the body now takes precedence over that default.

The skill now leads with the one-command form, and says to quote the heredoc marker so backticks and $ in the prose arrive as written.

Areas in one line each and files that fold

2026-09-24T00:00:00Z

Two complaints from use, both about friction rather than correctness: adding an area was a chore, and an entry with fifteen files put a wall of paths between its title and its first sentence.

`[area]` as one table

An area is a name and a phrase, and [[area]] spent three lines and two keys saying so. cairns.toml now also takes a single table:

[area]
spec = "the format itself - entries, config, log.json, publishing"
core = "cairns-core: parsing, validation, the canonical document"

The [[area]] list is still read and means the same thing. It is deliberately documented as the long form rather than an old one: each area there is its own table, so a key added to areas later has somewhere to go, and the short form only has room for about. TOML refuses a file holding both, so there is nothing to reconcile.

Both forms go through one hand-written visitor, areas in config.rs, rather than an untagged enum - an untagged enum reports "data did not match any variant" and throws away TOML's own message about what was actually wrong.

The order matters, since it is the presentation order in the filters, the skill and the index. I expected to need the toml crate's preserve_order feature for that; I did not. toml 0.8 hands a visitor the keys in document order regardless - the feature only changes the order of its own Table type. an_area_table_reads_in_the_order_written holds it, with areas declared non-alphabetically.

A name declared twice is now an error in either form. The table form gets that from TOML for free; the list form never checked, and now validate does.

The cheaper half of "adding an area is annoying" was the error message. cairns new --area nope now ends with the line to paste:

to add it, write this under [area] in cairns.toml:
    nope = "what belongs here"

It says [area] even to a config written in the long form, because the parsed config does not remember which form it came from. Not worth a flag.

cairns init writes the short form, and this repo's own config uses it.

Files, grouped and folded

The entry page printed files as one wrapped row of full paths. Most of the length was the same crates/x/src/ repeated. Now each directory is said once, muted, with the names after it, and the full path is on hover. Past five files (FILES_SHOWN in html.rs) the list is a <details> that starts closed, labelled with its count - "15 in 7 directories" - and opens to one directory per line. No script.

A path with a trailing slash is a directory and is named by its last component under its parent, so docs/spec/ shows as spec/ under docs/, not as an empty group under itself.

Checked with the render loop from 13, against a copy of this log with entry 22 given fifteen files, open and closed. The first screenshot showed the filename inside a code chip and the directory outside it, which read as two unrelated things; the chip is gone inside .files. Tests: an_entrys_files_say_each_directory_once, a_long_list_of_files_folds_behind_its_count.

A config section the binary had never heard of

2026-09-21T00:00:00Z

[[link]] from 21 worked here and did nothing on someone else's machine, with no error either way. Two causes, and only one of them is interesting.

The dull one: a Homebrew tap is a git clone, and it is as old as the last brew update. brew upgrade cairns against a stale tap reinstalls the version the tap knows about. Mine did exactly that while I was reproducing the report - I installed "0.5.0" and got 0.4.1.

The one that matters

A cairns that predates [[link]] reads a config containing it, ignores the section entirely, and prints ok.

$ cairns --version
cairns 0.4.1
$ cairns check
ok

That is serde's default: unknown fields are skipped. It is the right default for an entry's front matter, where 1 deliberately passes unknown keys through so a project can carry its own metadata. It is the wrong default for configuration, because configuration is instructions - a key the program does not recognise is an instruction it is not following, and silence is the worst possible answer.

Every config struct now refuses what it does not recognise:

cairns.toml: TOML parse error at line 59, column 3
unknown field `lnik`, expected one of `spec_version`, `project`, `paths`,
`site`, `index`, `check`, `docs`, `area`, `publish`, `link`

which catches a typo and, from here on, catches a config written for a newer cairns than the one running. It cannot fix 0.4.1 - that binary will go on ignoring things quietly - so the first symptom of being too old is still the one that was reported. From v0.5.1 the failure is loud.

spec_version was supposed to cover this and did not, because the rule says additive changes do not bump it. That rule is right for the entry format, where a new optional field genuinely does no harm to an old reader. For config it is wrong, and the fix is the one above rather than a version bump on every added section.

Serve prints its version now

Twice today I have been confused by a cairns serve still running the binary it was started with. It says which version it is at startup.

Links the generated nav could never know about

2026-09-21T00:00:00Z

The rail's navigation was whatever cairns had made: entries, the reference, the open questions, the About page, the feed. A project site needs to point somewhere else too - the repository, the releases, a chat - and there was no way to say so.

[[link]]
label = "Repository"
url   = "https://github.com/Toyz/cairns"
icon  = "github"

They sit in their own group below the generated nav rather than mixed into it, because one set is pages this tool made and the other is everywhere else, and a reader can tell at a glance which is which.

Ten icons, inline

github, globe, book, code, download, rss, chat, mail, star, link, with the obvious aliases - docs for book, feed for rss, discord for chat.

They are inline SVG, for the same reason the page has no webfonts: an icon that needs a request is missing for the first second, and missing forever behind a proxy. Ten of them cost less than one request. The GitHub mark is the Octicons path, which is MIT licensed; the rest are drawn as plain geometry.

An unknown name renders no icon at all. That is right at build time - a link without a glyph still works, and a typo should not stop a site from building - but it is wrong to stay quiet about, so check reports it with the list of what is available:

cairns.toml: link "Releases" wants icon "downlod", which is not one of:
github, globe, book, code, download, rss, chat, mail, star, link

That pairing is the shape worth repeating: be forgiving in the renderer, strict in check. The site builds either way, and the person who made the typo finds out.

One plus-minus sign crashed the scanner

2026-09-21T00:00:00Z

thread 'main' panicked at crates/cairns-core/src/entry.rs:490:32:
start byte index 1 is not a char boundary; it is inside '±' (bytes 0..2 of string)

The reference scanner from 19 walks each line looking for [[, and where a character is not one it advances with at += 1. That is a byte, not a character. ± is two bytes, so the next line[at..] started inside it and Rust refused - correctly, and fatally.

It steps by ch.len_utf8() now. Hellbender's log contains eight ±, amber's contains eleven em dashes, and both were enough; hellbender's is the log that found it.

What the tests missed and why

There were six tests on this scanner, covering references, labels, fenced code, inline code and dangling numbers. Every one of them was written in ASCII, because I wrote them, and I was thinking about the syntax rather than about the text it sits in. A worklog is prose about measurements - ±, —, µs, ° - and the one thing the scanner is guaranteed to meet is a character I did not type into a test.

The new tests run the scanner over ±, an em dash, an emoji, ±[[3]]±, and a fence containing ±, and assert the surrounding text survives the rewrite intact rather than merely that nothing panicked.

It is also worth noticing what caught it: not check, not the tests, not the build. Someone ran it on a real log. That is the fourth time in two days that the thing which found the fault was the tool meeting real content rather than anything I ran against content I had invented.

The rest of the codebase, checked

The same habit of mind wrote the front matter splitter, the slug derivation, the summary extractor and the trailer parser, so all of them were read again. They are safe, and for a reason worth recording rather than by luck:

every one of them slices at an index found by searching for an ASCII delimiter - \n, ---, . , /, #, **Still unknown:** - and a byte index found that way is always on a character boundary
slugify truncates its own output, which is ASCII by construction: it emits only a-z, 0-9 and -
the one other at += 1 in the tree walks a Vec<Event>, not a string

So the scanner was the only place advancing a byte at a time through text it had not built. That is the distinction to watch for: searching for ASCII and slicing there is fine, and stepping through arbitrary text is not.

References, and a parser that reads them in pieces

2026-09-21T00:00:00Z

An entry could point at another only by writing out its filename:

[12](0012-three-css-edits-three-wrong-anchors-and-half-a-stylesheet-gone.md)

which you have to look up, can mistype, and which breaks if the slug ever changes. [[12]] now does it: a link to entry 12 labelled with the number and carrying its title, with [[12|in other words]] for your own wording. check rejects a reference to an entry that does not exist, which is the first link-checking this tool has done and answers part of what 11 left open.

The trade is worth stating plainly: [[12]] is literal text on GitHub, where the filename form renders. Both work, so the choice is the author's - a reference reads better and cannot rot, a file link survives outside this tool. This log's six existing cross-links were converted.

The parser hands it over in pieces

The first attempt did the expansion on parsed events, which is where the existing link rewriting happens, and produced nothing at all. A markdown parser reads [[12]] as nested bracket tokens - an unresolved shortcut reference inside another pair of brackets - so the text arrives as several runs and [[ is never present in one of them to match on. The compiler said only that the function was never called.

So it happens on the source instead, before parsing, and emits [12](cairns:12 "title"). The scheme is resolved by the same function that resolves every other link, so a reference and a written-out link reach the same place by the same code rather than by two implementations that agree today.

Code has to be left alone

The spec pages show [[area]] and [[publish]] in fenced TOML, and the page documenting this syntax has to be able to print [[12]] without linking it. The scanner tracks fences and inline backticks, and the same scanner serves both the rewriter and check, so what gets linked and what gets validated cannot disagree.

Requiring digits would have protected [[area]] by accident. The code rules make it a guarantee.

Two things that were wrong about themselves

A test asserting that inline `[[1]]` produces no link counted two and failed. The second was the pager's "Previous" link, which points at entry 1 because entry 1 is the previous entry. The code was right and the assertion was too broad; it counts the reference form specifically now.

And the skill did not pick up the new section on the first init, because the template is embedded with include_str! and I ran the old binary. The template had changed, the file on disk was right, and the generated output was stale - which looks exactly like an edit that failed, and was not.

The tap is the repo

2026-09-20T00:00:00Z

A Homebrew tap does not need a repository of its own. brew tap takes an explicit URL, and any repo with a Formula/ directory in it is a tap:

brew tap Toyz/cairns https://github.com/Toyz/cairns
brew install cairns

The cost is that one command instead of brew install Toyz/tap/cairns - the short form resolves Toyz/cairns to Toyz/homebrew-cairns, which is why a dedicated tap is named that way. The gain is worth more than the keystrokes: the release workflow updates the formula in the repo it is already checked out in, with the token it already has. A separate tap needs a personal access token with write access to another repository, kept in a secret, which is a thing to create, store and eventually rotate.

Verified rather than assumed, because Homebrew 7 made two of my assumptions wrong on the way. brew audit <path> is disabled, and so is installing a formula from a path - "Homebrew requires formulae to be in a tap". So the test was a real tap pointed at this working copy, a real brew install, and running the binary it put on PATH:

$ brew tap Toyz/cairns "$(pwd)"
$ brew install Toyz/cairns/cairns
$ cairns --version
cairns 0.3.0

It also settled a detail I would otherwise have guessed at: each archive holds one top-level directory, and Homebrew enters it before running install, so the binary is cairns and not cairns-v0.3.0-aarch64-apple-darwin/cairns.

The formula is generated, not edited

scripts/update-formula.sh writes the whole file from a tag and that release's SHA256SUMS. Four values change per release - a version and three digests - and a formula patched line by line drifts the moment a line moves. Today has supplied five separate demonstrations of that, so this one regenerates.

The release workflow runs it after the binaries are built and commits the result to main. A tag now updates the binaries, the checksums and the formula together, which is the only way the three stay in agreement.

An entry that says nothing about what it does not know

2026-09-20T00:00:00Z

Hellbender's entry 60 asks whether check should refuse an entry with no **Still unknown:** line at all, rather than accepting a log that quietly stops collecting. It should, and the evidence in that entry settles it: twenty-six consecutive entries had dropped the line, cairns open had been reporting the project's state as of entry 33, and nothing complained for months, because a missing convention is not a broken one.

check now reports two faults it used to pass over:

worklog/0034-x.md: has no `**Still unknown:**` line - write `nothing` to close it out
worklog/0035-y.md: `**Still unknown:**` is empty - write `nothing` to close it out

The blank one matters as much as the missing one, and it was the easier of the two to get: cairns new writes the trailer into every entry it creates with nothing after it. An entry nobody filled in and an entry that deliberately closed out read identically to the collector, and only one of them meant it.

So the trailer has four states rather than two - missing, blank, closed, open - and only the last two are things a person decided.

Adoption does not fail on history

Turning this on would have failed hellbender before it was fixed, and fails amber now: 192 migrated entries, none with a trailer, because the format they came from had no such convention.

init writes the relaxation itself, the same way it freezes slugs:

$ cairns init
192 entries have no `**Still unknown:**` line - check relaxed to optional in cairns.toml
$ cairns check
ok

with a comment in cairns.toml saying to set it back once they carry one. The principle is the one adoption has followed throughout: preserve what is there, hold what is written from here on to the better standard. A tool that makes a project fix its history before it can be used is a tool nobody adopts.

A field carried all the way through and shown nowhere

2026-09-20T00:00:00Z

files is in the spec as "paths the entry is about". cairns new --files writes it, the parser reads it, log.json exports it, and every one of this log's entries has one. The site rendered it nowhere at all.

It had passed through the entire pipeline without ever arriving anywhere a reader could see it, which is why nothing caught it: there is no test for "appears on the page", and the field was present at every point anyone checked.

It sits under the dateline now, each path linked into the repository through the same resolution the prose uses - so an entry about a bug in html.rs is one click from html.rs.

The general shape is worth naming, because this project has hit it twice today: a field can be parsed, validated, exported and still be dead, and none of parsing, validating or exporting will tell you. The other was the traffic-light status badge, which rendered but looked like a different website. Both needed somebody to look at the page.

Two install instructions that were not true

2026-09-20T00:00:00Z

The README said:

cargo install cairns                    # from crates.io
brew install Toyz/tap/cairns            # macOS and Linux

Neither works. cairns is not on crates.io - the publish job is deliberately gated behind a repository variable nobody has set - and Toyz/homebrew-tap does not exist. Both return 404. I wrote them while writing the release plumbing, describing what the plumbing would make possible, and never came back to check whether it had.

That is the same failure as everything else today: stating a thing is so because I arranged for it to be possible, rather than because I watched it happen. A false install line is worse than most, because the person who finds out is a stranger who wanted to try the tool and now thinks it is broken.

The README now offers the two that were tested:

curl -fsSL .../install.sh | sh
cargo install --git https://github.com/Toyz/cairns cairns

The second was run before it was written down. It works, and it reports its version as 0.0.0-dev, because the repo never claims a release number - the tag does, and CI applies it to the working tree only. The binary is right and --version is uninformative, which is a real cost of that design and is now written next to the command rather than left to be discovered.

Hellbender's own docs tree crashed the renderer

2026-09-20T00:00:00Z

Enabling cairns on hellbender - the repo the format came from - took a cairns.toml and one init, which froze thirteen slugs and left the hand-written skill alone because it carries no marker. Then build died:

thread 'main' has overflowed its stack
fatal runtime error: stack overflow, aborting

Three faults, none of which this repo's own docs tree could have shown, because this repo's docs tree is one directory with a README in it.

The docs root is its own parent

docs/README.md is the index of docs/, so its slug is the directory it names - which at the root is the empty string. Its section is the directory above it, which at the root is also the empty string. The tree renderer asked for the folders inside a section, got a folder whose slug was that section, recursed into it, and asked the same question again.

Two lines guard it now, and the regression test renders a tree with a root README: a regression there is a crash, not a failed assertion.

The test earned itself immediately. It caught a second fault I had already convinced myself was fixed - docs//index.html, the root README being given a page of its own as well as being the index. The build "worked" and wrote 88 files; I counted the files and did not read them.

The rail was empty on the one repo that needed it

Folders were derived from index pages, so a directory without a README was not a folder and its pages belonged to a section that did not exist. Hellbender has four such directories - formats, engine, content, port - and every page in them. Its reference rail rendered a heading and nothing else.

Folders come from the directories themselves now. One with its own page is a link to it; one without is a label. Deriving structure from what a project happens to have written is how you get a tree that is empty for the projects with the most in them.

`worklog: 7 to 20`

docs/port/plan.md cites a range. The spec said comma-separated numbers, so check rejected it, correctly and uselessly - a page established over a run of entries is naturally written that way, and hellbender's was, years before this tool existed. 7 to 20 and 7-20 both expand now, inclusive.

The alternative was editing their page to match the parser. The parser was wrong about what people write.

Working blind, and the render loop I should have had first

2026-09-20T00:00:00Z

Four rounds of "still cramped", "so fucking tacky", "the page is too thin", before the accurate version of the complaint arrived: you're not even using a headless browser, you're throwing shit at a wall.

That was exactly right. Every CSS change in this project had been written, compiled, verified by grepping the rendered HTML for class names, and handed to a person to look at. I was using the reader as the render loop. Everything I called verification - the page returns 200, the tags close, the rule is in the stylesheet - tests that the bytes are what I wrote, never that the result looks like anything.

It is also how 12 went unnoticed. Half a stylesheet was missing and every check I had still passed, because a stylesheet with its middle deleted is a valid stylesheet.

The loop

Headless Edge is already on this machine:

"$EDGE" --headless --disable-gpu --hide-scrollbars \
  --window-size=1440,1700 --virtual-time-budget=2500 \
  --screenshot=/tmp/shot.png http://127.0.0.1:8899/

Three seconds a shot, against cairns serve. The first screenshot answered the question four rounds of guessing had not: the page had no structure at all. A flat column on a flat ground, a small masthead lost at the top, controls floating unattached above an undifferentiated list. Not "cramped" - empty, in the way a page with nothing holding it together is empty.

What it became

A rail and a column. The rail is sticky and carries the identity, the navigation with the current page marked, and - where they belong - the area filters, as a facet list with counts rather than a stack of pills that looked like form fields. The column is the same width on every page.

The reference section gets the same treatment: the docs tree in the rail, folders naming themselves and indenting what is inside them, the current page marked. A docs section whose only navigation is an index you have to go back to is a docs section nobody navigates.

Entry rows became one target rather than a title-sized one, with the number legible in a left gutter instead of buried in the meta line. Search stopped being an outlined box with a segmented control bolted beside it and became a filled field with an icon, and two words you can click.

None of those were ideas I could have had from the source. Each one was obvious within a second of looking at a picture.

Three CSS edits, three wrong anchors, and half a stylesheet gone

2026-09-20T00:00:00Z

The layout work was a run of small fixes - one page width everywhere, a simpler entry list, one hover effect instead of three, a one-line footer, the contents list moved out of the flow. Each was correct. The way I was making them was not.

I was editing by locating a marker string and splicing around it. That failed three times in a row, in two different ways.

In Rust, cargo fmt moved the target. A block I had read as one line came back as six, so the marker no longer matched and the edit silently did nothing - log.rs, entry.rs and serve.rs all went through a compile error that only said a later name was missing.

In CSS, I assumed document order and was wrong. The edit took everything between .toc { and a marker far below it. .toc had been inserted near the top of the file, so the splice removed 194 lines in between: the masthead, the nav, the chips, the sort control, the status line and the whole entry list. The page still rendered. It rendered with nav links run together, a default blue link where the title should be and bare text where the pills should be, which is what a stylesheet missing its middle looks like.

Nothing caught it. It compiled, the tests passed, check passed, every page returned 200 and every page validated - because a stylesheet that is missing half its rules is still a valid stylesheet. It took a person looking at the screen, which is the third time in this session that has been the thing that found the bug.

It happened a fourth time before the entry was finished. The resolves validation in problems() was written, missed its anchor, and never landed - and in the meantime I said in conversation that check rejected an invalid resolves, which it did not. The code compiled, the tests passed, and the claim was simply wrong. The last edit was made by line position after reading the file, and the validation now has tests of its own.

The stylesheet was rewritten whole rather than patched back, and each section asserted present afterwards.

The lesson is about method, not CSS. An edit that deletes a region has to verify the region first, and a marker-based splice does not - it silently does the wrong thing when the file is not shaped the way it was last read. Replacing an exact known string is safe because a miss is a no-op; splicing between two indices is not, because a miss is a deletion.

The log's own links were dead on its own site

2026-09-20T00:00:00Z

The skill tells you to correct an earlier entry by linking to it:

[[12]]

That is right in the repo and right on GitHub. On the generated site it is a 404, because there is no .md file there - an entry is a directory named for its number and its slug. Every cross-entry link in this log, which is the convention the format exists to encourage, was broken on the thing built to show the format off:

$ curl -o /dev/null -w '%{http_code}' .../7-migrate/0004-the-write-path.md
404

The fix is translation rather than a new convention. A link whose filename parses as NNNN- and matches an entry becomes that entry's page; anything else relative is a file in the repository and points there. Both spellings stay correct where they already were.

Two things fell out of doing it properly. A relative link inside an entry is relative to the entries directory, so ../docs/spec/entry.md is docs/spec/entry.md at the repository root - the first attempt pasted the ../ into the URL and produced github.com/Toyz/cairns/blob/HEAD/../docs/spec/entry.md. And the feed carries the same prose with no page to resolve a relative link against, so entry links render absolute there and relative on the site.

Why this went unnoticed

Every page returned 200 and every page validated. The broken thing was a link inside rendered prose, which nothing checks - not check, which reads front matter, and not the HTML validation, which only asks whether tags close.

A link checker over the rendered site would have caught it in a second, and there is still no such check. That is the gap, rather than the bug.

A question can be answered, not just a claim overturned

2026-09-20T00:00:00Z

Asked what happens when a later entry answers an earlier one's open question, and the answer was: nothing. The question stayed on the open list forever. The log could record that a claim had been overturned and could not record that a question had been closed, which are different things and only one of them had a field.

resolves is that field.

---
number: 7
resolves: 6
---

It is deliberately not supersedes. An entry that answers a question another entry left open has not shown that entry to be wrong - it closed something that entry opened. Folding the two together would lose the distinction that makes either of them worth recording at all.

A question with a resolves pointing at it leaves open_questions, so that list is what the project does not yet know rather than everything it has ever wondered. It stays on the entry that asked it, struck through, naming what closed it, because the fact that it was once open is part of the record.

check rejects a resolves aimed at an entry that left no question open. That is almost always a wrong number, and nothing else in the tool would notice it.

The one real case, backfilled

6 ended asking whether client-side search stays sensible as a log grows. 7 measured it at 192 entries and answered it. The field did not exist when 7 was written, so resolves: 6 was added to it afterwards.

Worth saying out loud, because the log is append-only: that is a metadata addition to front matter, not an edit to anything 7 claims. The prose is untouched. Had the correction been to a sentence rather than a field, the rule would have required a new entry instead.

The viewer felt cheap, and the filters had never worked

2026-09-20T00:00:00Z

Three rounds of "still cramped" before the actual problem was named: it felt cheap. That is a different complaint from a spacing one, and spacing is all I had been adjusting. A page with no identity reads as a default HTML list because that is exactly what it was.

A direction, rather than another nudge

A worklog is a lab notebook: numbered, dated, written in prose, read slowly. So the page is set like one. Prose and titles are a serif; the chrome - nav, chips, meta, code - is a sans; the entry number is large and quiet in the gutter and is the one piece of furniture on every page. The ground is warm paper rather than white, and the accent is a rust that marks the things a notebook marks: a correction, the open question at the foot of an entry, the section you are in.

No webfonts. The stacks resolve to something good without a request, because a log that only looks right online is a log that does not look right.

The measurements that changed, after two passes that did not:

              first     second    now
base type     16px      17px      17px, prose in a serif
entry title   17px      19px      22px
summary       14px      16px      17px
index width   704px     768px     992px
reading width 704px     592px     704px, with the contents list beside it

The width was the part I kept getting wrong in both directions. An index and a reading column want different things, and giving them one number makes one of them wrong. The index is wide and puts the date and areas in their own column on the right; an entry page is a reading column with its contents list in the margin.

The filters had never worked, and said nothing

.entries li { display: flex; }

The filter code sets hidden on a row. The browser's own [hidden] { display: none } is one class less specific than .entries li, so every hidden row kept its display: flex and stayed on screen. Clicking an area chip updated the button, updated the URL, updated the count in the status line, and changed nothing visible.

I introduced it in the same pass that made rows flex, which is worth saying plainly: the redesign broke a feature that had worked, and no test, no build and no console message registered it. It took a person clicking one.

[hidden] { display: none !important; } sits above every display rule now, with a comment saying why, because the next layout change would do it again.

A contents list, and pages that reload themselves

Entries run to several ## sections - hellbender's 55 carry 143 between them - and there was no way to move around inside one. Headings now get anchors, and an entry with more than one section gets a contents list: sticky in the margin on a wide screen, above the prose on a narrow one, with subsections nested.

cairns serve was already rebuilding when an entry changed, but the browser had no way to find out, so it meant nothing without a manual refresh. Pages served by it now poll a counter and reload when it moves. Polling rather than an event stream, because the server is single-threaded on purpose and one held-open stream is a server answering nothing else. The script is injected on the way out and is never in what build writes - checked by a test, since a production site quietly polling a dead endpoint would be a nasty thing to ship.

Distribution, and a worklog a model can read

2026-09-20T00:00:00Z

Two things that both amount to the same question - who can get at this - and one correction to work done earlier in the day.

The binary

CI runs fmt, clippy with -D warnings, the tests, and cairns check against this repo's own log, so the tool is held to the standard it holds everyone else to. A second job builds on the declared MSRV, 1.88, which is what let-chains in config.rs cost. Tagging cuts binaries for five targets - macOS on both architectures, Linux gnu and musl, Windows - with a SHA256SUMS beside them, and there is a Homebrew formula template in packaging/.

cargo publish --dry-run passes, and the packaged crates carry what they need: the binary's templates/SKILL.md, the site crate's CSS and JS.

The actions were years out of date

Every workflow was written against the versions in my head, and every one was several majors behind:

	written	current
`actions/checkout`	v4	v7
`actions/upload-artifact`	v4	v7
`actions/download-artifact`	v4	v8
`actions/upload-pages-artifact`	v3	v5
`actions/deploy-pages`	v4	v5
`softprops/action-gh-release`	v2	v3

Bumping a major is not the same as bumping a number, so each one's action.yml was read at the new tag to confirm the inputs still exist - merge-multiple, path, files, generate_release_notes, the page_url output. They all do. The workflows themselves have not been run; they are eyeballed YAML until a push proves otherwise.

Installing without a toolchain

install.sh picks the target from uname, resolves the latest tag from the API unless CAIRNS_VERSION says otherwise, and - the part that matters in anything piped to a shell - checks the download against the release's SHA256SUMS before unpacking it. On Linux it prefers the gnu build and falls back to musl where there is no glibc.

Tested against a fake release served locally, because a script nobody has run is a script that does not work:

good checksum      -> installed, `cairns --version` runs
tampered archive   -> "checksum mismatch", exit 1, nothing installed
missing from sums  -> "not listed in SHA256SUMS", exit 1

The tag is the version

Cargo.toml says 0.0.0-dev and never says anything else. Pushing v0.2.0 makes scripts/version-from-tag.sh rewrite the workspace version in the runner's working tree, and nothing is committed - so there is no file to remember to bump, and no way for a tag and a manifest to disagree about what a release is.

The rewrite replaces the exact current version string, which appears as the workspace version and as the pin on each path dependency and nowhere else, so serde = { version = "1" } is untouched. cargo update --workspace then moves only the workspace members in the lockfile, which leaves --locked meaning what it meant. Checked locally by running it for v1.2.3, building, and confirming the binary says cairns 1.2.3.

Publishing to crates.io stays off behind a repository variable. A tag that cuts binaries is a small mistake to make; a tag that publishes a crate version that can never be reused is not.

MCP

cairns mcp speaks JSON-RPC 2.0 over stdin and stdout. Read-only by default: tools for listing, reading, searching, open questions and check, and resources at worklog://entry/50, worklog://open, worklog://index and worklog://log.json. --write adds one tool for writing an entry, and its schema enumerates only the areas the project declares, so a model cannot invent one.

It is hand-rolled rather than taken from rmcp. The surface used here is small and synchronous and wants no async runtime; the cost is that protocol drift is ours. One hedge against that: initialize echoes back whatever protocolVersion the client asked for rather than insisting on a known one, because nothing in this server's tools or resources has ever differed between versions and refusing a newer client would break a host for no gain.

Driven with a real client, writing through it produces an entry indistinguishable from one the CLI wrote, supersedes and all - and reading the entry it corrects immediately says so:

worklog_read 47  ->  NOTE: something claimed here was corrected by entry 56.

The reason this was half a day rather than a week is a decision from 1: the core has no filesystem in its API and log.json is already the canonical serialisation, so the server is a transport over a document that existed, not new logic.

Worth being plain about where it does not help. In a host with a shell it adds nothing - the skill init writes teaches the CLI, and every entry in this log was written that way. MCP is for the host that has no terminal.

Migrate, and the backup that never fired

2026-09-20T00:00:00Z

migrate splits a single-file worklog on its ## headings, takes the number and title from each, demotes the sub-headings one level - the old format made the entry title an h2 and its sections h3, the new one makes the title the h1 - and writes one file per entry.

Amber's log is the real test: 9,727 lines, 192 entries, all numbered.

$ cairns migrate WORKLOG.md --date 2026-08-01
kept the original as .../WORKLOG.md.bak
192 entries -> worklog
192 entries -> WORKLOG.md
every entry is dated 2026-08-01 and filed under "port" - the old format
carried neither, so both want correcting by hand
4 entries have a "not done" section that should become a `**Still unknown:**`
trailer

Fidelity checks exactly: 7,329 non-blank prose lines in the original outside its headings, 7,329 across the 192 entries, and the two lists are identical once the ### demotion is applied. Nothing was reflowed, reordered or dropped.

What cannot be recovered is what the old format never held. Every entry gets one date and one area, which is a lie of uniformity rather than a loss - but it is visible, it is reported, and it is correctable by hand.

The backup never fired, and the original was destroyed

The first run printed no backup line and left this:

WORKLOG.md   9,727 lines  ->  202 lines

The migration wrote 192 entries correctly and then index regenerated WORKLOG.md over the top of the file it had just read. The guard meant to prevent that was:

if from == root.join(&config.paths.index) {

from is the path as typed - WORKLOG.md, relative. root.join(...) is absolute. The comparison is always false, so the backup branch was dead code and nothing said so. In the test clone the original came back out of git. In a repo where the log had uncommitted edits, it would not have.

This is the same shape as the init bug in 4: a command whose job is to help a project adopt the tool, destroying the thing it was adopting, and saying nothing. Twice now, which makes it a pattern rather than an accident - both times the destructive path was the one no test covered, because both were about a file the tool did not create.

The fix resolves both paths before anything is written, refuses if a .bak is already there, and treats a failed copy as a reason to stop rather than a warning to print on the way past.

What 192 entries cost

build       0.095s
site        2.5 MB, 199 files
index.html  63 KB raw / 17 KB gzipped
search.json 468 KB raw / 159 KB gzipped
log.json    582 KB raw / 193 KB gzipped

That answers most of what 6 left open about client-side search. Fetched once, lazily, over a host that serves gzip, 159 KB is unremarkable. Linear growth puts a 500-entry log around 410 KB gzipped, which is where a real index rather than a string scan starts to be worth it - so the answer is "fine, and the number to watch is 500".

The log reads as a website, and the feed is not the whole log

2026-09-20T00:00:00Z

cairns build renders the payload: an entry page each with prev/next and clean URLs, an index with area chips and a search box, an open-questions page, an Atom feed, a search index, and the log.json all of it was built from. The renderer consumes that document and nothing else - it never opens an entry file - which is what keeps a publish target and a local build the same code path.

Against hellbender's 55 entries: 57 pages, all of which parse with no unclosed or stray tags, 74 code blocks and 143 sub-headings rendered, 33 open questions collected, 1.2 MB total.

The correction notice works, once there is a correction to show

Hellbender has no supersedes edges, so the feature had nothing to render. Backfilling the one entry 2 identified - supersedes: 6 on entry 50, which overturns what entry 6 said about KREASH.MIX - produced both halves:

entry 6   Revisited later. Something claimed here was corrected by
          KREASH.MIX is the end of a table.
entry 50  This entry revisits Raw images have no header, and the filename
          carries the video mode.

A reader landing on entry 6 from a search is now told, above the prose, that part of it is wrong. That is the entire argument for an append-only log being safe to read, and it costs one line of front matter per correction.

Two things the real log changed

The feed was 263 KB. Carrying all 55 entries at full content makes a feed that no reader wants and that is slower to fetch than the site. It is capped at the newest 25 now, with a rel="alternate" link to log.json for anything that wants all of it. The distinction is worth stating plainly, because the spec had been sloppy about it: the feed is for reading, log.json is the complete document and the thing to ingest.

Raw markdown was leaking into link previews. An entry's summary is derived from its first sentence, and that sentence contains markup:

og:description: "`.RAW` is 8-bit indexed pixels, top to bottom, ..."

Backticks in a link preview look like a bug because they are one. Summaries are reduced to their text now wherever markup would be shown literally rather than rendered - the meta tags, the feed summaries, the index blurbs.

Publishing, and what is honestly not built

The dir target works, and the incremental comparison does what it was specified to do. Editing one entry:

$ cairns publish --target site --dry-run
changed: 53
54 unchanged

The manifest is the log.json already sitting at the destination, so there is no state file in the working tree to go stale.

The reserved http target earns its place already:

$ cairns publish --target hosted --dry-run
POST https://example.invalid/ingest
content-type: application/json
authorization: Bearer $(CAIRNS_TOKEN)
content-length: 264869

That is a real ingest request, from a real log, with no server anywhere. Run without --dry-run it refuses rather than pretending.

git-branch is not built, and publish.md claimed it was - written when the spec was describing intentions rather than code. It is marked reserved now. A CI job that runs build and hands the directory to the host's own deploy action does the same work without this tool force-pushing anything, which is both safer and what most projects already have; the workflow is in the spec and in this repo.

A test that was wrong about the code

One renderer test asserted an entry's prose appears once on its page. It appears three times, and the code is right: the derived summary lands in description and og:description as well as the article. The assertion now checks the rendered paragraph and the meta tag separately. Worth recording because the first instinct on a red test here was to go looking for a duplication bug that was never there.

The command was stricter than the format

2026-09-20T00:00:00Z

Asked whether an entry can sit in more than one area, the honest answer was yes

and then --area "decomp, engine" turned out to be rejected while --area decomp,engine worked.

The spec is explicit that both spellings are read: hellbender's log carries 31 entries written format, tooling and 19 written decomp,format, and entry.md says a reader accepts either. The front matter parser does. The command that writes front matter did not, because clap's value_delimiter splits on the comma without trimming, so the second area arrived as " engine" and failed the area check against a name that has no space in it.

Both halves were behaving as written. The bug is that they were written to different rules, and only one of them was the spec. A command that writes a file has no business being stricter than the one that reads it - the asymmetry is invisible until someone types the more natural spelling, and then it reads as the format being fussy rather than the tool being inconsistent.

Values are now split and trimmed on the way in, for --area and --files alike, and all three spellings produce the same line:

--area decomp,engine        -> area: decomp, engine
--area "decomp, engine"     -> area: decomp, engine
--area " decomp , engine "  -> area: decomp, engine

The question was really about the documentation

The prose in the skill said several areas may be given. Every example showed one - the cairns new line, and the front matter block in the entry format. Prose under a single-area example does not answer the question the example raises, which is why the question was asked at all.

Both examples now carry two areas, generated from the project's own first two, and the sentence saying so sits directly under the command rather than below the table. The typed form and the written form differ by a space, which the example now shows rather than explains.

The write path, and an init that nearly ate hellbender's skill

2026-09-20T00:00:00Z

new, init and the skill template close the write path. new refuses an area cairns.toml does not declare - naming the ones it does, since the useful part of that error is the list - and regenerates the index on the way out, so the index is never stale in the window between creating an entry and remembering to run index.

This entry was created with it.

Dates, in two places for one reason

cairns-core computes a civil date from a Unix timestamp with Howard Hinnant's civil_from_days, about ten lines, which keeps the crate dependency-free and wasm32-clean. The binary does not use it for new: it asks jiff for the local date, because an entry written at eleven at night should not be dated tomorrow, and getting a local date right means timezone data the core has no business carrying.

The arithmetic was tested against the epoch, a leap day, and an arbitrary timestamp. The arbitrary one failed - and the code was right, the expectation was wrong. Worth recording only because the reflex on a red test is to look at the code, and the leap day passing first time was the signal that the conversion was sound.

init froze hellbender's slugs, exactly as entry 2 asked

Adoption on a clean clone, with its fifteen areas declared:

$ cairns check          # before
... 13 problems
$ cairns init
froze 13 slugs - these entries keep the names they were published under
$ cairns check          # after
ok

Each of the thirteen gained a slug: line pinning the name it was published under, so the two entries whose titles had drifted and the eleven cut mid-word by the old 60-character rule all keep their URLs. New entries get the better derivation. Adoption preserves rather than improves, which is the only way it can be safe.

It also destroyed the thing it was adopting

The first working init rewrote .claude/skills/worklog/SKILL.md - 58 lines deleted - and hellbender's skill is not a generated file. It carries the rules that make that log what it is: every claim locatable by a VA against HELLBEND.EXE at 0x00400000, a format entry unfinished until the matching docs/formats/ page exists. All of it gone, in a command whose entire purpose is to help a project adopt the tool.

Worse, it announced the opposite:

wrote .claude/skills/worklog/SKILL.md (project section preserved)

The flag behind that message was "a file was already here", not "its project section survived". Two separate failures - a destructive default, and a message asserting the thing that had just not happened - and the second is the one that would have let it go unnoticed, because the output read like success.

init now leaves an existing skill alone unless it carries the  marker, and says why:

kept .claude/skills/worklog/SKILL.md - it has no <!-- cairns:project --> marker.
Everything below that marker is what init preserves, so put it above the parts
this project wrote and run init again.

With the marker added, regeneration rewrites the generic half from the template with the project's own areas in it and returns the project section verbatim. Both paths are now checked against a fresh hellbender clone.

The general rule this is an instance of: a command that writes into a repo it did not create must default to refusing, not to overwriting, and must never describe what it wishes it had done.

The index generates, and hellbender's own index proves it

2026-09-20T00:00:00Z

index was parked with the rest of the write path, which left a hole nobody had looked at: check passed on this repo while it had no WORKLOG.md at all. The Python tool would have failed that - comparing the index against a fresh render is one of the four things its check did. A check that is quiet about the artifact most likely to be wrong is worse than no check, because it is believed.

So the index renders now, and check compares:

$ cairns check
WORKLOG.md is stale - run `cairns index`

Missing and stale are reported separately. They have different causes - one is a repo that never ran the command, the other is entries edited since it last did - and a reader who sees the right one does not have to work out which.

The header is the only part a project writes

Everything in the index is derived except its opening prose, which is [index] header in cairns.toml. The generated default names the project and says the file is generated; a project that wants to explain what its log is for says it better than any generated sentence.

The area tally is sorted alphabetically rather than in declared order. The areas themselves are presented in declared order everywhere else, because that ordering is a taxonomy the project chose - but a tally is a lookup, and a lookup reads better sorted by the name you are looking for.

The parity test

The acceptance test for the port was always going to be hellbender's own index: render its 55 entries and diff against the file in the repo. With its header copied into [index] header:

$ diff committed.md WORKLOG.md | grep -c '^<'
27
$ sed 's/,\([a-z]\)/, \1/g' committed.md | diff - WORKLOG.md | grep -c '^[<>]'
0

27 of 55 rows differ, and every one of them differs only in the area column, where decomp,engine becomes decomp, engine. Normalise that one spelling and the two files are byte-identical: same header, same tally, same 55 rows, same titles, dates, paths and pipe escaping.

That is the whole intended delta. The log had accumulated both spellings because the old index printed whichever string the entry happened to carry, and normalising on write is the documented fix. Worth knowing precisely, though, because it means adopting cairns costs hellbender exactly one reflow commit on one column - not a migration.

What hellbender's own log said about the spec

2026-09-20T00:00:00Z

The spec was written against hellbender's log, so the first thing worth knowing is whether it actually reads it. Pointed at a fresh clone with a cairns.toml declaring the fifteen areas the Python tool hard-coded, all 55 entries parsed: no front matter errors, no unknown areas, no repeated numbers, and every area field read despite the log using both format, tooling and decomp,format spellings across it.

content_hash verified from outside the tool, which is the property it was specified for:

$ cairns export --reproducible -o log.json          # entry 50
  content_hash: sha256:40db750a77e9ed60d1b0e242a409751a63f93d0e91e8b9570d0c2e8a72ff6f20
$ shasum -a 256 worklog/0050-kreash-mix-is-the-end-of-a-table.md
  40db750a77e9ed60d1b0e242a409751a63f93d0e91e8b9570d0c2e8a72ff6f20

33 of the 55 entries carry an unresolved **Still unknown:** trailer, so the open-questions page has something real to show on day one rather than being a feature waiting for a habit to form.

Two entries had drifted, and nothing had noticed

check compares an entry's filename against the slug its title derives, which the Python tool never did - it only checked the four-digit prefix. Two entries fail it for reasons that are not about slug rules at all:

0035-powerups-and-the-sprite-models.md
  title: Powerups, and the sprite models they are drawn with

0037-the-players-guns-and-the-energy-that-feeds-them.md
  title: The player's guns, and the energy that feeds them

Both had their titles edited after the file was created. Harmless while the filename is only a filename. Not harmless once it is a URL, which is the argument for the slug: field: identity is the slug, the filename follows it, and a title can be tidied afterwards without breaking a link.

Adoption is not free, and that is the useful finding

Eleven more entries fail the same check for a different reason: the slug is now cut back to a word boundary rather than at exactly 60 characters, so ...-the-picture-foun becomes ...-the-picture. Better names, but every existing project adopting cairns would see its files want renaming, and any already-published link would break.

So adoption has to freeze what exists rather than improve it. init against a log that already has entries should write an explicit slug: into every entry whose filename disagrees with its title, pinning the URLs that were already handed out, and leave the better derivation for entries written from then on. That is a real change to what init does, and it was not in the plan before running this.

One more gap: no entry uses supersedes, because the field is new - yet entry 50 exists specifically to overturn a claim entry 6 made about KREASH.MIX, and says so in prose. The link is in the log already, just not in a form anything can read. Backfilling those during migration is worth doing by hand; there are not many, and they are the most valuable edges in the graph.

The log found a bug in the log

Writing this entry broke the parser that reads it. The paragraph above mentions the open-question marker in prose, and the trailer was found with an unanchored search for the literal, so entry 2's open question came out as the tail of a sentence about entry counts. The marker now has to begin a line, and where several qualify the last one is the trailer - which is what the spec should have said in the first place, because any log written about this format will mention the marker constantly.

Two entries in, dogfooding has paid for itself.

The format is the asset, so the spec is written down first

2026-09-20T00:00:00Z

The worklog format grew up inside hellbender as tools/worklog.py plus a skill, and it works - 55 entries, a generated index, numbering that holds. What it could not do is leave that repo. Three things were tangled in the one skill file: the format, the tool, and fifteen hard-coded areas, several of them specific to one 1996 game. Only the first of those is worth sharing, so this project separates them and writes the format down as a spec under docs/spec/ before implementing any of it.

The tool is one implementation. A worklog whose tooling is lost is still a worklog, which is the whole reason the markdown stays the source of truth and nothing here needs a database.

What got decided

Rust, one binary. The original is 200 lines of Python and the port buys nothing on its own; it buys distribution. Anyone handed a binary runs it, and the core compiles to wasm32 with --no-default-features, which is what keeps a future hosted version a deployment rather than a rewrite.

The static site renders from log.json, not from the markdown. One path from entries to structured data, so a second reader can never disagree with the first about something subtle in an output nobody is looking at. It also means an ingest contract can be designed against real payloads before any server exists - publish --target hosted --dry-run prints the request body today.

Front matter is not YAML. It is a strict key: value subset, defined in entry.md, with no quoting, nesting, blocks or comments. A real YAML parser reads it correctly, but that is a convenience rather than a promise. The subset has exactly one reading and cannot grow ambiguity, which matters more for a file format meant to be legible in twenty years than nesting nobody needs.

An entry's id is {project}/{number}, not the number. Costs one line of config now; retrofitting it invalidates every URL already handed out the moment two projects sit in one place.

content_hash is the SHA-256 of the file's bytes, so it verifies with shasum -a 256 and no knowledge of this format at all. It is what lets a publish send only what changed, and it works identically for a local directory and for an ingest endpoint that does not exist yet.

No secrets in cairns.toml. A token must be an environment variable reference beginning with $, and check fails on a literal - catching the leak in the commit that introduces it rather than after the push.

What is built

cairns-core parses and validates entries and builds the canonical document. cairns-site renders a payload from it, which today is log.json alone. The command surface is settled - new, next, index, check, open, build, export, publish, init, migrate - and the read half of it works. The write half is the parity port, and it is not built yet.

cairns

An entry written in one command, prose on stdin

One way for the trailer to arrive

The MCP tool

Areas in one line each and files that fold

[area] as one table

Files, grouped and folded

A config section the binary had never heard of

The one that matters

Serve prints its version now

Links the generated nav could never know about

Ten icons, inline

One plus-minus sign crashed the scanner

What the tests missed and why

The rest of the codebase, checked

References, and a parser that reads them in pieces

The parser hands it over in pieces

Code has to be left alone

Two things that were wrong about themselves

The tap is the repo

The formula is generated, not edited

An entry that says nothing about what it does not know

Adoption does not fail on history

A field carried all the way through and shown nowhere

Two install instructions that were not true

Hellbender's own docs tree crashed the renderer

The docs root is its own parent

The rail was empty on the one repo that needed it

worklog: 7 to 20

Working blind, and the render loop I should have had first

The loop

What it became

Three CSS edits, three wrong anchors, and half a stylesheet gone

The log's own links were dead on its own site

Why this went unnoticed

A question can be answered, not just a claim overturned

The one real case, backfilled

The viewer felt cheap, and the filters had never worked

A direction, rather than another nudge

The filters had never worked, and said nothing

A contents list, and pages that reload themselves

Distribution, and a worklog a model can read

The binary

The actions were years out of date

Installing without a toolchain

The tag is the version

MCP

Migrate, and the backup that never fired

The backup never fired, and the original was destroyed

What 192 entries cost

The log reads as a website, and the feed is not the whole log

The correction notice works, once there is a correction to show

Two things the real log changed

Publishing, and what is honestly not built

A test that was wrong about the code

The command was stricter than the format

The question was really about the documentation

The write path, and an init that nearly ate hellbender's skill

Dates, in two places for one reason

init froze hellbender's slugs, exactly as entry 2 asked

It also destroyed the thing it was adopting

The index generates, and hellbender's own index proves it

The header is the only part a project writes

The parity test

What hellbender's own log said about the spec

Two entries had drifted, and nothing had noticed

Adoption is not free, and that is the useful finding

The log found a bug in the log

The format is the asset, so the spec is written down first

What got decided

What is built

`[area]` as one table

`worklog: 7 to 20`