feat: add AI knowledge analysis MVP

.trellis/spec/frontend/ai-sdk-integration.md

@@ -244,6 +244,79 @@ if (type === "tool-output-available") {
 }
 ```
 
+## Scenario: Elder AI Analysis Panel MVP
+
+### 1. Scope / Trigger
+
+- Trigger: UI surfaces that render elder AI analysis, knowledge retrieval results, or AI history.
+- Current project contract: the MVP elder workflow is a fixed structured analysis panel, not chat and not streaming.
+- Do not use `@ai-sdk/react` hooks for this MVP panel; use the existing project API result shape through fetch until a generated client exists for these routes.
+
+### 2. Signatures
+
+- Elder row action:
+  - Visible only when current permissions include both `ai:read` and `elder:read`.
+  - Opens `ElderAiAnalysisDialog` with `width="wide"`.
+- Client APIs:
+  - `GET /api/ai/elders/[id]/analyses` -> `{ success, reason, history }`
+  - `POST /api/ai/elders/[id]/analyses` -> `{ success, reason, analysis }`
+  - `GET /api/ai/knowledge` -> `{ success, reason, entries }`
+  - Knowledge mutations -> `{ success, reason, entry }`
+
+### 3. Contracts
+
+- Render completed analysis from fixed fields:
+  - `overallRiskLevel`
+  - `summary`
+  - `keyFindings[]`
+  - `recommendations[]`
+  - `dataGaps[]`
+  - `citations[]`
+  - `confidence`
+  - `modelSummary`
+- Render `restricted: true` history items as placeholders only; do not assume `result` or citations exist.
+- Render failed history from sanitized `errorCategory` / `errorReason`; never display raw provider errors.
+- The MVP UI must not provide one-click business mutations or confirmable drafts from recommendations.
+
+### 4. Validation & Error Matrix
+
+- Missing `ai:read` or `elder:read` -> hide row action.
+- API failure -> show `reason` in the dialog or settings page message area.
+- `restricted: true` history -> show an access-restricted placeholder.
+- `status === "failed"` -> show failed badge and sanitized reason.
+- Empty history -> show empty state.
+- Generation pending -> disable generate button and show loading label.
+
+### 5. Good/Base/Bad Cases
+
+- Good: authorized manager opens dialog, generates analysis, sees latest completed result, citations, data gaps, and history list.
+- Base: generation fails because provider is not configured; user sees a structured failure message and failed history remains visible.
+- Bad: viewer without `ai:read` sees an `AI 分析` row action.
+- Bad: frontend renders recommendations as buttons that create care tasks, alert handling notes, or health review records.
+
+### 6. Tests Required
+
+- Component or route smoke coverage for hidden AI action when permissions are missing.
+- History rendering coverage for completed, failed, restricted, and empty states.
+- Knowledge settings coverage for read-only users and `knowledge:manage` users.
+- Build check must include both unscoped `/app/settings/knowledge` and scoped `/app/[organizationSlug]/settings/knowledge`.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```tsx
+// Do not expose an AI action based only on elder read permission.
+{permissions.includes("elder:read") ? <button>AI 分析</button> : null}
+```
+
+#### Correct
+
+```tsx
+const canUseAi = permissions.includes("ai:read") && permissions.includes("elder:read");
+{canUseAi ? <Button onClick={() => setAiTarget(elder)}>AI 分析</Button> : null}
+```
+
 ## 7. Best Practices Summary
 
 | Rule | Description |