[hmirin]

Summary

Two things, stacked in one PR:

1. README rewrite

• Newcomers: starts from why end-to-end encryption matters (a private repository is private from other people, not from the host), what E2EE changes, good fits, and what you give up.
• Why this tool: fast and safe compared with git-remote-gcrypt (pushes upload only new data, even to GitHub, though downloads from a Git carrier are not yet incremental; no silent force pushes thanks to compare-and-swap), and no master key compared with file-level tools like git-crypt (a fresh key per push, wrapped to each device; devices can be revoked individually).
• Experts: compares git-crypt (file-level), git-remote-gcrypt, and git-remote-e2ee in two tables — what the storage host can learn, and what each tool can do — with footnotes citing each tool's own documentation, candid about git-remote-e2ee's weaknesses.
• Adds an overview illustration (docs/art/overview.svg), moves usage details to docs/guide.md and test notes to CONTRIBUTING.md, and adds SECURITY.md.

2. Format v5: anonymous recipients

Storage previously saw every device's per-repository public keys, roles, and membership changes. v5 reduces that to a padded reader count (see docs/design.md, "Anonymous recipients"):

• Envelopes carry no recipient ID and are padded to the next power of two (minimum 4, cap 4096). Padding envelopes are genuine HPKE seals to throwaway X25519 recipients, so they are indistinguishable from real ones.
• Devices find their envelope by trial decryption of the head manifest only; older keys come from the backward key chain.
• Policy, signer identity, transition type, and the Ed25519 signature move into a sealed header encrypted under a K_t-derived subkey. Policies travel inside the transition manifest's encrypted body; policies/ objects are gone.
• An envelope audit (recipient device ID + per-envelope encapsulation seed, sealed) lets every reader re-seal and byte-compare all envelopes and require exactly one per active reader, so a malicious writer cannot corrupt one reader's envelope unnoticed.
• docs/spec.md, docs/design.md, docs/guide.md, and the README tables are updated. v5 is intentionally incompatible with v4 (prototype; no migration).

Also included

• Merges main (Flush Windows directory entries before acknowledging persistence #1 moved design/spec/benchmarks into docs/), with one fixture fix (verified_refs) needed after combining it with previously unpushed local commits (benchmarks, incremental connectivity checks, storage validation refactor).

Checks

cargo fmt --all -- --check, cargo clippy --all-targets -- -D warnings, and cargo test --all-targets pass locally: 70 passed, 1 ignored (the external power-cut harness).

Notes

• SECURITY.md asks for private reports to git-remote-e2ee@combinatrix.ai.

[hmirin]

Split into stacked PRs #3–#10 (same final tree).