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

.gitignore

@@ -113,4 +113,6 @@ venv.bak/
 .vscode
 
 # Notebook playground
-vf.ipynb
+vf.ipynb
+# epythet regenerates the Sphinx scaffold on every build
+docsrc/

README.md

@@ -4,21 +4,48 @@ Core tools for minting code.
 
 For human readers: [Documentation here.](https://i2mint.github.io/i2/)
 
-For AI agents, and humans that use them: this repo ships
-[agent skills](https://github.com/i2mint/i2/tree/master/.claude/skills) —
-focused, task-oriented guides that tell a coding agent when and how to reach
-for `i2`'s tools:
-
-- [i2-signatures](https://github.com/i2mint/i2/tree/master/.claude/skills/i2-signatures)
-  — introspect signatures and bind a call's `*args, **kwargs` to named arguments.
-- [i2-sig-arithmetic](https://github.com/i2mint/i2/tree/master/.claude/skills/i2-sig-arithmetic)
-  — build, merge (`+`/`-`) and edit function signatures.
-- [i2-wrapper](https://github.com/i2mint/i2/tree/master/.claude/skills/i2-wrapper)
-  — wrap functions to transform their interface, inputs and output.
-- [i2-castgraph](https://github.com/i2mint/i2/tree/master/.claude/skills/i2-castgraph)
-  — route data through a graph of type/representation conversions.
-- [i2-multi-object](https://github.com/i2mint/i2/tree/master/.claude/skills/i2-multi-object)
-  — compose a fixed set of functions or context managers (`Pipe`, `FuncFanout`, …).
+<!-- epythet:agentic-readme:start -->
+## For AI agents
+
+`i2` ships tooling for coding agents. If you are one, start here.
+
+**Skills** ([Agent Skills](https://agentskills.io) format), for any agent host.
+
+| Skill | Use it to |
+|---|---|
+| `i2-castgraph` | routing data through a graph of type/representation conversions with i2.castgraph's TransformationGraph — register pairwise transformers |
+| `i2-multi-object` | composing and combining a fixed collection of functions |
+| `i2-sig-arithmetic` | building, merging, and editing function signatures with i2's Sig — signature "+/-" arithmetic |
+| `i2-signatures` | introspecting function signatures and binding call arguments to parameter names with i2's Sig class — turning an arbitrary |
+| `i2-wrapper` | wrapping functions to transform their interface |
+
+**The documentation, machine-readable**: [`llms.txt`](https://i2mint.github.io/i2/llms.txt) indexes every page; [`i2.md`](https://i2mint.github.io/i2/i2.md) is the whole documentation in one file; every page has a `.md` twin; [`objects.inv`](https://i2mint.github.io/i2/objects.inv) maps symbols to URLs. The full list, with install lines, is on the site's [For AI agents](https://i2mint.github.io/i2/ai-agents.html) page.
+
+If you identify as a dinosaur, the rest of this README is written for you, starting at [Key Modules Overview](#key-modules-overview).
+<!-- epythet:agentic-readme:end -->
+
+## Install
+
+```
+pip install i2
+```
+
+The smallest useful thing: read, edit and re-apply a function's signature with `Sig`.
+
+```python
+from i2 import Sig
+
+def f(a, b=2, *, c=3):
+    return a + b * c
+
+Sig(f)               # <Sig (a, b=2, *, c=3)>
+Sig(f).names         # ['a', 'b', 'c']
+g = Sig(f).ch_names(a="x")(f)   # f itself, with its signature rewritten (g is f)
+Sig(g)               # <Sig (x, b=2, *, c=3)>
+g(1)                 # 7
+```
+
+The flat, single-file view of the whole documentation is [i2.md](https://i2mint.github.io/i2/i2.md).
 
 ## Key Modules Overview
 

i2/_deprecated.py

@@ -11,10 +11,10 @@
 
 
 class Command:
-    """A class that holds a `(caller, args, kwargs)` triple and allows one to execute
-    `caller(*args, **kwargs)`
+    """A class that holds a ``(caller, args, kwargs)`` triple and allows one to execute
+    ``caller(*args, **kwargs)``.
 
-    :param func: A callable that will be called with (*args, **kwargs) argument.
+    :param func: A callable that will be called with ``(*args, **kwargs)`` argument.
     :param args: The positional arguments to call the func with.
     :param kwargs: The keyword arguments to call the func with.
 
@@ -60,7 +60,6 @@ class Command:
     >>> c()
     hello, world
     Calling <built-in function print>(*('hello', 'world'), **{'sep': ', '}) with result: None
-
     """
 
     def __init__(self, func, *args, **kwargs):
@@ -89,7 +88,6 @@ def curried(cls, func, **kw_defaults):
         Command(foo, 'hi')
         >>> ff()
         'hihi'
-
         """
         sig = Sig(func)
         sig = sig.ch_defaults(**kw_defaults)
@@ -225,7 +223,6 @@ def commands_dict(
     7
     >>> d[formula1]()
     13
-
     """
     if callable(funcs):
         funcs = [funcs]

i2/base.py

@@ -1,7 +1,14 @@
-"""
-Tools to provide meta-interfaces of python objects.
-See also:
-    py2misc/py2store/tree_store.py
+"""Tools to provide meta-interfaces ("mints") of python objects.
+
+A mint is a ``Mapping`` view of the (meta-)information describing the interface of
+an object: for a callable, its parameters (name, kind, default, annotation) and its
+return annotation.
+
+Main entry points:
+
+- ``Mint``: mint of any python object
+- ``MintOfCallable``: mint of a callable, with parameter information
+- ``ParametersMint``: mint of the parameters of a callable
 """
 
 import inspect
@@ -14,6 +21,8 @@
 
 
 class NotFoundType:
+    """Type of the ``not_found`` sentinel: falsy, repr ``NotFound``."""
+
     def __bool__(self):
         return False
 
@@ -29,6 +38,7 @@ def __repr__(self):
 
 
 def is_not_empty(obj):
+    """False for ``inspect.Parameter.empty`` and ``NotFoundType`` instances, True otherwise."""
     if obj is inspect_is_empty or isinstance(obj, NotFoundType):
         return False
     else:
@@ -52,6 +62,7 @@ def _property_names_of(obj):
 #  see `i2.signatures.name_of_obj`.
 # TODO: Analyse usages and reroute to i2.signatures.name_of_obj instead.
 def name_of_obj(o):
+    """Deprecated alias of ``i2.signatures.name_of_obj`` (emits a ``DeprecationWarning``)."""
     from warnings import warn
 
     warn(
@@ -65,6 +76,8 @@ def name_of_obj(o):
 
 
 class AttrFromKey:
+    """Expose the keys of a mapping as attributes (``obj.k`` reads ``d[k]``)."""
+
     def __init__(self, d):
         self._d = d
 
@@ -75,6 +88,8 @@ def __getattr__(self, k):
 
 
 class KeyFromAttr:
+    """Expose the attributes of an object as mapping keys (``obj[k]`` reads ``getattr(d, k)``)."""
+
     def __init__(self, d):
         self._d = d
 
@@ -119,6 +134,12 @@ def __getstate__(self):
 
 
 class ParameterMint:
+    """Mint of one parameter: its name, kind, default and annotation (and position, if given).
+
+    Accepts an ``inspect.Parameter``-like object or a mapping with those keys; missing
+    attributes are set to ``inspect.Parameter.empty``.
+    """
+
     _attrs = ["name", "kind", "default", "annotation"]
 
     def __init__(self, param, position=None):
@@ -342,6 +363,8 @@ def module_name(self):
 
 
 class MintOfCallableMixin:
+    """Mint attributes computed from a callable's signature (parameters, return annotation, doc)."""
+
     @lazyprop
     def _signature(self):
         """Here's some doc"""
@@ -381,6 +404,8 @@ def annotation_of(self):
 
 
 class MintOfDocMixin:
+    """Placeholder mixin for parsed-docstring mint attributes (not implemented yet)."""
+
     @lazyprop
     def _parsed_doc(self):
         return "Not yet implemented (correctly)"