docs: ephapax↔AffineScript disambiguation hooks (README + CLAUDE.md + a2ml)

.machine_readable/6a2/AGENTIC.a2ml

@@ -32,5 +32,26 @@ banned = ["typescript", "go", "python", "makefile"]
 # NEVER modify formal proofs (Coq/Idris2) without verifying them.
 # Always run `just golden` before committing to ensure proof closure.
 # Respect the dyadic boundary: affine vs linear must be explicitly handled.
-last-modified-at = "2026-04-23T13:00:00Z"
-modification-summary = "Initial creation from 1.0.0 template"
+last-modified-at = "2026-05-26T20:00:00Z"
+modification-summary = "Added @disambiguation block — Ephapax vs AffineScript canonical pointer"
+
+# ── Disambiguation ────────────────────────────────────────────────────────
+# AI agents have repeatedly conflated this repo (Ephapax) with the unrelated
+# language AffineScript (hyperpolymath/affinescript). The two share exactly
+# one thing — both target hyperpolymath/typed-wasm — and otherwise have
+# different ASTs, type checkers, compilers, and proof stories. The shared
+# `affine` syllable names a substructural-logic property in BOTH cases (it's
+# a logic-family name), not a project relationship.
+[agentic-config.disambiguation]
+this = "hyperpolymath/ephapax"
+canonical-name = "Ephapax"
+distinct-from = ["hyperpolymath/affinescript"]
+shared-with-distinct = ["hyperpolymath/typed-wasm"]
+internal-sublanguages = ["ephapax-linear", "ephapax-affine"]
+# `ephapax-affine` is an internal sublanguage of THIS repo (dyadic with
+# ephapax-linear, one AST, one Rust crate). It is NOT the AffineScript
+# language at hyperpolymath/affinescript.
+ephapax-affine-is-not-affinescript = true
+canonical-doc = "https://github.com/hyperpolymath/nextgen-languages/blob/main/docs/disambiguation/ephapax-vs-affinescript.md"
+canonical-memory-entry = "feedback_affinescript_ephapax_siblings_not_impl_proof.md"
+do-not-apply-cross-repo-lessons-without-explicit-check = true

CLAUDE.md

@@ -0,0 +1,52 @@
+<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
+<!-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->
+
+# CLAUDE.md — Ephapax repo agent guidance
+
+## 🚨 Disambiguation (read first)
+
+**This repo is `hyperpolymath/ephapax`.** It is **NOT** `hyperpolymath/affinescript`.
+
+| | This repo | NOT this repo |
+|---|---|---|
+| Name | **Ephapax** | AffineScript |
+| Path | `hyperpolymath/ephapax` | `hyperpolymath/affinescript` |
+| File extension | `.eph` | `.affine` (plus face dialects) |
+| Build | `Cargo.toml` at root | `dune-project` at root |
+| Type checker | `ephapax-linear/src/{linear,affine}.rs` (Rust) | `lib/borrow.ml` (OCaml) |
+| Proofs | `formal/Semantics.v` (Coq), `src/abi/Ephapax/…` (Idris2) | None mechanized; `lib/borrow.ml` only |
+
+**Internal naming trap.** Ephapax itself is dyadic. Inside this repo:
+- **ephapax-linear** = strict, formally-verified core.
+- **ephapax-affine** = versatile prototyping companion to ephapax-linear.
+
+Both are *internal sublanguages*. They share one AST, one Rust crate (`ephapax-linear/`), one grammar directory. **The `ephapax-affine` sublanguage is NOT AffineScript.** The word `affine` is shared because both happen to be substructural-logic-family type systems — that's a logic-family fact, not a project relationship.
+
+**Rule for agents:** before applying any prior-session lesson, memory entry, or snippet, check whether it was about *ephapax* or about *AffineScript*. They share zero AST / typing / borrow-checker / codegen. The only shared surface is the compile target (`hyperpolymath/typed-wasm`).
+
+When in doubt: state the context shift explicitly ("switching from AffineScript context to ephapax context") so the user sees the boundary respected.
+
+**Canonical disambiguation doc** (single source of truth):
+https://github.com/hyperpolymath/nextgen-languages/blob/main/docs/disambiguation/ephapax-vs-affinescript.md
+
+**Companion memory entry** (in user auto-memory):
+`feedback_affinescript_ephapax_siblings_not_impl_proof.md`
+
+---
+
+## Machine-readable artefacts
+
+Structured project metadata lives in `.machine_readable/6a2/`:
+
+- `STATE.a2ml` — current project state and progress.
+- `META.a2ml` — architecture decisions and development practices.
+- `ECOSYSTEM.a2ml` — position in the ecosystem and related projects.
+- `AGENTIC.a2ml` — AI agent interaction patterns (also carries an `@disambiguation` block).
+- `NEUROSYM.a2ml` — neurosymbolic integration config.
+- `PLAYBOOK.a2ml` — operational runbook.
+
+## Standing reminders
+
+- Formal-proof work touches `formal/Semantics.v` (Coq) and `src/abi/Ephapax/…/*.idr` (Idris2). Both build oracles are authoritative; `coqc` and `idris2 --check` are the only "is this proved?" answers.
+- Preservation closure plan: see `ROADMAP.adoc` § "Preservation closure plan" and `formal/PRESERVATION-HANDOFF.md`.
+- All commits GPG-signed (key `4A03639C1EB1F86C7F0C97A91835A14A2867091E`), email `6759885+hyperpolymath@users.noreply.github.com`. Auto-merge ON for every PR.

README.adoc

@@ -16,6 +16,30 @@ image:https://api.thegreenwebfoundation.org/greencheckimage/ephapax.org[Green Ho
 
 _ἐφάπαξ — once for all._
 
+[IMPORTANT]
+.Not to be confused with AffineScript
+====
+This is **Ephapax**, a research language for WebAssembly memory safety.
+It is *not* https://github.com/hyperpolymath/affinescript[AffineScript], a
+separate language at `hyperpolymath/affinescript` that succeeds JS / TS /
+ReScript.
+
+The two share **exactly one thing**: both target
+https://github.com/hyperpolymath/typed-wasm[typed-wasm]. They have separate
+ASTs, separate type checkers, separate compilers, separate proof stories.
+The word `affine` overlaps in both names because it names a substructural-
+logic property — that's a logic-family fact, not a project relationship.
+
+Internal note: Ephapax is itself dyadic — `ephapax-linear` (strict core)
+and `ephapax-affine` (versatile prototyping companion) are *both inside this
+repo*, one Rust crate, one AST, two structural disciplines. **`ephapax-affine`
+is not AffineScript.** When ambiguous, write "ephapax-affine sublanguage"
+vs "AffineScript language".
+
+Canonical disambiguation:
+link:https://github.com/hyperpolymath/nextgen-languages/blob/main/docs/disambiguation/ephapax-vs-affinescript.md[nextgen-languages/docs/disambiguation/ephapax-vs-affinescript.md].
+====
+
 A dyadic linear+affine type system for compile-time WebAssembly
 memory safety. Resources are tracked through the type system so the
 compiler can guarantee — without a garbage collector — that no value