Update README.md

README.md

@@ -12,52 +12,87 @@ short_description: Ed25519-signed receipts-hash-chained runs-replay-drift diffs
 thumbnail: >-
   https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/ZH0Us3iUhibRFp7Ct89Bk.png
 ---
+
 # AuditPlane — Institution-Grade LLM Decision Proofs
 
 Ed25519-signed receipts + hash-chained runs + replay + drift diffs + Merkle proofs
 
-Most “LLM firewall” systems are easy to argue about and impossible to verify. AuditPlane is the missing verification layer: it turns safety and policy decisions into cryptographically verifiable artifacts that anyone can replay, diff, and falsify. This is not another detector. This is a proof plane for whatever detectors you run.
+Most “LLM firewall” projects are easy to argue about and hard to verify. AuditPlane is the verification plane: it turns safety and policy decisions into cryptographically verifiable artifacts that anyone can replay, diff, and falsify. This is not “another detector”. This is a proof layer for whatever detectors you already run.
+
+## What this Space does
+
+AuditPlane turns LLM decisioning into an auditable ledger:
+
+- Generates decision receipts for every prompt in a suite (JSONL)
+- Ed25519-signs each receipt (integrity / non-repudiation)
+- Hash-chains receipts (tamper-evident continuity)
+- Binds receipts to a suite via suite_digest + stable case_id
+- Enforces baseline validation (export is blocked if invalid)
+- Replays the same suite later and produces drift diffs
+- Emits a Merkle root + inclusion proofs
+- Exports a ZIP bundle containing:
+  - suite.jsonl
+  - baseline_receipts.jsonl
+  - merkle.json
+  - proofs.jsonl
+  - verify_bundle.py (offline verifier)
+
+Anyone can take your exported bundle, run verify_bundle.py, and independently confirm signature validity, receipt hash integrity, chain continuity, suite binding, and Merkle inclusion proofs. No Hugging Face trust required.
 
-What this Space does
+## What this Space is not
 
-AuditPlane turns LLM decisioning into an auditable ledger.
+- Not a complete safety solution by itself
+- Not a benchmark leaderboard
+- Not a policy engine
 
-It generates decision receipts for every prompt in a suite, Ed25519-signs each receipt for non-repudiation, hash-chains receipts for tamper evidence, binds receipts to a suite via suite_digest and stable case_id, enforces baseline validation so export is blocked if invalid, replays the same suite later and produces drift diffs, emits a Merkle root and inclusion proofs, and exports a ZIP bundle with an offline verifier.
+The value here is the receipt contract + replay + drift diff + cryptographic proof layer. Plug your real detector stack into the layer registry.
 
-Anyone can take your bundle, run verify_bundle.py, and independently confirm signatures, hashes, chain integrity, suite binding, and Merkle proofs without trusting Hugging Face or the Space.
+## How to use
 
-What this Space is not
+### Baseline
+1) Paste a JSONL prompt suite: one {"text":"..."} per line  
+2) Click Generate baseline  
+3) Save: baseline receipts (JSONL), merkle.json, proofs.jsonl  
 
-It is not a complete safety system, not a classifier benchmark, and not a policy engine. The product here is the receipt contract, replay system, diff engine, and cryptographic proof layer. You plug your own detectors into it.
+### Replay + Diff
+1) Paste the same suite + the baseline JSONL  
+2) Click Replay + diff  
+3) Inspect action drift, reason-code drift, check drift, and pipeline/config drift  
 
-How to use
+### Export offline bundle
+Export is blocked unless baseline validation passes. The ZIP contains verify_bundle.py so third parties can verify offline.
 
-Baseline
-Paste a JSONL prompt suite with one {"text":"..."} per line. Click Generate baseline. Save the baseline receipts JSONL, merkle.json, and proofs.jsonl. This becomes your cryptographic baseline.
+## Layer contract (what your layers must emit)
 
-Replay and Diff
-Paste the same suite and the baseline receipts. Click Replay and Diff. You get action drift (ALLOW, CLARIFY, REFUSE), reason code drift, check score and fired drift, and pipeline or configuration drift.
+Each detector layer/check only needs to output:
 
-Export
-Export is blocked unless all signatures, hashes, chain links, and suite bindings are valid. The ZIP contains suite.jsonl, baseline_receipts.jsonl, merkle.json, proofs.jsonl, and verify_bundle.py so anyone can verify offline.
+- name
+- version
+- score
+- threshold
+- fired
+- optional evidence
+- latency_ms
 
-Layer contract
+You can keep detector internals private while still producing verifiable outputs.
 
-Each detection layer only needs to emit name, version, score, threshold, fired, optional evidence, and latency_ms. You can keep all internal logic private while still producing fully auditable outputs.
+## Required Hugging Face Secrets
 
-HF Secrets required
+Set these in the Space settings:
 
-RP_SIGNING_PRIVKEY_B64 is base64 of 32 raw bytes for the Ed25519 private key.  
-RP_TRUSTED_PUBKEY_B64 is base64 of 32 raw bytes for the Ed25519 public key.  
-RP_KEY_ID is optional and is just a label for the signing key.
+- RP_SIGNING_PRIVKEY_B64 — base64 of 32 raw bytes (Ed25519 private key)
+- RP_TRUSTED_PUBKEY_B64 — base64 of 32 raw bytes (Ed25519 public key)
 
-Generate keys on Windows PowerShell
+Optional:
+- RP_KEY_ID — label for the signing key id
 
+## Generate keys (copy-paste)
+
+### Windows PowerShell
 py -3 -m pip install -U cryptography  
 py -3 -c "import base64; from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey; from cryptography.hazmat.primitives import serialization; priv=Ed25519PrivateKey.generate(); priv_raw=priv.private_bytes(encoding=serialization.Encoding.Raw, format=serialization.PrivateFormat.Raw, encryption_algorithm=serialization.NoEncryption()); pub_raw=priv.public_key().public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw); print('RP_SIGNING_PRIVKEY_B64='+base64.b64encode(priv_raw).decode()); print('RP_TRUSTED_PUBKEY_B64='+base64.b64encode(pub_raw).decode())"
 
-Generate keys on Linux or macOS
-
+### Linux / macOS
 python3 -m pip install -U cryptography  
 python3 - <<'PY'  
 import base64  
@@ -68,16 +103,26 @@ priv_raw = priv.private_bytes(encoding=serialization.Encoding.Raw, format=serial
 pub_raw = priv.public_key().public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw)  
 print("RP_SIGNING_PRIVKEY_B64=" + base64.b64encode(priv_raw).decode())  
 print("RP_TRUSTED_PUBKEY_B64=" + base64.b64encode(pub_raw).decode())  
-PY
+PY  
+
+## Key hygiene (non-negotiable)
+
+- Treat RP_SIGNING_PRIVKEY_B64 as production signing material.
+- Never paste it into issues/logs/screenshots/chat.
+- If it leaks: rotate immediately (new keys → update HF secrets → restart Space → regenerate baselines).
 
-Key hygiene
+## Offline verification (what the verifier checks)
 
-RP_SIGNING_PRIVKEY_B64 is production signing material. Never paste it into logs, issues, screenshots, or chat. If it leaks, rotate immediately by generating new keys, updating HF secrets, and regenerating baselines.
+The exported bundle can be verified without Hugging Face. The offline verifier checks:
 
-Offline verification
+- Ed25519 signature validity
+- receipt hash integrity
+- hash-chain continuity (tamper evidence)
+- suite binding (suite_digest + case_id)
+- Merkle root + inclusion proofs
 
-The exported bundle can be verified without Hugging Face. The verifier checks Ed25519 signatures, receipt hash integrity, hash-chain continuity, suite binding using suite_digest and case_id, and Merkle root inclusion proofs.
+## Deployment rule
 
-Deployment rule
+No receipt → no claim.
 
-No receipt means no claim. If a system cannot produce signed, chained, Merkle-anchored receipts with replay and diff, its safety claims are not auditable.
+If a system cannot produce signed, chained, Merkle-anchored receipts with replay and diff, its safety claims are not auditable.