api-docs — document a public API surface from the code

Produce reference docs that match the code exactly, derived from the source, not from assumptions about what the API "probably" does.

Read the surface

Identify the public surface to document (a module, class, CLI command group, or set of endpoints). Then have the researcher read it carefully:

• Dispatch the researcher (purpose: explore) to enumerate the public entry points and report each one's real signature, parameters, defaults, return shape, and raised errors — with file:line evidence.
• Prefer what the code declares (signatures, type hints, docstrings, default values) over prose descriptions. Public vs. private follows the project's convention (e.g. a leading underscore, or an __all__ / export list).

Structure

For each entry point:

### `<name>(<signature>)`

<one-line summary of what it does>

**Parameters**
- `<name>` (`<type>`, default `<value>`) — <meaning>

**Returns** — `<type>`: <meaning>

**Raises** — `<Error>`: <when>

**Example**
```
<minimal, runnable usage>
```

Write the entries

• Keep the summary to one line; put detail in the parameter and example sections.
• Document every public parameter, including defaults, in the order they appear in the signature.
• Give one minimal example per entry point that actually runs against the documented signature.
• Do not document private/internal helpers unless the user asks; a reference is the contract, not a code tour.

Verify

Signatures, defaults, and error types drift fastest, so route the finished reference through the reviewer (purpose: review) to confirm every signature and default matches the current code.