I built treedocs, a CLI that shows a tree of your file structure, side-by-side with docs.

The idea is simple: your filesystem already tells you what exists, but not what each path is for. treedocs mirrors the file tree into a treedocs.yaml file and lets you define short descriptions, references, and links to files and folders. It can then render that back as a documented tree, detect drift when files move or disappear, and fail checks when descriptions are missing.

I originally wanted this for two related problems: 1. Helping humans acclimate to unfamiliar repositories faster. 2. Giving coding agents concise project context without forcing them to rediscover the repo structure over and over.

Some things it does: - treedocs init creates a treedocs.yaml - treedocs sync reconciles it with the filesystem - treedocs check catches stale entries and missing descriptions - treedocs explore implements progressive disclosure for efficient token usage. - Nested treedocs.yaml files act as documentation boundaries for delegated subtrees - The YAML format is backed by a public JSON Schema

I’d be interested in feedback on the file format, CLI ergonomics, and whether this kind of repo-level map is useful for your workflows.

Like ... what's wrong with what he posted?

I've seen thousands of Show HNs here, for like a decade. Very similar to this.

What rule did he break?

[0] https://github.com/tristanmatthias/llmdoc