diff --git a/README.md b/README.md
index 7fc82b9..9e7aa4a 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,38 @@
 # CosmosMesh Privacy-Preserving Federated Mission Planning (MVP)
 
-This repository contains a minimal MVP oriented toward a CatOpt-inspired interoperability bridge for CosmosMesh primitives. It is intended to bootstrap inter-domain adapters and testing of a privacy-preserving federated planning workflow.
+CosmosMesh is a privacy-preserving, offline-first federation platform designed for distributed planning across heterogeneous space assets (rovers, drones, habitat modules, satellites). This MVP implements a canonical bridge (EnergiBridge / CatOpt-Bridge style) and an initial DSL to bootstrap interoperability, adapters, and end-to-end testing.
 
-What you get in this MVP:
-- A canonical bridge module that maps CosmosMesh primitives to a vendor-agnostic intermediate representation (Objects, Morphisms, PlanDelta, etc.).
-- A tiny DSL sketch outlining LocalProblem, SharedVariables, PlanDelta, DualVariables, PrivacyBudget, and AuditLog.
-- Basic data-models and a conformance scaffold to help bootstrap adapters and a small registry for contracts.
-- Tests that exercise a roundtrip between the IR and local structures.
+Key goals of the MVP
+- Map CosmosMesh primitives to a vendor-agnostic intermediate representation (IR): Objects = LocalProblems, Morphisms = SharedVariables/DualVariables, PlanDelta, PrivacyBudget, AuditLog, etc.
+- Provide a simple DSL scaffold for LocalProblem, SharedVariables, PlanDelta, DualVariables, PrivacyBudget, AuditLog, and a PolicyBlock for safety/exposure rules.
+- Supply tiny adapters and a conformance harness to kickstart multi-domain interoperability.
+- Include a lightweight ADMM-like local solver for federated optimization and a delta-sync workflow for islanding scenarios.
 
-Usage hints:
-- See tests/test_catopt_bridge.py for a usage example and expected round-trip behavior.
-- Extend the DSL sketch and bridge as you add more primitives and adapter specifics.
+What you get in this MVP
+- A canonical bridge module that maps CosmosMesh primitives to a vendor-agnostic intermediate representation (IR).
+- A minimal DSL sketch for core primitives and signals.
+- Core data models and a conformance scaffold to bootstrap adapters and a small contract registry.
+- Tests that exercise a roundtrip between the IR and local representations.
 
-Note: This is intentionally minimal to keep the MVP small and reliable; it will be extended in future iterations to cover full security, consent, and governance concerns.
+How to use this repo
+- Install and run tests: see test.sh for a complete verification workflow.
+- Run tests: bash test.sh
+- See tests/test_catopt_bridge.py for a representative usage of the CatOpt-Bridge and the roundtrip semantics.
 
-"""
+Project structure
+- src/cosmosmesh_privacy_preserving_federated: core models and logic (LocalProblem, SharedVariables, PlanDelta, etc.)
+- src/cosmosmesh_privacy_preserving_federated/adapters: starter adapters (rover_planner, habitat_module, etc.)
+- tests: unit tests for the bridge, contracts, and basic flow
+- README.md: this documentation
+
+Development and contribution
+- This MVP is designed to be extended in small, well-scoped steps. See AGENTS.md for repository-wide conventions and testing commands.
+- To extend interoperability, add adapters implementing the canonical IR and use the conformance harness to validate compatibility before onboarding.
+
+Roadmap (high level)
+- Phase 0: protocol skeleton and 2 starter adapters with TLS transport; a lightweight ADMM-lite local solver; end-to-end delta-sync with islanding.
+- Phase 1: governance ledger scaffolding; identity layer; secure aggregation defaults.
+- Phase 2: cross-domain demo with a toy contract example and NovaPlan SDK bindings.
+- Phase 3: hardware-in-the-loop validation and KPI dashboards.
+
+This repository aims to be a practical foundation for cross-domain interoperability in privacy-preserving federated planning, with a clear path toward broader ecosystem reuse.
diff --git a/pyproject.toml b/pyproject.toml
index 11a3bbc..be88e7b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -3,7 +3,7 @@ requires = ["setuptools>=61", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "cosmosmesh-privacy-preserving-federated"
+name = "cosmosmesh_privacy_preserving_federated"
 version = "0.0.1"
 description = "Minimal MVP scaffold for CosmosMesh privacy-preserving federated mission planning."
 readme = "README.md"