docs: add README with setup and end-to-end smoke test

Expand Development section with complete setup instructions (venv, calibration, config, run), add Running tests section, and include end-to-end smoke test checklist for real-hardware validation. Update phase-status table to reflect that Phase 1 is built and unit-tested, pending real-hardware validation.

README.md

@@ -15,12 +15,11 @@ volunteer/client work — it isn't part of any commercial product line.
 
 ## Status
 
-**Early / active development.** The intake station (Phase 1) is being
-built now. Not yet runnable end-to-end.
+**Phase 1 (intake station) is built, unit-tested, and ready for real-hardware validation.** Phase 2 (batch OCR/ISBN backfill) and Phase 3 (checkout station) are planned for later.
 
 | Phase | What it does | Status |
 |---|---|---|
-| 1 — Intake station | Camera capture, guided front/back flow, deterministic size bucketing, CSV catalogue | In progress |
+| 1 — Intake station | Camera capture, guided front/back flow, deterministic size bucketing, CSV catalogue | Built, unit-tested — pending real-hardware validation |
 | 2 — Batch OCR/ISBN backfill | Barcode decode + local vision-LLM fallback to fill in title/author/ISBN | Planned |
 | 3 — Checkout station | Track books leaving inventory, reusing the intake identification pipeline | Planned |
 
@@ -55,15 +54,69 @@ same file, symlinked for compatibility with different AI coding tools).
 
 Requires Python 3.11+.
 
+### Setup
+
+1. Create and activate a virtual environment:
+   ```bash
+   python3 -m venv .venv
+   .venv/bin/pip install -e ".[dev]"
+   ```
+
+2. Mount the USB webcam over the capture platform. See the design spec
+   (`circuitforge-plans/books-in-hand/superpowers/specs/2026-07-13-inventory-system-design.md`)
+   for physical setup details: nested size-boundary markers, guide box.
+
+3. Run calibration once per physical install, with the platform empty:
+   ```bash
+   .venv/bin/python calibrate.py <camera_device_index> reference.jpg
+   ```
+   This captures a reference image of the empty platform for marker detection.
+
+4. Copy `config.example.json` to `config.json` and fill in:
+   - `markers`: pixel coordinates (from the reference image)
+   - `guide_box`: capture region boundaries
+   - `trigger_strategy`: one of `manual`, `motion_stop`, or `stable_centered`
+
+5. Run the backend:
+   ```bash
+   .venv/bin/python run.py config.json
+   ```
+
+6. Open `http://<machine-ip>:8000` in a kiosk-mode browser on the station's monitor.
+
+### Running tests
+
 ```bash
-python3 -m venv .venv
-.venv/bin/pip install -e ".[dev]"
 .venv/bin/pytest -v
 ```
 
-Full setup, calibration, and end-to-end testing instructions will land
-here once the intake station is runnable (tracked in the project's
-implementation plan).
+All tests run without requiring real camera hardware — they use synthetic
+NumPy frames and mocked `cv2.VideoCapture`.
+
+### End-to-end smoke test (manual, requires real hardware)
+
+This checklist is for whoever installs this system on real hardware. It
+verifies that the intake workflow functions end-to-end.
+
+1. Boot the station per Setup above with `trigger_strategy: "manual"`.
+2. Place a book on the platform, click "Capture" — confirm the status
+   advances to "Front captured — flip it over" and a new row appears in
+   `catalogue.csv` with a `size_bucket` value and populated
+   `front_wide_path` / `front_cropped_path` columns pointing at real files
+   under `captures/<book_id>/`.
+3. Flip the book, click "Capture" again — confirm status advances to
+   "Book complete!" and the same row now has `back_wide_path` /
+   `back_cropped_path` populated.
+4. Click "Next Book" — confirm status returns to "Waiting for book..." and
+   the next capture gets a different `book_id`.
+5. Repeat with a small book and a large book — confirm `size_bucket`
+   differs correctly between them, matching which physical markers each
+   book actually covers.
+6. Switch `trigger_strategy` to `motion_stop` in `config.json`, restart,
+   and confirm placing a book and holding it still triggers capture
+   without pressing the button.
+7. Switch to `stable_centered` and repeat, confirming capture fires once
+   the book is centered and steady in the guide box.
 
 ## License