diff --git a/AGENTS.md b/AGENTS.md
index e810593..e4d81ae 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,6 +29,8 @@ This repository owns deployment concerns only. Backend and frontend directories
 
 - Everything runs through Docker, Docker Compose, Bash scripts, and environment files/templates.
 - The CSV-to-PostgreSQL workflow is a one-time administrative bootstrap/recovery command, never a scheduled ingestion service. ZarinPal owns future production payment writes.
+- The analytics refresh worker is not an ingestion service: it derives projections from normalized PostgreSQL changes, publishes within 15 minutes, and performs an idempotent nightly reconciliation. Deployment must surface failed/stale refreshes and must not advance freshness on failure.
+- Reviewed yearly Iranian calendar snapshots are versioned backend reference data and loaded into PostgreSQL; production containers must not depend on a runtime calendar API.
 - Nginx is the only public entry point. PostgreSQL and internal services are not internet-exposed.
 - Health checks distinguish liveness from readiness.
 - Backups are encrypted where supported, validated, retention-aware, and paired with rehearsed restores.
diff --git a/CAPABILITY-MAP.md b/CAPABILITY-MAP.md
index 181bb9a..5340a5d 100644
--- a/CAPABILITY-MAP.md
+++ b/CAPABILITY-MAP.md
@@ -15,7 +15,7 @@ The hackathon demo will seed one account per merchant. Where merchant profile fi
 |---:|---|---|---|:---:|
 | 1 | Data foundation | PostgreSQL model, one-time CSV bootstrap, provenance, validation, quality reporting, synthetic merchant profiles; future source writes are owned by ZarinPal | — | Yes |
 | 2 | Identity and access | Merchant credentials, sessions, tenant isolation, demo account seeding | Data foundation | Yes |
-| 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, traceability | Data foundation | Yes |
+| 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, traceability, projection refresh within 15 minutes, nightly reconciliation | Data foundation | Yes |
 | 4 | Merchant API | Stable authenticated interfaces for dashboard data and analytics | Identity and access, analytics engine | Yes |
 | 5 | Merchant dashboard | Persian RTL dashboard, responsive navigation, accessible charts/tables and explanations | Merchant API | Yes |
 | 6 | AI assistance | AvalAI-backed explanation/recommendation workflow over sanitized aggregates | Analytics engine, merchant API | No |
@@ -48,6 +48,8 @@ Build sequence: data foundation → identity and analytics → API → dashboard
 6. AI is post-MVP, receives only minimized/sanitized aggregates, and cannot become the source of record.
 7. External calls have timeouts and bounded retries; jobs are idempotent and observable.
 8. Production changes are reversible and backed by documented health checks and rollback steps.
+9. Only `Verified` is a confirmed successful session; `Paid` remains a separately reported state until an approved metric-catalogue revision says otherwise.
+10. Iranian official holidays come from reviewed, versioned annual calendar snapshots; broader analytical event windows are explicitly labeled and versioned.
 
 ## Required capability specs