docs agent generated reference pages for private internals

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

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