chore: snapshot CLAUDE.md before ai-handoff migration

Root cause of the 06:32 AM outage: running 'pytest tests/' inside the
resolutionflow_backend container silently dropped the public schema on
the DEV database. Two layered bugs made this possible; both are fixed.

Bug 1 — env-var lookup in conftest.TEST_DATABASE_URL put DATABASE_URL
(which normally points at the dev/prod DB) ahead of DATABASE_TEST_URL.
When DATABASE_URL is set, pytest used the dev DB as the 'test' DB and
the test_db fixture's DROP SCHEMA public CASCADE wiped it. Fixed:
  - Honor only DATABASE_TEST_URL (or the localhost fallback).
  - Assert at module load that the DB name contains 'test' — refuses
    to run otherwise. Makes future misconfiguration impossible.

Bug 2 — conftest overrode app.dependency_overrides[get_db] but not
get_admin_db. Endpoints using get_admin_db (register, admin routes)
bypassed the test session and hit the real admin DB. Before Bug 1 was
fixed this was hidden because both engines pointed at the same dev DB.
With isolation in place, register started failing 'Email already
registered' because of stale users in the dev DB. Fixed:
  - Also override get_admin_db to yield the same test session. RLS is
    not enabled in the create_all-managed test schema, so sharing is
    safe.

Also adds DATABASE_TEST_URL=resolutionflow_test to docker-compose.dev.yml
so pytest in the container works out of the box.

Verified: 49/50 Phase 8 + 9 tests pass against resolutionflow_test; the
1 failure is the pre-existing Phase 8 Issue #4
(test_record_decision_persists_and_bumps_state_version).

Refs gitea #145 (will update that issue with this as the primary fix).

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

.gitea/workflows/ci.yml

@@ -0,0 +1,154 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: resolutionflow_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      DATABASE_URL: postgresql+asyncpg://postgres:postgres@postgres:5432/resolutionflow_test
+      DATABASE_URL_SYNC: postgresql://postgres:postgres@postgres:5432/resolutionflow_test
+      SECRET_KEY: ci-test-secret-key-not-for-production
+      DEBUG: "true"
+      APP_NAME: ResolutionFlow
+      TEST_DB_NAME: resolutionflow_test
+      DB_APP_ROLE_PASSWORD: app_secret_ci
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: pip install --break-system-packages -r backend/requirements.txt -r backend/requirements-dev.txt
+
+      - name: Run Alembic migrations
+        run: cd backend && alembic upgrade head
+
+      - name: Check tenant filter enforcement
+        run: cd backend && python scripts/check_tenant_filters.py
+
+      - name: Run tests with coverage
+        run: cd backend && python -m pytest --override-ini="addopts=" --cov=app --cov-report=term-missing --cov-report=json:coverage.json --cov-fail-under=50
+
+      - name: Display coverage summary
+        if: always()
+        run: |
+          cd backend
+          python -c "
+          import json
+          with open('coverage.json') as f:
+              data = json.load(f)
+          total = data['totals']['percent_covered_display']
+          print(f'Total coverage: {total}%')
+          print()
+          print('Module coverage:')
+          for fname, fdata in sorted(data['files'].items()):
+              pct = fdata['summary']['percent_covered_display']
+              if float(pct) < 80:
+                  print(f'  WARNING {fname}: {pct}%')
+              else:
+                  print(f'  OK {fname}: {pct}%')
+          "
+
+  frontend:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: cd frontend && npm ci
+
+      - name: Lint
+        run: cd frontend && npm run lint
+
+      - name: Test with coverage
+        run: cd frontend && npm run test:coverage
+
+      - name: Build
+        run: cd frontend && NODE_OPTIONS="--max-old-space-size=4096" npm run build
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: frontend-dist
+          path: frontend/dist
+          retention-days: 1
+
+  e2e:
+    needs: [frontend]
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: resolutionflow_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      PLAYWRIGHT_DATABASE_URL: postgresql+asyncpg://postgres:postgres@postgres:5432/resolutionflow_test
+      PLAYWRIGHT_DATABASE_URL_SYNC: postgresql://postgres:postgres@postgres:5432/resolutionflow_test
+      PLAYWRIGHT_API_ORIGIN: http://127.0.0.1:8000
+      PLAYWRIGHT_BASE_URL: http://127.0.0.1:4173
+      PLAYWRIGHT_SECRET_KEY: ci-playwright-secret-key
+      PLAYWRIGHT_TEST_EMAIL: teamadmin@resolutionflow.example.com
+      PLAYWRIGHT_TEST_PASSWORD: TestPass123!
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install backend dependencies
+        run: pip install --break-system-packages -r backend/requirements.txt -r backend/requirements-dev.txt
+
+      - name: Install frontend dependencies
+        run: cd frontend && npm ci
+
+      - name: Download frontend build
+        uses: actions/download-artifact@v4
+        with:
+          name: frontend-dist
+          path: frontend/dist
+
+      - name: Install Playwright browser
+        run: cd frontend && npx playwright install --with-deps chromium
+
+      - name: Run Playwright smoke tests
+        run: cd frontend && npm run test:e2e
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: |
+            frontend/playwright-report
+            frontend/test-results
+          if-no-files-found: ignore

.gitea/workflows/mirror-to-github.yml

@@ -0,0 +1,19 @@
+name: Mirror to GitHub
+
+on:
+  push:
+    branches:
+      - '**'
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Push to GitHub
+        run: |
+          cd /tmp
+          git clone --mirror https://gitea.resolutionflow.com/chihlasm/resolutionflow.git repo
+          cd repo
+          git remote add github https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${{ secrets.GH_MIRROR_REPO }}
+          git push github --all --force
+          git push github --tags --force

.gitea/workflows/runner-probe.yml

@@ -0,0 +1,43 @@
+name: Runner Probe
+
+on:
+  workflow_dispatch:
+
+jobs:
+  probe:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Runner labels and OS
+        run: |
+          echo "=== OS ==="
+          uname -a
+          cat /etc/os-release 2>/dev/null || true
+
+      - name: Python versions
+        run: |
+          echo "=== Python ==="
+          which python3 && python3 --version || echo "python3 not found"
+          which python && python --version || echo "python not found"
+          ls /usr/bin/python* 2>/dev/null || true
+
+      - name: Node versions
+        run: |
+          echo "=== Node ==="
+          which node && node --version || echo "node not found"
+          which npm && npm --version || echo "npm not found"
+          ls /usr/bin/node* 2>/dev/null || true
+          ls ~/.nvm/versions/node/ 2>/dev/null || echo "no nvm versions"
+
+      - name: Docker
+        run: |
+          echo "=== Docker ==="
+          which docker && docker --version || echo "docker not found"
+          docker info 2>/dev/null | grep -E "Server Version|Operating System" || true
+
+      - name: User and home
+        run: |
+          echo "=== User ==="
+          whoami
+          echo "HOME=$HOME"
+          echo "PATH=$PATH"

.github/workflows/ci.yml

@@ -31,6 +31,8 @@ jobs:
       SECRET_KEY: ci-test-secret-key-not-for-production
       DEBUG: "true"
       APP_NAME: ResolutionFlow
+      TEST_DB_NAME: resolutionflow_test
+      DB_APP_ROLE_PASSWORD: app_secret_ci
 
     steps:
       - uses: actions/checkout@v5
@@ -47,6 +49,14 @@ jobs:
       - name: Install dependencies
         run: pip install -r backend/requirements.txt -r backend/requirements-dev.txt
 
+      - name: Run Alembic migrations
+        run: cd backend && alembic upgrade head
+
+      - name: Check tenant filter enforcement
+        run: cd backend && python scripts/check_tenant_filters.py
+        # Warn mode only (exits 0). Switch to --fail after Phase 1 backlog clears.
+        # See: docs/superpowers/specs/2026-04-09-tenant-data-isolation-design.md Section 3f
+
       - name: Run tests with coverage
         run: cd backend && python -m pytest --override-ini="addopts=" --cov=app --cov-report=term-missing --cov-report=json:coverage.json --cov-fail-under=50
 

.gitignore

@@ -233,3 +233,8 @@ package.json
 package-lock.json
 .worktrees/
 .gstack/
+.gitnexus
+
+# graphify knowledge graph outputs
+graphify-out/
+.graphify_python

CHANGELOG.md

@@ -4,37 +4,47 @@ All notable changes to ResolutionFlow are documented here.
 
 ## [Unreleased]
 
-## [2026-04-04] Network Diagram Editor UX Improvements
-
-### Added
-- Snap-to-grid (20px) on Network Diagram canvas — nodes align consistently when dragged
-- NodeResizer on group nodes (subnet/VLAN/site/DMZ) — select a group and drag its handles to resize
-- Group node dimensions now saved to and restored from the backend on reload
-
-### Fixed
-- Connection edges now render as straight lines instead of orthogonal bent paths
-- ISP device now appears inside the Cloud category in the sidebar instead of a standalone "Internet" section; respects search and item count
-- Group nodes now restore correctly as `type: 'group'` on diagram load (previously loaded as `type: 'device'`, breaking group display after save)
-
----
-
 ### Added
 - Tree Templates + Import/Export marketplace (#66)
 - Recurring Issue Detection — client-specific pattern alerts (#60)
 - Step Feedback Flag — "This Step is Wrong" reporting (#58)
+- **Tenant Isolation Phase 0** — multi-tenant data isolation (#132) with app-layer filtering helpers (`tenant_filter()`, `get_tenant_context`), cross-tenant access audit (analytics, categories, AI sessions, trees), UUID endpoint isolation with 404 responses for unauthorized access, ownership checks on all sensitive operations, and CI grep gate for missing tenant filters
+- **Tenant Isolation Phase 2** — PostgreSQL Row Level Security (RLS) on 11 session-related tables (ai_sessions, session_steps, session_tags, etc.), account_id NOT NULL enforcement on all write paths, Alembic migrations with dual-env support (Railway native vars + explicit DATABASE_URL_SYNC), RLS test coverage with cross-account isolation verification, migration CI/CD integration
+- **Tenant Isolation Phase 3** — RLS on audit_logs and tree_shares tables, cross-tenant session access for public shares (via get_admin_db), complete account_id propagation across PSA integration write paths, final RLS policy enforcement
+- **Tenant Isolation Phase 4** (#136) — RLS enforcement on all 31 remaining tables (users, trees, teams, integrations, scripts, categories, templates, surveys, etc.), BYPASSRLS session pattern for auth deps and background jobs, admin session factory for startup routines (service accounts, seed data), global table exclusions (platform_steps, template_trees, script_categories, accounts), RLS tests with complete cross-tenant isolation verification, proper tree_shares ownership checks using tree owner's account_id
 - **Script Library default view** — "All Scripts" tab now displays all accessible scripts (team + library)
+- **Session documentation overhaul** — reformatted PSA resolution/escalation notes with cleaner headers, inline engineer responses, decimal hour display (0.25 hrs), follow-up recommendations, and improved "What We Know" section from evidence items
+- **Client communication improvements** — new `request_info` audience type for client-facing information requests, improved status update and email draft prompts with per-context guidance
+- **Image support in Assistant Chat** — paste/attach images in chat input, uploaded to S3, resized for vision model, displayed in conversation history
 
 ### Changed
 - **Edit Procedure page** — layout overhaul and color system refinements for better visual hierarchy
 - **Flows sidebar navigation** — collapsed to reduce visual noise; session recovery removed from library view
 - **Account settings page** — audit fixes for improved consistency and usability
+- **PSA documentation formatting** — removed duplicate timing blocks and AI confidence sections; added client-facing communication context guidance
+- **Status update generation** — fixed option label lookup to use human-readable labels instead of machine values
+- **Assistant Chat session actions** — moved Pause/Resume/Close actions from action bar to page header for consistency with FlowPilot
+- **Design system token normalization** — unified FlowPilot, AssistantChat, and ScriptBuilder components to use consistent design tokens
+- **Tenant data boundaries** — all session and tree endpoints now return 404 (not 403) for cross-tenant access attempts to avoid confirming resource existence
 
 ### Fixed
+- **CRITICAL: Copilot tree query isolation** (#131) — user could access any tree UUID if known, exposing full tree structure to AI. Now scoped to current account with 404 for inaccessible trees.
+- **AI session search isolation** — search endpoint leaked other users' sessions via OR(user_id, account_id). Now restricted to current user only.
+- **Analytics endpoint isolation** — GET `/analytics/flows/{tree_id}` exposed session counts for any tree UUID. Now returns 404 if tree doesn't belong to requesting account.
+- **Category tree counts** — cross-tenant row count leakage via tree_count field in GET `/categories/{id}`. Now scoped to requesting account.
+- **PSA retry ownership check** — retry-psa-push had no ownership validation (CRITICAL). Now validates user ownership before allowing retry.
+- **Task Lane save operation** — invalid task_lane_item UUIDs returned 403 revealing existence. Now returns 404 and uses query-level filtering.
+- **Phase 4 RLS enforcement** — fixed auth deps, user-mutation endpoints, background jobs, and lifespan routines to use BYPASSRLS sessions for reading/writing tenant-isolated tables; fixed seed scripts to use ADMIN_DATABASE_URL; bootstrap service account now initializes correctly with proper BYPASSRLS context
 - Dark text rendering on blue accent step-number badges across all flow types
 - Script Library tab ownership filter now preserved across category and search changes
 - Race conditions in script builder session creation and slug generation
 - Stale async results in Assistant Chat (selectChat) no longer clobber new session task lane
 - Sentry DSN hardcoded fallback removed — now uses environment variable only
+- Option label resolution in status update context generation
+- "Sorry something went wrong" errors in chat when rendering unsupported message types
+- Task Lane stale data when creating new chat or resuming from concluded session
+- Chat ref invalidation race condition between handleNewChat and async data loads
+- Images now properly display in chat message history instead of blank placeholders
 
 ---
 

CLAUDE.md

@@ -1,520 +1,265 @@
-# CLAUDE.md - Patherly / ResolutionFlow Project Context
+# CLAUDE.md — ResolutionFlow
 
-> **Last Updated:** March 27, 2026
+> SaaS troubleshooting platform for MSPs. Last reviewed 2026-04-19.
+
+**Naming:** Canonical product name is **ResolutionFlow**. `patherly` is the legacy internal name — still present in DB name (`patherly` on Railway, `resolutionflow` locally), some Railway service names, and historical paths. Treat as aliases, not canonical. Docker containers are `resolutionflow_*`.
+
+**User terminology:** "Flows" (not Trees), "Projects" (not Procedures), "Solutions Library" (not Step Library). Maintenance flows hidden from pilot UI (backend retains them). DB column `tree_type` values unchanged.
+
+**SaaS shape:** Multi-tenant by account. Roles: `super_admin` > `team_admin` > `engineer` > `viewer`. Team admin = `role='engineer'` + `is_team_admin=True` + valid `team_id`. Never `role=='admin'` — use `is_super_admin`. Backend deps in `app/api/deps.py`: `get_current_active_user`, `require_engineer_or_admin`, `require_admin`. Frontend: `usePermissions()` hook. Central logic in `backend/app/core/permissions.py` + `frontend/src/hooks/usePermissions.ts`.
+
+**Status:** Go-to-Market Validation (pre-PMF). Backend feature-complete (55+ endpoints, 100+ tests). Phase 0.5 FlowPilot telemetry baseline accruing. See `CURRENT-STATE.md` for live status, `03-DEVELOPMENT-ROADMAP.md` for phases.
+
+**Principle:** Prefer correct architecture over minimal diff. Flag "simpler approach" tradeoffs for review before taking them.
 
 ---
 
-## Project Overview
+## Tech stack
 
-**Patherly** (user-facing brand: **ResolutionFlow**) is a **SaaS product for MSP professionals**. It provides troubleshooting decision trees that guide engineers through proven troubleshooting paths, capture decisions and notes, and generate professional ticket documentation.
-
-**Target Market:** MSP companies — IT service providers managing infrastructure and support for multiple clients.
-
-**SaaS Context:** Multi-tenant design — teams represent MSP companies, trees shared within teams, tiered access (super_admin, team_admin, engineer, viewer).
-
-### Branding
-
-| Context | Name Used |
-|---------|-----------|
-| Repository / directory / database / Docker | `patherly` / `patherly_postgres` |
-| 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.
-- **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
-- If two approaches exist, implement the one that scales, not the one that's faster to write
-- Flag any "simpler approach" tradeoffs for product owner review before proceeding
+- **Backend:** Python 3.11 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan).
+- **Frontend:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config in `index.css`), Zustand (immer + zundo), React Router v7, Axios (token-refresh interceptor), Lucide.
+- **DB:** PostgreSQL 16 (RLS enabled Phase 4, pgvector).
 
 ---
 
-## Current State
-
-- **Phase:** Go-to-Market Validation (Pre-PMF)
-- **Backend:** Complete (55+ API endpoints, 100+ integration tests)
-- **Frontend:** Core features complete, Tree Editor functional
-- **Database:** PostgreSQL with Docker, 98 migrations
-- **Detailed status:** [CURRENT-STATE.md](CURRENT-STATE.md)
-
-### What's In Progress
-
-- GTM validation: Shadow & Ship — founder dogfooding for 2 weeks, then 5 colleague pilot
-- Solutions Library spec written (`docs/plans/2026-03-23-solutions-library-design.md`), implementation post-pilot
-- Remaining open issues: #66 Templates + Import/Export, #60 Recurring Issue Detection, #58 Step Feedback Flag
-
----
-
-## Tech Stack
-
-### Backend
-
-- **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
-
-- **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
-
----
-
-## Key Project Structure
+## Project structure
 
 ```
-patherly/
+resolutionflow/
 ├── backend/
 │   ├── app/
-│   │   ├── main.py                 # FastAPI entry point
-│   │   ├── api/endpoints/          # Route handlers (auth, trees, sessions, admin, steps, survey, copilot, assistant_chat, integrations)
-│   │   │   ├── flow_proposals.py   # Knowledge Flywheel review queue CRUD
-│   │   │   └── flowpilot_analytics.py # FlowPilot dashboard metrics
-│   │   ├── api/deps.py             # Auth dependencies (includes require_team_admin)
-│   │   ├── api/router.py           # Route registration
-│   │   ├── core/                   # config, database, permissions, security, audit, rate_limit
-│   │   ├── models/                 # SQLAlchemy models (includes FlowProposal)
-│   │   ├── schemas/                # Pydantic schemas
-│   │   ├── services/psa/           # PSA provider abstraction (base, connectwise/, autotask/, halopsa/, cache, encryption, registry, types)
-│   │   ├── services/knowledge_flywheel.py        # AI session analysis → flow proposals
-│   │   ├── services/knowledge_flywheel_scheduler.py # APScheduler job for batch analysis
-│   │   └── services/knowledge_gap_service.py     # Weak options & escalation signal detection
-│   ├── alembic/                    # Database migrations (001-029+)
-│   ├── scripts/                    # seed_data.py, seed_trees.py
-│   └── tests/                      # pytest integration tests
+│   │   ├── main.py                     # FastAPI entry
+│   │   ├── api/endpoints/              # auth, trees, sessions, admin, steps, survey, copilot, assistant_chat, integrations, flow_proposals, flowpilot_analytics
+│   │   ├── api/deps.py                 # auth deps (incl. require_team_admin)
+│   │   ├── api/router.py               # registration
+│   │   ├── core/                       # config, database, permissions, security, audit, rate_limit
+│   │   ├── models/                     # SQLAlchemy (incl. FlowProposal)
+│   │   ├── schemas/                    # Pydantic
+│   │   ├── services/psa/               # PSA provider pattern (base, connectwise/, autotask/, halopsa/, cache, encryption, registry, types)
+│   │   ├── services/knowledge_flywheel.py + _scheduler.py
+│   │   └── services/knowledge_gap_service.py
+│   ├── alembic/versions/               # 001-070 sequential, then hex hash
+│   ├── scripts/                        # seed_data, seed_trees, seed_test_users
+│   └── tests/                          # pytest integration
 ├── 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
+│   │   ├── 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/
+│   │   ├── store/                      # Zustand (auth, treeEditor, proceduralEditor, userPreferences, scriptGeneratorStore)
+│   │   └── types/
+│   └── (Tailwind v4 CSS-only config in src/index.css)
+├── docs/plans/archive/                 # pre-March 2026 plans
+├── docs/connectwise/                   # CW API reference + best-practices guides
+├── docs/LESSONS-ARCHIVE.md             # archived lessons (fixes in code)
+├── CLAUDE.md · CURRENT-STATE.md · DESIGN-SYSTEM.md · DEV-ENV.md
 ```
 
 ---
 
-## Environment Variables
+## Design system
 
-### Backend (`backend/.env`)
+**Source of truth: [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md).** Read before any visual change.
+
+- Flat high-contrast dark theme, Sentry/PostHog-inspired. **No** glass, backdrop blur, ambient orbs, gradient surfaces.
+- Accent **electric blue** (#60a5fa dark / #2563eb light) — ≤5% of UI, interactive elements only. Warning amber (#fbbf24), info cyan (#67e8f9), success green (#34d399), danger red (#f87171). Each with `-dim` at 10% opacity.
+- Backgrounds: `bg-sidebar` (#0e1016) → `bg-page` (#16181f) → `bg-card` (#1e2028) → `bg-elevated` (#2a2d38). Borders `border-default` / `border-hover`.
+- Text: `text-heading` → `text-primary` → `text-muted-foreground` → `text-muted`.
+- Fonts: IBM Plex Sans (body), Bricolage Grotesque (heading, 700 weight for logo), JetBrains Mono (code).
+- Logo: 30px gradient square (ember orange) + "ResolutionFlow" in Bricolage Grotesque. Assets in `brand-assets/`, `frontend/src/assets/brand/`, `frontend/public/icons/`.
+- Mockups: `docs/mockups/` (HTML).
+- **Deprecated — do not use:** glass-card, glass-stat, `bg-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, purple gradients, ember orange as accent, cyan as accent (cyan is info only).
+
+---
+
+## ConnectWise PSA
+
+Reference: `docs/connectwise/` — start with `CONNECTWISE-API-REFERENCE.md`, then the `best-practices/` guides. Extracted OpenAPI spec in `connectwise-psa-resolutionflow-reference.json` (670 endpoints, v2025.16); full spec in `connectwise-psa-openapi-full.json`.
+
+- **Auth:** API Key (Base64 `companyId+publicKey:privateKey`) + `clientId` header every request. `clientId` is server-side (`CW_CLIENT_ID` in `config.py`) — identifies ResolutionFlow, not per-tenant. Per-connection: `company_id`, `public_key`, `private_key`, `server_url`.
+- **Architecture:** `services/psa/` provider pattern — `PSAProvider` base, `ConnectWiseProvider` impl, `PsaProviderRegistry` for multi-PSA dispatch. Credentials encrypted at rest via `services/psa/encryption.py` (Fernet). Per-team credentials, never per-user. Endpoints in `api/endpoints/integrations.py`. In-memory TTL cache in `services/psa/cache.py`.
+- **Integration flows:** session docs → ticket notes (`POST /service/tickets/{id}/notes`, markdown supported); ticket context → FlowPilot; callbacks via `/system/callbacks` with HMAC verification.
+- **API rules:** pin version via Accept header `application/vnd.connectwise.com+json; version=2025.16`. Paginate ≤1000/page. Dynamic base URL via `/login/companyinfo/{companyId}`. Request minimal permissions (MY, not ALL).
+
+---
+
+## Dev commands
+
+Full setup in [DEV-ENV.md](DEV-ENV.md) (host-agnostic, with homelab Proxmox reference topology). Day-to-day:
 
 ```bash
-APP_NAME=ResolutionFlow
-DEBUG=true
-DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/patherly
-DATABASE_URL_SYNC=postgresql://postgres:postgres@localhost:5432/patherly
-SECRET_KEY=<openssl rand -hex 32>
-ACCESS_TOKEN_EXPIRE_MINUTES=5
-REFRESH_TOKEN_EXPIRE_DAYS=7
-REQUIRE_INVITE_CODE=true
+docker compose -f docker-compose.dev.yml up -d                      # start stack
+cd backend && source venv/bin/activate && uvicorn app.main:app --reload
+cd frontend && npm run dev
+pytest --override-ini="addopts="                                    # tests (first time: CREATE DATABASE resolutionflow_test)
+cd backend && alembic upgrade head                                  # migrate
+cd backend && alembic revision -m "desc"                            # manual migration (preferred per Lesson 77)
+cd backend && alembic revision --autogenerate -m "desc"             # picks up drift; review carefully
+cd frontend && npm run build                                        # stricter than tsc --noEmit — final check
+cd frontend && npx tsc -b                                           # TS-only check when dist/ has EACCES
+docker exec -it resolutionflow_postgres psql -U postgres -d resolutionflow
+python -m scripts.seed_trees                                        # seed (from backend/)
 ```
 
-### Frontend (`frontend/.env.local` - optional)
+**URLs:** Frontend <http://localhost:5173>, backend <http://localhost:8000>, API docs <http://localhost:8000/api/docs>.
 
-```bash
-VITE_API_URL=http://localhost:8000
-```
+**Test users** (all password `TestPass123!`): `admin@resolutionflow.example.com` (super_admin), `teamadmin@resolutionflow.example.com`, `engineer@resolutionflow.example.com`, `pro@resolutionflow.example.com`.
+
+**CI:** Gitea (`gitea.resolutionflow.com/chihlasm/resolutionflow/actions`). `gh` CLI works for issues/PRs on the GitHub mirror, but not CI runs.
+
+**Never pass `--rev-id`** to alembic — let it generate the hex hash.
 
 ---
 
-## ConnectWise PSA Integration
+## Common tasks
 
-ResolutionFlow integrates with ConnectWise PSA (formerly Manage) as the primary PSA integration. All ConnectWise API reference materials live in `docs/connectwise/`.
-
-### Best Practices Documentation
-
-Official ConnectWise developer guides live in `docs/connectwise/best-practices/`. Read these 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-Callbacks.md` — Callback type/level matrix, retry behavior, URL parameter gotcha, HMAC signature verification.
-- `PSA-Pagination.md` — Navigable vs Forward-Only pagination, Link headers, while-loop pattern.
-- `PSA-Service-Tickets.md` — Ticket field philosophy, recommended field mappings.
-- `PSA-Versioning.md` — Pin API version via Accept header. Use `application/vnd.connectwise.com+json; version=2025.16`.
-- `PSA-Cloud-URL-Formatting.md` — Dynamic base URL construction via `/login/companyinfo/{companyId}`.
-- `Bundled-Requests.md` — Batch multiple API calls into one request via `/system/bundles`.
-- `PSA-Markdown.md` — Ticket notes support markdown. Format session documentation output accordingly.
-- `PSA-Company-Synchronization.md` — Filter companies by Status/Type for mapping UI.
-- `PSA-Data-Protection.md` — Security role model, 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.
-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.
-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.
-
-### 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`
-- All PSA integration code in `services/psa/` — provider pattern with `PSAProvider` abstract base class, `ConnectWiseProvider` implementation, `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)
-- 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
+- **New endpoint:** `endpoints/` → `router.py` → `schemas/` → tests → frontend API client.
+- **New page:** `pages/` → route in `router.tsx` → nav in `AppLayout.tsx`.
+- **New public route:** top-level in `router.tsx` alongside `/login`, not inside `ProtectedRoute`.
+- **New frontend API module:** types in `types/` → export from `types/index.ts` → client in `api/` → export from `api/index.ts`.
+- **Schema change:** update model → `alembic revision -m "desc"` → review → `alembic upgrade head`.
+- **New `VITE_*` env var:** add as `ARG` + `ENV` in `frontend/Dockerfile` for Railway builds (Lesson 60 — Railway env vars are runtime-only, Vite bakes at build time).
+- **Account sub-page:** add route in `router.tsx` under `account` children + add link card in `AccountSettingsPage.tsx` — `AccountLayout` has NO sidebar nav.
 
 ---
 
-## Development Commands
+## Coding standards
 
-```powershell
-# Start PostgreSQL
-docker start patherly_postgres
+- **Python:** type hints everywhere, async/await for DB, Pydantic v2, `DateTime(timezone=True)` always.
+- **TypeScript:** interfaces for all data, `const` over `let`, functional components + hooks, shared logic in custom hooks.
+- **Git:** feature branch before committing (`git checkout -b feat/feature-name`). Format: `type: description` (feat/fix/refactor/docs/test/chore). Always `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`. Large features: commit per phase with `npm run build` validation. Push to Gitea — auto-mirrors to GitHub (`.gitea/workflows/mirror-to-github.yml`); never push GitHub directly.
 
-# Backend (from backend/)
-source venv/bin/activate        # Linux/Mac
-# .\venv\Scripts\Activate       # Windows
-uvicorn app.main:app --reload
-
-# Frontend (from frontend/)
-npm run dev
-
-# Run tests (from backend/)
-pytest --override-ini="addopts="
-
-# First time only: create test database
-docker exec -it patherly_postgres psql -U postgres -c "CREATE DATABASE patherly_test;"
-
-# Frontend build (IMPORTANT: stricter than tsc --noEmit — always use as final check)
-cd frontend && npm run build
-
-# Database migrations
-cd backend && alembic upgrade head
-alembic revision --autogenerate -m "Description" --rev-id=NNN  # NNN = next sequential number
-# IMPORTANT: Migrations use sequential 3-digit IDs (001, 002, ..., 068, 069).
-# Check the latest: ls backend/alembic/versions/ | grep -E '^\d{3}_' | sort | tail -1
-# The revision ID and filename prefix MUST match (e.g., revision="068", file=068_description.py).
-# down_revision MUST point to the previous sequential number. Never use hex hash IDs for new migrations.
-
-# Access PostgreSQL
-docker exec -it patherly_postgres psql -U postgres -d patherly
-
-# Seed data
-cd backend && pip install httpx && python -m scripts.seed_trees
-
-# CI/CD debugging
-gh run list --limit 5                          # Recent CI runs
-gh run view <id> --log-failed                  # Failed job logs
-gh run view <id> --json jobs --jq '.jobs[] | {name: .name, conclusion: .conclusion}'
-# NEVER use `gh run watch` — it holds context open and burns tokens while waiting
-```
-
-### URLs
-
-- Frontend: <http://localhost:5173>
-- Backend API: <http://localhost:8000>
-- 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)
+**After shipping:** update `CURRENT-STATE.md` + `03-DEVELOPMENT-ROADMAP.md`, `gh issue close #N` for resolved issues, add lessons here only for non-obvious traps (otherwise let the code speak).
 
 ---
 
-## Critical Lessons Learned
-
-> Lessons 1-40 archived to `docs/LESSONS-ARCHIVE.md` — fixes are baked into the codebase. Consult if you hit a regression.
-
-### Active Lessons (41+)
-
-**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. Actions route to model tiers via `settings.get_model_for_action()`. 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:** Check the full data flow: 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: use 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_*` 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.
-
-**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.
-
-**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.
-
-**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/michaelchihlas/.nvm/versions/node/v20.19.0/bin:$PATH"`.
-
-**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.
-
-**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`.
-
-**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.
-
-**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.
-
-**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`.
-
-**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.
-
-**70. Toast library uses `toast.warning()` not `toast.warn()`:** Import from `@/lib/toast`. Methods: `success`, `error`, `warning`, `info`. See `frontend/src/lib/toast.ts`.
-
-**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.
-
-**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 is `position: fixed; bottom: 0`:** Any UI element placed in normal document flow below the session content will be hidden behind it. New fixed-position elements (like the message bar) must use `bottom: 68px` (action bar height) and the same `left: var(--sidebar-w)` pattern. The conversation column uses `pb-32` for clearance.
-
-**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.
-
-
-**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 ember orange — never use for code/kbd elements:** In Tailwind v4, `bg-accent` maps to `--color-accent: #f97316`. 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. Orange is reserved for interactive elements only (buttons, active nav, links).
-
-**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`).
-
-## 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)
-- **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`
+## Frontend patterns
+
+- **Component basics:** `cn()` from `@/lib/utils`, Lucide icons, `Modal.tsx` for modals (mobile-responsive `items-end sm:items-center` + `max-w-full sm:max-w-lg`).
+- **Types:** Create in `types/`, export from `types/index.ts`, `import type { T } from '@/types'`.
+- **Routing:** `getTreeNavigatePath()` / `getTreeEditorPath()` from `@/lib/routing`. Tree editor is `/trees/new`. All dashboard session clicks → `/pilot/:id` regardless of `session_type`.
+- **Lazy routes:** `lazyWithRetry` from `@/lib/lazyWithRetry.ts`, not `React.lazy` (auto-reload on stale chunks).
+- **Public pages:** raw `fetch()` with full URL, NOT `apiClient` (which requires auth tokens).
+- **Toast:** `toast.warning()` not `toast.warn()`. Import from `@/lib/toast` — methods: `success`, `error`, `warning`, `info`.
+- **Assistant chat:** uses local React `useState`, not Zustand. All three send paths (`handleSend`, `sendPrefill`, `handleResumeNew`) must call `setShowTaskLane(true)` when response has actions/questions.
+- **Chat backend wiring:** `aiSessionsApi.sendChatMessage` → `/ai-sessions/{id}/chat` → `unified_chat_service.py`. NOT `assistant_chat_service.py` (removed except retention settings).
+- **FlowPilot:** Actions live in page header (Resolve/Escalate/Share Update + overflow). `useBlocker` for active-session nav guard. "Pause & Leave" auto-pauses.
+- **AI markers:** `[QUESTIONS]`, `[ACTIONS]`, `[FORK]`, `[DELTA]...[/DELTA]` (editor), `[TREE_UPDATE]` (troubleshooting builder), `[STEPS_UPDATE]` (procedural builder), `[METADATA]`. Parsed in `unified_chat_service.py`; conversation history stores stripped `display_content`. If markers disappear: check system-prompt final reminder + per-user-message `[SYSTEM: ...]` injection in `_call_anthropic_cached()`.
+- **Image uploads:** paste/attach → Railway S3 via `uploadsApi.upload()` → resized by `storage_service.resize_image_for_vision()` (Pillow, 1568px max, PNG→JPEG) → base64 → Claude multimodal blocks. Max 3/msg. Images NOT stored in history.
+- **Async select-load-apply:** guard with a ref (pattern in `AssistantChatPage` `currentChatRef`). Update synchronously on every selection change; after every `await`, bail out if `ref.current !== thisId`.
+- **Editor-Embedded Flow Assist:** `EditorAIPanel` (320px side panel) + `useEditorAI`. Ghost nodes via `_suggestion: true`. Route actions via `settings.get_model_for_action()`.
+- **Script Builder:** `/script-builder`, chat-style. Backend `ScriptBuilderSession`, `script_builder_service.py`, endpoints `/scripts/builder/`. FlowPilot handoff via `action_type: "open_script_builder"` + `sessionStorage`.
+- **Intake form field schema:** `variable_name` + `field_type` (NOT `name` / `type`).
+- **Node field priority** (copilot, summaries): `title` → `question` → `description` → `content` → `label`.
+- **Procedural sessions auto-start** on page load (no intake/Start screen). Troubleshooting flows DO have a start screen.
 
 ---
 
-## Design System
+## Critical lessons
 
-**Source of truth:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — always read this before making visual or UI decisions.
+> Lessons 1-40 archived to `docs/LESSONS-ARCHIVE.md` — fixes baked into the codebase. **Grep the archive when an error message or symptom is unfamiliar, or after two failed attempts at resolving an issue.** Don't pre-load for routine work.
 
-- **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 planned.
-- **Backgrounds:** `bg-page` (`#1a1c23`), `bg-sidebar` (`#10121a`), `bg-card` (`#22252e`), `bg-elevated` (`#2e3140`)
-- **Cards:** `bg-card` with 1px `border-default` (`#2e3240`), 8px radius. No shadows, no blur, no gradients. Hover: `border-hover` (`#3d4252`)
-- **Buttons:** Primary: solid `accent` (#f97316), white text, 5px radius. Ghost: transparent + 1px border, hover `bg-elevated`
-- **Inputs:** `bg-input` (`#282b35`) with 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 (#2e3140), not a text color.
-- **Borders:** `border-default` (`#2e3240`), `border-hover` (`#3d4252`)
-- **Functional colors:** `#34d399` (success), `#eab308` (warning), `#f87171` (danger) — each with `-dim` variant at 10% opacity
-- **Accent:** Ember orange `#f97316` — used sparingly (≤5% of UI). `accent-dim` = `rgba(249,115,22,0.10)`, `accent-text` = `#fdba74`
-- **Deprecated:** Do NOT use `glass-card`, `glass-stat`, `bg-gradient-brand`, `text-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, purple gradients, or cyan accent (`#22d3ee`)
+### Backend / data
+
+- **APScheduler interval jobs always `max_instances=1`** — without it, overlapping runs reprocess records (TOCTOU).
+- **`get_db` rolls back on exception** — never remove the `await session.rollback()`, or one failed request poisons the connection with `InFailedSQLTransaction` cascading.
+- **Startup routines on tenant-isolated tables must use `_admin_session_factory()`, not `get_db()`.** Phase 4 RLS has no `app.current_account_id` set at startup. `get_service_account_id` is safe (reads cached `app.state`).
+- **Backfill migrations adding `account_id`:** grep ALL `ModelClass(` sites in service code to verify `account_id=` is passed. SQLAlchemy accepts `None` silently — Phase 4 RLS WITH CHECK surfaces the problem at runtime as `InsufficientPrivilegeError: new row violates row-level security policy`.
+- **`tree_shares.account_id = tree.account_id`**, never `current_user.account_id`. A super_admin sharing another tenant's tree must produce the share in the tree owner's tenant, or it becomes invisible post-RLS.
+- **Global tables (no `account_id`, never in RLS migrations):** `script_categories`, `platform_steps`, `template_trees`, `plan_feature_defaults`, `accounts`. Scan at class level — one `.py` file can hold multiple classes with different columns (e.g. `ScriptCategory` vs `ScriptTemplate`).
+- **`ai_sessions.status` is VARCHAR(30)** — fits `requesting_escalation` (23 chars). Migration `f0aad74ea51b` widened from 20.
+- **PostgreSQL `func.sum(case(...))` returns `Decimal` via asyncpg** — cast to `int()` before Pydantic `dict[str, Any]`.
+- **Enhancement / branch_addition proposals need `modified_flow_data` via "Edit & Publish"** — backend 400 on direct approve. Only `new_flow` supports direct approve.
+- **Adding email types:** static async method on `EmailService` in `core/email.py`. Fire-and-forget from endpoints (log errors, don't fail the request).
+
+### AI / FlowPilot
+
+- **Anthropic SDK `max_retries=1`** — default of 2 can take 3× the timeout.
+- **Model tier routing:** `settings.get_model_for_action(action_type)`. Always alias form (`claude-sonnet-4-6`).
+- **FlowPilot must ask GUI-vs-script before suggesting either** when both are viable — see `FLOWPILOT_SYSTEM_PROMPT` in `flowpilot_engine.py`.
+- **Telemetry events to grep:** `anthropic.cache` (prompt-cache hit/create), `mcp.turn` (per-turn MCP availability), `mcp.fallback` (MCP silent-retry fired).
+- **Don't put literal payloads in system prompts.** Bit us twice in one day: a worked `[QUESTIONS]` example with literal "Outlook + jsmith" content, and a full DNS troubleshooting tree, both caused Claude to recite that content on unrelated tickets — the symptom looked like task-lane state leaking across chats. The fix is structural: every output example in a system prompt uses `<placeholder>` syntax (`{"text": "<one short, specific question>"}`), never literal field values. Real-looking format examples live in few-shot messages (separate file, separate code path), not system prompts. Guardrail: `tests/test_prompt_anti_parrot.py` scans every `*_PROMPT`/`*_SCHEMA`/`*_PROTOCOL`/`*_FORMAT` constant in `app/services/` and `app/core/`; CI fails when a marker block contains a literal JSON value or when a known leaked token (jsmith, DC01, ADSync, Dnscache, etc.) appears anywhere in a prompt.
+
+### Frontend / UI
+
+- **Flex height chain:** every ancestor from `app-shell` grid to React Flow canvas needs `flex` + `flex-1` + `min-h-0` or `h-full`. Missing `flex` collapses to 0. Same rule for FlowPilot action bar and any tall scroller.
+- **React Flow CSS in Tailwind v4:** import in `index.css`, not component JS. Override dark theme via `--xy-*` CSS vars.
+- **`text-secondary` renders invisible on dark** — Tailwind v4 maps it to `--color-secondary` (a surface color). Use `text-muted-foreground` for readable secondary text. Avoid `text-muted` for body — labels only.
+- **`bg-accent` is electric blue — never for code/kbd.** Use `bg-white/[0.12] border border-white/[0.06]` for inline code, `bg-white/[0.08]` for kbd. Accent reserved for interactive elements.
+- **`landing.css` uses self-contained `--lp-*` vars** — never `var(--color-*)` theme tokens (they resolve incorrectly outside the app shell).
+- **Never `transition: all`** — list properties explicitly, or layout props animate and jank.
+- **Date range filter end dates:** `setHours(23, 59, 59, 999)` before sending, or the day's items are excluded. For string-based date inputs, append `T23:59:59.999Z`.
+- **TopBar search:** full bar `hidden sm:block`, icon button `sm:hidden` — both open CommandPalette.
+- **Hover pop-out cards:** scrim `pointer-events-none`, expanded card has its own click handler at `z-50`, dismiss via `onMouseLeave` on wrapper. Never put handlers on the scrim.
+- **`tsc -b` in Dockerfile is stricter than `tsc --noEmit`** — enforces `noUnusedLocals` / `noUnusedParameters` as hard errors. Check IDE yellow squiggles before pushing.
+- **Dashboard prefill auto-submits** via `useEffect` + `prefillHandledRef` guard — no double-enter.
+- **Global Axios 5xx interceptor fires before component `.catch()`** — fix optional-data endpoints at the source (return `[]` / `{}` on provider failure), not in the component.
+- **Playwright strict mode:** scope selectors to avoid sidebar/main ambiguity. Use `getByRole('heading', { name })` or `.animate-scale-in` locators, not bare `getByText()`.
+
+### Env / infra
+
+- **Node 20.19+ required** (Vite 7). `nvm use 20` or `PATH="$HOME/.nvm/versions/node/v20.19.0/bin:$PATH"`.
+- **Railway backend service is `patherly`, DB name `railway`.** Public Postgres proxy: `interchange.proxy.rlwy.net:45797`.
+- **Railway Object Storage bucket `resolutionflow-uploads`.** Env vars `STORAGE_*`. boto3 in `storage_service.py`. Dockerfile needs Pillow + `libjpeg-dev` / `zlib1g-dev`.
+- **PostHog:** `PostHogProvider` + `posthog.init()` in `main.tsx`. Helpers in `lib/analytics.ts`. Env: `VITE_PUBLIC_POSTHOG_KEY`, `VITE_PUBLIC_POSTHOG_HOST`. `identifyUser()` in `authStore.fetchUser()`, `resetAnalytics()` on logout.
+- **bun PATH on devserver01:** `BUN_INSTALL="$HOME/.bun"`, `PATH="$BUN_INSTALL/bin:$PATH"`. Playwright Chromium needs `libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2`.
+- **Full-stack change:** trace schema → endpoint → API client → hook → store → UI. Don't assume one end proves the other.
+- **Dev env** — see DEV-ENV.md for current topology, `REPO_ROOT` requirement when compose runs inside a container, Vite `allowedHosts`, linuxserver.io `group_add` + custom-cont-init.d workaround, `docker compose up` no-op-on-unchanged-hash gotcha.
 
 ---
 
-## Frontend Patterns
+## GitNexus code intelligence
 
-- **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` → custom step view. Key state: `pendingStep`, `pendingContinuationNodeId`, `customBranchMode`, `branchOriginNodeId`. Use `findCustomStep()` not `findNode()` for custom step UUIDs.
-- **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`.
-- **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`.
-- **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.
+Indexed as `resolutionflow`. Earns its cost on cross-cutting work only.
+
+| Tool | When |
+|---|---|
+| `gitnexus_query({query})` | Find code by concept when you don't know where to look |
+| `gitnexus_context({name})` | Callers/callees of a symbol before touching it |
+| `gitnexus_impact({target, direction})` | Blast radius before editing shared symbols |
+| `gitnexus_rename({symbol_name, new_name, dry_run: true})` | Safe multi-file rename |
+
+**Use for:** core shared symbols (`flowpilot_engine`, `unified_chat_service`, auth middleware, `get_db`, shared hooks), cross-file renames, unfamiliar bug traces, refactor safety. **Skip for:** new endpoints, isolated fixes, changes you can read in one file.
+
+Re-indexes automatically on commit (PostToolUse hook). Manual refresh if stale: `npx gitnexus analyze`.
 
 ---
 
-## Common Tasks
+## gstack skills
 
-- **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 public route (no auth):** Add at top level in `router.tsx` alongside `/login`, `/register` — NOT inside the `ProtectedRoute`/`AppLayout` children.
-- **Schema change:** Update model → `alembic revision --autogenerate -m "desc" --rev-id=NNN` (NNN = next sequential number, e.g., 068 → 069) → review → `alembic upgrade head`
-- **New frontend API module:** Types in `types/` → export from `types/index.ts` → client in `api/` → export from `api/index.ts`
+Always use `/browse` for web, never `mcp__claude-in-chrome__*`. Most-used:
 
----
-
-## Coding Standards
-
-### Python
-
-- 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, 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`
-- Large features: commit per phase with `npm run build` validation
-
-### After Completing Work
-
-When a feature, fix, or significant piece of work is finished and merged/committed:
-
-1. **Update `CURRENT-STATE.md`** — move completed items, update "In Progress" and "What's Next" sections
-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.
-
-**Available skills:**
-
-| 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 |
+- `/review` — pre-land PR review
+- `/ship` — tests + review + PR creation
+- `/browse` + `/qa` / `/qa-only` — headless browser testing (setup: Lesson 82)
+- `/design-review` — visual QA
+- `/investigate` — systematic debug with root cause
+- `/codex` — OpenAI Codex second opinion
+- `/plan-eng-review` / `/plan-design-review` / `/plan-ceo-review` — plan critiques
 
 ---
 
 ## Deployment (Railway)
 
-- **Production:** `resolutionflow.com` (frontend), `api.resolutionflow.com` (backend)
-- Auto-deploys on push to `main`
-- PR environments auto-created (need manual domain generation in Railway dashboard)
-- 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`
-- Super admin utility: `backend/make_superadmin_simple.py list|<email>`
+- **Prod:** `resolutionflow.com` (frontend), `api.resolutionflow.com` (backend).
+- Auto-deploy: Gitea push → GitHub mirror → Railway follows GitHub `main`.
+- PR environments auto-created; need manual domain generation + `VITE_API_URL` with `https://` prefix.
+- `ALLOW_RAILWAY_ORIGINS=true` for `*.up.railway.app` CORS.
+- Shared Variables (Railway project-level) auto-propagate to PR envs — use for secrets like `ANTHROPIC_API_KEY`.
+- Super admin utility: `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
-
----
-
-## Quick Reference
+## Quick reference
 
 | What | Where |
-|------|-------|
-| 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 |
+|---|---|
+| Detailed status | [CURRENT-STATE.md](CURRENT-STATE.md) |
+| Roadmap | [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) |
+| Design system | [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) |
+| Dev env | [DEV-ENV.md](DEV-ENV.md) |
+| Archived lessons | [docs/LESSONS-ARCHIVE.md](docs/LESSONS-ARCHIVE.md) |
+| ConnectWise API | `docs/connectwise/` |
+| GitHub issues | `gh issue list --state open` |
+| Local API docs | <http://localhost:8000/api/docs> |

CURRENT-STATE.md

@@ -2,7 +2,7 @@
 
 > **Purpose:** Quick-reference file showing exactly where the project stands.
 > **For Claude Code:** Read this first to understand what's done and what's next.
-> **Last Updated:** April 4, 2026 (evening)
+> **Last Updated:** April 12, 2026
 
 ---
 
@@ -13,8 +13,8 @@
 ## What's Complete
 
 ### Core Platform
-- FastAPI project structure with 55+ API endpoints
-- PostgreSQL database with Docker, 100+ Alembic migrations
+- FastAPI project structure with 35+ API endpoints
+- PostgreSQL database with Docker, 75+ Alembic migrations
 - User authentication (JWT, register, login, refresh, logout, invite codes)
 - Refresh token rotation with JTI-based revocation
 - Trees CRUD with full-text search (FTS index)
@@ -29,7 +29,7 @@
 
 ### Frontend Core
 - React 19 + Vite + TypeScript + Tailwind CSS v4 (`@tailwindcss/vite`)
-- **Charcoal Design System v6** — Flat, high-contrast dark theme (Sentry/PostHog-inspired), charcoal palette; accent color is electric blue (#60a5fa), replacing ember orange
+- **Charcoal Design System** — Flat, high-contrast dark theme (Sentry/PostHog-inspired), charcoal palette with sidebar-darkest approach
 - **Brand fonts:** Bricolage Grotesque (headings), IBM Plex Sans (body), JetBrains Mono (code)
 - Authentication UI (login, register, email verification)
 - Tree library/browsing page with grid/list/table views
@@ -130,36 +130,6 @@
 - Enhanced PSA metrics: time entries, hours logged, push success funnel, daily trend chart
 - 13 new backend tests for coverage and flow quality endpoints
 
-### Conversational Branching (Complete)
-
-- SessionBranch, ForkPoint, SessionHandoff, SessionResolutionOutput models + migration (4 tables, 13 columns)
-- BranchManager service, BranchAwarePromptBuilder, HandoffManager service with integration tests
-- Branch API endpoints: `session_branches.py`, `session_handoffs.py`, `session_resolutions.py`
-- Integrated into `unified_chat_service.py` and AI session step creation
-- Frontend: BranchNode, ForkCard, BranchMap, BranchRevivalCard, BranchTransitionBar, HandoffModal, ResolutionOutputPanel components
-- Wired into FlowPilotSession and `useFlowPilotSession` hook
-
-### Script Library Enhancements (Complete)
-
-- ParameterizeAndSavePanel replaces SaveToLibraryDialog — accepts `script_body` and `parameters_schema` in save flow
-- "New from Script" button on ScriptLibraryPage for one-click script creation from template
-- Default tab is "All Scripts" (previously filtered to owned scripts)
-- Ownership filter state preserved across category and search changes
-- Backend: `save-to-library` endpoint accepts `script_body` + `parameters_schema`
-
-### AI Vision Support (Complete)
-
-- Image uploads (paste/drag-drop) wired into AI assistant chat via `upload_ids`
-- Server-side image resize before sending to Claude (Pillow, 1568px max, PNG→JPEG)
-- `storage_service.resize_image_for_vision()` handles vision pipeline
-- Images are NOT stored in conversation history (text-only history)
-
-### Mid-Session Status Updates (Complete)
-
-- AI assistant can generate `status_update` steps (step_type added to CHECK constraint)
-- Status update generation wired into `unified_chat_service.py`
-- Frontend renders status update cards in session view
-
 ### Search & Recall + Evidence-Rich Sessions (Complete)
 
 **Evidence:**
@@ -193,7 +163,14 @@
 - SQL wildcard escaping in tag search
 - PSA credentials encrypted at rest (Fernet)
 
-### Copilot-First Dashboard (March–April 2026)
+### Tenant Isolation (Phases 1-4 Complete)
+- PostgreSQL RLS enabled across tenant-scoped tables in phased rollout
+- `account_id` propagation completed across core content, sessions, analytics, notifications, shares, and remaining Phase 4 tables
+- Global platform tables correctly excluded from tenant RLS where they have no `account_id` (`script_categories`, `platform_steps`, `template_trees`)
+- Runtime bootstrap paths updated to use BYPASSRLS/admin sessions where needed (auth/user mutations, startup service account, background jobs, seed scripts)
+- Preview Railway backend and frontend deployments green for PR 136 after the Phase 4 fixes
+
+### Copilot-First Dashboard (March 2026)
 
 - Redesigned dashboard as FlowPilot copilot launchpad (ChatGPT-style input)
 - Chat-style input with paste images, drag-drop files, attach button, paste logs
@@ -203,33 +180,9 @@
 - Unified Command Palette (Cmd+K) — merged QuickLaunch into omnibar
 - "Solutions Library" rename (from "Step Library") site-wide
 - Maintenance flows hidden from UI for pilot (backend still supports them)
-- Charcoal color palette: sidebar `#0e1016`, page `#16181f`, cards `#1e2028`
-- **Landing page redesign** — scroll-driven reveal animations, live chat animation, FAQ section, improved trust signals; copy: "Resolve tickets faster. Notes write themselves."
-- **Session History redesign** — tabbed layout with Load More pagination
-- **Edit Procedure page** — layout and color system overhaul
-- **TaskLane UX** improvements in assistant chat; persistence across page reload
-- TaskLane answers persist in sessionStorage; correct behavior on all three chat paths (send, prefill, resume)
-- **Action bar consolidation** — Deduplicated actions across FlowPilot/Cockpit headers and chat toolbars; chat toolbar now only has input tools (Attach, Paste Logs, Tasks)
-- **ViewToggle redesigned** as persistent tab bar with bottom-border active indicator and ARIA attributes (FlowPilot/Cockpit switcher)
-- **Standardized action naming** across all session pages: Resolve (emerald), Update (blue), Close (rose), Pause (muted)
-- **ConcludeSessionModal copy refresh** — Forward-facing action verbs, "Close & Generate" CTA, consistent outcome labels
-- Deleted unused FlowPilotActionBar component (227 lines dead code)
-
-### Network Diagrams (In Progress)
-
-- Network diagram editor with React Flow (@xyflow/react v12) canvas
-- Device node system: 27 device types across 7 categories (network, compute, storage, cloud, endpoint, infrastructure, security)
-- Custom device type creation via DeviceToolbar
-- Connection edges with 6 types (ethernet, fiber, wifi, vpn, vlan, wan) — color-coded, dashed for wireless/VPN
-- Properties panel for editing device and connection details
-- AI-assisted diagram generation (describe network → auto-layout)
-- Auto-save every 30 seconds, manual save, JSON export
-- **React Flow UI Components** — Cherry-picked and Charcoal-restyled: BaseNode (structured header/content/footer slots), BaseHandle (styled connection handles), LabeledHandle (named port labels), NodeStatusIndicator (status border effect: emerald/red/yellow), NodeTooltip (hover details via NodeToolbar), LabeledGroupNode (subnet/VLAN/site/DMZ containers), AnimatedSvgEdge (traffic flow visualization)
-- Grouping category in toolbar: Subnet, VLAN, Site, DMZ drag-drop to canvas
-- Traffic flow toggle on edges (switches between static and animated)
-- Context menu with copy/paste/duplicate/select all shortcuts
-- Drop position uses `screenToFlowPosition()` for correct placement at any zoom/pan level
-- **Bug fix:** PropertiesPanel inputs now work — selection uses IDs instead of stale object snapshots
+- Landing page copy rewrite: "Resolve tickets faster. Notes write themselves."
+- Spring bounce hover animation on dashboard cards
+- Charcoal color palette: sidebar `#10121a`, page `#1a1c23`, cards `#22252e`
 
 ### Maintenance Flows (Hidden from UI)
 
@@ -289,22 +242,21 @@
 
 ### Start Development
 ```bash
-# Start PostgreSQL (Docker — container name resolutionflow_postgres, port 5433, DB resolutionflow)
-docker start resolutionflow_postgres
+# Start PostgreSQL (Docker Compose)
+docker compose up -d
 
 # Backend (from backend/)
 source venv/bin/activate
 uvicorn app.main:app --reload
 
-# Frontend (from frontend/, requires Node 20)
+# Frontend (from frontend/)
 npm run dev
 ```
 
 ### URLs
-- Frontend: http://46.202.92.250:5173 (or https via Traefik reverse proxy)
-- Backend API: http://46.202.92.250:8000
-- API Docs: http://46.202.92.250:8000/api/docs
-- Dev env runs on Hostinger VPS (46.202.92.250) with Traefik + HTTPS; see [DEV-ENV.md](DEV-ENV.md)
+- Frontend: http://192.168.0.9:5173
+- Backend API: http://192.168.0.9:8000
+- API Docs: http://192.168.0.9:8000/api/docs
 
 ### Run Tests
 ```bash

DEV-ENV.md

@@ -1,262 +1,671 @@
-# ResolutionFlow Dev Environment Setup & Operations Guide
+# ResolutionFlow — Dev Environment Setup & Operations Guide
 
-## Server Overview
+> **Scope:** Stand up a working ResolutionFlow dev environment from scratch on any Linux host (VPS, on-prem Proxmox LXC/VM, bare metal). Self-contained — do not read another doc to get the dev stack running.
+> **Last rewritten:** April 2026, post-Hostinger-VPS deprecation, ahead of Proxmox migration.
+> **Audience:** You (returning to the project), a teammate, or a fresh Claude Code session.
 
-- **Provider:** Hostinger KVM VPS (srv1522117)
-- **IP Address:** 46.202.92.250
-- **OS:** Ubuntu 24.04 LTS
-- **CPU:** 2 vCPU cores
-- **RAM:** 8GB
-- **Disk:** 100GB NVMe SSD
-- **Swap:** 4GB (`/swapfile`, swappiness=10)
+If you're picking up mid-migration and need to know what code state is on the current branch, read `docs/FlowAssist_Migration/MIGRATION-HANDOFF.md` first.
 
-## Architecture
+---
 
-All services run as Docker containers on the host, managed via SSH or from the VS Code Server integrated terminal.
+## 1. What this project needs, regardless of host
 
-```
-Host (root@srv1522117)
-├── Traefik                       → reverse proxy + auto SSL (Let's Encrypt)
-├── VS Code Server                → browser IDE at https://code.resolutionflow.com
-└── ResolutionFlow Stack
-    ├── resolutionflow_frontend   → Vite/React on port 5173
-    ├── resolutionflow_backend    → FastAPI/Uvicorn on port 8000
-    └── resolutionflow_postgres   → PostgreSQL 16 + pgvector on port 5432
-```
+These are non-negotiable. If your host can't provide them, fix that before anything else.
 
-## Access URLs
+| Component | Required version | Notes |
+|---|---|---|
+| **Linux** | any mainstream distro | Ubuntu 22.04+ / Debian 12+ tested; Alpine fine for containers |
+| **Python** | 3.11+ | Backend and migrations |
+| **Node.js** | 20.19+ | Vite 7 fails on older versions — CLAUDE.md Lesson 63 |
+| **PostgreSQL** | 16 | `gen_random_uuid()` + `jsonb` + RLS are all leaned on |
+| **Docker + Docker Compose** | recent | Only if you are running Postgres and/or backend as containers |
+| **Git** | recent | |
 
-| Service | URL |
+Optional but recommended:
+
+| Tool | Why |
 |---|---|
-| VS Code Server | https://code.resolutionflow.com |
-| Frontend (dev) | http://46.202.92.250:5173 |
-| Backend API | http://46.202.92.250:8000 |
-| API Docs | http://46.202.92.250:8000/docs |
+| **code-server** | Browser-based VS Code; how this project has historically been edited |
+| **`gh` CLI** | Mirror repo is on GitHub via Gitea; `gh` reads issues and PRs |
+| **bun** | Required for the gstack `/browse` + `/qa` skills (CLAUDE.md Lesson 82) |
+| **`npx gitnexus analyze`** | Code-graph for Phase 2+ work that touches `unified_chat_service` |
+| **Claude Code CLI** | If you want to run Claude Code locally on the host |
 
-## Docker Layout
+---
+
+## 2. Architectural shape
+
+The project is three services plus your editor. Keep these facts in mind regardless of topology:
 
 ```
-/docker/
-├── traefik/
-│   ├── docker-compose.yml    → Traefik reverse proxy
-│   └── .env                  → ACME_EMAIL for Let's Encrypt
-└── vscode/
-    ├── docker-compose.yml    → VS Code Server
-    └── .env                  → CODE_PASSWORD
+Your browser
+   ├─► code-server         (editor, optional — usually port 8080 or behind TLS)
+   ├─► frontend (Vite)     (dev server, port 5173)
+   └─► backend (FastAPI)   (dev server, port 8000)
+                               │
+                               └─► PostgreSQL (port 5432)
 ```
 
-Project lives inside the VS Code Server Docker volume:
+**The frontend calls the backend by URL at runtime.** The frontend does not proxy through the backend. Whatever URL your browser uses to reach the backend is what `VITE_API_URL` must be set to, **baked in at build time**. Changing `VITE_API_URL` requires rebuilding the frontend.
+
+**The backend calls the database by URL at runtime.** The URL depends on where Postgres is relative to the backend — Docker service name if both are in the same compose network, `localhost` if Postgres is native on the same host, or a DNS name if they're in separate containers/VMs.
+
+**CORS is configured explicitly.** The backend's `CORS_ORIGINS` list must include every origin your browser will use to reach the frontend. A missing origin shows up as failed preflight requests.
+
+---
+
+## 3. Topology choices — pick one before you start
+
+The project is agnostic to topology, but each shape has different setup steps.
+
+### Option A — all-in-one LXC/VM/host (simplest)
+
+Postgres, backend, and frontend all run on one Linux host. code-server runs on the same host or a sibling. No Docker required. Best for a single-developer Proxmox LXC.
+
+### Option B — Docker Compose on one host
+
+Postgres, backend, and frontend run as Docker containers on one host. code-server runs outside the compose network (on the host or in another container). This is how the old Hostinger VPS was configured. Best if you want reproducible container images.
+
+### Option C — split services across containers/VMs
+
+Postgres in one container/VM, backend and frontend in another, code-server in a third. Most complex; requires explicit networking between them. Use only if you have a specific reason.
+
+**Pick one and stick with it for the entire setup.** Mixing Options A and B halfway through is where setup runs off the rails.
+
+---
+
+## 4. Per-host configuration
+
+These values are specific to your host. Fill them in once and reference them by name throughout the rest of the doc.
+
 ```
-/var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow/
+DEV_HOST              = <hostname or IP your browser uses, e.g. dev.internal, 10.0.0.42>
+DEV_HOST_SCHEME       = <http or https; http is fine for internal dev, https if behind a TLS proxy>
+FRONTEND_PORT         = 5173
+BACKEND_PORT          = 8000
+POSTGRES_PORT         = 5433  # host-side port. 5433 is the recommended default on any shared host to avoid collision with a host-level Postgres. The container's internal port stays 5432.
+POSTGRES_DB_NAME      = resolutionflow
+POSTGRES_USER         = postgres
+POSTGRES_PASSWORD     = <local-dev-password; anything, this is not prod>
+SECRET_KEY            = <openssl rand -hex 32 — generate fresh per host, do not reuse>
+ANTHROPIC_API_KEY     = <from https://console.anthropic.com>
+GOOGLE_AI_API_KEY     = <optional, only if using Gemini as a fallback>
 ```
 
-## VS Code Server
+Store these somewhere you can copy from during setup. Do not commit them.
 
-- **Container user:** `coder` (UID 1000)
-- **Home directory:** `/home/coder`
-- **Project location:** `/home/coder/resolutionflow`
-- **Host volume path:** `/var/lib/docker/volumes/vscode_vscode-data/_data`
-- **Access URL:** `https://code.resolutionflow.com`
-- **HTTPS:** Auto-provisioned via Traefik + Let's Encrypt
+> **Naming note:** the canonical database name is `resolutionflow`. If you see `patherly` in a config file, that's drift from an earlier rename and is being swept in a separate commit — use `resolutionflow`. CLAUDE.md tracks the live-code files that still reference `patherly`.
 
-### Compose File Location
-`/docker/vscode/docker-compose.yml`
+---
 
-## Traefik
+## 5. Setup procedure
 
-Handles reverse proxying and automatic SSL for all services. HTTP automatically redirects to HTTPS.
+Run these in order. Stop at the first failure and investigate.
 
-### Adding A New Service Behind Traefik
-
-Add these labels to any new Docker service:
-
-```yaml
-labels:
-  - "traefik.enable=true"
-  - "traefik.http.routers.<n>.rule=Host(`subdomain.resolutionflow.com`)"
-  - "traefik.http.routers.<n>.entrypoints=websecure"
-  - "traefik.http.routers.<n>.tls.certresolver=letsencrypt"
-  - "traefik.http.services.<n>.loadbalancer.server.port=<port>"
-```
-
-Also create an A record in DNS pointing the subdomain to `46.202.92.250`.
-
-## ResolutionFlow Dev Stack
-
-### Important: No Docker Inside VS Code Container
-
-The VS Code Server container does NOT have Docker. All `docker compose` commands must be run via SSH as root on the host.
-
-### Environment Files
-
-| File | Purpose |
-|---|---|
-| `.env` | Root — Docker Compose interpolation (`SECRET_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_AI_API_KEY`, `POSTGRES_PORT`) |
-| `backend/.env` | Backend source of truth — all FastAPI settings, API keys, DB URLs, CORS |
-| `frontend/.env` | Frontend — `VITE_API_URL` pointing to backend |
-
-### Critical Remote Access Config
-
-**`frontend/.env`:**
-```
-VITE_API_URL=http://46.202.92.250:8000
-```
-
-**`backend/.env`:**
-```
-CORS_ORIGINS=["http://localhost:3000","http://localhost:5173","http://127.0.0.1:3000","http://127.0.0.1:5173","http://46.202.92.250:5173","http://46.202.92.250:3000","https://resolutionflow.com","https://www.resolutionflow.com"]
-FRONTEND_URL=http://46.202.92.250:5173
-DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/resolutionflow
-DATABASE_URL_SYNC=postgresql://postgres:postgres@db:5432/resolutionflow
-```
-
-Note: `DATABASE_URL` uses `@db:5432` (Docker service name), not `@localhost`.
-
-**`docker-compose.dev.yml`:**
-```yaml
-- VITE_API_URL=http://46.202.92.250:8000
-```
-
-### Starting the Dev Environment
-
-SSH into host as root:
+### 5.1 Install system dependencies
 
 ```bash
-cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
-docker compose -f docker-compose.dev.yml up -d
+# Ubuntu / Debian
+sudo apt update && sudo apt install -y \
+  git curl build-essential \
+  python3.11 python3.11-venv python3-pip \
+  postgresql-client   # not the server — only if running Postgres natively
+
+# Node 20 via nvm (survives container rebuilds if stored in a volume)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+export NVM_DIR="$HOME/.nvm" && source "$NVM_DIR/nvm.sh"
+nvm install 20
+nvm alias default 20
 ```
 
-### Running Migrations (Fresh Database)
+For Option B (Docker Compose), also:
 
 ```bash
-cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER   # log out and back in for this to take effect
+```
+
+### 5.2 Clone the repo
+
+```bash
+git clone https://gitea.resolutionflow.com/chihlasm/resolutionflow.git
+# or the GitHub mirror:
+# git clone https://github.com/chihlasm/resolutionflow.git
+cd resolutionflow
+
+# Check out the working branch if you're continuing mid-migration.
+git fetch origin
+git checkout feat/flowpilot-migration
+```
+
+### 5.3 Start PostgreSQL
+
+**Option A (native Postgres on the host):**
+
+```bash
+sudo apt install -y postgresql-16
+sudo -u postgres psql -c "CREATE DATABASE resolutionflow;"
+sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';"
+# Adjust pg_hba.conf if you need non-local connections.
+```
+
+**Option B (Postgres via Docker Compose):** The repo has a `docker-compose.dev.yml` at the root. Check its Postgres service for the container name, port mapping, and volume. The local compose defaults use container name `resolutionflow_postgres`, database `resolutionflow`, and host-side port `5433` (mapped to the container's internal `5432`) — see CLAUDE.md Lesson 65. The host-side `5433` is the recommended default on any shared host: it keeps the port free for a host-level Postgres if you ever need one. The compose file also defines explicit `command:` directives on both `backend` and `frontend` to force `--host 0.0.0.0`, and expects the caller to pass `REPO_ROOT` (see 5.4) for bind-mount resolution. Confirm what the compose file actually says on your branch before trusting these values.
+
+```bash
+docker compose -f docker-compose.dev.yml up -d db
+docker compose -f docker-compose.dev.yml logs db    # wait for "ready to accept connections"
+```
+
+**Verify:**
+
+```bash
+# From the host (Option A) or the backend container/LXC (Option B):
+psql -h <db-host> -p <POSTGRES_PORT> -U postgres -d resolutionflow -c "SELECT now();"
+```
+
+### 5.4 Write the `.env` files
+
+The repo expects three env files. Create each one:
+
+**`backend/.env`** — backend source of truth:
+
+```bash
+APP_NAME=ResolutionFlow
+DEBUG=true
+
+# DB URLs — `<db-host>` is `localhost` for Option A, the Docker service name
+# (e.g. `db`) for Option B, or the DB container/VM hostname for Option C.
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@<db-host>:<POSTGRES_PORT>/resolutionflow
+DATABASE_URL_SYNC=postgresql://postgres:postgres@<db-host>:<POSTGRES_PORT>/resolutionflow
+
+# Auth
+SECRET_KEY=<SECRET_KEY>
+ACCESS_TOKEN_EXPIRE_MINUTES=5
+REFRESH_TOKEN_EXPIRE_DAYS=7
+REQUIRE_INVITE_CODE=true
+
+# AI providers
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
+GOOGLE_AI_API_KEY=<GOOGLE_AI_API_KEY or leave unset>
+
+# FlowPilot MCP telemetry — leave on so the Phase 0.5 baseline data keeps accruing
+ENABLE_MCP_MICROSOFT_LEARN=true
+
+# CORS + frontend URL
+FRONTEND_URL=<DEV_HOST_SCHEME>://<DEV_HOST>:<FRONTEND_PORT>
+CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173","<DEV_HOST_SCHEME>://<DEV_HOST>:<FRONTEND_PORT>"]
+```
+
+**`frontend/.env.local`** — frontend build-time config:
+
+```bash
+VITE_API_URL=<DEV_HOST_SCHEME>://<DEV_HOST>:<BACKEND_PORT>
+```
+
+Optional PostHog (CLAUDE.md Lesson 64 — enables product analytics locally):
+
+```bash
+VITE_PUBLIC_POSTHOG_KEY=<from PostHog project settings>
+VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
+```
+
+**Repo root `.env`** — only needed for Option B (Docker Compose interpolation):
+
+```bash
+SECRET_KEY=<SECRET_KEY>
+ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
+GOOGLE_AI_API_KEY=<GOOGLE_AI_API_KEY or leave unset>
+POSTGRES_PORT=<POSTGRES_PORT>
+# Absolute host-side path to the repo root. REQUIRED whenever docker-compose is
+# invoked from inside a container (e.g. a code-server container with the host
+# Docker socket mounted in). Without it, the bind mounts in
+# docker-compose.dev.yml (`${REPO_ROOT}/backend:/app`, `${REPO_ROOT}/frontend:/app`)
+# resolve against the CLI's CWD — a path the host daemon cannot see — and
+# Docker silently creates empty directories there instead of mounting the code.
+# If you run docker compose directly on the host shell, you can set this to `.`
+# or the absolute path of the repo; being explicit is safer either way.
+REPO_ROOT=/absolute/path/to/resolutionflow
+```
+
+> **Never commit any `.env` file.** The `.gitignore` already covers this.
+
+### 5.5 Run the backend setup
+
+**Option A (native):**
+
+```bash
+cd backend
+python3.11 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Migrate the DB to head.
+alembic upgrade head
+```
+
+**Option B (Docker):**
+
+```bash
+docker compose -f docker-compose.dev.yml up -d backend
 docker compose -f docker-compose.dev.yml run --rm backend alembic upgrade head
 ```
 
-### Seeding Test Users
+**Expected alembic head** (as of `feat/flowpilot-migration`): `f07010f17b01`. If `alembic current` shows anything else after `upgrade head`, something has gone wrong — stop and investigate.
+
+### 5.6 Seed test users
 
 ```bash
+# Option A
+cd backend && source venv/bin/activate
+python -m scripts.seed_test_users
+
+# Option B
 docker exec resolutionflow_backend python -m scripts.seed_test_users
 ```
 
-Test accounts (password: `TestPass123!`):
+Test users (all share password `TestPass123!`):
 
-| Email | Role | Plan |
-|---|---|---|
-| admin@resolutionflow.example.com | Owner | Team |
-| pro@resolutionflow.example.com | Owner | Pro |
-| teamadmin@resolutionflow.example.com | Owner | Team |
-| engineer@resolutionflow.example.com | Engineer | Shared |
+| Email | Role |
+|---|---|
+| `admin@resolutionflow.example.com` | super admin |
+| `teamadmin@resolutionflow.example.com` | team admin |
+| `engineer@resolutionflow.example.com` | engineer |
+| `pro@resolutionflow.example.com` | solo pro |
 
-### Rebuilding After Config Changes
+### 5.7 Run the backend
+
+**Option A:**
+
+```bash
+cd backend && source venv/bin/activate
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+**Option B:** Already running from `docker compose up -d backend`. Tail logs:
+
+```bash
+docker compose -f docker-compose.dev.yml logs -f backend
+```
+
+**Verify:** `curl <DEV_HOST_SCHEME>://<DEV_HOST>:<BACKEND_PORT>/api/docs` — OpenAPI docs page loads.
+
+### 5.8 Run the frontend
+
+**Option A:**
+
+```bash
+cd frontend
+npm install
+npm run dev -- --host 0.0.0.0 --port 5173
+```
+
+**Option B:**
 
-**Frontend** (Vite bakes env vars at build time — requires rebuild):
 ```bash
-cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
 docker compose -f docker-compose.dev.yml up -d --build frontend
 ```
 
-**Backend** (restart only):
+**Verify:** Open `<DEV_HOST_SCHEME>://<DEV_HOST>:<FRONTEND_PORT>` in your browser. Log in with one of the test users. Navigate to `/pilot` — the FlowPilot session page should render.
+
+---
+
+## 6. Verification — proof the env actually works
+
+Run these after setup. Every item has a concrete expected outcome.
+
+### 6.1 Database schema is at the right version
+
 ```bash
+# Option A
+cd backend && source venv/bin/activate && alembic current
+# Option B
+docker compose -f docker-compose.dev.yml run --rm backend alembic current
+```
+
+Expected: `f07010f17b01 (head)` on the `feat/flowpilot-migration` branch. On `main`, expected: `074 (head)`.
+
+### 6.2 Alembic reversibility
+
+```bash
+alembic downgrade -1    # should complete cleanly
+alembic upgrade head    # should return to f07010f17b01
+```
+
+If either step fails, the migration has a bug and Phase 2 cannot start.
+
+### 6.3 Prompt-cache hit verification (the deferred Phase 0 TODO)
+
+`backend/app/core/ai_provider.py` module docstring has a `TODO(phase0-verify)` note describing this. Procedure:
+
+1. Confirm `AI_PROVIDER=anthropic` and `ANTHROPIC_API_KEY` is set in `backend/.env`.
+2. Start the backend with log level INFO or lower.
+3. In the UI, open `/pilot` and send a chat message. Wait a few seconds for the response.
+4. Send a second chat message in the same session, within 5 minutes of the first.
+5. In backend logs, grep for lines containing `anthropic.cache`:
+
+   ```bash
+   # Option A
+   grep 'anthropic.cache' <log-path>
+   # Option B
+   docker compose -f docker-compose.dev.yml logs backend | grep 'anthropic.cache'
+   ```
+
+6. Expected: two `anthropic.cache` log events. First has `cache_creation_input_tokens > 0`. Second has `cache_read_input_tokens > 0`.
+7. If the second shows zero reads, inspect the prompt prefix for silent invalidators (timestamps, unsorted JSON keys, varying tool list ordering). Fix before proceeding with any Phase 2 work.
+
+### 6.4 Frontend build is TypeScript-clean
+
+```bash
+cd frontend
+npx tsc -b        # no errors
+npm run build     # no errors
+```
+
+CLAUDE.md Lesson 105 notes that `npm run build` may fail with an `EACCES` on `dist/` inside code-server — that is a Docker filesystem permission issue, not a real build error. Use `npx tsc -b` to verify TypeScript cleanliness in that case.
+
+### 6.5 `/assistant` → `/pilot` redirect
+
+Open `<DEV_HOST_SCHEME>://<DEV_HOST>:<FRONTEND_PORT>/assistant/<some-real-session-id>` in the browser. Expected: URL changes to `/pilot/<that-id>`; the FlowPilot session page renders. Bare `/assistant` redirects to bare `/pilot`.
+
+### 6.6 Dispatcher de-branching
+
+Navigate to the dashboard. Click a session in `ActiveFlowPilotSessions` or `RecentFlowPilotSessions`. Expected: routes to `/pilot/:id` regardless of the session's `session_type` value. (Check the browser URL bar.)
+
+### 6.7 CORS
+
+Open the browser DevTools Network tab, navigate to any backend-hitting page. Expected: no CORS errors. If you see "blocked by CORS policy," the missing origin needs adding to `backend/.env`'s `CORS_ORIGINS`.
+
+---
+
+## 7. Runbook
+
+Day-to-day commands after setup is complete.
+
+### Restart services
+
+```bash
+# Option A
+# backend — Ctrl-C and re-run uvicorn
+# frontend — Ctrl-C and re-run npm run dev
+
+# Option B
 docker compose -f docker-compose.dev.yml restart backend
+docker compose -f docker-compose.dev.yml up -d --build frontend    # rebuild required if VITE_* changed
+docker compose -f docker-compose.dev.yml down && docker compose -f docker-compose.dev.yml up -d   # full restart
 ```
 
-**Full restart:**
-```bash
-docker compose -f docker-compose.dev.yml down
-docker compose -f docker-compose.dev.yml up -d
-```
-
-## Installed Tools (Inside VS Code Server Container)
-
-Installed in `/home/coder` — persists via Docker volume:
-
-- **nvm** — Node version manager
-- **Node.js 20.x** — via nvm, default alias set
-- **npm** — latest
-- **GitHub CLI (gh)** — authenticated via personal access token
-- **Claude Code CLI** — `@anthropic-ai/claude-code` (global npm)
-
-### Permanent Tool Installs
-
-Tools installed via `apt` inside the container do NOT survive container rebuilds. To add permanently, modify the VS Code Server Docker image and rebuild.
-
-Temporary (session only):
-```bash
-sudo apt update && sudo apt install -y <tool>
-```
-
-## SSH Access
+### Apply a new migration
 
 ```bash
-ssh root@46.202.92.250
+# Option A
+cd backend && source venv/bin/activate && alembic upgrade head
+# Option B
+docker compose -f docker-compose.dev.yml run --rm backend alembic upgrade head
 ```
 
-Key auth configured via `~/.ssh/authorized_keys` on host.
+### Create a new migration
 
-## Useful Commands
-
-### Check all running containers
 ```bash
-docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
+# Option A
+cd backend && source venv/bin/activate
+alembic revision -m "short description"        # manual, preferred per CLAUDE.md Lesson 77
+# OR
+alembic revision --autogenerate -m "description"  # pulls in drift; review carefully
 ```
 
-### View container logs
+Never pass `--rev-id` — let Alembic generate the hex hash.
+
+### Inspect the database
+
 ```bash
-docker logs <container_name> --tail 30 -f
+# Option A (native Postgres)
+psql -h localhost -p 5432 -U postgres -d resolutionflow
+
+# Option B (Docker)
+docker exec -it resolutionflow_postgres psql -U postgres -d resolutionflow
 ```
 
-### Restart VS Code Server
+### Run tests
+
 ```bash
-cd /docker/vscode && docker compose restart
+# Option A
+cd backend && source venv/bin/activate
+pytest --override-ini="addopts="
+
+# Option B
+docker compose -f docker-compose.dev.yml run --rm backend pytest --override-ini="addopts="
 ```
 
-### Restart Traefik
+First time only, create the test database:
+
 ```bash
-cd /docker/traefik && docker compose restart
+# Option A
+sudo -u postgres psql -c "CREATE DATABASE resolutionflow_test;"
+
+# Option B
+docker exec -it resolutionflow_postgres psql -U postgres -c "CREATE DATABASE resolutionflow_test;"
 ```
 
-### Restart dev stack
+### View backend logs
+
 ```bash
-cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
-docker compose -f docker-compose.dev.yml down
-docker compose -f docker-compose.dev.yml up -d
+# Option A: wherever you ran uvicorn
+# Option B
+docker compose -f docker-compose.dev.yml logs -f --tail=100 backend
 ```
 
-### Check swap
+Structured events to grep for:
+- `anthropic.cache` — prompt-cache hit/creation telemetry (Phase 0.1)
+- `mcp.turn` — per-turn MCP availability/invocation (Phase 0.5)
+- `mcp.fallback` — MCP silent-retry fallback fired (Phase 0.5)
+
+---
+
+## 8. Troubleshooting
+
+### CORS errors in the browser
+
+The backend did not accept the origin your browser used. Check `backend/.env`'s `CORS_ORIGINS` — it must include the exact scheme + host + port the browser sent. Restart the backend after editing.
+
+### `VITE_API_URL` points at the wrong place
+
+The frontend was built with a stale value. Rebuild the frontend. Option B: `docker compose up -d --build frontend`. Option A: restart `npm run dev`.
+
+### `alembic upgrade head` fails with "target database is not up to date"
+
+Your DB migration chain is out of sync with the code. On a dev box, the safe recovery is to drop the DB and re-migrate from scratch:
+
 ```bash
-free -h && swapon --show
+# Option A
+sudo -u postgres psql -c "DROP DATABASE resolutionflow;" -c "CREATE DATABASE resolutionflow;"
+cd backend && source venv/bin/activate && alembic upgrade head
+
+# Option B
+docker exec resolutionflow_postgres psql -U postgres -c "DROP DATABASE resolutionflow;" -c "CREATE DATABASE resolutionflow;"
+docker compose -f docker-compose.dev.yml run --rm backend alembic upgrade head
 ```
 
-### Check disk
+Only do this on a dev box — it destroys all local data.
+
+### `alembic heads` shows more than one head
+
+Only on a local branch that has diverged from `origin/main`. Production `main` has a single head. If this happens on a fresh clone, one of your local migration files has the wrong `down_revision`. Inspect each file's `down_revision` and reconnect the chain.
+
+### Frontend build fails with "EACCES: permission denied" on `dist/`
+
+Filesystem permission issue inside the code-server container (CLAUDE.md Lesson 105). TypeScript compilation itself completes — use `npx tsc -b` to verify cleanliness without needing to write to `dist/`.
+
+### Backend/frontend containers start but `/app` is empty (no code mounted)
+
+Almost always a `REPO_ROOT` problem. `docker-compose.dev.yml` uses `${REPO_ROOT}/backend:/app` and `${REPO_ROOT}/frontend:/app` bind mounts. If `REPO_ROOT` is unset, or set to a path that doesn't exist *on the Docker host* (not inside the code-server container), Docker silently creates an empty directory at that path and mounts it — the containers come up but have no source code. Symptom: backend returns import errors, or frontend serves a default Vite page. Fix: set `REPO_ROOT` in the repo-root `.env` to the absolute host-side path to the repo, then `docker compose down && docker compose up -d`. See 5.4 for the full note. This matters specifically when `docker compose` is invoked from inside a container (e.g. code-server with the host Docker socket mounted) — the CLI's CWD is container-local but the daemon resolves paths against the host filesystem.
+
+### Frontend shows "Blocked request. This host is not allowed" in the browser
+
+Vite 5+ ships DNS-rebinding protection that rejects any `Host:` header not in `server.allowedHosts`. The browser's hostname must be in that list. Edit `frontend/vite.config.ts` — the `server.allowedHosts` array should include every hostname you reach the dev server from (e.g. `'docker-01'`, `'localhost'`, `.ts.net` as a wildcard for Tailscale MagicDNS). Restart the Vite dev server (for Option B: `docker compose restart frontend`). This is unrelated to CORS — Vite blocks the request before any app code runs.
+
+### `docker` command not found inside code-server
+
+If your code-server is itself inside a container, Docker is probably not exposed to it. CLAUDE.md Lesson 103 was written for this case on the old VPS. On Proxmox, the fix depends on topology — either SSH to the host to run Docker commands, or mount the host's Docker socket into the code-server container.
+
+### Backend returns 500 with `InsufficientPrivilegeError: new row violates row-level security policy`
+
+RLS is enabled on a table your code wrote to without the right `account_id`. CLAUDE.md Lessons 107, 108, 110 cover this family of bugs. The fix is always at the service layer: make sure every model creation passes `account_id=` explicitly, and that startup routines that touch tenant-isolated tables use `_admin_session_factory()` rather than `get_db()`.
+
+### Anthropic cache reads are zero on the second turn
+
+Something in the cached prefix is changing between turns. Inspect the system-block list and the first N history messages for timestamps, `datetime.now()`, unsorted dict keys in JSON prompts, or varying tool-list order. The `anthropic.cache` telemetry shows exactly how many tokens were read vs created — use it to narrow down the invalidator.
+
+---
+
+## 9. Security posture for dev environments
+
+This doc is about dev, not production. But:
+
+- Never commit `.env` files. The `.gitignore` covers this.
+- `SECRET_KEY` should be generated per-host, not reused across environments.
+- `ANTHROPIC_API_KEY` is billable — rotate if leaked into logs or chat.
+- Postgres on a dev host should not be exposed to the internet. Bind it to `127.0.0.1` or to a private network interface only.
+- If you expose the frontend or backend publicly (for teammates to test against), put it behind TLS with a real certificate. Do not let dev credentials travel over plain HTTP on the public internet.
+
+---
+
+## 10. What's not in this doc
+
+- **Production deployment.** This is a dev-env doc. Production lives on Railway — see `CLAUDE.md`'s Deployment section.
+- **How to set up Traefik or any particular reverse proxy.** Whichever proxy you use is your choice; the dev stack just needs something that routes `<host>:5173` and `<host>:8000` to the right services. **Direct port exposure over a private network** (Tailscale, WireGuard, a VPN, or a LAN behind a firewall) is a fully supported option for dev and is what the homelab reference topology in Section 11 uses — no reverse proxy, no TLS, just `http://<host>:5173` and `http://<host>:8000` reachable only from the private network. That's a perfectly reasonable choice; it's just not the only one.
+- **How to configure code-server itself.** Install it however you prefer (native, Docker, LXC); point it at the repo, and the rest of this doc applies.
+- **Where to host the Proxmox instance.** Up to you.
+
+If something in this doc turns out to be wrong on your host, fix the doc. This is a living document — the whole point of rewriting it from the Hostinger-specific version was to make it survive host changes.
+
+---
+
+## 11. Reference topology: homelab Proxmox + code-server (Option B)
+
+This section documents the first concrete host instantiation since the April 2026 host-agnostic rewrite. It's a worked example, not the canonical topology — Section 3's Option A/B/C framing still stands. If your setup looks different, follow Sections 1–10 and ignore this appendix.
+
+### 11.1 Host
+
+- **Hypervisor:** Proxmox (homelab).
+- **VM:** `docker-01`, Debian 13, running Docker Engine + Docker Compose natively.
+- **Tailscale IP:** `100.64.78.44`. MagicDNS hostname: `docker-01` (and the full `.ts.net` FQDN).
+- **code-server:** runs on the same VM in its own container, with the host's Docker socket mounted in so it can drive `docker compose`. Its workspace bind-mounts the repo at `/opt/docker/code-server/workspace/resolutionflow`.
+
+This is a concrete instance of Option B from Section 3: Postgres, backend, and frontend all run as containers from `docker-compose.dev.yml`; the editor lives outside that compose network.
+
+### 11.2 Access pattern — direct port over Tailscale, no reverse proxy
+
+The browser reaches the dev stack directly:
+
+- Frontend: `http://docker-01:5173`
+- Backend: `http://docker-01:8000`
+- Backend API docs: `http://docker-01:8000/api/docs`
+
+There is **no Caddy, no Traefik, no nginx, no TLS, no basic auth** in front of either service. The tailnet provides the wire encryption and access control — only devices on the tailnet can resolve `docker-01` or reach `100.64.78.44`, and Tailscale ACLs decide which of those devices are allowed to connect.
+
+Why this choice:
+
+- **Zero routing config to maintain.** There is no proxy rulebook to keep in sync with new services. Add a container, expose a port, you're done.
+- **Backend-to-backend services stay private.** Redis, Celery workers, the planned ConnectWise proxy, the MCP server — none of them need to be reachable from the browser, so none of them need proxy rules. They stay inside the `resolutionflow` Docker network and talk by service name. The proxy would only ever have carried frontend and backend traffic, so the proxy's value was small relative to its maintenance cost.
+- **Debuggability.** `curl http://docker-01:8000/api/docs` from any tailnet device works without auth headers, TLS handshakes, or DNS shenanigans.
+
+Tradeoff: **this only works because every client device is on the tailnet.** If someone needed to test from a non-tailnet device, they'd either join the tailnet or we'd need to front the stack with a proxy. For the current single-developer setup, the tailnet-only assumption holds.
+
+### 11.3 Per-host config values (as actually configured on `docker-01`)
+
+Plugging these into Section 4's template:
+
+```
+DEV_HOST              = docker-01
+DEV_HOST_SCHEME       = http
+FRONTEND_PORT         = 5173
+BACKEND_PORT          = 8000
+POSTGRES_PORT         = 5433         # host-side; container-internal stays 5432
+POSTGRES_DB_NAME      = resolutionflow
+POSTGRES_USER         = postgres
+POSTGRES_PASSWORD     = postgres     # local-dev only
+SECRET_KEY            = <generated per host; do not reuse>
+ANTHROPIC_API_KEY     = <from console.anthropic.com>
+GOOGLE_AI_API_KEY     = <unset; Anthropic is sole provider in dev>
+```
+
+And the repo-root `.env` that `docker-compose.dev.yml` interpolates from:
+
 ```bash
-df -h
+SECRET_KEY=<redacted>
+ANTHROPIC_API_KEY=<redacted>
+POSTGRES_PORT=5433
+REPO_ROOT=/opt/docker/code-server/workspace/resolutionflow
 ```
 
-### Check memory + container usage
+### 11.4 Why `REPO_ROOT` is non-optional on this host
+
+code-server runs inside a container. When you open a terminal in code-server and run `docker compose -f docker-compose.dev.yml up -d`, the Docker CLI talks to the *host* daemon via the mounted socket — but the CWD it reports (`/config/workspace/resolutionflow`) is a path that only exists inside the code-server container. The host daemon has never heard of it.
+
+Relative bind mounts like `./backend:/app` therefore resolve against a path the host can't see, and Docker silently creates empty directories there rather than erroring out. The containers come up, but `/app` is empty.
+
+`docker-compose.dev.yml` sidesteps this by using `${REPO_ROOT}/backend:/app` and `${REPO_ROOT}/frontend:/app`. `REPO_ROOT` must be set to the absolute path **on the host** (`/opt/docker/code-server/workspace/resolutionflow`), not the path inside the code-server container. Same contents, different mount point, different name.
+
+If you ever run `docker compose` directly from a host shell (SSH'd into `docker-01`), set `REPO_ROOT` to `.` or the absolute host path. Being explicit is always safe; leaving it unset is the failure mode.
+
+### 11.5 Vite `server.allowedHosts` — required for `docker-01` to resolve
+
+Vite 5+ rejects any `Host:` header not in `server.allowedHosts` (DNS-rebinding protection). `frontend/vite.config.ts` has:
+
+```ts
+server: {
+  host: '0.0.0.0',
+  allowedHosts: ['docker-01', '.ts.net', 'localhost'],
+  ...
+}
+```
+
+- `docker-01` — the MagicDNS short name the browser uses day-to-day.
+- `.ts.net` — wildcard for the full Tailscale MagicDNS FQDN, in case anyone uses it.
+- `localhost` — for the "am I serving anything at all" smoke-test from inside the container.
+
+If you move this setup to a different host, add that host's hostname to `allowedHosts` or the browser will see "Blocked request. This host is not allowed." See Section 8's troubleshooting entry for the full symptom/fix.
+
+### 11.6 CORS origins on this host
+
+The `backend` service's `CORS_ORIGINS` environment variable is pinned in the compose file to:
+
+```
+["http://localhost:5173","http://127.0.0.1:5173","http://docker-01:5173","http://100.64.78.44:5173"]
+```
+
+The last two are what make browser calls from tailnet clients work — they cover both MagicDNS (`docker-01`) and the raw Tailscale IP. If you add a new hostname to reach the frontend from, also add the matching origin here and restart the backend.
+
+### 11.7 Compose file shape (as of this writing)
+
+`docker-compose.dev.yml` has been through a round of cleanup for this topology. Specifics worth knowing if you're comparing against older revisions of the file:
+
+- **No Traefik labels.** They were removed — nothing in this topology uses Traefik.
+- **No Hostinger-VPS-era origins** in `CORS_ORIGINS`.
+- `Dockerfile.dev` for both `backend` and `frontend` is still the build source — this didn't change.
+- Explicit `command:` directives on both `backend` (`uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`) and `frontend` (`npm run dev -- --host 0.0.0.0 --port 5173`) — this guarantees `--host 0.0.0.0` regardless of what's baked into the image, so the services listen on all interfaces and are reachable from outside the container.
+- `REPO_ROOT` is interpolated into both service volume mounts (see 11.4).
+
+If you're adapting the file for a different host, the things most likely to need editing are `REPO_ROOT` (see 11.4), `CORS_ORIGINS` (see 11.6), `FRONTEND_URL`, `VITE_API_URL`, and `POSTGRES_PORT` if you want something other than `5433`.
+
+### 11.8 End-to-end sanity check for this topology
+
+From any device on the tailnet:
+
 ```bash
-free -h && docker stats --no-stream
+# Backend reachable
+curl -sSf http://docker-01:8000/api/docs >/dev/null && echo OK
+
+# Frontend reachable
+curl -sSf http://docker-01:5173 >/dev/null && echo OK
+
+# Alembic head matches the branch expectation
+docker exec resolutionflow_backend alembic current
+# expect f07010f17b01 on feat/flowpilot-migration, 074 on main
+
+# Postgres is alive inside the compose network
+docker exec resolutionflow_postgres psql -U postgres -d resolutionflow -c "SELECT now();"
 ```
 
-## DNS Records (resolutionflow.com)
-
-| Type | Name | Value | Purpose |
-|---|---|---|---|
-| A | code | 46.202.92.250 | VS Code Server |
-
-## Security Notes
-
-- UFW is inactive — Traefik and Docker manage port exposure
-- All public-facing services run through Traefik with valid HTTPS certs
-- PostgreSQL port 5432 is exposed on all interfaces — restrict if needed in production
-- Rotate API keys (Anthropic, Voyage) if ever exposed in logs or chat
-- Never commit `.env` files to Git
-
-## VS Code Server Browser Tips
-
-- **Command Palette:** `F1`
-- **Terminal:** Ctrl+`
-- **Rename file:** `F2`
-- **Go to definition:** `F12`
-- **Find references:** `Shift+F12`
-- **Context Menu:** `Alt + Right Click`
+All four passing = the dev environment is live end-to-end.

backend/alembic/env.py

@@ -29,13 +29,37 @@ from app.models.session_branch import SessionBranch  # noqa: F401
 from app.models.fork_point import ForkPoint  # noqa: F401
 from app.models.session_handoff import SessionHandoff  # noqa: F401
 from app.models.session_resolution_output import SessionResolutionOutput  # noqa: F401
+
 from app.core.config import settings
 
+
+def _alembic_sync_url() -> str:
+    """Return a psycopg2-compatible sync URL for Alembic.
+
+    Priority order:
+    1. DATABASE_URL_SYNC — in Railway this is set as a reference variable
+       (${{pgvector.DATABASE_URL}}) that resolves to the correct postgres
+       superuser credentials for the current environment (production, PR preview,
+       etc.). This always works even on fresh databases before any custom roles
+       have been created, because it uses the postgres superuser.
+    2. ADMIN_DATABASE_URL (resolutionflow_admin, BYPASSRLS) converted to a sync
+       driver — fallback for local dev where DATABASE_URL_SYNC may not be set.
+    """
+    if settings.DATABASE_URL_SYNC:
+        return settings.DATABASE_URL_SYNC
+
+    admin_url = settings.ADMIN_DATABASE_URL
+    if admin_url and "+asyncpg" in admin_url:
+        return admin_url.replace("postgresql+asyncpg://", "postgresql://")
+
+    return settings.DATABASE_URL_SYNC
+
+
 # this is the Alembic Config object
 config = context.config
 
 # Override sqlalchemy.url with the sync version for migrations
-config.set_main_option("sqlalchemy.url", settings.DATABASE_URL_SYNC)
+config.set_main_option("sqlalchemy.url", _alembic_sync_url())
 
 # Interpret the config file for Python logging.
 if config.config_file_name is not None:
@@ -86,7 +110,7 @@ def run_migrations_online() -> None:
     from sqlalchemy import create_engine
 
     connectable = create_engine(
-        settings.DATABASE_URL_SYNC,
+        _alembic_sync_url(),
         poolclass=pool.NullPool,
     )
 

backend/alembic/versions/04f013768235_enable_rls_phase3.py

@@ -0,0 +1,59 @@
+"""Enable RLS on Phase 3 tables.
+
+Tables covered:
+  - step_ratings      (account_id NOT NULL since migration 7167e9374b0c)
+  - step_usage_log    (account_id NOT NULL since migration 7167e9374b0c)
+  - target_lists      (account_id NOT NULL since migration 2c6aabd89bc6)
+  - session_shares    (account_id NOT NULL since session_share model)
+  - audit_logs        (account_id NOT NULL since migration 2a9056eddd90)
+  - tree_shares       (account_id NOT NULL since migration a05e1a1bea7c)
+
+All use a standard intra-tenant isolation policy.
+Token-based access to session_shares and tree_shares goes through
+endpoints that use get_admin_db (BYPASSRLS), so a strict tenant
+policy here is correct.
+
+Revision ID: 04f013768235
+Revises: a05e1a1bea7c
+Create Date: 2026-04-11 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+
+revision: str = '04f013768235'
+down_revision: Union[str, None] = 'a05e1a1bea7c'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_CURRENT_ACCOUNT = (
+    "COALESCE(NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    "'00000000-0000-0000-0000-000000000000')::uuid"
+)
+
+_STANDARD_USING = f"account_id = {_CURRENT_ACCOUNT}"
+
+_PHASE3_TABLES = [
+    "step_ratings",
+    "step_usage_log",
+    "target_lists",
+    "session_shares",
+    "audit_logs",
+    "tree_shares",
+]
+
+
+def upgrade() -> None:
+    for table in _PHASE3_TABLES:
+        op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")
+        op.execute(f"ALTER TABLE {table} FORCE ROW LEVEL SECURITY")
+        op.execute(f"""
+            CREATE POLICY tenant_isolation ON {table}
+                USING ({_STANDARD_USING})
+        """)
+
+
+def downgrade() -> None:
+    for table in _PHASE3_TABLES:
+        op.execute(f"DROP POLICY IF EXISTS tenant_isolation ON {table}")
+        op.execute(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY")
+        op.execute(f"ALTER TABLE {table} NO FORCE ROW LEVEL SECURITY")

backend/alembic/versions/071_add_triage_fields_to_ai_sessions.py

@@ -1,31 +0,0 @@
-"""add triage fields to ai_sessions for cockpit harness
-
-Revision ID: 071
-Revises: 070
-Create Date: 2026-04-01
-"""
-from alembic import op
-import sqlalchemy as sa
-from sqlalchemy.dialects.postgresql import JSONB
-
-
-revision = "071"
-down_revision = "070"
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    op.add_column("ai_sessions", sa.Column("client_name", sa.String(255), nullable=True))
-    op.add_column("ai_sessions", sa.Column("asset_name", sa.String(255), nullable=True))
-    op.add_column("ai_sessions", sa.Column("issue_category", sa.String(100), nullable=True))
-    op.add_column("ai_sessions", sa.Column("triage_hypothesis", sa.Text(), nullable=True))
-    op.add_column("ai_sessions", sa.Column("evidence_items", JSONB(), nullable=True))
-
-
-def downgrade() -> None:
-    op.drop_column("ai_sessions", "evidence_items")
-    op.drop_column("ai_sessions", "triage_hypothesis")
-    op.drop_column("ai_sessions", "issue_category")
-    op.drop_column("ai_sessions", "asset_name")
-    op.drop_column("ai_sessions", "client_name")

backend/alembic/versions/072_seed_flowpilot_cockpit_flag.py

@@ -1,61 +0,0 @@
-"""Seed flowpilot_cockpit feature flag with plan defaults.
-
-Revision ID: 072
-Revises: 071
-Create Date: 2026-04-02
-"""
-from alembic import op
-import sqlalchemy as sa
-
-
-revision = "072"
-down_revision = "071"
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    # Insert the feature flag
-    op.execute(
-        sa.text(
-            "INSERT INTO feature_flags (id, flag_key, display_name, description) "
-            "VALUES (gen_random_uuid(), 'flowpilot_cockpit', 'FlowPilot Cockpit', "
-            "'Access to the FlowPilot Cockpit triage view') "
-            "ON CONFLICT (flag_key) DO NOTHING"
-        )
-    )
-
-    # Set plan defaults: disabled for free, enabled for pro and team
-    op.execute(
-        sa.text(
-            "INSERT INTO plan_feature_defaults (id, plan, flag_id, enabled) "
-            "SELECT gen_random_uuid(), 'free', id, false FROM feature_flags WHERE flag_key = 'flowpilot_cockpit' "
-            "ON CONFLICT (plan, flag_id) DO NOTHING"
-        )
-    )
-    op.execute(
-        sa.text(
-            "INSERT INTO plan_feature_defaults (id, plan, flag_id, enabled) "
-            "SELECT gen_random_uuid(), 'pro', id, true FROM feature_flags WHERE flag_key = 'flowpilot_cockpit' "
-            "ON CONFLICT (plan, flag_id) DO NOTHING"
-        )
-    )
-    op.execute(
-        sa.text(
-            "INSERT INTO plan_feature_defaults (id, plan, flag_id, enabled) "
-            "SELECT gen_random_uuid(), 'team', id, true FROM feature_flags WHERE flag_key = 'flowpilot_cockpit' "
-            "ON CONFLICT (plan, flag_id) DO NOTHING"
-        )
-    )
-
-
-def downgrade() -> None:
-    op.execute(
-        sa.text(
-            "DELETE FROM plan_feature_defaults WHERE flag_id IN "
-            "(SELECT id FROM feature_flags WHERE flag_key = 'flowpilot_cockpit')"
-        )
-    )
-    op.execute(
-        sa.text("DELETE FROM feature_flags WHERE flag_key = 'flowpilot_cockpit'")
-    )

backend/alembic/versions/073_add_device_types_table.py

@@ -1,8 +1,8 @@
-"""Add device_types table with system seed data.
+"""Add account-scoped device_types table with platform seed data.
 
 Revision ID: 073
-Revises: 072
-Create Date: 2026-04-04
+Revises: b3c7e9f2a1d8
+Create Date: 2026-04-12
 """
 from alembic import op
 import sqlalchemy as sa
@@ -11,10 +11,18 @@ import uuid
 
 
 revision = "073"
-down_revision = "072"
+down_revision = "b3c7e9f2a1d8"
 branch_labels = None
 depends_on = None
 
+_PLATFORM_UUID = "00000000-0000-0000-0000-000000000001"
+_CURRENT_ACCOUNT = (
+    "COALESCE("
+    "NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    "'00000000-0000-0000-0000-000000000000'"
+    ")::uuid"
+)
+
 SYSTEM_DEVICE_TYPES = [
     ("router", "Router", "network", 0),
     ("switch", "Switch", "network", 1),
@@ -55,16 +63,13 @@ def upgrade() -> None:
         sa.Column("label", sa.String(100), nullable=False),
         sa.Column("category", sa.String(50), nullable=False),
         sa.Column("is_system", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-        sa.Column("team_id", UUID(as_uuid=True), sa.ForeignKey("teams.id", ondelete="CASCADE"), nullable=True),
+        sa.Column("account_id", UUID(as_uuid=True), sa.ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False),
         sa.Column("sort_order", sa.Integer(), nullable=False, server_default=sa.text("0")),
         sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
     )
 
-    op.execute(
-        "ALTER TABLE device_types ADD CONSTRAINT uq_device_types_slug_team "
-        "UNIQUE NULLS NOT DISTINCT (slug, team_id)"
-    )
-    op.create_index("idx_device_types_team", "device_types", ["team_id"])
+    op.create_unique_constraint("uq_device_types_slug_account", "device_types", ["slug", "account_id"])
+    op.create_index("ix_device_types_account_id", "device_types", ["account_id"])
 
     device_types_table = sa.table(
         "device_types",
@@ -73,7 +78,7 @@ def upgrade() -> None:
         sa.column("label", sa.String),
         sa.column("category", sa.String),
         sa.column("is_system", sa.Boolean),
-        sa.column("team_id", UUID(as_uuid=True)),
+        sa.column("account_id", UUID(as_uuid=True)),
         sa.column("sort_order", sa.Integer),
     )
 
@@ -84,12 +89,44 @@ def upgrade() -> None:
             "label": label,
             "category": category,
             "is_system": True,
-            "team_id": None,
+            "account_id": uuid.UUID(_PLATFORM_UUID),
             "sort_order": sort_order,
         }
         for slug, label, category, sort_order in SYSTEM_DEVICE_TYPES
     ])
 
+    op.execute("ALTER TABLE device_types ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE device_types FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY device_types_select ON device_types
+        FOR SELECT
+        USING (
+            account_id = {_CURRENT_ACCOUNT}
+            OR account_id = '{_PLATFORM_UUID}'::uuid
+        )
+    """)
+    op.execute(f"""
+        CREATE POLICY device_types_insert ON device_types
+        FOR INSERT
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
+    op.execute(f"""
+        CREATE POLICY device_types_update ON device_types
+        FOR UPDATE
+        USING (account_id = {_CURRENT_ACCOUNT})
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
+    op.execute(f"""
+        CREATE POLICY device_types_delete ON device_types
+        FOR DELETE
+        USING (account_id = {_CURRENT_ACCOUNT})
+    """)
+
 
 def downgrade() -> None:
+    op.execute("DROP POLICY IF EXISTS device_types_delete ON device_types")
+    op.execute("DROP POLICY IF EXISTS device_types_update ON device_types")
+    op.execute("DROP POLICY IF EXISTS device_types_insert ON device_types")
+    op.execute("DROP POLICY IF EXISTS device_types_select ON device_types")
+    op.execute("ALTER TABLE device_types DISABLE ROW LEVEL SECURITY")
     op.drop_table("device_types")

backend/alembic/versions/074_add_network_diagrams_table.py

@@ -2,7 +2,7 @@
 
 Revision ID: 074
 Revises: 073
-Create Date: 2026-04-04
+Create Date: 2026-04-12
 """
 from alembic import op
 import sqlalchemy as sa
@@ -14,12 +14,19 @@ down_revision = "073"
 branch_labels = None
 depends_on = None
 
+_CURRENT_ACCOUNT = (
+    "COALESCE("
+    "NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    "'00000000-0000-0000-0000-000000000000'"
+    ")::uuid"
+)
+
 
 def upgrade() -> None:
     op.create_table(
         "network_diagrams",
         sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
-        sa.Column("team_id", UUID(as_uuid=True), sa.ForeignKey("teams.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("account_id", UUID(as_uuid=True), sa.ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False),
         sa.Column("name", sa.String(255), nullable=False),
         sa.Column("client_name", sa.String(255), nullable=True),
         sa.Column("asset_name", sa.String(255), nullable=True),
@@ -33,9 +40,18 @@ def upgrade() -> None:
         sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
     )
 
-    op.create_index("idx_network_diagrams_team", "network_diagrams", ["team_id"])
-    op.create_index("idx_network_diagrams_client", "network_diagrams", ["team_id", "client_name"])
+    op.create_index("ix_network_diagrams_account_id", "network_diagrams", ["account_id"])
+    op.create_index("idx_network_diagrams_account_client", "network_diagrams", ["account_id", "client_name"])
+    op.execute("ALTER TABLE network_diagrams ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE network_diagrams FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON network_diagrams
+        USING (account_id = {_CURRENT_ACCOUNT})
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
 
 
 def downgrade() -> None:
+    op.execute("DROP POLICY IF EXISTS tenant_isolation ON network_diagrams")
+    op.execute("ALTER TABLE network_diagrams DISABLE ROW LEVEL SECURITY")
     op.drop_table("network_diagrams")

backend/alembic/versions/0b470d9e6cf1_create_db_roles.py

@@ -0,0 +1,102 @@
+"""create_db_roles
+
+Revision ID: 0b470d9e6cf1
+Revises: a9f3b2c1d4e5
+Create Date: 2026-04-10 03:58:10.207919
+
+"""
+import os
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import text
+
+
+# revision identifiers, used by Alembic.
+revision: str = '0b470d9e6cf1'
+down_revision: Union[str, None] = 'a9f3b2c1d4e5'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Passwords from env vars. For local dev, defaults are sufficient.
+    # For production (Railway), set DB_APP_ROLE_PASSWORD and
+    # DB_ADMIN_ROLE_PASSWORD as environment variables before running migrations.
+    # Passwords must not contain single quotes.
+    app_pw = os.environ.get("DB_APP_ROLE_PASSWORD", "app_secret_change_me")
+    admin_pw = os.environ.get("DB_ADMIN_ROLE_PASSWORD", "admin_secret_change_me")
+
+    # Fetch the current database name dynamically — avoids hardcoding
+    # (the DB is named 'resolutionflow' in dev, potentially different elsewhere).
+    conn = op.get_bind()
+    db_name = conn.execute(text("SELECT current_database()")).scalar()
+
+    # ── Application role ────────────────────────────────────────────────────
+    # Subject to RLS. Used by FastAPI at runtime via DATABASE_URL.
+    op.execute(f"""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'resolutionflow_app') THEN
+                CREATE ROLE resolutionflow_app LOGIN PASSWORD '{app_pw}';
+            ELSE
+                ALTER ROLE resolutionflow_app LOGIN PASSWORD '{app_pw}';
+            END IF;
+        END $$
+    """)
+    op.execute(f"GRANT CONNECT ON DATABASE {db_name} TO resolutionflow_app")
+    op.execute("GRANT USAGE ON SCHEMA public TO resolutionflow_app")
+    op.execute(
+        "GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public "
+        "TO resolutionflow_app"
+    )
+    op.execute(
+        "GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO resolutionflow_app"
+    )
+    # Ensure future tables automatically get the same permissions
+    op.execute(
+        "ALTER DEFAULT PRIVILEGES IN SCHEMA public "
+        "GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO resolutionflow_app"
+    )
+    op.execute(
+        "ALTER DEFAULT PRIVILEGES IN SCHEMA public "
+        "GRANT USAGE, SELECT ON SEQUENCES TO resolutionflow_app"
+    )
+
+    # ── Admin role ──────────────────────────────────────────────────────────
+    # BYPASSRLS. Used by Alembic (DATABASE_URL_SYNC) and /admin/* endpoints
+    # (ADMIN_DATABASE_URL) after Task 11.
+    op.execute(f"""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'resolutionflow_admin') THEN
+                CREATE ROLE resolutionflow_admin LOGIN PASSWORD '{admin_pw}';
+            ELSE
+                ALTER ROLE resolutionflow_admin LOGIN PASSWORD '{admin_pw}';
+            END IF;
+        END $$
+    """)
+    op.execute("GRANT resolutionflow_app TO resolutionflow_admin")
+    op.execute("ALTER ROLE resolutionflow_admin BYPASSRLS")
+    op.execute(f"GRANT CONNECT ON DATABASE {db_name} TO resolutionflow_admin")
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    db_name = conn.execute(text("SELECT current_database()")).scalar()
+
+    op.execute(
+        "REVOKE ALL ON ALL TABLES IN SCHEMA public FROM resolutionflow_app"
+    )
+    op.execute(
+        "REVOKE ALL ON ALL SEQUENCES IN SCHEMA public FROM resolutionflow_app"
+    )
+    op.execute(
+        f"REVOKE CONNECT ON DATABASE {db_name} FROM resolutionflow_app"
+    )
+    op.execute(
+        f"REVOKE CONNECT ON DATABASE {db_name} FROM resolutionflow_admin"
+    )
+    op.execute("DROP ROLE IF EXISTS resolutionflow_admin")
+    op.execute("DROP ROLE IF EXISTS resolutionflow_app")

backend/alembic/versions/172ad76d7d20_drop_team_id_target_lists.py

@@ -0,0 +1,32 @@
+"""Drop team_id from target_lists.
+
+account_id (NOT NULL) is now the tenant isolation key; team_id is redundant.
+All reads/writes use account_id via RLS + application filter.
+
+Revision ID: 172ad76d7d20
+Revises: 04f013768235
+Create Date: 2026-04-11 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '172ad76d7d20'
+down_revision: Union[str, None] = '04f013768235'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.drop_index('ix_target_lists_team_id', table_name='target_lists', if_exists=True)
+    op.drop_constraint('target_lists_team_id_fkey', 'target_lists', type_='foreignkey')
+    op.drop_column('target_lists', 'team_id')
+
+
+def downgrade() -> None:
+    op.add_column('target_lists', sa.Column('team_id', sa.UUID(), nullable=True))
+    op.create_foreign_key(
+        'target_lists_team_id_fkey', 'target_lists', 'teams',
+        ['team_id'], ['id'], ondelete='CASCADE',
+    )
+    op.create_index('ix_target_lists_team_id', 'target_lists', ['team_id'])

backend/alembic/versions/174f442795b7_set_not_null_account_id_phase1.py

@@ -0,0 +1,86 @@
+"""set NOT NULL on all previously-nullable account_id columns
+
+Revision ID: 174f442795b7
+Revises: 3a40fe11b427
+Create Date: 2026-04-09 00:00:00.000000
+
+All tables in this migration had account_id set to nullable previously.
+Task 9 (create_global_content_tables) cleared all NULL rows.
+This migration enforces the NOT NULL constraint.
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '174f442795b7'
+down_revision: Union[str, None] = '3a40fe11b427'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # tree_embeddings: backfill from trees (must happen before SET NOT NULL)
+    op.execute("""
+        UPDATE tree_embeddings te
+        SET account_id = t.account_id
+        FROM trees t
+        WHERE te.tree_id = t.id
+          AND te.account_id IS NULL
+    """)
+
+    # feedback: backfill from users
+    op.execute("""
+        UPDATE feedback f
+        SET account_id = u.account_id
+        FROM users u
+        WHERE f.user_id = u.id
+          AND f.account_id IS NULL
+    """)
+
+    # Verify ALL tables before touching any SET NOT NULL
+    tables_with_account_id = [
+        'users', 'trees', 'tree_categories', 'tree_tags',
+        'step_categories', 'step_library', 'tree_embeddings', 'feedback',
+    ]
+    for table in tables_with_account_id:
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(
+                f"ROLLBACK: {count} NULL account_id rows in {table}. "
+                "Run Task 9 (create_global_content_tables) first, or "
+                "manually backfill/delete orphaned rows."
+            )
+
+    # SET NOT NULL on all
+    for table in tables_with_account_id:
+        op.alter_column(table, 'account_id', nullable=False)
+
+    # Create indexes where they don't already exist
+    new_indexes = [
+        ('tree_embeddings', 'ix_tree_embeddings_account_id'),
+        ('feedback', 'ix_feedback_account_id'),
+    ]
+    for table, index_name in new_indexes:
+        result = op.get_bind().execute(sa.text(
+            f"SELECT 1 FROM pg_indexes WHERE tablename='{table}' AND indexname='{index_name}'"
+        ))
+        if not result.fetchone():
+            op.create_index(index_name, table, ['account_id'])
+
+
+def downgrade() -> None:
+    # Revert to nullable
+    for table in ('users', 'trees', 'tree_categories', 'tree_tags',
+                  'step_categories', 'step_library', 'tree_embeddings', 'feedback'):
+        op.alter_column(table, 'account_id', nullable=True)
+    for table, index_name in (
+        ('tree_embeddings', 'ix_tree_embeddings_account_id'),
+        ('feedback', 'ix_feedback_account_id'),
+    ):
+        try:
+            op.drop_index(index_name, table_name=table)
+        except Exception:
+            pass

backend/alembic/versions/2a9056eddd90_add_account_id_audit_logs.py

@@ -0,0 +1,51 @@
+"""Add account_id to audit_logs and backfill via user_id.
+
+Revision ID: 2a9056eddd90
+Revises: 70a5dd746e83
+Create Date: 2026-04-11 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '2a9056eddd90'
+down_revision: Union[str, None] = '70a5dd746e83'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('audit_logs', sa.Column('account_id', sa.UUID(), nullable=True))
+    op.create_foreign_key(
+        'fk_audit_logs_account_id', 'audit_logs', 'accounts',
+        ['account_id'], ['id'], ondelete='CASCADE',
+    )
+
+    # Backfill: derive from the acting user's account
+    op.execute("""
+        UPDATE audit_logs al
+        SET account_id = u.account_id
+        FROM users u
+        WHERE al.user_id = u.id
+          AND u.account_id IS NOT NULL
+          AND al.account_id IS NULL
+    """)
+
+    result = op.get_bind().execute(
+        sa.text("SELECT COUNT(*) FROM audit_logs WHERE account_id IS NULL")
+    )
+    count = result.scalar()
+    if count > 0:
+        raise RuntimeError(
+            f"ROLLBACK: {count} audit_logs rows have NULL account_id after backfill. "
+            "All audit log entries must have an associated user with an account."
+        )
+
+    op.alter_column('audit_logs', 'account_id', nullable=False)
+    op.create_index('ix_audit_logs_account_id', 'audit_logs', ['account_id'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_audit_logs_account_id', table_name='audit_logs')
+    op.drop_constraint('fk_audit_logs_account_id', 'audit_logs', type_='foreignkey')
+    op.drop_column('audit_logs', 'account_id')

backend/alembic/versions/2c6aabd89bc6_add_account_id_target_lists.py

@@ -0,0 +1,62 @@
+"""add account_id to target_lists (keep team_id)
+
+Revision ID: 2c6aabd89bc6
+Revises: 78fc200abac1
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '2c6aabd89bc6'
+down_revision: Union[str, None] = '78fc200abac1'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('target_lists', sa.Column('account_id', sa.UUID(), nullable=True))
+    op.create_foreign_key(
+        'fk_target_lists_account_id', 'target_lists', 'accounts',
+        ['account_id'], ['id'], ondelete='CASCADE',
+    )
+
+    # Primary: team_id → team admin user → account_id
+    op.execute("""
+        UPDATE target_lists tl
+        SET account_id = u.account_id
+        FROM users u
+        WHERE u.team_id = tl.team_id
+          AND u.is_team_admin = TRUE
+          AND u.account_id IS NOT NULL
+          AND tl.account_id IS NULL
+    """)
+
+    # Fallback: created_by → users.account_id
+    op.execute("""
+        UPDATE target_lists tl
+        SET account_id = u.account_id
+        FROM users u
+        WHERE tl.created_by = u.id
+          AND u.account_id IS NOT NULL
+          AND tl.account_id IS NULL
+    """)
+
+    result = op.get_bind().execute(
+        sa.text("SELECT COUNT(*) FROM target_lists WHERE account_id IS NULL")
+    )
+    count = result.scalar()
+    if count > 0:
+        raise RuntimeError(
+            f"ROLLBACK: {count} target_lists rows have NULL account_id. "
+            "No team admin found for these teams. Resolve before re-running."
+        )
+
+    op.alter_column('target_lists', 'account_id', nullable=False)
+    op.create_index('ix_target_lists_account_id', 'target_lists', ['account_id'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_target_lists_account_id', table_name='target_lists')
+    op.drop_constraint('fk_target_lists_account_id', 'target_lists', type_='foreignkey')
+    op.drop_column('target_lists', 'account_id')

backend/alembic/versions/3a40fe11b427_create_global_content_tables.py

@@ -0,0 +1,175 @@
+"""create template_trees and platform_steps global content tables
+
+Revision ID: 3a40fe11b427
+Revises: 2c6aabd89bc6
+Create Date: 2026-04-09 00:00:00.000000
+
+These tables hold platform-owned content that is readable by all
+authenticated users. No account_id. No RLS. Ever.
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+revision: str = '3a40fe11b427'
+down_revision: Union[str, None] = '2c6aabd89bc6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ── Create template_trees ─────────────────────────────────────────────────
+    op.create_table(
+        'template_trees',
+        sa.Column('id', UUID(), primary_key=True),
+        sa.Column('name', sa.String(255), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('category', sa.String(100), nullable=True),
+        sa.Column('tree_type', sa.String(20), nullable=False),
+        sa.Column('tree_structure', JSONB(), nullable=False),
+        sa.Column('tags', JSONB(), nullable=False, server_default='[]'),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default='true'),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('source_tree_id', UUID(), sa.ForeignKey('trees.id', ondelete='SET NULL'), nullable=True),
+    )
+    op.create_index('ix_template_trees_tree_type', 'template_trees', ['tree_type'])
+
+    # ── Create platform_steps ────────────────────────────────────────────────
+    op.create_table(
+        'platform_steps',
+        sa.Column('id', UUID(), primary_key=True),
+        sa.Column('title', sa.String(255), nullable=False),
+        sa.Column('step_type', sa.String(50), nullable=False),
+        sa.Column('content', JSONB(), nullable=False),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default='true'),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('source_step_id', UUID(), sa.ForeignKey('step_library.id', ondelete='SET NULL'), nullable=True),
+    )
+    op.create_index('ix_platform_steps_step_type', 'platform_steps', ['step_type'])
+
+    # ── Copy is_default=TRUE trees → template_trees ─────────────────────────
+    # Note: trees.tags is a relationship via tree_tags join table — no direct column.
+    # Aggregate tag names via a correlated subquery.
+    op.execute("""
+        INSERT INTO template_trees
+            (id, name, description, category, tree_type, tree_structure,
+             tags, is_active, created_at, updated_at, source_tree_id)
+        SELECT
+            gen_random_uuid(), t.name, t.description, t.category, t.tree_type,
+            t.tree_structure,
+            COALESCE(
+                (SELECT jsonb_agg(tt.name ORDER BY tt.name)
+                 FROM tree_tag_assignments ta
+                 JOIN tree_tags tt ON tt.id = ta.tag_id
+                 WHERE ta.tree_id = t.id),
+                '[]'::jsonb
+            ),
+            t.is_active,
+            COALESCE(t.created_at, NOW()), COALESCE(t.updated_at, NOW()), t.id
+        FROM trees t
+        WHERE t.is_default = TRUE
+    """)
+
+    # ── Copy visibility='public' steps → platform_steps ─────────────────────
+    op.execute("""
+        INSERT INTO platform_steps
+            (id, title, step_type, content, is_active, created_at, updated_at, source_step_id)
+        SELECT
+            gen_random_uuid(), title, step_type, content, is_active,
+            COALESCE(created_at, NOW()), COALESCE(updated_at, NOW()), id
+        FROM step_library
+        WHERE visibility = 'public'
+    """)
+
+    # ── Create platform sentinel account ─────────────────────────────────────
+    op.execute("""
+        INSERT INTO accounts (id, name, display_code, created_at, updated_at)
+        VALUES (
+            '00000000-0000-0000-0000-000000000001',
+            'ResolutionFlow Platform',
+            'PLATFORM',
+            NOW(),
+            NOW()
+        )
+        ON CONFLICT (id) DO NOTHING
+    """)
+
+    # ── Assign is_default trees to platform account ──────────────────────────
+    op.execute("""
+        UPDATE trees
+        SET account_id = '00000000-0000-0000-0000-000000000001'
+        WHERE is_default = TRUE
+          AND account_id IS NULL
+    """)
+
+    # ── Assign remaining trees to their author's account ─────────────────────
+    # Handles trees with no team_id that aren't is_default (e.g. inactive test
+    # trees, trees created before the team system existed).
+    op.execute("""
+        UPDATE trees
+        SET account_id = u.account_id
+        FROM users u
+        WHERE trees.author_id = u.id
+          AND trees.account_id IS NULL
+          AND u.account_id IS NOT NULL
+    """)
+
+    # ── Final fallback: any still-NULL trees go to platform account ───────────
+    # Covers trees whose author has no account (seeded content, system rows).
+    op.execute("""
+        UPDATE trees
+        SET account_id = '00000000-0000-0000-0000-000000000001'
+        WHERE account_id IS NULL
+    """)
+
+    # ── Assign global categories/tags/steps to platform account ─────────────
+    op.execute("""
+        UPDATE tree_categories
+        SET account_id = '00000000-0000-0000-0000-000000000001'
+        WHERE account_id IS NULL
+    """)
+
+    op.execute("""
+        UPDATE tree_tags
+        SET account_id = '00000000-0000-0000-0000-000000000001'
+        WHERE account_id IS NULL
+    """)
+
+    op.execute("""
+        UPDATE step_categories
+        SET account_id = '00000000-0000-0000-0000-000000000001'
+        WHERE account_id IS NULL
+    """)
+
+    op.execute("""
+        UPDATE step_library
+        SET account_id = '00000000-0000-0000-0000-000000000001'
+        WHERE account_id IS NULL
+    """)
+
+    # ── Verify zero NULLs in all 5 tables ───────────────────────────────────
+    for table in ('trees', 'tree_categories', 'tree_tags', 'step_categories', 'step_library'):
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(
+                f"ROLLBACK: {count} NULL account_id rows remain in {table} "
+                "after platform account assignment. Investigate before re-running."
+            )
+
+
+def downgrade() -> None:
+    platform_id = '00000000-0000-0000-0000-000000000001'
+    for table in ('trees', 'tree_categories', 'tree_tags', 'step_categories', 'step_library'):
+        op.execute(f"UPDATE {table} SET account_id = NULL WHERE account_id = '{platform_id}'")
+
+    op.execute(f"DELETE FROM accounts WHERE id = '{platform_id}'")
+    op.drop_index('ix_platform_steps_step_type', table_name='platform_steps')
+    op.drop_index('ix_template_trees_tree_type', table_name='template_trees')
+    op.drop_table('platform_steps')
+    op.drop_table('template_trees')

backend/alembic/versions/478c159e5654_add_account_id_ai_branching.py

@@ -0,0 +1,77 @@
+"""add account_id to AI branching tables
+
+Revision ID: 478c159e5654
+Revises: cc214c63aa30
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '478c159e5654'
+down_revision: Union[str, None] = 'cc214c63aa30'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    ai_tables = ('session_branches', 'session_handoffs', 'fork_points', 'ai_session_steps')
+
+    # Step 1: ADD COLUMN (nullable)
+    for table in ai_tables:
+        op.add_column(table, sa.Column('account_id', sa.UUID(), nullable=True))
+        op.create_foreign_key(
+            f'fk_{table}_account_id', table, 'accounts',
+            ['account_id'], ['id'], ondelete='CASCADE',
+        )
+
+    op.add_column('ai_suggestions', sa.Column('account_id', sa.UUID(), nullable=True))
+    op.create_foreign_key(
+        'fk_ai_suggestions_account_id', 'ai_suggestions', 'accounts',
+        ['account_id'], ['id'], ondelete='CASCADE',
+    )
+
+    # Step 2: BACKFILL
+    for table in ai_tables:
+        op.execute(f"""
+            UPDATE {table} t
+            SET account_id = ai.account_id
+            FROM ai_sessions ai
+            WHERE t.session_id = ai.id
+              AND t.account_id IS NULL
+        """)
+
+    op.execute("""
+        UPDATE ai_suggestions s
+        SET account_id = u.account_id
+        FROM users u
+        WHERE s.user_id = u.id
+          AND s.account_id IS NULL
+    """)
+
+    # Step 3: VERIFY zero NULLs
+    for table in ai_tables + ('ai_suggestions',):
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(
+                f"ROLLBACK: {count} NULL account_id rows in {table}."
+            )
+
+    # Step 4: SET NOT NULL
+    for table in ai_tables + ('ai_suggestions',):
+        op.alter_column(table, 'account_id', nullable=False)
+
+    # Step 5: CREATE INDEX
+    for table in ai_tables + ('ai_suggestions',):
+        op.create_index(f'ix_{table}_account_id', table, ['account_id'])
+
+
+def downgrade() -> None:
+    for table in ('session_branches', 'session_handoffs', 'fork_points',
+                  'ai_session_steps', 'ai_suggestions'):
+        op.drop_index(f'ix_{table}_account_id', table_name=table)
+        op.drop_constraint(f'fk_{table}_account_id', table, type_='foreignkey')
+        op.drop_column(table, 'account_id')

backend/alembic/versions/6492ec8d2d5b_add_fix_outcome_tracking_columns_to_.py

@@ -0,0 +1,74 @@
+"""add fix outcome tracking columns to session_suggested_fixes
+
+Adds: status, applied_at, verified_at, partial_notes, failure_reason,
+ai_outcome_proposal.
+
+status is the outcome dimension (did the fix work?), orthogonal to the
+existing user_decision column (which script-path the engineer took).
+
+Revision ID: 6492ec8d2d5b
+Revises: f07010f17b01
+Create Date: 2026-04-23 18:32:38.609719
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision: str = '6492ec8d2d5b'
+down_revision: Union[str, None] = 'f07010f17b01'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("status", sa.String(length=20), nullable=False, server_default=sa.text("'proposed'")),
+    )
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("applied_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("verified_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("partial_notes", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("failure_reason", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "session_suggested_fixes",
+        sa.Column("ai_outcome_proposal", postgresql.JSONB(), nullable=True),
+    )
+    # Backfill before constraint creation so dismissed rows satisfy the new CHECK.
+    op.execute(
+        "UPDATE session_suggested_fixes "
+        "SET status = 'dismissed' "
+        "WHERE user_decision = 'dismissed'"
+    )
+    op.create_check_constraint(
+        "ck_session_suggested_fixes_status",
+        "session_suggested_fixes",
+        "status IN ('proposed', 'applied_success', 'applied_failed', 'applied_partial', 'dismissed')",
+    )
+    op.alter_column("session_suggested_fixes", "status", server_default=None)
+
+
+def downgrade() -> None:
+    op.drop_constraint("ck_session_suggested_fixes_status", "session_suggested_fixes", type_="check")
+    op.drop_column("session_suggested_fixes", "ai_outcome_proposal")
+    op.drop_column("session_suggested_fixes", "failure_reason")
+    op.drop_column("session_suggested_fixes", "partial_notes")
+    op.drop_column("session_suggested_fixes", "verified_at")
+    op.drop_column("session_suggested_fixes", "applied_at")
+    op.drop_column("session_suggested_fixes", "status")

backend/alembic/versions/70a5dd746e83_enable_rls_phase2.py

@@ -0,0 +1,90 @@
+"""Enable RLS on Phase 2 session and supporting tables.
+
+10 tables use a standard tenant-only policy.
+step_library uses a visibility-aware policy — public steps visible to all tenants.
+
+NOTE: session_messages does not exist in this codebase (removed from plan).
+script_generations is the correct table name (not script_template_generations).
+sessions and ai_sessions are two separate tables, both in scope.
+
+Prerequisites:
+- Phase 1 migration must have run (resolutionflow_app role exists, Phase 1 tables have RLS)
+- NOT NULL write-path bugs fixed (P2-A commits b641ac6)
+- shares.py cross-tenant session fix deployed (P2-B commit ac2b193)
+
+Revision ID: 70a5dd746e83
+Revises: c5f48b9890f9
+Create Date: 2026-04-10 06:54:49.431817
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = '70a5dd746e83'
+down_revision: Union[str, None] = 'c5f48b9890f9'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_NULL_UUID = "00000000-0000-0000-0000-000000000000"
+_CURRENT_ACCOUNT = (
+    f"COALESCE(NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    f"'{_NULL_UUID}')::uuid"
+)
+
+# Standard tenant-only policy — account_id must match the current tenant.
+# When no tenant context is set, COALESCE returns the nil UUID so zero rows
+# are visible (fail-closed).
+_STANDARD_USING = f"account_id = {_CURRENT_ACCOUNT}"
+
+# Visibility-aware policy for step_library — public steps (visibility='public')
+# must be visible to ALL tenants regardless of account_id. This covers the
+# visibility='public' arm of build_step_visibility_filter() in app/core/filters.py.
+# The created_by arm (private steps visible to their author) is covered
+# transitively: private steps share account_id with their creator, so the
+# account_id match handles it. This relies on account_id NOT NULL on step_library.
+_STEP_LIBRARY_USING = f"account_id = {_CURRENT_ACCOUNT} OR visibility = 'public'"
+
+# Standard tables: strict tenant isolation, no cross-tenant visibility.
+_STANDARD_TABLES = [
+    "sessions",
+    "ai_sessions",
+    "session_branches",
+    "session_supporting_data",
+    "session_resolution_outputs",
+    "session_handoffs",
+    "script_templates",
+    "script_generations",
+    "maintenance_schedules",
+    "psa_post_log",
+]
+
+
+def upgrade() -> None:
+    # ── Standard tenant-isolation tables ────────────────────────────────────
+    for table in _STANDARD_TABLES:
+        op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")
+        op.execute(f"ALTER TABLE {table} FORCE ROW LEVEL SECURITY")
+        op.execute(f"""
+            CREATE POLICY tenant_isolation ON {table}
+                USING ({_STANDARD_USING})
+        """)
+
+    # ── step_library ────────────────────────────────────────────────────────
+    # Public steps (visibility='public') must be readable by all tenants so
+    # the Solutions Library browsing experience works without tenant context.
+    # Private/team steps remain tenant-scoped.
+    op.execute("ALTER TABLE step_library ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE step_library FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON step_library
+            USING ({_STEP_LIBRARY_USING})
+    """)
+
+
+def downgrade() -> None:
+    for table in _STANDARD_TABLES + ["step_library"]:
+        op.execute(f"DROP POLICY IF EXISTS tenant_isolation ON {table}")
+        op.execute(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY")
+        op.execute(f"ALTER TABLE {table} NO FORCE ROW LEVEL SECURITY")

backend/alembic/versions/7167e9374b0c_add_account_id_step_ratings.py

@@ -0,0 +1,46 @@
+"""add account_id to step_ratings and step_usage_log
+
+Revision ID: 7167e9374b0c
+Revises: 478c159e5654
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '7167e9374b0c'
+down_revision: Union[str, None] = '478c159e5654'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    for table in ('step_ratings', 'step_usage_log'):
+        op.add_column(table, sa.Column('account_id', sa.UUID(), nullable=True))
+        op.create_foreign_key(
+            f'fk_{table}_account_id', table, 'accounts',
+            ['account_id'], ['id'], ondelete='CASCADE',
+        )
+        # Backfill: from the RATER/LOGGER user's account (not the step's account)
+        op.execute(f"""
+            UPDATE {table} t
+            SET account_id = u.account_id
+            FROM users u
+            WHERE t.user_id = u.id
+              AND t.account_id IS NULL
+        """)
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(f"ROLLBACK: {count} NULL account_id rows in {table}.")
+        op.alter_column(table, 'account_id', nullable=False)
+        op.create_index(f'ix_{table}_account_id', table, ['account_id'])
+
+
+def downgrade() -> None:
+    for table in ('step_ratings', 'step_usage_log'):
+        op.drop_index(f'ix_{table}_account_id', table_name=table)
+        op.drop_constraint(f'fk_{table}_account_id', table, type_='foreignkey')
+        op.drop_column(table, 'account_id')

backend/alembic/versions/71efd2102f49_add_origin_discriminator_inline_.py

@@ -0,0 +1,70 @@
+"""add origin discriminator + inline idempotency to script_builder_sessions
+
+Adds:
+- origin VARCHAR(20) NOT NULL DEFAULT 'standalone' with CHECK enum
+- invariant: pilot_inline rows must have ai_session_id
+- partial unique index: one pilot_inline session per (user, pilot session)
+
+Revision ID: 71efd2102f49
+Revises: 6492ec8d2d5b
+Create Date: 2026-04-24 04:22:10.819809
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '71efd2102f49'
+down_revision = '6492ec8d2d5b'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "script_builder_sessions",
+        sa.Column(
+            "origin",
+            sa.String(length=20),
+            nullable=False,
+            server_default=sa.text("'standalone'"),
+        ),
+    )
+    op.create_check_constraint(
+        "ck_script_builder_sessions_origin",
+        "script_builder_sessions",
+        "origin IN ('standalone', 'pilot_inline')",
+    )
+    op.create_check_constraint(
+        "ck_script_builder_sessions_origin_ai_session",
+        "script_builder_sessions",
+        "origin <> 'pilot_inline' OR ai_session_id IS NOT NULL",
+    )
+    op.create_index(
+        "ux_script_builder_sessions_pilot_inline",
+        "script_builder_sessions",
+        ["user_id", "ai_session_id"],
+        unique=True,
+        postgresql_where=sa.text("origin = 'pilot_inline'"),
+    )
+    # Drop the server_default — app code owns the default via model default.
+    op.alter_column("script_builder_sessions", "origin", server_default=None)
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ux_script_builder_sessions_pilot_inline",
+        table_name="script_builder_sessions",
+    )
+    op.drop_constraint(
+        "ck_script_builder_sessions_origin_ai_session",
+        "script_builder_sessions",
+        type_="check",
+    )
+    op.drop_constraint(
+        "ck_script_builder_sessions_origin",
+        "script_builder_sessions",
+        type_="check",
+    )
+    op.drop_column("script_builder_sessions", "origin")

backend/alembic/versions/78fc200abac1_add_account_id_script_tables.py

@@ -0,0 +1,103 @@
+"""add account_id to script_builder_sessions, script_templates, script_generations
+
+Revision ID: 78fc200abac1
+Revises: 7f136778f5a8
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '78fc200abac1'
+down_revision: Union[str, None] = '7f136778f5a8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+PLATFORM_ACCOUNT_ID = '00000000-0000-0000-0000-000000000001'
+
+
+def upgrade() -> None:
+    # Ensure the platform sentinel account exists before any fallback assignments.
+    # Migration 3a40fe11b427 also inserts this with ON CONFLICT DO NOTHING — safe.
+    op.execute(f"""
+        INSERT INTO accounts (id, name, display_code, created_at, updated_at)
+        VALUES (
+            '{PLATFORM_ACCOUNT_ID}',
+            'ResolutionFlow Platform',
+            'PLATFORM',
+            NOW(),
+            NOW()
+        )
+        ON CONFLICT (id) DO NOTHING
+    """)
+
+    for table in ('script_builder_sessions', 'script_templates', 'script_generations'):
+        op.add_column(table, sa.Column('account_id', sa.UUID(), nullable=True))
+        op.create_foreign_key(
+            f'fk_{table}_account_id', table, 'accounts',
+            ['account_id'], ['id'], ondelete='CASCADE',
+        )
+
+    # script_builder_sessions: user_id → users.account_id
+    op.execute("""
+        UPDATE script_builder_sessions sbs
+        SET account_id = u.account_id
+        FROM users u
+        WHERE sbs.user_id = u.id
+          AND sbs.account_id IS NULL
+    """)
+
+    # script_templates: created_by → users.account_id (nullable created_by)
+    op.execute("""
+        UPDATE script_templates st
+        SET account_id = u.account_id
+        FROM users u
+        WHERE st.created_by = u.id
+          AND st.account_id IS NULL
+    """)
+    # Fallback: team_id → team admin user
+    op.execute("""
+        UPDATE script_templates st
+        SET account_id = u.account_id
+        FROM users u
+        WHERE u.team_id = st.team_id
+          AND u.is_team_admin = TRUE
+          AND u.account_id IS NOT NULL
+          AND st.account_id IS NULL
+    """)
+    # Final fallback: platform-seeded templates with NULL team_id AND NULL created_by
+    # (e.g. the 6 AD templates inserted by migration 057) → platform sentinel account
+    op.execute(f"""
+        UPDATE script_templates
+        SET account_id = '{PLATFORM_ACCOUNT_ID}'
+        WHERE account_id IS NULL
+    """)
+
+    # script_generations: user_id → users.account_id
+    op.execute("""
+        UPDATE script_generations sg
+        SET account_id = u.account_id
+        FROM users u
+        WHERE sg.user_id = u.id
+          AND sg.account_id IS NULL
+    """)
+
+    # VERIFY
+    for table in ('script_builder_sessions', 'script_templates', 'script_generations'):
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(f"ROLLBACK: {count} NULL account_id rows in {table}.")
+
+    for table in ('script_builder_sessions', 'script_templates', 'script_generations'):
+        op.alter_column(table, 'account_id', nullable=False)
+        op.create_index(f'ix_{table}_account_id', table, ['account_id'])
+
+
+def downgrade() -> None:
+    for table in ('script_builder_sessions', 'script_templates', 'script_generations'):
+        op.drop_index(f'ix_{table}_account_id', table_name=table)
+        op.drop_constraint(f'fk_{table}_account_id', table, type_='foreignkey')
+        op.drop_column(table, 'account_id')

backend/alembic/versions/7f136778f5a8_add_account_id_maintenance.py

@@ -0,0 +1,62 @@
+"""add account_id to maintenance_schedules
+
+Revision ID: 7f136778f5a8
+Revises: 8aac5b372402
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '7f136778f5a8'
+down_revision: Union[str, None] = '8aac5b372402'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('maintenance_schedules',
+                  sa.Column('account_id', sa.UUID(), nullable=True))
+    op.create_foreign_key(
+        'fk_maintenance_schedules_account_id', 'maintenance_schedules', 'accounts',
+        ['account_id'], ['id'], ondelete='CASCADE',
+    )
+
+    # Primary: tree_id → trees.account_id (only where tree.account_id is NOT NULL)
+    op.execute("""
+        UPDATE maintenance_schedules ms
+        SET account_id = t.account_id
+        FROM trees t
+        WHERE ms.tree_id = t.id
+          AND t.account_id IS NOT NULL
+          AND ms.account_id IS NULL
+    """)
+
+    # Fallback: created_by → users.account_id (for is_default trees with NULL account_id)
+    op.execute("""
+        UPDATE maintenance_schedules ms
+        SET account_id = u.account_id
+        FROM users u
+        WHERE ms.created_by = u.id
+          AND u.account_id IS NOT NULL
+          AND ms.account_id IS NULL
+    """)
+
+    result = op.get_bind().execute(
+        sa.text("SELECT COUNT(*) FROM maintenance_schedules WHERE account_id IS NULL")
+    )
+    count = result.scalar()
+    if count > 0:
+        raise RuntimeError(
+            f"ROLLBACK: {count} maintenance_schedules rows have NULL account_id. "
+            "Check if created_by is NULL — those rows need manual resolution."
+        )
+
+    op.alter_column('maintenance_schedules', 'account_id', nullable=False)
+    op.create_index('ix_maintenance_schedules_account_id', 'maintenance_schedules', ['account_id'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_maintenance_schedules_account_id', table_name='maintenance_schedules')
+    op.drop_constraint('fk_maintenance_schedules_account_id', 'maintenance_schedules', type_='foreignkey')
+    op.drop_column('maintenance_schedules', 'account_id')

backend/alembic/versions/8aac5b372402_add_account_id_psa_notifications.py

@@ -0,0 +1,81 @@
+"""add account_id to PSA and notification tables
+
+Revision ID: 8aac5b372402
+Revises: a1d2a84b9abb
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = '8aac5b372402'
+down_revision: Union[str, None] = 'a1d2a84b9abb'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Step 1: ADD COLUMN
+    for table in ('psa_post_log', 'psa_member_mappings', 'notification_logs'):
+        op.add_column(table, sa.Column('account_id', sa.UUID(), nullable=True))
+        op.create_foreign_key(
+            f'fk_{table}_account_id', table, 'accounts',
+            ['account_id'], ['id'], ondelete='CASCADE',
+        )
+
+    # Step 2: BACKFILL
+    # psa_post_log: prefer psa_connection → fallback to posted_by user
+    # Note: cannot reference the updated table (ppl) inside the FROM clause JOIN,
+    # so use a correlated subquery for psa_connections lookup instead.
+    op.execute("""
+        UPDATE psa_post_log ppl
+        SET account_id = COALESCE(
+            (SELECT account_id FROM psa_connections WHERE id = ppl.psa_connection_id),
+            u.account_id
+        )
+        FROM users u
+        WHERE ppl.posted_by = u.id
+          AND ppl.account_id IS NULL
+    """)
+
+    # psa_member_mappings: via psa_connection
+    op.execute("""
+        UPDATE psa_member_mappings pmm
+        SET account_id = pc.account_id
+        FROM psa_connections pc
+        WHERE pmm.psa_connection_id = pc.id
+          AND pmm.account_id IS NULL
+    """)
+
+    # notification_logs: via notification_config
+    op.execute("""
+        UPDATE notification_logs nl
+        SET account_id = nc.account_id
+        FROM notification_configs nc
+        WHERE nl.notification_config_id = nc.id
+          AND nl.account_id IS NULL
+    """)
+
+    # Step 3: VERIFY
+    for table in ('psa_post_log', 'psa_member_mappings', 'notification_logs'):
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(f"ROLLBACK: {count} NULL account_id rows in {table}.")
+
+    # Step 4: SET NOT NULL
+    for table in ('psa_post_log', 'psa_member_mappings', 'notification_logs'):
+        op.alter_column(table, 'account_id', nullable=False)
+
+    # Step 5: CREATE INDEX
+    for table in ('psa_post_log', 'psa_member_mappings', 'notification_logs'):
+        op.create_index(f'ix_{table}_account_id', table, ['account_id'])
+
+
+def downgrade() -> None:
+    for table in ('psa_post_log', 'psa_member_mappings', 'notification_logs'):
+        op.drop_index(f'ix_{table}_account_id', table_name=table)
+        op.drop_constraint(f'fk_{table}_account_id', table, type_='foreignkey')
+        op.drop_column(table, 'account_id')

backend/alembic/versions/a05e1a1bea7c_add_account_id_tree_shares.py

@@ -0,0 +1,57 @@
+"""Add account_id to tree_shares and backfill via tree owner's account.
+
+The share belongs to the tree's tenant, not the actor who created it.
+A super admin in account A can share a tree owned by account B; that share
+must land in account B so account B's RLS filter sees it.
+
+Revision ID: a05e1a1bea7c
+Revises: 2a9056eddd90
+Create Date: 2026-04-11 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'a05e1a1bea7c'
+down_revision: Union[str, None] = '2a9056eddd90'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('tree_shares', sa.Column('account_id', sa.UUID(), nullable=True))
+    op.create_foreign_key(
+        'fk_tree_shares_account_id', 'tree_shares', 'accounts',
+        ['account_id'], ['id'], ondelete='CASCADE',
+    )
+
+    # Backfill: derive from the tree's account, not the creator's account.
+    # A share lives in the same tenant as its tree so that the tree owner's
+    # RLS context covers their own shares regardless of who created them.
+    op.execute("""
+        UPDATE tree_shares ts
+        SET account_id = t.account_id
+        FROM trees t
+        WHERE ts.tree_id = t.id
+          AND t.account_id IS NOT NULL
+          AND ts.account_id IS NULL
+    """)
+
+    result = op.get_bind().execute(
+        sa.text("SELECT COUNT(*) FROM tree_shares WHERE account_id IS NULL")
+    )
+    count = result.scalar()
+    if count > 0:
+        raise RuntimeError(
+            f"ROLLBACK: {count} tree_shares rows have NULL account_id after backfill. "
+            "All share entries must have a creating user with an account."
+        )
+
+    op.alter_column('tree_shares', 'account_id', nullable=False)
+    op.create_index('ix_tree_shares_account_id', 'tree_shares', ['account_id'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_tree_shares_account_id', table_name='tree_shares')
+    op.drop_constraint('fk_tree_shares_account_id', 'tree_shares', type_='foreignkey')
+    op.drop_column('tree_shares', 'account_id')

backend/alembic/versions/a1d2a84b9abb_add_account_id_user_personalization.py

@@ -0,0 +1,45 @@
+"""add account_id to user personalization tables
+
+Revision ID: a1d2a84b9abb
+Revises: 7167e9374b0c
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'a1d2a84b9abb'
+down_revision: Union[str, None] = '7167e9374b0c'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    for table in ('user_folders', 'user_pinned_trees'):
+        op.add_column(table, sa.Column('account_id', sa.UUID(), nullable=True))
+        op.create_foreign_key(
+            f'fk_{table}_account_id', table, 'accounts',
+            ['account_id'], ['id'], ondelete='CASCADE',
+        )
+        op.execute(f"""
+            UPDATE {table} t
+            SET account_id = u.account_id
+            FROM users u
+            WHERE t.user_id = u.id
+              AND t.account_id IS NULL
+        """)
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(f"ROLLBACK: {count} NULL account_id rows in {table}.")
+        op.alter_column(table, 'account_id', nullable=False)
+        op.create_index(f'ix_{table}_account_id', table, ['account_id'])
+
+
+def downgrade() -> None:
+    for table in ('user_folders', 'user_pinned_trees'):
+        op.drop_index(f'ix_{table}_account_id', table_name=table)
+        op.drop_constraint(f'fk_{table}_account_id', table, type_='foreignkey')
+        op.drop_column(table, 'account_id')

backend/alembic/versions/a9f3b2c1d4e5_merge_phase1_with_main.py

@@ -0,0 +1,24 @@
+"""merge Phase 1 tenant isolation chain with main head
+
+Revision ID: a9f3b2c1d4e5
+Revises: 070, 174f442795b7
+Create Date: 2026-04-09 00:00:00.000000
+
+Merge migration: consolidates the Phase 1 account_id chain (cc214c63aa30 → … → 174f442795b7)
+with the main sequential chain (… → 070) into a single head so that
+`alembic upgrade head` works without ambiguity.
+"""
+from typing import Sequence, Union
+
+revision: str = 'a9f3b2c1d4e5'
+down_revision: Union[str, tuple] = ('070', '174f442795b7')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

backend/alembic/versions/b3c7e9f2a1d8_enable_rls_phase4.py

@@ -0,0 +1,85 @@
+"""Enable RLS on Phase 4 tables — all remaining tenant-scoped tables.
+
+All tables in this migration already have account_id NOT NULL (enforced by
+earlier migrations). This migration adds ENABLE ROW LEVEL SECURITY,
+FORCE ROW LEVEL SECURITY, and the appropriate tenant isolation policy to each.
+
+Policy variants used:
+  - Standard:  account_id = current_setting(app.current_account_id)::uuid
+  - Platform:  standard OR account_id = PLATFORM_ACCOUNT_ID
+               (for global content tables readable by all tenants)
+
+Skipped intentionally:
+  - accounts            — IS the root table; no account_id column
+  - plan_feature_defaults — platform config; no account_id column
+  - script_categories   — global lookup table; no account_id column
+  - platform_steps      — global content; no account_id column (readable by all)
+  - template_trees      — global content; no account_id column (readable by all)
+
+Revision ID: b3c7e9f2a1d8
+Revises: 172ad76d7d20
+Create Date: 2026-04-12
+"""
+
+from typing import Union
+from alembic import op
+
+revision: str = "b3c7e9f2a1d8"
+down_revision: Union[str, None] = "172ad76d7d20"
+branch_labels = None
+depends_on = None
+
+# Standard policy — tenant sees only own rows.
+_STANDARD_TABLES = [
+    "users",
+    "account_invites",
+    "account_limit_overrides",
+    "account_feature_overrides",
+    "subscriptions",
+    "ai_chat_sessions",
+    "ai_conversations",
+    "ai_session_steps",
+    "ai_session_embeddings",
+    "ai_suggestions",
+    "ai_usage",
+    "assistant_chats",
+    "attachments",
+    "copilot_conversations",
+    "feedback",
+    "file_uploads",
+    "fork_points",
+    "kb_imports",
+    "notifications",
+    "notification_configs",
+    "notification_logs",
+    "psa_activity_logs",
+    "psa_member_mappings",
+    "script_builder_sessions",
+    "session_ratings",
+    "tree_embeddings",
+    "user_folders",
+    "user_pinned_trees",
+]
+
+_POLICY_EXPR = (
+    "account_id = COALESCE("
+    "NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    "'00000000-0000-0000-0000-000000000000'"
+    ")::uuid"
+)
+
+
+def upgrade() -> None:
+    for table in _STANDARD_TABLES:
+        op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")
+        op.execute(f"ALTER TABLE {table} FORCE ROW LEVEL SECURITY")
+        op.execute(f"""
+            CREATE POLICY tenant_isolation ON {table}
+            USING ({_POLICY_EXPR})
+        """)
+
+
+def downgrade() -> None:
+    for table in _STANDARD_TABLES:
+        op.execute(f"DROP POLICY IF EXISTS tenant_isolation ON {table}")
+        op.execute(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY")

backend/alembic/versions/c5f48b9890f9_enable_rls_phase1.py

@@ -0,0 +1,108 @@
+"""enable_rls_phase1
+
+Revision ID: c5f48b9890f9
+Revises: 0b470d9e6cf1
+Create Date: 2026-04-10 04:01:13.043321
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'c5f48b9890f9'
+down_revision: Union[str, None] = '0b470d9e6cf1'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_NULL_UUID = "00000000-0000-0000-0000-000000000000"
+_PLATFORM_UUID = "00000000-0000-0000-0000-000000000001"
+_CURRENT_ACCOUNT = (
+    f"COALESCE(NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    f"'{_NULL_UUID}')::uuid"
+)
+
+
+def upgrade() -> None:
+    # ── trees ───────────────────────────────────────────────────────────────
+    # Extended policy mirrors can_access_tree() in app/core/permissions.py.
+    # Tenant sees: own rows, platform rows, any default tree, any public tree,
+    # any gallery-featured tree.
+    # is_gallery_featured = TRUE is included because /public/templates is a
+    # no-auth endpoint — no tenant context is set, so gallery trees must pass
+    # RLS on their own flag rather than relying on account_id or is_public.
+    # Private/team trees from other accounts are hidden.
+    op.execute("ALTER TABLE trees ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE trees FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON trees
+            USING (
+                account_id = {_CURRENT_ACCOUNT}
+                OR account_id = '{_PLATFORM_UUID}'::uuid
+                OR is_default = TRUE
+                OR is_public = TRUE
+                OR is_gallery_featured = TRUE
+            )
+    """)
+
+    # ── tree_tags ────────────────────────────────────────────────────────────
+    # Own account + platform tags (global tags visible to all tenants).
+    op.execute("ALTER TABLE tree_tags ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE tree_tags FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON tree_tags
+            USING (
+                account_id = {_CURRENT_ACCOUNT}
+                OR account_id = '{_PLATFORM_UUID}'::uuid
+            )
+    """)
+
+    # ── tree_categories ──────────────────────────────────────────────────────
+    op.execute("ALTER TABLE tree_categories ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE tree_categories FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON tree_categories
+            USING (
+                account_id = {_CURRENT_ACCOUNT}
+                OR account_id = '{_PLATFORM_UUID}'::uuid
+            )
+    """)
+
+    # ── step_categories ──────────────────────────────────────────────────────
+    op.execute("ALTER TABLE step_categories ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE step_categories FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON step_categories
+            USING (
+                account_id = {_CURRENT_ACCOUNT}
+                OR account_id = '{_PLATFORM_UUID}'::uuid
+            )
+    """)
+
+    # ── psa_connections ──────────────────────────────────────────────────────
+    # Tenant-only — PSA credentials must never cross tenant boundaries.
+    op.execute("ALTER TABLE psa_connections ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE psa_connections FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON psa_connections
+            USING (account_id = {_CURRENT_ACCOUNT})
+    """)
+
+    # ── flow_proposals ────────────────────────────────────────────────────────
+    # Tenant-only.
+    op.execute("ALTER TABLE flow_proposals ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE flow_proposals FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON flow_proposals
+            USING (account_id = {_CURRENT_ACCOUNT})
+    """)
+
+
+def downgrade() -> None:
+    for table in ["trees", "tree_tags", "tree_categories", "step_categories",
+                  "psa_connections", "flow_proposals"]:
+        op.execute(f"DROP POLICY IF EXISTS tenant_isolation ON {table}")
+        op.execute(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY")
+        op.execute(f"ALTER TABLE {table} NO FORCE ROW LEVEL SECURITY")

backend/alembic/versions/cc214c63aa30_add_account_id_core_sessions.py

@@ -0,0 +1,95 @@
+"""add account_id to core session tables
+
+Revision ID: cc214c63aa30
+Revises: b8d2f4a6c091
+Create Date: 2026-04-09 00:00:00.000000
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'cc214c63aa30'
+down_revision: Union[str, None] = '064'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = ('067',)
+
+
+def upgrade() -> None:
+    # ── Step 1: ADD COLUMN (nullable) ────────────────────────────────────────
+    for table in ('sessions', 'attachments', 'session_supporting_data',
+                  'session_resolution_outputs'):
+        op.add_column(table, sa.Column('account_id', sa.UUID(), nullable=True))
+        op.create_foreign_key(
+            f'fk_{table}_account_id',
+            table, 'accounts',
+            ['account_id'], ['id'],
+            ondelete='CASCADE',
+        )
+
+    # ── Step 2: BACKFILL ─────────────────────────────────────────────────────
+    # sessions: direct join to users
+    op.execute("""
+        UPDATE sessions s
+        SET account_id = u.account_id
+        FROM users u
+        WHERE s.user_id = u.id
+          AND s.account_id IS NULL
+    """)
+
+    # attachments: chain through sessions (now backfilled above)
+    op.execute("""
+        UPDATE attachments a
+        SET account_id = s.account_id
+        FROM sessions s
+        WHERE a.session_id = s.id
+          AND a.account_id IS NULL
+    """)
+
+    # session_supporting_data: same chain
+    op.execute("""
+        UPDATE session_supporting_data sd
+        SET account_id = s.account_id
+        FROM sessions s
+        WHERE sd.session_id = s.id
+          AND sd.account_id IS NULL
+    """)
+
+    # session_resolution_outputs: FK is to ai_sessions, not sessions
+    op.execute("""
+        UPDATE session_resolution_outputs sro
+        SET account_id = ai.account_id
+        FROM ai_sessions ai
+        WHERE sro.session_id = ai.id
+          AND sro.account_id IS NULL
+    """)
+
+    # ── Step 3: VERIFY zero NULLs — raises if any remain ────────────────────
+    for table in ('sessions', 'attachments', 'session_supporting_data',
+                  'session_resolution_outputs'):
+        result = op.get_bind().execute(
+            sa.text(f"SELECT COUNT(*) FROM {table} WHERE account_id IS NULL")
+        )
+        count = result.scalar()
+        if count > 0:
+            raise RuntimeError(
+                f"ROLLBACK: {count} NULL account_id rows remain in {table}. "
+                f"Fix the backfill before re-running."
+            )
+
+    # ── Step 4: SET NOT NULL ─────────────────────────────────────────────────
+    for table in ('sessions', 'attachments', 'session_supporting_data',
+                  'session_resolution_outputs'):
+        op.alter_column(table, 'account_id', nullable=False)
+
+    # ── Step 5: CREATE INDEX ─────────────────────────────────────────────────
+    for table in ('sessions', 'attachments', 'session_supporting_data',
+                  'session_resolution_outputs'):
+        op.create_index(f'ix_{table}_account_id', table, ['account_id'])
+
+
+def downgrade() -> None:
+    for table in ('sessions', 'attachments', 'session_supporting_data',
+                  'session_resolution_outputs'):
+        op.drop_index(f'ix_{table}_account_id', table_name=table)
+        op.drop_constraint(f'fk_{table}_account_id', table, type_='foreignkey')
+        op.drop_column(table, 'account_id')

backend/alembic/versions/f07010f17b01_flowpilot_phase1_schema.py

@@ -0,0 +1,404 @@
+"""FlowPilot migration Phase 1 — schema for the unified session surface.
+
+Revision ID: f07010f17b01
+Revises: 074
+Create Date: 2026-04-17
+
+Creates the backing store for the FlowPilot unified session surface:
+
+- `session_facts` — "What we know" facts, keyed to a session, with a polymorphic
+  `source_ref` pointing at a task-lane item inside `ai_sessions.pending_task_lane`
+  (no DB-level FK; integrity enforced at the service layer per the design doc).
+- `session_suggested_fixes` — AI-proposed resolution paths. Only one active
+  (`superseded_at IS NULL`) per session at a time.
+- `draft_templates` — scripts pending post-resolve templatization
+  (Option 2 in the three-option dialog).
+- `account_settings` — new per-account key/value settings table with a JSONB
+  `preferences` grab-bag. Rows are created lazily on first write.
+- Column additions to `ai_sessions` — resolution/escalation markdown + external IDs,
+  plus `state_version` (incremented by any write that invalidates the resolution
+  note preview cache).
+- Column additions to `script_templates` — provenance fields for templates
+  promoted from draft_templates.
+
+All four new tenant-scoped tables have RLS enabled + forced with a
+`tenant_isolation` policy matching the repo pattern (USING + WITH CHECK on
+`account_id = app.current_account_id`). Downgrade is reversible: drops in the
+inverse order of creation.
+
+Chained from `074` (add_network_diagrams_table) per the single-head state of
+production; the other local heads on feat/flowpilot-migration are branch
+artifacts not present in production.
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+
+revision = "f07010f17b01"
+down_revision = "074"
+branch_labels = None
+depends_on = None
+
+
+_CURRENT_ACCOUNT = (
+    "COALESCE("
+    "NULLIF(current_setting('app.current_account_id', TRUE), ''), "
+    "'00000000-0000-0000-0000-000000000000'"
+    ")::uuid"
+)
+
+
+def upgrade() -> None:
+    # ── ai_sessions: resolution / escalation columns + state_version ───────
+    op.add_column(
+        "ai_sessions",
+        sa.Column("resolution_note_markdown", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "ai_sessions",
+        sa.Column("resolution_note_posted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "ai_sessions",
+        sa.Column("resolution_note_external_id", sa.String(128), nullable=True),
+    )
+    op.add_column(
+        "ai_sessions",
+        sa.Column("escalation_package_markdown", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "ai_sessions",
+        sa.Column("escalation_package_posted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "ai_sessions",
+        sa.Column("escalation_package_external_id", sa.String(128), nullable=True),
+    )
+    op.add_column(
+        "ai_sessions",
+        sa.Column(
+            "state_version",
+            sa.Integer(),
+            nullable=False,
+            server_default=sa.text("0"),
+        ),
+    )
+
+    # ── script_templates: provenance for post-resolve promotion ────────────
+    op.add_column(
+        "script_templates",
+        sa.Column(
+            "source_session_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("ai_sessions.id"),
+            nullable=True,
+        ),
+    )
+    op.add_column(
+        "script_templates",
+        sa.Column(
+            "source_user_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("users.id"),
+            nullable=True,
+        ),
+    )
+    op.add_column(
+        "script_templates",
+        sa.Column("source_ticket_ref", sa.String(64), nullable=True),
+    )
+
+    # ── session_facts ──────────────────────────────────────────────────────
+    op.create_table(
+        "session_facts",
+        sa.Column(
+            "id",
+            UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "session_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("ai_sessions.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "account_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("accounts.id"),
+            nullable=False,
+        ),
+        sa.Column("text", sa.Text(), nullable=False),
+        sa.Column("source_type", sa.String(32), nullable=False),
+        # `source_ref` is a polymorphic pointer to a task-lane item inside
+        # ai_sessions.pending_task_lane JSON, NOT a FK to any table.
+        # Integrity enforced at the service layer per Section 4.2 of the
+        # migration design doc.
+        sa.Column("source_ref", UUID(as_uuid=True), nullable=True),
+        sa.Column("source_summary", sa.Text(), nullable=True),
+        sa.Column(
+            "created_by",
+            UUID(as_uuid=True),
+            sa.ForeignKey("users.id"),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.CheckConstraint(
+            "source_type IN ('question', 'diagnostic_check', 'user_note', 'ai_synthesis')",
+            name="ck_session_facts_source_type",
+        ),
+    )
+    # Active-facts-per-session; partial index excludes soft-deleted rows.
+    op.create_index(
+        "idx_session_facts_session",
+        "session_facts",
+        ["session_id"],
+        postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+    op.create_index(
+        "idx_session_facts_account",
+        "session_facts",
+        ["account_id"],
+    )
+    op.execute("ALTER TABLE session_facts ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE session_facts FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON session_facts
+        USING (account_id = {_CURRENT_ACCOUNT})
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
+
+    # ── session_suggested_fixes ────────────────────────────────────────────
+    op.create_table(
+        "session_suggested_fixes",
+        sa.Column(
+            "id",
+            UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "session_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("ai_sessions.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "account_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("accounts.id"),
+            nullable=False,
+        ),
+        sa.Column("title", sa.String(200), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("confidence_pct", sa.Integer(), nullable=False),
+        sa.Column(
+            "script_template_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("script_templates.id"),
+            nullable=True,
+        ),
+        sa.Column("ai_drafted_script", sa.Text(), nullable=True),
+        sa.Column("ai_drafted_parameters", JSONB(), nullable=True),
+        sa.Column("user_decision", sa.String(32), nullable=True),
+        sa.Column("superseded_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.CheckConstraint(
+            "confidence_pct BETWEEN 0 AND 100",
+            name="ck_session_suggested_fixes_confidence_pct",
+        ),
+        sa.CheckConstraint(
+            "user_decision IS NULL OR user_decision IN ("
+            "'one_off', 'draft_template', 'build_template', 'dismissed')",
+            name="ck_session_suggested_fixes_user_decision",
+        ),
+    )
+    # Only-one-active-per-session is enforced by service-layer supersession;
+    # this partial index serves the "find active fix" query.
+    op.create_index(
+        "idx_session_suggested_fixes_session_active",
+        "session_suggested_fixes",
+        ["session_id"],
+        postgresql_where=sa.text("superseded_at IS NULL"),
+    )
+    op.execute("ALTER TABLE session_suggested_fixes ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE session_suggested_fixes FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON session_suggested_fixes
+        USING (account_id = {_CURRENT_ACCOUNT})
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
+
+    # ── draft_templates ────────────────────────────────────────────────────
+    op.create_table(
+        "draft_templates",
+        sa.Column(
+            "id",
+            UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "account_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("accounts.id"),
+            nullable=False,
+        ),
+        sa.Column(
+            "source_session_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("ai_sessions.id"),
+            nullable=False,
+        ),
+        sa.Column(
+            "source_user_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("users.id"),
+            nullable=False,
+        ),
+        sa.Column("script_body", sa.Text(), nullable=False),
+        sa.Column("proposed_parameters", JSONB(), nullable=False),
+        sa.Column("proposed_name", sa.String(200), nullable=True),
+        sa.Column(
+            "proposed_category_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("script_categories.id"),
+            nullable=True,
+        ),
+        sa.Column(
+            "status",
+            sa.String(32),
+            nullable=False,
+            server_default=sa.text("'pending'"),
+        ),
+        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "promoted_template_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("script_templates.id"),
+            nullable=True,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.CheckConstraint(
+            "status IN ('pending', 'accepted', 'rejected')",
+            name="ck_draft_templates_status",
+        ),
+    )
+    # Supports the Script Library "N scripts ready to review" badge.
+    op.create_index(
+        "idx_draft_templates_account_pending",
+        "draft_templates",
+        ["account_id"],
+        postgresql_where=sa.text("status = 'pending'"),
+    )
+    op.execute("ALTER TABLE draft_templates ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE draft_templates FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON draft_templates
+        USING (account_id = {_CURRENT_ACCOUNT})
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
+
+    # ── account_settings ───────────────────────────────────────────────────
+    # One row per account, created lazily on first write. The `preferences`
+    # JSONB is a grab-bag for simple settings (e.g. templatize_prompt_enabled).
+    # Settings graduate to typed columns via future migrations when they meet
+    # the promotion criteria in Section 4.6 of the design doc (hot path /
+    # validation / joins).
+    op.create_table(
+        "account_settings",
+        sa.Column(
+            "account_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("accounts.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column(
+            "preferences",
+            JSONB(),
+            nullable=False,
+            server_default=sa.text("'{}'::jsonb"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    op.execute("ALTER TABLE account_settings ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE account_settings FORCE ROW LEVEL SECURITY")
+    op.execute(f"""
+        CREATE POLICY tenant_isolation ON account_settings
+        USING (account_id = {_CURRENT_ACCOUNT})
+        WITH CHECK (account_id = {_CURRENT_ACCOUNT})
+    """)
+
+
+def downgrade() -> None:
+    # Drop in reverse order so FK dependencies unwind cleanly.
+    op.execute("DROP POLICY IF EXISTS tenant_isolation ON account_settings")
+    op.execute("ALTER TABLE account_settings DISABLE ROW LEVEL SECURITY")
+    op.drop_table("account_settings")
+
+    op.execute("DROP POLICY IF EXISTS tenant_isolation ON draft_templates")
+    op.execute("ALTER TABLE draft_templates DISABLE ROW LEVEL SECURITY")
+    op.drop_index("idx_draft_templates_account_pending", table_name="draft_templates")
+    op.drop_table("draft_templates")
+
+    op.execute("DROP POLICY IF EXISTS tenant_isolation ON session_suggested_fixes")
+    op.execute("ALTER TABLE session_suggested_fixes DISABLE ROW LEVEL SECURITY")
+    op.drop_index(
+        "idx_session_suggested_fixes_session_active",
+        table_name="session_suggested_fixes",
+    )
+    op.drop_table("session_suggested_fixes")
+
+    op.execute("DROP POLICY IF EXISTS tenant_isolation ON session_facts")
+    op.execute("ALTER TABLE session_facts DISABLE ROW LEVEL SECURITY")
+    op.drop_index("idx_session_facts_account", table_name="session_facts")
+    op.drop_index("idx_session_facts_session", table_name="session_facts")
+    op.drop_table("session_facts")
+
+    op.drop_column("script_templates", "source_ticket_ref")
+    op.drop_column("script_templates", "source_user_id")
+    op.drop_column("script_templates", "source_session_id")
+
+    op.drop_column("ai_sessions", "state_version")
+    op.drop_column("ai_sessions", "escalation_package_external_id")
+    op.drop_column("ai_sessions", "escalation_package_posted_at")
+    op.drop_column("ai_sessions", "escalation_package_markdown")
+    op.drop_column("ai_sessions", "resolution_note_external_id")
+    op.drop_column("ai_sessions", "resolution_note_posted_at")
+    op.drop_column("ai_sessions", "resolution_note_markdown")

backend/app/api/deps.py

@@ -10,6 +10,8 @@ from app.core.database import get_db
 from app.core.security import decode_token
 from app.models.user import User
 from app.models.plan_limits import PlanLimits
+from app.core.tenant_context import set_current_account_id, clear_current_account_id
+from app.core.admin_database import get_admin_db  # noqa: F401 — re-exported for use in endpoints
 
 # Routes that are allowed even when must_change_password is True
 _PASSWORD_CHANGE_ALLOWLIST = {
@@ -22,10 +24,14 @@ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
 
 
 async def get_current_user(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     token: Annotated[str, Depends(oauth2_scheme)]
 ) -> User:
-    """Get current authenticated user from JWT token."""
+    """Get current authenticated user from JWT token.
+
+    Must use get_admin_db (BYPASSRLS): this dep runs before require_tenant_context
+    sets app.current_account_id, so the users table RLS would block the lookup.
+    """
     credentials_exception = HTTPException(
         status_code=status.HTTP_401_UNAUTHORIZED,
         detail="Could not validate credentials",
@@ -75,10 +81,14 @@ async def get_refresh_token_payload(
 async def get_current_active_user(
     request: Request,
     current_user: Annotated[User, Depends(get_current_user)],
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
 ) -> User:
     """Ensure user is active (not disabled). Auto-downgrades expired trials.
-    Enforces must_change_password — blocks all routes except allowlist."""
+    Enforces must_change_password — blocks all routes except allowlist.
+
+    Uses get_admin_db: runs before require_tenant_context sets the ContextVar,
+    so tenant-scoped tables (subscriptions) would return 0 rows via app role.
+    """
     if not current_user.is_active:
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
@@ -190,3 +200,44 @@ async def get_plan_limits_for_user(
     """Get plan limits for the current user's account."""
     from app.core.subscriptions import get_user_plan_limits
     return await get_user_plan_limits(current_user.account_id, db)
+
+
+async def require_tenant_context(
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Set per-request tenant context for RLS.
+
+    Raises 403 if the authenticated user has no account_id — never falls back
+    to PLATFORM_ACCOUNT_ID (that would grant platform-scope access to a
+    malformed account).
+
+    Sets the ContextVar that the SQLAlchemy transaction-begin listener reads to
+    issue set_config('app.current_account_id', …, true) on every transaction.
+
+    Applied to every user-facing router. NOT applied to /admin/* routers or
+    public endpoints (auth, shared, webhooks).
+    """
+    if current_user.account_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account required",
+        )
+    token = set_current_account_id(current_user.account_id)
+    try:
+        yield
+    finally:
+        clear_current_account_id(token)
+
+
+async def require_admin_db(
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+    current_user: Annotated[User, Depends(require_admin)],
+) -> AsyncSession:
+    """Return a BYPASSRLS admin DB session after verifying super_admin role.
+
+    Use on /admin/* endpoints that query RLS-protected tables. Replaces
+    Depends(get_db) on the db parameter of those endpoints.
+    The current_user dep is still declared separately on the endpoint if
+    the user object is needed in the handler.
+    """
+    return db

backend/app/api/endpoints/accounts.py

@@ -9,12 +9,14 @@ from sqlalchemy import select
 
 from pydantic import BaseModel
 from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.core.subscriptions import get_account_subscription, get_plan_limits, get_account_usage
 from app.core.audit import log_audit
 from app.models.refresh_token import RefreshToken
 from app.core.email import EmailService
 from app.models.account import Account
 from app.models.account_invite import AccountInvite
+from app.models.account_settings import AccountSettings
 from app.models.subscription import Subscription
 from app.models.user import User
 from app.schemas.account import AccountResponse, AccountUpdate, AccountInviteCreate, AccountInviteResponse, TransferOwnershipRequest
@@ -148,7 +150,7 @@ async def update_member_role(
 @router.post("/me/transfer-ownership", response_model=AccountResponse)
 async def transfer_ownership(
     data: TransferOwnershipRequest,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_account_owner)]
 ):
     """Transfer account ownership to another member (owner only)."""
@@ -377,7 +379,7 @@ async def list_invites(
 
 @router.post("/me/leave")
 async def leave_account(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(get_current_active_user)]
 ):
     """Leave the current account (non-owners only). Creates a personal account."""
@@ -423,7 +425,7 @@ class DeleteAccountRequest(BaseModel):
 @router.delete("/me")
 async def delete_account(
     data: DeleteAccountRequest,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_account_owner)]
 ):
     """Delete the current account and soft-delete the user (owner only, no other members)."""
@@ -558,3 +560,65 @@ async def get_sso_status(
         sso_enabled=account.sso_enabled,
         sso_provider=account.sso_provider,
     )
+
+
+# ─── Account Preferences (FlowPilot Phase 6) ──────────────────────────────────
+#
+# Preferences live in `account_settings.preferences` as a JSONB grab-bag
+# (per FLOWPILOT-MIGRATION.md Section 4.6). Rows are lazily created on first
+# write. Any engineer-role user can read + update preferences because the
+# keys stored here (templatize_prompt_enabled, cw_resolved_status_id, etc.)
+# are team-level toggles rather than account-owner-gated admin settings.
+
+
+class AccountPreferencesResponse(BaseModel):
+    preferences: dict
+
+
+class AccountPreferencesUpdate(BaseModel):
+    """Merge-style update — each key in `preferences` overwrites that key in
+    the stored JSONB, other keys are preserved. Omit the body entirely to
+    no-op.
+    """
+    preferences: dict
+
+
+@router.get("/me/preferences", response_model=AccountPreferencesResponse)
+async def get_my_preferences(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Return the current account's preferences JSONB (empty dict if no row)."""
+    result = await db.execute(
+        select(AccountSettings.preferences).where(
+            AccountSettings.account_id == current_user.account_id
+        )
+    )
+    prefs = result.scalar_one_or_none() or {}
+    return AccountPreferencesResponse(preferences=prefs)
+
+
+@router.patch("/me/preferences", response_model=AccountPreferencesResponse)
+async def update_my_preferences(
+    data: AccountPreferencesUpdate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+):
+    """Upsert preference keys. Existing keys not present in the payload are kept.
+
+    Example: posting `{"preferences": {"templatize_prompt_enabled": false}}`
+    from the post-resolve "Don't ask me again for this team" checkbox sets
+    just that key without clobbering any other preferences.
+    """
+    for key, value in data.preferences.items():
+        await AccountSettings.set_setting(db, current_user.account_id, key, value)
+    await db.commit()
+
+    # Return the merged state so the client doesn't need a second GET.
+    result = await db.execute(
+        select(AccountSettings.preferences).where(
+            AccountSettings.account_id == current_user.account_id
+        )
+    )
+    prefs = result.scalar_one_or_none() or {}
+    return AccountPreferencesResponse(preferences=prefs)

backend/app/api/endpoints/admin.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func, or_
 from sqlalchemy.orm import selectinload, aliased
 
-from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.core.audit import log_audit
 from app.core.config import settings
 from app.core.security import get_password_hash, generate_temp_password, create_password_reset_token, decode_token, hash_token
@@ -57,7 +57,7 @@ router = APIRouter(prefix="/admin", tags=["admin"])
 
 @router.get("/users", response_model=AdminUserListResponse)
 async def list_users(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
     page: Optional[int] = Query(None, ge=1),
     size: Optional[int] = Query(None, ge=1, le=100),
@@ -153,7 +153,7 @@ async def list_users(
 
 @router.get("/accounts", response_model=AdminAccountListResponse)
 async def list_accounts(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
     page: int = Query(1, ge=1),
     size: int = Query(12, ge=1, le=100),
@@ -427,14 +427,23 @@ async def _get_account_detail_payload(
 @router.post("/accounts", response_model=AdminAccountDetailResponse, status_code=status.HTTP_201_CREATED)
 async def create_account(
     data: AdminAccountCreate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Create a new account without requiring an initial user."""
+    owner_id = None
+    if data.owner_email:
+        result = await db.execute(select(User).where(User.email == data.owner_email.strip()))
+        owner = result.scalar_one_or_none()
+        if not owner:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"No user found with email '{data.owner_email}'")
+        owner_id = owner.id
+
     display_code = await _generate_unique_display_code(db)
     new_account = Account(
         name=data.name.strip(),
         display_code=display_code,
+        owner_id=owner_id,
     )
     db.add(new_account)
     await db.flush()
@@ -448,7 +457,7 @@ async def create_account(
 
     await log_audit(
         db, current_user.id, "account.create_admin", "account", new_account.id,
-        {"name": new_account.name, "plan": data.plan},
+        {"name": new_account.name, "plan": data.plan, "owner_email": data.owner_email},
     )
     await db.commit()
     return await _get_account_detail_payload(new_account.id, db)
@@ -457,7 +466,7 @@ async def create_account(
 @router.get("/accounts/{account_id}", response_model=AdminAccountDetailResponse)
 async def get_account_detail(
     account_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
     include_archived: bool = Query(False),
 ):
@@ -469,7 +478,7 @@ async def get_account_detail(
 async def update_account(
     account_id: UUID,
     data: AdminAccountUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Update account settings from the admin panel."""
@@ -491,7 +500,7 @@ async def update_account(
 @router.post("/users", response_model=AdminUserCreateResponse, status_code=status.HTTP_201_CREATED)
 async def create_user(
     data: AdminUserCreate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Create a new user with a temporary password (super admin only).
@@ -616,7 +625,7 @@ async def create_user(
 @router.get("/users/{user_id}", response_model=UserDetailResponse)
 async def get_user(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)]
 ):
     """Get enriched user details (super admin only)."""
@@ -734,7 +743,7 @@ async def get_user(
 async def update_user_role(
     user_id: UUID,
     role_data: RoleUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)]
 ):
     """Change user role (super admin only)."""
@@ -766,7 +775,7 @@ async def update_user_role(
 async def update_account_role(
     user_id: UUID,
     data: AccountRoleUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)]
 ):
     """Change a user's account role (super admin only)."""
@@ -792,7 +801,7 @@ async def update_account_role(
 async def update_super_admin_status(
     user_id: UUID,
     data: dict,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)]
 ):
     """Promote or demote a user to/from super admin (super admin only)."""
@@ -831,7 +840,7 @@ async def update_super_admin_status(
 @router.put("/users/{user_id}/deactivate", response_model=UserResponse)
 async def deactivate_user(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)]
 ):
     """Deactivate a user account (super admin only)."""
@@ -860,7 +869,7 @@ async def deactivate_user(
 @router.put("/users/{user_id}/activate", response_model=UserResponse)
 async def activate_user(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)]
 ):
     """Reactivate a user account (super admin only)."""
@@ -884,7 +893,7 @@ async def activate_user(
 async def move_user_account(
     user_id: UUID,
     data: MoveUserAccount,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Move a user to a different account (super admin only)."""
@@ -959,7 +968,7 @@ async def _get_account_subscription(account_id: UUID, db: AsyncSession) -> tuple
 async def update_user_plan(
     user_id: UUID,
     data: SubscriptionPlanUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Change a user's subscription plan (super admin only)."""
@@ -978,7 +987,7 @@ async def update_user_plan(
 async def update_account_plan(
     account_id: UUID,
     data: SubscriptionPlanUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Change an account subscription plan (super admin only)."""
@@ -1003,7 +1012,7 @@ async def update_account_plan(
 async def extend_user_trial(
     user_id: UUID,
     data: ExtendTrialRequest,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Extend or start a trial for a user's subscription (super admin only)."""
@@ -1033,7 +1042,7 @@ async def extend_user_trial(
 async def extend_account_trial(
     account_id: UUID,
     data: ExtendTrialRequest,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Extend or start a trial for an account subscription (super admin only)."""
@@ -1070,7 +1079,7 @@ async def extend_account_trial(
 async def admin_reset_password(
     user_id: UUID,
     data: AdminPasswordReset,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Admin-triggered password reset (super admin only).
@@ -1141,7 +1150,7 @@ async def admin_reset_password(
 @router.put("/users/{user_id}/archive", response_model=UserResponse)
 async def archive_user(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Archive (soft delete) a user (super admin only)."""
@@ -1176,7 +1185,7 @@ async def archive_user(
 @router.put("/users/{user_id}/restore", response_model=UserResponse)
 async def restore_user(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Restore an archived user (super admin only)."""
@@ -1201,7 +1210,7 @@ async def restore_user(
 @router.get("/users/{user_id}/hard-delete-check", response_model=HardDeleteCheckResponse)
 async def hard_delete_check(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Check if a user can be hard-deleted (super admin only). Returns blockers."""
@@ -1274,7 +1283,7 @@ async def hard_delete_check(
 @router.delete("/users/{user_id}/hard-delete", status_code=status.HTTP_204_NO_CONTENT)
 async def hard_delete_user(
     user_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Permanently delete a user (super admin only). User must be archived first."""
@@ -1334,7 +1343,7 @@ async def hard_delete_user(
 @router.post("/invites", status_code=status.HTTP_201_CREATED)
 async def admin_create_invite(
     data: dict,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Quick-invite a user to an account (super admin only).

backend/app/api/endpoints/admin_categories.py

@@ -4,25 +4,26 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func
 
-from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.core.audit import log_audit
 from app.models.user import User
 from app.models.category import TreeCategory
 from app.models.tree import Tree
 from app.schemas.admin import GlobalCategoryCreate, GlobalCategoryUpdate, GlobalCategoryResponse
 from app.api.deps import require_admin
+from app.core.service_account import PLATFORM_ACCOUNT_ID
 
 router = APIRouter(prefix="/admin/categories", tags=["admin-categories"])
 
 
 @router.get("/global", response_model=list[GlobalCategoryResponse])
 async def list_global_categories(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """List all global categories (account_id IS NULL)."""
     result = await db.execute(
-        select(TreeCategory).where(TreeCategory.account_id.is_(None)).order_by(TreeCategory.name)
+        select(TreeCategory).where(TreeCategory.account_id == PLATFORM_ACCOUNT_ID).order_by(TreeCategory.name)
     )
     categories = result.scalars().all()
 
@@ -45,36 +46,36 @@ async def list_global_categories(
 @router.post("/global", response_model=GlobalCategoryResponse, status_code=status.HTTP_201_CREATED)
 async def create_global_category(
     data: GlobalCategoryCreate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Create a global category."""
     # Check slug uniqueness for global categories
     existing = await db.execute(
-        select(TreeCategory).where(TreeCategory.slug == data.slug, TreeCategory.account_id.is_(None))
+        select(TreeCategory).where(TreeCategory.slug == data.slug, TreeCategory.account_id == PLATFORM_ACCOUNT_ID)
     )
     if existing.scalar_one_or_none():
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Global category with this slug already exists")
 
-    category = TreeCategory(name=data.name, slug=data.slug, account_id=None)
+    category = TreeCategory(name=data.name, slug=data.slug, account_id=PLATFORM_ACCOUNT_ID)
     db.add(category)
     await log_audit(db, current_user.id, "global_category.create", "category", details={"name": data.name})
     await db.commit()
     await db.refresh(category)
 
-    return GlobalCategoryResponse(id=category.id, name=category.name, slug=category.slug, account_id=None, tree_count=0)
+    return GlobalCategoryResponse(id=category.id, name=category.name, slug=category.slug, account_id=PLATFORM_ACCOUNT_ID, tree_count=0)
 
 
 @router.put("/global/{category_id}", response_model=GlobalCategoryResponse)
 async def update_global_category(
     category_id: UUID,
     data: GlobalCategoryUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Update a global category."""
     result = await db.execute(
-        select(TreeCategory).where(TreeCategory.id == category_id, TreeCategory.account_id.is_(None))
+        select(TreeCategory).where(TreeCategory.id == category_id, TreeCategory.account_id == PLATFORM_ACCOUNT_ID)
     )
     category = result.scalar_one_or_none()
     if not category:
@@ -86,7 +87,7 @@ async def update_global_category(
         # Check slug uniqueness
         existing = await db.execute(
             select(TreeCategory).where(
-                TreeCategory.slug == data.slug, TreeCategory.account_id.is_(None), TreeCategory.id != category_id
+                TreeCategory.slug == data.slug, TreeCategory.account_id == PLATFORM_ACCOUNT_ID, TreeCategory.id != category_id
             )
         )
         if existing.scalar_one_or_none():
@@ -103,19 +104,19 @@ async def update_global_category(
 
     return GlobalCategoryResponse(
         id=category.id, name=category.name, slug=category.slug,
-        account_id=None, tree_count=tree_count,
+        account_id=PLATFORM_ACCOUNT_ID, tree_count=tree_count,
     )
 
 
 @router.delete("/global/{category_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_global_category(
     category_id: UUID,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Delete (archive) a global category."""
     result = await db.execute(
-        select(TreeCategory).where(TreeCategory.id == category_id, TreeCategory.account_id.is_(None))
+        select(TreeCategory).where(TreeCategory.id == category_id, TreeCategory.account_id == PLATFORM_ACCOUNT_ID)
     )
     category = result.scalar_one_or_none()
     if not category:

backend/app/api/endpoints/admin_dashboard.py

@@ -3,7 +3,7 @@ from fastapi import APIRouter, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func
 
-from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.models.user import User
 from app.models.subscription import Subscription
 from app.models.tree import Tree
@@ -16,7 +16,7 @@ router = APIRouter(prefix="/admin/dashboard", tags=["admin-dashboard"])
 
 @router.get("/metrics", response_model=DashboardMetrics)
 async def get_dashboard_metrics(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Get platform overview metrics."""
@@ -45,7 +45,7 @@ async def get_dashboard_metrics(
 
 @router.get("/activity", response_model=list[ActivityEntry])
 async def get_dashboard_activity(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Get recent audit log entries for activity feed."""

backend/app/api/endpoints/admin_gallery.py

@@ -12,7 +12,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import require_admin
-from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.models.script_template import ScriptTemplate
 from app.models.tree import Tree
 from app.models.user import User
@@ -66,7 +66,7 @@ def _script_summary(script: ScriptTemplate) -> dict:
 
 @router.get("/featured")
 async def list_featured(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """List all featured flows and scripts (super admin only)."""
@@ -92,7 +92,7 @@ async def list_featured(
 
 @router.get("/items")
 async def list_all_items(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """List ALL flows and scripts with their gallery status (super admin only)."""
@@ -119,7 +119,7 @@ async def list_all_items(
 async def toggle_flow_featured(
     flow_id: UUID,
     body: FeatureToggle,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Toggle is_gallery_featured on a flow (super admin only)."""
@@ -138,7 +138,7 @@ async def toggle_flow_featured(
 async def update_flow_sort_order(
     flow_id: UUID,
     body: SortOrderUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Update gallery_sort_order on a flow (super admin only)."""
@@ -157,7 +157,7 @@ async def update_flow_sort_order(
 async def toggle_script_featured(
     script_id: UUID,
     body: FeatureToggle,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Toggle is_gallery_featured on a script (super admin only)."""
@@ -176,7 +176,7 @@ async def toggle_script_featured(
 async def update_script_sort_order(
     script_id: UUID,
     body: SortOrderUpdate,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Update gallery_sort_order on a script (super admin only)."""

backend/app/api/endpoints/ai_sessions.py

@@ -49,8 +49,6 @@ from app.schemas.ai_session import (
     ChatMessageRequest,
     ChatMessageResponse,
     SaveTaskLaneRequest,
-    TriagePatchRequest,
-    TriagePatchResponse,
 )
 from app.services import flowpilot_engine
 from app.services import unified_chat_service
@@ -122,11 +120,6 @@ def _build_session_detail(session: AISession) -> AISessionDetail:
         pending_task_lane=session.pending_task_lane,
         is_branching=getattr(session, 'is_branching', False),
         active_branch_id=str(session.active_branch_id) if getattr(session, 'active_branch_id', None) else None,
-        client_name=getattr(session, 'client_name', None),
-        asset_name=getattr(session, 'asset_name', None),
-        issue_category=getattr(session, 'issue_category', None),
-        triage_hypothesis=getattr(session, 'triage_hypothesis', None),
-        evidence_items=getattr(session, 'evidence_items', None),
     )
 
 
@@ -308,7 +301,7 @@ async def send_chat_message(
             message = f"{message}\n\n[Attached document content]\n{doc_context}"
 
     try:
-        ai_content, suggested_flows, session, fork_metadata, actions_data, questions_data, triage_update_data = await unified_chat_service.send_chat_message(
+        ai_content, suggested_flows, session, fork_metadata, actions_data, questions_data = await unified_chat_service.send_chat_message(
             session_id=session_id,
             user_id=user_id,
             account_id=account_id,
@@ -353,7 +346,6 @@ async def send_chat_message(
         fork=fork_metadata,
         actions=actions_data,
         questions=questions_data,
-        triage_update=triage_update_data,
     )
 
 
@@ -450,12 +442,7 @@ async def resolve_session(
         try:
             from app.services.resolution_output_generator import ResolutionOutputGenerator
             gen = ResolutionOutputGenerator(db)
-            await gen.generate_all(
-                session_id,
-                root_cause=data.root_cause,
-                steps_taken=data.steps_taken,
-                recommendations=data.recommendations,
-            )
+            await gen.generate_all(session_id)
         except Exception:
             logger.exception(f"Failed to generate resolution outputs for session {session_id}")
 
@@ -532,11 +519,15 @@ async def save_task_lane(
     _: None = Depends(require_engineer_or_admin),
 ):
     """Save the current task lane state including user's in-progress responses."""
-    session = await db.get(AISession, session_id)
+    result = await db.execute(
+        select(AISession).where(
+            AISession.id == session_id,
+            AISession.user_id == current_user.id,
+        )
+    )
+    session = result.scalar_one_or_none()
     if not session:
         raise HTTPException(status_code=404, detail="Session not found")
-    if session.user_id != current_user.id:
-        raise HTTPException(status_code=403, detail="Not your session")
 
     payload = {
         "questions": [q.model_dump() for q in body.questions],
@@ -553,122 +544,6 @@ async def save_task_lane(
     await db.commit()
 
 
-# ── Triage Metadata ──
-
-@router.patch("/{session_id}/triage", response_model=TriagePatchResponse)
-@limiter.limit("30/minute")
-async def update_triage(
-    request: Request,
-    session_id: UUID,
-    body: TriagePatchRequest,
-    current_user: Annotated[User, Depends(get_current_active_user)],
-    db: Annotated[AsyncSession, Depends(get_db)],
-    _: None = Depends(require_engineer_or_admin),
-):
-    """Update triage metadata on a session (incident header fields)."""
-    session = await db.get(AISession, session_id)
-    if not session:
-        raise HTTPException(status_code=404, detail="Session not found")
-    if session.user_id != current_user.id:
-        raise HTTPException(status_code=403, detail="Not your session")
-
-    patch_data = body.model_dump(exclude_unset=True)
-    for field, value in patch_data.items():
-        setattr(session, field, value)
-
-    await db.commit()
-    await db.refresh(session)
-
-    return TriagePatchResponse(
-        id=session.id,
-        client_name=session.client_name,
-        asset_name=session.asset_name,
-        issue_category=session.issue_category,
-        triage_hypothesis=session.triage_hypothesis,
-        evidence_items=session.evidence_items,
-    )
-
-
-# ── Handoff Draft ──
-
-@router.post("/{session_id}/handoff-draft")
-@limiter.limit("10/minute")
-async def handoff_draft(
-    request: Request,
-    session_id: UUID,
-    current_user: Annotated[User, Depends(get_current_active_user)],
-    db: Annotated[AsyncSession, Depends(get_db)],
-    _: None = Depends(require_engineer_or_admin),
-):
-    """Stream a structured handoff draft for the conclude modal."""
-    from fastapi.responses import StreamingResponse
-    from app.services.assistant_chat_service import _call_ai
-
-    session = await db.get(AISession, session_id)
-    if not session:
-        raise HTTPException(status_code=404, detail="Session not found")
-    if session.user_id != current_user.id:
-        raise HTTPException(status_code=403, detail="Not your session")
-
-    # Build context from session data
-    context_parts = [
-        f"Problem: {session.problem_summary or 'Unknown'}",
-        f"Domain: {session.problem_domain or 'Unknown'}",
-        f"Client: {session.client_name or 'Unknown'}",
-        f"Asset: {session.asset_name or 'Unknown'}",
-        f"Hypothesis: {session.triage_hypothesis or 'None'}",
-    ]
-
-    if session.evidence_items:
-        context_parts.append("\nEvidence collected:")
-        for item in session.evidence_items:
-            status_icon = {"confirmed": "✓", "ruled_out": "✗", "pending": "?"}.get(item.get("status", ""), "?")
-            context_parts.append(f"  {status_icon} {item.get('text', '')}")
-
-    # Include task lane steps if available
-    if session.pending_task_lane:
-        actions = session.pending_task_lane.get("actions", [])
-        if actions:
-            context_parts.append("\nSteps taken:")
-            for a in actions:
-                context_parts.append(f"  - {a.get('label', '')}")
-
-    # Include last 20 conversation messages
-    msgs = session.conversation_messages or []
-    if msgs:
-        context_parts.append("\nRecent conversation:")
-        for msg in msgs[-20:]:
-            role = msg.get("role", "unknown")
-            content = msg.get("content", "")[:300]
-            context_parts.append(f"  [{role}]: {content}")
-
-    context = "\n".join(context_parts)
-
-    prompt = (
-        "Generate a structured handoff summary for this troubleshooting session.\n"
-        "Return ONLY valid JSON with exactly these four fields:\n"
-        '{"root_cause": "...", "resolution": "...", "steps_taken": ["step1", "step2"], "recommendations": "..."}\n\n'
-        f"Session context:\n{context}"
-    )
-
-    async def generate():
-        try:
-            content, _, _ = await _call_ai(
-                system_base="You are a concise technical documentation assistant for MSP teams. Return only JSON.",
-                rag_context="",
-                history=[],
-                new_message=prompt,
-                max_tokens=1024,
-            )
-            yield f"data: {content}\n\n"
-        except Exception as e:
-            logger.exception(f"Handoff draft generation failed for session {session_id}")
-            import json
-            yield f"data: {json.dumps({'error': str(e)})}\n\n"
-
-    return StreamingResponse(generate(), media_type="text/event-stream")
-
-
 # ── Resume ──
 
 @router.post("/{session_id}/resume", status_code=204)
@@ -891,13 +766,13 @@ async def search_sessions(
     limit: int = Query(5, ge=1, le=20),
 ):
     """Search AI sessions by content using full-text search. Used by Command Palette."""
+    # Sessions are user-scoped. The list endpoint uses user_id only;
+    # search must be consistent. Cross-user access requires explicit
+    # escalation or session sharing — not ambient account membership.
     result = await db.execute(
         select(AISession)
         .where(
-            or_(
-                AISession.user_id == current_user.id,
-                AISession.account_id == current_user.account_id,
-            ),
+            AISession.user_id == current_user.id,
             text("ai_sessions.search_vector @@ plainto_tsquery('english', :q)"),
         )
         .params(q=q)
@@ -1030,7 +905,7 @@ async def get_session(
     pkg = session.escalation_package or {}
     is_handler = pkg.get("picked_up_by") == str(current_user.id)
     if session.user_id != current_user.id and session.escalated_to_id != current_user.id and not is_handler:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not found")
 
     return _build_session_detail(session)
 
@@ -1046,6 +921,18 @@ async def get_documentation(
     db: Annotated[AsyncSession, Depends(get_db)],
 ):
     """Get auto-generated documentation for a session."""
+    # Verify session ownership — owner only. Documentation endpoints require direct
+    # ownership; escalated_to_id / picked_up_by handlers use get_session (read-only).
+    # This is consistent with stream_documentation which has the same owner-only check.
+    result = await db.execute(
+        select(AISession).where(
+            AISession.id == session_id,
+            AISession.user_id == current_user.id,
+        )
+    )
+    if not result.scalar_one_or_none():
+        raise HTTPException(status_code=404, detail="Session not found")
+
     try:
         return await flowpilot_engine.get_session_documentation(
             session_id=session_id,
@@ -1071,13 +958,14 @@ async def stream_documentation(
 
     # Verify session ownership
     result = await db.execute(
-        select(AISession).where(AISession.id == session_id)
+        select(AISession).where(
+            AISession.id == session_id,
+            AISession.user_id == current_user.id,
+        )
     )
     session = result.scalar_one_or_none()
     if not session:
         raise HTTPException(status_code=404, detail="Session not found")
-    if session.user_id != current_user.id:
-        raise HTTPException(status_code=403, detail="Not authorized")
 
     async def event_generator():
         try:
@@ -1172,6 +1060,19 @@ async def retry_psa_push_endpoint(
     """Manually retry a failed PSA documentation push."""
     from app.models.psa_post_log import PsaPostLog
 
+    # Verify the session belongs to the current user
+    session_result = await db.execute(
+        select(AISession).where(
+            AISession.id == session_id,
+            AISession.user_id == current_user.id,
+        )
+    )
+    if not session_result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found",
+        )
+
     # Find the latest failed push log for this session
     result = await db.execute(
         select(PsaPostLog)

backend/app/api/endpoints/ai_suggestions.py

@@ -43,6 +43,7 @@ async def create_suggestion(
     suggestion = AISuggestion(
         tree_id=data.tree_id,
         user_id=current_user.id,
+        account_id=current_user.account_id,
         session_id=data.session_id,
         action_type=data.action_type,
         target_node_id=data.target_node_id,

backend/app/api/endpoints/analytics.py

@@ -7,6 +7,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.database import get_db
 from app.api.deps import get_current_active_user
+from app.core.filters import tenant_filter
 from app.models import User, Session, Tree, SessionRating
 from app.schemas.analytics import (
     TeamAnalyticsResponse, PersonalAnalyticsResponse, FlowAnalyticsResponse,
@@ -290,8 +291,13 @@ async def get_flow_analytics(
     current_user: User = Depends(get_current_active_user),
 ):
     """Analytics for a specific flow."""
-    # Verify tree exists
-    result = await db.execute(select(Tree).where(Tree.id == tree_id))
+    # Verify tree exists and belongs to the requesting user's account.
+    result = await db.execute(
+        select(Tree).where(
+            Tree.id == tree_id,
+            tenant_filter(Tree, current_user.account_id),
+        )
+    )
     tree = result.scalar_one_or_none()
     if not tree:
         raise HTTPException(status_code=404, detail="Flow not found")

backend/app/api/endpoints/auth.py

@@ -1,6 +1,5 @@
 import secrets
 import string
-import uuid
 from datetime import datetime, timezone, timedelta
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException, status, Request
@@ -9,7 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, update as sa_update
 from app.core.config import settings
 from app.core.settings_manager import SettingsManager
-from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.core.rate_limit import limiter
 from app.core.security import (
     verify_password,
@@ -27,7 +26,6 @@ from app.models.refresh_token import RefreshToken
 from app.models.account import Account
 from app.models.subscription import Subscription
 from app.models.account_invite import AccountInvite
-from app.models.feature_flag import FeatureFlag, PlanFeatureDefault, AccountFeatureOverride
 from app.schemas.user import UserCreate, UserResponse, UserLogin, UserUpdate
 from app.schemas.token import Token
 from app.schemas.auth_password import (
@@ -69,7 +67,7 @@ def _generate_display_code() -> str:
 async def register(
     request: Request,
     user_data: UserCreate,
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Register a new user.
 
@@ -234,7 +232,7 @@ async def register(
 async def login(
     request: Request,
     form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Login and get access token."""
     # Find user by email
@@ -272,7 +270,7 @@ async def login(
 async def login_json(
     request: Request,
     credentials: UserLogin,
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Login with JSON body (alternative to form data)."""
     result = await db.execute(select(User).where(User.email == credentials.email))
@@ -306,7 +304,7 @@ async def login_json(
 async def refresh_token(
     request: Request,
     payload: Annotated[dict, Depends(get_refresh_token_payload)],
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Refresh access token using refresh token (rotation: old token is revoked)."""
     user_id = payload.get("sub")
@@ -370,7 +368,7 @@ async def get_me(
 async def update_me(
     data: UserUpdate,
     current_user: Annotated[User, Depends(get_current_active_user)],
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Update current user's profile (name, email)."""
     update_fields = data.model_fields_set - {"current_password"}
@@ -417,7 +415,7 @@ async def update_me(
 @router.post("/logout")
 async def logout(
     payload: Annotated[dict, Depends(get_refresh_token_payload)],
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Logout user by revoking the refresh token."""
     jti = payload.get("jti")
@@ -440,7 +438,7 @@ async def change_password(
     request: Request,
     data: ChangePasswordRequest,
     current_user: Annotated[User, Depends(get_current_active_user)],
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Change the current user's password."""
     if not verify_password(data.current_password, current_user.password_hash):
@@ -480,7 +478,7 @@ async def change_password(
 async def forgot_password(
     request: Request,
     data: ForgotPasswordRequest,
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Request a password reset email. Always returns success (anti-enumeration)."""
     result = await db.execute(select(User).where(User.email == data.email))
@@ -515,7 +513,7 @@ async def forgot_password(
 @router.post("/password/verify-reset-token", response_model=VerifyResetTokenResponse)
 async def verify_reset_token(
     data: VerifyResetTokenRequest,
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Verify a password reset token is valid."""
     payload = decode_token(data.token)
@@ -546,7 +544,7 @@ async def verify_reset_token(
 async def reset_password(
     request: Request,
     data: ResetPasswordRequest,
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Reset password using a valid reset token."""
     payload = decode_token(data.token)
@@ -613,7 +611,7 @@ async def reset_password(
 
 @router.get("/email/verification-status")
 async def get_verification_status(
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Check if email verification is enabled on the platform."""
     enabled = await SettingsManager.get("email_verification_enabled", db, default=True)
@@ -625,7 +623,7 @@ async def get_verification_status(
 async def send_verification_email(
     request: Request,
     current_user: Annotated[User, Depends(get_current_active_user)],
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Send an email verification link to the current user."""
     verification_enabled = await SettingsManager.get("email_verification_enabled", db, default=True)
@@ -664,7 +662,7 @@ async def send_verification_email(
 @router.post("/email/verify")
 async def verify_email(
     data: dict,
-    db: Annotated[AsyncSession, Depends(get_db)]
+    db: Annotated[AsyncSession, Depends(get_admin_db)]
 ):
     """Verify an email using a token. Public endpoint."""
     token = data.get("token")
@@ -720,59 +718,3 @@ async def verify_email(
     await db.commit()
 
     return {"message": "Email verified successfully"}
-
-
-@router.get("/me/feature-flags", response_model=dict[str, bool])
-async def get_my_feature_flags(
-    current_user: Annotated[User, Depends(get_current_active_user)],
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> dict[str, bool]:
-    """Resolve feature flags for the current user's account and plan."""
-    plan = "free"
-    if current_user.account_id:
-        sub_result = await db.execute(
-            select(Subscription).where(
-                Subscription.account_id == current_user.account_id,
-                Subscription.status.in_(["active", "trialing"]),
-            )
-        )
-        sub = sub_result.scalar_one_or_none()
-        if sub:
-            plan = sub.plan
-
-    flags_result = await db.execute(select(FeatureFlag))
-    flags = flags_result.scalars().all()
-
-    if not flags:
-        return {}
-
-    flag_ids = [f.id for f in flags]
-
-    defaults_result = await db.execute(
-        select(PlanFeatureDefault).where(
-            PlanFeatureDefault.flag_id.in_(flag_ids),
-            PlanFeatureDefault.plan == plan,
-        )
-    )
-    plan_defaults = {d.flag_id: d.enabled for d in defaults_result.scalars().all()}
-
-    overrides: dict[uuid.UUID, bool] = {}
-    if current_user.account_id:
-        overrides_result = await db.execute(
-            select(AccountFeatureOverride).where(
-                AccountFeatureOverride.flag_id.in_(flag_ids),
-                AccountFeatureOverride.account_id == current_user.account_id,
-            )
-        )
-        overrides = {o.flag_id: o.enabled for o in overrides_result.scalars().all()}
-
-    resolved = {}
-    for flag in flags:
-        if flag.id in overrides:
-            resolved[flag.flag_key] = overrides[flag.id]
-        elif flag.id in plan_defaults:
-            resolved[flag.flag_key] = plan_defaults[flag.id]
-        else:
-            resolved[flag.flag_key] = False
-
-    return resolved

backend/app/api/endpoints/categories.py

@@ -12,6 +12,8 @@ from app.models.user import User
 from app.schemas.category import CategoryCreate, CategoryUpdate, CategoryResponse, CategoryListResponse
 from app.api.deps import get_current_active_user
 from app.core.permissions import can_manage_category, can_create_category
+from app.core.service_account import PLATFORM_ACCOUNT_ID
+from app.core.filters import tenant_filter
 
 router = APIRouter(prefix="/categories", tags=["categories"])
 
@@ -47,13 +49,13 @@ async def list_categories(
     elif current_user.account_id:
         query = query.where(
             or_(
-                TreeCategory.account_id.is_(None),  # Global
+                TreeCategory.account_id == PLATFORM_ACCOUNT_ID,  # Global
                 TreeCategory.account_id == current_user.account_id  # User's account
             )
         )
     else:
         # User has no account, only show global categories
-        query = query.where(TreeCategory.account_id.is_(None))
+        query = query.where(TreeCategory.account_id == PLATFORM_ACCOUNT_ID)
 
     query = query.order_by(TreeCategory.display_order, TreeCategory.name)
 
@@ -108,10 +110,12 @@ async def get_category(
             detail="You don't have access to this category"
         )
 
-    # Get tree count
+    # Get tree count — scoped to the requesting account so cross-account
+    # trees in shared categories are not counted.
     count_query = select(func.count(Tree.id)).where(
         Tree.category_id == category.id,
-        Tree.is_active == True
+        Tree.is_active == True,
+        tenant_filter(Tree, current_user.account_id),
     )
     count_result = await db.execute(count_query)
     tree_count = count_result.scalar() or 0
@@ -173,7 +177,7 @@ async def create_category(
         name=category_data.name,
         slug=slug,
         description=category_data.description,
-        account_id=category_data.account_id,
+        account_id=category_data.account_id if category_data.account_id is not None else PLATFORM_ACCOUNT_ID,
         display_order=max_order + 1,
         created_by=current_user.id
     )

backend/app/api/endpoints/device_types.py

@@ -15,6 +15,7 @@ from app.schemas.device_type import (
     DeviceTypeUpdate,
     DeviceTypeResponse,
 )
+from app.core.service_account import PLATFORM_ACCOUNT_ID
 
 router = APIRouter(prefix="/device-types", tags=["device-types"])
 
@@ -28,8 +29,8 @@ async def list_device_types(
         select(DeviceType)
         .where(
             or_(
-                DeviceType.is_system.is_(True),
-                DeviceType.team_id == current_user.team_id,
+                DeviceType.account_id == PLATFORM_ACCOUNT_ID,
+                DeviceType.account_id == current_user.account_id,
             )
         )
         .order_by(DeviceType.category, DeviceType.sort_order, DeviceType.label)
@@ -48,16 +49,16 @@ async def create_device_type(
     existing = await db.execute(
         select(DeviceType).where(
             DeviceType.slug == data.slug,
-            DeviceType.team_id == current_user.team_id,
+            DeviceType.account_id == current_user.account_id,
         )
     )
     if existing.scalar_one_or_none():
-        raise HTTPException(status_code=409, detail=f"Device type '{data.slug}' already exists for your team")
+        raise HTTPException(status_code=409, detail=f"Device type '{data.slug}' already exists for your account")
 
     system_existing = await db.execute(
         select(DeviceType).where(
             DeviceType.slug == data.slug,
-            DeviceType.is_system.is_(True),
+            DeviceType.account_id == PLATFORM_ACCOUNT_ID,
         )
     )
     if system_existing.scalar_one_or_none():
@@ -68,7 +69,7 @@ async def create_device_type(
         label=data.label,
         category=data.category,
         is_system=False,
-        team_id=current_user.team_id,
+        account_id=current_user.account_id,
         sort_order=data.sort_order,
     )
     db.add(device_type)
@@ -89,7 +90,7 @@ async def update_device_type(
         raise HTTPException(status_code=404, detail="Device type not found")
     if device_type.is_system:
         raise HTTPException(status_code=403, detail="Cannot modify system device types")
-    if device_type.team_id != current_user.team_id:
+    if device_type.account_id != current_user.account_id:
         raise HTTPException(status_code=404, detail="Device type not found")
 
     update_data = data.model_dump(exclude_unset=True)
@@ -112,7 +113,7 @@ async def delete_device_type(
         raise HTTPException(status_code=404, detail="Device type not found")
     if device_type.is_system:
         raise HTTPException(status_code=403, detail="Cannot delete system device types")
-    if device_type.team_id != current_user.team_id:
+    if device_type.account_id != current_user.account_id:
         raise HTTPException(status_code=404, detail="Device type not found")
 
     await db.delete(device_type)

backend/app/api/endpoints/draft_templates.py

@@ -0,0 +1,221 @@
+"""Draft template endpoints — Phase 6 post-resolve templatization flow.
+
+Engineers who picked "Run now, templatize after resolve" on the three-option
+dialog (Phase 5) generate a `draft_templates` row at decision time. After
+the session resolves, the TemplatizePrompt component lets them either:
+  - Accept → promotes the draft to a real `script_templates` row
+  - Reject → marks the draft rejected, no library entry created
+
+The Script Library sidebar uses the list endpoint to surface a
+"X drafts ready to review" badge for the account.
+
+See FLOWPILOT-MIGRATION.md Section 5.3.
+"""
+import logging
+import re
+from datetime import datetime, timezone
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_active_user, get_db, require_engineer_or_admin
+from app.models.ai_session import AISession
+from app.models.draft_template import DraftTemplate
+from app.models.script_template import ScriptCategory, ScriptTemplate
+from app.models.user import User
+from app.schemas.draft_template import (
+    DraftTemplateAcceptRequest,
+    DraftTemplateAcceptResponse,
+    DraftTemplateListResponse,
+    DraftTemplateRejectResponse,
+    DraftTemplateResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/draft-templates", tags=["draft-templates"])
+
+
+def _slugify(name: str) -> str:
+    """Same slug rule as scripts.create_template — lowercase, kebab-case, ASCII."""
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+# ── List ─────────────────────────────────────────────────────────────────
+
+@router.get("", response_model=DraftTemplateListResponse)
+async def list_drafts(
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+    pending_only: bool = True,
+) -> DraftTemplateListResponse:
+    """List drafts for the current user's account.
+
+    Defaults to pending-only — that's what the Script Library badge counts
+    and what the post-resolve TemplatizePrompt iterates over. Pass
+    `pending_only=false` to include accepted/rejected for an audit view.
+    """
+    stmt = select(DraftTemplate).order_by(DraftTemplate.created_at.desc())
+    if pending_only:
+        stmt = stmt.where(DraftTemplate.status == "pending")
+    result = await db.execute(stmt)
+    drafts = list(result.scalars().all())
+    return DraftTemplateListResponse(
+        drafts=[DraftTemplateResponse.model_validate(d) for d in drafts]
+    )
+
+
+# ── Get one ──────────────────────────────────────────────────────────────
+
+@router.get("/{draft_id}", response_model=DraftTemplateResponse)
+async def get_draft(
+    draft_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> DraftTemplateResponse:
+    draft = await _load_draft_or_404(db, draft_id)
+    return DraftTemplateResponse.model_validate(draft)
+
+
+# ── Accept ───────────────────────────────────────────────────────────────
+
+@router.post(
+    "/{draft_id}/accept",
+    response_model=DraftTemplateAcceptResponse,
+    status_code=201,
+)
+async def accept_draft(
+    draft_id: UUID,
+    body: DraftTemplateAcceptRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> DraftTemplateAcceptResponse:
+    """Promote a draft to a real `script_templates` row.
+
+    Provenance fields (`source_session_id`, `source_user_id`,
+    `source_ticket_ref`) are copied so the Script Library can render the
+    "generated from CW #X · resolved by Y · used N times" chip.
+
+    On success: draft.status='accepted', draft.promoted_template_id set,
+    draft.resolved_at set. The new template is owned by the engineer's team
+    (matches scripts.create_template's behavior).
+
+    Returns 409 if the draft is already accepted/rejected.
+    """
+    draft = await _load_draft_or_404(db, draft_id)
+    if draft.status != "pending":
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Draft is already {draft.status}",
+        )
+
+    # Validate the category exists and belongs to (or is global for) this account.
+    cat_result = await db.execute(
+        select(ScriptCategory).where(
+            ScriptCategory.id == body.category_id,
+            ScriptCategory.is_active == True,  # noqa: E712
+        )
+    )
+    if cat_result.scalar_one_or_none() is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="category_id does not reference an active script category",
+        )
+
+    # Look up source-session ticket ref for the provenance chip. RLS makes
+    # cross-account ai_session lookup impossible — the draft must belong to
+    # the same account as the requesting user.
+    source_session = (
+        await db.execute(
+            select(AISession).where(AISession.id == draft.source_session_id)
+        )
+    ).scalar_one_or_none()
+    source_ticket_ref = (
+        f"CW #{source_session.psa_ticket_id}"
+        if source_session and source_session.psa_ticket_id
+        else None
+    )
+
+    slug = _slugify(body.name)
+
+    template = ScriptTemplate(
+        category_id=body.category_id,
+        team_id=current_user.team_id,
+        account_id=current_user.account_id,
+        created_by=current_user.id,
+        name=body.name,
+        slug=slug,
+        description=body.description,
+        script_body=body.edited_body or draft.script_body,
+        parameters_schema=body.parameters_schema,
+        # FlowPilot provenance — drives the Script Library chip.
+        source_session_id=draft.source_session_id,
+        source_user_id=draft.source_user_id,
+        source_ticket_ref=source_ticket_ref,
+    )
+    db.add(template)
+    await db.flush()  # populate template.id
+
+    draft.status = "accepted"
+    draft.promoted_template_id = template.id
+    draft.resolved_at = datetime.now(timezone.utc)
+
+    await db.commit()
+    await db.refresh(template)
+
+    return DraftTemplateAcceptResponse(
+        draft_id=draft.id,
+        promoted_template_id=template.id,
+        template_slug=template.slug,
+    )
+
+
+# ── Reject ───────────────────────────────────────────────────────────────
+
+@router.post("/{draft_id}/reject", response_model=DraftTemplateRejectResponse)
+async def reject_draft(
+    draft_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> DraftTemplateRejectResponse:
+    """Mark a draft rejected.
+
+    No template is created. The row stays for audit (so a team admin can see
+    the engineer reviewed and explicitly declined). Returns 409 on a draft
+    that's already accepted/rejected.
+    """
+    draft = await _load_draft_or_404(db, draft_id)
+    if draft.status != "pending":
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Draft is already {draft.status}",
+        )
+    draft.status = "rejected"
+    draft.resolved_at = datetime.now(timezone.utc)
+    await db.commit()
+    return DraftTemplateRejectResponse(draft_id=draft.id, status="rejected")
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+async def _load_draft_or_404(
+    db: AsyncSession, draft_id: UUID
+) -> DraftTemplate:
+    """RLS-scoped draft load. 404 covers missing + cross-tenant."""
+    result = await db.execute(
+        select(DraftTemplate).where(DraftTemplate.id == draft_id)
+    )
+    draft = result.scalar_one_or_none()
+    if draft is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Draft template not found",
+        )
+    return draft

backend/app/api/endpoints/integrations.py

@@ -27,6 +27,7 @@ from app.schemas.psa_connection import (
     PsaMemberMappingSaveRequest,
     PsaMemberResponse,
     AutoMatchResult,
+    PSABoardResponse,
 )
 from app.core.config import settings
 from app.services.psa.encryption import (
@@ -345,26 +346,103 @@ async def update_flowpilot_settings(
 # ── ticket / status / company endpoints ──────────────────────────
 
 
-@router.get("/tickets/search", response_model=list[PSATicketSearchResult])
-async def search_tickets(
+@router.get("/boards", response_model=list[PSABoardResponse])
+async def list_boards(
     current_user: Annotated[User, Depends(require_engineer_or_admin)],
     db: Annotated[AsyncSession, Depends(get_db)],
-    query: str = "",
-    board_id: int | None = None,
-    status_id: int | None = None,
-    include_closed: bool = False,
 ):
-    """Search ConnectWise tickets."""
+    """List PSA service boards."""
     if not current_user.account_id:
         raise HTTPException(status_code=400, detail="User has no account")
 
     from app.services.psa.registry import get_provider_for_account
     from app.services.psa.exceptions import PSAError
 
+    try:
+        provider = await get_provider_for_account(current_user.account_id, db)
+        boards = await provider.list_boards()
+        return [PSABoardResponse(id=b.id, name=b.name) for b in boards]
+    except PSAError:
+        # Boards are optional UI chrome — degrade gracefully rather than surfacing a toast
+        return []
+
+
+@router.get("/tickets/search", response_model=list[PSATicketSearchResult])
+async def search_tickets(
+    current_user: Annotated[User, Depends(require_engineer_or_admin)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    query: str = "",
+    board_id: int | None = None,
+    status_id: int | None = None,
+    include_closed: bool = False,
+    assigned_to_me: bool = False,
+    unassigned: bool = False,
+    board_ids: str = "",
+    page: int = 1,
+    page_size: int = 10,
+):
+    """Search ConnectWise tickets."""
+    if not current_user.account_id:
+        raise HTTPException(status_code=400, detail="User has no account")
+
+    from app.services.psa.registry import get_provider_for_account
+    from app.services.psa.exceptions import PSAError
+
+    # Resolve assigned_to_me → member_identifier (CW login name for resources contains filter)
+    member_identifier: str | None = None
+    if assigned_to_me:
+        conn_result = await db.execute(
+            select(PsaConnection).where(
+                PsaConnection.account_id == current_user.account_id,
+                PsaConnection.is_active.is_(True),
+            )
+        )
+        conn = conn_result.scalar_one_or_none()
+        if conn:
+            mapping_result = await db.execute(
+                select(PsaMemberMapping).where(
+                    PsaMemberMapping.psa_connection_id == conn.id,
+                    PsaMemberMapping.user_id == current_user.id,
+                )
+            )
+            mapping = mapping_result.scalar_one_or_none()
+            if not mapping:
+                # No mapping for this user — return empty list
+                return []
+
+            from app.services.psa.registry import get_provider_for_account as _get_provider
+            from app.services.psa.exceptions import PSAError as _PSAError
+            try:
+                _provider = await _get_provider(current_user.account_id, db)
+                cw_members = await _provider.list_members()
+                matched = next((m for m in cw_members if m.id == mapping.external_member_id), None)
+                if matched:
+                    member_identifier = matched.identifier
+                else:
+                    return []
+            except _PSAError:
+                return []
+
+    # Parse comma-separated board_ids
+    parsed_board_ids: list[int] = []
+    if board_ids:
+        try:
+            parsed_board_ids = [int(bid.strip()) for bid in board_ids.split(",") if bid.strip()]
+        except ValueError:
+            raise HTTPException(status_code=400, detail="board_ids must be comma-separated integers")
+
     try:
         provider = await get_provider_for_account(current_user.account_id, db)
         tickets = await provider.search_tickets(
-            query, board_id=board_id, status_id=status_id, include_closed=include_closed
+            query,
+            board_id=board_id,
+            status_id=status_id,
+            include_closed=include_closed,
+            member_identifier=member_identifier,
+            unassigned=unassigned,
+            board_ids=parsed_board_ids,
+            page=page,
+            page_size=page_size,
         )
         return [
             PSATicketSearchResult(
@@ -517,31 +595,37 @@ async def get_member_mappings(
     current_user: Annotated[User, Depends(require_account_owner)],
     db: Annotated[AsyncSession, Depends(get_db)],
 ):
-    """Get all member mappings for the account."""
+    """Get all account users with their PSA member mappings (unmapped users included)."""
     conn = await _get_account_connection(current_user.account_id, db)
     if not conn:
         return []
 
-    result = await db.execute(
+    # Fetch all active account users
+    users_result = await db.execute(
+        select(User).where(User.account_id == current_user.account_id, User.is_active.is_(True))
+    )
+    users = users_result.scalars().all()
+
+    # Fetch all existing mappings keyed by user_id for O(1) lookup
+    mappings_result = await db.execute(
         select(PsaMemberMapping).where(PsaMemberMapping.psa_connection_id == conn.id)
     )
-    mappings = result.scalars().all()
+    mapping_by_user: dict[str, PsaMemberMapping] = {
+        str(m.user_id): m for m in mappings_result.scalars().all()
+    }
 
-    response = []
-    for m in mappings:
-        user_result = await db.execute(select(User).where(User.id == m.user_id))
-        user = user_result.scalar_one_or_none()
-        if user:
-            response.append(PsaMemberMappingResponse(
-                id=str(m.id),
-                user_id=str(m.user_id),
-                user_email=user.email,
-                user_name=user.name,
-                external_member_id=m.external_member_id,
-                external_member_name=m.external_member_name,
-                matched_by=m.matched_by,
-            ))
-    return response
+    return [
+        PsaMemberMappingResponse(
+            id=str(m.id) if (m := mapping_by_user.get(str(user.id))) else None,
+            user_id=str(user.id),
+            user_email=user.email,
+            user_name=user.name,
+            external_member_id=m.external_member_id if m else None,
+            external_member_name=m.external_member_name if m else None,
+            matched_by=m.matched_by if m else None,
+        )
+        for user in users
+    ]
 
 
 @router.post("/member-mappings", response_model=list[PsaMemberMappingResponse])
@@ -564,6 +648,7 @@ async def save_member_mappings(
     for m in mappings:
         mapping = PsaMemberMapping(
             psa_connection_id=conn.id,
+            account_id=current_user.account_id,
             user_id=UUID(m.user_id),
             external_member_id=m.external_member_id,
             external_member_name=m.external_member_name,
@@ -624,6 +709,7 @@ async def auto_match_members(
             if not existing.scalar_one_or_none():
                 mapping = PsaMemberMapping(
                     psa_connection_id=conn.id,
+                    account_id=current_user.account_id,
                     user_id=user.id,
                     external_member_id=cw_member.id,
                     external_member_name=cw_member.name,

backend/app/api/endpoints/maintenance_schedules.py

@@ -29,8 +29,8 @@ def _compute_next_run(cron_expression: str, tz_name: str) -> datetime:
     return cron.get_next(datetime).astimezone(timezone.utc)
 
 
-async def _get_tree_or_403(tree_id: UUID, current_user: User, db: AsyncSession) -> "Tree":
-    """Fetch tree and verify the current user's team owns it."""
+async def _get_tree_or_404(tree_id: UUID, current_user: User, db: AsyncSession) -> "Tree":
+    """Fetch tree and verify the current user's team owns it. Raises 404 if not found or access denied."""
     result = await db.execute(select(Tree).where(Tree.id == tree_id))
     tree = result.scalar_one_or_none()
     if not tree:
@@ -38,7 +38,7 @@ async def _get_tree_or_403(tree_id: UUID, current_user: User, db: AsyncSession)
     # Super admins can access any tree; regular users must be on the same team
     if not getattr(current_user, 'is_super_admin', False):
         if tree.team_id != current_user.team_id:
-            raise HTTPException(status_code=403, detail="Access denied")
+            raise HTTPException(status_code=404, detail="Tree not found")
     return tree
 
 
@@ -51,7 +51,7 @@ async def create_schedule(
 ):
     """Create a cron schedule for a maintenance flow. One per flow."""
     # Verify user's team owns the tree
-    tree = await _get_tree_or_403(data.tree_id, current_user, db)
+    tree = await _get_tree_or_404(data.tree_id, current_user, db)
     if tree.tree_type != "maintenance":
         raise HTTPException(status_code=400, detail="Schedules are only supported for maintenance flows")
 
@@ -69,6 +69,7 @@ async def create_schedule(
 
     schedule = MaintenanceSchedule(
         tree_id=data.tree_id,
+        account_id=current_user.account_id,
         created_by=current_user.id,
         cron_expression=data.cron_expression,
         timezone=data.timezone,
@@ -94,7 +95,7 @@ async def get_schedule_for_tree(
 ):
     """Get the schedule for a specific maintenance flow."""
     # Verify user's team owns the tree before returning schedule data
-    await _get_tree_or_403(tree_id, current_user, db)
+    await _get_tree_or_404(tree_id, current_user, db)
 
     result = await db.execute(
         select(MaintenanceSchedule).where(MaintenanceSchedule.tree_id == tree_id)
@@ -122,7 +123,7 @@ async def update_schedule(
         raise HTTPException(status_code=404, detail="Schedule not found")
 
     # Verify user's team owns the tree this schedule belongs to
-    await _get_tree_or_403(schedule.tree_id, current_user, db)
+    await _get_tree_or_404(schedule.tree_id, current_user, db)
 
     update_fields = data.model_fields_set
     was_active = schedule.is_active

backend/app/api/endpoints/network_diagrams.py

@@ -1,10 +1,12 @@
 """Network diagrams API endpoints."""
+import base64
 import logging
 from datetime import datetime, timezone
 from typing import Annotated
 from uuid import UUID
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
 from sqlalchemy import select, or_
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -13,6 +15,7 @@ from app.api.deps import get_current_active_user
 from app.models.user import User
 from app.models.device_type import DeviceType
 from app.models.network_diagram import NetworkDiagram
+from app.core.service_account import PLATFORM_ACCOUNT_ID
 from app.schemas.network_diagram import (
     NetworkDiagramCreate,
     NetworkDiagramUpdate,
@@ -26,7 +29,7 @@ from app.schemas.network_diagram import (
     DiagramNode,
     DiagramEdge,
 )
-from app.services import network_diagram_ai_service
+from app.services import network_diagram_ai_service, storage_service
 
 # Maps system device-type slugs to their category — mirrors frontend deviceRegistry.ts
 _SLUG_CATEGORY: dict[str, str] = {
@@ -49,11 +52,11 @@ router = APIRouter(prefix="/network-diagrams", tags=["network-diagrams"])
 
 async def _get_diagram_or_404(
     diagram_id: UUID,
-    team_id: UUID,
+    account_id: UUID,
     db: AsyncSession,
 ) -> NetworkDiagram:
     diagram = await db.get(NetworkDiagram, diagram_id)
-    if not diagram or diagram.team_id != team_id or diagram.is_archived:
+    if not diagram or diagram.account_id != account_id or diagram.is_archived:
         raise HTTPException(status_code=404, detail="Diagram not found")
     return diagram
 
@@ -82,15 +85,19 @@ def _diagram_to_list_item(
         description=diagram.description,
         node_count=len(nodes),
         category_counts=category_counts,
+        thumbnail_url=diagram.thumbnail_url,
         created_by=diagram.created_by,
         created_at=diagram.created_at,
         updated_at=diagram.updated_at,
     )
 
 
-async def _get_available_slugs(team_id: UUID, db: AsyncSession) -> set[str]:
+async def _get_available_slugs(account_id: UUID, db: AsyncSession) -> set[str]:
     stmt = select(DeviceType.slug).where(
-        or_(DeviceType.is_system.is_(True), DeviceType.team_id == team_id)
+        or_(
+            DeviceType.account_id == PLATFORM_ACCOUNT_ID,
+            DeviceType.account_id == account_id,
+        )
     )
     result = await db.execute(stmt)
     return {row[0] for row in result.all()}
@@ -104,7 +111,7 @@ async def list_client_names(
     stmt = (
         select(NetworkDiagram.client_name)
         .where(
-            NetworkDiagram.team_id == current_user.team_id,
+            NetworkDiagram.account_id == current_user.account_id,
             NetworkDiagram.is_archived.is_(False),
             NetworkDiagram.client_name.isnot(None),
             NetworkDiagram.client_name != "",
@@ -126,7 +133,7 @@ async def list_diagrams(
     stmt = (
         select(NetworkDiagram)
         .where(
-            NetworkDiagram.team_id == current_user.team_id,
+            NetworkDiagram.account_id == current_user.account_id,
             NetworkDiagram.is_archived.is_(False),
         )
         .order_by(NetworkDiagram.updated_at.desc())
@@ -148,7 +155,7 @@ async def list_diagrams(
     # Single query for custom device types so category_counts is accurate
     dt_stmt = select(DeviceType.slug, DeviceType.category).where(
         DeviceType.is_system.is_(False),
-        DeviceType.team_id == current_user.team_id,
+        DeviceType.account_id == current_user.account_id,
     )
     dt_result = await db.execute(dt_stmt)
     custom_slug_category = {row[0]: row[1] for row in dt_result.all()}
@@ -164,13 +171,8 @@ async def create_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> NetworkDiagramResponse:
-    if current_user.team_id is None:
-        raise HTTPException(
-            status_code=422,
-            detail="Network Diagrams require a team account. Assign your account to a team first.",
-        )
     diagram = NetworkDiagram(
-        team_id=current_user.team_id,
+        account_id=current_user.account_id,
         name=data.name,
         client_name=data.client_name,
         asset_name=data.asset_name,
@@ -191,7 +193,7 @@ async def get_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> NetworkDiagramResponse:
-    diagram = await _get_diagram_or_404(diagram_id, current_user.team_id, db)
+    diagram = await _get_diagram_or_404(diagram_id, current_user.account_id, db)
     return _diagram_to_response(diagram)
 
 
@@ -202,7 +204,7 @@ async def update_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> NetworkDiagramResponse:
-    diagram = await _get_diagram_or_404(diagram_id, current_user.team_id, db)
+    diagram = await _get_diagram_or_404(diagram_id, current_user.account_id, db)
 
     update_data = data.model_dump(exclude_unset=True)
     if "nodes" in update_data and update_data["nodes"] is not None:
@@ -225,7 +227,7 @@ async def archive_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> None:
-    diagram = await _get_diagram_or_404(diagram_id, current_user.team_id, db)
+    diagram = await _get_diagram_or_404(diagram_id, current_user.account_id, db)
     diagram.is_archived = True
     diagram.updated_at = datetime.now(timezone.utc)
     await db.commit()
@@ -237,9 +239,9 @@ async def duplicate_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> NetworkDiagramResponse:
-    source = await _get_diagram_or_404(diagram_id, current_user.team_id, db)
+    source = await _get_diagram_or_404(diagram_id, current_user.account_id, db)
     copy = NetworkDiagram(
-        team_id=current_user.team_id,
+        account_id=current_user.account_id,
         name=f"Copy of {source.name}",
         client_name=source.client_name,
         asset_name=source.asset_name,
@@ -260,7 +262,7 @@ async def export_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> DiagramExportResponse:
-    diagram = await _get_diagram_or_404(diagram_id, current_user.team_id, db)
+    diagram = await _get_diagram_or_404(diagram_id, current_user.account_id, db)
     nodes = [DiagramNode(**n) for n in (diagram.nodes or [])]
     edges = [DiagramEdge(**e) for e in (diagram.edges or [])]
     return DiagramExportResponse(
@@ -280,7 +282,7 @@ async def import_diagram(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> DiagramImportResponse:
-    available_slugs = await _get_available_slugs(current_user.team_id, db)
+    available_slugs = await _get_available_slugs(current_user.account_id, db)
 
     warnings: list[str] = []
     for node in data.nodes:
@@ -288,7 +290,7 @@ async def import_diagram(
             warnings.append(f"Unknown device type '{node.type}' — will render with default icon")
 
     diagram = NetworkDiagram(
-        team_id=current_user.team_id,
+        account_id=current_user.account_id,
         name=data.name,
         client_name=data.client_name,
         description=data.description,
@@ -306,13 +308,41 @@ async def import_diagram(
     )
 
 
+class ThumbnailUploadRequest(BaseModel):
+    data_url: str  # base64 PNG data URL: "data:image/png;base64,..."
+
+
+@router.post("/{diagram_id}/thumbnail", status_code=204)
+async def upload_thumbnail(
+    diagram_id: UUID,
+    body: ThumbnailUploadRequest,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> None:
+    diagram = await _get_diagram_or_404(diagram_id, current_user.account_id, db)
+    try:
+        header, encoded = body.data_url.split(",", 1)
+    except ValueError:
+        raise HTTPException(status_code=422, detail="Invalid data URL format")
+    image_bytes = base64.b64decode(encoded)
+    storage_key = await storage_service.upload_file(
+        file_data=image_bytes,
+        filename=f"thumbnail-{diagram_id}.png",
+        content_type="image/png",
+        account_id=str(current_user.account_id),
+    )
+    presigned_url = storage_service.get_presigned_url(storage_key)
+    diagram.thumbnail_url = presigned_url
+    await db.commit()
+
+
 @router.post("/ai-generate", response_model=AIGenerateResponse)
 async def ai_generate_diagram(
     data: AIGenerateRequest,
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> AIGenerateResponse:
-    available_slugs_set = await _get_available_slugs(current_user.team_id, db)
+    available_slugs_set = await _get_available_slugs(current_user.account_id, db)
     available_slugs = list(available_slugs_set)
 
     existing_node_ids: list[str] | None = None

backend/app/api/endpoints/onboarding.py

@@ -8,6 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_active_user
 from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.models.assistant_chat import AssistantChat
 from app.models.psa_connection import PsaConnection
 from app.models.session import Session
@@ -98,7 +99,7 @@ async def get_onboarding_status(
 
 @router.post("/onboarding-status/dismiss", response_model=OnboardingStatus)
 async def dismiss_onboarding(
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> OnboardingStatus:
     """Dismiss the onboarding checklist for the current user."""

backend/app/api/endpoints/ratings.py

@@ -91,6 +91,7 @@ async def submit_step_feedback(
         new_rating = StepRating(
             step_id=step_id,
             user_id=current_user.id,
+            account_id=current_user.account_id,
             session_id=session_uuid,
             was_helpful=data.was_helpful,
             # rating is nullable now — thumbs-only mode

backend/app/api/endpoints/script_builder.py

@@ -3,12 +3,14 @@ from typing import Annotated
 from uuid import UUID
 
 from fastapi import APIRouter, Depends, HTTPException, Request
-from sqlalchemy import text
+from sqlalchemy import select, text
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.database import get_db
 from app.core.rate_limit import limiter
 from app.api.deps import get_current_active_user
+from app.models.ai_session import AISession
 from app.models.user import User
 from app.models.script_builder_session import ScriptBuilderSession
 from app.schemas.script_builder import (
@@ -67,15 +69,85 @@ async def create_session(
     db: Annotated[AsyncSession, Depends(get_db)],
     current_user: Annotated[User, Depends(get_current_active_user)],
 ) -> ScriptBuilderSessionDetail:
-    """Start a new Script Builder session."""
+    """Start a new Script Builder session.
+
+    When origin='pilot_inline', behaves as get-or-create: the same row is
+    returned on repeated calls with the same (user, ai_session_id) pair.
+    Inline sessions are excluded from the session cap and the list endpoint.
+    """
+    # Phase 9: inline origin validation + authorization
+    if data.origin == "pilot_inline":
+        if data.ai_session_id is None:
+            raise HTTPException(
+                status_code=400,
+                detail="ai_session_id is required when origin='pilot_inline'",
+            )
+        # Ownership check: the pilot session must belong to the current user.
+        ai_session = await db.scalar(
+            select(AISession).where(
+                AISession.id == data.ai_session_id,
+                AISession.user_id == current_user.id,
+            )
+        )
+        if ai_session is None:
+            raise HTTPException(
+                status_code=404,
+                detail="Session not found",
+            )
+
+        # Idempotent get-or-create: if a pilot_inline row already exists for
+        # this (user, ai_session_id) pair, return it without creating a duplicate.
+        existing = await db.scalar(
+            select(ScriptBuilderSession).where(
+                ScriptBuilderSession.user_id == current_user.id,
+                ScriptBuilderSession.ai_session_id == data.ai_session_id,
+                ScriptBuilderSession.origin == "pilot_inline",
+            )
+        )
+        if existing is not None:
+            # Re-fetch with message_records loaded
+            session = await script_builder_service.get_session(db, existing.id, current_user.id)
+            return _session_to_detail(session)
+
+        # Create the inline session — wrap in IntegrityError catch for races.
+        try:
+            session = await script_builder_service.create_session(
+                db=db,
+                user_id=current_user.id,
+                account_id=current_user.account_id,
+                team_id=current_user.team_id,
+                language=data.language,
+                origin=data.origin,
+                ai_session_id=data.ai_session_id,
+            )
+            await db.commit()
+        except IntegrityError:
+            await db.rollback()
+            # Race: another request won the unique index — re-read the winner row.
+            existing = await db.scalar(
+                select(ScriptBuilderSession).where(
+                    ScriptBuilderSession.user_id == current_user.id,
+                    ScriptBuilderSession.ai_session_id == data.ai_session_id,
+                    ScriptBuilderSession.origin == "pilot_inline",
+                )
+            )
+            if existing is None:
+                raise
+            session = existing
+
+        # Re-fetch with message_records loaded
+        session = await script_builder_service.get_session(db, session.id, current_user.id)
+        return _session_to_detail(session)
+
+    # ── Standalone session ──────────────────────────────────────────────────
     # Acquire per-user advisory lock so concurrent create requests are serialized.
     # Without this, two simultaneous requests both read count < limit and both
     # insert, exceeding MAX_SESSIONS_PER_USER.
     user_lock_key = hash(str(current_user.id)) % (2**62)
     await db.execute(text("SELECT pg_advisory_xact_lock(:key)"), {"key": user_lock_key})
 
-    # Enforce max concurrent sessions
-    count = await script_builder_service.count_user_sessions(db, current_user.id)
+    # Enforce max concurrent sessions (inline sessions excluded from cap)
+    count = await script_builder_service.count_user_sessions(db, current_user.id, include_inline=False)
     if count >= MAX_SESSIONS_PER_USER:
         raise HTTPException(
             status_code=400,
@@ -85,8 +157,11 @@ async def create_session(
     session = await script_builder_service.create_session(
         db=db,
         user_id=current_user.id,
+        account_id=current_user.account_id,
         team_id=current_user.team_id,
         language=data.language,
+        origin=data.origin,
+        ai_session_id=data.ai_session_id,
     )
     await db.commit()
     # Re-fetch with message_records loaded

backend/app/api/endpoints/scripts.py

@@ -5,7 +5,7 @@ import re
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy import select, func, or_, literal
+from sqlalchemy import select, func, or_, literal, update as sa_update
 
 from app.core.database import get_db
 from app.api.deps import get_current_active_user
@@ -197,6 +197,7 @@ async def create_template(
     template = ScriptTemplate(
         category_id=data.category_id,
         team_id=current_user.team_id,
+        account_id=current_user.account_id,
         created_by=current_user.id,
         name=data.name,
         slug=slug,
@@ -364,6 +365,7 @@ async def generate_script(
     generation = ScriptGeneration(
         template_id=template.id,
         user_id=current_user.id,
+        account_id=current_user.account_id,
         team_id=current_user.team_id,
         session_id=data.session_id,
         ai_session_id=data.ai_session_id,
@@ -372,6 +374,20 @@ async def generate_script(
     )
     db.add(generation)
     template.usage_count += 1
+
+    # FlowPilot Phase 3: bump the linked AI session's state_version so the
+    # resolution-note preview cache invalidates. One-off scripts run outside
+    # any FlowPilot session — in that case the UPDATE matches zero rows.
+    if data.ai_session_id is not None:
+        # Local import: scripts endpoint stays independent of AI-session
+        # imports for non-AI generation paths.
+        from app.models.ai_session import AISession
+        await db.execute(
+            sa_update(AISession)
+            .where(AISession.id == data.ai_session_id)
+            .values(state_version=AISession.state_version + 1)
+        )
+
     await db.commit()
     await db.refresh(generation)
 

backend/app/api/endpoints/session_facts.py

@@ -0,0 +1,315 @@
+"""Session fact endpoints — the "What we know" CRUD surface for a FlowPilot session.
+
+All routes are sub-resources of `/ai-sessions/{session_id}`. Tenant isolation is
+enforced by RLS on `session_facts.account_id`; a user from another account
+literally cannot see or write facts for this session.
+
+Editability rule (per FLOWPILOT-MIGRATION.md Section 7.3):
+- `user_note` and `ai_synthesis` facts are editable at the card level.
+- `question` and `diagnostic_check` facts are read-only at the card level —
+  edit the source question/check instead. PATCH returns 403 for those.
+
+Fact promotion writes always bump `ai_sessions.state_version` so the
+resolution-note preview cache invalidates (Section 5.5).
+"""
+import logging
+from datetime import datetime, timezone
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_active_user, get_db, require_engineer_or_admin
+from app.models.ai_session import AISession
+from app.models.session_fact import SessionFact
+from app.models.user import User
+from app.schemas.session_fact import (
+    SessionFactCreateRequest,
+    SessionFactListResponse,
+    SessionFactPromoteRequest,
+    SessionFactResponse,
+    SessionFactUpdateRequest,
+)
+from app.services.fact_synthesis_service import (
+    FactSynthesisService,
+    list_facts_for_session,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai-sessions/{session_id}", tags=["session-facts"])
+
+# Source types whose facts can be edited at the card level (Section 7.3).
+_EDITABLE_SOURCE_TYPES = frozenset({"user_note", "ai_synthesis"})
+
+
+def _to_response(fact: SessionFact) -> SessionFactResponse:
+    """Wrap an ORM SessionFact in the response model with the editable flag."""
+    return SessionFactResponse(
+        id=fact.id,
+        session_id=fact.session_id,
+        text=fact.text,
+        source_type=fact.source_type,  # type: ignore[arg-type]
+        source_ref=fact.source_ref,
+        source_summary=fact.source_summary,
+        created_by=fact.created_by,
+        created_at=fact.created_at,
+        updated_at=fact.updated_at,
+        editable=fact.source_type in _EDITABLE_SOURCE_TYPES,
+    )
+
+
+async def _load_session_or_404(db: AsyncSession, session_id: UUID) -> AISession:
+    """Load the session via RLS-scoped SELECT. Returns 404 if missing/cross-tenant.
+
+    Tenant isolation: RLS on `ai_sessions` filters by current account, so a
+    cross-tenant access returns no rows and we 404 (rather than 403, which
+    would leak the row's existence).
+    """
+    result = await db.execute(select(AISession).where(AISession.id == session_id))
+    session = result.scalar_one_or_none()
+    if session is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not found")
+    return session
+
+
+async def _load_fact_or_404(
+    db: AsyncSession, session_id: UUID, fact_id: UUID
+) -> SessionFact:
+    """Load a non-deleted fact for the session. 404 if missing or already deleted."""
+    result = await db.execute(
+        select(SessionFact).where(
+            SessionFact.id == fact_id,
+            SessionFact.session_id == session_id,
+            SessionFact.deleted_at.is_(None),
+        )
+    )
+    fact = result.scalar_one_or_none()
+    if fact is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Fact not found")
+    return fact
+
+
+# ── List ──
+
+@router.get("/facts", response_model=SessionFactListResponse)
+async def list_facts(
+    session_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionFactListResponse:
+    """List facts for a session, oldest first."""
+    await _load_session_or_404(db, session_id)
+    facts = await list_facts_for_session(db, session_id)
+    return SessionFactListResponse(facts=[_to_response(f) for f in facts])
+
+
+# ── Create (manual user note) ──
+
+@router.post("/facts", response_model=SessionFactResponse, status_code=201)
+async def create_fact(
+    session_id: UUID,
+    body: SessionFactCreateRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionFactResponse:
+    """Create a manual fact (the "+ Add a note" UI affordance).
+
+    Always recorded as `source_type=user_note`. Source-typed creation goes
+    through `/facts/promote` so the originating item ID is captured.
+    """
+    session = await _load_session_or_404(db, session_id)
+    service = FactSynthesisService(db)
+    try:
+        fact = await service.create_fact(
+            session_id=session.id,
+            account_id=session.account_id,
+            user_id=current_user.id,
+            source_type="user_note",
+            text=body.text,
+            summary=body.summary,
+            source_ref=None,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    await db.commit()
+    await db.refresh(fact)
+    return _to_response(fact)
+
+
+# ── Update ──
+
+@router.patch("/facts/{fact_id}", response_model=SessionFactResponse)
+async def update_fact(
+    session_id: UUID,
+    fact_id: UUID,
+    body: SessionFactUpdateRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionFactResponse:
+    """Edit fact text or summary.
+
+    Returns 403 for `question` and `diagnostic_check`-sourced facts: the
+    source item is the canonical input, so editing the fact card would
+    desync the two. Engineers edit the source instead.
+    """
+    fact = await _load_fact_or_404(db, session_id, fact_id)
+    if fact.source_type not in _EDITABLE_SOURCE_TYPES:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=(
+                f"Facts sourced from {fact.source_type!r} are read-only at the "
+                "card level. Edit the originating question or diagnostic check instead."
+            ),
+        )
+
+    if body.text is None and body.summary is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="At least one of `text` or `summary` must be provided",
+        )
+
+    service = FactSynthesisService(db)
+    try:
+        fact = await service.update_fact(fact, text=body.text, summary=body.summary)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    await db.commit()
+    await db.refresh(fact)
+    return _to_response(fact)
+
+
+# ── Soft delete ──
+
+@router.delete("/facts/{fact_id}", status_code=204)
+async def delete_fact(
+    session_id: UUID,
+    fact_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> None:
+    """Soft-delete a fact. All source types are deletable.
+
+    Soft delete (rather than hard) preserves provenance for audit and lets
+    accidental deletes be recovered if needed. The `editable` flag does NOT
+    control deletion — even read-only facts can be removed when the
+    underlying question/check turned out to be wrong.
+    """
+    fact = await _load_fact_or_404(db, session_id, fact_id)
+    service = FactSynthesisService(db)
+    await service.soft_delete_fact(fact)
+    await db.commit()
+
+
+# ── Promote (AI marker + engineer-driven) ──
+
+@router.post("/facts/promote", response_model=SessionFactResponse, status_code=201)
+async def promote_fact(
+    session_id: UUID,
+    body: SessionFactPromoteRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionFactResponse:
+    """Convert a question answer / check result into a fact.
+
+    Two modes:
+
+    - `proposed_text` provided → persisted as-is.
+    - `raw_input` provided → server drafts text/summary via FactSynthesisService.
+
+    Exactly one of the two must be set. The engineer-facing UI typically uses
+    `proposed_text` after letting the engineer review/edit a draft.
+    """
+    if (body.proposed_text is None) == (body.raw_input is None):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Exactly one of `proposed_text` or `raw_input` must be provided",
+        )
+    if body.source_type == "ai_synthesis" and body.source_ref is not None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="`source_ref` must be null for source_type=ai_synthesis",
+        )
+
+    session = await _load_session_or_404(db, session_id)
+    service = FactSynthesisService(db)
+
+    text = body.proposed_text
+    summary = body.proposed_summary
+    if text is None:
+        # Synthesize via LLM. Caller must hint which task-lane item the input
+        # came from so we can shape the prompt appropriately.
+        raw = body.raw_input or ""
+        if body.source_type == "question":
+            draft = await service.synthesize_from_question(
+                question_text=_lookup_task_lane_text(session, body.source_ref, "questions"),
+                raw_answer=raw,
+            )
+        elif body.source_type == "diagnostic_check":
+            draft = await service.synthesize_from_check(
+                check_label=_lookup_task_lane_text(session, body.source_ref, "actions"),
+                check_output=raw,
+            )
+        else:
+            # ai_synthesis with raw_input: the raw input IS the synthesis.
+            # Re-run through the question synthesizer with an empty question
+            # so the conservative prompt still applies.
+            draft = await service.synthesize_from_question(
+                question_text="(none — synthesizing from engineer summary)",
+                raw_answer=raw,
+            )
+        text = draft["text"]
+        summary = summary or draft["summary"]
+        if not text:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail=(
+                    "Synthesizer found no substantive fact in the input. "
+                    "Edit the input or supply `proposed_text` directly."
+                ),
+            )
+
+    try:
+        fact = await service.create_fact(
+            session_id=session.id,
+            account_id=session.account_id,
+            user_id=current_user.id,
+            source_type=body.source_type,
+            text=text,
+            summary=summary,
+            source_ref=body.source_ref,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+    await db.commit()
+    await db.refresh(fact)
+    return _to_response(fact)
+
+
+def _lookup_task_lane_text(
+    session: AISession, source_ref: UUID | None, list_key: str
+) -> str:
+    """Find the originating question text / action label from pending_task_lane.
+
+    Falls back to a generic placeholder if the source item is no longer in
+    the lane (e.g., the AI dropped it from a later turn). The synthesizer is
+    forgiving — an empty/generic question still produces a useful fact when
+    the engineer's answer is substantive on its own.
+    """
+    if source_ref is None:
+        return ""
+    lane = session.pending_task_lane or {}
+    items = lane.get(list_key) or []
+    sref = str(source_ref)
+    for item in items:
+        if isinstance(item, dict) and str(item.get("id")) == sref:
+            return str(item.get("text") or item.get("label") or "")
+    return ""

backend/app/api/endpoints/session_suggested_fixes.py

@@ -0,0 +1,759 @@
+"""Suggested-fix + resolution-note / escalation-package preview-and-post endpoints.
+
+Phase 3: active suggested fix lookup + decision recording, resolution-note
+preview with state_version cache.
+
+Phase 4: resolution-note POST (writeback to PSA + mark resolved), escalation
+package preview + POST (writeback + mark escalated). Local-only path when
+the session has no linked PSA ticket: markdown is stored on the session and
+the status flipped, no external call.
+
+Per FLOWPILOT-MIGRATION.md Sections 5.2 + 5.4.
+"""
+import logging
+from datetime import datetime, timezone
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_active_user, get_db, require_engineer_or_admin
+from app.models.ai_session import AISession
+from app.models.session_suggested_fix import SessionSuggestedFix
+from app.models.user import User
+from app.schemas.session_suggested_fix import (
+    EscalationPackagePostRequest,
+    ResolutionNotePostRequest,
+    ResolutionNotePreviewResponse,
+    ResolutionPostResponse,
+    SessionSuggestedFixDecisionRequest,
+    SessionSuggestedFixDecisionResponse,
+    SessionSuggestedFixOutcomeRequest,
+    SessionSuggestedFixResponse,
+    SessionSuggestedFixScriptRequest,
+)
+from app.models.draft_template import DraftTemplate
+from app.models.session_fact import SessionFact
+from app.services.escalation_package_generator import EscalationPackageGeneratorService
+from app.services.preview_cache import preview_cache
+from app.services.psa_writeback_service import (
+    PSAStatusVerificationError,
+    PSAWritebackService,
+)
+from app.services.resolution_note_generator import ResolutionNoteGeneratorService
+from app.services.template_extraction_service import extract_parameters as _extract_template_parameters
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai-sessions/{session_id}", tags=["session-suggested-fixes"])
+
+
+async def _load_session_or_404(db: AsyncSession, session_id: UUID) -> AISession:
+    """RLS-scoped session load. 404 covers both missing and cross-tenant."""
+    result = await db.execute(select(AISession).where(AISession.id == session_id))
+    session = result.scalar_one_or_none()
+    if session is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not found")
+    return session
+
+
+# ── Suggested fix: active ──────────────────────────────────────────────────
+
+@router.get(
+    "/suggested-fixes/active",
+    response_model=SessionSuggestedFixResponse,
+)
+async def get_active_suggested_fix(
+    session_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionSuggestedFixResponse:
+    """Return the current active suggested fix (`superseded_at IS NULL`) or 404.
+
+    A session has at most one active fix. Multiple historical rows persist
+    for audit, but only the most-recent un-superseded one is returned here.
+    """
+    await _load_session_or_404(db, session_id)
+    result = await db.execute(
+        select(SessionSuggestedFix)
+        .where(
+            SessionSuggestedFix.session_id == session_id,
+            SessionSuggestedFix.superseded_at.is_(None),
+        )
+        .order_by(SessionSuggestedFix.created_at.desc())
+    )
+    fix = result.scalars().first()
+    if fix is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No active suggested fix for this session",
+        )
+    return SessionSuggestedFixResponse.model_validate(fix)
+
+
+# ── Suggested fix: decision ────────────────────────────────────────────────
+
+@router.post(
+    "/suggested-fixes/{fix_id}/decision",
+    response_model=SessionSuggestedFixDecisionResponse,
+)
+async def record_decision(
+    session_id: UUID,
+    fix_id: UUID,
+    body: SessionSuggestedFixDecisionRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionSuggestedFixDecisionResponse:
+    """Record the engineer's path choice on a suggested fix.
+
+    Phase 3 recorded the choice and (for `dismissed`) superseded the fix.
+    Phase 5 adds side effects: one_off / draft_template return the rendered
+    script; draft_template also creates a `draft_templates` row via the
+    TemplateExtractionService; build_template returns a redirect to the
+    Script Builder.
+    """
+    session_obj = await _load_session_or_404(db, session_id)
+
+    result = await db.execute(
+        select(SessionSuggestedFix).where(
+            SessionSuggestedFix.id == fix_id,
+            SessionSuggestedFix.session_id == session_id,
+        )
+    )
+    fix = result.scalar_one_or_none()
+    if fix is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Suggested fix not found"
+        )
+
+    # Once a fix has been superseded we still record the engineer's
+    # decision (it's a historical signal — "engineer dismissed the
+    # interim hypothesis"), but `dismissed` on a superseded row would
+    # be redundant noise.
+    if fix.superseded_at is not None and body.decision == "dismissed":
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="This fix is already superseded by a newer suggestion",
+        )
+
+    fix.user_decision = body.decision
+    if body.decision == "dismissed" and fix.superseded_at is None:
+        fix.superseded_at = datetime.now(timezone.utc)
+
+    # Engineer's choice changes the bundle the resolution-note preview sees,
+    # so bump state_version too.
+    await db.execute(
+        update(AISession)
+        .where(AISession.id == session_id)
+        .values(state_version=AISession.state_version + 1)
+    )
+
+    rendered_script: str | None = None
+    draft_template_id: UUID | None = None
+    redirect_path: str | None = None
+
+    # Phase 5 side effects. All three non-dismiss paths assume the fix has
+    # either a script_template_id (template match — use the dedicated
+    # /scripts/generate endpoint from the frontend, not this one) or an
+    # ai_drafted_script (custom script — this is the entry point).
+    if body.decision in ("one_off", "draft_template", "build_template"):
+        drafted = body.edited_script or fix.ai_drafted_script
+        if not drafted:
+            # Template-matched fixes take the regular /scripts/generate path.
+            # If a fix somehow reaches here without a drafted script AND
+            # without a template, that's a client-side wiring bug.
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=(
+                    "Suggested fix has no ai_drafted_script — use "
+                    "/api/v1/scripts/generate for template-matched fixes."
+                ),
+            )
+        rendered_script = drafted.strip()
+
+    if body.decision == "draft_template":
+        # TemplateExtractionService proposes the parameterization. Runs
+        # under the same transaction so a failure rolls back the decision.
+        session_ctx = await _summarize_session_for_extraction(db, session_id)
+        extraction = await _extract_template_parameters(
+            script_body=rendered_script or "",
+            session_context=session_ctx,
+            ticket_context=None,  # ticket context wiring lands in Phase 5 polish
+        )
+
+        draft = DraftTemplate(
+            account_id=session_obj.account_id,
+            source_session_id=session_obj.id,
+            source_user_id=current_user.id,
+            script_body=extraction["templated_body"] or (rendered_script or ""),
+            proposed_parameters={"parameters": extraction["parameters"]},
+            proposed_name=fix.title[:200] if fix.title else None,
+            status="pending",
+        )
+        db.add(draft)
+        await db.flush()
+        draft_template_id = draft.id
+
+    if body.decision == "build_template":
+        # Frontend navigates to the Script Builder preloaded with the
+        # drafted body. The builder wires the full parameterization flow;
+        # we hand it a scratch-pad query string, not persistent state.
+        redirect_path = (
+            f"/scripts/builder?from_session={session_obj.id}&fix={fix.id}"
+        )
+
+    await db.commit()
+    await db.refresh(fix)
+
+    return SessionSuggestedFixDecisionResponse(
+        id=fix.id,
+        user_decision=fix.user_decision,  # type: ignore[arg-type]
+        rendered_script=rendered_script,
+        draft_template_id=draft_template_id,
+        redirect_path=redirect_path,
+    )
+
+
+# ── Suggested fix: apply (stamp applied_at) ──────────────────────────────
+
+@router.post(
+    "/suggested-fixes/{fix_id}/apply",
+    response_model=SessionSuggestedFixResponse,
+)
+async def apply_suggested_fix(
+    session_id: UUID,
+    fix_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionSuggestedFixResponse:
+    """Stamp applied_at when the engineer clicks Apply in the ProposalBanner.
+
+    This does NOT change status (fix remains 'proposed'). Status only flips
+    when the engineer records an outcome via PATCH /outcome.
+
+    Rules:
+    - Fix must be in 'proposed' status; any other status → 409.
+    - Idempotent: if applied_at is already set, returns 200 with the unchanged row.
+    - Bumps ai_sessions.state_version so resolve/escalate preview generators
+      know the fix has entered the verifying phase.
+    """
+    await _load_session_or_404(db, session_id)
+
+    result = await db.execute(
+        select(SessionSuggestedFix).where(
+            SessionSuggestedFix.id == fix_id,
+            SessionSuggestedFix.session_id == session_id,
+        )
+    )
+    fix = result.scalar_one_or_none()
+    if fix is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Suggested fix not found"
+        )
+
+    if fix.status != "proposed":
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Apply is only valid from 'proposed'; fix is already '{fix.status}'",
+        )
+
+    # Idempotent: already stamped → return as-is without bumping state_version again.
+    if fix.applied_at is not None:
+        return SessionSuggestedFixResponse.model_validate(fix)
+
+    fix.applied_at = datetime.now(timezone.utc)
+
+    # Bump state_version so preview generators see the verifying-phase signal.
+    await db.execute(
+        update(AISession)
+        .where(AISession.id == session_id)
+        .values(state_version=AISession.state_version + 1)
+    )
+
+    await db.commit()
+    await db.refresh(fix)
+    return SessionSuggestedFixResponse.model_validate(fix)
+
+
+# ── Suggested fix: outcome ────────────────────────────────────────────────
+
+@router.patch(
+    "/suggested-fixes/{fix_id}/outcome",
+    response_model=SessionSuggestedFixResponse,
+)
+async def patch_suggested_fix_outcome(
+    session_id: UUID,
+    fix_id: UUID,
+    body: SessionSuggestedFixOutcomeRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionSuggestedFixResponse:
+    """Record the engineer's outcome for an applied fix.
+
+    See `SessionSuggestedFixOutcomeRequest` for transition rules.
+    """
+    await _load_session_or_404(db, session_id)
+    now = datetime.now(timezone.utc)
+
+    result = await db.execute(
+        select(SessionSuggestedFix).where(
+            SessionSuggestedFix.id == fix_id,
+            SessionSuggestedFix.session_id == session_id,
+        )
+    )
+    fix = result.scalar_one_or_none()
+    if fix is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Suggested fix not found"
+        )
+
+    if body.outcome == "applied_partial" and not (body.notes and body.notes.strip()):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="notes are required when outcome is applied_partial",
+        )
+
+    TERMINAL = {"applied_success", "applied_failed", "dismissed"}
+    if fix.status in TERMINAL:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Fix is already in terminal status {fix.status!r}",
+        )
+
+    fix.status = body.outcome
+    if body.outcome == "applied_partial":
+        fix.partial_notes = (body.notes or "").strip() or None
+    elif body.outcome == "applied_failed":
+        fix.failure_reason = (body.notes or "").strip() or None
+        fix.verified_at = now
+    elif body.outcome == "applied_success":
+        fix.verified_at = now
+    # dismissed: no timestamp/notes stamping
+
+    if fix.applied_at is None and body.outcome != "dismissed":
+        fix.applied_at = now
+
+    # Clear any pending AI outcome proposal — engineer has taken a terminal action.
+    fix.ai_outcome_proposal = None
+
+    # Outcome changes the bundle that resolution-note/escalation-package
+    # previews see, so bump state_version inside the same transaction —
+    # mirrors the pattern in record_decision above.
+    await db.execute(
+        update(AISession)
+        .where(AISession.id == session_id)
+        .values(state_version=AISession.state_version + 1)
+    )
+
+    await db.commit()
+    await db.refresh(fix)
+    return SessionSuggestedFixResponse.model_validate(fix)
+
+
+# ── Suggested fix: attach drafted script ─────────────────────────────────────
+
+@router.patch(
+    "/suggested-fixes/{fix_id}/script",
+    response_model=SessionSuggestedFixResponse,
+)
+async def patch_suggested_fix_script(
+    session_id: UUID,
+    fix_id: UUID,
+    body: SessionSuggestedFixScriptRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionSuggestedFixResponse:
+    """Attach an engineer-drafted script to a suggested fix.
+
+    Called by the inline Script Builder tab on Submit. Does NOT stamp
+    applied_at — a draft is not an application. Bumps state_version so
+    the Resolve/Escalate preview bundles regenerate.
+    """
+    await _load_session_or_404(db, session_id)
+
+    fix = await db.scalar(
+        select(SessionSuggestedFix).where(
+            SessionSuggestedFix.id == fix_id,
+            SessionSuggestedFix.session_id == session_id,
+        )
+    )
+    if fix is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Suggested fix not found")
+
+    TERMINAL = {"applied_success", "applied_failed", "dismissed"}
+    if fix.status in TERMINAL:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Fix is already in terminal status {fix.status!r}",
+        )
+
+    fix.ai_drafted_script = body.ai_drafted_script
+    fix.ai_drafted_parameters = body.ai_drafted_parameters
+
+    # Bump state_version on the parent session — previews cached by
+    # (session_id, state_version) must regenerate to reflect the new draft.
+    await db.execute(
+        update(AISession)
+        .where(AISession.id == session_id)
+        .values(state_version=AISession.state_version + 1)
+    )
+
+    await db.commit()
+    await db.refresh(fix)
+    return SessionSuggestedFixResponse.model_validate(fix)
+
+
+# ── Suggested fix: clear AI outcome proposal ("Not yet") ─────────────────────
+
+@router.delete(
+    "/suggested-fixes/{fix_id}/ai-outcome-proposal",
+    response_model=SessionSuggestedFixResponse,
+)
+async def clear_ai_outcome_proposal(
+    session_id: UUID,
+    fix_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> SessionSuggestedFixResponse:
+    """Explicitly dismiss the AI-proposed outcome banner ("Not yet").
+
+    Clears `ai_outcome_proposal` without touching status or state_version
+    (this is pure UI state, not outcome data). Idempotent: returns 200 even
+    when the field is already null. After this call the banner will not
+    re-surface on the next refreshSessionDerived unless the AI emits a new
+    proposal.
+    """
+    await _load_session_or_404(db, session_id)
+
+    result = await db.execute(
+        select(SessionSuggestedFix).where(
+            SessionSuggestedFix.id == fix_id,
+            SessionSuggestedFix.session_id == session_id,
+        )
+    )
+    fix = result.scalar_one_or_none()
+    if fix is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Suggested fix not found"
+        )
+
+    fix.ai_outcome_proposal = None
+
+    await db.commit()
+    await db.refresh(fix)
+    return SessionSuggestedFixResponse.model_validate(fix)
+
+
+async def _summarize_session_for_extraction(
+    db: AsyncSession, session_id: UUID,
+) -> str:
+    """Compact fact list for TemplateExtractionService context.
+
+    We don't send the full chat transcript — the extractor only needs enough
+    signal to decide which values in the script are session-specific (and
+    therefore worth parameterizing).
+    """
+    result = await db.execute(
+        select(SessionFact)
+        .where(
+            SessionFact.session_id == session_id,
+            SessionFact.deleted_at.is_(None),
+        )
+        .order_by(SessionFact.created_at.asc())
+    )
+    facts = list(result.scalars().all())
+    if not facts:
+        return ""
+    lines = [f"- {f.text}" for f in facts]
+    return "\n".join(lines)
+
+
+# ── Resolution note preview ────────────────────────────────────────────────
+
+@router.post(
+    "/resolution-note/preview",
+    response_model=ResolutionNotePreviewResponse,
+)
+async def resolution_note_preview(
+    session_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> ResolutionNotePreviewResponse:
+    """Generate (or return cached) draft markdown for the Resolve note.
+
+    Cache key: `(resolution_note, session_id, state_version)`. State_version is
+    bumped by every fact / suggested-fix / script-generation write, so two
+    consecutive calls with no intervening writes return the same cached
+    payload (and won't pay for a Sonnet call).
+
+    Posted to PSA in Phase 4. Until then, this endpoint is read-only.
+    """
+    await _load_session_or_404(db, session_id)
+    gen = ResolutionNoteGeneratorService(db)
+    try:
+        payload = await gen.generate_or_get_cached(session_id)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+    except Exception as e:
+        logger.exception("Resolution note preview failed for session %s", session_id)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"Resolution-note generator error ({type(e).__name__})",
+        )
+    return ResolutionNotePreviewResponse(**payload)
+
+
+# ── Phase 4: escalation-package preview ────────────────────────────────────
+
+@router.post(
+    "/escalation-package/preview",
+    response_model=ResolutionNotePreviewResponse,
+)
+async def escalation_package_preview(
+    session_id: UUID,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> ResolutionNotePreviewResponse:
+    """Generate (or return cached) draft markdown for the Escalate handoff package.
+
+    Same caching story as the resolution-note preview: keyed on
+    `(session_id, state_version)`. Separate cache kind so a Resolve preview
+    and an Escalate preview for the same state can coexist.
+    """
+    await _load_session_or_404(db, session_id)
+    gen = EscalationPackageGeneratorService(db)
+    try:
+        payload = await gen.generate_or_get_cached(session_id)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+    except Exception as e:
+        logger.exception("Escalation package preview failed for session %s", session_id)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"Escalation-package generator error ({type(e).__name__})",
+        )
+    return ResolutionNotePreviewResponse(**payload)
+
+
+# ── Phase 4: Resolve & post ────────────────────────────────────────────────
+
+@router.post(
+    "/resolution-note/post",
+    response_model=ResolutionPostResponse,
+)
+async def post_resolution_note(
+    session_id: UUID,
+    body: ResolutionNotePostRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> ResolutionPostResponse:
+    """Commit the engineer-edited resolution note and close the session.
+
+    Three outcomes:
+    - **External post + status verified** — session.status='resolved',
+      markdown + external_id + posted_at persisted, CW status flipped to
+      the configured Resolved status ID and re-fetch-verified.
+    - **External post only** — markdown posted, but no cw_resolved_status_id
+      configured → session.status='resolved', `status_transition_skipped_reason`
+      explains the skip. Not an error — posting the note is meaningful.
+    - **Local-only** — session has no linked PSA ticket → markdown stored on
+      `resolution_note_markdown`, session.status='resolved', outcome =
+      'resolved_local'. No external call.
+
+    Status verification failure raises 502: the engineer intended to close
+    the ticket but we cannot confirm it actually closed. Surfacing silent
+    success would be a footgun.
+    """
+    session_obj = await _load_session_or_404(db, session_id)
+    if session_obj.status not in ("active", "paused", "requesting_escalation", "escalated"):
+        # Already-resolved sessions shouldn't be re-posted; caller should
+        # query first. escalated→resolved is allowed (engineer revised course).
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Session is already {session_obj.status}",
+        )
+
+    service = PSAWritebackService(db)
+    summary = (body.resolution_summary or body.markdown.strip().splitlines()[0])[:500]
+
+    # Local-only path — no PSA ticket linked, nothing to post.
+    if not session_obj.psa_ticket_id or not session_obj.psa_connection_id:
+        session_obj.resolution_note_markdown = body.markdown.strip()
+        session_obj.status = "resolved"
+        session_obj.resolved_at = datetime.now(timezone.utc)
+        session_obj.resolution_summary = summary
+        await db.commit()
+        return ResolutionPostResponse(
+            outcome="resolved_local",
+            session_status=session_obj.status,
+        )
+
+    try:
+        posted = await service.post_resolution_note(session_obj, body.markdown)
+    except Exception as e:
+        logger.exception("post_resolution_note failed for session %s", session_id)
+        await db.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"PSA post failed ({type(e).__name__})",
+        )
+
+    # Attempt the status transition if configured; failed verification is
+    # surfaced loudly (status_code 502) per the ConnectWise anti-silent-
+    # success principle. Not configured → skip with a reason, not an error.
+    target_status_id = await service.resolved_status_id_for_account(session_obj.account_id)
+    verified_status_id: int | None = None
+    verified_status_name: str | None = None
+    skipped_reason: str | None = None
+    if target_status_id is None:
+        skipped_reason = (
+            "No cw_resolved_status_id configured in account_settings.preferences — "
+            "note posted, status unchanged."
+        )
+    else:
+        try:
+            result = await service.transition_ticket_status(session_obj, target_status_id)
+            verified_status_id = result["verified_status_id"]
+            verified_status_name = result["verified_status_name"]
+        except PSAStatusVerificationError as e:
+            logger.error("Status verification failed for session %s: %s", session_id, e)
+            # Note was already posted — roll that partial side effect back in
+            # the session record (the CW note itself can't be un-posted).
+            await db.rollback()
+            raise HTTPException(
+                status_code=status.HTTP_502_BAD_GATEWAY,
+                detail=str(e),
+            )
+        except Exception as e:
+            logger.exception("Status transition failed for session %s", session_id)
+            await db.rollback()
+            raise HTTPException(
+                status_code=status.HTTP_502_BAD_GATEWAY,
+                detail=f"PSA status transition error ({type(e).__name__})",
+            )
+
+    session_obj.status = "resolved"
+    session_obj.resolved_at = datetime.now(timezone.utc)
+    session_obj.resolution_summary = summary
+    await db.commit()
+
+    return ResolutionPostResponse(
+        outcome="resolved",
+        session_status=session_obj.status,
+        external_id=posted["external_id"],
+        posted_at=posted["posted_at"],
+        verified_status_id=verified_status_id,
+        verified_status_name=verified_status_name,
+        status_transition_skipped_reason=skipped_reason,
+    )
+
+
+# ── Phase 4: Escalate & post ──────────────────────────────────────────────
+
+@router.post(
+    "/escalation-package/post",
+    response_model=ResolutionPostResponse,
+)
+async def post_escalation_package(
+    session_id: UUID,
+    body: EscalationPackagePostRequest,
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    _: None = Depends(require_engineer_or_admin),
+) -> ResolutionPostResponse:
+    """Commit the engineer-edited escalation package and mark the session escalated.
+
+    Structure mirrors post_resolution_note:
+    - Local-only when no PSA ticket: markdown stored, session.status='escalated'.
+    - PSA post: internal-analysis note (handoff is for the next engineer,
+      not the customer), optional status transition via cw_escalated_status_id,
+      re-fetch verified.
+    """
+    session_obj = await _load_session_or_404(db, session_id)
+    if session_obj.status not in ("active", "paused", "resolved"):
+        # resolved→escalated is allowed (engineer realized they need help
+        # after closing); escalated→escalated would be a no-op, block it.
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Session is already {session_obj.status}",
+        )
+
+    service = PSAWritebackService(db)
+    reason = body.escalation_reason or body.markdown.strip().splitlines()[0][:500]
+
+    if not session_obj.psa_ticket_id or not session_obj.psa_connection_id:
+        session_obj.escalation_package_markdown = body.markdown.strip()
+        session_obj.status = "escalated"
+        session_obj.escalation_reason = reason
+        await db.commit()
+        return ResolutionPostResponse(
+            outcome="escalated_local",
+            session_status=session_obj.status,
+        )
+
+    try:
+        posted = await service.post_escalation_package(session_obj, body.markdown)
+    except Exception as e:
+        logger.exception("post_escalation_package failed for session %s", session_id)
+        await db.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"PSA post failed ({type(e).__name__})",
+        )
+
+    target_status_id = await service.escalated_status_id_for_account(session_obj.account_id)
+    verified_status_id: int | None = None
+    verified_status_name: str | None = None
+    skipped_reason: str | None = None
+    if target_status_id is None:
+        skipped_reason = (
+            "No cw_escalated_status_id configured — package posted, status unchanged."
+        )
+    else:
+        try:
+            result = await service.transition_ticket_status(session_obj, target_status_id)
+            verified_status_id = result["verified_status_id"]
+            verified_status_name = result["verified_status_name"]
+        except PSAStatusVerificationError as e:
+            logger.error("Status verification failed for session %s: %s", session_id, e)
+            await db.rollback()
+            raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(e))
+        except Exception as e:
+            logger.exception("Status transition failed for session %s", session_id)
+            await db.rollback()
+            raise HTTPException(
+                status_code=status.HTTP_502_BAD_GATEWAY,
+                detail=f"PSA status transition error ({type(e).__name__})",
+            )
+
+    session_obj.status = "escalated"
+    session_obj.escalation_reason = reason
+    await db.commit()
+
+    return ResolutionPostResponse(
+        outcome="escalated",
+        session_status=session_obj.status,
+        external_id=posted["external_id"],
+        posted_at=posted["posted_at"],
+        verified_status_id=verified_status_id,
+        verified_status_name=verified_status_name,
+        status_transition_skipped_reason=skipped_reason,
+    )
+
+
+# ── Helper used by tests ───────────────────────────────────────────────────
+
+def _clear_preview_cache_for_tests() -> None:
+    """Reset the singleton cache between tests."""
+    preview_cache._store.clear()  # noqa: SLF001 — test-only access

backend/app/api/endpoints/sessions.py

@@ -143,8 +143,8 @@ async def get_session(
 
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this session"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     return session
@@ -196,6 +196,7 @@ async def start_session(
     new_session = Session(
         tree_id=tree.id,
         user_id=current_user.id,
+        account_id=current_user.account_id,
         tree_snapshot=tree_snapshot,
         path_taken=[],
         decisions=[],
@@ -234,8 +235,8 @@ async def update_session(
 
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this session"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     if session.completed_at:
@@ -281,8 +282,8 @@ async def complete_session(
 
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this session"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     if session.completed_at:
@@ -319,8 +320,8 @@ async def update_scratchpad(
 
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this session"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     session.scratchpad = data.scratchpad
@@ -348,8 +349,8 @@ async def update_session_variables(
 
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this session"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     if session.completed_at:
@@ -387,8 +388,8 @@ async def export_session(
 
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this session"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     # PDF export — separate path with binary response
@@ -693,6 +694,7 @@ async def prepare_session(
     new_session = Session(
         tree_id=tree.id,
         user_id=data.assigned_to_id or current_user.id,
+        account_id=current_user.account_id,
         tree_snapshot=tree_snapshot,
         path_taken=[],
         decisions=[],
@@ -770,6 +772,7 @@ async def batch_launch_sessions(
         session = Session(
             tree_id=tree.id,
             user_id=current_user.id,
+            account_id=current_user.account_id,
             tree_snapshot=tree_snapshot,
             path_taken=[],
             decisions=[],
@@ -830,8 +833,8 @@ async def link_ticket(
     if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
         if not current_user.is_super_admin:
             raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
-                detail="You don't have access to this session",
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Session not found",
             )
 
     # Unlink
@@ -1102,6 +1105,7 @@ async def psa_post_to_ticket(
     # Log to audit trail
     log_entry = PsaPostLog(
         session_id=session.id,
+        account_id=session.account_id,
         psa_connection_id=psa_connection.id if psa_connection else None,
         ticket_id=session.psa_ticket_id,
         note_type=data.note_type,

backend/app/api/endpoints/shares.py

@@ -9,6 +9,7 @@ from sqlalchemy.orm import joinedload
 from sqlalchemy.exc import IntegrityError
 
 from app.core.database import get_db
+from app.core.admin_database import get_admin_db
 from app.models.session import Session
 from app.models.session_share import SessionShare, SessionShareView
 from app.models.user import User
@@ -72,8 +73,8 @@ async def create_share(
 
     if session.user_id != current_user.id and not current_user.is_super_admin:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Only the session owner can create share links"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
         )
 
     # Require account_id for account-scoped shares
@@ -170,8 +171,8 @@ async def revoke_share(
 
     if share.created_by != current_user.id and not current_user.is_super_admin:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Only the share creator can revoke it"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Share not found"
         )
 
     share.is_active = False
@@ -210,7 +211,7 @@ async def _get_optional_user(request: Request, db: AsyncSession) -> Optional[Use
 async def access_share(
     share_token: str,
     request: Request,
-    db: Annotated[AsyncSession, Depends(get_db)],
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
 ):
     """Access a shared session via share token.
 

backend/app/api/endpoints/step_categories.py

@@ -16,6 +16,7 @@ from app.schemas.step_category import (
 )
 from app.api.deps import get_current_active_user
 from app.core.permissions import can_manage_step_category, can_create_step_category
+from app.core.service_account import PLATFORM_ACCOUNT_ID
 
 router = APIRouter(prefix="/step-categories", tags=["step-categories"])
 
@@ -44,13 +45,13 @@ async def list_step_categories(
     elif current_user.account_id:
         query = query.where(
             or_(
-                StepCategory.account_id.is_(None),  # Global
+                StepCategory.account_id == PLATFORM_ACCOUNT_ID,  # Global
                 StepCategory.account_id == current_user.account_id  # User's account
             )
         )
     else:
         # User has no account, only show global categories
-        query = query.where(StepCategory.account_id.is_(None))
+        query = query.where(StepCategory.account_id == PLATFORM_ACCOUNT_ID)
 
     query = query.order_by(StepCategory.display_order, StepCategory.name)
 
@@ -94,8 +95,8 @@ async def get_step_category(
     # Check access: global categories visible to all, account categories only to account members
     if category.account_id and category.account_id != current_user.account_id and not current_user.is_super_admin:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this step category"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Step category not found"
         )
 
     return StepCategoryResponse(
@@ -155,7 +156,7 @@ async def create_step_category(
         name=category_data.name,
         slug=slug,
         description=category_data.description,
-        account_id=category_data.account_id,
+        account_id=category_data.account_id if category_data.account_id is not None else PLATFORM_ACCOUNT_ID,
         display_order=max_order + 1,
         created_by=current_user.id
     )

backend/app/api/endpoints/steps.py

@@ -47,10 +47,10 @@ async def get_step_or_404(
         raise HTTPException(status_code=404, detail="Step not found")
 
     if check_view and not can_view_step(current_user, step):
-        raise HTTPException(status_code=403, detail="Not authorized to view this step")
+        raise HTTPException(status_code=404, detail="Step not found")
 
     if check_edit and not can_edit_step(current_user, step):
-        raise HTTPException(status_code=403, detail="Not authorized to modify this step")
+        raise HTTPException(status_code=404, detail="Step not found")
 
     return step
 
@@ -460,6 +460,7 @@ async def rate_step(
     rating = StepRating(
         step_id=step_id,
         user_id=current_user.id,
+        account_id=current_user.account_id,
         rating=rating_data.rating,
         was_helpful=rating_data.was_helpful,
         review_text=rating_data.review_text,

backend/app/api/endpoints/supporting_data.py

@@ -103,6 +103,7 @@ async def create_supporting_data(
 
     item = SessionSupportingData(
         session_id=session_id,
+        account_id=session.account_id,
         label=data.label,
         data_type=data.data_type,
         content=data.content,

backend/app/api/endpoints/tags.py

@@ -12,6 +12,7 @@ from app.models.user import User
 from app.schemas.tag import TagCreate, TagResponse, TagListResponse, TagAssignment
 from app.api.deps import get_current_active_user
 from app.core.permissions import can_manage_tree_tags, can_create_tag
+from app.core.service_account import PLATFORM_ACCOUNT_ID
 
 router = APIRouter(prefix="/tags", tags=["tags"])
 
@@ -33,13 +34,13 @@ async def list_tags(
     if include_account and current_user.account_id:
         query = query.where(
             or_(
-                TreeTag.account_id.is_(None),  # Global
+                TreeTag.account_id == PLATFORM_ACCOUNT_ID,  # Global
                 TreeTag.account_id == current_user.account_id  # User's account
             )
         )
     else:
         # Only show global tags
-        query = query.where(TreeTag.account_id.is_(None))
+        query = query.where(TreeTag.account_id == PLATFORM_ACCOUNT_ID)
 
     query = query.order_by(TreeTag.usage_count.desc(), TreeTag.name)
 
@@ -71,12 +72,12 @@ async def search_tags(
     if include_account and current_user.account_id:
         query = query.where(
             or_(
-                TreeTag.account_id.is_(None),
+                TreeTag.account_id == PLATFORM_ACCOUNT_ID,
                 TreeTag.account_id == current_user.account_id
             )
         )
     else:
-        query = query.where(TreeTag.account_id.is_(None))
+        query = query.where(TreeTag.account_id == PLATFORM_ACCOUNT_ID)
 
     query = query.order_by(TreeTag.usage_count.desc(), TreeTag.name).limit(limit)
 
@@ -105,8 +106,8 @@ async def get_tag(
     # Check access: global tags visible to all, account tags only to account members
     if tag.account_id and tag.account_id != current_user.account_id and not current_user.is_super_admin:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this tag"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Tag not found"
         )
 
     return TagResponse.model_validate(tag)
@@ -147,7 +148,7 @@ async def create_tag(
     new_tag = TreeTag(
         name=tag_data.name,
         slug=slug,
-        account_id=tag_data.account_id,
+        account_id=tag_data.account_id if tag_data.account_id is not None else PLATFORM_ACCOUNT_ID,
         created_by=current_user.id
     )
     db.add(new_tag)
@@ -206,7 +207,7 @@ async def add_tags_to_tree(
         tag_query = select(TreeTag).where(
             TreeTag.slug == slug,
             or_(
-                TreeTag.account_id.is_(None),  # Global tag
+                TreeTag.account_id == PLATFORM_ACCOUNT_ID,  # Global tag
                 TreeTag.account_id == tag_account_id  # Account tag
             )
         )
@@ -340,7 +341,7 @@ async def replace_tree_tags(
         tag_query = select(TreeTag).where(
             TreeTag.slug == slug,
             or_(
-                TreeTag.account_id.is_(None),
+                TreeTag.account_id == PLATFORM_ACCOUNT_ID,
                 TreeTag.account_id == tag_account_id
             )
         )

backend/app/api/endpoints/target_lists.py

@@ -18,12 +18,10 @@ async def list_target_lists(
     current_user: Annotated[User, Depends(get_current_active_user)],
     db: Annotated[AsyncSession, Depends(get_db)],
 ):
-    """List all target lists for the current user's team."""
-    if not current_user.team_id:
-        return []
+    """List all target lists for the current user's account."""
     result = await db.execute(
         select(TargetList)
-        .where(TargetList.team_id == current_user.team_id)
+        .where(TargetList.account_id == current_user.account_id)
         .order_by(TargetList.name)
     )
     return result.scalars().all()
@@ -36,11 +34,9 @@ async def create_target_list(
     db: Annotated[AsyncSession, Depends(get_db)],
     _: None = Depends(require_engineer_or_admin),
 ):
-    """Create a new target list for the current team."""
-    if not current_user.team_id:
-        raise HTTPException(status_code=400, detail="User must belong to a team")
+    """Create a new target list for the current account."""
     target_list = TargetList(
-        team_id=current_user.team_id,
+        account_id=current_user.account_id,
         created_by=current_user.id,
         name=data.name,
         description=data.description,
@@ -61,7 +57,7 @@ async def get_target_list(
     result = await db.execute(
         select(TargetList).where(
             TargetList.id == list_id,
-            TargetList.team_id == current_user.team_id,
+            TargetList.account_id == current_user.account_id,
         )
     )
     target_list = result.scalar_one_or_none()
@@ -81,7 +77,7 @@ async def update_target_list(
     result = await db.execute(
         select(TargetList).where(
             TargetList.id == list_id,
-            TargetList.team_id == current_user.team_id,
+            TargetList.account_id == current_user.account_id,
         )
     )
     target_list = result.scalar_one_or_none()
@@ -91,7 +87,7 @@ async def update_target_list(
     if "name" in update_fields and data.name is not None:
         target_list.name = data.name
     if "description" in update_fields:
-        target_list.description = data.description  # allow setting to None
+        target_list.description = data.description
     if "targets" in update_fields and data.targets is not None:
         target_list.targets = [t.model_dump() for t in data.targets]
     await db.commit()
@@ -109,7 +105,7 @@ async def delete_target_list(
     result = await db.execute(
         select(TargetList).where(
             TargetList.id == list_id,
-            TargetList.team_id == current_user.team_id,
+            TargetList.account_id == current_user.account_id,
         )
     )
     target_list = result.scalar_one_or_none()

backend/app/api/endpoints/trees.py

@@ -29,6 +29,7 @@ from app.core.subscriptions import check_tree_limit, get_account_subscription, g
 from app.core.audit import log_audit
 from app.core.config import settings
 from app.core.tree_validation import can_publish_tree
+from app.core.service_account import PLATFORM_ACCOUNT_ID
 from app.core.step_sync import sync_steps_from_tree, deactivate_synced_steps_for_tree
 from app.services.rag_service import index_tree as rag_index_tree
 
@@ -391,9 +392,10 @@ async def get_tree(
         )
 
     if not tree.is_active or not can_access_tree(current_user, tree):
+        # Always 404, never 403. A 403 confirms the resource exists.
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You don't have access to this tree"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Tree not found"
         )
 
     return build_full_tree_response(tree)
@@ -470,7 +472,7 @@ async def create_tree(
         tree_structure=tree_data.tree_structure,
         intake_form=intake_form_data,
         author_id=service_account_id if is_default else current_user.id,
-        account_id=None if is_default else current_user.account_id,
+        account_id=PLATFORM_ACCOUNT_ID if is_default else current_user.account_id,
         is_public=True if is_default else tree_data.is_public,  # Default trees are always public
         is_default=is_default,
         status=tree_data.status
@@ -610,9 +612,17 @@ async def update_tree(
         )
 
     if not can_edit_tree(current_user, tree):
+        # If the user can see this tree (same account, team visibility), give a 403 with
+        # a clear message — returning 404 here would be confusing since GET returns 200.
+        # For truly inaccessible trees (cross-account), return 404 to avoid confirming existence.
+        if can_access_tree(current_user, tree):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You do not have permission to edit this flow"
+            )
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You can only edit your own trees"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Tree not found"
         )
 
     # Extract tags for separate handling
@@ -1038,6 +1048,7 @@ async def create_tree_share(
     # Create share
     tree_share = TreeShare(
         tree_id=tree.id,
+        account_id=tree.account_id,  # share belongs to the tree's tenant, not the actor
         share_token=share_token,
         created_by=current_user.id,
         allow_forking=share_data.allow_forking,
@@ -1144,9 +1155,17 @@ async def update_tree_visibility(
         )
 
     if not can_edit_tree(current_user, tree):
+        # If the user can see this tree (same account, team visibility), give a 403 with
+        # a clear message — returning 404 here would be confusing since GET returns 200.
+        # For truly inaccessible trees (cross-account), return 404 to avoid confirming existence.
+        if can_access_tree(current_user, tree):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You do not have permission to edit this flow"
+            )
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="You can only edit your own trees"
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Tree not found"
         )
 
     # Update visibility

backend/app/api/endpoints/uploads.py

@@ -255,9 +255,9 @@ async def get_upload_url(
     if upload is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Upload not found")
 
-    # Verify the upload belongs to the user's account
+    # Verify the upload belongs to the user's account — 404 to avoid revealing existence
     if upload.account_id != current_user.account_id and not current_user.is_super_admin:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Upload not found")
 
     url = storage_service.get_presigned_url(upload.storage_key)
     return {"url": url}
@@ -311,9 +311,9 @@ async def delete_upload(
     if upload is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Upload not found")
 
-    # Verify ownership
+    # Verify ownership — 404 to avoid revealing existence
     if upload.uploaded_by != current_user.id and not current_user.is_super_admin:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Upload not found")
 
     # Delete from S3
     await storage_service.delete_file(upload.storage_key)

backend/app/api/router.py

@@ -1,53 +1,94 @@
-from fastapi import APIRouter
-from app.api.endpoints import auth, trees, sessions, sidebar, invite, categories, tags, folders, step_categories, steps, admin, accounts, webhooks, shares, shared, tree_markdown
-from app.api.endpoints import admin_dashboard, admin_audit, admin_plan_limits, admin_feature_flags, admin_settings, admin_categories
-from app.api.endpoints import ratings, analytics
-from app.api.endpoints import target_lists
-from app.api.endpoints import maintenance_schedules
-from app.api.endpoints import feedback
-from app.api.endpoints import ai_builder
-from app.api.endpoints import ai_fix
-from app.api.endpoints import ai_chat
-from app.api.endpoints import copilot
-from app.api.endpoints import assistant_chat
-from app.api.endpoints import survey
-from app.api.endpoints import admin_survey
-from app.api.endpoints import tree_transfer
-from app.api.endpoints import ai_suggestions
-from app.api.endpoints import kb_accelerator
-from app.api.endpoints import beta_signup
-from app.api.endpoints import scripts
-from app.api.endpoints import integrations
-from app.api.endpoints import onboarding
-from app.api.endpoints import branding
-from app.api.endpoints import supporting_data
-from app.api.endpoints import ai_sessions
-from app.api.endpoints import flow_proposals
-from app.api.endpoints import flowpilot_analytics
-from app.api.endpoints import notifications
-from app.api.endpoints import public_templates
-from app.api.endpoints import admin_gallery
-from app.api.endpoints import uploads
-from app.api.endpoints import script_builder
-from app.api.endpoints import beta_feedback
-from app.api.endpoints import session_branches
-from app.api.endpoints import session_handoffs
-from app.api.endpoints import session_resolutions
-from app.api.endpoints import device_types
-from app.api.endpoints import network_diagrams
+from fastapi import APIRouter, Depends
+
+from app.api.deps import require_tenant_context
+from app.api.endpoints import (
+    admin,
+    admin_audit,
+    admin_categories,
+    admin_dashboard,
+    admin_feature_flags,
+    admin_gallery,
+    admin_plan_limits,
+    admin_settings,
+    admin_survey,
+    ai_builder,
+    ai_chat,
+    ai_fix,
+    ai_sessions,
+    ai_suggestions,
+    analytics,
+    assistant_chat,
+    auth,
+    beta_feedback,
+    beta_signup,
+    branding,
+    categories,
+    copilot,
+    device_types,
+    draft_templates,
+    feedback,
+    flow_proposals,
+    flowpilot_analytics,
+    folders,
+    integrations,
+    invite,
+    kb_accelerator,
+    maintenance_schedules,
+    network_diagrams,
+    notifications,
+    onboarding,
+    public_templates,
+    ratings,
+    scripts,
+    script_builder,
+    session_branches,
+    session_facts,
+    session_handoffs,
+    session_resolutions,
+    session_suggested_fixes,
+    sessions,
+    shared,
+    shares,
+    sidebar,
+    step_categories,
+    steps,
+    supporting_data,
+    survey,
+    tags,
+    target_lists,
+    tree_markdown,
+    tree_transfer,
+    trees,
+    uploads,
+    webhooks,
+    accounts,
+)
 
 api_router = APIRouter()
 
+# ---------------------------------------------------------------------------
+# Public / unauthenticated endpoints — no tenant context
+#
+# Note: auth.router contains both public endpoints (register, login,
+# forgot-password, reset-password, email/verify) and authenticated endpoints
+# (GET/PATCH /me, logout, change-password, email/send-verification).
+# The authenticated auth endpoints only query the `users` table, which is
+# excluded from Phase 1 RLS. They work correctly without tenant context
+# in Phase 1. This will need revisiting in Phase 2 when `users` gets RLS.
+# ---------------------------------------------------------------------------
 api_router.include_router(auth.router)
-api_router.include_router(trees.router)
-api_router.include_router(sidebar.router)
-api_router.include_router(sessions.router)
-api_router.include_router(invite.router)
-api_router.include_router(categories.router)
-api_router.include_router(tags.router)
-api_router.include_router(folders.router)
-api_router.include_router(step_categories.router)
-api_router.include_router(steps.router)
+api_router.include_router(shared.router)       # Public share links (no auth)
+api_router.include_router(beta_signup.router)
+api_router.include_router(webhooks.router)     # Stripe webhook receiver
+api_router.include_router(public_templates.router)  # Public gallery (no auth, rate-limited)
+
+# ---------------------------------------------------------------------------
+# Admin endpoints — super_admin only
+# admin_categories, admin_gallery, admin_dashboard, admin query Phase 1 RLS
+# tables and MUST use get_admin_db (migrated in Task 8). The remaining admin
+# endpoints (admin_audit, admin_plan_limits, admin_feature_flags,
+# admin_settings, admin_survey) are safe until Phase 2 extends RLS.
+# ---------------------------------------------------------------------------
 api_router.include_router(admin.router)
 api_router.include_router(admin_dashboard.router)
 api_router.include_router(admin_audit.router)
@@ -55,44 +96,60 @@ api_router.include_router(admin_plan_limits.router)
 api_router.include_router(admin_feature_flags.router)
 api_router.include_router(admin_settings.router)
 api_router.include_router(admin_categories.router)
-api_router.include_router(accounts.router)
-api_router.include_router(webhooks.router)
-api_router.include_router(shares.router)
-api_router.include_router(shared.router)  # Public endpoints (no auth)
-api_router.include_router(tree_markdown.router)
-api_router.include_router(ratings.router)
-api_router.include_router(analytics.router)
-api_router.include_router(target_lists.router)
-api_router.include_router(maintenance_schedules.router)
-api_router.include_router(feedback.router)
-api_router.include_router(ai_builder.router)
-api_router.include_router(ai_fix.router)
-api_router.include_router(ai_chat.router)
-api_router.include_router(copilot.router)
-api_router.include_router(assistant_chat.router)
-api_router.include_router(survey.router)
 api_router.include_router(admin_survey.router)
-api_router.include_router(tree_transfer.router)
-api_router.include_router(ai_suggestions.router)
-api_router.include_router(kb_accelerator.router)
-api_router.include_router(beta_signup.router)
-api_router.include_router(scripts.router)
-api_router.include_router(integrations.router)
-api_router.include_router(onboarding.router)
-api_router.include_router(branding.router)
-api_router.include_router(supporting_data.router)
-api_router.include_router(network_diagrams.router)  # Must be before ai_sessions to avoid /{diagram_id} conflict
-api_router.include_router(session_handoffs.queue_router)  # Must be before ai_sessions to avoid /{session_id} conflict
-api_router.include_router(session_resolutions.router)  # Must be before ai_sessions to avoid /{session_id} conflict
-api_router.include_router(ai_sessions.router)
-api_router.include_router(flow_proposals.router)
-api_router.include_router(flowpilot_analytics.router)
-api_router.include_router(notifications.router)
-api_router.include_router(public_templates.router)
 api_router.include_router(admin_gallery.router)
-api_router.include_router(uploads.router)
-api_router.include_router(script_builder.router)
-api_router.include_router(beta_feedback.router)
-api_router.include_router(session_branches.router)
-api_router.include_router(session_handoffs.router)
-api_router.include_router(device_types.router)
+# ---------------------------------------------------------------------------
+# User-facing endpoints — tenant context required
+# ---------------------------------------------------------------------------
+_tenant_deps = [Depends(require_tenant_context)]
+
+api_router.include_router(trees.router, dependencies=_tenant_deps)
+api_router.include_router(sidebar.router, dependencies=_tenant_deps)
+api_router.include_router(sessions.router, dependencies=_tenant_deps)
+api_router.include_router(invite.router, dependencies=_tenant_deps)
+api_router.include_router(categories.router, dependencies=_tenant_deps)
+api_router.include_router(tags.router, dependencies=_tenant_deps)
+api_router.include_router(folders.router, dependencies=_tenant_deps)
+api_router.include_router(step_categories.router, dependencies=_tenant_deps)
+api_router.include_router(steps.router, dependencies=_tenant_deps)
+api_router.include_router(accounts.router, dependencies=_tenant_deps)
+api_router.include_router(shares.router, dependencies=_tenant_deps)
+api_router.include_router(tree_markdown.router, dependencies=_tenant_deps)
+api_router.include_router(ratings.router, dependencies=_tenant_deps)
+api_router.include_router(analytics.router, dependencies=_tenant_deps)
+api_router.include_router(target_lists.router, dependencies=_tenant_deps)
+api_router.include_router(maintenance_schedules.router, dependencies=_tenant_deps)
+api_router.include_router(feedback.router, dependencies=_tenant_deps)
+api_router.include_router(ai_builder.router, dependencies=_tenant_deps)
+api_router.include_router(ai_fix.router, dependencies=_tenant_deps)
+api_router.include_router(ai_chat.router, dependencies=_tenant_deps)
+api_router.include_router(copilot.router, dependencies=_tenant_deps)
+api_router.include_router(assistant_chat.router, dependencies=_tenant_deps)
+api_router.include_router(survey.router, dependencies=_tenant_deps)
+api_router.include_router(tree_transfer.router, dependencies=_tenant_deps)
+api_router.include_router(ai_suggestions.router, dependencies=_tenant_deps)
+api_router.include_router(kb_accelerator.router, dependencies=_tenant_deps)
+api_router.include_router(scripts.router, dependencies=_tenant_deps)
+api_router.include_router(integrations.router, dependencies=_tenant_deps)
+api_router.include_router(onboarding.router, dependencies=_tenant_deps)
+api_router.include_router(branding.router, dependencies=_tenant_deps)
+api_router.include_router(supporting_data.router, dependencies=_tenant_deps)
+api_router.include_router(network_diagrams.router, dependencies=_tenant_deps)
+# session_handoffs queue router must come before ai_sessions to avoid conflict
+api_router.include_router(session_handoffs.queue_router, dependencies=_tenant_deps)
+api_router.include_router(session_resolutions.router, dependencies=_tenant_deps)
+# session_facts mounts under /ai-sessions/{id}/facts — register before ai_sessions
+# so the {session_id}/facts subpaths take precedence over any future generic catchalls.
+api_router.include_router(session_facts.router, dependencies=_tenant_deps)
+api_router.include_router(session_suggested_fixes.router, dependencies=_tenant_deps)
+api_router.include_router(draft_templates.router, dependencies=_tenant_deps)
+api_router.include_router(ai_sessions.router, dependencies=_tenant_deps)
+api_router.include_router(flow_proposals.router, dependencies=_tenant_deps)
+api_router.include_router(flowpilot_analytics.router, dependencies=_tenant_deps)
+api_router.include_router(notifications.router, dependencies=_tenant_deps)
+api_router.include_router(uploads.router, dependencies=_tenant_deps)
+api_router.include_router(script_builder.router, dependencies=_tenant_deps)
+api_router.include_router(beta_feedback.router, dependencies=_tenant_deps)
+api_router.include_router(session_branches.router, dependencies=_tenant_deps)
+api_router.include_router(session_handoffs.router, dependencies=_tenant_deps)
+api_router.include_router(device_types.router, dependencies=_tenant_deps)

backend/app/core/admin_database.py

@@ -0,0 +1,38 @@
+# backend/app/core/admin_database.py
+"""
+Admin database engine — connects as resolutionflow_admin (BYPASSRLS).
+
+Use ONLY where explicit application-level access control makes database-layer
+tenant filtering unnecessary: /admin/* endpoints, internal tooling, and public
+endpoints that enforce their own authorization before returning data (e.g.
+share access via opaque token + visibility check).
+"""
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config import settings
+
+admin_engine = create_async_engine(
+    settings.ADMIN_DATABASE_URL,
+    echo=settings.DEBUG,
+    future=True,
+)
+
+_admin_session_factory = async_sessionmaker(
+    admin_engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+async def get_admin_db() -> AsyncGenerator[AsyncSession, None]:
+    """Yield an admin DB session (BYPASSRLS). See module docstring for approved use cases."""
+    async with _admin_session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()

backend/app/core/ai_chat_service.py

@@ -40,7 +40,7 @@ CRITICAL BEHAVIORS:
 - Act as a senior engineer, not a chatbot. Use your domain knowledge to SUGGEST diagnostic steps, not just record what the user says.
 - When the user describes a problem area, demonstrate understanding by naming specific sub-categories, common causes, and relevant tools.
 - Challenge assumptions constructively: "Before we go down that path, have you considered checking X first? In my experience, that resolves 60% of these cases."
-- Capture SPECIFIC commands with exact syntax. Not "check the service" but "Get-Service ADSync | Select-Object Status, StartType".
+- Capture SPECIFIC commands with exact syntax (PowerShell/CLI invocations the engineer would actually paste into a shell), not vague directives like "check the service".
 - Include expected outcomes for every action: what does success look like?
 - Surface edge cases proactively: "What about multi-forest environments?" or "Does this change if they have conditional access policies?"
 - Explain WHY the diagnostic order matters: "We check connectivity before auth because a network issue masquerades as an auth failure."
@@ -74,7 +74,7 @@ STRUCTURAL RULES:
 - All IDs must be unique strings (use descriptive slugs like "check-service-status")
 
 CROSS-REFERENCE / LOOP-BACK PATTERN:
-When a troubleshooting path needs to loop back (e.g., after remediation, re-verify from an earlier checkpoint), set next_node_id to the target node's ID. Example: an action node "restart-ssh-service" can set next_node_id to "verify-ssh-connection" (an ancestor decision node) to create a re-verification loop.
+When a troubleshooting path needs to loop back (e.g., after remediation, re-verify from an earlier checkpoint), set next_node_id to the target node's ID — including ancestor decision nodes for re-verification loops. The target ID must already exist somewhere in the tree.
 """
 
 INTERVIEW_PROTOCOL = """
@@ -85,7 +85,7 @@ Ask broad questions to understand the problem domain and scope:
 - What type of issue is this flow for?
 - Who is the target audience? (Tier 1 help desk, Tier 2, Tier 3?)
 - What environment assumptions? (On-prem, hybrid, specific vendors?)
-Demonstrate domain expertise immediately. If the user says "Azure AD Sync failures," show understanding: "Are you primarily seeing password hash sync issues, object attribute sync failures, or full directory sync errors?"
+Demonstrate domain expertise immediately. When the user names a technology, ask a follow-up that proves you know its common failure modes — a sub-categorization question that only someone fluent in that area would think to ask. Use vocabulary native to whatever the user actually mentioned, not stock examples from past conversations.
 DO NOT emit [TREE_UPDATE] during scoping. You are still understanding the problem.
 
 PHASE 2 - DISCOVERY (current_phase: discovery):
@@ -130,7 +130,7 @@ Your response is natural conversational text. When the tree structure changes, i
 
 3. Metadata capture (when you learn the flow's name, description, or tags):
 [METADATA]
-{"name": "...", "description": "...", "tags": ["..."]}
+{"name": "<flow name>", "description": "<one-sentence summary>", "tags": ["<tag1>", "<tag2>"]}
 [/METADATA]
 
 IMPORTANT:
@@ -172,8 +172,8 @@ STRUCTURAL RULES:
 - All IDs must be unique descriptive slugs (e.g., "check-dns-resolution", not UUIDs)
 - The last step MUST be type "procedure_end"
 - Use section_headers to organize steps into logical phases
-- Commands are arrays of objects: [{"code": "Get-Service ADSync", "label": "Check sync service", "language": "powershell"}]
-- Descriptions support [VAR:variable_name] interpolation for intake form variables (e.g., "Connect to [VAR:server_name] via RDP")
+- Commands are arrays of objects: [{"code": "<exact command>", "label": "<short label>", "language": "powershell|bash|cmd"}]
+- Descriptions support [VAR:variable_name] interpolation for intake form variables. Pick variable names that fit the procedure being built — do not reuse names from prior conversations.
 
 VARIABLE INTERPOLATION:
 When the procedure needs per-execution input (server name, IP address, client name, etc.), use [VAR:variable_name] syntax in descriptions and commands. These map to intake form fields that the engineer fills in before starting.
@@ -188,7 +188,7 @@ Understand the process being documented:
 - Who will execute it? (Tier 1 help desk, Tier 2, senior engineers?)
 - What environment context? (Specific vendor, on-prem vs cloud, tools available?)
 - Will this need per-execution input? (server name, client info, IP addresses → intake form fields)
-Demonstrate domain expertise: if the user says "Exchange Online mailbox migration," show understanding: "Are we covering full tenant-to-tenant migration, on-prem to Exchange Online cutover, or individual mailbox moves with hybrid?"
+Demonstrate domain expertise: when the user names a process, ask a sub-categorization question that distinguishes which variant of that process they mean (the variants will differ by technology — use vocabulary specific to whatever the user mentioned, not examples from prior chats).
 DO NOT emit [STEPS_UPDATE] during scoping. You are still understanding the process.
 
 PHASE 2 - DISCOVERY (current_phase: discovery):
@@ -238,12 +238,12 @@ Your response is natural conversational text. When the step structure changes, i
 
 3. Metadata capture (when you learn the flow's name, description, or tags):
 [METADATA]
-{"name": "...", "description": "...", "tags": ["..."]}
+{"name": "<flow name>", "description": "<one-sentence summary>", "tags": ["<tag1>", "<tag2>"]}
 [/METADATA]
 
 4. Intake form suggestion (when intake form fields are identified):
 [INTAKE_FORM]
-[{"variable_name": "server_name", "label": "Server Name", "field_type": "text", "required": true, "placeholder": "e.g., DC01", "group_name": "Server Details", "display_order": 1}]
+[{"variable_name": "<snake_case_name>", "label": "<Human Label>", "field_type": "text|password|select|textarea|number|boolean", "required": true|false, "placeholder": "<short hint, optional>", "group_name": "<section heading, optional>", "display_order": <integer>}]
 [/INTAKE_FORM]
 
 IMPORTANT:
@@ -659,12 +659,12 @@ Requirements:
 
 Also provide metadata as a separate JSON object after the steps:
 [METADATA]
-{"name": "...", "description": "...", "tags": ["..."]}
+{"name": "<flow name>", "description": "<one-sentence summary>", "tags": ["<tag1>", "<tag2>"]}
 [/METADATA]
 
 If we discussed intake form fields, also include:
 [INTAKE_FORM]
-[{"variable_name": "server_name", "label": "Server Name", "field_type": "text", "required": true, "placeholder": "e.g., DC01", "group_name": "Server Details", "display_order": 1}]
+[{"variable_name": "<snake_case_name>", "label": "<Human Label>", "field_type": "text|password|select|textarea|number|boolean", "required": true|false, "placeholder": "<short hint, optional>", "group_name": "<section heading, optional>", "display_order": <integer>}]
 [/INTAKE_FORM]"""
     else:
         generation_instruction = """Based on our entire conversation, generate the COMPLETE and FINAL TreeStructure JSON for this flow.
@@ -681,7 +681,7 @@ Requirements:
 
 Also provide metadata as a separate JSON object after the tree:
 [METADATA]
-{"name": "...", "description": "...", "tags": ["..."]}
+{"name": "<flow name>", "description": "<one-sentence summary>", "tags": ["<tag1>", "<tag2>"]}
 [/METADATA]"""
 
     provider_messages.append({"role": "user", "content": generation_instruction})

backend/app/core/ai_fix_service.py

@@ -199,7 +199,10 @@ async def generate_fixes(
 
         try:
             text, in_tok, out_tok = await provider.generate_json(
-                system_prompt=FIX_SYSTEM_PROMPT,
+                system_prompt=[
+                    {"type": "text", "text": FIX_SYSTEM_PROMPT},
+                    # cacheable: stable constant across all fix attempts
+                ],
                 messages=messages,
                 max_tokens=2048,
             )
@@ -232,7 +235,11 @@ async def generate_fixes(
 
             try:
                 text2, in_tok2, out_tok2 = await provider.generate_json(
-                    system_prompt=FIX_SYSTEM_PROMPT,
+                    system_prompt=[
+                        {"type": "text", "text": FIX_SYSTEM_PROMPT},
+                        # cacheable: stable constant; retry reads the cached
+                        # system block from the first attempt above
+                    ],
                     messages=messages,
                     max_tokens=2048,
                 )

backend/app/core/ai_provider.py

@@ -3,16 +3,169 @@ AI Provider abstraction layer.
 
 Supports Gemini (google-genai) and Anthropic (anthropic) as interchangeable
 backends for JSON generation used by the AI Flow Builder.
+
+## Prompt caching (Anthropic only)
+
+Callers may pass `system_prompt` as either:
+
+- `str` — backward-compatible, uncached.
+- `list[SystemBlock]` — Anthropic structured system blocks. Each block is a
+  dict of shape `{"type": "text", "text": str, "cache_control": {...}?}`.
+
+Caching policy (policy α, per Phase 0.1 design):
+- If any block in the list carries an explicit `cache_control` key, that
+  caller-authored configuration is honored verbatim.
+- If no block carries `cache_control`, the provider applies
+  `cache_control: {"type": "ephemeral"}` to the first block only. First block
+  is the common "large static prefix" case (e.g. system prompt, reference data).
+
+Gemini ignores cache_control and concatenates list blocks into one system
+string — callers should not rely on Gemini for cache-hit behavior.
+
+TODO(phase0-verify): When a dev environment is available, verify cache-hit
+behavior by hitting any FlowPilot endpoint twice within the 5-minute
+ephemeral TTL. First call should emit `anthropic.cache` with
+`cache_creation_input_tokens > 0`; second call with `cache_read_input_tokens > 0`.
+If the second call returns zero reads, inspect the prefix for silent
+invalidators (timestamps, unsorted JSON keys, varying tool list ordering).
 """
 
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator
+from typing import Any
 
 from app.core.config import settings
 
 logger = logging.getLogger(__name__)
 
+# Anthropic structured system block. See module docstring for caching policy.
+SystemBlock = dict[str, Any]
+
+
+def _normalize_system_for_anthropic(
+    system_prompt: str | list[SystemBlock],
+) -> str | list[SystemBlock]:
+    """Return the value to pass as the `system=` parameter to the Anthropic API.
+
+    - Plain strings pass through untouched (uncached path).
+    - Lists are returned as structured system blocks. If no block in the list
+      carries an explicit `cache_control`, `cache_control: {"type": "ephemeral"}`
+      is applied to the FIRST block only (policy α).
+    - Caller-authored `cache_control` is never overwritten.
+    """
+    if isinstance(system_prompt, str):
+        return system_prompt
+
+    if not system_prompt:
+        # Empty list is not a meaningful system prompt — pass empty string so
+        # Anthropic treats this as "no system prompt" rather than erroring.
+        return ""
+
+    blocks = [dict(b) for b in system_prompt]
+    already_cached = any("cache_control" in b for b in blocks)
+
+    if not already_cached:
+        blocks[0]["cache_control"] = {"type": "ephemeral"}
+
+    return blocks
+
+
+def _flatten_system_for_gemini(
+    system_prompt: str | list[SystemBlock],
+) -> str:
+    """Gemini has no structured system blocks; concatenate list entries."""
+    if isinstance(system_prompt, str):
+        return system_prompt
+    return "\n\n".join(b.get("text", "") for b in system_prompt)
+
+
+def build_anthropic_chat_messages(
+    history: list[dict[str, Any]],
+    new_message: str,
+    images: list[dict[str, Any]] | None = None,
+    format_reminder: str | None = None,
+) -> list[dict[str, Any]]:
+    """Construct the Anthropic `messages` payload for a cached multi-turn chat.
+
+    Responsibilities:
+    - Copy the valid history messages in order.
+    - Apply `cache_control: ephemeral` to the LAST history message so the entire
+      conversation prefix is cached across turns. The new user message stays
+      uncached (it changes each turn).
+    - Append `format_reminder` to the new user message if provided. The reminder
+      is invisible to storage (caller's concern) but helps enforce structured
+      output compliance at generation time.
+    - If `images` are provided, render the new user message as a multimodal
+      content block list (images first, then text). Otherwise, render it as
+      a plain string.
+
+    This helper is Anthropic-specific: the cache-breakpoint pattern, ephemeral
+    cache_control, and multimodal block shape are all Anthropic conventions.
+    Do not call it from Gemini code paths.
+    """
+    messages: list[dict[str, Any]] = []
+    for msg in history:
+        messages.append({"role": msg["role"], "content": msg["content"]})
+
+    # Cache breakpoint on the last existing history message so the entire
+    # conversation prefix is cached across turns. Safe only when there IS a
+    # history message; otherwise the new message is the only message.
+    if messages:
+        last = messages[-1]
+        messages[-1] = {
+            "role": last["role"],
+            "content": [
+                {
+                    "type": "text",
+                    "text": last["content"],
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ],
+        }
+
+    effective_text = new_message + (format_reminder or "")
+
+    if images:
+        content_blocks: list[dict[str, Any]] = []
+        for img in images:
+            content_blocks.append(
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": img["media_type"],
+                        "data": img["data"],
+                    },
+                }
+            )
+        content_blocks.append({"type": "text", "text": effective_text})
+        messages.append({"role": "user", "content": content_blocks})
+    else:
+        messages.append({"role": "user", "content": effective_text})
+
+    return messages
+
+
+def _log_anthropic_cache_usage(usage: Any, model: str) -> None:
+    """Emit a structured log line capturing cache_read / cache_creation tokens."""
+    cache_read = getattr(usage, "cache_read_input_tokens", 0) or 0
+    cache_creation = getattr(usage, "cache_creation_input_tokens", 0) or 0
+    input_tokens = getattr(usage, "input_tokens", 0) or 0
+    output_tokens = getattr(usage, "output_tokens", 0) or 0
+    if cache_read or cache_creation:
+        logger.info(
+            "anthropic.cache",
+            extra={
+                "event": "anthropic.cache",
+                "model": model,
+                "cache_read_input_tokens": cache_read,
+                "cache_creation_input_tokens": cache_creation,
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+            },
+        )
+
 
 class AIProvider(ABC):
     """Abstract base class for AI providers."""
@@ -20,14 +173,16 @@ class AIProvider(ABC):
     @abstractmethod
     async def generate_json(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> tuple[str, int, int]:
         """Generate a JSON response from the AI model.
 
         Args:
-            system_prompt: System-level instruction for the model.
+            system_prompt: System-level instruction. Plain `str` is uncached
+                (Anthropic) or used as-is (Gemini). `list[SystemBlock]` enables
+                Anthropic prompt caching per module-docstring policy.
             messages: List of message dicts with "role" and "content" keys.
             max_tokens: Maximum output tokens.
 
@@ -39,37 +194,25 @@ class AIProvider(ABC):
     @abstractmethod
     async def generate_text(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> tuple[str, int, int]:
         """Generate a text response from the AI model (no JSON constraint).
 
-        Args:
-            system_prompt: System-level instruction for the model.
-            messages: List of message dicts with "role" and "content" keys.
-            max_tokens: Maximum output tokens.
-
-        Returns:
-            Tuple of (response_text, input_tokens, output_tokens).
+        See `generate_json` for argument semantics.
         """
         ...
 
     async def generate_text_stream(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> "AsyncIterator[str]":
         """Stream a text response token by token.
 
-        Args:
-            system_prompt: System-level instruction for the model.
-            messages: List of message dicts with "role" and "content" keys.
-            max_tokens: Maximum output tokens.
-
-        Yields:
-            Text chunks as they are generated.
+        See `generate_json` for argument semantics.
         """
         raise NotImplementedError("Streaming not supported for this provider")
         # Make this an async generator to satisfy type checker
@@ -85,14 +228,15 @@ class GeminiProvider(AIProvider):
 
     async def generate_json(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> tuple[str, int, int]:
         from google import genai
         from google.genai import types as genai_types
 
         client = genai.Client(api_key=self._api_key)
+        system_text = _flatten_system_for_gemini(system_prompt)
 
         # Convert messages to Gemini Content format
         contents: list[genai_types.Content] = []
@@ -106,7 +250,7 @@ class GeminiProvider(AIProvider):
             )
 
         config = genai_types.GenerateContentConfig(
-            system_instruction=system_prompt,
+            system_instruction=system_text,
             max_output_tokens=max_tokens,
             response_mime_type="application/json",
         )
@@ -137,14 +281,15 @@ class GeminiProvider(AIProvider):
 
     async def generate_text(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> tuple[str, int, int]:
         from google import genai
         from google.genai import types as genai_types
 
         client = genai.Client(api_key=self._api_key)
+        system_text = _flatten_system_for_gemini(system_prompt)
 
         contents: list[genai_types.Content] = []
         for msg in messages:
@@ -157,7 +302,7 @@ class GeminiProvider(AIProvider):
             )
 
         config = genai_types.GenerateContentConfig(
-            system_instruction=system_prompt,
+            system_instruction=system_text,
             max_output_tokens=max_tokens,
             # No response_mime_type — allow free-form text
         )
@@ -214,16 +359,17 @@ class AnthropicProvider(AIProvider):
 
     async def generate_json(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> tuple[str, int, int]:
         client = _get_anthropic_client(self._api_key, self._timeout)
+        normalized_system = _normalize_system_for_anthropic(system_prompt)
 
         response = await client.messages.create(
             model=self._model,
             max_tokens=max_tokens,
-            system=system_prompt,
+            system=normalized_system,
             messages=messages,
         )
 
@@ -231,12 +377,14 @@ class AnthropicProvider(AIProvider):
         input_tokens = response.usage.input_tokens
         output_tokens = response.usage.output_tokens
 
+        _log_anthropic_cache_usage(response.usage, self._model)
+
         return text, input_tokens, output_tokens
 
     async def generate_text(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> tuple[str, int, int]:
         # Anthropic doesn't differentiate between JSON and text mode
@@ -244,20 +392,28 @@ class AnthropicProvider(AIProvider):
 
     async def generate_text_stream(
         self,
-        system_prompt: str,
-        messages: list[dict[str, str]],
+        system_prompt: str | list[SystemBlock],
+        messages: list[dict[str, Any]],
         max_tokens: int = 4096,
     ) -> AsyncIterator[str]:
         client = _get_anthropic_client(self._api_key, self._timeout)
+        normalized_system = _normalize_system_for_anthropic(system_prompt)
 
         async with client.messages.stream(
             model=self._model,
             max_tokens=max_tokens,
-            system=system_prompt,
+            system=normalized_system,
             messages=messages,
         ) as stream:
             async for text in stream.text_stream:
                 yield text
+            # Per Anthropic SDK, get_final_message() resolves the stream's
+            # final usage object (including cache_read/cache_creation tokens).
+            try:
+                final = await stream.get_final_message()
+                _log_anthropic_cache_usage(final.usage, self._model)
+            except Exception as exc:  # best-effort telemetry, never fail the stream
+                logger.debug("anthropic.cache streaming usage unavailable: %s", exc)
 
 
 def get_ai_provider(model: str | None = None) -> AIProvider:

backend/app/core/ai_tree_generator_service.py

@@ -89,8 +89,10 @@ Additional rules:
 5. Use unique node IDs prefixed with the branch context (e.g., "gpo-check-link")
 6. Build the tree bottom-up in your head: create solution/leaf nodes first, then build parent nodes referencing their IDs
 
-Few-shot example showing correct action node next_node_id usage:
-{"id": "dns-root", "type": "decision", "question": "Can the client resolve any DNS names?", "help_text": "Run: nslookup google.com", "options": [{"id": "dns-opt-none", "label": "No — nslookup times out or returns 'server failed'", "next_node_id": "dns-check-service"}, {"id": "dns-opt-partial", "label": "Some names resolve but others fail", "next_node_id": "dns-check-specific"}], "children": [{"id": "dns-check-service", "type": "action", "title": "Check DNS Client Service", "description": "Verify the DNS Client service is running on the affected machine", "commands": ["Get-Service -Name Dnscache | Select-Object Status,StartType"], "expected_outcome": "Status should be Running", "next_node_id": "dns-service-solution"}, {"id": "dns-service-solution", "type": "solution", "title": "DNS Service Was Stopped", "description": "The DNS Client service was stopped, preventing all name resolution", "resolution_steps": ["Run: Start-Service Dnscache", "Set startup type: Set-Service Dnscache -StartupType Automatic", "Flush cache: ipconfig /flushdns", "Test: nslookup google.com"]}, {"id": "dns-check-specific", "type": "solution", "title": "Selective DNS Failure — Stale or Missing Records", "description": "Some records resolve correctly, indicating DNS is functional but specific records are stale or missing", "resolution_steps": ["Check DNS server for missing A/CNAME records", "Clear DNS cache on the DNS server: Clear-DnsServerCache", "Flush client cache: ipconfig /flushdns", "Verify with: nslookup <failing-hostname>"]}]}"""
+SHAPE-ONLY schema example (do not copy this content verbatim — it shows
+how IDs link, NOT what to ask or run; your real tree must reflect the
+branch the user described):
+{"id": "<root-slug>", "type": "decision", "question": "<diagnostic question for THIS branch>", "help_text": "<optional hint>", "options": [{"id": "<opt-1>", "label": "<observable answer 1>", "next_node_id": "<child-1>"}, {"id": "<opt-2>", "label": "<observable answer 2>", "next_node_id": "<child-2>"}], "children": [{"id": "<child-1>", "type": "action", "title": "<what to do>", "description": "<details>", "commands": ["<exact command for THIS branch>"], "expected_outcome": "<what success looks like>", "next_node_id": "<sibling-id>"}, {"id": "<sibling-id>", "type": "solution", "title": "<resolution title>", "description": "<resolution description>", "resolution_steps": ["<step 1>", "<step 2>"]}, {"id": "<child-2>", "type": "solution", "title": "<other resolution>", "description": "<...>", "resolution_steps": ["<step 1>"]}]}"""
 
 
 CORRECTIVE_PROMPT_TEMPLATE = """Your previous JSON was invalid for ResolutionFlow's tree schema.
@@ -146,7 +148,10 @@ async def scaffold_branches(
         user_message += f"Environment: {', '.join(tags)}\n"
 
     raw_text, input_tokens, output_tokens = await provider.generate_json(
-        system_prompt=SCAFFOLD_SYSTEM_PROMPT,
+        system_prompt=[
+            {"type": "text", "text": SCAFFOLD_SYSTEM_PROMPT},
+            # cacheable: stable constant across all scaffold calls
+        ],
         messages=[{"role": "user", "content": user_message}],
         max_tokens=2048,
     )
@@ -207,7 +212,13 @@ async def generate_branch_detail(
 
     for attempt in range(3):
         raw_text, input_tokens, output_tokens = await provider.generate_json(
-            system_prompt=BRANCH_DETAIL_SYSTEM_PROMPT,
+            system_prompt=[
+                {"type": "text", "text": BRANCH_DETAIL_SYSTEM_PROMPT},
+                # cacheable: stable constant. Retries in this loop re-read the
+                # cached system block rather than paying full input cost each
+                # attempt — the ~2.5k-token prompt with few-shot example is
+                # the dominant cost here.
+            ],
             messages=messages,
             max_tokens=8192,
         )

backend/app/core/audit.py

@@ -12,10 +12,19 @@ async def log_audit(
     resource_type: str,
     resource_id: Optional[UUID] = None,
     details: Optional[dict] = None,
+    account_id: Optional[UUID] = None,
 ) -> None:
     """Record an audit log entry. Does not commit — piggybacks on the caller's commit."""
+    if account_id is None:
+        # Derive from the acting user's account as a fallback (one extra query).
+        from sqlalchemy import select
+        from app.models.user import User
+        result = await db.execute(select(User.account_id).where(User.id == user_id))
+        account_id = result.scalar_one()
+
     entry = AuditLog(
         user_id=user_id,
+        account_id=account_id,
         action=action,
         resource_type=resource_type,
         resource_id=resource_id,

backend/app/core/config.py

@@ -23,10 +23,33 @@ class Settings(BaseSettings):
             return v.replace("postgresql://", "postgresql+asyncpg://", 1)
         return v
 
-    @property
-    def DATABASE_URL_SYNC(self) -> str:
-        """Get sync URL by removing asyncpg prefix from DATABASE_URL."""
-        return self.DATABASE_URL.replace("postgresql+asyncpg://", "postgresql://", 1)
+    # Sync URL for Alembic migrations. Defaults to DATABASE_URL (sync-converted).
+    # Set explicitly in .env to use a different role for migrations (e.g. superuser)
+    # when DATABASE_URL has been switched to the app role.
+    DATABASE_URL_SYNC: str = ""
+
+    @field_validator("DATABASE_URL_SYNC", mode="before")
+    @classmethod
+    def default_database_url_sync(cls, v: str, info) -> str:
+        """Fall back to sync-converted DATABASE_URL if not explicitly set."""
+        if not v:
+            base = info.data.get("DATABASE_URL", "")
+            return base.replace("postgresql+asyncpg://", "postgresql://", 1)
+        return v
+
+    # Admin database — resolutionflow_admin role, BYPASSRLS.
+    # Used by /admin/* endpoints. Defaults to DATABASE_URL for local dev.
+    ADMIN_DATABASE_URL: str = ""
+
+    @field_validator("ADMIN_DATABASE_URL", mode="before")
+    @classmethod
+    def default_admin_database_url(cls, v: str, info) -> str:
+        """Fall back to DATABASE_URL if ADMIN_DATABASE_URL is not set."""
+        if not v:
+            return info.data.get("DATABASE_URL", "")
+        if v.startswith("postgresql://"):
+            return v.replace("postgresql://", "postgresql+asyncpg://", 1)
+        return v
 
     # JWT Settings
     SECRET_KEY: str = _DEFAULT_SECRET_KEY
@@ -106,6 +129,23 @@ class Settings(BaseSettings):
         "kb_convert": "standard",
         "script_build": "standard",
         "network_diagram_generate": "standard",
+        # FlowPilot migration Phase 2 — short, latency-sensitive transformation
+        # of an engineer's answer/check output into a candidate fact.
+        # Doc Section 6.6 sets Haiku as the default; instrumentation tracks
+        # disputed_fact_rate so we can escalate to Sonnet if quality drops.
+        "fact_synthesis": "fast",
+        # FlowPilot migration Phase 3 — resolution-note preview that ships to
+        # the customer ticket. Sonnet because customer-facing artifact quality
+        # matters more than latency; the in-process state_version cache keeps
+        # cost manageable.
+        "resolution_note": "standard",
+        # FlowPilot migration Phase 4 — escalation handoff package. Parallel
+        # to resolution_note: Sonnet, same cache story, no MCP.
+        "escalation_package": "standard",
+        # FlowPilot migration Phase 5 — extract a parameter schema from a
+        # concrete rendered script so a draft_template can be proposed.
+        # Creates a persistent library artifact on accept, so Sonnet.
+        "template_extraction": "standard",
     }
 
     def get_model_for_action(self, action_type: str) -> str:

backend/app/core/database.py

@@ -1,6 +1,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
 from sqlalchemy.orm import DeclarativeBase
 from .config import settings
+from app.core.tenant_context import register_tenant_listener
 
 # Create async engine
 engine = create_async_engine(
@@ -16,6 +17,11 @@ async_session_maker = async_sessionmaker(
     expire_on_commit=False
 )
 
+# Register the RLS tenant context listener on the app engine.
+# Fires at the start of every transaction; issues set_config automatically.
+# Must NOT be called on admin_engine — admin connections bypass RLS.
+register_tenant_listener(engine)
+
 
 class Base(DeclarativeBase):
     """Base class for all database models."""

backend/app/core/filters.py

@@ -1,10 +1,12 @@
 """
 Centralized query filters for ResolutionFlow.
 
-Provides reusable SQLAlchemy filter builders for tree access control
-and step visibility, used across multiple endpoint modules.
+Provides reusable SQLAlchemy filter builders for tree access control,
+step visibility, and the canonical tenant_filter used by all queries
+on tenant-scoped tables.
 """
 from __future__ import annotations
+import uuid
 from typing import TYPE_CHECKING
 
 from sqlalchemy import or_, and_, true as sa_true
@@ -13,6 +15,18 @@ if TYPE_CHECKING:
     from app.models.user import User
 
 
+def tenant_filter(model, account_id: uuid.UUID):
+    """Primary app-layer tenant filter.
+
+    MUST be used in every SELECT/UPDATE/DELETE on tenant tables.
+    RLS (Phase 2) is the safety net — this is the primary enforcement.
+
+    Usage:
+        stmt = select(Tree).where(tenant_filter(Tree, current_user.account_id), ...)
+    """
+    return model.account_id == account_id
+
+
 def build_tree_access_filter(current_user: User):
     """Build the access filter for trees based on user permissions.
 
@@ -36,10 +50,11 @@ def build_tree_access_filter(current_user: User):
         Tree.author_id == current_user.id,
     ]
     if current_user.account_id:
+        # Team-visible trees: use tenant_filter as the account match
         conditions.append(
             and_(
                 Tree.visibility == 'team',
-                Tree.account_id == current_user.account_id
+                tenant_filter(Tree, current_user.account_id),
             )
         )
     return or_(*conditions)
@@ -58,11 +73,14 @@ def build_step_visibility_filter(current_user: User):
     if current_user.account_id:
         return or_(
             StepLibrary.visibility == 'public',
-            and_(StepLibrary.visibility == 'team', StepLibrary.account_id == current_user.account_id),
-            StepLibrary.created_by == current_user.id  # Own private steps
+            and_(
+                StepLibrary.visibility == 'team',
+                tenant_filter(StepLibrary, current_user.account_id),
+            ),
+            StepLibrary.created_by == current_user.id,
         )
     else:
         return or_(
             StepLibrary.visibility == 'public',
-            StepLibrary.created_by == current_user.id
+            StepLibrary.created_by == current_user.id,
         )

backend/app/core/kb_conversion_service.py

@@ -153,48 +153,29 @@ Identify values that would change between executions (server names, IPs, usernam
 
 ## Output Format
 
-Return a JSON object:
+Return a JSON object with this SHAPE (DO NOT copy the placeholders below
+verbatim — fill each field with content derived from the actual KB article
+the engineer attached, NOT from this schema):
 ```json
 {
-  "title": "Procedure title derived from the article",
-  "description": "Brief description of what this procedure accomplishes",
+  "title": "<procedure title derived from the article>",
+  "description": "<brief description of what this procedure accomplishes>",
   "steps": [
     {
-      "id": "unique-step-id",
-      "type": "step",
-      "content": "Open Server Manager and navigate to Add Roles on [VAR:server_name]",
-      "confidence": 0.95,
-      "source_excerpt": "Step 1: Open Server Manager on DC01..."
-    },
-    {
-      "id": "warning-dns",
-      "type": "warning",
-      "content": "WARNING: This will restart DNS and cause brief connectivity loss",
-      "confidence": 0.90,
-      "source_excerpt": "Note: Restarting DNS will cause a brief outage"
-    },
-    {
-      "id": "section-verification",
-      "type": "section_header",
-      "content": "Verification Steps",
-      "confidence": 1.0,
-      "source_excerpt": "Verification"
+      "id": "<unique-kebab-case-id>",
+      "type": "step|warning|section_header",
+      "content": "<step body — may include [VAR:<your_variable>] interpolation>",
+      "confidence": <float 0.0-1.0>,
+      "source_excerpt": "<the verbatim sentence/phrase from the article that this step came from>"
     }
   ],
   "intake_form": [
     {
-      "variable_name": "server_name",
-      "label": "Server Name",
-      "field_type": "text",
-      "required": true,
-      "display_order": 1
-    },
-    {
-      "variable_name": "ip_address",
-      "label": "IP Address",
-      "field_type": "text",
-      "required": true,
-      "display_order": 2
+      "variable_name": "<snake_case_name fitting THIS procedure>",
+      "label": "<Human Label>",
+      "field_type": "text|password|select|textarea|number|boolean",
+      "required": true|false,
+      "display_order": <integer>
     }
   ]
 }
@@ -425,7 +406,12 @@ async def convert_document(
 
     try:
         raw_text, input_tokens, output_tokens = await provider.generate_json(
-            system_prompt=system_prompt,
+            system_prompt=[
+                {"type": "text", "text": system_prompt},
+                # cacheable: one of two stable constants (TROUBLESHOOTING_SYSTEM_PROMPT
+                # or PROCEDURAL_SYSTEM_PROMPT) selected by target_type. Each
+                # variant caches independently by text content.
+            ],
             messages=[{"role": "user", "content": user_message}],
             max_tokens=16384,
         )

backend/app/core/scheduler.py

@@ -21,7 +21,7 @@ async def _fire_maintenance_schedule(schedule_id: str) -> None:
     """Create batch sessions for a scheduled maintenance run."""
     # Import all models first to ensure SQLAlchemy mapper relationships resolve
     import app.models  # noqa: F401
-    from app.core.database import async_session_maker
+    from app.core.admin_database import _admin_session_factory as async_session_maker
     from app.models.maintenance_schedule import MaintenanceSchedule
     from app.models.session import Session
     from app.models.target_list import TargetList
@@ -118,7 +118,7 @@ async def _fire_maintenance_schedule(schedule_id: str) -> None:
 async def _cleanup_expired_ai_conversations() -> None:
     """Delete expired AI wizard conversations."""
     import app.models  # noqa: F401
-    from app.core.database import async_session_maker
+    from app.core.admin_database import _admin_session_factory as async_session_maker
     from app.models.ai_conversation import AIConversation
 
     async with async_session_maker() as db:

backend/app/core/service_account.py

@@ -14,10 +14,16 @@ import logging
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.core.admin_database import _admin_session_factory
+
 logger = logging.getLogger(__name__)
 
 SERVICE_ACCOUNT_EMAIL = "noreply@resolutionflow.com"
 SERVICE_ACCOUNT_NAME = "ResolutionFlow"
+
+# Well-known UUID for the platform account — owns all default/global content.
+# Created by migration 3a40fe11b427_create_global_content_tables.
+PLATFORM_ACCOUNT_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
 SYSTEM_ACCOUNT_NAME = "ResolutionFlow System"
 SYSTEM_ACCOUNT_DISPLAY_CODE = "RF-SYS-1"
 
@@ -48,40 +54,45 @@ async def _ensure_system_account(db: AsyncSession) -> uuid.UUID:
 async def ensure_service_account(db: AsyncSession) -> uuid.UUID:
     """Ensure the ResolutionFlow service account exists and return its ID.
 
-    Idempotent — safe to call on every startup. Creates the account if it
-    does not exist. The account has no usable password and is_service_account=True
-    so it can never log in via normal auth flows.
+    Idempotent — safe to call on every startup. This lookup must bypass RLS
+    because startup runs before any request-scoped tenant context exists and
+    the users table is tenant-isolated in Phase 4. The service account is
+    normally created by Alembic migration 1490781700bc; the runtime create path
+    remains as a self-healing fallback for environments that predate that seed.
     """
+    _ = db  # Retained for call-site compatibility in app lifespan startup.
+
     from app.models.user import User
 
-    result = await db.execute(
-        select(User).where(User.email == SERVICE_ACCOUNT_EMAIL)
-    )
-    user = result.scalar_one_or_none()
+    async with _admin_session_factory() as admin_db:
+        result = await admin_db.execute(
+            select(User).where(User.email == SERVICE_ACCOUNT_EMAIL)
+        )
+        user = result.scalar_one_or_none()
 
-    if user is not None:
-        if not user.is_service_account:
-            user.is_service_account = True
-            await db.commit()
-        return user.id
+        if user is not None:
+            if not user.is_service_account:
+                user.is_service_account = True
+                await admin_db.commit()
+            return user.id
 
-    account_id = await _ensure_system_account(db)
+        account_id = await _ensure_system_account(admin_db)
 
-    new_user = User(
-        id=uuid.uuid4(),
-        email=SERVICE_ACCOUNT_EMAIL,
-        name=SERVICE_ACCOUNT_NAME,
-        password_hash="!service-account-no-login",  # bcrypt can't produce this prefix
-        role="engineer",
-        is_super_admin=False,
-        is_team_admin=False,
-        is_active=True,
-        is_service_account=True,
-        must_change_password=False,
-        account_id=account_id,
-        account_role="engineer",
-    )
-    db.add(new_user)
-    await db.commit()
-    logger.info(f"[service_account] Created service account (id={new_user.id})")
-    return new_user.id
+        new_user = User(
+            id=uuid.uuid4(),
+            email=SERVICE_ACCOUNT_EMAIL,
+            name=SERVICE_ACCOUNT_NAME,
+            password_hash="!service-account-no-login",  # bcrypt can't produce this prefix
+            role="engineer",
+            is_super_admin=False,
+            is_team_admin=False,
+            is_active=True,
+            is_service_account=True,
+            must_change_password=False,
+            account_id=account_id,
+            account_role="engineer",
+        )
+        admin_db.add(new_user)
+        await admin_db.commit()
+        logger.info(f"[service_account] Created service account (id={new_user.id})")
+        return new_user.id

backend/app/core/tenant_context.py

@@ -0,0 +1,92 @@
+# backend/app/core/tenant_context.py
+"""
+Per-request tenant context for row-level security.
+
+Flow:
+  1. require_tenant_context (FastAPI dep) calls set_current_account_id().
+  2. The SQLAlchemy transaction-begin listener fires on every new transaction
+     and calls set_config('app.current_account_id', <id>, true) automatically.
+  3. PostgreSQL RLS policies read current_setting('app.current_account_id', TRUE)
+     to filter rows.
+
+The ContextVar is asyncio-task-scoped: each concurrent request has its own value.
+set_config with is_local=true is transaction-scoped: it resets on COMMIT or
+ROLLBACK, so the listener re-applies it at the start of every transaction.
+"""
+import contextvars
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import event, or_, text
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+if TYPE_CHECKING:
+    from app.models.user import User
+
+# One slot per async task — each concurrent request gets its own value.
+_current_account_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "current_account_id", default=None
+)
+
+# Platform account — global content visible to all tenants.
+PLATFORM_ACCOUNT_ID = UUID("00000000-0000-0000-0000-000000000001")
+
+
+def set_current_account_id(account_id: UUID) -> contextvars.Token:
+    """Set tenant context for the current request coroutine.
+
+    Returns a token so the caller can reset it after the request.
+    """
+    return _current_account_id.set(str(account_id))
+
+
+def clear_current_account_id(token: contextvars.Token) -> None:
+    """Reset the ContextVar to its previous value (call in finally block)."""
+    _current_account_id.reset(token)
+
+
+def get_current_account_id() -> str | None:
+    """Return the account_id string for the current request, or None."""
+    return _current_account_id.get()
+
+
+def register_tenant_listener(engine: AsyncEngine) -> None:
+    """Register the transaction-begin listener on the given engine.
+
+    Must be called once at application startup, AFTER the engine is created.
+    The listener issues set_config() at the start of every transaction so that
+    the setting is re-applied automatically even when a request commits
+    mid-flight and starts a new transaction.
+
+    Do NOT call this on admin_engine — admin connections must never set tenant
+    context automatically.
+    """
+
+    @event.listens_for(engine.sync_engine, "begin")
+    def _on_transaction_begin(conn) -> None:  # noqa: ANN001
+        account_id = _current_account_id.get()
+        if account_id:
+            # set_config(name, value, is_local=true) ≡ SET LOCAL.
+            # Unlike SET LOCAL, set_config IS parameterisable.
+            conn.execute(
+                text("SELECT set_config('app.current_account_id', :id, true)"),
+                {"id": account_id},
+            )
+        # If no account_id is set, do nothing. The RLS policy falls back to a
+        # null-matching UUID and returns zero rows — fail-closed behaviour.
+
+
+def tenant_filter(Model, current_user: "User"):  # noqa: ANN001
+    """SQLAlchemy filter clause for tables that contain platform-owned rows.
+
+    Use for: tree_tags, tree_categories, step_categories, step_library,
+             template_trees, platform_steps.
+
+    For tenant-only tables (trees, sessions, psa_connections, etc.) use:
+        Model.account_id == current_user.account_id
+    directly.
+    """
+    return or_(
+        Model.account_id == current_user.account_id,
+        Model.account_id == PLATFORM_ACCOUNT_ID,
+    )

backend/app/main.py

@@ -25,7 +25,8 @@ if settings.SENTRY_DSN:
         ),
     )
 
-from app.core.database import init_db, async_session_maker
+from app.core.database import init_db
+from app.core.admin_database import _admin_session_factory as async_session_maker
 from app.core.logging_config import setup_logging
 from app.core.middleware import RequestLoggingMiddleware, ErrorLoggingMiddleware
 from app.core.security_headers import SecurityHeadersMiddleware

backend/app/models/__init__.py

@@ -54,8 +54,14 @@ from .session_branch import SessionBranch
 from .fork_point import ForkPoint
 from .session_handoff import SessionHandoff
 from .session_resolution_output import SessionResolutionOutput
+from .template_tree import TemplateTree
+from .platform_step import PlatformStep
 from .device_type import DeviceType
 from .network_diagram import NetworkDiagram
+from .session_fact import SessionFact
+from .session_suggested_fix import SessionSuggestedFix
+from .draft_template import DraftTemplate
+from .account_settings import AccountSettings
 
 __all__ = [
     "User",
@@ -124,6 +130,12 @@ __all__ = [
     "ForkPoint",
     "SessionHandoff",
     "SessionResolutionOutput",
+    "TemplateTree",
+    "PlatformStep",
     "DeviceType",
     "NetworkDiagram",
+    "SessionFact",
+    "SessionSuggestedFix",
+    "DraftTemplate",
+    "AccountSettings",
 ]

backend/app/models/account_settings.py

@@ -0,0 +1,99 @@
+"""Per-account settings with a JSONB preferences grab-bag.
+
+Rows are created lazily on first write. Reads of a missing row return the
+caller-supplied default — no upfront row creation per account.
+
+Settings live in `preferences` until they meet the promotion criteria in
+Section 4.6 of FLOWPILOT-MIGRATION.md (hot path / validation / joins), at
+which point a future migration adds a typed column and the helpers prefer it.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, TYPE_CHECKING
+
+from sqlalchemy import DateTime, ForeignKey, text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID, JSONB, insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql import select
+
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.account import Account
+
+
+class AccountSettings(Base):
+    """One row per account. Created lazily on first `set_setting` call."""
+    __tablename__ = "account_settings"
+
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    preferences: Mapped[dict[str, Any]] = mapped_column(
+        JSONB, nullable=False, default=dict, server_default=text("'{}'::jsonb")
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+    account: Mapped["Account"] = relationship("Account", foreign_keys=[account_id])
+
+    @classmethod
+    async def get_setting(
+        cls,
+        db: AsyncSession,
+        account_id: uuid.UUID,
+        key: str,
+        default: Any = None,
+    ) -> Any:
+        """Return preferences[key] for the account, or `default` if no row/no key.
+
+        Never creates a row — this is the pure-read path.
+        """
+        result = await db.execute(
+            select(cls.preferences).where(cls.account_id == account_id)
+        )
+        prefs = result.scalar_one_or_none()
+        if prefs is None:
+            return default
+        return prefs.get(key, default)
+
+    @classmethod
+    async def set_setting(
+        cls,
+        db: AsyncSession,
+        account_id: uuid.UUID,
+        key: str,
+        value: Any,
+    ) -> None:
+        """Upsert preferences[key] = value for the account.
+
+        Creates the row on first write; on subsequent writes, merges the key
+        into the existing preferences JSON without clobbering other keys.
+        Uses PostgreSQL's `||` jsonb merge operator via ON CONFLICT DO UPDATE.
+        """
+        stmt = pg_insert(cls).values(
+            account_id=account_id,
+            preferences={key: value},
+        )
+        stmt = stmt.on_conflict_do_update(
+            index_elements=[cls.account_id],
+            set_={
+                # Merge the new {key: value} into the existing preferences.
+                # The `||` operator on jsonb overwrites matching keys and keeps
+                # all other keys intact.
+                "preferences": cls.preferences.op("||")(stmt.excluded.preferences),
+                "updated_at": text("now()"),
+            },
+        )
+        await db.execute(stmt)

backend/app/models/ai_session.py

@@ -137,28 +137,6 @@ class AISession(Base):
         comment="Snapshot of PSA ticket data at session start",
     )
 
-    # ── Triage / Cockpit Header ──
-    client_name: Mapped[Optional[str]] = mapped_column(
-        String(255), nullable=True,
-        comment="MSP client name for incident header (AI-inferred or manual)",
-    )
-    asset_name: Mapped[Optional[str]] = mapped_column(
-        String(255), nullable=True,
-        comment="Device, asset, or user being worked on",
-    )
-    issue_category: Mapped[Optional[str]] = mapped_column(
-        String(100), nullable=True,
-        comment="Human-readable category (e.g. DNS / Networking)",
-    )
-    triage_hypothesis: Mapped[Optional[str]] = mapped_column(
-        Text, nullable=True,
-        comment="Current working hypothesis — AI-updated + engineer-editable",
-    )
-    evidence_items: Mapped[Optional[list[dict[str, Any]]]] = mapped_column(
-        JSONB, nullable=True,
-        comment='What We Know list: [{"text": str, "status": "confirmed"|"ruled_out"|"pending"}]',
-    )
-
     # ── Resolution / Escalation ──
     resolution_summary: Mapped[Optional[str]] = mapped_column(
         Text, nullable=True,
@@ -236,6 +214,38 @@ class AISession(Base):
         comment="Current task lane state: {questions: [...], actions: [...]}",
     )
 
+    # ── Resolution / Escalation artifacts (Phase 1 — FlowPilot migration) ──
+    # Markdown of the posted note + PSA external ID for round-trip traceability.
+    resolution_note_markdown: Mapped[Optional[str]] = mapped_column(
+        Text, nullable=True,
+        comment="Final Resolve note markdown, as posted to the PSA",
+    )
+    resolution_note_posted_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True), nullable=True,
+    )
+    resolution_note_external_id: Mapped[Optional[str]] = mapped_column(
+        String(128), nullable=True,
+        comment="PSA (e.g. CW) ticket-note ID returned at post time",
+    )
+    escalation_package_markdown: Mapped[Optional[str]] = mapped_column(
+        Text, nullable=True,
+        comment="Final Escalate handoff package markdown, as posted to the PSA",
+    )
+    escalation_package_posted_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True), nullable=True,
+    )
+    escalation_package_external_id: Mapped[Optional[str]] = mapped_column(
+        String(128), nullable=True,
+        comment="PSA ticket-note ID for the escalation package",
+    )
+    # Incremented atomically by any write that invalidates the resolution
+    # note preview cache (facts, suggested fixes, script generations).
+    # See FLOWPILOT-MIGRATION.md Section 5.5.
+    state_version: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default=sa.text("0"),
+        comment="Monotonic preview-cache version; bumped on state-changing writes",
+    )
+
     # ── Branching ──
     is_branching: Mapped[bool] = mapped_column(
         default=False,

backend/app/models/ai_session_step.py

@@ -50,6 +50,13 @@ class AISessionStep(Base):
         nullable=False,
         index=True,
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+        comment="Denormalized from ai_sessions.account_id for direct tenant filtering.",
+    )
     step_order: Mapped[int] = mapped_column(
         Integer, nullable=False,
         comment="Sequential position in the session (0-indexed)",

backend/app/models/ai_suggestion.py

@@ -28,6 +28,12 @@ class AISuggestion(Base):
         nullable=False,
         index=True,
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     session_id: Mapped[Optional[uuid.UUID]] = mapped_column(
         UUID(as_uuid=True),
         ForeignKey("ai_chat_sessions.id", ondelete="SET NULL"),

backend/app/models/attachment.py

@@ -20,6 +20,12 @@ class Attachment(Base):
         ForeignKey("sessions.id"),
         nullable=False
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     node_id: Mapped[Optional[str]] = mapped_column(String(100), nullable=True)
     file_name: Mapped[str] = mapped_column(String(255), nullable=False)
     file_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)

backend/app/models/audit_log.py

@@ -21,6 +21,12 @@ class AuditLog(Base):
         nullable=False,
         index=True
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
     action: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
     resource_type: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
     resource_id: Mapped[Optional[uuid.UUID]] = mapped_column(

backend/app/models/category.py

@@ -39,10 +39,10 @@ class TreeCategory(Base):
         nullable=True,
         index=True
     )
-    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+    account_id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True),
         ForeignKey("accounts.id", ondelete="CASCADE"),
-        nullable=True,
+        nullable=False,
         index=True
     )
     display_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0, index=True)

backend/app/models/device_type.py

@@ -10,7 +10,7 @@ from app.core.database import Base
 
 
 class DeviceType(Base):
-    """A device type for network diagram nodes (system or team-custom)."""
+    """A device type for network diagram nodes (platform or account-custom)."""
     __tablename__ = "device_types"
 
     id: Mapped[uuid.UUID] = mapped_column(
@@ -32,11 +32,11 @@ class DeviceType(Base):
         Boolean, nullable=False, default=False,
         comment="True for built-in types that cannot be deleted",
     )
-    team_id: Mapped[uuid.UUID | None] = mapped_column(
+    account_id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True),
-        ForeignKey("teams.id", ondelete="CASCADE"),
-        nullable=True,
-        comment="NULL for system types, set for team-custom types",
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        comment="Platform account for system types, tenant account for custom types",
     )
     sort_order: Mapped[int] = mapped_column(
         Integer, nullable=False, default=0,

backend/app/models/draft_template.py

@@ -0,0 +1,91 @@
+"""Draft template model — scripts generated during a session, pending templatization.
+
+Created when an engineer picks "Run now, templatize after resolve" in the
+three-option dialog. Post-resolve, the TemplatizePrompt component reads pending
+drafts and lets the engineer accept (promotes to `script_templates`) or reject.
+"""
+import uuid
+from datetime import datetime, timezone
+from typing import Any, TYPE_CHECKING
+
+from sqlalchemy import (
+    Text, DateTime, ForeignKey, String, CheckConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.account import Account
+    from app.models.ai_session import AISession
+    from app.models.user import User
+    from app.models.script_template import ScriptCategory, ScriptTemplate
+
+
+class DraftTemplate(Base):
+    """A session-generated script pending conversion to a reusable template."""
+    __tablename__ = "draft_templates"
+    __table_args__ = (
+        CheckConstraint(
+            "status IN ('pending', 'accepted', 'rejected')",
+            name="ck_draft_templates_status",
+        ),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id"),
+        nullable=False,
+    )
+    source_session_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ai_sessions.id"),
+        nullable=False,
+    )
+    source_user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id"),
+        nullable=False,
+    )
+    script_body: Mapped[str] = mapped_column(Text, nullable=False)
+    proposed_parameters: Mapped[dict[str, Any]] = mapped_column(
+        JSONB, nullable=False
+    )
+    proposed_name: Mapped[str | None] = mapped_column(String(200), nullable=True)
+    proposed_category_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("script_categories.id"),
+        nullable=True,
+    )
+    status: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="pending"
+    )
+    resolved_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # Set when status transitions to 'accepted' and the draft is promoted
+    # to a real script_templates row.
+    promoted_template_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("script_templates.id"),
+        nullable=True,
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    account: Mapped["Account"] = relationship("Account", foreign_keys=[account_id])
+    source_session: Mapped["AISession"] = relationship(
+        "AISession", foreign_keys=[source_session_id]
+    )
+    source_user: Mapped["User"] = relationship("User", foreign_keys=[source_user_id])
+    proposed_category: Mapped["ScriptCategory | None"] = relationship(
+        "ScriptCategory", foreign_keys=[proposed_category_id]
+    )
+    promoted_template: Mapped["ScriptTemplate | None"] = relationship(
+        "ScriptTemplate", foreign_keys=[promoted_template_id]
+    )

backend/app/models/feedback.py

@@ -1,6 +1,5 @@
 import uuid
 from datetime import datetime, timezone
-from typing import Optional
 from sqlalchemy import String, Text, DateTime, ForeignKey
 from sqlalchemy.orm import Mapped, mapped_column
 from sqlalchemy.dialects.postgresql import UUID
@@ -11,7 +10,7 @@ class Feedback(Base):
     __tablename__ = "feedback"
 
     id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("accounts.id", ondelete="SET NULL"), nullable=True)
+    account_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False, index=True)
     user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=False)
     email: Mapped[str] = mapped_column(String(255), nullable=False)
     feedback_type: Mapped[str] = mapped_column(String(50), nullable=False)

backend/app/models/folder.py

@@ -46,6 +46,12 @@ class UserFolder(Base):
         nullable=False,
         index=True
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     name: Mapped[str] = mapped_column(String(100), nullable=False)
     color: Mapped[str] = mapped_column(String(7), nullable=False, default="#6366f1")
     icon: Mapped[str] = mapped_column(String(50), nullable=False, default="folder")

backend/app/models/fork_point.py

@@ -23,6 +23,12 @@ class ForkPoint(Base):
 
     id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     session_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("ai_sessions.id", ondelete="CASCADE"), nullable=False, index=True)
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     parent_branch_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("session_branches.id", ondelete="CASCADE"), nullable=False)
     trigger_step_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("ai_session_steps.id", ondelete="SET NULL"), nullable=True)
     fork_reason: Mapped[str] = mapped_column(Text, nullable=False)

backend/app/models/maintenance_schedule.py

@@ -23,6 +23,12 @@ class MaintenanceSchedule(Base):
     created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
         UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     cron_expression: Mapped[str] = mapped_column(String(100), nullable=False)
     timezone: Mapped[str] = mapped_column(String(100), nullable=False, default="UTC")
     target_list_id: Mapped[Optional[uuid.UUID]] = mapped_column(

backend/app/models/network_diagram.py

@@ -3,7 +3,7 @@ import uuid
 from datetime import datetime, timezone
 from typing import Any, TYPE_CHECKING
 
-from sqlalchemy import String, Text, Boolean, DateTime, ForeignKey
+from sqlalchemy import String, Text, Boolean, DateTime, ForeignKey, text
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID, JSONB
 
@@ -14,15 +14,15 @@ if TYPE_CHECKING:
 
 
 class NetworkDiagram(Base):
-    """A network topology diagram, team-scoped."""
+    """A network topology diagram scoped to one account."""
     __tablename__ = "network_diagrams"
 
     id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
     )
-    team_id: Mapped[uuid.UUID] = mapped_column(
+    account_id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True),
-        ForeignKey("teams.id", ondelete="CASCADE"),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
         nullable=False,
         index=True,
     )
@@ -30,8 +30,8 @@ class NetworkDiagram(Base):
     client_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
     asset_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    nodes: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, server_default="'[]'")
-    edges: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, server_default="'[]'")
+    nodes: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, server_default=text("'[]'::jsonb"))
+    edges: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, server_default=text("'[]'::jsonb"))
     thumbnail_url: Mapped[str | None] = mapped_column(Text, nullable=True)
     is_archived: Mapped[bool] = mapped_column(
         Boolean, nullable=False, default=False,

backend/app/models/notification_log.py

@@ -31,6 +31,12 @@ class NotificationLog(Base):
         nullable=False,
         index=True,
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     event: Mapped[str] = mapped_column(String(50), nullable=False)
     payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
     status: Mapped[str] = mapped_column(String(20), default="sent")

backend/app/models/platform_step.py

@@ -0,0 +1,37 @@
+"""Platform step model — platform-owned steps, readable by all users.
+
+No account_id. No RLS. Readable by any authenticated user.
+Populated by promoting visibility='public' steps from step_library.
+"""
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, Any
+
+from sqlalchemy import String, Boolean, DateTime, ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+from app.core.database import Base
+
+
+class PlatformStep(Base):
+    __tablename__ = "platform_steps"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    step_type: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    content: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    source_step_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("step_library.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )

backend/app/models/psa_member_mapping.py

@@ -25,6 +25,12 @@ class PsaMemberMapping(Base):
         nullable=False,
         index=True,
     )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     user_id: Mapped[uuid.UUID] = mapped_column(
         UUID(as_uuid=True),
         ForeignKey("users.id", ondelete="CASCADE"),