docs: epythet documentation sweep (WP6): zero rendering errors, 88 new docstrings, README agent section

[thorwhalen]

WP6 documentation sweep of i2 (one repository of the fleet sweep tracked in i2mint/epythet#16), following the epythet-repair-migrate procedure: mechanical repair, hand repair of the remaining rendering artifacts, coverage / correctness / completeness passes under the behaviour-claim policy, README, theme check, docsrc/ handling.

Before / after

Core package only (i2/ excluding tests/, scrap/, examples/, which the site does not document).

	before	after
tests (pytest i2)	470 passed, 2 xfailed	470 passed, 2 xfailed
doctests (pytest --doctest-modules i2)	723 passed	761 passed
epythet validate level 0.5 errors	91	0
epythet validate warnings / info	551 / 690	280 / 603
Sphinx build warnings (epythet quickstart)	8	0
build-level findings (validate --level 2)	11 DR015, 2 DR034	none
undocumented objects (validate summary, whole tree)	172	150
public module-level callables without a docstring (15 modules)	71	3
names in i2/__init__ without a docstring	1 (preprocess)	0
site pages	16 API + 7 top-level	16 API + 7 top-level

Error rules cleared: DR010 26, DR001 20, DR008 13, DR002 12, DR006 10, DR003 7, DR018 1, DR020 1, DR028 1. Coverage/quality rules: DQ001 (no docstring) 172 to 56, D103 72 to 1, D101 29 to 4, DQ005 (meta-language summary) 11 to 0, DQ002 (entry point without example) 12 to 4, D417 4 to 0, DR014 11 to 0.

What changed

• Mechanical repair (epythet repair --write): blank lines before glued doctests, bullet lists and field lists in 157 docstrings; no wording changes.
• Hand repair of the 36 errors the tool could not fix safely: RST section titles inside docstrings (castgraph module, Wrap) and .. rubric:: lines that the mechanical repair step itself had inserted (33 of them, from Example(s): headers, # comment lines and wrapped prose; a defect tracked in repair regressions found by the fleet sweep: blank lines inside ASCII-art blocks, Google Args name: + indented body turned into name:: literal; agentic-readme snippet overstates tooling epythet#27; the last three are fixed in docs: fix the last repair artifacts from the sweep (rubrics, literal block) #87) restored to bold phrases or prose; prose *args/**kwargs in double backticks; commented-out doctests moved out of docstrings into code comments (they were never run and rendered as prose); duplicated :param: block in copy_func removed; dangling references (iterable_, response_, a py2misc/... path) removed; sigs_for_builtins.print docstring made raw.
• Coverage: docstrings for 88 previously undocumented public callables across signatures, wrapper, deco, doc_mint, util, footprints, itypes, errors, multi_object, base, routing_forest, key_path, io_trans; mostly one-line summaries written after reading the implementation, plus run doctests where the behaviour was simple to show. Wrapx's docstring moves from __init__ to the class.
• Correctness: swapped summaries on return_true / return_false fixed; set_signature_of_func documented signature but the parameter is parameters; missing parameter descriptions added (attrs_used_by_method.src_code, new_type.assign_to_globals, FileLikeObject.io_cls/open_mode, mk_sentinel.module, extract_arguments flags); new_type Returns said None but returns the type.
• Completeness: run examples added to entry points that had none (preprocess, preprocess_arguments, asis, return_true, return_false, inject_method, get_function_body, InterruptWithBlock, MultiFunc, Sig.ch_names, copy_func, postprocess, defaults_are_the_same_when_not_empty, and helpers). Every example was executed and its real output pasted.
• README: pip install i2 and a smallest complete example (run first) after the intro; the hand-written skills list is replaced by the epythet-generated "For AI agents" section (epythet ai-readme-check . passes; policy add / humour / agents first); link to the flat i2.md aggregate.
• docsrc/: never committed here; now in .gitignore so a local epythet quickstart cannot land it.
• Theme: auto (resolves to sphinxawesome for i2); no pyproject.toml in this repo and the theme decision procedure gives no reason to override for a pure API library, so nothing written.

One behaviour change (not docs)

i2.util.return_true returned False (copy-paste of return_false). The name, the comment in i2/__init__.py and the README all said True, and ConditionalExceptionCatcher uses it as the default exception_condition (so the default never caught anything). It now returns True. No caller in the local fleet depends on the old value (grep over the local package tree).

Claims declined (behaviour not verified, left undocumented)

• get_app_folder: no example (OS-dependent output).
• is_a_new_type / typ_name: on Python 3.10+ is_a_new_type(NewType(...)) is False and typ_name raises on a NewType or on int; mechanism documented only, code left as is.
• get_function_body raises StopIteration on a one-line def; only the multi-line case is shown.
• object_dependencies returns an "Invalid input" string instead of raising for a non-class/non-instance; not documented.
• Sig.normalize_kind: allow_reordering and add_defaults_if_necessary behave oddly (see the fork notes in the sweep ledger); not documented.
• normalized_func: documented as work in progress (both tests are xfail).
• split_line_comments with more than one # raises from tuple unpacking; not documented.
• find_in_params: annotation params: Callable | str contradicts the docstring and body (a list of dicts is accepted); code annotation, not changed.
• transform_args (deco): documents rootdir/name_arg that do not exist in its signature; left for a separate pass.
• footprints.py: trace_class_decorator, get_class_that_defined_method, cls_and_method_name_of_method are each defined twice (the first trace_class_decorator is dead); left as is.

Adversarial review

An independent review of the diff (AST diff of every changed module, 40 rewritten docstrings checked against code) found two HIGH items, both fixed in the last commit: the preprocess docstring claimed bound-method handling the code does not deliver (claim removed), and return_true is the one executable change (documented above). MEDIUM/LOW items fixed: ArgValConverterIngress presented the name-mangled __strict as switchable; object_dependencies "skips methods without source" (only TypeError is caught); a Markdown image converted to a broken link in multi_object; ensure_signature raises ValueError, not TypeError, on a string. Left as is: duplicate function definitions in footprints.py (code), truncated skill descriptions in the generated README table (epythet's snippet cuts long descriptions).

Skill placement (recorded for the fleet inventory, not migrated)

Skills live as real directories under .claude/skills/ (i2-castgraph, i2-multi-object, i2-sig-arithmetic, i2-signatures, i2-wrapper); no subagents, no instruction files.

Observation for epythet

epythet validate . -i tests/ scrap/ examples/ (ignore after the positional) still reports level 0 / 0.5 findings under i2/tests, i2/scrap, i2/examples; epythet validate -i tests/ scrap/ examples/ -- . applies them.