Show HN: Treedocs: Documentation that automatically checks for staleness

# treedocs Source: [https://dandylyons.github.io/treedocs/](https://dandylyons.github.io/treedocs/) Swift CLI Understand any codebase faster with a documented`tree`for every file and folder\. ## treedocs demo video ## Readable Tree Output Just run`treedocs`to see the repository at a glance\. Current files render green, while stale or invalid entries render red so problems stand out immediately\. ``` ✅ The treedocs below is up to date with the filesystem. . ├── README.md User-facing overview, installation, and command usage documentation. ├── Sources/ Swift package source code for the treedocs executable. │ └── treedocs/ Main treedocs executable target. │ ├── Commands/ ArgumentParser command implementations for treedocs subcommands. │ └── Core/ Core services for loading, scanning, rendering, and updating treedocs data. ├── site/ Static files deployed to the project GitHub Pages site. │ ├── index.html Landing page for the treedocs GitHub Pages site. │ └── styles.css Stylesheet for the treedocs GitHub Pages landing page. └── old-file.swift Stale entry: no matching path exists on disk. ``` ## Acclimate Faster Give new teammates, future you, and coding agents the concise context they need to understand complex repositories so that they don't need to wander aimlessly\. ## Stay Current Keep documentation from going stale with automatic drift checks that warn or fail\. You can even install a Git pre\-commit hook so that you never commit undocumented changes\. ## Review With Context Store simple, human\-readable, version\-controlled summaries in`treedocs\.yaml`so reviews are easier and agents spend fewer tokens rediscovering project structure\. Installation`treedocs`currently supports macOS 13 and newer\. Version 0\.2\.0 is source\-build only, so installing through Homebrew, Mint, or mise requires a Swift 6\-capable build environment, usually Xcode 16\+\. mise``` MISE_EXPERIMENTAL=true mise use -g spm:DandyLyons/[email protected] ``` [mise](https://mise.jdx.dev/)uses its Swift Package Manager backend\. treedocs does not currently publish artifact bundles, so mise builds from source\. The mise`spm:`backend is currently experimental, so set`MISE\_EXPERIMENTAL=true`when installing\. Homebrew``` brew install DandyLyons/tap/treedocs ``` The[Homebrew](https://brew.sh/)formula builds treedocs from source through the DandyLyons tap\. Mint``` mint install DandyLyons/[email protected] mint run DandyLyons/[email protected] --help ``` [Mint](https://github.com/yonaskolb/Mint)builds the Swift executable package from the tagged GitHub source\. ## Quick Start ``` treedocs init # Create a treedocs.yaml file treedocs sync # Synchronize treedocs.yaml with your current folder structure and check for errors. treedocs show . # Show the documented tree treedocs check # Check for errors in treedocs.yaml. treedocs explore . # Progressive disclosure exploration of the codebase. Perfect for agent exploration. ``` ## The`treedocs\.yaml`Schema `treedocs\.yaml`is a version\-controlled map of your repository\. It mirrors your file tree and stores a human\-readable YAML description for every file and folder\. This same description can be parsed and displayed with`treedocs`' rich tooling\. The file format is defined by a[canonical JSON Schema](https://dandylyons.github.io/treedocs/schemas/latest/treedocs.schema.json), which means editors, CI tools, and AI agents can all parse, validate, and understand the same structure\. Keeping docs up to date is an ongoing task, but`treedocs`makes it easy\! Running`treedocs sync`updates your`treedocs\.yaml`file, adding new paths and removing ghost paths\. All that's left to do is add short descriptions\. It's easy to update descriptions with`treedocs update`\. Or simply ask an agent to fill in your`treedocs\.yaml`file for you\. Agents are extremely good at filling in descriptions and everything can be validated with`treedocs check`\.