docs agent failed: could not map monorepo package boundaries to doc sections

TL;DR

Derive boundaries from package manifests (package.json, pyproject, Cargo.toml) rather than directory heuristics. Map each manifest to a doc section, handle nested packages explicitly, and fail loudly on ambiguous layouts instead of guessing.

The exact error

docs agent could not map monorepo package boundaries

Steps

1. List the manifests Find every package manifest in the repo; each one defines a package boundary. Success check: You have the authoritative list of packages.

2. Map manifests to sections Assign each manifest's directory to a doc section, using the package name for the section title. Success check: Every package has exactly one doc section.

3. Handle nesting For nested packages, document the nesting explicitly and decide whether the inner package gets its own section or folds into the parent. Success check: No package is documented twice or zero times.

4. Fail on ambiguity If two manifests claim overlapping paths, stop and surface the conflict instead of generating. Success check: Ambiguous layouts fail loudly instead of producing wrong docs.

When to use

• Use when a docs agent must split generated docs by monorepo package.
• Use when adding a new package to a monorepo with generated docs.

When not to use

• Not for single-package repos (no boundaries to map).
• Not for docs that intentionally span packages (architecture guides).

Why it happens

Directory structure alone does not define packages; only manifests do. Agents that guess boundaries from folder depth misattribute modules whenever the layout deviates from the convention.

Edge cases

Workspace globs in the root manifest are the most reliable boundary source because the build tooling already maintains them. Keep the doc section map generated from the same globs so docs and build can never disagree.

Provenance

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