docs: rewrite the README in plain English and add a developer guide

[hseshadr]

What this changes

Rewrites the README in plain English, following the standard approved on aml-filter#151, and adds a developer guide.

Claim touched: none of the product's behavior. This is docs and doc-contract tests only; no library code changes (two docstrings updated to point at the new doc location).

First 15 lines, before

# EdgeProc

For Python apps that ship data to devices: each one checks it's genuine, downloads only changes, and searches offline.

[![CI](https://github.com/hseshadr/edge-proc/actions/workflows/dagger.yml/badge.svg)](https://github.com/hseshadr/edge-proc/actions/workflows/dagger.yml)
[![Version](https://img.shields.io/github/v/tag/hseshadr/edge-proc?label=version)](CHANGELOG.md)
[![License](https://img.shields.io/github/license/hseshadr/edge-proc)](LICENSE)

[Docs](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md)

```text
input:  a two-product catalog, published and signed on your machine, then pulled into a
        "device" folder; then one new file; then one piece corrupted on the server
output: synced v1.0.0 manifest=71d733a8dddb chunks_fetched=1 chunks_reused=0 bytes_fetched=70
        synced v1.0.1 manifest=18499ab39ead chunks_fetched=1 chunks_reused=1 bytes_fetched=27

First 15 lines, after

# EdgeProc

A Python library for sending data files to many devices: each device checks they came from you, downloads only what changed, and can search them offline.

**Try it in a minute: `pip install "edge-proc[bundles]"`, then run the commands under [Try it](#try-it). No server or account needed.**

Say your app needs the same data on many devices you don't control: a product catalog, a
search index, a price list, a small AI model. The usual way is to put the file on a web
server and have each device download it. That has two problems. A device can't tell if the
file was corrupted or swapped on the way, so it may quietly give wrong answers. And when one
line changes, every device downloads the whole file again.

EdgeProc handles both. You publish a folder once, on your own machine: it cuts the files into
small pieces and signs a list of them with your private key. You upload the result to any
plain web server. Each device downloads only the pieces it doesn't have yet, checks them all

Where the old README content went (nothing deleted)

Old README section	Now in
At a glance, problem story	README intro paragraphs
Try it in 60 seconds	README ## Try it (same commands, re-run against PyPI 0.5.0, plus the no-key refusal)
How it answers them, security and trust model, verification chain, key rotation, what this proves	docs/ARCHITECTURE.md
Full walkthrough	already in docs/QUICKSTART.md (linked)
Prefer to stay in Python?	docs/QUICKSTART.md#use-it-from-python
Router, Task/budget, saved indexes	docs/ARCHITECTURE.md
Configuration table + EDGEPROC_ERROR_FORMAT	new docs/CONFIGURATION.md
Why this and not X	README ## When to use something else
Limitations & roadmap	README ## What it does not do + ROADMAP.md
Contributing / development	README ## Develop + new docs/GETTING_STARTED.md

New README sections: ## How it fits with the related projects (edgeproc-core underneath; @edgeproc/browser checks the same signed format in a web page; edge-reco is a demo store using them; privacy-core shares the @edgeproc npm scope but is unrelated and does not use EdgeProc).

Tests (red first)

• tests/test_readme_contract.py rewritten: pins name, tagline == pyproject description, bold try-it line, at most 3 badges, section order, the Technical docs: line (Architecture first, Getting started present), ## Develop links Getting started, ## More detail links every technical doc, related-projects section names edgeproc-core / @edgeproc/browser / privacy-core, retired template headings gone, and a banned-jargon check (northstar, seam, fail-closed, gate, fleet, portfolio, substrate, hype words) outside code spans. Plus a check that GETTING_STARTED has all six required sections.
• tests/test_release_contract_docs.py: README-pinned facts retargeted to where the content now lives (config table -> docs/CONFIGURATION.md, MemoryManager wording -> docs/ARCHITECTURE.md, Dagger-scope claim -> docs/GETTING_STARTED.md). The lock-free read-only loads check now covers OPERATIONS + ARCHITECTURE only (the README no longer discusses persistence). README still must name the 0.5.0 version, the edgeproc-core>=0.4.3 floor, both refusal codes, the active pointer file, run_loop.sh inside Try it, and must not restate p50/p95.
• Contract reversed, said loudly: docs/QUICKSTART.md pinned "uv run poe gate | ~20 s". That was false: from a fresh clone it took 204 s (pytest alone 110 s). The pin now reads "about 3.5 min".
• Red run: 35 failures before the rewrite. Guard proven: injecting "robust fail-closed substrate" into the README turns 3 jargon tests red.

Evidence

Check	Result
pip install "edge-proc[bundles]" (0.5.0 + edgeproc-core 0.4.3) in a fresh 3.13 venv, README Try it run verbatim	output pasted in README matches byte for byte except key_id
bash examples/run_loop.sh on a fresh clone	exit 0, 117 s
Python API example (QUICKSTART)	p1 0.219, p3 0.374, p2 0.556, matches
uv run poe gate on this branch	exit 0, 769 passed, 98.63% coverage
dagger call ci locally on a fresh clone of main	exit 0, ~10 min (first attempt failed on a leftover .coverage; documented as a trap)
GETTING_STARTED first-change walkthrough (add demo_flag)	the 3 failing tests listed there are exactly what failed
git merge-tree vs #77 head	clean, no conflicts

Proposed GitHub About description

A Python library for sending data files to many devices: each device checks they came from you, downloads only what changed, and can search them offline.

(Not applied; repo settings unchanged.)

Note on PyPI

The pyproject description changes to match the new first line. The PyPI project page (summary and long description) only updates on the next release; 0.5.0 on PyPI keeps the old README until then.

🤖 Generated with Claude Code

https://claude.ai/code/session_015oBArfm762nN1r4F4Fst5a