docs: rewrite the README in plain English

[hseshadr]

Rewrites the README in plain English, following the standard approved on hseshadr/aml-filter#151. Touches the claim "each customer only sees their own results": the README now demonstrates it with real output (and shows the unfiltered admin view next to it) instead of asserting it.

What changed

• README.md: one plain sentence, the install line, the problem, a 3-step walkthrough with real output, how it works, how it relates to edge-proc / edge-reco / @edgeproc/browser / privacy-core, honest limits, install, develop, and a link to every doc. 497 → 176 lines.
• docs/ARCHITECTURE.md (new): everything technical moved out of the README, nothing deleted: routing, strategies, conformance suite table, error module, configuration, source tree, alternatives, security model, coverage and benchmark figures, shipped vs planned.
• docs/GETTING_STARTED.md (new): fresh clone to green build to a first change. Every command was run from a fresh clone and timed (clone 2s, uv sync 2s, poe gate 45s). Records a real trap: a shallow clone fails test_changelog_provenance.
• pyproject description now equals the new first line. PyPI will keep showing the old README and description until the next release; nothing is published here.
• docs/README.md, CONTRIBUTING.md, CLAUDE.md, installation-guide.md: links retargeted. CHANGELOG entry under [Unreleased].

Contract tests (red first)

With the new tests and the old README, 20 tests failed for the right reasons (missing sections, missing docs/ARCHITECTURE.md, banned template headings). Then green.

• tests/test_readme_contract.py now pins: title + pyproject description, bold install line, ≤3 badges, section order, the technical-docs line (Architecture + Getting started), Getting started linked from Develop, real output in Try it, the sibling projects, beta at v0.4.3, every doc listed under More detail, links resolve, MIT. Plus a banned-jargon list (outside code spans) that includes the retired "At a glance" / "Try it in 60 seconds" headings.
• Proof the jargon guard can fail: inserting "This robust gate" into the README turned [gate] and [robust] red (2 failed, 29 passed); reverted, 31 passed.
• Contract reversals, stated plainly: coverage figures (scripts/check_coverage_claim.py) and benchmark figures (tests/test_benchmark_claims.py) are now checked in docs/ARCHITECTURE.md instead of the README. test_readme_and_guide_agree_on_the_pinned_ref changed from "README pins == guide pins" to "README pins ⊆ guide pins, and the guide has one": the source pin now lives only in the installation guide. This source and packaged README describe v… became This README describes v…. No test was deleted; check_docs_imports now also covers docs/ARCHITECTURE.md.

Evidence

Check	Result
README example, run verbatim against edgeproc-core 0.4.3 from PyPI (fresh venv, Python 3.13)	output matches the README exactly
uv run poe gate on this branch	exit 0, 380 passed, coverage 99.31% total / 99.13% statements / 100.00% branches, docs imports OK
git merge-tree vs #60 head	clean, no ordering needed
Hosted Dagger check on 3f48aae	success (run)
Local dagger call ci on main, run for GETTING_STARTED	failed at the benchmark step on a busy laptop (routing p95 266 ms vs budget); documented as a known trap. CI runs the benchmark, poe gate does not, so "the gate mirrors CI exactly" (CLAUDE.md) is not quite true. Not changed here.

Proposed GitHub About description (not applied)

A Python library that keeps each customer's search results separate in a shared index, and gives errors stable codes.

First 15 lines BEFORE

# edgeproc-core

Keeps each customer's search results apart in a shared vector index, and gives errors stable codes, for Python apps.

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

[Docs](docs/README.md) · [Quickstart](docs/installation-guide.md)

```text
input:  "acme-invoice" and "globex-invoice", identical, stored in ONE shared index; search as acme
output: acme sees: [('acme-invoice', 0.0)]

input:  a raw failure shaped like an HTTP 402 response: {"status": 402}

First 15 lines AFTER

# edgeproc-core

A Python library that keeps each customer's search results separate in a shared index, and gives errors stable codes.

**Python 3.13 or newer: `pip install edgeproc-core`**

[![CI](https://github.com/hseshadr/edgeproc-core/actions/workflows/dagger.yml/badge.svg)](https://github.com/hseshadr/edgeproc-core/actions/workflows/dagger.yml)
[![PyPI](https://img.shields.io/pypi/v/edgeproc-core)](https://pypi.org/project/edgeproc-core/)
[![License](https://img.shields.io/github/license/hseshadr/edgeproc-core)](LICENSE)

Many apps have a "find similar" or document search feature that all their customers share.
Each item is stored as a list of numbers (an embedding) in an index built for that kind of
lookup (a vector index). One index per customer wastes memory once you have thousands of
customers. One shared index means every search, delete and count must be filtered by customer,
and a single missed filter shows, or deletes, someone else's data.

🤖 Generated with Claude Code

https://claude.ai/code/session_015oBArfm762nN1r4F4Fst5a