A manual is your product's set of numbered chapters, and a chapter is one page of that manual whose factual sentences are anchored to your code. You write the brief; the generator writes the prose and records, for every sentence that states a value, exactly where that value lives in your repository.
Your repository is the source of truth. The dashboard says so on the page: your repository stays canonical, and editing here prepares a change that nothing writes to git until you approve it.
The loop
- Create a chapter. It gets a number and a title.
- Generate. A generation is one run that turns a brief and a list of source files into a chapter's prose and its claims, a claim being one recorded link between a sentence in the chapter and an exact value in an exact file of your repository. The brief is two or three sentences saying what the chapter must explain; the source files are the repository-relative paths that hold the answers, entered one per line. List no files and the generate form refuses with "List at least one file for the generator to read." and sends nothing.
- Read the claims. Verifying a claim means reading its file and confirming the recorded value is still there; the generator has done that once, and you read the claims before you read the prose.
- Cold read. Read the chapter front to back as a stranger to the code would, looking for sentences that are true and useless.
- Approve. Approval opens a pull request against your repository. Git stays canonical; nothing lands before that pull request merges.
- Merge, then publish the chapter from its page: the public manual shows published chapters only.
- Cut a version when the set is ready: a version is the snapshot of the manual that pins each repository to a commit.
Generation
A generation is not one model call. Each draft is checked against the code and redrafted with the findings. The bound is three drafts, and "the bound" below means those three. A chapter still not clean on the third arrives marked for review, and its claims are saved with it so you can see what failed.
The free allowance is five manual generations a month. Chapter 12 covers plans and billing. When a generation is refused for any reason, the form surfaces the reason returned and leaves the chapter body exactly as it was; the fallback line is "Could not generate this chapter".
Regenerate replaces the whole body. The browser asks first, "This chapter already has content. Replace it with a fresh generation?", and declining sends nothing.
Generate and Regenerate are offered only on a chapter that is still a draft or marked for review. An approved or published chapter refuses generation however it is asked, and a generation only ever delivers a draft or a chapter marked for review.
A chapter marked for review is not broken; it needs your reading. A chapter that reads as a draft is one whose every claim verified.
What the checker does
The checker reads each cited file at the commit its version pinned and compares the recorded value with the file by text matching. It never judges prose and it does not read meaning. A recorded value is looked for on the line it was taken from, and a recorded string anywhere in the file. Because it is text matching, a claim can point at a file in any language. Repository name casing does not matter to it.
Only code and shipped files can back a claim. A claim that cites internal documentation is refused before any file is read, and the redraft is told to take the fact from the code or drop the sentence.
The five verdicts
A verdict is the one-word outcome a chapter gets from a check, and there are five:
- The recorded value moved. That is drift.
- A file the chapter depends on changed, and everything checked still holds.
- Everything checked holds and nothing it depends on moved.
- The check could not be made.
- The chapter anchors nothing at all.
A drift reads like a diff of one fact: the finding names the claim, the file, the line, the value now in the code and the value your sentence states.
Found drift and could not check are different outcomes, and neither merges. A cited file that cannot be read, a symbol that no longer exists, and a value spread over several lines are failures to check, not drift. Only a value that closes on its own line can be checked at all; a missing name is reported as not found in that file.
Clean does not mean right
- No claims. A chapter with no claims is not clear, it is unanchored: nothing in it can ever be re-checked. It carries the warning "Nothing in this chapter is being checked" next to its status.
- Coverage. Coverage is the share of a chapter's sentences stating a concrete value that carry a claim. Below the threshold, generation feeds the unclaimed sentences back and redrafts; still below at the bound, the chapter arrives marked for review with those sentences named.
- Unwatched claims. An unwatched claim is one in a repository that no push and no scheduled check ever visits, so no future drift in it would ever be seen. It is reported on every run and never blocks anything.
Full check and push check
On a push, only claims whose cited file is in that push are checked. The push check is the GitHub Action's verify mode, chapter 06; the same check from a terminal is the CLI's manual verify, chapter 05. Everything else is skipped, with no finding either way. Pre-existing drift surfaces on a full check, which is what generation runs on every draft.
You do not choose which files are watched. The distinct files a chapter's own claims cite are its anchors, derived from the claims themselves.
Voice
The voice profile is the register the manual is drafted in, set on the manual page; its banned words and every em or en dash are refused deterministically and fixed on redraft. Register beyond that floor is your read, not the machine's.
Status words
A chapter carries one of four status words in the dashboard: "Draft", "Needs review", "Approved", "Published".
The public manual
The reader of your public manual never sees drift. The page lists published chapters only, in your order, with no version switcher and no staleness of any kind; drift is reported to you. Until one chapter is published, the public address is not found. Search is rebuilt from the same published chapters on every view, so nothing is stored and the index cannot fall behind the contents above it.