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"

CHANGELOG.md

@@ -11,6 +11,7 @@ All notable changes to ResolutionFlow are documented here.
 - **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
@@ -33,6 +34,7 @@ All notable changes to ResolutionFlow are documented here.
 - **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

CLAUDE.md

@@ -1,628 +1,265 @@
-# CLAUDE.md - Patherly / ResolutionFlow Project Context
+# CLAUDE.md — ResolutionFlow
 
-> **Last Updated:** April 6, 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 | `patherly` (internal name) |
-| Docker containers | `resolutionflow_postgres`, `resolutionflow_frontend`, `resolutionflow_backend` |
-| Backend, frontend UI, production URLs | **ResolutionFlow** |
-
-- **Design system:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — THE source of truth for all design decisions
-- **Design aesthetic:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no gradients on surfaces, no ambient effects. Light mode planned.
-- **Accent color:** Electric blue (#60a5fa dark / #2563eb light). Used sparingly — ≤5% of the UI. Warning is amber (#fbbf24), info is cyan (#67e8f9).
-- **Fonts:** IBM Plex Sans (`font-sans`, body), Bricolage Grotesque (`font-heading`, headings), JetBrains Mono (`font-mono`, code) — loaded via Google Fonts
-- **Logo:** 30px gradient square (ember orange) + "ResolutionFlow" in Bricolage Grotesque 700
-- **Layout:** Icon rail sidebar (72px default) with hover flyout panels. Pinnable to full 260px sidebar. See [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md)
-- **Brand assets:** `brand-assets/` (source SVGs), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon)
-- **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. Step Library is called "Solutions Library" in the UI. Maintenance flows are hidden from UI for pilot (backend still supports them). `tree_type` column values unchanged in DB.
-- **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, 101 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-070 sequential, then hash IDs)
-│   ├── 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
-```
-
-### Frontend (`frontend/.env.local` - optional)
-
-```bash
-VITE_API_URL=http://localhost:8000
-```
-
----
-
-## ConnectWise PSA Integration
-
-ResolutionFlow integrates with ConnectWise PSA (formerly Manage) as the primary PSA integration. All ConnectWise API reference materials live in `docs/connectwise/`.
-
-### 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
-
----
-
-## Development Commands
-
-```powershell
-# Start PostgreSQL (run from VPS SSH — docker not available inside code-server, see Lesson 103)
-docker start resolutionflow_postgres
-
-# 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 resolutionflow_postgres psql -U postgres -c "CREATE DATABASE resolutionflow_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"
-# Sequential 3-digit IDs (001–070) were used historically. New migrations use Alembic's default hex hash IDs.
-# Do NOT pass --rev-id — let Alembic generate the hash automatically.
-
-# Access PostgreSQL (run from VPS SSH — docker not available inside code-server, see Lesson 103)
+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
-
-# 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
+python -m scripts.seed_trees                                        # seed (from backend/)
 ```
 
-### URLs
+**URLs:** Frontend <http://localhost:5173>, backend <http://localhost:8000>, API docs <http://localhost:8000/api/docs>.
 
-- Frontend: <http://localhost:5173>
-- Backend API: <http://localhost:8000>
-- API Docs: <http://localhost:8000/api/docs>
+**Test users** (all password `TestPass123!`): `admin@resolutionflow.example.com` (super_admin), `teamadmin@resolutionflow.example.com`, `engineer@resolutionflow.example.com`, `pro@resolutionflow.example.com`.
 
-### Test Users (seeded via `scripts/seed_test_users.py`)
+**CI:** Gitea (`gitea.resolutionflow.com/chihlasm/resolutionflow/actions`). `gh` CLI works for issues/PRs on the GitHub mirror, but not CI runs.
 
-- 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)
+**Never pass `--rev-id`** to alembic — let it generate the hex hash.
 
 ---
 
-## 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/.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 fixed bottom~~ (Superseded by Lesson 93):** Actions moved to the page header. `FlowPilotActionBar` component exists but is no longer used in the main session flow. The only fixed-bottom element is the message input.
-
-**84. AI session `abandoned` status is fully wired:** `POST /ai-sessions/{id}/abandon` sets status to `abandoned` with optional `reason` param. Frontend: `aiSessionsApi.abandonSession()`, `useFlowPilotSession().abandonSession()`, "Close" button in `FlowPilotActionBar`. Redirects to `/sessions` after closing.
-
-**85. Date range filter end dates must use end-of-day:** `toDate.toISOString()` sends midnight (start of day), excluding items created later that day. Always set `toDate.setHours(23, 59, 59, 999)` before sending. For string-based date inputs (AI sessions), append `T23:59:59.999Z`. See `SessionHistoryPage.tsx`.
-
-**86. Script Builder system:** AI-powered script generation at `/script-builder`. Chat-style interface generates PowerShell/Bash/Python scripts from natural language. Backend: `ScriptBuilderSession` model, `script_builder_service.py`, endpoints at `/scripts/builder/`. Frontend: `ScriptBuilderPage`, `ScriptCodeBlock`, `ScriptPreviewModal`, `SaveToLibraryDialog`. FlowPilot can hand off to Script Builder via `action_type: "open_script_builder"` with `sessionStorage` context passing.
-
-**87. FlowPilot must ask GUI vs script preference:** When a task can be done via GUI or script (e.g., creating AD users), FlowPilot must ask the engineer which approach they prefer BEFORE suggesting either. Never assume the user wants a script. See `FLOWPILOT_SYSTEM_PROMPT` rules in `flowpilot_engine.py`.
-
-**88. Charcoal palette — sidebar-darkest approach:** Sidebar `#0e1016`, page `#16181f`, cards `#1e2028`, borders `#2a2e3a`. This gives more contrast range than true-dark. All colors via CSS variables in `index.css` `@theme` block. Accent is electric blue (#60a5fa), not orange or cyan.
-
-*(Lessons 89–91 were retracted.)*
-
-**92. `tsc -b` in Dockerfile is stricter than `npx tsc --noEmit`:** The production build (`tsc -b && vite build`) enforces `noUnusedLocals` and `noUnusedParameters` as hard errors. After any refactor that moves logic between components or removes features, trace every import and destructured prop to remove orphans. IDE warnings (yellow squiggles) flag these — check them before pushing.
-
-**93. FlowPilot actions live in the page header, not a bottom bar:** `FlowPilotSessionPage` renders Resolve/Escalate/Share Update in the header bar. Desktop: inline buttons + `⋯` overflow (Pause/Close). Mobile: single `⋯` menu. The bottom only has the message input. `FlowPilotActionBar` component still exists but is no longer used in the main session flow.
-
-**94. Frontend chat uses unified_chat_service, not assistant_chat_service:** `AssistantChatPage` calls `/ai-sessions/{id}/chat` → `unified_chat_service.py`. The old `assistant_chat_service` endpoints were removed (only retention settings remain at `/assistant/retention`). When tracing chat features, start from `aiSessionsApi.sendChatMessage` → `ai_sessions.py` → `unified_chat_service.py`. Never wire chat features into `assistant_chat.py`.
-
-**95. Image upload → AI vision pipeline:** Paste/attach images → upload to Railway S3 bucket via `uploadsApi.upload()` → send `upload_ids` with chat message → backend fetches from S3 via `storage_service.download_file()` → resized via `storage_service.resize_image_for_vision()` (Pillow, 1568px max, PNG→JPEG) → base64-encoded → sent as Claude multimodal content blocks. Max 3 images/message. Images are NOT stored in conversation history (text-only). Vision helpers live in `storage_service.py`.
-
-**96. `bg-accent` is electric blue — never use for code/kbd elements:** In Tailwind v4, `bg-accent` maps to `--color-accent: #60a5fa` (dark) / `#2563eb` (light). Use `bg-code` for code blocks, `bg-white/[0.12] border border-white/[0.06]` for inline code/badges, `bg-white/[0.08]` for kbd shortcuts. Blue accent is reserved for interactive elements only (buttons, active nav, links). Ember orange (#f97316) is deprecated — do not use.
-
-**97. Railway Object Storage (S3 bucket) is provisioned:** Bucket `resolutionflow-uploads` on Railway canvas. Variables: `STORAGE_ENDPOINT`, `STORAGE_ACCESS_KEY`, `STORAGE_SECRET_KEY`, `STORAGE_BUCKET_NAME`, `STORAGE_REGION` — mapped via variable references on the `patherly` backend service. Accessed via boto3 in `storage_service.py`. Pillow (`Pillow>=10.0.0`) + `libjpeg-dev`/`zlib1g-dev` in Dockerfile for image resize.
-
-**98. `lazyWithRetry` for stale chunk errors:** All lazy-loaded routes use `lazyWithRetry` from `@/lib/lazyWithRetry.ts` instead of `React.lazy`. Auto-reloads the page on chunk load failures (stale deploys). Uses sessionStorage debounce (10s) to prevent loops. When adding new lazy routes, use `lazyWithRetry`, not `lazy`.
-
-**99. Tailwind v4 `text-secondary` renders invisible on dark backgrounds:** `text-secondary` maps to `--color-secondary: #2e3140` (a dark surface color), NOT `--color-text-secondary`. For readable secondary text, use `text-muted-foreground` (`#848b9b`). Also avoid `text-muted` (`#4f5666`) for body text — it's for labels only. This applies to ALL new components.
-
-**100. Hover pop-out card pattern:** For cards that expand on hover "in front of everything": use `pointer-events-none` on the scrim (`fixed inset-0 z-40 bg-black/30`), absolute-position the expanded card at `z-50` with its own `onClick` handler, and dismiss via `onMouseLeave` on the wrapper div. Never put interactive event handlers on the scrim — it blocks clicks on sibling elements.
-
-**101. AI marker format compliance:** The AI assistant uses `[QUESTIONS]`, `[ACTIONS]`, and `[FORK]` markers in responses. Parsed by `unified_chat_service.py` (`_parse_*_marker` functions), returned as structured data in the API response. System prompt in `assistant_chat_service.py` has a final reminder section, and each user message gets an invisible `[SYSTEM: ...]` reminder appended in `_call_anthropic_cached()`. If markers stop appearing: check conversation history stores `display_content` (stripped), verify system prompt final reminder exists, check user message reminder injection is active.
-
-**102. TaskLane activation must happen in ALL chat response paths:** `AssistantChatPage.tsx` has three code paths calling `sendChatMessage`: `handleSend` (regular messages), `sendPrefill` (dashboard handoff), `handleResumeNew` (resume from concluded session). ALL three must check `response.actions`/`response.questions` and call `setShowTaskLane(true)`. Missing this in any path causes TaskLane to not appear on first message.
-
-**103. Docker not available in code-server container:** The dev environment runs code-server inside Docker on the VPS. The `docker` CLI is not available inside the code-server container. To query the database, use the VPS SSH session: `docker exec resolutionflow_postgres psql -U postgres -d resolutionflow -t -c "SQL"`. Python is also not available in the container.
-
-**104. `landing.css` uses self-contained `--lp-*` color variables:** The landing page defines its own color palette at the top of `landing.css` (`--lp-bg`, `--lp-accent`, `--lp-text-*`, etc.). Never use `var(--color-*)` theme tokens in `landing.css` — they may resolve incorrectly outside the app shell context. Extend the `--lp-*` palette for any new landing page colors.
-
-**105. `npm run build` fails with `EACCES: permission denied` on `dist/` in code-server:** This is a filesystem permission issue in the Docker environment, not a TypeScript error — the TS compilation completes successfully. Use `npx tsc -b` to verify TypeScript cleanly without needing to write to `dist/`.
-
-**106. Guard async "select item → load data → apply state" flows with a ref:** When a component lets the user switch between items (chat sessions, flows, scripts) and loads data asynchronously on each switch, the load for item A can complete *after* the user has already switched to item B — overwriting B's state with A's stale data. Fix pattern: keep a `currentSelectionRef = useRef(initialId)` and update it synchronously whenever the selection changes (in every creation/switch path). After every `await`, bail out if `currentSelectionRef.current !== thisItemId`. See `AssistantChatPage.tsx` `selectChat` for the reference implementation (`currentChatRef`).
-
-**107. Startup routines must use `_admin_session_factory()` after Phase 4 RLS:** Any code that runs at startup (lifespan, `ensure_service_account`, seed scripts) and touches tenant-isolated tables (`users`, etc.) must use `_admin_session_factory()` — not `get_db()`. Phase 4 enabled RLS on `users`; a tenant-scoped session has no `app.current_account_id` set at startup, so all queries return 0 rows or fail. `get_service_account_id` in `deps.py` is safe — it reads from `app.state` cached at startup, never hits the DB per-request.
-
-**108. Tables with no `account_id` column (never add to RLS migrations):** `script_categories`, `platform_steps`, `template_trees`, `plan_feature_defaults`, `accounts` — global/platform tables documented with "No account_id. No RLS." in their model files. When writing RLS migrations, scan at the class level (check for `account_id: Mapped` within the class block), not the file level — multiple classes in one `.py` file can have different columns (e.g. `ScriptCategory` vs `ScriptTemplate` in `script_template.py`).
-
-**109. `tree_shares.account_id` must equal `tree.account_id`, not the actor's account:** When creating a `TreeShare`, always use `account_id=tree.account_id` (tree owner's tenant). A super admin in tenant A sharing tenant B's tree must produce a share row in tenant B's RLS context — using `current_user.account_id` instead makes the share invisible to the tree owner after RLS is enforced.
-
-## 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`
+## Common tasks
+
+- **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.
 
 ---
 
-## Design System
+## Coding standards
 
-**Source of truth:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — always read this before making visual or UI decisions.
+- **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.
 
-- **Theme:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no backdrop blur, no ambient orbs, no gradient backgrounds on surfaces. Light mode fully specified (v6).
-- **Backgrounds:** `bg-page` (`#16181f`), `bg-sidebar` (`#0e1016`), `bg-card` (`#1e2028`), `bg-elevated` (`#2a2d38`)
-- **Cards:** `bg-card` with 1px `border-default` (`#2a2e3a`), 8px radius. No shadows, no blur, no gradients. Hover: `border-hover` (`#3d4252`)
-- **Buttons:** Primary: solid `accent` (#60a5fa dark / #2563eb light), white text, 5px radius. Ghost: transparent + 1px border, hover `bg-elevated`
-- **Inputs:** `bg-input` (`#252830`) 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, not a text color.
-- **Borders:** `border-default` (`#2a2e3a`), `border-hover` (`#3d4252`)
-- **Functional colors:** `#34d399` (success), `#fbbf24` (warning/amber), `#f87171` (danger), `#67e8f9` (info/cyan) — each with `-dim` variant at 10% opacity
-- **Accent:** Electric blue `#60a5fa` (dark) / `#2563eb` (light) — used sparingly (≤5% of UI). `accent-dim` = `rgba(96,165,250,0.10)`, `accent-text` = `#93c5fd`
-- **Deprecated:** Do NOT use `glass-card`, `glass-stat`, `bg-gradient-brand`, `text-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, purple gradients, ember orange (`#f97316`), or cyan (`#22d3ee`) as accent — cyan is now the info color only
+**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).
 
 ---
 
-## Frontend Patterns
+## Frontend patterns
 
-- **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.
+- **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.
 
 ---
 
-## Common Tasks
+## Critical lessons
 
-- **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`
+> 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.
+
+### 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.
 
 ---
 
-## Coding Standards
+## GitNexus code intelligence
 
-### Python
+Indexed as `resolutionflow`. Earns its cost on cross-cutting work only.
 
-- Type hints everywhere, async/await for DB, Pydantic for validation, `DateTime(timezone=True)` always
+| 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 |
 
-### TypeScript
+**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.
 
-- 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
+Re-indexes automatically on commit (PostToolUse hook). Manual refresh if stale: `npx gitnexus analyze`.
 
 ---
 
-## gstack (Browser & Workflow Skills)
+## gstack skills
 
-**Web browsing:** Always use the `/browse` skill from gstack for all web browsing needs. Never use `mcp__claude-in-chrome__*` tools.
+Always use `/browse` for web, never `mcp__claude-in-chrome__*`. Most-used:
 
-**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 |
-
-<!-- gitnexus:start -->
-# GitNexus — Code Intelligence
-
-This project is indexed by GitNexus as **resolutionflow** (16703 symbols, 35922 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
-
-> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
-
-## Always Do
-
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
-
-## When Debugging
-
-1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
-2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
-3. `READ gitnexus://repo/resolutionflow/process/{processName}` — trace the full execution flow step by step
-4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
-
-## When Refactoring
-
-- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
-- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
-- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
-
-## Never Do
-
-- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
-- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
-
-## Tools Quick Reference
-
-| Tool | When to use | Command |
-|------|-------------|---------|
-| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
-| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
-| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
-| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
-| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
-| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
-| d=2 | LIKELY AFFECTED — indirect deps | Should test |
-| d=3 | MAY NEED TESTING — transitive | Test if critical path |
-
-## Resources
-
-| Resource | Use for |
-|----------|---------|
-| `gitnexus://repo/resolutionflow/context` | Codebase overview, check index freshness |
-| `gitnexus://repo/resolutionflow/clusters` | All functional areas |
-| `gitnexus://repo/resolutionflow/processes` | All execution flows |
-| `gitnexus://repo/resolutionflow/process/{name}` | Step-by-step execution trace |
-
-## Self-Check Before Finishing
-
-Before completing any code modification task, verify:
-1. `gitnexus_impact` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. `gitnexus_detect_changes()` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
-
-## Keeping the Index Fresh
-
-After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
-
-```bash
-npx gitnexus analyze
-```
-
-If the index previously included embeddings, preserve them by adding `--embeddings`:
-
-```bash
-npx gitnexus analyze --embeddings
-```
-
-To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
-
-> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
-
-## CLI
-
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
-| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
-| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
-| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
-| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
-| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
-
-<!-- gitnexus:end -->
+|---|---|
+| 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> |

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/versions/073_add_device_types_table.py

@@ -0,0 +1,132 @@
+"""Add account-scoped device_types table with platform seed data.
+
+Revision ID: 073
+Revises: b3c7e9f2a1d8
+Create Date: 2026-04-12
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+import uuid
+
+
+revision = "073"
+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),
+    ("firewall", "Firewall", "network", 2),
+    ("access-point", "Access Point", "network", 3),
+    ("load-balancer", "Load Balancer", "network", 4),
+    ("server", "Server", "compute", 0),
+    ("workstation", "Workstation", "compute", 1),
+    ("vm", "Virtual Machine", "compute", 2),
+    ("container", "Container", "compute", 3),
+    ("nas", "NAS", "storage", 0),
+    ("san", "SAN", "storage", 1),
+    ("cloud-storage", "Cloud Storage", "storage", 2),
+    ("cloud", "Cloud", "cloud", 0),
+    ("aws", "AWS", "cloud", 1),
+    ("azure", "Azure", "cloud", 2),
+    ("gcp", "Google Cloud", "cloud", 3),
+    ("printer", "Printer", "endpoint", 0),
+    ("phone", "Phone", "endpoint", 1),
+    ("iot", "IoT Device", "endpoint", 2),
+    ("camera", "Camera", "endpoint", 3),
+    ("tablet", "Tablet", "endpoint", 4),
+    ("laptop", "Laptop", "endpoint", 5),
+    ("ups", "UPS", "infrastructure", 0),
+    ("pdu", "PDU", "infrastructure", 1),
+    ("rack", "Rack", "infrastructure", 2),
+    ("patch-panel", "Patch Panel", "infrastructure", 3),
+    ("nvr", "NVR", "security", 0),
+    ("badge-reader", "Badge Reader", "security", 1),
+]
+
+
+def upgrade() -> None:
+    op.create_table(
+        "device_types",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("slug", sa.String(50), nullable=False),
+        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("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.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",
+        sa.column("id", UUID(as_uuid=True)),
+        sa.column("slug", sa.String),
+        sa.column("label", sa.String),
+        sa.column("category", sa.String),
+        sa.column("is_system", sa.Boolean),
+        sa.column("account_id", UUID(as_uuid=True)),
+        sa.column("sort_order", sa.Integer),
+    )
+
+    op.bulk_insert(device_types_table, [
+        {
+            "id": uuid.uuid4(),
+            "slug": slug,
+            "label": label,
+            "category": category,
+            "is_system": True,
+            "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

@@ -0,0 +1,57 @@
+"""Add network_diagrams table.
+
+Revision ID: 074
+Revises: 073
+Create Date: 2026-04-12
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+
+revision = "074"
+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("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),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("nodes", JSONB(), nullable=False, server_default=sa.text("'[]'::jsonb")),
+        sa.Column("edges", JSONB(), nullable=False, server_default=sa.text("'[]'::jsonb")),
+        sa.Column("thumbnail_url", sa.Text(), nullable=True),
+        sa.Column("is_archived", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("created_by", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
+    )
+
+    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/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/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/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/endpoints/accounts.py

@@ -16,6 +16,7 @@ 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
@@ -559,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

@@ -5,8 +5,8 @@ from typing import Annotated, Optional
 from uuid import UUID
 from fastapi import APIRouter, Depends, HTTPException, status, Query
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy import select, func
-from sqlalchemy.orm import selectinload
+from sqlalchemy import select, func, or_
+from sqlalchemy.orm import selectinload, aliased
 
 from app.core.admin_database import get_admin_db
 from app.core.audit import log_audit
@@ -24,21 +24,44 @@ from app.models.invite_code import InviteCode
 from app.models.account_invite import AccountInvite
 from app.models.tree import Tree
 from app.schemas.user import UserResponse, RoleUpdate, AccountRoleUpdate
-from app.schemas.admin import MoveUserAccount, AdminUserCreate, AdminUserCreateResponse, AdminPasswordReset, AdminPasswordResetResponse, HardDeleteCheckResponse
+from app.schemas.admin import (
+    MoveUserAccount,
+    AdminUserCreate,
+    AdminUserCreateResponse,
+    AdminPasswordReset,
+    AdminPasswordResetResponse,
+    HardDeleteCheckResponse,
+    AdminUserListItem,
+    AdminUserListResponse,
+    AdminAccountMember,
+    AdminAccountListItem,
+    AdminAccountListResponse,
+    AdminAccountOwnerSummary,
+    AdminAccountSubscriptionSummary,
+    AdminAccountUsageSummary,
+    AdminAccountDetailResponse,
+    AdminAccountInviteSummary,
+    AdminAccountCreate,
+    AdminAccountUpdate,
+)
 from app.schemas.subscription import SubscriptionPlanUpdate, ExtendTrialRequest
 from app.schemas.user_detail import (
     UserDetailResponse, AccountSummary, SubscriptionSummary,
     SessionSummary, AuditLogSummary, InviteCodeUsedSummary,
 )
 from app.api.deps import require_admin
+from app.core.subscriptions import get_account_usage
 
 router = APIRouter(prefix="/admin", tags=["admin"])
 
 
-@router.get("/users", response_model=list[UserResponse])
+@router.get("/users", response_model=AdminUserListResponse)
 async def list_users(
     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),
+    search: Optional[str] = Query(None, description="Search by user or account fields"),
     skip: int = Query(0, ge=0),
     limit: int = Query(100, ge=1, le=100),
     is_active: Optional[bool] = Query(None, description="Filter by active status"),
@@ -46,23 +69,240 @@ async def list_users(
     account_id: Optional[UUID] = Query(None, description="Filter by account"),
     include_archived: bool = Query(False, description="Include archived (soft-deleted) users"),
 ):
-    """List all users (super admin only)."""
-    query = select(User)
+    """List users for super admin global people search."""
+    resolved_limit = size or limit
+    resolved_skip = skip
+    current_page = 1
+
+    if page is not None:
+        resolved_skip = (page - 1) * resolved_limit
+        current_page = page
+    elif resolved_limit > 0:
+        current_page = (resolved_skip // resolved_limit) + 1
+
+    count_query = (
+        select(func.count())
+        .select_from(User)
+        .outerjoin(Account, User.account_id == Account.id)
+    )
+    query = (
+        select(
+            User,
+            Account.name.label("account_name"),
+            Account.display_code.label("account_display_code"),
+        )
+        .outerjoin(Account, User.account_id == Account.id)
+    )
 
     if not include_archived:
         query = query.where(User.deleted_at.is_(None))
+        count_query = count_query.where(User.deleted_at.is_(None))
     if is_active is not None:
         query = query.where(User.is_active == is_active)
+        count_query = count_query.where(User.is_active == is_active)
     if role:
         query = query.where(User.role == role)
+        count_query = count_query.where(User.role == role)
     if account_id:
         query = query.where(User.account_id == account_id)
+        count_query = count_query.where(User.account_id == account_id)
+    if search:
+        search_term = f"%{search.strip()}%"
+        search_filter = or_(
+            User.name.ilike(search_term),
+            User.email.ilike(search_term),
+            Account.name.ilike(search_term),
+            Account.display_code.ilike(search_term),
+        )
+        query = query.where(search_filter)
+        count_query = count_query.where(search_filter)
 
-    query = query.order_by(User.created_at.desc()).offset(skip).limit(limit)
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
 
+    query = query.order_by(User.created_at.desc()).offset(resolved_skip).limit(resolved_limit)
     result = await db.execute(query)
-    users = result.scalars().all()
-    return users
+    rows = result.all()
+
+    items = [
+        AdminUserListItem(
+            id=user.id,
+            email=user.email,
+            name=user.name,
+            role=user.role,
+            is_super_admin=user.is_super_admin,
+            is_active=user.is_active,
+            account_id=user.account_id,
+            account_role=user.account_role,
+            account_name=account_name,
+            account_display_code=account_display_code,
+            created_at=user.created_at,
+            last_login=user.last_login,
+            deleted_at=user.deleted_at,
+        )
+        for user, account_name, account_display_code in rows
+    ]
+
+    return AdminUserListResponse(
+        items=items,
+        total=total,
+        page=current_page,
+        per_page=resolved_limit,
+    )
+
+
+@router.get("/accounts", response_model=AdminAccountListResponse)
+async def list_accounts(
+    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),
+    search: Optional[str] = Query(None, description="Search by account, display code, or owner"),
+    plan: Optional[str] = Query(None, description="Filter by subscription plan"),
+    status: Optional[str] = Query(None, description="Filter by subscription status"),
+    include_archived: bool = Query(False, description="Include archived users in account member lists"),
+):
+    """List accounts with embedded members for the admin panel."""
+    owner_user = aliased(User)
+
+    count_query = (
+        select(func.count(func.distinct(Account.id)))
+        .select_from(Account)
+        .outerjoin(owner_user, Account.owner_id == owner_user.id)
+        .outerjoin(Subscription, Subscription.account_id == Account.id)
+    )
+    accounts_query = (
+        select(
+            Account,
+            owner_user.id.label("owner_user_id"),
+            owner_user.name.label("owner_name"),
+            owner_user.email.label("owner_email"),
+            Subscription.id.label("subscription_id"),
+            Subscription.plan.label("subscription_plan"),
+            Subscription.status.label("subscription_status"),
+            Subscription.billing_interval.label("subscription_billing_interval"),
+            Subscription.current_period_end.label("subscription_current_period_end"),
+            Subscription.cancel_at_period_end.label("subscription_cancel_at_period_end"),
+        )
+        .outerjoin(owner_user, Account.owner_id == owner_user.id)
+        .outerjoin(Subscription, Subscription.account_id == Account.id)
+    )
+
+    if search:
+        search_term = f"%{search.strip()}%"
+        search_filter = or_(
+            Account.name.ilike(search_term),
+            Account.display_code.ilike(search_term),
+            owner_user.name.ilike(search_term),
+            owner_user.email.ilike(search_term),
+        )
+        count_query = count_query.where(search_filter)
+        accounts_query = accounts_query.where(search_filter)
+    if plan:
+        count_query = count_query.where(Subscription.plan == plan)
+        accounts_query = accounts_query.where(Subscription.plan == plan)
+    if status:
+        count_query = count_query.where(Subscription.status == status)
+        accounts_query = accounts_query.where(Subscription.status == status)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    accounts_result = await db.execute(
+        accounts_query
+        .order_by(Account.created_at.desc())
+        .offset((page - 1) * size)
+        .limit(size)
+    )
+    rows = accounts_result.all()
+    accounts = [row.Account for row in rows]
+
+    account_ids = [account.id for account in accounts]
+    members_by_account: dict[UUID, list[AdminAccountMember]] = {account_id: [] for account_id in account_ids}
+    pending_invites_by_account: dict[UUID, int] = {account_id: 0 for account_id in account_ids}
+    usage_by_account: dict[UUID, AdminAccountUsageSummary] = {}
+
+    if account_ids:
+        members_query = select(User).where(User.account_id.in_(account_ids))
+        if not include_archived:
+            members_query = members_query.where(User.deleted_at.is_(None))
+        members_query = members_query.order_by(User.created_at.asc())
+
+        members_result = await db.execute(members_query)
+        for member in members_result.scalars().all():
+            members_by_account.setdefault(member.account_id, []).append(
+                AdminAccountMember(
+                    id=member.id,
+                    email=member.email,
+                    name=member.name,
+                    role=member.role,
+                    is_super_admin=member.is_super_admin,
+                    is_active=member.is_active,
+                    account_role=member.account_role,
+                    created_at=member.created_at,
+                    last_login=member.last_login,
+                    deleted_at=member.deleted_at,
+                )
+            )
+
+        pending_invites_result = await db.execute(
+            select(AccountInvite.account_id, func.count(AccountInvite.id))
+            .where(
+                AccountInvite.account_id.in_(account_ids),
+                AccountInvite.used_at.is_(None),
+            )
+            .group_by(AccountInvite.account_id)
+        )
+        pending_invites_by_account.update({row[0]: row[1] for row in pending_invites_result.all()})
+
+        for account_id in account_ids:
+            usage = await get_account_usage(account_id, db)
+            usage_by_account[account_id] = AdminAccountUsageSummary(
+                tree_count=usage.get("tree_count", 0),
+                session_count_this_month=usage.get("session_count_this_month", 0),
+            )
+
+    items = [
+        AdminAccountListItem(
+            id=row.Account.id,
+            name=row.Account.name,
+            display_code=row.Account.display_code,
+            created_at=row.Account.created_at,
+            owner_id=row.Account.owner_id,
+            owner=(
+                AdminAccountOwnerSummary(
+                    id=row.owner_user_id,
+                    name=row.owner_name,
+                    email=row.owner_email,
+                ) if row.owner_user_id and row.owner_name and row.owner_email else None
+            ),
+            subscription=(
+                AdminAccountSubscriptionSummary(
+                    id=row.subscription_id,
+                    plan=row.subscription_plan,
+                    status=row.subscription_status,
+                    billing_interval=row.subscription_billing_interval,
+                    current_period_end=row.subscription_current_period_end,
+                    cancel_at_period_end=row.subscription_cancel_at_period_end or False,
+                ) if row.subscription_id and row.subscription_plan and row.subscription_status else None
+            ),
+            usage=usage_by_account.get(row.Account.id, AdminAccountUsageSummary()),
+            member_count=len(members_by_account.get(row.Account.id, [])),
+            active_member_count=sum(1 for member in members_by_account.get(row.Account.id, []) if member.is_active),
+            pending_invite_count=pending_invites_by_account.get(row.Account.id, 0),
+            sso_enabled=row.Account.sso_enabled,
+            branding_company_name=row.Account.branding_company_name,
+            members=members_by_account.get(row.Account.id, []),
+        )
+        for row in rows
+    ]
+
+    return AdminAccountListResponse(
+        items=items,
+        total=total,
+        page=page,
+        per_page=size,
+    )
 
 
 def _generate_display_code() -> str:
@@ -71,6 +311,192 @@ def _generate_display_code() -> str:
     return ''.join(secrets.choice(chars) for _ in range(8))
 
 
+async def _generate_unique_display_code(db: AsyncSession) -> str:
+    """Generate a unique display code for a new account."""
+    while True:
+        display_code = _generate_display_code()
+        existing = await db.execute(select(Account.id).where(Account.display_code == display_code))
+        if existing.scalar_one_or_none() is None:
+            return display_code
+
+
+async def _get_account_detail_payload(
+    account_id: UUID,
+    db: AsyncSession,
+    include_archived: bool = False,
+) -> AdminAccountDetailResponse:
+    owner_user = aliased(User)
+    result = await db.execute(
+        select(
+            Account,
+            owner_user.id.label("owner_user_id"),
+            owner_user.name.label("owner_name"),
+            owner_user.email.label("owner_email"),
+            Subscription.id.label("subscription_id"),
+            Subscription.plan.label("subscription_plan"),
+            Subscription.status.label("subscription_status"),
+            Subscription.billing_interval.label("subscription_billing_interval"),
+            Subscription.current_period_end.label("subscription_current_period_end"),
+            Subscription.cancel_at_period_end.label("subscription_cancel_at_period_end"),
+        )
+        .outerjoin(owner_user, Account.owner_id == owner_user.id)
+        .outerjoin(Subscription, Subscription.account_id == Account.id)
+        .where(Account.id == account_id)
+    )
+    row = result.one_or_none()
+    if not row:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Account not found")
+
+    members_query = select(User).where(User.account_id == account_id).order_by(User.created_at.asc())
+    if not include_archived:
+        members_query = members_query.where(User.deleted_at.is_(None))
+    members_result = await db.execute(members_query)
+    members = [
+        AdminAccountMember(
+            id=member.id,
+            email=member.email,
+            name=member.name,
+            role=member.role,
+            is_super_admin=member.is_super_admin,
+            is_active=member.is_active,
+            account_role=member.account_role,
+            created_at=member.created_at,
+            last_login=member.last_login,
+            deleted_at=member.deleted_at,
+        )
+        for member in members_result.scalars().all()
+    ]
+
+    invites_result = await db.execute(
+        select(AccountInvite)
+        .where(AccountInvite.account_id == account_id)
+        .order_by(AccountInvite.created_at.desc())
+    )
+    invites = [
+        AdminAccountInviteSummary(
+            id=invite.id,
+            email=invite.email,
+            role=invite.role,
+            expires_at=invite.expires_at,
+            created_at=invite.created_at,
+            used_at=invite.used_at,
+        )
+        for invite in invites_result.scalars().all()
+        if invite.used_at is None
+    ]
+
+    usage = await get_account_usage(account_id, db)
+
+    return AdminAccountDetailResponse(
+        id=row.Account.id,
+        name=row.Account.name,
+        display_code=row.Account.display_code,
+        created_at=row.Account.created_at,
+        owner_id=row.Account.owner_id,
+        owner=(
+            AdminAccountOwnerSummary(
+                id=row.owner_user_id,
+                name=row.owner_name,
+                email=row.owner_email,
+            ) if row.owner_user_id and row.owner_name and row.owner_email else None
+        ),
+        subscription=(
+            AdminAccountSubscriptionSummary(
+                id=row.subscription_id,
+                plan=row.subscription_plan,
+                status=row.subscription_status,
+                billing_interval=row.subscription_billing_interval,
+                current_period_end=row.subscription_current_period_end,
+                cancel_at_period_end=row.subscription_cancel_at_period_end or False,
+            ) if row.subscription_id and row.subscription_plan and row.subscription_status else None
+        ),
+        usage=AdminAccountUsageSummary(
+            tree_count=usage.get("tree_count", 0),
+            session_count_this_month=usage.get("session_count_this_month", 0),
+        ),
+        member_count=len(members),
+        active_member_count=sum(1 for member in members if member.is_active),
+        pending_invite_count=len(invites),
+        sso_enabled=row.Account.sso_enabled,
+        branding_company_name=row.Account.branding_company_name,
+        members=members,
+        invites=invites,
+    )
+
+
+@router.post("/accounts", response_model=AdminAccountDetailResponse, status_code=status.HTTP_201_CREATED)
+async def create_account(
+    data: AdminAccountCreate,
+    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()
+
+    new_subscription = Subscription(
+        account_id=new_account.id,
+        plan=data.plan,
+        status="active",
+    )
+    db.add(new_subscription)
+
+    await log_audit(
+        db, current_user.id, "account.create_admin", "account", new_account.id,
+        {"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)
+
+
+@router.get("/accounts/{account_id}", response_model=AdminAccountDetailResponse)
+async def get_account_detail(
+    account_id: UUID,
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+    current_user: Annotated[User, Depends(require_admin)],
+    include_archived: bool = Query(False),
+):
+    """Get detailed account information for admin management."""
+    return await _get_account_detail_payload(account_id, db, include_archived=include_archived)
+
+
+@router.put("/accounts/{account_id}", response_model=AdminAccountDetailResponse)
+async def update_account(
+    account_id: UUID,
+    data: AdminAccountUpdate,
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+    current_user: Annotated[User, Depends(require_admin)],
+):
+    """Update account settings from the admin panel."""
+    result = await db.execute(select(Account).where(Account.id == account_id))
+    account = result.scalar_one_or_none()
+    if not account:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Account not found")
+
+    old_name = account.name
+    account.name = data.name.strip()
+    await log_audit(
+        db, current_user.id, "account.update_admin", "account", account.id,
+        {"old_name": old_name, "new_name": account.name},
+    )
+    await db.commit()
+    return await _get_account_detail_payload(account.id, db)
+
+
 @router.post("/users", response_model=AdminUserCreateResponse, status_code=status.HTTP_201_CREATED)
 async def create_user(
     data: AdminUserCreate,
@@ -516,6 +942,28 @@ async def _get_user_subscription(user_id: UUID, db: AsyncSession) -> tuple[User,
     return user, subscription
 
 
+async def _get_account_subscription(account_id: UUID, db: AsyncSession) -> tuple[Account, Subscription]:
+    """Helper to load account and its subscription."""
+    account_result = await db.execute(select(Account).where(Account.id == account_id))
+    account = account_result.scalar_one_or_none()
+    if not account:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Account not found")
+
+    sub_result = await db.execute(
+        select(Subscription).where(Subscription.account_id == account.id)
+    )
+    subscription = sub_result.scalar_one_or_none()
+    if not subscription:
+        subscription = Subscription(
+            account_id=account.id,
+            plan="free",
+            status="active",
+        )
+        db.add(subscription)
+        await db.flush()
+    return account, subscription
+
+
 @router.put("/users/{user_id}/subscription/plan")
 async def update_user_plan(
     user_id: UUID,
@@ -535,6 +983,31 @@ async def update_user_plan(
     return {"plan": subscription.plan, "status": subscription.status}
 
 
+@router.put("/accounts/{account_id}/subscription/plan")
+async def update_account_plan(
+    account_id: UUID,
+    data: SubscriptionPlanUpdate,
+    db: Annotated[AsyncSession, Depends(get_admin_db)],
+    current_user: Annotated[User, Depends(require_admin)],
+):
+    """Change an account subscription plan (super admin only)."""
+    if data.plan not in ("free", "pro", "team"):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid plan")
+    account, subscription = await _get_account_subscription(account_id, db)
+    old_plan = subscription.plan
+    subscription.plan = data.plan
+    await log_audit(
+        db,
+        current_user.id,
+        "subscription.plan_change",
+        "subscription",
+        subscription.id,
+        {"old_plan": old_plan, "new_plan": data.plan, "account_id": str(account_id)},
+    )
+    await db.commit()
+    return {"plan": subscription.plan, "status": subscription.status}
+
+
 @router.put("/users/{user_id}/subscription/extend-trial")
 async def extend_user_trial(
     user_id: UUID,
@@ -565,6 +1038,43 @@ async def extend_user_trial(
             "current_period_end": subscription.current_period_end}
 
 
+@router.put("/accounts/{account_id}/subscription/extend-trial")
+async def extend_account_trial(
+    account_id: UUID,
+    data: ExtendTrialRequest,
+    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)."""
+    if data.days < 1 or data.days > 90:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Days must be 1-90")
+    account, subscription = await _get_account_subscription(account_id, db)
+
+    now = datetime.now(timezone.utc)
+    if subscription.status == "trialing" and subscription.current_period_end:
+        new_end = subscription.current_period_end + timedelta(days=data.days)
+    else:
+        subscription.status = "trialing"
+        subscription.current_period_start = now
+        new_end = now + timedelta(days=data.days)
+
+    subscription.current_period_end = new_end
+    await log_audit(
+        db,
+        current_user.id,
+        "subscription.extend_trial",
+        "subscription",
+        subscription.id,
+        {"days": data.days, "new_end": new_end.isoformat(), "account_id": str(account.id)},
+    )
+    await db.commit()
+    return {
+        "plan": subscription.plan,
+        "status": subscription.status,
+        "current_period_end": subscription.current_period_end,
+    }
+
+
 @router.post("/users/{user_id}/password-reset", response_model=AdminPasswordResetResponse)
 async def admin_reset_password(
     user_id: UUID,

backend/app/api/endpoints/device_types.py

@@ -0,0 +1,120 @@
+"""Device types API endpoints."""
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select, or_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.api.deps import get_current_active_user
+from app.models.user import User
+from app.models.device_type import DeviceType
+from app.schemas.device_type import (
+    DeviceTypeCreate,
+    DeviceTypeUpdate,
+    DeviceTypeResponse,
+)
+from app.core.service_account import PLATFORM_ACCOUNT_ID
+
+router = APIRouter(prefix="/device-types", tags=["device-types"])
+
+
+@router.get("/", response_model=list[DeviceTypeResponse])
+async def list_device_types(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> list[DeviceTypeResponse]:
+    stmt = (
+        select(DeviceType)
+        .where(
+            or_(
+                DeviceType.account_id == PLATFORM_ACCOUNT_ID,
+                DeviceType.account_id == current_user.account_id,
+            )
+        )
+        .order_by(DeviceType.category, DeviceType.sort_order, DeviceType.label)
+    )
+    result = await db.execute(stmt)
+    rows = result.scalars().all()
+    return [DeviceTypeResponse.model_validate(r) for r in rows]
+
+
+@router.post("/", response_model=DeviceTypeResponse, status_code=201)
+async def create_device_type(
+    data: DeviceTypeCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> DeviceTypeResponse:
+    existing = await db.execute(
+        select(DeviceType).where(
+            DeviceType.slug == data.slug,
+            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 account")
+
+    system_existing = await db.execute(
+        select(DeviceType).where(
+            DeviceType.slug == data.slug,
+            DeviceType.account_id == PLATFORM_ACCOUNT_ID,
+        )
+    )
+    if system_existing.scalar_one_or_none():
+        raise HTTPException(status_code=409, detail=f"Device type '{data.slug}' conflicts with a system type")
+
+    device_type = DeviceType(
+        slug=data.slug,
+        label=data.label,
+        category=data.category,
+        is_system=False,
+        account_id=current_user.account_id,
+        sort_order=data.sort_order,
+    )
+    db.add(device_type)
+    await db.commit()
+    await db.refresh(device_type)
+    return DeviceTypeResponse.model_validate(device_type)
+
+
+@router.put("/{device_type_id}", response_model=DeviceTypeResponse)
+async def update_device_type(
+    device_type_id: UUID,
+    data: DeviceTypeUpdate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> DeviceTypeResponse:
+    device_type = await db.get(DeviceType, device_type_id)
+    if not 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.account_id != current_user.account_id:
+        raise HTTPException(status_code=404, detail="Device type not found")
+
+    update_data = data.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(device_type, field, value)
+
+    await db.commit()
+    await db.refresh(device_type)
+    return DeviceTypeResponse.model_validate(device_type)
+
+
+@router.delete("/{device_type_id}", status_code=204)
+async def delete_device_type(
+    device_type_id: UUID,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> None:
+    device_type = await db.get(DeviceType, device_type_id)
+    if not 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.account_id != current_user.account_id:
+        raise HTTPException(status_code=404, detail="Device type not found")
+
+    await db.delete(device_type)
+    await db.commit()

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/network_diagrams.py

@@ -0,0 +1,362 @@
+"""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
+
+from app.core.database import get_db
+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,
+    NetworkDiagramResponse,
+    NetworkDiagramListItem,
+    AIGenerateRequest,
+    AIGenerateResponse,
+    DiagramImportRequest,
+    DiagramImportResponse,
+    DiagramExportResponse,
+    DiagramNode,
+    DiagramEdge,
+)
+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] = {
+    "router": "network", "switch": "network", "access-point": "network", "load-balancer": "network",
+    "firewall": "security", "badge-reader": "security",
+    "server": "compute", "vm": "compute", "container": "compute",
+    "nas": "storage", "san": "storage", "cloud-storage": "storage",
+    "cloud": "cloud", "aws": "cloud", "azure": "cloud", "gcp": "cloud", "isp": "cloud",
+    "workstation": "endpoint", "laptop": "endpoint", "tablet": "endpoint",
+    "phone": "endpoint", "printer": "endpoint",
+    "ups": "infrastructure", "pdu": "infrastructure", "rack": "infrastructure",
+    "patch-panel": "infrastructure", "camera": "infrastructure",
+    "nvr": "infrastructure", "iot": "infrastructure",
+}
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/network-diagrams", tags=["network-diagrams"])
+
+
+async def _get_diagram_or_404(
+    diagram_id: UUID,
+    account_id: UUID,
+    db: AsyncSession,
+) -> NetworkDiagram:
+    diagram = await db.get(NetworkDiagram, diagram_id)
+    if not diagram or diagram.account_id != account_id or diagram.is_archived:
+        raise HTTPException(status_code=404, detail="Diagram not found")
+    return diagram
+
+
+def _diagram_to_response(diagram: NetworkDiagram) -> NetworkDiagramResponse:
+    return NetworkDiagramResponse.model_validate(diagram)
+
+
+def _diagram_to_list_item(
+    diagram: NetworkDiagram,
+    custom_slug_category: dict[str, str] | None = None,
+) -> NetworkDiagramListItem:
+    nodes = diagram.nodes if isinstance(diagram.nodes, list) else []
+    slug_to_cat = {**_SLUG_CATEGORY, **(custom_slug_category or {})}
+
+    category_counts: dict[str, int] = {}
+    for node in nodes:
+        slug = node.get("type", "") if isinstance(node, dict) else ""
+        cat = slug_to_cat.get(slug, "other")
+        category_counts[cat] = category_counts.get(cat, 0) + 1
+
+    return NetworkDiagramListItem(
+        id=diagram.id,
+        name=diagram.name,
+        client_name=diagram.client_name,
+        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(account_id: UUID, db: AsyncSession) -> set[str]:
+    stmt = select(DeviceType.slug).where(
+        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()}
+
+
+@router.get("/clients", response_model=list[str])
+async def list_client_names(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> list[str]:
+    stmt = (
+        select(NetworkDiagram.client_name)
+        .where(
+            NetworkDiagram.account_id == current_user.account_id,
+            NetworkDiagram.is_archived.is_(False),
+            NetworkDiagram.client_name.isnot(None),
+            NetworkDiagram.client_name != "",
+        )
+        .distinct()
+        .order_by(NetworkDiagram.client_name)
+    )
+    result = await db.execute(stmt)
+    return [row[0] for row in result.all()]
+
+
+@router.get("/", response_model=list[NetworkDiagramListItem])
+async def list_diagrams(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+    client_name: str | None = Query(default=None),
+    search: str | None = Query(default=None),
+) -> list[NetworkDiagramListItem]:
+    stmt = (
+        select(NetworkDiagram)
+        .where(
+            NetworkDiagram.account_id == current_user.account_id,
+            NetworkDiagram.is_archived.is_(False),
+        )
+        .order_by(NetworkDiagram.updated_at.desc())
+    )
+
+    if client_name:
+        stmt = stmt.where(NetworkDiagram.client_name == client_name)
+
+    if search:
+        escaped = search.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        search_filter = f"%{escaped}%"
+        stmt = stmt.where(
+            or_(
+                NetworkDiagram.name.ilike(search_filter),
+                NetworkDiagram.client_name.ilike(search_filter),
+            )
+        )
+
+    # 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.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()}
+
+    result = await db.execute(stmt)
+    rows = result.scalars().all()
+    return [_diagram_to_list_item(r, custom_slug_category) for r in rows]
+
+
+@router.post("/", response_model=NetworkDiagramResponse, status_code=201)
+async def create_diagram(
+    data: NetworkDiagramCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> NetworkDiagramResponse:
+    diagram = NetworkDiagram(
+        account_id=current_user.account_id,
+        name=data.name,
+        client_name=data.client_name,
+        asset_name=data.asset_name,
+        description=data.description,
+        nodes=[n.model_dump() for n in data.nodes],
+        edges=[e.model_dump() for e in data.edges],
+        created_by=current_user.id,
+    )
+    db.add(diagram)
+    await db.commit()
+    await db.refresh(diagram)
+    return _diagram_to_response(diagram)
+
+
+@router.get("/{diagram_id}", response_model=NetworkDiagramResponse)
+async def get_diagram(
+    diagram_id: UUID,
+    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.account_id, db)
+    return _diagram_to_response(diagram)
+
+
+@router.put("/{diagram_id}", response_model=NetworkDiagramResponse)
+async def update_diagram(
+    diagram_id: UUID,
+    data: NetworkDiagramUpdate,
+    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.account_id, db)
+
+    update_data = data.model_dump(exclude_unset=True)
+    if "nodes" in update_data and update_data["nodes"] is not None:
+        update_data["nodes"] = [n.model_dump() if hasattr(n, "model_dump") else n for n in update_data["nodes"]]
+    if "edges" in update_data and update_data["edges"] is not None:
+        update_data["edges"] = [e.model_dump() if hasattr(e, "model_dump") else e for e in update_data["edges"]]
+
+    for field, value in update_data.items():
+        setattr(diagram, field, value)
+
+    diagram.updated_at = datetime.now(timezone.utc)
+    await db.commit()
+    await db.refresh(diagram)
+    return _diagram_to_response(diagram)
+
+
+@router.delete("/{diagram_id}", status_code=204)
+async def archive_diagram(
+    diagram_id: UUID,
+    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)
+    diagram.is_archived = True
+    diagram.updated_at = datetime.now(timezone.utc)
+    await db.commit()
+
+
+@router.post("/{diagram_id}/duplicate", response_model=NetworkDiagramResponse, status_code=201)
+async def duplicate_diagram(
+    diagram_id: UUID,
+    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.account_id, db)
+    copy = NetworkDiagram(
+        account_id=current_user.account_id,
+        name=f"Copy of {source.name}",
+        client_name=source.client_name,
+        asset_name=source.asset_name,
+        description=source.description,
+        nodes=source.nodes,
+        edges=source.edges,
+        created_by=current_user.id,
+    )
+    db.add(copy)
+    await db.commit()
+    await db.refresh(copy)
+    return _diagram_to_response(copy)
+
+
+@router.get("/{diagram_id}/export", response_model=DiagramExportResponse)
+async def export_diagram(
+    diagram_id: UUID,
+    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.account_id, db)
+    nodes = [DiagramNode(**n) for n in (diagram.nodes or [])]
+    edges = [DiagramEdge(**e) for e in (diagram.edges or [])]
+    return DiagramExportResponse(
+        schemaVersion=1,
+        name=diagram.name,
+        client_name=diagram.client_name,
+        description=diagram.description,
+        nodes=nodes,
+        edges=edges,
+        exportedAt=datetime.now(timezone.utc).isoformat(),
+    )
+
+
+@router.post("/import", response_model=DiagramImportResponse, status_code=201)
+async def import_diagram(
+    data: DiagramImportRequest,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)],
+) -> DiagramImportResponse:
+    available_slugs = await _get_available_slugs(current_user.account_id, db)
+
+    warnings: list[str] = []
+    for node in data.nodes:
+        if node.type not in available_slugs:
+            warnings.append(f"Unknown device type '{node.type}' — will render with default icon")
+
+    diagram = NetworkDiagram(
+        account_id=current_user.account_id,
+        name=data.name,
+        client_name=data.client_name,
+        description=data.description,
+        nodes=[n.model_dump() for n in data.nodes],
+        edges=[e.model_dump() for e in data.edges],
+        created_by=current_user.id,
+    )
+    db.add(diagram)
+    await db.commit()
+    await db.refresh(diagram)
+
+    return DiagramImportResponse(
+        diagram=_diagram_to_response(diagram),
+        warnings=warnings,
+    )
+
+
+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.account_id, db)
+    available_slugs = list(available_slugs_set)
+
+    existing_node_ids: list[str] | None = None
+    if data.mode == "merge" and data.existingBounds:
+        existing_node_ids = []
+
+    try:
+        return await network_diagram_ai_service.generate_diagram(
+            request=data,
+            available_slugs=available_slugs,
+            existing_node_ids=existing_node_ids,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=str(e))
+    except Exception:
+        logger.exception("AI diagram generation failed")
+        raise HTTPException(status_code=500, detail="Diagram generation failed")

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,
@@ -88,6 +160,8 @@ async def create_session(
         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
@@ -374,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/router.py

@@ -24,6 +24,8 @@ from app.api.endpoints import (
     branding,
     categories,
     copilot,
+    device_types,
+    draft_templates,
     feedback,
     flow_proposals,
     flowpilot_analytics,
@@ -32,6 +34,7 @@ from app.api.endpoints import (
     invite,
     kb_accelerator,
     maintenance_schedules,
+    network_diagrams,
     notifications,
     onboarding,
     public_templates,
@@ -39,8 +42,10 @@ from app.api.endpoints import (
     scripts,
     script_builder,
     session_branches,
+    session_facts,
     session_handoffs,
     session_resolutions,
+    session_suggested_fixes,
     sessions,
     shared,
     shares,
@@ -93,7 +98,6 @@ api_router.include_router(admin_settings.router)
 api_router.include_router(admin_categories.router)
 api_router.include_router(admin_survey.router)
 api_router.include_router(admin_gallery.router)
-
 # ---------------------------------------------------------------------------
 # User-facing endpoints — tenant context required
 # ---------------------------------------------------------------------------
@@ -130,9 +134,15 @@ 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)
@@ -142,3 +152,4 @@ 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/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/config.py

@@ -128,6 +128,24 @@ class Settings(BaseSettings):
         "variable_inference": "fast",
         "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/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/models/__init__.py

@@ -56,6 +56,12 @@ 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",
@@ -126,4 +132,10 @@ __all__ = [
     "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

@@ -214,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/device_type.py

@@ -0,0 +1,47 @@
+"""Device type model for network diagrams."""
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import String, Boolean, Integer, DateTime, ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.dialects.postgresql import UUID
+
+from app.core.database import Base
+
+
+class DeviceType(Base):
+    """A device type for network diagram nodes (platform or account-custom)."""
+    __tablename__ = "device_types"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    slug: Mapped[str] = mapped_column(
+        String(50), nullable=False,
+        comment="Unique identifier used in diagram node data",
+    )
+    label: Mapped[str] = mapped_column(
+        String(100), nullable=False,
+        comment="Display name",
+    )
+    category: Mapped[str] = mapped_column(
+        String(50), nullable=False,
+        comment="network, compute, storage, cloud, endpoint, infrastructure, security",
+    )
+    is_system: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False,
+        comment="True for built-in types that cannot be deleted",
+    )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        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,
+        comment="Display order within category",
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )

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/network_diagram.py

@@ -0,0 +1,53 @@
+"""Network diagram model."""
+import uuid
+from datetime import datetime, timezone
+from typing import Any, TYPE_CHECKING
+
+from sqlalchemy import String, Text, Boolean, DateTime, ForeignKey, text
+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.user import User
+
+
+class NetworkDiagram(Base):
+    """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
+    )
+    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(255), nullable=False)
+    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=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,
+    )
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id"),
+        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),
+    )
+
+    creator: Mapped["User | None"] = relationship("User", foreign_keys=[created_by])

backend/app/models/script_builder_session.py

@@ -62,6 +62,16 @@ class ScriptBuilderSession(Base):
         nullable=True,
         comment="Link to FlowPilot session if launched from there",
     )
+    origin: Mapped[str] = mapped_column(
+        String(20),
+        nullable=False,
+        default="standalone",
+        comment=(
+            "Session origin — 'standalone' (from /script-builder) or "
+            "'pilot_inline' (from FlowPilot Script Builder tab). "
+            "Invariant: pilot_inline rows must have ai_session_id set."
+        ),
+    )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
     )

backend/app/models/script_template.py

@@ -78,6 +78,20 @@ class ScriptTemplate(Base):
     is_gallery_featured: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, server_default=text("false"), index=True)
     gallery_sort_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=text("0"))
     usage_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=text("0"))
+    # ── Provenance (Phase 1 — FlowPilot migration) ──
+    # Populated when a template is promoted from a post-resolve draft_templates row.
+    # Powers the Script Library provenance chip:
+    # "generated from CW #X · resolved by Y · used N times"
+    source_session_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ai_sessions.id"), nullable=True,
+    )
+    source_user_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("users.id"), nullable=True,
+    )
+    source_ticket_ref: Mapped[Optional[str]] = mapped_column(
+        String(64), nullable=True,
+        comment="Human-readable PSA ticket ref for display, e.g. 'CW #48307'",
+    )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
     )

backend/app/models/session_fact.py

@@ -0,0 +1,79 @@
+"""Session fact model — the "What we know" backing store for a FlowPilot session.
+
+A fact is an atomic, engineer-readable statement of what has been confirmed
+during troubleshooting. Facts accumulate across the session and drive the
+resolution note preview.
+
+`source_ref` is a polymorphic pointer to a task-lane item inside
+`ai_sessions.pending_task_lane` JSON — it is NOT a FK. Integrity is enforced
+at the service layer per the FLOWPILOT-MIGRATION design doc Section 4.2.
+Phase 2 assigns stable UUIDs to those task-lane items so `source_ref` has
+something reliable to point to.
+"""
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Text, DateTime, ForeignKey, String, CheckConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.ai_session import AISession
+    from app.models.account import Account
+    from app.models.user import User
+
+
+class SessionFact(Base):
+    """A single fact in the What-we-know section of a session's task lane."""
+    __tablename__ = "session_facts"
+    __table_args__ = (
+        CheckConstraint(
+            "source_type IN ('question', 'diagnostic_check', 'user_note', 'ai_synthesis')",
+            name="ck_session_facts_source_type",
+        ),
+    )
+
+    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,
+    )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id"),
+        nullable=False,
+    )
+    text: Mapped[str] = mapped_column(Text, nullable=False)
+    source_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    # Pointer to a task-lane item UUID inside ai_sessions.pending_task_lane.
+    # NOT a FK. Null for `user_note` and `ai_synthesis` sources.
+    source_ref: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), nullable=True
+    )
+    source_summary: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_by: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id"),
+        nullable=False,
+    )
+    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),
+    )
+    deleted_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    session: Mapped["AISession"] = relationship("AISession", foreign_keys=[session_id])
+    account: Mapped["Account"] = relationship("Account", foreign_keys=[account_id])
+    creator: Mapped["User"] = relationship("User", foreign_keys=[created_by])

backend/app/models/session_suggested_fix.py

@@ -0,0 +1,100 @@
+"""Session suggested-fix model — AI-proposed resolution path for a session.
+
+A session can have multiple suggested fixes over its lifetime as the AI's
+understanding evolves. Only one is active at a time (superseded_at IS NULL);
+emitting a new [SUGGEST_FIX] marker supersedes the prior active one.
+"""
+import uuid
+from datetime import datetime, timezone
+from typing import Any, TYPE_CHECKING
+
+from sqlalchemy import (
+    Text, DateTime, ForeignKey, String, Integer, 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.ai_session import AISession
+    from app.models.account import Account
+    from app.models.script_template import ScriptTemplate
+
+
+class SessionSuggestedFix(Base):
+    """One AI-proposed fix for a FlowPilot session."""
+    __tablename__ = "session_suggested_fixes"
+    __table_args__ = (
+        CheckConstraint(
+            "confidence_pct BETWEEN 0 AND 100",
+            name="ck_session_suggested_fixes_confidence_pct",
+        ),
+        CheckConstraint(
+            "user_decision IS NULL OR user_decision IN ("
+            "'one_off', 'draft_template', 'build_template', 'dismissed')",
+            name="ck_session_suggested_fixes_user_decision",
+        ),
+        CheckConstraint(
+            "status IN ('proposed', 'applied_success', 'applied_failed', "
+            "'applied_partial', 'dismissed')",
+            name="ck_session_suggested_fixes_status",
+        ),
+    )
+
+    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,
+    )
+    account_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id"),
+        nullable=False,
+    )
+    title: Mapped[str] = mapped_column(String(200), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    confidence_pct: Mapped[int] = mapped_column(Integer, nullable=False)
+    script_template_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("script_templates.id"),
+        nullable=True,
+    )
+    # Populated only when there's no matching template and the AI has
+    # drafted a session-specific script.
+    ai_drafted_script: Mapped[str | None] = mapped_column(Text, nullable=True)
+    ai_drafted_parameters: Mapped[dict[str, Any] | None] = mapped_column(
+        JSONB, nullable=True
+    )
+    user_decision: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # Outcome dimension — did the fix work? Orthogonal to user_decision.
+    status: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="proposed"
+    )
+    applied_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    verified_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    partial_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    failure_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    ai_outcome_proposal: Mapped[dict[str, Any] | None] = mapped_column(
+        JSONB, nullable=True
+    )
+    # Set when a newer suggested fix supersedes this one.
+    superseded_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    session: Mapped["AISession"] = relationship("AISession", foreign_keys=[session_id])
+    account: Mapped["Account"] = relationship("Account", foreign_keys=[account_id])
+    script_template: Mapped["ScriptTemplate | None"] = relationship(
+        "ScriptTemplate", foreign_keys=[script_template_id]
+    )

backend/app/schemas/__init__.py

@@ -20,6 +20,7 @@ from .psa_connection import (
     PSATicketSearchResult, PSATicketStatusItem,
     PsaPostRequest, PsaPostResponse, PsaPreviewResponse, PsaPostLogResponse,
     PsaMemberMappingResponse, PsaMemberMappingSaveRequest, PsaMemberResponse, AutoMatchResult,
+    PSABoardResponse,
 )
 
 __all__ = [
@@ -50,4 +51,5 @@ __all__ = [
     "PSATicketSearchResult", "PSATicketStatusItem",
     "PsaPostRequest", "PsaPostResponse", "PsaPreviewResponse", "PsaPostLogResponse",
     "PsaMemberMappingResponse", "PsaMemberMappingSaveRequest", "PsaMemberResponse", "AutoMatchResult",
+    "PSABoardResponse",
 ]

backend/app/schemas/admin.py

@@ -28,6 +28,111 @@ class ActivityEntry(BaseModel):
         from_attributes = True
 
 
+# --- Admin Accounts & People Search ---
+
+class AdminUserListItem(BaseModel):
+    id: UUID
+    email: EmailStr
+    name: str
+    role: str
+    is_super_admin: bool = False
+    is_active: bool = True
+    account_id: Optional[UUID] = None
+    account_role: Optional[str] = None
+    account_name: Optional[str] = None
+    account_display_code: Optional[str] = None
+    created_at: datetime
+    last_login: Optional[datetime] = None
+    deleted_at: Optional[datetime] = None
+
+
+class AdminUserListResponse(BaseModel):
+    items: list[AdminUserListItem]
+    total: int
+    page: int
+    per_page: int
+
+
+class AdminAccountMember(BaseModel):
+    id: UUID
+    email: EmailStr
+    name: str
+    role: str
+    is_super_admin: bool = False
+    is_active: bool = True
+    account_role: Optional[str] = None
+    created_at: datetime
+    last_login: Optional[datetime] = None
+    deleted_at: Optional[datetime] = None
+
+
+class AdminAccountOwnerSummary(BaseModel):
+    id: UUID
+    name: str
+    email: EmailStr
+
+
+class AdminAccountSubscriptionSummary(BaseModel):
+    id: UUID
+    plan: str
+    status: str
+    billing_interval: Optional[str] = None
+    current_period_end: Optional[datetime] = None
+    cancel_at_period_end: bool = False
+
+
+class AdminAccountUsageSummary(BaseModel):
+    tree_count: int = 0
+    session_count_this_month: int = 0
+
+
+class AdminAccountInviteSummary(BaseModel):
+    id: UUID
+    email: EmailStr
+    role: str
+    expires_at: Optional[datetime] = None
+    created_at: datetime
+    used_at: Optional[datetime] = None
+
+
+class AdminAccountListItem(BaseModel):
+    id: UUID
+    name: str
+    display_code: str
+    created_at: datetime
+    owner_id: Optional[UUID] = None
+    owner: Optional[AdminAccountOwnerSummary] = None
+    subscription: Optional[AdminAccountSubscriptionSummary] = None
+    usage: AdminAccountUsageSummary = Field(default_factory=AdminAccountUsageSummary)
+    member_count: int = 0
+    active_member_count: int = 0
+    pending_invite_count: int = 0
+    sso_enabled: bool = False
+    branding_company_name: Optional[str] = None
+    members: list[AdminAccountMember] = Field(default_factory=list)
+
+
+class AdminAccountListResponse(BaseModel):
+    items: list[AdminAccountListItem]
+    total: int
+    page: int
+    per_page: int
+
+
+class AdminAccountDetailResponse(AdminAccountListItem):
+    invites: list[AdminAccountInviteSummary] = Field(default_factory=list)
+
+
+class AdminAccountCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    plan: Literal["free", "pro", "team"] = "free"
+    owner_email: Optional[EmailStr] = Field(None, description="Email of an existing user to set as owner")
+
+
+class AdminAccountUpdate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+
+
 # --- Audit Logs ---
 
 class AuditLogEntry(BaseModel):
@@ -215,7 +320,7 @@ class AdminUserCreate(BaseModel):
     name: str = Field(..., min_length=1, max_length=255)
     account_mode: Literal["existing", "personal"]
     account_display_code: Optional[str] = Field(None, description="Required when account_mode='existing'")
-    account_role: Optional[Literal["engineer", "viewer"]] = Field(None, description="Required when account_mode='existing'")
+    account_role: Optional[Literal["owner", "admin", "engineer", "viewer"]] = Field(None, description="Required when account_mode='existing'")
     send_email: bool = True
 
 

backend/app/schemas/device_type.py

@@ -0,0 +1,37 @@
+"""Pydantic schemas for device types."""
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class DeviceTypeCreate(BaseModel):
+    slug: str = Field(min_length=1, max_length=50, pattern=r"^[a-z0-9\-]+$")
+    label: str = Field(min_length=1, max_length=100)
+    category: str = Field(
+        min_length=1, max_length=50,
+        pattern=r"^(network|compute|storage|cloud|endpoint|infrastructure|security)$",
+    )
+    sort_order: int = Field(default=0, ge=0)
+
+
+class DeviceTypeUpdate(BaseModel):
+    label: str | None = Field(default=None, min_length=1, max_length=100)
+    category: str | None = Field(
+        default=None, min_length=1, max_length=50,
+        pattern=r"^(network|compute|storage|cloud|endpoint|infrastructure|security)$",
+    )
+    sort_order: int | None = Field(default=None, ge=0)
+
+
+class DeviceTypeResponse(BaseModel):
+    id: UUID
+    slug: str
+    label: str
+    category: str
+    is_system: bool
+    account_id: UUID
+    sort_order: int
+    created_at: datetime
+
+    model_config = {"from_attributes": True}

backend/app/schemas/draft_template.py

@@ -0,0 +1,68 @@
+"""Pydantic schemas for FlowPilot Phase 6 draft templates.
+
+A draft is the engineer's "Run now, templatize after resolve" path output:
+the script ran for the ticket, and the AI proposed a parameterization.
+Post-resolve, the engineer accepts (promotes to a real template) or rejects.
+
+See FLOWPILOT-MIGRATION.md Section 5.3.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+DraftStatus = Literal["pending", "accepted", "rejected"]
+
+
+class DraftTemplateResponse(BaseModel):
+    id: UUID
+    account_id: UUID
+    source_session_id: UUID
+    source_user_id: UUID
+    script_body: str
+    proposed_parameters: dict[str, Any]
+    proposed_name: str | None
+    proposed_category_id: UUID | None
+    status: DraftStatus
+    resolved_at: datetime | None
+    promoted_template_id: UUID | None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class DraftTemplateListResponse(BaseModel):
+    drafts: list[DraftTemplateResponse]
+
+
+class DraftTemplateAcceptRequest(BaseModel):
+    """Engineer's confirmation that this draft should become a real template.
+
+    Engineer may override the AI's proposed name / category and edit the
+    parameter schema before promotion. Body and parameters_schema are
+    persisted to the new `script_templates` row.
+    """
+    name: str = Field(..., min_length=1, max_length=200)
+    category_id: UUID
+    description: str | None = Field(None, max_length=2000)
+    # Final parameter schema in the Script Generator's standard shape.
+    # See ScriptTemplate.parameters_schema for the contract.
+    parameters_schema: dict[str, Any]
+    # Optional last-minute edits to the script body. Defaults to the draft's
+    # `script_body` (which TemplateExtractionService produced as the templated
+    # form with `{{ key }}` placeholders).
+    edited_body: str | None = Field(None, min_length=1, max_length=50_000)
+
+
+class DraftTemplateAcceptResponse(BaseModel):
+    draft_id: UUID
+    promoted_template_id: UUID
+    template_slug: str
+
+
+class DraftTemplateRejectResponse(BaseModel):
+    draft_id: UUID
+    status: Literal["rejected"]

backend/app/schemas/network_diagram.py

@@ -0,0 +1,145 @@
+"""Pydantic schemas for network diagrams."""
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class Position(BaseModel):
+    x: float
+    y: float
+
+
+class DeviceProperties(BaseModel):
+    hostname: str | None = None
+    ip: str | None = None
+    subnet: str | None = None
+    vendor: str | None = None
+    model: str | None = None
+    role: str | None = None
+    vlan: str | None = None
+    notes: str | None = None
+    status: str = Field(default="unknown", pattern=r"^(unknown|online|offline|degraded)$")
+
+
+class NodeStyle(BaseModel):
+    width: float | None = None
+    height: float | None = None
+
+
+class DiagramNode(BaseModel):
+    id: str
+    type: str
+    label: str
+    position: Position
+    properties: DeviceProperties = Field(default_factory=DeviceProperties)
+    nodeType: str | None = None
+    style: NodeStyle | None = None
+    parentId: str | None = None
+
+
+class DiagramEdge(BaseModel):
+    id: str
+    source: str
+    target: str
+    label: str | None = None
+    connectionType: str = "ethernet"
+    speed: str | None = None
+    notes: str | None = None
+    routing: str | None = None
+
+
+class NetworkDiagramCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=255)
+    client_name: str | None = None
+    asset_name: str | None = None
+    description: str | None = None
+    nodes: list[DiagramNode] = Field(default_factory=list)
+    edges: list[DiagramEdge] = Field(default_factory=list)
+
+
+class NetworkDiagramUpdate(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=255)
+    client_name: str | None = None
+    asset_name: str | None = None
+    description: str | None = None
+    nodes: list[DiagramNode] | None = None
+    edges: list[DiagramEdge] | None = None
+
+
+class NetworkDiagramResponse(BaseModel):
+    id: UUID
+    account_id: UUID
+    name: str
+    client_name: str | None = None
+    asset_name: str | None = None
+    description: str | None = None
+    nodes: list[DiagramNode] = Field(default_factory=list)
+    edges: list[DiagramEdge] = Field(default_factory=list)
+    thumbnail_url: str | None = None
+    is_archived: bool = False
+    created_by: UUID | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class NetworkDiagramListItem(BaseModel):
+    id: UUID
+    name: str
+    client_name: str | None = None
+    description: str | None = None
+    node_count: int = 0
+    category_counts: dict[str, int] = Field(default_factory=dict)
+    thumbnail_url: str | None = None
+    created_by: UUID | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class ExistingBounds(BaseModel):
+    minX: float
+    maxX: float
+    minY: float
+    maxY: float
+
+
+class AIGenerateRequest(BaseModel):
+    description: str = Field(min_length=1, max_length=5000)
+    client_name: str | None = None
+    mode: str = Field(default="replace", pattern=r"^(replace|merge)$")
+    existingBounds: ExistingBounds | None = None
+
+
+class AIGenerateResponse(BaseModel):
+    nodes: list[DiagramNode]
+    edges: list[DiagramEdge]
+    suggestedName: str | None = None
+    notes: str | None = None
+
+
+class DiagramImportRequest(BaseModel):
+    schemaVersion: int = Field(ge=1, le=1)
+    name: str = Field(min_length=1, max_length=255)
+    client_name: str | None = None
+    description: str | None = None
+    nodes: list[DiagramNode] = Field(default_factory=list)
+    edges: list[DiagramEdge] = Field(default_factory=list)
+
+
+class DiagramImportResponse(BaseModel):
+    diagram: NetworkDiagramResponse
+    warnings: list[str] = Field(default_factory=list)
+
+
+class DiagramExportResponse(BaseModel):
+    schemaVersion: int = 1
+    name: str
+    client_name: str | None = None
+    description: str | None = None
+    nodes: list[DiagramNode]
+    edges: list[DiagramEdge]
+    exportedAt: str

backend/app/schemas/psa_connection.py

@@ -111,13 +111,13 @@ class PsaPostLogResponse(BaseModel):
 
 
 class PsaMemberMappingResponse(BaseModel):
-    id: str
+    id: str | None = None  # None for users without a mapping
     user_id: str
     user_email: str
     user_name: str
-    external_member_id: str
-    external_member_name: str
-    matched_by: str
+    external_member_id: str | None = None
+    external_member_name: str | None = None
+    matched_by: str | None = None
 
 
 class PsaMemberMappingSaveRequest(BaseModel):
@@ -136,3 +136,8 @@ class PsaMemberResponse(BaseModel):
 class AutoMatchResult(BaseModel):
     matched: list[PsaMemberMappingResponse]
     unmatched_users: int
+
+
+class PSABoardResponse(BaseModel):
+    id: int
+    name: str

backend/app/schemas/script_builder.py

@@ -1,18 +1,27 @@
 """Pydantic schemas for the AI Script Builder."""
 from datetime import datetime
-from typing import Optional
+from typing import Literal, Optional
 from uuid import UUID
 
 from pydantic import BaseModel, Field
 
 
 class ScriptBuilderCreateRequest(BaseModel):
-    """Request to start a new builder session."""
+    """Request to start (or get-or-create, for inline origin) a builder session.
+
+    When `origin='pilot_inline'`, `ai_session_id` is REQUIRED and must
+    reference a pilot session owned by the current user. The endpoint's
+    get-or-create semantics kick in: if a pilot_inline session already
+    exists for (user_id, ai_session_id), that row is returned instead of
+    creating a duplicate.
+    """
     language: str = Field(
         default="powershell",
         pattern=r"^(powershell|bash|python)$",
         description="Script language",
     )
+    origin: Literal["standalone", "pilot_inline"] = "standalone"
+    ai_session_id: UUID | None = None
 
 
 class ScriptBuilderMessageRequest(BaseModel):

backend/app/schemas/session_fact.py

@@ -0,0 +1,81 @@
+"""Pydantic schemas for the FlowPilot "What we know" session facts.
+
+See FLOWPILOT-MIGRATION.md Section 4.2 for the data model rationale.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+# AI-emittable source types are a subset (`user_note` is engineer-only).
+AIEmittableSourceType = Literal["question", "diagnostic_check", "ai_synthesis"]
+SourceType = Literal["question", "diagnostic_check", "user_note", "ai_synthesis"]
+
+
+class SessionFactResponse(BaseModel):
+    """A single fact card in the What-we-know panel."""
+    id: UUID
+    session_id: UUID
+    text: str
+    source_type: SourceType
+    source_ref: UUID | None
+    source_summary: str | None
+    created_by: UUID
+    created_at: datetime
+    updated_at: datetime
+    # `editable` is computed server-side so the client doesn't have to
+    # re-encode the editability rule. It mirrors the PATCH endpoint's
+    # 403 policy: only user_note and ai_synthesis facts are editable.
+    editable: bool
+
+    model_config = {"from_attributes": False}
+
+
+class SessionFactListResponse(BaseModel):
+    facts: list[SessionFactResponse]
+
+
+class SessionFactCreateRequest(BaseModel):
+    """Engineer-created manual fact (the "+ Add a note" affordance).
+
+    The endpoint hard-codes source_type="user_note" — manual creation cannot
+    spoof a question/check origin. Source-type-bound creation goes through
+    `/promote` instead.
+    """
+    text: str = Field(..., min_length=1, max_length=2000)
+    summary: str | None = Field(None, max_length=200)
+
+
+class SessionFactUpdateRequest(BaseModel):
+    """Edit an existing fact's text or summary.
+
+    The endpoint returns 403 when the fact's source_type is `question` or
+    `diagnostic_check` — those facts must be edited at the source item.
+    """
+    text: str | None = Field(None, min_length=1, max_length=2000)
+    summary: str | None = Field(None, max_length=200)
+
+
+class SessionFactPromoteRequest(BaseModel):
+    """Promote a question answer / check result into a fact.
+
+    Two modes:
+    - **Direct**: caller provides `proposed_text` (and optionally `proposed_summary`).
+      The fact is persisted as-is. Used by the AI [PROMOTE] marker path and by the
+      engineer's "edit then save" affordance.
+    - **Synthesize**: caller provides `raw_input` (the engineer's typed answer or
+      the check output) and the server drafts `text`/`summary` via the
+      FactSynthesisService. The draft is persisted immediately for now —
+      the supervisor-staging review is a future enhancement (out of scope per
+      Section 12).
+
+    Exactly one of `proposed_text` or `raw_input` must be set.
+    """
+    source_type: AIEmittableSourceType
+    source_ref: UUID | None = None
+    proposed_text: str | None = Field(None, min_length=1, max_length=2000)
+    proposed_summary: str | None = Field(None, max_length=200)
+    raw_input: str | None = Field(None, min_length=1, max_length=10_000)

backend/app/schemas/session_suggested_fix.py

@@ -0,0 +1,166 @@
+"""Pydantic schemas for session suggested fixes (Phase 3).
+
+See FLOWPILOT-MIGRATION.md Section 5.2.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+UserDecision = Literal["one_off", "draft_template", "build_template", "dismissed"]
+
+# "dismissed" here is the outcome dimension — orthogonal to UserDecision's
+# "dismissed" (script-path choice), though the migration backfill aligns
+# them for pre-existing rows.
+FixStatus = Literal[
+    "proposed",
+    "applied_success",
+    "applied_failed",
+    "applied_partial",
+    "dismissed",
+]
+
+
+class SessionSuggestedFixResponse(BaseModel):
+    id: UUID
+    session_id: UUID
+    title: str
+    description: str
+    confidence_pct: int
+    script_template_id: UUID | None
+    ai_drafted_script: str | None
+    ai_drafted_parameters: dict[str, Any] | None
+    user_decision: UserDecision | None
+    superseded_at: datetime | None
+    created_at: datetime
+    status: FixStatus
+    applied_at: datetime | None
+    verified_at: datetime | None
+    partial_notes: str | None
+    failure_reason: str | None
+    ai_outcome_proposal: dict[str, Any] | None
+
+    model_config = {"from_attributes": True}
+
+
+class SessionSuggestedFixDecisionRequest(BaseModel):
+    """Engineer's path choice on a suggested fix.
+
+    Server-side side effects per Section 5.2:
+    - one_off: record decision, return the rendered (AI-drafted or
+      engineer-edited) script. No persistent library artifact created.
+    - draft_template: same as one_off, plus TemplateExtractionService
+      proposes a parameterization and a draft_templates row is created.
+    - build_template: return a redirect payload pointing at the Script
+      Builder page, pre-loaded with the drafted script body.
+    - dismissed: mark the fix superseded.
+
+    For one_off / draft_template, the engineer may have edited the drafted
+    script or its parameters in the dialog. The final versions are sent
+    back here so we persist what will actually run.
+    """
+    decision: UserDecision
+    # Present for one_off / draft_template — the engineer's final version of
+    # the drafted script after any inline edits. Omit to use the fix's
+    # `ai_drafted_script` verbatim.
+    edited_script: str | None = Field(None, min_length=1, max_length=50_000)
+    # Parameter values used when rendering (informational, stored on the
+    # draft_template row so a reviewer can see what the first run used).
+    parameters_used: dict[str, Any] | None = None
+
+
+class SessionSuggestedFixDecisionResponse(BaseModel):
+    """Returned after recording a decision."""
+    id: UUID
+    user_decision: UserDecision
+    # Populated for one_off / draft_template — the script to display/run.
+    rendered_script: str | None = None
+    # Populated for draft_template — the ID of the draft_templates row so
+    # the post-resolve TemplatizePrompt can fetch it in Phase 6.
+    draft_template_id: UUID | None = None
+    # Populated for build_template — where to send the engineer next.
+    redirect_path: str | None = Field(
+        None,
+        description="Where to send the engineer next (e.g. /scripts/builder?... for build_template)",
+    )
+
+
+# Subset of FixStatus that the engineer can set via the outcome endpoint —
+# `proposed` is excluded because you can't un-decide a fix back to "proposed".
+FixOutcome = Literal[
+    "applied_success", "applied_failed", "applied_partial", "dismissed"
+]
+
+
+class SessionSuggestedFixOutcomeRequest(BaseModel):
+    """Engineer-reported outcome of applying a suggested fix.
+
+    Writes to session_suggested_fixes.status and companion columns. This is
+    orthogonal to `user_decision` (which records which script-path the
+    engineer took); outcome captures whether the fix actually worked.
+
+    Allowed transitions:
+    - from `proposed` or `applied_partial`: any outcome is valid
+      (partial is parked, not terminal — the engineer may update notes,
+      abandon via dismiss, or advance to success/failed)
+    - from any terminal outcome (`applied_success`, `applied_failed`,
+      `dismissed`): server returns 409
+    """
+    outcome: FixOutcome
+    # Required for applied_partial, optional for applied_failed, ignored otherwise.
+    notes: str | None = Field(None, max_length=500)
+
+
+class SessionSuggestedFixScriptRequest(BaseModel):
+    """Engineer-submitted drafted script for a suggested fix.
+
+    Called when the inline Script Builder tab's Submit action fires. The
+    fix must be non-terminal (still proposed/applied_partial). Setting
+    the script does NOT stamp applied_at — a draft is not an application.
+    """
+    ai_drafted_script: str = Field(..., min_length=1, max_length=50_000)
+    ai_drafted_parameters: dict[str, Any] | None = None
+
+
+# ── Resolution note preview ────────────────────────────────────────────────
+
+class ResolutionNotePreviewResponse(BaseModel):
+    markdown: str
+    target_ticket_ref: str | None
+    state_version: int
+    from_cache: bool
+
+
+# ── Phase 4: Resolve + Escalate post ───────────────────────────────────────
+
+class ResolutionNotePostRequest(BaseModel):
+    """Engineer-edited resolution markdown. Server posts to PSA + marks resolved."""
+    markdown: str = Field(..., min_length=1, max_length=20_000)
+    # Optional override for resolution summary shown on the session listing;
+    # defaults to the first line of the markdown if omitted.
+    resolution_summary: str | None = Field(None, max_length=500)
+
+
+class EscalationPackagePostRequest(BaseModel):
+    markdown: str = Field(..., min_length=1, max_length=20_000)
+    # Free-text reason shown in session listings and escalation queue.
+    escalation_reason: str | None = Field(None, max_length=500)
+
+
+class ResolutionPostResponse(BaseModel):
+    """Response shape for both Resolve/Escalate POST endpoints."""
+    # "resolved" / "escalated" / "resolved_local" / "escalated_local"
+    # The _local variants indicate the session has no linked PSA ticket —
+    # markdown is stored, session state is updated, nothing was posted externally.
+    outcome: str
+    session_status: str
+    external_id: str | None = None
+    posted_at: datetime | None = None
+    # Populated when a status transition was attempted and verified. None
+    # when no target status is configured in account_settings.preferences.
+    verified_status_id: int | None = None
+    verified_status_name: str | None = None
+    status_transition_skipped_reason: str | None = None

backend/app/schemas/user.py

@@ -68,4 +68,4 @@ class RoleUpdate(BaseModel):
 
 
 class AccountRoleUpdate(BaseModel):
-    account_role: str = Field(..., pattern="^(engineer|viewer)$")
+    account_role: str = Field(..., pattern="^(owner|admin|engineer|viewer)$")

backend/app/services/assistant_chat_service.py

@@ -10,10 +10,32 @@ Uses Anthropic prompt caching to reduce cost on multi-turn conversations:
 
 Optionally connects to Microsoft Learn via Anthropic's MCP connector
 for real-time documentation lookups (controlled by ENABLE_MCP_MICROSOFT_LEARN).
+
+## Architectural note — this module is the one MCP/beta chat caller
+
+`chat_call_cached` below is the ONLY caller in the codebase that uses
+Anthropic's `client.beta.messages.create` endpoint, MCP servers, multimodal
+user messages, and the retry-without-MCP fallback. It is deliberately NOT
+routed through `AnthropicProvider` — MCP/beta/images are features of exactly
+one optional Anthropic beta endpoint and do not belong in a provider-agnostic
+abstraction that also serves Gemini.
+
+If a new caller needs the same (MCP, beta, images, history caching) bundle,
+call `chat_call_cached` directly rather than pushing those concerns into
+`AnthropicProvider`. Cached-system-block plumbing is shared with the provider
+via `_normalize_system_for_anthropic` / `build_anthropic_chat_messages` /
+`_log_anthropic_cache_usage` in `app.core.ai_provider` — cache primitives are
+reusable, but the MCP/beta orchestration stays here.
 """
 import logging
 from typing import Any
 
+from app.core.ai_provider import (
+    _get_anthropic_client,
+    _log_anthropic_cache_usage,
+    _normalize_system_for_anthropic,
+    build_anthropic_chat_messages,
+)
 from app.core.config import settings
 
 logger = logging.getLogger(__name__)
@@ -40,29 +62,31 @@ Every response you write MUST follow this exact structure:
 1. **1-3 sentences of analysis** (what the symptoms tell you)
 2. **[QUESTIONS] marker** with 1-3 questions for the engineer (if you need info)
 3. **[ACTIONS] marker** with 1-4 diagnostic commands to run (if applicable)
+4. **[PROMOTE] marker(s)** when the engineer's most recent message confirmed a fact \
+worth recording (optional; see "Promoting facts" below)
 
 You MUST include at least one marker ([QUESTIONS] or [ACTIONS]) in every response. \
-A response with only prose and no markers is INVALID and will break the UI.
+A response with only prose and no markers is INVALID and will break the UI. \
+[PROMOTE] is optional and IN ADDITION to the required markers, never a replacement.
 
-### Complete example of a correct first response:
+### Format-only schema (DO NOT reuse the literal text below)
 
-User: "Outlook disconnects every 10-15 min, Teams drops too, only this one user, WiFi"
+The structure to follow is shown below using PLACEHOLDERS. The placeholders \
+are not real questions or commands — they describe the SHAPE of valid output. \
+Your real response must contain analysis and markers tailored to the actual \
+ticket the engineer just sent. Reusing any placeholder text (or text from a \
+prior unrelated example you've seen) verbatim is a bug.
 
-Your response:
-
-Both apps dropping on the same 10-15 min cycle on WiFi points to a network-layer \
-timeout — likely DHCP lease renewal, AP roaming, or NIC power management. Single-user \
-scope narrows it to this endpoint.
+Analysis prose: 1-3 sentences specific to the engineer's symptoms.
 
 [QUESTIONS]
-[{"text": "Is this user on a laptop or desktop?", "context": "Laptops have power management and docking transitions that cause WiFi drops"},
-{"text": "Are they on corporate WiFi or working from home?", "context": "Corporate WiFi with multiple APs can cause roaming disconnects"}]
+[{"text": "<one short, specific question about THIS ticket>", "context": "<one-sentence justification, optional>"},
+{"text": "<another specific question>", "context": "<...>"}]
 [/QUESTIONS]
 
 [ACTIONS]
-[{"label": "Check DHCP lease time", "command": "ipconfig /all | Select-String -Pattern 'DHCP|IPv4|Lease|Gateway'", "description": "Short lease times (under 1 hour) cause brief drops at renewal"},
-{"label": "Check NIC power management", "command": "Get-NetAdapterPowerManagement | Select Name, AllowComputerToTurnOffDevice", "description": "If True, Windows is likely killing the adapter during idle periods"},
-{"label": "Check WiFi signal and AP", "command": "netsh wlan show interfaces", "description": "Shows current BSSID, signal strength, and whether they are bouncing between APs"}]
+[{"label": "<short imperative label for THIS ticket>", "command": "<exact PowerShell or shell command, omit for GUI-only steps>", "description": "<one sentence explaining what the output reveals>"},
+{"label": "<...>", "command": "<...>", "description": "<...>"}]
 [/ACTIONS]
 
 ### Rules
@@ -90,6 +114,128 @@ information is no longer needed to resolve the issue. Default to keeping them.
 **Both markers are stripped from display** — the engineer sees them as interactive UI cards, \
 not raw JSON. Put analysis BEFORE markers. Markers go at the END of your response.
 
+## Promoting facts to "What we know"
+
+The engineer has a "What we know" panel that holds confirmed facts about this \
+session. Each confirmed fact stays visible to the engineer for the rest of the \
+session and feeds the resolution note posted to the customer ticket. Surface \
+facts there using a `[PROMOTE]` marker.
+
+**When to emit [PROMOTE]:**
+- The engineer just answered a [QUESTIONS] item with a substantive answer that \
+rules something in or out
+- The engineer just shared diagnostic-check output that confirmed a finding
+- You synthesized a new conclusion from two or more prior facts
+
+**When NOT to emit [PROMOTE]:**
+- The engineer's answer was "unknown", "I don't know", or a clarifying question \
+back to you
+- The diagnostic output was empty, errored, or inconclusive
+- You're re-stating something already in What we know
+- The "fact" is your own hypothesis, not something the engineer confirmed
+
+**[PROMOTE] marker format:**
+Each fact is its own block. You may emit multiple blocks per response.
+
+[PROMOTE]
+{"source_type": "question", "source_ref": "<task_lane_item_id>", "text": "<one short past-tense sentence stating what is now confirmed FROM THIS TICKET>", "summary": "<3-7 word provenance label specific to what the fact rules in/out>"}
+[/PROMOTE]
+
+- `source_type` is one of: `"question"` (fact derived from a question's answer), \
+`"diagnostic_check"` (fact derived from a check's output), or `"ai_synthesis"` \
+(you combined prior facts).
+- `source_ref` is the `id` field of the originating task-lane item — the \
+[QUESTIONS] and [ACTIONS] payloads you receive in conversation context include \
+an `id` for each item. Copy that UUID verbatim. For `ai_synthesis`, OMIT \
+`source_ref` (or set it to null).
+- `text` is a short past-tense sentence stating what's now confirmed. Use ONLY \
+information present in the engineer's CURRENT message — never invent specifics, \
+never reuse phrasing from past tickets or example payloads.
+- `summary` names the diagnostic value (what the fact rules in or out), 3-7 \
+words, no period.
+
+**Strict rule:** [PROMOTE] is for confirmed facts only. If you're not certain \
+the engineer's message confirms the fact, do not emit a [PROMOTE]. Hallucinated \
+facts get posted to customer tickets and will erode trust in the system.
+
+## Proposing a fix with [SUGGEST_FIX]
+
+When you have a concrete proposed resolution path with reasonable confidence, \
+emit a `[SUGGEST_FIX]` marker. This populates the "Suggested fix" card the \
+engineer can act on (run a script, build a template, etc.). A new \
+[SUGGEST_FIX] supersedes any prior suggested fix on the session — emit a fresh \
+one whenever your top hypothesis changes meaningfully.
+
+**When to emit [SUGGEST_FIX]:**
+- You have a concrete resolution path (not just "investigate further")
+- Confidence is at least ~50% — below that, keep diagnosing
+- Either a known Script Library template applies, OR you can draft a script \
+that resolves the issue end-to-end
+
+**When NOT to emit [SUGGEST_FIX]:**
+- You're still narrowing causes and the fix depends on the next answer
+- The "fix" is just running another diagnostic — that goes in [ACTIONS]
+- Two paths are equally likely — fork or ask first, suggest later
+
+**[SUGGEST_FIX] marker format (one block per response, last one wins).**
+Schema below — DO NOT copy these placeholders into your real response, fill \
+each field with content specific to the actual ticket:
+
+[SUGGEST_FIX]
+{"title": "<short imperative summary of the fix, ≤200 chars>", "description": "<one short paragraph: root cause + how the fix resolves it>", "confidence": <integer 0-100>, "script_template_slug": "<slug-of-existing-template-or-omit>"}
+[/SUGGEST_FIX]
+
+- `title`: short imperative summary, ≤ 200 chars
+- `description`: one short paragraph explaining the root cause and the fix
+- `confidence`: integer 0-100 (what you'd bet this resolves the ticket)
+- `script_template_slug`: slug of an existing Script Library template if one \
+applies; OMIT or set null otherwise
+- `ai_drafted_script`: full script body if no template matches (only when \
+`script_template_slug` is null/omitted)
+- `ai_drafted_parameters`: optional JSON object of suggested parameter values \
+for the drafted script
+
+The marker is stripped from display — the engineer sees the suggested fix as \
+an interactive card with confidence badge, not raw JSON.
+
+## Reporting fix outcome with [FIX_OUTCOME]
+
+When the engineer clearly indicates in chat that a previously proposed fix
+worked, didn't work, or was partially applied, emit a [FIX_OUTCOME] marker
+on its own lines. This surfaces a "confirm outcome?" banner in the UI — it
+does NOT mark the fix resolved on its own; the engineer confirms via the UI.
+
+**When to emit [FIX_OUTCOME]:**
+- The engineer states the user's problem is resolved after applying the fix
+  (affirmative resolution language → outcome="success")
+- The engineer states the issue persists after applying the fix
+  (→ outcome="failure")
+- The engineer describes applying only part of the fix
+  (→ outcome="partial")
+
+**When NOT to emit [FIX_OUTCOME]:**
+- The engineer is still verifying (user rebooting, testing, etc.)
+- The outcome is ambiguous or inferred rather than stated
+- No [SUGGEST_FIX] has been emitted this session
+
+**[FIX_OUTCOME] marker format (one block per response, on its own lines).**
+Schema below — DO NOT copy these placeholders into your real response, fill \
+each field with content specific to the actual ticket:
+
+[FIX_OUTCOME]
+{"fix_id": "<uuid-of-the-active-suggested-fix>",
+ "outcome": "<success|failure|partial>",
+ "reason": "<one-line-quote-or-paraphrase-of-what-the-engineer-said>"}
+[/FIX_OUTCOME]
+
+- `fix_id`: the UUID of the active suggested fix (provided in session context)
+- `outcome`: one of `"success"`, `"failure"`, or `"partial"`
+- `reason`: one-line paraphrase of what the engineer said — derived from \
+their CURRENT message, not invented
+
+The marker is stripped from display — the engineer sees a "confirm outcome?" \
+banner in the UI, not raw JSON.
+
 ## Using the Team's Flow Library
 Your team has built troubleshooting flows in ResolutionFlow. When relevant flows \
 appear in the context below, reference them by name so the engineer can launch them \
@@ -117,7 +263,7 @@ forking, branching, or paths to the engineer. You just continue the conversation
 The fork marker is metadata that the system uses behind the scenes.
 
 **You MUST fork when:**
-- Symptoms affect multiple applications or layers (e.g., Outlook AND Teams dropping)
+- Symptoms affect multiple applications or layers simultaneously
 - The problem could be endpoint-side OR infrastructure-side
 - Multiple well-known causes match the exact same symptom pattern
 
@@ -132,11 +278,6 @@ to those, not a replacement. Do NOT ask questions in prose — put them in [QUES
 
 Structure: 1-3 sentences of analysis → [QUESTIONS] and/or [ACTIONS] → [FORK] at the very end.
 
-Example flow:
-- Engineer: "Outlook disconnects every 15 min, Teams drops too, only one user"
-- You: "The 10-15 min pattern with both apps points to network layer."
-- Then: [QUESTIONS] marker, then [ACTIONS] marker, then [FORK] marker last.
-
 The fork marker is stripped from display — the engineer never sees it. \
 The system creates branches silently. Based on the engineer's answer, you pick \
 the most relevant branch to investigate first.
@@ -144,7 +285,7 @@ the most relevant branch to investigate first.
 To create a fork, append this marker AFTER your [QUESTIONS]/[ACTIONS] markers:
 
 [FORK]
-{"fork_reason": "Brief reason", "options": [{"label": "Short name", "description": "One sentence"}, {"label": "Another", "description": "One sentence"}]}
+{"fork_reason": "<one short sentence: why these branches need independent investigation>", "options": [{"label": "<short hypothesis name for branch 1>", "description": "<one sentence: what this branch will check>"}, {"label": "<branch 2 name>", "description": "<...>"}]}
 [/FORK]
 
 2-4 options. Never mention "fork", "branch", or "path" in your visible text.
@@ -160,6 +301,25 @@ No exceptions. Not even when forking. A response without at least one of these m
 will crash the UI. If you are unsure, include both. The markers are REQUIRED output, not optional.
 If any tasks in the engineer's message are marked `_(not yet completed)_`, re-include them \
 in your markers unless you are ≥75% confident that information is no longer relevant.
+[PROMOTE] markers are OPTIONAL and IN ADDITION to the required ones — emit them only \
+when the engineer's most recent message confirmed something worth recording, and copy \
+the originating item's `id` into `source_ref` verbatim.
+[SUGGEST_FIX] is OPTIONAL — emit one at most per response, only when you have a \
+concrete proposed resolution at ~50%+ confidence. A new [SUGGEST_FIX] supersedes \
+any prior suggested fix.
+[FIX_OUTCOME] is OPTIONAL — emit one at most per response, only when the engineer \
+has clearly stated the outcome in their current message.
+
+ANTI-PARROT RULE: The schemas above use placeholders in `<angle brackets>` to show \
+the SHAPE of valid output. Your real questions, actions, facts, and suggested fixes \
+must be derived from the engineer's CURRENT message — never copy placeholder text, \
+never reuse content from a prior unrelated session, never invent ticket-specific \
+details (usernames, hostnames, IPs, error codes, application names, ticket numbers) \
+that the engineer has not stated. The technology, vocabulary, and named entities in \
+your output must match the technology, vocabulary, and named entities in the \
+engineer's most recent message. If the engineer's ticket is about a different \
+domain than the last ticket you saw, your output must reflect the new domain — \
+do not let the previous ticket's specifics bleed into the new one.
 """
 
 
@@ -184,7 +344,7 @@ async def _call_ai(
                 to include alongside the new_message as vision content.
     """
     if settings.AI_PROVIDER == "anthropic" and settings.ANTHROPIC_API_KEY:
-        return await _call_anthropic_cached(
+        return await chat_call_cached(
             system_base, rag_context, history, new_message, max_tokens,
             images=images,
         )
@@ -202,7 +362,18 @@ async def _call_ai(
     )
 
 
-async def _call_anthropic_cached(
+# Appended to every chat turn's user message immediately before generation.
+# Invisible to storage (unified_chat_service strips markers before persisting),
+# but critical for structured output compliance — the model emits invalid
+# responses often enough without it that removing this reminder regresses UX.
+_CHAT_FORMAT_REMINDER = (
+    "\n\n[SYSTEM: Remember — your response MUST end with [QUESTIONS] "
+    "and/or [ACTIONS] markers containing valid JSON arrays. "
+    "Responses without markers break the UI.]"
+)
+
+
+async def chat_call_cached(
     system_base: str,
     rag_context: str,
     history: list[dict[str, Any]],
@@ -210,79 +381,56 @@ async def _call_anthropic_cached(
     max_tokens: int,
     images: list[dict[str, Any]] | None = None,
 ) -> tuple[str, int, int]:
-    """Call Anthropic with prompt caching on system prompt and history.
+    """Call Anthropic's chat surface with caching, MCP, images, and retry-without-MCP.
 
-    Uses structured system blocks so the static base prompt is cached
-    independently from the per-query RAG context. Optionally connects
-    to Microsoft Learn via MCP for real-time documentation lookups.
+    This is the ONE MCP/beta/multimodal chat caller. It is deliberately NOT
+    routed through `AnthropicProvider`. See module docstring for rationale.
+
+    Responsibilities unique to this function (not in the provider):
+    - Anthropic beta endpoint (`client.beta.messages.create`)
+    - Microsoft Learn MCP connector wiring (optional via ENABLE_MCP_MICROSOFT_LEARN)
+    - Retry-without-MCP fallback when the MCP server misbehaves
+    - Multimodal image blocks in the user message
+    - Format-reminder append for structured-output compliance
+    - Telemetry (`mcp.turn`, `mcp.fallback`) for Phase 0.5 MCP usage signal
+
+    Cache plumbing is shared with the provider via helpers in `ai_provider`:
+    `_normalize_system_for_anthropic` (policy α — ephemeral on first block if
+    none specified), `build_anthropic_chat_messages` (history cache breakpoint +
+    multimodal user message + format reminder), `_log_anthropic_cache_usage`.
     """
     import anthropic
 
-    client = anthropic.AsyncAnthropic(
-        api_key=settings.ANTHROPIC_API_KEY,
+    client = _get_anthropic_client(
+        settings.ANTHROPIC_API_KEY,
         timeout=settings.AI_REQUEST_TIMEOUT_SECONDS,
     )
 
-    # System prompt as structured blocks:
-    # Block 1: static base prompt (cached)
-    # Block 2: RAG context (changes per query, not cached)
+    # System prompt as structured blocks. The static base is cacheable; the
+    # RAG context changes per query and must NOT be cached — so we mark the
+    # base explicitly and leave the RAG block unmarked. `_normalize_system`
+    # honors caller-authored cache_control verbatim (policy α).
     system_blocks: list[dict[str, Any]] = [
         {
             "type": "text",
             "text": system_base,
             "cache_control": {"type": "ephemeral"},
+            # cacheable: static system prompt, stable across all turns of all sessions
         },
     ]
     if rag_context:
-        system_blocks.append({"type": "text", "text": rag_context})
+        system_blocks.append(
+            {"type": "text", "text": rag_context}
+            # uncached: RAG retrieval varies per query
+        )
+    normalized_system = _normalize_system_for_anthropic(system_blocks)
 
-    # Build messages with cache breakpoint on conversation history
-    messages: list[dict[str, Any]] = []
-    for msg in history:
-        messages.append({"role": msg["role"], "content": msg["content"]})
-
-    # Place cache breakpoint on the last history message so the entire
-    # conversation prefix is cached across turns
-    if messages:
-        last = messages[-1]
-        messages[-1] = {
-            "role": last["role"],
-            "content": [
-                {
-                    "type": "text",
-                    "text": last["content"],
-                    "cache_control": {"type": "ephemeral"},
-                }
-            ],
-        }
-
-    # Add the new user message (uncached — it's new each turn)
-    # Append a format reminder to the user message so the model sees it
-    # immediately before generating. This is invisible to the user (stripped
-    # before storage) but critical for structured output compliance.
-    format_reminder = (
-        "\n\n[SYSTEM: Remember — your response MUST end with [QUESTIONS] "
-        "and/or [ACTIONS] markers containing valid JSON arrays. "
-        "Responses without markers break the UI.]"
+    messages = build_anthropic_chat_messages(
+        history=history,
+        new_message=new_message,
+        images=images,
+        format_reminder=_CHAT_FORMAT_REMINDER,
     )
-    reminded_message = new_message + format_reminder
-
-    # If images are attached, build multimodal content blocks
-    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": reminded_message})
-        messages.append({"role": "user", "content": content_blocks})
-    else:
-        messages.append({"role": "user", "content": reminded_message})
 
     # MCP server config (optional — controlled by settings)
     mcp_servers = anthropic.NOT_GIVEN
@@ -304,12 +452,13 @@ async def _call_anthropic_cached(
         ]
 
     _mcp_active = mcp_servers is not anthropic.NOT_GIVEN
+    _mcp_fallback_triggered = False
 
     try:
         response = await client.beta.messages.create(
             model=settings.AI_MODEL_ANTHROPIC,
             max_tokens=max_tokens,
-            system=system_blocks,
+            system=normalized_system,
             messages=messages,
             mcp_servers=mcp_servers,
             tools=tools,
@@ -326,14 +475,24 @@ async def _call_anthropic_cached(
             or isinstance(e, (anthropic.BadRequestError, anthropic.APIStatusError))
         )
         if _is_mcp_error:
+            _mcp_fallback_triggered = True
             logger.warning(
                 "MCP server error (%s), retrying without MCP: %s",
                 type(e).__name__, e,
             )
+            # Phase 0.5 telemetry: per-turn fallback event.
+            logger.info(
+                "mcp.fallback",
+                extra={
+                    "event": "mcp.fallback",
+                    "mcp_error_type": type(e).__name__,
+                    "mcp_error_message": str(e)[:500],
+                },
+            )
             response = await client.messages.create(
                 model=settings.AI_MODEL_ANTHROPIC,
                 max_tokens=max_tokens,
-                system=system_blocks,
+                system=normalized_system,
                 messages=messages,
             )
         else:
@@ -355,18 +514,27 @@ async def _call_anthropic_cached(
     input_tokens = usage.input_tokens
     output_tokens = usage.output_tokens
 
-    # Log MCP tool usage
+    # Phase 0.5 telemetry: per-turn MCP event. Emitted for every turn that
+    # reached this code path (i.e., AI_PROVIDER=anthropic chat). `mcp_available`
+    # reflects whether MCP was actually wired into the request (scope (ii) from
+    # the Phase 0.5 design — Anthropic code path AND flag on). `mcp_invoked`
+    # reflects whether the model chose to call an MCP tool on this turn.
+    logger.info(
+        "mcp.turn",
+        extra={
+            "event": "mcp.turn",
+            "mcp_available": _mcp_active,
+            "mcp_invoked": bool(mcp_tools_used),
+            "mcp_tools": mcp_tools_used,
+            "mcp_fallback_triggered": _mcp_fallback_triggered,
+        },
+    )
+
+    # Human-readable log retained for grep-based inspection.
     if mcp_tools_used:
         logger.info("MCP tools used: %s", ", ".join(mcp_tools_used))
 
-    # Log cache performance
-    cache_read = getattr(usage, "cache_read_input_tokens", 0) or 0
-    cache_creation = getattr(usage, "cache_creation_input_tokens", 0) or 0
-    if cache_read or cache_creation:
-        logger.info(
-            "Anthropic cache: read=%d creation=%d input=%d output=%d",
-            cache_read, cache_creation, input_tokens, output_tokens,
-        )
+    _log_anthropic_cache_usage(usage, settings.AI_MODEL_ANTHROPIC)
 
     return text, input_tokens, output_tokens
 

backend/app/services/escalation_package_generator.py

@@ -0,0 +1,309 @@
+"""EscalationPackageGeneratorService — drafts the handoff package for a session.
+
+Parallel to ResolutionNoteGeneratorService but oriented around handoff to
+another engineer instead of closing the ticket. The output markdown follows
+FLOWPILOT-MIGRATION.md Section 6.3:
+
+    ## Problem
+    ## What we've confirmed
+    ## What we've tried
+    ## Current hypothesis
+    ## Suggested next steps
+
+Same caching story as resolution-note previews: keyed on
+`(session_id, ai_sessions.state_version)` via `preview_cache`, invalidated by
+any fact / suggested-fix / script-generation write.
+
+Model: Sonnet (`escalation_package` action tier per Section 6.6). MCP off.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.ai_provider import get_ai_provider
+from app.core.config import settings
+from app.models.ai_session import AISession
+from app.models.script_template import ScriptGeneration, ScriptTemplate
+from app.models.session_fact import SessionFact
+from app.models.session_suggested_fix import SessionSuggestedFix
+from app.services.preview_cache import preview_cache
+from app.services.script_template_engine import ScriptTemplateEngine
+
+logger = logging.getLogger(__name__)
+
+
+_ESCALATION_SYSTEM_PROMPT = """\
+You produce structured escalation handoff packages for an MSP troubleshooting \
+platform. The package is read by the next engineer picking up the ticket; it \
+must give them a running start without making them re-read the chat transcript.
+
+Output exactly this markdown structure, no preamble, no closing remarks, no \
+extra headings:
+
+## Problem
+<one short paragraph stating the issue the first engineer was working on, \
+past tense, no hedging. Derived from the session's intake/title and incident \
+header.>
+
+## What we've confirmed
+<bulleted list of facts from the "What we know" section, each a short line. \
+If there are no facts, write "Nothing confirmed yet." and continue.>
+
+## What we've tried
+<Bulleted list of diagnostic checks run and scripts generated during the \
+session. The content of this section also depends on the outcome recorded for \
+the active suggested fix, as given in the input bundle under "Outcome status":>
+
+- applied_failed: List the fix as a tried path. Include the failure reason if \
+provided. State that it did not resolve the issue.
+- applied_partial: Include the fix as a partially tried path. Include partial \
+notes if provided. Indicate it was not fully completed or not verified.
+- applied_success: Note that the fix was applied and verified but escalation \
+is still needed for another reason (unusual — reflect this accurately).
+- dismissed: Do not mention the fix as a tried path; it was only considered.
+- proposed (no outcome yet): Do not list it here; it goes in Current hypothesis.
+
+If nothing has been tried at all (no checks, no scripts, no applied/partial \
+fix), write "No diagnostic actions run yet." and continue.
+
+## Current hypothesis
+<The content depends on the outcome recorded for the active suggested fix:>
+
+- proposed (no outcome yet): State the fix title and confidence. If confidence \
+is below 60% or there is no active fix, say "No leading hypothesis yet — \
+symptoms are still being narrowed."
+- applied_failed or dismissed: Say the proposed fix did not hold or was set \
+aside. State any remaining uncertainty.
+- applied_partial: Note the partial application and what remains open.
+- applied_success: Unusual in an escalate path — state the fix resolved the \
+original symptom but a new or related issue requires escalation.
+
+## Suggested next steps
+<bulleted list of 2-4 concrete next actions the receiving engineer should \
+take. Prefer specifics: commands to run, tickets to check, people to contact. \
+Derive from the gap between confirmed facts and a complete resolution. \
+If the active suggested fix failed (applied_failed), inform the next steps \
+accordingly — e.g. suggest alternatives or deeper investigation paths, \
+drawing on the failure reason if provided. \
+If the fix is partially applied (applied_partial), the first step is typically \
+to complete or verify it. \
+If the fix is still proposed (no outcome), the first step is to try it if \
+confidence is high (>80%).>
+
+Strict rules:
+- Use ONLY the input I provide. Never invent command names, KB articles, or \
+configuration specifics that aren't in the input.
+- Do not include placeholder text like "TBD" or empty bullets.
+- Do not include the engineer's name, the AI's name, session IDs, or the \
+chat transcript verbatim.
+- Markdown headings exactly as shown (## level), no bolding.
+- The tone is a peer handing off to a peer, not a status report.
+"""
+
+
+class EscalationPackageGeneratorService:
+    """Generates and caches the five-section Escalate handoff markdown."""
+
+    KIND = "escalation_package"
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def generate_or_get_cached(
+        self, session_id: UUID, *, force: bool = False,
+    ) -> dict[str, Any]:
+        session = await self._load_session(session_id)
+        cached = preview_cache.get(self.KIND, session.id, session.state_version) if not force else None
+        if cached is not None:
+            return {**cached, "from_cache": True}
+
+        markdown = await self._render(session)
+        target = self._target_ticket_ref(session)
+        payload = {
+            "markdown": markdown,
+            "target_ticket_ref": target,
+            "state_version": session.state_version,
+        }
+        preview_cache.set(self.KIND, session.id, session.state_version, payload)
+        return {**payload, "from_cache": False}
+
+    # ── Internals (parallel to ResolutionNoteGenerator) ───────────────────
+
+    async def _load_session(self, session_id: UUID) -> AISession:
+        result = await self.db.execute(
+            select(AISession).where(AISession.id == session_id)
+        )
+        session = result.scalar_one_or_none()
+        if session is None:
+            raise ValueError(f"Session {session_id} not found")
+        return session
+
+    async def _render(self, session: AISession) -> str:
+        facts = await self._load_facts(session.id)
+        active_fix = await self._load_active_fix(session.id)
+        gens = await self._load_redacted_generations(session.id)
+
+        bundle = self._build_input_bundle(session, facts, active_fix, gens)
+
+        model = settings.get_model_for_action("escalation_package")
+        provider = get_ai_provider(model=model)
+
+        system_blocks: list[dict[str, Any]] = [
+            {
+                "type": "text",
+                "text": _ESCALATION_SYSTEM_PROMPT,
+                "cache_control": {"type": "ephemeral"},
+                # cacheable: identical across every escalation-package preview call
+            },
+        ]
+
+        try:
+            text, _in, _out = await provider.generate_text(
+                system_prompt=system_blocks,
+                messages=[{"role": "user", "content": bundle}],
+                max_tokens=1400,
+            )
+        except Exception:
+            logger.exception("Escalation package generation failed for session %s", session.id)
+            raise
+        return text.strip()
+
+    async def _load_facts(self, session_id: UUID) -> list[SessionFact]:
+        result = await self.db.execute(
+            select(SessionFact)
+            .where(
+                SessionFact.session_id == session_id,
+                SessionFact.deleted_at.is_(None),
+            )
+            .order_by(SessionFact.created_at.asc())
+        )
+        return list(result.scalars().all())
+
+    async def _load_active_fix(self, session_id: UUID) -> SessionSuggestedFix | None:
+        result = await self.db.execute(
+            select(SessionSuggestedFix)
+            .where(
+                SessionSuggestedFix.session_id == session_id,
+                SessionSuggestedFix.superseded_at.is_(None),
+            )
+            .order_by(SessionSuggestedFix.created_at.desc())
+        )
+        return result.scalars().first()
+
+    async def _load_redacted_generations(
+        self, session_id: UUID
+    ) -> list[dict[str, Any]]:
+        result = await self.db.execute(
+            select(ScriptGeneration)
+            .where(ScriptGeneration.ai_session_id == session_id)
+            .order_by(ScriptGeneration.created_at.asc())
+        )
+        gens = list(result.scalars().all())
+        if not gens:
+            return []
+
+        template_ids = {g.template_id for g in gens}
+        tpl_result = await self.db.execute(
+            select(ScriptTemplate).where(ScriptTemplate.id.in_(template_ids))
+        )
+        templates_by_id = {t.id: t for t in tpl_result.scalars().all()}
+
+        engine = ScriptTemplateEngine()
+        out: list[dict[str, Any]] = []
+        for g in gens:
+            tpl = templates_by_id.get(g.template_id)
+            sensitive_keys: set[str] = set()
+            schema = (tpl.parameters_schema if tpl else {}) or {}
+            params = schema.get("parameters") if isinstance(schema, dict) else None
+            if isinstance(params, list):
+                for p in params:
+                    if isinstance(p, dict) and p.get("field_type") == "password":
+                        k = p.get("key") or p.get("variable_name")
+                        if isinstance(k, str):
+                            sensitive_keys.add(k)
+            redacted_params = engine.redact_sensitive(g.parameters_used or {}, sensitive_keys)
+            out.append({
+                "template_name": tpl.name if tpl else "(unknown template)",
+                "template_slug": tpl.slug if tpl else None,
+                "parameters_used": redacted_params,
+                "created_at": g.created_at.isoformat(),
+            })
+        return out
+
+    @staticmethod
+    def _target_ticket_ref(session: AISession) -> str | None:
+        if not session.psa_ticket_id:
+            return None
+        return f"CW #{session.psa_ticket_id}"
+
+    @staticmethod
+    def _build_input_bundle(
+        session: AISession,
+        facts: list[SessionFact],
+        active_fix: SessionSuggestedFix | None,
+        generations: list[dict[str, Any]],
+    ) -> str:
+        lines: list[str] = []
+        lines.append("# Session context")
+        lines.append(f"Title: {session.title or '(untitled)'}")
+        if session.problem_summary:
+            lines.append(f"Problem summary: {session.problem_summary}")
+        if session.problem_domain:
+            lines.append(f"Domain: {session.problem_domain}")
+        intake_text = (session.intake_content or {}).get("text") if isinstance(session.intake_content, dict) else None
+        if intake_text:
+            lines.append(f"Intake message: {intake_text}")
+        if session.psa_ticket_id:
+            lines.append(f"Linked PSA ticket: CW #{session.psa_ticket_id}")
+
+        lines.append("")
+        lines.append("# Confirmed facts (What we know)")
+        if not facts:
+            lines.append("(none)")
+        else:
+            for f in facts:
+                tag = f.source_type
+                summary = f" — {f.source_summary}" if f.source_summary else ""
+                lines.append(f"- [{tag}] {f.text}{summary}")
+
+        lines.append("")
+        lines.append("# Diagnostic checks run during the session")
+        check_facts = [f for f in facts if f.source_type == "diagnostic_check"]
+        if not check_facts and not generations:
+            lines.append("(none)")
+        else:
+            for f in check_facts:
+                lines.append(f"- {f.text}")
+            for g in generations:
+                lines.append(f"- Ran script {g['template_name']} (slug={g['template_slug']})")
+                if g["parameters_used"]:
+                    lines.append(f"  parameters: {g['parameters_used']}")
+
+        lines.append("")
+        lines.append("# Active suggested fix (current hypothesis)")
+        if active_fix is None:
+            lines.append("(no active suggested fix)")
+        else:
+            lines.append(f"Title: {active_fix.title}")
+            lines.append(f"Confidence: {active_fix.confidence_pct}%")
+            lines.append(f"Description: {active_fix.description}")
+            lines.append(f"Outcome status: {active_fix.status}")
+            if active_fix.applied_at:
+                lines.append(f"Applied at: {active_fix.applied_at.isoformat()}")
+            if active_fix.verified_at:
+                lines.append(f"Verified at: {active_fix.verified_at.isoformat()}")
+            if active_fix.partial_notes:
+                lines.append(f"Partial notes: {active_fix.partial_notes}")
+            if active_fix.failure_reason:
+                lines.append(f"Failure reason: {active_fix.failure_reason}")
+
+        lines.append("")
+        lines.append(
+            "Produce the five-section escalation handoff now. Use only the input above."
+        )
+        return "\n".join(lines)

backend/app/services/fact_synthesis_service.py

@@ -0,0 +1,285 @@
+"""FactSynthesisService — converts engineer answers and check output into facts.
+
+Two paths feed this service:
+
+1. **AI marker path (the common case).** When the model emits a `[PROMOTE]`
+   marker in the chat stream, `unified_chat_service` parses the marker (which
+   already contains the engineer-readable `text` and short provenance `summary`)
+   and calls `create_fact` directly. No LLM call is needed — the model already
+   wrote the fact.
+
+2. **Engineer-driven synthesize path.** The "+ Promote to What we know" affordance
+   in the UI sends a raw answer or check output and asks the server to draft
+   `text` + `summary` for review. `synthesize_from_question` /
+   `synthesize_from_check` make a small Haiku call for that draft. The engineer
+   confirms (or edits) before persistence, so the LLM output is never
+   silently posted to a customer ticket.
+
+Either way, persistence funnels through `create_fact`, which ALSO bumps
+`ai_sessions.state_version` so the resolution-note preview cache invalidates
+(see FLOWPILOT-MIGRATION.md Section 5.5).
+
+Model tier is `fact_synthesis` in `settings.ACTION_MODEL_MAP` (Haiku per
+Section 6.6). MCP is intentionally disabled for synthesis — these are
+pure transformations of input, not research calls.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.ai_provider import get_ai_provider
+from app.core.config import settings
+from app.models.ai_session import AISession
+from app.models.session_fact import SessionFact
+
+logger = logging.getLogger(__name__)
+
+
+# Conservative synthesis prompt. Hallucinated specifics are a trust-killer
+# because facts feed the resolution note posted to customer tickets — the
+# prompt makes "no fact" an explicit, valid output.
+_SYNTHESIS_SYSTEM_PROMPT = """\
+You convert one engineer answer or one diagnostic-check output into a single \
+candidate fact for a troubleshooting session's "What we know" log.
+
+Return strict JSON with this shape:
+{
+  "text": "<one short sentence stating what is now known, in past tense>",
+  "summary": "<3-7 word provenance label, e.g. 'rules out tenant/license'>"
+}
+
+If the answer/output does NOT contain a substantive fact (e.g. the engineer \
+typed 'unknown', the command failed, the output is empty), return:
+{
+  "text": null,
+  "summary": null
+}
+
+Strict rules:
+- Use ONLY information present in the input. Never add details that were not stated.
+- Do not speculate, infer causes, or extrapolate. State only what the input proves.
+- The text is a fact a colleague could verify by looking at the original answer/output.
+- The summary names the diagnostic value (what this fact rules in or out), not the topic.
+- Output ONLY the JSON object, no prose, no markdown fences.
+"""
+
+
+class FactSynthesisService:
+    """Persists session facts and (optionally) drafts them via an LLM call.
+
+    Methods that touch the database take an `AsyncSession` and assume the
+    caller commits. `create_fact` flushes so the returned row has a primary key.
+    """
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    # ── Persistence ────────────────────────────────────────────────────────
+
+    async def create_fact(
+        self,
+        *,
+        session_id: UUID,
+        account_id: UUID,
+        user_id: UUID,
+        source_type: str,
+        text: str,
+        summary: str | None = None,
+        source_ref: UUID | None = None,
+    ) -> SessionFact:
+        """Persist a fact and bump the session's preview-cache version.
+
+        `source_ref` MUST be None for `user_note` and `ai_synthesis` sources;
+        for `question` and `diagnostic_check` it should point at the stable
+        UUID of the originating task-lane item. The DB has no FK constraint
+        on `source_ref` (the target lives inside JSONB) — integrity is enforced
+        here.
+        """
+        if source_type not in ("question", "diagnostic_check", "user_note", "ai_synthesis"):
+            raise ValueError(f"Invalid source_type: {source_type}")
+
+        if source_type in ("user_note", "ai_synthesis") and source_ref is not None:
+            # `source_ref` is a back-pointer to a question/check; user notes
+            # and AI-synthesized facts have no source item to point at.
+            raise ValueError(
+                f"source_ref must be None for source_type={source_type}"
+            )
+
+        text = (text or "").strip()
+        if not text:
+            raise ValueError("Fact text cannot be empty")
+
+        fact = SessionFact(
+            session_id=session_id,
+            account_id=account_id,
+            text=text,
+            source_type=source_type,
+            source_ref=source_ref,
+            source_summary=(summary or "").strip() or None,
+            created_by=user_id,
+        )
+        self.db.add(fact)
+
+        # Invalidate any preview cached against the prior state_version.
+        # Single UPDATE so the bump is atomic relative to the fact insert
+        # within this transaction; concurrent writers serialize on the row.
+        await self.db.execute(
+            update(AISession)
+            .where(AISession.id == session_id)
+            .values(state_version=AISession.state_version + 1)
+        )
+        await self.db.flush()
+        return fact
+
+    async def soft_delete_fact(self, fact: SessionFact) -> None:
+        """Mark a fact deleted and bump state_version."""
+        from datetime import datetime, timezone
+
+        fact.deleted_at = datetime.now(timezone.utc)
+        await self.db.execute(
+            update(AISession)
+            .where(AISession.id == fact.session_id)
+            .values(state_version=AISession.state_version + 1)
+        )
+        await self.db.flush()
+
+    async def update_fact(
+        self,
+        fact: SessionFact,
+        *,
+        text: str | None = None,
+        summary: str | None = None,
+    ) -> SessionFact:
+        """Update an editable fact and bump state_version.
+
+        Caller is responsible for the editability check — only `user_note`
+        and `ai_synthesis` facts may be edited at the card level. The
+        endpoint enforces this and returns 403 for the read-only types.
+        """
+        if text is not None:
+            stripped = text.strip()
+            if not stripped:
+                raise ValueError("Fact text cannot be empty")
+            fact.text = stripped
+        if summary is not None:
+            fact.source_summary = summary.strip() or None
+
+        await self.db.execute(
+            update(AISession)
+            .where(AISession.id == fact.session_id)
+            .values(state_version=AISession.state_version + 1)
+        )
+        await self.db.flush()
+        return fact
+
+    # ── LLM-backed drafting ────────────────────────────────────────────────
+
+    async def synthesize_from_question(
+        self, *, question_text: str, raw_answer: str
+    ) -> dict[str, str | None]:
+        """Draft `{text, summary}` from a question + engineer's free-text answer.
+
+        Returns `{"text": None, "summary": None}` when the answer doesn't
+        contain a substantive fact — caller should not persist in that case.
+        """
+        return await self._synthesize(
+            user_input=(
+                f"Question asked: {question_text.strip()}\n"
+                f"Engineer's answer: {raw_answer.strip()}"
+            ),
+        )
+
+    async def synthesize_from_check(
+        self, *, check_label: str, check_output: str
+    ) -> dict[str, str | None]:
+        """Draft `{text, summary}` from a diagnostic check label + its output."""
+        return await self._synthesize(
+            user_input=(
+                f"Diagnostic check: {check_label.strip()}\n"
+                f"Output:\n{check_output.strip()}"
+            ),
+        )
+
+    async def _synthesize(self, *, user_input: str) -> dict[str, str | None]:
+        """Single Haiku call with the conservative synthesis prompt."""
+        model = settings.get_model_for_action("fact_synthesis")
+        provider = get_ai_provider(model=model)
+
+        # Cache the system prompt — it's identical across every synthesis call.
+        system_blocks: list[dict[str, Any]] = [
+            {
+                "type": "text",
+                "text": _SYNTHESIS_SYSTEM_PROMPT,
+                "cache_control": {"type": "ephemeral"},
+                # cacheable: identical across all fact-synthesis calls
+            },
+        ]
+
+        try:
+            text, _in, _out = await provider.generate_json(
+                system_prompt=system_blocks,
+                messages=[{"role": "user", "content": user_input}],
+                max_tokens=200,
+            )
+        except Exception:
+            logger.exception("Fact synthesis LLM call failed")
+            return {"text": None, "summary": None}
+
+        return self._parse_synthesis_response(text)
+
+    @staticmethod
+    def _parse_synthesis_response(raw: str) -> dict[str, str | None]:
+        """Tolerant parse: strip fences, accept null fields, ignore extras."""
+        cleaned = raw.strip()
+        if cleaned.startswith("```"):
+            cleaned = re.sub(r"^```(?:json)?\s*", "", cleaned)
+            cleaned = re.sub(r"\s*```$", "", cleaned)
+
+        try:
+            data = json.loads(cleaned)
+        except (json.JSONDecodeError, ValueError):
+            logger.warning("Fact synthesis returned non-JSON: %r", raw[:200])
+            return {"text": None, "summary": None}
+
+        if not isinstance(data, dict):
+            return {"text": None, "summary": None}
+
+        text = data.get("text")
+        summary = data.get("summary")
+        if text is not None and not isinstance(text, str):
+            text = None
+        if summary is not None and not isinstance(summary, str):
+            summary = None
+
+        # Treat empty strings the same as null — "no substantive fact".
+        if isinstance(text, str) and not text.strip():
+            text = None
+        if isinstance(summary, str) and not summary.strip():
+            summary = None
+
+        return {"text": text, "summary": summary}
+
+
+async def list_facts_for_session(
+    db: AsyncSession, session_id: UUID
+) -> list[SessionFact]:
+    """List non-deleted facts for a session, oldest first.
+
+    RLS filters by tenant; the explicit account_id check is unnecessary here.
+    """
+    result = await db.execute(
+        select(SessionFact)
+        .where(
+            SessionFact.session_id == session_id,
+            SessionFact.deleted_at.is_(None),
+        )
+        .order_by(SessionFact.created_at.asc())
+    )
+    return list(result.scalars().all())

backend/app/services/flowpilot_engine.py

@@ -330,6 +330,7 @@ async def start_session(
     # 7. Create first step
     step = _create_step_from_parsed(
         session_id=session.id,
+        account_id=session.account_id,
         step_order=0,
         parsed=parsed,
         input_tokens=input_tokens,
@@ -433,6 +434,7 @@ async def process_response(
     # Create new step
     step = _create_step_from_parsed(
         session_id=session.id,
+        account_id=session.account_id,
         step_order=session.step_count - 1,
         parsed=parsed,
         input_tokens=input_tokens,
@@ -694,6 +696,7 @@ async def pickup_session(
     briefing_step = AISessionStep(
         id=uuid.uuid4(),
         session_id=session.id,
+        account_id=session.account_id,
         branch_id=session.active_branch_id if session.is_branching else None,
         step_order=session.step_count,
         step_type="action",
@@ -765,6 +768,7 @@ async def pickup_session(
 
     next_step = _create_step_from_parsed(
         session_id=session.id,
+        account_id=session.account_id,
         step_order=session.step_count - 1,
         parsed=parsed,
         input_tokens=input_tokens,
@@ -997,6 +1001,7 @@ async def generate_status_update(
     step = AISessionStep(
         id=uuid.uuid4(),
         session_id=session.id,
+        account_id=session.account_id,
         branch_id=session.active_branch_id if session.is_branching else None,
         step_order=session.step_count,
         step_type="status_update",
@@ -1440,6 +1445,7 @@ def _format_engineer_response(request: StepResponseRequest) -> str:
 
 def _create_step_from_parsed(
     session_id: UUID,
+    account_id: UUID,
     step_order: int,
     parsed: dict[str, Any],
     input_tokens: int,
@@ -1487,6 +1493,7 @@ def _create_step_from_parsed(
     return AISessionStep(
         id=uuid.uuid4(),
         session_id=session_id,
+        account_id=account_id,
         branch_id=branch_id,
         step_order=step_order,
         step_type=step_type if parsed["type"] != "resolution_suggestion" else "action",

backend/app/services/network_diagram_ai_service.py

@@ -0,0 +1,151 @@
+"""AI service for generating network diagrams from natural language."""
+import json
+import logging
+
+from app.core.ai_provider import get_ai_provider
+from app.core.config import settings
+from app.schemas.network_diagram import (
+    AIGenerateRequest,
+    AIGenerateResponse,
+    DiagramNode,
+    DiagramEdge,
+    DeviceProperties,
+    Position,
+)
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT_TEMPLATE = """You are a network diagram generator for MSP engineers.
+Given a plain English description of a network, you must return ONLY valid JSON with no markdown, no explanation, no preamble.
+
+Return this exact structure:
+{{
+  "nodes": [
+    {{
+      "id": "unique-string",
+      "type": "device-type-slug",
+      "label": "device label",
+      "position": {{ "x": number, "y": number }},
+      "properties": {{
+        "hostname": "string or null",
+        "ip": "string or null",
+        "subnet": "string or null",
+        "vendor": "string or null",
+        "model": "string or null",
+        "role": "string or null",
+        "vlan": "string or null",
+        "notes": "string or null",
+        "status": "unknown"
+      }}
+    }}
+  ],
+  "edges": [
+    {{
+      "id": "unique-string",
+      "source": "node-id",
+      "target": "node-id",
+      "label": "connection label or null",
+      "connectionType": "ethernet|fiber|wifi|vpn|vlan|wan",
+      "speed": "string or null",
+      "notes": "string or null"
+    }}
+  ],
+  "suggestedName": "short descriptive diagram name",
+  "notes": "any important assumptions or missing info, or null"
+}}
+
+Available device type slugs: {available_slugs}
+
+Position nodes thoughtfully in a logical network topology layout.
+Use x/y coordinates between 0 and 1200 for x, 0 and 800 for y.
+Place WAN/internet at top, core network in middle, endpoints at bottom.
+{merge_instructions}"""
+
+MERGE_INSTRUCTIONS = """
+IMPORTANT: You are ADDING devices to an existing diagram. Do NOT replace existing devices.
+The existing diagram occupies this bounding box: minX={minX}, maxX={maxX}, minY={minY}, maxY={maxY}.
+Place all new nodes OUTSIDE this bounding box — below (y > {maxY} + 100) or to the right (x > {maxX} + 100).
+You may create edges that connect new nodes to existing nodes if the description implies a connection.
+Use these existing node IDs for connections: {existing_node_ids}"""
+
+
+async def generate_diagram(
+    request: AIGenerateRequest,
+    available_slugs: list[str],
+    existing_node_ids: list[str] | None = None,
+) -> AIGenerateResponse:
+    merge_instructions = ""
+    if request.mode == "merge" and request.existingBounds:
+        b = request.existingBounds
+        merge_instructions = MERGE_INSTRUCTIONS.format(
+            minX=b.minX, maxX=b.maxX, minY=b.minY, maxY=b.maxY,
+            existing_node_ids=", ".join(existing_node_ids or []),
+        )
+
+    system_prompt = SYSTEM_PROMPT_TEMPLATE.format(
+        available_slugs=", ".join(available_slugs),
+        merge_instructions=merge_instructions,
+    )
+
+    model = settings.get_model_for_action("network_diagram_generate")
+    provider = get_ai_provider(model)
+
+    messages = [{"role": "user", "content": request.description}]
+
+    response_text, input_tokens, output_tokens = await provider.generate_json(
+        system_prompt=system_prompt,
+        messages=messages,
+        max_tokens=4096,
+    )
+
+    logger.info(
+        "Network diagram AI generation: input_tokens=%d, output_tokens=%d",
+        input_tokens, output_tokens,
+    )
+
+    try:
+        data = json.loads(response_text)
+    except json.JSONDecodeError as e:
+        logger.error("Failed to parse AI response as JSON: %s", e)
+        raise ValueError("AI generated an invalid response, please try again")
+
+    try:
+        nodes = []
+        for raw_node in data.get("nodes", []):
+            node_type = raw_node.get("type", "server")
+            if node_type not in available_slugs:
+                logger.warning("Unknown device type '%s', falling back to 'server'", node_type)
+                node_type = "server"
+
+            nodes.append(DiagramNode(
+                id=raw_node["id"],
+                type=node_type,
+                label=raw_node.get("label", node_type),
+                position=Position(**raw_node.get("position", {"x": 0, "y": 0})),
+                properties=DeviceProperties(**{
+                    k: v for k, v in raw_node.get("properties", {}).items()
+                    if k in DeviceProperties.model_fields
+                }),
+            ))
+
+        edges = []
+        for raw_edge in data.get("edges", []):
+            edges.append(DiagramEdge(
+                id=raw_edge["id"],
+                source=raw_edge["source"],
+                target=raw_edge["target"],
+                label=raw_edge.get("label"),
+                connectionType=raw_edge.get("connectionType", "ethernet"),
+                speed=raw_edge.get("speed"),
+                notes=raw_edge.get("notes"),
+            ))
+    except KeyError as e:
+        logger.warning("AI response missing required field: %s", e)
+        raise ValueError(f"AI generated incomplete data (missing {e}), please try again")
+
+    return AIGenerateResponse(
+        nodes=nodes,
+        edges=edges,
+        suggestedName=data.get("suggestedName"),
+        notes=data.get("notes"),
+    )

backend/app/services/preview_cache.py

@@ -0,0 +1,52 @@
+"""In-process preview cache for FlowPilot resolution-note / escalation-package previews.
+
+Phase 3 implementation per FLOWPILOT-MIGRATION.md Section 5.5:
+- Cache key: `(kind, session_id, state_version)` — no TTL needed, state_version
+  is the source of truth.
+- Invalidation: any write to session_facts, session_suggested_fixes, or
+  script_generations bumps `ai_sessions.state_version`. Old entries simply
+  stop being looked up and leak harmlessly until process restart.
+- Storage: plain dict, single-process. When Session Sharing brings Redis,
+  swap the storage without changing the call sites.
+
+Bound: best-effort soft cap of 5000 entries. When exceeded we drop the
+oldest insertion. Not a TTL — at current scale, the cap is more about
+resident-memory hygiene than correctness.
+"""
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Any
+from uuid import UUID
+
+_MAX_ENTRIES = 5000
+
+
+class _PreviewCache:
+    def __init__(self) -> None:
+        self._store: OrderedDict[tuple[str, UUID, int], Any] = OrderedDict()
+
+    def get(self, kind: str, session_id: UUID, state_version: int) -> Any | None:
+        key = (kind, session_id, state_version)
+        if key not in self._store:
+            return None
+        # Touch on access so LRU eviction is meaningful.
+        self._store.move_to_end(key)
+        return self._store[key]
+
+    def set(self, kind: str, session_id: UUID, state_version: int, value: Any) -> None:
+        key = (kind, session_id, state_version)
+        self._store[key] = value
+        self._store.move_to_end(key)
+        # Evict oldest if over cap. OrderedDict.popitem(last=False) is O(1).
+        while len(self._store) > _MAX_ENTRIES:
+            self._store.popitem(last=False)
+
+    def invalidate_session(self, session_id: UUID) -> None:
+        """Drop all entries for a session — used when the session is deleted."""
+        keys = [k for k in self._store if k[1] == session_id]
+        for k in keys:
+            del self._store[k]
+
+
+preview_cache = _PreviewCache()

backend/app/services/psa/autotask/provider.py

@@ -11,6 +11,7 @@ from app.services.psa.types import (
     PSAMember,
     PSAConfiguration,
     PSATimeEntry,
+    PSABoard,
 )
 
 
@@ -58,6 +59,9 @@ class AutotaskProvider(PSAProvider):
     async def list_members(self) -> list[PSAMember]:
         raise NotImplementedError("Autotask integration coming soon")
 
+    async def list_boards(self) -> list[PSABoard]:
+        raise NotImplementedError("list_boards not implemented for this provider")
+
     async def get_ticket_configurations(self, ticket_id: str) -> list[PSAConfiguration]:
         raise NotImplementedError("Autotask integration coming soon")
 

backend/app/services/psa/base.py

@@ -12,6 +12,7 @@ from .types import (
     PSAMember,
     PSAConfiguration,
     PSATimeEntry,
+    PSABoard,
 )
 
 
@@ -64,6 +65,10 @@ class PSAProvider(ABC):
     async def list_members(self) -> list[PSAMember]:
         ...
 
+    @abstractmethod
+    async def list_boards(self) -> list[PSABoard]:
+        ...
+
     @abstractmethod
     async def get_ticket_configurations(self, ticket_id: str) -> list[PSAConfiguration]:
         ...

backend/app/services/psa/connectwise/provider.py

@@ -16,6 +16,7 @@ from app.services.psa.types import (
     PSAMember,
     PSAConfiguration,
     PSATimeEntry,
+    PSABoard,
 )
 from .client import ConnectWiseClient
 
@@ -55,11 +56,16 @@ class ConnectWiseProvider(PSAProvider):
         return self._map_ticket(data)
 
     async def search_tickets(self, query: str, **filters) -> list[PSATicket]:
-        """Search CW tickets by summary. Supports board_id and status_id filters."""
+        """Search CW tickets by summary. Supports board_id, status_id, member_id,
+        unassigned, board_ids, page, and page_size filters."""
+        page_size = filters.get("page_size", 10)
+        page = filters.get("page", 1)
+
         params: dict = {
             "fields": "id,summary,company,board,status,priority,closedFlag",
             "orderBy": "id desc",
-            "pageSize": 25,
+            "pageSize": page_size,
+            "page": page,
         }
 
         # Build CW condition query
@@ -72,6 +78,14 @@ class ConnectWiseProvider(PSAProvider):
             conditions.append(f"status/id = {filters['status_id']}")
         if not filters.get("include_closed", False):
             conditions.append("closedFlag = false")
+        if filters.get("member_identifier") is not None:
+            conditions.append(f"resources contains '{filters['member_identifier']}'")
+        if filters.get("unassigned", False):
+            conditions.append("resources = null")
+        board_ids: list[int] = filters.get("board_ids") or []
+        if board_ids:
+            board_list = ", ".join(str(bid) for bid in board_ids)
+            conditions.append(f"board/id in ({board_list})")
 
         if conditions:
             params["conditions"] = " and ".join(conditions)
@@ -270,6 +284,32 @@ class ConnectWiseProvider(PSAProvider):
         psa_cache.set(cache_key, result, ttl_seconds=900)
         return result
 
+    async def list_boards(self) -> list[PSABoard]:
+        """List active CW service boards (cached 1 hour)."""
+        cache_key = "boards"
+        cached = psa_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        data = await self.client.get(
+            "/service/boards",
+            params={
+                "fields": "id,name,inactiveFlag",
+                "conditions": "inactiveFlag = false",
+                "pageSize": 100,
+            },
+        )
+        result = [
+            PSABoard(
+                id=b["id"],
+                name=b["name"],
+                inactive=b.get("inactiveFlag", False),
+            )
+            for b in (data if isinstance(data, list) else [])
+        ]
+        psa_cache.set(cache_key, result, ttl_seconds=3600)
+        return result
+
     # ── Ticket Context ────────────────────────────────────────────────
 
     async def get_ticket_context(
@@ -536,7 +576,7 @@ class ConnectWiseProvider(PSAProvider):
         if work_type:
             payload["workType"] = {"name": work_type}
 
-        data = await self._client.post("/time/entries", payload)
+        data = await self.client.post("/time/entries", payload)
         return PSATimeEntry(
             id=str(data["id"]),
             ticket_id=ticket_id,

backend/app/services/psa/halopsa/provider.py

@@ -11,6 +11,7 @@ from app.services.psa.types import (
     PSAMember,
     PSAConfiguration,
     PSATimeEntry,
+    PSABoard,
 )
 
 
@@ -58,6 +59,9 @@ class HaloPSAProvider(PSAProvider):
     async def list_members(self) -> list[PSAMember]:
         raise NotImplementedError("Halo PSA integration coming soon")
 
+    async def list_boards(self) -> list[PSABoard]:
+        raise NotImplementedError("list_boards not implemented for this provider")
+
     async def get_ticket_configurations(self, ticket_id: str) -> list[PSAConfiguration]:
         raise NotImplementedError("Halo PSA integration coming soon")
 

backend/app/services/psa/types.py

@@ -67,6 +67,12 @@ class PSATimeEntry(BaseModel):
     created_at: str | None = None
 
 
+class PSABoard(BaseModel):
+    id: int
+    name: str
+    inactive: bool = False
+
+
 class NoteType:
     INTERNAL_ANALYSIS = "internal_analysis"
     RESOLUTION = "resolution"

backend/app/services/psa_writeback_service.py

@@ -0,0 +1,223 @@
+"""PSA writeback for FlowPilot Phase 4 — Resolve + Escalate round-trip.
+
+Three primitives:
+
+- `post_resolution_note` — post the engineer-edited resolution markdown to
+  the PSA ticket, store `{external_id, posted_at}` on the session.
+- `post_escalation_package` — same pattern for the Escalate flow.
+- `transition_ticket_status` — patch the ticket status, then re-fetch and
+  verify the change actually took. Failed verification raises loudly so the
+  UI never reports silent success (per the existing ConnectWise integration
+  principle called out in FLOWPILOT-MIGRATION.md Section 6.5 and CLAUDE.md).
+
+The target status IDs live in `account_settings.preferences`
+(`cw_resolved_status_id`, `cw_escalated_status_id`). When unset, the status
+transition is a no-op and the endpoint response says so — we do not guess a
+default because CW status IDs are board-specific.
+
+Local-only path: callers handle sessions without `psa_ticket_id` before
+calling this service. Nothing here tries to "post locally" — the service's
+job ends at the PSA boundary.
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.account_settings import AccountSettings
+from app.models.ai_session import AISession
+from app.services.psa.exceptions import PSAConnectionError
+from app.services.psa.registry import get_provider_for_connection
+from app.services.psa.types import NoteType
+
+logger = logging.getLogger(__name__)
+
+
+class PSAStatusVerificationError(RuntimeError):
+    """Raised when a ticket status transition didn't stick on re-fetch.
+
+    The `update_ticket_status` call returned OK but the subsequent
+    `get_ticket` still shows the prior status (or some unrelated one).
+    This is the exact failure mode CLAUDE.md flags as a ConnectWise
+    anti-pattern: reporting success when nothing changed.
+    """
+
+    def __init__(self, ticket_id: str, expected_status_id: int, observed_status: Any) -> None:
+        super().__init__(
+            f"Ticket {ticket_id} status transition to {expected_status_id} "
+            f"did not verify — observed {observed_status!r} after re-fetch."
+        )
+        self.ticket_id = ticket_id
+        self.expected_status_id = expected_status_id
+        self.observed_status = observed_status
+
+
+class PSAWritebackService:
+    """Thin orchestration over the PSA provider for FlowPilot writebacks.
+
+    Instances are per-request — the AsyncSession is the one handling the
+    current HTTP call, and the provider is resolved lazily from the session's
+    `psa_connection_id`.
+    """
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    # ── Public API ────────────────────────────────────────────────────────
+
+    async def post_resolution_note(
+        self, session: AISession, markdown: str
+    ) -> dict[str, Any]:
+        """Post `markdown` as a resolution note on the linked CW ticket.
+
+        On success, persists `resolution_note_markdown`, `_posted_at`,
+        `_external_id` on the session and returns the same triple. Caller is
+        responsible for committing the transaction.
+        """
+        return await self._post_note(
+            session=session,
+            markdown=markdown,
+            note_type=NoteType.RESOLUTION,
+            markdown_col="resolution_note_markdown",
+            posted_at_col="resolution_note_posted_at",
+            external_id_col="resolution_note_external_id",
+            kind="resolution",
+        )
+
+    async def post_escalation_package(
+        self, session: AISession, markdown: str
+    ) -> dict[str, Any]:
+        """Post `markdown` as an escalation handoff note on the CW ticket."""
+        return await self._post_note(
+            session=session,
+            markdown=markdown,
+            # Internal-analysis visibility: the handoff is for the next engineer,
+            # not the customer. CW fires no notifications, keeps the note internal.
+            note_type=NoteType.INTERNAL_ANALYSIS,
+            markdown_col="escalation_package_markdown",
+            posted_at_col="escalation_package_posted_at",
+            external_id_col="escalation_package_external_id",
+            kind="escalation",
+        )
+
+    async def transition_ticket_status(
+        self,
+        session: AISession,
+        target_status_id: int,
+    ) -> dict[str, Any]:
+        """PATCH ticket status, then re-fetch and verify.
+
+        Returns `{"success": True, "verified_status_id": <int>, "verified_status_name": <str>}`
+        when the observed status matches. Raises `PSAStatusVerificationError`
+        when the transition didn't take (most common real-world failure: CW
+        requires certain fields before allowing a status change to
+        Resolved — the PATCH returns 200 but the status silently stays put).
+        """
+        if not session.psa_ticket_id or not session.psa_connection_id:
+            raise ValueError("Session has no linked PSA ticket for status transition")
+
+        provider = await get_provider_for_connection(session.psa_connection_id, self.db)
+        await provider.update_ticket_status(
+            ticket_id=session.psa_ticket_id, status_id=target_status_id,
+        )
+
+        # Verify by re-fetch — this is the load-bearing step.
+        verification = await provider.get_ticket(session.psa_ticket_id)
+        observed_id = getattr(verification, "status_id", None)
+        observed_name = getattr(verification, "status_name", None)
+        if observed_id != target_status_id:
+            raise PSAStatusVerificationError(
+                ticket_id=session.psa_ticket_id,
+                expected_status_id=target_status_id,
+                observed_status={"id": observed_id, "name": observed_name},
+            )
+
+        return {
+            "success": True,
+            "verified_status_id": observed_id,
+            "verified_status_name": observed_name,
+        }
+
+    async def resolved_status_id_for_account(
+        self, account_id: UUID
+    ) -> int | None:
+        """Return the configured CW "Resolved" status ID for the account.
+
+        None means "no transition configured" — callers should skip the
+        transition (posting the note is still meaningful). This lives in
+        account_settings.preferences per the Phase 1 JSONB grab-bag design.
+        """
+        raw = await AccountSettings.get_setting(self.db, account_id, "cw_resolved_status_id", None)
+        return self._coerce_status_id(raw)
+
+    async def escalated_status_id_for_account(
+        self, account_id: UUID
+    ) -> int | None:
+        raw = await AccountSettings.get_setting(self.db, account_id, "cw_escalated_status_id", None)
+        return self._coerce_status_id(raw)
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    async def _post_note(
+        self,
+        *,
+        session: AISession,
+        markdown: str,
+        note_type: str,
+        markdown_col: str,
+        posted_at_col: str,
+        external_id_col: str,
+        kind: str,
+    ) -> dict[str, Any]:
+        if not session.psa_ticket_id or not session.psa_connection_id:
+            raise ValueError(f"Session has no linked PSA ticket for {kind} post")
+
+        markdown = (markdown or "").strip()
+        if not markdown:
+            raise ValueError(f"{kind} markdown is empty")
+
+        try:
+            provider = await get_provider_for_connection(session.psa_connection_id, self.db)
+        except PSAConnectionError:
+            # Connection could have been deleted or deactivated since session
+            # creation — propagate as a clear error for the endpoint to surface.
+            logger.exception(
+                "PSA connection %s is no longer available for session %s",
+                session.psa_connection_id, session.id,
+            )
+            raise
+
+        posted = await provider.post_note(
+            ticket_id=session.psa_ticket_id,
+            text=markdown,
+            note_type=note_type,
+        )
+
+        posted_at = datetime.now(timezone.utc)
+        setattr(session, markdown_col, markdown)
+        setattr(session, posted_at_col, posted_at)
+        setattr(session, external_id_col, str(posted.id) if posted.id else None)
+
+        return {
+            "external_id": str(posted.id) if posted.id else None,
+            "posted_at": posted_at,
+            "kind": kind,
+        }
+
+    @staticmethod
+    def _coerce_status_id(raw: Any) -> int | None:
+        if raw is None:
+            return None
+        try:
+            return int(raw)
+        except (TypeError, ValueError):
+            logger.warning(
+                "Non-integer CW status ID in account_settings.preferences: %r",
+                raw,
+            )
+            return None

backend/app/services/resolution_note_generator.py

@@ -0,0 +1,342 @@
+"""ResolutionNoteGeneratorService — drafts the structured Resolve note for a session.
+
+Produces the four-section markdown that ships to the customer ticket (per
+FLOWPILOT-MIGRATION.md Section 6.2):
+
+    ## Problem
+    ## What we confirmed
+    ## Root cause
+    ## Resolution
+
+The output is the *draft* — engineers review and edit in the preview popover
+before clicking Confirm & post (Phase 4). Caching is keyed on
+`(session_id, ai_sessions.state_version)` per Section 5.5; the cache lives in
+`preview_cache` and invalidates automatically when any fact / suggested fix /
+script generation bumps the session's state_version.
+
+Model: Sonnet (`resolution_note` action tier — quality matters because the
+output is customer-facing). MCP intentionally disabled — this is a summary
+of existing state, not a research task.
+
+Sensitive parameter values in script_generations are redacted using the
+script template's `parameters_schema` (`field_type: "password"`). Existing
+ScriptTemplateEngine.redact_sensitive handles the substitution.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.ai_provider import get_ai_provider
+from app.core.config import settings
+from app.models.ai_session import AISession
+from app.models.script_template import ScriptGeneration, ScriptTemplate
+from app.models.session_fact import SessionFact
+from app.models.session_suggested_fix import SessionSuggestedFix
+from app.services.preview_cache import preview_cache
+from app.services.script_template_engine import ScriptTemplateEngine
+
+logger = logging.getLogger(__name__)
+
+
+_RESOLUTION_NOTE_SYSTEM_PROMPT = """\
+You produce structured resolution notes for an MSP troubleshooting platform. \
+The notes are posted as ticket notes in the customer's PSA, so they must read \
+like a competent senior engineer summarized the work — not like an AI \
+narration. Your output goes in front of paying customers.
+
+Output exactly this markdown structure, no preamble, no closing remarks, no \
+extra headings:
+
+## Problem
+<one short paragraph stating the issue the engineer worked on, derived from the \
+session's intake/title and the incident header. Past tense. No "user reported" \
+hedging — state the problem directly.>
+
+## What we confirmed
+<bulleted list of facts from the "What we know" section, each one a short line. \
+Group similar facts together; do not invent connecting prose. If there are no \
+facts, write "Nothing was confirmed." and skip to Root cause.>
+
+## Root cause
+<one short paragraph naming the root cause based on the active suggested fix \
+and confirmed facts. If the suggested fix is low-confidence (<60%) or absent, \
+say "Root cause not definitively isolated." and explain what is suspected based \
+on facts.>
+
+## Resolution
+<The content of this section depends on the outcome recorded for the active \
+suggested fix, as given in the input bundle under "fix.status":>
+
+- applied_success: Write in past tense using closure language. State that the \
+fix was applied and verified as working. If verified_at is provided, you may \
+reference it as the time resolution was confirmed. Example phrasing: \
+"Applied <fix title>; confirmed working."
+- applied_failed: Acknowledge that the proposed fix did not resolve the issue \
+and was discarded. If failure_reason is provided, include it. Then describe \
+the actual resolution path taken (derived from facts and scripts run). This \
+state means the engineer resolved the issue another way; the note should cover \
+that actual resolution, not just the failed attempt.
+- applied_partial: Note that the fix was partially applied. If partial_notes \
+are provided, include them. Then describe the final resolution path taken.
+- dismissed: Treat the fix as considered and set aside. Do not center the note \
+on it. Describe the resolution based on what was actually confirmed and done.
+- proposed (no outcome yet): Write "Resolution not yet applied — fix proposed: \
+<fix title>." Pull verbatim script names and template references when available.
+
+Strict rules:
+- Use ONLY the facts and state I provide. Never invent specifics that are not \
+in the input.
+- Do not include placeholder text like "TBD", "TODO", or empty bullets.
+- Do not include the engineer's name, the AI's name, internal session IDs, or \
+the session's chat transcript.
+- Markdown headings exactly as shown (## level), no bolding the headings.
+- No trailing whitespace, no double-blank lines, no horizontal rules.
+"""
+
+
+class ResolutionNoteGeneratorService:
+    """Generates and caches the four-section Resolve note markdown."""
+
+    KIND = "resolution_note"
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def generate_or_get_cached(
+        self, session_id: UUID, *, force: bool = False,
+    ) -> dict[str, Any]:
+        """Return the preview for the session.
+
+        Reads `(KIND, session_id, state_version)` from the in-process cache;
+        on miss, generates fresh markdown and stores under the same key.
+        `force=True` bypasses the cache and refreshes the cached entry.
+
+        Returns `{"markdown": str, "target_ticket_ref": str | None,
+                   "state_version": int, "from_cache": bool}`.
+        """
+        session = await self._load_session(session_id)
+        cached = preview_cache.get(self.KIND, session.id, session.state_version) if not force else None
+        if cached is not None:
+            return {**cached, "from_cache": True}
+
+        markdown = await self._render(session)
+        target = self._target_ticket_ref(session)
+        payload = {
+            "markdown": markdown,
+            "target_ticket_ref": target,
+            "state_version": session.state_version,
+        }
+        preview_cache.set(self.KIND, session.id, session.state_version, payload)
+        return {**payload, "from_cache": False}
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    async def _load_session(self, session_id: UUID) -> AISession:
+        result = await self.db.execute(
+            select(AISession).where(AISession.id == session_id)
+        )
+        session = result.scalar_one_or_none()
+        if session is None:
+            raise ValueError(f"Session {session_id} not found")
+        return session
+
+    async def _render(self, session: AISession) -> str:
+        """Build the prompt input bundle, call the model, return markdown."""
+        facts = await self._load_facts(session.id)
+        active_fix = await self._load_active_fix(session.id)
+        gens = await self._load_redacted_generations(session.id)
+
+        bundle = self._build_input_bundle(session, facts, active_fix, gens)
+
+        model = settings.get_model_for_action("resolution_note")
+        provider = get_ai_provider(model=model)
+
+        # Cache the system prompt — identical across every preview call for
+        # every session. Per-session bundle is in the user message, uncached.
+        system_blocks: list[dict[str, Any]] = [
+            {
+                "type": "text",
+                "text": _RESOLUTION_NOTE_SYSTEM_PROMPT,
+                "cache_control": {"type": "ephemeral"},
+                # cacheable: identical across every resolution-note preview call
+            },
+        ]
+
+        try:
+            text, _in, _out = await provider.generate_text(
+                system_prompt=system_blocks,
+                messages=[{"role": "user", "content": bundle}],
+                max_tokens=1200,
+            )
+        except Exception:
+            logger.exception("Resolution note generation failed for session %s", session.id)
+            raise
+        return text.strip()
+
+    async def _load_facts(self, session_id: UUID) -> list[SessionFact]:
+        result = await self.db.execute(
+            select(SessionFact)
+            .where(
+                SessionFact.session_id == session_id,
+                SessionFact.deleted_at.is_(None),
+            )
+            .order_by(SessionFact.created_at.asc())
+        )
+        return list(result.scalars().all())
+
+    async def _load_active_fix(self, session_id: UUID) -> SessionSuggestedFix | None:
+        result = await self.db.execute(
+            select(SessionSuggestedFix)
+            .where(
+                SessionSuggestedFix.session_id == session_id,
+                SessionSuggestedFix.superseded_at.is_(None),
+            )
+            .order_by(SessionSuggestedFix.created_at.desc())
+        )
+        return result.scalars().first()
+
+    async def _load_redacted_generations(
+        self, session_id: UUID
+    ) -> list[dict[str, Any]]:
+        """Pull script_generations for the session, redacting password params.
+
+        Password fields are inferred from the linked template's
+        `parameters_schema` (`field_type: "password"`). The existing
+        ScriptTemplateEngine.redact_sensitive handles the substitution.
+        """
+        result = await self.db.execute(
+            select(ScriptGeneration)
+            .where(ScriptGeneration.ai_session_id == session_id)
+            .order_by(ScriptGeneration.created_at.asc())
+        )
+        gens = list(result.scalars().all())
+        if not gens:
+            return []
+
+        template_ids = {g.template_id for g in gens}
+        tpl_result = await self.db.execute(
+            select(ScriptTemplate).where(ScriptTemplate.id.in_(template_ids))
+        )
+        templates_by_id = {t.id: t for t in tpl_result.scalars().all()}
+
+        engine = ScriptTemplateEngine()
+        out: list[dict[str, Any]] = []
+        for g in gens:
+            tpl = templates_by_id.get(g.template_id)
+            sensitive_keys = self._sensitive_keys_from_schema(
+                (tpl.parameters_schema if tpl else {}) or {}
+            )
+            redacted_params = engine.redact_sensitive(g.parameters_used or {}, sensitive_keys)
+            out.append({
+                "template_name": tpl.name if tpl else "(unknown template)",
+                "template_slug": tpl.slug if tpl else None,
+                "parameters_used": redacted_params,
+                "created_at": g.created_at.isoformat(),
+            })
+        return out
+
+    @staticmethod
+    def _sensitive_keys_from_schema(schema: dict[str, Any]) -> set[str]:
+        """Extract password-typed parameter keys from a template's schema.
+
+        The schema shape is `{"parameters": [{"key": "...", "field_type": "password", ...}]}`
+        per the existing Script Generator convention. Tolerate both that shape
+        and the simpler `{"key": {"field_type": "password"}}` form.
+        """
+        keys: set[str] = set()
+        params = schema.get("parameters") if isinstance(schema, dict) else None
+        if isinstance(params, list):
+            for p in params:
+                if isinstance(p, dict) and p.get("field_type") == "password":
+                    k = p.get("key") or p.get("variable_name")
+                    if isinstance(k, str):
+                        keys.add(k)
+        elif isinstance(schema, dict):
+            for k, v in schema.items():
+                if isinstance(v, dict) and v.get("field_type") == "password":
+                    keys.add(k)
+        return keys
+
+    @staticmethod
+    def _target_ticket_ref(session: AISession) -> str | None:
+        """Display ref for the linked PSA ticket, e.g. 'CW #48291'.
+
+        ConnectWise is the only PSA wired today (per the Phase 1 constraint),
+        so a CW prefix is reasonable. Other PSAs will need provider-aware
+        formatting in Phase 4.
+        """
+        if not session.psa_ticket_id:
+            return None
+        return f"CW #{session.psa_ticket_id}"
+
+    @staticmethod
+    def _build_input_bundle(
+        session: AISession,
+        facts: list[SessionFact],
+        active_fix: SessionSuggestedFix | None,
+        generations: list[dict[str, Any]],
+    ) -> str:
+        """Compose the structured input the LLM sees for one preview call."""
+        lines: list[str] = []
+        lines.append("# Session context")
+        lines.append(f"Title: {session.title or '(untitled)'}")
+        if session.problem_summary:
+            lines.append(f"Problem summary: {session.problem_summary}")
+        if session.problem_domain:
+            lines.append(f"Domain: {session.problem_domain}")
+        intake_text = (session.intake_content or {}).get("text") if isinstance(session.intake_content, dict) else None
+        if intake_text:
+            lines.append(f"Intake message: {intake_text}")
+        if session.psa_ticket_id:
+            lines.append(f"Linked PSA ticket: CW #{session.psa_ticket_id}")
+
+        lines.append("")
+        lines.append("# Confirmed facts (What we know)")
+        if not facts:
+            lines.append("(none)")
+        else:
+            for f in facts:
+                tag = f.source_type
+                summary = f" — {f.source_summary}" if f.source_summary else ""
+                lines.append(f"- [{tag}] {f.text}{summary}")
+
+        lines.append("")
+        lines.append("# Active suggested fix")
+        if active_fix is None:
+            lines.append("(no active suggested fix)")
+        else:
+            lines.append(f"Title: {active_fix.title}")
+            lines.append(f"Confidence: {active_fix.confidence_pct}%")
+            lines.append(f"Description: {active_fix.description}")
+            if active_fix.user_decision:
+                lines.append(f"Engineer decision: {active_fix.user_decision}")
+            lines.append(f"Outcome status: {active_fix.status}")
+            if active_fix.applied_at:
+                lines.append(f"Applied at: {active_fix.applied_at.isoformat()}")
+            if active_fix.verified_at:
+                lines.append(f"Verified at: {active_fix.verified_at.isoformat()}")
+            if active_fix.partial_notes:
+                lines.append(f"Partial notes: {active_fix.partial_notes}")
+            if active_fix.failure_reason:
+                lines.append(f"Failure reason: {active_fix.failure_reason}")
+
+        lines.append("")
+        lines.append("# Scripts run during the session (passwords redacted)")
+        if not generations:
+            lines.append("(none)")
+        else:
+            for g in generations:
+                lines.append(f"- {g['template_name']} (slug={g['template_slug']})")
+                if g["parameters_used"]:
+                    lines.append(f"  parameters: {g['parameters_used']}")
+
+        lines.append("")
+        lines.append(
+            "Produce the four-section resolution note now. Use only the input above."
+        )
+        return "\n".join(lines)

backend/app/services/script_builder_service.py

@@ -148,6 +148,8 @@ async def create_session(
     team_id: UUID | None,
     language: str,
     initial_prompt: str | None = None,
+    origin: str = "standalone",
+    ai_session_id: UUID | None = None,
 ) -> ScriptBuilderSession:
     """Create a new Script Builder session."""
     session = ScriptBuilderSession(
@@ -155,6 +157,8 @@ async def create_session(
         account_id=account_id,
         team_id=team_id,
         language=language,
+        origin=origin,
+        ai_session_id=ai_session_id,
     )
     db.add(session)
     await db.flush()
@@ -220,7 +224,15 @@ async def send_message(
     model = settings.get_model_for_action("script_build")
     provider = get_ai_provider(model=model)
     ai_text, input_tokens, output_tokens = await provider.generate_text(
-        system_prompt=system_prompt,
+        system_prompt=[
+            {"type": "text", "text": system_prompt},
+            # cacheable: SYSTEM_PROMPT_TEMPLATE with a per-session language
+            # substitution. Two sessions on the same language share a cache
+            # entry; different languages cache independently. Conversation
+            # history (ai_messages) is NOT cached at this layer — if that
+            # becomes a cost driver, route script_builder through the chat
+            # wrapper (0.4) which handles history caching.
+        ],
         messages=ai_messages,
         max_tokens=8192,
     )
@@ -287,15 +299,22 @@ async def list_sessions(
     user_id: UUID,
     limit: int = 20,
     offset: int = 0,
+    *,
+    include_inline: bool = False,
 ) -> list[ScriptBuilderSession]:
-    """List user's builder sessions ordered by updated_at desc."""
-    result = await db.execute(
+    """List user's builder sessions ordered by updated_at desc.
+
+    By default (include_inline=False) excludes pilot_inline sessions so the
+    /script-builder dashboard only shows standalone sessions.
+    """
+    stmt = (
         select(ScriptBuilderSession)
         .where(ScriptBuilderSession.user_id == user_id)
-        .order_by(ScriptBuilderSession.updated_at.desc())
-        .limit(limit)
-        .offset(offset)
     )
+    if not include_inline:
+        stmt = stmt.where(ScriptBuilderSession.origin == "standalone")
+    stmt = stmt.order_by(ScriptBuilderSession.updated_at.desc()).limit(limit).offset(offset)
+    result = await db.execute(stmt)
     return list(result.scalars().all())
 
 
@@ -313,13 +332,23 @@ async def delete_session(
     return True
 
 
-async def count_user_sessions(db: AsyncSession, user_id: UUID) -> int:
-    """Count active builder sessions for a user."""
-    result = await db.execute(
-        select(func.count(ScriptBuilderSession.id)).where(
-            ScriptBuilderSession.user_id == user_id
-        )
+async def count_user_sessions(
+    db: AsyncSession,
+    user_id: UUID,
+    *,
+    include_inline: bool = False,
+) -> int:
+    """Count active builder sessions for a user.
+
+    By default (include_inline=False) excludes pilot_inline sessions so they
+    don't consume slots against the MAX_SESSIONS_PER_USER cap.
+    """
+    stmt = select(func.count(ScriptBuilderSession.id)).where(
+        ScriptBuilderSession.user_id == user_id
     )
+    if not include_inline:
+        stmt = stmt.where(ScriptBuilderSession.origin == "standalone")
+    result = await db.execute(stmt)
     return result.scalar_one()
 
 

backend/app/services/template_extraction_service.py

@@ -0,0 +1,201 @@
+"""TemplateExtractionService — propose a parameter schema from a rendered script.
+
+Phase 5 of the FlowPilot migration. Called when an engineer chooses
+"Run now, templatize after resolve" on a suggested fix with no existing
+library match. The service looks at the concrete script (with the values
+the engineer is about to run with) and session/ticket context, then
+proposes a parameterization that future engineers could use from the
+Script Library.
+
+Design choices (per FLOWPILOT-MIGRATION.md Section 6.4):
+
+- **Conservative by default.** Prefer fewer parameters. Environment-agnostic
+  values (like a command name) should not be parameterized. The prompt calls
+  that out explicitly.
+- **Round-trip check.** After the LLM proposes parameters, we validate that
+  the templated body renders back to the original script when given the
+  extracted parameter values. Failures log a warning and the caller falls
+  back to a single-parameter "raw script" proposal.
+- **Model:** Sonnet (`template_extraction` tier). Creates a persistent
+  library artifact — quality matters more than latency.
+
+Output shape mirrors the Script Generator's parameter schema:
+    {
+      "parameters": [
+        {"key": "<snake>", "label": "<human>", "type": "text|password|select|...",
+         "inferred_from": "<session fact / ticket field / ai guess>"}
+      ],
+      "templated_body": "<script with {{ key }} placeholders>",
+    }
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from app.core.ai_provider import get_ai_provider
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+_EXTRACTION_SYSTEM_PROMPT = """\
+You are a senior MSP engineer drafting a reusable script template from a \
+concrete script that resolved one ticket. Your job is to identify the values \
+in the script that would change for a different invocation — those become \
+parameters — and replace them with {{ snake_case }} placeholders.
+
+Return strict JSON with this shape:
+{
+  "parameters": [
+    {
+      "key": "<snake_case, ASCII>",
+      "label": "<Short human label, Title Case>",
+      "type": "text" | "password" | "select" | "boolean" | "number" | "textarea",
+      "inferred_from": "<short sentence naming the session fact or ticket \
+field this value came from; or 'ai best-guess' when neither>"
+    }
+  ],
+  "templated_body": "<the original script with each parameterized value \
+replaced by {{ key }} matching the parameters above>"
+}
+
+Rules:
+- Prefer FEWER parameters. If a value looks environment-agnostic — a cmdlet \
+name, a standard path like C:\\Windows\\System32, a Microsoft-documented URL \
+— keep it hardcoded.
+- Secret-looking values (passwords, API keys, client secrets) MUST be \
+parameterized with type=password.
+- The templated_body MUST render back to the original script when the \
+parameter values from the context are substituted in. Preserve all whitespace, \
+comments, and casing.
+- If the script has no meaningful parameters (e.g. it's a single read-only \
+cmdlet like Get-Service), return parameters=[] and templated_body = original.
+- No markdown fences, no prose, only the JSON object.
+"""
+
+
+async def extract_parameters(
+    *,
+    script_body: str,
+    session_context: str | None = None,
+    ticket_context: str | None = None,
+) -> dict[str, Any]:
+    """Return `{parameters, templated_body}` for the given rendered script.
+
+    On LLM failure or malformed output, returns a conservative fallback:
+    the original body with no parameters proposed. Callers can still create
+    a `draft_templates` row from this — the engineer reviews and refines
+    before accepting in the post-resolve prompt (Phase 6).
+    """
+    model = settings.get_model_for_action("template_extraction")
+    provider = get_ai_provider(model=model)
+
+    input_lines = [
+        "# Script to templatize",
+        "```",
+        script_body.strip(),
+        "```",
+    ]
+    if session_context:
+        input_lines.extend(["", "# Session context (facts, symptoms)", session_context.strip()])
+    if ticket_context:
+        input_lines.extend(["", "# Ticket context (company, user, priority)", ticket_context.strip()])
+    user_input = "\n".join(input_lines)
+
+    system_blocks: list[dict[str, Any]] = [
+        {
+            "type": "text",
+            "text": _EXTRACTION_SYSTEM_PROMPT,
+            "cache_control": {"type": "ephemeral"},
+            # cacheable: identical across every extraction call
+        },
+    ]
+
+    try:
+        text, _in, _out = await provider.generate_json(
+            system_prompt=system_blocks,
+            messages=[{"role": "user", "content": user_input}],
+            max_tokens=3000,
+        )
+    except Exception:
+        logger.exception("TemplateExtractionService LLM call failed; returning fallback")
+        return _fallback(script_body)
+
+    parsed = _parse_response(text)
+    if parsed is None:
+        return _fallback(script_body)
+
+    # Round-trip validation: render parsed["templated_body"] with the
+    # `inferred_from` values and confirm it matches the original. We don't
+    # have the engineer's values yet here (those come at runtime), but we
+    # can at least check that every {{ key }} in templated_body maps to a
+    # declared parameter. A mismatch means the LLM referenced an undeclared
+    # placeholder — conservative fallback.
+    declared_keys = {p.get("key") for p in parsed["parameters"] if isinstance(p, dict)}
+    referenced_keys = set(re.findall(r"\{\{\s*(\w+)\s*\}\}", parsed["templated_body"]))
+    missing = referenced_keys - declared_keys
+    if missing:
+        logger.warning(
+            "TemplateExtractionService: templated_body references undeclared "
+            "keys %s; using fallback",
+            sorted(missing),
+        )
+        return _fallback(script_body)
+
+    return parsed
+
+
+def _parse_response(raw: str) -> dict[str, Any] | None:
+    """Tolerant parse. Returns None on any structural problem."""
+    cleaned = raw.strip()
+    if cleaned.startswith("```"):
+        cleaned = re.sub(r"^```(?:json)?\s*", "", cleaned)
+        cleaned = re.sub(r"\s*```$", "", cleaned)
+    try:
+        data = json.loads(cleaned)
+    except (json.JSONDecodeError, ValueError):
+        logger.warning("TemplateExtractionService returned non-JSON: %r", raw[:200])
+        return None
+
+    if not isinstance(data, dict):
+        return None
+    params = data.get("parameters")
+    body = data.get("templated_body")
+    if not isinstance(params, list) or not isinstance(body, str):
+        logger.warning("TemplateExtractionService missing parameters or templated_body")
+        return None
+
+    # Validate each parameter shape. Drop malformed entries rather than
+    # failing the whole response — the engineer will review before accept.
+    valid_params: list[dict[str, Any]] = []
+    allowed_types = {"text", "password", "select", "boolean", "number", "textarea", "multi_text"}
+    for p in params:
+        if not isinstance(p, dict):
+            continue
+        key = p.get("key")
+        if not isinstance(key, str) or not re.match(r"^[a-z_][a-z0-9_]*$", key):
+            continue
+        ptype = p.get("type", "text")
+        if ptype not in allowed_types:
+            ptype = "text"
+        valid_params.append({
+            "key": key,
+            "label": p.get("label") or key.replace("_", " ").title(),
+            "type": ptype,
+            "inferred_from": p.get("inferred_from") or "ai best-guess",
+        })
+
+    return {"parameters": valid_params, "templated_body": body}
+
+
+def _fallback(script_body: str) -> dict[str, Any]:
+    """Conservative no-op result: zero parameters, body unchanged.
+
+    Used when the LLM call fails or returns unusable output. The engineer
+    can still save this as a draft and refine in the post-resolve prompt —
+    it just won't propose a parameterization for them.
+    """
+    return {"parameters": [], "templated_body": script_body}

backend/app/services/unified_chat_service.py

@@ -3,22 +3,41 @@
 Replaces assistant_chat_service for new chat sessions. Messages are stored
 in ai_sessions.conversation_messages JSONB. Reuses the same AI calling
 infrastructure and system prompt from assistant_chat_service.
+
+## Markers parsed here
+- `[QUESTIONS]` / `[ACTIONS]` — task-lane items shown to the engineer
+- `[FORK]` — diagnostic forking, creates SessionBranch rows
+- `[PROMOTE]` (Phase 2) — surfaces a fact to the What-we-know section.
+  Items in pending_task_lane carry stable UUIDs (assigned here) so PROMOTE
+  source_refs survive across turns even when the model re-emits the same
+  question/action.
+- `[SUGGEST_FIX]` (Phase 3) — proposes a resolution path for the session.
+  Each new emission supersedes the previous active row (sets superseded_at)
+  so there's exactly one active fix at a time.
 """
 import json
 import logging
 import re
+import uuid as _uuid
 from typing import Any
 from uuid import UUID
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from datetime import datetime, timezone
+
+from sqlalchemy import update
+
 from app.models.ai_session import AISession
+from app.models.script_template import ScriptTemplate
+from app.models.session_suggested_fix import SessionSuggestedFix
 from app.services.assistant_chat_service import (
     ASSISTANT_SYSTEM_PROMPT,
     _call_ai,
     _auto_title,
 )
+from app.services.fact_synthesis_service import FactSynthesisService
 from app.services.rag_service import search as rag_search, build_rag_context, extract_suggested_flows
 
 logger = logging.getLogger(__name__)
@@ -147,6 +166,378 @@ def _parse_questions_marker(ai_content: str) -> tuple[str, list[dict[str, Any]]
     return cleaned, valid_questions
 
 
+def _parse_promote_marker(ai_content: str) -> tuple[str, list[dict[str, Any]] | None]:
+    """Extract one or more [PROMOTE]...[/PROMOTE] JSON blocks from AI response.
+
+    Each block contains a JSON object describing a candidate fact:
+      {"source_type": "question"|"diagnostic_check"|"ai_synthesis",
+       "source_ref": "<task_lane_item_uuid>" | null,
+       "text": "<fact text>",
+       "summary": "<short provenance, optional>"}
+
+    Returns (cleaned_content, list_of_items_or_None). All matched blocks are
+    stripped from display text. Invalid items are dropped silently with a
+    warning — a malformed PROMOTE should never break the chat response.
+
+    Per FLOWPILOT-MIGRATION.md Section 8.1, the model emits text + summary
+    inline so no LLM round-trip is needed to persist the fact.
+    """
+    blocks = list(re.finditer(r"\[PROMOTE\]\s*([\s\S]*?)\s*\[/PROMOTE\]", ai_content))
+    if not blocks:
+        return ai_content, None
+
+    items: list[dict[str, Any]] = []
+    for m in blocks:
+        raw = m.group(1).strip()
+        if raw.startswith("```"):
+            raw = re.sub(r"^```(?:json)?\s*", "", raw)
+            raw = re.sub(r"\s*```$", "", raw)
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, ValueError) as e:
+            logger.warning("Failed to parse [PROMOTE] block: %s", e)
+            continue
+
+        if not isinstance(data, dict):
+            logger.warning("[PROMOTE] block must be a JSON object, got %s", type(data).__name__)
+            continue
+
+        source_type = data.get("source_type")
+        text = (data.get("text") or "").strip()
+        summary = (data.get("summary") or "").strip() or None
+        source_ref_raw = data.get("source_ref")
+
+        if source_type not in ("question", "diagnostic_check", "ai_synthesis"):
+            # `user_note` is engineer-only, not an AI-emittable type.
+            logger.warning("Invalid [PROMOTE] source_type=%r, skipping", source_type)
+            continue
+        if not text:
+            logger.warning("[PROMOTE] block missing text, skipping")
+            continue
+
+        source_ref: UUID | None = None
+        if source_ref_raw:
+            try:
+                source_ref = UUID(str(source_ref_raw))
+            except (ValueError, AttributeError):
+                logger.warning("[PROMOTE] source_ref %r is not a valid UUID, dropping ref", source_ref_raw)
+                source_ref = None
+
+        # `ai_synthesis` must NEVER carry a source_ref (no question/check item
+        # to point at) — surface mistakes from the model rather than tripping
+        # the FactSynthesisService validation later.
+        if source_type == "ai_synthesis":
+            source_ref = None
+
+        items.append({
+            "source_type": source_type,
+            "source_ref": source_ref,
+            "text": text,
+            "summary": summary,
+        })
+
+    # Strip all PROMOTE blocks from display content — engineers see facts in
+    # the What-we-know panel, not as raw markers in the chat.
+    cleaned = re.sub(r"\[PROMOTE\]\s*[\s\S]*?\s*\[/PROMOTE\]", "", ai_content).strip()
+
+    return cleaned, items or None
+
+
+def _assign_stable_task_lane_ids(
+    prev_lane: dict[str, Any] | None,
+    questions: list[dict[str, Any]] | None,
+    actions: list[dict[str, Any]] | None,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Assign stable UUIDs to task-lane items, preserving them across turns.
+
+    The model often re-emits the same question/action across multiple turns
+    (it is told to keep `_(not yet completed)_` items alive). When the
+    question text matches a prior turn's, we keep the prior UUID so any
+    `session_facts.source_ref` pointing at it stays valid.
+
+    Match key:
+    - Questions: exact `text`
+    - Actions: exact `label`
+
+    Returns the questions/actions lists augmented with an `id` field.
+    """
+    prev_questions = (prev_lane or {}).get("questions") or []
+    prev_actions = (prev_lane or {}).get("actions") or []
+
+    prev_q_ids: dict[str, str] = {
+        str(q.get("text") or "").strip(): str(q["id"])
+        for q in prev_questions
+        if isinstance(q, dict) and q.get("id") and q.get("text")
+    }
+    prev_a_ids: dict[str, str] = {
+        str(a.get("label") or "").strip(): str(a["id"])
+        for a in prev_actions
+        if isinstance(a, dict) and a.get("id") and a.get("label")
+    }
+
+    out_questions: list[dict[str, Any]] = []
+    for q in questions or []:
+        text = str(q.get("text") or "").strip()
+        existing = prev_q_ids.get(text) if text else None
+        out_questions.append({
+            **q,
+            "id": existing or str(_uuid.uuid4()),
+        })
+
+    out_actions: list[dict[str, Any]] = []
+    for a in actions or []:
+        label = str(a.get("label") or "").strip()
+        existing = prev_a_ids.get(label) if label else None
+        out_actions.append({
+            **a,
+            "id": existing or str(_uuid.uuid4()),
+        })
+
+    return out_questions, out_actions
+
+
+def _parse_suggest_fix_marker(
+    ai_content: str,
+) -> tuple[str, dict[str, Any] | None]:
+    """Extract a single [SUGGEST_FIX]...[/SUGGEST_FIX] JSON block from AI response.
+
+    The block contains:
+      {"title": "...", "description": "...", "confidence": 0..100,
+       "script_template_slug": "..." | null,
+       "ai_drafted_script": "..." | null,
+       "ai_drafted_parameters": {...} | null}
+
+    Per FLOWPILOT-MIGRATION.md Section 8.2. Only the LAST block in the response
+    is honored — if the model emits multiple, only its final view of the fix
+    matters; earlier ones in the same turn are stale even before persistence.
+
+    Returns (cleaned_content, fix_dict_or_None). Marker stripped from display.
+    """
+    blocks = list(re.finditer(r"\[SUGGEST_FIX\]\s*([\s\S]*?)\s*\[/SUGGEST_FIX\]", ai_content))
+    if not blocks:
+        return ai_content, None
+
+    # Take the last block — most-recent intent wins within a single turn.
+    last = blocks[-1]
+    raw = last.group(1).strip()
+    if raw.startswith("```"):
+        raw = re.sub(r"^```(?:json)?\s*", "", raw)
+        raw = re.sub(r"\s*```$", "", raw)
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError) as e:
+        logger.warning("Failed to parse [SUGGEST_FIX] block: %s", e)
+        return re.sub(r"\[SUGGEST_FIX\]\s*[\s\S]*?\s*\[/SUGGEST_FIX\]", "", ai_content).strip(), None
+
+    if not isinstance(data, dict):
+        return re.sub(r"\[SUGGEST_FIX\]\s*[\s\S]*?\s*\[/SUGGEST_FIX\]", "", ai_content).strip(), None
+
+    title = (data.get("title") or "").strip()
+    description = (data.get("description") or "").strip()
+    confidence = data.get("confidence")
+    if not title or not description or not isinstance(confidence, (int, float)):
+        logger.warning("[SUGGEST_FIX] missing required fields, dropping")
+        return re.sub(r"\[SUGGEST_FIX\]\s*[\s\S]*?\s*\[/SUGGEST_FIX\]", "", ai_content).strip(), None
+
+    confidence_int = max(0, min(100, int(round(float(confidence)))))
+
+    parsed = {
+        "title": title[:200],
+        "description": description,
+        "confidence_pct": confidence_int,
+        "script_template_slug": (data.get("script_template_slug") or None),
+        "ai_drafted_script": (data.get("ai_drafted_script") or None),
+        "ai_drafted_parameters": data.get("ai_drafted_parameters") if isinstance(data.get("ai_drafted_parameters"), dict) else None,
+    }
+
+    cleaned = re.sub(r"\[SUGGEST_FIX\]\s*[\s\S]*?\s*\[/SUGGEST_FIX\]", "", ai_content).strip()
+    return cleaned, parsed
+
+
+def _parse_fix_outcome_marker(
+    ai_content: str,
+) -> tuple[str, dict[str, Any] | None]:
+    """Extract a single [FIX_OUTCOME]...[/FIX_OUTCOME] JSON block.
+
+    Block shape:
+      {"fix_id": "<uuid>", "outcome": "success"|"failure"|"partial",
+       "reason": "<one-line>"}
+
+    Emitted by the AI when the engineer clearly indicates in chat that a
+    prior suggested fix worked, didn't work, or was partially applied.
+    The marker PROPOSES an outcome — the engineer confirms via the UI.
+    Only the last block in a response is honored.
+    """
+    blocks = list(re.finditer(
+        r"\[FIX_OUTCOME\]\s*([\s\S]*?)\s*\[/FIX_OUTCOME\]", ai_content,
+    ))
+    if not blocks:
+        return ai_content, None
+
+    last = blocks[-1]
+    raw = last.group(1).strip()
+    if raw.startswith("```"):
+        raw = re.sub(r"^```(?:json)?\s*", "", raw)
+        raw = re.sub(r"\s*```$", "", raw)
+
+    cleaned = re.sub(
+        r"\[FIX_OUTCOME\]\s*[\s\S]*?\s*\[/FIX_OUTCOME\]", "", ai_content,
+    ).strip()
+
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError) as e:
+        logger.warning("Failed to parse [FIX_OUTCOME] block: %s", e)
+        return cleaned, None
+
+    if not isinstance(data, dict):
+        return cleaned, None
+
+    fix_id = str(data.get("fix_id") or "").strip()
+    outcome = str(data.get("outcome") or "").strip().lower()
+    reason = str(data.get("reason") or "").strip()
+
+    if not fix_id or outcome not in {"success", "failure", "partial"}:
+        logger.warning("[FIX_OUTCOME] missing/invalid fields, dropping")
+        return cleaned, None
+
+    return cleaned, {"fix_id": fix_id, "outcome": outcome, "reason": reason}
+
+
+async def _persist_suggested_fix(
+    *,
+    db: AsyncSession,
+    session: AISession,
+    fix: dict[str, Any],
+) -> None:
+    """Supersede the prior active fix and insert the new one. Bumps state_version.
+
+    A session has at most one active suggested fix (`superseded_at IS NULL`).
+    Emitting [SUGGEST_FIX] is the only way to introduce a new one; the
+    engineer's user_decision is recorded via the decision endpoint.
+    """
+    now = datetime.now(timezone.utc)
+
+    # Mark any prior active rows for this session as superseded.
+    await db.execute(
+        update(SessionSuggestedFix)
+        .where(
+            SessionSuggestedFix.session_id == session.id,
+            SessionSuggestedFix.superseded_at.is_(None),
+        )
+        .values(superseded_at=now)
+    )
+
+    # Resolve script_template_slug → script_template_id if provided.
+    script_template_id = None
+    slug = fix.get("script_template_slug")
+    if slug:
+        result = await db.execute(
+            select(ScriptTemplate).where(ScriptTemplate.slug == slug)
+        )
+        tpl = result.scalar_one_or_none()
+        if tpl is not None:
+            script_template_id = tpl.id
+        else:
+            logger.warning(
+                "SUGGEST_FIX referenced unknown script_template_slug=%r — "
+                "treating as no template match", slug,
+            )
+
+    new_fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title=fix["title"],
+        description=fix["description"],
+        confidence_pct=fix["confidence_pct"],
+        script_template_id=script_template_id,
+        ai_drafted_script=fix.get("ai_drafted_script"),
+        ai_drafted_parameters=fix.get("ai_drafted_parameters"),
+    )
+    db.add(new_fix)
+
+    # Bump preview-cache version atomically with the supersession+insert.
+    await db.execute(
+        update(AISession)
+        .where(AISession.id == session.id)
+        .values(state_version=AISession.state_version + 1)
+    )
+    await db.flush()
+
+
+async def _record_ai_outcome_proposal(
+    *,
+    db: AsyncSession,
+    session: AISession,
+    proposal: dict[str, Any],
+) -> None:
+    """Persist the AI's proposed outcome on the active fix.
+
+    Writes to session_suggested_fixes.ai_outcome_proposal. Frontend polls
+    the active fix and renders the AI-confirming banner state when this is
+    non-null. Does NOT mutate the fix's status — the engineer's confirmation
+    click via PATCH /outcome is what changes the status.
+
+    Drops silently when the fix_id isn't a valid UUID or doesn't belong to
+    this session.
+    """
+    try:
+        fix_uuid = UUID(proposal["fix_id"])
+    except (ValueError, KeyError, TypeError):
+        logger.warning("[FIX_OUTCOME] invalid fix_id, dropping")
+        return
+
+    await db.execute(
+        update(SessionSuggestedFix)
+        .where(
+            SessionSuggestedFix.id == fix_uuid,
+            SessionSuggestedFix.session_id == session.id,
+        )
+        .values(ai_outcome_proposal=proposal)
+    )
+    await db.flush()
+
+
+async def _persist_promote_items(
+    *,
+    db: AsyncSession,
+    session: AISession,
+    user_id: UUID,
+    items: list[dict[str, Any]],
+) -> None:
+    """Persist parsed [PROMOTE] items as session_facts. Failures are logged.
+
+    A malformed PROMOTE must never break the chat response — the engineer
+    still gets the AI's analysis; the missing fact can be added manually.
+    """
+    if not items:
+        return
+    service = FactSynthesisService(db)
+    for item in items:
+        try:
+            await service.create_fact(
+                session_id=session.id,
+                account_id=session.account_id,
+                user_id=user_id,
+                source_type=item["source_type"],
+                text=item["text"],
+                summary=item["summary"],
+                source_ref=item["source_ref"],
+            )
+        except ValueError:
+            # Validation failure (e.g. empty text after strip, or
+            # source_ref-on-ai_synthesis race). Log and continue — losing
+            # one fact is better than aborting the whole chat turn.
+            logger.warning(
+                "Skipping invalid PROMOTE item for session %s: %r",
+                session.id, item, exc_info=True,
+            )
+        except Exception:
+            logger.exception(
+                "Failed to persist PROMOTE item for session %s", session.id
+            )
+
+
 async def create_chat_session(
     user_id: UUID,
     account_id: UUID,
@@ -251,10 +642,14 @@ async def send_chat_message(
             if session.status == "paused":
                 session.status = "active"
 
-            # Check for fork, actions, and questions markers in branch response too
+            # Check for fork, actions, questions, promote, and suggest_fix markers
+            # in branch response too
             branch_display, branch_fork_data = _parse_fork_marker(ai_content)
             branch_display, branch_actions_data = _parse_actions_marker(branch_display)
             branch_display, branch_questions_data = _parse_questions_marker(branch_display)
+            branch_display, branch_promote_items = _parse_promote_marker(branch_display)
+            branch_display, branch_suggest_fix = _parse_suggest_fix_marker(branch_display)
+            branch_display, branch_outcome_proposal = _parse_fix_outcome_marker(branch_display)
             if branch_display != ai_content:
                 # Store stripped content in branch history
                 msgs[-1] = {"role": "assistant", "content": branch_display}
@@ -288,15 +683,42 @@ async def send_chat_message(
                 except Exception:
                     logger.exception("Failed to create fork within branch for session %s", session.id)
 
-            # Persist task lane state on session
+            # Persist task lane state on session — assign stable UUIDs so any
+            # PROMOTE marker emitted later can reference the same items.
             if branch_questions_data or branch_actions_data:
+                stable_qs, stable_as = _assign_stable_task_lane_ids(
+                    session.pending_task_lane,
+                    branch_questions_data,
+                    branch_actions_data,
+                )
                 session.pending_task_lane = {
-                    "questions": branch_questions_data or [],
-                    "actions": branch_actions_data or [],
+                    "questions": stable_qs,
+                    "actions": stable_as,
                 }
             else:
                 session.pending_task_lane = None
 
+            # Persist any PROMOTE items emitted in this turn. Done AFTER the
+            # task-lane write so source_refs to brand-new items would still
+            # land on persisted UUIDs (the model can also reference IDs from
+            # the previous turn, which were already persisted).
+            if branch_promote_items:
+                await _persist_promote_items(
+                    db=db, session=session, user_id=user_id, items=branch_promote_items,
+                )
+
+            # Persist a [SUGGEST_FIX] if the branch turn included one.
+            if branch_suggest_fix:
+                await _persist_suggested_fix(
+                    db=db, session=session, fix=branch_suggest_fix,
+                )
+
+            # Persist a [FIX_OUTCOME] proposal if the branch turn included one.
+            if branch_outcome_proposal is not None:
+                await _record_ai_outcome_proposal(
+                    db=db, session=session, proposal=branch_outcome_proposal,
+                )
+
             suggested_flows = extract_suggested_flows(
                 await rag_search(query=message, account_id=account_id, db=db, limit=8)
             )
@@ -343,9 +765,22 @@ async def send_chat_message(
     # Check for questions marker in AI response
     display_content, questions_data = _parse_questions_marker(display_content)
 
+    # Check for promote markers — facts the AI is surfacing to What we know.
+    display_content, promote_items = _parse_promote_marker(display_content)
+
+    # Check for a [SUGGEST_FIX] marker — supersedes the prior active fix.
+    display_content, suggest_fix_data = _parse_suggest_fix_marker(display_content)
+
+    # Check for a [FIX_OUTCOME] proposal — AI confirms a prior fix's outcome.
+    display_content, outcome_proposal = _parse_fix_outcome_marker(display_content)
+
     logger.info(
-        "Marker parsing results — actions: %s, questions: %s, fork: %s, raw_length: %d, display_length: %d",
+        "Marker parsing results — actions: %s, questions: %s, fork: %s, "
+        "promote: %d, suggest_fix: %s, outcome_proposal: %s, "
+        "raw_length: %d, display_length: %d",
         bool(actions_data), bool(questions_data), bool(fork_data),
+        len(promote_items or []), bool(suggest_fix_data),
+        bool(outcome_proposal),
         len(ai_content), len(display_content),
     )
 
@@ -410,15 +845,36 @@ async def send_chat_message(
             logger.exception("Failed to create fork for session %s", session_id)
             # Fork failed but chat message still sent — don't break the response
 
-    # Persist task lane state on session
+    # Persist task lane state on session — assign stable UUIDs so any PROMOTE
+    # marker (this turn or a later one) can reference the same items.
     if questions_data or actions_data:
+        stable_qs, stable_as = _assign_stable_task_lane_ids(
+            session.pending_task_lane, questions_data, actions_data,
+        )
         session.pending_task_lane = {
-            "questions": questions_data or [],
-            "actions": actions_data or [],
+            "questions": stable_qs,
+            "actions": stable_as,
         }
     else:
         session.pending_task_lane = None
 
+    # Persist any PROMOTE items emitted in this turn. Done after task-lane
+    # assignment so source_refs the model invented this turn already exist.
+    if promote_items:
+        await _persist_promote_items(
+            db=db, session=session, user_id=user_id, items=promote_items,
+        )
+
+    # Persist a [SUGGEST_FIX] if this turn included one — supersedes prior fix.
+    if suggest_fix_data:
+        await _persist_suggested_fix(db=db, session=session, fix=suggest_fix_data)
+
+    # Persist a [FIX_OUTCOME] proposal if this turn included one.
+    if outcome_proposal is not None:
+        await _record_ai_outcome_proposal(
+            db=db, session=session, proposal=outcome_proposal,
+        )
+
     suggested_flows = extract_suggested_flows(rag_results)
 
     return display_content, suggested_flows, session, fork_metadata, actions_data, questions_data

backend/tests/conftest.py

@@ -14,21 +14,33 @@ from sqlalchemy.pool import NullPool
 
 from app.main import app
 from app.core.database import Base, get_db
+from app.core.admin_database import get_admin_db
 from app.core.config import settings
 
 # Disable invite code requirement for tests
 settings.REQUIRE_INVITE_CODE = False
 
-# Test database URL (separate from production)
-# Use DATABASE_TEST_URL env var if set (e.g. inside Docker where host is 'db'),
-# otherwise fall back to localhost for local development.
+# Test database URL — NEVER reuse DATABASE_URL. The test_db fixture does
+# `DROP SCHEMA public CASCADE` on every test; if DATABASE_URL (which normally
+# points at the dev/prod DB) leaked into this value, running `pytest tests/`
+# would silently nuke the dev database. Only DATABASE_TEST_URL is honored,
+# and the safety assertion below refuses to run against a DB whose name
+# doesn't contain "test".
 import os
 TEST_DATABASE_URL = os.environ.get(
-    "DATABASE_URL",
-    os.environ.get(
-        "DATABASE_TEST_URL",
-        "postgresql+asyncpg://postgres:postgres@localhost:5432/patherly_test",
-    ),
+    "DATABASE_TEST_URL",
+    "postgresql+asyncpg://postgres:postgres@localhost:5432/resolutionflow_test",
+)
+
+# Belt-and-suspenders: refuse to run tests against a DB whose name doesn't
+# contain "test". Parses the last path segment of the URL (everything after
+# the final '/', with query string stripped) so credentials / hosts that
+# happen to contain "test" can't bypass the check.
+_test_db_name = TEST_DATABASE_URL.rsplit("/", 1)[-1].split("?", 1)[0].lower()
+assert "test" in _test_db_name, (
+    f"Refusing to run tests against database {_test_db_name!r} — "
+    f"the DB name must contain 'test'. Set DATABASE_TEST_URL to a dedicated "
+    f"test database (e.g. resolutionflow_test)."
 )
 
 
@@ -131,6 +143,11 @@ async def client(test_db: AsyncSession):
         yield test_db
 
     app.dependency_overrides[get_db] = override_get_db
+    # Endpoints that use get_admin_db (register, admin routes, service accounts)
+    # must also hit the test DB; otherwise they leak into the real admin DB.
+    # RLS is not enabled in the test schema (create_all, not alembic), so sharing
+    # the same session is safe.
+    app.dependency_overrides[get_admin_db] = override_get_db
 
     transport = ASGITransport(app=app)
     async with AsyncClient(transport=transport, base_url="http://test") as ac:

backend/tests/test_admin.py

@@ -19,8 +19,116 @@ class TestAdminEndpoints:
             "/api/v1/admin/users", headers=admin_auth_headers
         )
         assert response.status_code == 200
-        users = response.json()
-        assert len(users) >= 2  # admin + test_user
+        payload = response.json()
+        assert payload["total"] >= 2  # admin + test_user
+        assert len(payload["items"]) >= 2
+
+    @pytest.mark.asyncio
+    async def test_list_users_supports_search(
+        self, client: AsyncClient, admin_auth_headers: dict, test_user: dict
+    ):
+        """Test admin people search by user email."""
+        response = await client.get(
+            "/api/v1/admin/users",
+            params={"search": test_user["email"]},
+            headers=admin_auth_headers,
+        )
+        assert response.status_code == 200
+        payload = response.json()
+        assert payload["total"] >= 1
+        assert any(item["email"] == test_user["email"] for item in payload["items"])
+
+    @pytest.mark.asyncio
+    async def test_list_accounts_as_admin(
+        self, client: AsyncClient, admin_auth_headers: dict
+    ):
+        """Test listing accounts with member data."""
+        response = await client.get(
+            "/api/v1/admin/accounts", headers=admin_auth_headers
+        )
+        assert response.status_code == 200
+        payload = response.json()
+        assert payload["total"] >= 1
+        assert len(payload["items"]) >= 1
+        assert "members" in payload["items"][0]
+        assert "subscription" in payload["items"][0]
+
+    @pytest.mark.asyncio
+    async def test_create_account_as_admin(
+        self, client: AsyncClient, admin_auth_headers: dict
+    ):
+        """Test creating an empty account from admin."""
+        response = await client.post(
+            "/api/v1/admin/accounts",
+            json={"name": "Acme Customer", "plan": "pro"},
+            headers=admin_auth_headers,
+        )
+        assert response.status_code == 201
+        payload = response.json()
+        assert payload["name"] == "Acme Customer"
+        assert payload["subscription"]["plan"] == "pro"
+        assert payload["display_code"]
+
+    @pytest.mark.asyncio
+    async def test_get_account_detail_as_admin(
+        self, client: AsyncClient, admin_auth_headers: dict, test_user: dict
+    ):
+        """Test fetching account detail for management view."""
+        account_id = test_user["user_data"]["account_id"]
+        response = await client.get(
+            f"/api/v1/admin/accounts/{account_id}",
+            headers=admin_auth_headers,
+        )
+        assert response.status_code == 200
+        payload = response.json()
+        assert payload["id"] == account_id
+        assert "members" in payload
+        assert "invites" in payload
+
+    @pytest.mark.asyncio
+    async def test_update_account_name_as_admin(
+        self, client: AsyncClient, admin_auth_headers: dict, test_user: dict
+    ):
+        """Test renaming an account from admin detail view."""
+        account_id = test_user["user_data"]["account_id"]
+        response = await client.put(
+            f"/api/v1/admin/accounts/{account_id}",
+            json={"name": "Renamed Customer Account"},
+            headers=admin_auth_headers,
+        )
+        assert response.status_code == 200
+        payload = response.json()
+        assert payload["id"] == account_id
+        assert payload["name"] == "Renamed Customer Account"
+
+    @pytest.mark.asyncio
+    async def test_update_account_plan(
+        self, client: AsyncClient, admin_auth_headers: dict, test_user: dict
+    ):
+        """Test changing an account's subscription plan."""
+        account_id = test_user["user_data"]["account_id"]
+        response = await client.put(
+            f"/api/v1/admin/accounts/{account_id}/subscription/plan",
+            json={"plan": "pro"},
+            headers=admin_auth_headers,
+        )
+        assert response.status_code == 200
+        assert response.json()["plan"] == "pro"
+
+    @pytest.mark.asyncio
+    async def test_extend_account_trial(
+        self, client: AsyncClient, admin_auth_headers: dict, test_user: dict
+    ):
+        """Test starting or extending an account trial."""
+        account_id = test_user["user_data"]["account_id"]
+        response = await client.put(
+            f"/api/v1/admin/accounts/{account_id}/subscription/extend-trial",
+            json={"days": 14},
+            headers=admin_auth_headers,
+        )
+        assert response.status_code == 200
+        assert response.json()["status"] == "trialing"
+        assert response.json()["current_period_end"] is not None
 
     @pytest.mark.asyncio
     async def test_list_users_as_non_admin(

backend/tests/test_fix_outcome_endpoint.py

@@ -0,0 +1,536 @@
+"""Integration tests for PATCH /ai-sessions/{sid}/suggested-fixes/{fid}/outcome.
+
+Fixture style follows test_session_suggested_fixes_api.py:
+  client, test_user, auth_headers, test_db
+"""
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, call, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.api.endpoints.session_suggested_fixes import _clear_preview_cache_for_tests
+from app.models.ai_session import AISession
+from app.models.session_suggested_fix import SessionSuggestedFix
+
+
+@pytest.fixture(autouse=True)
+def _isolate_preview_cache():
+    _clear_preview_cache_for_tests()
+    yield
+    _clear_preview_cache_for_tests()
+
+
+# ── shared helper ────────────────────────────────────────────────────────────
+
+async def _make_session_with_fix(test_db, user) -> tuple[str, str]:
+    """Create an AISession + active proposed SessionSuggestedFix.
+
+    Returns (session_id_str, fix_id_str).
+    """
+    session = AISession(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "outcome test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="Reset credential cache",
+        description="Clear stale credentials from the domain cache.",
+        confidence_pct=82,
+    )
+    test_db.add(fix)
+    await test_db.commit()
+    await test_db.refresh(fix)
+
+    return str(session.id), str(fix.id)
+
+
+# ── tests ────────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_patch_outcome_marks_success(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_success"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "applied_success"
+    assert body["verified_at"] is not None
+
+
+@pytest.mark.asyncio
+async def test_patch_outcome_partial_requires_notes(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_partial"},
+    )
+    assert r.status_code == 400
+    assert "notes" in r.text.lower()
+
+
+@pytest.mark.asyncio
+async def test_partial_to_success_allowed(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r1 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_partial", "notes": "ran cred clear only"},
+    )
+    assert r1.status_code == 200, r1.text
+
+    r2 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_success"},
+    )
+    assert r2.status_code == 200
+    assert r2.json()["status"] == "applied_success"
+
+
+@pytest.mark.asyncio
+async def test_terminal_outcome_is_locked(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r1 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_failed", "notes": "no change"},
+    )
+    assert r1.status_code == 200
+
+    r2 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_success"},
+    )
+    assert r2.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_partial_notes_can_be_updated(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """partial→partial with new notes updates the stored notes."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r1 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_partial", "notes": "ran cred clear only"},
+        headers=auth_headers,
+    )
+    assert r1.status_code == 200
+    assert r1.json()["partial_notes"] == "ran cred clear only"
+
+    r2 = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_partial", "notes": "also finished the rebuild; not verified yet"},
+        headers=auth_headers,
+    )
+    assert r2.status_code == 200
+    assert r2.json()["partial_notes"] == "also finished the rebuild; not verified yet"
+
+
+@pytest.mark.asyncio
+async def test_dismissed_sets_no_timestamps(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """dismissed outcome does not stamp applied_at or verified_at."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "dismissed"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["status"] == "dismissed"
+    assert body["applied_at"] is None
+    assert body["verified_at"] is None
+
+
+@pytest.mark.asyncio
+async def test_applied_at_auto_stamped_on_first_outcome(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """If applied_at is null when the engineer sets outcome, server stamps it."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_success"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["applied_at"] is not None
+    assert body["verified_at"] is not None
+
+
+@pytest.mark.asyncio
+async def test_failed_outcome_stores_notes_as_failure_reason(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """applied_failed stores notes under failure_reason (not partial_notes)."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_failed", "notes": "user reports no change"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["failure_reason"] == "user reports no change"
+    assert body["partial_notes"] is None
+
+
+# ── state_version bump ────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_outcome_patch_bumps_state_version(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """PATCH /outcome must increment ai_sessions.state_version (like record_decision)."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    # Capture the initial state_version from DB.
+    from uuid import UUID
+    result = await test_db.execute(
+        select(AISession).where(AISession.id == UUID(session_id))
+    )
+    session_obj = result.scalar_one()
+    initial_version = session_obj.state_version
+
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        json={"outcome": "applied_success"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 200
+
+    await test_db.refresh(session_obj)
+    assert session_obj.state_version == initial_version + 1, (
+        "Outcome patch must bump state_version so preview cache is invalidated"
+    )
+
+
+# ── outcome propagation into preview bundle ───────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_resolution_note_preview_reflects_outcome_after_patch(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """End-to-end: preview before outcome != preview after outcome; new preview
+    bundle includes failure_reason; state_version was bumped between the two.
+
+    The LLM is stubbed so the test is deterministic. The stub returns whatever
+    the user-message content is, which means the captured call args reflect
+    what the bundle actually contained.
+    """
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    distinct_failure_reason = "DISTINCT-FAILURE-REASON-XYZZY-42"
+
+    calls_made: list[str] = []
+
+    async def fake_generate_text(system_prompt, messages, max_tokens):
+        user_content = messages[0]["content"]
+        calls_made.append(user_content)
+        # Return markdown that includes the user-message bundle verbatim so we
+        # can assert the bundle shape without inspecting mock internals.
+        return (
+            f"## Problem\ntest\n\n## What we confirmed\n(none)\n\n"
+            f"## Root cause\ntest\n\n## Resolution\nBUNDLE_CONTENT={user_content}",
+            100,
+            50,
+        )
+
+    fake_provider = AsyncMock()
+    fake_provider.generate_text = AsyncMock(side_effect=fake_generate_text)
+
+    with patch(
+        "app.services.resolution_note_generator.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        # Preview A — before any outcome recorded (status = "proposed").
+        r_a = await client.post(
+            f"/api/v1/ai-sessions/{session_id}/resolution-note/preview",
+            headers=auth_headers,
+        )
+        assert r_a.status_code == 200
+        markdown_a = r_a.json()["markdown"]
+        version_a = r_a.json()["state_version"]
+        assert r_a.json()["from_cache"] is False
+
+        # Record an applied_failed outcome with a distinctive reason.
+        r_patch = await client.patch(
+            f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+            json={"outcome": "applied_failed", "notes": distinct_failure_reason},
+            headers=auth_headers,
+        )
+        assert r_patch.status_code == 200
+
+        # Preview B — must be a cache miss because state_version changed.
+        r_b = await client.post(
+            f"/api/v1/ai-sessions/{session_id}/resolution-note/preview",
+            headers=auth_headers,
+        )
+        assert r_b.status_code == 200
+        markdown_b = r_b.json()["markdown"]
+        version_b = r_b.json()["state_version"]
+        assert r_b.json()["from_cache"] is False, (
+            "Preview after outcome patch must be a cache miss (state_version changed)"
+        )
+
+    # State version increased between the two previews.
+    assert version_b > version_a, (
+        f"state_version should have increased; got {version_a} → {version_b}"
+    )
+
+    # Markdown differs between the two previews.
+    assert markdown_a != markdown_b, (
+        "Regenerated preview after outcome patch should differ from pre-outcome preview"
+    )
+
+    # The bundle passed to the LLM for preview B includes the outcome fields.
+    assert len(calls_made) == 2, f"Expected 2 LLM calls (one per preview); got {len(calls_made)}"
+    bundle_b = calls_made[1]
+    assert "applied_failed" in bundle_b, (
+        "Bundle for second preview should include 'Outcome status: applied_failed'"
+    )
+    assert distinct_failure_reason in bundle_b, (
+        "Bundle for second preview should include the failure_reason text"
+    )
+
+
+# ── Apply endpoint ─────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_apply_stamps_applied_at(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """POST /apply stamps applied_at and bumps state_version."""
+    from uuid import UUID
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    result = await test_db.execute(
+        select(AISession).where(AISession.id == UUID(session_id))
+    )
+    session_obj = result.scalar_one()
+    initial_version = session_obj.state_version
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/apply",
+        headers=auth_headers,
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["applied_at"] is not None, "applied_at must be set after /apply"
+    assert body["status"] == "proposed", "status must remain 'proposed' after /apply"
+
+    await test_db.refresh(session_obj)
+    assert session_obj.state_version == initial_version + 1, (
+        "/apply must bump state_version so preview cache is invalidated"
+    )
+
+
+@pytest.mark.asyncio
+async def test_apply_is_idempotent(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """Second POST /apply returns 200 with applied_at unchanged (no double-bump)."""
+    from uuid import UUID
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r1 = await client.post(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/apply",
+        headers=auth_headers,
+    )
+    assert r1.status_code == 200, r1.text
+    applied_at_first = r1.json()["applied_at"]
+
+    result = await test_db.execute(
+        select(AISession).where(AISession.id == UUID(session_id))
+    )
+    session_obj = result.scalar_one()
+    version_after_first = session_obj.state_version
+
+    r2 = await client.post(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/apply",
+        headers=auth_headers,
+    )
+    assert r2.status_code == 200, r2.text
+    assert r2.json()["applied_at"] == applied_at_first, (
+        "applied_at must not change on second /apply call"
+    )
+
+    await test_db.refresh(session_obj)
+    assert session_obj.state_version == version_after_first, (
+        "state_version must not be bumped a second time on idempotent /apply"
+    )
+
+
+@pytest.mark.asyncio
+async def test_apply_rejects_non_proposed(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """POST /apply returns 409 when fix status is 'applied_success'."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    # Advance the fix to a terminal status via the outcome endpoint.
+    r_outcome = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_success"},
+    )
+    assert r_outcome.status_code == 200
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/apply",
+        headers=auth_headers,
+    )
+    assert r.status_code == 409, r.text
+
+
+@pytest.mark.asyncio
+async def test_apply_rejects_dismissed(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """POST /apply returns 409 when fix status is 'dismissed'."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    r_outcome = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "dismissed"},
+    )
+    assert r_outcome.status_code == 200
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/apply",
+        headers=auth_headers,
+    )
+    assert r.status_code == 409, r.text
+
+
+# ── AI outcome proposal: clear / reject ───────────────────────────────────────
+
+async def _make_session_with_fix_and_proposal(test_db, user) -> tuple[str, str]:
+    """Create an AISession + fix with a populated ai_outcome_proposal."""
+    from uuid import UUID as _UUID
+    session = AISession(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "proposal clear test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="Flush DNS cache",
+        description="Run ipconfig /flushdns on the affected host.",
+        confidence_pct=74,
+        ai_outcome_proposal={"fix_id": str(session.id), "outcome": "success", "reason": "User confirmed resolved"},
+    )
+    test_db.add(fix)
+    await test_db.commit()
+    await test_db.refresh(fix)
+
+    return str(session.id), str(fix.id)
+
+
+@pytest.mark.asyncio
+async def test_outcome_patch_clears_ai_proposal(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """PATCH /outcome clears ai_outcome_proposal regardless of which outcome is written."""
+    session_id, fix_id = await _make_session_with_fix_and_proposal(test_db, test_user)
+
+    # Verify the proposal is set before the patch.
+    from uuid import UUID
+    result = await test_db.execute(
+        select(SessionSuggestedFix).where(SessionSuggestedFix.id == UUID(fix_id))
+    )
+    fix_before = result.scalar_one()
+    assert fix_before.ai_outcome_proposal is not None
+
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/outcome",
+        headers=auth_headers,
+        json={"outcome": "applied_success"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["ai_outcome_proposal"] is None, (
+        "PATCH /outcome must clear ai_outcome_proposal on any terminal action"
+    )
+
+
+@pytest.mark.asyncio
+async def test_delete_ai_proposal_clears_field(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """DELETE /ai-outcome-proposal clears the field without changing status."""
+    session_id, fix_id = await _make_session_with_fix_and_proposal(test_db, test_user)
+
+    r = await client.delete(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/ai-outcome-proposal",
+        headers=auth_headers,
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["ai_outcome_proposal"] is None, (
+        "DELETE /ai-outcome-proposal must clear the field"
+    )
+    assert body["status"] == "proposed", (
+        "DELETE /ai-outcome-proposal must not change fix status"
+    )
+
+
+@pytest.mark.asyncio
+async def test_delete_ai_proposal_when_none_is_idempotent(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """DELETE /ai-outcome-proposal returns 200 even when the field is already null."""
+    session_id, fix_id = await _make_session_with_fix(test_db, test_user)
+
+    # Fix created by _make_session_with_fix has ai_outcome_proposal=None.
+    r = await client.delete(
+        f"/api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/ai-outcome-proposal",
+        headers=auth_headers,
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["ai_outcome_proposal"] is None

backend/tests/test_fix_outcome_marker.py

@@ -0,0 +1,91 @@
+"""Unit tests for the [FIX_OUTCOME] marker parser."""
+from __future__ import annotations
+
+from app.services.unified_chat_service import _parse_fix_outcome_marker
+
+
+def test_parses_success_outcome():
+    ai = (
+        "Great news — that confirms the root cause.\n\n"
+        "[FIX_OUTCOME]\n"
+        '{"fix_id":"11111111-1111-1111-1111-111111111111",'
+        '"outcome":"success","reason":"user said the fix worked"}\n'
+        "[/FIX_OUTCOME]\n"
+    )
+    cleaned, parsed = _parse_fix_outcome_marker(ai)
+    assert "[FIX_OUTCOME]" not in cleaned
+    assert "confirms the root cause" in cleaned
+    assert parsed == {
+        "fix_id": "11111111-1111-1111-1111-111111111111",
+        "outcome": "success",
+        "reason": "user said the fix worked",
+    }
+
+
+def test_parses_failure_outcome():
+    ai = (
+        "[FIX_OUTCOME]\n"
+        '{"fix_id":"22222222-2222-2222-2222-222222222222",'
+        '"outcome":"failure","reason":"user reports still broken"}\n'
+        "[/FIX_OUTCOME]"
+    )
+    cleaned, parsed = _parse_fix_outcome_marker(ai)
+    assert "[FIX_OUTCOME]" not in cleaned
+    assert parsed["outcome"] == "failure"
+
+
+def test_missing_marker_returns_none():
+    ai = "no marker here"
+    cleaned, parsed = _parse_fix_outcome_marker(ai)
+    assert cleaned == ai
+    assert parsed is None
+
+
+def test_invalid_json_is_dropped():
+    ai = "[FIX_OUTCOME]\nnot-json\n[/FIX_OUTCOME]"
+    cleaned, parsed = _parse_fix_outcome_marker(ai)
+    assert "[FIX_OUTCOME]" not in cleaned
+    assert parsed is None
+
+
+def test_unknown_outcome_rejected():
+    ai = (
+        "[FIX_OUTCOME]\n"
+        '{"fix_id":"33333333-3333-3333-3333-333333333333",'
+        '"outcome":"maybe","reason":"x"}\n'
+        "[/FIX_OUTCOME]"
+    )
+    _, parsed = _parse_fix_outcome_marker(ai)
+    assert parsed is None
+
+
+def test_last_block_wins_when_multiple():
+    ai = (
+        "[FIX_OUTCOME]\n"
+        '{"fix_id":"44444444-4444-4444-4444-444444444444",'
+        '"outcome":"failure","reason":"first"}\n'
+        "[/FIX_OUTCOME]\n"
+        "[FIX_OUTCOME]\n"
+        '{"fix_id":"55555555-5555-5555-5555-555555555555",'
+        '"outcome":"success","reason":"second"}\n'
+        "[/FIX_OUTCOME]"
+    )
+    cleaned, parsed = _parse_fix_outcome_marker(ai)
+    assert "[FIX_OUTCOME]" not in cleaned
+    assert parsed["fix_id"] == "55555555-5555-5555-5555-555555555555"
+    assert parsed["outcome"] == "success"
+
+
+def test_parses_partial_outcome():
+    ai = (
+        "[FIX_OUTCOME]\n"
+        '{"fix_id":"66666666-6666-6666-6666-666666666666",'
+        '"outcome":"partial","reason":"user ran cred clear only"}\n'
+        "[/FIX_OUTCOME]"
+    )
+    _, parsed = _parse_fix_outcome_marker(ai)
+    assert parsed == {
+        "fix_id": "66666666-6666-6666-6666-666666666666",
+        "outcome": "partial",
+        "reason": "user ran cred clear only",
+    }

backend/tests/test_fix_script_endpoint.py

@@ -0,0 +1,120 @@
+"""Integration tests for PATCH /ai-sessions/{sid}/suggested-fixes/{fid}/script."""
+from __future__ import annotations
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+from uuid import UUID, uuid4
+
+from app.models.ai_session import AISession
+from app.models.session_suggested_fix import SessionSuggestedFix
+
+
+async def _make_session_with_fix(
+    test_db, user, *, status: str = "proposed", with_script: bool = False,
+) -> tuple[str, str]:
+    """Create a pilot session + suggested fix for tests. Returns (sid, fid)."""
+    session = AISession(
+        id=uuid4(),
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="tshoot",
+        intake_type="psa_ticket",
+        intake_content={},
+        title="QA",
+        status="active",
+        confidence_tier="exploring",
+        confidence_score=0.0,
+    )
+    test_db.add(session)
+    await test_db.flush()
+    fix = SessionSuggestedFix(
+        id=uuid4(),
+        session_id=session.id,
+        account_id=user["user_data"]["account_id"],
+        title="QA: test fix",
+        description="desc",
+        confidence_pct=80,
+        status=status,
+        ai_drafted_script="pre-existing" if with_script else None,
+    )
+    test_db.add(fix)
+    await test_db.commit()
+    return str(session.id), str(fix.id)
+
+
+@pytest.mark.asyncio
+async def test_patch_script_happy_path(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    sid, fid = await _make_session_with_fix(test_db, test_user)
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/script",
+        json={"ai_drafted_script": "Write-Host 'hello'"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["ai_drafted_script"] == "Write-Host 'hello'"
+    assert body["applied_at"] is None  # draft != apply
+    assert body["status"] == "proposed"
+
+
+@pytest.mark.asyncio
+async def test_patch_script_bumps_state_version(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    sid, fid = await _make_session_with_fix(test_db, test_user)
+    before = await test_db.scalar(
+        select(AISession.state_version).where(AISession.id == UUID(sid))
+    )
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/script",
+        json={"ai_drafted_script": "echo hi"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 200
+    after = await test_db.scalar(
+        select(AISession.state_version).where(AISession.id == UUID(sid))
+    )
+    assert after == (before or 0) + 1
+
+
+@pytest.mark.asyncio
+async def test_patch_script_rejects_terminal_fix(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    sid, fid = await _make_session_with_fix(test_db, test_user, status="applied_success")
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/script",
+        json={"ai_drafted_script": "echo hi"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_patch_script_rejects_empty_body(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    sid, fid = await _make_session_with_fix(test_db, test_user)
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/script",
+        json={"ai_drafted_script": ""},
+        headers=auth_headers,
+    )
+    assert r.status_code == 422  # pydantic min_length=1
+
+
+@pytest.mark.asyncio
+async def test_patch_script_404_on_wrong_session(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    _, fid = await _make_session_with_fix(test_db, test_user)
+    wrong_sid = str(uuid4())
+    r = await client.patch(
+        f"/api/v1/ai-sessions/{wrong_sid}/suggested-fixes/{fid}/script",
+        json={"ai_drafted_script": "echo hi"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 404

backend/tests/test_network_diagrams.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from sqlalchemy import select
+
+from app.models.device_type import DeviceType
+from app.models.user import User
+from app.core.service_account import PLATFORM_ACCOUNT_ID
+
+
+async def _login_headers(client, email: str, password: str) -> dict[str, str]:
+    response = await client.post(
+        "/api/v1/auth/login/json",
+        json={"email": email, "password": password},
+    )
+    assert response.status_code == 200
+    token = response.json()["access_token"]
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.mark.asyncio
+async def test_device_types_include_platform_and_account_custom(client, test_db, auth_headers, test_user):
+    result = await test_db.execute(select(User).where(User.email == test_user["email"]))
+    user = result.scalar_one()
+
+    test_db.add(
+        DeviceType(
+            id=uuid.uuid4(),
+            slug="platform-router",
+            label="Platform Router",
+            category="network",
+            is_system=True,
+            account_id=PLATFORM_ACCOUNT_ID,
+            sort_order=0,
+        )
+    )
+    await test_db.commit()
+
+    create_response = await client.post(
+        "/api/v1/device-types/",
+        json={
+            "slug": "tenant-appliance",
+            "label": "Tenant Appliance",
+            "category": "network",
+            "sort_order": 3,
+        },
+        headers=auth_headers,
+    )
+    assert create_response.status_code == 201
+    assert create_response.json()["account_id"] == str(user.account_id)
+
+    list_response = await client.get("/api/v1/device-types/", headers=auth_headers)
+    assert list_response.status_code == 200
+    payload = list_response.json()
+    slugs = {item["slug"] for item in payload}
+
+    assert "platform-router" in slugs
+    assert "tenant-appliance" in slugs
+
+
+@pytest.mark.asyncio
+async def test_network_diagrams_are_account_scoped(client, test_db, auth_headers, test_user):
+    other_user = {
+        "email": "other-network@example.com",
+        "password": "TestPassword123!",
+        "name": "Other Network User",
+    }
+    register_response = await client.post("/api/v1/auth/register", json=other_user)
+    assert register_response.status_code in (200, 201)
+    other_headers = await _login_headers(client, other_user["email"], other_user["password"])
+
+    owner_result = await test_db.execute(select(User).where(User.email == test_user["email"]))
+    owner = owner_result.scalar_one()
+
+    create_response = await client.post(
+        "/api/v1/network-diagrams/",
+        json={
+            "name": "HQ Core",
+            "client_name": "Acme",
+            "description": "Primary topology",
+            "nodes": [],
+            "edges": [],
+        },
+        headers=auth_headers,
+    )
+    assert create_response.status_code == 201
+    diagram = create_response.json()
+    assert diagram["account_id"] == str(owner.account_id)
+
+    own_get = await client.get(f"/api/v1/network-diagrams/{diagram['id']}", headers=auth_headers)
+    assert own_get.status_code == 200
+
+    other_get = await client.get(f"/api/v1/network-diagrams/{diagram['id']}", headers=other_headers)
+    assert other_get.status_code == 404

backend/tests/test_phase5_inline_script.py

@@ -0,0 +1,277 @@
+"""API + service tests for Phase 5 inline Script Generator integration.
+
+Covers:
+- TemplateExtractionService: well-formed, fallback on bad output, missing-key fallback.
+- /suggested-fixes/{fix_id}/decision side effects:
+  * one_off returns rendered_script, no draft_templates row.
+  * draft_template returns rendered_script + draft_template_id, draft persisted.
+  * build_template returns redirect_path.
+  * dismissed (Phase 3) still works.
+- 400 when ai_drafted_script is missing for a non-template fix.
+"""
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.api.endpoints.session_suggested_fixes import _clear_preview_cache_for_tests
+from app.models.ai_session import AISession
+from app.models.draft_template import DraftTemplate
+from app.models.session_suggested_fix import SessionSuggestedFix
+from app.services.template_extraction_service import (
+    _fallback,
+    _parse_response,
+    extract_parameters,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_preview_cache():
+    _clear_preview_cache_for_tests()
+    yield
+    _clear_preview_cache_for_tests()
+
+
+async def _make_session_with_fix(
+    test_db, user, *, with_template_id: bool = False, with_drafted_script: bool = True,
+) -> tuple[AISession, SessionSuggestedFix]:
+    session = AISession(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "phase 5 test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="Reset cached creds",
+        description="Clearing the cached credential...",
+        confidence_pct=85,
+        ai_drafted_script=(
+            'cmdkey /delete:"outlook.office365.com"\n'
+            'Restart-Process -Name OUTLOOK'
+        ) if with_drafted_script else None,
+        ai_drafted_parameters={"target_user": "jsmith"} if with_drafted_script else None,
+    )
+    test_db.add(fix)
+    await test_db.commit()
+    await test_db.refresh(session)
+    await test_db.refresh(fix)
+    return session, fix
+
+
+# ── TemplateExtractionService: parse + fallback ───────────────────────────
+
+class TestParseResponse:
+    def test_well_formed(self):
+        raw = (
+            '{"parameters": [{"key":"host","label":"Host","type":"text",'
+            '"inferred_from":"session fact"}],'
+            '"templated_body":"Get-Service -ComputerName {{ host }}"}'
+        )
+        result = _parse_response(raw)
+        assert result is not None
+        assert len(result["parameters"]) == 1
+        assert result["parameters"][0]["key"] == "host"
+        assert result["templated_body"].endswith("{{ host }}")
+
+    def test_strips_fences(self):
+        raw = '```json\n{"parameters": [], "templated_body": "x"}\n```'
+        result = _parse_response(raw)
+        assert result is not None and result["parameters"] == []
+
+    def test_invalid_key_dropped(self):
+        # Capital letters and dashes in key names violate snake_case — drop.
+        raw = (
+            '{"parameters":[{"key":"BadKey-Name","type":"text"}],'
+            '"templated_body":"x"}'
+        )
+        result = _parse_response(raw)
+        assert result is not None and result["parameters"] == []
+
+    def test_unknown_type_falls_back_to_text(self):
+        raw = (
+            '{"parameters":[{"key":"x","type":"weird"}],"templated_body":"x"}'
+        )
+        result = _parse_response(raw)
+        assert result is not None and result["parameters"][0]["type"] == "text"
+
+    def test_malformed_json_returns_none(self):
+        assert _parse_response("not json") is None
+
+    def test_non_dict_returns_none(self):
+        assert _parse_response('["a","b"]') is None
+
+
+@pytest.mark.asyncio
+async def test_extract_parameters_round_trip_failure_uses_fallback():
+    """Templated_body referencing an undeclared placeholder triggers fallback."""
+    fake_provider = AsyncMock()
+    fake_provider.generate_json = AsyncMock(return_value=(
+        # Declares parameter `host` but the body references `port` too.
+        '{"parameters":[{"key":"host","label":"Host","type":"text"}],'
+        '"templated_body":"Get-Service -ComputerName {{ host }} -Port {{ port }}"}',
+        100, 50,
+    ))
+    with patch(
+        "app.services.template_extraction_service.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        result = await extract_parameters(
+            script_body="Get-Service -ComputerName srv01 -Port 8080",
+        )
+    fb = _fallback("Get-Service -ComputerName srv01 -Port 8080")
+    assert result == fb
+
+
+@pytest.mark.asyncio
+async def test_extract_parameters_llm_exception_uses_fallback():
+    fake_provider = AsyncMock()
+    fake_provider.generate_json = AsyncMock(side_effect=RuntimeError("boom"))
+    with patch(
+        "app.services.template_extraction_service.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        result = await extract_parameters(script_body="echo hello")
+    assert result == _fallback("echo hello")
+
+
+# ── Decision endpoint: one_off ─────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_one_off_returns_rendered_script_no_draft(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session, fix = await _make_session_with_fix(test_db, test_user)
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={"decision": "one_off"},
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["user_decision"] == "one_off"
+    assert body["rendered_script"] is not None
+    assert "cmdkey" in body["rendered_script"]
+    assert body["draft_template_id"] is None
+    assert body["redirect_path"] is None
+
+    # No draft_templates row should have been created.
+    rows = (
+        await test_db.execute(select(DraftTemplate).where(DraftTemplate.source_session_id == session.id))
+    ).scalars().all()
+    assert list(rows) == []
+
+
+# ── Decision endpoint: draft_template ─────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_draft_template_creates_draft_with_extracted_params(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session, fix = await _make_session_with_fix(test_db, test_user)
+
+    fake_provider = AsyncMock()
+    fake_provider.generate_json = AsyncMock(return_value=(
+        '{"parameters":[{"key":"target_user","label":"Target User","type":"text",'
+        '"inferred_from":"session fact"}],'
+        '"templated_body":"cmdkey /delete:\\"outlook.office365.com\\"\\n'
+        'Restart-Process -Name OUTLOOK"}',
+        80, 60,
+    ))
+
+    with patch(
+        "app.services.template_extraction_service.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        r = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+            headers=auth_headers,
+            json={"decision": "draft_template"},
+        )
+
+    assert r.status_code == 200
+    body = r.json()
+    assert body["user_decision"] == "draft_template"
+    assert body["rendered_script"] is not None
+    assert body["draft_template_id"] is not None
+    assert body["redirect_path"] is None
+
+    drafts = (
+        await test_db.execute(select(DraftTemplate).where(DraftTemplate.source_session_id == session.id))
+    ).scalars().all()
+    drafts = list(drafts)
+    assert len(drafts) == 1
+    draft = drafts[0]
+    assert draft.status == "pending"
+    assert draft.proposed_name == fix.title
+    proposed = draft.proposed_parameters.get("parameters") if isinstance(draft.proposed_parameters, dict) else None
+    assert isinstance(proposed, list) and len(proposed) == 1
+    assert proposed[0]["key"] == "target_user"
+
+
+# ── Decision endpoint: build_template ─────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_build_template_returns_redirect_path(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session, fix = await _make_session_with_fix(test_db, test_user)
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={"decision": "build_template"},
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["redirect_path"] is not None
+    assert str(session.id) in body["redirect_path"]
+    assert str(fix.id) in body["redirect_path"]
+
+
+# ── Decision endpoint: 400 when no drafted script ─────────────────────────
+
+@pytest.mark.asyncio
+async def test_one_off_without_drafted_script_returns_400(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """A template-matched fix takes the dedicated /scripts/generate path; trying
+    to one_off it via this endpoint without an ai_drafted_script must surface
+    a clear client-error, not silently render nothing."""
+    session, fix = await _make_session_with_fix(test_db, test_user, with_drafted_script=False)
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={"decision": "one_off"},
+    )
+    assert r.status_code == 400
+    assert "ai_drafted_script" in r.json()["detail"]
+
+
+# ── Decision endpoint: edited script overrides ai_drafted_script ──────────
+
+@pytest.mark.asyncio
+async def test_edited_script_overrides_ai_drafted(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session, fix = await _make_session_with_fix(test_db, test_user)
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={
+            "decision": "one_off",
+            "edited_script": "Get-Service -Name Dnscache",
+        },
+    )
+    assert r.status_code == 200
+    assert r.json()["rendered_script"] == "Get-Service -Name Dnscache"

backend/tests/test_phase6_draft_templates.py

@@ -0,0 +1,295 @@
+"""API tests for the FlowPilot Phase 6 post-resolve templatization flow.
+
+Covers:
+- GET /api/v1/draft-templates list with pending_only filter.
+- POST /{id}/accept → creates script_templates row with provenance fields,
+  marks draft accepted + promoted_template_id set.
+- POST /{id}/reject → marks rejected.
+- 409 when accepting or rejecting a non-pending draft.
+- Category validation (400 on unknown category_id).
+- GET/PATCH /accounts/me/preferences round-trip.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import UUID
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.models.account_settings import AccountSettings
+from app.models.ai_session import AISession
+from app.models.draft_template import DraftTemplate
+from app.models.script_template import ScriptCategory, ScriptTemplate
+
+
+async def _make_draft(
+    test_db,
+    user,
+    *,
+    proposed_name: str = "Test draft",
+    status_: str = "pending",
+    with_psa_ticket: bool = False,
+) -> tuple[AISession, DraftTemplate]:
+    session = AISession(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "phase 6 test"},
+        status="resolved",
+        confidence_tier="discovery",
+        conversation_messages=[],
+        psa_ticket_id="48307" if with_psa_ticket else None,
+    )
+    test_db.add(session)
+    await test_db.flush()
+
+    draft = DraftTemplate(
+        account_id=user["user_data"]["account_id"],
+        source_session_id=session.id,
+        source_user_id=user["user_data"]["id"],
+        script_body='Do-Something -Target {{ target_name }}\n',
+        proposed_parameters={
+            "parameters": [
+                {"key": "target_name", "label": "Target Name", "type": "text"},
+            ],
+        },
+        proposed_name=proposed_name,
+        status=status_,
+    )
+    test_db.add(draft)
+    await test_db.commit()
+    await test_db.refresh(draft)
+    return session, draft
+
+
+async def _make_category(test_db) -> ScriptCategory:
+    cat = ScriptCategory(
+        name="Phase 6 Test Category",
+        slug=f"phase-6-test-{datetime.now(timezone.utc).timestamp()}",
+        description="test",
+        is_active=True,
+    )
+    test_db.add(cat)
+    await test_db.commit()
+    await test_db.refresh(cat)
+    return cat
+
+
+# ── List ─────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_list_pending_only_default(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    await _make_draft(test_db, test_user, proposed_name="pending-a", status_="pending")
+    await _make_draft(test_db, test_user, proposed_name="accepted-b", status_="accepted")
+
+    r = await client.get("/api/v1/draft-templates", headers=auth_headers)
+    assert r.status_code == 200
+    drafts = r.json()["drafts"]
+    names = {d["proposed_name"] for d in drafts}
+    assert "pending-a" in names
+    assert "accepted-b" not in names
+
+
+@pytest.mark.asyncio
+async def test_list_with_pending_only_false_includes_all(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    await _make_draft(test_db, test_user, proposed_name="pending-c", status_="pending")
+    await _make_draft(test_db, test_user, proposed_name="rejected-d", status_="rejected")
+
+    r = await client.get(
+        "/api/v1/draft-templates?pending_only=false", headers=auth_headers,
+    )
+    assert r.status_code == 200
+    names = {d["proposed_name"] for d in r.json()["drafts"]}
+    assert {"pending-c", "rejected-d"}.issubset(names)
+
+
+# ── Accept ───────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_accept_creates_template_with_provenance(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session, draft = await _make_draft(test_db, test_user, with_psa_ticket=True)
+    cat = await _make_category(test_db)
+
+    r = await client.post(
+        f"/api/v1/draft-templates/{draft.id}/accept",
+        headers=auth_headers,
+        json={
+            "name": "Do Something On Target",
+            "category_id": str(cat.id),
+            "description": "promoted from phase 6 test",
+            "parameters_schema": {
+                "parameters": [
+                    {"key": "target_name", "label": "Target", "field_type": "text"},
+                ],
+            },
+        },
+    )
+    assert r.status_code == 201
+    body = r.json()
+    assert body["draft_id"] == str(draft.id)
+    assert body["promoted_template_id"] is not None
+    assert body["template_slug"] == "do-something-on-target"
+
+    # Draft row is now accepted with the promoted template ID set.
+    await test_db.refresh(draft)
+    assert draft.status == "accepted"
+    assert draft.promoted_template_id == UUID(body["promoted_template_id"])
+    assert draft.resolved_at is not None
+
+    # New template row exists with provenance fields populated.
+    tpl_result = await test_db.execute(
+        select(ScriptTemplate).where(ScriptTemplate.id == UUID(body["promoted_template_id"]))
+    )
+    tpl = tpl_result.scalar_one()
+    assert tpl.source_session_id == session.id
+    assert tpl.source_user_id == UUID(test_user["user_data"]["id"])
+    assert tpl.source_ticket_ref == "CW #48307"
+    assert tpl.script_body == draft.script_body  # edited_body was not supplied
+
+
+@pytest.mark.asyncio
+async def test_accept_with_edited_body_overrides_draft(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    _, draft = await _make_draft(test_db, test_user)
+    cat = await _make_category(test_db)
+
+    r = await client.post(
+        f"/api/v1/draft-templates/{draft.id}/accept",
+        headers=auth_headers,
+        json={
+            "name": "Edited Body Test",
+            "category_id": str(cat.id),
+            "parameters_schema": {"parameters": []},
+            "edited_body": 'Write-Host "edited final version"\n',
+        },
+    )
+    assert r.status_code == 201
+    tpl = (
+        await test_db.execute(
+            select(ScriptTemplate).where(
+                ScriptTemplate.id == UUID(r.json()["promoted_template_id"])
+            )
+        )
+    ).scalar_one()
+    assert tpl.script_body == 'Write-Host "edited final version"\n'
+
+
+@pytest.mark.asyncio
+async def test_accept_rejects_unknown_category(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    _, draft = await _make_draft(test_db, test_user)
+    bogus_cat = "00000000-0000-0000-0000-000000000000"
+    r = await client.post(
+        f"/api/v1/draft-templates/{draft.id}/accept",
+        headers=auth_headers,
+        json={
+            "name": "x",
+            "category_id": bogus_cat,
+            "parameters_schema": {"parameters": []},
+        },
+    )
+    assert r.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_accept_already_accepted_returns_409(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    _, draft = await _make_draft(test_db, test_user, status_="accepted")
+    cat = await _make_category(test_db)
+    r = await client.post(
+        f"/api/v1/draft-templates/{draft.id}/accept",
+        headers=auth_headers,
+        json={
+            "name": "x",
+            "category_id": str(cat.id),
+            "parameters_schema": {"parameters": []},
+        },
+    )
+    assert r.status_code == 409
+
+
+# ── Reject ───────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_reject_marks_draft_rejected(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    _, draft = await _make_draft(test_db, test_user)
+    r = await client.post(
+        f"/api/v1/draft-templates/{draft.id}/reject", headers=auth_headers,
+    )
+    assert r.status_code == 200
+    assert r.json()["status"] == "rejected"
+    await test_db.refresh(draft)
+    assert draft.status == "rejected"
+    assert draft.resolved_at is not None
+
+
+@pytest.mark.asyncio
+async def test_reject_already_accepted_returns_409(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    _, draft = await _make_draft(test_db, test_user, status_="accepted")
+    r = await client.post(
+        f"/api/v1/draft-templates/{draft.id}/reject", headers=auth_headers,
+    )
+    assert r.status_code == 409
+
+
+# ── Preferences ──────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_get_preferences_empty_by_default(
+    client: AsyncClient, auth_headers,
+):
+    r = await client.get("/api/v1/accounts/me/preferences", headers=auth_headers)
+    assert r.status_code == 200
+    assert r.json()["preferences"] == {}
+
+
+@pytest.mark.asyncio
+async def test_patch_preferences_merges_keys(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    # First write: one key.
+    r = await client.patch(
+        "/api/v1/accounts/me/preferences",
+        headers=auth_headers,
+        json={"preferences": {"templatize_prompt_enabled": False}},
+    )
+    assert r.status_code == 200
+    assert r.json()["preferences"]["templatize_prompt_enabled"] is False
+
+    # Second write: different key — first must be preserved (merge semantics).
+    r2 = await client.patch(
+        "/api/v1/accounts/me/preferences",
+        headers=auth_headers,
+        json={"preferences": {"cw_resolved_status_id": 42}},
+    )
+    assert r2.status_code == 200
+    prefs = r2.json()["preferences"]
+    assert prefs["templatize_prompt_enabled"] is False
+    assert prefs["cw_resolved_status_id"] == 42
+
+    # Stored on the account_settings row.
+    stored = (
+        await test_db.execute(
+            select(AccountSettings.preferences).where(
+                AccountSettings.account_id == UUID(test_user["user_data"]["account_id"])
+            )
+        )
+    ).scalar_one()
+    assert stored["templatize_prompt_enabled"] is False
+    assert stored["cw_resolved_status_id"] == 42

backend/tests/test_prompt_anti_parrot.py

@@ -0,0 +1,184 @@
+"""Guardrail: literal output payloads must not live in any LLM system prompt.
+
+This test exists because the same anti-pattern bit us twice in the same
+day: a worked example with literal content (Outlook + jsmith + literal
+JSON; full DNS troubleshooting tree) sitting inside a `*_PROMPT` constant
+caused Claude to recite that content on unrelated tickets, making the
+task lane look like it was leaking previous-session data.
+
+The fix is structural: every output example in a system prompt must use
+`<placeholder>` or `<...>` syntax, never literal field values, command
+names, hostnames, or usernames that the model could parrot. Format
+examples that need real-looking content live in few-shot messages
+(separate file, separate code path, model treats them as past behavior),
+not in system prompts.
+
+Failure messages here name the constant + line; fix by replacing the
+literal payload with a placeholder schema, or by moving the example
+out of the system prompt entirely.
+
+See CLAUDE.md → Critical Lessons → "Don't put literal payloads in
+system prompts" for the longer rationale.
+"""
+from __future__ import annotations
+
+import importlib
+import inspect
+import pkgutil
+import re
+from typing import Iterator
+
+import pytest
+
+# Modules to scan. We deliberately import the modules (not just walk source
+# files) so we get the actual string values of `*_PROMPT` constants — which
+# may be assembled from concat / .format() / f-strings.
+_MODULE_PACKAGES = ("app.services", "app.core")
+
+
+def _iter_prompt_constants() -> Iterator[tuple[str, str, str]]:
+    """Yield (module_name, constant_name, value) for every uppercase string
+    constant whose name ends in `_PROMPT` (or `_SCHEMA`/`_PROTOCOL`/`_FORMAT`
+    — same anti-pattern risk).
+
+    Skips modules that fail to import to keep the test resilient when an
+    individual module has unrelated breakage.
+    """
+    suffixes = ("_PROMPT", "_SCHEMA", "_PROTOCOL", "_FORMAT", "_CONTEXT")
+    for pkg_name in _MODULE_PACKAGES:
+        pkg = importlib.import_module(pkg_name)
+        for mod_info in pkgutil.iter_modules(pkg.__path__, prefix=f"{pkg_name}."):
+            try:
+                mod = importlib.import_module(mod_info.name)
+            except Exception:
+                continue
+            for name, value in inspect.getmembers(mod):
+                if not name.isupper() or not name.endswith(suffixes):
+                    continue
+                if not isinstance(value, str):
+                    continue
+                yield mod_info.name, name, value
+
+
+# ── The forbidden patterns ──────────────────────────────────────────────────
+
+# A literal username pattern that Claude has historically parroted across
+# unrelated tickets. The list isn't exhaustive — it's the exact strings
+# we've seen leak. Add to it if a new one shows up in production.
+_FORBIDDEN_LITERAL_TOKENS: tuple[str, ...] = (
+    "jsmith",       # leaked from an Outlook/AD example
+    "DC01",         # leaked from an intake-form example
+    "ADSync",       # leaked from a commands-array example
+    "Dnscache",     # leaked from a DNS troubleshooting tree example
+    "google.com",   # leaked from a DNS troubleshooting tree example
+    "Outlook keeps", "Teams drops",  # specific phrasings from a worked Outlook/WiFi example
+)
+
+# Marker-with-payload patterns. A `[QUESTIONS]\n[{...JSON with real field values...}]`
+# block in a prompt is the highest-risk shape — the model treats it as a
+# canonical response template. We allow placeholder content (anything inside
+# angle brackets `<...>` is treated as a placeholder, not a literal).
+#
+# Restrictions on the regex (to avoid false positives where the marker name
+# appears in prose like "include [QUESTIONS] markers"):
+# - opening tag must be at start of string OR preceded by newline/whitespace
+#   AND followed by newline+JSON-ish content
+# - block content must START with `[` or `{` after optional whitespace,
+#   so prose blocks (like the closing-tag-distance regex match across
+#   markdown headings) are excluded
+_MARKER_BLOCK_RE = re.compile(
+    r"(?:^|\n)\[(QUESTIONS|ACTIONS|SUGGEST_FIX|FIX_OUTCOME|PROMOTE|FORK|TREE_UPDATE|STEPS_UPDATE|INTAKE_FORM|METADATA|DELTA)\]"
+    r"\s*\n"                          # forced newline before content
+    r"(\s*[\[{][\s\S]*?)"             # content must start with [ or {
+    r"\s*\n\[/\1\]"
+)
+
+# Heuristic: only flag JSON VALUES, not JSON KEYS. Keys are followed by `:`,
+# values come after `: ` (object value) or are bare strings inside an array.
+# The shape we're defending against is `{"text": "Is this user on a laptop?"}` —
+# the value `"Is this user on a laptop?"` is a literal payload the model will
+# recite. Keys like `"text"` are part of the schema and must stay literal.
+#
+# Matches a quoted string that has at least 3 chars, no angle brackets, and
+# is followed by a JSON value-terminator (`,` `]` `}`) — i.e. NOT followed
+# by `:` (which would mark it as a key).
+_QUOTED_VALUE_RE = re.compile(
+    r'"([^"<>][^"<>]{2,}?)"\s*(?=[,\]\}])'
+)
+# Substrings that, if PRESENT in the candidate value, indicate it's a
+# placeholder marker rather than literal output. Be strict — broad markers
+# like "?" alone would whitelist any sentence ending in a question mark,
+# defeating the test's purpose.
+_PLACEHOLDER_HINTS = ("...", "snake_case", "kebab-case", "<", "TODO")
+# Schema enum-like values that are part of the format spec, not parrotable text.
+_ALLOWED_ENUM_VALUES = frozenset({
+    "text", "password", "select", "boolean", "number", "textarea", "multi_text",
+    "powershell", "bash", "cmd", "python",
+    "question", "diagnostic_check", "user_note", "ai_synthesis",
+    "decision", "action", "solution", "procedure_step", "section_header", "procedure_end",
+    "step", "warning",
+})
+
+
+def _block_has_literal_payload(block_body: str) -> tuple[bool, str | None]:
+    """Return (True, offending_string) if the marker block looks like literal output."""
+    for m in _QUOTED_VALUE_RE.finditer(block_body):
+        s = m.group(1).strip()
+        if not s:
+            continue
+        # Pure placeholder hints — accept.
+        if any(h in s for h in _PLACEHOLDER_HINTS):
+            continue
+        # Pipe-separated enum like `text|password|select` — schema spec.
+        if "|" in s:
+            continue
+        # Single-word enum value we explicitly allow.
+        if s in _ALLOWED_ENUM_VALUES:
+            continue
+        # JSON ellipsis-style placeholders, ".." etc.
+        if all(c in "._" for c in s):
+            continue
+        return True, s
+    return False, None
+
+
+# ── Tests ──────────────────────────────────────────────────────────────────
+
+def test_no_known_leaked_literal_tokens_in_prompts() -> None:
+    """Constants must not contain strings the model has historically parroted.
+
+    Adding a new entry to _FORBIDDEN_LITERAL_TOKENS after a production leak is
+    the right way to extend coverage — keep this list as the audit trail.
+    """
+    failures: list[str] = []
+    for module_name, const_name, value in _iter_prompt_constants():
+        for token in _FORBIDDEN_LITERAL_TOKENS:
+            if token in value:
+                failures.append(
+                    f"{module_name}.{const_name} contains forbidden literal token "
+                    f"{token!r} — replace with a <placeholder>. See CLAUDE.md → "
+                    f"'Don't put literal payloads in system prompts'."
+                )
+    assert not failures, "\n".join(failures)
+
+
+def test_marker_blocks_in_prompts_use_placeholders_not_literal_payloads() -> None:
+    """Every marker block in a system prompt must contain placeholders only.
+
+    A block like `[QUESTIONS]\\n[{"text": "Is this user on a laptop or desktop?"}]\\n[/QUESTIONS]`
+    will be recited verbatim by Claude on unrelated tickets. Use angle-bracket
+    placeholders instead: `[{"text": "<one short, specific question>"}]`.
+    """
+    failures: list[str] = []
+    for module_name, const_name, value in _iter_prompt_constants():
+        for m in _MARKER_BLOCK_RE.finditer(value):
+            marker = m.group(1)
+            body = m.group(2)
+            has_literal, offender = _block_has_literal_payload(body)
+            if has_literal:
+                failures.append(
+                    f"{module_name}.{const_name}: [{marker}] block contains literal "
+                    f"payload string {offender!r}. Replace with a <placeholder>. "
+                    f"See CLAUDE.md → 'Don't put literal payloads in system prompts'."
+                )
+    assert not failures, "\n".join(failures)

backend/tests/test_psa_writeback_phase4.py

@@ -0,0 +1,281 @@
+"""API tests for the FlowPilot Phase 4 Resolve + Escalate writeback flow.
+
+Covers:
+- Local-only path when no PSA ticket is linked (markdown stored, status flipped,
+  no provider call).
+- PSA post happy path (provider mocked).
+- Status transition verified by re-fetch (happy path).
+- Status verification failure surfaces 502 with a clear error body.
+- 409 when trying to resolve an already-resolved session / escalate an
+  already-escalated one.
+- Escalation parallel to resolution (same structure).
+"""
+from __future__ import annotations
+
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+
+from app.api.endpoints.session_suggested_fixes import _clear_preview_cache_for_tests
+from app.models.account_settings import AccountSettings
+from app.models.ai_session import AISession
+from app.models.psa_connection import PsaConnection
+from app.services.psa.types import NoteType, PSANote, PSATicket
+
+
+@pytest.fixture(autouse=True)
+def _isolate_preview_cache():
+    _clear_preview_cache_for_tests()
+    yield
+    _clear_preview_cache_for_tests()
+
+
+async def _make_session(test_db, user, *, with_psa: bool = False) -> AISession:
+    session_kwargs: dict = dict(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "phase 4 test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    if with_psa:
+        # Fake connection — provider factory is patched in each test so we
+        # never touch a real CW instance.
+        from app.services.psa.encryption import encrypt_credentials
+        conn = PsaConnection(
+            account_id=user["user_data"]["account_id"],
+            provider="connectwise",
+            site_url="https://fake.cw.local",
+            company_id="TEST",
+            credentials_encrypted=encrypt_credentials({"public_key": "x", "private_key": "y"}),
+            is_active=True,
+        )
+        test_db.add(conn)
+        await test_db.flush()
+        session_kwargs["psa_connection_id"] = conn.id
+        session_kwargs["psa_ticket_id"] = "48291"
+
+    session = AISession(**session_kwargs)
+    test_db.add(session)
+    await test_db.commit()
+    await test_db.refresh(session)
+    return session
+
+
+# ── Resolve: local-only ────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_resolve_local_only_when_no_psa_ticket(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user, with_psa=False)
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/resolution-note/post",
+        headers=auth_headers,
+        json={"markdown": "## Problem\nx\n\n## Resolution\nfixed"},
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["outcome"] == "resolved_local"
+    assert body["session_status"] == "resolved"
+    assert body["external_id"] is None
+
+    await test_db.refresh(session)
+    assert session.status == "resolved"
+    assert session.resolution_note_markdown == "## Problem\nx\n\n## Resolution\nfixed"
+    assert session.resolved_at is not None
+
+
+# ── Resolve: happy path (PSA post + status transition verified) ────────────
+
+@pytest.mark.asyncio
+async def test_resolve_posts_to_psa_and_verifies_status(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user, with_psa=True)
+
+    # Configure the Resolved status ID so the transition is attempted.
+    await AccountSettings.set_setting(
+        test_db, session.account_id, "cw_resolved_status_id", 42,
+    )
+    await test_db.commit()
+
+    # Mock provider: post_note returns a fake note, update_ticket_status
+    # returns anything, get_ticket returns the new status_id (matches 42
+    # → verification passes).
+    fake_provider = AsyncMock()
+    fake_provider.post_note = AsyncMock(return_value=PSANote(
+        id="cw-note-777", text="...", note_type=NoteType.RESOLUTION, created_at=None,
+    ))
+    fake_provider.update_ticket_status = AsyncMock(return_value=None)
+    fake_provider.get_ticket = AsyncMock(return_value=PSATicket(
+        id="48291", summary="t", status_id=42, status_name="Resolved",
+    ))
+
+    with patch(
+        "app.services.psa_writeback_service.get_provider_for_connection",
+        return_value=fake_provider,
+    ):
+        r = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/post",
+            headers=auth_headers,
+            json={"markdown": "## Problem\nx\n\n## Resolution\nfixed"},
+        )
+
+    assert r.status_code == 200
+    body = r.json()
+    assert body["outcome"] == "resolved"
+    assert body["external_id"] == "cw-note-777"
+    assert body["verified_status_id"] == 42
+    assert body["verified_status_name"] == "Resolved"
+
+    # post_note must have used the RESOLUTION note type
+    fake_provider.post_note.assert_awaited_once()
+    called_note_type = fake_provider.post_note.await_args.kwargs["note_type"]
+    assert called_note_type == NoteType.RESOLUTION
+
+
+# ── Resolve: status verification failure → 502 ──────────────────────────────
+
+@pytest.mark.asyncio
+async def test_resolve_surfaces_status_verification_failure(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """CW silently rejecting a status change must NOT report silent success."""
+    session = await _make_session(test_db, test_user, with_psa=True)
+    await AccountSettings.set_setting(
+        test_db, session.account_id, "cw_resolved_status_id", 42,
+    )
+    await test_db.commit()
+
+    fake_provider = AsyncMock()
+    fake_provider.post_note = AsyncMock(return_value=PSANote(
+        id="cw-note-alpha", text="...", note_type=NoteType.RESOLUTION, created_at=None,
+    ))
+    fake_provider.update_ticket_status = AsyncMock(return_value=None)
+    # get_ticket returns a DIFFERENT status_id — the transition didn't stick.
+    fake_provider.get_ticket = AsyncMock(return_value=PSATicket(
+        id="48291", summary="t", status_id=99, status_name="In Progress",
+    ))
+
+    with patch(
+        "app.services.psa_writeback_service.get_provider_for_connection",
+        return_value=fake_provider,
+    ):
+        r = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/post",
+            headers=auth_headers,
+            json={"markdown": "## Problem\nx\n\n## Resolution\nfixed"},
+        )
+
+    assert r.status_code == 502
+    assert "did not verify" in r.json()["detail"]
+
+
+# ── Resolve: skip status transition when not configured ────────────────────
+
+@pytest.mark.asyncio
+async def test_resolve_skips_status_transition_when_unconfigured(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """No cw_resolved_status_id setting → post the note, don't touch status, not an error."""
+    session = await _make_session(test_db, test_user, with_psa=True)
+    # Deliberately no AccountSettings row.
+
+    fake_provider = AsyncMock()
+    fake_provider.post_note = AsyncMock(return_value=PSANote(
+        id="cw-note-beta", text="...", note_type=NoteType.RESOLUTION, created_at=None,
+    ))
+
+    with patch(
+        "app.services.psa_writeback_service.get_provider_for_connection",
+        return_value=fake_provider,
+    ):
+        r = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/post",
+            headers=auth_headers,
+            json={"markdown": "## Problem\nx\n\n## Resolution\nfixed"},
+        )
+
+    assert r.status_code == 200
+    body = r.json()
+    assert body["outcome"] == "resolved"
+    assert body["verified_status_id"] is None
+    assert body["status_transition_skipped_reason"] is not None
+    fake_provider.update_ticket_status.assert_not_called()
+    fake_provider.get_ticket.assert_not_called()
+
+
+# ── Resolve: already-resolved → 409 ─────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_resolve_rejects_already_resolved_session(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user, with_psa=False)
+    session.status = "resolved"
+    await test_db.commit()
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/resolution-note/post",
+        headers=auth_headers,
+        json={"markdown": "..."},
+    )
+    assert r.status_code == 409
+
+
+# ── Escalate: local-only + PSA parallels ────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_escalate_local_only_when_no_psa_ticket(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user, with_psa=False)
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/escalation-package/post",
+        headers=auth_headers,
+        json={"markdown": "## Problem\nx\n\n## Suggested next steps\n- try X"},
+    )
+    assert r.status_code == 200
+    assert r.json()["outcome"] == "escalated_local"
+
+    await test_db.refresh(session)
+    assert session.status == "escalated"
+    assert session.escalation_package_markdown is not None
+
+
+@pytest.mark.asyncio
+async def test_escalate_posts_internal_note_to_psa(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """Escalation handoff posts as INTERNAL_ANALYSIS (not customer-visible)."""
+    session = await _make_session(test_db, test_user, with_psa=True)
+
+    fake_provider = AsyncMock()
+    fake_provider.post_note = AsyncMock(return_value=PSANote(
+        id="cw-note-esc", text="...", note_type=NoteType.INTERNAL_ANALYSIS, created_at=None,
+    ))
+
+    with patch(
+        "app.services.psa_writeback_service.get_provider_for_connection",
+        return_value=fake_provider,
+    ):
+        r = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/escalation-package/post",
+            headers=auth_headers,
+            json={"markdown": "## Problem\nx\n\n## Suggested next steps\n- try X"},
+        )
+
+    assert r.status_code == 200
+    body = r.json()
+    assert body["outcome"] == "escalated"
+    assert body["external_id"] == "cw-note-esc"
+
+    # Handoff packages are internal — must NOT be posted with RESOLUTION or DESCRIPTION flags.
+    called = fake_provider.post_note.await_args.kwargs
+    assert called["note_type"] == NoteType.INTERNAL_ANALYSIS

backend/tests/test_script_builder_inline.py

@@ -0,0 +1,176 @@
+"""Integration tests for inline pilot_inline script_builder_session behavior.
+
+Covers:
+- Idempotent get-or-create for (user, ai_session_id) on origin='pilot_inline'
+- Authorization: ai_session_id must belong to current user
+- list_sessions + count_user_sessions default-scope to 'standalone'
+"""
+from __future__ import annotations
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select, func
+from uuid import uuid4
+
+from app.models.ai_session import AISession
+from app.models.script_builder_session import ScriptBuilderSession
+
+
+async def _make_pilot_session(test_db, user) -> str:
+    """Helper: create a minimal pilot session owned by `user`.
+
+    Matches the existing pattern used by test_fix_outcome_endpoint.py.
+    `user` is the dict returned by the test_user fixture:
+        {"email": ..., "password": ..., "user_data": {"id": ..., "account_id": ..., ...}}
+    """
+    user_id = user["user_data"]["id"]
+    account_id = user["user_data"]["account_id"]
+    session = AISession(
+        id=uuid4(), user_id=user_id, account_id=account_id,
+        session_type="tshoot", intake_type="psa_ticket",
+        intake_content={}, title="QA",
+        status="active", confidence_tier="exploring", confidence_score=0.0,
+    )
+    test_db.add(session)
+    await test_db.commit()
+    return str(session.id)
+
+
+@pytest.mark.asyncio
+async def test_inline_create_is_idempotent(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """Second create with same (user, ai_session_id) returns the existing row."""
+    ai_session_id = await _make_pilot_session(test_db, test_user)
+
+    r1 = await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell", "origin": "pilot_inline",
+              "ai_session_id": ai_session_id},
+        headers=auth_headers,
+    )
+    assert r1.status_code in (200, 201), r1.text
+    first_id = r1.json()["id"]
+
+    r2 = await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell", "origin": "pilot_inline",
+              "ai_session_id": ai_session_id},
+        headers=auth_headers,
+    )
+    assert r2.status_code in (200, 201)
+    assert r2.json()["id"] == first_id
+
+    # DB confirms only one row
+    row_count = await test_db.scalar(
+        select(func.count()).select_from(ScriptBuilderSession).where(
+            ScriptBuilderSession.user_id == test_user["user_data"]["id"],
+            ScriptBuilderSession.origin == "pilot_inline",
+        )
+    )
+    assert row_count == 1
+
+
+@pytest.mark.asyncio
+async def test_inline_requires_ai_session_id(
+    client: AsyncClient, auth_headers
+):
+    """origin='pilot_inline' without ai_session_id is rejected."""
+    r = await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell", "origin": "pilot_inline"},
+        headers=auth_headers,
+    )
+    assert r.status_code == 400
+    assert "ai_session_id" in r.text.lower()
+
+
+@pytest.mark.asyncio
+async def test_inline_ai_session_must_belong_to_caller(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """ai_session_id pointing at another user's session is rejected."""
+    # Create pilot session owned by a DIFFERENT user
+    from app.models.user import User
+    from app.models.account import Account
+    other_account = Account(id=uuid4(), name="other", display_code="OTH-0001")
+    test_db.add(other_account)
+    await test_db.flush()
+    other_user = User(
+        id=uuid4(), email="other@example.com",
+        password_hash="x", name="Other", role="engineer",
+        is_super_admin=False, is_team_admin=False, is_active=True,
+        is_service_account=False, must_change_password=False,
+        account_id=other_account.id, account_role="engineer",
+    )
+    test_db.add(other_user)
+    await test_db.flush()
+    # Build user dict in the same shape as the test_user fixture
+    other_user_dict = {
+        "user_data": {"id": str(other_user.id), "account_id": str(other_account.id)}
+    }
+    other_session_id = await _make_pilot_session(test_db, other_user_dict)
+
+    r = await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell", "origin": "pilot_inline",
+              "ai_session_id": other_session_id},
+        headers=auth_headers,
+    )
+    assert r.status_code in (403, 404), r.text
+
+
+@pytest.mark.asyncio
+async def test_list_sessions_excludes_inline(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """GET /scripts/builder/sessions returns only standalone rows."""
+    ai_session_id = await _make_pilot_session(test_db, test_user)
+
+    # Create one inline session
+    await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell", "origin": "pilot_inline",
+              "ai_session_id": ai_session_id},
+        headers=auth_headers,
+    )
+    # Create one standalone session
+    await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell"},
+        headers=auth_headers,
+    )
+
+    r = await client.get("/api/v1/scripts/builder/sessions", headers=auth_headers)
+    assert r.status_code == 200
+    body = r.json()
+    # Depending on response shape, this may be a list or {"sessions": [...]}.
+    items = body if isinstance(body, list) else body.get("sessions", body.get("items", []))
+    # Response schema does not surface `origin`; len==1 is the only meaningful guard:
+    # inline row would push this to 2.
+    assert len(items) == 1
+
+
+@pytest.mark.asyncio
+async def test_inline_sessions_do_not_count_against_cap(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """Creating 5 pilot_inline sessions does not block a subsequent standalone."""
+    # Create 5 distinct pilot sessions and attach inline builder sessions to each
+    for _ in range(5):
+        ai_session_id = await _make_pilot_session(test_db, test_user)
+        r = await client.post(
+            "/api/v1/scripts/builder/sessions",
+            json={"language": "powershell", "origin": "pilot_inline",
+                  "ai_session_id": ai_session_id},
+            headers=auth_headers,
+        )
+        assert r.status_code in (200, 201), r.text
+
+    # A standalone create should still succeed — inline sessions don't count
+    r = await client.post(
+        "/api/v1/scripts/builder/sessions",
+        json={"language": "powershell"},
+        headers=auth_headers,
+    )
+    assert r.status_code in (200, 201), r.text

backend/tests/test_session_facts_api.py

@@ -0,0 +1,455 @@
+"""API + service tests for the FlowPilot Phase 2 "What we know" facts surface.
+
+Covers:
+- /api/v1/ai-sessions/{id}/facts CRUD
+- Editability rule (403 on PATCH for question/diagnostic_check facts)
+- /facts/promote with `proposed_text` (no LLM call) and via synthesis (mocked)
+- state_version increments on every fact write
+- Stable-UUID assignment for pending_task_lane items
+- [PROMOTE] marker parser shape
+"""
+from __future__ import annotations
+
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.models.ai_session import AISession
+from app.models.session_fact import SessionFact
+from app.services.fact_synthesis_service import FactSynthesisService
+from app.services.unified_chat_service import (
+    _assign_stable_task_lane_ids,
+    _parse_promote_marker,
+)
+
+
+# ── Fixtures ────────────────────────────────────────────────────────────────
+
+async def _make_session(test_db, user, *, pending_task_lane=None) -> AISession:
+    session = AISession(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+        pending_task_lane=pending_task_lane,
+    )
+    test_db.add(session)
+    await test_db.commit()
+    await test_db.refresh(session)
+    return session
+
+
+# ── [PROMOTE] marker parser ─────────────────────────────────────────────────
+
+class TestPromoteMarkerParser:
+    def test_no_marker_returns_unchanged(self):
+        text = "Just an analysis sentence."
+        cleaned, items = _parse_promote_marker(text)
+        assert cleaned == text
+        assert items is None
+
+    def test_single_block(self):
+        ref = uuid.uuid4()
+        text = (
+            "Some analysis.\n\n"
+            f'[PROMOTE]\n{{"source_type":"question","source_ref":"{ref}",'
+            '"text":"OWA login confirmed working","summary":"rules out tenant"}\n'
+            "[/PROMOTE]"
+        )
+        cleaned, items = _parse_promote_marker(text)
+        assert cleaned == "Some analysis."
+        assert items is not None and len(items) == 1
+        assert items[0]["source_type"] == "question"
+        assert items[0]["source_ref"] == ref
+        assert items[0]["text"] == "OWA login confirmed working"
+        assert items[0]["summary"] == "rules out tenant"
+
+    def test_multiple_blocks(self):
+        text = (
+            '[PROMOTE]\n{"source_type":"question","source_ref":null,'
+            '"text":"a","summary":"x"}\n[/PROMOTE]\n'
+            '[PROMOTE]\n{"source_type":"diagnostic_check","source_ref":null,'
+            '"text":"b","summary":"y"}\n[/PROMOTE]'
+        )
+        cleaned, items = _parse_promote_marker(text)
+        assert items is not None and len(items) == 2
+        assert items[0]["text"] == "a"
+        assert items[1]["text"] == "b"
+        assert "[PROMOTE]" not in cleaned
+
+    def test_ai_synthesis_strips_source_ref(self):
+        # The model should not provide source_ref for synthesis facts —
+        # the parser drops it defensively even if the model does.
+        ref = uuid.uuid4()
+        text = (
+            f'[PROMOTE]\n{{"source_type":"ai_synthesis","source_ref":"{ref}",'
+            '"text":"Combined finding","summary":"synth"}\n[/PROMOTE]'
+        )
+        _, items = _parse_promote_marker(text)
+        assert items is not None and items[0]["source_ref"] is None
+
+    def test_invalid_source_type_dropped(self):
+        text = (
+            '[PROMOTE]\n{"source_type":"bogus","text":"x"}\n[/PROMOTE]\n'
+            '[PROMOTE]\n{"source_type":"question","source_ref":null,"text":"good"}\n[/PROMOTE]'
+        )
+        _, items = _parse_promote_marker(text)
+        assert items is not None and len(items) == 1
+        assert items[0]["text"] == "good"
+
+    def test_missing_text_dropped(self):
+        text = '[PROMOTE]\n{"source_type":"question","source_ref":null,"text":""}\n[/PROMOTE]'
+        _, items = _parse_promote_marker(text)
+        assert items is None  # empty list collapses to None
+
+    def test_invalid_uuid_drops_ref_keeps_item(self):
+        text = '[PROMOTE]\n{"source_type":"question","source_ref":"not-a-uuid","text":"keep"}\n[/PROMOTE]'
+        _, items = _parse_promote_marker(text)
+        assert items is not None and items[0]["source_ref"] is None
+        assert items[0]["text"] == "keep"
+
+    def test_malformed_json_dropped(self):
+        text = "[PROMOTE]\nnot json at all\n[/PROMOTE]"
+        cleaned, items = _parse_promote_marker(text)
+        assert items is None
+        # Block is still stripped from display so the engineer doesn't see it.
+        assert "[PROMOTE]" not in cleaned
+
+
+# ── Stable-UUID assignment ──────────────────────────────────────────────────
+
+class TestAssignStableTaskLaneIds:
+    def test_empty_prev_assigns_fresh_uuids(self):
+        qs, acts = _assign_stable_task_lane_ids(
+            None,
+            [{"text": "Q1", "context": "c1"}],
+            [{"label": "A1", "command": "cmd"}],
+        )
+        assert len(qs) == 1 and uuid.UUID(qs[0]["id"])
+        assert len(acts) == 1 and uuid.UUID(acts[0]["id"])
+
+    def test_prev_uuid_preserved_on_text_match(self):
+        qid = str(uuid.uuid4())
+        prev = {
+            "questions": [{"id": qid, "text": "Same text"}],
+            "actions": [],
+        }
+        qs, _ = _assign_stable_task_lane_ids(prev, [{"text": "Same text"}], [])
+        assert qs[0]["id"] == qid
+
+    def test_prev_uuid_replaced_when_text_changes(self):
+        qid = str(uuid.uuid4())
+        prev = {"questions": [{"id": qid, "text": "Original"}], "actions": []}
+        qs, _ = _assign_stable_task_lane_ids(prev, [{"text": "Different"}], [])
+        assert qs[0]["id"] != qid
+
+    def test_action_label_match_preserves_uuid(self):
+        aid = str(uuid.uuid4())
+        prev = {"questions": [], "actions": [{"id": aid, "label": "Run X"}]}
+        _, acts = _assign_stable_task_lane_ids(prev, [], [{"label": "Run X"}])
+        assert acts[0]["id"] == aid
+
+
+# ── FactSynthesisService.create_fact validation ─────────────────────────────
+
+@pytest.mark.asyncio
+async def test_create_fact_rejects_source_ref_for_user_note(test_db, test_user):
+    session = await _make_session(test_db, test_user)
+    svc = FactSynthesisService(test_db)
+    with pytest.raises(ValueError, match="source_ref must be None"):
+        await svc.create_fact(
+            session_id=session.id,
+            account_id=session.account_id,
+            user_id=session.user_id,
+            source_type="user_note",
+            text="x",
+            source_ref=uuid.uuid4(),
+        )
+
+
+@pytest.mark.asyncio
+async def test_create_fact_rejects_invalid_source_type(test_db, test_user):
+    session = await _make_session(test_db, test_user)
+    svc = FactSynthesisService(test_db)
+    with pytest.raises(ValueError, match="Invalid source_type"):
+        await svc.create_fact(
+            session_id=session.id,
+            account_id=session.account_id,
+            user_id=session.user_id,
+            source_type="not_a_type",
+            text="x",
+        )
+
+
+@pytest.mark.asyncio
+async def test_create_fact_bumps_state_version(test_db, test_user):
+    session = await _make_session(test_db, test_user)
+    initial_version = session.state_version
+    svc = FactSynthesisService(test_db)
+    await svc.create_fact(
+        session_id=session.id,
+        account_id=session.account_id,
+        user_id=session.user_id,
+        source_type="user_note",
+        text="A confirmed observation",
+    )
+    await test_db.commit()
+    await test_db.refresh(session)
+    assert session.state_version == initial_version + 1
+
+
+# ── Endpoint tests ──────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_list_facts_empty(client: AsyncClient, test_user, auth_headers, test_db):
+    session = await _make_session(test_db, test_user)
+    resp = await client.get(
+        f"/api/v1/ai-sessions/{session.id}/facts",
+        headers=auth_headers,
+    )
+    assert resp.status_code == 200
+    assert resp.json()["facts"] == []
+
+
+@pytest.mark.asyncio
+async def test_create_user_note_fact(client: AsyncClient, test_user, auth_headers, test_db):
+    session = await _make_session(test_db, test_user)
+    resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts",
+        headers=auth_headers,
+        json={"text": "Customer is on a laptop", "summary": "endpoint type"},
+    )
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["source_type"] == "user_note"
+    assert body["editable"] is True
+    assert body["source_ref"] is None
+    assert body["text"] == "Customer is on a laptop"
+
+
+@pytest.mark.asyncio
+async def test_patch_user_note_succeeds(client: AsyncClient, test_user, auth_headers, test_db):
+    session = await _make_session(test_db, test_user)
+    create = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts",
+        headers=auth_headers,
+        json={"text": "original"},
+    )
+    fact_id = create.json()["id"]
+
+    patch_resp = await client.patch(
+        f"/api/v1/ai-sessions/{session.id}/facts/{fact_id}",
+        headers=auth_headers,
+        json={"text": "edited", "summary": "new label"},
+    )
+    assert patch_resp.status_code == 200
+    assert patch_resp.json()["text"] == "edited"
+    assert patch_resp.json()["source_summary"] == "new label"
+
+
+@pytest.mark.asyncio
+async def test_patch_question_fact_returns_403(client: AsyncClient, test_user, auth_headers, test_db):
+    """Question/check-sourced facts must be edited at the source item, not the card."""
+    session = await _make_session(test_db, test_user)
+    # Insert a question-sourced fact directly so the editability rule applies.
+    fact = SessionFact(
+        session_id=session.id,
+        account_id=session.account_id,
+        text="Pre-existing question fact",
+        source_type="question",
+        source_ref=uuid.uuid4(),
+        created_by=session.user_id,
+    )
+    test_db.add(fact)
+    await test_db.commit()
+    await test_db.refresh(fact)
+
+    resp = await client.patch(
+        f"/api/v1/ai-sessions/{session.id}/facts/{fact.id}",
+        headers=auth_headers,
+        json={"text": "trying to edit"},
+    )
+    assert resp.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_delete_fact_soft_deletes(client: AsyncClient, test_user, auth_headers, test_db):
+    session = await _make_session(test_db, test_user)
+    create = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts",
+        headers=auth_headers,
+        json={"text": "to be removed"},
+    )
+    fact_id = create.json()["id"]
+
+    del_resp = await client.delete(
+        f"/api/v1/ai-sessions/{session.id}/facts/{fact_id}",
+        headers=auth_headers,
+    )
+    assert del_resp.status_code == 204
+
+    # Listed facts should not include the soft-deleted one.
+    list_resp = await client.get(
+        f"/api/v1/ai-sessions/{session.id}/facts",
+        headers=auth_headers,
+    )
+    assert list_resp.status_code == 200
+    assert all(f["id"] != fact_id for f in list_resp.json()["facts"])
+
+    # Row still exists in DB (deleted_at set), proving it was soft-deleted.
+    row = (
+        await test_db.execute(
+            select(SessionFact).where(SessionFact.id == uuid.UUID(fact_id))
+        )
+    ).scalar_one()
+    assert row.deleted_at is not None
+
+
+@pytest.mark.asyncio
+async def test_promote_with_proposed_text(client: AsyncClient, test_user, auth_headers, test_db):
+    qid = uuid.uuid4()
+    session = await _make_session(
+        test_db, test_user,
+        pending_task_lane={
+            "questions": [{"id": str(qid), "text": "Is OWA working?"}],
+            "actions": [],
+        },
+    )
+    resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts/promote",
+        headers=auth_headers,
+        json={
+            "source_type": "question",
+            "source_ref": str(qid),
+            "proposed_text": "OWA confirmed working for jsmith",
+            "proposed_summary": "rules out tenant/license",
+        },
+    )
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["source_type"] == "question"
+    assert body["source_ref"] == str(qid)
+    assert body["editable"] is False  # question-sourced facts are read-only at the card
+
+
+@pytest.mark.asyncio
+async def test_promote_via_synthesis(client: AsyncClient, test_user, auth_headers, test_db):
+    qid = uuid.uuid4()
+    session = await _make_session(
+        test_db, test_user,
+        pending_task_lane={
+            "questions": [{"id": str(qid), "text": "Is the user on a laptop?"}],
+            "actions": [],
+        },
+    )
+
+    # Mock the LLM call to avoid hitting the network in tests.
+    fake_provider = AsyncMock()
+    fake_provider.generate_json = AsyncMock(return_value=(
+        '{"text": "User confirmed on a laptop", "summary": "endpoint type"}',
+        50, 20,
+    ))
+
+    with patch(
+        "app.services.fact_synthesis_service.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        resp = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/facts/promote",
+            headers=auth_headers,
+            json={
+                "source_type": "question",
+                "source_ref": str(qid),
+                "raw_input": "Yes, it's a Lenovo X1 Carbon",
+            },
+        )
+
+    assert resp.status_code == 201
+    assert resp.json()["text"] == "User confirmed on a laptop"
+    assert resp.json()["source_summary"] == "endpoint type"
+
+
+@pytest.mark.asyncio
+async def test_promote_synthesis_returning_null_returns_422(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """When the synthesizer judges the input has no fact, the endpoint surfaces 422."""
+    qid = uuid.uuid4()
+    session = await _make_session(
+        test_db, test_user,
+        pending_task_lane={
+            "questions": [{"id": str(qid), "text": "Is OWA working?"}],
+            "actions": [],
+        },
+    )
+
+    fake_provider = AsyncMock()
+    fake_provider.generate_json = AsyncMock(return_value=(
+        '{"text": null, "summary": null}', 30, 10,
+    ))
+
+    with patch(
+        "app.services.fact_synthesis_service.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        resp = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/facts/promote",
+            headers=auth_headers,
+            json={
+                "source_type": "question",
+                "source_ref": str(qid),
+                "raw_input": "unknown",
+            },
+        )
+    assert resp.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_promote_rejects_both_or_neither_inputs(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user)
+    # Neither
+    resp = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts/promote",
+        headers=auth_headers,
+        json={"source_type": "question"},
+    )
+    assert resp.status_code == 400
+
+    # Both
+    resp2 = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts/promote",
+        headers=auth_headers,
+        json={
+            "source_type": "question",
+            "proposed_text": "x",
+            "raw_input": "y",
+        },
+    )
+    assert resp2.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_state_version_bumps_on_create_via_endpoint(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user)
+    initial = session.state_version
+
+    await client.post(
+        f"/api/v1/ai-sessions/{session.id}/facts",
+        headers=auth_headers,
+        json={"text": "a"},
+    )
+
+    # Reload — refresh fetches the latest persisted row.
+    await test_db.refresh(session)
+    assert session.state_version == initial + 1

backend/tests/test_session_suggested_fixes_api.py

@@ -0,0 +1,356 @@
+"""API + service tests for the FlowPilot Phase 3 suggested-fix + preview surface.
+
+Covers:
+- /api/v1/ai-sessions/{id}/suggested-fixes/active (200 + 404)
+- /api/v1/ai-sessions/{id}/suggested-fixes/{fix_id}/decision (one_off,
+  draft_template, build_template, dismissed; 409 on dismissing a superseded
+  fix; state_version bump)
+- /api/v1/ai-sessions/{id}/resolution-note/preview (LLM mocked; cache hit on
+  same state_version, miss after a fact write)
+- [SUGGEST_FIX] marker parser shape
+- _persist_suggested_fix supersession + state_version bump
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import AsyncClient
+from sqlalchemy import select
+
+from app.api.endpoints.session_suggested_fixes import _clear_preview_cache_for_tests
+from app.models.ai_session import AISession
+from app.models.session_suggested_fix import SessionSuggestedFix
+from app.services.unified_chat_service import (
+    _parse_suggest_fix_marker,
+    _persist_suggested_fix,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_preview_cache():
+    _clear_preview_cache_for_tests()
+    yield
+    _clear_preview_cache_for_tests()
+
+
+async def _make_session(test_db, user) -> AISession:
+    session = AISession(
+        user_id=user["user_data"]["id"],
+        account_id=user["user_data"]["account_id"],
+        session_type="chat",
+        intake_type="free_text",
+        intake_content={"text": "phase 3 test"},
+        status="active",
+        confidence_tier="discovery",
+        conversation_messages=[],
+    )
+    test_db.add(session)
+    await test_db.commit()
+    await test_db.refresh(session)
+    return session
+
+
+# ── [SUGGEST_FIX] parser ────────────────────────────────────────────────────
+
+class TestSuggestFixParser:
+    def test_no_marker(self):
+        cleaned, fix = _parse_suggest_fix_marker("just analysis")
+        assert cleaned == "just analysis"
+        assert fix is None
+
+    def test_well_formed_block(self):
+        text = (
+            "Analysis sentence.\n\n"
+            '[SUGGEST_FIX]\n'
+            '{"title": "Reset password", "description": "Stale credential.", '
+            '"confidence": 87, "script_template_slug": "reset-cw"}\n'
+            '[/SUGGEST_FIX]'
+        )
+        cleaned, fix = _parse_suggest_fix_marker(text)
+        assert cleaned == "Analysis sentence."
+        assert fix is not None
+        assert fix["title"] == "Reset password"
+        assert fix["confidence_pct"] == 87
+        assert fix["script_template_slug"] == "reset-cw"
+        assert fix["ai_drafted_script"] is None
+
+    def test_confidence_clamped_and_rounded(self):
+        text = (
+            '[SUGGEST_FIX]\n{"title":"x","description":"y","confidence":120.7}\n[/SUGGEST_FIX]'
+        )
+        _, fix = _parse_suggest_fix_marker(text)
+        assert fix is not None and fix["confidence_pct"] == 100
+
+        text2 = (
+            '[SUGGEST_FIX]\n{"title":"x","description":"y","confidence":-3}\n[/SUGGEST_FIX]'
+        )
+        _, fix2 = _parse_suggest_fix_marker(text2)
+        assert fix2 is not None and fix2["confidence_pct"] == 0
+
+    def test_only_last_block_wins(self):
+        # Stale early block plus a final intent — the parser keeps the LAST one.
+        text = (
+            '[SUGGEST_FIX]\n{"title":"old","description":"o","confidence":50}\n[/SUGGEST_FIX]\n'
+            '[SUGGEST_FIX]\n{"title":"new","description":"n","confidence":80}\n[/SUGGEST_FIX]'
+        )
+        cleaned, fix = _parse_suggest_fix_marker(text)
+        assert fix is not None and fix["title"] == "new"
+        assert "[SUGGEST_FIX]" not in cleaned
+
+    def test_missing_required_field_dropped(self):
+        text = '[SUGGEST_FIX]\n{"title":"only title"}\n[/SUGGEST_FIX]'
+        cleaned, fix = _parse_suggest_fix_marker(text)
+        assert fix is None
+        # Marker still stripped from display.
+        assert "[SUGGEST_FIX]" not in cleaned
+
+    def test_malformed_json_dropped(self):
+        text = "[SUGGEST_FIX]\nnot json\n[/SUGGEST_FIX]"
+        cleaned, fix = _parse_suggest_fix_marker(text)
+        assert fix is None
+        assert "[SUGGEST_FIX]" not in cleaned
+
+
+# ── _persist_suggested_fix ──────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_persist_supersedes_prior_active_and_bumps_state_version(test_db, test_user):
+    session = await _make_session(test_db, test_user)
+    initial_version = session.state_version
+
+    # Insert an existing active fix so we can verify supersession.
+    existing = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="Old fix",
+        description="prior",
+        confidence_pct=60,
+    )
+    test_db.add(existing)
+    await test_db.commit()
+
+    await _persist_suggested_fix(
+        db=test_db,
+        session=session,
+        fix={
+            "title": "New fix",
+            "description": "current best",
+            "confidence_pct": 88,
+            "script_template_slug": None,
+            "ai_drafted_script": None,
+            "ai_drafted_parameters": None,
+        },
+    )
+    await test_db.commit()
+    await test_db.refresh(existing)
+    await test_db.refresh(session)
+
+    assert existing.superseded_at is not None
+    assert session.state_version == initial_version + 1
+
+    # Exactly one active row remains — and it's the new one.
+    result = await test_db.execute(
+        select(SessionSuggestedFix).where(
+            SessionSuggestedFix.session_id == session.id,
+            SessionSuggestedFix.superseded_at.is_(None),
+        )
+    )
+    actives = list(result.scalars().all())
+    assert len(actives) == 1
+    assert actives[0].title == "New fix"
+
+
+# ── /suggested-fixes/active endpoint ────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_get_active_returns_404_when_none(client: AsyncClient, test_user, auth_headers, test_db):
+    session = await _make_session(test_db, test_user)
+    r = await client.get(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/active",
+        headers=auth_headers,
+    )
+    assert r.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_get_active_returns_active_fix(client: AsyncClient, test_user, auth_headers, test_db):
+    session = await _make_session(test_db, test_user)
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="Active fix",
+        description="d",
+        confidence_pct=72,
+    )
+    test_db.add(fix)
+    await test_db.commit()
+
+    r = await client.get(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/active",
+        headers=auth_headers,
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["title"] == "Active fix"
+    assert body["confidence_pct"] == 72
+    assert body["superseded_at"] is None
+
+
+# ── /decision endpoint ─────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_record_decision_persists_and_bumps_state_version(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user)
+    initial_version = session.state_version
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="x",
+        description="y",
+        confidence_pct=50,
+    )
+    test_db.add(fix)
+    await test_db.commit()
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={"decision": "draft_template"},
+    )
+    assert r.status_code == 200
+    assert r.json()["user_decision"] == "draft_template"
+
+    await test_db.refresh(session)
+    assert session.state_version == initial_version + 1
+
+
+@pytest.mark.asyncio
+async def test_dismissed_supersedes_the_fix(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user)
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="x",
+        description="y",
+        confidence_pct=50,
+    )
+    test_db.add(fix)
+    await test_db.commit()
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={"decision": "dismissed"},
+    )
+    assert r.status_code == 200
+    await test_db.refresh(fix)
+    assert fix.superseded_at is not None
+
+
+@pytest.mark.asyncio
+async def test_dismiss_already_superseded_returns_409(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user)
+    fix = SessionSuggestedFix(
+        session_id=session.id,
+        account_id=session.account_id,
+        title="x",
+        description="y",
+        confidence_pct=50,
+        superseded_at=datetime.now(timezone.utc),
+    )
+    test_db.add(fix)
+    await test_db.commit()
+
+    r = await client.post(
+        f"/api/v1/ai-sessions/{session.id}/suggested-fixes/{fix.id}/decision",
+        headers=auth_headers,
+        json={"decision": "dismissed"},
+    )
+    assert r.status_code == 409
+
+
+# ── /resolution-note/preview endpoint ──────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_preview_uses_state_version_cache(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    session = await _make_session(test_db, test_user)
+
+    fake_provider = AsyncMock()
+    fake_provider.generate_text = AsyncMock(return_value=(
+        "## Problem\nx\n\n## What we confirmed\n(none)\n\n## Root cause\ny\n\n## Resolution\nz",
+        100, 50,
+    ))
+
+    with patch(
+        "app.services.resolution_note_generator.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        # First call — cache miss, generates fresh.
+        r1 = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/preview",
+            headers=auth_headers,
+        )
+        assert r1.status_code == 200
+        assert r1.json()["from_cache"] is False
+        assert fake_provider.generate_text.await_count == 1
+
+        # Second call, no state change — must hit the cache (no extra LLM call).
+        r2 = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/preview",
+            headers=auth_headers,
+        )
+        assert r2.status_code == 200
+        assert r2.json()["from_cache"] is True
+        assert r2.json()["markdown"] == r1.json()["markdown"]
+        assert fake_provider.generate_text.await_count == 1
+
+
+@pytest.mark.asyncio
+async def test_preview_invalidates_after_fact_write(
+    client: AsyncClient, test_user, auth_headers, test_db
+):
+    """A new fact bumps state_version → next preview is a fresh generation, not cached."""
+    session = await _make_session(test_db, test_user)
+
+    fake_provider = AsyncMock()
+    fake_provider.generate_text = AsyncMock(return_value=(
+        "## Problem\nx\n\n## What we confirmed\n(none)\n\n## Root cause\ny\n\n## Resolution\nz",
+        100, 50,
+    ))
+
+    with patch(
+        "app.services.resolution_note_generator.get_ai_provider",
+        return_value=fake_provider,
+    ):
+        await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/preview",
+            headers=auth_headers,
+        )
+        assert fake_provider.generate_text.await_count == 1
+
+        # Add a fact — bumps state_version on the session.
+        await client.post(
+            f"/api/v1/ai-sessions/{session.id}/facts",
+            headers=auth_headers,
+            json={"text": "a confirmed observation"},
+        )
+
+        # Next preview must regenerate (cache key includes state_version).
+        r = await client.post(
+            f"/api/v1/ai-sessions/{session.id}/resolution-note/preview",
+            headers=auth_headers,
+        )
+        assert r.status_code == 200
+        assert r.json()["from_cache"] is False
+        assert fake_provider.generate_text.await_count == 2

docker-compose.dev.yml

@@ -1,4 +1,5 @@
 name: resolutionflow
+
 services:
   db:
     image: pgvector/pgvector:pg16
@@ -8,7 +9,7 @@ services:
       POSTGRES_PASSWORD: postgres
       POSTGRES_DB: resolutionflow
     ports:
-      - "${POSTGRES_PORT:-5432}:5432"
+      - "${POSTGRES_PORT:-5433}:5432"
     volumes:
       - rf_postgres_data:/var/lib/postgresql/data
     healthcheck:
@@ -22,53 +23,51 @@ services:
       context: ./backend
       dockerfile: Dockerfile.dev
     container_name: resolutionflow_backend
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+    ports:
+      - "8000:8000"
     volumes:
-      - ./backend:/app
+      - ${REPO_ROOT}/backend:/app
     environment:
       - APP_NAME=ResolutionFlow
       - DEBUG=true
       - DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/resolutionflow
       - DATABASE_URL_SYNC=postgresql://postgres:postgres@db:5432/resolutionflow
+      # Dedicated test database — pytest will refuse to run against any DB
+      # whose name doesn't contain 'test' (conftest.py safety assertion).
+      - DATABASE_TEST_URL=postgresql+asyncpg://postgres:postgres@db:5432/resolutionflow_test
       - SECRET_KEY=${SECRET_KEY}
       - ALGORITHM=HS256
       - ACCESS_TOKEN_EXPIRE_MINUTES=15
       - REFRESH_TOKEN_EXPIRE_DAYS=7
+      - REQUIRE_INVITE_CODE=true
       - FEEDBACK_EMAIL=feedback@resolutionflow.com
       - AI_PROVIDER=anthropic
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
-      - GOOGLE_AI_API_KEY=${GOOGLE_AI_API_KEY}
-      - 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"]
+      - GOOGLE_AI_API_KEY=${GOOGLE_AI_API_KEY:-}
+      - ENABLE_MCP_MICROSOFT_LEARN=true
+      - FRONTEND_URL=http://docker-01:5173
+      - CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173","http://docker-01:5173","http://100.64.78.44:5173"]
     depends_on:
       db:
         condition: service_healthy
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.rf-api.rule=Host(`dev.resolutionflow.com`) && PathPrefix(`/api`)"
-      - "traefik.http.routers.rf-api.entrypoints=websecure"
-      - "traefik.http.routers.rf-api.tls.certresolver=letsencrypt"
-      - "traefik.http.services.rf-api.loadbalancer.server.port=8000"
 
   frontend:
     build:
       context: ./frontend
       dockerfile: Dockerfile.dev
     container_name: resolutionflow_frontend
+    command: npm run dev -- --host 0.0.0.0 --port 5173
+    ports:
+      - "5173:5173"
     volumes:
-      - ./frontend:/app
+      - ${REPO_ROOT}/frontend:/app
       - /app/node_modules
     environment:
-      - VITE_API_URL=https://dev.resolutionflow.com/
+      - VITE_API_URL=http://docker-01:8000
+      - CHOKIDAR_USEPOLLING=true
     depends_on:
       - backend
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.rf-frontend.rule=Host(`dev.resolutionflow.com`)"
-      - "traefik.http.routers.rf-frontend.middlewares=dev-auth"
-      - "traefik.http.middlewares.dev-auth.basicauth.users=chihlasm:$$apr1$$dJXUAZ3Y$$SsJm.K8fOjCeNMe4B70Bi0"
-      - "traefik.http.routers.rf-frontend.entrypoints=websecure"
-      - "traefik.http.routers.rf-frontend.tls.certresolver=letsencrypt"
-      - "traefik.http.services.rf-frontend.loadbalancer.server.port=5173"
 
 volumes:
-  rf_postgres_data:
- 
+  rf_postgres_data:

docs/FLOWPILOT-AND-RESOLUTIONASSIST.md

@@ -0,0 +1,163 @@
+# FlowPilot & ResolutionAssist
+
+> ResolutionFlow offers two AI-driven troubleshooting modes that share the same session backend but present very different interaction styles. Both work standalone and become richer when paired with a PSA connection.
+
+---
+
+## At a glance
+
+| | **FlowPilot** | **ResolutionAssist** |
+|---|---|---|
+| **Style** | Guided, structured | Conversational, freeform |
+| **Entry** | `/pilot` | `/assistant` |
+| **Interaction** | Questions → Actions → Resolution, one step at a time | Natural chat with inline questions/actions |
+| **Best for** | Reproducible workflows, low-context engineers, handoffs | Exploratory problems, quick lookups, rubber-ducking |
+| **Lifecycle** | Active → Paused → Resolved / Escalated / Abandoned | Active → Resolved / Abandoned (lightweight) |
+| **Confidence tracking** | Yes — drives tier transitions | No — always responsive to user direction |
+| **Navigation guard** | Yes — prevents accidental loss | No — free to leave and return |
+
+Both modes share the `ai_sessions` table (discriminated by `session_type`), the same multimodal AI backend (image uploads, markdown, cached prompts), and the same `[QUESTIONS]` / `[ACTIONS]` / `[FORK]` marker vocabulary that renders inline TaskLane elements.
+
+---
+
+## FlowPilot — guided troubleshooting
+
+FlowPilot is a wizard-style AI engineer that walks you through a problem one diagnostic step at a time. It runs on confidence tiers:
+
+- **Discovery** (confidence < 0.4) — asking broad, open-ended questions to characterize the problem
+- **Exploring** (0.4–0.8) — proposing targeted actions and narrowing hypotheses
+- **Guided** (≥ 0.8) — recommending a specific fix with steps to verify
+
+### The FlowPilot session flow
+
+1. **Intake.** You start from `/pilot` or from the dashboard "New Session" button. The intake screen accepts free-text description, PSA ticket context, screenshots, or log pastes.
+2. **Preference check.** Before suggesting any fix, the AI asks whether you want a **GUI** or **script** approach. This is enforced in the system prompt so you never get steps you can't execute.
+3. **Step-by-step progression.** Each AI response is either a question (with clickable options), an action (with "Done" / "Didn't work" buttons), a `[FORK]` (two distinct paths to try), or a final resolution suggestion. You respond, the AI updates its confidence, and the next step is generated.
+4. **Action bar.** The session header always shows **Pause & Leave**, **Resolve**, **Escalate**, **Share Update**, and **Close**. Pausing freezes the session; resuming restores the full context.
+5. **Resolve / Escalate.** *Resolve* marks the ticket fixed and generates a clean summary of what worked. *Escalate* packages the problem summary and steps tried into an **escalation package** that the next engineer (or the PSA ticket) inherits.
+
+### Why FlowPilot exists
+
+- **New engineers** get senior-engineer-level diagnostic rigor without needing the experience to know what to ask next.
+- **Documented resolutions** — every step is captured, so the generated note on the ticket is substantive (not just "fixed it").
+- **Handoff-friendly** — escalation packages mean the next person doesn't start from zero.
+
+---
+
+## ResolutionAssist — conversational AI
+
+ResolutionAssist is a chat with an expert IT systems engineer. It's less structured than FlowPilot but still surfaces interactive elements when the AI wants structured input.
+
+### The ResolutionAssist flow
+
+1. **Open a chat.** From `/assistant` or the dashboard. Sessions show up in the left sidebar just like any messaging app.
+2. **Send a message.** Freeform prose. Attach up to 3 images per message (screenshots, error dialogs, network diagrams). Paste logs, code, or PowerShell output.
+3. **AI responds.** The response is prose, but any `[QUESTIONS]` or `[ACTIONS]` blocks render as a **TaskLane** — a side panel with clickable options and action buttons. You can answer via chat or click the TaskLane elements.
+4. **Branching (`[FORK]`).** If the AI proposes two paths ("check cable or restart switch?"), the fork renders as a choice. Picking one continues the conversation down that path.
+5. **Resume later.** Unlike FlowPilot, there's no navigation guard. Leave mid-conversation; every message is stored.
+
+### Why ResolutionAssist exists
+
+- **Unstructured problems** — "I have no idea where to start, here's a screenshot" works great.
+- **Reference lookups** — "what's the right PowerShell command to check Exchange health" is faster in chat than through an intake form.
+- **Senior engineers** — when you already know what you're doing and just want a second opinion or a syntax check.
+
+---
+
+## Without a PSA connection
+
+Both modes work standalone. Without ConnectWise connected:
+
+- Sessions live entirely in ResolutionFlow. They're listed in your session history, searchable, and shareable via public share links (`/shared/sessions/:token`).
+- Summaries generated on Resolve are saved to the session record but **not** written anywhere else. You can copy/paste into whatever ticketing or documentation system you use.
+- Escalating a FlowPilot session routes the escalation package to another ResolutionFlow engineer on your team — not to an external PSA ticket.
+- No ticket context is injected into the AI prompt, so the AI starts cold with only what you provide in the intake or first message.
+
+**Standalone use cases:**
+- Evaluating ResolutionFlow before committing to a PSA integration
+- Troubleshooting internal IT issues that aren't client-facing
+- Teams using a PSA ResolutionFlow doesn't integrate with yet
+- Knowledge-base research ("what are my options for X") that don't map to a ticket
+
+---
+
+## With a PSA connection (ConnectWise)
+
+When ConnectWise is connected, both modes become ticket-aware and write back to the PSA as a first-class client.
+
+### FlowPilot + PSA
+
+**Starting from a ticket:**
+- Click a ticket row (from `/tickets` or the dashboard queue) and pick "Start FlowPilot." The ticket's problem description, recent notes, configurations, company details, and related tickets are auto-injected into the AI's context. No manual retyping.
+- The session shows the linked ticket badge in the header.
+
+**During the session:**
+- **Share Update** — posts an interim note to the CW ticket with the current AI summary, so stakeholders can see progress without interrupting you.
+- **Status changes** — the detail panel and session header let you move the ticket through statuses (New → In Progress → Waiting on Customer → Resolved) directly from ResolutionFlow. Status writes are verified against CW so you're never told "success" when CW silently rejected the change.
+- **Resource assignment** — add yourself or a teammate as a co-assignee without touching the owner. If the ticket has no owner yet, assigning sets owner; if there's already an owner, you're added as an additional resource via a CW schedule entry.
+
+**On Resolve:**
+- Final summary is posted as a ticket note.
+- Ticket status can auto-update to Resolved (per your team's settings).
+
+**On Escalate:**
+- The escalation package (problem summary + steps tried) is posted as a note.
+- The ticket can be routed via CW's normal escalation rules.
+- The next engineer picking up the ticket can auto-start a new session with the full escalation context pre-filled.
+
+**Spin-off tickets (new):**
+- During any session, if you discover a separate issue, the AI can propose `create_spin_off_ticket`. Accepting opens the New Ticket modal pre-filled with the current ticket's company and board, so a second ticket is one click away without leaving your session.
+
+### ResolutionAssist + PSA
+
+**Starting from a ticket:**
+- Same ticket-context injection as FlowPilot. When opened with a linked ticket, the AI sees company, configs, notes, and related tickets.
+- A "New Ticket" button appears in the header — lets you spawn a separate ticket mid-conversation (same flow as FlowPilot's spin-off).
+
+**During the chat:**
+- Ask the AI about the ticket directly: *"Summarize what's been tried," "What configs does this company have?"* — the AI already has that context loaded.
+- `[ACTIONS]` can include `create_spin_off_ticket` when the AI detects a separate issue surfaced in the conversation.
+
+**Writing back:**
+- ResolutionAssist is a lighter-weight mode, so it doesn't auto-post on resolve. You can manually copy the conversation summary to a ticket note if useful.
+- Status updates and resource assignment are done via the `/tickets` page rather than the chat UI.
+
+---
+
+## Choosing between them
+
+| I want to… | Use |
+|---|---|
+| Walk through a known issue type with step-by-step rigor | **FlowPilot** |
+| Document every action taken for audit or handoff | **FlowPilot** |
+| Escalate with a full context package | **FlowPilot** |
+| Ask a question, get an answer, move on | **ResolutionAssist** |
+| Paste a screenshot and say "what's wrong here?" | **ResolutionAssist** |
+| Stay on the ticket for 2 minutes, not 20 | **ResolutionAssist** |
+| Troubleshoot without breaking flow to switch pages | Either, with the linked ticket panel open alongside |
+
+The two modes aren't competitive. A common workflow is to start in ResolutionAssist to scope the problem, then kick off a FlowPilot session when you realize the issue is going to take real diagnosis. Both show up in the unified session history.
+
+---
+
+## Tickets page — the PSA hub
+
+`/tickets` is the CW ticket manager built into ResolutionFlow. With a PSA connection:
+
+- Search and filter tickets by assignment (me / unassigned / specific member via searchable picker), board, status, priority, company, open/closed.
+- Slide-out detail panel shows notes, configurations, related tickets, and assignees — all fetched in parallel for fast hydration.
+- From the detail panel: change status, add/remove assignees, post notes, or "Start FlowPilot" / "Open in ResolutionAssist" with full context.
+- New Ticket modal offers both AI-parse ("Create a high-priority ticket for Acme — Outlook not syncing for jsmith") and a traditional form.
+
+Without a PSA connection, `/tickets` is hidden from the sidebar entirely — there's nothing to show.
+
+---
+
+## Summary
+
+- **FlowPilot** = guided, structured, lifecycle-heavy, ideal for resolvable issues and handoffs.
+- **ResolutionAssist** = freeform chat, ideal for scoping and quick answers.
+- **Without PSA** = both work, sessions live in ResolutionFlow, summaries are yours to export.
+- **With PSA** = both become ticket-aware, write back to CW (notes, status, resources), and can spawn spin-off tickets mid-session.
+
+The AI is the same under the hood. The difference is how much structure you want around the conversation — and how deeply the result needs to integrate with your ticketing system.

docs/FlowAssist_Migration/CODEX-FlowAssist-Migration-PLAN.md

@@ -0,0 +1,178 @@
+# FlowPilot Migration Plan: Phase 0 Through Phase 7
+
+## Summary
+- Stay code-change-free until execution is explicitly requested.
+- Implement in commit-sized phases, with Phase 0 as a prerequisite for AI-heavy Phases 2+.
+- Use this repo’s existing `/api/v1/ai-sessions` API namespace instead of the doc’s generic `/sessions` path.
+- Move the existing chat-first `AssistantChatPage` to `/pilot`; `/assistant` becomes a permanent redirect.
+- Keep `ai_sessions.session_type` for compatibility, but the user-facing product becomes one FlowPilot surface.
+
+## Phase 0: Prompt Caching Infrastructure
+- Consolidate Anthropic prompt caching into `backend/app/core/ai_provider.py`, then route all Anthropic calls through that provider.
+- Preserve the existing cached behavior from `assistant_chat_service`, but remove the private duplicate cached implementation once provider parity exists.
+- Add cache-control blocks for static system prompt sections and stable tool/context prefixes; keep volatile user messages outside the cached prefix.
+- Update one-shot AI generators and `/tickets/ai-parse` to separate stable context from changing request content.
+- Instrument every Anthropic response with `cache_read_input_tokens` and `cache_creation_input_tokens`.
+- Acceptance: two identical FlowPilot/provider-backed calls within 5 minutes show creation tokens on the first call and read tokens on the second.
+
+## Phase 1: Schema + Route Rename
+- Add Alembic migration after current repo head with:
+  - `session_facts`
+  - `session_suggested_fixes`
+  - `draft_templates`
+  - `account_settings`
+  - new artifact columns on `ai_sessions`
+  - provenance columns on `script_templates`
+- Create `account_settings` as one lazy row per account:
+  - `account_id` primary key, FK to `accounts(id)` with cascade delete
+  - `preferences JSONB NOT NULL DEFAULT '{}'`
+  - timestamps
+  - `get_setting(key, default)` helper on the SQLAlchemy model
+  - `templatize_prompt_enabled` default read as `true` when the row/key is absent
+- Apply RLS to all new tenant-scoped tables using the repo’s `app.current_account_id` policy pattern.
+- Route `/pilot` and `/pilot/:sessionId` to the existing chat UI; redirect `/assistant` and `/assistant/:sessionId` permanently.
+- Update sidebar, command palette, dashboard cards, session list links, and visible labels from “AI Assistant”/ResolutionAssist to “FlowPilot” where they describe the troubleshooting surface.
+- Acceptance: `/pilot` renders the chat UI, `/assistant` redirects, RLS grep/check passes, and no Phase 2 UI is introduced yet.
+
+## Phase 2: What We Know
+- Add `FactSynthesisService` for conservative conversion of answers/check outputs into facts.
+- Add fact APIs under `/api/v1/ai-sessions/{id}/facts`:
+  - list, create manual note, update editable fact, soft-delete, promote source item.
+- Extend `unified_chat_service` marker parsing with `[PROMOTE]`; do not create a separate marker pipeline.
+- Because current questions/checks live in `ai_sessions.pending_task_lane` JSON, Phase 2 must assign stable UUIDs to task-lane questions/actions/checks when they are first persisted. `session_facts.source_ref` points to those stable JSON item IDs; it remains polymorphic and unconstrained at the DB level.
+- Add frontend task lane components under the new FlowPilot component namespace:
+  - `TaskLane`
+  - `WhatWeKnow`
+  - `WhatWeKnowItem`
+  - `AddNoteButton`
+  - moved/refactored Questions and Diagnostic Checks sections
+- Place What We Know above Questions. Facts from questions/checks are read-only at the fact card level; manual and AI-synthesis facts are editable.
+- Acceptance: answering a question or completing a check can promote a fact within 2 seconds; manual notes persist; page reload preserves facts; cross-account access is blocked.
+
+## Phase 3: Suggested Fix + Resolve Preview
+- Add suggested-fix APIs under `/api/v1/ai-sessions/{id}/suggested-fixes`:
+  - get active suggested fix
+  - record decision for one-off/draft-template/build-template/dismissed
+- Extend `unified_chat_service` marker parsing with `[SUGGEST_FIX]`; supersede the prior active fix when a new one is persisted.
+- Add `ResolutionNoteGeneratorService` that builds the fixed markdown shape:
+  - Problem
+  - What we confirmed
+  - Root cause
+  - Resolution
+- Add preview endpoint at `/api/v1/ai-sessions/{id}/resolution-note/preview`.
+- Generate the preview from `ai_sessions`, `session_facts`, active suggested fix, and linked script generations; redact sensitive script parameters.
+- Cache preview output by session-state version or content hash; invalidate on fact/suggested-fix/script-generation writes.
+- Add `SuggestedFix`, `ResolveButton`, and `ResolutionNotePreview` popover. Debounce preview refresh to 500ms.
+- Acceptance: a session with facts and a suggested fix shows a four-section preview; editing a fact refreshes preview; human review confirms no unsupported claims.
+
+## Phase 4: Resolve + Escalate Writebacks
+- Add `EscalationPackageGeneratorService` with handoff-oriented markdown:
+  - Problem
+  - What we’ve confirmed
+  - What we’ve tried
+  - Current hypothesis
+  - Suggested next steps
+- Add preview/post endpoints under `/api/v1/ai-sessions/{id}`:
+  - `/resolution-note/preview`
+  - `/resolution-note/post`
+  - `/escalation-package/preview`
+  - `/escalation-package/post`
+- Extend PSA writeback service using the existing PSA provider registry and `post_note` seam.
+- Implement “confirm and fire”: engineer edits preview, clicks Confirm & post, then server posts to PSA and stores result metadata.
+- Ticket status transitions must verify by re-fetching status; failed verification is surfaced as an error, not silent success.
+- Resolving without a linked PSA ticket stores markdown and marks the session resolved without external posting.
+- Acceptance: ConnectWise test ticket receives the note/package, status verification works, and unlinked sessions resolve locally.
+
+## Phase 5: Inline Script Generator Integration
+- Add inline Script Generator components:
+  - `TemplateMatchPanel`
+  - `NoTemplateDialog`
+  - `ParameterizationPreview`
+- For template matches, clicking the suggested fix opens the existing Script Generator flow with parameters prefilled from facts, ticket context, account/PSA config, and AI-suggested values.
+- For no-template matches, show the three-option dialog:
+  - Run as one-off
+  - Run now, templatize after resolve
+  - Build as template now
+- Persist the selected path on `session_suggested_fixes.user_decision`.
+- Add `TemplateExtractionService` for converting concrete scripts into proposed parameter schemas and templated bodies.
+- Link every script generation back to `ai_sessions` via existing `script_generations.ai_session_id`.
+- `Cmd+K → script` opens the inline generator from the FlowPilot session; no Resolve keyboard shortcut is added.
+- Acceptance: matched templates prefill parameters; no-match flow shows three options; all options produce the correct session/template side effects.
+
+## Phase 6: Post-Resolve Templatize Prompt
+- Add `TemplatizePrompt` after successful Resolve only when:
+  - the account setting allows prompts
+  - the session has pending `draft_templates`
+  - the user chose “Run now, templatize after resolve”
+- Accept flow creates a real `script_templates` row with:
+  - `source_session_id`
+  - `source_user_id`
+  - `source_ticket_ref`
+  - accepted parameter schema/body edits
+- Skip flow marks the draft rejected.
+- “Don’t ask me again for this team” writes `{"templatize_prompt_enabled": false}` to `account_settings.preferences`.
+- Script Library shows a pending-drafts badge/count for the account.
+- Acceptance: accept creates a visible template with provenance; skip creates no template; disabled prompt is respected on the next resolve.
+
+## Phase 7: Polish
+- Match the authoritative mockup HTML for spacing, colors, typography, and component structure; use PNGs for visual target confirmation.
+- Add loading states for fact synthesis, preview generation, template extraction, PSA post/verify, and script generation.
+- Add empty states for:
+  - no facts
+  - no questions
+  - no checks
+  - no suggested fix
+  - no pending draft templates
+- Add keyboard shortcuts except Resolve:
+  - `Cmd+K` command palette
+  - `Cmd+Enter` send composer
+  - `Cmd+G` script generator
+- At widths below 1200px, collapse the task lane into a bottom drawer.
+- Use existing design tokens where present; add missing tokens only if needed to match the mockups.
+- Acceptance: major screens visually compare within the doc’s tolerance, no horizontal scroll at 1280px, mobile task lane works, and shortcuts do not conflict with browser reload.
+
+## Public Interfaces
+- New backend routes use `/api/v1/ai-sessions/{id}/...`, not `/api/v1/sessions/{id}/...`.
+- Existing chat creation/message APIs remain compatible.
+- `session_type` remains queryable and stored, but frontend routing no longer sends chat sessions to `/assistant`.
+- New persistent entities:
+  - `session_facts`
+  - `session_suggested_fixes`
+  - `draft_templates`
+  - `account_settings`
+- New persisted artifact columns on `ai_sessions` store resolution/escalation markdown and PSA post metadata.
+
+## Test Plan
+- Migration tests:
+  - fresh DB upgrade succeeds
+  - downgrade succeeds if the repo expects reversible migrations
+  - new tables have RLS enabled/forced
+  - tenant policy includes `app.current_account_id`
+- Backend tests:
+  - fact CRUD and promotion authorization
+  - suggested-fix supersession and decision persistence
+  - preview generation cache invalidation
+  - Resolve/Escalate local-only behavior without PSA
+  - PSA status verification failure path
+  - draft-template accept/reject behavior
+- Frontend tests:
+  - route redirects
+  - task lane rendering and persistence
+  - inline editing and preview refresh
+  - script generator option flows
+  - templatize prompt settings behavior
+  - responsive drawer behavior
+- Manual QA:
+  - run through one ConnectWise linked Resolve
+  - run through one Escalate
+  - run one template-match script path
+  - run one no-template draft-template path through post-resolve save
+
+## Assumptions
+- Phase 0 is included and must be complete before Phase 2 begins.
+- No Resolve keyboard shortcut in this migration.
+- Templatize prompt defaults to enabled.
+- Resolution notes use engineer review plus Confirm & post, not supervisor staging.
+- Existing component folders may be renamed opportunistically, but behavior and route migration matter more than directory-name purity.
+- No backfill of What We Know for old sessions.
+- Team Wiki compilation, SharePoint integration, marketplace sharing, and confidence-tier UI are out of scope.

docs/FlowAssist_Migration/FLOWPILOT-MIGRATION-v1.md

@@ -0,0 +1,809 @@
+# FlowPilot Migration — Design & Implementation Doc
+
+> **Target:** Transform `/assistant` (ResolutionAssist) into the new unified `/pilot` (FlowPilot) surface.
+> **Audience:** Claude Code (implementation) reviewed by Michael (owner).
+> **Status:** Design locked. Ready for phased implementation.
+> **Last updated:** April 17, 2026
+
+---
+
+## 0. Prerequisite reading for Claude Code
+
+Before writing any code, read these in order:
+
+1. This document end-to-end.
+2. `mockups/01-session-primary.png` — the target state for the main session UI.
+3. `mockups/02-script-template-match.png`, `03-script-three-options.png`, `04-script-templatize-prompt.png` — Script Generator integration states.
+4. The source HTML files `mockups/01-session-primary.html` and `mockups/02-04-script-integration.html` — authoritative for spacing, colors, and component structure. When CSS or layout questions arise during implementation, these files are the tiebreaker.
+
+Do not proceed to implementation until you have confirmed you understand the following three architectural claims. If any of them are unclear, stop and ask.
+
+1. **There is one AI troubleshooting surface, not two.** The existing split between FlowPilot (guided) and ResolutionAssist (chat) is collapsed into a single chat-primary product called FlowPilot at `/pilot`. The `ai_sessions.session_type` discriminator column is retained for data, but the product shows one unified UI.
+2. **The task lane is the load-bearing structural feature.** It is not a sidebar of metadata. It actively tracks diagnostic state: *What we know*, *Questions*, *Diagnostic checks*, *Suggested fix*. Engineers interact with it; facts flow between sections.
+3. **Resolve and Escalate are deterministic artifact generators, not free-text prompts.** When an engineer clicks Resolve, a structured summary is generated from task lane state (not from the chat transcript alone) and posted to CW. The summary structure is fixed: *Problem / What we confirmed / Root cause / Resolution*.
+
+---
+
+## 1. Why this change
+
+### The current state
+
+- `/assistant` is a chat-primary AI session with a `[QUESTIONS]` and `[DIAGNOSTIC_CHECKS]` task lane.
+- `/pilot` was specced as a separate guided, confidence-tiered wizard with a different UI and lifecycle.
+- The `FLOWPILOT-AND-RESOLUTIONASSIST.md` design document treated them as two products sharing a backend.
+
+### The problems with the current state
+
+- Two sidebar entries, two session histories, two mental models for engineers to learn.
+- The PSA integration scope doubles (writebacks for lifecycle events must be built twice, or built for Pilot and bolted onto Assist).
+- The Team Wiki moat depends on structured session artifacts with explicit resolutions — a chat-only mode produces weaker artifacts.
+- The cockpit positioning (the core ResolutionFlow brand promise) does not map to a blank chat window.
+- Branching into two modes forces a decision onto the engineer ("which mode for this ticket?") that has no right answer.
+
+### The resolution
+
+The existing `/assistant` UI already does most of what `/pilot` was supposed to do — structured questions, diagnostic checks, lifecycle actions in the header. It is closer to the right product than the doc anticipated. Rather than building Pilot as a second surface, we extend Assist with the missing structural features (*What we know*, auto-generated summaries, escalation packages) and rename it FlowPilot.
+
+### The strategic move
+
+FlowPilot becomes the single canonical troubleshooting surface. Every PSA writeback, every Wiki compilation path, every Script Generator invocation points here. One session shape, one lifecycle, one integration surface.
+
+---
+
+## 2. Terminology used in this document
+
+| Term | Meaning |
+|---|---|
+| **Session** | A single `ai_sessions` row representing one troubleshooting conversation. |
+| **Task lane** | The right-side panel containing What we know, Questions, Diagnostic checks, Suggested fix. |
+| **Fact** | An item in the What we know section. Has `text`, `source_type` (`question` / `diagnostic_check` / `user_note`), and `source_ref` (FK to the originating question/check, or null for user notes). |
+| **Suggested fix** | The AI's current best-guess resolution path. Has a confidence score and, optionally, a reference to a Script Library template. |
+| **Promotion** | The act of a question answer or diagnostic check result being converted into a fact in What we know. Triggered by AI, confirmed/editable by engineer. |
+| **Resolution note** | The structured document generated when the engineer clicks Resolve. Posted to CW as a ticket note. |
+| **Escalation package** | The structured handoff document generated when the engineer clicks Escalate. Posted to CW and attached to the session for the next engineer. |
+
+---
+
+## 3. Target UI — annotated
+
+### 3.1 Primary session view
+
+![Primary session view](mockups/01-session-primary.png)
+
+The session UI is a four-column layout:
+
+1. **Icon rail** (64px wide) — primary app navigation. FlowPilot / Tickets / Trees / Scripts / Wiki. Avatar at bottom.
+2. **Session list** (260px wide) — all sessions grouped by state (Active / Recent). Each row shows title, state dot, PSA ticket number, and client name.
+3. **Conversation column** (fluid) — the chat thread, composer, and incident header.
+4. **Task lane** (380px wide) — *What we know*, *Questions*, *Diagnostic checks*, *Suggested fix*, and the Resolve action at the bottom.
+
+Key visual and behavioral elements numbered against the mockup:
+
+**Incident header (top of conversation column)**
+- PSA chip showing `CW #48291` in cyan, monospaced
+- Client / contact / priority meta line
+- Incident title in Bricolage Grotesque 19px
+- Four lifecycle buttons right-aligned: **Pause** (ghost), **Share update** (neutral), **Escalate** (amber), **Resolve** (green)
+
+**Conversation column**
+- Standard chat thread with pilot and user avatars
+- Pilot uses cyan gradient avatar; user uses purple gradient
+- AI messages in `bg-2` bubbles with subtle border; user messages in cyan-tinted bubbles
+- Composer at bottom with inline action chips (Attach / Paste logs / Ticket context) and a send button
+
+**Task lane sections, in order:**
+
+1. **What we know** (NEW)
+   - Header: `WHAT WE KNOW · 4` (section title + count)
+   - Each fact is a card: `bg-2` background, dashed circular green check, fact text, and a provenance line (`from question · rules out tenant/license`)
+   - "+ Add a note" button at the bottom for manual facts from the engineer
+   - Background has a subtle green-to-transparent gradient to visually distinguish from the rest of the lane
+
+2. **Questions**
+   - Header: `QUESTIONS · 2 unanswered`
+   - Each unanswered question: title, AI hint text, Answer / Skip buttons
+   - Answered questions dim to 55% opacity with a dashed border and show the resolution inline (`Answered · isolated to jsmith (promoted to What we know)`)
+
+3. **Diagnostic checks**
+   - Header: `DIAGNOSTIC CHECKS · 1 / 3 run`
+   - "Run remaining 2 checks" button at top when applicable
+   - Each check: icon + command name (monospaced), description
+   - Completed checks dim and show "Complete · findings promoted to What we know" in green
+
+4. **Suggested fix**
+   - Header: `SUGGESTED FIX · 94% confidence`
+   - Amber-accented card with fix title and description
+   - Clicking opens the Script Generator flow (Section 5)
+
+**Resolve action bar (bottom of task lane)**
+- Small hint text ("Summary preview is open →")
+- Full-width "Resolve & post to CW" button in green
+
+**Resolution note preview (floating, anchored to Resolve button)**
+- A persistent popover, NOT a modal
+- Shows the draft resolution note with Problem / What we confirmed / Root cause / Resolution sections
+- Displays the target ticket (`CW #48291`) and status change (`Resolved`)
+- Edit button opens an inline editor; Confirm & post fires the PSA writeback
+
+### 3.2 Script Generator integration — template match
+
+![Template match flow](mockups/02-script-template-match.png)
+
+When the suggested fix references an existing Script Library template, clicking the fix opens the Script Generator panel in place of (or sliding over) the task lane. Key behavior:
+
+- A **Verified template** badge appears above the parameter form
+- Parameters pre-filled from session context get a cyan `from session` tag and a cyan-tinted input background
+- Each pre-filled parameter has a hint line explaining the source: *"Pulled from CW company config for Acme Corp"*
+- The engineer can adjust any pre-filled value before generating
+- `⌘K` → "script" invokes the generator mid-conversation from anywhere in the session
+
+### 3.3 Script Generator integration — no template match (three-option dialog)
+
+![No template match](mockups/03-script-three-options.png)
+
+When no template matches the suggested fix, FlowPilot drafts a session-specific script and presents three paths:
+
+1. **Run as one-off** (neutral outline CTA)
+   - Script generated and captured in session documentation, discarded after
+   - Tradeoffs: fastest, but team won't benefit next time
+
+2. **Run now, templatize after resolve** (RECOMMENDED, cyan primary CTA)
+   - Script generated for this ticket; draft template queued
+   - Post-resolve prompt offers to templatize (Section 5.3)
+   - Tradeoffs: zero cognitive overhead now, only templatize what works, ~30s review later
+
+3. **Build as template now** (purple outline CTA)
+   - Full parameterization upfront
+   - Tradeoffs: immediate team benefit, but adds time mid-ticket
+
+The drafted script renders as a code preview above the option cards with the AI's proposed parameters highlighted in amber.
+
+### 3.4 Script Generator integration — post-resolve templatization prompt
+
+![Templatize prompt](mockups/04-script-templatize-prompt.png)
+
+If the engineer picked Option 2 in the three-option dialog and Resolve succeeds, this prompt appears after the resolution note is posted to CW:
+
+- Success banner confirms the resolution posted
+- Templatize card shows the script with AI-proposed parameters substituted in as `{{ gateway_host }}`, etc.
+- Right pane lists extracted parameters with remove buttons (engineer can adjust)
+- Provenance note: *"generated from CW #48307 · resolved by M. Davis"*
+- Three actions: Skip / Edit parameters / Save as team template
+- "Don't ask me again for this team" opt-out in footer
+
+---
+
+## 4. Data model changes
+
+### 4.1 New columns on `ai_sessions`
+
+```sql
+ALTER TABLE ai_sessions
+  ADD COLUMN resolution_note_markdown TEXT NULL,
+  ADD COLUMN resolution_note_posted_at TIMESTAMPTZ NULL,
+  ADD COLUMN resolution_note_external_id VARCHAR(128) NULL,  -- CW note ID after posting
+  ADD COLUMN escalation_package_markdown TEXT NULL,
+  ADD COLUMN escalation_package_posted_at TIMESTAMPTZ NULL;
+```
+
+No migration of `session_type` — the column stays. New sessions all default to the unified FlowPilot type.
+
+### 4.2 New `session_facts` table (the What we know backing store)
+
+```sql
+CREATE TABLE session_facts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id UUID NOT NULL REFERENCES ai_sessions(id) ON DELETE CASCADE,
+  account_id UUID NOT NULL REFERENCES accounts(id),  -- for RLS, per multi-tenant architecture
+  text TEXT NOT NULL,
+  source_type VARCHAR(32) NOT NULL CHECK (source_type IN ('question', 'diagnostic_check', 'user_note', 'ai_synthesis')),
+  source_ref UUID NULL,  -- FK to session_questions.id or session_diagnostic_checks.id, null for user_note
+  source_summary TEXT NULL,  -- free-text provenance label, e.g. "rules out tenant/license"
+  created_by UUID NOT NULL REFERENCES users(id),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  deleted_at TIMESTAMPTZ NULL
+);
+CREATE INDEX idx_session_facts_session ON session_facts(session_id) WHERE deleted_at IS NULL;
+CREATE INDEX idx_session_facts_account ON session_facts(account_id);
+```
+
+**Important:** `source_ref` is a polymorphic FK and should NOT have a database-level FK constraint. Enforce integrity at the service layer.
+
+### 4.3 New `session_suggested_fixes` table
+
+```sql
+CREATE TABLE session_suggested_fixes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id UUID NOT NULL REFERENCES ai_sessions(id) ON DELETE CASCADE,
+  account_id UUID NOT NULL REFERENCES accounts(id),
+  title VARCHAR(200) NOT NULL,
+  description TEXT NOT NULL,
+  confidence_pct INTEGER NOT NULL CHECK (confidence_pct BETWEEN 0 AND 100),
+  script_template_id UUID NULL REFERENCES script_templates(id),  -- null if no template match
+  ai_drafted_script TEXT NULL,                                    -- populated if no template match
+  ai_drafted_parameters JSONB NULL,                               -- AI's proposed parameterization
+  user_decision VARCHAR(32) NULL CHECK (user_decision IN ('one_off', 'draft_template', 'build_template', 'dismissed')),
+  superseded_at TIMESTAMPTZ NULL,  -- set when a new suggestion replaces this one
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX idx_session_suggested_fixes_session ON session_suggested_fixes(session_id) WHERE superseded_at IS NULL;
+```
+
+A session can have multiple suggested fixes over time as the AI's understanding evolves. Only one is active (superseded_at IS NULL) at a time.
+
+### 4.4 New `draft_templates` table
+
+Backing store for Option 2 in the three-option dialog — scripts generated during sessions that are pending templatization.
+
+```sql
+CREATE TABLE draft_templates (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  account_id UUID NOT NULL REFERENCES accounts(id),
+  source_session_id UUID NOT NULL REFERENCES ai_sessions(id),
+  source_user_id UUID NOT NULL REFERENCES users(id),
+  script_body TEXT NOT NULL,
+  proposed_parameters JSONB NOT NULL,  -- {"parameters": [{"key": "...", "label": "...", "type": "..."}]}
+  proposed_name VARCHAR(200) NULL,
+  proposed_category_id UUID NULL REFERENCES script_categories(id),
+  status VARCHAR(32) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'accepted', 'rejected')),
+  resolved_at TIMESTAMPTZ NULL,  -- when the user acted on the draft
+  promoted_template_id UUID NULL REFERENCES script_templates(id),  -- if accepted, the created template
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+Accepted draft templates produce a new `script_templates` row and record the source session for provenance display.
+
+### 4.5 Extension to `script_templates`
+
+```sql
+ALTER TABLE script_templates
+  ADD COLUMN source_session_id UUID NULL REFERENCES ai_sessions(id),
+  ADD COLUMN source_user_id UUID NULL REFERENCES users(id),
+  ADD COLUMN source_ticket_ref VARCHAR(64) NULL;  -- e.g. "CW #48307" for display
+```
+
+These fields power the provenance chip in the Script Library: *"generated from CW #48307 · resolved by M. Davis · used 7 times"*.
+
+### 4.6 Per-account settings
+
+```sql
+ALTER TABLE account_settings
+  ADD COLUMN templatize_prompt_enabled BOOLEAN NOT NULL DEFAULT true;
+```
+
+Controls whether the post-resolve templatize prompt appears. Toggleable from the prompt's footer ("Don't ask me again for this team") and from admin settings.
+
+---
+
+## 5. API endpoints
+
+All endpoints follow ResolutionFlow conventions: `/api/v1/` prefix, JWT auth, tenant-scoped via RLS.
+
+### 5.1 Session facts
+
+```
+GET    /api/v1/sessions/{id}/facts               List facts for a session (ordered by created_at ASC)
+POST   /api/v1/sessions/{id}/facts               Create a manual fact (user_note source_type)
+PATCH  /api/v1/sessions/{id}/facts/{fact_id}     Edit fact text or summary (only for user_note or AI-synthesized facts)
+DELETE /api/v1/sessions/{id}/facts/{fact_id}     Soft-delete
+POST   /api/v1/sessions/{id}/facts/promote       Promote a question answer or check result to a fact
+                                                 Body: { source_type, source_ref, proposed_text, proposed_summary }
+                                                 Returns the created fact. Used by the AI synthesis flow and
+                                                 by the engineer's explicit "promote to What we know" action.
+```
+
+### 5.2 Suggested fixes
+
+```
+GET    /api/v1/sessions/{id}/suggested-fixes/active     Returns the current active fix (superseded_at IS NULL) or 404
+POST   /api/v1/sessions/{id}/suggested-fixes/{fix_id}/decision
+                                                        Body: { decision: "one_off" | "draft_template" | "build_template" | "dismissed" }
+                                                        Records the user's path choice. Server-side side effects:
+                                                        - one_off: generates script via ScriptTemplateEngine, returns rendered script
+                                                        - draft_template: same as one_off, plus creates draft_templates row
+                                                        - build_template: redirects to full template creation flow
+                                                        - dismissed: marks fix as superseded
+```
+
+### 5.3 Draft templates (post-resolve flow)
+
+```
+GET    /api/v1/draft-templates                          List pending drafts for the current user's account
+                                                        (used by the Script Library "X scripts ready to review" notification)
+GET    /api/v1/draft-templates/{id}                     Get a single draft including its proposed parameterization
+POST   /api/v1/draft-templates/{id}/accept              Body: { name, category_id, parameters_schema, edits }
+                                                        Creates a new script_templates row with source_session_id set,
+                                                        sets draft status to 'accepted', returns the new template
+POST   /api/v1/draft-templates/{id}/reject              Sets status to 'rejected'
+```
+
+### 5.4 Resolution notes and escalation packages
+
+```
+POST   /api/v1/sessions/{id}/resolution-note/preview    Generates the draft resolution note from current session state
+                                                        WITHOUT posting. Returns { markdown, target_ticket_ref }.
+                                                        Called when the task lane renders and refreshed whenever
+                                                        facts/suggested fix change.
+POST   /api/v1/sessions/{id}/resolution-note/post       Body: { markdown }  (engineer-edited version)
+                                                        Posts to the linked PSA ticket, updates ticket status if configured,
+                                                        marks session resolved.
+POST   /api/v1/sessions/{id}/escalation-package/preview Same pattern for escalation
+POST   /api/v1/sessions/{id}/escalation-package/post    Posts and transitions session to escalated state
+```
+
+---
+
+## 6. Services to implement
+
+### 6.1 `FactSynthesisService` (new)
+
+**Location:** `services/fact_synthesis_service.py`
+
+**Purpose:** Converts question answers and diagnostic check results into candidate facts. Called by the AI pipeline when the LLM emits a `[PROMOTE]` marker, and by explicit engineer action.
+
+**Key methods:**
+- `synthesize_from_question(question_id: UUID, raw_answer: str) -> dict` — returns `{proposed_text, proposed_summary}` via LLM call. The summary is the short provenance label ("rules out tenant/license").
+- `synthesize_from_check(check_id: UUID, check_output: str) -> dict` — same pattern for diagnostic check output.
+- `create_fact(session_id, source_type, source_ref, text, summary, user_id) -> SessionFact` — persists the fact.
+
+**Prompt engineering note:** The synthesis prompt should be conservative — short, factual statements. Hallucinated specifics are a trust-killer. The prompt must explicitly instruct: *"Use only information present in the answer/output. If the answer does not contain a substantive fact, return null."*
+
+### 6.2 `ResolutionNoteGeneratorService` (new)
+
+**Location:** `services/resolution_note_generator.py`
+
+**Purpose:** Produces the structured resolution note markdown from session state.
+
+**Input:** session_id
+**Output:** `{markdown: str, target_ticket_ref: str | None}`
+
+**Template structure:**
+```markdown
+## Problem
+{ai-synthesized one-paragraph problem statement, pulling from session description + incident header}
+
+## What we confirmed
+{bulleted list of session_facts, grouped by source_type}
+
+## Root cause
+{ai-synthesized from the active suggested fix + facts}
+
+## Resolution
+{description of the fix applied, parameters used if a script ran, outcome}
+```
+
+The service pulls from four data sources: `ai_sessions`, `session_facts`, `session_suggested_fixes` (active), and `script_generations` (if scripts ran during the session). Passwords in script_generations.parameters_used must be redacted (already a Script Generator pattern per the existing plan).
+
+**Critical:** This service is called on every fact/suggestion change to keep the preview live. Cache aggressively — LLM calls for every keystroke will blow the budget. Invalidate the cache on any write to session_facts or session_suggested_fixes.
+
+### 6.3 `EscalationPackageGeneratorService` (new)
+
+**Location:** `services/escalation_package_generator.py`
+
+Same structure as ResolutionNoteGenerator but with a handoff-oriented template:
+
+```markdown
+## Problem
+...
+
+## What we've confirmed
+...
+
+## What we've tried
+{list of diagnostic_checks run with their outcomes, scripts generated}
+
+## Current hypothesis
+{active suggested fix description}
+
+## Suggested next steps
+{ai-synthesized from the gap between facts and a complete resolution}
+```
+
+### 6.4 `TemplateExtractionService` (new)
+
+**Location:** `services/template_extraction_service.py`
+
+**Purpose:** Given a concrete rendered script and session context, propose a parameterization.
+
+**Input:** `{script_body: str, session_context: dict, ticket_context: dict}`
+**Output:** `{parameters: [{key, label, type, inferred_from}], templated_body: str}`
+
+**Implementation approach:**
+- LLM call with a structured prompt: "Given this script that resolved a ticket, identify values that would change for a different invocation. Propose a parameter schema following the Script Generator conventions (text / password / select / boolean / multi_text / number / textarea)."
+- Post-process to ensure the proposed template renders back to the original script when given the extracted parameter values.
+- Conservative default: prefer fewer parameters. If a value looks environment-agnostic (e.g. a command name), don't parameterize it.
+
+This service is the engine behind Option 2 and Option 3 of the three-option dialog, and behind the post-resolve templatize prompt.
+
+### 6.5 Extend `PSAWritebackService` (existing)
+
+Add methods:
+- `post_resolution_note(session_id, markdown) -> {external_id, posted_at}`
+- `post_escalation_package(session_id, markdown) -> {external_id, posted_at}`
+- `transition_ticket_status(ticket_ref, new_status) -> {success, verified_status}`
+
+The `transition_ticket_status` method must verify the status change took effect (per the existing ConnectWise integration principle: "never told 'success' when CW silently rejected the change").
+
+### 6.6 Model selection per service
+
+Each AI-calling service must use a configurable model string from application settings, not a hardcoded model. Use these defaults:
+
+```python
+FACT_SYNTHESIS_MODEL = "claude-haiku-4-5-20251001"           # short transformation, latency-sensitive
+RESOLUTION_NOTE_MODEL = "claude-sonnet-4-6"                  # customer-facing artifact, quality matters
+ESCALATION_PACKAGE_MODEL = "claude-sonnet-4-6"               # same
+TEMPLATE_EXTRACTION_MODEL = "claude-sonnet-4-6"              # creates persistent library artifact
+MAIN_CONVERSATION_MODEL = "claude-sonnet-4-6"                # primary FlowPilot chat
+```
+
+Do not hardcode model strings at call sites. Every new service must read from settings with a service-specific key.
+
+**Instrumentation requirement:** log a `disputed_fact_rate` metric for fact synthesis — the percentage of AI-synthesized facts that engineers subsequently edit or delete. If this exceeds 10% over a 500-session window, escalate `FACT_SYNTHESIS_MODEL` to `claude-sonnet-4-6`. If under 5%, Haiku is performing correctly.
+
+Do not use Opus 4.7 for any of these services at current scale.
+
+---
+
+## 7. Frontend components
+
+### 7.1 Routes to change
+
+| Current route | New route | Action |
+|---|---|---|
+| `/assistant` | `/pilot` | **Rename** the route. The existing page moves. `/assistant` permanently redirects to `/pilot` with no sunset date. |
+| `/pilot` (if it exists as a separate guided flow) | REMOVED | Collapse into the unified surface. |
+| `/pilot/session/:id` | `/pilot/session/:id` | No change (this is where the unified session UI lives) |
+
+Sidebar nav entry renames from "ResolutionAssist" to "FlowPilot" with the cockpit icon.
+
+### 7.2 New React components
+
+Under `src/components/pilot/`:
+
+```
+TaskLane.tsx                  -- The right-side panel, owns all four sections
+  sections/
+    WhatWeKnow.tsx            -- New component for the facts list
+    WhatWeKnowItem.tsx        -- Single fact card with provenance line
+    AddNoteButton.tsx         -- "+ Add a note" inline composer
+    Questions.tsx             -- Existing questions rendering (moved if already present)
+    DiagnosticChecks.tsx      -- Existing checks rendering (moved if already present)
+    SuggestedFix.tsx          -- New or refactored component for the suggested fix card
+ResolveButton.tsx             -- The Resolve CTA at the bottom of the task lane
+ResolutionNotePreview.tsx     -- Floating popover anchored to Resolve button
+EscalatePackagePreview.tsx    -- Same pattern for Escalate
+
+ScriptGenInline/              -- Script Generator embedded in session context
+  TemplateMatchPanel.tsx      -- Scene 1 mockup: template pre-filled
+  NoTemplateDialog.tsx        -- Scene 2 mockup: three-option dialog
+  TemplatizePrompt.tsx        -- Scene 3 mockup: post-resolve prompt
+  ParameterizationPreview.tsx -- Shared component: script with highlighted params
+```
+
+### 7.3 Component behavior contracts
+
+**`WhatWeKnowItem`**
+- Props: `{fact: SessionFact, onEdit, onDelete}`
+- Renders the fact text, a green checkmark, and the provenance line with source-type color coding
+- Clicking the fact text opens inline edit (only for `user_note` and `ai_synthesis` sources — question/check facts are read-only, edit the source instead)
+
+**`TaskLane`**
+- Subscribes to a session state hook that polls for fact / question / check / suggested-fix updates
+- On any state change, calls `POST /api/v1/sessions/{id}/resolution-note/preview` to refresh the ResolutionNotePreview
+- Debounce preview refresh to 500ms to avoid LLM spam
+
+**`NoTemplateDialog`** (three-option dialog)
+- Props: `{suggestedFix, onDecision}`
+- Renders the three cards with the middle (draft_template) marked as recommended
+- `onDecision` posts to `/api/v1/sessions/{id}/suggested-fixes/{fix_id}/decision` and either opens the Script Generator (one_off / draft_template) or navigates to full template creation (build_template)
+
+**`TemplatizePrompt`**
+- Rendered after successful Resolve when a draft template exists for the session
+- Fetches proposed parameters from the draft template record
+- Save button posts to `/api/v1/draft-templates/{id}/accept`
+
+---
+
+## 8. AI prompt changes
+
+The existing FlowPilot / ResolutionAssist system prompt needs updates to emit the new markers.
+
+### 8.1 New marker: `[PROMOTE]`
+
+Used to surface facts to What we know. Syntax:
+
+```
+[PROMOTE]
+source_type: question
+source_ref: {question_id}
+text: OWA login and send/receive confirmed working for jsmith
+summary: rules out tenant/license
+[/PROMOTE]
+```
+
+The AI should emit `[PROMOTE]` blocks in the same message that answers or processes a question/check, so the fact appears in What we know simultaneously with the chat acknowledgment.
+
+### 8.2 New marker: `[SUGGEST_FIX]`
+
+```
+[SUGGEST_FIX]
+title: Clear cached credentials + rebuild Outlook profile
+description: Stale cached credential in Credential Manager is holding the pre-reset token...
+confidence: 94
+script_template_slug: clear-outlook-credentials   # or omitted if no template match
+ai_drafted_script: |                              # only if no template match
+  # Generated by FlowPilot...
+  ...
+[/SUGGEST_FIX]
+```
+
+### 8.3 Removed markers
+
+The old `[FORK]` marker from the ResolutionAssist prompt is removed. Forks were a Guided-mode concept; in the unified model, they're replaced by Questions with mutually exclusive answer options.
+
+---
+
+## 9. Implementation phases
+
+Each phase ends with a git commit and verification step. Do not advance to the next phase until verification passes.
+
+### Phase 0 — Prompt caching infrastructure (prerequisite)
+
+A codebase audit revealed that prompt caching is only implemented in `assistant_chat_service.py` (the file being deprecated). Every other Anthropic API call site — including all of FlowPilot's 7 call sites through `AnthropicProvider` — is uncached. Phase 0 must land before Phase 2 starts because new services built in Phase 2 will inherit caching from `AnthropicProvider` automatically once it's fixed.
+
+**Deliverables:**
+
+- **0.1** Promote `AnthropicProvider.generate_json()` and `generate_text_stream()` in `ai_provider.py` to the cached pattern currently implemented in `assistant_chat_service.py:_call_anthropic_cached()`. Convert the `system` string parameter to a structured system block list with `cache_control: {"type": "ephemeral"}` on the static portion. Add a second breakpoint on the last history message. For the streaming variant, capture the final usage object via `get_final_message()`. Log `cache_read_input_tokens` and `cache_creation_input_tokens` on every response.
+- **0.2** Update `integrations.py:557` (`/tickets/ai-parse`) to move the members list and team-stable boards data into a cached system block.
+
+  > **Phase 0.2 — pending target endpoint.** The `/tickets/ai-parse` endpoint described in the original migration doc does not exist in the codebase as of this commit. When this endpoint is built, apply the cached-system-block pattern:
+  >
+  > ```python
+  > system_blocks = [
+  >     {"type": "text", "text": members_json, "cache_control": {"type": "ephemeral"}},
+  >     # cacheable: team-stable
+  >     {"type": "text", "text": boards_json, "cache_control": {"type": "ephemeral"}},
+  >     # cacheable: team-stable
+  >     {"type": "text", "text": engineer_description},
+  >     # uncached: per-request
+  > ]
+  > ```
+  >
+  > Remove this note when the endpoint is implemented and the pattern applied.
+- **0.3** Add `cache_control` to one-shot generators: `ai_tree_generator`, `kb_conversion`, `ai_fix`, `script_builder`. Same pattern as 0.1.
+- **0.4** Extract the caching logic from `assistant_chat_service.py:_call_anthropic_cached()` into `AnthropicProvider` and delete `_call_anthropic_cached`. `assistant_chat_service` should call the provider like every other service. This prevents two canonical implementations of the same pattern.
+
+**Verification:**
+
+- Hit any FlowPilot endpoint twice within 5 minutes. First call shows `cache_creation_input_tokens > 0`, second call shows `cache_read_input_tokens > 0`.
+- If the second call returns zero cache reads, inspect the prefix for silent invalidators (timestamps, unsorted JSON keys, varying tool list ordering). Fix before proceeding.
+
+```
+git commit -m "feat(ai): promote AnthropicProvider to cached pattern, consolidate caching implementation"
+```
+
+**Dependencies:**
+
+- Phase 1 (route rename and schema) can run in parallel with Phase 0.
+- Phase 2 (What we know) must not start until Phase 0 is complete and verified.
+
+### Phase 1 — Data model and route rename (backend + routing only)
+
+**Deliverables:**
+- Alembic migration creating `session_facts`, `session_suggested_fixes`, `draft_templates` tables and the column additions to `ai_sessions`, `script_templates`, `account_settings`
+- All tables include `account_id` and have RLS policies following the multi-tenant architecture (per existing project standard)
+- `/assistant` → `/pilot` route rename with permanent redirect (stays in place indefinitely; no sunset date)
+- Sidebar nav entry rename
+- No UI changes yet beyond the nav label
+
+**Verification:**
+- Run migration on a fresh dev database
+- Confirm RLS policies active via the existing CI grep check for `tenant_filter()`
+- Navigate to `/assistant` — should 301 to `/pilot`
+- Navigate to `/pilot` — should render the existing ResolutionAssist UI with the sidebar entry now reading "FlowPilot"
+
+```
+git commit -m "feat(pilot): rename /assistant to /pilot, add session_facts + suggested_fixes + draft_templates schema"
+```
+
+### Phase 2 — What we know (task lane + service + API)
+
+**Deliverables:**
+- `FactSynthesisService` and its LLM prompt
+- Fact CRUD API endpoints
+- `WhatWeKnow`, `WhatWeKnowItem`, `AddNoteButton` components
+- Task lane layout adjustment: What we know section renders above Questions
+- Counter in task lane header updates to `X / Y answered` format
+- AI prompt updated to emit `[PROMOTE]` markers; backend parses them and creates facts
+
+**Verification:**
+- Open a session, answer a question; within 2 seconds a fact should appear in What we know with correct provenance
+- Click "+ Add a note", type a manual fact, confirm it appears with `source_type: user_note`
+- Run a diagnostic check, confirm the check result promotes to a fact
+- Facts persist across page reloads
+- RLS: a user from a different account cannot read or write facts for this session
+
+```
+git commit -m "feat(pilot): add What we know section with fact synthesis"
+```
+
+### Phase 3 — Suggested fix + resolution note preview
+
+**Deliverables:**
+- `session_suggested_fixes` API endpoints and data flow
+- `SuggestedFix` component in the task lane
+- AI prompt updated to emit `[SUGGEST_FIX]` markers
+- `ResolutionNoteGeneratorService` and preview endpoint
+- `ResolutionNotePreview` floating popover anchored to Resolve button
+- Preview refreshes on fact / suggested-fix changes (debounced)
+
+**Verification:**
+- Session with ≥3 facts and an active suggested fix shows a populated Resolve preview
+- Editing a fact updates the preview within 1 second
+- Preview markdown renders correctly with all four sections (Problem / What we confirmed / Root cause / Resolution)
+- Preview contains no hallucinated information not present in session state (human review of 5 real-ish sessions)
+
+```
+git commit -m "feat(pilot): add suggested fix tracking and Resolve note preview"
+```
+
+### Phase 4 — Resolve and Escalate PSA writebacks
+
+**Deliverables:**
+- `transition_ticket_status` method with CW verification
+- `post_resolution_note` endpoint and CW integration
+- Resolve button fires: post note → transition status → mark session resolved → show templatize prompt (if applicable)
+- `EscalationPackageGeneratorService` and parallel flow for Escalate
+- Escalate button fires: post package → transition status → mark session escalated → route via CW rules
+
+**Verification:**
+- Complete a session end-to-end with a ConnectWise test instance
+- Click Resolve, edit the preview, confirm post — verify the note appears in CW and status changes to Resolved
+- Click Escalate on a different session — verify the package is posted and the ticket routes correctly
+- Attempt to Resolve without a linked PSA ticket — should mark the session resolved without erroring, note stored in `resolution_note_markdown` only
+
+```
+git commit -m "feat(pilot): wire Resolve and Escalate to ConnectWise writeback"
+```
+
+### Phase 5 — Script Generator inline integration
+
+**Deliverables:**
+- `ScriptGenInline/TemplateMatchPanel` — when suggested fix has `script_template_id`, clicking the fix opens this panel with pre-filled parameters from session context
+- Parameter pre-fill logic: pulls from session facts, ticket context (company configs), and AI-suggested values in the `[SUGGEST_FIX]` marker
+- `ScriptGenInline/NoTemplateDialog` — three-option dialog when no template match
+- User decision persisted on `session_suggested_fixes.user_decision`
+- `TemplateExtractionService` for generating parameterization proposals
+- Script generation flow produces a `script_generations` record linked to the session (existing Script Generator behavior)
+
+**Verification:**
+- Session with a template-matched suggested fix: clicking opens generator with ≥2 pre-filled parameters
+- Session with a custom script suggested fix: dialog appears with three options, script preview shows parameters highlighted
+- All three paths end correctly: one-off generates and closes, draft creates `draft_templates` row and generates, build_template opens full template creation
+- `⌘K` → "script" anywhere in a session opens the generator directly
+
+```
+git commit -m "feat(pilot): integrate Script Generator inline with suggested fixes"
+```
+
+### Phase 6 — Post-resolve templatize prompt
+
+**Deliverables:**
+- `TemplatizePrompt` component
+- Logic: after Resolve success, check for pending `draft_templates` rows for this session; if any, show the prompt
+- Accept flow creates a new `script_templates` row with `source_session_id`, `source_user_id`, `source_ticket_ref` set
+- "Don't ask me again" writes to `account_settings.templatize_prompt_enabled`
+- Script Library sidebar shows a small badge when `draft_templates` with `status='pending'` exist for the current user
+
+**Verification:**
+- Resolve a session where the engineer picked Option 2 — templatize prompt appears with AI-proposed parameters
+- Accept the prompt — new template appears in the Script Library with the provenance chip ("generated from CW #...")
+- Skip the prompt — draft marked rejected, Script Library shows no new template
+- Toggle "don't ask me again" — next session Resolve skips the prompt even with a pending draft
+
+```
+git commit -m "feat(pilot): add post-resolve templatize prompt for draft templates"
+```
+
+### Phase 7 — Polish
+
+**Deliverables:**
+- Visual polish against the mockup files (spacing, colors, animations)
+- Loading states for LLM calls (fact synthesis, preview generation, template extraction)
+- Empty states (new session with no facts yet, no active suggested fix, no draft templates pending)
+- Keyboard shortcuts: `⌘K` (command menu), `⌘↵` (send composer), `⌘G` (generator), `⌘R` (resolve with confirm)
+- Responsive behavior: task lane collapses on <1200px viewports into a bottom drawer
+
+**Verification:**
+- Compare each major screen side-by-side with the mockup PNG files — colors, spacing, typography within 5px / exact color match
+- All flows work on a 1280px viewport without horizontal scroll
+- Keyboard shortcuts documented in-app via `?` overlay
+
+```
+git commit -m "feat(pilot): visual polish and keyboard shortcuts"
+```
+
+---
+
+## 10. Design system reference
+
+All components must use the existing ResolutionFlow design system. Pulling the key tokens from the mockup CSS for quick reference — these should already exist in your tokens file; if they don't, add them:
+
+```css
+/* Backgrounds */
+--bg-0: #070b12;          /* page background */
+--bg-1: #0d131c;          /* sidebar / chrome */
+--bg-2: #121a25;          /* card / bubble background */
+--bg-3: #1a2332;          /* raised element */
+
+/* Borders */
+--border: rgba(148, 163, 184, 0.12);
+--border-strong: rgba(148, 163, 184, 0.22);
+
+/* Text */
+--text-primary: #e2e8f0;
+--text-secondary: #94a3b8;
+--text-tertiary: #64748b;
+
+/* Brand cyan (FlowPilot accent) */
+--cyan-400: #22d3ee;
+--cyan-500: #06b6d4;
+--cyan-600: #0891b2;
+--cyan-bg: rgba(34, 211, 238, 0.10);
+--cyan-border: rgba(34, 211, 238, 0.30);
+
+/* Semantic */
+--success: #34d399;   /* Resolve, facts */
+--warning: #fbbf24;   /* Escalate, proposed parameters */
+--danger:  #f87171;
+--purple:  #a78bfa;   /* Script Generator / templates */
+```
+
+**Typography:**
+- Body: IBM Plex Sans, 14px/1.5
+- Headings: Bricolage Grotesque, 500 weight, -0.01em letter-spacing
+- Code: JetBrains Mono
+
+**Icons:** Phosphor Icons (Duotone) per the memory-recorded design decision to migrate off Lucide.
+
+---
+
+## 11. Non-goals for this migration
+
+Do not build these as part of this work. They belong to later phases of the roadmap.
+
+- **Confidence tiers (Discovery / Exploring / Guided).** We explicitly removed these. The task lane itself is the progress signal.
+- **Mode toggle between Guided and Quick ask.** There is one mode.
+- **"Convert to guided" promotion flow.** No longer applicable.
+- **Team Wiki compilation from resolved sessions.** Tracked separately; depends on this migration but is not part of it.
+- **SharePoint integration.** Sequenced after ConnectWise per roadmap.
+- **Template marketplace / sharing across accounts.** Tracked under Client Context System roadmap item.
+
+---
+
+## 12. Risks and mitigations
+
+| Risk | Mitigation |
+|---|---|
+| LLM fact synthesis hallucinates specifics not in the answer | Conservative prompt; engineer can edit/delete any AI-synthesized fact; provenance line shows the source so the engineer can verify |
+| Resolution note preview LLM cost at scale | Cache aggressively, invalidate only on session state write; debounce UI updates to 500ms; consider lower-tier model for preview generation (final post-to-CW version can use the better model) |
+| ConnectWise silently rejects status change | `transition_ticket_status` must re-fetch and verify; fail loudly if the change didn't stick |
+| Template extraction proposes bad parameterization | Engineer reviews before saving; draft templates never silently become real templates; provenance chip lets team admins audit |
+| Users lose muscle memory from `/assistant` → `/pilot` rename | Permanent redirect (no sunset date); inline toast on first `/pilot` visit explaining the rename |
+| Existing sessions have no `session_facts` entries, so What we know is empty | Acceptable — Phase 2 deliberately does not backfill; facts only accumulate for new or ongoing sessions after deploy. Document in release notes. |
+
+---
+
+## 13. Questions for Michael before implementation starts
+
+These are the decisions Claude Code cannot make unilaterally. Answer these inline in the doc or in chat before kicking off Phase 1.
+
+1. **Keyboard shortcut for Resolve** — I've proposed `⌘R` (with a confirm). Browsers intercept `⌘R` for page reload. Alternative: `⌘⇧R` or no shortcut. Preference?
+2. **Default `templatize_prompt_enabled` value** — I defaulted to `true`. If your beta testers find it annoying we'll learn fast, but it's a tradeoff between "every engineer sees the prompt" and "feature gets discovered only by those who know about it".
+3. **Resolution note posts immediately, or stage for review?** — Current design: engineer edits preview inline, clicks Confirm & post. Alternative: stage in CW as draft note for a supervisor to approve before posting. Affects MSPs with strict compliance.
+
+---
+
+## End of document

docs/FlowAssist_Migration/Issues/phase-8-review-issues.md

@@ -0,0 +1,165 @@
+# Phase 8 Review Issues
+
+Date: 2026-04-23
+
+Scope reviewed:
+- `backend/app/api/endpoints/session_suggested_fixes.py`
+- `backend/app/services/unified_chat_service.py`
+- `frontend/src/pages/AssistantChatPage.tsx`
+- `frontend/src/components/pilot/ProposalBanner.tsx`
+- `frontend/src/components/pilot/EscalateInterceptDialog.tsx`
+
+## 1. Outcome writes do not invalidate Resolve/Escalate preview cache
+
+Severity: High
+
+`PATCH /suggested-fixes/{fix_id}/outcome` updates the fix row but does not bump
+`ai_sessions.state_version`. Even after adding that bump, the preview input
+bundle also needs to include the fix outcome fields; otherwise a regenerated
+preview still cannot distinguish proposed, partially applied, failed, or
+successful fixes.
+
+Relevant files:
+- `backend/app/api/endpoints/session_suggested_fixes.py:226`
+- `backend/app/api/endpoints/session_suggested_fixes.py:146`
+- `backend/app/services/resolution_note_generator.py:13`
+- `backend/app/services/escalation_package_generator.py:14`
+
+Why this matters:
+- Resolve and Escalate previews are cached by `(session_id, state_version)`.
+- The decision endpoint already bumps `state_version`.
+- The new outcome endpoint does not.
+- A user can record `applied_success` / `applied_failed` / `applied_partial`
+  and still see markdown generated from the pre-outcome session state.
+- The preview generators currently pass only the active fix title,
+  confidence, description, and user decision into the LLM bundle. They do not
+  pass `status`, `applied_at`, `verified_at`, `partial_notes`, or
+  `failure_reason`.
+- Therefore a cache miss alone is not enough: the generated markdown may still
+  describe the fix as merely proposed because the outcome is absent from the
+  prompt input.
+
+Recommended fix:
+- Bump `AISession.state_version` inside the outcome endpoint transaction.
+- Include suggested-fix outcome state in both preview bundles:
+  - `status`
+  - `applied_at`
+  - `verified_at`
+  - `partial_notes`
+  - `failure_reason`
+- Update the resolution-note prompt expectations so `applied_success` produces
+  closure language, `applied_failed` states that the proposed fix did not
+  resolve the issue, and `applied_partial` includes the engineer's partial
+  notes.
+- Update the escalation-package prompt expectations so failed/partial outcomes
+  appear under "What we've tried" and inform "Suggested next steps."
+- Add a test proving a preview generated before an outcome change is
+  invalidated after the outcome patch and that the regenerated preview input
+  includes the recorded outcome.
+
+## 2. "Apply" is not persisted, so Verifying state is lost on reload/reselect
+
+Severity: High
+
+Phase 8 introduces a Verifying lifecycle in the UI, but clicking Apply only
+sets local React state.
+
+Relevant files:
+- `frontend/src/pages/AssistantChatPage.tsx:142`
+- `frontend/src/pages/AssistantChatPage.tsx:516`
+- `backend/app/api/endpoints/session_suggested_fixes.py:276`
+
+Why this matters:
+- `bannerApplied` is a client-side-only flag.
+- `handleApplyFix()` opens the script panel and flips local state, but does not
+  persist anything.
+- `applied_at` is only stamped later when an outcome is patched.
+- After refresh, chat reselect, or multi-tab use, a fix that had entered
+  Verifying falls back to `proposed`.
+- Nudge timing, resolve auto-success, and escalate interception therefore do
+  not survive normal session resume.
+
+Recommended fix:
+- Persist "apply started" as part of the fix lifecycle.
+- Either add an explicit backend transition for apply/start-verifying, or
+  persist `applied_at` when Apply is clicked.
+- Add a test or browser regression check covering refresh/reselect continuity.
+
+## 3. Rejecting an AI outcome proposal is only local and will reappear
+
+Severity: Medium
+
+Rejecting the AI-confirming banner clears `ai_outcome_proposal` only in local
+component state.
+
+Relevant files:
+- `frontend/src/pages/AssistantChatPage.tsx:571`
+- `frontend/src/pages/AssistantChatPage.tsx:431`
+
+Why this matters:
+- `handleRejectAIProposal()` only updates local `activeFix`.
+- The server-side `ai_outcome_proposal` remains unchanged.
+- The proposal comes back on the next `refreshSessionDerived()` call, which
+  happens after sends, task submissions, and chat selection.
+- "Not yet" is therefore a temporary hide, not a real rejection/correction.
+
+Recommended fix:
+- Add a backend way to clear or reject `ai_outcome_proposal`.
+- Make the reject action persist so the banner does not immediately re-arm on
+  the next refetch.
+
+## 4. Pre-existing failing decision test
+
+Severity: Low (test gap, no runtime regression)
+
+`tests/test_session_suggested_fixes_api.py::test_record_decision_persists_and_bumps_state_version`
+was authored in Phase 3 (`66e5920`) when the `decision` endpoint had no
+validation on `ai_drafted_script`. Phase 5 (`fa61376`) added a 400 guard:
+when the decision is `one_off`, `draft_template`, or `build_template` and the
+fix has no `ai_drafted_script` (and the caller provides no `edited_script` in
+the request body), the endpoint returns 400 with the message "Suggested fix has
+no ai_drafted_script — use /api/v1/scripts/generate for template-matched
+fixes."
+
+The test creates a fix without an `ai_drafted_script` and posts
+`{"decision": "draft_template"}` naked, so the guard fires and returns 400. The
+test still asserts 200. This was already broken before Phase 8 began — commit
+`cdd8bb0` (first Phase 8 commit) is 8 commits after `fa61376`.
+
+Root cause: test was never updated to match the Phase 5 contract change.
+
+Recommended fix for the next branch:
+- Option A (minimal): supply `ai_drafted_script="echo hello"` when creating the
+  fix fixture, or add `edited_script` to the POST body. Validates the happy path
+  for `draft_template` with a real drafted body.
+- Option B (comprehensive): add a separate test case asserting the 400 when
+  `ai_drafted_script` is null and no `edited_script` is provided, then fix the
+  existing test as in Option A. The 400-guard already has coverage in the
+  Phase 5 test file; the main gap is just the missing fixture update here.
+
+No Phase 8 code change required — this is a test-fixture gap from Phase 3/5
+drift, not a regression introduced in this branch.
+
+## Test Context
+
+Relevant backend suites were run serially from `backend/`:
+
+```bash
+pytest tests/test_fix_outcome_endpoint.py tests/test_fix_outcome_marker.py tests/test_session_suggested_fixes_api.py -q
+```
+
+Observed result:
+- `28 passed`
+- `1 failed`
+
+Remaining failure:
+- `tests/test_session_suggested_fixes_api.py::test_record_decision_persists_and_bumps_state_version`
+
+Notes:
+- That failing test is in the older decision-path suite and expects
+  `draft_template` to succeed without a drafted script.
+- The new outcome endpoint tests and marker parser tests passed in the serial
+  run.
+- The three issues above are based on code inspection and remain valid
+  regardless of that separate failing test.
+- Full root cause analysis documented in section 4 above.

docs/FlowAssist_Migration/mockups/05-resolve-cta-merge.html

@@ -0,0 +1,679 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>FlowPilot — Suggested Fix → Resolve CTA merge (Option A)</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=Bricolage+Grotesque:wght@500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg-sidebar: #0e1016;
+    --bg-page: #16181f;
+    --bg-card: #1e2028;
+    --bg-elevated: #2a2d38;
+    --border-default: rgba(148, 163, 184, 0.12);
+    --border-hover: rgba(148, 163, 184, 0.22);
+    --text-heading: #f1f5f9;
+    --text-primary: #e2e8f0;
+    --text-muted-foreground: #94a3b8;
+    --text-muted: #64748b;
+    --accent: #60a5fa;
+    --accent-dim: rgba(96, 165, 250, 0.10);
+    --accent-border: rgba(96, 165, 250, 0.30);
+    --warning: #fbbf24;
+    --warning-dim: rgba(251, 191, 36, 0.10);
+    --warning-border: rgba(251, 191, 36, 0.28);
+    --success: #34d399;
+    --success-dim: rgba(52, 211, 153, 0.10);
+    --success-border: rgba(52, 211, 153, 0.28);
+    --danger: #f87171;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html, body {
+    background: var(--bg-sidebar);
+    color: var(--text-primary);
+    font-family: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  .page {
+    max-width: 1680px;
+    margin: 0 auto;
+    padding: 32px 24px 64px;
+  }
+
+  .page-header {
+    margin-bottom: 28px;
+  }
+  .page-title {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 22px;
+    color: var(--text-heading);
+    letter-spacing: -0.01em;
+  }
+  .page-sub {
+    margin-top: 6px;
+    color: var(--text-muted-foreground);
+    font-size: 13px;
+    max-width: 840px;
+  }
+
+  .columns {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 20px;
+  }
+
+  /* ----- Column scaffold (pretending to be the task-lane rail) ----- */
+  .col {
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 12px;
+    display: flex;
+    flex-direction: column;
+    height: 760px;
+    overflow: hidden;
+  }
+  .col-head {
+    padding: 14px 16px;
+    border-bottom: 1px solid var(--border-default);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    background: var(--bg-sidebar);
+  }
+  .col-head-label {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 13px;
+    color: var(--text-heading);
+    letter-spacing: 0.01em;
+  }
+  .col-head-tag {
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 1.2px;
+    text-transform: uppercase;
+    color: var(--text-muted);
+  }
+  .col-head-tag.today { color: var(--text-muted-foreground); }
+  .col-head-tag.opt-a { color: var(--accent); }
+  .col-head-tag.opt-a-disabled { color: var(--warning); }
+
+  .lane-body {
+    flex: 1;
+    overflow-y: auto;
+    padding: 14px 14px 10px;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+  }
+
+  /* ----- Section labels (match current component styling) ----- */
+  .section-label {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 1.2px;
+    text-transform: uppercase;
+    color: var(--text-muted-foreground);
+    padding: 0 2px 8px;
+  }
+  .dot {
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    display: inline-block;
+  }
+  .dot-accent  { background: var(--accent); }
+  .dot-warning { background: var(--warning); }
+  .dot-success { background: var(--success); }
+  .section-meta {
+    color: var(--text-muted);
+    font-weight: 500;
+    letter-spacing: 0;
+    text-transform: none;
+  }
+  .conf-high { color: var(--success); font-variant-numeric: tabular-nums; letter-spacing: 0; text-transform: none; }
+
+  /* ----- What-we-know facts ----- */
+  .fact {
+    background: var(--bg-card);
+    border: 1px solid var(--border-default);
+    border-left: 3px solid var(--accent);
+    border-radius: 8px;
+    padding: 10px 12px;
+    display: flex;
+    gap: 10px;
+    align-items: flex-start;
+  }
+  .fact + .fact { margin-top: 8px; }
+  .fact-icon {
+    width: 14px;
+    height: 14px;
+    border-radius: 3px;
+    background: var(--accent-dim);
+    border: 1px solid var(--accent-border);
+    flex-shrink: 0;
+    margin-top: 2px;
+  }
+  .fact-body { min-width: 0; flex: 1; }
+  .fact-title {
+    font-size: 12.5px;
+    font-weight: 500;
+    color: var(--text-heading);
+    line-height: 1.4;
+  }
+  .fact-meta {
+    margin-top: 3px;
+    font-size: 11px;
+    color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+  }
+
+  /* ----- Suggested fix card (today only) ----- */
+  .fix-card {
+    border-radius: 8px;
+    border: 1px solid var(--warning-border);
+    border-left: 3px solid var(--warning);
+    background: var(--warning-dim);
+    padding: 12px 14px;
+    display: flex;
+    gap: 10px;
+    align-items: flex-start;
+  }
+  .fix-spark {
+    color: var(--warning);
+    flex-shrink: 0;
+    margin-top: 1px;
+  }
+  .fix-title {
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--text-heading);
+    line-height: 1.4;
+  }
+  .fix-desc {
+    margin-top: 4px;
+    font-size: 12px;
+    color: var(--text-muted-foreground);
+    line-height: 1.5;
+  }
+  .fix-hint {
+    margin-top: 6px;
+    font-size: 11px;
+    color: var(--success);
+  }
+  .fix-x {
+    margin-left: auto;
+    color: var(--text-muted);
+    background: transparent;
+    border: 0;
+    padding: 2px 4px;
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 11px;
+  }
+
+  /* ----- Action bar at bottom ----- */
+  .action-bar {
+    border-top: 1px solid var(--border-default);
+    padding: 12px 14px 14px;
+    background: var(--bg-sidebar);
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .action-row {
+    display: flex;
+    gap: 8px;
+  }
+
+  .btn {
+    appearance: none;
+    border: 1px solid var(--border-default);
+    background: var(--bg-card);
+    color: var(--text-primary);
+    padding: 10px 12px;
+    border-radius: 8px;
+    font-family: inherit;
+    font-weight: 500;
+    font-size: 13px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    cursor: pointer;
+    transition: border-color 0.12s ease, background-color 0.12s ease, color 0.12s ease;
+  }
+  .btn:hover { border-color: var(--border-hover); background: var(--bg-elevated); }
+
+  .btn-secondary {
+    flex: 0 0 auto;
+    min-width: 96px;
+  }
+
+  .btn-resolve-today {
+    flex: 1;
+    background: var(--accent);
+    color: #0a0d14;
+    border-color: transparent;
+    font-weight: 600;
+  }
+  .btn-resolve-today:hover { background: #7ab4fb; color: #0a0d14; }
+
+  /* Option A — Resolve w/ embedded fix */
+  .btn-resolve-merged {
+    flex: 1;
+    background: var(--accent);
+    color: #0a0d14;
+    border-color: transparent;
+    padding: 10px 14px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    justify-content: flex-start;
+    min-height: 52px;
+    text-align: left;
+  }
+  .btn-resolve-merged:hover { background: #7ab4fb; color: #0a0d14; }
+  .btn-resolve-merged .rc-leading {
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    color: rgba(10, 13, 20, 0.72);
+    font-family: 'Bricolage Grotesque', sans-serif;
+  }
+  .btn-resolve-merged .rc-title {
+    font-size: 13.5px;
+    font-weight: 600;
+    color: #0a0d14;
+    line-height: 1.25;
+    letter-spacing: -0.01em;
+  }
+  .btn-resolve-merged .rc-body {
+    min-width: 0;
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+  .btn-resolve-merged .rc-conf {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 3px 8px;
+    border-radius: 999px;
+    background: rgba(10, 13, 20, 0.14);
+    color: #0a0d14;
+    font-size: 11px;
+    font-weight: 700;
+    font-variant-numeric: tabular-nums;
+    flex-shrink: 0;
+  }
+  .btn-resolve-merged .rc-chevron {
+    color: rgba(10, 13, 20, 0.55);
+    flex-shrink: 0;
+  }
+
+  /* Disabled (no proposal yet) */
+  .btn-resolve-disabled {
+    flex: 1;
+    background: var(--bg-card);
+    color: var(--text-muted-foreground);
+    border: 1px dashed var(--border-hover);
+    padding: 10px 14px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    justify-content: flex-start;
+    min-height: 52px;
+    cursor: not-allowed;
+    text-align: left;
+  }
+  .btn-resolve-disabled .rc-leading {
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    color: var(--text-muted);
+    font-family: 'Bricolage Grotesque', sans-serif;
+  }
+  .btn-resolve-disabled .rc-title {
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--text-muted-foreground);
+    line-height: 1.25;
+  }
+
+  /* Escalate / overflow */
+  .btn-escalate {
+    background: transparent;
+    color: var(--text-muted-foreground);
+  }
+  .btn-escalate:hover { color: var(--text-primary); }
+
+  /* tiny spinner dot for the waiting state */
+  .pulse {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: var(--warning);
+    box-shadow: 0 0 0 0 rgba(251, 191, 36, 0.5);
+    animation: pulse 1.6s infinite;
+    flex-shrink: 0;
+  }
+  @keyframes pulse {
+    0%   { box-shadow: 0 0 0 0   rgba(251, 191, 36, 0.45); }
+    70%  { box-shadow: 0 0 0 8px rgba(251, 191, 36, 0); }
+    100% { box-shadow: 0 0 0 0   rgba(251, 191, 36, 0); }
+  }
+
+  /* Annotation callouts beneath the columns */
+  .callout {
+    margin-top: 14px;
+    padding: 12px 14px;
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 10px;
+    font-size: 12px;
+    color: var(--text-muted-foreground);
+    line-height: 1.55;
+  }
+  .callout strong { color: var(--text-heading); font-weight: 600; }
+  .callout.note-accent { border-left: 3px solid var(--accent); }
+  .callout.note-warning { border-left: 3px solid var(--warning); }
+  .callout.note-muted   { border-left: 3px solid var(--border-hover); }
+
+  .legend {
+    margin-top: 40px;
+    padding: 18px 20px;
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 12px;
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 14px 32px;
+    font-size: 12.5px;
+    color: var(--text-muted-foreground);
+    line-height: 1.55;
+  }
+  .legend h4 {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--text-heading);
+    margin-bottom: 6px;
+    letter-spacing: 0;
+  }
+  .legend li { margin-top: 4px; }
+
+  /* subtle faux scrollbar hint */
+  .lane-body::-webkit-scrollbar { width: 6px; }
+  .lane-body::-webkit-scrollbar-thumb { background: var(--border-hover); border-radius: 3px; }
+</style>
+</head>
+<body>
+
+<div class="page">
+
+  <div class="page-header">
+    <div class="page-title">Option A — Suggested Fix merges into the Resolve CTA</div>
+    <div class="page-sub">
+      Three versions of the same task lane. <strong style="color:var(--text-primary)">Today</strong> keeps Suggested Fix as a separate card that gets pushed down by a long facts list. <strong style="color:var(--text-primary)">Option A (armed)</strong> deletes the card — the Resolve button at the bottom becomes the proposal. <strong style="color:var(--text-primary)">Option A (waiting)</strong> is what the same bar looks like before the AI emits a proposal.
+    </div>
+  </div>
+
+  <div class="columns">
+
+    <!-- ============== COLUMN 1: TODAY ============== -->
+    <div>
+      <div class="col">
+        <div class="col-head">
+          <div class="col-head-label">Today</div>
+          <div class="col-head-tag today">Baseline</div>
+        </div>
+        <div class="lane-body">
+
+          <!-- What we know -->
+          <section>
+            <div class="section-label">
+              <span class="dot dot-accent"></span>
+              What we know
+              <span class="section-meta">· 5 facts</span>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">User cannot authenticate to Outlook; repeated 401s from Exchange Online.</div>
+                <div class="fact-meta">promoted 14:02 · from ticket</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Cached credentials in Credential Manager reference a prior tenant the user migrated off six months ago.</div>
+                <div class="fact-meta">promoted 14:07 · from chat</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">MFA prompt appears then fails silently — no authenticator notification, no error code surfaced to the user.</div>
+                <div class="fact-meta">promoted 14:11 · from chat</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Other devices under same account authenticate successfully, isolating the problem to this workstation.</div>
+                <div class="fact-meta">promoted 14:14 · from chat</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Office 365 client last updated three weeks ago; local profile not recreated since migration.</div>
+                <div class="fact-meta">promoted 14:18 · from chat</div>
+              </div>
+            </div>
+          </section>
+
+          <!-- Suggested Fix card (this is the thing that gets buried) -->
+          <section>
+            <div class="section-label">
+              <span class="dot dot-warning"></span>
+              Suggested fix
+              <span class="section-meta">·</span>
+              <span class="conf-high">94% confidence</span>
+            </div>
+            <div class="fix-card">
+              <svg class="fix-spark" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+              <div style="min-width:0;flex:1">
+                <div class="fix-title">Clear cached credentials + rebuild Outlook profile</div>
+                <div class="fix-desc">Remove stale entries from Credential Manager referencing the prior tenant, then rebuild the local Outlook profile so the client re-authenticates cleanly against the current tenant.</div>
+                <div class="fix-hint">✓ Matches an existing Script Library template — click to use</div>
+              </div>
+              <button class="fix-x" aria-label="Dismiss">✕</button>
+            </div>
+          </section>
+
+        </div>
+
+        <div class="action-bar">
+          <div class="action-row">
+            <button class="btn btn-escalate btn-secondary">Escalate</button>
+            <button class="btn btn-resolve-today">Resolve</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="callout note-muted">
+        <strong>Baseline problem.</strong> The Suggested Fix card sits after What-we-know. With 5+ facts (common by mid-session) it's below the fold. The generic <em>Resolve</em> button at the bottom doesn't surface what would be resolved, so the engineer has to scroll up, read the card, then scroll back down to act.
+      </div>
+    </div>
+
+    <!-- ============== COLUMN 2: OPTION A — ARMED ============== -->
+    <div>
+      <div class="col">
+        <div class="col-head">
+          <div class="col-head-label">Option A — armed</div>
+          <div class="col-head-tag opt-a">Proposal ready</div>
+        </div>
+        <div class="lane-body">
+
+          <!-- Same facts, but no Suggested Fix card -->
+          <section>
+            <div class="section-label">
+              <span class="dot dot-accent"></span>
+              What we know
+              <span class="section-meta">· 5 facts</span>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">User cannot authenticate to Outlook; repeated 401s from Exchange Online.</div>
+                <div class="fact-meta">promoted 14:02 · from ticket</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Cached credentials in Credential Manager reference a prior tenant the user migrated off six months ago.</div>
+                <div class="fact-meta">promoted 14:07 · from chat</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">MFA prompt appears then fails silently — no authenticator notification, no error code surfaced to the user.</div>
+                <div class="fact-meta">promoted 14:11 · from chat</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Other devices under same account authenticate successfully, isolating the problem to this workstation.</div>
+                <div class="fact-meta">promoted 14:14 · from chat</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Office 365 client last updated three weeks ago; local profile not recreated since migration.</div>
+                <div class="fact-meta">promoted 14:18 · from chat</div>
+              </div>
+            </div>
+          </section>
+
+          <!-- NO Suggested Fix card here — it lives on the button -->
+
+        </div>
+
+        <div class="action-bar">
+          <div class="action-row">
+            <button class="btn btn-escalate btn-secondary">Escalate</button>
+            <button class="btn btn-resolve-merged" aria-label="Resolve with: Clear cached credentials + rebuild Outlook profile (94% confidence)">
+              <div class="rc-body">
+                <div class="rc-leading">Resolve with</div>
+                <div class="rc-title">Clear cached credentials + rebuild Outlook profile</div>
+              </div>
+              <span class="rc-conf">
+                <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+                94%
+              </span>
+              <svg class="rc-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>
+            </button>
+          </div>
+        </div>
+      </div>
+
+      <div class="callout note-accent">
+        <strong>What changes.</strong> The Suggested Fix card is gone. Its content moved onto the Resolve button, which is always in view. One click = accept the fix + open the existing <code style="font-family:'JetBrains Mono',monospace;font-size:11.5px;background:var(--bg-card);padding:1px 5px;border-radius:3px;">ResolutionNotePreview</code> popover pre-filled. No card-then-button two-step.
+      </div>
+    </div>
+
+    <!-- ============== COLUMN 3: OPTION A — WAITING ============== -->
+    <div>
+      <div class="col">
+        <div class="col-head">
+          <div class="col-head-label">Option A — waiting</div>
+          <div class="col-head-tag opt-a-disabled">No proposal yet</div>
+        </div>
+        <div class="lane-body">
+
+          <section>
+            <div class="section-label">
+              <span class="dot dot-accent"></span>
+              What we know
+              <span class="section-meta">· 2 facts</span>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">User cannot authenticate to Outlook; repeated 401s from Exchange Online.</div>
+                <div class="fact-meta">promoted 14:02 · from ticket</div>
+              </div>
+            </div>
+            <div class="fact">
+              <span class="fact-icon"></span>
+              <div class="fact-body">
+                <div class="fact-title">Cached credentials in Credential Manager reference a prior tenant.</div>
+                <div class="fact-meta">promoted 14:07 · from chat</div>
+              </div>
+            </div>
+          </section>
+
+        </div>
+
+        <div class="action-bar">
+          <div class="action-row">
+            <button class="btn btn-escalate btn-secondary">Escalate</button>
+            <button class="btn btn-resolve-disabled" disabled aria-label="Resolve (waiting for AI proposal)">
+              <span class="pulse" aria-hidden="true"></span>
+              <div class="rc-body">
+                <div class="rc-leading">Resolve</div>
+                <div class="rc-title">Waiting for proposal…</div>
+              </div>
+            </button>
+          </div>
+        </div>
+      </div>
+
+      <div class="callout note-warning">
+        <strong>Before confidence threshold.</strong> Same slot, disabled state. Amber pulse signals the AI is still reasoning. Below threshold or no proposal yet → same visual — the engineer can still use <em>Escalate</em> at any time.
+      </div>
+    </div>
+
+  </div>
+
+  <!-- ============== LEGEND / TRADE-OFFS ============== -->
+  <div class="legend">
+    <div>
+      <h4>Why this helps discoverability</h4>
+      <ul style="padding-left:18px;list-style:disc">
+        <li>Proposal is in the place the engineer looks to <em>act</em>, not in the scrolling lane above.</li>
+        <li>Resolve bar is already sticky at the bottom — no new sticky patterns needed (preserves the <code style="font-family:'JetBrains Mono',monospace;font-size:11px">8879f96</code> fix).</li>
+        <li>Accepting a fix and resolving the session collapse into one click instead of two.</li>
+      </ul>
+    </div>
+    <div>
+      <h4>What you give up</h4>
+      <ul style="padding-left:18px;list-style:disc">
+        <li>No space for secondary info on the button (reasoning, alternative fixes). Would need an expand/chevron or hover tooltip.</li>
+        <li>No standalone "dismiss this fix" affordance — need to decide where dismiss/reject lives (chevron menu? secondary button?).</li>
+        <li>If the AI proposes multiple candidates, only the top one fits the button. Need a "▾ 2 other candidates" menu.</li>
+      </ul>
+    </div>
+  </div>
+
+</div>
+
+</body>
+</html>

docs/FlowAssist_Migration/mockups/06-slide-up-banner.html

@@ -0,0 +1,849 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>FlowPilot — Suggested Fix as slide-up composer banner</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=Bricolage+Grotesque:wght@500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg-sidebar: #0e1016;
+    --bg-page: #16181f;
+    --bg-card: #1e2028;
+    --bg-elevated: #2a2d38;
+    --border-default: rgba(148, 163, 184, 0.12);
+    --border-hover: rgba(148, 163, 184, 0.22);
+    --text-heading: #f1f5f9;
+    --text-primary: #e2e8f0;
+    --text-muted-foreground: #94a3b8;
+    --text-muted: #64748b;
+    --accent: #60a5fa;
+    --accent-dim: rgba(96, 165, 250, 0.10);
+    --accent-border: rgba(96, 165, 250, 0.30);
+    --warning: #fbbf24;
+    --warning-dim: rgba(251, 191, 36, 0.10);
+    --warning-dim-strong: rgba(251, 191, 36, 0.16);
+    --warning-border: rgba(251, 191, 36, 0.32);
+    --success: #34d399;
+    --success-dim: rgba(52, 211, 153, 0.10);
+    --success-border: rgba(52, 211, 153, 0.28);
+    --danger: #f87171;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html, body {
+    background: var(--bg-sidebar);
+    color: var(--text-primary);
+    font-family: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  .page {
+    max-width: 1680px;
+    margin: 0 auto;
+    padding: 32px 24px 72px;
+  }
+
+  .page-header { margin-bottom: 24px; }
+  .page-title {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 22px;
+    color: var(--text-heading);
+    letter-spacing: -0.01em;
+  }
+  .page-sub {
+    margin-top: 6px;
+    color: var(--text-muted-foreground);
+    font-size: 13px;
+    max-width: 980px;
+    line-height: 1.55;
+  }
+
+  /* =================== Main frame =================== */
+  .frame {
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 14px;
+    overflow: hidden;
+    display: grid;
+    grid-template-columns: 1fr 380px;
+    height: 780px;
+  }
+
+  /* ------ Chat area ------ */
+  .chat {
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-page);
+    min-width: 0;
+  }
+  .chat-head {
+    padding: 14px 20px;
+    border-bottom: 1px solid var(--border-default);
+    background: var(--bg-sidebar);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+  }
+  .chat-head-title {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 14px;
+    color: var(--text-heading);
+  }
+  .chat-head-sub {
+    font-size: 11.5px;
+    color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+  }
+  .chat-head-actions {
+    display: flex;
+    gap: 8px;
+  }
+
+  .chat-scroll {
+    flex: 1;
+    overflow-y: auto;
+    padding: 24px 28px 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+  }
+
+  .msg {
+    max-width: 640px;
+    display: flex;
+    gap: 10px;
+    align-items: flex-start;
+  }
+  .msg.user { align-self: flex-end; }
+  .msg-av {
+    width: 26px; height: 26px;
+    border-radius: 50%;
+    flex-shrink: 0;
+    font-size: 11px;
+    font-weight: 600;
+    display: flex; align-items: center; justify-content: center;
+    margin-top: 2px;
+  }
+  .msg.user .msg-av {
+    background: var(--accent-dim);
+    color: var(--accent);
+    border: 1px solid var(--accent-border);
+  }
+  .msg.ai .msg-av {
+    background: var(--warning-dim);
+    color: var(--warning);
+    border: 1px solid var(--warning-border);
+  }
+  .msg-body {
+    background: var(--bg-card);
+    border: 1px solid var(--border-default);
+    border-radius: 10px;
+    padding: 10px 13px;
+    font-size: 13px;
+    color: var(--text-primary);
+    line-height: 1.55;
+  }
+  .msg.user .msg-body {
+    background: var(--accent-dim);
+    border-color: var(--accent-border);
+    color: var(--text-heading);
+  }
+  .msg-meta {
+    margin-top: 4px;
+    font-size: 10.5px;
+    color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+  }
+
+  /* ------ Composer area (sticky bottom of chat) ------ */
+  .composer-wrap {
+    border-top: 1px solid var(--border-default);
+    background: var(--bg-page);
+    position: relative;
+  }
+
+  /* ------ Slide-up banner ------ */
+  .proposal-banner {
+    margin: 0;
+    border-top: 1px solid var(--warning-border);
+    background: linear-gradient(180deg, var(--warning-dim-strong) 0%, var(--warning-dim) 100%);
+    padding: 12px 20px 14px;
+    display: flex;
+    gap: 14px;
+    align-items: flex-start;
+    position: relative;
+    animation: slideUp 320ms cubic-bezier(.22, .9, .28, 1) both;
+  }
+  .proposal-banner::before {
+    content: '';
+    position: absolute;
+    left: 0; top: 0; bottom: 0;
+    width: 3px;
+    background: var(--warning);
+  }
+  @keyframes slideUp {
+    from { transform: translateY(14px); opacity: 0; }
+    to   { transform: translateY(0);    opacity: 1; }
+  }
+
+  .proposal-icon {
+    width: 28px; height: 28px;
+    border-radius: 7px;
+    background: var(--warning-dim-strong);
+    border: 1px solid var(--warning-border);
+    display: flex; align-items: center; justify-content: center;
+    color: var(--warning);
+    flex-shrink: 0;
+    margin-top: 2px;
+  }
+  .proposal-body {
+    flex: 1;
+    min-width: 0;
+  }
+  .proposal-head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 1.2px;
+    text-transform: uppercase;
+    color: var(--warning);
+    font-family: 'Bricolage Grotesque', sans-serif;
+  }
+  .proposal-head .pill {
+    padding: 2px 7px;
+    border-radius: 999px;
+    background: rgba(251, 191, 36, 0.20);
+    color: var(--warning);
+    font-size: 10.5px;
+    font-weight: 700;
+    letter-spacing: 0.5px;
+    font-family: 'IBM Plex Sans', sans-serif;
+    font-variant-numeric: tabular-nums;
+  }
+  .proposal-title {
+    margin-top: 3px;
+    font-size: 14px;
+    font-weight: 600;
+    color: var(--text-heading);
+    line-height: 1.35;
+    letter-spacing: -0.005em;
+  }
+  .proposal-desc {
+    margin-top: 3px;
+    font-size: 12.5px;
+    color: var(--text-muted-foreground);
+    line-height: 1.5;
+  }
+  .proposal-hint {
+    margin-top: 6px;
+    font-size: 11.5px;
+    color: var(--success);
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+  }
+
+  .proposal-actions {
+    display: flex;
+    gap: 8px;
+    align-items: center;
+    flex-shrink: 0;
+    padding-top: 2px;
+  }
+
+  .btn {
+    appearance: none;
+    border: 1px solid var(--border-default);
+    background: var(--bg-card);
+    color: var(--text-primary);
+    padding: 8px 12px;
+    border-radius: 8px;
+    font-family: inherit;
+    font-weight: 500;
+    font-size: 12.5px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    cursor: pointer;
+    transition: border-color 0.12s, background-color 0.12s, color 0.12s;
+    white-space: nowrap;
+  }
+  .btn:hover { border-color: var(--border-hover); background: var(--bg-elevated); }
+
+  .btn-apply {
+    background: var(--warning);
+    color: #1a1200;
+    border-color: transparent;
+    font-weight: 600;
+    padding: 9px 14px;
+  }
+  .btn-apply:hover { background: #ffce4f; color: #1a1200; }
+
+  .btn-ghost {
+    background: transparent;
+    color: var(--text-muted-foreground);
+    border-color: transparent;
+    padding: 8px 10px;
+  }
+  .btn-ghost:hover {
+    background: rgba(148, 163, 184, 0.08);
+    color: var(--text-primary);
+    border-color: transparent;
+  }
+
+  .icon-btn {
+    width: 30px; height: 30px;
+    padding: 0;
+    background: transparent;
+    color: var(--text-muted-foreground);
+    border: 1px solid transparent;
+  }
+  .icon-btn:hover {
+    background: rgba(148, 163, 184, 0.08);
+    color: var(--text-primary);
+  }
+
+  /* ------ Composer ------ */
+  .composer {
+    padding: 14px 20px 16px;
+    display: flex;
+    align-items: flex-end;
+    gap: 10px;
+  }
+  .composer-input {
+    flex: 1;
+    min-height: 44px;
+    background: var(--bg-card);
+    border: 1px solid var(--border-default);
+    border-radius: 10px;
+    padding: 10px 14px;
+    color: var(--text-muted-foreground);
+    font-size: 13px;
+    line-height: 1.4;
+    display: flex;
+    align-items: center;
+  }
+  .composer-send {
+    width: 44px; height: 44px;
+    border-radius: 10px;
+    background: var(--accent);
+    color: #0a0d14;
+    border: 0;
+    display: flex; align-items: center; justify-content: center;
+    cursor: pointer;
+    flex-shrink: 0;
+  }
+
+  /* ------ Task lane (right rail) ------ */
+  .lane {
+    border-left: 1px solid var(--border-default);
+    background: var(--bg-sidebar);
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+  }
+  .lane-head {
+    padding: 14px 16px;
+    border-bottom: 1px solid var(--border-default);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  .lane-head-label {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 13px;
+    color: var(--text-heading);
+  }
+  .lane-body {
+    flex: 1;
+    overflow-y: auto;
+    padding: 14px 14px 10px;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+  }
+
+  .section-label {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 1.2px;
+    text-transform: uppercase;
+    color: var(--text-muted-foreground);
+    padding: 0 2px 8px;
+  }
+  .dot { width: 6px; height: 6px; border-radius: 50%; display: inline-block; }
+  .dot-accent { background: var(--accent); }
+  .dot-muted  { background: var(--text-muted); }
+  .section-meta {
+    color: var(--text-muted);
+    font-weight: 500;
+    letter-spacing: 0;
+    text-transform: none;
+  }
+
+  .fact {
+    background: var(--bg-card);
+    border: 1px solid var(--border-default);
+    border-left: 3px solid var(--accent);
+    border-radius: 8px;
+    padding: 10px 12px;
+  }
+  .fact + .fact { margin-top: 8px; }
+  .fact-title {
+    font-size: 12.5px;
+    font-weight: 500;
+    color: var(--text-heading);
+    line-height: 1.4;
+  }
+  .fact-meta {
+    margin-top: 3px;
+    font-size: 10.5px;
+    color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+  }
+
+  .dismissed-pill {
+    padding: 8px 10px;
+    background: var(--bg-card);
+    border: 1px dashed var(--border-hover);
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 11.5px;
+    color: var(--text-muted-foreground);
+    cursor: pointer;
+    transition: border-color 0.12s, color 0.12s;
+  }
+  .dismissed-pill:hover { border-color: var(--warning-border); color: var(--warning); }
+
+  .action-bar {
+    border-top: 1px solid var(--border-default);
+    padding: 12px 14px 14px;
+    display: flex;
+    gap: 8px;
+  }
+  .btn-escalate { flex: 0 0 auto; min-width: 96px; background: transparent; color: var(--text-muted-foreground); }
+  .btn-resolve {
+    flex: 1;
+    background: var(--accent);
+    color: #0a0d14;
+    border-color: transparent;
+    font-weight: 600;
+    padding: 10px 12px;
+  }
+  .btn-resolve:hover { background: #7ab4fb; color: #0a0d14; }
+
+  /* =================== Callouts =================== */
+  .callout {
+    margin-top: 20px;
+    padding: 14px 16px;
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 10px;
+    font-size: 13px;
+    color: var(--text-muted-foreground);
+    line-height: 1.55;
+    border-left: 3px solid var(--warning);
+  }
+  .callout strong { color: var(--text-heading); font-weight: 600; }
+
+  /* =================== State detail row =================== */
+  .states-title {
+    margin-top: 48px;
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 18px;
+    color: var(--text-heading);
+  }
+  .states-sub {
+    margin-top: 4px;
+    color: var(--text-muted-foreground);
+    font-size: 13px;
+  }
+  .states {
+    margin-top: 16px;
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 20px;
+  }
+  .state {
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 10px;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+  }
+  .state-label {
+    padding: 10px 14px;
+    border-bottom: 1px solid var(--border-default);
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 12.5px;
+    color: var(--text-heading);
+    background: var(--bg-sidebar);
+  }
+  .state-body {
+    padding: 0;
+    background: var(--bg-page);
+    min-height: 220px;
+    display: flex;
+    flex-direction: column;
+    justify-content: flex-end;
+  }
+  .state-mini-chat {
+    flex: 1;
+    padding: 14px;
+    opacity: 0.55;
+    font-size: 11px;
+    color: var(--text-muted);
+    display: flex;
+    align-items: flex-end;
+    font-family: 'JetBrains Mono', monospace;
+  }
+
+  /* Collapsed banner variant */
+  .banner-collapsed {
+    border-top: 1px solid var(--warning-border);
+    background: var(--warning-dim);
+    padding: 8px 14px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font-size: 12px;
+    color: var(--text-primary);
+    position: relative;
+  }
+  .banner-collapsed::before {
+    content: '';
+    position: absolute;
+    left: 0; top: 0; bottom: 0;
+    width: 3px;
+    background: var(--warning);
+  }
+  .banner-collapsed-title {
+    font-weight: 500;
+    color: var(--text-heading);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    flex: 1;
+  }
+  .banner-collapsed .pill {
+    padding: 1px 7px;
+    border-radius: 999px;
+    background: rgba(251, 191, 36, 0.20);
+    color: var(--warning);
+    font-size: 10.5px;
+    font-weight: 700;
+  }
+  .banner-collapsed .expand {
+    color: var(--text-muted-foreground);
+    font-size: 11px;
+  }
+
+  /* mini composer for the detail states */
+  .mini-composer {
+    border-top: 1px solid var(--border-default);
+    padding: 10px 14px;
+    display: flex;
+    gap: 8px;
+    align-items: center;
+  }
+  .mini-input {
+    flex: 1;
+    background: var(--bg-card);
+    border: 1px solid var(--border-default);
+    border-radius: 8px;
+    padding: 7px 10px;
+    font-size: 11.5px;
+    color: var(--text-muted);
+  }
+  .mini-send {
+    width: 28px; height: 28px;
+    border-radius: 7px;
+    background: var(--accent);
+    color: #0a0d14;
+    border: 0;
+    font-size: 14px;
+    display: flex; align-items: center; justify-content: center;
+  }
+
+  /* pill in chat stream (replaced state) */
+  .replaced-note {
+    align-self: flex-end;
+    font-size: 10.5px;
+    color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+    padding: 4px 8px;
+    background: var(--bg-card);
+    border: 1px dashed var(--border-hover);
+    border-radius: 6px;
+  }
+
+  /* annotation captions under each state */
+  .state-caption {
+    padding: 10px 14px 12px;
+    font-size: 11.5px;
+    color: var(--text-muted-foreground);
+    line-height: 1.5;
+    border-top: 1px solid var(--border-default);
+    background: var(--bg-sidebar);
+  }
+  .state-caption strong { color: var(--text-heading); font-weight: 600; }
+
+  .lane-body::-webkit-scrollbar { width: 6px; }
+  .lane-body::-webkit-scrollbar-thumb { background: var(--border-hover); border-radius: 3px; }
+  .chat-scroll::-webkit-scrollbar { width: 6px; }
+  .chat-scroll::-webkit-scrollbar-thumb { background: var(--border-hover); border-radius: 3px; }
+</style>
+</head>
+<body>
+
+<div class="page">
+
+  <div class="page-header">
+    <div class="page-title">Option C — Suggested Fix slides up from the chat composer</div>
+    <div class="page-sub">
+      The AI's proposal docks as a persistent banner just above the chat composer — right where the engineer's eyes already are. Apply lives on the banner (warning amber). <em>Resolve</em> stays generic at the bottom of the task lane, so there's no false-resolve risk. The Suggested Fix card is removed from the task lane entirely.
+    </div>
+  </div>
+
+  <!-- ============ MAIN: Armed + expanded ============ -->
+  <div class="frame">
+
+    <div class="chat">
+      <div class="chat-head">
+        <div>
+          <div class="chat-head-title">Outlook won't authenticate after tenant migration</div>
+          <div class="chat-head-sub">ticket #48213 · in progress · 14:22</div>
+        </div>
+        <div class="chat-head-actions">
+          <button class="btn btn-ghost">Share update</button>
+          <button class="btn icon-btn" aria-label="More">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.5"/><circle cx="12" cy="12" r="1.5"/><circle cx="19" cy="12" r="1.5"/></svg>
+          </button>
+        </div>
+      </div>
+
+      <div class="chat-scroll">
+        <div class="msg ai">
+          <div class="msg-av">AI</div>
+          <div>
+            <div class="msg-body">
+              A few things we know line up with a stale-credential pattern rather than an MFA or network issue. Can you confirm whether the user has other Microsoft 365 services (Teams, SharePoint) working on the same workstation?
+            </div>
+            <div class="msg-meta">14:16</div>
+          </div>
+        </div>
+
+        <div class="msg user">
+          <div>
+            <div class="msg-body">Teams works fine. SharePoint in browser is fine too. It's just Outlook.</div>
+            <div class="msg-meta">14:17</div>
+          </div>
+          <div class="msg-av">ME</div>
+        </div>
+
+        <div class="msg ai">
+          <div class="msg-av">AI</div>
+          <div>
+            <div class="msg-body">
+              That narrows it to the Outlook profile specifically. Given Credential Manager still has entries pointing at the prior tenant, the cleanest path is to clear those entries and rebuild the local Outlook profile — the client will re-auth against the current tenant from scratch.
+            </div>
+            <div class="msg-meta">14:22</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- ============ Slide-up banner ============ -->
+      <div class="composer-wrap">
+
+        <div class="proposal-banner" role="region" aria-label="AI proposed fix">
+          <div class="proposal-icon">
+            <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+          </div>
+          <div class="proposal-body">
+            <div class="proposal-head">
+              <span>Suggested Fix</span>
+              <span class="pill">94% confidence</span>
+            </div>
+            <div class="proposal-title">Clear cached credentials + rebuild Outlook profile</div>
+            <div class="proposal-desc">
+              Remove stale Credential Manager entries referencing the prior tenant, then rebuild the local Outlook profile so the client re-authenticates cleanly against the current tenant.
+            </div>
+            <div class="proposal-hint">
+              <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+              Matches an existing Script Library template — one-click apply
+            </div>
+          </div>
+          <div class="proposal-actions">
+            <button class="btn btn-ghost" aria-label="Collapse banner">
+              <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
+            </button>
+            <button class="btn btn-ghost" aria-label="Dismiss fix">Dismiss</button>
+            <button class="btn btn-apply">
+              Apply fix
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>
+            </button>
+          </div>
+        </div>
+
+        <div class="composer">
+          <div class="composer-input">Ask a follow-up, paste an error, drop a screenshot…</div>
+          <button class="composer-send" aria-label="Send">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+          </button>
+        </div>
+
+      </div>
+    </div>
+
+    <!-- ============ Task lane (no Suggested Fix card) ============ -->
+    <div class="lane">
+      <div class="lane-head">
+        <div class="lane-head-label">Task lane</div>
+      </div>
+      <div class="lane-body">
+        <section>
+          <div class="section-label">
+            <span class="dot dot-accent"></span>
+            What we know
+            <span class="section-meta">· 5 facts</span>
+          </div>
+          <div class="fact">
+            <div class="fact-title">User cannot authenticate to Outlook; repeated 401s from Exchange Online.</div>
+            <div class="fact-meta">promoted 14:02 · from ticket</div>
+          </div>
+          <div class="fact">
+            <div class="fact-title">Credential Manager still references the prior tenant from six months ago.</div>
+            <div class="fact-meta">promoted 14:07 · from chat</div>
+          </div>
+          <div class="fact">
+            <div class="fact-title">MFA prompt appears but fails silently — no authenticator notification.</div>
+            <div class="fact-meta">promoted 14:11 · from chat</div>
+          </div>
+          <div class="fact">
+            <div class="fact-title">Other devices under same account authenticate successfully.</div>
+            <div class="fact-meta">promoted 14:14 · from chat</div>
+          </div>
+          <div class="fact">
+            <div class="fact-title">Teams + SharePoint work on same workstation — isolated to Outlook.</div>
+            <div class="fact-meta">promoted 14:22 · from chat</div>
+          </div>
+        </section>
+      </div>
+      <div class="action-bar">
+        <button class="btn btn-escalate">Escalate</button>
+        <button class="btn btn-resolve">Resolve</button>
+      </div>
+    </div>
+
+  </div>
+
+  <div class="callout">
+    <strong>How it reads.</strong> Proposal arrives with a 320ms slide-up from below the composer, docks as a persistent banner until applied, dismissed, or replaced. Apply is amber (not accent-blue) so it visually belongs to the proposal, not the chat send button. Resolve in the task lane stays generic — there's no false-resolve risk because the two actions are spatially and visually separate.
+  </div>
+
+  <!-- ============ State detail row ============ -->
+  <div class="states-title">Banner states</div>
+  <div class="states-sub">What the same region looks like in the other three states — collapsed to save chat space, after the engineer dismisses it, and when a new proposal replaces an existing one.</div>
+
+  <div class="states">
+
+    <!-- STATE 1: Collapsed -->
+    <div class="state">
+      <div class="state-label">Collapsed (saves chat space)</div>
+      <div class="state-body">
+        <div class="state-mini-chat">…earlier messages…</div>
+        <div class="banner-collapsed">
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="var(--warning)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+          <span class="banner-collapsed-title">Clear cached credentials + rebuild Outlook profile</span>
+          <span class="pill">94%</span>
+          <span class="expand">▸ expand</span>
+        </div>
+        <div class="mini-composer">
+          <div class="mini-input">Type a message…</div>
+          <button class="mini-send">↑</button>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>~28px strip.</strong> Auto-collapses after 30s of no interaction, or when the engineer clicks the chevron. Title + confidence still visible. Click strip → expands. Apply still reachable via the expanded state.
+      </div>
+    </div>
+
+    <!-- STATE 2: Dismissed (pill in lane) -->
+    <div class="state">
+      <div class="state-label">Dismissed — parked in the task lane</div>
+      <div class="state-body">
+        <div class="state-mini-chat">chat unobstructed · banner gone</div>
+        <div class="mini-composer">
+          <div class="mini-input">Type a message…</div>
+          <button class="mini-send">↑</button>
+        </div>
+      </div>
+      <div style="padding: 12px 14px; background: var(--bg-sidebar); border-top: 1px solid var(--border-default);">
+        <div class="section-label" style="padding-bottom: 6px">
+          <span class="dot dot-muted"></span>
+          Dismissed proposals
+          <span class="section-meta">· 1</span>
+        </div>
+        <div class="dismissed-pill">
+          <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="var(--warning)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+          <span style="flex:1;color:var(--text-heading)">Clear cached credentials…</span>
+          <span style="color:var(--text-muted)">restore ↺</span>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>Recoverable, out of the way.</strong> Dismissing the banner parks the proposal as a pill in the task lane. Clicking restore → banner slides back in. Prevents accidental loss.
+      </div>
+    </div>
+
+    <!-- STATE 3: Replaced -->
+    <div class="state">
+      <div class="state-label">Replaced — new proposal overrides old</div>
+      <div class="state-body">
+        <div class="state-mini-chat" style="flex-direction:column;align-items:flex-end;gap:8px;justify-content:flex-end;">
+          <span class="replaced-note">previous: "Rebuild Outlook profile" — didn't resolve, new proposal below</span>
+        </div>
+        <div class="proposal-banner" style="padding:10px 14px;gap:10px;">
+          <div class="proposal-icon" style="width:22px;height:22px;border-radius:6px">
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+          </div>
+          <div class="proposal-body">
+            <div class="proposal-head" style="font-size:9px">
+              <span>New suggested fix</span>
+              <span class="pill" style="font-size:9.5px;padding:1px 6px">78%</span>
+            </div>
+            <div class="proposal-title" style="font-size:12.5px">Reset Autodiscover registry entries for this user</div>
+          </div>
+          <button class="btn btn-apply" style="padding:6px 10px;font-size:11.5px">Apply</button>
+        </div>
+        <div class="mini-composer">
+          <div class="mini-input">Type a message…</div>
+          <button class="mini-send">↑</button>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>Old proposal cross-fades out, new one slides in.</strong> 200ms cross-fade, same slot. A tiny footnote in chat ("previous didn't resolve") preserves the audit trail without re-stacking banners.
+      </div>
+    </div>
+
+  </div>
+
+</div>
+
+</body>
+</html>

docs/FlowAssist_Migration/mockups/07-verify-states.html

@@ -0,0 +1,805 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>FlowPilot — Post-apply outcome states</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=Bricolage+Grotesque:wght@500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg-sidebar: #0e1016;
+    --bg-page: #16181f;
+    --bg-card: #1e2028;
+    --bg-elevated: #2a2d38;
+    --border-default: rgba(148, 163, 184, 0.12);
+    --border-hover: rgba(148, 163, 184, 0.22);
+    --text-heading: #f1f5f9;
+    --text-primary: #e2e8f0;
+    --text-muted-foreground: #94a3b8;
+    --text-muted: #64748b;
+    --accent: #60a5fa;
+    --accent-dim: rgba(96, 165, 250, 0.10);
+    --accent-dim-strong: rgba(96, 165, 250, 0.16);
+    --accent-border: rgba(96, 165, 250, 0.30);
+    --warning: #fbbf24;
+    --warning-dim: rgba(251, 191, 36, 0.10);
+    --warning-dim-strong: rgba(251, 191, 36, 0.16);
+    --warning-border: rgba(251, 191, 36, 0.32);
+    --success: #34d399;
+    --success-dim: rgba(52, 211, 153, 0.10);
+    --success-dim-strong: rgba(52, 211, 153, 0.16);
+    --success-border: rgba(52, 211, 153, 0.30);
+    --info: #67e8f9;
+    --info-dim: rgba(103, 232, 249, 0.10);
+    --info-dim-strong: rgba(103, 232, 249, 0.16);
+    --info-border: rgba(103, 232, 249, 0.30);
+    --danger: #f87171;
+    --danger-dim: rgba(248, 113, 113, 0.10);
+    --danger-dim-strong: rgba(248, 113, 113, 0.16);
+    --danger-border: rgba(248, 113, 113, 0.30);
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  html, body {
+    background: var(--bg-sidebar);
+    color: var(--text-primary);
+    font-family: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  .page {
+    max-width: 1680px;
+    margin: 0 auto;
+    padding: 32px 24px 72px;
+  }
+  .page-header { margin-bottom: 24px; }
+  .page-title {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600;
+    font-size: 22px;
+    color: var(--text-heading);
+    letter-spacing: -0.01em;
+  }
+  .page-sub {
+    margin-top: 6px;
+    color: var(--text-muted-foreground);
+    font-size: 13px;
+    max-width: 1020px;
+    line-height: 1.55;
+  }
+
+  /* ====== Shared button styles ====== */
+  .btn {
+    appearance: none;
+    border: 1px solid var(--border-default);
+    background: var(--bg-card);
+    color: var(--text-primary);
+    padding: 8px 12px;
+    border-radius: 8px;
+    font-family: inherit;
+    font-weight: 500;
+    font-size: 12.5px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    cursor: pointer;
+    transition: border-color 0.12s, background-color 0.12s, color 0.12s;
+    white-space: nowrap;
+  }
+  .btn:hover { border-color: var(--border-hover); background: var(--bg-elevated); }
+  .btn-ghost {
+    background: transparent;
+    border-color: transparent;
+    color: var(--text-muted-foreground);
+    padding: 8px 10px;
+  }
+  .btn-ghost:hover {
+    background: rgba(148, 163, 184, 0.08);
+    color: var(--text-primary);
+    border-color: transparent;
+  }
+  .icon-btn {
+    width: 30px; height: 30px; padding: 0;
+    background: transparent; border: 1px solid transparent;
+    color: var(--text-muted-foreground);
+  }
+  .icon-btn:hover { background: rgba(148, 163, 184, 0.08); color: var(--text-primary); }
+
+  .btn-success {
+    background: var(--success); color: #0a1a12; border-color: transparent; font-weight: 600;
+  }
+  .btn-success:hover { background: #55e0af; color: #0a1a12; }
+  .btn-danger-outline {
+    background: transparent; color: var(--danger); border-color: var(--danger-border);
+  }
+  .btn-danger-outline:hover { background: var(--danger-dim); color: var(--danger); border-color: var(--danger); }
+  .btn-danger {
+    background: var(--danger); color: #180808; border-color: transparent; font-weight: 600;
+  }
+  .btn-danger:hover { background: #fa8a8a; color: #180808; }
+
+  /* ====== Frame ====== */
+  .frame {
+    background: var(--bg-page);
+    border: 1px solid var(--border-default);
+    border-radius: 14px;
+    overflow: hidden;
+    display: grid;
+    grid-template-columns: 1fr 380px;
+    height: 760px;
+  }
+  .chat {
+    display: flex; flex-direction: column;
+    background: var(--bg-page);
+    min-width: 0;
+  }
+  .chat-head {
+    padding: 14px 20px;
+    border-bottom: 1px solid var(--border-default);
+    background: var(--bg-sidebar);
+    display: flex; align-items: center; justify-content: space-between; gap: 12px;
+  }
+  .chat-head-title {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600; font-size: 14px; color: var(--text-heading);
+  }
+  .chat-head-sub {
+    font-size: 11.5px; color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+  }
+  .chat-scroll {
+    flex: 1; overflow-y: auto;
+    padding: 24px 28px 16px;
+    display: flex; flex-direction: column; gap: 16px;
+  }
+  .msg { max-width: 640px; display: flex; gap: 10px; align-items: flex-start; }
+  .msg.user { align-self: flex-end; }
+  .msg-av {
+    width: 26px; height: 26px; border-radius: 50%;
+    flex-shrink: 0; font-size: 11px; font-weight: 600;
+    display: flex; align-items: center; justify-content: center; margin-top: 2px;
+  }
+  .msg.user .msg-av { background: var(--accent-dim); color: var(--accent); border: 1px solid var(--accent-border); }
+  .msg.ai   .msg-av { background: var(--warning-dim); color: var(--warning); border: 1px solid var(--warning-border); }
+  .msg.system .msg-av { background: rgba(148,163,184,0.08); color: var(--text-muted); border: 1px solid var(--border-default); }
+  .msg-body {
+    background: var(--bg-card); border: 1px solid var(--border-default);
+    border-radius: 10px; padding: 10px 13px; font-size: 13px; color: var(--text-primary);
+    line-height: 1.55;
+  }
+  .msg.user .msg-body { background: var(--accent-dim); border-color: var(--accent-border); color: var(--text-heading); }
+  .msg.system .msg-body { background: transparent; border-style: dashed; color: var(--text-muted); font-size: 12px; font-style: italic; }
+  .msg-meta {
+    margin-top: 4px; font-size: 10.5px; color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+  }
+
+  .composer-wrap { border-top: 1px solid var(--border-default); background: var(--bg-page); position: relative; }
+  .composer { padding: 14px 20px 16px; display: flex; align-items: flex-end; gap: 10px; }
+  .composer-input {
+    flex: 1; min-height: 44px; background: var(--bg-card);
+    border: 1px solid var(--border-default); border-radius: 10px;
+    padding: 10px 14px; color: var(--text-muted-foreground);
+    font-size: 13px; line-height: 1.4;
+    display: flex; align-items: center;
+  }
+  .composer-send {
+    width: 44px; height: 44px; border-radius: 10px;
+    background: var(--accent); color: #0a0d14; border: 0;
+    display: flex; align-items: center; justify-content: center; cursor: pointer;
+  }
+
+  /* ====== Banner generic ====== */
+  .banner {
+    position: relative;
+    padding: 12px 20px 14px;
+    display: flex; gap: 14px; align-items: flex-start;
+    border-top-width: 1px; border-top-style: solid;
+    animation: fadeIn 260ms ease-out both;
+  }
+  .banner::before {
+    content: '';
+    position: absolute; left: 0; top: 0; bottom: 0;
+    width: 3px;
+  }
+  @keyframes fadeIn { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: translateY(0); } }
+
+  .banner-icon {
+    width: 28px; height: 28px; border-radius: 7px;
+    display: flex; align-items: center; justify-content: center;
+    flex-shrink: 0; margin-top: 2px;
+  }
+  .banner-body { flex: 1; min-width: 0; }
+  .banner-head {
+    display: flex; align-items: center; gap: 8px;
+    font-size: 10px; font-weight: 600; letter-spacing: 1.2px;
+    text-transform: uppercase; font-family: 'Bricolage Grotesque', sans-serif;
+  }
+  .banner-title {
+    margin-top: 3px; font-size: 14px; font-weight: 600;
+    color: var(--text-heading); line-height: 1.35; letter-spacing: -0.005em;
+  }
+  .banner-note {
+    margin-top: 3px; font-size: 12.5px; color: var(--text-muted-foreground);
+    line-height: 1.5;
+  }
+  .banner-actions {
+    display: flex; gap: 8px; align-items: center;
+    flex-shrink: 0; padding-top: 2px;
+  }
+  .pill {
+    padding: 2px 7px; border-radius: 999px;
+    font-size: 10.5px; font-weight: 700; letter-spacing: 0.5px;
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* Verifying — amber pulse, mirrors the proposed color but with pulse */
+  .banner-verify {
+    background: linear-gradient(180deg, var(--warning-dim-strong) 0%, var(--warning-dim) 100%);
+    border-top-color: var(--warning-border);
+  }
+  .banner-verify::before { background: var(--warning); }
+  .banner-verify .banner-icon {
+    background: var(--warning-dim-strong); border: 1px solid var(--warning-border); color: var(--warning);
+    position: relative;
+  }
+  .banner-verify .banner-icon::after {
+    content: ''; position: absolute; inset: -3px; border-radius: 9px;
+    box-shadow: 0 0 0 0 rgba(251, 191, 36, 0.45);
+    animation: pulseAmber 1.6s infinite;
+  }
+  @keyframes pulseAmber {
+    0%   { box-shadow: 0 0 0 0   rgba(251, 191, 36, 0.45); }
+    70%  { box-shadow: 0 0 0 10px rgba(251, 191, 36, 0); }
+    100% { box-shadow: 0 0 0 0   rgba(251, 191, 36, 0); }
+  }
+  .banner-verify .banner-head { color: var(--warning); }
+  .banner-verify .pill { background: rgba(251, 191, 36, 0.20); color: var(--warning); }
+
+  /* Partial — muted info/cyan to communicate "parked, outcome unknown" */
+  .banner-partial {
+    background: linear-gradient(180deg, var(--info-dim-strong) 0%, var(--info-dim) 100%);
+    border-top-color: var(--info-border);
+  }
+  .banner-partial::before { background: var(--info); }
+  .banner-partial .banner-icon { background: var(--info-dim-strong); border: 1px solid var(--info-border); color: var(--info); }
+  .banner-partial .banner-head { color: var(--info); }
+  .banner-partial .pill { background: rgba(103, 232, 249, 0.18); color: var(--info); }
+
+  /* AI-inferred — accent blue, AI-sourced */
+  .banner-ai {
+    background: linear-gradient(180deg, var(--accent-dim-strong) 0%, var(--accent-dim) 100%);
+    border-top-color: var(--accent-border);
+  }
+  .banner-ai::before { background: var(--accent); }
+  .banner-ai .banner-icon { background: var(--accent-dim-strong); border: 1px solid var(--accent-border); color: var(--accent); }
+  .banner-ai .banner-head { color: var(--accent); }
+  .banner-ai .pill { background: rgba(96, 165, 250, 0.20); color: var(--accent); }
+
+  /* Nudge — compact strip */
+  .banner-nudge {
+    padding: 8px 20px;
+    background: var(--warning-dim);
+    border-top-color: var(--warning-border);
+    align-items: center;
+    gap: 10px;
+  }
+  .banner-nudge::before { background: var(--warning); }
+  .banner-nudge .nudge-icon {
+    width: 16px; height: 16px; flex-shrink: 0; color: var(--warning);
+  }
+  .banner-nudge .nudge-title {
+    flex: 1; font-size: 12.5px; color: var(--text-primary); font-weight: 500;
+  }
+
+  /* ====== Task lane ====== */
+  .lane {
+    border-left: 1px solid var(--border-default);
+    background: var(--bg-sidebar);
+    display: flex; flex-direction: column; min-height: 0;
+  }
+  .lane-head {
+    padding: 14px 16px;
+    border-bottom: 1px solid var(--border-default);
+    display: flex; align-items: center; justify-content: space-between;
+  }
+  .lane-head-label {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600; font-size: 13px; color: var(--text-heading);
+  }
+  .lane-body {
+    flex: 1; overflow-y: auto;
+    padding: 14px 14px 10px;
+    display: flex; flex-direction: column; gap: 16px;
+  }
+  .section-label {
+    display: flex; align-items: center; gap: 8px;
+    font-size: 10px; font-weight: 600; letter-spacing: 1.2px;
+    text-transform: uppercase; color: var(--text-muted-foreground);
+    padding: 0 2px 8px;
+  }
+  .dot { width: 6px; height: 6px; border-radius: 50%; display: inline-block; }
+  .dot-accent { background: var(--accent); }
+  .dot-danger { background: var(--danger); }
+  .section-meta {
+    color: var(--text-muted); font-weight: 500; letter-spacing: 0; text-transform: none;
+  }
+  .fact {
+    background: var(--bg-card); border: 1px solid var(--border-default);
+    border-left: 3px solid var(--accent); border-radius: 8px;
+    padding: 10px 12px;
+  }
+  .fact + .fact { margin-top: 8px; }
+  .fact-title { font-size: 12.5px; font-weight: 500; color: var(--text-heading); line-height: 1.4; }
+  .fact-meta { margin-top: 3px; font-size: 10.5px; color: var(--text-muted); font-family: 'JetBrains Mono', monospace; }
+
+  .failed-pill {
+    padding: 9px 11px; background: var(--bg-card);
+    border: 1px dashed var(--danger-border); border-radius: 8px;
+    display: flex; align-items: center; gap: 8px;
+    font-size: 11.5px; color: var(--text-muted-foreground);
+  }
+  .failed-pill-title { flex: 1; color: var(--text-heading); font-weight: 500; }
+  .failed-pill-badge {
+    padding: 1px 6px; border-radius: 4px; font-size: 9.5px;
+    font-weight: 700; letter-spacing: 0.4px;
+    background: var(--danger-dim); color: var(--danger);
+    text-transform: uppercase;
+  }
+
+  .action-bar {
+    border-top: 1px solid var(--border-default);
+    padding: 12px 14px 14px;
+    display: flex; gap: 8px;
+    position: relative;
+  }
+  .btn-escalate { flex: 0 0 auto; min-width: 96px; background: transparent; color: var(--text-muted-foreground); }
+  .btn-resolve {
+    flex: 1; background: var(--accent); color: #0a0d14;
+    border-color: transparent; font-weight: 600; padding: 10px 12px;
+  }
+  .btn-resolve:hover { background: #7ab4fb; color: #0a0d14; }
+
+  /* ====== Callouts ====== */
+  .callout {
+    margin-top: 20px; padding: 14px 16px;
+    background: var(--bg-page); border: 1px solid var(--border-default);
+    border-radius: 10px; font-size: 13px; color: var(--text-muted-foreground);
+    line-height: 1.55; border-left: 3px solid var(--warning);
+  }
+  .callout strong { color: var(--text-heading); font-weight: 600; }
+
+  /* ====== State detail panels ====== */
+  .states-title {
+    margin-top: 48px; font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600; font-size: 18px; color: var(--text-heading);
+  }
+  .states-sub { margin-top: 4px; color: var(--text-muted-foreground); font-size: 13px; }
+
+  .states {
+    margin-top: 16px;
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 20px;
+  }
+  .state {
+    background: var(--bg-page); border: 1px solid var(--border-default);
+    border-radius: 10px; overflow: hidden;
+    display: flex; flex-direction: column;
+  }
+  .state-label {
+    padding: 10px 14px; border-bottom: 1px solid var(--border-default);
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600; font-size: 12.5px; color: var(--text-heading);
+    background: var(--bg-sidebar);
+  }
+  .state-body {
+    padding: 0; background: var(--bg-page);
+    min-height: 280px;
+    display: flex; flex-direction: column; justify-content: flex-end;
+    position: relative;
+  }
+  .state-mini-chat {
+    flex: 1; padding: 14px 16px;
+    font-size: 11px; color: var(--text-muted);
+    display: flex; align-items: flex-end; gap: 6px;
+    font-family: 'JetBrains Mono', monospace;
+    opacity: 0.6;
+  }
+  .mini-composer {
+    border-top: 1px solid var(--border-default);
+    padding: 10px 14px; display: flex; gap: 8px; align-items: center;
+  }
+  .mini-input {
+    flex: 1; background: var(--bg-card);
+    border: 1px solid var(--border-default); border-radius: 8px;
+    padding: 7px 10px; font-size: 11.5px; color: var(--text-muted);
+  }
+  .mini-send {
+    width: 28px; height: 28px; border-radius: 7px;
+    background: var(--accent); color: #0a0d14; border: 0; font-size: 14px;
+    display: flex; align-items: center; justify-content: center;
+  }
+
+  .state-caption {
+    padding: 10px 14px 12px; font-size: 11.5px;
+    color: var(--text-muted-foreground); line-height: 1.5;
+    border-top: 1px solid var(--border-default); background: var(--bg-sidebar);
+  }
+  .state-caption strong { color: var(--text-heading); font-weight: 600; }
+
+  /* ====== Escalate intercept popover ====== */
+  .intercept-wrap {
+    position: relative;
+    padding: 24px 14px 14px;
+    background: var(--bg-page);
+    flex: 1;
+    display: flex;
+    align-items: flex-end;
+    justify-content: flex-start;
+  }
+  .intercept-popover {
+    position: absolute;
+    bottom: 70px;
+    left: 14px;
+    width: 340px;
+    background: var(--bg-card);
+    border: 1px solid var(--border-hover);
+    border-radius: 10px;
+    padding: 14px;
+    box-shadow: 0 18px 40px rgba(0,0,0,0.55), 0 0 0 1px rgba(96,165,250,0.15);
+  }
+  .intercept-popover::after {
+    content: '';
+    position: absolute;
+    bottom: -7px; left: 40px;
+    width: 14px; height: 14px;
+    background: var(--bg-card);
+    border-right: 1px solid var(--border-hover);
+    border-bottom: 1px solid var(--border-hover);
+    transform: rotate(45deg);
+  }
+  .intercept-head {
+    font-family: 'Bricolage Grotesque', sans-serif;
+    font-weight: 600; font-size: 13px; color: var(--text-heading);
+    margin-bottom: 4px;
+  }
+  .intercept-sub {
+    font-size: 12px; color: var(--text-muted-foreground);
+    line-height: 1.5; margin-bottom: 12px;
+  }
+  .intercept-options {
+    display: flex; flex-direction: column; gap: 6px;
+  }
+  .intercept-option {
+    display: flex; align-items: center; gap: 10px;
+    padding: 10px 12px; border-radius: 8px;
+    background: var(--bg-elevated); border: 1px solid var(--border-default);
+    font-size: 12.5px; color: var(--text-primary);
+    cursor: pointer; text-align: left; width: 100%;
+    transition: border-color 0.12s, background-color 0.12s;
+    font-family: inherit;
+  }
+  .intercept-option:hover { border-color: var(--border-hover); background: var(--bg-sidebar); }
+  .intercept-option.primary {
+    border-color: var(--danger-border); background: var(--danger-dim);
+  }
+  .intercept-option.primary:hover { border-color: var(--danger); background: var(--danger-dim-strong); }
+  .intercept-kbd {
+    margin-left: auto; font-size: 10.5px; color: var(--text-muted);
+    font-family: 'JetBrains Mono', monospace;
+    background: rgba(148,163,184,0.08);
+    padding: 2px 6px; border-radius: 4px;
+  }
+
+  .mock-btn-row {
+    display: flex; gap: 8px;
+    padding: 12px 14px 14px;
+    border-top: 1px solid var(--border-default);
+  }
+  .mock-escalate {
+    background: transparent; color: var(--text-muted-foreground);
+    border: 1px solid var(--border-default); padding: 9px 14px;
+    border-radius: 8px; font-size: 12.5px; min-width: 96px;
+    position: relative;
+  }
+  .mock-escalate.active {
+    border-color: var(--danger-border); color: var(--danger);
+    background: var(--danger-dim);
+  }
+  .mock-resolve {
+    flex: 1; background: var(--accent); color: #0a0d14;
+    border: 0; font-weight: 600; padding: 9px 12px;
+    border-radius: 8px; font-size: 12.5px;
+  }
+
+  /* Partial inline input row */
+  .partial-note {
+    margin-top: 4px;
+    padding: 6px 10px;
+    background: rgba(103, 232, 249, 0.08);
+    border: 1px solid var(--info-border);
+    border-radius: 6px;
+    font-size: 12px; color: var(--text-primary);
+    display: flex; align-items: center; gap: 8px;
+    font-style: italic;
+  }
+  .partial-note-label {
+    font-style: normal; color: var(--info);
+    font-size: 10.5px; font-weight: 700; letter-spacing: 0.6px;
+    text-transform: uppercase;
+  }
+
+  .lane-body::-webkit-scrollbar,
+  .chat-scroll::-webkit-scrollbar { width: 6px; }
+  .lane-body::-webkit-scrollbar-thumb,
+  .chat-scroll::-webkit-scrollbar-thumb { background: var(--border-hover); border-radius: 3px; }
+</style>
+</head>
+<body>
+
+<div class="page">
+
+  <div class="page-header">
+    <div class="page-title">Post-apply outcome states — how we recognize whether a fix worked</div>
+    <div class="page-sub">
+      Hero frame shows the <strong style="color:var(--text-primary)">Verifying</strong> state — what the banner becomes the moment the engineer clicks Apply. Below, four detail panels show the other outcome paths: <strong style="color:var(--text-primary)">Partial apply</strong>, <strong style="color:var(--text-primary)">AI-inferred outcome</strong> from chat, <strong style="color:var(--text-primary)">Escalate-intercept</strong>, and the <strong style="color:var(--text-primary)">Nudge</strong> that appears when the engineer keeps chatting without confirming.
+    </div>
+  </div>
+
+  <!-- ============ HERO: VERIFYING ============ -->
+  <div class="frame">
+
+    <div class="chat">
+      <div class="chat-head">
+        <div>
+          <div class="chat-head-title">Outlook won't authenticate after tenant migration</div>
+          <div class="chat-head-sub">ticket #48213 · in progress · 14:26</div>
+        </div>
+      </div>
+
+      <div class="chat-scroll">
+        <div class="msg ai">
+          <div class="msg-av">AI</div>
+          <div>
+            <div class="msg-body">Given Credential Manager still has entries for the prior tenant, the cleanest path is to clear those and rebuild the local Outlook profile.</div>
+            <div class="msg-meta">14:22</div>
+          </div>
+        </div>
+        <div class="msg user">
+          <div>
+            <div class="msg-body">Okay, I'll run the script now.</div>
+            <div class="msg-meta">14:24</div>
+          </div>
+          <div class="msg-av">ME</div>
+        </div>
+        <div class="msg system">
+          <div class="msg-av">✓</div>
+          <div>
+            <div class="msg-body">Applied fix: Clear cached credentials + rebuild Outlook profile — script completed without errors at 14:24.</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- VERIFY BANNER (persistent after Apply) -->
+      <div class="composer-wrap">
+        <div class="banner banner-verify" role="region" aria-label="Verify fix outcome">
+          <div class="banner-icon">
+            <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
+          </div>
+          <div class="banner-body">
+            <div class="banner-head">
+              <span>Verifying</span>
+              <span class="pill">Applied 14:24 · 2m ago</span>
+            </div>
+            <div class="banner-title">Did "Clear cached credentials + rebuild Outlook profile" work?</div>
+            <div class="banner-note">Mark the outcome so the AI can either close the session with this as the resolution, or propose something else.</div>
+          </div>
+          <div class="banner-actions">
+            <button class="btn btn-ghost" aria-label="More options" title="Mark partial apply, re-open details">
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.6"/><circle cx="12" cy="12" r="1.6"/><circle cx="19" cy="12" r="1.6"/></svg>
+            </button>
+            <button class="btn btn-danger-outline">
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+              Didn't work
+            </button>
+            <button class="btn btn-success">
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+              It worked
+            </button>
+          </div>
+        </div>
+
+        <div class="composer">
+          <div class="composer-input">Tell the AI what happened — or click an outcome above</div>
+          <button class="composer-send" aria-label="Send">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <!-- Task lane: fix is now in "verifying" status — no longer a standalone suggested fix -->
+    <div class="lane">
+      <div class="lane-head">
+        <div class="lane-head-label">Task lane</div>
+      </div>
+      <div class="lane-body">
+        <section>
+          <div class="section-label">
+            <span class="dot dot-accent"></span>
+            What we know
+            <span class="section-meta">· 5 facts</span>
+          </div>
+          <div class="fact">
+            <div class="fact-title">User cannot authenticate to Outlook; repeated 401s from Exchange Online.</div>
+            <div class="fact-meta">promoted 14:02 · from ticket</div>
+          </div>
+          <div class="fact">
+            <div class="fact-title">Credential Manager still references the prior tenant from six months ago.</div>
+            <div class="fact-meta">promoted 14:07 · from chat</div>
+          </div>
+          <div class="fact">
+            <div class="fact-title">Teams + SharePoint work on same workstation — isolated to Outlook.</div>
+            <div class="fact-meta">promoted 14:22 · from chat</div>
+          </div>
+        </section>
+      </div>
+      <div class="action-bar">
+        <button class="btn btn-escalate">Escalate</button>
+        <button class="btn btn-resolve">Resolve</button>
+      </div>
+    </div>
+
+  </div>
+
+  <div class="callout">
+    <strong>How Verifying works.</strong> Clicking Apply transitions the banner into this state instead of dismissing it. No timeout — the banner stays pinned until the engineer marks <em>Worked</em>, <em>Didn't work</em>, or <em>Partial</em> (overflow). If they ignore it and keep chatting, the Nudge state (panel D below) appears after a few messages. If they hit the task lane's <em>Resolve</em> button without clicking either outcome, we auto-stamp <code style="font-family:'JetBrains Mono',monospace;font-size:11.5px;background:var(--bg-card);padding:1px 5px;border-radius:3px;">applied_success</code>. If they hit <em>Escalate</em>, panel C intercepts.
+  </div>
+
+  <!-- ============ DETAIL PANELS ============ -->
+  <div class="states-title">Outcome branches</div>
+  <div class="states-sub">Four paths from Verifying to a final status. Each one writes to <code style="font-family:'JetBrains Mono',monospace;font-size:12px;background:var(--bg-card);padding:1px 6px;border-radius:3px;color:var(--text-primary)">session_suggested_fixes.status</code> so the AI's next turn has ground truth about what's been tried.</div>
+
+  <div class="states">
+
+    <!-- A. PARTIAL -->
+    <div class="state">
+      <div class="state-label">A. Partial apply — "I did some of it"</div>
+      <div class="state-body">
+        <div class="state-mini-chat">…engineer picked "Mark partial…" from the verify banner's overflow menu</div>
+        <div class="banner banner-partial">
+          <div class="banner-icon">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>
+          </div>
+          <div class="banner-body">
+            <div class="banner-head">
+              <span>Partially applied</span>
+              <span class="pill">Parked</span>
+            </div>
+            <div class="banner-title">Clear cached credentials + rebuild Outlook profile</div>
+            <div class="partial-note">
+              <span class="partial-note-label">Note</span>
+              <span>Ran cred clear — skipped profile rebuild, user in a meeting. Back at 3:30.</span>
+            </div>
+          </div>
+          <div class="banner-actions">
+            <button class="btn btn-ghost">Edit note</button>
+            <button class="btn btn-danger-outline">Didn't work</button>
+            <button class="btn">Finish it ›</button>
+          </div>
+        </div>
+        <div class="mini-composer">
+          <div class="mini-input">Type a message…</div>
+          <button class="mini-send">↑</button>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>Status:</strong> <code style="font-family:'JetBrains Mono',monospace;font-size:11.5px">applied_partial</code>, with <code style="font-family:'JetBrains Mono',monospace;font-size:11.5px">partial_notes</code> free-text. Not terminal — banner stays pinned until engineer marks a terminal outcome, or clicks <em>Finish it</em> to re-run the remainder and flip back to Verifying. AI treats partial as "tried but uncertain" — doesn't re-propose, but doesn't assume failure either.
+      </div>
+    </div>
+
+    <!-- B. AI-INFERRED CONFIRM -->
+    <div class="state">
+      <div class="state-label">B. AI-inferred outcome — from chat</div>
+      <div class="state-body">
+        <div class="state-mini-chat" style="flex-direction:column;align-items:flex-end;gap:8px;opacity:0.8">
+          <div style="background:var(--bg-card);border:1px solid var(--border-default);border-radius:10px;padding:8px 12px;font-size:12px;color:var(--text-heading);font-style:normal;font-family:inherit;max-width:80%;"><strong style="font-weight:500">Engineer:</strong> "yep that fixed it, thanks"</div>
+          <div style="font-size:10.5px;color:var(--text-muted);padding-right:2px;">14:31 · user message triggered <code style="font-family:'JetBrains Mono',monospace;font-size:10.5px">[FIX_OUTCOME]</code></div>
+        </div>
+        <div class="banner banner-ai">
+          <div class="banner-icon">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/></svg>
+          </div>
+          <div class="banner-body">
+            <div class="banner-head">
+              <span>AI detected outcome</span>
+              <span class="pill">Success · 92%</span>
+            </div>
+            <div class="banner-title">AI thinks the fix resolved the issue — confirm?</div>
+            <div class="banner-note">Based on your message at 14:31. One click closes the session with this fix as the documented resolution.</div>
+          </div>
+          <div class="banner-actions">
+            <button class="btn btn-ghost">Not yet</button>
+            <button class="btn btn-danger-outline">No, didn't work</button>
+            <button class="btn btn-success">Confirm · Resolve</button>
+          </div>
+        </div>
+        <div class="mini-composer">
+          <div class="mini-input">Type a message…</div>
+          <button class="mini-send">↑</button>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>Triggered by</strong> the new <code style="font-family:'JetBrains Mono',monospace;font-size:11.5px">[FIX_OUTCOME fix_id=… outcome=success]</code> marker from the system prompt. Engineer stays in the loop — the AI <em>proposes</em> the outcome, doesn't set it. One-click accept fires the normal Resolve flow. Works for failure too ("still broken" → <em>No, didn't work</em> pre-selected, with the AI's reasoning shown).
+      </div>
+    </div>
+
+    <!-- C. ESCALATE INTERCEPT -->
+    <div class="state">
+      <div class="state-label">C. Escalate-intercept — capture outcome before handoff</div>
+      <div class="state-body">
+        <div class="intercept-wrap">
+          <div class="intercept-popover">
+            <div class="intercept-head">Before escalating — what happened with the fix?</div>
+            <div class="intercept-sub">"Clear cached credentials" is still in the Verifying state. Tag its outcome so the senior picking this up knows what's been tried.</div>
+            <div class="intercept-options">
+              <button class="intercept-option primary">
+                <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="var(--danger)" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+                The fix didn't work
+                <span class="intercept-kbd">↵</span>
+              </button>
+              <button class="intercept-option">
+                <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>
+                It worked — escalating for another reason
+              </button>
+              <button class="intercept-option">
+                <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>
+                Never actually applied it
+              </button>
+            </div>
+          </div>
+        </div>
+        <div class="mock-btn-row">
+          <button class="mock-escalate active">Escalate</button>
+          <button class="mock-resolve">Resolve</button>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>Fires when</strong> engineer clicks Escalate while a fix is in Verifying (or Partial). Defaults to <em>Didn't work</em> on Enter — common case. <em>Escalating for another reason</em> preserves success; <em>Never applied</em> flips to <code style="font-family:'JetBrains Mono',monospace;font-size:11.5px">dismissed</code>. Takes 1s and makes the escalation narrative honest for whoever picks it up.
+      </div>
+    </div>
+
+    <!-- D. NUDGE -->
+    <div class="state">
+      <div class="state-label">D. Nudge — passive prompt after a few messages</div>
+      <div class="state-body">
+        <div class="state-mini-chat" style="flex-direction:column;align-items:flex-end;gap:6px;opacity:0.8;">
+          <div style="background:var(--bg-card);border:1px solid var(--border-default);border-radius:10px;padding:7px 11px;font-size:11.5px;color:var(--text-heading);font-style:normal;font-family:inherit;max-width:70%;">"user is rebooting"</div>
+          <div style="background:var(--bg-card);border:1px solid var(--border-default);border-radius:10px;padding:7px 11px;font-size:11.5px;color:var(--text-heading);font-style:normal;font-family:inherit;max-width:75%;">"okay it's back up, signing in now"</div>
+          <div style="background:var(--bg-card);border:1px solid var(--border-default);border-radius:10px;padding:7px 11px;font-size:11.5px;color:var(--text-heading);font-style:normal;font-family:inherit;max-width:75%;">"going to try opening Outlook"</div>
+        </div>
+        <div class="banner banner-nudge">
+          <svg class="nudge-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 8v4"/><path d="M12 16h.01"/></svg>
+          <span class="nudge-title">Did <strong style="color:var(--text-heading)">"Clear cached credentials"</strong> work?</span>
+          <button class="btn btn-ghost" style="padding:4px 10px">Still checking</button>
+          <button class="btn btn-danger-outline" style="padding:4px 10px">No</button>
+          <button class="btn btn-success" style="padding:4px 10px">Yes</button>
+        </div>
+        <div class="mini-composer">
+          <div class="mini-input">Type a message…</div>
+          <button class="mini-send">↑</button>
+        </div>
+      </div>
+      <div class="state-caption">
+        <strong>Appears after</strong> ~3 post-apply engineer messages with no outcome click. Collapses the verify banner into this thin nudge strip above it so chat space isn't eaten. Passive — never auto-marks anything. <em>Still checking</em> silences the nudge for another 3 messages. Yes/No route to the normal Success / Failed flows.
+      </div>
+    </div>
+
+  </div>
+
+</div>
+
+</body>
+</html>

docs/FlowAssist_Migration/phase-9-script-builder-tab.md

@@ -0,0 +1,384 @@
+# FlowPilot Phase 9 — Tabbed Script Builder + NoTemplateDialog relocation
+
+**Date:** 2026-04-23
+**Branch target:** `feat/flowpilot-migration` (continuation of Phases 0–8)
+**Depends on:** Phase 8 (ProposalBanner in chat region)
+
+---
+
+## Goal
+
+Close the two remaining open items from the FlowPilot migration handoff:
+
+1. **NoTemplateDialog narrow-lane bug** — today the dialog renders in the task lane (~340px) and its `grid-cols-1 sm:grid-cols-3` layout crushes the three option cards. When the AI proposes a fix with no drafted script, all three cards render disabled, producing a dead end.
+2. **Tabbed Script Builder inside the chat** — give the engineer a way to draft the missing script without leaving the session (either by chatting with the AI or hand-writing in a code editor), then feed the draft back into the existing fix lifecycle.
+
+Plus two Phase 8 cleanup items flagged during code review:
+
+3. **`EscalateInterceptDialog` missing the Partial choice** — if a fix is in `applied_partial` when the engineer escalates, the intercept dialog's current three choices (worked / didn't work / never applied) don't match. Add a fourth choice for partial.
+4. **`applied_at` semantics correction** — today Phase 8's `handleApplyFix` stamps `applied_at` on every banner Apply click, starting the Verifying timer even when the engineer is only opening a drafting/evaluation surface. Move the stamp to the actual run-action handlers (see §5).
+
+This phase depends on Phase 8's `ProposalBanner` already being in the chat region — it reuses the same "chat-region-owns-Apply-flow" philosophy.
+
+---
+
+## Architectural decisions (settled during brainstorming)
+
+| # | Decision | Rationale |
+|---|---|---|
+| 1 | When a fix has no `ai_drafted_script`, the banner's Apply button routes **directly** to the Script Builder tab (bypassing `NoTemplateDialog` entirely). | Banner is the single entry point for Apply. `NoTemplateDialog` stays narrowly scoped to evaluating a draft that actually exists. |
+| 2 | Inside the Script Builder tab, the default experience is AI-driven — a new `ScriptBuilderTab` controller owns session lifecycle + submit, and *renders* `ScriptBuilderChat` (which stays purely presentational). A "✎ Write it myself" button in the tab's header toolbar swaps the controller's render into a Monaco editor. | AI is the common path. Persistence semantics belong on the controller, not the chat display component (`ScriptBuilderChat` already exposes `onSaveScript` as its seam — the controller wires that callback). |
+| 3 | The manual editor uses **Monaco**, reusing the pattern from `frontend/src/components/tree-editor/code-mode/CodeModeEditor.tsx`. | Monaco is already a dependency (`@monaco-editor/react` + `monaco-editor`). No bundle cost, proven pattern. |
+| 4 | The Script Builder tab is **always present while the fix is non-terminal** (no close affordance). An **indicator dot** on the tab signals in-progress draft state. | Matches Phase 8's `display: none` philosophy — engineers move freely between chat and draft without tracking a separate open/close state. |
+| 5 | `NoTemplateDialog` (draft-exists case) moves from `TaskLane.bottomSlot` to the **chat region** (sibling of `ProposalBanner`, slides up above composer). | Script evaluation is an action surface, not a context surface — belongs with the other action surfaces. Chat region is wide enough for the three cards to actually fit side-by-side. |
+| 6 | `EscalateInterceptDialog` gains a **fourth "Partial" choice** that writes `applied_partial` with a notes prompt. | Closes the gap flagged in Phase 8 final review. Minimal incremental cost since the dialog is already getting touched. |
+| 7 | `applied_at` is stamped only when the engineer commits to an action that **runs or triggers** a script — not on banner Apply click. Opening a drafting/evaluation surface no longer starts the Verifying timer. | Prevents false "applied" state when the engineer is still authoring. Corrects a Phase 8 over-eager stamp that this phase would otherwise multiply across three surfaces. |
+
+---
+
+## Architecture
+
+### 1. Chat region gets a tab strip
+
+A two-tab strip at the top of the chat region:
+
+```
+┌──────────────────────────────────────┐
+│ [Chat]  [Script Builder ●]           │
+├──────────────────────────────────────┤
+│                                      │
+│   (content per active tab,           │
+│    via display:none toggling)        │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+- **When the strip renders:** only when an `activeFix` exists AND the fix is non-terminal AND (`fix.ai_drafted_script` is null AND `fix.script_template_id` is null) — i.e., the fix genuinely needs a script drafted. Otherwise the chat region shows without tabs.
+- **Tab switching uses `display: none`**, not unmount. Chat scroll position, draft message, and Script Builder state all persist across switches.
+- **Indicator dot** on the Script Builder tab fires when there's in-progress draft state: at least one AI message sent in the `ScriptBuilderChat`, or non-empty Monaco buffer. Clears when the draft is submitted.
+- **Session switch** clears tab state via the existing `resetSessionDerivedState` helper.
+
+### 2. Script Builder tab content
+
+A new controller component `ScriptBuilderTab` owns the inline lifecycle:
+- Creates / resumes a `script_builder_sessions` row with `origin='pilot_inline'` + `ai_session_id = <pilot session id>`.
+- Manages AI-chat message state (via the existing script-builder message endpoints) and the Monaco editor buffer.
+- On submit, fires `PATCH /ai-sessions/{sid}/suggested-fixes/{fid}/script`.
+
+`ScriptBuilderChat` itself is **unchanged** — it stays a pure display component taking `messages`, `language`, `onViewScript`, `onSaveScript`, `isLoading`. The controller wires `onSaveScript` to its submit path instead of the template-creation path the standalone `/script-builder` page uses.
+
+A header toolbar above the controller's render area hosts the mode toggle:
+
+```
+┌──────────────────────────────────────┐
+│ Script Builder · Outlook fix         │
+│                      [✎ Write myself]│
+├──────────────────────────────────────┤
+│  (mode-specific content)             │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+- Clicking **✎ Write myself** flips `scriptBuilderMode` to `'editor'` — the controller renders Monaco in place of `ScriptBuilderChat`, pre-loaded with a scaffold (fix description as a language-appropriate comment header + an empty body).
+- A reciprocal **✨ Back to AI** button in editor mode returns to the chat.
+- Switching modes **does not discard** work. The Monaco buffer and the script-builder session both persist across toggles. This matters when an engineer drafts with AI, switches to editor to tweak a line, then considers going back.
+- Both modes share a single terminal action: the controller's **Submit → `PATCH /ai-sessions/{sid}/suggested-fixes/{fid}/script`**. On success the fix gains `ai_drafted_script`; the tab strip disappears (since the fix no longer needs a script) and the banner's Apply button now routes to `NoTemplateDialog` in the chat region.
+- **Submit does NOT stamp `applied_at`.** A draft is not an application — see §5 Apply lifecycle below.
+
+### 3. NoTemplateDialog relocation to chat region
+
+- Removed from `TaskLane.bottomSlot`. Renders in the chat region, slide-up-above-composer (same mechanical placement as `ProposalBanner`).
+- The three-card layout (`grid-cols-3` at the chat region's natural width) actually fits — no `grid-cols-1` regression needed.
+- Opens when the engineer clicks Apply on the banner AND `fix.ai_drafted_script` is non-empty.
+- Decision semantics unchanged (still `one_off` / `draft_template` / `build_template` with the same server-side effects) except for the moved apply stamp — see §5. Only the render location changes beyond that.
+
+### 4. Banner Apply routing (updated)
+
+Three mutually-exclusive outcomes based on the fix's shape:
+
+```
+handleApplyFix():
+  if fix.script_template_id:
+    open TemplateMatchPanel (unchanged — still renders in task lane for now)
+  elif fix.ai_drafted_script:
+    open NoTemplateDialog in chat region (new location, Chat tab)
+  else:
+    open Script Builder tab in chat region (new tab)
+```
+
+The NoTemplateDialog-in-chat-region path lives on the **Chat tab** (slides up above composer; the tab strip only renders for the no-draft case, so when NoTemplateDialog shows, the tab strip is not on screen). The Script Builder tab path is the opposite — tab strip renders, engineer is on the Script Builder tab.
+
+`TemplateMatchPanel` stays in the task lane for this phase — it's a different surface with different interactions and it's not broken. Moving it is possible future work.
+
+### 5. Apply lifecycle — `applied_at` semantics correction
+
+**Problem.** Today (Phase 8) `handleApplyFix` calls `POST /apply` the moment the banner's Apply button is clicked, stamping `applied_at` regardless of what happens next. This starts the Verifying timer (nudge countdown, Resolve auto-success, Escalate intercept) even if the engineer is only opening a drafting surface and hasn't actually run anything yet. For the no-draft path introduced in this phase, that's clearly wrong — opening the Script Builder tab is the start of *authoring*, not the start of *verifying*.
+
+**Rule.** `applied_at` is stamped **only when the engineer commits to an action that produces or triggers a run**, not when they open a surface:
+
+| Banner Apply click → routes to... | Stamps `applied_at`? |
+|---|---|
+| `TemplateMatchPanel` (existing flow) | Only when the engineer clicks a new explicit **"✓ I ran this"** action inside the panel (see below) |
+| `NoTemplateDialog` → `one_off` card ("Run now, no template") | **Yes** — the card click declares "I'm running this now" |
+| `NoTemplateDialog` → `draft_template` card ("Run now, templatize after") | **Yes** — same declaration, the template proposal is a side effect |
+| `NoTemplateDialog` → `build_template` card ("Just open the builder") | No — no run is declared; the engineer is going off to author a proper template |
+| Script Builder tab → Submit | No — just produces a draft. Engineer then clicks Apply again, gets `NoTemplateDialog`, picks `one_off` or `draft_template` to declare the run |
+
+**New explicit "I ran this" action in `TemplateMatchPanel`.** Today the panel has Generate, Copy, and Edit Parameters — none of which commit to running. Copying doesn't imply running; the engineer can walk away. This phase adds a distinct primary button (accent-colored, below Copy) labeled **"✓ I ran this"** or **"Mark as applied"**. Click → calls `applyFix` → fix transitions to Verifying. Until clicked, the fix stays in `proposed`.
+
+**Implementation.**
+- Remove `sessionSuggestedFixesApi.applyFix(...)` call from `handleApplyFix`. Move it to the three run-declaring call sites: `NoTemplateDialog`'s `handleScriptDecision('one_off' | 'draft_template')` paths AND the new `TemplateMatchPanel` "I ran this" button. The `applyFix` endpoint itself (from Phase 8 Issue #2) stays unchanged — only its call sites move.
+- Until `applied_at` is stamped, the fix remains in `proposed`. `bannerMode` computation already returns `'proposed'` when `applied_at` is null, so the banner naturally stays on Proposed state through the entire drafting phase.
+- **Phase 8 consequence.** This is a semantic revision of Phase 8, not just Phase 9 behavior. Tests must assert: opening `TemplateMatchPanel` does NOT stamp `applied_at`; clicking "I ran this" DOES; `NoTemplateDialog` `one_off` AND `draft_template` both DO; `build_template` does NOT.
+
+### 6. EscalateInterceptDialog partial choice
+
+Adds a fourth button to the existing popover:
+
+| Existing choices | New choice |
+|---|---|
+| The fix didn't work | (existing) |
+| It worked — escalating for another reason | (existing) |
+| Never actually applied it | (existing) |
+| **I applied some of it — partial** | **NEW** |
+
+- When clicked: prompts for partial notes (same pattern as the banner's Partial path — `window.prompt` for now, matching Phase 8's interim), then calls `patchOutcome('applied_partial', notes)`.
+- `handleInterceptChoice` gains an `applied_partial` branch. The `InterceptChoice` type already includes `'applied_partial'` via `FixOutcome | 'never_applied'`, so no type changes needed.
+- When a fix enters the dialog already in `applied_partial` state, the fourth button is hidden (can't transition partial → partial with different semantics). The "didn't work" button remains available to progress to `applied_failed`.
+
+---
+
+## Data model
+
+### New migration
+
+`script_builder_sessions` **already has** `ai_session_id` (FK → `ai_sessions.id`, nullable, `ON DELETE SET NULL`) with the comment "Link to FlowPilot session if launched from there." The existing column is the link we need — no new FK is added. The migration introduces only the `origin` discriminator plus a uniqueness guard for inline sessions:
+
+```sql
+ALTER TABLE script_builder_sessions
+  ADD COLUMN origin VARCHAR(20) NOT NULL DEFAULT 'standalone';
+
+ALTER TABLE script_builder_sessions
+  ADD CONSTRAINT ck_script_builder_sessions_origin
+    CHECK (origin IN ('standalone', 'pilot_inline'));
+
+-- Invariant: pilot_inline rows must be linked to a pilot session.
+-- Standalone rows may or may not be linked (legacy back-channel).
+ALTER TABLE script_builder_sessions
+  ADD CONSTRAINT ck_script_builder_sessions_origin_ai_session
+    CHECK (origin <> 'pilot_inline' OR ai_session_id IS NOT NULL);
+
+-- Uniqueness: at most one pilot_inline session per (user, pilot session).
+-- Required to back the get-or-create semantics on the endpoint and prevent
+-- duplicate scratch rows on remount. Partial index scoped to pilot_inline
+-- so standalone rows are unaffected.
+CREATE UNIQUE INDEX ux_script_builder_sessions_pilot_inline
+  ON script_builder_sessions (user_id, ai_session_id)
+  WHERE origin = 'pilot_inline';
+```
+
+`origin = 'standalone'` → existing `/script-builder` page usage (existing rows backfill to this default). `origin = 'pilot_inline'` → new Script Builder tab; `ai_session_id` is populated at row creation.
+
+`origin` earns its keep as an explicit discriminator for:
+- Filtering (`list_sessions` / `count_user_sessions` exclude `pilot_inline` by default — see §Data model filter changes below).
+- Future split-quota billing (decided to count as one billable session for now, but tagged for analytics).
+
+### Data-model filter changes — `script_builder_sessions` list + count
+
+Inline sessions would otherwise pollute the standalone `/script-builder` dashboard and count against the per-user 5-session cap enforced by the `POST /script-builder/sessions` endpoint. Required changes:
+
+- `script_builder_service.list_sessions(user_id)` → default scope `origin = 'standalone'`. Callers that genuinely want all rows (e.g., an admin dashboard in a future phase) can pass an explicit `include_inline=True` flag, but no current caller needs it.
+- `script_builder_service.count_user_sessions(user_id)` → same scope.
+- Both changes covered by tests:
+  - 5 `pilot_inline` sessions should still leave the engineer free to create 5 standalone sessions (no cap interaction).
+  - `list_sessions` returns only `standalone` rows.
+
+### New backend endpoint
+
+```
+PATCH /api/v1/ai-sessions/{session_id}/suggested-fixes/{fix_id}/script
+```
+
+Request:
+```json
+{
+  "ai_drafted_script": "string (required, 1..50_000 chars)",
+  "ai_drafted_parameters": { /* optional JSONB */ }
+}
+```
+
+Behavior:
+- Auth: `require_engineer_or_admin` + `_load_session_or_404`.
+- 404 if fix not found on that session.
+- 409 if fix is in a terminal status (`applied_success`, `applied_failed`, `dismissed`) — a drafted script can't be attached after the fix is done.
+- Sets `fix.ai_drafted_script` + `fix.ai_drafted_parameters`.
+- **Does NOT stamp `fix.applied_at`.** A draft is not an application — see §5 above.
+- **Bumps `ai_sessions.state_version`** — the fix just transitioned from "needs drafting" to "has draft", which affects Resolve/Escalate preview regeneration.
+- Returns `SessionSuggestedFixResponse`.
+
+### ScriptBuilderTab controller (frontend) — no changes to `ScriptBuilderChat`
+
+`ScriptBuilderChat` (`frontend/src/components/script-builder/ScriptBuilderChat.tsx`) is a presentational component taking `messages`, `language`, `onViewScript`, `onSaveScript`, `isLoading`. **It does not need a `mode` prop** — adding persistence semantics to a display component would be wrong.
+
+Instead, introduce a new controller component `frontend/src/components/pilot/ScriptBuilderTab.tsx` that owns the inline lifecycle:
+
+- On mount: **get-or-create** the single inline `script_builder_sessions` row for `(current user, current pilot session)` via the existing `POST /script-builder/sessions` endpoint, passing `origin: 'pilot_inline'` and the current pilot session id for `ai_session_id`. The endpoint becomes idempotent for `origin='pilot_inline'` — if a row exists for that `(user_id, ai_session_id)` pair, it's returned; otherwise created. The partial unique index on the DB backs the invariant independent of endpoint code. Remounting (tab hide/show, page refresh) resumes the same session — no duplicates, no lost draft continuity.
+- Holds local state for the AI message list, the Monaco buffer, and `scriptBuilderMode`.
+- Renders `ScriptBuilderChat` in AI mode with `onSaveScript` wired to the inline submit path (PATCH /script), NOT the standalone template-creation path.
+- Renders Monaco (via existing `CodeModeEditor` pattern) in `'editor'` mode with its own Save button that triggers the same submit.
+- Emits an `onScriptDrafted` event to `AssistantChatPage` on success so the page can `setActiveFix(updated)`, hide the tab strip, and return the engineer to Chat tab.
+
+The standalone `/script-builder` page retains its current behavior unchanged — it continues to create `script_templates` rows on submit. The split happens cleanly at the controller layer, not inside `ScriptBuilderChat`.
+
+### `POST /script-builder/sessions` — changes for inline origin
+
+The existing endpoint is extended in three ways:
+
+1. **Accepts `origin`** in the request body (`Literal['standalone', 'pilot_inline']`, default `'standalone'`). Legacy callers unchanged.
+2. **Authorization on `ai_session_id`.** When `origin='pilot_inline'` is passed AND `ai_session_id` is provided, the handler MUST verify the referenced `ai_sessions` row is owned by the current user (or within their account — whichever guard `_load_session_or_404(db, ai_session_id, current_user)` already enforces for the pilot endpoints). Without this check, a caller could attach an inline scratch session to an arbitrary pilot session. The check fires before any row lookup or creation.
+3. **Idempotent for `origin='pilot_inline'`.** If a row with `(user_id = current, ai_session_id = provided, origin = 'pilot_inline')` already exists, the handler returns that row (200) instead of creating a new one (201). The unique partial index enforces at-most-one at the DB layer; a race between two concurrent POSTs surfaces as an integrity error that the handler catches and re-reads.
+
+For `origin='standalone'`, behavior is unchanged — always creates, still subject to the 5-session cap.
+
+The 5-session cap applies only to `standalone` rows (see §Data-model filter changes). Inline sessions are out of that accounting entirely.
+
+---
+
+## State
+
+### Frontend state (AssistantChatPage)
+
+New local state on the page:
+- `chatTab: 'chat' | 'script_builder'` — which tab is visible. Defaults to `'chat'`.
+- `scriptBuilderHasProgress: boolean` — drives the indicator dot. Set by `ScriptBuilderTab` via an `onProgressChange` callback.
+
+Reset in `resetSessionDerivedState`: both back to defaults.
+
+`scriptBuilderMode` ('ai' | 'editor') lives **inside `ScriptBuilderTab`**, not on the page — the parent never needs to drive the AI/editor toggle. The controller resets it naturally via unmount/remount when the page switches sessions.
+
+Banner's Apply handler (`handleApplyFix`) updated:
+- If no script + no template → set `chatTab = 'script_builder'` (and show tab strip).
+- If drafted script → open NoTemplateDialog in the chat region (new state or existing `scriptPanelOpen` reused).
+- If template → open `TemplateMatchPanel` in the task lane (render location unchanged); run stamping happens via the new "I ran this" action inside the panel (see §5), not on Apply click.
+
+### Tab strip visibility
+
+The tab strip is derived, not state:
+```ts
+const showTabStrip =
+  activeFix != null &&
+  activeFix.status !== 'dismissed' &&
+  activeFix.status !== 'applied_success' &&
+  activeFix.status !== 'applied_failed' &&
+  !activeFix.script_template_id &&
+  !activeFix.ai_drafted_script
+```
+
+When the strip hides (e.g., after script is drafted), `chatTab` resets to `'chat'` to avoid stuck state.
+
+### Tab switching guard
+
+The existing `currentChatRef` pattern (Async-select-load-apply guard) applies: when the engineer switches chats, any in-flight tab-derived state is discarded.
+
+---
+
+## Out of scope
+
+- **NoTemplateDialog grid fix.** Moved to the chat region (wide enough), so the `grid-cols-1 sm:grid-cols-3` layout now works as intended. No grid edit required.
+- **`window.prompt` replacement** for partial-notes / failure-reason capture. Still the Phase 8 interim pattern; replacement is deferred to a later design debt pass.
+- **TemplateMatchPanel relocation** to the chat region. Different surface, different interactions, not broken today. Possible future work.
+- **Dedicated "clear AI outcome proposal" button in the UI.** Already covered by Phase 8 Issue #3 fix (DELETE endpoint + clear-on-outcome-write).
+- **Task lane bottom-slot audit.** With NoTemplateDialog removed from the slot, it may be empty on most sessions. Keep the slot API stable; any cleanup is out of scope.
+
+---
+
+## Tests
+
+### Backend
+
+- **Migration:** forward + downgrade reversibility; existing rows backfill to `origin='standalone'`; the `origin='pilot_inline' ⇒ ai_session_id IS NOT NULL` invariant is enforced by the check constraint.
+- **PATCH /script endpoint** (new test file `test_fix_script_endpoint.py`):
+  - happy path — 200, `ai_drafted_script` set, `state_version` bumped, `applied_at` untouched.
+  - 404 on wrong session.
+  - 409 on terminal status.
+  - 400 on empty body.
+- **list/count filter changes** (extend `test_script_builder.py` or nearby):
+  - 5 `pilot_inline` sessions + subsequent `standalone` session creation succeeds (does not hit the 5-cap).
+  - `list_sessions` returns only `standalone` rows by default.
+- **Apply lifecycle correction** (extend `test_fix_outcome_endpoint.py`):
+  - Banner Apply click that routes to a drafting/evaluation surface does NOT stamp `applied_at`.
+  - `one_off` decision from `NoTemplateDialog` DOES stamp `applied_at`.
+  - `draft_template` decision from `NoTemplateDialog` DOES stamp `applied_at` (it still runs the script).
+  - `build_template` decision from `NoTemplateDialog` does NOT stamp (no run).
+  - `TemplateMatchPanel` "I ran this" action DOES stamp `applied_at`; Generate / Copy alone do NOT.
+- **Script Builder session create — inline semantics** (extend `test_script_builder.py` or equivalent):
+  - First `POST /script-builder/sessions` with `origin='pilot_inline', ai_session_id=X` creates and returns a row.
+  - Second `POST` with the same `(ai_session_id, user)` returns the SAME row (no duplicate created); DB row count confirms.
+  - `POST` with `origin='pilot_inline'` and `ai_session_id` pointing at another user's pilot session is rejected (403/404).
+  - Race: two concurrent `POST`s for the same `(user, ai_session_id)` resolve to the same row id (one winner, one returns the existing).
+
+### Frontend
+
+Manual verification (no component test harness in this codebase per CLAUDE.md):
+- No-draft fix → Apply click opens Script Builder tab.
+- AI path: chat with AI, submit, tab disappears, NoTemplateDialog becomes eligible.
+- Manual path: ✎ Write myself → Monaco loads with scaffold → edit → submit → tab disappears.
+- Drafted fix → Apply click opens NoTemplateDialog in chat region (three cards side-by-side).
+- Tab indicator dot appears on first AI message / non-empty Monaco buffer; clears on submit.
+- Session switch with open Script Builder tab → tab/mode state resets.
+- EscalateInterceptDialog partial choice → applied_partial written with notes.
+
+### Build discipline
+
+- `tsc -b` clean
+- `npm run build` clean
+- `docker exec resolutionflow_backend pytest` — all pre-existing suites still pass, no regression from the new endpoint.
+
+---
+
+## Files to touch (rough inventory)
+
+**Backend — new:**
+- `backend/alembic/versions/<hash>_script_builder_origin.py`
+- `backend/tests/test_fix_script_endpoint.py`
+
+**Backend — modified:**
+- `backend/app/models/script_builder_session.py` — add `origin` column only (`ai_session_id` already exists).
+- `backend/app/schemas/session_suggested_fix.py` — add `SessionSuggestedFixScriptRequest`.
+- `backend/app/schemas/script_builder.py` — extend `ScriptBuilderCreateRequest` with two new optional fields: `origin: Literal['standalone', 'pilot_inline'] = 'standalone'` and `ai_session_id: UUID | None = None`. Handler-side validation: when `origin='pilot_inline'`, `ai_session_id` is required (not null) AND must pass the current-user ownership check. Legacy callers pass neither and continue to create standalone sessions as before.
+- `backend/app/api/endpoints/session_suggested_fixes.py` — add PATCH /script endpoint. Move the existing `applied_at` stamp out of the apply path and into `handleScriptDecision('one_off' | 'draft_template')` plus `TemplateMatchPanel`'s new "I ran this" handler (server side: no change to `/apply`; callers shift instead).
+- `backend/app/api/endpoints/script_builder.py` — accept `origin` on session creation; enforce the `pilot_inline ⇒ ai_session_id` invariant at the handler level.
+- `backend/app/services/script_builder_service.py` — persist `origin`; `list_sessions` + `count_user_sessions` filter to `origin='standalone'` by default.
+- `backend/app/models/session_suggested_fix.py` — unchanged (schema already has `ai_drafted_script`).
+
+**Frontend — new:**
+- `frontend/src/components/pilot/ChatTabStrip.tsx` — renders the `[Chat] [Script Builder ●]` strip.
+- `frontend/src/components/pilot/ScriptBuilderTab.tsx` — controller that owns session lifecycle, AI message state, Monaco buffer, mode toggle, and submit. Renders `ScriptBuilderChat` in AI mode and Monaco in editor mode.
+- `frontend/src/components/pilot/NoTemplateDialogInline.tsx` (or reuse existing `NoTemplateDialog` with a new wrapper for chat-region styling).
+
+**Frontend — modified:**
+- `frontend/src/api/sessionSuggestedFixes.ts` — add `patchScript(sessionId, fixId, body, parameters)` method.
+- `frontend/src/api/scriptBuilder.ts` (or equivalent) — `createSession` accepts optional `origin` and `ai_session_id` arguments (both required together when the caller is `ScriptBuilderTab`; both omitted for the legacy standalone caller).
+- `frontend/src/components/script-builder/ScriptBuilderChat.tsx` — **unchanged**. Stays a pure display component.
+- `frontend/src/pages/ScriptBuilderPage.tsx` — **unchanged on the session-creation path** (defaults to `origin='standalone'`).
+- `frontend/src/pages/AssistantChatPage.tsx` — wire tab strip, mount `ScriptBuilderTab`, banner Apply routing (no `applied_at` stamp on click), NoTemplateDialog chat-region render. Move the `sessionSuggestedFixesApi.applyFix(...)` call from `handleApplyFix` to `handleScriptDecision('one_off' | 'draft_template')` and `TemplateMatchPanel`'s new "I ran this" handler.
+- `frontend/src/components/pilot/EscalateInterceptDialog.tsx` — add fourth choice.
+- `frontend/src/components/pilot/TaskLane.tsx` — remove `bottomSlot` usage of NoTemplateDialog (leave prop API stable).
+
+**Frontend — deleted:**
+- None (existing components get refactored, not deleted).
+
+---
+
+## Rollout
+
+- Single branch, merged as part of the in-flight `feat/flowpilot-migration` PR (same as Phase 8). 
+- No feature flag — the new surface is strictly additive to the banner's Apply flow; old behavior for drafted-script fixes is preserved (just renders in a different location).
+
+---
+
+## Open deferrals (acknowledged, not in this phase)
+
+- `window.prompt` → inline input migration for partial notes / failure reasons.
+- Anti-parrot compliance check for the inline `ScriptBuilderTab` flow — verify it reuses the existing script-builder AI system prompt (no new prompt content introduced; the controller only changes what `onSaveScript` does, not what the AI sees).
+- Telemetry events for tab opens / AI→editor toggles / script submissions from tab — add in the Phase 9 implementation plan if we want them.

docs/connectwise-psa-testing-checklist.md

@@ -0,0 +1,158 @@
+# ConnectWise PSA Integration — Testing Checklist
+
+> **Purpose:** Step-by-step guide to connect ResolutionFlow to a ConnectWise developer sandbox and validate each integration feature end-to-end.
+>
+> **Date created:** 2026-04-14
+> **Branch:** main
+
+---
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- [ ] ResolutionFlow backend running (`uvicorn app.main:app --reload` from `backend/`)
+- [ ] ResolutionFlow frontend running (`npm run dev` from `frontend/`)
+- [ ] A ConnectWise developer sandbox account
+
+---
+
+## Step 1 — Get Your ConnectWise Developer Credentials
+
+You need four pieces of information from your ConnectWise sandbox.
+
+**Company ID**
+- This is the company name you log in with on the CW login screen (e.g. if your URL is `na.myconnectwise.net` and your login company is `resolutionflow`, the Company ID is `resolutionflow`)
+
+**Site URL**
+- Developer sandboxes are typically `na.myconnectwise.net` or `aus.connectwisedev.com`
+- Do **not** include `https://` — enter just the hostname (e.g. `na.myconnectwise.net`)
+
+**API Public Key + Private Key**
+1. Log into your CW sandbox
+2. Go to **System → Members** → open your own member record
+3. Click the **API Keys** tab
+4. Click **New** → give it a name (e.g. "ResolutionFlow Dev")
+5. Save — the **Private Key** is shown only once, copy it now
+6. Note both the **Public Key** (shown on the list) and **Private Key**
+
+**Client ID** (already configured server-side)
+- The `CW_CLIENT_ID` is set in `backend/app/core/config.py` — this identifies the ResolutionFlow app to ConnectWise and is shared across all tenants. You do not need to enter this in the UI.
+
+---
+
+## Step 2 — Connect ResolutionFlow to ConnectWise
+
+- [ ] Log into ResolutionFlow as a **Team Admin or Super Admin** user
+- [ ] Navigate to **Account → Integrations**
+- [ ] On the **Connection** tab, fill in the form:
+  - Display Name: anything (e.g. `CW Dev Sandbox`)
+  - Site URL: your sandbox hostname (e.g. `na.myconnectwise.net`)
+  - Company ID: your CW company ID
+  - Public Key: from Step 1
+  - Private Key: from Step 1
+- [ ] Click **Connect** — the backend tests the credentials before saving
+- [ ] Verify: "Connected" status appears with a green dot
+- [ ] Click **Test Connection** button and confirm it returns a success message + server version
+
+---
+
+## Step 3 — Member Mapping
+
+Maps ResolutionFlow users to ConnectWise members so that PSA posts are attributed to the right technician.
+
+- [ ] Click the **Member Mapping** tab
+- [ ] Click **Auto-Match by Email** — ResolutionFlow matches users to CW members with the same email address
+- [ ] Verify the matched count in the toast notification
+- [ ] If any users are unmatched, manually assign them via the dropdown
+- [ ] Click **Save Mappings** if you made manual changes
+
+---
+
+## Step 4 — Ticket Search (via FlowPilot session)
+
+- [ ] Start a new FlowPilot session (from the Dashboard)
+- [ ] Look for the **Link Ticket** button in the session header
+- [ ] Search for a ticket by keyword or ticket number
+- [ ] Verify: ticket results appear showing summary, board, status, priority
+- [ ] Select a ticket and confirm it links to the session
+
+---
+
+## Step 5 — Ticket Context Injection
+
+Once a ticket is linked, FlowPilot should enrich its context with CW data.
+
+- [ ] With a ticket linked, send a message to FlowPilot
+- [ ] Verify: FlowPilot's response references ticket details (company name, status, configurations, etc.)
+- [ ] Check backend logs to confirm `GET /integrations/psa/tickets/{id}/context` is being called
+
+---
+
+## Step 6 — PSA Post (push session notes to ticket)
+
+This is the core feature — pushing session documentation back to the ConnectWise ticket.
+
+- [ ] In the linked session, click **Update** (or the PSA post button in the session header)
+- [ ] Review the **Preview** — confirm the generated content looks correct
+- [ ] Select a **Note Type**:
+  - `Internal Analysis` — internal-only note (visible to techs, not clients)
+  - `Resolution` — marks as resolved, notifies client
+  - `Description` — main ticket description note
+- [ ] Optionally select a **Status** to update the ticket to (e.g. "In Progress" → "Resolved")
+- [ ] Click **Post to Ticket**
+- [ ] Verify: success toast appears
+- [ ] Verify in ConnectWise: open the ticket and confirm the note was posted with correct content and attribution (your member name)
+
+---
+
+## Step 7 — FlowPilot Settings
+
+Configure how FlowPilot behaves with PSA automation.
+
+- [ ] Go to **Account → Integrations → FlowPilot** tab
+- [ ] Review each setting:
+  - **Auto Push** — automatically post session doc on session close
+  - **Auto Time Entry** — automatically log hours from session duration
+  - **Time Rounding** — 15min / 30min / exact / none
+  - **Note Visibility** — internal only vs. internal + external
+  - **Include Diagnostic Steps** — whether to include step-by-step notes
+  - **Prompt Status on Resolution** — ask to update CW status when resolving
+  - **Prompt Status on Escalation** — ask to update CW status when escalating
+- [ ] Adjust to your preference and save
+
+---
+
+## Step 8 — End-to-End Smoke Test
+
+Run a complete session to confirm the full flow works together.
+
+- [ ] Start a new FlowPilot session with a test ticket in CW
+- [ ] Link the ticket at session start
+- [ ] Work through a troubleshooting flow (even a simple one)
+- [ ] Resolve or escalate the session
+- [ ] Post the session documentation to the CW ticket
+- [ ] Open the ticket in ConnectWise and confirm:
+  - [ ] Note content is correct and well-formatted
+  - [ ] Note is attributed to the correct CW member
+  - [ ] Ticket status was updated (if you chose to update)
+  - [ ] Duration / time entry was logged (if auto-time-entry is on)
+
+---
+
+## Known Issues / Bugs Fixed
+
+| Bug | Status | Location |
+|-----|--------|----------|
+| `create_time_entry()` used `self._client` instead of `self.client` | Fixed 2026-04-14 | `services/psa/connectwise/provider.py:539` |
+
+---
+
+## What's NOT Yet Implemented
+
+| Feature | Notes |
+|---------|-------|
+| Autotask PSA | Schema accepts `autotask` as provider but no implementation exists |
+| Retry queue for failed posts | `retry_count` / `next_retry_at` columns exist in DB but no background job |
+| `psa_activity_log` population | Table exists, no endpoints write to it yet |
+| Post History tab | Currently a placeholder — post history is viewable per-session only |

docs/handoff/2026-04-22-flowpilot-migration.md

@@ -0,0 +1,88 @@
+---
+date: 2026-04-22
+branch: feat/flowpilot-migration
+remote: ssh://gitea.resolutionflow.com/chihlasm/resolutionflow.git
+last_commit: faf1d8d fix(pilot): applied_at stamps on run-declaring actions, not Apply click
+status: Sprint 9/9 phases complete and pushed; PR not yet opened. Open items #1 and #3 resolved by Phase 9.
+---
+
+# FlowPilot Migration — Session Handoff
+
+## Where the work lives
+
+- Branch: `feat/flowpilot-migration` (pushed to Gitea, mirrors to GitHub)
+- Spec: [docs/FlowAssist_Migration/FLOWPILOT-MIGRATION.md](../FlowAssist_Migration/FLOWPILOT-MIGRATION.md)
+- Mockups: [docs/FlowAssist_Migration/mockups/](../FlowAssist_Migration/mockups/) (PNG + HTML reference)
+
+## What shipped
+
+All nine migration phases are merged onto the branch and verified against the live dev stack (`resolutionflow_frontend` / `resolutionflow_backend` / `resolutionflow_postgres` containers).
+
+| Phase | Commit | What landed |
+|---|---|---|
+| 0 — baseline telemetry | (pre-branch) | analytics events for funnel deltas |
+| 1 — `/assistant` → `/pilot` rename | early commits | route redirects, sidebar updates |
+| 2 — What we know (facts) | (mid) | `session_facts` table, `[PROMOTE]` marker, fact CRUD endpoints, `WhatWeKnow` section |
+| 3 — Suggested fix + Resolve preview | `7ccf4c6` and prior | `session_suggested_fixes`, `[SUGGEST_FIX]` marker, `ResolutionNotePreview` popover |
+| 4 — Escalate + PSA writeback | `8fd2c1b` | `psa_writeback_service` with status verification, kind-parameterized preview |
+| 5 — inline Script Generator | `fa61376` | `TemplateMatchPanel`, `NoTemplateDialog` three-option dialog |
+| 6 — post-resolve templatize | `4aaf57a` | `draft_templates` table, accept/reject endpoints, `TemplatizePrompt` modal, account preferences |
+| 7 — polish | `8a242f5` | loading/empty states, keyboard shortcuts (`⌘↵`, `⌘G`, `?` overlay), responsive bottom-drawer <1200px |
+| 8 — Fix Outcome Banner | `cdd8bb0`..`a47ce07` | Six outcome columns on `session_suggested_fixes` (`status`, `applied_at`, `verified_at`, `partial_notes`, `failure_reason`, `ai_outcome_proposal`) + `PATCH /api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/outcome` endpoint + `[FIX_OUTCOME]` marker; replaces task-lane `SuggestedFix` card with a chat-composer-anchored `ProposalBanner` (5 states: proposed/verifying/partial/ai_confirming/nudge + collapsed); `EscalateInterceptDialog` captures outcome before handoff; Resolve-while-verifying auto-marks success; 17 new tests (8 endpoint + 7 marker + 2 anti-parrot) |
+| 9 — Tabbed Script Builder | `5bcb7aa`..`faf1d8d` | Chat-region tab strip (`[Chat] [Script Builder ●]`) with `ChatTabStrip` + new `ScriptBuilderTab` controller wrapping the existing `ScriptBuilderChat` + Monaco editor (`ScriptBodyEditor`); `InlineNoTemplateDialog` relocates the existing `NoTemplateDialog` from the narrow task-lane `bottomSlot` to a chat-region placement wrapper; `EscalateInterceptDialog` gains a fourth "partial" choice; `PATCH /api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/script` endpoint for engineer-drafted scripts (does not stamp `applied_at`); Alembic migration adds `origin VARCHAR(20)` to `script_builder_sessions` (reuses existing `ai_session_id` FK) + partial unique index on `(user_id, ai_session_id) WHERE origin='pilot_inline'` for idempotent get-or-create; `applied_at` semantics corrected to stamp only on run-declaring actions (`handleScriptDecision` for `one_off`/`draft_template`; new `onMarkRun` on `TemplateMatchPanel`) — not the Apply click |
+
+Plus the structural fixes that came up along the way:
+- `50215b9` + `d0ebdef` — full sweep removing literal payloads from AI system prompts; new `tests/test_prompt_anti_parrot.py` guardrail
+- `ce7c8ac` + `ddae171` — task-lane state-leak across chats (centralized `resetSessionDerivedState()` helper)
+- `8879f96` — dropped `sticky top-0` from all four lane section headers (they were orphaning over unrelated content on scroll)
+
+## How to resume
+
+1. `git checkout feat/flowpilot-migration`
+2. `docker compose -f docker-compose.dev.yml up -d` (if the stack isn't running)
+3. Verify: `docker exec resolutionflow_frontend sh -c "cd /app && npx tsc -b"` should be clean
+4. Live URL: <http://localhost:5173/pilot> (or `<host-ip>:5173/pilot`)
+5. Test users (password `TestPass123!`): `engineer@resolutionflow.example.com`
+
+## Open work — pick one
+
+Items #1 and #3 were discovered during Phase 6/7 verification. Item #2 was resolved by Phase 8. Items #1 and #3 are **resolved by Phase 9** (see below).
+
+### 1. NoTemplateDialog narrow-lane bug
+**Status: RESOLVED by Phase 9.**
+
+Phase 9 relocated `InlineNoTemplateDialog` from the task-lane `bottomSlot` into a dedicated chat-region placement wrapper (`InlineNoTemplateDialog.tsx`). The dialog no longer renders inside the narrow 380px task lane, eliminating the `sm:grid-cols-3` viewport-breakpoint collision. The disabled-cards bug (when no `ai_drafted_script` is present) is also resolved: when no draft exists, the engineer is routed into the new `ScriptBuilderTab` inline chat instead of reaching the three-option dialog with disabled cards.
+
+See [docs/FlowAssist_Migration/phase-9-implementation-plan.md](../FlowAssist_Migration/phase-9-implementation-plan.md) and [docs/FlowAssist_Migration/phase-9-script-builder-tab.md](../FlowAssist_Migration/phase-9-script-builder-tab.md) for full implementation details.
+
+### 2. Task lane crowding / Suggested Fix discoverability
+**Status: RESOLVED by Phase 8.** The `SuggestedFix` card no longer lives inside the scrollable task lane. Phase 8 replaced it with a chat-composer-anchored slide-up banner (`ProposalBanner`) that is always visible at the bottom of the conversation column regardless of how far the task lane has scrolled. The banner is the primary entry point for fix application; the task lane retains a compact read-only summary of the active fix for reference.
+
+See [docs/FlowAssist_Migration/phase-8-fix-outcome-banner.md](../FlowAssist_Migration/phase-8-fix-outcome-banner.md) for the implementation plan and design rationale. Because the banner is now the primary entry point, the NoTemplateDialog narrow-lane bug (open item #1) is considerably less visible — the three-option dialog is only reached after the engineer opts in via the banner, at which point they have already acknowledged the fix.
+
+### 3. Tabbed Script Builder inside the chat (Option A from the modal-vs-tab discussion)
+**Status: RESOLVED by Phase 9.**
+
+Phase 9 shipped the complete tabbed Script Builder integration. The chat region now has a `[Chat] [Script Builder ●]` tab strip (`ChatTabStrip`) powered by a new `ScriptBuilderTab` controller that wraps the existing (untouched) `ScriptBuilderChat` for AI mode and `ScriptBodyEditor` (Monaco) for a "Write it myself" editor mode. `display: none` toggling preserves chat scroll position, draft message, and editor buffer across tab switches.
+
+The `PATCH /api/v1/ai-sessions/{sid}/suggested-fixes/{fid}/script` endpoint writes `ai_drafted_script` + `ai_drafted_parameters` back to the fix record without stamping `applied_at` — a draft is not an application. Bumps `state_version` so cached Resolve/Escalate previews regenerate.
+
+The migration added `origin VARCHAR(20) NOT NULL DEFAULT 'standalone'` (with CHECK constraint on the two valid values + invariant that `origin='pilot_inline'` requires `ai_session_id IS NOT NULL`) to `script_builder_sessions`. It reuses the pre-existing `ai_session_id` FK rather than adding a new parent column. A partial unique index on `(user_id, ai_session_id) WHERE origin='pilot_inline'` backs get-or-create idempotency from the inline tab.
+
+See [docs/FlowAssist_Migration/phase-9-implementation-plan.md](../FlowAssist_Migration/phase-9-implementation-plan.md) and [docs/FlowAssist_Migration/phase-9-script-builder-tab.md](../FlowAssist_Migration/phase-9-script-builder-tab.md) for full implementation details.
+
+## Loose ends / things to verify on resume
+
+- **PR not opened.** Branch is pushed but no Gitea PR yet. When ready: `gh pr create` works against the GitHub mirror, but the actual review happens in Gitea.
+- **`/ultrareview` not run** on the final state of the branch (including Phase 9). Worth doing before PR creation.
+- **Phase 9 browser QA not done.** The new tab strip, `ScriptBuilderTab` (AI + editor modes), `InlineNoTemplateDialog` chat-region placement, and `EscalateInterceptDialog` fourth-choice flow have not been exercised in a headless-browser session. Key states to cover: tab strip renders and toggles without unmounting chat or losing editor buffer; Script Builder tab Submit persists script via PATCH without stamping `applied_at`; `one_off`/`draft_template` decisions DO stamp; `build_template` does NOT stamp; `TemplateMatchPanel` "I ran this" stamps via `onMarkRun`; partial-attempt choice in `EscalateInterceptDialog` is recorded correctly.
+- **Phase 8 browser QA not done.** The `ProposalBanner` and `EscalateInterceptDialog` (three-choice variant) have not been exercised in a headless-browser session. Key states: banner appears on `[FIX_OUTCOME]` marker; banner dismisses correctly; escalate mid-fix triggers dialog; banner auto-collapses after session resolved. Use `/qa` or `/design-review` against `mockups/06-slide-up-banner.html` and `mockups/07-verify-states.html`.
+- **Phase 7 visual verification was structural only** — `tsc -b` and `npm run build` both clean, HMR applied each change without error, but no headless-browser screenshot comparison against the mockup PNGs. If you want pixel-level verification, `/qa` or `/design-review` would catch deltas.
+- **Anti-parrot test runs as part of `pytest`** but is not enforced in any specific CI step yet — verify `tests/test_prompt_anti_parrot.py` is discovered by the existing pytest run, and consider failing CI explicitly on regression.
+
+## Files most likely to need attention next
+
+- [frontend/src/pages/AssistantChatPage.tsx](../../frontend/src/pages/AssistantChatPage.tsx) — 1500+ lines, the central pilot orchestrator. Most state-leak and rendering bugs surface here first. Search for `resetSessionDerivedState` to see the chat-switch reset pattern.
+- [frontend/src/components/assistant/TaskLane.tsx](../../frontend/src/components/assistant/TaskLane.tsx) — accepts `whatWeKnowSlot` / `bottomSlot` from the parent, plus a `variant: 'side' | 'drawer'` for responsive. `bottomSlot` remains active (carries `TemplateMatchPanel` + resolve/escalate preview buttons in both side and drawer variants).
+- [backend/app/services/unified_chat_service.py](../../backend/app/services/unified_chat_service.py) — owns marker parsing for `[PROMOTE]`, `[SUGGEST_FIX]`, `[QUESTIONS]`, `[ACTIONS]`, `[FORK]`, `[TREE_UPDATE]`. If markers stop firing in chat, this is the first place to check.
+- [backend/app/services/assistant_chat_service.py](../../backend/app/services/assistant_chat_service.py) — `ASSISTANT_SYSTEM_PROMPT` constant. Anti-parrot test enforces no literal payloads here; use `<placeholder>` syntax only.

docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md

@@ -0,0 +1,757 @@
+# Network Diagram Editor — Draw.io-Style Implementation Document
+
+> **Date:** 2026-04-13  
+> **Status:** Proposed  
+> **Audience:** Product, frontend, backend, and agentic workers  
+> **Goal:** Build a production-grade network diagram editor inside ResolutionFlow that feels close to draw.io while staying MSP- and topology-focused.
+
+---
+
+## Executive Summary
+
+ResolutionFlow should implement network diagrams as a first-class editor surface, not as a lightweight canvas utility. The right target is not "clone draw.io exactly," but "deliver draw.io-grade editing quality for MSP network topology work."
+
+The recommended path is:
+
+1. **Use the existing network-diagram branch architecture as the foundation**
+2. **Ship the already-proven CRUD/editor shell as Phase 1**
+3. **Invest the next phases in interaction quality, editor commands, and interoperability**
+4. **Keep a ResolutionFlow-native JSON schema as the source of truth**
+5. **Add draw.io compatibility at import/export boundaries, not at the storage layer**
+
+This preserves delivery speed while giving the product room to grow into a robust diagramming tool.
+
+---
+
+## Product Goal
+
+Build a network diagram creation tool that:
+
+- Feels familiar to users who already know draw.io
+- Supports MSP workflows better than a generic diagramming app
+- Makes manual editing fast and safe
+- Supports AI-assisted generation and clean-up without depending on AI for correctness
+- Fits ResolutionFlow's existing frontend/backend architecture cleanly
+
+Success is not measured by raw feature count alone. Success means a user can open the editor and confidently:
+
+- Create a clean network map from scratch
+- Drag devices from a stencil palette onto a canvas
+- Connect, label, group, align, copy, duplicate, and organize elements quickly
+- Save and revisit diagrams safely
+- Export the result for documentation and client communication
+
+---
+
+## Existing Repo Context
+
+ResolutionFlow already has strong signals for this direction:
+
+- The main architecture is React 19 + Vite + TypeScript on the frontend, FastAPI + PostgreSQL on the backend.
+- There are existing design and plan docs for network diagrams:
+  - `docs/superpowers/specs/2026-04-04-react-flow-ui-network-diagrams-design.md`
+  - `docs/superpowers/specs/2026-04-04-network-diagram-ux-improvements-design.md`
+  - `docs/superpowers/plans/2026-04-04-react-flow-ui-network-diagrams.md`
+  - `docs/superpowers/plans/2026-04-04-network-diagram-ux-improvements.md`
+- Git history shows a substantial prior implementation on `feat/network-map-builder-prod`.
+
+That branch already included:
+
+- Backend model, schema, migration, API routes, and AI generation service
+- Frontend list page and editor page
+- React Flow-based canvas
+- Device registry and custom node types
+- Context menu, copy/paste/duplicate shortcuts, and drag/drop improvements
+- Inspector/properties panel
+- Import/export JSON
+
+This is important: **the best implementation path is to revive and harden that architecture, not to invent a parallel one.**
+
+---
+
+## Non-Goals
+
+The first implementation should not try to become a full whiteboard platform.
+
+Out of scope for the initial milestone:
+
+- Real-time multiplayer collaboration
+- Comments/presence/cursors
+- Arbitrary slide decks or presentation features
+- BPMN/UML/general enterprise diagram libraries
+- Full draw.io parity on day one
+- Replacing ResolutionFlow's tree editor architecture
+
+The editor should stay focused on network topology and MSP documentation use cases.
+
+---
+
+## User Experience Target
+
+The editor should feel close to draw.io in the following ways:
+
+- Fast drag/drop from a left stencil panel
+- Predictable selection behavior
+- Context menus and keyboard shortcuts
+- Snap-to-grid and alignment affordances
+- Resizable groups and containers
+- Good edge routing options
+- Easy text and label editing
+- Familiar import/export workflows
+
+The editor should exceed draw.io in MSP-specific workflows:
+
+- Device types that reflect real client environments
+- AI-generated starting diagrams from text descriptions
+- Client and asset metadata
+- Future hooks into PSA, assets, tickets, and documentation
+
+---
+
+## Recommended Architecture
+
+### Frontend
+
+Use a dedicated feature area:
+
+- `frontend/src/pages/NetworkDiagrams/`
+- `frontend/src/components/network/`
+- `frontend/src/api/networkDiagrams.ts`
+- `frontend/src/types/network-diagram.ts`
+
+Use React Flow as the canvas/rendering engine.
+
+Why React Flow:
+
+- Already used conceptually in the codebase
+- Strong node/edge rendering model
+- Good selection/dragging/viewport primitives
+- Enough flexibility for custom nodes, groups, and edge styles
+- Faster path to production than building custom canvas behavior from scratch
+
+### Backend
+
+Use a document-style data model stored in PostgreSQL JSONB:
+
+- `network_diagrams` table
+- JSONB `nodes`
+- JSONB `edges`
+- Metadata columns for account scoping, names, timestamps, archive state
+
+Why document storage:
+
+- Flexible schema evolution
+- Fast implementation
+- Simple import/export
+- Easy autosave
+- Works well with editor-state persistence
+
+### Source of Truth
+
+Use a ResolutionFlow-native schema as the system of record.
+
+Do not store draw.io XML as the primary database format.
+
+Instead:
+
+- Store native JSON internally
+- Import from draw.io into native JSON
+- Export native JSON to draw.io-compatible XML when needed
+
+This keeps the application decoupled from an external vendor format.
+
+---
+
+## Recommended File Layout
+
+### Frontend
+
+- `frontend/src/pages/NetworkDiagrams/index.tsx`
+  - Diagram list page
+
+- `frontend/src/pages/NetworkDiagrams/DiagramEditor.tsx`
+  - Editor orchestration layer
+
+- `frontend/src/components/network/NetworkCanvas.tsx`
+  - React Flow wrapper and viewport surface
+
+- `frontend/src/components/network/DiagramHeader.tsx`
+  - Save state, title, metadata actions, export/import controls
+
+- `frontend/src/components/network/ContextMenu.tsx`
+  - Node/canvas context menus
+
+- `frontend/src/components/network/CanvasEmptyPrompt.tsx`
+  - Empty-state guidance
+
+- `frontend/src/components/network/panels/DeviceToolbar.tsx`
+  - Stencil palette and searchable device library
+
+- `frontend/src/components/network/panels/PropertiesPanel.tsx`
+  - Inspector for node/edge editing
+
+- `frontend/src/components/network/panels/AIAssistPanel.tsx`
+  - AI generate/merge UX
+
+- `frontend/src/components/network/hooks/useCanvasShortcuts.ts`
+  - Keyboard shortcuts and clipboard behavior
+
+- `frontend/src/components/network/hooks/useDiagramCommands.ts`
+  - Shared command layer for actions invoked by keyboard, menus, and toolbar
+
+- `frontend/src/components/network/nodes/*`
+  - Node components, registry, types, and render configuration
+
+- `frontend/src/components/network/edges/*`
+  - Edge components and routing styles
+
+- `frontend/src/api/networkDiagrams.ts`
+  - CRUD, import/export, AI generation, duplication
+
+- `frontend/src/types/network-diagram.ts`
+  - Shared client-side typing
+
+### Backend
+
+- `backend/app/models/network_diagram.py`
+  - SQLAlchemy model
+
+- `backend/app/schemas/network_diagram.py`
+  - Pydantic request/response models
+
+- `backend/app/api/endpoints/network_diagrams.py`
+  - CRUD + import/export + AI routes
+
+- `backend/app/services/network_diagram_ai_service.py`
+  - AI generation and later AI clean-up/layout assistance
+
+- `backend/alembic/versions/074_add_network_diagrams_table.py`
+  - Initial schema migration
+
+- `backend/app/models/network_diagram_version.py`
+  - Later addition for version history
+
+- `backend/app/api/endpoints/network_diagram_versions.py`
+  - Later addition for restore/history flows
+
+---
+
+## Data Model
+
+### V1 Database Model
+
+The existing JSONB storage pattern is good for a first release:
+
+- `id`
+- `account_id`
+- `name`
+- `client_name`
+- `asset_name`
+- `description`
+- `nodes` JSONB
+- `edges` JSONB
+- `thumbnail_url`
+- `is_archived`
+- `created_by`
+- `created_at`
+- `updated_at`
+
+### Recommended Node Schema
+
+Use a richer internal node shape than a minimal device-only object. The schema should be resilient enough to support future features without painful migration.
+
+Recommended fields:
+
+- `id`
+- `kind`
+  - `device | group | text | shape | image`
+- `type`
+  - device slug or shape subtype
+- `label`
+- `position`
+- `size`
+- `rotation`
+- `zIndex`
+- `parentId`
+- `ports`
+- `style`
+- `data`
+
+Examples:
+
+- `kind=device`, `type=router`
+- `kind=group`, `type=subnet`
+- `kind=text`, `type=label`
+
+### Recommended Edge Schema
+
+- `id`
+- `source`
+- `target`
+- `sourcePort`
+- `targetPort`
+- `label`
+- `routing`
+  - `straight | step | orthogonal | curved`
+- `waypoints`
+- `style`
+- `data`
+
+### Why This Matters
+
+The prior branch stored a solid but fairly lean `DiagramNode`/`DiagramEdge`. That is enough to start, but draw.io-like editing will need more than just `position`, `label`, and `connectionType`.
+
+If we adopt the richer shape early, we reduce future rework in:
+
+- manual bend-point support
+- z-ordering
+- groups/containers
+- text/shape nodes
+- port-specific connections
+
+---
+
+## Editor State Model
+
+The editor should be built around four distinct layers of state:
+
+### 1. Persisted Diagram State
+
+What is saved to the backend:
+
+- nodes
+- edges
+- metadata
+
+### 2. Editor UI State
+
+What lives only in the browser while editing:
+
+- selected node IDs
+- selected edge IDs
+- open context menu
+- active tool
+- inspector visibility
+- drag-over state
+- clipboard reference
+
+### 3. Derived View State
+
+- filtered palette items
+- current selection bounds
+- whether paste is available
+- whether align/distribute commands are valid
+
+### 4. History State
+
+- undo stack
+- redo stack
+- last autosave timestamp
+
+The editor page should orchestrate these, but command logic should not be scattered across component trees.
+
+---
+
+## Command System
+
+To make the tool feel like draw.io, add a shared command layer.
+
+Recommended hook:
+
+- `frontend/src/components/network/hooks/useDiagramCommands.ts`
+
+This hook should expose commands like:
+
+- `copySelection`
+- `pasteSelection`
+- `duplicateSelection`
+- `deleteSelection`
+- `selectAll`
+- `fitView`
+- `bringToFront`
+- `sendToBack`
+- `alignLeft`
+- `alignCenter`
+- `alignRight`
+- `alignTop`
+- `alignMiddle`
+- `alignBottom`
+- `distributeHorizontally`
+- `distributeVertically`
+- `groupSelection`
+- `ungroupSelection`
+- `lockSelection`
+- `unlockSelection`
+
+All of the following should call the same command functions:
+
+- keyboard shortcuts
+- toolbar buttons
+- context menu items
+- future command palette entries
+
+This avoids duplicate logic and keeps behavior consistent.
+
+---
+
+## Phase-by-Phase Delivery Plan
+
+## Phase 1 — Foundation MVP
+
+### Objective
+
+Ship a usable network diagram editor quickly using the existing branch shape.
+
+### Scope
+
+- Diagram list page
+- Create/edit/archive/duplicate
+- React Flow canvas
+- Searchable device palette
+- Device and group nodes
+- Edge creation
+- Properties panel
+- Save + autosave
+- Import/export ResolutionFlow JSON
+- Basic AI generation from natural language
+- Context menu
+- Keyboard shortcuts:
+  - copy
+  - paste
+  - duplicate
+  - select all
+  - fit view
+  - delete
+
+### Frontend Work
+
+- Restore `NetworkDiagrams` page routes and navigation
+- Restore `DiagramEditor`
+- Restore `NetworkCanvas`
+- Restore node/edge registries
+- Restore clipboard + context menu behavior
+- Add command-layer extraction if time allows
+
+### Backend Work
+
+- Restore migration, model, schemas, endpoints
+- Validate account scoping and tenant isolation
+- Restore import/export endpoint
+- Restore AI generate endpoint
+
+### Acceptance Criteria
+
+- User can create and save a network map
+- User can reopen it later
+- User can drag devices from palette onto canvas
+- User can connect nodes and label links
+- User can copy/paste/duplicate/delete
+- User can import/export JSON
+- User can generate a starter diagram from text
+
+---
+
+## Phase 2 — Draw.io-Grade Editing Quality
+
+### Objective
+
+Close the biggest UX gap between a basic node editor and a real diagramming tool.
+
+### Scope
+
+- Snap-to-guides in addition to snap-to-grid
+- Alignment commands
+- Distribution commands
+- Multi-select improvements
+- Better z-order handling
+- Inline text editing
+- Better group/container behavior
+- Rich edge routing choices
+- Manual bend points
+- Port-aware connection handling
+- Keyboard nudging and modifier behavior
+
+### New/Expanded Files
+
+- `hooks/useDiagramCommands.ts`
+- `hooks/useSelectionBounds.ts`
+- `components/network/guides/*`
+- `components/network/edges/*`
+
+### Acceptance Criteria
+
+- Multi-select editing feels reliable
+- Align/distribute work predictably
+- User can produce a polished topology without fighting the canvas
+- Connectors can be shaped intentionally rather than only auto-routed
+
+---
+
+## Phase 3 — Interoperability and Export
+
+### Objective
+
+Let the editor fit real customer and internal documentation workflows.
+
+### Scope
+
+- SVG export
+- PNG export
+- PDF export
+- Thumbnail generation
+- Draw.io XML import
+- Draw.io XML export
+
+### Implementation Notes
+
+Do not try to mirror every draw.io primitive internally.
+
+Instead:
+
+- Build a compatible subset for network maps
+- Translate supported draw.io elements into native nodes/edges/groups/text
+- Emit supported native diagrams back into draw.io XML
+- Warn on unsupported constructs during import
+
+### Acceptance Criteria
+
+- A diagram can be exported for customer-facing documentation
+- A supported draw.io network map can be imported into ResolutionFlow
+- Users can move work between tools without losing essential topology content
+
+---
+
+## Phase 4 — ResolutionFlow-Native Differentiation
+
+### Objective
+
+Make this better than a generic diagram editor for MSP use cases.
+
+### Scope
+
+- AI merge into existing topology
+- AI tidy-up / auto-layout refinement
+- Asset-aware device metadata
+- Client templates
+- Common MSP topology starter kits
+- Diagram-to-ticket or diagram-to-flow linking
+- Version history and restore
+
+### Acceptance Criteria
+
+- AI helps users start faster and clean up faster
+- Diagrams connect to the rest of the ResolutionFlow product
+- Version history reduces fear of experimentation
+
+---
+
+## Draw.io Parity Matrix
+
+| Capability | Priority | Notes |
+|-----------|----------|-------|
+| Drag/drop stencil palette | P0 | Must feel immediate and stable |
+| Node resize/move/select | P0 | Core editor behavior |
+| Edge creation and labeling | P0 | Core topology use case |
+| Copy/paste/duplicate/delete | P0 | Expected baseline |
+| Context menu + keyboard shortcuts | P0 | Must be fast and familiar |
+| Snap-to-grid | P0 | Already supported directionally |
+| Align/distribute | P1 | Big usability leap |
+| Grouping/containers | P1 | Important for subnets, rooms, racks |
+| Edge routing modes | P1 | Necessary for professional-looking diagrams |
+| Inline text editing | P1 | Draw.io expectation |
+| Layers/lock/hide | P2 | Useful once diagrams get large |
+| Draw.io import/export | P2 | Important for migration and adoption |
+| Realtime collaboration | P3 | Valuable, but not early priority |
+
+---
+
+## Risks and Mitigations
+
+### Risk: Editor complexity balloons too quickly
+
+**Mitigation**
+
+- Keep the MVP narrow
+- Use phased delivery
+- Center everything around the command layer
+
+### Risk: React Flow abstraction limits parity
+
+**Mitigation**
+
+- Validate manual bend points, grouping, and selection ergonomics early
+- If a specific advanced behavior is awkward, implement it in a focused extension layer instead of abandoning React Flow entirely
+
+### Risk: Import/export compatibility becomes a trap
+
+**Mitigation**
+
+- Support a documented subset of draw.io semantics
+- Keep native JSON as the canonical internal model
+- Warn clearly on unsupported import constructs
+
+### Risk: AI-generated diagrams feel impressive but unreliable
+
+**Mitigation**
+
+- Treat AI output as a starting point only
+- Keep editing UX first-class
+- Make merge mode explicit and safe
+
+### Risk: Users lose work through autosave/history gaps
+
+**Mitigation**
+
+- Add diagram versioning soon after MVP
+- Preserve a local dirty-state guard
+- Add explicit "saved at" feedback
+
+---
+
+## Versioning Recommendation
+
+Version history should be planned early, even if shipped after the MVP.
+
+Recommended table:
+
+- `network_diagram_versions`
+  - `id`
+  - `diagram_id`
+  - `account_id`
+  - `snapshot` JSONB
+  - `created_by`
+  - `label`
+  - `created_at`
+
+Recommended triggers for version creation:
+
+- explicit "Save Version"
+- before destructive import-replace
+- before AI replace mode
+- optionally every N minutes when dirty changes are substantial
+
+This is one of the highest-leverage additions for user trust.
+
+---
+
+## Testing Strategy
+
+### Frontend
+
+- Unit-test command logic
+- Unit-test serialization/deserialization
+- Component-test context menu and shortcut behavior
+- E2E test core editor flows:
+  - create diagram
+  - drag node
+  - connect nodes
+  - save and reload
+  - copy/paste
+  - import/export
+
+### Backend
+
+- API tests for CRUD
+- API tests for tenant isolation
+- API tests for import/export validation
+- API tests for duplicate/archive
+- AI endpoint tests with mocked provider output
+
+### Manual QA
+
+Required flows:
+
+- New blank diagram
+- Existing diagram edit
+- Large diagram performance
+- Multi-select behavior
+- Keyboard shortcut guard behavior while inputs are focused
+- Import malformed JSON
+- AI merge into populated canvas
+
+---
+
+## Suggested Delivery Order
+
+### Slice 1
+
+- Restore backend migration/model/schema/router
+- Restore types and API client
+- Restore list page
+
+### Slice 2
+
+- Restore editor shell and canvas
+- Restore nodes, edges, palette, save/load
+
+### Slice 3
+
+- Restore context menu, clipboard, shortcuts, inspector
+- Validate dirty-state and autosave behavior
+
+### Slice 4
+
+- Restore AI generation and merge mode
+- Tighten import/export UX
+
+### Slice 5
+
+- Implement command layer
+- Add align/distribute/z-order polish
+
+### Slice 6
+
+- Add version history
+- Add export polish and thumbnails
+
+### Slice 7
+
+- Add draw.io XML import/export subset
+
+---
+
+## Recommended Immediate Next Step
+
+The best immediate implementation move is:
+
+1. **Rebase or selectively port `feat/network-map-builder-prod` into the current codebase**
+2. **Use that as the Phase 1 foundation**
+3. **Do not start by rewriting the editor architecture**
+
+That approach is faster, lower risk, and already aligned with the repo's documented direction.
+
+---
+
+## Worker Notes
+
+If agentic workers implement this plan, they should:
+
+- Reuse the existing network-diagram branch structure where possible
+- Avoid introducing a second diagram architecture
+- Keep native JSON as the canonical schema
+- Treat command centralization as a priority, not an afterthought
+- Ship MVP behavior first, then polish toward draw.io parity in focused slices
+
+---
+
+## Summary
+
+ResolutionFlow can support a draw.io-like network diagram editor without fighting its current stack. The prior network-diagram branch already proves the right foundation:
+
+- React Flow canvas
+- FastAPI CRUD
+- JSONB persistence
+- device registry
+- AI assist
+- context menus
+- keyboard shortcuts
+- import/export
+
+The real work now is not deciding whether to build it. The real work is:
+
+- restoring that foundation cleanly,
+- formalizing the internal schema,
+- adding a reusable command system,
+- and iterating on the editor interactions until the experience feels professional.
+
+That path gives ResolutionFlow a practical, high-value network topology tool quickly, while preserving a credible route to near-draw.io quality over the next phases.

frontend/package-lock.json

@@ -23,6 +23,7 @@
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "date-fns": "^4.1.0",
+        "html-to-image": "^1.11.13",
         "immer": "^11.1.3",
         "lucide-react": "^0.563.0",
         "monaco-editor": "^0.55.1",
@@ -5331,6 +5332,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/html-to-image": {
+      "version": "1.11.13",
+      "resolved": "https://registry.npmjs.org/html-to-image/-/html-to-image-1.11.13.tgz",
+      "integrity": "sha512-cuOPoI7WApyhBElTTb9oqsawRvZ0rHhaHwghRLlTuffoD1B2aDemlCruLeZrUIIdvG7gs9xeELEPm6PhuASqrg==",
+      "license": "MIT"
+    },
     "node_modules/html-url-attributes": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",