docs: phase3b quickstart and CLAUDE.md integration

Add Phase 3b status section to CLAUDE.md covering neural pipeline location,
Gohr-pattern constraint, checkpoint policy, hybrid-attack pair streams, and
CUDA XOR limitation. Append Phase 3b Quick start section to README.md with
train/recover-key examples and pair-stream explanation. Also apply ruff format
to bench_attack.py and test_neural_e2e_64r.py (no logic changes).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: cahlen

CLAUDE.md

@@ -2,6 +2,44 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Phase 3b status (2026)
+
+Neural differential cryptanalysis pipeline in `src/keeloq/neural/`, following
+Gohr 2019 adapted for KeeLoq's 1-bit-per-round key schedule. CLI:
+
+- `keeloq neural train --rounds N --delta 0xΔ --samples M --out <ckpt>`
+- `keeloq neural evaluate --checkpoint <ckpt> --rounds N`
+- `keeloq neural recover-key --checkpoint <ckpt> --rounds N --diff-pair <c0>:<c1> --sat-pair <pt>:<ct>`
+- `keeloq neural auto --rounds N --trained-depth D --samples M --checkpoint-out <path>`
+
+**Gohr-pattern constraint.** A distinguisher trained at depth D gives strong signal only on
+D-round pairs. Peeling K rounds with a single distinguisher works well only for small K. For
+deep-round attacks, train a family of distinguishers at strategic depths (e.g. D=56 for a
+64-round attack peeling K=8 rounds). The `auto` subcommand handles this automatically.
+`neural-target-bits` controls how many prefix key-bits the neural phase covers before handing
+off to SAT.
+
+**Checkpoint policy.** Checkpoints are NOT committed to the repo by default (external GPU
+contention prevented full training runs for d64.pt/d96.pt/d128.pt). Produce them via:
+
+    uv run keeloq neural auto --rounds 64 --trained-depth 56 \
+        --samples 10000000 --pairs 512 --checkpoint-out checkpoints/d64.pt
+
+The regression test `tests/test_neural_e2e_64r.py` auto-skips when `checkpoints/d64.pt` is
+absent. Benchmark runner (`benchmarks/bench_neural.py` + `benchmarks/neural_matrix.toml`) is
+smoke-safe against missing checkpoints.
+
+**Hybrid-attack CLI.** The `recover-key` subcommand takes two distinct argument streams:
+`--diff-pair <c0>:<c1>` (differential ciphertext pairs for the neural distinguisher) and
+`--sat-pair <pt>:<ct>` (plaintext:ciphertext pairs for the SAT suffix). These are separate
+because a differential attack doesn't require known plaintexts; only the SAT phase does.
+
+**CUDA XOR limitation.** `rshift_cuda` for uint32 is not implemented in PyTorch 2.11 + CUDA
+13. All XOR / delta application is done CPU-side before tensors are moved to the GPU.
+
+Checkpoints in `checkpoints/` with training metadata embedded. Results under
+`docs/phase3b-results/`. Spec/plan in `docs/superpowers/`.
+
 ## Phase 1 status (2026)
 
 The repo is mid-migration from the 2015 Python 2 scripts (now in `legacy/`, frozen) to a

README.md

@@ -44,3 +44,31 @@ Reproduce the 2015 README result (160 rounds, 25 hints, 2 pairs):
 See `docs/superpowers/specs/2026-04-22-phase1-foundation-design.md` for the
 design and `docs/superpowers/plans/2026-04-22-phase1-foundation-plan.md` for
 the implementation plan.
+
+## Phase 3b (neural cryptanalysis) — Quick start
+
+Train and attack end-to-end (GPU recommended, ~10 M samples):
+
+    uv run keeloq neural auto --rounds 64 --trained-depth 56 \
+        --samples 10000000 --pairs 512 \
+        --checkpoint-out checkpoints/d64.pt
+
+Or, if you have a pre-trained checkpoint:
+
+    uv run keeloq neural recover-key --checkpoint checkpoints/d64.pt \
+        --rounds 64 --diff-pair <c0>:<c1> --sat-pair <pt>:<ct> \
+        --beam-width 16 --sat-timeout 120
+
+**How it works (Gohr pattern).** A ResNet-1D-CNN distinguisher is trained at depth
+`--trained-depth D` (e.g. 56). It then peels K = rounds − D rounds (e.g. 8) one at a time
+via Bayesian beam search (`recover_prefix`), recovering the top K key bits. The remaining
+suffix bits are handed to Phase 1's XOR-aware encoder + CryptoMiniSat. Every recovered key
+is cipher-verified before reporting SUCCESS.
+
+**Separate pair streams.** `--diff-pair` carries differential ciphertext pairs (c0:c1) used
+by the neural distinguisher. `--sat-pair` carries known plaintext:ciphertext pairs used by
+the SAT solver. They are distinct because a differential attack does not require known
+plaintexts.
+
+See `docs/phase3b-results/benchmark.md` (generated by the benchmark runner after training)
+for neural-hybrid vs pure-SAT comparison across round counts.

benchmarks/bench_attack.py

@@ -2,6 +2,7 @@
 
 Reads benchmarks/matrix.toml, runs each config, writes a CSV + markdown summary.
 """
+
 from __future__ import annotations
 
 import csv
@@ -58,9 +59,7 @@ def run_matrix(matrix_path: Path, out_dir: Path) -> Path:
         pairs = [(p, encrypt(p, key, rounds)) for p in pts[:n_pairs]]
         hint_bits = run["hint_bits"]
         hints = (
-            {i: (key >> (63 - i)) & 1 for i in range(64 - hint_bits, 64)}
-            if hint_bits > 0
-            else None
+            {i: (key >> (63 - i)) & 1 for i in range(64 - hint_bits, 64)} if hint_bits > 0 else None
         )
 
         print(f"[bench] running {run['name']!r}...", flush=True)
@@ -73,23 +72,24 @@ def run_matrix(matrix_path: Path, out_dir: Path) -> Path:
             timeout_s=run["timeout_s"],
         )
         print(
-            f"  -> status={result.status} "
-            f"wall_time_s={result.solve_result.stats.wall_time_s:.3f}",
+            f"  -> status={result.status} wall_time_s={result.solve_result.stats.wall_time_s:.3f}",
             flush=True,
         )
-        rows.append({
-            "name": run["name"],
-            "rounds": rounds,
-            "num_pairs": n_pairs,
-            "hint_bits": hint_bits,
-            "encoder": run["encoder"],
-            "solver": run["solver"],
-            "status": result.status,
-            "wall_time_s": f"{result.solve_result.stats.wall_time_s:.3f}",
-            "num_vars": result.solve_result.stats.num_vars,
-            "num_clauses": result.solve_result.stats.num_clauses,
-            "num_xors": result.solve_result.stats.num_xors,
-        })
+        rows.append(
+            {
+                "name": run["name"],
+                "rounds": rounds,
+                "num_pairs": n_pairs,
+                "hint_bits": hint_bits,
+                "encoder": run["encoder"],
+                "solver": run["solver"],
+                "status": result.status,
+                "wall_time_s": f"{result.solve_result.stats.wall_time_s:.3f}",
+                "num_vars": result.solve_result.stats.num_vars,
+                "num_clauses": result.solve_result.stats.num_clauses,
+                "num_xors": result.solve_result.stats.num_xors,
+            }
+        )
 
     csv_path = out_dir / "results.csv"
     with csv_path.open("w", newline="") as f:

tests/test_neural_e2e_64r.py

@@ -1,4 +1,5 @@
 """Phase 3b 64-round hybrid attack using committed d64.pt (floor commitment)."""
+
 from __future__ import annotations
 
 import time
@@ -34,21 +35,26 @@ def test_64_round_full_key_recovery() -> None:
 
     n_pairs = 512
     gen = torch.Generator(device="cpu").manual_seed(31337)
-    pts0 = torch.randint(0, 1 << 32, (n_pairs,), generator=gen,
-                         dtype=torch.int64).to(dtype=torch.uint32, device="cuda")
+    pts0 = torch.randint(0, 1 << 32, (n_pairs,), generator=gen, dtype=torch.int64).to(
+        dtype=torch.uint32, device="cuda"
+    )
     pts0_cpu = pts0.cpu()
     delta_t = torch.tensor(delta, dtype=torch.uint32)
     pts1 = (pts0_cpu ^ delta_t).to("cuda")
     keys = torch.tensor(
         [[target_key & 0xFFFFFFFF, (target_key >> 32) & 0xFFFFFFFF]] * n_pairs,
-        dtype=torch.uint32, device="cuda",
+        dtype=torch.uint32,
+        device="cuda",
     )
     c0 = encrypt_batch(pts0, keys, rounds=attack_depth)
     c1 = encrypt_batch(pts1, keys, rounds=attack_depth)
-    diff_pairs = [(int(c0[i].item()) & 0xFFFFFFFF,
-                   int(c1[i].item()) & 0xFFFFFFFF) for i in range(n_pairs)]
-    sat_pairs = [(int(pts0_cpu[i].item()) & 0xFFFFFFFF,
-                  int(c0[i].item()) & 0xFFFFFFFF) for i in range(n_pairs)]
+    diff_pairs = [
+        (int(c0[i].item()) & 0xFFFFFFFF, int(c1[i].item()) & 0xFFFFFFFF) for i in range(n_pairs)
+    ]
+    sat_pairs = [
+        (int(pts0_cpu[i].item()) & 0xFFFFFFFF, int(c0[i].item()) & 0xFFFFFFFF)
+        for i in range(n_pairs)
+    ]
 
     t0 = time.perf_counter()
     result = hybrid_attack(