Update README.md

README.md

@@ -10,5 +10,110 @@ pinned: false
 license: other
 short_description: Tamper-evident, hash-chained event logging for AI/agent runs
 ---
+# RFT Agent Flight Recorder — Black Box Behaviour Trace
+
+A proof-first flight recorder for AI/agent runs. This Space writes an **append-only, hash-chained event log** so you can verify **what happened, when it happened, and what triggered it**—without taking anyone’s word for it.
+
+It’s built to be boringly audit-friendly: deterministic hashing, optional Ed25519 signatures, session verification, and exportable proof bundles that third parties can check.
+
+---
+
+## What this Space does
+
+### ✅ Records a tamper-evident timeline
+Each action becomes an **event** (JSON) written to `flightlog.jsonl`:
+
+- `prompt`
+- `output`
+- `tool_call` / `tool_result`
+- `memory_read` / `memory_write`
+- `retrieval`
+- `policy_block`
+- `error`
+- `note`
+
+Every event includes:
+
+- `seq` (monotonic step number)
+- `ts_utc` (timestamp)
+- `prev_event_hash_sha256` (links to previous event)
+- `event_hash_sha256` (hash of this event)
+- optional `signature_ed25519` (Ed25519 signature)
+
+If any event is edited, removed, or reordered, verification fails.
+
+### ✅ Verifies sessions end-to-end
+The verifier recomputes hashes and confirms the chain is intact. Optionally, it can require a valid signature on every event.
+
+### ✅ Exports proof bundles
+Exports `rft_flight_bundle_<session_id>.zip` containing:
+
+- `<session_id>_events.jsonl` (the session timeline)
+- `<session_id>_verify_report.txt` (verification report)
+
+### ✅ Imports and verifies third-party bundles
+Upload a bundle and verify it locally. Optionally store PASSed events into your local `flightlog.jsonl`.
+
+---
+
+## How to use
+
+### 1) Generate keys (optional)
+Go to **Keys** → **Generate Keypair**.
+
+- **Private key** signs events (keep it private).
+- **Public key** verifies signatures (safe to share).
+
+> demo note: don’t paste production private keys here.
+
+### 2) Start a session
+Go to **Start Session** → **Start New Session**.  
+Copy the `session_id`.
+
+### 3) Record events
+Go to **Record Event** and append events as they occur.
+
+Payload accepts:
+- JSON (recommended)
+- plain text (stored under `_text`)
+
+If `parent_event_hash_sha256` is left empty, it defaults to the previous event hash (simple linear causality).
+
+### 4) View timeline
+Go to **Timeline** → **Load timeline**.
+
+### 5) Verify
+Go to **Verify Session** → **Verify**.
+
+Enable “Require signatures” only if you signed every event.
+
+### 6) Finalise + Export
+Go to **Finalise + Export**:
+- **Finalise session** creates a session anchor.
+- **Export session bundle** produces the ZIP proof bundle.
+
+### 7) Import bundle (third-party verification)
+Go to **Import Bundle**, upload `rft_flight_bundle_*.zip`, and verify.  
+If you want to retain verified sessions, tick **Store imported events**.
+
+---
+
+## Data format (high-level)
+
+### Event (simplified)
+```json
+{
+  "spec": "rft-flight-event-v0",
+  "ts_utc": "2026-01-08T12:34:56.789+00:00",
+  "session_id": "…",
+  "seq": 3,
+  "event_type": "tool_call",
+  "parent_event_hash_sha256": "…",
+  "prev_event_hash_sha256": "…",
+  "payload": { "tool": "search", "input": { "q": "…" } },
+  "meta": { "model_id": "audit-demo", "run_mode": "deterministic" },
+  "event_hash_sha256": "…",
+  "signature_ed25519": "…"  // optional
+}
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference