# AI Growth Analyst UX Spec

- Status: Approved — implementation authorized 2026-08-21
- Route: `/growth`
- Language/direction: Persian, RTL

## Experience

- Add `تحلیل‌گر رشد` to the authenticated sidebar and a compact dashboard teaser linking to it.
- Reuse the global terminal selector. Merchant scope may show peers; terminal scope explains that peer comparison is unavailable.
- Keep the previous successful report visible during refresh. Initial and uncached states use visible light/dark skeletons; no state renders an empty page.
- Header states the 90-day horizon starts after the latest complete dataset date. A daily `به‌روزرسانی تحلیل` action shows `nextRefreshAt`, loading, and typed rate-limit feedback.
- Render a responsive, keyboard-accessible forecast chart with count/amount mode, hover/focus points, P10–P90 band, axes/units, chart summary, and a non-visual data alternative.
- Show historical wins, up to five upcoming opportunities, up to three gentle low-period warnings, and a peer card when permitted.
- Each brief contains server-rendered timing/range/evidence plus validated AI headline, interpretation, offer/message suggestion, one preparation step, confidence, and limitation.
- `PARTIAL` keeps deterministic charts/cards and explains that the written AI interpretation was unavailable. `LOW` keeps the forecast visible with an explicit limited-history or high-variance warning. `INSUFFICIENT_DATA` is reserved for scopes with no historical observations. `FAILED` offers safe retry without hiding an older successful report.
- Motion is restrained, supports reduced motion, and does not block reading. All interactive targets are at least 44 px.

## Copy rules

- Use natural professional Persian, Persian `ی`/`ک`, appropriate نیم‌فاصله, Persian digits, and Rial.
- Keep tone constructive: describe opportunity, preparation, and uncertainty; do not shame the merchant or claim guaranteed outcomes.
- Every recommendation visibly cites its deterministic evidence card. AI is labeled advisory.
- No chat, notifications, campaign execution, user memory, provider/model names, token usage, or internal failure details appear in merchant UI.

## Acceptance

- Works at 360, 768, 1024, and wide desktop widths in light/dark RTL layouts.
- All job, cache, refresh, partial, insufficient, unauthorized, and recoverable error states are accessible and tested.
- Generated OpenAPI types are used; no handwritten duplicate growth DTOs or browser secrets exist.
- Cached navigation performs no generation request. Manual retry remains available while the current scope has no persisted AI-written summary; after one exists, refresh is limited once per merchant per Tehran day.