diff --git a/AGENTS.md b/AGENTS.md
index e516510..bdfb9c0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1 +1,35 @@
 # AGENTS.md
+
+This repository implements CrossVenueArbX, a lightweight federated, deterministic cross-venue equity arbitrage framework (MVP). The goal of this document is to define the architecture, testing, contribution rules, and onboarding expectations for contributors.
+
+Overview
+- Core modules live under `crossvenue_arbx/`:
+  - `core.py`: Data contracts for local signals, shared signals, deltas, and governance primitives.
+  - `adapters.py`: Starter adapters for venue price feeds and simulated broker execution.
+  - `coordinator.py`: Central coordinator implementing a minimal async-ADMM-like flow and deterministic replay.
+  - `demo.py`: A small end-to-end demo wiring adapters and the coordinator.
+  - `governance.py`: In-memory Graph-of-Contracts registry used for versioning adapters and data contracts.
+- Tests exercise core data contracts and a small integration flow via the demo. The test suite is designed to be fast and deterministic.
+
+Getting Started
+- Run tests and build: `bash test.sh` (this runs `pytest`, builds the package, and installs it in editable mode).
+- To run the demo locally: `python -m crossvenue_arbx.demo --iterations 3` or use `python crossvenue_arbx/demo.py --iterations 3`.
+
+Architecture Guidelines
+- LocalArbProblem, SharedSignals, PlanDelta, DualVariables, AuditLog, PrivacyBudget form the canonical IR (data contracts).
+- Async ADMM-lite: each venue computes local deltas; a central coordinator merges aggregated signals with bounded staleness.
+- Privacy and governance: use secure aggregation stubs and a Graph-of-Contracts registry for versioning adapters and data contracts.
+- Deterministic replay on reconnects via CRDT-like delta merges and explicit signatures.
+
+Testing & Validation
+- Use `test.sh` for quick end-to-end validation. It runs unit tests, builds the package, and ensures packaging metadata compiles.
+- Additional checks can be added to CI to exercise the demo end-to-end with more iterations and randomized seeds.
+
+Contribution Rules
+- All changes should be covered by tests. If you introduce breaking changes, add or adjust tests accordingly.
+- Follow the existing naming conventions used in `crossvenue_arbx/` (CamelCase class names, snake_case functions).
+- Update `README.md` with user-facing changes and new data contracts or adapters.
+
+If you are releasing an idea or patch that affects the governance contract or adapters, please ensure you
+- add a tag/remark to `governance.py` and wire up versioning in `GraphOfContracts`.
+- keep the scope small and well-scoped to enable incremental onboarding and testing.
diff --git a/README.md b/README.md
index 6bf298b..0d29d8d 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,30 @@
 # CrossVenueArbX (MVP)
+
+CrossVenueArbX is a lightweight, privacy-aware framework for federated discovery and execution of cross-venue equity arbitrage signals.
+
+- Core IR: LocalArbProblem, SharedSignals, PlanDelta, DualVariables, AuditLog, PrivacyBudget.
+- Lightweight coordination: Async ADMM-lite with deterministic replay and bounded staleness.
+- Privacy by design: secure aggregation stubs, optional local DP budgets, cryptographic attestation of adapters.
+- Adapters and data feeds: starter price-feed adapters and a minimal broker adapter for execution.
+- Governance and provenance: tamper-evident audit logs and a Graph-of-Contracts registry.
+- MVP pipeline: Phase 0 skeleton with 2 starter adapters; Phase 1 governance ledger; Phase 2 cross-venue demo; Phase 3 production-like testing and SDK.
+
+Getting Started
+- Run tests and build: `bash test.sh`.
+- Run the demo locally: `python -m crossvenue_arbx.demo --iterations 3`.
+- View coverage and governance artefacts in `crossvenue_arbx/governance.py` and `crossvenue_arbx/core.py`.
+
+Architecture Summary
+- Local signal discovery per venue; aggregated signals managed by a central coordinator.
+- PlanDelta encodes actionable cross-venue arb legs.
+- Graph-of-Contracts provides versioning for adapters and data contracts.
+- CRDT-like delta merges enable deterministic replay after reconnects.
+
+Usage and API surface
+- LocalArbProblem: per-asset, per-venue problem statement.
+- SharedSignals: cross-venue deltas, correlations, liquidity estimates.
+- PlanDelta: incremental arb actions with timestamps and signatures.
+- AuditLog/PrivacyBudget: governance and data-leakage controls.
+
+Notes
+- This release aims for a production-ready architecture rather than a bare MVP. See AGENTS.md for contribution rules and testing commands.