DocuSOR
Using a coding agent? Download the DocuSOR skill so your agent can write and fix testable claims for you. Drop theSKILL.mdinto your agent's skills folder.

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

## 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:

{ "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.