diff --git a/README.md b/README.md
index bf8f43f..8bafd06 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,41 @@
-DeltaTrace MVP
+DeltaTrace MVP: Deterministic Replayable Latency & Compliance Tracing
 
-A minimal, production-oriented scaffolding for end-to-end traceability in live-market
-execution pipelines. This repository provides a core event-graph schema, a
-deterministic replay engine, and governance scaffolding with starter adapters.
+Overview
+- DeltaTrace provides a tiny but practical MVP foundation for end-to-end traceability in live-market pipelines.
+- Focus areas: deterministic replay, cross-layer event graphs, auditability, and lightweight adapters that avoid vendor lock-in.
+- The current repository contains a minimal core, a deterministic replay engine, and a trace payload model that can be extended into a production-ready toolkit.
 
-What you get
-- Lightweight event graph primitives: LocalEvent, PlanDelta, OrderEvent, FillEvent, RiskCheck, AuditLog, PrivacyBudget
-- Deterministic replay engine to reproduce a decision path from a delta stream and event log
-- Governance ledger scaffold with crypto-signed audit entries (in-memory for MVP)
-- Two starter adapters: FIX feed simulator and exchange gateway stub
-- Packaging metadata and tests ensuring a safe MVP workflow
+What’s inside (core MVP)
+- deltatrace.core: lightweight event graph primitives (LocalEvent, PlanDelta, OrderEvent, FillEvent, RiskCheck, AuditLog, PrivacyBudget, MessageMeta) and a minimal in-memory TraceGraph.
+- deltatrace.replay: DeterministicReplayEngine that consumes a delta-stream and yields a deterministic ordering of events.
+- deltatrace.trace: a small but usable form for trace payloads (LocalEvent, PlanDelta, etc.) with JSON-serializable to_dict and from_dict helpers.
+- adapters/: starter adapters (FIX feed simulator, exchange gateway) to illustrate plug-and-play deployment.
+- governance/: scaffolding for governance logs and audit trails.
 
-Usage outline
-- Build and test: ./test.sh
-- Explore the API under deltatrace.core and adapters package
-- Extend with additional adapters and governance rules as needed
+How to run
+- Ensure you have Python 3.9+.
+- Install (local development): python3 -m build && pip install -e .
+- Run tests: ./test.sh
+- You can also import modules in an interactive session to experiment:
+  from deltatrace.core import LocalEvent, PlanDelta, ReplayEngine
+  from deltatrace.replay import DeterministicReplayEngine
 
-This README intentionally stays lightweight and actionable for quick onboarding.
+Usage patterns (MVP approach)
+- Build an event graph across layers: LocalEvent -> PlanDelta -> OrderEvent/FillEvent -> RiskCheck -> AuditLog.
+- Capture a delta-stream and an event-log, then use the deterministic replay to reproduce a specific decision path.
+- Use the governance scaffolds to crypto-sign and tamper-evident-log entries for auditability.
+
+Roadmap (high level)
+- Phase 0: Core schema, deterministic replay, 2 starters adapters (FIX feed, exchange gateway).
+- Phase 1: Privacy controls and governance ledger scaffold.
+- Phase 2: Partitioned-network testbed with sandboxed exchange.
+- Phase 3: Incident replay dashboard and governance reporting.
+
+Contributing
+- Small, well-scoped changes with tests.
+- Follow the existing style and add docstrings.
+- Run test.sh after meaningful changes.
+
+This repository is designed as a production-oriented MVP: small, well-typed, and easy to extend. For questions or collaboration, ping in the repository issues and PRs.
+
+End of README