diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8039182
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# revenue-recovery-agent
+
+A deterministic, dry-run A2A agent that identifies recoverable subscription revenue and prepares respectful, policy-compliant recovery actions without autonomously charging, refunding, changing subscriptions, sending messages, or updating CRM.
+
+## Public skills
+
+The Agent Card exposes exactly five typed skills:
+
+1. `analyze_revenue_leakage` — ingests authorized billing/subscription/usage/CRM/support snapshots or deterministic synthetic fixtures, reconciles records, classifies leakage, estimates recoverable amount and confidence intervals, and writes `leakage.json`.
+2. `prioritize_accounts` — prioritizes tokenized accounts by value, likelihood, customer risk, and policy blockers, and writes `prioritized-accounts.json`.
+3. `propose_recovery` — prepares remediation recommendations and respectful message drafts, each with immutable plan digest and explicit approval boundary, and writes `recovery-plans.json`.
+4. `validate_recovery` — validates plans against consent, suppression, jurisdiction, dispute, brand, and prohibited-action rules, and writes `compliance-report.json`.
+5. `generate_campaign_pack` — generates an approval-ready campaign pack and measurement plan, and writes `campaign-pack.md` plus `measurement-plan.json`.
+
+## Safety and policy boundary
+
+- `dry_run=true` is enforced by schema validation.
+- No LLM calls are made; caller LLM credentials are not required.
+- No external HTTP calls are made. Egress is denied by default.
+- Consumer integration setup fields are declared for future read-only adapters, but synthetic/provided snapshots are used by this implementation.
+- All customer identifiers are tokenized; outputs must not include emails, phone numbers, card data, bank details, or raw CRM notes.
+- Protected trait metadata keys are rejected.
+- Prompt-injection-like and SSRF-like values are rejected or reported as critical safety findings.
+- Any future external action must require `I_APPROVE_THE_LISTED_STEPS:<immutable_plan_digest>`; this version only prepares plans.
+
+## Outputs
+
+The agent persists redacted artifacts under:
+
+```text
+outputs/revenue-recovery/{run_id}/
+```
+
+The synthetic full workflow produces:
+
+- `leakage.json`
+- `prioritized-accounts.json`
+- `recovery-plans.json`
+- `compliance-report.json`
+- `campaign-pack.md`
+- `measurement-plan.json`
+
+Individual skills write their own stage output; `generate_campaign_pack` runs the deterministic synthetic pipeline when intermediate inputs are not supplied and writes the campaign/measurement artifacts.
+
+## Example smoke payload
+
+```json
+{
+  "request": {
+    "tenant_id": "tenant-acme",
+    "use_synthetic_data": true,
+    "policy": {"dry_run": true}
+  }
+}
+```
+
+Call it against `analyze_revenue_leakage` or provide the analogous `request` object to any of the five skills.
+
+## Tests
+
+Focused tests cover:
+
+- Agent Card skill/schema contract
+- Reconciliation and duplicate-invoice double-count prevention
+- Suppression and dispute blockers
+- Confidence scoring bounds and intervals
+- Fairness/privacy rejection of protected trait and malicious inputs
+- SSRF-style endpoint blocking
+- Idempotent deterministic analysis
+- Synthetic campaign pack artifact generation