Update README.md

README.md

@@ -1,14 +1,78 @@
 ---
 title: TimelineDiff  Differential Reproducibility
 emoji: 🐠
-colorFrom: blue
-colorTo: indigo
+colorFrom: indigo
+colorTo: pink
 sdk: gradio
 sdk_version: 6.2.0
 app_file: app.py
 pinned: false
 license: other
 short_description: Diff agent timelines. Find first divergence. Export forensic
+thumbnail: >-
+  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/cc2glLOtiZJWxbbDoELfT.jpeg
 ---
+# TimelineDiff — Differential Reproducibility Protocol (DRP)
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Production agents fail in non-deterministic ways: sampling variance, flaky tools, drifting data, timing/race effects.
+Benchmarks tell you *whether* you failed. Logs tell you *what happened once*. TimelineDiff tells you **why two runs diverged**.
+
+## What this Space does
+- Upload **two DRP trace bundles (.zip)**
+- Computes:
+  - **First divergence point**
+  - Divergence class (sampling / tool / memory / control-flow / state)
+  - Per-event structured JSON diffs
+- Exports:
+  - `report.md`, `diff.json`, `drp-diff-report.zip`
+- Can also:
+  - Verify hash-chained integrity of a bundle
+  - Generate demo bundles to test the UI
+  - Create a patched “fork” bundle (counterfactual edit) for sandbox what-if workflows
+
+## DRP bundle format (v0)
+A bundle is a `.zip` containing:
+- `manifest.json`
+- `events.jsonl`
+
+Each event is hash-chained:
+- `prev` is the previous event hash
+- `hash` is SHA-256 of canonical event JSON
+This gives a tamper-evident timeline, and makes diffs trustworthy.
+
+## Integrations (where this plugs in)
+- Agent frameworks can export DRP events at decision points (LLM call, tool call, memory write, planner step).
+- Observability can be ingested and mapped to DRP (spans → events).
+- Verification primitives (signing / zk / attestations) can be layered later.
+
+## Quick start (local)
+```bash
+pip install -r requirements.txt
+python app.py
+Suggested event kinds
+	•	llm_sample
+	•	tool_call
+	•	tool_result
+	•	memory_write
+	•	plan_step
+	•	guardrail
+	•	state_snapshot
+---
+
+# `drp/__init__.py`
+
+```python
+__all__ = [
+    "canon",
+    "sha256_hex",
+    "now_utc_iso",
+    "load_bundle",
+    "verify_bundle",
+    "write_bundle_zip",
+    "diff_bundles",
+    "render_report_markdown",
+    "make_demo_bundle_zip",
+    "fork_patch_bundle",
+]
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference