1 files changed, 105 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..56b76ec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# GAP minimal reproduction package
+
+This repository contains the generation and verification pipeline for GAP:
+four surface-renaming families and one proof-plan-preserving kernel variant.
+It is intentionally small and includes one canonical Putnam example for an
+end-to-end check.
+
+## One-click reproduction
+
+Open `GAP_End_to_End.ipynb` and choose **Run All**. The notebook:
+
+1. installs the package;
+2. loads one canonical problem;
+3. generates four surface variants;
+4. runs the five-stage kernel pipeline;
+5. applies five judges until the same candidate receives two consecutive
+   unanimous rounds;
+6. exports and validates one machine-readable GAP record.
+
+The default live model is `o3`. Set `OPENAI_API_KEY` before starting Jupyter,
+or enter it in the notebook's hidden prompt. The key is not written to the
+notebook or run artifacts.
+
+To test the complete software path without API calls:
+
+```bash
+GAP_OFFLINE_SMOKE=1 jupyter notebook GAP_End_to_End.ipynb
+```
+
+Offline smoke mode uses scripted model responses. It validates pipeline wiring,
+verification control flow, and release assembly; it does not evaluate generated
+mathematical content.
+
+## Install and test
+
+```bash
+python -m pip install -e '.[api,test]'
+pytest
+```
+
+Without installation:
+
+```bash
+PYTHONPATH=src pytest
+PYTHONPATH=src python -m gap_pipeline.cli --help
+```
+
+## Live one-item commands
+
+Generate the kernel variant:
+
+```bash
+export OPENAI_API_KEY=...
+PYTHONPATH=src python -m gap_pipeline.cli generate-kernel \
+  --dataset examples/sample_data \
+  --item-id 1998-B-1 \
+  --run-dir runs/kernel \
+  --proposer-model o3 \
+  --judge-model o3
+```
+
+Generate all surface variants:
+
+```bash
+PYTHONPATH=src python -m gap_pipeline.cli generate-surfaces \
+  --dataset examples/sample_data \
+  --item-id 1998-B-1 \
+  --run-dir runs/surface \
+  --proposer-model o3
+```
+
+Assemble the final record after both runs complete:
+
+```bash
+PYTHONPATH=src python -m gap_pipeline.cli export-release \
+  --source-dataset examples/sample_data \
+  --surface-run-dir runs/surface \
+  --kernel-run-dir runs/kernel \
+  --output-root release \
+  --item-id 1998-B-1
+```
+
+## Protocol
+
+The kernel path consists of:
+
+1. reference solution → proof DAG;
+2. proof DAG → content-free method plan;
+3. guarded replacement at a DAG leaf;
+4. replacement diffusion through the fixed DAG;
+5. regenerated proof → self-contained problem statement.
+
+Verification uses `J=5` judges, requires `K=2` consecutive unanimous rounds for
+the same candidate, and permits at most `T=15` rounds. A non-unanimous round
+resets the pass streak and triggers repair.
+
+`STAGE_MAP.md` maps each paper operation to the implementation and its validated
+output. Every model call and intermediate stage is saved below the selected run
+directory for inspection.
+
+## Reproducibility scope
+
+LLM generation is stochastic, so repeated live runs need not produce identical
+wording. This package reproduces the prompts, transformation stages, typed
+structural checks, verification state machine, and release format.