build(agent): new-agents-4#58ba63 iteration

README.md

@@ -17,7 +17,35 @@ Usage
   print(ir)
 
 - CLI (Python module):
-  python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/dsl_file.txt
+python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/dsl_file.txt
+
+Verifiable DSL Overview
+- The EquiCompiler MVP translates a mathematically precise portfolio DSL into a portable, verifiable IR (EquiIR).
+- Each transformation step embeds lightweight cryptographic attestations (digest-based) to ensure auditability and replayability without leaking sensitive data.
+- A Graph-of-Contracts (GoC) skeleton is attached to the IR to enable plug-and-play adapters for data feeds and brokers, while preserving versioned contracts and compatibility.
+- The system supports offline-first evaluation with deterministic delta-sync, enabling local backtests and plan replay when connectivity resumes.
+- Backends are designed for cross-runtime portability: Python backtester for offline tests, C++ for live trading, and WebAssembly for browser-based evaluation.
+- The MVP keeps a minimal, stable surface area while providing clear extension points for future formal verification hooks and delta-sync workflows.
+
+Example workflow
+- Parse a DSL to IR (programmatic):
+  ``from equicompiler_algebraic_portfolio_dsl_to_.core import parse_dsl_to_ir``
+  ``dsl = "assets: AAPL, MSFT, GOOG\nobjectives: maximize_return\nconstraints: max_drawdown=0.2, var=0.95"``
+  ``ir = parse_dsl_to_ir(dsl)``
+  ``print(ir)``
+- Use the CLI to validate and inspect the IR produced from a file:
+  ``python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/dsl_file.txt``
+
+Roadmap (high level)
+- Phase 0: DSL to IR, start backends (Python backtester, minimal C++ live skeleton) and a minimal GoC registry.
+- Phase 1: Formal verification hooks and delta-sync for offline/online reconciliation.
+- Phase 2: Cross-backend interoperability tests with toy adapters.
+- Phase 3: Hardware-in-the-loop (HIL) testing with partitioned portfolios.
+
+Publishing readiness
+- This repository is designed for packaging as a Python module named
+  ``equicompiler_algebraic_portfolio_dsl_to`` with versioning in ``pyproject.toml``.
+- The README now includes a marketing-style overview and usage examples to aid publication.
 
 Project structure
 - AGENTS.md: architecture and testing guidelines for future agents