diff --git a/README.md b/README.md
index 636361a..8bfa591 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,37 @@
-# MercuryMesh Federated Reproducible Market Sandbox (MVP)
+MercuryMesh Federated Reproducible Market Sandbox (MVP)
 
 Overview
-- A minimal, portable Python-based MVP for a federated, contract-driven market microstructure sandbox.
-- Primitives: MarketStateSnapshot, SharedSignals, PlanDelta, AuditLog.
-- Coordination: FederatedCoordinator provides a tiny, safe aggregation layer to mimic cross-venue signal exchange.
-- Deterministic replay and auditability are scaffolded around the core data contracts.
+- A portable, open-source stack to design, simulate, and reproduce cross-venue market microstructure experiments for multiple assets.
+- Canonical primitives: LocalBook (per-asset local state), SharedSignals (aggregated metrics), PlanDelta (deltas/allocations), AuditLog (provenance).
+- Federated coordination: lightweight, ADMM-like signals exchange with bounded staleness, preserving data privacy.
+- Deterministic replay: offline backtesting and education through seedable, reproducible runs.
+- Edge-friendly runtimes and scenario builder: WebAssembly-ready cores, portable Python/C++ binaries, and an orchestration UI for scenario design and backtests.
 
-What you get in this MVP
-- A reproducible Python package: mercurymesh_federated_reproducible_marke
-- Lightweight, testable contracts and a toy federated coordinator
-- Basic tests ensuring serialization, coordination, and data contracts work as intended
-- A test script (test.sh) to run tests and packaging checks
+Status
+- MVP focus: Python-based core primitives and a minimal federated coordinator suitable for unit tests.
+- Testing: powered by pytest; packaging via setuptools. See test.sh for the verification workflow.
 
-Usage
-- Install: python3 -m build (outside-of-repo tooling) and pip install dist/*
-- Run tests: bash test.sh
+Getting started
+- Core API: mercurymesh_federated_reproducible_marke.core
+- Replay: mercurymesh_federated_reproducible_marke.replay
+- Public exports: mercurymesh_federated_reproducible_marke.__init__ (MarketStateSnapshot, SharedSignals, PlanDelta, AuditLog, FederatedCoordinator)
 
-Notes
-- This is a starter MVP meant for extension. It intentionally focuses on clarity and correct packaging wiring, not production-grade performance or security.
+Usage example (high level)
+- Create a MarketStateSnapshot for initial state.
+- Produce PlanDelta updates from participating agents.
+- Use DeterministicReplayer.replay to deterministically apply deltas and obtain a final state.
+
+Future plans (phases)
+- Phase 0: protocol skeleton with two starter adapters and a basic ADMM-lite solver.
+- Phase 1: governance ledger, secure identities, and secure aggregation of signals.
+- Phase 2: cross-domain demo with simulated multi-venue scenarios and bindings.
+- Phase 3: hardware-in-the-loop validation with metrics and dashboards.
+
+Contributing
+- This project follows a lightweight MVP approach focused on quality and reproducibility.
+- See AGENTS.md for architectural notes and contribution guidelines.
+
+Licensing
+- MIT License. See LICENSE file in the repository root.
+
+For more details, see the code and tests under mercurymesh_federated_reproducible_marke.
diff --git a/mercurymesh_federated_reproducible_marke/replay.py b/mercurymesh_federated_reproducible_marke/replay.py
new file mode 100644
index 0000000..3b15d02
--- /dev/null
+++ b/mercurymesh_federated_reproducible_marke/replay.py
@@ -0,0 +1,61 @@
+"""Deterministic replay engine for MercuryMesh MVP.
+
+This module provides a tiny, deterministic replay utility that applies a
+sequence of PlanDelta updates to a starting MarketStateSnapshot to reproduce
+past runs. The implementation is intentionally minimal and safe for educational
+and testing purposes.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List
+from datetime import datetime
+
+from .core import MarketStateSnapshot, PlanDelta
+
+
+def _now_iso() -> str:
+    return datetime.utcnow().isoformat() + "Z"
+
+
+@dataclass
+class DeterministicReplayer:
+    """A tiny replay engine that applies PlanDelta deltas to a MarketStateSnapshot.
+
+    The replay model is intentionally simple: for each delta, asset-level values
+    in bids are increased by delta amount, while corresponding values in offers
+    are decreased by the same amount. This provides a predictable, reversible
+    transformation suitable for offline backtesting and educational labs.
+    """
+
+    @staticmethod
+    def apply_delta(state: MarketStateSnapshot, delta: PlanDelta) -> MarketStateSnapshot:
+        # Copy mutable maps to avoid in-place mutation of inputs
+        bids = dict(state.bids)
+        offers = dict(state.offers)
+
+        for asset, change in delta.delta.items():
+            bids[asset] = bids.get(asset, 0.0) + float(change)
+            offers[asset] = offers.get(asset, 0.0) - float(change)
+
+        # Build a new MarketStateSnapshot with updated bids/offers and a new timestamp
+        return MarketStateSnapshot(
+            assets=list(state.assets),
+            bids=bids,
+            offers=offers,
+            last_trade_times=dict(state.last_trade_times),
+            liquidity_metrics=dict(state.liquidity_metrics),
+            timestamp=_now_iso(),
+            version=int(state.version) + 1,
+        )
+
+    @staticmethod
+    def replay(start: MarketStateSnapshot, deltas: Iterable[PlanDelta]) -> MarketStateSnapshot:
+        """Replays a sequence of PlanDelta updates starting from a given state.
+
+        Returns the final MarketStateSnapshot after applying all deltas in order.
+        """
+        current = start
+        for d in deltas:
+            current = DeterministicReplayer.apply_delta(current, d)
+        return current