docs: define peer comparison presentation

DESIGN.md

@@ -1,7 +1,7 @@
 # Design System — ZarinPal Merchant Analytics
 
 - Status: Draft baseline for approval
-- Version: 0.2.0
+- Version: 0.2.1
 - Last updated: 2026-08-20
 - Direction: Persian-first RTL
 
@@ -106,7 +106,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
 ## Data visualization
 
 - Lead with a written takeaway and exact KPI; charts support the conclusion rather than decorate it.
-- Default comparisons: current period vs previous equivalent period and merchant vs an eligible anonymized cohort. Peer values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise show a clear insufficient-data state.
+- Default comparisons: current period vs previous equivalent period and merchant vs eligible merchants in the same category and selected period. Peer cards show the merchant-weighted cohort median and the active merchant's performance percentile; each peer contributes one value regardless of transaction volume. A higher displayed percentile always means better, so processing-time and fee-rate ranks are direction-adjusted. Peer values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise show a clear insufficient-data state.
 - Always show unit, timezone/calendar, exact reporting period, comparison baseline, sample size, freshness, and missing-data caveat where material.
 - Success/failure colors remain semantic and consistent. Never use a rainbow categorical palette for ordered values.
 - Tooltips are keyboard reachable and not the sole location of important values.
@@ -146,6 +146,7 @@ Navigation labels should describe merchant tasks, not internal database concepts
 
 | Version | Date | Decision |
 |---|---|---|
+| 0.2.1 | 2026-08-20 | Defined same-category peer cards as an equal-per-merchant median plus direction-aware percentile. This prevents the dataset's largest merchants from dominating what should represent a typical peer. |
 | 0.2.0 | 2026-08-20 | Corrected payment lifecycle semantics from CTO guidance: `Paid` and `Verified` are bank-payment successes, `Paid` remains unverified, and session-level fees are real Rial amounts. |
 | 0.1.9 | 2026-08-20 | Added rate-limit UX, 15-second SSE heartbeat/recovery, one-hour replay, and failed-section-only manual retry. |
 | 0.1.8 | 2026-08-20 | Fixed the four parallel section ids, 30-day cache, idempotent start/SSE flow, and section timeout/retry behavior. |

docs/DASHBOARD-SPEC.md

@@ -20,7 +20,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 2. The app shell identifies the active merchant and offers logout.
 3. Overview shows data freshness, selected period, primary outcomes, trend, and prioritized deterministic insights.
 4. Payment performance supports success/failure/retry/timing analysis and traceable drill-downs.
-5. Peer comparison excludes the active merchant and exposes only eligible anonymized cohort aggregates. It displays a value only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise it explains that there is not enough data. This never hides the merchant's own analytics.
+5. Peer comparison uses other eligible merchants in the active merchant's category for the same selected period and excludes the active merchant. For payment success, verification completion, retry recovery, processing-time p50/p95, and paid fee rate, it shows the merchant-weighted cohort median plus the active merchant's direction-aware performance percentile. Every peer has equal weight regardless of transaction volume. Values appear only when at least 10 other merchants and 1,000 combined peer sessions contribute; otherwise the page explains that there is not enough data. This never hides the merchant's own analytics.
 6. Filters and pagination are reflected in the URL where sharing/reload is useful.
 7. Every screen implements loading, empty, partial-data, stale, unauthorized, forbidden, and recoverable-error behavior as applicable.
 8. Responsive behavior and component contracts follow `DESIGN.md`.
@@ -57,6 +57,9 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 - Success views include `Paid` plus `Verified`, verification-completion views separate them, and unverified paid sessions are never styled or described as failures.
 - Paid volume and merchant fee values reconcile at session grain; fee totals remain unchanged when a session has additional attempts.
 - Retry recovery includes eventual `Paid` or `Verified`, and timing percentiles never treat missing values as zero.
+- Peer benchmarks use only the same category and selected period, exclude the active merchant, and give every eligible peer merchant one equal-weight metric value.
+- Peer cards show the cohort median and a percentile where higher always means better; processing-time and fee-rate ranks are direction-adjusted because lower values are better.
+- A high-volume peer cannot dominate the cohort median, and under-sized cohorts produce the typed insufficient-data state without hiding merchant-owned analytics.
 - All core sections begin on first access and become visible independently in completion order without blocking the whole dashboard.
 - The start request is idempotent and always maps equivalent concurrent starts to the same current run.
 - A second equivalent access reuses current Redis entries, and concurrent first accesses do not enqueue duplicate equivalent section jobs.
@@ -71,7 +74,7 @@ Give a non-technical merchant a fast, trustworthy Persian RTL view of payment pe
 
 ## Unresolved dependencies
 
-- Approved analytics metric catalogue and cohort suppression policy
+- Approved analytics interface contract for the metric catalogue and cohort policy
 - Approved authentication/session API
 - OpenAPI/interface contract and error format
 - Decisions listed in `DESIGN.md`