From ba4be31786bde9f141c3d919a6cb6e85f28c2fb7 Mon Sep 17 00:00:00 2001 From: chihlasm Date: Sat, 21 Mar 2026 05:15:44 +0000 Subject: [PATCH] docs: update CLAUDE.md with lessons 72-77 and dashboard patterns Added lessons for varchar(30) status column, get_db rollback, action bar height chain, dashboard prefill auto-submit, navigation guard, and manual Alembic migration preference. Updated project structure and frontend patterns for new dashboard cockpit and sidebar sections. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 937a15f9..7b26ee17 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -126,7 +126,7 @@ patherly/ ├── frontend/ │ ├── src/ │ │ ├── api/ # Axios client + endpoint modules -│ │ ├── components/ # common, layout, tree-editor, session, procedural, procedural-editor, library, step-library, ui +│ │ ├── components/ # common, layout, dashboard, tree-editor, session, procedural, procedural-editor, library, step-library, ui, flowpilot │ │ ├── hooks/ # usePermissions, useSessionTimer, useKeyboardShortcuts │ │ ├── pages/ # All page components │ │ ├── store/ # Zustand stores (auth, treeEditor, proceduralEditor, userPreferences) @@ -330,6 +330,18 @@ gh run view --json jobs --jq '.jobs[] | {name: .name, conclusion: .conclusi **71. Enhancement/branch_addition proposals cannot be directly approved:** Backend returns 400 — they require `modified_flow_data` via "Edit & Publish" flow. Only `new_flow` proposals support direct approve. +**72. `ai_sessions.status` column is `VARCHAR(30)`:** Must fit `requesting_escalation` (23 chars). If adding new status values, verify length. Migration `f0aad74ea51b` widened from 20→30. + +**73. `get_db` rolls back on exception:** The dependency does `await session.rollback()` on error to prevent `InFailedSQLTransaction` cascade. Never remove this — without it, one failed request poisons subsequent requests on the same connection. + +**74. FlowPilot action bar height chain:** The action bar (Resolve/Escalate/Pause) requires every ancestor from `app-shell` grid down to have proper flex constraints. Key fix: `ViewTransitionOutlet` wrapper needs `flex flex-col`. If action bar disappears, check height chain with DevTools `getBoundingClientRect()` walk. + +**75. Dashboard prefill auto-submits:** `StartSessionInput` navigates to `/pilot` or `/assistant` with `{ state: { prefill } }`. `FlowPilotSessionPage` auto-submits via `useEffect` + `prefillHandledRef` guard — no double-enter. `AssistantChatPage` does the same pattern. + +**76. Active session navigation guard:** `FlowPilotSessionPage` uses `useBlocker` (same as `TreeEditorPage`) to intercept navigation during active sessions. "Pause & Leave" auto-pauses before proceeding. + +**77. Prefer manual Alembic migrations for targeted changes:** `alembic revision --autogenerate` picks up drift from all tables. For single-column fixes, use `alembic revision -m "desc"` and write `op.alter_column()` manually. + --- ## RBAC & Permissions @@ -370,6 +382,8 @@ gh run view --json jobs --jq '.jobs[] | {name: .name, conclusion: .conclusi - **Procedural navigation:** `ProceduralNavigationPage` handles intake forms, step-by-step execution, and resume via `location.state.sessionId`. Uses `StepChecklist`, `StepDetail`, `ProgressBar`, `CompletionSummary` components. - **Routing helper:** Use `getTreeNavigatePath()` and `getTreeEditorPath()` from `@/lib/routing` for all tree/session navigation. - **Account section layout:** `AccountLayout` has NO sidebar nav. Account sub-pages (categories, target-lists) are reached via link cards on `AccountSettingsPage.tsx`. New account pages: add route in `router.tsx` under `account` children + add a link card in `AccountSettingsPage`. +- **Dashboard cockpit:** `QuickStartPage` is the FlowPilot launchpad. Components in `components/dashboard/`: `StartSessionInput` (mode picker: guided/chat), `PendingEscalations`, `ActiveFlowPilotSessions`, `PerformanceCards`, `KnowledgeBaseCards`, `TeamSummary`, `RecentFlowPilotSessions`. Every stat/card navigates to its detail page on click. +- **Sidebar sections:** Dashboard → RESOLVE (Active Sessions, Escalations) → KNOWLEDGE (Flows, Step Library, Scripts, Review Queue) → INSIGHTS (Exports, Analytics, FlowPilot Analytics). Footer: User Guides, Feedback, Account, Collapse. ---