docs: define page insight operations contract

docs/AI-PAGE-INSIGHTS-SPEC.md

@@ -0,0 +1,29 @@
+# AI Page Insights and Calendar Intelligence
+
+Status: implemented platform contract; reviewed production calendar data must be imported and approved before module flags are enabled.
+
+## Scope and authority
+
+The platform serves `overview`, `payments`, `fees`, `peers`, `transactions`, and `growth`. Transaction-detail pages are excluded. Merchant identity comes only from the authenticated session; the optional terminal must belong to that merchant. Reporting periods and table filters never enter the insight scope or fingerprint.
+
+PostgreSQL and Go own dates, aggregates, rankings, confidence, forecasts, calendar classifications, and freshness. Provider input may contain aggregate evidence IDs only. Raw payment rows, payer-card keys, session source keys, and unsuppressed peer values are forbidden.
+
+## Time semantics
+
+`asOfDate` and `forecastStartDate` are the real `Asia/Tehran` date supplied through an injectable clock. `dataThroughDate` is the latest completed dataset date. A lag of zero or one day is `FRESH`, two through seven is `LAGGING`, and more than seven is `STALE`. Stale output remains visible, is labelled “latest observed state,” and is capped at `LOW` confidence. Missing prior-year evidence is `INSUFFICIENT_DATA`, never synthetic history.
+
+## Persistence and delivery
+
+`ai_insight_snapshots` preserves immutable revisions and the latest valid `READY` or deterministic `PARTIAL` result. `ai_insight_jobs` is a PostgreSQL durable queue with bounded leases and recovery. `ai_insight_events` retains one hour of tenant-scoped replay for SSE. Fingerprints cover merchant, optional terminal, module, real as-of date, dataset watermark, calendar, analytics, prompt/schema, and model versions.
+
+Manual refresh requires CSRF plus `Idempotency-Key` and is limited to one accepted refresh per module, terminal scope, and Tehran day. Import, calendar, and nightly jobs do not consume this quota. Refreshes never hide an earlier valid snapshot.
+
+## Calendar workflow
+
+Calendar versions move through `DRAFT`, `APPROVED`, `ACTIVE`, and `RETIRED`. Import validation requires coverage of three previous and two future Jalali years, source lineage, unique keys, valid classifications, resolved recurrence dates, and safe commercial posture. The importer and reviewer must be different actors. Activation is serialized and schedules new insight snapshots.
+
+Use `go run ./cmd/calendar -action import -file <reviewed.json> -current-jalali-year 1405`, then separate `approve` and `activate` commands. Production readiness requires a human-reviewed University of Tehran official-calendar extraction plus separately sourced Iran-impact events. The codebase does not treat an example or partial catalog as production-ready.
+
+## UI contract
+
+Each page mounts an independent `AIInsightPanel`. It depends only on module and terminal. It keeps prior copy during refresh, represents loading/stale/partial/limited/unavailable states independently, announces status changes, preserves RTL and keyboard behavior, and gives mourning or memorial events restrained neutral styling. Growth retains its legacy 90-day detail during the compatibility release.

docs/decisions/0016-persisted-page-insight-platform.md

@@ -0,0 +1,17 @@
+# ADR 0016: Persisted page insight platform and reviewed calendar authority
+
+Status: Accepted
+
+## Decision
+
+Use versioned PostgreSQL snapshots and leased jobs for all six page insights. Page rendering reads the last valid snapshot and never invokes the AI provider. Scheduled, import, calendar, anomaly, and manual triggers enqueue deduplicated work. Keep the growth-report API as a compatibility adapter for one release.
+
+Use a reviewed, activated database calendar as the only forecasting calendar authority. No render or forecast path may depend on a live calendar API. Tone and commercial posture control language safety but never imply financial direction; a direction requires deterministic merchant or eligible-cohort evidence.
+
+## Consequences
+
+- Analytics numbers remain reproducible and independently testable.
+- Provider latency and outages degrade to explicit deterministic `PARTIAL` copy without blocking metrics.
+- Calendar completeness and human approval become release-readiness gates.
+- PostgreSQL remains the durable queue, avoiding a second coordination system while preserving lease recovery and idempotency.
+- Worker scheduling is now intentional recurring production work; operations must monitor job age, fallback rate, stale scope count, calendar coverage, provider usage, and cost.