## TL;DR
Add the orphan page to a toctree, or mark it :orphan: if it is intentionally standalone. Find every affected file with the warning text, add a toctree entry pointing at it, then rebuild with -W to confirm the warning is gone.

## The exact error
```text
WARNING: document isn't included in any toctree
```

## Steps
1. **List every orphan page**
   Run sphinx-build and collect each file named in the toctree warning. The message names the page; copy the list into a checklist.
   Success check: You have the exact list of files the build cannot reach from any toctree.
2. **Add each page to a toctree**
   Edit the nearest index.rst and add the page filename (without extension) under a toctree directive. Keep the ordering that matches the site navigation.
   Success check: The page filename appears under a toctree directive in a committed index file.
3. **Or mark intentional orphans**
   For pages that must stay outside navigation, put :orphan: at the very top of the file before any other content.
   Success check: :orphan: is the first line of the file and the warning for that page disappears.
4. **Rebuild with warnings as errors**
   Run sphinx-build -W -b html sourcedir builddir and confirm exit code 0 with no toctree warnings in the log.
   Success check: Clean build, exit 0, no toctree warnings, and the page appears in the sidebar navigation.

## When to use
- Use when Sphinx emits the toctree warning and the page is missing from site navigation.
- Use when an agent doc-sync job needs a deterministic rule for orphan pages.

## When not to use
- Not for pages that fail to build for other reasons (import errors, missing theme).
- Not for deliberately standalone pages that already carry :orphan:.

## Why it happens
Sphinx builds navigation from toctree directives only. A .rst file that no toctree references still renders to HTML, but it is unreachable from navigation and search indexes, so the build warns.

## Edge cases
Large doc trees can emit hundreds of these at once after a directory restructure; fix them with a script that adds entries to the nearest index. Note the warning text uses a curly apostrophe in newer Sphinx versions.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qjMe8uDRGNXMMTiK9rMxsw