docs: epythet WP6 documentation sweep (artifact repair + coverage, correctness, completeness)

[thorwhalen]

WP6 fleet documentation sweep for dol (one repository, end to end), per i2mint/epythet#16. Docs only: an AST comparison with docstrings stripped shows no code change in the 25 Python files touched.

Before / after

Measure	Before	After
pytest -q (unit + doctests)	573 passed, 2 skipped	591 passed, 2 skipped
doctests only	314	332
epythet validate level 0.5 (parse) errors	106	0
level 0.5 findings, all severities	296	104 (info only)
level 1 (Sphinx build) findings	45	0
level 0: D101 / D103 / undocumented objects	57 / 101 / 451	30 / 60 / 382
public surface (dol namespace, 137 names) documented	127	137
lazy summaries	2	0
undocumented public classes/functions in entry-point modules (base, trans, filesys, kv_codecs, caching, paths)	61	0
module docstrings with entry points and a run doctest	5	20 of 22

Level 0.5 per rule, before -> after: DR001 24->0, DR002 15->0, DR003 9->0, DR006 8->0, DR008 18->0, DR010 30->0, DR014 20->0, DR016 26->2, DR017 3->0, DR020 1->0, DR028 1->0, DR029 28->0, DR032 2->0, DR011 92->91 (info), DR030 7->6 (info), DR031 12->5 (info). Build: DR015 29->0, DR034 14->0, DR023 2->0.

What changed

1. Mechanical repair: blank lines before doctests, lists and field lists; Returns: one-liners to sections; Markdown fences to code blocks; *args/**kwargs and trailing-underscore names in literals; broken Google headers; param x: lists in dol.sources that were missing their leading colon; commented-out doctests moved out of docstrings into code comments; docsrc/ gitignored (it was never committed).
2. Coverage, correctness, completeness: module docstrings (purpose, named entry points, one run doctest) on 15 modules; docstrings for the 10 undocumented names exported from dol; two lazy summaries rewritten; the remaining Sphinx build warnings fixed; README fences pydocstring -> python; README "For AI agents" section written by epythet ai-readme-check . --write (check passes).
3. Entry-point modules: one-line summaries for the 61 undocumented public classes and functions in base, trans, filesys, kv_codecs, caching and paths.

Every added example was executed first and its real output pasted. Theme: auto resolves to furo, right for a pure API library, so nothing was written to [tool.epythet].

Deliberately left (claims declined for lack of verification)

• add_prefix_filtering(relativize_prefix=True): a quick run returned the whole dict for s['a/']; behaviour unclear, so only the default case is documented.
• disallow_overwrites: the disable_deletes effect is referenced, not described.
• flush_on_exit and dig.layers: no doctest (quick runs did not give an output I could vouch for).
• Commented-out doctests in Sig.ch_param_attrs, call_forgivingly, ch_func_to_all_pk and naming.BigDocTest stay as code comments.
• D102/D105/D107 (methods, magic methods, __init__) untouched: not entry points, no filler. DR011 (single backticks, info) untouched: a no-op on epythet sites.

Review

An independent adversarial review (separate agent, 87 claims checked against code and tests) found 11 false or misleading claims; all corrected in the last commit. Two of them are worth a maintainer's eye as code, not docs: dol.trans.disallow_overwrites never attaches its __setitem__ override and returns None, and dol.caching.cache_func_outputs fails with its default cache and never caches keyword-argument calls. Both docstrings now say so.

Observations for epythet (not changed here)

• repair_package turns # comment lines inside docstrings into .. rubric:: headings (worst on commented-out doctests), nests a :return: field that follows a Note: paragraph into the Note, and rewrites Term: + indented prose as Term:: literal blocks. All were fixed by hand here.
• The docstring-style skill's Main entry points: template (indented name: clause lines) trips DR014; a bullet list does not.
• epythet validate -i tests/ still reported dol.tests.* objects at level 0.5.

Merging publishes a dol release (wads CI) and republishes the site on epythet v2.