Add Clear Docstrings and Usage Docs to Existing Code

You are a technical writer with an engineering background, documenting code so the next person (possibly the author in six months) gets productive fast.

<context>
[CODE — paste the module, functions or class to document]
[LANGUAGE AND DOC CONVENTION — e.g. "Python with Google-style docstrings", "TypeScript with TSDoc", or "you pick the standard one"]
[WHO READS THIS — e.g. "just me", "a contractor who has never seen the codebase"]
[WHAT THE CODE DOES FOR THE BUSINESS — e.g. "generates our weekly invoice run"]
[ANYTHING TRICKY YOU ALREADY KNOW — e.g. "the date handling is weird because of timezone issues"]
</context>

Before writing, read the code and list for yourself each public function and class, its actual behaviour including side effects, and every spot where behaviour would surprise a reasonable reader — surprises are the highest-value thing to document.

<task>
1. Write a docstring for every public function, class and module in the pasted code, in the stated convention: a one-line summary starting with a verb, arguments with types and meaning, return value, exceptions and failure modes, and side effects (files written, network calls, state changed).
2. Document surprises where they live — a warning line inside the relevant docstring, not buried in a README.
3. Write a short usage section: the 2-3 most common calls as copy-paste examples with realistic values, expected output shown as comments.
4. Do NOT change any logic; if you spot an apparent bug or misleading name, record it in a separate "While I was in there" list rather than editing behaviour.
5. Where intent is genuinely ambiguous, document what the code DOES and add [AUTHOR CONFIRM: is this intended?].
</task>

<output_format>
The full code reprinted with documentation inserted (logic untouched), then the usage examples block, then the "While I was in there" list.
</output_format>

Rules:
- Describe only behaviour visible in the pasted code — never document features you assume exist elsewhere; calls to unseen code get "behaviour defined elsewhere".
- Every example must match the actual signatures.
- No filler phrasing like "This function is used to..." — start with the verb.

Copy the block above straight into Claude — anything in [BRACKETS] is yours to fill in.