chore: bump version and changelog (v0.1.0.0)

Add CW security roles reference docs and PSA ticket management plan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-16 14:44:03 +00:00
parent 294b309faa
commit bea34229d6
11 changed files with 7008 additions and 294 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,30 @@
 All notable changes to ResolutionFlow are documented here.
 ## [0.1.0.0] - 2026-04-16
 ### Added
 - **PSA Ticket Management** — dedicated `/tickets` page with URL-param filter state (board, status, priority, company, assignment, closed), paginated ticket list, and slide-in detail panel
 - **TicketDetailPanel** — full ticket view with notes feed, configurations, related tickets, and resource manager; optimistic status updates via dropdown
 - **NewTicketModal** — two-tab ticket creation: "Quick Create (AI)" parses natural language into a pre-filled form via Claude, "Full Form" for manual entry; validates required fields before submitting to CW
 - **AiTicketParseForm** — natural language → structured ticket data using Claude; resolves board and assignee automatically, flags fields needing manual selection
 - **TicketResourceManager** — add/remove CW members as ticket resources with member search autocomplete
 - **Spin-off ticket creation from ResolutionAssist** — AI can detect when a new ticket should be created mid-session and surface the NewTicketModal pre-filled with session context
 - **TicketQueue improvements** — dashboard widget now detects member mapping, caps at 5 items, shows "View All" link to `/tickets`
 - **Board statuses endpoint** — `GET /integrations/boards/{board_id}/statuses` for direct status lookup without a ticket context
 - **Paginated ticket search** — `search_tickets` returns `{items, total, page, page_size}`; parallel CW count fetch for accurate totals
 - **Ticket service layer** — `ticket_service.py` wraps all PSA mutations (create, update status, list/add/remove resources)
 - **Priority lookup endpoint** — `GET /integrations/tickets/priorities` for form dropdowns
 - **PSA error surfacing** — `/tickets` page shows inline error banner with specific guidance when CW returns a permissions error (replaces silent empty state)
 ### Fixed
 - CW query injection: sanitize search `query` string to strip single quotes before interpolation into CW conditions
 - `company_id` filter now correctly applied to CW ticket search conditions (was silently ignored)
 - `linkedTicket` fetch in ResolutionAssist guarded with `currentChatRef` to prevent race condition on session switch
 - Members endpoint auth gate no longer rejects engineers without a PSA mapping
 - Board fallback: ticket list derives available boards from ticket data when the boards API returns empty (permissions)
 - Assignment search and "Load More" removed from resource manager in favor of direct member list
 ## [Unreleased]
 ### Added
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # CLAUDE.md - Patherly / ResolutionFlow Project Context
-> **Last Updated:** April 6, 2026
+> **Last Updated:** April 16, 2026
 ---
@@ -20,18 +20,12 @@
 | Docker containers | `resolutionflow_postgres`, `resolutionflow_frontend`, `resolutionflow_backend` |
 | Backend, frontend UI, production URLs | **ResolutionFlow** |
 - **Design system:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — THE source of truth for all design decisions
 - **Design aesthetic:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no gradients on surfaces, no ambient effects. Light mode planned.
 - **Accent color:** Electric blue (#60a5fa dark / #2563eb light). Used sparingly — ≤5% of the UI. Warning is amber (#fbbf24), info is cyan (#67e8f9).
 - **Fonts:** IBM Plex Sans (`font-sans`, body), Bricolage Grotesque (`font-heading`, headings), JetBrains Mono (`font-mono`, code) — loaded via Google Fonts
 - **Logo:** 30px gradient square (ember orange) + "ResolutionFlow" in Bricolage Grotesque 700
 - **Layout:** Icon rail sidebar (72px default) with hover flyout panels. Pinnable to full 260px sidebar. See [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md)
 - **Brand assets:** `brand-assets/` (source SVGs), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon)
- **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. Step Library is called "Solutions Library" in the UI. Maintenance flows are hidden from UI for pilot (backend still supports them). `tree_type` column values unchanged in DB.
+- **Logo:** 30px gradient square (ember orange) + "ResolutionFlow" in Bricolage Grotesque 700
 - **Layout:** Icon rail sidebar (72px default) with hover flyout panels. Pinnable to full 260px sidebar.
 - **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. Step Library is called "Solutions Library" in the UI. `tree_type` column values unchanged in DB.
 - **Reference mockups:** `docs/mockups/` (HTML files, open in browser)
 **Component styling:** See Design System section below and [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md). All colors via CSS variables. Use "Flows" not "Trees" in user-facing text; use "Projects" not "Procedures" for procedural flows.
 ## Implementation Principles
 - Prefer correct architecture over minimal diff
@@ -59,22 +53,10 @@
 ## Tech Stack
 ### Backend
-
+Python FastAPI, PostgreSQL 16 (async SQLAlchemy 2.0 + asyncpg), Alembic, JWT (python-jose) + bcrypt, Pydantic v2, APScheduler 3.x
 - **Framework:** Python FastAPI
 - **Database:** PostgreSQL 16 (async via SQLAlchemy 2.0 + asyncpg)
 - **Migrations:** Alembic
 - **Auth:** JWT (python-jose) + bcrypt, refresh token rotation (JTI-based)
 - **Validation:** Pydantic v2
 - **Scheduling:** APScheduler 3.x (async, in-process with FastAPI lifespan) + croniter + pytz
 ### Frontend
-
+React 19 + Vite + TypeScript, Tailwind CSS v4 (CSS-only config in `index.css`), Zustand (immer + zundo), React Router v7, Axios, Lucide React
 - **Framework:** React 19 + Vite + TypeScript
 - **Styling:** Tailwind CSS v4 (`@tailwindcss/vite` plugin, CSS-only config in `index.css`) — flat dark theme with ember orange accent (see [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md))
 - **State:** Zustand (with immer + zundo for undo/redo)
 - **Routing:** React Router v7
 - **API Client:** Axios with token refresh interceptor
 - **Icons:** Lucide React
 ---
@@ -82,37 +64,23 @@
 ```
 patherly/
-├── backend/
+├── backend/app/
-│   ├── app/
+│   ├── main.py                     # FastAPI entry point
-│   │   ├── main.py                 # FastAPI entry point
+│   ├── api/endpoints/              # Route handlers
-│   │   ├── api/endpoints/          # Route handlers (auth, trees, sessions, admin, steps, survey, copilot, assistant_chat, integrations)
+│   ├── api/deps.py                 # Auth dependencies
-│   │   │   ├── flow_proposals.py   # Knowledge Flywheel review queue CRUD
+│   ├── core/                       # config, database, permissions, security, audit, rate_limit
-│   │   │   └── flowpilot_analytics.py # FlowPilot dashboard metrics
+│   ├── models/                     # SQLAlchemy models
-│   │   ├── api/deps.py             # Auth dependencies (includes require_team_admin)
+│   ├── schemas/                    # Pydantic schemas
-│   │   ├── api/router.py           # Route registration
+│   └── services/psa/               # PSA provider abstraction (connectwise/, autotask/, halopsa/)
-│   │   ├── core/                   # config, database, permissions, security, audit, rate_limit
+├── backend/alembic/                # Migrations (001-070 sequential, then hash IDs)
-│   │   ├── models/                 # SQLAlchemy models (includes FlowProposal)
+├── backend/tests/                  # pytest integration tests
-│   │   ├── schemas/                # Pydantic schemas
+├── frontend/src/
-│   │   ├── services/psa/           # PSA provider abstraction (base, connectwise/, autotask/, halopsa/, cache, encryption, registry, types)
+│   ├── api/                        # Axios client + endpoint modules
-│   │   ├── services/knowledge_flywheel.py        # AI session analysis → flow proposals
+│   ├── components/                 # UI components
-│   │   ├── services/knowledge_flywheel_scheduler.py # APScheduler job for batch analysis
+│   ├── hooks/                      # usePermissions, useSessionTimer, etc.
-│   │   └── services/knowledge_gap_service.py     # Weak options & escalation signal detection
+│   ├── pages/                      # Page components
-│   ├── alembic/                    # Database migrations (001-070 sequential, then hash IDs)
+│   ├── store/                      # Zustand stores
-│   ├── scripts/                    # seed_data.py, seed_trees.py
+│   └── types/                      # TypeScript interfaces
 │   └── tests/                      # pytest integration tests
 ├── frontend/
 │   ├── src/
 │   │   ├── api/                    # Axios client + endpoint modules
 │   │   ├── 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, scriptGeneratorStore)
 │   │   └── types/                  # TypeScript interfaces
 │   └── (Tailwind v4: CSS-only config in src/index.css)
 ├── docs/plans/archive/             # Archived design/impl docs (pre-March 2026)
 ├── CLAUDE.md                       # This file
 ├── CURRENT-STATE.md                # Detailed feature status
 ├── LESSONS-LEARNED.md              # (Deprecated — consolidated into CLAUDE.md)
 └── docs/plans/                     # Design docs & implementation plans
 ```
@@ -143,252 +111,163 @@ VITE_API_URL=http://localhost:8000
 ## ConnectWise PSA Integration
-ResolutionFlow integrates with ConnectWise PSA (formerly Manage) as the primary PSA integration. All ConnectWise API reference materials live in `docs/connectwise/`.
+All reference materials in `docs/connectwise/`. See [CONNECTWISE-API-REFERENCE.md](docs/connectwise/CONNECTWISE-API-REFERENCE.md) first.
 ### Best Practices Documentation
-Official ConnectWise developer guides live in `docs/connectwise/best-practices/`. Read these BEFORE implementing any CW API integration code:
+Read `docs/connectwise/best-practices/` BEFORE implementing any CW API integration code:
- `PSA-API-Requests.md` — HTTP methods, response codes, condition query syntax, PATCH format, URL encoding, partial responses, custom fields. READ FIRST.
+- `PSA-API-Requests.md` — HTTP methods, condition syntax, PATCH format. READ FIRST.
- `PSA-Callbacks.md` — Callback type/level matrix, retry behavior, URL parameter gotcha, HMAC signature verification.
+- `PSA-Callbacks.md` — Callback matrix, HMAC verification.
- `PSA-Pagination.md` — Navigable vs Forward-Only pagination, Link headers, while-loop pattern.
+- `PSA-Pagination.md` — Forward-Only vs Navigable, Link headers.
- `PSA-Service-Tickets.md` — Ticket field philosophy, recommended field mappings.
+- `PSA-Service-Tickets.md` — Ticket field mappings.
- `PSA-Versioning.md` — Pin API version via Accept header. Use `application/vnd.connectwise.com+json; version=2025.16`.
+- `PSA-Versioning.md` — Pin `application/vnd.connectwise.com+json; version=2025.16`.
- `PSA-Cloud-URL-Formatting.md` — Dynamic base URL construction via `/login/companyinfo/{companyId}`.
+- `PSA-Cloud-URL-Formatting.md` — Dynamic base URL via `/login/companyinfo/{companyId}`.
- `Bundled-Requests.md` — Batch multiple API calls into one request via `/system/bundles`.
+- `Bundled-Requests.md` — Batch via `/system/bundles`.
- `PSA-Markdown.md` — Ticket notes support markdown. Format session documentation output accordingly.
+- `PSA-Markdown.md` — Notes support markdown.
- `PSA-Company-Synchronization.md` — Filter companies by Status/Type for mapping UI.
+- `PSA-Company-Synchronization.md` — Filter companies by Status/Type.
- `PSA-Data-Protection.md` — Security role model, request minimal permissions (MY not ALL).
+- `PSA-Data-Protection.md` — Request minimal permissions (MY not ALL).
 ### Reference Files (read in this order)
-1. `docs/connectwise/CONNECTWISE-API-REFERENCE.md` — Read FIRST. Quick reference covering auth patterns, tiered endpoint map, key field mappings, and integration architecture flows.
+1. `docs/connectwise/CONNECTWISE-API-REFERENCE.md` — Auth patterns, endpoint map, field mappings.
-2. `docs/connectwise/connectwise-psa-resolutionflow-reference.json` — Extracted OpenAPI 3.0.1 spec (v2025.16) with only the 670 endpoints and 342 schemas relevant to ResolutionFlow. Use for exact field types, request/response shapes, and parameter details.
+2. `docs/connectwise/connectwise-psa-resolutionflow-reference.json` — Extracted OpenAPI 3.0.1 spec (670 endpoints, 342 schemas).
-3. `docs/connectwise/connectwise-psa-openapi-full.json` — Complete ConnectWise PSA OpenAPI spec (1838 endpoints, 842 schemas). Only consult if you need an endpoint outside the extracted subset.
+3. `docs/connectwise/connectwise-psa-openapi-full.json` — Full spec (1838 endpoints). Only if you need something outside the subset.
 ### Integration Architecture
 - **Session → Ticket Notes:** Post auto-generated session documentation to ConnectWise tickets as internal analysis notes via `POST /service/tickets/{id}/notes`
 - **Ticket Context → Session Runner:** Pull ticket details, company info, and attached configurations to give FlowPilot AI real-world context
 - **Callbacks:** Register webhooks via `/system/callbacks` for real-time ticket event notifications to suggest relevant Flows
 ### Key Implementation Rules
 - Auth: API Key auth (Base64 of `companyId+publicKey:privateKey`) + `clientId` header on every request
- `clientId` is server-side config (`CW_CLIENT_ID` in `config.py`) — identifies the ResolutionFlow app, NOT per-tenant. Per-connection credentials: `company_id`, `public_key`, `private_key`, `server_url`
+- `clientId` is server-side config (`CW_CLIENT_ID` in `config.py`) — identifies ResolutionFlow app, NOT per-tenant. Per-connection: `company_id`, `public_key`, `private_key`, `server_url`
- All PSA integration code in `services/psa/` — provider pattern with `PSAProvider` abstract base class, `ConnectWiseProvider` implementation, `PsaProviderRegistry` for multi-PSA dispatch
+- All PSA code in `services/psa/` — `PSAProvider` abstract base, `ConnectWiseProvider` impl, `PsaProviderRegistry` for multi-PSA dispatch
 - PSA endpoints in `api/endpoints/integrations.py` — connection CRUD, ticket ops, member mapping
- Credentials encrypted at rest via `services/psa/encryption.py` (Fernet)
+- Credentials encrypted via `services/psa/encryption.py` (Fernet); stored per-team, never per-user
 - Each MSP tenant provides their own CW credentials — ResolutionFlow stores these per-team, never per-user
 - Design for the Autotask integration following the same service layer pattern (future PSA)
 - In-memory TTL cache in `services/psa/cache.py` for board/status/priority lookups
- Respect CW API: paginate with max 1000 per page, handle retries gracefully
+- Integration flows: Session → Ticket Notes via `POST /service/tickets/{id}/notes`; Ticket Context → FlowPilot via ticket details/company/configs; Callbacks via `/system/callbacks`
 ---
 ## Development Commands
-```powershell
+```bash
-# Start PostgreSQL (run from VPS SSH — docker not available inside code-server, see Lesson 103)
+# PostgreSQL (run from VPS SSH — docker not available in code-server, see Lesson 103)
 docker start resolutionflow_postgres
 # Backend (from backend/)
-source venv/bin/activate        # Linux/Mac
+source venv/bin/activate
 # .\venv\Scripts\Activate       # Windows
 uvicorn app.main:app --reload
-# Frontend (from frontend/)
+# Frontend (from frontend/) — requires Node 20 (use nvm: nvm use 20)
 npm run dev
-# Run tests (from backend/)
+# Tests (from backend/)
 pytest --override-ini="addopts="
-# First time only: create test database
+# TypeScript check (use in code-server — avoids EACCES on dist/, see Lesson 105)
-docker exec -it resolutionflow_postgres psql -U postgres -c "CREATE DATABASE resolutionflow_test;"
+npx tsc -b
-# Frontend build (IMPORTANT: stricter than tsc --noEmit — always use as final check)
+# Frontend build — stricter than tsc, always use as final check before push
 cd frontend && npm run build
-# Database migrations
+# Migrations
 cd backend && alembic upgrade head
-alembic revision --autogenerate -m "Description"
+alembic revision --autogenerate -m "Description"  # do NOT pass --rev-id; Alembic generates hash IDs
 # Sequential 3-digit IDs (001–070) were used historically. New migrations use Alembic's default hex hash IDs.
 # Do NOT pass --rev-id — let Alembic generate the hash automatically.
-# Access PostgreSQL (run from VPS SSH — docker not available inside code-server, see Lesson 103)
+# Access PostgreSQL (VPS SSH)
 docker exec -it resolutionflow_postgres psql -U postgres -d resolutionflow
-# Seed data
+# CI runs on Gitea (NOT GitHub Actions): https://gitea.resolutionflow.com/chihlasm/resolutionflow/actions
 cd backend && pip install httpx && python -m scripts.seed_trees
 # CI/CD debugging
 # CI runs on Gitea (gitea.resolutionflow.com), NOT GitHub Actions — gh run list will return nothing useful
 # Check CI status at: https://gitea.resolutionflow.com/chihlasm/resolutionflow/actions
 # `gh` CLI is still used for GitHub Issues/PRs (mirrored repo), not for CI runs
 ```
-### URLs
+### URLs & Test Users
- Frontend: <http://localhost:5173>
+- Frontend: `http://localhost:5173` | Backend: `http://localhost:8000` | API Docs: `http://localhost:8000/api/docs`
- Backend API: <http://localhost:8000>
+- Test password: `TestPass123!` — users: `admin@`, `teamadmin@`, `engineer@`, `pro@` (all `@resolutionflow.example.com`)
 - API Docs: <http://localhost:8000/api/docs>
 ### Test Users (seeded via `scripts/seed_test_users.py`)
 - All share password: `TestPass123!`
 - `admin@resolutionflow.example.com` (super_admin), `teamadmin@resolutionflow.example.com` (team_admin), `engineer@resolutionflow.example.com` (engineer), `pro@resolutionflow.example.com` (solo pro)
 ---
 ## Critical Lessons Learned
-> Lessons 1-40 archived to `docs/LESSONS-ARCHIVE.md` — fixes are baked into the codebase. Consult if you hit a regression.
+> Lessons 1-70 archived to `docs/LESSONS-ARCHIVE.md` — fixes are baked into the codebase.
-### Active Lessons (41+)
+**71. Enhancement/branch_addition proposals cannot be directly approved:** Backend returns 400 — requires `modified_flow_data` via "Edit & Publish". Only `new_flow` proposals support direct approve.
-**41. Assistant chat uses local React state, not Zustand:** `AssistantChatPage.tsx` uses `useState` for `chats`, `messages`, `input`, `loading`. No store.
+**72. `ai_sessions.status` column is `VARCHAR(30)`:** Must fit `requesting_escalation` (23 chars). Verify length when adding new status values.
-**42. Public pages use raw `fetch()`, not `apiClient`:** Survey, shared sessions, and no-auth pages use `fetch()` with full URL. `apiClient` requires auth tokens.
+**73. `get_db` rolls back on exception:** Prevents `InFailedSQLTransaction` cascade. Never remove the `await session.rollback()` in the dependency.
-**43. Adding new email types:** Add static async method to `EmailService` in `core/email.py`. Fire-and-forget from endpoints (log errors, don't fail).
+**74. FlowPilot action bar height chain:** `ViewTransitionOutlet` wrapper needs `flex flex-col`. If action bar disappears, walk `getBoundingClientRect()` from `app-shell` down.
-**44. AI Chat Builder is flow-type-aware:** `ai_chat_service.py` dispatches by `flow_type`. Troubleshooting: `[TREE_UPDATE]` markers. Procedural: `[STEPS_UPDATE]` markers. Both support `[METADATA]`.
+**75. Dashboard prefill auto-submits:** `StartSessionInput` passes `{ state: { prefill } }`. Both `FlowPilotSessionPage` and `AssistantChatPage` auto-submit via `useEffect` + `prefillHandledRef` guard.
-**45. Intake form field schema:** Uses `variable_name` and `field_type` (NOT `name` and `type`).
+**76. Active session navigation guard:** `FlowPilotSessionPage` uses `useBlocker` to intercept navigation. "Pause & Leave" auto-pauses before proceeding.
-**46. `CreateFlowDropdown` uses `AIPromptDialog`:** Opens prompt modal, starts AI session, generates flow, navigates to editor with `{ state: { aiPanelOpen: true, sessionId } }`.
+**77. Prefer manual Alembic migrations for targeted changes:** `--autogenerate` picks up all table drift. For single-column fixes, use `alembic revision -m "desc"` and write `op.alter_column()` manually.
-**47. Editor-Embedded Flow Assist:** `EditorAIPanel` (320px side panel) + `useEditorAI` hook. Ghost nodes use `_suggestion: true` flag. Actions route to model tiers via `settings.get_model_for_action()`. Delta responses use `[DELTA]...[/DELTA]` markers.
+**78. Landing page subtitle is "AI-Powered Troubleshooting for MSPs":** Appears on login, register, and `<title>`. Not "Decision Tree Platform".
-**48. Tree orphan validation uses dynamic root ID:** Orphan check compares against `state.treeStructure?.id` (NOT hardcoded `'root'`).
+**79. Custom modals must be mobile-responsive:** Use `items-end sm:items-center` + `max-w-full sm:max-w-lg`. See `Modal.tsx` and `PrepareSessionModal.tsx`.
-**49. Full-stack features — verify both ends:** Check the full data flow: schema → endpoint → API client → hook → store → UI.
+**80. TopBar search collapses to icon on mobile:** Full bar (`hidden sm:block`) + icon fallback (`sm:hidden`). Both open `CommandPalette`.
-**50. Anthropic SDK retry:** Set `max_retries=1` to fail fast. Default `max_retries=2` can take 3× timeout.
+**81. Never use `transition: all` in landing.css:** Specify exact properties. `transition: all` animates layout and causes jank.
-**51. AI model tier routing:** Use `settings.get_model_for_action(action_type)`. Model IDs: use alias form (`claude-sonnet-4-6`).
+**82. `bun` requires PATH setup:** `export BUN_INSTALL="$HOME/.bun" && export PATH="$BUN_INSTALL/bin:$PATH"`. Chromium deps: `libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2`.
-**52. Mobile scroll-to-top:** Use `ref.current.scrollIntoView()`, not `window.scrollTo()`. Trigger via `useEffect`.
+**84. AI session `abandoned` status is fully wired:** `POST /ai-sessions/{id}/abandon` with optional `reason`. Frontend: `aiSessionsApi.abandonSession()` → `useFlowPilotSession().abandonSession()`.
-**53. Flex height chain:** Every ancestor must be a flex container for `flex-1` to work. Missing `flex` class collapses React Flow to 0 height.
+**85. Date range filter end dates must use end-of-day:** Set `toDate.setHours(23, 59, 59, 999)`. For string inputs append `T23:59:59.999Z`. See `SessionHistoryPage.tsx`.
-**54. React Flow CSS in Tailwind v4:** Import in `index.css`, not component JS. Override dark theme using `--xy-*` CSS custom properties.
+**86. Script Builder:** `/script-builder` — `ScriptBuilderSession` model, `script_builder_service.py`, endpoints at `/scripts/builder/`. FlowPilot handoff via `action_type: "open_script_builder"` + sessionStorage context.
-**55. App shell height chain:** Every wrapper between `.main-content` and canvas needs `flex` + `flex-1` + `min-h-0` or `h-full`.
+**87. FlowPilot must ask GUI vs script preference:** Ask BEFORE suggesting either approach. See `FLOWPILOT_SYSTEM_PROMPT` in `flowpilot_engine.py`.
-**56. Railway backend service name is `patherly`:** Production DB name is `railway`. Public Postgres proxy: `interchange.proxy.rlwy.net:45797`.
+**88. Charcoal palette:** Sidebar `#0e1016`, page `#16181f`, cards `#1e2028`, borders `#2a2e3a`. All via CSS variables in `index.css` `@theme`. Accent is electric blue (#60a5fa).
-**57. Node field priority:** `title` → `question` → `description` → `content` → `label`. See `copilot_service.py`.
+**92. `tsc -b` in Dockerfile enforces `noUnusedLocals`/`noUnusedParameters` as hard errors.** After refactors, trace every import and destructured prop. Check IDE yellow squiggles before pushing.
-**58. `scriptGeneratorStore.generate()` optional param:** Always wrap: `onClick={() => generate()}`, never `onClick={generate}`.
+**93. FlowPilot actions live in the page header, not a bottom bar:** Resolve/Escalate/Share Update in header. Desktop: inline + `⋯` overflow (Pause/Close). Mobile: single `⋯`. Bottom = message input only.
-**59. ConnectWise `clientId` is server-side config:** Set in `config.py` as `CW_CLIENT_ID`. Per-connection: `company_id`, `public_key`, `private_key`, `server_url`.
+**94. Frontend chat uses `unified_chat_service`, not `assistant_chat_service`:** `AssistantChatPage` → `/ai-sessions/{id}/chat` → `unified_chat_service.py`. Never wire chat into `assistant_chat.py`.
-**60. Dockerfile build args for Vite env vars:** Any new `VITE_*` or `VITE_PUBLIC_*` env var must be added as `ARG` + `ENV` in `frontend/Dockerfile` for Railway deploys. Railway env vars are runtime-only unless explicitly passed through as Docker build args. Without this, `import.meta.env.VITE_*` resolves to `undefined` in production builds.
+**95. Image upload → AI vision:** `uploadsApi.upload()` → `upload_ids` in message → backend fetches S3 → `storage_service.resize_image_for_vision()` (Pillow, 1568px, PNG→JPEG) → base64 → Claude multimodal. Max 3 images/message. Images NOT stored in history.
-**61. Procedural sessions auto-start on page load:** `ProceduralNavigationPage` calls `startSession()` immediately in `loadTree()` — there is no intake form screen or "Start" button. Variables are filled inline during execution. Troubleshooting flows DO have a start screen with ticket/client fields. Don't write tests or UI that assume a Start button on procedural flows.
+**96. `bg-accent` is electric blue — never use for code/kbd.** Use `bg-code` for code blocks, `bg-white/[0.12]` for inline code/badges, `bg-white/[0.08]` for kbd.
-**62. Playwright strict mode — scope selectors to avoid ambiguity:** Step titles appear in both the sidebar checklist and main content heading. Use `getByRole('heading', { name })` for the main content, or scope with `page.locator('.animate-scale-in')` for command palette items. `getByText()` frequently matches multiple elements due to the sidebar + main content layout.
+**97. Railway S3 provisioned:** Bucket `resolutionflow-uploads`. Variables: `STORAGE_ENDPOINT`, `STORAGE_ACCESS_KEY`, `STORAGE_SECRET_KEY`, `STORAGE_BUCKET_NAME`, `STORAGE_REGION`. boto3 in `storage_service.py`.
-**63. Node 20 required for frontend builds:** Vite 7+ requires Node 20.19+. The system Node may be v18; use nvm: `export NVM_DIR="$HOME/.nvm" && source "$NVM_DIR/nvm.sh" && nvm use 20`. For direct binary access without nvm sourcing: `PATH="$HOME/.nvm/versions/node/v20.19.0/bin:$PATH"`.
+**98. `lazyWithRetry` for lazy routes:** Use instead of `React.lazy` — auto-reloads on chunk failures with 10s sessionStorage debounce.
-**64. PostHog product analytics:** Initialized via `PostHogProvider` in `main.tsx` with explicit `posthog.init()` + `client` prop pattern. Event helpers in `lib/analytics.ts` — use `analytics.eventName(props)` to track. `identifyUser()` called in `authStore.fetchUser()`, `resetAnalytics()` on logout. Env vars: `VITE_PUBLIC_POSTHOG_KEY`, `VITE_PUBLIC_POSTHOG_HOST`. Autocapture enabled.
+**99. `text-secondary` renders invisible on dark backgrounds:** Maps to `--color-secondary` (dark surface). Use `text-muted-foreground` (`#848b9b`) for readable secondary text. Never use `text-muted` for body text.
-**65. Local Docker Compose uses `resolutionflow` database on port 5433:** Container name is `resolutionflow_postgres`, database is `resolutionflow` (not `patherly`), port mapped to `5433` (not `5432`). The `POSTGRES_PORT` env var controls this. Playwright config defaults must match: `postgresql+asyncpg://postgres:postgres@127.0.0.1:5433/resolutionflow`.
+**100. Hover pop-out card pattern:** `pointer-events-none` on scrim (`z-40`), `z-50` expanded card with own `onClick`, dismiss via `onMouseLeave`. Never put handlers on scrim.
-**66. Dev environment runs on Hostinger VPS (46.202.92.250), not localhost:** Code-server runs in Docker on a VPS (previously devserver01/192.168.0.9). Frontend/backend are accessed via `46.202.92.250`, not `localhost`. CORS must include the VPS IP in `CORS_ORIGINS` and `FRONTEND_URL`. Frontend `.env` must set `VITE_API_URL` to the VPS backend URL. See [DEV-ENV.md](DEV-ENV.md) for full setup, Docker config, networking, and known issues.
+**101. AI marker format compliance:** `[QUESTIONS]`, `[ACTIONS]`, `[FORK]` parsed by `unified_chat_service.py`. History stores `display_content` (stripped). Each user message gets `[SYSTEM: ...]` reminder appended in `_call_anthropic_cached()`.
-**67. Tree editor route is `/trees/new`:** NOT `/editor/new`. Check `router.tsx` line 156 for the canonical path. Use `getTreeEditorPath()` from `@/lib/routing` when navigating programmatically.
+**102. TaskLane activation must happen in ALL chat response paths:** Three paths in `AssistantChatPage.tsx` — `handleSend`, `sendPrefill`, `handleResumeNew`. All must check `response.actions`/`response.questions` and call `setShowTaskLane(true)`.
-**68. APScheduler jobs need `max_instances=1`:** Without it, overlapping scheduler runs can process the same records twice (TOCTOU race). Always set `max_instances=1` on interval jobs in `main.py`.
+**103. Docker not available in code-server:** Use VPS SSH: `docker exec resolutionflow_postgres psql -U postgres -d resolutionflow -t -c "SQL"`. Python also not available in container.
-**69. PostgreSQL `func.sum(case(...))` returns `Decimal` via asyncpg:** Cast to `int()` before storing in Pydantic `dict[str, Any]` fields, or JSON serialization may produce unexpected types.
+**104. `landing.css` uses `--lp-*` variables:** Never use `var(--color-*)` tokens in `landing.css`. Extend the `--lp-*` palette for new landing page colors.
-**70. Toast library uses `toast.warning()` not `toast.warn()`:** Import from `@/lib/toast`. Methods: `success`, `error`, `warning`, `info`. See `frontend/src/lib/toast.ts`.
+**105. `npm run build` fails with `EACCES` on `dist/` in code-server:** Use `npx tsc -b` to verify TypeScript without writing to `dist/`.
-**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.
+**106. Guard async "select item → load data → apply state" flows:** Use `currentSelectionRef = useRef(id)` — update on every switch, bail after each `await` if ref no longer matches. See `AssistantChatPage.tsx` `currentChatRef`.
-**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.
+**107. Startup routines use `_admin_session_factory()`:** RLS is enabled; `get_db()` at startup has no `app.current_account_id`, so queries return 0 rows. Affects lifespan, `ensure_service_account`, seed scripts.
-**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.
+**108. Tables with no `account_id` (never add to RLS migrations):** `script_categories`, `platform_steps`, `template_trees`, `plan_feature_defaults`, `accounts`. Scan at class level, not file level — one `.py` file can have multiple classes with different columns.
-**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.
+**109. `tree_shares.account_id` must equal `tree.account_id`:** Use tree owner's tenant, not the actor's. Cross-tenant admin shares become invisible after RLS enforcement.
-**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.
+**110. Backfill `account_id` migrations require service-code audit:** Grep all `ModelClass(` sites, verify `account_id=` is passed. SQLAlchemy accepts `None` silently; RLS WITH CHECK surfaces it at runtime as `InsufficientPrivilegeError`.
-**76. Active session navigation guard:** `FlowPilotSessionPage` uses `useBlocker` (same as `TreeEditorPage`) to intercept navigation during active sessions. "Pause & Leave" auto-pauses before proceeding.
+**111. Global Axios interceptor fires before component `.catch()`:** Fix optional-data endpoints at the source — return `[]`/`{}` on provider failure instead of raising 502. See `list_boards` in `integrations.py`.
 **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.
 **78. Landing page subtitle is "AI-Powered Troubleshooting for MSPs":** Not "Decision Tree Platform". This tagline appears on login, register, and the HTML `<title>`. The old "Decision Tree Platform" was internal jargon misaligned with user-facing branding.
 **79. Custom modals must be mobile-responsive:** Use `items-end sm:items-center` (bottom-sheet on mobile, centered on desktop) and `max-w-full sm:max-w-lg` (full-width on mobile). The shared `Modal.tsx` does this correctly — custom modal implementations must follow the same pattern. See `PrepareSessionModal.tsx` for the fix pattern.
 **80. TopBar search collapses to icon on mobile:** Full search bar (`hidden sm:block`) shows on desktop; magnifying glass icon button (`sm:hidden`) shows on mobile (<640px). Both open the same CommandPalette. Don't add `w-full` search bar without the mobile icon fallback.
 **81. Never use `transition: all` in landing.css:** Specify exact properties: `transition: background 0.3s, border-color 0.3s, box-shadow 0.3s, transform 0.3s, opacity 0.3s`. `transition: all` animates layout properties and causes jank.
 **82. `bun` requires PATH setup on devserver01:** `export BUN_INSTALL="$HOME/.bun" && export PATH="$BUN_INSTALL/bin:$PATH"`. The gstack browse binary and Playwright need this. Chromium system deps: `libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2`.
 **83. ~~FlowPilot ActionBar fixed bottom~~ (Superseded by Lesson 93):** Actions moved to the page header. `FlowPilotActionBar` component exists but is no longer used in the main session flow. The only fixed-bottom element is the message input.
 **84. AI session `abandoned` status is fully wired:** `POST /ai-sessions/{id}/abandon` sets status to `abandoned` with optional `reason` param. Frontend: `aiSessionsApi.abandonSession()`, `useFlowPilotSession().abandonSession()`, "Close" button in `FlowPilotActionBar`. Redirects to `/sessions` after closing.
 **85. Date range filter end dates must use end-of-day:** `toDate.toISOString()` sends midnight (start of day), excluding items created later that day. Always set `toDate.setHours(23, 59, 59, 999)` before sending. For string-based date inputs (AI sessions), append `T23:59:59.999Z`. See `SessionHistoryPage.tsx`.
 **86. Script Builder system:** AI-powered script generation at `/script-builder`. Chat-style interface generates PowerShell/Bash/Python scripts from natural language. Backend: `ScriptBuilderSession` model, `script_builder_service.py`, endpoints at `/scripts/builder/`. Frontend: `ScriptBuilderPage`, `ScriptCodeBlock`, `ScriptPreviewModal`, `SaveToLibraryDialog`. FlowPilot can hand off to Script Builder via `action_type: "open_script_builder"` with `sessionStorage` context passing.
 **87. FlowPilot must ask GUI vs script preference:** When a task can be done via GUI or script (e.g., creating AD users), FlowPilot must ask the engineer which approach they prefer BEFORE suggesting either. Never assume the user wants a script. See `FLOWPILOT_SYSTEM_PROMPT` rules in `flowpilot_engine.py`.
 **88. Charcoal palette — sidebar-darkest approach:** Sidebar `#0e1016`, page `#16181f`, cards `#1e2028`, borders `#2a2e3a`. This gives more contrast range than true-dark. All colors via CSS variables in `index.css` `@theme` block. Accent is electric blue (#60a5fa), not orange or cyan.
 *(Lessons 89–91 were retracted.)*
 **92. `tsc -b` in Dockerfile is stricter than `npx tsc --noEmit`:** The production build (`tsc -b && vite build`) enforces `noUnusedLocals` and `noUnusedParameters` as hard errors. After any refactor that moves logic between components or removes features, trace every import and destructured prop to remove orphans. IDE warnings (yellow squiggles) flag these — check them before pushing.
 **93. FlowPilot actions live in the page header, not a bottom bar:** `FlowPilotSessionPage` renders Resolve/Escalate/Share Update in the header bar. Desktop: inline buttons + `⋯` overflow (Pause/Close). Mobile: single `⋯` menu. The bottom only has the message input. `FlowPilotActionBar` component still exists but is no longer used in the main session flow.
 **94. Frontend chat uses unified_chat_service, not assistant_chat_service:** `AssistantChatPage` calls `/ai-sessions/{id}/chat` → `unified_chat_service.py`. The old `assistant_chat_service` endpoints were removed (only retention settings remain at `/assistant/retention`). When tracing chat features, start from `aiSessionsApi.sendChatMessage` → `ai_sessions.py` → `unified_chat_service.py`. Never wire chat features into `assistant_chat.py`.
 **95. Image upload → AI vision pipeline:** Paste/attach images → upload to Railway S3 bucket via `uploadsApi.upload()` → send `upload_ids` with chat message → backend fetches from S3 via `storage_service.download_file()` → resized via `storage_service.resize_image_for_vision()` (Pillow, 1568px max, PNG→JPEG) → base64-encoded → sent as Claude multimodal content blocks. Max 3 images/message. Images are NOT stored in conversation history (text-only). Vision helpers live in `storage_service.py`.
 **96. `bg-accent` is electric blue — never use for code/kbd elements:** In Tailwind v4, `bg-accent` maps to `--color-accent: #60a5fa` (dark) / `#2563eb` (light). Use `bg-code` for code blocks, `bg-white/[0.12] border border-white/[0.06]` for inline code/badges, `bg-white/[0.08]` for kbd shortcuts. Blue accent is reserved for interactive elements only (buttons, active nav, links). Ember orange (#f97316) is deprecated — do not use.
 **97. Railway Object Storage (S3 bucket) is provisioned:** Bucket `resolutionflow-uploads` on Railway canvas. Variables: `STORAGE_ENDPOINT`, `STORAGE_ACCESS_KEY`, `STORAGE_SECRET_KEY`, `STORAGE_BUCKET_NAME`, `STORAGE_REGION` — mapped via variable references on the `patherly` backend service. Accessed via boto3 in `storage_service.py`. Pillow (`Pillow>=10.0.0`) + `libjpeg-dev`/`zlib1g-dev` in Dockerfile for image resize.
 **98. `lazyWithRetry` for stale chunk errors:** All lazy-loaded routes use `lazyWithRetry` from `@/lib/lazyWithRetry.ts` instead of `React.lazy`. Auto-reloads the page on chunk load failures (stale deploys). Uses sessionStorage debounce (10s) to prevent loops. When adding new lazy routes, use `lazyWithRetry`, not `lazy`.
 **99. Tailwind v4 `text-secondary` renders invisible on dark backgrounds:** `text-secondary` maps to `--color-secondary: #2e3140` (a dark surface color), NOT `--color-text-secondary`. For readable secondary text, use `text-muted-foreground` (`#848b9b`). Also avoid `text-muted` (`#4f5666`) for body text — it's for labels only. This applies to ALL new components.
 **100. Hover pop-out card pattern:** For cards that expand on hover "in front of everything": use `pointer-events-none` on the scrim (`fixed inset-0 z-40 bg-black/30`), absolute-position the expanded card at `z-50` with its own `onClick` handler, and dismiss via `onMouseLeave` on the wrapper div. Never put interactive event handlers on the scrim — it blocks clicks on sibling elements.
 **101. AI marker format compliance:** The AI assistant uses `[QUESTIONS]`, `[ACTIONS]`, and `[FORK]` markers in responses. Parsed by `unified_chat_service.py` (`_parse_*_marker` functions), returned as structured data in the API response. System prompt in `assistant_chat_service.py` has a final reminder section, and each user message gets an invisible `[SYSTEM: ...]` reminder appended in `_call_anthropic_cached()`. If markers stop appearing: check conversation history stores `display_content` (stripped), verify system prompt final reminder exists, check user message reminder injection is active.
 **102. TaskLane activation must happen in ALL chat response paths:** `AssistantChatPage.tsx` has three code paths calling `sendChatMessage`: `handleSend` (regular messages), `sendPrefill` (dashboard handoff), `handleResumeNew` (resume from concluded session). ALL three must check `response.actions`/`response.questions` and call `setShowTaskLane(true)`. Missing this in any path causes TaskLane to not appear on first message.
 **103. Docker not available in code-server container:** The dev environment runs code-server inside Docker on the VPS. The `docker` CLI is not available inside the code-server container. To query the database, use the VPS SSH session: `docker exec resolutionflow_postgres psql -U postgres -d resolutionflow -t -c "SQL"`. Python is also not available in the container.
 **104. `landing.css` uses self-contained `--lp-*` color variables:** The landing page defines its own color palette at the top of `landing.css` (`--lp-bg`, `--lp-accent`, `--lp-text-*`, etc.). Never use `var(--color-*)` theme tokens in `landing.css` — they may resolve incorrectly outside the app shell context. Extend the `--lp-*` palette for any new landing page colors.
 **105. `npm run build` fails with `EACCES: permission denied` on `dist/` in code-server:** This is a filesystem permission issue in the Docker environment, not a TypeScript error — the TS compilation completes successfully. Use `npx tsc -b` to verify TypeScript cleanly without needing to write to `dist/`.
 **106. Guard async "select item → load data → apply state" flows with a ref:** When a component lets the user switch between items (chat sessions, flows, scripts) and loads data asynchronously on each switch, the load for item A can complete *after* the user has already switched to item B — overwriting B's state with A's stale data. Fix pattern: keep a `currentSelectionRef = useRef(initialId)` and update it synchronously whenever the selection changes (in every creation/switch path). After every `await`, bail out if `currentSelectionRef.current !== thisItemId`. See `AssistantChatPage.tsx` `selectChat` for the reference implementation (`currentChatRef`).
 **107. Startup routines must use `_admin_session_factory()` after Phase 4 RLS:** Any code that runs at startup (lifespan, `ensure_service_account`, seed scripts) and touches tenant-isolated tables (`users`, etc.) must use `_admin_session_factory()` — not `get_db()`. Phase 4 enabled RLS on `users`; a tenant-scoped session has no `app.current_account_id` set at startup, so all queries return 0 rows or fail. `get_service_account_id` in `deps.py` is safe — it reads from `app.state` cached at startup, never hits the DB per-request.
 **108. Tables with no `account_id` column (never add to RLS migrations):** `script_categories`, `platform_steps`, `template_trees`, `plan_feature_defaults`, `accounts` — global/platform tables documented with "No account_id. No RLS." in their model files. When writing RLS migrations, scan at the class level (check for `account_id: Mapped` within the class block), not the file level — multiple classes in one `.py` file can have different columns (e.g. `ScriptCategory` vs `ScriptTemplate` in `script_template.py`).
 **109. `tree_shares.account_id` must equal `tree.account_id`, not the actor's account:** When creating a `TreeShare`, always use `account_id=tree.account_id` (tree owner's tenant). A super admin in tenant A sharing tenant B's tree must produce a share row in tenant B's RLS context — using `current_user.account_id` instead makes the share invisible to the tree owner after RLS is enforced.
 **110. Backfill migrations for `account_id` require a service-code audit:** When a migration adds `account_id` to an existing model via backfill (nullable → backfill → NOT NULL), grep for ALL `ModelClass(` instantiation sites in service code and verify `account_id=` is passed. SQLAlchemy accepts `None` silently with no warning; Phase 4 RLS WITH CHECK only surfaces the problem at runtime as `InsufficientPrivilegeError: new row violates row-level security policy`. Fixed example: `AISessionStep` — all 5 creation sites in `flowpilot_engine.py` were missing `account_id` until April 2026.
 **111. Global Axios interceptor fires before component `.catch()` — fix optional-data endpoints at the source:** The global 5xx handler in `client.ts` fires for ALL non-401 5xx responses, even when a component does `.catch(() => {})`. If an endpoint returns optional UI data (e.g., board filters, PSA config), return `[]` / `{}` on provider failure rather than raising 502. Silencing the error in the component is not enough — the toast appears anyway. See `list_boards` in `integrations.py` for the fixed pattern.
 ## RBAC & Permissions
 - **Role hierarchy:** super_admin > team_admin > engineer > viewer
 - **Team Admin:** `role='engineer'` + `is_team_admin=True` + valid `team_id`
- **Backend deps:** `get_current_active_user(user, db)` (any active + auto-downgrades expired trials), `require_engineer_or_admin` (blocks viewers), `require_admin` (super admin only)
+- **Backend deps:** `get_current_active_user`, `require_engineer_or_admin` (blocks viewers), `require_admin` (super admin only)
 - **Never use** `role == "admin"` — use `is_super_admin` instead
 - **Frontend:** `usePermissions()` hook for all permission checks
 - **Centralized:** `backend/app/core/permissions.py`, `frontend/src/hooks/usePermissions.ts`
@@ -397,18 +276,16 @@ cd backend && pip install httpx && python -m scripts.seed_trees
 ## Design System
-**Source of truth:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — always read this before making visual or UI decisions.
+**Source of truth:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — always read before visual/UI decisions.
- **Theme:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no backdrop blur, no ambient orbs, no gradient backgrounds on surfaces. Light mode fully specified (v6).
+- **Theme:** Flat, high-contrast dark (Sentry/PostHog-inspired). No glass morphism, no backdrop blur, no gradients on surfaces. Fonts: IBM Plex Sans (body), Bricolage Grotesque (headings), JetBrains Mono (code).
 - **Backgrounds:** `bg-page` (`#16181f`), `bg-sidebar` (`#0e1016`), `bg-card` (`#1e2028`), `bg-elevated` (`#2a2d38`)
- **Cards:** `bg-card` with 1px `border-default` (`#2a2e3a`), 8px radius. No shadows, no blur, no gradients. Hover: `border-hover` (`#3d4252`)
+- **Cards:** `bg-card` + 1px `border-default` (`#2a2e3a`), 8px radius. Hover: `border-hover` (`#3d4252`)
- **Buttons:** Primary: solid `accent` (#60a5fa dark / #2563eb light), white text, 5px radius. Ghost: transparent + 1px border, hover `bg-elevated`
+- **Buttons:** Primary: solid `accent` (#60a5fa / #2563eb), white text, 5px radius. Ghost: transparent + 1px border.
- **Inputs:** `bg-input` (`#252830`) with 1px `border-default`, 5px radius. Focus: `border-color: accent` + `box-shadow: 0 0 0 2px accent-dim`
+- **Inputs:** `bg-input` (`#252830`) + 1px `border-default`, 5px radius. Focus: `border-color: accent` + `box-shadow: 0 0 0 2px accent-dim`
- **Text:** `text-heading` (`#f0f2f5`) → `text-primary` (`#e2e5eb`) → `text-muted-foreground` (`#848b9b`) → `text-muted` (`#4f5666`). NEVER use `text-secondary` — in Tailwind v4 it maps to a surface color, not a text color.
+- **Text:** `text-heading` → `text-primary` → `text-muted-foreground` (`#848b9b`). **NEVER `text-secondary`** — maps to a dark surface color.
- **Borders:** `border-default` (`#2a2e3a`), `border-hover` (`#3d4252`)
+- **Functional colors:** `#34d399` success, `#fbbf24` warning, `#f87171` danger, `#67e8f9` info — each has `-dim` at 10% opacity
- **Functional colors:** `#34d399` (success), `#fbbf24` (warning/amber), `#f87171` (danger), `#67e8f9` (info/cyan) — each with `-dim` variant at 10% opacity
+- **Deprecated:** No `glass-card`, `backdrop-filter: blur()`, ambient orbs, ember orange (`#f97316`), or cyan as accent
 - **Accent:** Electric blue `#60a5fa` (dark) / `#2563eb` (light) — used sparingly (≤5% of UI). `accent-dim` = `rgba(96,165,250,0.10)`, `accent-text` = `#93c5fd`
 - **Deprecated:** Do NOT use `glass-card`, `glass-stat`, `bg-gradient-brand`, `text-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, purple gradients, ember orange (`#f97316`), or cyan (`#22d3ee`) as accent — cyan is now the info color only
 ---
@@ -416,23 +293,21 @@ cd backend && pip install httpx && python -m scripts.seed_trees
 - **Component guidelines:** Use `cn()` from `@/lib/utils`, Lucide icons (wrap in `<span>` for title), modals with fixed header/footer
 - **Type organization:** Create in `types/`, export from `types/index.ts`, import with `import type { T } from '@/types'`
- **Scratchpad overlay:** `position: fixed`, `onOpenChange` callback for parent padding adjustment, `right-2` positioning
+- **Custom step flow:** `CustomStepModal` → `PostStepActionModal` → `ContinuationModal`. Use `findCustomStep()` not `findNode()` for custom step UUIDs.
- **Custom step flow:** `CustomStepModal` → `PostStepActionModal` → `ContinuationModal` → custom step view. Key state: `pendingStep`, `pendingContinuationNodeId`, `customBranchMode`, `branchOriginNodeId`. Use `findCustomStep()` not `findNode()` for custom step UUIDs.
+- **Session sharing:** `ShareSessionModal` + `SharedSessionPage`. Utils in `lib/sessionShare.ts`. Share URLs: `/shared/sessions/:token`.
 - **Session sharing:** `ShareSessionModal` manages share links, `SharedSessionPage` renders public/account views. Helper utils in `lib/sessionShare.ts`. Share URLs use `/shared/sessions/:token`.
 - **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`.
+- **Account section:** `AccountLayout` has NO sidebar nav. New account pages: route under `account` children in `router.tsx` + link card in `AccountSettingsPage`.
- **Dashboard cockpit:** `QuickStartPage` is the copilot-first launchpad. Greeting + "What are you troubleshooting?" + ChatGPT-style `StartSessionInput` (auto-growing textarea, paste images, drag-drop files, attach button, paste logs, suggestion chips). Below: `PendingEscalations`, `ActiveFlowPilotSessions`, `RecentFlowPilotSessions`. Collapsible "Dashboard" section for `PerformanceCards`, `KnowledgeBaseCards`, `TeamSummary`.
+- **Dashboard cockpit:** `QuickStartPage` — `StartSessionInput` + `PendingEscalations`, `ActiveFlowPilotSessions`, `RecentFlowPilotSessions`. Collapsible section for `PerformanceCards`, `KnowledgeBaseCards`, `TeamSummary`.
- **Sidebar sections:** Amber "New Session" button → Home → RESOLVE (History) → KNOWLEDGE (Flows with Solutions Library sub-item, Scripts) → INSIGHTS (Data). Footer: Account, Pin/Unpin. No help/guides/feedback in sidebar — accessible via TopBar.
+- **Sidebar:** Amber "New Session" → Home → RESOLVE → KNOWLEDGE (Flows, Scripts) → INSIGHTS. Footer: Account, Pin/Unpin.
 ---
 ## Common Tasks
 - **New endpoint:** Create in `endpoints/` → add to `router.py` → schema in `schemas/` → tests → frontend API client
- **New page:** Create in `pages/` → add route in `router.tsx` → nav link in `AppLayout.tsx`
+- **New page:** Create in `pages/` → route in `router.tsx` → nav link in `AppLayout.tsx`
- **New public route (no auth):** Add at top level in `router.tsx` alongside `/login`, `/register` — NOT inside the `ProtectedRoute`/`AppLayout` children.
+- **New public route:** Add at top level in `router.tsx` (alongside `/login`) — NOT inside `ProtectedRoute`/`AppLayout`
- **Schema change:** Update model → `alembic revision --autogenerate -m "desc" --rev-id=NNN` (NNN = next sequential number, e.g., 068 → 069) → review → `alembic upgrade head`
+- **Schema change:** Update model → `alembic revision -m "desc"` (no `--rev-id`) → review → `alembic upgrade head`
 - **New frontend API module:** Types in `types/` → export from `types/index.ts` → client in `api/` → export from `api/index.ts`
 ---
@@ -440,80 +315,41 @@ cd backend && pip install httpx && python -m scripts.seed_trees
 ## Coding Standards
 ### Python
-
+Type hints everywhere, async/await for DB, Pydantic validation, `DateTime(timezone=True)` always.
 - Type hints everywhere, async/await for DB, Pydantic for validation, `DateTime(timezone=True)` always
 ### TypeScript
-
+Interfaces for all data, `const` over `let`, functional components + hooks.
 - Interfaces for all data, `const` over `let`, functional components + hooks, reusable logic in custom hooks
 ### Git
 - Format: `type: description` (feat, fix, refactor, docs, test, chore)
 - Always include `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`
- Always create feature branch BEFORE committing: `git checkout -b feat/feature-name`
+- Create feature branch BEFORE committing: `git checkout -b feat/feature-name`
- Large features: commit per phase with `npm run build` validation
+- **Remote is Gitea:** Push to `gitea.resolutionflow.com/chihlasm/resolutionflow`. Mirrors to GitHub via `.gitea/workflows/mirror-to-github.yml` — never push directly to GitHub.
 - **Remote is Gitea, not GitHub directly:** Push to `gitea.resolutionflow.com/chihlasm/resolutionflow`. Gitea auto-mirrors to GitHub via `.gitea/workflows/mirror-to-github.yml` — never push directly to GitHub.
 ### After Completing Work
-
+1. Update `CURRENT-STATE.md`
-When a feature, fix, or significant piece of work is finished and merged/committed:
+2. Update `03-DEVELOPMENT-ROADMAP.md`
-
+3. Close related GitHub Issues: `gh issue close #N`
-1. **Update `CURRENT-STATE.md`** — move completed items, update "In Progress" and "What's Next" sections
+4. Update `CLAUDE.md` if new patterns or lessons emerged
 2. **Update `03-DEVELOPMENT-ROADMAP.md`** — check off completed work, update phase status
 3. **Close related GitHub Issues** — use `gh issue close #N` for any issues resolved by the work
 4. **Update `CLAUDE.md`** if the work introduced new patterns, lessons learned, or changed project structure
 ---
 ## gstack (Browser & Workflow Skills)
-**Web browsing:** Always use the `/browse` skill from gstack for all web browsing needs. Never use `mcp__claude-in-chrome__*` tools.
+**Web browsing:** Always use `/browse`. Never use `mcp__claude-in-chrome__*` tools.
-**Available skills:**
+**Skills:** `/office-hours` · `/plan-ceo-review` · `/plan-eng-review` · `/plan-design-review` · `/design-consultation` · `/review` (PR review) · `/ship` · `/browse` (headless QA) · `/qa` (QA + fix) · `/qa-only` · `/design-review` (visual QA) · `/setup-browser-cookies` · `/retro` · `/investigate` · `/document-release` · `/codex` · `/careful` · `/freeze` · `/unfreeze` · `/guard` · `/gstack-upgrade`
 | Skill | Purpose |
 |-------|---------|
 | `/office-hours` | Brainstorm new ideas (YC-style office hours) |
 | `/plan-ceo-review` | CEO/founder-mode plan review (scope, ambition) |
 | `/plan-eng-review` | Engineering plan review (architecture, edge cases) |
 | `/plan-design-review` | Design plan review (UI/UX critique) |
 | `/design-consultation` | Create a design system / DESIGN.md |
 | `/review` | Pre-landing PR code review |
 | `/ship` | Ship workflow (tests, review, PR creation) |
 | `/browse` | Headless browser for QA testing and site dogfooding |
 | `/qa` | Systematic QA testing + auto-fix bugs found |
 | `/qa-only` | QA report only (no fixes) |
 | `/design-review` | Visual QA — find and fix design inconsistencies |
 | `/setup-browser-cookies` | Import cookies from real browser for authenticated testing |
 | `/retro` | Weekly engineering retrospective |
 | `/investigate` | Systematic debugging with root cause analysis |
 | `/document-release` | Post-ship documentation updates |
 | `/codex` | Second opinion via OpenAI Codex CLI |
 | `/careful` | Safety guardrails for destructive commands |
 | `/freeze` | Restrict edits to a specific directory |
 | `/guard` | Full safety mode (careful + freeze) |
 | `/unfreeze` | Remove edit restrictions |
 | `/gstack-upgrade` | Upgrade gstack to latest version |
 ---
 ## Deployment (Railway)
 - **Production:** `resolutionflow.com` (frontend), `api.resolutionflow.com` (backend)
- Auto-deploys via: push to Gitea → Gitea mirrors to GitHub → Railway watches GitHub `main` and deploys
+- Deploy pipeline: push to Gitea → mirrors to GitHub → Railway watches `main`
- PR environments auto-created (need manual domain generation in Railway dashboard)
+- PR envs: need manual domain generation + `VITE_API_URL` with `https://` prefix
 - PR envs need `VITE_API_URL` set with `https://` prefix on frontend service
 - `ALLOW_RAILWAY_ORIGINS=true` enables CORS for `*.up.railway.app`
- Shared Variables (project-level in Railway dashboard) auto-propagate to all environments including PR envs — use for secrets like `ANTHROPIC_API_KEY`
+- Shared Variables auto-propagate to all PR envs — use for `ANTHROPIC_API_KEY` etc.
- Super admin utility: `backend/make_superadmin_simple.py list|<email>`
+- Super admin: `backend/make_superadmin_simple.py list|<email>`
 ---
 ## Future Roadmap
 - **Phase 3:** PSA integrations (ConnectWise in progress), file attachments, client context, analytics
 - **Phase 4:** Additional PSA integrations (Autotask/Kaseya), PowerShell automation, enterprise SSO
 ---
@@ -521,13 +357,12 @@ When a feature, fix, or significant piece of work is finished and merged/committ
 | What | Where |
 |------|-------|
-| API Docs | <http://localhost:8000/api/docs> |
+| API Docs | http://localhost:8000/api/docs |
 | Detailed Status | [CURRENT-STATE.md](CURRENT-STATE.md) |
 | Development Roadmap | [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) |
 | GitHub Issues | `gh issue list --state open` |
 | Bugs & Fixes | CLAUDE.md → Critical Lessons Learned section |
 | Design System | [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) |
-| Dev Environment | [DEV-ENV.md](DEV-ENV.md) — 46.202.92.250 setup, Docker, CORS, networking |
+| Dev Environment | [DEV-ENV.md](DEV-ENV.md) — VPS setup, Docker, CORS, networking |
 <!-- gitnexus:start -->
--- a/1
+++ b/1
@@ -0,0 +1 @@
 0.1.0.0
--- a/docs/LESSONS-ARCHIVE.md
+++ b/docs/LESSONS-ARCHIVE.md
@@ -1,4 +1,4 @@
-# Lessons Archive (1-40)
+# Lessons Archive (1-70)
 > These lessons were originally in CLAUDE.md. They've been archived because the fixes are now baked into the codebase. Consult this file if you encounter a regression in any of these areas.
@@ -81,3 +81,67 @@
 **39. Platform settings for feature toggles:** Use `SettingsManager.get("key", db, default=True)`.
 **40. Survey public routes:** Add at top level in `router.tsx` alongside `/login`.
 ---
 ## Archived Lessons (41-70)
 **41. Assistant chat uses local React state, not Zustand:** `AssistantChatPage.tsx` uses `useState` for `chats`, `messages`, `input`, `loading`. No store.
 **42. Public pages use raw `fetch()`, not `apiClient`:** Survey, shared sessions, and no-auth pages use `fetch()` with full URL. `apiClient` requires auth tokens.
 **43. Adding new email types:** Add static async method to `EmailService` in `core/email.py`. Fire-and-forget from endpoints (log errors, don't fail).
 **44. AI Chat Builder is flow-type-aware:** `ai_chat_service.py` dispatches by `flow_type`. Troubleshooting: `[TREE_UPDATE]` markers. Procedural: `[STEPS_UPDATE]` markers. Both support `[METADATA]`.
 **45. Intake form field schema:** Uses `variable_name` and `field_type` (NOT `name` and `type`).
 **46. `CreateFlowDropdown` uses `AIPromptDialog`:** Opens prompt modal, starts AI session, generates flow, navigates to editor with `{ state: { aiPanelOpen: true, sessionId } }`.
 **47. Editor-Embedded Flow Assist:** `EditorAIPanel` (320px side panel) + `useEditorAI` hook. Ghost nodes use `_suggestion: true` flag. Delta responses use `[DELTA]...[/DELTA]` markers.
 **48. Tree orphan validation uses dynamic root ID:** Orphan check compares against `state.treeStructure?.id` (NOT hardcoded `'root'`).
 **49. Full-stack features — verify both ends:** schema → endpoint → API client → hook → store → UI.
 **50. Anthropic SDK retry:** Set `max_retries=1` to fail fast. Default `max_retries=2` can take 3× timeout.
 **51. AI model tier routing:** Use `settings.get_model_for_action(action_type)`. Model IDs: alias form (`claude-sonnet-4-6`).
 **52. Mobile scroll-to-top:** Use `ref.current.scrollIntoView()`, not `window.scrollTo()`. Trigger via `useEffect`.
 **53. Flex height chain:** Every ancestor must be a flex container for `flex-1` to work. Missing `flex` class collapses React Flow to 0 height.
 **54. React Flow CSS in Tailwind v4:** Import in `index.css`, not component JS. Override dark theme using `--xy-*` CSS custom properties.
 **55. App shell height chain:** Every wrapper between `.main-content` and canvas needs `flex` + `flex-1` + `min-h-0` or `h-full`.
 **56. Railway backend service name is `patherly`:** Production DB name is `railway`. Public Postgres proxy: `interchange.proxy.rlwy.net:45797`.
 **57. Node field priority:** `title` → `question` → `description` → `content` → `label`. See `copilot_service.py`.
 **58. `scriptGeneratorStore.generate()` optional param:** Always wrap: `onClick={() => generate()}`, never `onClick={generate}`.
 **59. ConnectWise `clientId` is server-side config:** Set in `config.py` as `CW_CLIENT_ID`. Per-connection: `company_id`, `public_key`, `private_key`, `server_url`.
 **60. Dockerfile build args for Vite env vars:** Any new `VITE_*` var must be added as `ARG` + `ENV` in `frontend/Dockerfile`. Railway env vars are runtime-only without this; `import.meta.env.VITE_*` resolves to `undefined` in production builds.
 **61. Procedural sessions auto-start on page load:** `ProceduralNavigationPage` calls `startSession()` immediately in `loadTree()` — no intake form screen or "Start" button. Variables filled inline. Troubleshooting flows DO have a start screen.
 **62. Playwright strict mode — scope selectors:** Step titles appear in both sidebar and main heading. Use `getByRole('heading', { name })` for main content.
 **63. Node 20 required for frontend builds:** `export NVM_DIR="$HOME/.nvm" && source "$NVM_DIR/nvm.sh" && nvm use 20`. Or: `PATH="$HOME/.nvm/versions/node/v20.19.0/bin:$PATH"`.
 **64. PostHog product analytics:** `PostHogProvider` in `main.tsx`. Event helpers in `lib/analytics.ts`. `identifyUser()` in `authStore.fetchUser()`, `resetAnalytics()` on logout. Env vars: `VITE_PUBLIC_POSTHOG_KEY`, `VITE_PUBLIC_POSTHOG_HOST`.
 **65. Local Docker Compose uses `resolutionflow` database on port 5433:** Container `resolutionflow_postgres`, DB `resolutionflow` (not `patherly`), port `5433`. Playwright config defaults must match.
 **66. Dev environment runs on Hostinger VPS (46.202.92.250):** CORS must include VPS IP in `CORS_ORIGINS` and `FRONTEND_URL`. See DEV-ENV.md.
 **67. Tree editor route is `/trees/new`:** NOT `/editor/new`. Use `getTreeEditorPath()` from `@/lib/routing`.
 **68. APScheduler jobs need `max_instances=1`:** Without it, overlapping runs can process the same records twice (TOCTOU race).
 **69. PostgreSQL `func.sum(case(...))` returns `Decimal` via asyncpg:** Cast to `int()` before storing in Pydantic `dict[str, Any]` fields.
 **70. Toast library uses `toast.warning()` not `toast.warn()`:** Import from `@/lib/toast`. Methods: `success`, `error`, `warning`, `info`.
--- a/docs/connectwise/CW_Security_Roles/README.md
+++ b/docs/connectwise/CW_Security_Roles/README.md
@@ -0,0 +1,63 @@
 # ConnectWise integration docs
 Reference material for ResolutionFlow's ConnectWise Manage integration.
 This folder pairs a **human-editable source** (the XLSX) with two
 **generated artifacts** (YAML + Markdown). Code reads the YAML; humans
 read the Markdown; edits happen in the XLSX.
 ## Files
 | File | Role | Edit? |
 |------|------|-------|
 | `api-member-security-roles.md` | Human-readable reference — browse on GitHub, link in PRs, onboard new contributors. | Generated — do not edit |
 | `api-member-security-roles.yaml` | Machine-readable source of truth — imported by integration code, queried by Claude Code when writing permission checks. | Generated — do not edit |
 | `source/Security_Roles_Matrix_11132017.xlsx` | Canonical source. The matrix as published by ConnectWise (with any corrections we've applied). | Yes — this is the editing surface |
 | `source/generate_role_docs.py` | Regenerates the YAML and Markdown from the XLSX. Deterministic. | Only if the matrix schema itself changes |
 | `source/requirements.txt` | Python deps for the generator (`openpyxl`, `PyYAML`). | Only when bumping deps |
 ## Regeneration workflow
 After editing the XLSX:
 ```bash
 cd docs/integrations/connectwise/source
 pip install -r requirements.txt
 python generate_role_docs.py \
    --source Security_Roles_Matrix_11132017.xlsx \
    --out-yaml ../api-member-security-roles.yaml \
    --out-md   ../api-member-security-roles.md
 ```
 Commit all three files together (XLSX, YAML, MD). The diff on the YAML
 is what reviewers should scrutinize — it is the source of truth for code.
 ## Querying the YAML from integration code
 The YAML groups permissions by module and action. Example — checking
 what `Inquire: ALL` means for Service Desk → Service Tickets:
 ```python
 import yaml
 from pathlib import Path
 doc = yaml.safe_load(
    Path("docs/integrations/connectwise/api-member-security-roles.yaml").read_text()
 )
 levels = doc["modules"]["Service Desk"]["actions"]["Service Tickets"]["inquire"]["levels"]
 print(levels["ALL"])
 ```
 This is the pattern `ConnectWiseAuthManager` and the proxy authorization
 layer should use when the required permission level for a given API
 endpoint needs to be documented or validated against an assigned role.
 ## Conventions
 - **Levels are ordered most-to-least privileged:** `ALL`, `MY`, `MINE`, `NONE`.
 - **Verbs are always in this order:** `add`, `edit`, `delete`, `inquire`.
 - **`Not applicable` notes** in a verb's cell mean the meaningful level
  is documented under another verb (almost always `inquire`) — the
  generator preserves these as `note:` fields rather than inventing
  placeholder levels.
 - **The XLSX is the single source of input.** Never hand-edit the YAML
  or Markdown; your changes will be overwritten on the next regeneration.
--- a/docs/connectwise/CW_Security_Roles/Security_Roles_Matrix_11132017.xlsx
+++ b/docs/connectwise/CW_Security_Roles/Security_Roles_Matrix_11132017.xlsx
--- a/docs/connectwise/CW_Security_Roles/api-member-security-roles.md
+++ b/docs/connectwise/CW_Security_Roles/api-member-security-roles.md
--- a/docs/connectwise/CW_Security_Roles/api-member-security-roles.yaml
+++ b/docs/connectwise/CW_Security_Roles/api-member-security-roles.yaml
--- a/docs/connectwise/CW_Security_Roles/generate_role_docs.py
+++ b/docs/connectwise/CW_Security_Roles/generate_role_docs.py
@@ -0,0 +1,361 @@
 """
 Generate ConnectWise security-role documentation from the source XLSX.
 Produces:
  - api-member-security-roles.yaml : machine-readable source of truth
  - api-member-security-roles.md   : human-readable reference
 Re-run this script after editing the source XLSX. Both outputs are
 deterministic — they will produce identical content from identical input,
 so diffs in version control reflect only real permission-model changes.
 Usage:
    python generate_role_docs.py \
        --source source/Security_Roles_Matrix_11132017.xlsx \
        --out-yaml ../api-member-security-roles.yaml \
        --out-md   ../api-member-security-roles.md
 """
 from __future__ import annotations
 import argparse
 import re
 from dataclasses import dataclass, field
 from datetime import date
 from pathlib import Path
 from typing import Dict, List, Optional
 import yaml
 from openpyxl import load_workbook
 # ---------------------------------------------------------------------------
 # Parsing
 # ---------------------------------------------------------------------------
 # A level description line looks like "ALL: text..." or "NONE: text..."
 # We capture the prefix (ALL | NONE | MINE | MY) and the trailing description.
 LEVEL_LINE = re.compile(r"^(ALL|NONE|MINE|MY)\s*:\s*(.*)$", re.DOTALL)
 # Recognized ConnectWise permission levels, most-to-least privileged.
 LEVEL_ORDER = ["ALL", "MY", "MINE", "NONE"]
 VERBS = ["add", "edit", "delete", "inquire"]
 VERB_COLS = {"add": 3, "edit": 4, "delete": 5, "inquire": 6}
@dataclass
 class CellPermission:
    """Parsed contents of a single (action, verb) cell."""
    levels: Dict[str, str] = field(default_factory=dict)  # level -> description
    note: Optional[str] = None  # for "Not applicable. See Inquire level." etc.
    raw: str = ""  # original cell text, preserved for audit
@dataclass
 class ActionRow:
    module: str
    action: str
    permissions: Dict[str, CellPermission]  # verb -> CellPermission
 def parse_cell(raw: Optional[str]) -> CellPermission:
    """Parse a single cell's multi-line content into levels + note."""
    if raw is None:
        return CellPermission(raw="")
    text = str(raw).strip()
    cp = CellPermission(raw=text)
    if not text:
        return cp
    # Split into candidate entries. Each entry is typically one line that
    # starts with a level prefix, but description text can itself contain
    # newlines. We therefore split on newlines and accumulate continuation
    # lines into the preceding entry.
    current_level: Optional[str] = None
    current_buf: List[str] = []
    note_buf: List[str] = []
    def flush_level() -> None:
        nonlocal current_level, current_buf
        if current_level is not None:
            cp.levels[current_level] = " ".join(current_buf).strip()
        current_level = None
        current_buf = []
    for line in text.splitlines():
        line = line.strip()
        if not line:
            continue
        m = LEVEL_LINE.match(line)
        if m:
            flush_level()
            current_level = m.group(1).upper()
            current_buf = [m.group(2).strip()]
        elif current_level is not None:
            current_buf.append(line)
        else:
            # No level prefix yet — belongs to the note.
            note_buf.append(line)
    flush_level()
    if note_buf:
        cp.note = " ".join(note_buf).strip()
    return cp
 def read_matrix(xlsx_path: Path) -> List[ActionRow]:
    wb = load_workbook(xlsx_path, data_only=True)
    ws = wb.active  # Single sheet in this workbook.
    # Header row is row 2 per the source file; data begins row 3.
    actions: List[ActionRow] = []
    for r in range(3, ws.max_row + 1):
        module = ws.cell(row=r, column=1).value
        action = ws.cell(row=r, column=2).value
        if not (module or action):
            continue  # skip fully empty rows
        if not module or not action:
            # Partial row — keep but flag. This shouldn't happen in the
            # current source; if it does, the generator should fail loudly
            # rather than silently produce wrong output.
            raise ValueError(
                f"Row {r} has a missing Module or Action: "
                f"module={module!r}, action={action!r}"
            )
        perms: Dict[str, CellPermission] = {}
        for verb, col in VERB_COLS.items():
            perms[verb] = parse_cell(ws.cell(row=r, column=col).value)
        actions.append(
            ActionRow(module=module.strip(), action=action.strip(), permissions=perms)
        )
    return actions
 # ---------------------------------------------------------------------------
 # Output: YAML
 # ---------------------------------------------------------------------------
 def build_yaml_document(actions: List[ActionRow], source_file: str) -> dict:
    """Build a plain-dict representation that YAML dumps cleanly."""
    # Group by module, preserving action order within each module.
    modules: Dict[str, List[ActionRow]] = {}
    for a in actions:
        modules.setdefault(a.module, []).append(a)
    doc = {
        "metadata": {
            "source_file": source_file,
            "generated_on": date.today().isoformat(),
            "generator": "docs/integrations/connectwise/source/generate_role_docs.py",
            "description": (
                "ConnectWise security-role matrix. Each (module, action) entry "
                "describes what each access level (ALL, MY, MINE, NONE) means "
                "for the Add, Edit, Delete, and Inquire verbs. This is a "
                "reference catalog, not a per-role assignment — role "
                "assignments live in ConnectWise and are mirrored in the "
                "ResolutionFlow integration config."
            ),
            "level_order_most_to_least_privileged": LEVEL_ORDER,
        },
        "modules": {},
    }
    for module_name, rows in modules.items():
        module_block = {"actions": {}}
        for a in rows:
            action_block: Dict[str, object] = {}
            for verb in VERBS:
                cell = a.permissions[verb]
                entry: Dict[str, object] = {}
                if cell.levels:
                    # Emit levels in canonical order, only those present.
                    entry["levels"] = {
                        lvl: cell.levels[lvl]
                        for lvl in LEVEL_ORDER
                        if lvl in cell.levels
                    }
                if cell.note:
                    entry["note"] = cell.note
                if not entry:
                    # Truly empty cell — represent explicitly so downstream
                    # consumers can distinguish "empty" from "missing".
                    entry["note"] = "(no description provided)"
                action_block[verb] = entry
            module_block["actions"][a.action] = action_block
        doc["modules"][module_name] = module_block
    return doc
 class _LiteralStr(str):
    """Marker type so PyYAML renders long strings as block literals."""
 def _literal_presenter(dumper, data):
    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
 yaml.add_representer(_LiteralStr, _literal_presenter)
 def _use_block_style_for_long_strings(obj):
    """Recursively wrap long strings so the YAML is readable, not one-line."""
    if isinstance(obj, dict):
        return {k: _use_block_style_for_long_strings(v) for k, v in obj.items()}
    if isinstance(obj, list):
        return [_use_block_style_for_long_strings(v) for v in obj]
    if isinstance(obj, str) and (len(obj) > 80 or "\n" in obj):
        return _LiteralStr(obj)
    return obj
 def dump_yaml(doc: dict, out_path: Path) -> None:
    prepared = _use_block_style_for_long_strings(doc)
    out_path.parent.mkdir(parents=True, exist_ok=True)
    with out_path.open("w", encoding="utf-8") as f:
        f.write("# ConnectWise API Member Security Roles — reference matrix.\n")
        f.write("# Generated from the source XLSX; do not edit by hand.\n")
        f.write("# Re-run generate_role_docs.py after updating the XLSX.\n\n")
        yaml.dump(
            prepared,
            f,
            sort_keys=False,
            allow_unicode=True,
            width=100,
            default_flow_style=False,
        )
 # ---------------------------------------------------------------------------
 # Output: Markdown
 # ---------------------------------------------------------------------------
 def _md_escape(text: str) -> str:
    """Escape pipes and collapse whitespace for Markdown table cells."""
    return text.replace("|", "\\|").replace("\n", " ").strip()
 def build_markdown(actions: List[ActionRow], source_file: str) -> str:
    modules: Dict[str, List[ActionRow]] = {}
    for a in actions:
        modules.setdefault(a.module, []).append(a)
    lines: List[str] = []
    lines.append("# ConnectWise API Member — Security Roles Reference")
    lines.append("")
    lines.append(
        f"_Generated {date.today().isoformat()} from "
        f"`{source_file}`. Do not edit by hand — update the XLSX and "
        f"re-run `generate_role_docs.py`._"
    )
    lines.append("")
    lines.append("## How to read this document")
    lines.append("")
    lines.append(
        "Each ConnectWise module lists the actions it governs. For every "
        "action, four permission verbs — **Add**, **Edit**, **Delete**, "
        "**Inquire** — can be granted at one of these levels, most to "
        "least privileged:"
    )
    lines.append("")
    lines.append("| Level | Meaning |")
    lines.append("|-------|---------|")
    lines.append("| `ALL` | Access to all records in the system. |")
    lines.append("| `MY` | Access to records owned by the user's team. |")
    lines.append("| `MINE` | Access only to records owned by the user. |")
    lines.append("| `NONE` | No access. |")
    lines.append("")
    lines.append(
        "Not every level applies to every action — the source matrix "
        "only documents the levels that are meaningful for each cell. "
        "Cells marked _Not applicable_ reference another verb (usually "
        "Inquire) where the meaningful level is defined."
    )
    lines.append("")
    lines.append(
        "The machine-readable form of this document is "
        "[`api-member-security-roles.yaml`](./api-member-security-roles.yaml). "
        "Use the YAML when writing integration code; use this Markdown "
        "when reviewing, discussing, or onboarding."
    )
    lines.append("")
    lines.append("## Table of contents")
    lines.append("")
    for module_name in modules:
        anchor = module_name.lower().replace(" ", "-").replace("/", "")
        lines.append(f"- [{module_name}](#{anchor}) — {len(modules[module_name])} actions")
    lines.append("")
    for module_name, rows in modules.items():
        lines.append(f"## {module_name}")
        lines.append("")
        for a in rows:
            lines.append(f"### {a.action}")
            lines.append("")
            lines.append("| Verb | Level | Description |")
            lines.append("|------|-------|-------------|")
            wrote_any = False
            for verb in VERBS:
                cell = a.permissions[verb]
                if cell.levels:
                    for lvl in LEVEL_ORDER:
                        if lvl in cell.levels:
                            lines.append(
                                f"| {verb.capitalize()} | `{lvl}` | "
                                f"{_md_escape(cell.levels[lvl])} |"
                            )
                            wrote_any = True
                elif cell.note:
                    lines.append(
                        f"| {verb.capitalize()} | — | "
                        f"_{_md_escape(cell.note)}_ |"
                    )
                    wrote_any = True
            if not wrote_any:
                lines.append("| — | — | _(no description provided)_ |")
            lines.append("")
    return "\n".join(lines) + "\n"
 def write_markdown(md_text: str, out_path: Path) -> None:
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text(md_text, encoding="utf-8")
 # ---------------------------------------------------------------------------
 # Entry point
 # ---------------------------------------------------------------------------
 def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--source", type=Path, required=True,
                        help="Path to the source .xlsx")
    parser.add_argument("--out-yaml", type=Path, required=True,
                        help="Path to write the YAML output")
    parser.add_argument("--out-md", type=Path, required=True,
                        help="Path to write the Markdown output")
    args = parser.parse_args()
    actions = read_matrix(args.source)
    doc = build_yaml_document(actions, source_file=args.source.name)
    dump_yaml(doc, args.out_yaml)
    md = build_markdown(actions, source_file=args.source.name)
    write_markdown(md, args.out_md)
    # Quick data-quality summary to stdout — helpful when re-running after edits.
    from collections import Counter
    modules_seen = Counter(a.module for a in actions)
    print(f"Parsed {len(actions)} actions across {len(modules_seen)} modules:")
    for m, n in modules_seen.most_common():
        print(f"  {m}: {n}")
    print(f"\nWrote {args.out_yaml}")
    print(f"Wrote {args.out_md}")
 if __name__ == "__main__":
    main()
--- a/docs/connectwise/CW_Security_Roles/requirements.txt
+++ b/docs/connectwise/CW_Security_Roles/requirements.txt
@@ -0,0 +1,5 @@
 # Dependencies for generate_role_docs.py.
 # These are only needed when regenerating the role docs from the XLSX —
 # they are not runtime dependencies of ResolutionFlow itself.
 openpyxl>=3.1,<4.0
 PyYAML>=6.0,<7.0
--- a/docs/superpowers/plans/2026-04-16-psa-ticket-management.md
+++ b/docs/superpowers/plans/2026-04-16-psa-ticket-management.md