diff --git a/README.md b/README.md
index e894ca3..7f5e9d2 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,37 @@
-Open-EnergyMesh (Offline-First MVP)
+Open-EnergyMesh: Offline-First Distributed Microgrid Orchestration (MVP)
 
 Overview
 - A minimal, open MVP for offline-first distributed microgrid orchestration.
 - Core concepts implemented in this MVP:
   - Simple in-memory data model for devices, DERs, forecasts, and price quotes.
-- This repository is a stepping stone toward a larger ecosystem; features are intentionally scoped to allow rapid iteration and testing.
+- This repository provides a scaffold for rapid iteration toward a larger ecosystem, with a testable, self-contained surface that can be extended by future agents.
 
-Project layout
-- package.json: npm metadata and test script.
-- src/mesh.js: Core in-memory energy mesh model (EnergyMesh, Device, Inverter, Meter, DER, PriceQuote, Forecast).
-- test/test.js: Basic unit test verifying energy-flow calculation.
-- AGENTS.md: Architecture and testing guidance for future agents.
-- README.md: This file.
-- test.sh: Executable to run tests in CI/local environment.
-- READY_TO_PUBLISH: marker file to signal completion (created when ready).
+How it maps to the Open-EnergyMesh vision
+- Data model and APIs: A lightweight in-code model (Device, Inverter, Meter, DER, Forecast, PriceQuote) with a simple EnergyMesh orchestrator. The current tests exercise a basic energy-flow calculation.
+- Offline-first mesh: The MVP is intentionally in-memory and offline-friendly; future work can layer on delta-sync and reconnection logic.
+- Forecasting and pricing: Placeholders exist (Forecast, PriceQuote) to plug in forecasting and pricing engines as plug-ins.
+- Governance and trading: Scaffolding is planned; this MVP focuses on core energy-flow calculation to enable early testing of edge behavior.
+- Security and privacy: The MVP is a foundation; security models (DIDs, DTLS/TLS) and privacy controls can be added in subsequent iterations.
 
-How to run locally
+Getting started
 - Install dependencies: npm install
-- Run tests: npm test
-- Or run the provided test script: ./test.sh
+- Run tests: npm test (or ./test.sh)
+- Source: src/mesh.js defines the in-memory data model and EnergyMesh orchestration.
+- Tests: test/test.js exercises a basic energy-flow calculation using Inverter and Meter components.
 
 Extending the MVP
-- Add more detailed data models (Event, Trade, etc.).
-- Implement a lightweight mesh protocol layer and offline-sync logic.
-- Introduce a forecasting and pricing plug-in interface.
-- Add governance/peer-to-peer trading scaffolding in a separate module.
+- Add more detailed data models (Event, Trade, Forecast, PriceQuote) and richer flow logic.
+- Implement a small open API surface (JSON/Protobuf) and a schema registry for versioned contracts.
+- Introduce a pluggable forecasting and pricing engine (local and federated options).
+- Build a delta-sync protocol for offline periods and reconnection.
+- Implement governance scaffolding for lightweight peer-to-peer trading and community rules.
 
-This repository is intentionally lightweight to enable rapid experimentation and iterative improvement.
+Development and contribution
+- This project adheres to the Open-EnergyMesh vision of interoperability and resilience.
+- see AGENTS.md for the architectural guidance and testing commands.
+
+License
+- MIT
+
+Ready-to-publish marker
+- A ready-to-publish marker will be placed at the repository root when the project is fully production-ready.
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..d2f5ee0
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,13 @@
+{
+  "name": "@community/open-energymesh-offline-first-distribute",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@community/open-energymesh-offline-first-distribute",
+      "version": "0.1.0",
+      "license": "MIT"
+    }
+  }
+}
diff --git a/package.json b/package.json
index 102b398..abb65fd 100644
--- a/package.json
+++ b/package.json
@@ -9,5 +9,6 @@
   },
   "license": "MIT",
   "homepage": "",
-  "dependencies": {}
+  "dependencies": {},
+  "readme": "README.md"
 }