diff --git a/README.md b/README.md
index e2ea4b7..e39b99f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,44 @@
 # marketcompiler-verifiable-dsl-edge-compi
 
-Idea summary: A novel, open-source compiler-runtime that lets portfolio managers and fintech developers express investment rules, risk budgets, and execution policies in a mathematically-precise DSL, which is then compiled into portable, verifiable e
\ No newline at end of file
+Idea summary: A novel, open-source compiler-runtime that lets portfolio managers and fintech developers express investment rules, risk budgets, and execution policies in a mathematically-precise DSL, which is then compiled into portable, verifiable execution graphs suitable for edge devices and desktop workloads.
+
+This repository hosts a lightweight MVP that focuses on portability, auditability, and offline testing for verifiable investment-strategy DSLs.
+
+Key goals
+- A portable DSL to express assets, objectives (return vs. risk), constraints, and execution policies.
+- Verifiable IRs with per-step proofs and cryptographic signing to support end-to-end auditability.
+- Offline-first execution and deterministic delta-sync for governance-enabled workflows.
+- Lightweight, interoperable adapters to plug in data feeds, risk models, and broker interfaces.
+
+What you get in this MVP
+- Core models: LocalProblem, PlanDelta, AuditLog (in marketcompiler_verifiable_dsl_edge_compi/core.py).
+- Signer: simple HMAC-based signing to attest plans (marketcompiler_verifiable_dsl_edge_compi/signer.py).
+- Adapters: starter adapters (PriceFeedAdapter, MockBrokerAdapter) implementing a common interface (AbstractAdapter).
+- Graph-of-Contracts registry: tiny registry to track adapter schemas and versioning (marketcompiler_verifiable_dsl_edge_compi/registry.py).
+- Deterministic backtester: small offline tester to validate DSL-derived plans against historical data (marketcompiler_verifiable_dsl_edge_compi/backtest.py).
+- Packaging ready: Python packaging metadata in pyproject.toml and a functional test suite.
+
+How to use (quickstart)
+- Install locally: python3 -m build && pip install dist/marketcompiler_verifiable_dsl_edge_compi-0.0.1-py3-none-any.whl
+- Run tests: ./test.sh
+- Example usage:
+  - Define a LocalProblem with assets and objectives.
+  - Create a PlanDelta to capture changes, sign with Signer, and serialize to JSON.
+  - Use Backtester.run(lp) to validate a DSL-derived plan against prices.
+
+Design notes
+- The MVP emphasizes simple, explicit data models and deterministic behavior to enable offline testing and governance workflows.
+- The Graph-of-Contracts and adapters are designed to scale as a marketplace of data feeds, risk models, and brokers. TLS-based transport is planned for real adapters.
+- The repository is intentionally small but structured to support rapid extension in Phase 0–3 of the MVP plan.
+
+Roadmap (8–12 weeks)
+- Phase 0 (done for MVP): DSL parser, core IR, two starter adapters, basic local backtester, delta-sync skeleton, tamper-evident AuditLog.
+- Phase 1: Risk budgets (VaR, CVaR), drawdown constraints, governance ledger, cryptographic signing for plans.
+- Phase 2: Cross-exchange adapters, simple optimizer backend for multi-venue execution, mobile SDK for edge execution.
+- Phase 3: End-to-end test harness with simulated markets, metrics on reproducibility, delta-sync latency, and audit-trail completeness.
+
+Contributing
+- See AGENTS.md for architecture and testing rules. This project follows a pragmatic MVP approach with a strong emphasis on correctness and auditability.
+
+License and contact
+- This project is open-source and designed for collaborative improvement.
diff --git a/marketcompiler_verifiable_dsl_edge_compi/__init__.py b/marketcompiler_verifiable_dsl_edge_compi/__init__.py
index 823141c..1fd458a 100644
--- a/marketcompiler_verifiable_dsl_edge_compi/__init__.py
+++ b/marketcompiler_verifiable_dsl_edge_compi/__init__.py
@@ -9,6 +9,9 @@ This package provides:
 - a basic deterministic backtester
 """
 
+# Package version (synchronized with pyproject dynamic version)
+__version__ = "0.0.1"
+
 from .core import LocalProblem, PlanDelta, AuditLog
 from .signer import Signer
 from .adapters import AbstractAdapter, PriceFeedAdapter, MockBrokerAdapter
diff --git a/test.sh b/test.sh
old mode 100644
new mode 100755