Rewrite the README and add a user guide

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Issues and pull requests are welcome. For security problems, follow
+[SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+## Ground rules
+
+- Keep the storage contract backend-neutral. Filesystem behavior must not leak
+  into encrypted repository semantics.
+- Do not invent cryptographic primitives. Use established AEAD, signature,
+  hashing, and key-wrapping libraries.
+- Treat storage as malicious for confidentiality and integrity, and document
+  availability, rollback, freeze, and equivocation limits precisely.
+- Never commit key files or decrypted test data. Test secrets must live only in
+  temporary directories.
+- Protocol changes must update [docs/spec.md](docs/spec.md) and, where relevant,
+  [docs/design.md](docs/design.md) in the same change.
+
+## Build and test
+
+```console
+cargo test --all-targets
+cargo clippy --all-targets -- -D warnings
+cargo fmt --all -- --check
+```
+
+CI runs the same three commands. The ignored power-cut harness is not part of
+the default run; its protocol, Windows commands, and durability limits are in
+[docs/durability.md](docs/durability.md).
+
+The test suite covers:
+
+- incremental push and reconstruction into a fresh repository;
+- native clone, fetch, pull, push, dry-run, refspec, and force-push behavior;
+- rollback, same-generation fork, and ciphertext-tampering rejection;
+- streaming-AEAD chunk boundaries, wrong keys or AAD, reordering, duplication,
+  truncation, trailing bytes, forged sizes, and legacy-format rejection;
+- independent device add, read, and write, non-admin rejection,
+  genesis-substitution rejection, administrative rollback pinning, device
+  revocation without pack rewrites, and multi-generation offline catch-up;
+- malformed predecessor-link, generation-key commitment, recipient-set, and
+  signed-but-incomplete Git object-graph rejection;
+- two independent carrier writers racing real `git push` processes, with
+  exactly one winner;
+- plaintext-absence checks across carrier history;
+- applicable black-box scenarios independently reimplemented from Git
+  upstream's
+  [`t/t5801-remote-helpers.sh`](https://github.com/git/git/blob/master/t/t5801-remote-helpers.sh).
+
+A local bare Git repository is enough for deterministic carrier concurrency
+tests: local-path pushes still run Git's real `receive-pack`, ref locking, and
+fast-forward checks. Hosted smoke tests remain useful for authentication,
+request limits, and provider-specific policy.
+
+## Benchmarks
+
+The opt-in harness in `scripts/` measures encryption, reconstruction,
+verification, and incremental updates. See [docs/benchmarks.md](docs/benchmarks.md).
+Benchmark outputs, repository keys, and reconstructed data must not be
+committed.

SECURITY.md

@@ -0,0 +1,20 @@
+# Security
+
+Please report vulnerabilities privately to
+**git-remote-e2ee@combinatrix.ai** rather than opening a public issue.
+
+`git-remote-e2ee` is an early prototype and has not been independently
+audited. Its intended guarantees and known limits are listed in the
+[README](README.md#security-model) and specified in [docs/design.md](docs/design.md) and
+[docs/spec.md](docs/spec.md). Reports are especially welcome about:
+
+- plaintext, refs, paths, or other inner metadata reaching storage;
+- accepting tampered, rolled-back, or forked state that a returning clone
+  should reject;
+- a revoked device obtaining keys for later generations;
+- authorization bypass between reader, writer, and administrator roles;
+- key material leaking into logs, Git configuration, or the remote.
+
+Limits already documented, such as rollback shown to a fresh clone or metadata
+visible to storage, are not vulnerabilities by themselves. Proposals to close
+them are still welcome as issues.

docs/art/LICENSE-griddy-icons

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Griddy Icons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/art/LICENSE-tabler-icons

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Paweł Kuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.