# docs-bootstrap

> A documentation format for codebases whose primary reader is a coding agent: layers linked by ids, paths into the code instead of copies of it, and checks that can fail — run by CI against the repository's own worked example.

Page: https://kotlin.website/docs-bootstrap

## Why it exists

Documentation meant for a coding agent is usually described in prose rules that nothing verifies.
[docs-bootstrap](https://github.com/youndie/docs-bootstrap) is the same idea with checks that can
fail. Four layers linked by ids, and a fifth above them that says why:

```
[ Research — why the architecture is this one; verified vs hypothesis ]   optional
                        │
[ Feature — what the system does and why, + BDD scenarios ]
                        │
[ Client screen or flow — states, actions, navigation ]
                        │
[ API endpoint — the complete route reference, auth tiers ]
                        │
[ Service — ownership, dependencies, deploy, quirks ]
```

Every document carries paths into the code, so a reader — human or agent — gets from a claim to the
source in one hop. Nothing in a document duplicates what lives in the code, because a copy is wrong
within a sprint and a path is not.

## The two rules

> **`main` describes what exists. An open pull request describes what will be.**

A designed but unshipped feature is `status: draft` and lives in an open pull request; a draft that
reaches the default branch is an error.

> **What was verified is separated from what was assumed, explicitly.**

Every status code, error string and limit is read out of the source before it is written down, and a
claim that was not verified says so. A document that does not distinguish the two reads as equally
authoritative either way.

## What the checks do

| Script | Guards |
|---|---|
| `docs_check.py` | the link graph across the layers, required fields, the `status` vocabulary, at least one path into the code |
| `coverage_map.py` | the map in `docs/README.md` matches the files on disk |
| `backlog_index.py` | the generated backlog index matches the items; no duplicate numbers; `blocked_by` resolves |
| `code_anchors.py` | whether the paths still exist, and whether a member written `Type.member` is still declared where its type is |
| `bdd_report.py` | how many scenarios there are, and how many are automated |

What they deliberately do **not** do: enforce the template's section structure, confuse an empty list
with a forgotten one, or block on code anchors by default — an anchor breaks because of a refactor in
someone else's repository, and a person reads that report.

## The example is the specification you can run

`example/` is a small library lending system — a research document, three services, three features,
two screens, two endpoint references, six backlog items — over a real, if tiny, code tree, so every
anchor resolves. The repository's own CI runs the checks against it, through the same Makefile and
action a documented repository uses. A format that claims to be machine-checkable and does not check
itself is asking to be taken on faith.

## Install

As a Claude Code plugin — the repository is its own marketplace:

```bash
claude plugin marketplace add youndie/docs-bootstrap
claude plugin install docs-bootstrap@docs-bootstrap
```

Then ask your agent to document a repository. `SKILL.md` is a markdown file of instructions any agent
can follow, and the half that is not the skill — the format contract, the templates and six Python
scripts behind `make check` — works for a team writing the documents by hand.

A documented repository runs the checks from here at a pinned tag, `uses: youndie/docs-bootstrap@<tag>`,
rather than as copies; the Makefile reads the same line for a local `make check`. Copied scripts used to
be the route, and that is how 18 copies of one script came to exist in three versions.

The format is `spec_version: 1`: additive changes keep the version, and anything that would make a v1
reader wrong raises it.
