# Writing testable docs

DocuSOR can test your repository's own Markdown files, such as `README.md`, runbooks, and
onboarding guides, against your running app. You keep writing normal prose. Wherever you state a
checkable fact, write it as a short **claim**, and DocuSOR reports whether each claim is true.

There is nothing to install and no new syntax: a claim is a plain sentence with the concrete
values in backticks.

## How it works

1. Click **Test a doc** on the repository page and pick a file, or have your agent call
   `check_doc` with the repository and the file's path.
2. DocuSOR runs your app in an isolated sandbox at the latest commit.
3. Each claim it recognizes is checked against the running app.
4. You get a pass or fail for every claim, plus a warning for each line that looked like a claim
   but couldn't be understood.

## Rules for writing claims

- **Put values in backticks.** Paths, URLs, ports, status codes, commands, file names, and service
  names go in backticks: "`GET /health` returns `200`".
- **One claim per line.** Bullets work well. List markers, headings, and bold or italic markers
  are ignored.
- **Start the line with the claim.** "listens on port `8080`" works. "The API listens on port
  `8080`" does not.
- **No trailing punctuation.** "`GET /health` returns `200`" works. Adding a period at the end
  makes it unrecognized.
- **Prose is left alone.** Lines with no backticks and no claim keywords are treated as
  documentation. Code blocks and HTML comments are skipped.
- **Unrecognized claims are warnings.** A line with backticks or claim keywords that doesn't match
  a claim below is reported as a warning. It never counts as passing and never fails the test.

## What you can claim

Alternative wordings are in parentheses.

### Endpoints

Write the request as `GET /path`, or just `/path` (defaults to `GET`). Paths are sent to your
running app. Full URLs are used as written.

- `GET /health` returns `200` (responds with, gives)
- `GET /health` responds (is ok, is reachable, works)
- `/health` responds within `2s` (or `200ms`)
- `GET /users` body contains `"id"`
- `/api` header `Content-Type` is `application/json` (contains, equals)
- `/status` json `$.ok` is `true` (equals)
- `/admin` requires authentication (requires auth, is protected)

### Files

- ships a `Dockerfile` (has, includes, provides)
- `package.json` exists
- has a `src/` directory (folder, dir)
- `package.json` is valid JSON
- `README.md` contains `Getting Started`
- `.env` is absent

### Services and ports

- the `db` service is running (container)
- the `db` service is healthy
- listens on port `8080` (port `8080`, port `8080` is open)
- port `9000` is closed
- redis responds (is reachable, pings)

### Commands and tools

- `npm test` succeeds
- `node` is installed (is available, is on the path)

### Environment and data

- `DATABASE_URL` is set
- migrations are applied
- the working tree is clean

### Networking

- `example.com` resolves

## Combining and negating claims

- **Negate** with "does not", "doesn't", "no longer", or "never": `/admin` does not respond
- **Combine** with "and" or commas. Each part is checked separately: the `db` service is running
  and healthy

## Example

```md
## Running the service

Start the stack with Docker Compose, then confirm:

- listens on port `8080`
- `GET /health` returns `200`
- `/health` responds within `500ms`
- the `db` service is running and healthy
- migrations are applied
- ships a `Dockerfile`
```

## What the sandbox can run

- **With a Compose file**, DocuSOR starts your stack before checking claims, so endpoint, port,
  and service claims run against real services.
- **Without a Compose file**, including Dockerfile-only repositories, your app is not started.
  File, command, tool, and environment claims still work. Endpoint and service claims will fail.

## Choosing which docs to test

Any `.md` or `.mdx` file in the repository can be tested (dependency and build folders such as
`node_modules` and `dist` are excluded). To list your most important docs first in the picker, add
`.docusor/docs.json` at the repository root:

```json
{ "docs": ["README.md", "docs/runbook.md"] }
```

## Cost and status

- Testing a doc from the dashboard is free.
- An agent's `check_doc` uses one credit, and only if at least one claim runs.
- A doc test never changes your repository's "Validated" status.

## Tips

- Prefer specific claims. "`GET /health` returns `200`" proves more than "`GET /health` responds".
- Write values exactly as they are: real port numbers, paths relative to the repository root, and
  full request lines like `POST /login`.
- Keep inline code out of prose lines you don't want checked, or expect a warning for them.
