## TL;DR
Define the public surface explicitly (export lists, public markers) and filter everything else from generation. Verify by diffing generated pages against the public surface. Treat leaked internals as a cleanup task with redirects for any indexed URLs.

## The exact error
```text
generated docs include private internal modules
```

## Steps
1. **Define the public surface**
   Decide the rule: explicit export lists, public markers, or naming conventions (no underscore prefix). Write it down.
   Success check: The public-surface rule is explicit.
2. **Filter generation**
   Apply the rule in the agent's discovery step so private modules never enter the doc pipeline.
   Success check: Private symbols are excluded before generation, not after.
3. **Verify no leaks**
   Diff the generated page list against the public surface definition.
   Success check: Every generated page maps to a public symbol.
4. **Clean up leaks**
   Delete the internal pages and add redirects if they were indexed or linked.
   Success check: No internal page remains reachable.

## When to use
- Use when generated reference docs expose private internals.
- Use when an agent discovers API surface automatically.

## When not to use
- Not for internal docs that are intentionally published (different audience).
- Not for missing public symbols (the opposite problem).

## Why it happens
Agents document what they can import, and they can import internals. Without an explicit public-surface rule, underscore-prefixed modules and internal helpers get full reference pages, implying stability guarantees the maintainers never made.

## Edge cases
Explicit export lists (__all__, index exports, pub markers) are more reliable than naming conventions because conventions get violated. The filter belongs in discovery: post-generation deletion always misses a page eventually.

## Provenance

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