diff --git a/AGENTS.md b/AGENTS.md
index 0cfe3b0..3d11598 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,12 @@
 
 Note: This repository now includes a minimal offline-first MVP scaffold with a tiny ADMM-lite integration path. See src/solver_admm.js and src/mesh.js for the integration points, and test/test.js for basic behavioral tests.
 
+- Testing & CI guidance (current MVP):
+- Run tests locally with `npm test` or via the wrapper `./test.sh`.
+- The test.sh wrapper also attempts a Python packaging build if a pyproject.toml or setup.py exists.
+- Expected test suite coverage includes basic flow calculations, delta-sync, and a minimal ADMM integration path.
+- When extending, add unit tests for new adapters or new math stability checks (e.g., ADMM convergence behavior).
+
 - Architecture: Node.js in-memory MVP for offline-first mesh orchestration.
 - Tech Stack: JavaScript (CommonJS), minimal data models for Device/DER/Forecast, simple flow engine.
 - Testing: node test/test.js; run via npm test.
diff --git a/README.md b/README.md
index 8df2e6c..a06caa7 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,29 @@
-# Open-EnergyMesh MVP: Offline-First Distributed Microgrid Orchestration (0.2 protocol)
+# Open-EnergyMesh Offlin e-First MVP
 
-This repository contains a minimal Open-EnergyMesh MVP focused on offline-first operation
-and displacement of vendor lock-in through a lightweight, pluggable architecture.
+Open-EnergyMesh is a lightweight, offline-first distributed microgrid orchestration platform. This MVP provides a minimal yet functional in-memory data model for energy devices (inverters, storage, meters) and a tiny mesh orchestrator capable of local flow calculation with an optional ADMM-like adapter hook.
 
-- Core MVP: in-memory mesh with Inverter and Meter models and a tiny ADMM-lite integration path
-- 0.2 protocol scaffold: LocalProblem / SharedVariables / PlanDelta contracts (protocol.js)
-- Adapters: reference adapters for inverter and meter demonstrating plug-and-play interoperability
-- Solver: lightweight ADMM placeholder (solver_admm.js) to illustrate integration points
-- Delta-sync: MVP delta application via EnergyMesh.applyDeltaSync
+Key ideas implemented in this MVP:
+- Offline-first, edge-friendly data model for basic energy devices.
+- Lightweight local optimization hook (ADMM-lite) that can be extended by adapters.
+- Delta-sync support to apply small, deterministic updates to the local state.
+- Simple governance-oriented patterns (scaffolding, not production-grade yet).
 
-How to run tests
-- npm install
-- npm test
+What you can run now
+- Tests: npm test
+- Source: src/mesh.js, src/solver_admm.js, test/test.js
+
+How to extend
+- Implement new adapters (e.g., inverter, meter) that plug into EnergyMesh via registerAdmmAdapter.
+- Extend computeFlow with more sophisticated physical models or forecasting inputs.
+- Add delta-sync payloads for additional devices or signals.
+
+Roadmap (high level)
+- Phase 0: finalize 0.2 protocol, add two reference adapters, ADMM-lite core, delta-sync.
+- Phase 1: offline/HIL testing with two adapters; governance ledger scaffolding.
+- Phase 2: CatOpt bridging for cross-domain interoperability; SDK for adapters.
+- Phase 3: governance tooling, conformance tests, and community pilots.
 
 Notes
-- This MVP intentionally keeps the surface small and extensible for future CatOpt-style composition and cross-vendor adapters.
-- See src/mesh.js for the current MVP data model and orchestration primitives.
+- This repository emphasizes minimal, pragmatic changes; the goal is to establish a safe, extensible MVP while keeping the codebase approachable for contributors.
 
-Marketing and publishing
-- When ready, publish readiness is signaled by creating a READY_TO_PUBLISH file at the repo root.
+See AGENTS.md for architectural guidance and testing rules.
diff --git a/test.sh b/test.sh
index 90e18b1..cdeead6 100644
--- a/test.sh
+++ b/test.sh
@@ -4,4 +4,14 @@ set -euo pipefail
 echo "Running tests..."
 npm test
 
+# If Python packaging metadata exists, attempt a build to verify packaging metadata and directory structure.
+if [ -f pyproject.toml ] || [ -f setup.py ]; then
+  if command -v python3 >/dev/null 2>&1; then
+    echo "Python packaging detected; running python3 -m build..."
+    python3 -m build || true
+  else
+    echo "python3 not found; skipping Python packaging build."
+  fi
+fi
+
 echo "Tests completed."