From 754b2e86ab17d62d58334df7b8712bc09964c27a Mon Sep 17 00:00:00 2001
From: Thor Whalen <1906276+thorwhalen@users.noreply.github.com>
Date: Tue, 22 Sep 2026 14:41:12 +0000
Subject: [PATCH] Add .claude/CLAUDE.md index

Module map centered on signatures.py/deco.py/wrapper.py, verified test
command (legacy isee CI, no lint gate), the i2#88/#89 breaking-change
postmortem as a standing invariant, and the 50-package dependent list.
Docs-only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .claude/CLAUDE.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 .claude/CLAUDE.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 00000000..ac90fc6e
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,68 @@
+# i2
+
+The middleware toolbox: meta-programming tools for building declarative frameworks
+— function signatures as data, decorators, wrapping/routing, multi-object
+composition. Legacy-packaged (`setup.cfg`/`setup.py`, no `pyproject.toml`) but
+heavily depended upon across the fleet — see Dependents below.
+
+## Module map (`i2/`)
+
+- `signatures.py` — **the core**: `Sig` (extended `Signature`), `Param`,
+  `call_forgivingly`/`call_somewhat_forgivingly`, `name_of_obj`. Signature calculus
+  underlies most of the rest of the package.
+- `deco.py` — decorator tools: `FuncFactory`, `preprocess`/`postprocess`,
+  `preprocess_arguments`, `input_output_decorator`,
+  `wrap_class_methods_input_and_output`, `double_up_as_factory`.
+- `wrapper.py` — the `Wrap` class: wraps a function while controlling its
+  ingress/egress and signature.
+- `multi_object.py` — operating on a fixed collection of functions: `MultiObj`,
+  `MultiFunc`, `Pipe`, `FuncFanout`, `FlexFuncFanout`, `ParallelFuncs`, `ContextFanout`.
+  Skill: `i2-multi-object`.
+- `routing_forest.py` — specifying functions through trees/forests of conditions.
+- `castgraph.py` — a transformation service for the "stable role, unstable
+  representation" problem. Skill: `i2-castgraph`.
+- `base.py` / `doc_mint.py` — "mints": `Mapping` views of an object's interface.
+- `footprints.py` — what attributes of an input object a function actually uses.
+- `key_path.py` — flattening maps and manipulating key paths.
+- `io_trans.py` — building input/output-transforming decorators.
+- `itypes.py`, `util.py`, `errors.py` — types, misc utilities, error objects.
+- `chain_map.py` — merging mappings; **marked for deprecation**, don't build on it.
+
+## Tests (verified)
+
+```bash
+uv venv .venv && uv pip install -e . pytest
+.venv/bin/pytest i2/ --ignore=i2/examples --ignore=i2/scrap --doctest-modules -q
+# 756 passed, 2 xfailed
+```
+No `ruff`/lint gate in CI — `.github/workflows/ci.yml` uses the legacy
+`i2mint/isee` actions (`install-packages`, `format-source-code`,
+`pytest-validation`), not the `i2mint/wads` reusable workflow other repos use.
+`ruff check i2/` reports hundreds of pre-existing findings; it is not what gates
+merges here.
+
+## Invariant: this package has no safety net for its own breaking changes
+
+i2#88/i2#89 (2026-09-22): a `NotSet` sentinel default landed in `FuncFactory`
+signatures, shipped to PyPI (0.1.71), and broke `front` (number-input TypeError,
+text inputs prefilled with the literal string `'NotSet'`) and `py2http` (OpenAPI
+JSON) — i2's own test suite didn't catch it because nothing in it exercises a
+`FuncFactory` signature end-to-end through a consumer. Reverted; re-land plan is
+on the reopened [i2mint/i2#48](https://github.com/i2mint/i2/issues/48). **Before
+changing any public signature, default, or return type in `signatures.py`,
+`deco.py`, or `wrapper.py`, check dependents' tests, not just this repo's.**
+
+## Docs & skills
+
+- `.claude/skills/`: `i2-signatures`, `i2-sig-arithmetic`, `i2-wrapper`,
+  `i2-multi-object`, `i2-castgraph`.
+- `misc/docs/wrapper_improvement_docs/`; notebooks under `misc/`.
+
+## Dependents
+
+50 packages import `i2` (fleet dependency graph), including `allude`, `chromadol`,
+`config2py`, `crude`, `dagapp`, `front`, `guided`, `http2py`, `meshed`, `mongodol`,
+`py2http`, `py2json`, `tabled`, `taped`, `uf` — see
+`fleet_dependents.json` for the full list. This is the widest blast radius in the
+fleet; treat any signature/default/return-type change as breaking until proven
+otherwise.