The documentation of Spinbox, an Astro Starlight site. README.md is the catalogue: every check
the site keeps, and what each reads. This file is what the checks cannot say.
A page is generated from the code it describes, or held to it by a check, or it does not exist. Everything below follows from that.
- A page with
source:in its frontmatter is written bytask reference: everything undersrc/content/docs/reference/, and the pages that are a document of spin's or of the module's (spinDocsintools/refgen/spindocs.go,includedintools/refgen/include.go). Edit the source, in its repository; an edit to the page is undone by the next run. - Prose spin already keeps is not written again here. A page that would restate one of spin's
documents becomes that document (
spinDocs), and the others link to it. Reading every page against one release found some thirty sentences the sources no longer said, and nearly all were paraphrases. - Each kind of sentence on a hand-written page has the form a check reads. What Spinbox does
is a link to the board's row,
[words](<feature:the row's name>). A duration, a size or a count is a<Value>, or has a line intools/refgen/figures.txtnaming the constant that decides it. A command is in abashblock. A sentence in none of these forms is held only by the page'sreads, which is the weakest: prefer the form. - A page's
readsare the files whose change would make it wrong, the narrowest that do: a file, never a package. Whentask reference:checksays one changed, run thegit diffit prints, read the whole page against it, correct the page, and only thentask reviewed PAGE=<the page>. A stamp says somebody read the page; one put there to turn the check green is the failure this exists to prevent. - A finding is checked against the source before a page changes. An audit by an agent is
right about half the time: open the file it cites and read the line. The site's own checks
have holes too - one took a
<placeholder>for a redirection and passed a flag the CLI does not have - so a check that passes is not a page that is true. - A feature spin ships reaches a page, or
tools/refgen/unsaid.txt. The list is what the site owes its readers; it shrinks by pages being written, and a line is added only for a row the same pull request does not have a page for yet. - A new page is in the sidebar's list (
nav.mjs, undersrc/lib/), has adescriptionof one sentence, and names itsreads. - Branch
sync/sourcesis written over every day by.github/workflows/sync.yml. A fix to a hand-written page that the sync's pull request needs rides that pull request and merges before the next run, or goes tomainfirst. - This repository is public, and a pull request is public the moment it is opened. spin is
not: nothing of spin's goes in a commit, a pull request or an issue here but what the pages
themselves publish.
task exposureis the check.
| changed | run |
|---|---|
a page, a component, tools/ |
task check |
| nothing here, and the sync's pull request is red | task check, and read what it names |
versions.yaml |
task reference, then task check |
| a workflow | task gate |
Tasks run as go tool task <name>. spin is private: task sources reads it with SOURCES_TOKEN
(gh auth token gives one) or git's own credentials. A host needs Go and Docker: Node and pnpm
run in the image the Dockerfile makes, never on the host.
The site and the blog (blog.spinbox.dev, where the reasons and the failures live) describe the same
project, and hold it to the same rules. The site says what Spinbox is and how to use it; the blog
says why it is built that way and what went wrong. Link to a post where a page would explain a
reason, instead of restating it: [why](<post:the-slug>), a slug of src/data/posts.json (the
published posts; a draft's slug is private and goes nowhere here).
- What a workspace is comes first; the sandbox follows from it. A workspace is a whole machine, built from parts Linux and QEMU already have, made for a person to work in. That is what makes it a place to run code you don't fully trust, an agent's included. Lead with the machine, not with "sandbox".
- No absolute guarantees. "Nothing reaches the host" is a promise a reader can test and find wanting. Say what the mechanism is (its own user, nothing opened by name, a namespace of its own) and link to the security model and its known gaps. A boundary is described, never vouched for.
- Built and tested is not used every day. A feature with a test behind it is built; say "used day to day" only of what is. The agent features are the least lived-in part today: present them as ready and tested, not as proven in production.
- Plain words, no slogans. Say the verdict, then the reason, in the plainest words that are
still exact. A number has a source (
<Value>,figures.txt) like any other.