init: cryptographic append-only ledger

README.md

@@ -0,0 +1,50 @@
+# Civilization Ledger
+
+Not a game.
+
+`civilization-ledger` is a cryptographic, append-only, tamper-evident ledger for governance/law/memory/AI accountability.
+
+## Properties (v0)
+
+- Append-only log with a hash-chain.
+- Signed entries (Ed25519).
+- Deterministic verification: replay from genesis, verify hashes + signatures, emit an audit report.
+- Local-first: no services required.
+- No plaintext secrets committed; key material lives outside the repo.
+
+## Quick start
+
+```bash
+# from this repo root
+cd civilization-ledger
+
+cargo run -p ledger-cli -- keygen --out ~/.config/civ-ledger/keys/operator.json
+cargo run -p ledger-cli -- init --dir ./my-ledger
+
+ENTRY_HASH="$(cargo run -q -p ledger-cli -- append --dir ./my-ledger \
+  --key ~/.config/civ-ledger/keys/operator.json \
+  --namespace law \
+  --payload-format json \
+  --payload '{"type":"policy","id":"P-001","text":"No plaintext secrets in Git."}')"
+
+cargo run -p ledger-cli -- checkpoint --dir ./my-ledger
+
+cargo run -p ledger-cli -- keygen --out ~/.config/civ-ledger/keys/witness.json
+cargo run -p ledger-cli -- attest --dir ./my-ledger --witness-key ~/.config/civ-ledger/keys/witness.json
+cargo run -p ledger-cli -- verify-attestations --dir ./my-ledger --format json
+
+cargo run -p ledger-cli -- receipt --dir ./my-ledger --entry-hash "$ENTRY_HASH" --out ./receipt.json --require-attestation
+cargo run -p ledger-cli -- verify-receipt --receipt ./receipt.json --require-attestation
+
+cargo run -p ledger-cli -- verify --dir ./my-ledger --format json
+```
+
+## On-disk layout (v0)
+
+- `log/entries.cborseq` — concatenated CBOR-encoded `Entry` items (append-only).
+- `log/checkpoints.jsonl` — optional Merkle checkpoints (append-only).
+- `log/checkpoints.attestations.jsonl` — witness attestations over checkpoints (append-only).
+
+## Spec
+
+See `civilization-ledger/FORMAT.md`.