diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..bd5590b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,21 @@
+node_modules/
+.npmrc
+.env
+.env.*
+__tests__/
+coverage/
+.nyc_output/
+dist/
+build/
+.cache/
+*.log
+.DS_Store
+tmp/
+.tmp/
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+READY_TO_PUBLISH
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d88dcfa
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,10 @@
+# AGENTS.md
+
+Architecture and contribution guide for PolicyMesh MVP.
+
+- Tech stack: Python 3.8+, pydantic for data models, minimal in-memory registry, lightweight ADMM-like solver.
+- Testing: pytest-based unit tests; packaging validation via python -m build.
+- How to contribute: implement adapters, extend policy primitives, add concrete cross-domain models, and expand governance ledger persistence.
+- Testing commands:
+  - bash test.sh
+- Guidelines: keep changes small, maintain backward compatibility unless explicit migration is required, add tests for new features.
diff --git a/README.md b/README.md
index 0d570a7..46f6b3a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,19 @@
-# policymesh-policy-driven-federated-optim
+# PolicyMesh: Policy-Driven Federated Optimization (MVP)
 
-A novel platform that enables municipalities and communities to encode policy objectives (reliability, equity, carbon targets) as constraints and run privacy-preserving, offline-first federated optimization across cross-domain assets (electric DERs, 
\ No newline at end of file
+PolicyMesh is a scaffold for building a policy-driven, privacy-preserving, offline-first federated optimization platform across cross-domain assets (electric DERs, water pumps, heating systems). This MVP focuses on clear separation of concerns, a minimal Graph-of-Contracts (GoC) abstraction, a lightweight ADMM-like solver, and a governance ledger for auditable settlements.
+
+What’s included in this MVP
+- Core data models: LocalPolicySet, GlobalConstraints, DataExposurePolicy
+- Lightweight PolicyMesh engine with local problem management and a tiny ADMM-lite step
+- In-memory registry for adapters/contracts (extensible to persistent storage)
+- Minimal solver utilities (policy aggregation and delta-sync scaffolding)
+- Basic tests verifying a two-domain flow and ledger growth
+- Packaging metadata and a test script that runs pytest and builds the package
+
+How to run
+- Install dependencies and run tests:
+  - python3 -m pip install -r requirements.txt  (if you add dependencies)
+  - bash test.sh
+
+Notes
+- This is an MVP scaffolding intended for extension. It focuses on architectural clarity and testability over full production features.
diff --git a/policy_mesh/__init__.py b/policy_mesh/__init__.py
new file mode 100644
index 0000000..05da4cd
--- /dev/null
+++ b/policy_mesh/__init__.py
@@ -0,0 +1,8 @@
+from .core import LocalPolicySet, GlobalConstraints, DataExposurePolicy, PolicyMesh
+
+__all__ = [
+    "LocalPolicySet",
+    "GlobalConstraints",
+    "DataExposurePolicy",
+    "PolicyMesh",
+]
diff --git a/policy_mesh/core.py b/policy_mesh/core.py
new file mode 100644
index 0000000..2ced030
--- /dev/null
+++ b/policy_mesh/core.py
@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class LocalPolicySet:
+    domain: str
+    policies: Dict[str, Any]  # domain-specific policy primitives
+    version: str
+
+    def dict(self) -> Dict[str, Any]:
+        return {
+            "domain": self.domain,
+            "policies": self.policies,
+            "version": self.version,
+        }
+
+
+@dataclass
+class GlobalConstraints:
+    constraints: Dict[str, Any]  # mesh-level constraints (limits, envelopes, etc.)
+    version: str
+
+    def dict(self) -> Dict[str, Any]:
+        return {
+            "constraints": self.constraints,
+            "version": self.version,
+        }
+
+
+@dataclass
+class DataExposurePolicy:
+    allowed_data: List[str]
+    privacy_budget: float  # simple DP budget proxy
+    version: str
+
+    def dict(self) -> Dict[str, Any]:
+        return {
+            "allowed_data": self.allowed_data,
+            "privacy_budget": self.privacy_budget,
+            "version": self.version,
+        }
+
+
+class PolicyMesh:
+    def __init__(self) -> None:
+        self.local_problems: Dict[str, LocalPolicySet] = {}
+        self.global_constraints: Optional[GlobalConstraints] = None
+        # internal solver state (very lightweight ADMM-lite mock)
+        self._z: Dict[str, Any] = {}
+        self._u: Dict[str, Any] = {}
+
+        # governance ledger (in-process; can be swapped to persistent store)
+        self._ledger: List[Dict[str, Any]] = []
+
+    # Local problem management
+    def add_local_policy(self, policy: LocalPolicySet) -> None:
+        self.local_problems[policy.domain] = policy
+
+    def set_global_constraints(self, constraints: GlobalConstraints) -> None:
+        self.global_constraints = constraints
+
+    # Lightweight ADMM-like update (mock for MVP)
+    def admm_step(self, rho: float = 1.0) -> None:
+        # initialize if first run
+        if not self.local_problems:
+            return
+        # simple placeholder: push domain policy sums into z and reset u
+        for domain, policy in self.local_problems.items():
+            # naive objective: sum of numeric policy values where possible
+            total = 0.0
+            for k, v in policy.policies.items():
+                try:
+                    total += float(v)
+                except Exception:
+                    continue
+            self._z[domain] = total
+            self._u[domain] = self._u.get(domain, 0.0)  # keep a scalar dual-like variable
+
+        # Commit a governance-like delta to the ledger for traceability
+        self._ledger.append({
+            "type": "admm_step",
+            "count": len(self._ledger) + 1,
+            "z": self._z.copy(),
+            "u": self._u.copy(),
+        })
+
+    # Delta-sync: merge updates from a remote partner (mock)
+    def delta_sync(self, remote: Dict[str, Any]) -> None:
+        # naive: merge remote z into local, respecting versioning if provided
+        for k, v in remote.get("z", {}).items():
+            self._z[k] = v
+        for k, v in remote.get("u", {}).items():
+            self._u[k] = v
+        self._ledger.append({
+            "type": "delta_sync",
+            "remote": True,
+            "z": self._z.copy(),
+            "u": self._u.copy(),
+        })
+
+    # Query helpers
+    def get_state(self) -> Dict[str, Any]:
+        return {
+            "local_problems": {d: p.dict() for d, p in self.local_problems.items()},
+            "global_constraints": self.global_constraints.dict() if self.global_constraints else None,
+            "z": self._z,
+            "u": self._u,
+        }
+
+    def get_ledger(self) -> List[Dict[str, Any]]:
+        return self._ledger
diff --git a/policy_mesh/registry.py b/policy_mesh/registry.py
new file mode 100644
index 0000000..156b96d
--- /dev/null
+++ b/policy_mesh/registry.py
@@ -0,0 +1,24 @@
+"""In-memory registry for adapters and contracts (MVP).
+
+- This is a lightweight stand-in for a proper contract registry with versioning.
+"""
+from __future__ import annotations
+
+from typing import Dict, Any
+
+
+class Registry:
+    def __init__(self) -> None:
+        self.adapters: Dict[str, Dict[str, Any]] = {}
+
+    def register_adapter(self, name: str, version: str, meta: Dict[str, Any]) -> None:
+        self.adapters[name] = {"version": version, "meta": meta}
+
+    def get_adapter(self, name: str) -> Dict[str, Any] | None:
+        return self.adapters.get(name)
+
+    def list_adapters(self) -> Dict[str, Dict[str, Any]]:
+        return self.adapters
+
+
+registry = Registry()
diff --git a/policy_mesh/solver.py b/policy_mesh/solver.py
new file mode 100644
index 0000000..a57c4b7
--- /dev/null
+++ b/policy_mesh/solver.py
@@ -0,0 +1,26 @@
+"""ADMM-lite solver utilities for PolicyMesh (minimal MVP).
+
+- This module provides small helpers to perform a toy ADMM-like step and
+- to compute a simple synchronization delta for cross-domain coordination.
+"""
+
+from typing import Any, Dict
+
+
+def admm_lite_step(z: Dict[str, float], u: Dict[str, float], rho: float = 1.0) -> Dict[str, Dict[str, float]]:
+    # Very small, deterministic update for demonstration purposes
+    new_z: Dict[str, float] = {}
+    new_u: Dict[str, float] = {}
+    for k, val in z.items():
+        # pretend we adjust z toward a neutral value 0.0 using rho
+        new_z[k] = val - rho * u.get(k, 0.0)
+        new_u[k] = u.get(k, 0.0)  # keep dual variable in sync (no-op placeholder)
+    return {"z": new_z, "u": new_u}
+
+
+def delta_sync(local_z: Dict[str, float], remote_z: Dict[str, float]) -> Dict[str, float]:
+    # simple max-merge for demonstration
+    merged: Dict[str, float] = dict(local_z)
+    for k, v in remote_z.items():
+        merged[k] = max(merged.get(k, float('-inf')), v)
+    return merged
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..093d181
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "policy_mesh"
+description = "Policy-driven federated optimization scaffold for cross-domain microgrids"
+authors = [ { name = "OpenCode" } ]
+requires-python = ">=3.8"
+license = {text = "MIT"}
+readme = "README.md"
+dynamic = ["version"]
+
+[tool.setuptools.packages.find]
+where = ["." ]
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..27e666b
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
+pydantic>=1.10
+pytest>=7.0
+build>=0.7
diff --git a/test.sh b/test.sh
new file mode 100644
index 0000000..325238d
--- /dev/null
+++ b/test.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run tests and packaging check
+echo "Setting PYTHONPATH for test environment..."
+# Ensure repository root is on PYTHONPATH so policy_mesh imports resolve
+export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}/workspace/repo"
+echo "Running tests..."
+pytest -q
+echo "Building package (Python) to verify packaging metadata..."
+python3 -m build
diff --git a/tests/test_basic.py b/tests/test_basic.py
new file mode 100644
index 0000000..3c50a6e
--- /dev/null
+++ b/tests/test_basic.py
@@ -0,0 +1,32 @@
+import json
+
+from policy_mesh.core import LocalPolicySet, GlobalConstraints, PolicyMesh
+
+
+def test_basic_policymesh_flow():
+    pm = PolicyMesh()
+
+    # Create two local domains
+    lp1 = LocalPolicySet(domain="district-a", policies={"energy_budget": 100.0, "ramp_rate": 1.0}, version="v0")
+    lp2 = LocalPolicySet(domain="district-b", policies={"energy_budget": 80.0, "ramp_rate": 0.8}, version="v0")
+
+    pm.add_local_policy(lp1)
+    pm.add_local_policy(lp2)
+
+    # Global constraint placeholder
+    gc = GlobalConstraints(constraints={"mesh_budget": 180.0}, version="v0")
+    pm.set_global_constraints(gc)
+
+    # Run a couple of ADMM steps (mocked)
+    pm.admm_step(rho=1.0)
+    pm.admm_step(rho=1.0)
+
+    state = pm.get_state()
+    # basic assertions about stored state
+    assert "local_problems" in state
+    assert "district-a" in state["local_problems"]
+    assert state["global_constraints"]["version"] == "v0" if state["global_constraints"] else True
+
+    # ensure ledger has entries from admm steps
+    ledger = pm.get_ledger()
+    assert len(ledger) >= 2