docs: specify growth analyst experience

docs/GROWTH-ANALYST-UX-SPEC.md

@@ -0,0 +1,32 @@
+# 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. `INSUFFICIENT_DATA` explains the minimum evidence without presenting a forecast. `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 refresh is explicit and limited once per merchant per Tehran day.
+

tasks/ai-growth-analyst.md

@@ -0,0 +1,8 @@
+# AI Growth Analyst Frontend Tasks
+
+- [ ] U1: Regenerate OpenAPI types and extend the typed client/report state model.
+- [ ] U2: Add `/growth`, sidebar navigation, dashboard teaser, and global-terminal scope integration.
+- [ ] U3: Add accessible 90-day forecast chart, confidence/summary states, event evidence, opportunity/risk, peer, and campaign brief components.
+- [ ] U4: Add initial/refresh skeletons, preserved previous report, SSE/poll recovery, daily refresh feedback, partial/insufficient/error states, and reduced-motion behavior.
+- [ ] U5: Add unit/component tests, format/check/build verification, responsive RTL review, and light/dark accessibility review without browser automation unless the user grants permission.
+