chore: src-layout, notebooks→examples, distribute working docs out of root

.gitignore

@@ -10,7 +10,7 @@ tests/assets/vdjdb.slim.txt.gz
 tests/assets/real_repertoires/
 tests/assets/srx_repertoires/
 *.airr.tsv
-notebooks/assets/
+examples/assets/
 
 ## VSCode
 
@@ -184,10 +184,10 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
-mir/docs
+src/mir/docs
 .idea
 public
-notebooks/assets/derived/
+examples/assets/derived/
 
 # ML run artifacts (checkpoints/metrics) — never committed
 experiments/runs/

CHANGELOG.md

@@ -36,6 +36,11 @@ Python API removed; one optional-dependency group split out.
 - Documentation overhaul: a use-case-driven user guide, the two CLI commands documented, an
   examples/notebooks page, `mir.cohort` and `mir.bench.eval` added to the API reference, a logo, and
   the sample-embedding schematic + real depth-robustness figure. Zero-warning Sphinx build.
+- **Repo layout** (no effect on the installed package): adopted the **src-layout** (`mir/` →
+  `src/mir/`); renamed `notebooks/` → `examples/`; and moved the working result/plan markdown out of
+  the repo root — `THEORY.md` to the manuscript repo, `BENCHMARKS.md` / `REPERTOIRE_{EMBEDDING,LESSONS}.md`
+  / `SQRT_D_MIGRATION.md` / `ROADMAP.md` to `2026-mirpy-analysis/benchmarks/`. Root keeps
+  README / CHANGELOG / CLAUDE / SOURCES.
 
 ### Fixed
 

CLAUDE.md

@@ -8,9 +8,12 @@ frozen on branch **`legacy-v2`** (`mirpy-lib` 2.x) — do not develop there.
 
 ## Repo split (2026-07-16) — three homes
 This repo is now **the library + its CI/test data only**. Analysis and manuscript live elsewhere:
-- **`~/vcs/code/mirpy`** (here): `mir/` library, unit + fast/slow CI tests (`tests/`, on slim bundled
-  data), plans for new features, docs, and **slim tabular benchmark results** for README/docs. Benchmark
-  *scripts* and the theory *appendix* have moved out (below).
+- **`~/vcs/code/mirpy`** (here): **src-layout** — the library is `src/mir/` (import `mir`); unit +
+  fast/slow CI tests (`tests/`, on slim bundled data), runnable `examples/` (marimo), docs. As of the
+  3.4.x cleanup the result/plan markdown moved out: **`THEORY.md` → the manuscript repo**;
+  **`BENCHMARKS.md`, `REPERTOIRE_{EMBEDDING,LESSONS}.md`, `SQRT_D_MIGRATION.md`, `ROADMAP.md` →
+  `2026-mirpy-analysis/benchmarks/`**. Only `README`/`CHANGELOG`/`CLAUDE`/`SOURCES` stay at the root.
+  Benchmark *scripts* and the theory *appendix* had already moved out (below).
 - **`~/vcs/projects/2026-mirpy-analysis`**: all **benchmark scripts** (`benchmarks/` — local + aldan3),
   full result docs (BENCHMARKS/THEORY/…), figures, run outputs, dataset catalog. Run the mirpy library
   from here; refresh numbers-of-record here.
@@ -53,7 +56,7 @@ negative S2) — so prototypes use real reads, not model generation.
 mirpy is normally read-only to the sibling repos; the `from_arda` builder + a tandem-D generation
 fix were added to `vdjtools` under the owner's direction (this is that owner's ecosystem).
 
-## Layout (`mir/`)
+## Layout (`src/mir/`)
 - `aliases.py`, `alleles.py` — species/locus + allele normalization.
 - `distances/junction.py` — `junction_distance_matrix` (seqtree.gapblock). Coordinate knobs (all
   default to the published space, threaded through `TCREmp`): `metric="squared"` (=`d`, default) |
@@ -148,7 +151,8 @@ fix were added to `vdjtools` under the owner's direction (this is that owner's e
   GPU only in `mir.ml`: `pick_device()` = **CUDA → MPS → CPU** auto, override `device=`/`MIR_DEVICE`.
 
 ## Open loops / next steps
-- **Embedding-tier roadmap** (`ROADMAP.md`, 2026-07-17) — the "vdjtools at the embedding level" audit +
+- **Embedding-tier roadmap** (`2026-mirpy-analysis/benchmarks/ROADMAP.md`, moved out in the 3.4.x
+  cleanup) — the "vdjtools at the embedding level" audit +
   plan (three verbs: make / measure / generate-decode). **Phase 0** (robustness + optimization quick wins)
   and **Phase 1** (cohort tier: `bench/eval.py`, `repertoire.{fit_repertoire_spaces,centroid_atypicality}`,
   `cohort.py` digital donor) are **DONE**. Next: **Phase 2** generative loop (`generate.py` `DescriptorDensity`

README.md

@@ -17,7 +17,7 @@
 **mirpy v3** turns T-/B-cell receptor sequences into fixed-length numeric vectors you can
 cluster, visualize, and feed to ML models. It implements **TCREMP** — embedding each receptor
 by its alignment distances to a fixed set of *prototype* sequences — so that Euclidean distance
-in embedding space approximates pairwise alignment distance (see [`THEORY.md`](THEORY.md)).
+in embedding space approximates pairwise alignment distance (Theory T1).
 
 > v3 is a slim, embedding-focused rewrite. The classical repertoire toolkit (parsing, overlap,
 > diversity, TCRnet, GLIPH, …) lives on the **`legacy-v2`** branch (`mirpy-lib` 2.x) and in the
@@ -186,17 +186,18 @@ a batch offset is first-order and cancels, while a batch-orthogonal signal (e.g.
 empirical rule of thumb — **diversity for how-even, the embedding for which-clones**: clone-size
 phenotypes (age, CMV) are a diversity summary's turf, while clonotype identity (HLA — strongest in
 TRA and class II) lives in the second moment / witness. A learned co-equal set encoder
-(Set-Transformer / DeepRC) is in `mir.ml.set_encoder` (`[ml]` extra). See [`BENCHMARKS.md`](BENCHMARKS.md)
-and [`THEORY.md`](THEORY.md) T7 (the benchmark scripts themselves live in the analysis repo).
+(Set-Transformer / DeepRC) is in `mir.ml.set_encoder` (`[ml]` extra). Recorded results and theory
+(T7) live in the companion [`2026-mirpy-analysis`](https://github.com/antigenomics) repo
+(`benchmarks/{BENCHMARKS,THEORY}.md`) alongside the benchmark scripts.
 
 ## Reproduce the paper
 
 The self-contained theory notebooks run on bundled data:
 
 ```bash
 pip install "mirpy-lib[examples]"
-marimo edit notebooks/theory.py         # supplementary S1–S3 (distance laws, D↔d, prototype robustness)
-marimo edit notebooks/quickstart.py     # embed + cluster VDJdb antigens
+marimo edit examples/theory.py          # supplementary S1–S3 (distance laws, D↔d, prototype robustness)
+marimo edit examples/quickstart.py      # embed + cluster VDJdb antigens
 ```
 
 The full benchmark suite (VDJdb Table S1, density, repertoire/TCGA) and result docs live in the