diff --git a/.gitignore b/.gitignore
index dcb8580..7e2742a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,8 +2,10 @@ __pycache__/
 *.py[cod]
 .coverage
 .hypothesis/
-.workspace/transitions/
-.workspace/work/
+.workspace/
+.claude/
+.codex/
+CLAUDE.md
 .pytest_cache/
 .ruff_cache/
 .venv/
diff --git a/.workspace/shared-context.md b/.workspace/shared-context.md
deleted file mode 100644
index c6eaa11..0000000
--- a/.workspace/shared-context.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Shared project context: ml4t-specs
-
-## Package
-
-- Package name: `ml4t-specs`
-- Import path: `ml4t.specs`
-- Purpose: runtime-neutral contracts shared by ML4T libraries
-
-## Workflow
-
-```bash
-uv sync
-uv run ruff check src tests
-uv run ruff format --check src tests
-uv run ty check
-uv run pytest
-```
-
-## Contract requirements
-
-- Keep specifications independent of engine implementations.
-- Use versioned, serializable values for cross-library behavior.
-- Export public contract types from `ml4t.specs`.
diff --git a/AGENTS.md b/AGENTS.md
index 27da4ac..c3a357f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,47 @@
 # ml4t-specs
 
-Codex uses `AGENTS.md` as the repository entry point.
+Runtime-neutral, serializable contracts shared at the boundaries of the ML4T libraries. The package
+defines market-data schemas, artifact metadata, strategy lifecycle events, canonical order intents,
+execution policies, and position-rule state without depending on a backtest or live engine.
 
-@.workspace/shared-context.md
+## Public entry points
+
+```python
+from ml4t.specs import FeedSpec, LifecycleContract, MarketDataSpec
+from ml4t.specs import read_spec_payload, write_spec_payload
+```
+
+Use exports from `ml4t.specs` rather than implementation modules. Contract field names, enum values,
+validation behavior, and serialized representations are public compatibility surfaces.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/ml4t/specs/base.py` | Artifact identity, provenance, and storage contracts |
+| `src/ml4t/specs/market_data.py` | Feed, schema, semantics, and market-data specifications |
+| `src/ml4t/specs/lifecycle.py` | Versioned lifecycle phases, events, and causal validation |
+| `src/ml4t/specs/intents.py` | Targets, child orders, execution policies, and position rules |
+| `src/ml4t/specs/io.py` | YAML and JSON payload reading and writing |
+| `tests/fixtures/` | Canonical serialized compatibility fixtures |
+| `docs/contracts.md` | Contract semantics and cross-library responsibilities |
+
+## Contract constraints
+
+- Keep specifications independent of engine implementations. Backtest and Live own runtime
+  behavior; Specs owns the values they exchange.
+- Use versioned, serializable values for cross-library behavior.
+- Export supported contract types from `ml4t.specs`.
+- Preserve compatible payloads. When compatibility cannot be maintained, add a new contract version,
+  migration guidance, and fixtures that define the transition.
+
+## Quality commands
+
+```bash
+uv sync --dev
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run ty check
+uv run pytest
+uv run mkdocs build --strict
+```
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 43c994c..0000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1 +0,0 @@
-@AGENTS.md