scaffold: README, LICENSE, design docs (spec + prereg from research repo 00c696d)

1 files changed, 34 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bae6cf7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# Prime Grokking
+
+Can minimal architectures learn the next-prime function — or *grok* it rather than memorize it?
+
+Experiment 1 (seed 0): weight-tied 2-layer RNN cell (K=20 tied steps, ACT learned halting)
+vs. a fixed-d_model transformer baseline, range n ∈ [2, 100], 30% holdout.
+
+## Layout
+
+```
+design/experiment-spec.md    design doc (copied from the research repo, provenance noted)
+design/preregistration.md    pre-registered outcome→interpretation matrix (LOCK: commit 00c696d in research repo)
+src/                         config, data, model API, models, train, eval
+tests/                       pytest suite (data correctness, model shapes, halting)
+scripts/                     run_experiment.sh, plot.py
+runs/                        metrics CSVs + plots (gitignored)
+```
+
+## Quick start
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu numpy matplotlib pytest
+.venv/bin/pytest tests/ -q
+scripts/run_experiment.sh rnn 0          # full run, ~35 min on 2 cores
+scripts/run_experiment.sh transformer 0
+scripts/plot.py
+```
+
+## Notes
+
+- Results are interpreted ONLY against `design/preregistration.md` (outcome codes O1–O8, H1–H4, P1–P4).
+- Seed-0 runs are anecdotes until seeds {1, 2}; no hyperparameter tuning on the val set.
+- Remote: `ssh://meru/~/projects/prime-grokking.git` (private; MIT license included for future publishing).