Every document in this repository, one line each — start with the root README, and see AGENTS.md for how to work here.
Backlog of record: GitHub Issues with the fleet labels (.github/sdlc.yml).
New to ocrmd? Read setup, then scanning or point ocrmd ingest at a folder, then output to see what you got. The two files under reference/ are generated from the code by tools/gen_reference.py; this index is generated by tools/docs_index.py.
| Document |
What it covers |
AGENTS.md |
A webcam, image and PDF book scanner that reads every page twice — local OCR and a vision LLM — and diffs the readings into cross-checked Markdown with a searchable inventory. |
CHANGELOG.md |
Release history: the notable changes in each version, newest first. |
PRD.md |
What ocrmd is for and whom it serves: the problem, users, goals and non-goals, current features, requirements, proposed success metrics and open questions. |
| Document |
What it covers |
docs/ARCHITECTURE.md |
The design, module by module, with the measurement behind each default: capture and the auto-shutter, preprocessing, local OCR and the LLM pass, reconciliation, the page format, storage, concurrency, and the build history. |
docs/constitution.md |
The rules every change to this repo must satisfy, whoever makes it — a human or an AI agent. Agents read this before AGENTS.md conventions, the PRD, or the feature catalog. Ratified… |
docs/corpus.md |
What to do with pages once they are scanned: the SQLite inventory and full-text search, the four export formats, and structured-data extraction with ocrmd etl. |
docs/integrations.md |
How a page leaves ocrmd: the sink contract a receiver speaks (law-ai is the worked example), and ocrmd.api.Library for embedding the whole pipeline in another program. |
docs/operations.md |
Running ocrmd day to day — degraded mode, costs, camera drop-outs, health checks, upgrades, logs, sharing one root — and debugging it in VS Code. |
docs/output.md |
What ocrmd writes under its root, what each page's verification status means and what to do about it, and which of your edits survive a re-run. |
docs/round-trip.md |
ocrmd reconstruct rebuilds each page from its Markdown and scores it against the photograph; ocrmd annotate folds pen and highlighter marks made on scanned paper back into the Markdown. |
docs/scanning.md |
How to set up the camera rig, read the scan window, get captures the OCR can use, and tune the auto-shutter — with the measurement behind each default. |
docs/setup.md |
What a working install needs beyond pip install: macOS camera permission, Claude credentials and which models they reach, the local OCR engines, and where settings come from. |
docs/web-ui.md |
What each view of ocrmd serve shows and does — library, scan, documents, page, jobs and settings — and the rules it shares with the CLI. |
docs/adr/ |
Every hard-to-reverse decision made for ocrmd, one record each, and the format a new record follows. |
docs/amendments/ |
The append-only log of changes to the constitution. |
| Document |
What it covers |
examples/captures/ |
Real webcam frames and two generated PDFs from this project's own scans, for trying the pipeline without a camera — and what each one exercises. |
| Document |
What it covers |
docs/reference/cli.md |
Every ocrmd command, argument and option with its default — read from the typer app in ocrmd/cli.py, so it cannot drift from the code. |
docs/reference/settings.md |
Every Settings field in ocrmd/config.py — its OCRMD_* environment variable, type, built-in default and the note written beside it in the source. |