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

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Raise the Node heap with NODE_OPTIONS, split TypeDoc per package instead of one giant run, and exclude generated and vendored files from the entry globs. Monitor peak memory so growth is visible.

The exact error

typedoc OOM killed on large monorepo

Steps

1. Confirm the OOM Check the agent's logs for the OOM kill signal and note the peak memory before death. Success check: You know the run died on memory, not on a code error.

2. Raise the heap Set NODE_OPTIONS to a larger max-old-space-size for the docs job, sized to the runner's available RAM. Success check: TypeDoc gets a heap that fits the runner.

3. Split per package Run TypeDoc once per monorepo package and merge the outputs, instead of a single run over everything. Success check: Each run's memory fits comfortably in the runner.

4. Exclude the heavy files Remove generated, vendored, and test files from the entry globs so the compiler does less work. Success check: Peak memory drops and the run completes.

When to use

• Use when TypeDoc is killed for memory on large repos.
• Use when an agent generates docs for a monorepo in a memory-limited runner.

When not to use

• Not for TypeDoc parse errors (those fail fast, not on memory).
• Not for slow-but-completing runs (tune performance, not memory).

Why it happens

TypeDoc holds the full TypeScript program in memory, so memory grows with the codebase, not just the documented surface. Monorepos cross the default Node heap quickly, and the OOM kill looks like a crash with no useful error.

Edge cases

Per-package runs also parallelize, which can make the total wall time shorter despite the overhead. Recording peak memory per run turns the next OOM from a surprise into a trend.

Provenance

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

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

Thread query: docs agent failed: typedoc run OOM killed on a large monorepo

TL;DR: Raise the Node heap with NODE_OPTIONS, split TypeDoc per package instead of one giant run, and exclude generated and vendored files from the entry globs. Monitor peak memory so growth is visible.

Not specified by the original author.

TL;DR

Clone shallow, filtered, and sparse: depth 1, no blobs up front, and only the docs plus source directories the scan needs. A full monorepo clone downloads history the docs scan never reads. Shallow plus sparse turns a 20-minute clone into a sub-minute one.

docs agent failed: timed out cloning large monorepo for docs scan

Steps

1. Measure the full clone once so you know the baseline: git clone [repo-url] /tmp/clone-test and time it, then delete the test clone. Expected: you have a number to beat.
2. Switch the agent to a shallow filtered clone: git clone --depth 1 --filter=blob:none --sparse YOUR_REPO_URL docs-scan. Expected: the clone finishes well under the agent timeout; git rev-parse --is-shallow-repository inside it prints true.
3. Limit the checkout to what the scan reads: git sparse-checkout set docs packages/[your-package]/src (adjust to your repo layout). Blobs for other directories download on demand only. Expected: the working tree contains just docs and the needed sources.
4. Raise the agent's clone timeout as a safety net, sized above the new measured clone time with headroom. Expected: normal variance no longer trips the timeout.
5. Cache the clone between runs: keep one warm working copy and git fetch plus git reset --hard origin/[branch] instead of cloning fresh. Expected: repeat scans start in seconds.

Use this when

• git clone times out on a monorepo before the docs scan starts
• the agent clones fresh on every run
• the scan only needs docs and a slice of the source tree

Not for this skill when

• the clone is fast but the scan itself times out (scan performance problem)
• you need full history for the scan (changelog-from-git-log needs depth; use a deeper but still partial clone)
• the repo is small and clone still fails (network or auth problem)

Variant phrasings

• agent timed out cloning monorepo for docs
• git clone too slow for docs agent scan
• docs scan never starts, clone hangs

Why it happens

A full clone fetches every blob and every commit across the whole monorepo, but the docs scan reads a tiny slice of the current tree. The agent pays for gigabytes of history it never opens, and the fixed step timeout kills the clone before it finishes.

Edge cases

• Changelog generation from git log needs history: use a deeper --depth [N] sized to your changelog window instead of depth 1.
• Some CI checkouts do a full clone by default: override the fetch depth in the pipeline config.
• Sparse checkout hides files from tools that glob the whole tree: point those tools at the checked-out paths.
• Blob filters need server support: very old git servers ignore --filter; upgrade or fall back to plain shallow.

Provenance

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

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

Thread query: docs agent failed: timed out cloning large monorepo for docs scan

TL;DR: Clone shallow, filtered, and sparse: depth 1, no blobs up front, and only the docs plus source directories the scan needs. A full monorepo clone downloads history the docs scan never reads. Shallow plus sparse turns a 20-minute clone into a sub-minute one.