diff --git a/README.md b/README.md
index 1498a90..164ebb6 100644
--- a/README.md
+++ b/README.md
@@ -3,31 +3,48 @@
 Graph-Calculus-Driven Compositional Optimization Studio for Edge Meshes
 
 Overview
-- CatOpt-Graph provides a minimal, pragmatic MVP for compositional optimization across edge meshes. It introduces a light-weight ontology (Objects, Morphisms, Functors) and a tiny ADMM-lite solver that demonstrates delta-sync/for reconnections while converging on a simple global constraint.
+- CatOpt-Graph provides a minimal, pragmatic MVP for compositional optimization across edge meshes. It introduces a lightweight ontology (Objects, Morphisms, Functors) and a tiny ADMM-lite solver that demonstrates delta-sync and reconnection semantics while converging on a simple global constraint.
 
 What you get in this MVP
-- Core ontology scaffolding: Object, Morphism, Functor, and a tiny versioned contract registry.
+- Core ontology scaffolding: Object, Morphism, Functor, and a tiny versioned ContractRegistry.
 - ADMM-lite solver: asynchronous, two-agent solver with bounded staleness and deterministic reconciliation on reconnects.
 - Adapters: rover and habitat stubs that map to a canonical representation.
-- Lightweight governance/contract conformance scaffolding.
-- Basic transport surface (mocked for MVP) and tests.
+- Governance scaffolding: lightweight conformance checks and audit-friendly data flow.
+- Transport surface: a minimal TLS/REST-like mock transport for MVP testing.
+- Tests: unit tests for the ADMM-lite core and contract registry.
 
 How to run
 - This project is Python-based. See test.sh for the test runner which also builds the package to validate packaging metadata.
 - After cloning, run: bash test.sh
 
-Long-term vision (brief)
-- Protocol skeleton bridging to Open-EnergyMesh/runtime, a Graph-of-Contracts registry, API bindings for adapters, and a simulated HIL environment with Gazebo/ROS.
+Roadmap (MVP, 8–12 weeks)
+- Phase 0: Core ontology, 2 adapters (rover, habitat), ADMM-lite core, delta-sync scaffold.
+- Phase 1: Global constraints layer (Limits/Colimits) and governance ledger.
+- Phase 2: Bridge to cross-domain runtimes (Open-EnergyMesh/GridVerse-like ecosystems) and a canonical transport.
+- Phase 3: HIL validation with Gazebo/ROS and minimal cross-domain demos.
 
-This README is a marketing and onboarding document for the MVP. The code is intentionally minimal but designed to be incrementally extended towards a working cross-domain orchestration platform.
+Architecture snapshot
+- Core: Objects, Morphisms, Functors, Limits/Colimits skeleton, and a versioned ContractRegistry.
+- ADMM-lite: two-agent solver with delta-sync and deterministic reconciliation on reconnects.
+- Adapters: rover and habitat stubs exposing a minimal interface readState, exposeLocalProblemData, applyCommand.
+- Bridge: mapping between domain LocalProblem data and a canonical CatOpt representation.
+- Governance: auditing and contract conformance scaffolds.
+- Transport: mock TLS/REST-like surface for MVP integration.
+- Tests: unit tests for core components and end-to-end tests for the ADMM-lite flow.
 
-Package metadata
-- The Python package name is catopt-graph-graph_calculus_driven_compo per the repository requirements.
-- See pyproject.toml for build configuration and packaging details.
+Extending the MVP
+- Add new adapters and register them in the ContractRegistry.
+- Enhance the bridge with richer to_canonical/from_canonical mappings for domain data.
+- Introduce additional data contracts (SharedVariables, DualVariables, PlanDelta, PrivacyBudget, AuditLog).
+- Add a lightweight HIL simulation layer (Gazebo/ROS) for offline testing.
 
-License
+Packaging and metadata
+- The Python package name is catopt_graph_graph_calculus_driven_compo, as defined in pyproject.toml.
+- See pyproject.toml for build configuration and packaging details; readme is declared in the project metadata.
+
+License and contribution
 - This MVP is provided as-is for exploration and testing purposes.
-
-Contributing
 - See AGENTS.md for architectural guidance and test commands.
-. 
+
+Notes
+- This README is a living document. It explains the MVP and how to extend it toward a cross-domain orchestration platform.