Goals

what every part of the tool is for

The goals page collects the intent of every approved page, except a page that says goals = false, when the wiki is built, in the order the sidebar lists the pages. Changing an intent changes what that part of the tool is trying to be, and that is the owner's decision.

Installation

Installation exists so that any project, on any stack, can start a wiki with one pinned release of the tool and a handful of files. Updating should be a one-line change a reviewer can see.

Continuous integration

Continuous integration exists so that a wiki cannot be merged while it is not fit to read: every push and pull request runs the same check a person runs on their own machine. A project should get it by adding one step, and the result should not depend on which machine ran it.

Deployment (GitHub)

This guide exists so that a project on GitHub can publish its wiki as a website for free, read by people who never open the repository, and only in a state that passed its checks. A project should get there with one workflow and a DNS record.

Deployment (Cloudflare)

This guide exists so that a project can publish its wiki on Cloudflare as a website for free, read by people who never open the repository, and only in a state that passed its checks. Cloudflare should build it from the repository on every push, with no workflow file to keep.

Pages

A page is how a writer who has read the code tells a reader who will not what it does. Writing one should need nothing but markdown and a few lines of settings, and where the file sits should decide where the page is found, so no list has to be kept in step with the files.

Diagrams

Diagrams exist so that a flow, a sequence or a decision can be drawn on a page, written as text the way GitHub and markdown already allow. A diagram should be readable wherever the page is read, with or without a network.

Skill

The skill exists so that an agent writing a page, in any project, writes it the way the owner approved without each project inventing its own rules. A change to those rules should reach a project only when that project asks for it, and arrive where the project reviews it.

Site

The site exists so that pages can be read by a reader who will never open the markdown, wherever they happen to open it. It should be impossible for the site to be out of date, and nothing a reader sees should change unless a page did.

Agent markdown

Agent markdown exists so that an agent reading the wiki gets each page as it was written, not as text picked back out of HTML. An agent should find every page from one index, without a person pointing it there.

Layout

The layout exists so that a reader can always see where they are and get somewhere else, whatever they are reading. Moving through a long page should never cost them the sidebar, and a sample on the page should be as easy to copy as it is to read.

Local server

The local server exists so that following a citation lands on the code it names, readable in the browser, rather than on a download or a dead link. What a person sees should always be what was just built.

Checks

The checks exist so that a wiki read instead of the code cannot quietly stop being true. Each one refuses a way documentation has been seen to rot, and together they should name every problem at once, in sentences a person can act on.

Reading budgets

Reading budgets exist so that a page answers in about two minutes and every goal can be read in one sitting. A page that outgrows its budget should be split rather than squeezed.

Citations

Citations exist so that a reader who cannot read the code can still tell a checked sentence from a guess. Every statement should lead to the code it came from, or to the documentation of the outside service it describes, or say plainly that nothing was found.

Headings

Headings exist so that a reader scanning a page finds the section holding their answer without reading the others. Every heading should name what its section contains, never ask about it or rate it.

Pictures

The picture check exists so that a page never shows something that has since changed. When a picture's subject moves, the picture should have to be redrawn, or given a reason why it is still true.

Pointing words

The pointing check exists so that every name and sentence on a page still means something to a reader who arrived from a search or a link. A page should name the project and its parts, never point at the page it sits on.

Commands

The command reference exists so that a person using the tool can find the command for a job, and exactly how to type it, without reading the code. Every command, option, argument and exit code the tool accepts should be here, and nothing it does not.

wiki audit

wiki audit exists so that a reader can see when a page was last checked against the code, and an owner can see which pages have gone longest without a check. It should record only a check of the page as it stands, and never move the day a page was updated.

wiki bless

wiki bless exists so that a person who has looked at a picture whose subject changed can clear the check, and leave a record of why. It should never clear a picture without a reason.

wiki build

wiki build exists so that a person can turn the pages into a site they can open, and see what each page costs to read while they do. It should change nothing but the site and the record of when pages changed.

wiki check

wiki check exists so that a person, or the gate a project runs before merging, learns every reason the wiki is not fit to read in one run. It should change nothing, and its exit code alone should be enough to fail a build.

wiki publish

wiki publish exists so that a wiki can be put on a web host with addresses that read cleanly. It should never write over a folder the tool did not make.

wiki serve

wiki serve exists so that a person can read the wiki as it stands by typing one command. It should always show what was just built, and only to this machine.

wiki sync

wiki sync exists so that a project takes up a release of the tool in one step: the skill its agents read, and the release its pages are checked against. It should write only those, and only where the project asks.

wiki user

wiki user exists so that the pages meant for people outside the project can be handed to them with nothing internal left in. It should never carry a reference, a missing-source mark or a page's source.

wiki.toml

wiki.toml exists so that a project decides, in one file it owns, what its wiki is called, which pages start its sidebar and how long a page may be, without the tool guessing any of it. A mistake in it should stop the build with a sentence saying what to fix.

Front matter

Front matter exists so that everything about a page that is not its text, such as its title, its purpose, its approval and its infobox, sits in the page itself. A mistake in it should stop the build with a sentence naming the page, never be read as nothing.

Infobox fields

Infobox fields exist so that a page's reference card is written beside the page it summarises, with every row naming the footnote that proves it. A row that cites nothing should never reach a reader unmarked.

PICTURES.toml

PICTURES.toml exists so that every picture on a page says what it depicts, and the tool can tell when that has changed. A picture should never reach a page without a record.