The line telling you what to widen to should name your documentation, not your biggest folder

[melbinjp]

report_coverage names the unread directories and then tells the reader how to widen. It picked the directory to suggest by file count, which is almost never the documentation.

Measured

Sweep batch 10: twenty-three public repositories, 4,819 unread documentation files. The largest unread top-level segments across all of them:

segment	files
skills/	429
tools/	176
docs.feldera.com/	131
datafusion/	123
.changeset/	108
.claude/	108
src/	97
backends/	77
crates/	69

One of those nine is documentation. The rest are source-tree READMEs, agent skill definitions and changelog fragments, which is exactly what find_docs excludes and exactly what its docstring says it excludes: "a fixture, a vendored README or a changelog fragment deep in a package is not a promise the project is making."

So the scope was never the defect. Grouped by kind, the 4,819 unread break down as 30% package-internal, 17% working documents (plans, tickets, agent skills), 9% changelogs, and the remainder mostly source-tree READMEs. The default is right. The advice underneath it was wrong.

What it did

project	suggested	its actual documentation tree
immich-app/immich	mobile/ (89)	readme_i18n/ (20)
pytorch/executorch	examples/	.wiki/
langchain-ai/deepagents	libs/	openwiki/

Three of twenty-three change. The other twenty already pointed at the right place, or had nothing better to point at.

And when nothing looks like documentation, it says so

superset-sh/superset has 276 unread across apps/ 116, plans/ 100, packages/ 21. Suggesting apps/**/*.md tells the reader to widen into precisely the package-internal READMEs the scope exists to skip, which would manufacture the findings nobody asked for. It now prints:

     none of them is named like a documentation tree; if one is, widen with
     --docs 'DIR/**/*.md' or [tool.docproof] docs = ["DIR/**/*.md"]

Both routes stay, because a project whose docs live somewhere odd still needs to know how to say so.

The list itself still ranks by count, unchanged: that is what shows the reader the shape of their tree, and .changeset/ 108 is self-explaining in a way a curated list would not be.

199 tests.