feat(guides): rewrite in-product User Guides as Diátaxis how-tos

Replace 15 feature-dump guides with 43 problem-oriented how-tos grouped
under 10 categories. Drop Maintenance Flows / AI Assistant / Flow Assist
Sparkles — those surfaces no longer exist post-FlowPilot pivot. Rename
Step Library → Solutions Library throughout. Correct every "click X in
the sidebar" reference to match live labels (Home, History, Tickets,
Flows, Scripts, Data, Acct).

Schema: add `category: CategoryId` and optional `relatedSlugs` to Guide;
new Category type and `categories` const drive hub ordering. GuidesHubPage
renders category sections (auto-hides empty); GuideDetailPage renders a
related-guides footer when set; GuideCard drops the misleading "N sections"
subtitle.

Fix step.tip markdown rendering — `**bold**` rendered literally because
tip used plain text instead of the same regex replacement used on
instruction.

14 net-new how-tos for FlowPilot-era surfaces with no prior coverage:
tasklane keyboard flow, view-what-we-know, ask-AI mid-session,
pause-and-leave, resolve, record-fix-outcome, escalate (Escalation
Mode), post-docs-to-ticket, send-client-update, build-script-from-scratch,
open-suggested-flow, pin-a-flow, invite-teammate.

Browser-verified against engineer + owner test users (sidebar labels,
account sub-pages, pilot-screen header buttons, Tasks panel, integration
form). tsc clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.ai/HANDOFF.md

@@ -2,28 +2,41 @@
 
 # HANDOFF.md
 
-**Last updated:** 2026-05-01 (session 9 — started issue cleanup plan sections 1 and 2)
+**Last updated:** 2026-05-02 (post-guides-rewrite, uncommitted)
 
-**Active task:** None. Pick next from `.ai/TODO.md` or roadmap.
-
-**Just-updated:** issue cleanup plan sections 1 and 2 were started and documented.
+**Active task:** None. The guide rewrite is complete; working tree dirty pending review/commit.
 
 ## Where this session ended
 
-Issue cleanup plan follow-up completed:
+In-product User Guides at `/guides` rewritten from 15 feature-dump guides → 43 problem-oriented Diátaxis how-tos under 10 categories. Schema extended (`category`, `relatedSlugs`), hub re-rendered with category headings, detail page gained a Related guides footer, tip-markdown rendering bug fixed. All changes browser-verified (engineer + owner) against live UI, every detail page renders without 404, tsc clean.
 
-- Section 1: frontend lint is clean. Stale lint disables from the warning set were removed or replaced with justified comments, hook dependency warnings were resolved, e2e selectors were added for session history and the FlowPilot command-palette entry, and `AssistantChatPage` now logs unexpected `currentChatRef` stale async discards.
-- Section 2: `TaskLane` action cards now have diagnostic help affordances for common commands (connectivity, DNS, IP config, event logs, services, and generic checks). #128 was documented as "keep existing responsive side-panel/bottom-drawer behavior unless pilot feedback proves a preference is needed."
-- Updated `docs/plans/2026-05-01-issue-cleanup-plan.md` with section 1/2 status and validation.
-- Validation passed: `docker exec -w /app resolutionflow_frontend npm run lint`, `docker exec -w /app resolutionflow_frontend npx tsc -b`, and `docker exec -w /app resolutionflow_frontend npm run build` (existing Vite large-chunk warning only).
+**Working tree dirty.** Files touched:
+- `frontend/src/data/guides.ts` (full rewrite of `guides` array + new `categories` array + extended types)
+- `frontend/src/pages/GuidesHubPage.tsx` (renders category sections, hides empty ones)
+- `frontend/src/pages/GuideDetailPage.tsx` (related-guides footer, dropped section-count)
+- `frontend/src/components/guides/GuideCard.tsx` (dropped section-count subtitle)
+- `frontend/src/components/guides/GuideSection.tsx` (markdown bold now works in tips)
+- `CHANGELOG.md` ([Unreleased] entry added)
+- `.ai/CURRENT_TASK.md` ("Recently shipped" entry added)
+- `.ai/SESSION_LOG.md` (session entry added)
+- `.ai/HANDOFF.md` (this file)
+
+The user has not yet been asked to commit. When picking this up next session, check with the user before staging — they may want to ship as a single commit, branch + PR, or fold into another change in flight.
 
 ## Resume point — DO THIS NEXT
 
-If tracker auth is available, close #127 and close/archive stale PR #124; rewrite #66 to template packs / one-click install only. Then continue the plan at section 3: #58 structured "step is wrong" quality signals. After that, section 4 is #60 recurring issue detection and section 5 is #129 hierarchical guide navigation.
+1. **Decide commit shape.** Likely a single commit on a `feat/guides-diataxis-rewrite` branch with PR. Pre-existing TODOs from the prior session (cleanup of #127, rewrite of #66, sections 3-5 of the issue cleanup plan) are **unblocked again** — pick up `2026-05-01-issue-cleanup-plan.md` section 3 (#58 structured "step is wrong" quality signals) once the guides land.
+
+2. **Two follow-ups intentionally deferred from this session** (worth picking up if a related touch happens):
+   - **`change-teammate-role` how-to was dropped** because the test owner account has no non-owner members to inspect the role-change control. Once a teammate is invited via `invite-teammate`, verify whether the Membership list exposes a Role dropdown (or some other control) for non-owners and add the guide back.
+   - **Resolve / Escalate modal contents are unverified.** Browser couldn't drive Resolve to completion (test session has 6 pending Tasks gating it; clicking Resolve fired a toast). The how-tos point at the right buttons in the right place, but the exact modal copy and the Escalation Mode wedge specifics are based on project context, not live observation. Worth a quick spot-check the next time a clean test session is available.
+
+3. **`/etc/hosts` entry added on this code-server LXC.** `100.64.78.44 docker-01` — should now persist; HANDOFF.md previously claimed it was already there but wasn't. If `/browse` against `docker-01:5173` ever fails to resolve again, re-add it via `sudo tee` from a real terminal (the `!` shell prefix can't drive interactive sudo on this LXC).
 
 ## Environment notes (carry-forward)
 
-- This code-server LXC has bun + docker but no native `python`/`node`/`npm`. Use `docker exec resolutionflow_{backend,frontend} …` for all build/test commands. Documented in `.ai/PROJECT_CONTEXT.md`.
-- Headless Chromium (used by `/qa` `/browse`) needs `CONTAINER=1` in the env that launches the browse server, otherwise it aborts at `sandbox/linux/services/credentials.cc` due to the LXC namespace constraint. The browse server is currently running with that env set; restarting it manually requires `CONTAINER=1 $B status` again.
-- Code-server's `/etc/hosts` has `100.64.78.44 docker-01` so the headless browser can resolve the bake-in `VITE_API_URL`. Persistent — no need to re-add unless the container is rebuilt.
+- Code-server LXC has bun + docker but no native `python`/`node`/`npm`. Use `docker exec resolutionflow_{backend,frontend} …` for build/test commands.
+- No `gh` CLI on this LXC — use the Gitea API (`$GITEA_TOKEN`) for PR/issue work, or run `gh` from a host that has it.
+- Headless Chromium (`/qa`, `/browse`) needs `CONTAINER=1` in the env launching the browse server (LXC namespace constraint).
+- `/etc/hosts` has `100.64.78.44 docker-01` so the headless browser resolves the bake-in `VITE_API_URL`. Confirmed persistent as of this session.
 - Multi-head alembic state on `main` (heads `070`, `c0f3a4b7e91d`, `024`) is pre-existing. Use `alembic upgrade heads` (plural) if `head` complains.