code-explanation

1# Code Explanation
2 
3Produce a thorough written explanation of an entire repository so someone new
4can understand **what it does, how it is built, and how the pieces fit
5together**. The output is a `CODE_EXPLANATION/` folder of markdown files: one
6`OVERVIEW.md` and a series of numbered deep-dive documents.
7 
8The goal is genuine understanding, not a file inventory. A good explanation
9reads like a knowledgeable engineer walking a new teammate through the codebase:
10it names the important abstractions, shows real code, and explains *why* things
11are shaped the way they are.
12 
13## Workflow
14 
15### 1. Establish the structural map with `treecap`
16 
17Before reading any code, get a bird's-eye view of the repo layout. Use
18`treecap`, a tree viewer that caps how many entries it shows per folder so large
19repos stay readable.
20 
21Resolve the tool in this order:
22 
231. **`treecap`** — preferred. Check with `which treecap`.
242. If it is missing, **install it**: `pip install treecap` (it is a PyPI
25   package: https://pypi.org/project/treecap/). If `pip` isn't available, try
26   `pip3 install treecap` or `python -m pip install treecap`.
273. If installation fails or is declined, **fall back to `tree`**
28   (`which tree`).
294. If neither exists, fall back to a manual listing (e.g. `find . -type f`
30   filtered sensibly), but prefer the real tools.
31 
32Run it on the target repo. Sensible defaults:
33 
34```bash
35treecap -W 0 -L 3        # full width (all entries), 3 levels deep
36```
37…