Add TYPE_ALGEBRA

.gitignore

@@ -7,7 +7,7 @@ build/
 .scratch*/
 dist*/
 result*
-__pycache__/**
+__pycache__/
 .cache/
 .devcontainer/
 .venv/
@@ -23,3 +23,4 @@ CMakeUserPresets.json
 bazel-*
 MODULE.bazel.lock
 .bazelversion
+.memsearch/**

.pre-commit-config.yaml

@@ -61,9 +61,16 @@ repos:
     language: python
     files: ^include/.*\.hpp$
     pass_filenames: false
+  # NOTE each document and its example must match a DOCUMENTS entry in scripts/sync_md_examples.py
   - id: sync-readme-example
-    name: sync README example with examples/readme
-    entry: python scripts/sync_readme_example.py
+    name: sync README code fences with examples/readme
+    entry: python scripts/sync_md_examples.py README.md
     language: python
     files: ^(README\.md|examples/readme/main\.cpp)$
     pass_filenames: false
+  - id: sync-type-algebra-examples
+    name: sync TYPE_ALGEBRA code fences with examples/type_algebra
+    entry: python scripts/sync_md_examples.py TYPE_ALGEBRA.md
+    language: python
+    files: ^(TYPE_ALGEBRA\.md|examples/type_algebra/main\.cpp)$
+    pass_filenames: false

CLAUDE.md

@@ -2,68 +2,82 @@
 
 Conventions for AI agents in this repo (you are the primary reader — keep this terse).
 
+The project is libfn: a header-only C++20 functional-programming library — `fn` (monadic
+composition and types) layered over `pfn` (polyfills of C++23/26 vocabulary types).
+
 ## Collaboration
 
 - Pushing back **and** asking questions is welcome — a challenged design beats a silently implemented flawed one.
 
 ## CI
 
-- Red CI is top priority — fix before other work; a failed build masks failures behind it. Check CI state when starting new work: via `gh` if available, else ask the user.
-- `gh` is **optional** — use it when `GH_TOKEN` is set (repo `libfn/functional`); scope varies per session, so attempt what the user asks and fall back to drafting/asking when a permission blocks. The token is a RAM-only, short-lived PAT injected at launch — never `gh auth login` (persists it to disk).
+- Red CI is top priority — fix before other work; a failed build masks failures behind it. At session start (top-level agent, not subagents): check CI state via `gh` if available, else ask the user.
+- Before editing `.github/workflows/`, read CONTRIBUTING `## GitHub Actions workflow pitfalls`.
+- `gh` works iff `GH_TOKEN` is set; its scope varies per session — on a permission block, fall back to drafting/asking. Never `gh auth login` (would persist the ephemeral token to disk). `gh pr edit` / `gh issue view` SILENTLY no-op under this token — use `gh api` instead.
 
-## Commits
+## Commits & GitHub text
 
-- Trailer `Assisted-by: Claude:<exact session model id>` (Linux-kernel convention), e.g. `claude-opus-4-8`. No `Co-Authored-By:`.
-- Offer commits; never commit without confirmation. Terse messages: imperative topic, body only if needed.
+- Trailer `Assisted-by: Claude:<your live model id>` (Linux-kernel convention), e.g. `claude-opus-4-8`. This replaces the harness's trailer boilerplate entirely — no `Co-Authored-By:`, no `Claude-Session:` URL. Same rule for GitHub issues, PRs and comments: `Assisted-by:` is welcome; no other footers or attribution boilerplate.
+- Offer commits; never commit without the user's confirmation — which may be relayed to a commit subagent by the parent that received it. Terse messages: imperative topic; body only when the change needs a *why* (the routing rule in Code names that case).
+- If a pre-commit hook rewrites staged files, the commit aborts — re-stage the same files and retry once (CONTRIBUTING `## Pre-commit`).
 - A feature or fix commit should include a test for the behaviour it changes; exceptions are allowed. The PR must contain such a test somewhere unless the behaviour is inherently untestable (for example, because of language or compiler limitations); explain the omission.
 - Never `git push` or sign commits — the user signs (GPG) and pushes.
 
 ## Git state
 
-- Starting work, orient first: `git status -sb` + `git log --oneline -5` — catches silent branch switches; unpushed commits await the user's push. Read-only git is free; `git diff` can be large — use judiciously.
+- At session start (top-level agent, not subagents), orient first: `git status -sb` + `git log --oneline -5` — catches silent branch switches; unpushed commits await the user's push. `git diff` can be large — use judiciously.
+
+## Build & verification
+
+- Build/test is CMake + Catch2, one ctest target per test source; toolchain, options and modes: CONTRIBUTING `## Building locally`. Local build trees are gitignored siblings named `.build*` — reuse an existing tree rather than configuring a fresh one per task.
+- Watch every gate's output: never send a build or test run to `/dev/null`, and read the failing tail as well as the exit code. Rebuild before rerunning tests — a stale binary passes the tests it was built from.
 
 ## Code
 
 - Default to no comment; assume the reader reads the surrounding code. Comment only where the *why* stays non-obvious despite that context (constraint/invariant/workaround/surprise); never restate code; no boilerplate docstrings.
 - Routing: *unusual code* → comment; *ordinary code, noteworthy change* → commit body; *both obvious* → neither. "Context" = code the reader sees; why-the-change → commit.
-- Don't create `.md`/summary/planning files unless asked.
+- Don't create `.md`/summary/planning files unless asked (memory files are exempt — see Memory).
 - A new file's copyright year = the year it enters the codebase (the current year; if unsure, infer from the latest commit).
 - In `include/` headers, anchor the standard library as `::std::`, never bare `std::` — a user's `fn::std` would otherwise win lookup inside namespace `fn`. Not needed in tests.
 
 ## Layering
 
-Four header layers; each may depend only on those below it:
-- `include/fn` — may use `fn/detail` and `pfn`
-- `include/fn/detail` — may use `pfn`, never `fn`
-- `include/pfn` — C++23/26 polyfill; standalone except for the version header
-- `include/libfn_version.hpp` — base: the sole root header, no dependencies
+- Four header trees under `include/`, strictly layered — `fn` → `fn/detail` → `pfn` → `libfn_version.hpp`; each may depend only on layers after it, never back. Rules and the hoist technique (making an `fn` facility available to `fn/detail`): CONTRIBUTING `## Header layering`.
+- Inline-namespace versioning wrap: CONTRIBUTING `## Versioning`; pre-commit enforces.
 
-Every `namespace fn` opening in `include/` carries `inline namespace LIBFN_VERSION`, every `namespace pfn` opening `inline namespace LIBFN_VERSION_BASE` — the mode-less spelling; pfn never joins the `_cxx26` ABI twin (pre-commit enforced). A header that opens either includes `<libfn_version.hpp>` itself.
+## C++ standard versions
 
-To give an `fn/detail` file something that lives in `fn`, hoist it: the implementation moves into `fn/detail/X.hpp` as `fn::detail::_name` (no doxygen — detail headers aren't user-facing); `fn/X.hpp` stays a thin public wrapper re-exporting it as `fn::name` (pattern: `fn/functional.hpp`).
+- C++20 is the baseline: `include/` relies on C++20 only in every default-mode build, and `pfn` never relies on post-C++20 features in any mode. Spell C++23-isms as C++20: `static operator()` → `const` member; a `static constexpr` local in a constexpr function → non-static; `std::unreachable` → `pfn::unreachable`; `0uz` → `std::size_t{0}`.
+- `LIBFN_CXX26` (strict opt-in): C++26 reliance — `std::type_order` behind its capability gate; details in CONTRIBUTING `### Standard-mode feature reliance`.
 
-## C++20
+## Client code
 
-C++20 is the sole export surface — fn + pfn build and pass tests as C++20 on all supported compilers, incl. MSVC; CI validates C++23 via the test-only `VALIDATE_CXX23` lanes. Keep `include/` C++20 — spell C++23-isms as C++20: `static operator()` → `const` member; a `static constexpr` local in a constexpr function → non-static; `std::unreachable` → `pfn::unreachable`; `0uz` → `std::size_t{0}`.
+- Code written against the library — examples, documentation snippets, reproducers, anything a user of libfn might imitate: follow CONTRIBUTING `## Client code`.
 
 ## Tests
 
 - Before writing or reviewing tests, read and follow `CONTRIBUTING.md` from `## Unit tests` to the next top-level heading; it is the source of truth for test structure, assertions and compile-time probes.
 
+## Delegation
+
+- Delegate mechanical, well-specified, verifiable work — builds, test sweeps, commit mechanics, compile probes — to subagents by default; their noise stays out of the working context. Run independent delegations concurrently.
+- Keep exploratory reading, design and diagnosis inline: a subagent returns its result, not the understanding built producing it, and for this work the understanding is the point.
+- Local agent definitions may exist under `.claude/agents/` (not committed); prefer them when present. Agents register at session start — a new or edited definition is invisible until the session restarts.
+- Verify a finding empirically before filing it anywhere; for a compile-time claim that means a probe compiled on both gcc and clang.
+
 ## Tooling
 
-- Prefer `clangd-lsp@claude-plugins-official` over grep/whole-file reads for C++ symbol navigation (go-to-def, find-refs) and post-edit diagnostics — targeted lookups should cut context, not add it. Needs a populated `compile_commands.json`; if unavailable/empty, ask the user to populate it and offer help.
+- When the `clangd-lsp@claude-plugins-official` plugin is available, prefer it over grep/whole-file reads for C++ symbol navigation (go-to-def, find-refs) and post-edit diagnostics — targeted lookups should cut context, not add it. Needs a populated `compile_commands.json`; if unavailable/empty, ask the user to populate it and offer help.
 - clangd reflects one local toolchain, not the CI matrix — a clean clangd buffer is NOT portability clearance; full `-Werror` builds + CI stay the authority.
 
 ## Memory
 
-- Keep memory current as facts change.
-- Create memory files without asking, but announce each one and its purpose.
-- On wrap-up or a "memory pass" request: review memory — update/remove obsolete, flag new.
+- On wrap-up or a "memory pass" request: curate memory — update or remove obsolete entries, capture new durable facts; announce each new memory file and its purpose. A "consolidation pass" request does the same against recent session journals.
 
 ## Docs
 
-- Map: README.md = user-facing overview (purpose, usage, project shape, support surface; no agent directives, no internal mechanics; CI surfaced as evidence only, never mechanics); CONTRIBUTING.md = contributor facts (coding + tests standards, build environment, workflows, all CI details, mechanics of every aspect; no agent directives, no library usage); CHANGELOG.md = design history (dated entries, newest first); docs/ = API reference (Doxygen → Pages; also usage); CLAUDE.md = agent practice + the critical selection of standards (coding, tests, documentation).
-- Living documents (README, CONTRIBUTING, docs/) are timeless present tense — no "now", "no longer", "previously"; when reading or updating them, remove recency bias. A change that obsoletes documented design gets a dated CHANGELOG.md entry in the same change, saying what it obsoleted and why.
-- Recency bias defence (all documentation except CHANGELOG.md, and code comments): you over-weight whatever you just worked on, so text written right after a change reads as a diff against your context, not a document for a reader who arrives fresh. The banned transition words are only the shallow symptom; test deeper: (1) day-one test — would this sentence exist had the feature or fix always been here? if not, cut it; (2) effort test — is the detail sized by reader need, or by how hard the work was? cut whatever answers questions no reader asked; (3) placement test — is it where a newcomer would look, or where your recent work pulls it? Defence: after editing, reread the whole file top-to-bottom as a first-time reader and re-judge the new text's length and position against the whole document — never review only your diff. CHANGELOG.md and commit messages are exempt: both are read as an increment on top of previous state, so change-perspective is their correct form.
+- Map: README.md = user-facing overview (purpose, usage, project shape, support surface; no agent directives, no internal mechanics; CI surfaced as evidence only, never mechanics); CONTRIBUTING.md = contributor facts (coding + tests standards, build environment, workflows, all CI details, mechanics of every aspect; no agent directives, no library usage); TYPE_ALGEBRA.md = the design document — the library's type algebra worked from first principles; CHANGELOG.md = design history (dated entries, newest first); docs/ = API reference (Doxygen + znai → Pages; also usage); CLAUDE.md = agent practice + guardrails pointing into the above.
+- Fenced C++ examples in README.md and TYPE_ALGEBRA.md are generated from sources in `examples/` by `scripts/sync_md_examples.py` (pre-commit keeps them in sync) — edit the example source, never the fence; prose edits stay outside fences.
+- Living documents (README, CONTRIBUTING, docs/) are timeless present tense — no "now", "no longer", "previously". A change that obsoletes documented design gets a dated CHANGELOG.md entry in the same change, saying what it obsoleted and why.
+- Recency-bias and wordiness defence (all human-readable text — docs, code comments, and the like; CHANGELOG.md and commit messages are exempt — change-perspective is their correct form): before keeping new text, test — (1) day-one: would this sentence exist had the feature or fix always been here? (2) effort: is detail sized by reader need, or by how hard the work was? — a hard-won bugfix earns no extra words; its history lives in `git log`/`git blame`/CHANGELOG.md; (3) placement: is it where a newcomer looks, or where your recent work pulls it? (4) economy: could fewer words say it as well? After editing, delegate a whole-file top-to-bottom reread to a subagent briefed as a first-time reader, blind to what changed — never review only your diff. Triage its findings: fix what your edit touches, surface the rest rather than rewriting unasked.
 - On memory or practice changes, check the root `.md` files for drift from reality and **offer** fixes (CLAUDE.md = practice, README/CONTRIBUTING = facts).

CONTRIBUTING.md

@@ -56,6 +56,29 @@ Match the assertion to the kind of fact being tested.
 
 Choose fixtures with care when probing exception specifications. `helper_t` has a separate constructor for each value category, and its non-const-lvalue copy constructor is always `noexcept`. A `helper_t` configured to throw is therefore not throwing for every value category, and a specification that remains `noexcept` for that constructor may be correct. Use a plain local type when the test needs every relevant construction to be potentially throwing.
 
+## Client code
+
+Code written against the library — examples, documentation snippets, reproducers, anything a user of libfn might imitate:
+
+* Let the library derive graded error types. Never spell a multi-alternative `copack<...>` by hand — the canonical alternative order is internal and platform-dependent (MSVC orders class types after fundamentals); use `copack_for<...>`, and pin a deduced type with `static_assert` where the type is the point.
+* Give behaviour a constant-evaluation twin: a `static_assert` replaying the same operations. UB is ill-formed in a constant expression, so the compiler diagnoses what a runtime run may silently get wrong — users rely on the library in constexpr for exactly this.
+* Prefer monadic composition to unchecked access. `value()` is the library's only throw; reaching for it where `and_then`/`transform` would carry the value teaches the wrong idiom.
+* Don't trust a bare `requires`-probe of a libfn call: several refusals (`apply` on mismatched branches, `and_then` on grade mismatches) are `static_assert`s inside the callee, so the probe answers true and instantiation hard-errors. Compile the call to know; negative viability probes must be dependent (see `### Compile-time probes` above).
+* Outside `LIBFN_CXX26`, the internal type ordering is not expected to work with unnamed types or types without linkage — no lambdas or local types as `copack` alternatives in portable code.
+* One libfn version per binary: header-only makes mixing versions an ODR violation, including two `z` releases of the same `y` line; default and `LIBFN_CXX26` builds never link as one, by design — see README `## Versioning and ABI`.
+* A standalone reproducer (compiler or library bug) proves nothing until it is UB-free: gate it on UBSan and ASan with empty stderr as the criterion, not the exit code.
+
+## Header layering
+
+Four header trees under `include/`, each depending only on those below it:
+
+* `fn` — may use `fn/detail` and `pfn`
+* `fn/detail` — may use `pfn`, never `fn`
+* `pfn` — the C++23/26 polyfill; standalone except for the version header
+* `libfn_version.hpp` — the sole root header, no dependencies
+
+To make an `fn`-level facility available to `fn/detail`, hoist it: the implementation moves into `fn/detail/X.hpp` as `fn::detail::_name` (detail headers are not user-facing and carry no Doxygen); `fn/X.hpp` remains a thin public wrapper re-exporting it as `fn::name` (pattern: `fn/functional.hpp`).
+
 ## Versioning
 
 `VERSION` (in the repository root) is the single source of truth for the project version. A pre-commit hook (`scripts/sync_versions.py`) mirrors it into `ports/libfn/vcpkg.json` (`version-semver`), `MODULE.bazel`, and `include/libfn_version.hpp` — the header defining the `LIBFN_VERSION` macro that names the ABI-versioning inline namespace wrapping `fn`, and its mode-less sibling `LIBFN_VERSION_BASE` wrapping `pfn` (the layer rule below). Do **not** hand-edit those version literals — edit `VERSION` and let the hook sync them.
@@ -75,7 +98,7 @@ This repository uses [pre-commit](https://pre-commit.com/) to enforce formatting
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r ci/pre-commit/requirements.txt
-# Now install the pre-commit hooks locally
+# Install the pre-commit hooks locally
 pre-commit install
 ```