feat(ui): responsive + WCAG AA polish pass across chat and sources — v1 feature complete

.agent/phases/complete/05_story_suggestion_chips.md

@@ -0,0 +1,59 @@
+# Phase 05 — Story: Suggestion Chips
+
+**Story:** `.agent/user_stories/suggestion-chips.md`
+**Context:** `.agent/PLAN.md` §7 (UI/UX), story file for chip spec
+
+## Goal
+Zero-friction onboarding: 3–4 real example questions on first load,
+clickable → filled → submitted, keyboard-first, mobile-scrollable.
+
+## Implementation steps
+1. `app/config.py` — confirm `suggestions` is env-overridable
+   (`BOR_SUGGESTIONS` as JSON list via pydantic-settings) and tune the
+   defaults against the *actually imported* Homelab/Deployments topics
+   (read a sample of `documents` titles; pick questions real answers
+   exist for).
+2. `app.js` — extract a `renderChips(container, items, {onSelect})` helper;
+   real `<button type="button" class="suggestion-chip" role="listitem">`
+   inside `#suggestions[role="list"]`; onboarding `onSelect` = fill
+   `#message-input` + focus + `composer.requestSubmit()`. Reuse the same
+   helper for deflection chips (Phase 04) with the same submit behavior.
+3. Empty-state lifecycle: first user message hides `#empty-state` (already
+   done in `addMessage`) — verify chips don't linger in the conversation.
+4. Mobile CSS check: chip row `nowrap + overflow-x auto` at ≤640px (tokens
+   already exist — verify, don't duplicate).
+
+## UI Verification
+Against the story: pills 999px radius, ≥44px, brand-soft/brand-ink (≥6:1),
+hover/active states; desktop centered wrap vs mobile single scroll row;
+Tab order reaches chips before the composer input is required; screen
+reader: group labeled "Suggested questions". Screenshot pass 1280px + 375px.
+
+## Testing & Quality
+- Unit/integration: `GET /api/suggestions` honors `BOR_SUGGESTIONS` env
+  override (JSON list); default list has ≥3 non-empty strings.
+- Coverage: **>90%** on `app/` (JS is covered by E2E).
+
+## Playwright Execution Phase
+Run ONLY this story's suite:
+
+```bash
+uv run pytest tests/e2e/test_suggestion_chips.py -v --no-cov
+```
+
+Implements the story mapping: chips render (≥3, role=list); chip click
+submits (user bubble with exact chip text + mock reply); keyboard Tab+Enter
+activates; 375px chip row is a horizontal scroll row.
+
+## Success criteria
+- [ ] onboarding chips render from the API; click = one-tap question
+- [ ] keyboard + SR usable; mobile scroll row
+- [ ] deflection chips share the component + submit behavior
+- [ ] unit + integration green, coverage >90%
+- [ ] story E2E green in isolation
+- [ ] committed
+
+## Commit
+```bash
+git add -A && git commit --no-gpg-sign -m "feat(ui): onboarding suggestion chips with one-tap submit, keyboard access, and mobile scroll row"
+```