diff --git a/README.md b/README.md
index 1133f12..8e4a2b5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,46 @@
 # Entropy-RNG: Camera-Based Random Number Generator
 
-This project uses a live video feed from a network camera (e.g. an **Axis M1013**) to generate cryptographically secure random numbers. The camera is pointed at a high-contrast, ever-changing scene (e.g. ceiling and lamps) so the pixel data carries genuine entropy.
+This project uses a live video feed from a network camera (e.g. an **Axis M1013**) to generate cryptographically secure random numbers. The camera is pointed at a high-contrast, ever-changing scene (e.g. ceiling and lamps) so the pixel data carries genuine entropy. The output can be used locally (feeding the kernel RNG via `rngd`) or served over HTTP so remote systems can pull entropy to seed their own pools.
+
+---
+
+## What Changed
+
+This section records the rewrite from the original scripts to the current pipeline. Each bullet maps to a commit in `git log`.
+
+### Core RNG fix (the important one)
+The original code computed a SHA-256 of the camera frame into a variable named `entropy` and then **discarded it**, drawing instead from the OS CSPRNG via `secrets.randbits()`. The camera contributed nothing — the output was just relabeled `/dev/urandom`.
+
+- Replaced with a **NIST SP 800-90A HMAC-DRBG** (SHA-256) seeded from the frame hash. The camera now genuinely contributes entropy.
+- The DRBG is reseeded every frame, so output changes even when camera noise is modest.
+- Added `--interval` for loop rate control, `--out` for writing raw bytes to a FIFO, mutual exclusion of `--loop`/`--single`, and bit-multiple validation.
+
+### Health checks
+- Added `health.py` with **FIPS 140-2 continuous tests** (monobit, runs, long-run) on the raw JPEG bytes before hashing.
+- A frozen, all-identical, or degraded frame is rejected and never seeds the DRBG.
+- Runs thresholds are doubled because we count 0-runs and 1-runs together.
+- `--no-health` disables the checks for debugging.
+
+### Cleanup
+- Removed `entropy-rng-cam.py` and `entropy-rng-opencv.py`, which were superseded by `entropy.py` and carried the same unused-entropy bug.
+- Removed the empty 0-byte `file`.
+- Added `requirements.txt` with pinned dependencies.
+
+### HTTP service + container deployment
+- Added `api.py` — a FastAPI app that runs the camera producer in a background thread and serves the latest entropy blob over HTTP.
+- Added `Dockerfile` for container builds, with a healthcheck against `/healthz`.
+- All config is via environment variables for containers.
+
+### Auth (simple by design)
+- Single shared secret via `X-API-Key` header, controlled by `ENTROPY_API_KEY`.
+- Empty key means no auth, so you can start open and lock down by setting one env var.
+- The API layer is where HMAC-signed blobs or mTLS plug in later — no architecture change needed.
+
+### Tests
+- Added `test_entropy.py` — 16 tests covering the DRBG, health checks, a bit-balance smoke test, and API auth gating. All pass without a camera (the producer is stubbed).
+
+### Docs
+- Rewrote this README and `notes.md` to match the new pipeline and commands.
 
 ---
 
@@ -16,14 +56,32 @@ This project uses a live video feed from a network camera (e.g. an **Axis M1013*
 
 ## Requirements
 
+### Software
 - Python 3.10+
-- `opencv-python`, `fastapi`, `uvicorn`, `pytest`
+- Python packages: `opencv-python`, `fastapi`, `uvicorn`, `pytest`
 
+### System libraries (Debian/Ubuntu)
+OpenCV needs runtime libraries that are not pip-installed:
+```bash
+sudo apt-get install libgl1 libglib2.0-0
+```
+
+### Install Python dependencies
 ```bash
 pip install -r requirements.txt
 ```
 
-On Debian/Ubuntu you also need OpenCV runtime libs: `apt-get install libgl1 libglib2.0-0`.
+### Hardware
+- An IP webcam serving an MJPEG stream over HTTP (e.g. Axis M1013 at `http://192.168.0.200/mjpg/video.mjpg`).
+- The camera must be pointed at a dynamic, high-contrast scene. A static frame will fail health checks and be rejected.
+
+### For the kernel-RNG flow
+- Linux with `rngd` installed (`rng-tools` package).
+- `sudo` privileges to run `rngd`.
+
+### For container deployment
+- Docker (or any OCI-compatible runtime) for local containers.
+- Kubernetes for orchestrated deployment (optional).
 
 ---
 
@@ -142,3 +200,4 @@ Covers the HMAC-DRBG (determinism, reseed, length, reseed limit), health checks
 - Point the camera at a dynamic scene. A static frame will fail health checks and be rejected.
 - The DRBG is reseeded from each frame, so output changes even if the camera noise is modest.
 - Auth is a single shared secret for now. When you need per-client keys, rotate to HMAC-signed blobs or mTLS — the API layer is where that plugs in.
+- The 256-bits-per-frame entropy credit is conservative. If you want a defensible number for your specific camera, run `ent` or `rngtest` on a captured sample.