docs agent missed the new v2 namespace when generating api reference

TL;DR

Diff the public API surface against the generated docs to find the missing namespace, regenerate with the v2 paths included, and add a coverage check that fails the agent's run when namespaces are undocumented. Confirm the v2 pages render.

The exact error

docs agent missed new api namespace in reference generation

Steps

1. Diff code against docs List the public namespaces in the code and compare against the generated reference pages. The v2 namespace has no page. Success check: You have the list of undocumented namespaces.

2. Find why it was skipped Check the agent's discovery logic: hardcoded paths, a stale glob, or an exclusion rule that matched the new namespace. Success check: You know the filter or assumption that excluded v2.

3. Regenerate with v2 included Fix the discovery to cover the new namespace and rerun the generation. Success check: The v2 namespace has complete reference pages.

4. Add a coverage check After generation, assert every public namespace has a corresponding page; fail the run otherwise. Success check: Future new namespaces cannot slip through silently.

When to use

• Use when generated API reference is missing a namespace.
• Use when an agent discovers API surface automatically.

When not to use

• Not for namespaces that are intentionally internal (mark them internal instead).
• Not for handwritten docs missing a section (different workflow).

Why it happens

Discovery-based generation only documents what its traversal finds. New namespaces that do not match the agent's glob, or that live outside its hardcoded roots, are silently skipped and the run still reports success.

Edge cases

The coverage check is the real fix: generation without verification drifts on every refactor. Some teams generate the namespace list from the package manifest rather than filesystem traversal to avoid glob drift.

Provenance

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