improvise/context/code/doc-site.md

The documentation site — the arguments

scripts/build-doc-site.mjs turns the prose in context/ into the static site served at /docs/ on GitHub Pages. This is the reasoning behind what it publishes, what it deliberately does not, and why it is a hundred-odd lines of node rather than a static site generator (improvise-djoo).

---

1. What is published, and what is not

The manifest is the SECTIONS array at the top of the script, and a document is published only by being named there. That is the point: a glob over context/** would publish the next working file somebody drops in, and the decision about what a stranger should read is not one to make by accident.

Published, in four sections:

Section	Contents	Why
Start here	docs/design-notes.md, context/design-principles.md, context/repo-map.md	What the project is for, the doctrine, and the single best explanation of how it is built.
Decision records	context/adr/*.md	An ADR is written for an outside reader by construction — it states the options that were rejected, which is the part that is worth reading and the part that is nowhere else.
The arguments, by area	context/code/*.md	This is the reasoning that used to live in code comments and was moved out under the two-line cap (design-principles §6). It is the most valuable prose in the repository and it is addressed to exactly the reader a documentation site has.
Test evidence	context/test-evidence/*.md	501 entries, one per test whose narrative is longer than its code.

Not published:

• context/plan.md is a prompt: it opens "You are working in the improvise repository… Your job is to prepare this repository for a public Show HN launch", and it instructs a reader to audit a context/SPEC.md that no longer exists. It is an instruction to an agent about a launch, not a description of the program, and publishing a launch plan on the site the launch points at inverts the two.
• context/cloud-agents.md is operational notes for agents running in a cloud session — tracker hydration, bd pitfalls, what the sandbox blocks. It is true and it is useful and it is addressed to nobody who visits a website.

Neither is referenced by any published document except as a row in repo-map.md's file inventory, which is inside a code fence, so leaving them out creates no dangling link. That was checked rather than assumed.

Test evidence is the one judgement call worth stating. The argument for leaving it out is that 501 entries about individual tests are noise to a reader who wanted to know what a pivot table is. The argument for keeping it is stronger: every one of the seven context/code/*.md documents points at its evidence file by name, so omitting it would break the published prose in exactly the way this site is otherwise careful not to; and the evidence file is the most distinctive artefact the repository has — a written record of the injected fault behind each load-bearing test is not a thing most projects can show. It is therefore published as its own section, last, described as a contributor reference rather than a tour, so nobody wanders into it expecting a narrative.

2. Ticket ids resolve to a page, never to a URL that does not exist

The prose cites improvise-xxxx roughly 190 times. On a public site those are meaningless strings, and the obvious repair — link them to an issue tracker — is unavailable: beads keeps its issues in a Dolt database on a git ref, and there is no public issue URL to point at. Inventing one would produce 190 links that 404, which is worse than plain text because a link is a promise.

So the ids resolve inward. tickets.html is generated from .beads/issues.jsonl — already committed, already public — and carries id, status and title, nothing else; descriptions are internal working notes and are not the site's business. Each citation in the prose becomes a link to that page's anchor, with the title in a title= attribute so a hover answers the question without a navigation.

issues.jsonl is a passive export and lags the database, which is not a defect to work around but a fact to render honestly: an id the export does not carry is emitted as plain text with a dotted underline and no link, and the ticket page lists it as "not exported". The site therefore never links to an anchor it did not generate, whatever state the export is in. At the time of writing 8 of 178 linkified ids are in that state. A generator that instead linked every id it saw would produce a page that is right today and broken the first time somebody cites a fresh ticket.

3. Source paths link only where the file exists

A code span whose entire content is a repo path becomes a link — to the generated page when the path is one of the published documents, to GitHub otherwise. Two constraints make that safe. The whole span must be the path, so a sentence that merely mentions a directory is untouched; and the path must exist on disk at generation time, so a citation that has gone stale degrades to plain text rather than to a 404. The GitHub ref is the cache-bust token web/assemble.sh already receives, used only when it is a 40-hex sha and falling back to main otherwise — a local dev build must not emit blob/dev/….

4. The link check is the test, and it is part of the build

The generator collects every anchor it emits and every internal href it writes, resolves them against each other, and exits non-zero if any href names a page it did not generate or a fragment that page does not carry. web/assemble.sh runs under set -eu, so a broken cross-reference fails the assembly rather than shipping.

This is not ceremony. It caught two real defects on its first two runs: a fence-close regex that compared a three-character marker against a one-character string, which swallowed every document from its first code block onward; and a list parser that ended the gotcha list at the first blank line, so 47 of the 48 gotcha anchors were never emitted while the "jump to gotcha N" strip linked to all of them. Both were invisible in a rendered page that otherwise looked fine.

It is proved by injection rather than asserted: renaming the emitted anchor ids makes it report 48 missing anchors, and pointing the ticket links at a page name that is never generated makes it report 763 missing pages — two different diagnoses, because "the page is absent" and "the page is there but the anchor is not" call for different repairs.

What it does not cover is links that leave the docs/ subtree — the ones to ../index.html and ../app/. Those are checked against the assembled site/ tree by hand at the moment, and the honest statement is that a rename of the app directory would not be caught here.

5. Why a node script and not a generator

The landing page is hand-written HTML with no build step and one pinned CDN script; the same posture applies here. A static site generator would add a dependency tree, a lockfile and a toolchain to a repository whose site is currently four files, in exchange for features this corpus does not use — the docs contain no front matter, no shortcodes and, as it happens, not a single markdown link. Every cross-reference in them is prose naming a path or an id, which is precisely why §2 and §3 are the interesting parts and Markdown rendering is the boring part.

So the renderer is a deliberately small subset covering exactly what the corpus contains: ATX headings, fenced code, pipe tables, blockquotes, ordered and unordered lists with indented continuations, thematic breaks, and inline code, strong, emphasis and links. Anything it does not recognise becomes paragraph text, so no input line is ever dropped — the failure mode is an ugly paragraph, never a missing one.

Two details in it are load-bearing and easy to undo. Code spans are replaced by placeholders before emphasis is matched, because this corpus routinely opens ** on one side of a code span and closes it on the other; matching emphasis per segment silently drops that bold, which is a fidelity loss with no visible symptom. And strong is matched before emphasis, with a body that may contain a single * pair, because [^*]+ cannot match **a *b* c** and the leftover * then pairs across the bold — which is how a single sentence in gotcha 33 came out as three italic paragraphs.

6. Navigation

repo-map.md is one long document whose gotcha list is numbered 1 to 48, and splitting it per gotcha was rejected: the gotchas cross-reference each other constantly ("see gotcha 35", "for the reason gotcha 39 watches…"), and a reader following those wants a scroll, not 48 page loads. It stays one page, with an id on every list item and a compact strip of 48 numbered links under the heading. The ids come from the list item's own number, not from a counter, so an inserted gotcha renumbers the anchors exactly as it renumbers the prose that cites them.