resolutionflow/.ai/HANDOFF.md

HANDOFF.md

Last updated: 2026-05-02 (post-PR-159 — guides Diátaxis rewrite merged into main)

Active task: None. Pick next from .ai/TODO.md or 03-DEVELOPMENT-ROADMAP.md.

Just-merged: PR #159 — In-product User Guides rewritten as 43 Diátaxis how-tos under 10 categories. Drops 3 deprecated guides, renames Step Library → Solutions Library, fixes tip-markdown rendering, adds 14 net-new how-tos for FlowPilot-era surfaces.

Where this session ended

PR #159 merged into main. CHANGELOG, CURRENT_TASK, SESSION_LOG all updated. See .ai/CURRENT_TASK.md "Recently shipped" for the structured rollup.

The 43 guides live at /guides in the app. Schema is now category-aware (Guide.category, optional relatedSlugs); categories const drives hub ordering. Browser-verified against engineer + owner test users (sidebar labels, account sub-pages, pilot-screen header buttons, Tasks panel, integration form). tsc and Vite build clean.

Resume point — DO THIS NEXT

The issue cleanup plan continues from before this session. Pick up docs/plans/2026-05-01-issue-cleanup-plan.md at section 3: #58 structured "step is wrong" quality signals. Then section 4 (#60 recurring issue detection) and section 5 (#129 hierarchical guide navigation).

$GITEA_TOKEN is in .claude/settings.local.json — confirmed working via the PR-creation API call this session. Issue tracker actions can be done from the code-server LXC via curl against https://gitea.resolutionflow.com/api/v1/....

Followups deferred from this session

Worth picking up if a related touch happens:

• change-teammate-role how-to was dropped from PR #159 because the test owner account has no non-owner members to inspect the role-change control. Once a teammate is invited via the Membership form on /account, verify whether the list exposes a Role dropdown (or some other control) for non-owners and add the guide back to frontend/src/data/guides.ts under the account-admin category.
• 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.

Environment notes (carry-forward)

• 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. The previous handoff claimed this entry was persistent but it was missing on this LXC at the start of this session — re-added via sudo tee from a real terminal (the ! shell prefix can't drive interactive sudo). Confirmed working.
• Multi-head alembic state on main (heads 070, c0f3a4b7e91d, 024) is pre-existing. Use alembic upgrade heads (plural) if head complains.