feat(pilot): unify AI troubleshooting surface at /pilot, redirect /assistant (Phase 1)

Collapses the pre-existing dual-surface setup (AssistantChatPage at /assistant,
FlowPilotSessionPage at /pilot) into a single chat-primary surface per
architectural claim #1 of FLOWPILOT-MIGRATION.md.

Router changes (frontend/src/router.tsx):
- /pilot and /pilot/:sessionId now render AssistantChatPage.
- /assistant redirects permanently to /pilot via <Navigate replace>.
- /assistant/:sessionId redirects to /pilot/:sessionId preserving the ID
  via an AssistantSessionRedirect helper that reads the param.
- FlowPilotSessionPage is no longer imported or mounted. Per the
  beta-history-disposable decision, the file stays on disk for reference
  but is unreachable; delete once nothing else in the tree imports it.

Dispatcher de-branching — previously these sites routed by session_type
(chat -> /assistant, otherwise -> /pilot). All now unconditionally go to
/pilot/:id since session_type is no longer used for frontend routing:
- components/dashboard/ActiveFlowPilotSessions.tsx
- components/dashboard/RecentFlowPilotSessions.tsx
- components/flowpilot/AISessionListItem.tsx
  (keeps isChat for icon selection, but linkTo is unconditional)

User-facing label + navigation updates:
- components/layout/CommandPalette.tsx: "AI Assistant" palette entry
  becomes "FlowPilot" pointing to /pilot; the sparkles quick-action also
  routes to /pilot.
- components/dashboard/StartSessionInput.tsx: both navigate() call sites
  now go to /pilot instead of /assistant.
- lib/routePrefetch.ts: prefetch entry for AssistantChatPage keyed to
  /pilot (the real surface) rather than /assistant (now redirect-only).

Preserved intentionally (not user-facing routes):
- Backend /assistant/retention API path and the assistantChatApi module
  name — those are internal API and module identifiers, not SPA routes.
- src/components/assistant/* and src/types/assistant-chat — TypeScript
  module paths, not routes.
- Sidebar.tsx — no top-level AI entry existed to rename; /pilot is
  already in the History group's matchPaths. Whether FlowPilot deserves
  its own rail entry is a future UX decision, not Phase 1 scope.
- FlowPilotAnalyticsPage at /analytics/flowpilot — analytics for the
  unified product, not guided-only, per the agreed Q16 interpretation.

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

@@ -222,10 +222,9 @@ docker exec -it resolutionflow_postgres psql -U postgres -d resolutionflow
 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
+# CI runs on Gitea (gitea.resolutionflow.com), NOT GitHub Actions — gh run list will return nothing useful
+# Check CI status at: https://gitea.resolutionflow.com/chihlasm/resolutionflow/actions
+# `gh` CLI is still used for GitHub Issues/PRs (mirrored repo), not for CI runs
 ```
 
 ### URLs
@@ -381,6 +380,10 @@ gh run view <id> --json jobs --jq '.jobs[] | {name: .name, conclusion: .conclusi
 
 **109. `tree_shares.account_id` must equal `tree.account_id`, not the actor's account:** When creating a `TreeShare`, always use `account_id=tree.account_id` (tree owner's tenant). A super admin in tenant A sharing tenant B's tree must produce a share row in tenant B's RLS context — using `current_user.account_id` instead makes the share invisible to the tree owner after RLS is enforced.
 
+**110. Backfill migrations for `account_id` require a service-code audit:** When a migration adds `account_id` to an existing model via backfill (nullable → backfill → NOT NULL), grep for ALL `ModelClass(` instantiation sites in service code and verify `account_id=` is passed. SQLAlchemy accepts `None` silently with no warning; Phase 4 RLS WITH CHECK only surfaces the problem at runtime as `InsufficientPrivilegeError: new row violates row-level security policy`. Fixed example: `AISessionStep` — all 5 creation sites in `flowpilot_engine.py` were missing `account_id` until April 2026.
+
+**111. Global Axios interceptor fires before component `.catch()` — fix optional-data endpoints at the source:** The global 5xx handler in `client.ts` fires for ALL non-401 5xx responses, even when a component does `.catch(() => {})`. If an endpoint returns optional UI data (e.g., board filters, PSA config), return `[]` / `{}` on provider failure rather than raising 502. Silencing the error in the component is not enough — the toast appears anyway. See `list_boards` in `integrations.py` for the fixed pattern.
+
 ## RBAC & Permissions
 
 - **Role hierarchy:** super_admin > team_admin > engineer > viewer
@@ -450,6 +453,7 @@ gh run view <id> --json jobs --jq '.jobs[] | {name: .name, conclusion: .conclusi
 - 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
+- **Remote is Gitea, not GitHub directly:** Push to `gitea.resolutionflow.com/chihlasm/resolutionflow`. Gitea auto-mirrors to GitHub via `.gitea/workflows/mirror-to-github.yml` — never push directly to GitHub.
 
 ### After Completing Work
 
@@ -497,7 +501,7 @@ When a feature, fix, or significant piece of work is finished and merged/committ
 ## Deployment (Railway)
 
 - **Production:** `resolutionflow.com` (frontend), `api.resolutionflow.com` (backend)
-- Auto-deploys on push to `main`
+- Auto-deploys via: push to Gitea → Gitea mirrors to GitHub → Railway watches GitHub `main` and deploys
 - 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`
@@ -525,104 +529,42 @@ When a feature, fix, or significant piece of work is finished and merged/committ
 | 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.
+This project is indexed by GitNexus as **resolutionflow**. Use it selectively — for routine additive work (new endpoints, new components, isolated fixes) just read the files directly. GitNexus earns its cost when you're about to touch something genuinely central with many callers.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 
-## Always Do
+## When to Use It
 
-- **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"})`.
+**Use GitNexus when:**
+- Touching a core shared symbol with many callers — `flowpilot_engine`, `unified_chat_service`, auth middleware, `get_db`, shared hooks
+- Renaming anything used across multiple files
+- Tracing an unfamiliar bug through a call chain you haven't read
+- Assessing whether a refactor is safe before starting
 
-## When Debugging
+**Skip GitNexus when:**
+- Adding a new endpoint, component, or isolated feature
+- Fixing a bug in a self-contained file
+- Making changes you can already see the full scope of by reading the file
 
-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
+## Useful Tools
 
 | 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"})` |
+| `query` | Find code by concept when you don't know where to look | `gitnexus_query({query: "auth validation"})` |
+| `context` | See all callers/callees of a symbol before touching it | `gitnexus_context({name: "symbolName"})` |
+| `impact` | Blast radius check before editing a shared symbol | `gitnexus_impact({target: "X", direction: "upstream"})` |
 | `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:
+A PostToolUse hook re-indexes automatically after `git commit`. To manually refresh:
 
 ```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 -->

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

@@ -431,10 +431,19 @@ async def create_account(
     current_user: Annotated[User, Depends(require_admin)],
 ):
     """Create a new account without requiring an initial user."""
+    owner_id = None
+    if data.owner_email:
+        result = await db.execute(select(User).where(User.email == data.owner_email.strip()))
+        owner = result.scalar_one_or_none()
+        if not owner:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"No user found with email '{data.owner_email}'")
+        owner_id = owner.id
+
     display_code = await _generate_unique_display_code(db)
     new_account = Account(
         name=data.name.strip(),
         display_code=display_code,
+        owner_id=owner_id,
     )
     db.add(new_account)
     await db.flush()
@@ -448,7 +457,7 @@ async def create_account(
 
     await log_audit(
         db, current_user.id, "account.create_admin", "account", new_account.id,
-        {"name": new_account.name, "plan": data.plan},
+        {"name": new_account.name, "plan": data.plan, "owner_email": data.owner_email},
     )
     await db.commit()
     return await _get_account_detail_payload(new_account.id, db)

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

@@ -24,6 +24,7 @@ from app.api.endpoints import (
     branding,
     categories,
     copilot,
+    device_types,
     feedback,
     flow_proposals,
     flowpilot_analytics,
@@ -32,6 +33,7 @@ from app.api.endpoints import (
     invite,
     kb_accelerator,
     maintenance_schedules,
+    network_diagrams,
     notifications,
     onboarding,
     public_templates,
@@ -93,7 +95,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,6 +131,7 @@ 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)
@@ -142,3 +144,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_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

@@ -146,7 +146,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 +210,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,7 @@ class Settings(BaseSettings):
         "variable_inference": "fast",
         "kb_convert": "standard",
         "script_build": "standard",
+        "network_diagram_generate": "standard",
     }
 
     def get_model_for_action(self, action_type: str) -> str:

backend/app/core/kb_conversion_service.py

@@ -425,7 +425,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
+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="'[]'")
+    edges: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, server_default="'[]'")
+    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_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,80 @@
+"""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",
+        ),
+    )
+
+    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)
+    # 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

@@ -126,6 +126,7 @@ class AdminAccountDetailResponse(AdminAccountListItem):
 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):
@@ -319,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/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/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__)
@@ -184,7 +206,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 +224,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 +243,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 +314,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 +337,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 +376,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/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/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/script_builder_service.py

@@ -220,7 +220,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,
     )

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

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/FLOWPILOT-MIGRATION.md

@@ -0,0 +1,960 @@
+# FlowPilot Migration — Design & Implementation Doc
+
+> **Target:** Transform `/assistant` (ResolutionAssist) into the new unified `/pilot` (FlowPilot) surface.
+> **Audience:** Claude Code (implementation) and Codex (review) reviewed by Michael (owner).
+> **Status:** Phase 0 in progress. Phases 1–7 awaiting Phase 0 completion for the AI-dependent work; Phase 1 can run in parallel.
+> **Last updated:** April 17, 2026 (post-Codex plan review, reflects Phase 0 audit findings and in-flight implementation decisions)
+
+---
+
+## 0. Prerequisite reading for Claude Code
+
+Before writing any code for Phase 1 or later, 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 compatibility, but the product shows one unified UI and no new code branches on `session_type` for UI routing.
+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*.
+
+### 0.1 Spec drift note for reviewers
+
+This document was originally written against a set of assumptions about the codebase that turned out to be partially incorrect. Two audits (Claude Code's Phase 0 audit and the Codex plan review) surfaced drift. Key corrections already integrated:
+
+- **API namespace is `/api/v1/ai-sessions/{id}/...`**, not the doc's original `/api/v1/sessions/{id}/...`. All route references below reflect this.
+- **`pending_task_lane` items do not have stable IDs today.** Phase 2 must assign stable UUIDs when questions/checks are first persisted. `session_facts.source_ref` points to those JSON item IDs.
+- **`account_settings` table did not exist.** Phase 1 creates it with a JSONB `preferences` column; settings live in `preferences` until they need their own column.
+- **`/tickets/ai-parse` endpoint does not exist.** Phase 0.2 became a doc-only note; no code change.
+
+Any further drift found during implementation should be flagged by the implementer and reconciled in this doc before writing code that assumes the drifted spec.
+
+---
+
+## 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 original 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. |
+| **Task lane item ID** | A stable UUID assigned to each question / action / check inside `ai_sessions.pending_task_lane` when first persisted. `session_facts.source_ref` points to these. |
+| **Fact** | An item in the What we know section. Has `text`, `source_type` (`question` / `diagnostic_check` / `user_note` / `ai_synthesis`), and `source_ref` (task lane item ID, or null for `user_note` and `ai_synthesis`). |
+| **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 (via `[PROMOTE]` marker), 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. |
+| **Draft template** | A script generated during a session where the engineer chose "Run now, templatize after resolve." Lives in `draft_templates` until accepted or rejected. |
+
+---
+
+## 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
+   - Fact editability: **facts sourced from questions or diagnostic checks are read-only at the fact card level** (edit the source question/check instead); **manual notes and AI-synthesis facts are editable**
+
+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 3.4)
+   - 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,
+  ADD COLUMN escalation_package_external_id VARCHAR(128) NULL,
+  ADD COLUMN state_version INTEGER NOT NULL DEFAULT 0;  -- incremented on any write to facts/suggested_fixes/script_generations; drives preview cache invalidation
+```
+
+No migration of `session_type` — the column stays for data compatibility. New sessions default to the unified FlowPilot type. Phase 1 does not branch frontend routing on `session_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,  -- task lane item ID (from pending_task_lane JSON), null for user_note and ai_synthesis
+  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 pointer to a JSON item inside `ai_sessions.pending_task_lane` (not a FK to any table). It has no database-level FK constraint. Enforce integrity at the service layer. Phase 2 includes the work of assigning stable UUIDs to task lane items so `source_ref` has something reliable to point to.
+
+### 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_active 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()
+);
+CREATE INDEX idx_draft_templates_account_pending ON draft_templates(account_id) WHERE status = 'pending';
+```
+
+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 New `account_settings` table
+
+The codebase has no existing `account_settings` table. Create it with a JSONB grab-bag column for simple settings, plus room for typed columns as settings graduate to needing their own structure.
+
+```sql
+CREATE TABLE account_settings (
+  account_id UUID PRIMARY KEY REFERENCES accounts(id) ON DELETE CASCADE,
+  preferences JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+**Row lifecycle:** rows are created lazily on first write. A `get_setting(account_id, key, default)` helper returns the default when no row exists — no upfront row creation for every account.
+
+**Promotion rule:** settings live in `preferences` (keyed JSON) until they meet one of these thresholds:
+- Accessed in a hot path (frequent reads, latency-sensitive)
+- Has validation rules that warrant a CHECK constraint
+- Participates in joins or aggregations
+
+When a setting graduates, add a typed column in a future migration and update `get_setting` to prefer the typed column over the JSON key.
+
+**Initial contents:** `templatize_prompt_enabled` lives in `preferences` as `{"templatize_prompt_enabled": true}` (effective default when absent). No column needed.
+
+---
+
+## 5. API endpoints
+
+All endpoints follow ResolutionFlow conventions: `/api/v1/` prefix, JWT auth, tenant-scoped via RLS. **All session-related routes use the `/api/v1/ai-sessions/{id}/...` namespace** to match the existing codebase pattern (not the generic `/sessions/` originally specced).
+
+### 5.1 Session facts
+
+```
+GET    /api/v1/ai-sessions/{id}/facts               List facts for a session (ordered by created_at ASC)
+POST   /api/v1/ai-sessions/{id}/facts               Create a manual fact (user_note source_type)
+PATCH  /api/v1/ai-sessions/{id}/facts/{fact_id}     Edit fact text or summary
+                                                    Authorization: only user_note and ai_synthesis facts are editable;
+                                                    question and diagnostic_check facts return 403 (edit the source instead)
+DELETE /api/v1/ai-sessions/{id}/facts/{fact_id}     Soft-delete
+POST   /api/v1/ai-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/ai-sessions/{id}/suggested-fixes/active     Returns the current active fix (superseded_at IS NULL) or 404
+POST   /api/v1/ai-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: returns redirect payload 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/ai-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. Cached by state_version.
+POST   /api/v1/ai-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/ai-sessions/{id}/escalation-package/preview Same pattern for escalation
+POST   /api/v1/ai-sessions/{id}/escalation-package/post    Posts and transitions session to escalated state
+```
+
+### 5.5 Preview caching strategy
+
+The resolution note preview and escalation package preview are LLM-generated and refresh on every fact / suggested-fix / script-generation change. To avoid LLM-per-keystroke cost:
+
+- **Cache key:** `(session_id, state_version)` where `state_version` is the `ai_sessions.state_version` integer column
+- **Invalidation:** any write to `session_facts`, `session_suggested_fixes`, or `script_generations` for a session atomically increments `ai_sessions.state_version` (a single SQL UPDATE wrapped into the same transaction)
+- **Cache backend:** Redis (planned for Session Sharing work; can be in-memory LRU for Phase 3, swapped to Redis when Redis is available)
+- **Client debounce:** 500ms on the UI side to batch rapid edits before hitting the preview endpoint
+
+The choice of `state_version` over content hash is deliberate: cheaper to compute (single-integer comparison), easier to debug (logs show explicit version bumps), and makes invalidation failures visible (stale preview would keep showing an old version number).
+
+---
+
+## 6. Services to implement
+
+### 6.1 `FactSynthesisService` (new)
+
+**Location:** `backend/app/services/fact_synthesis_service.py`
+
+**Purpose:** Converts question answers and diagnostic check results into candidate facts. Called by `unified_chat_service`'s marker parser when the LLM emits a `[PROMOTE]` marker, and by explicit engineer action.
+
+**Key methods:**
+- `synthesize_from_question(question_ref: 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_ref: 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, increments `ai_sessions.state_version`.
+
+**Prompt engineering note:** The synthesis prompt must be conservative. Hallucinated specifics are a trust-killer and would be particularly damaging because facts feed into the resolution note that gets posted to customer tickets. 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:** `backend/app/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 an existing Script Generator pattern).
+
+**Caching:** keyed by `(session_id, ai_sessions.state_version)` per Section 5.5. Debounced client-side at 500ms.
+
+### 6.3 `EscalationPackageGeneratorService` (new)
+
+**Location:** `backend/app/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}
+```
+
+Same caching and invalidation model.
+
+### 6.4 `TemplateExtractionService` (new)
+
+**Location:** `backend/app/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 using the existing PSA provider registry and `post_note` seam:
+- `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 by re-fetching** the status after the transition attempt. Failed verification is surfaced as an error, not silent success (per the existing ConnectWise integration principle).
+
+### 6.6 Model and capability selection per service
+
+Each AI-calling service must use configurable model and MCP strings from application settings, not hardcoded values. Use these defaults:
+
+```python
+# Model tier per service
+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
+
+# MCP availability per service (true = this service can use MCP tools when available)
+FACT_SYNTHESIS_MCP_ENABLED       = False  # fast transformation, no external lookup needed
+RESOLUTION_NOTE_MCP_ENABLED      = False  # summarizing existing state, not researching
+ESCALATION_PACKAGE_MCP_ENABLED   = False  # same
+TEMPLATE_EXTRACTION_MCP_ENABLED  = False  # purely transforms an existing script
+MAIN_CONVERSATION_MCP_ENABLED    = True   # interactive troubleshooting, grounding matters
+SCRIPT_GENERATOR_MCP_ENABLED     = True   # Microsoft Learn for documentation grounding
+```
+
+Do not hardcode model or MCP strings at call sites. Every new service reads from settings with a service-specific key.
+
+**Instrumentation:** 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` | Move existing `AssistantChatPage` to `/pilot`. |
+| `/assistant/:sessionId` | `/pilot/:sessionId` | Session-deep-links must redirect with the session ID preserved. |
+| `/assistant` (bare) | → `/pilot` | **Permanent** 301 redirect. No sunset date. |
+| `/assistant/:sessionId` (deep) | → `/pilot/:sessionId` | **Permanent** 301 redirect. |
+
+Sidebar nav entry renames from "ResolutionAssist" to "FlowPilot" with the cockpit icon. Command palette entries, dashboard cards, and session list links that previously pointed to `/assistant` all update to `/pilot`.
+
+### 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/refactored from current location)
+    DiagnosticChecks.tsx      -- Existing checks rendering (moved/refactored from current location)
+    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
+```
+
+Existing component folders (e.g., `src/components/assistant/`) may be renamed opportunistically, but behavior and route migration matter more than directory-name purity.
+
+### 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
+- Edit affordance: only shown when `fact.source_type` is `user_note` or `ai_synthesis`. Question/check facts are read-only at the card level (edit the source question/check instead).
+- Delete affordance: shown for all facts (soft-delete via DELETE endpoint)
+
+**`TaskLane`**
+- Subscribes to a session state hook that polls for fact / question / check / suggested-fix updates
+- On any state change (state_version increment), calls `POST /api/v1/ai-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/ai-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 AND `account_settings.preferences.templatize_prompt_enabled` is not `false`
+- 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. Parser lives in `unified_chat_service` alongside the existing `[QUESTIONS]` / `[DIAGNOSTIC_CHECKS]` parsing — do not create a separate marker pipeline.
+
+### 8.1 New marker: `[PROMOTE]`
+
+Used to surface facts to What we know. Syntax:
+
+```
+[PROMOTE]
+source_type: question
+source_ref: {task_lane_item_uuid}
+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. `source_ref` points to the stable UUID of the task lane item being promoted (assigned in Phase 2).
+
+### 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]
+```
+
+Emitting a new `[SUGGEST_FIX]` supersedes any existing active fix for the session (sets `superseded_at` on the old row).
+
+### 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 (or, for Phase 0, the verification step is explicitly deferred to the new dev environment with a tracking TODO).
+
+### Phase 0 — Prompt caching infrastructure (prerequisite)
+
+A codebase audit revealed that prompt caching was 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` — was 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 — Cached system-block support in `AnthropicProvider`.** Convert `AnthropicProvider.generate_json()` and `generate_text_stream()` signatures to accept `system_prompt: str | list[SystemBlock]`. Plain string = uncached (backward compatible). List = cached using **policy α**: if the caller marks `cache_control` on any block, honor those markers; if no block has `cache_control`, cache the first block only by default. For streaming, capture the final usage object via `get_final_message()`. Log `cache_read_input_tokens` and `cache_creation_input_tokens` on every response.
+
+- **0.2 — Pending target endpoint.** The `/tickets/ai-parse` endpoint described in the original migration doc does not exist in the codebase. No code change in Phase 0. 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 — Opt-in caching for one-shot generators.** Add `cache_control` to the static system prompt in `ai_tree_generator_service`, `kb_conversion_service`, `ai_fix_service`, and `script_builder_service`. Pattern: single-block list with policy α auto-caching the first (and only) block. Per-block inline comment explaining cacheability. For `script_builder` (multi-turn): cache only the system prompt; conversation history stays uncached in this phase. Retries in `ai_tree_generator.generate_branch_detail` inherit the cache automatically — no special handling.
+
+- **0.4 — Consolidate the MCP-capable chat path.** Rename `_call_anthropic_cached` to `chat_call_cached()` in `assistant_chat_service` (or move to a shared module; implementer's choice based on cleanest structure). Refactor it to delegate cached-system-block plumbing to `AnthropicProvider`. MCP + image + beta-endpoint logic stays inside the chat wrapper — do NOT push MCP into `AnthropicProvider`, which is a provider-agnostic abstraction (Gemini has no MCP). Document that this wrapper is the one MCP-using caller, the exception not the rule. Track MCP unification as a separate future ticket.
+
+- **0.5 — MCP telemetry.** Add counters for: (a) turns where MCP was available, (b) turns where the model actually invoked an MCP tool, (c) turns where the silent-retry-without-MCP fallback was triggered, (d) which MCP tool names got called. Log to whatever telemetry path exists (PostHog if wired up, otherwise structured logs). This gives us real data by the time Phase 2+ decisions about MCP investment are made. **Do 0.5 first or alongside 0.1 — don't save it for last.**
+
+**Per-call-site comment pattern for multi-block lists:**
+
+When a call site passes more than one block to `system_prompt`, add a one-line comment next to EACH block — including uncached ones — explaining why it is or isn't cached. The absence of a marker deserves documentation as much as the presence of one, because it tells the next dev you made a conscious choice.
+
+**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.
+
+**Verification is deferred to the new dev environment.** Phase 0 code commits without live verification because no running environment exists at authoring time. A `TODO(phase-0-verification)` inline comment in the caching module names the verification steps. Execute verification when the new env is up; if it fails, that is a debug task then, not a blocker now.
+
+```
+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 verification has passed (or been explicitly deferred with a tracked issue).
+
+### Phase 1 — Data model and route rename (can run in parallel with Phase 0)
+
+**Deliverables:**
+
+- Alembic migration after current repo head creating: `session_facts`, `session_suggested_fixes`, `draft_templates`, `account_settings`; column additions to `ai_sessions` (including `state_version`), `script_templates`.
+- All new tenant-scoped tables have `account_id` and RLS policies using the repo's `app.current_account_id` policy pattern.
+- SQLAlchemy models for each new table. `AccountSettings` model includes `get_setting(key, default)` and `set_setting(key, value)` helpers; lazy row creation on first write.
+- Route move: `AssistantChatPage` component mounted at `/pilot` and `/pilot/:sessionId`.
+- Permanent 301 redirect: `/assistant` → `/pilot`, `/assistant/:sessionId` → `/pilot/:sessionId` (preserving session ID).
+- Sidebar nav entry renames from "ResolutionAssist" / "AI Assistant" to "FlowPilot". Command palette entries, dashboard cards, and session list links update to `/pilot`.
+- No Phase 2 UI changes yet (no task lane restructuring, no What we know section).
+
+**Verification:**
+
+- Run migration on a fresh dev database — succeeds.
+- Downgrade migration succeeds (reversibility).
+- RLS grep/check passes for new tables.
+- `/assistant` redirects to `/pilot` (301).
+- `/assistant/:sessionId` redirects to `/pilot/:sessionId` with ID preserved.
+- `/pilot` renders the existing chat UI with the sidebar now reading "FlowPilot".
+- No Phase 2 UI introduced.
+
+```
+git commit -m "feat(pilot): rename /assistant to /pilot, add session_facts/suggested_fixes/draft_templates/account_settings schema"
+```
+
+### Phase 2 — What we know (task lane + service + API)
+
+**Deliverables:**
+
+- Stable-UUID assignment for `pending_task_lane` items. When questions/checks are persisted (or when a legacy session is loaded), each item receives a UUID written back into the JSON. This is a prerequisite for `session_facts.source_ref` to point anywhere reliable. Handle in-flight sessions gracefully — sessions open during deploy may have unstable IDs until their next save.
+- `FactSynthesisService` per Section 6.1, with its LLM prompt.
+- Fact CRUD API endpoints per Section 5.1.
+- `WhatWeKnow`, `WhatWeKnowItem`, `AddNoteButton`, `TaskLane` components under `src/components/pilot/`.
+- Task lane layout adjustment: What we know section renders above Questions.
+- Counter in task lane header updates to `X / Y answered` format.
+- AI system prompt updated to emit `[PROMOTE]` markers; `unified_chat_service` marker parser extended to handle them.
+- Fact editability enforcement: API returns 403 on PATCH of `question` or `diagnostic_check`-sourced facts. UI hides the edit affordance for those facts.
+
+**Verification:**
+
+- Open a session, answer a question; within 2 seconds a fact appears in What we know with correct provenance.
+- Click "+ Add a note", type a manual fact, confirm it persists 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.
+- Attempt to PATCH a question-sourced fact → 403.
+- PATCH a user_note fact → succeeds.
+
+```
+git commit -m "feat(pilot): add What we know section with fact synthesis and stable task-lane item IDs"
+```
+
+### Phase 3 — Suggested fix + resolution note preview
+
+**Deliverables:**
+
+- `session_suggested_fixes` API endpoints per Section 5.2 and data flow.
+- `SuggestedFix` component in the task lane.
+- AI system prompt updated to emit `[SUGGEST_FIX]` markers; parser handles supersession.
+- `ResolutionNoteGeneratorService` per Section 6.2 and preview endpoint per Section 5.4.
+- `ResolutionNotePreview` floating popover anchored to Resolve button.
+- Preview refreshes on fact / suggested-fix / script-generation changes via `state_version` increment. Client-side 500ms debounce.
+- Preview cache keyed by `(session_id, state_version)` per Section 5.5.
+
+**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).
+- Incrementing `state_version` invalidates the preview cache; reading the same version returns the cached markdown.
+
+```
+git commit -m "feat(pilot): add suggested fix tracking and Resolve note preview with state_version caching"
+```
+
+### Phase 4 — Resolve and Escalate PSA writebacks
+
+**Deliverables:**
+
+- `transition_ticket_status` method on `PSAWritebackService` with CW re-fetch verification.
+- `post_resolution_note` endpoint and CW integration via existing PSA provider registry + `post_note` seam.
+- Resolve button flow: engineer edits preview → Confirm & post → server posts to PSA → stores `{external_id, posted_at}` → transitions status → verifies status → marks session resolved → shows templatize prompt if applicable.
+- `EscalationPackageGeneratorService` and parallel flow for Escalate, including CW routing rules.
+- Local-only path: resolving or escalating a session with no linked PSA ticket stores markdown locally and marks the session state without external posting.
+
+**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 (verified by re-fetch).
+- Click Escalate on a different session — verify the package is posted and the ticket routes correctly.
+- Simulate CW silently rejecting a status change — verify the app surfaces an error, not silent success.
+- Attempt to Resolve without a linked PSA ticket — session marks resolved locally without erroring; markdown stored in `resolution_note_markdown`.
+
+```
+git commit -m "feat(pilot): wire Resolve and Escalate to ConnectWise writeback with status verification"
+```
+
+### Phase 5 — Script Generator inline integration
+
+**Deliverables:**
+
+- `ScriptGenInline/TemplateMatchPanel` — when suggested fix has `script_template_id`, clicking the fix opens this panel with parameters pre-filled 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 (Section 6.4).
+- Script generation flow produces a `script_generations` record linked to the session via existing `script_generations.ai_session_id`; increments `state_version`.
+- `⌘K → "script"` opens the inline generator from the FlowPilot session. **No Resolve keyboard shortcut** is added (browsers intercept `⌘R`; decided against alternatives).
+- Script Generator inherits MCP access for Microsoft Learn lookups via the `chat_call_cached` wrapper (Phase 0.4), not via `AnthropicProvider` directly.
+
+**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_template creates `draft_templates` row and generates, build_template opens full template creation.
+- `⌘K → "script"` anywhere in a session opens the generator directly.
+- Edge case: if the suggested fix's `script_template_id` points at a template that has been deleted, show the no-template three-option dialog with the AI-drafted script (do not error).
+
+```
+git commit -m "feat(pilot): integrate Script Generator inline with suggested fixes"
+```
+
+### Phase 6 — Post-resolve templatize prompt
+
+**Deliverables:**
+
+- `TemplatizePrompt` component.
+- Show logic: after successful Resolve, show only when ALL of:
+  1. `account_settings.preferences.templatize_prompt_enabled` is not `false` (default `true` when absent)
+  2. Session has pending `draft_templates` rows
+  3. The user chose `draft_template` on the original three-option dialog
+- Accept flow creates a new `script_templates` row with `source_session_id`, `source_user_id`, `source_ticket_ref` set. Updates draft to `status='accepted'`, `promoted_template_id` set.
+- Reject flow updates draft to `status='rejected'`.
+- "Don't ask me again for this team" writes `{"templatize_prompt_enabled": false}` to `account_settings.preferences`.
+- Script Library sidebar shows a pending-drafts badge/count for the account.
+
+**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.
+- 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 HTML source files (spacing, colors, typography, component structure). Use PNGs for visual target confirmation.
+- Loading states for: fact synthesis, preview generation, template extraction, PSA post/verify, script generation.
+- Empty states: no facts yet, no questions, no checks, no active suggested fix, no pending draft templates.
+- Keyboard shortcuts (no Resolve shortcut): `⌘K` (command palette), `⌘↵` (send composer), `⌘G` (script generator).
+- Responsive: at widths below 1200px, task lane collapses into a bottom drawer.
+- Use existing design tokens where present; add missing tokens only if needed to match the mockups.
+
+**Verification:**
+
+- Major screens visually compare within tolerance against the mockup PNG files.
+- No horizontal scroll at 1280px viewport.
+- Keyboard shortcuts documented in-app via `?` overlay.
+- Shortcuts do not conflict with browser reload.
+
+```
+git commit -m "feat(pilot): visual polish, empty/loading states, keyboard shortcuts"
+```
+
+---
+
+## 10. Design system reference
+
+All components must use the existing ResolutionFlow design system. 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 recorded design decision to migrate off Lucide.
+
+---
+
+## 11. Test plan
+
+### Migration tests
+- Fresh DB upgrade succeeds.
+- Downgrade succeeds (reversibility).
+- New tables have RLS enabled/forced.
+- Tenant policy includes `app.current_account_id`.
+
+### Backend tests
+- Fact CRUD authorization (edit allowed on `user_note` / `ai_synthesis`, 403 on `question` / `diagnostic_check`).
+- Fact promotion: `POST /facts/promote` creates fact and increments `state_version`.
+- Suggested-fix supersession: emitting a new `[SUGGEST_FIX]` sets `superseded_at` on the prior active one.
+- Decision persistence on `session_suggested_fixes.user_decision`.
+- Resolution note preview cache invalidation on `state_version` increment.
+- Resolve/Escalate local-only behavior without a linked PSA ticket.
+- PSA status verification failure path (simulated rejection surfaces error).
+- Draft-template accept/reject behavior.
+- `AccountSettings.get_setting` returns default when row absent.
+
+### Frontend tests
+- Route redirects (`/assistant` → `/pilot`, deep-link ID preservation).
+- Task lane rendering and persistence across reloads.
+- Inline fact editing refreshes the Resolve preview.
+- Script Generator option flows (template match, three-option dialog, post-resolve prompt).
+- Templatize prompt respects `templatize_prompt_enabled` setting.
+- Responsive drawer behavior at <1200px.
+
+### Manual QA
+- Run one ConnectWise-linked Resolve end-to-end.
+- Run one Escalate end-to-end.
+- Run one template-match script generation path.
+- Run one no-template draft-template path through post-resolve save.
+
+---
+
+## 12. 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).** Explicitly removed. 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.
+- **Backfill of What we know for pre-Phase-2 sessions.** Sessions resolved before Phase 2 ships will not retroactively gain facts. Document in release notes.
+- **MCP unification into `AnthropicProvider`.** Deferred pending telemetry-driven evaluation. Track as a separate ticket.
+- **Supervisor staging of resolution notes.** Engineer review + Confirm & post is the committed flow (not compliance-grade draft approval).
+
+---
+
+## 13. 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. Haiku default + `disputed_fact_rate` telemetry triggers escalation to Sonnet if quality drops. |
+| Resolution note preview LLM cost at scale | `state_version`-keyed cache prevents re-generation on unchanged state; 500ms client debounce batches rapid edits. |
+| ConnectWise silently rejects status change | `transition_ticket_status` re-fetches and verifies; fails 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 301 redirect (no sunset date); deep-link session IDs preserved through the redirect. |
+| Existing sessions have no facts at Phase 2 deploy | Acceptable per non-goals. Facts accumulate for new or ongoing sessions after deploy. Document in release notes. |
+| In-flight sessions during Phase 2 deploy lack stable task-lane item IDs | Sessions open at deploy time may have unstable IDs until the next save cycle re-persists with UUIDs. Facts tied to those sessions may reference IDs that don't resolve. Engineer can manually re-promote if needed. |
+| Phase 0 cache verification deferred to new env | Tracked via inline TODO in the caching module. If verification fails when executed, debug as a normal bug — do not retroactively block dependent phases. |
+| MCP usage data unknown, may under- or over-invest | Phase 0.5 telemetry answers this within 30 days of new env being live. Schedule "MCP review" checkpoint at that mark. |
+
+---
+
+## 14. Decisions made during migration planning
+
+These questions were raised during the planning conversation and have been resolved. Captured here so the decisions are traceable.
+
+1. **Keyboard shortcut for Resolve** — **Decided: no shortcut.** `⌘R` conflicts with browser reload; alternatives add complexity without clear value. Resolve has a button, a preview, and a confirm step. No shortcut needed.
+2. **Default for `templatize_prompt_enabled`** — **Decided: true.** Feature discovery outweighs annoyance at pre-revenue stage. Opt-out is one click and persistent. Tune surfacing logic rather than the default if feedback indicates over-prompting.
+3. **Resolution note posting** — **Decided: engineer edits inline, clicks Confirm & post.** Supervisor staging is out of scope for this migration. Revisit if an MSP with strict compliance requirements surfaces the need.
+4. **Fact synthesis model tier** — **Decided: Haiku 4.5 behind a `FACT_SYNTHESIS_MODEL` config flag.** All other AI services default to Sonnet 4.6. Opus 4.7 not used at current scale. Per-service MCP capability configured via matching flags (Section 6.6).
+5. **MCP architecture in Phase 0** — **Decided: leave MCP in the chat wrapper.** Option C from the Phase 0 audit. Do not push MCP into the provider-agnostic `AnthropicProvider`. Add telemetry in Phase 0.5 to gather data for a future unification decision.
+6. **Cache breakpoint policy** — **Decided: policy α.** Caller-marked `cache_control` is honored; if no blocks are marked, the first block is cached by default.
+7. **API namespace** — **Decided: `/api/v1/ai-sessions/{id}/...`**, matching the existing codebase.
+8. **`account_settings` structure** — **Decided: new table with JSONB `preferences` column, lazy row creation.** Simple settings live in `preferences`; settings graduate to typed columns when they meet the promotion criteria (hot path / validation / joins).
+
+---
+
+## End of document

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/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",

frontend/package.json

@@ -36,6 +36,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",

frontend/src/api/client.ts

@@ -49,9 +49,9 @@ function handleGlobalError(error: AxiosError) {
     return
   }
 
-  // Server errors (5xx)
+  // Server errors (5xx) — show backend detail when available, else generic message
   if (status >= 500) {
-    toast.error('Server error - please try again later')
+    toast.error(detail || 'Server error - please try again later')
     return
   }
 }

frontend/src/api/deviceTypes.ts

@@ -0,0 +1,23 @@
+import apiClient from './client'
+import type { DeviceTypeResponse, DeviceTypeCreate } from '@/types'
+
+export const deviceTypesApi = {
+  async list(): Promise<DeviceTypeResponse[]> {
+    const response = await apiClient.get<DeviceTypeResponse[]>('/device-types/')
+    return response.data
+  },
+
+  async create(data: DeviceTypeCreate): Promise<DeviceTypeResponse> {
+    const response = await apiClient.post<DeviceTypeResponse>('/device-types/', data)
+    return response.data
+  },
+
+  async update(id: string, data: Partial<DeviceTypeCreate>): Promise<DeviceTypeResponse> {
+    const response = await apiClient.put<DeviceTypeResponse>(`/device-types/${id}`, data)
+    return response.data
+  },
+
+  async remove(id: string): Promise<void> {
+    await apiClient.delete(`/device-types/${id}`)
+  },
+}

frontend/src/api/index.ts

@@ -35,3 +35,5 @@ export { betaFeedbackApi } from './betaFeedback'
 export { branchesApi } from './branches'
 export { handoffsApi } from './handoffs'
 export { resolutionsApi } from './resolutions'
+export { deviceTypesApi } from './deviceTypes'
+export { networkDiagramsApi } from './networkDiagrams'

frontend/src/api/integrations.ts

@@ -1,6 +1,6 @@
 import { apiClient } from './client'
 import type { PsaConnectionResponse, PsaConnectionCreate, PsaConnectionUpdate, PsaConnectionTestResponse } from '@/types'
-import type { TicketLinkResponse, PSATicketSearchResult, PSATicketInfo, PSATicketStatusItem, PsaPreviewResponse, PsaPostResponse, PsaPostLogEntry, PsaMemberResponse, PsaMemberMappingResponse, AutoMatchResult, FlowpilotSettings } from '@/types/integrations'
+import type { PSABoard, TicketLinkResponse, PSATicketSearchResult, PSATicketInfo, PSATicketStatusItem, PsaPreviewResponse, PsaPostResponse, PsaPostLogEntry, PsaMemberResponse, PsaMemberMappingResponse, AutoMatchResult, FlowpilotSettings } from '@/types/integrations'
 
 export const integrationsApi = {
   getConnection: () =>
@@ -13,8 +13,18 @@ export const integrationsApi = {
     apiClient.delete(`/integrations/psa/connections/${id}`),
   testConnection: (id: string) =>
     apiClient.post<PsaConnectionTestResponse>(`/integrations/psa/connections/${id}/test`).then(r => r.data),
+  listBoards: () =>
+    apiClient.get<PSABoard[]>('/integrations/psa/boards').then(r => r.data),
   searchTickets: (params: { query?: string; board_id?: number; include_closed?: boolean }) =>
     apiClient.get<PSATicketSearchResult[]>('/integrations/psa/tickets/search', { params }).then(r => r.data),
+  searchTicketsQueue: (params: {
+    assigned_to_me?: boolean
+    unassigned?: boolean
+    board_ids?: string
+    page?: number
+    page_size?: number
+  }) =>
+    apiClient.get<PSATicketSearchResult[]>('/integrations/psa/tickets/search', { params }).then(r => r.data),
   getTicket: (id: string) =>
     apiClient.get<PSATicketInfo>(`/integrations/psa/tickets/${id}`).then(r => r.data),
   getTicketStatuses: (ticketId: string) =>

frontend/src/api/networkDiagrams.ts

@@ -0,0 +1,67 @@
+import apiClient from './client'
+import type {
+  NetworkDiagramResponse,
+  NetworkDiagramListItem,
+  NetworkDiagramCreate,
+  NetworkDiagramUpdate,
+  AIGenerateRequest,
+  AIGenerateResponse,
+  DiagramImportData,
+  DiagramImportResponse,
+  DiagramExportResponse,
+} from '@/types'
+
+export const networkDiagramsApi = {
+  async list(params?: { client_name?: string; search?: string }): Promise<NetworkDiagramListItem[]> {
+    const response = await apiClient.get<NetworkDiagramListItem[]>('/network-diagrams/', { params })
+    return response.data
+  },
+
+  async get(id: string): Promise<NetworkDiagramResponse> {
+    const response = await apiClient.get<NetworkDiagramResponse>(`/network-diagrams/${id}`)
+    return response.data
+  },
+
+  async create(data: NetworkDiagramCreate): Promise<NetworkDiagramResponse> {
+    const response = await apiClient.post<NetworkDiagramResponse>('/network-diagrams/', data)
+    return response.data
+  },
+
+  async update(id: string, data: NetworkDiagramUpdate): Promise<NetworkDiagramResponse> {
+    const response = await apiClient.put<NetworkDiagramResponse>(`/network-diagrams/${id}`, data)
+    return response.data
+  },
+
+  async archive(id: string): Promise<void> {
+    await apiClient.delete(`/network-diagrams/${id}`)
+  },
+
+  async duplicate(id: string): Promise<NetworkDiagramResponse> {
+    const response = await apiClient.post<NetworkDiagramResponse>(`/network-diagrams/${id}/duplicate`)
+    return response.data
+  },
+
+  async exportJson(id: string): Promise<DiagramExportResponse> {
+    const response = await apiClient.get<DiagramExportResponse>(`/network-diagrams/${id}/export`)
+    return response.data
+  },
+
+  async importJson(data: DiagramImportData): Promise<DiagramImportResponse> {
+    const response = await apiClient.post<DiagramImportResponse>('/network-diagrams/import', data)
+    return response.data
+  },
+
+  async uploadThumbnail(id: string, dataUrl: string): Promise<void> {
+    await apiClient.post(`/network-diagrams/${id}/thumbnail`, { data_url: dataUrl })
+  },
+
+  async aiGenerate(data: AIGenerateRequest): Promise<AIGenerateResponse> {
+    const response = await apiClient.post<AIGenerateResponse>('/network-diagrams/ai-generate', data)
+    return response.data
+  },
+
+  async listClients(): Promise<string[]> {
+    const response = await apiClient.get<string[]>('/network-diagrams/clients')
+    return response.data
+  },
+}

frontend/src/components/dashboard/ActiveFlowPilotSessions.tsx

@@ -48,7 +48,7 @@ export function ActiveFlowPilotSessions({ hideHeader = false }: { hideHeader?: b
           {sessions.map((session) => (
             <button
               key={session.id}
-              onClick={() => navigate(session.session_type === 'chat' ? `/assistant/${session.id}` : `/pilot/${session.id}`)}
+              onClick={() => navigate(`/pilot/${session.id}`)}
               className="card-interactive p-4 text-left"
             >
               <div className="flex items-start justify-between gap-2 mb-2">

frontend/src/components/dashboard/RecentFlowPilotSessions.tsx

@@ -52,7 +52,7 @@ export function RecentFlowPilotSessions({ hideHeader = false }: { hideHeader?: b
           return (
             <button
               key={session.id}
-              onClick={() => navigate(session.session_type === 'chat' ? `/assistant/${session.id}` : `/pilot/${session.id}`)}
+              onClick={() => navigate(`/pilot/${session.id}`)}
               className="flex w-full items-center gap-3 px-5 py-3 text-left hover:bg-[rgba(255,255,255,0.02)] transition-colors"
               style={{
                 borderBottom: i < sessions.length - 1 ? '1px solid var(--color-border-default)' : undefined,

frontend/src/components/dashboard/StartSessionInput.tsx

@@ -52,7 +52,7 @@ export function StartSessionInput() {
     if (completedUploadIds.length > 0) {
       state.uploadIds = completedUploadIds
     }
-    navigate('/assistant', { state })
+    navigate('/pilot', { state })
   }
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -63,7 +63,7 @@ export function StartSessionInput() {
   }
 
   const handleSuggestionClick = (suggestion: string) => {
-    navigate('/assistant', { state: { prefill: suggestion } })
+    navigate('/pilot', { state: { prefill: suggestion } })
   }
 
   // ── File handling ──────────────────────────────

frontend/src/components/dashboard/TicketQueue.tsx

@@ -0,0 +1,397 @@
+import { useState, useEffect, useRef, useCallback } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { Ticket, ChevronDown, Check, Loader2, AlertCircle } from 'lucide-react'
+import { integrationsApi } from '@/api/integrations'
+import type { PSABoard, PSATicketSearchResult } from '@/types/integrations'
+import { cn } from '@/lib/utils'
+
+const PAGE_SIZE = 10
+
+type Tab = 'mine' | 'unassigned'
+
+function SkeletonRows() {
+  return (
+    <div className="space-y-0">
+      {[0, 1, 2].map((i) => (
+        <div
+          key={i}
+          className="flex items-center gap-4 px-5 py-3.5"
+          style={{ borderBottom: '1px solid var(--color-border-default)' }}
+        >
+          <div className="flex-1 space-y-2">
+            <div className="h-3 w-1/3 rounded bg-[rgba(255,255,255,0.06)] animate-pulse" />
+            <div className="h-3 w-2/3 rounded bg-[rgba(255,255,255,0.04)] animate-pulse" />
+            <div className="h-2.5 w-1/4 rounded bg-[rgba(255,255,255,0.03)] animate-pulse" />
+          </div>
+          <div className="h-6 w-16 rounded bg-[rgba(255,255,255,0.04)] animate-pulse shrink-0" />
+          <div className="h-7 w-24 rounded bg-[rgba(255,255,255,0.04)] animate-pulse shrink-0" />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+interface BoardSelectorProps {
+  boards: PSABoard[]
+  selectedIds: number[]
+  onChange: (ids: number[]) => void
+}
+
+function BoardSelector({ boards, selectedIds, onChange }: BoardSelectorProps) {
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false)
+      }
+    }
+    if (open) {
+      document.addEventListener('mousedown', handleClickOutside)
+    }
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [open])
+
+  const allSelected = selectedIds.length === 0
+  const label = allSelected
+    ? 'All Boards'
+    : selectedIds.length === 1
+    ? (boards.find((b) => b.id === selectedIds[0])?.name ?? '1 board')
+    : `${selectedIds.length} boards`
+
+  const handleAllBoards = () => {
+    onChange([])
+  }
+
+  const handleToggleBoard = (id: number) => {
+    if (selectedIds.includes(id)) {
+      const next = selectedIds.filter((x) => x !== id)
+      onChange(next)
+    } else {
+      onChange([...selectedIds, id])
+    }
+  }
+
+  if (boards.length === 0) return null
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        onClick={() => setOpen((v) => !v)}
+        className="flex items-center gap-1.5 rounded-lg border border-[rgba(255,255,255,0.08)] bg-[rgba(255,255,255,0.04)] px-3 py-1.5 text-xs text-muted-foreground hover:text-foreground hover:border-[rgba(255,255,255,0.14)] transition-colors"
+      >
+        {label}
+        <ChevronDown size={12} className={cn('transition-transform', open && 'rotate-180')} />
+      </button>
+
+      {open && (
+        <div className="absolute right-0 top-full mt-1 z-50 w-52 rounded-lg border border-[rgba(255,255,255,0.1)] bg-card shadow-lg py-1">
+          {/* All Boards */}
+          <button
+            onClick={handleAllBoards}
+            className="flex w-full items-center gap-2.5 px-3 py-2 text-xs text-foreground hover:bg-[rgba(255,255,255,0.06)] transition-colors"
+          >
+            <span
+              className={cn(
+                'flex h-3.5 w-3.5 shrink-0 items-center justify-center rounded border',
+                allSelected
+                  ? 'border-accent bg-accent'
+                  : 'border-[rgba(255,255,255,0.2)] bg-transparent',
+              )}
+            >
+              {allSelected && <Check size={9} className="text-white" />}
+            </span>
+            All Boards
+          </button>
+
+          {boards.length > 0 && (
+            <div className="my-1" style={{ borderTop: '1px solid var(--color-border-default)' }} />
+          )}
+
+          {boards.map((board) => {
+            const checked = selectedIds.includes(board.id)
+            return (
+              <button
+                key={board.id}
+                onClick={() => handleToggleBoard(board.id)}
+                className="flex w-full items-center gap-2.5 px-3 py-2 text-xs text-foreground hover:bg-[rgba(255,255,255,0.06)] transition-colors"
+              >
+                <span
+                  className={cn(
+                    'flex h-3.5 w-3.5 shrink-0 items-center justify-center rounded border',
+                    checked
+                      ? 'border-accent bg-accent'
+                      : 'border-[rgba(255,255,255,0.2)] bg-transparent',
+                  )}
+                >
+                  {checked && <Check size={9} className="text-white" />}
+                </span>
+                <span className="truncate">{board.name}</span>
+              </button>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+interface TicketRowProps {
+  ticket: PSATicketSearchResult
+  isLast: boolean
+  onStartSession: (ticket: PSATicketSearchResult) => void
+}
+
+function TicketRow({ ticket, isLast, onStartSession }: TicketRowProps) {
+  return (
+    <div
+      className="flex items-center gap-3 px-5 py-3.5"
+      style={{ borderBottom: isLast ? undefined : '1px solid var(--color-border-default)' }}
+    >
+      {/* Left: ticket info */}
+      <div className="flex-1 min-w-0">
+        <div className="flex items-baseline gap-2 mb-0.5">
+          <span className="font-mono text-xs font-semibold text-accent shrink-0">
+            #{ticket.id}
+          </span>
+          <span className="text-sm text-foreground truncate">{ticket.summary}</span>
+        </div>
+        <div className="flex items-center gap-1.5 text-[0.6875rem] text-muted-foreground">
+          {ticket.company_name && <span className="truncate">{ticket.company_name}</span>}
+          {ticket.company_name && ticket.priority_name && (
+            <span className="shrink-0">&middot;</span>
+          )}
+          {ticket.priority_name && <span className="shrink-0">{ticket.priority_name}</span>}
+        </div>
+      </div>
+
+      {/* Right: status badge + action */}
+      <div className="flex items-center gap-2 shrink-0">
+        {ticket.status_name && (
+          <span className="hidden sm:inline-flex items-center rounded-md border border-[rgba(255,255,255,0.08)] bg-[rgba(255,255,255,0.04)] px-2 py-0.5 text-[0.625rem] text-muted-foreground">
+            {ticket.status_name}
+          </span>
+        )}
+        <button
+          onClick={() => onStartSession(ticket)}
+          className="flex items-center gap-1.5 rounded-lg border border-accent/30 bg-accent-dim px-3 py-1.5 text-xs font-medium text-accent hover:bg-accent/20 hover:border-accent/50 transition-colors"
+        >
+          <Ticket size={11} />
+          Start Session
+        </button>
+      </div>
+    </div>
+  )
+}
+
+export function TicketQueue() {
+  const navigate = useNavigate()
+  const [hasConnection, setHasConnection] = useState<boolean | null>(null)
+  const [boards, setBoards] = useState<PSABoard[]>([])
+  const [selectedBoardIds, setSelectedBoardIds] = useState<number[]>([])
+  const [activeTab, setActiveTab] = useState<Tab>('mine')
+  const [tickets, setTickets] = useState<PSATicketSearchResult[]>([])
+  const [page, setPage] = useState(1)
+  const [hasMore, setHasMore] = useState(false)
+  const [loading, setLoading] = useState(false)
+  const [loadingMore, setLoadingMore] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  // Check connection on mount
+  useEffect(() => {
+    integrationsApi.getConnection()
+      .then((conn) => {
+        const active = !!(conn && conn.is_active)
+        setHasConnection(active)
+      })
+      .catch(() => setHasConnection(false))
+  }, [])
+
+  // Fetch boards once connection confirmed
+  useEffect(() => {
+    if (!hasConnection) return
+    integrationsApi.listBoards()
+      .then(setBoards)
+      .catch(() => {}) // boards are optional — don't block UI
+  }, [hasConnection])
+
+  const fetchTickets = useCallback(
+    async (tab: Tab, boardIds: number[], pageNum: number, append: boolean) => {
+      const params: Parameters<typeof integrationsApi.searchTicketsQueue>[0] = {
+        page: pageNum,
+        page_size: PAGE_SIZE,
+      }
+      if (tab === 'mine') {
+        params.assigned_to_me = true
+      } else {
+        params.unassigned = true
+      }
+      if (boardIds.length > 0) {
+        params.board_ids = boardIds.join(',')
+      }
+
+      try {
+        const results = await integrationsApi.searchTicketsQueue(params)
+        if (append) {
+          setTickets((prev) => [...prev, ...results])
+        } else {
+          setTickets(results)
+        }
+        setHasMore(results.length === PAGE_SIZE)
+        setError(null)
+      } catch {
+        setError('Failed to load tickets. Check your PSA connection.')
+      }
+    },
+    [],
+  )
+
+  // Initial + reset fetch when tab or board selection changes
+  useEffect(() => {
+    if (!hasConnection) return
+    setPage(1)
+    setTickets([])
+    setHasMore(false)
+    setLoading(true)
+    fetchTickets(activeTab, selectedBoardIds, 1, false).finally(() => setLoading(false))
+  }, [activeTab, selectedBoardIds, hasConnection, fetchTickets])
+
+  const handleLoadMore = async () => {
+    const nextPage = page + 1
+    setPage(nextPage)
+    setLoadingMore(true)
+    await fetchTickets(activeTab, selectedBoardIds, nextPage, true)
+    setLoadingMore(false)
+  }
+
+  const handleStartSession = (ticket: PSATicketSearchResult) => {
+    navigate('/pilot', {
+      state: {
+        psaTicketId: ticket.id,
+        psaTicket: {
+          id: ticket.id,
+          summary: ticket.summary,
+          company_name: ticket.company_name,
+          board_name: ticket.board_name,
+          status_name: ticket.status_name,
+          priority_name: ticket.priority_name,
+        },
+      },
+    })
+  }
+
+  // Don't render until we know connection status
+  if (hasConnection === null) return null
+  // No active connection → hide entirely
+  if (!hasConnection) return null
+
+  return (
+    <div className="card-flat overflow-hidden">
+      {/* Header */}
+      <div
+        className="flex items-center justify-between px-5 py-3"
+        style={{ borderBottom: '1px solid var(--color-border-default)' }}
+      >
+        <div className="flex items-center gap-2">
+          <Ticket size={14} className="text-accent" />
+          <h3 className="font-heading text-sm font-bold text-foreground">Ticket Queue</h3>
+        </div>
+        <BoardSelector
+          boards={boards}
+          selectedIds={selectedBoardIds}
+          onChange={(ids) => setSelectedBoardIds(ids)}
+        />
+      </div>
+
+      {/* Tabs */}
+      <div
+        className="flex"
+        style={{ borderBottom: '1px solid var(--color-border-default)' }}
+      >
+        {(['mine', 'unassigned'] as Tab[]).map((tab) => (
+          <button
+            key={tab}
+            onClick={() => setActiveTab(tab)}
+            className={cn(
+              'px-5 py-2.5 text-xs font-medium transition-colors border-b-2 -mb-px',
+              activeTab === tab
+                ? 'border-accent text-accent'
+                : 'border-transparent text-muted-foreground hover:text-foreground',
+            )}
+          >
+            {tab === 'mine' ? 'My Tickets' : 'Unassigned'}
+          </button>
+        ))}
+      </div>
+
+      {/* Content */}
+      <div>
+        {/* Error */}
+        {error && (
+          <div className="flex items-center gap-2 px-5 py-4 text-sm text-danger">
+            <AlertCircle size={14} className="shrink-0" />
+            <span>{error}</span>
+          </div>
+        )}
+
+        {/* Loading skeleton */}
+        {!error && loading && <SkeletonRows />}
+
+        {/* Ticket rows */}
+        {!error && !loading && tickets.length > 0 && (
+          <>
+            {tickets.map((ticket, i) => (
+              <TicketRow
+                key={ticket.id}
+                ticket={ticket}
+                isLast={i === tickets.length - 1 && !hasMore}
+                onStartSession={handleStartSession}
+              />
+            ))}
+          </>
+        )}
+
+        {/* Empty states */}
+        {!error && !loading && tickets.length === 0 && (
+          <div className="px-5 py-8 text-center">
+            <Ticket size={24} className="mx-auto mb-2 text-muted-foreground/40" />
+            {activeTab === 'mine' ? (
+              <>
+                <p className="text-sm text-muted-foreground">No open tickets assigned to you</p>
+                <p className="mt-1 text-[0.6875rem] text-muted-foreground/60">
+                  Make sure your member mapping is configured in Account &rarr; Integrations
+                </p>
+              </>
+            ) : (
+              <p className="text-sm text-muted-foreground">No unassigned open tickets</p>
+            )}
+          </div>
+        )}
+
+        {/* Load more */}
+        {!error && !loading && hasMore && (
+          <div
+            className="px-5 py-3"
+            style={{ borderTop: '1px solid var(--color-border-default)' }}
+          >
+            <button
+              onClick={handleLoadMore}
+              disabled={loadingMore}
+              className="flex w-full items-center justify-center gap-2 rounded-lg border border-[rgba(255,255,255,0.08)] bg-transparent py-2 text-xs text-muted-foreground hover:text-foreground hover:border-[rgba(255,255,255,0.14)] disabled:opacity-50 transition-colors"
+            >
+              {loadingMore ? (
+                <>
+                  <Loader2 size={12} className="animate-spin" />
+                  Loading...
+                </>
+              ) : (
+                'Load more'
+              )}
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/flowpilot/AISessionListItem.tsx

@@ -18,9 +18,12 @@ const STATUS_CONFIG = {
 export function AISessionListItem({ session }: AISessionListItemProps) {
   const config = STATUS_CONFIG[session.status as keyof typeof STATUS_CONFIG] ?? STATUS_CONFIG.active
   const StatusIcon = config.icon
+  // Both chat and guided sessions now land on the unified /pilot surface.
+  // session_type is preserved on the DB row for data compatibility but is
+  // no longer used for frontend route selection (Phase 1 FlowPilot migration).
   const isChat = session.session_type === 'chat'
   const TypeIcon = isChat ? MessageCircle : Route
-  const linkTo = isChat ? `/assistant/${session.id}` : `/pilot/${session.id}`
+  const linkTo = `/pilot/${session.id}`
   const displayTitle = isChat
     ? (session.title || session.problem_summary || 'Untitled chat')
     : (session.problem_summary || 'Untitled session')

frontend/src/components/layout/CommandPalette.tsx

@@ -42,7 +42,7 @@ const PAGES: PaletteItem[] = [
   { id: 'page-dashboard', group: 'pages', title: 'Dashboard', path: '/', icon: 'page' },
   { id: 'page-flows', group: 'pages', title: 'All Flows', subtitle: 'Browse your flow library', path: '/trees', icon: 'page' },
   { id: 'page-sessions', group: 'pages', title: 'Sessions', subtitle: 'View session history', path: '/sessions', icon: 'page' },
-  { id: 'page-assistant', group: 'pages', title: 'AI Assistant', subtitle: 'FlowPilot chat', path: '/assistant', icon: 'page' },
+  { id: 'page-flowpilot', group: 'pages', title: 'FlowPilot', subtitle: 'AI troubleshooting', path: '/pilot', icon: 'page' },
   { id: 'page-scripts', group: 'pages', title: 'Script Generator', subtitle: 'Generate PowerShell scripts', path: '/scripts', icon: 'page' },
   { id: 'page-analytics', group: 'pages', title: 'Analytics', subtitle: 'Team usage & metrics', path: '/analytics', icon: 'page' },
   { id: 'page-settings', group: 'pages', title: 'Settings', subtitle: 'Account & preferences', path: '/account', icon: 'page' },
@@ -177,7 +177,7 @@ export function CommandPalette({ open, onClose }: CommandPaletteProps) {
       group: 'flowpilot',
       title: 'Troubleshoot with FlowPilot',
       subtitle: trimmed,
-      path: '/assistant',
+      path: '/pilot',
       icon: 'sparkles',
     }
 

frontend/src/components/layout/Sidebar.tsx

@@ -5,7 +5,7 @@ import {
   LayoutGrid, Clock, AlertTriangle, GitBranch, Code2, Wand2,
   ListChecks, Download, BarChart3,
   Settings, Pin, PinOff,
-  History, FileText,
+  History, FileText, Network,
 } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { useUserPreferencesStore } from '@/store/userPreferencesStore'
@@ -86,10 +86,11 @@ export function Sidebar() {
     {
       href: '/trees', icon: GitBranch, label: 'Flows', shortLabel: 'Flows',
       badge: stats?.tree_counts.total || undefined,
-      matchPaths: ['/trees', '/flows', '/my-trees', '/step-library', '/review-queue'],
+      matchPaths: ['/trees', '/flows', '/my-trees', '/step-library', '/review-queue', '/network-diagrams'],
       children: [
         { href: '/trees', label: 'Flow Library', count: stats?.tree_counts.total || undefined },
         { href: '/trees?type=procedural', label: 'Projects', count: stats?.tree_counts.procedural || undefined },
+        { href: '/network-diagrams', label: 'Network Maps' },
         { href: '/step-library', label: 'Solutions Library' },
         { href: '/review-queue', label: 'Review Queue' },
       ],
@@ -134,6 +135,7 @@ export function Sidebar() {
             { href: '/trees?type=procedural', label: 'Projects', count: stats?.tree_counts.procedural || undefined },
           ],
         },
+        { href: '/network-diagrams', icon: Network, label: 'Network Maps', shortLabel: 'NetMap', matchPaths: ['/network-diagrams'] },
         { href: '/scripts', icon: Code2, label: 'Scripts', shortLabel: 'Scripts' },
         { href: '/script-builder', icon: Wand2, label: 'Script Builder', shortLabel: 'Builder' },
         { href: '/review-queue', icon: ListChecks, label: 'Review Queue', shortLabel: 'Review' },

frontend/src/components/network/CanvasEmptyPrompt.tsx

@@ -0,0 +1,232 @@
+import { useState, useCallback, useEffect } from 'react'
+import { Sparkles, ArrowRight, PencilRuler, Wand2, X } from 'lucide-react'
+import { networkDiagramsApi } from '@/api'
+import type { AIGenerateResponse } from '@/types'
+
+const EXAMPLE_PROMPTS = [
+  'Small office with firewall and core switch',
+  'Azure hybrid cloud with VPN gateway',
+  'Branch office connected to HQ via MPLS',
+  'Data center with redundant core switches',
+  'Remote workforce with Meraki and cloud apps',
+]
+
+interface CanvasEmptyPromptProps {
+  onGenerate: (result: AIGenerateResponse, mode: 'replace' | 'merge') => void
+}
+
+export function CanvasEmptyPrompt({ onGenerate }: CanvasEmptyPromptProps) {
+  const [mode, setMode] = useState<'choice' | 'ai' | 'manual'>('choice')
+  const [description, setDescription] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const switchToManual = useCallback(() => {
+    if (loading) return
+    setMode('manual')
+    setError(null)
+  }, [loading])
+
+  const handleGenerate = useCallback(async (text?: string) => {
+    const desc = (text ?? description).trim()
+    if (!desc) return
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await networkDiagramsApi.aiGenerate({
+        description: desc,
+        mode: 'replace',
+        existingBounds: null,
+      })
+      onGenerate(result, 'replace')
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Generation failed. Please try again.')
+    } finally {
+      setLoading(false)
+    }
+  }, [description, onGenerate])
+
+  useEffect(() => {
+    if (mode === 'manual') return
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        switchToManual()
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [mode, switchToManual])
+
+  if (mode === 'manual') {
+    return (
+      <div className="pointer-events-none absolute inset-x-0 bottom-6 z-10 flex justify-center px-6">
+        <div className="pointer-events-auto flex max-w-xl items-center gap-3 rounded-lg border border-default bg-card px-4 py-3 shadow-xl">
+          <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-accent/10 text-accent">
+            <PencilRuler size={14} />
+          </div>
+          <div className="min-w-0 flex-1">
+            <p className="text-sm font-medium text-heading">Manual mode is on</p>
+            <p className="text-xs text-muted-foreground">
+              Drag devices from the left panel onto the canvas, or reopen AI whenever you want.
+            </p>
+          </div>
+          <button
+            onClick={() => setMode('ai')}
+            className="inline-flex shrink-0 items-center gap-1 rounded-full border border-default px-3 py-1 text-xs font-medium text-primary hover:border-accent hover:text-accent"
+          >
+            <Sparkles size={12} />
+            Open AI Generator
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className="pointer-events-none absolute inset-0 z-10 flex items-center justify-center bg-[rgba(10,14,20,0.42)] px-6"
+      onClick={event => {
+        if (event.target === event.currentTarget) {
+          switchToManual()
+        }
+      }}
+    >
+      <div className="pointer-events-auto relative w-full max-w-lg rounded-lg border border-default bg-card p-8 shadow-2xl">
+        <button
+          onClick={switchToManual}
+          disabled={loading}
+          aria-label="Close AI prompt and build manually"
+          className="absolute right-4 top-4 inline-flex h-8 w-8 items-center justify-center rounded-full border border-default text-muted-foreground hover:border-hover hover:text-primary disabled:opacity-40"
+        >
+          <X size={14} />
+        </button>
+        {mode === 'choice' ? (
+          <>
+            <div className="mb-6 text-center">
+              <div className="mb-2 flex items-center justify-center gap-2">
+                <Wand2 size={16} className="text-accent" />
+                <h2 className="font-heading text-base font-semibold text-heading">
+                  Start a network map
+                </h2>
+              </div>
+              <p className="text-xs text-muted-foreground">
+                Generate a topology with AI or start with a blank canvas and build it manually.
+              </p>
+              <p className="mt-2 text-[11px] text-muted-foreground/80">
+                Press <span className="font-medium text-primary">Esc</span> or click outside to skip AI and start dragging devices.
+              </p>
+            </div>
+
+            <div className="grid gap-3 sm:grid-cols-2">
+              <button
+                onClick={() => setMode('ai')}
+                className="rounded-lg border border-accent/40 bg-accent/10 p-4 text-left transition-colors hover:border-accent hover:bg-accent/15"
+              >
+                <div className="mb-3 inline-flex rounded-lg bg-accent/15 p-2 text-accent">
+                  <Sparkles size={16} />
+                </div>
+                <div className="mb-1 text-sm font-semibold text-heading">Generate with AI</div>
+                <p className="text-xs text-muted-foreground">
+                  Describe the environment and let AI lay out the first version for you.
+                </p>
+              </button>
+
+              <button
+                onClick={switchToManual}
+                className="rounded-lg border border-default bg-elevated/40 p-4 text-left transition-colors hover:border-accent hover:bg-elevated/60"
+              >
+                <div className="mb-3 inline-flex rounded-lg bg-primary/10 p-2 text-primary">
+                  <PencilRuler size={16} />
+                </div>
+                <div className="mb-1 text-sm font-semibold text-heading">Build manually</div>
+                <p className="text-xs text-muted-foreground">
+                  Close this prompt and use click-and-drag from the left toolbar to place devices on the canvas.
+                </p>
+              </button>
+            </div>
+
+          </>
+        ) : (
+          <>
+            <div className="mb-5 text-center">
+              <div className="mb-2 flex items-center justify-center gap-2">
+                <Sparkles size={16} className="text-accent" />
+                <h2 className="font-heading text-base font-semibold text-heading">
+                  Describe your network
+                </h2>
+              </div>
+              <p className="text-xs text-muted-foreground">
+                AI will generate the topology in seconds, or you can go back and switch to manual creation.
+              </p>
+              <p className="mt-2 text-[11px] text-muted-foreground/80">
+                Press <span className="font-medium text-primary">Esc</span>, click outside, or use the close button to build manually instead.
+              </p>
+            </div>
+
+            <div className="relative mb-3">
+              <textarea
+                value={description}
+                onChange={e => setDescription(e.target.value)}
+                onKeyDown={e => {
+                  if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) handleGenerate()
+                }}
+                placeholder="e.g. Small office with a firewall, core switch, 3 access points, a file server, and 20 workstations"
+                rows={3}
+                disabled={loading}
+                autoFocus
+                className="w-full resize-none rounded-lg border border-default bg-input px-4 py-3 pb-7 text-sm text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none disabled:opacity-50"
+              />
+              <span className="pointer-events-none absolute bottom-2 right-3 text-[10px] text-muted-foreground">
+                ⌘↵ to generate
+              </span>
+            </div>
+
+            <div className="mb-4 flex flex-wrap gap-1.5">
+              {EXAMPLE_PROMPTS.map(p => (
+                <button
+                  key={p}
+                  onClick={() => handleGenerate(p)}
+                  disabled={loading}
+                  className="rounded-full border border-default px-3 py-1 text-xs text-muted-foreground transition-colors hover:border-accent hover:text-accent disabled:opacity-40"
+                >
+                  {p}
+                </button>
+              ))}
+            </div>
+
+            {error && <p className="mb-3 text-xs text-red-400">{error}</p>}
+
+            <div className="flex gap-2">
+              <button
+                onClick={switchToManual}
+                disabled={loading}
+                className="flex-1 rounded-lg border border-default px-4 py-2.5 text-sm font-medium text-primary hover:border-accent hover:text-accent disabled:opacity-40"
+              >
+                Build Manually
+              </button>
+              {loading ? (
+                <div className="flex flex-1 items-center justify-center gap-2 py-2.5">
+                  <div className="h-4 w-4 animate-spin rounded-full border-2 border-accent border-t-transparent" />
+                  <span className="text-sm text-muted-foreground">Mapping your network…</span>
+                </div>
+              ) : (
+                <button
+                  onClick={() => handleGenerate()}
+                  disabled={!description.trim()}
+                  className="flex flex-1 items-center justify-center gap-2 rounded-lg bg-accent px-4 py-2.5 text-sm font-medium text-white transition-opacity hover:bg-accent/90 disabled:opacity-40"
+                >
+                  <Sparkles size={14} />
+                  Generate Diagram
+                  <ArrowRight size={14} />
+                </button>
+              )}
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/network/ContextMenu.tsx

@@ -0,0 +1,209 @@
+import { useEffect, useRef } from 'react'
+import {
+  Copy, CopyPlus, Trash2, ClipboardPaste, BoxSelect, Ungroup, Maximize2, BringToFront, SendToBack,
+  AlignStartVertical, AlignCenterHorizontal, AlignEndVertical,
+  AlignStartHorizontal, AlignCenterVertical, AlignEndHorizontal,
+  AlignHorizontalSpaceAround, AlignVerticalSpaceAround,
+} from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+interface MenuAction {
+  label: string
+  icon: React.ElementType
+  shortcut: string
+  onClick: () => void
+  disabled?: boolean
+  dividerBefore?: boolean
+}
+
+interface ContextMenuProps {
+  position: { x: number; y: number }
+  actions: MenuAction[]
+  onClose: () => void
+  onAlignLeft?: () => void
+  onAlignRight?: () => void
+  onAlignCenterH?: () => void
+  onAlignTop?: () => void
+  onAlignBottom?: () => void
+  onAlignCenterV?: () => void
+  onDistributeH?: () => void
+  onDistributeV?: () => void
+  canAlign?: boolean
+  canDistribute?: boolean
+  onGroupSelection?: () => void
+  onUngroupSelection?: () => void
+  canGroup?: boolean
+  canUngroup?: boolean
+}
+
+export function ContextMenu({
+  position,
+  actions,
+  onClose,
+  onAlignLeft,
+  onAlignRight,
+  onAlignCenterH,
+  onAlignTop,
+  onAlignBottom,
+  onAlignCenterV,
+  onDistributeH,
+  onDistributeV,
+  canAlign,
+  canDistribute,
+  onGroupSelection,
+  onUngroupSelection,
+  canGroup,
+  canUngroup,
+}: ContextMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null)
+
+  const clampedPosition = { ...position }
+  if (typeof window !== 'undefined') {
+    const itemCount = actions.length
+    const dividerCount = actions.filter(a => a.dividerBefore).length
+    const menuWidth = 192
+    const menuHeight = itemCount * 36 + dividerCount * 9 + 8
+    if (clampedPosition.x + menuWidth > window.innerWidth) {
+      clampedPosition.x = window.innerWidth - menuWidth - 8
+    }
+    if (clampedPosition.y + menuHeight > window.innerHeight) {
+      clampedPosition.y = window.innerHeight - menuHeight - 8
+    }
+  }
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as HTMLElement)) {
+        onClose()
+      }
+    }
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    const handleScroll = () => onClose()
+
+    document.addEventListener('mousedown', handleClickOutside)
+    document.addEventListener('keydown', handleEscape)
+    document.addEventListener('scroll', handleScroll, true)
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside)
+      document.removeEventListener('keydown', handleEscape)
+      document.removeEventListener('scroll', handleScroll, true)
+    }
+  }, [onClose])
+
+  return (
+    <div
+      ref={menuRef}
+      className="fixed z-50 w-48 rounded-lg border border-default bg-card py-1 shadow-lg"
+      style={{ left: clampedPosition.x, top: clampedPosition.y }}
+    >
+      {actions.map((action) => (
+        <div key={action.label}>
+          {action.dividerBefore && (
+            <div className="my-1 border-t border-default" />
+          )}
+          <button
+            onClick={() => {
+              action.onClick()
+              onClose()
+            }}
+            disabled={action.disabled}
+            className={cn(
+              'flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated',
+              action.disabled && 'opacity-40 pointer-events-none',
+            )}
+          >
+            <action.icon size={14} />
+            <span>{action.label}</span>
+            <span className="ml-auto text-[10px] text-muted-foreground">{action.shortcut}</span>
+          </button>
+        </div>
+      ))}
+
+      {canAlign && (
+        <>
+          <div className="border-t border-default my-1" />
+          <div className="px-3 py-0.5 text-[10px] font-medium text-muted uppercase tracking-wider">Align</div>
+          <button onClick={() => { onAlignLeft?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+            <AlignStartVertical size={13} /> <span>Align Left</span>
+          </button>
+          <button onClick={() => { onAlignCenterH?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+            <AlignCenterHorizontal size={13} /> <span>Align Center</span>
+          </button>
+          <button onClick={() => { onAlignRight?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+            <AlignEndVertical size={13} /> <span>Align Right</span>
+          </button>
+          <button onClick={() => { onAlignTop?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+            <AlignStartHorizontal size={13} /> <span>Align Top</span>
+          </button>
+          <button onClick={() => { onAlignCenterV?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+            <AlignCenterVertical size={13} /> <span>Align Middle</span>
+          </button>
+          <button onClick={() => { onAlignBottom?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+            <AlignEndHorizontal size={13} /> <span>Align Bottom</span>
+          </button>
+          {canDistribute && (
+            <>
+              <div className="border-t border-default my-1" />
+              <div className="px-3 py-0.5 text-[10px] font-medium text-muted uppercase tracking-wider">Distribute</div>
+              <button onClick={() => { onDistributeH?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+                <AlignHorizontalSpaceAround size={13} /> <span>Space Horizontally</span>
+              </button>
+              <button onClick={() => { onDistributeV?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+                <AlignVerticalSpaceAround size={13} /> <span>Space Vertically</span>
+              </button>
+            </>
+          )}
+        </>
+      )}
+
+      {(canGroup || canUngroup) && (
+        <>
+          <div className="border-t border-default my-1" />
+          {canGroup && (
+            <button onClick={() => { onGroupSelection?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+              <BoxSelect size={13} /> <span>Group Selection</span>
+            </button>
+          )}
+          {canUngroup && (
+            <button onClick={() => { onUngroupSelection?.(); onClose() }} className="flex w-full items-center gap-2 px-3 py-2 text-xs text-primary hover:bg-elevated">
+              <Ungroup size={13} /> <span>Ungroup</span>
+            </button>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function getNodeMenuActions(handlers: {
+  onCopy: () => void
+  onDuplicate: () => void
+  onBringToFront: () => void
+  onSendToBack: () => void
+  onDelete: () => void
+}): MenuAction[] {
+  return [
+    { label: 'Copy', icon: Copy, shortcut: 'Ctrl+C', onClick: handlers.onCopy },
+    { label: 'Duplicate', icon: CopyPlus, shortcut: 'Ctrl+D', onClick: handlers.onDuplicate },
+    { label: 'Bring to Front', icon: BringToFront, shortcut: ']', onClick: handlers.onBringToFront, dividerBefore: true },
+    { label: 'Send to Back', icon: SendToBack, shortcut: '[', onClick: handlers.onSendToBack },
+    { label: 'Delete', icon: Trash2, shortcut: 'Del', onClick: handlers.onDelete, dividerBefore: true },
+  ]
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function getCanvasMenuActions(handlers: {
+  onPaste: () => void
+  onSelectAll: () => void
+  onFitView: () => void
+  hasClipboard: boolean
+}): MenuAction[] {
+  return [
+    { label: 'Paste', icon: ClipboardPaste, shortcut: 'Ctrl+V', onClick: handlers.onPaste, disabled: !handlers.hasClipboard },
+    { label: 'Select All', icon: BoxSelect, shortcut: 'Ctrl+A', onClick: handlers.onSelectAll },
+    { label: 'Fit View', icon: Maximize2, shortcut: '⌘⇧F', onClick: handlers.onFitView },
+  ]
+}

frontend/src/components/network/DiagramHeader.tsx

@@ -0,0 +1,275 @@
+import { useState, useCallback, useRef, useEffect } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { ChevronLeft, Save, Download, FileJson, FileCode, Image, FileText, Undo2, Redo2, MousePointer2, Hand, FileOutput, Upload, Cable } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+export type InteractionMode = 'select' | 'pan' | 'connect'
+
+interface DiagramHeaderProps {
+  name: string
+  clientName: string | null
+  isDirty: boolean
+  isSaving: boolean
+  lastSavedAt: Date | null
+  diagramId: string | null
+  onNameChange: (name: string) => void
+  onSave: () => void
+  onExportPng: () => void
+  onExportSvg: () => void
+  onExportPdf: () => void
+  onExportJson: () => void
+  onExportDrawio: () => void
+  onImportDrawio: () => void  // draw.io import — triggered from Export menu
+  onUndo: () => void
+  onRedo: () => void
+  canUndo: boolean
+  canRedo: boolean
+  interactionMode: InteractionMode
+  onModeChange: (mode: InteractionMode) => void
+}
+
+export function DiagramHeader({
+  name,
+  clientName,
+  isDirty,
+  isSaving,
+  lastSavedAt,
+  diagramId,
+  onNameChange,
+  onSave,
+  onExportPng,
+  onExportSvg,
+  onExportPdf,
+  onExportJson,
+  onExportDrawio,
+  onImportDrawio,
+  onUndo,
+  onRedo,
+  canUndo,
+  canRedo,
+  interactionMode,
+  onModeChange,
+}: DiagramHeaderProps) {
+  const navigate = useNavigate()
+  const [editing, setEditing] = useState(false)
+  const [editValue, setEditValue] = useState(name)
+  const [showExportMenu, setShowExportMenu] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const exportMenuRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (editing && inputRef.current) {
+      inputRef.current.focus()
+      inputRef.current.select()
+    }
+  }, [editing])
+
+  useEffect(() => {
+    setEditValue(name)
+  }, [name])
+
+  useEffect(() => {
+    if (!showExportMenu) return
+    const handleClick = (e: MouseEvent) => {
+      if (exportMenuRef.current && !exportMenuRef.current.contains(e.target as HTMLElement)) {
+        setShowExportMenu(false)
+      }
+    }
+    document.addEventListener('mousedown', handleClick)
+    return () => document.removeEventListener('mousedown', handleClick)
+  }, [showExportMenu])
+
+  const handleConfirmName = useCallback(() => {
+    setEditing(false)
+    if (editValue.trim() && editValue !== name) {
+      onNameChange(editValue.trim())
+    } else {
+      setEditValue(name)
+    }
+  }, [editValue, name, onNameChange])
+
+  const formatLastSaved = () => {
+    if (!lastSavedAt) return null
+    // eslint-disable-next-line react-hooks/purity
+    const diff = Date.now() - lastSavedAt.getTime()
+    if (diff < 60_000) return 'Saved just now'
+    const mins = Math.floor(diff / 60_000)
+    return `Saved ${mins}m ago`
+  }
+
+  return (
+    <div className="flex h-14 items-center gap-3 border-b border-default bg-card px-4">
+      <button
+        onClick={() => navigate('/network-diagrams')}
+        className="flex items-center gap-1 text-xs text-muted-foreground hover:text-primary"
+      >
+        <ChevronLeft size={16} />
+        Network Maps
+      </button>
+
+      <div className="mx-2 h-5 w-px bg-border-default" />
+
+      <div className="flex items-center gap-1">
+        <button
+          onClick={onUndo}
+          disabled={!canUndo}
+          title="Undo (Ctrl+Z)"
+          className="p-1.5 rounded text-muted-foreground hover:text-primary hover:bg-elevated disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+        >
+          <Undo2 size={16} />
+        </button>
+        <button
+          onClick={onRedo}
+          disabled={!canRedo}
+          title="Redo (Ctrl+Y)"
+          className="p-1.5 rounded text-muted-foreground hover:text-primary hover:bg-elevated disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+        >
+          <Redo2 size={16} />
+        </button>
+      </div>
+
+      <div className="mx-2 h-5 w-px bg-border-default" />
+
+      {/* Interaction mode toggle */}
+      <div className="flex items-center overflow-hidden rounded border border-default">
+        <button
+          onClick={() => onModeChange('select')}
+          title="Select (V)"
+          className={cn(
+            'flex items-center gap-1.5 px-2.5 py-1.5 text-xs transition-colors',
+            interactionMode === 'select'
+              ? 'bg-elevated text-primary'
+              : 'text-muted-foreground hover:text-primary hover:bg-elevated/50',
+          )}
+        >
+          <MousePointer2 size={15} />
+          <span className="hidden sm:inline">Select</span>
+        </button>
+        <button
+          onClick={() => onModeChange('pan')}
+          title="Pan (H)"
+          className={cn(
+            'flex items-center gap-1.5 border-l border-default px-2.5 py-1.5 text-xs transition-colors',
+            interactionMode === 'pan'
+              ? 'bg-elevated text-primary'
+              : 'text-muted-foreground hover:text-primary hover:bg-elevated/50',
+          )}
+        >
+          <Hand size={15} />
+          <span className="hidden sm:inline">Pan</span>
+        </button>
+        <button
+          onClick={() => onModeChange('connect')}
+          title="Connect (C)"
+          className={cn(
+            'flex items-center gap-1.5 border-l border-default px-2.5 py-1.5 text-xs transition-colors',
+            interactionMode === 'connect'
+              ? 'bg-elevated text-primary'
+              : 'text-muted-foreground hover:text-primary hover:bg-elevated/50',
+          )}
+        >
+          <Cable size={15} />
+          <span className="hidden sm:inline">Connect</span>
+        </button>
+      </div>
+
+      <div className="mx-2 h-5 w-px bg-border-default" />
+
+      {editing ? (
+        <input
+          ref={inputRef}
+          value={editValue}
+          onChange={e => setEditValue(e.target.value)}
+          onBlur={handleConfirmName}
+          onKeyDown={e => { if (e.key === 'Enter') handleConfirmName(); if (e.key === 'Escape') { setEditing(false); setEditValue(name) } }}
+          className="rounded border border-accent bg-input px-2 py-1 text-sm font-heading font-semibold text-heading focus:outline-none"
+        />
+      ) : (
+        <button
+          onClick={() => setEditing(true)}
+          className="text-sm font-heading font-semibold text-heading hover:text-accent"
+        >
+          {name || 'Untitled Diagram'}
+        </button>
+      )}
+
+      {clientName && (
+        <span className="rounded-full bg-elevated px-2 py-0.5 text-[10px] text-muted-foreground">
+          {clientName}
+        </span>
+      )}
+
+      <div className="flex-1" />
+
+      {isDirty && !isSaving ? (
+        <span className="text-[10px] text-amber-400">Unsaved changes</span>
+      ) : lastSavedAt ? (
+        <span className="text-[10px] text-muted-foreground">{formatLastSaved()}</span>
+      ) : null}
+
+      <button
+        onClick={onSave}
+        disabled={isSaving}
+        className="flex items-center gap-1.5 rounded bg-accent px-3 py-1.5 text-xs font-medium text-white hover:bg-accent/90 disabled:opacity-50"
+      >
+        <Save size={14} />
+        {isSaving ? 'Saving...' : 'Save'}
+      </button>
+
+      <div className="relative" ref={exportMenuRef}>
+        <button
+          onClick={() => setShowExportMenu(prev => !prev)}
+          className="flex items-center gap-1.5 rounded border border-default px-3 py-1.5 text-xs text-primary hover:border-hover"
+        >
+          <Download size={14} />
+          Export / Import
+        </button>
+        {showExportMenu && (
+          <div className="absolute right-0 top-full z-50 mt-1 w-44 rounded border border-default bg-card py-1 shadow-lg">
+            <div className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">Export as</div>
+            <button
+              onClick={() => { onExportPng(); setShowExportMenu(false) }}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-primary hover:bg-elevated"
+            >
+              <Image size={12} /> PNG
+            </button>
+            <button
+              onClick={() => { onExportSvg(); setShowExportMenu(false) }}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-primary hover:bg-elevated"
+            >
+              <FileCode size={12} /> SVG
+            </button>
+            <button
+              onClick={() => { onExportPdf(); setShowExportMenu(false) }}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-primary hover:bg-elevated"
+            >
+              <FileText size={12} /> PDF
+            </button>
+            {diagramId && (
+              <button
+                onClick={() => { onExportJson(); setShowExportMenu(false) }}
+                className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-primary hover:bg-elevated"
+              >
+                <FileJson size={12} /> JSON
+              </button>
+            )}
+            <button
+              onClick={() => { onExportDrawio(); setShowExportMenu(false) }}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-primary hover:bg-elevated"
+            >
+              <FileOutput size={12} /> draw.io
+            </button>
+            <div className="my-1 border-t border-default" />
+            <div className="px-3 py-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">Import</div>
+            <button
+              onClick={() => { onImportDrawio(); setShowExportMenu(false) }}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-xs text-primary hover:bg-elevated"
+            >
+              <Upload size={12} /> draw.io file…
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/network/KeyboardShortcutsOverlay.tsx

@@ -0,0 +1,129 @@
+import { useEffect } from 'react'
+import { X } from 'lucide-react'
+
+interface ShortcutRow {
+  keys: string[]
+  label: string
+}
+
+interface ShortcutGroup {
+  title: string
+  rows: ShortcutRow[]
+}
+
+const GROUPS: ShortcutGroup[] = [
+  {
+    title: 'Modes',
+    rows: [
+      { keys: ['V'], label: 'Select mode' },
+      { keys: ['H'], label: 'Pan mode' },
+      { keys: ['C'], label: 'Connect mode' },
+      { keys: ['Space'], label: 'Temporary pan (hold)' },
+    ],
+  },
+  {
+    title: 'Canvas',
+    rows: [
+      { keys: ['Ctrl', 'Shift', 'F'], label: 'Fit view' },
+      { keys: ['Ctrl', 'A'], label: 'Select all' },
+      { keys: ['Ctrl', 'Z'], label: 'Undo' },
+      { keys: ['Ctrl', 'Y'], label: 'Redo' },
+    ],
+  },
+  {
+    title: 'Nodes',
+    rows: [
+      { keys: ['Ctrl', 'C'], label: 'Copy' },
+      { keys: ['Ctrl', 'V'], label: 'Paste' },
+      { keys: ['Ctrl', 'D'], label: 'Duplicate' },
+      { keys: ['Del'], label: 'Delete selected' },
+      { keys: [']'], label: 'Bring to front' },
+      { keys: ['['], label: 'Send to back' },
+    ],
+  },
+  {
+    title: 'Nudge',
+    rows: [
+      { keys: ['↑', '↓', '←', '→'], label: 'Move 1px' },
+      { keys: ['Shift', '↑↓←→'], label: 'Move 10px' },
+    ],
+  },
+]
+
+interface KeyboardShortcutsOverlayProps {
+  onClose: () => void
+}
+
+function Kbd({ children }: { children: string }) {
+  return (
+    <span className="inline-flex h-5 min-w-[1.25rem] items-center justify-center rounded border border-white/10 bg-white/[0.07] px-1.5 text-[10px] font-mono text-muted-foreground">
+      {children}
+    </span>
+  )
+}
+
+export function KeyboardShortcutsOverlay({ onClose }: KeyboardShortcutsOverlayProps) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', handler)
+    return () => document.removeEventListener('keydown', handler)
+  }, [onClose])
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-[2px]"
+      onClick={e => { if (e.target === e.currentTarget) onClose() }}
+    >
+      <div className="w-full max-w-xl rounded-lg border border-default bg-card shadow-2xl">
+        {/* Header */}
+        <div className="flex items-center justify-between border-b border-default px-5 py-3.5">
+          <div>
+            <h2 className="font-heading text-sm font-semibold text-heading">Keyboard Shortcuts</h2>
+            <p className="text-[11px] text-muted-foreground">Press <Kbd>?</Kbd> anytime to open this</p>
+          </div>
+          <button
+            onClick={onClose}
+            className="flex h-7 w-7 items-center justify-center rounded border border-default text-muted-foreground hover:border-hover hover:text-primary"
+          >
+            <X size={13} />
+          </button>
+        </div>
+
+        {/* Shortcut grid */}
+        <div className="grid grid-cols-2 gap-0 divide-x divide-default">
+          {GROUPS.map((group, gi) => (
+            <div key={group.title} className={gi >= 2 ? 'border-t border-default' : ''}>
+              <div className="px-5 pb-2 pt-4">
+                <div className="mb-2 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+                  {group.title}
+                </div>
+                <div className="space-y-1.5">
+                  {group.rows.map(row => (
+                    <div key={row.label} className="flex items-center justify-between gap-3">
+                      <span className="text-xs text-primary">{row.label}</span>
+                      <div className="flex shrink-0 items-center gap-0.5">
+                        {row.keys.map((k, i) => (
+                          <span key={i} className="flex items-center gap-0.5">
+                            {i > 0 && <span className="text-[10px] text-muted-foreground/50">+</span>}
+                            <Kbd>{k}</Kbd>
+                          </span>
+                        ))}
+                      </div>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+
+        {/* Footer hint */}
+        <div className="border-t border-default px-5 py-2.5 text-[11px] text-muted-foreground">
+          On Mac, <Kbd>Ctrl</Kbd> = <Kbd>⌘ Cmd</Kbd>
+        </div>
+      </div>
+    </div>
+  )
+}

frontend/src/components/network/NetworkCanvas.tsx

@@ -0,0 +1,146 @@
+import { useCallback } from 'react'
+import {
+  ReactFlow,
+  Background,
+  Controls,
+  MiniMap,
+  BackgroundVariant,
+  type OnConnect,
+  type OnReconnect,
+  type OnNodesChange,
+  type OnEdgesChange,
+  type Node,
+  type Edge,
+} from '@xyflow/react'
+import { nodeTypes } from './nodes/nodeTypes'
+import { edgeTypes } from './edges/edgeTypes'
+import { getDeviceRenderConfig } from './nodes/deviceRegistry'
+import type { DeviceNodeData } from './nodes/DeviceNode'
+import type { InteractionMode } from './DiagramHeader'
+import { cn } from '@/lib/utils'
+
+interface NetworkCanvasProps {
+  nodes: Node[]
+  edges: Edge[]
+  onNodesChange: OnNodesChange
+  onEdgesChange: OnEdgesChange
+  onConnect: OnConnect
+  onReconnect: OnReconnect<Edge>
+  onNodeSelect: (nodeId: string | null) => void
+  onEdgeSelect: (edgeId: string | null) => void
+  onDrop: (event: React.DragEvent) => void
+  onDragOver: (event: React.DragEvent) => void
+  onDragLeave?: (event: React.DragEvent) => void
+  isDragOver?: boolean
+  onNodeContextMenu?: (event: React.MouseEvent, node: Node) => void
+  onPaneContextMenu?: (event: MouseEvent | React.MouseEvent) => void
+  onPaneClick?: () => void
+  interactionMode?: InteractionMode
+}
+
+export function NetworkCanvas({
+  nodes,
+  edges,
+  onNodesChange,
+  onEdgesChange,
+  onConnect,
+  onReconnect,
+  onNodeSelect,
+  onEdgeSelect,
+  onDrop,
+  onDragOver,
+  onDragLeave,
+  isDragOver,
+  onNodeContextMenu,
+  onPaneContextMenu,
+  onPaneClick: onPaneClickProp,
+  interactionMode = 'select',
+}: NetworkCanvasProps) {
+  const handleSelectionChange = useCallback(({ nodes: selectedNodes, edges: selectedEdges }: { nodes: Node[]; edges: Edge[] }) => {
+    if (selectedNodes.length === 1) {
+      onNodeSelect(selectedNodes[0].id)
+      onEdgeSelect(null)
+    } else if (selectedEdges.length === 1) {
+      onEdgeSelect(selectedEdges[0].id)
+      onNodeSelect(null)
+    } else {
+      onNodeSelect(null)
+      onEdgeSelect(null)
+    }
+  }, [onNodeSelect, onEdgeSelect])
+
+  const handlePaneClick = useCallback(() => {
+    onNodeSelect(null)
+    onEdgeSelect(null)
+    onPaneClickProp?.()
+  }, [onNodeSelect, onEdgeSelect, onPaneClickProp])
+
+  const getNodeColor = useCallback((node: Node) => {
+    if (node.type === 'group') return 'var(--color-bg-elevated)'
+    const data = node.data as unknown as DeviceNodeData
+    return getDeviceRenderConfig(data?.deviceType || '', data?.category).color
+  }, [])
+
+  return (
+    <div
+      className="relative h-full w-full"
+      onDragLeave={onDragLeave}
+      onMouseDownCapture={(event) => {
+        if (event.button === 1) {
+          event.preventDefault()
+        }
+      }}
+    >
+      <ReactFlow
+        nodes={nodes}
+        edges={edges}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+        onConnect={onConnect}
+        onReconnect={onReconnect}
+        onSelectionChange={handleSelectionChange}
+        onPaneClick={handlePaneClick}
+        onDrop={onDrop}
+        onDragOver={onDragOver}
+        onNodeContextMenu={onNodeContextMenu}
+        onPaneContextMenu={onPaneContextMenu}
+        nodeTypes={nodeTypes}
+        edgeTypes={edgeTypes}
+        defaultEdgeOptions={{ type: 'connection' }}
+        edgesReconnectable
+        connectOnClick={interactionMode === 'connect'}
+        reconnectRadius={20}
+        connectionRadius={24}
+        deleteKeyCode={['Backspace', 'Delete']}
+        multiSelectionKeyCode="Shift"
+        panOnDrag={interactionMode === 'pan' ? [0, 1] : [1]}
+        selectionOnDrag={interactionMode === 'select'}
+        panActivationKeyCode="Space"
+        snapToGrid={true}
+        snapGrid={[20, 20]}
+        fitView
+        className={cn(
+          'bg-page',
+          interactionMode === 'pan' && 'cursor-grab active:cursor-grabbing',
+          interactionMode === 'connect' && 'rf-connect-mode cursor-crosshair',
+        )}
+      >
+        <Background variant={BackgroundVariant.Dots} color="var(--color-border-default)" gap={20} size={1} />
+        <Controls className="!border-default !bg-card [&>button]:!border-default [&>button]:!bg-card [&>button]:!fill-text-primary" />
+        <MiniMap
+          nodeColor={getNodeColor}
+          maskColor="rgba(0,0,0,0.5)"
+          className="!border-default !bg-card"
+          position="bottom-right"
+        />
+      </ReactFlow>
+      {isDragOver && (
+        <div className="pointer-events-none absolute inset-2 z-10 flex items-center justify-center rounded-lg border-2 border-dashed border-accent/30">
+          <span className="rounded-md bg-card/80 px-3 py-1.5 text-sm text-muted-foreground">
+            Drop to add
+          </span>
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/components/network/edges/ConnectionEdge.tsx

@@ -0,0 +1,72 @@
+import { memo } from 'react'
+import { BaseEdge, EdgeLabelRenderer, getStraightPath, getBezierPath, getSmoothStepPath, type EdgeProps } from '@xyflow/react'
+
+interface ConnectionEdgeData {
+  connectionType?: string
+  routing?: string | null
+  speed?: string | null
+  notes?: string | null
+  [key: string]: unknown
+}
+
+const CONNECTION_STYLES: Record<string, { stroke: string; strokeDasharray?: string; strokeWidth: number }> = {
+  ethernet: { stroke: '#60a5fa', strokeWidth: 2 },
+  fiber: { stroke: '#34d399', strokeWidth: 3 },
+  wifi: { stroke: '#a78bfa', strokeDasharray: '3,3', strokeWidth: 2 },
+  vpn: { stroke: '#eab308', strokeDasharray: '8,4', strokeWidth: 2 },
+  vlan: { stroke: '#848b9b', strokeWidth: 2 },
+  wan: { stroke: '#f87171', strokeDasharray: '12,4', strokeWidth: 2 },
+}
+
+const DEFAULT_STYLE = { stroke: '#848b9b', strokeWidth: 2 }
+
+function getEdgePath(routing: string | null | undefined, props: EdgeProps) {
+  const base = {
+    sourceX: props.sourceX,
+    sourceY: props.sourceY,
+    sourcePosition: props.sourcePosition,
+    targetX: props.targetX,
+    targetY: props.targetY,
+    targetPosition: props.targetPosition,
+  }
+  if (routing === 'curved') return getBezierPath(base)
+  if (routing === 'step') return getSmoothStepPath(base)
+  if (routing === 'orthogonal') return getSmoothStepPath({ ...base, borderRadius: 0 })
+  return getStraightPath(base)
+}
+
+function ConnectionEdgeComponent(props: EdgeProps) {
+  const edgeData = props.data as ConnectionEdgeData | undefined
+  const connectionType = edgeData?.connectionType || 'ethernet'
+  const style = CONNECTION_STYLES[connectionType] || DEFAULT_STYLE
+
+  const [edgePath, labelX, labelY] = getEdgePath(edgeData?.routing, props)
+
+  return (
+    <>
+      <BaseEdge
+        path={edgePath}
+        style={{
+          ...style,
+          ...(props.selected ? { stroke: '#60a5fa', strokeWidth: style.strokeWidth + 1 } : {}),
+        }}
+      />
+      {props.label && (
+        <EdgeLabelRenderer>
+          <div
+            className="nodrag nopan rounded border border-default bg-card px-1.5 py-0.5 text-[10px] text-muted-foreground shadow-sm"
+            style={{
+              position: 'absolute',
+              transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`,
+              pointerEvents: 'all',
+            }}
+          >
+            {props.label}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  )
+}
+
+export const ConnectionEdge = memo(ConnectionEdgeComponent)

frontend/src/components/network/edges/edgeTypes.ts

@@ -0,0 +1,7 @@
+import { ConnectionEdge } from './ConnectionEdge'
+import { AnimatedSvgEdge } from '../ui/animated-svg-edge'
+
+export const edgeTypes = {
+  connection: ConnectionEdge,
+  animated: AnimatedSvgEdge,
+}

frontend/src/components/network/hooks/useCanvasShortcuts.ts

@@ -0,0 +1,304 @@
+import { useCallback, useEffect, useRef } from 'react'
+import { useReactFlow, type Node, type Edge } from '@xyflow/react'
+
+interface ClipboardData {
+  nodes: Array<{
+    type: string
+    data: Record<string, unknown>
+    style?: React.CSSProperties
+    relativePosition: { x: number; y: number }
+  }>
+  edges: Array<{
+    sourceIndex: number
+    targetIndex: number
+    type?: string
+    data?: Record<string, unknown>
+    label?: string
+  }>
+}
+
+function generateId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+}
+
+function isInputFocused(): boolean {
+  const tag = document.activeElement?.tagName
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT'
+}
+
+export function useCanvasShortcuts({
+  nodes: _nodes, // eslint-disable-line @typescript-eslint/no-unused-vars
+  edges,
+  setNodes,
+  setEdges,
+  setIsDirty,
+  canvasRef,
+  onUndo,
+  onRedo,
+  onNudge,
+  onSetMode,
+  onToggleShortcuts,
+}: {
+  nodes: Node[]
+  edges: Edge[]
+  setNodes: React.Dispatch<React.SetStateAction<Node[]>>
+  setEdges: React.Dispatch<React.SetStateAction<Edge[]>>
+  setIsDirty: (dirty: boolean) => void
+  canvasRef: React.RefObject<HTMLDivElement | null>
+  onUndo: () => void
+  onRedo: () => void
+  onNudge: (dx: number, dy: number) => void
+  onSetMode: (mode: 'select' | 'pan' | 'connect') => void
+  onToggleShortcuts: () => void
+}) {
+  const { getNodes, fitView, screenToFlowPosition, setNodes: rfSetNodes } = useReactFlow()
+  const clipboardRef = useRef<ClipboardData | null>(null)
+
+  const getSelectedNodes = useCallback((): Node[] => {
+    return getNodes().filter(n => n.selected)
+  }, [getNodes])
+
+  const copyNodes = useCallback(() => {
+    const selected = getSelectedNodes()
+    if (selected.length === 0) return
+
+    const centroid = {
+      x: selected.reduce((sum, n) => sum + n.position.x, 0) / selected.length,
+      y: selected.reduce((sum, n) => sum + n.position.y, 0) / selected.length,
+    }
+
+    const selectedIds = new Set(selected.map(n => n.id))
+
+    const clipNodes = selected.map(n => ({
+      type: n.type || 'device',
+      data: structuredClone(n.data),
+      style: n.style ? { ...n.style } : undefined,
+      relativePosition: {
+        x: n.position.x - centroid.x,
+        y: n.position.y - centroid.y,
+      },
+    }))
+
+    const selectedList = selected.map(n => n.id)
+    const clipEdges = edges
+      .filter(e => selectedIds.has(e.source) && selectedIds.has(e.target))
+      .map(e => ({
+        sourceIndex: selectedList.indexOf(e.source),
+        targetIndex: selectedList.indexOf(e.target),
+        type: e.type,
+        data: e.data ? structuredClone(e.data) as Record<string, unknown> : undefined,
+        label: typeof e.label === 'string' ? e.label : undefined,
+      }))
+
+    clipboardRef.current = { nodes: clipNodes, edges: clipEdges }
+  }, [getSelectedNodes, edges])
+
+  const pasteNodes = useCallback(() => {
+    const clipboard = clipboardRef.current
+    if (!clipboard || clipboard.nodes.length === 0) return
+
+    const canvasEl = canvasRef.current
+    if (!canvasEl) return
+    const rect = canvasEl.getBoundingClientRect()
+    const center = screenToFlowPosition({
+      x: rect.left + rect.width / 2,
+      y: rect.top + rect.height / 2,
+    })
+
+    const newNodeIds: string[] = []
+    const newNodes: Node[] = clipboard.nodes.map(cn => {
+      const prefix = cn.type === 'group' ? 'group' : 'device'
+      const id = generateId(prefix)
+      newNodeIds.push(id)
+      return {
+        id,
+        type: cn.type,
+        position: {
+          x: center.x + cn.relativePosition.x,
+          y: center.y + cn.relativePosition.y,
+        },
+        data: structuredClone(cn.data) as Record<string, unknown>,
+        style: cn.style ? { ...cn.style } : undefined,
+        selected: true,
+      }
+    })
+
+    const newEdges: Edge[] = clipboard.edges.map(ce => ({
+      id: generateId('edge'),
+      source: newNodeIds[ce.sourceIndex],
+      target: newNodeIds[ce.targetIndex],
+      type: ce.type,
+      data: ce.data ? structuredClone(ce.data) as Record<string, unknown> : undefined,
+      label: ce.label,
+    }))
+
+    setNodes(nds => [
+      ...nds.map(n => ({ ...n, selected: false })),
+      ...newNodes,
+    ])
+    setEdges(eds => [...eds, ...newEdges])
+    setIsDirty(true)
+  }, [canvasRef, screenToFlowPosition, setNodes, setEdges, setIsDirty])
+
+  const duplicateNodes = useCallback(() => {
+    const selected = getSelectedNodes()
+    if (selected.length === 0) return
+
+    const selectedIds = new Set(selected.map(n => n.id))
+    const idMap = new Map<string, string>()
+
+    const newNodes: Node[] = selected.map(n => {
+      const prefix = n.type === 'group' ? 'group' : 'device'
+      const newId = generateId(prefix)
+      idMap.set(n.id, newId)
+      return {
+        id: newId,
+        type: n.type,
+        position: { x: n.position.x + 30, y: n.position.y + 30 },
+        data: structuredClone(n.data) as Record<string, unknown>,
+        style: n.style ? { ...n.style } : undefined,
+        selected: true,
+      }
+    })
+
+    const newEdges: Edge[] = edges
+      .filter(e => selectedIds.has(e.source) && selectedIds.has(e.target))
+      .map(e => ({
+        id: generateId('edge'),
+        source: idMap.get(e.source)!,
+        target: idMap.get(e.target)!,
+        type: e.type,
+        data: e.data ? structuredClone(e.data) as Record<string, unknown> : undefined,
+        label: e.label,
+      }))
+
+    setNodes(nds => [
+      ...nds.map(n => ({ ...n, selected: false })),
+      ...newNodes,
+    ])
+    setEdges(eds => [...eds, ...newEdges])
+    setIsDirty(true)
+  }, [getSelectedNodes, edges, setNodes, setEdges, setIsDirty])
+
+  const selectAll = useCallback(() => {
+    rfSetNodes(nds => nds.map(n => ({ ...n, selected: true })))
+  }, [rfSetNodes])
+
+  const deleteSelected = useCallback(() => {
+    const selected = getSelectedNodes()
+    if (selected.length === 0) return
+    const selectedIds = new Set(selected.map(n => n.id))
+    setNodes(nds => nds.filter(n => !selectedIds.has(n.id)))
+    setEdges(eds => eds.filter(e => !selectedIds.has(e.source) && !selectedIds.has(e.target)))
+    setIsDirty(true)
+  }, [getSelectedNodes, setNodes, setEdges, setIsDirty])
+
+  const bringSelectedToFront = useCallback(() => {
+    const selected = getSelectedNodes()
+    if (!selected.length) return
+    const selectedIds = new Set(selected.map(n => n.id))
+    setNodes(nds => {
+      const maxZ = Math.max(0, ...nds.map(n => n.zIndex ?? 0))
+      return nds.map(n => selectedIds.has(n.id) ? { ...n, zIndex: maxZ + 1 } : n)
+    })
+    setIsDirty(true)
+  }, [getSelectedNodes, setNodes, setIsDirty])
+
+  const sendSelectedToBack = useCallback(() => {
+    const selected = getSelectedNodes()
+    if (!selected.length) return
+    const selectedIds = new Set(selected.map(n => n.id))
+    setNodes(nds => {
+      const minZ = Math.min(0, ...nds.map(n => n.zIndex ?? 0))
+      return nds.map(n => selectedIds.has(n.id) ? { ...n, zIndex: minZ - 1 } : n)
+    })
+    setIsDirty(true)
+  }, [getSelectedNodes, setNodes, setIsDirty])
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (isInputFocused()) return
+
+      const ctrl = e.ctrlKey || e.metaKey
+
+      // Undo: Ctrl+Z / Cmd+Z
+      if (e.key === 'z' && ctrl && !e.shiftKey) {
+        e.preventDefault()
+        onUndo()
+        return
+      }
+      // Redo: Ctrl+Y or Ctrl+Shift+Z
+      if ((e.key === 'y' && ctrl) || (e.key === 'z' && ctrl && e.shiftKey)) {
+        e.preventDefault()
+        onRedo()
+        return
+      }
+      // Arrow key nudging
+      if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(e.key)) {
+        e.preventDefault()
+        const delta = e.shiftKey ? 10 : 1
+        switch (e.key) {
+          case 'ArrowUp':    onNudge(0, -delta); break
+          case 'ArrowDown':  onNudge(0,  delta); break
+          case 'ArrowLeft':  onNudge(-delta, 0); break
+          case 'ArrowRight': onNudge( delta, 0); break
+        }
+        return
+      }
+
+      // Mode shortcuts: V = select, H = pan, C = connect
+      if (!ctrl && e.key === 'v') {
+        onSetMode('select')
+        return
+      }
+      if (!ctrl && e.key === 'h') {
+        onSetMode('pan')
+        return
+      }
+      if (!ctrl && e.key === 'c') {
+        onSetMode('connect')
+        return
+      }
+
+      if (ctrl && e.key === 'c') {
+        e.preventDefault()
+        copyNodes()
+      } else if (ctrl && e.key === 'v') {
+        e.preventDefault()
+        pasteNodes()
+      } else if (ctrl && e.key === 'd') {
+        e.preventDefault()
+        duplicateNodes()
+      } else if (ctrl && e.key === 'a') {
+        e.preventDefault()
+        selectAll()
+      } else if (ctrl && e.shiftKey && (e.key === 'f' || e.key === 'F')) {
+        e.preventDefault()
+        fitView({ padding: 0.2 })
+      } else if (e.key === ']' && !ctrl) {
+        e.preventDefault()
+        bringSelectedToFront()
+      } else if (e.key === '[' && !ctrl) {
+        e.preventDefault()
+        sendSelectedToBack()
+      } else if (e.key === '?' && !ctrl) {
+        e.preventDefault()
+        onToggleShortcuts()
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown)
+    return () => document.removeEventListener('keydown', handleKeyDown)
+  }, [copyNodes, pasteNodes, duplicateNodes, selectAll, fitView, bringSelectedToFront, sendSelectedToBack, onUndo, onRedo, onNudge, onSetMode, onToggleShortcuts])
+
+  return {
+    copyNodes,
+    pasteNodes,
+    duplicateNodes,
+    selectAll,
+    deleteSelected,
+    bringSelectedToFront,
+    sendSelectedToBack,
+    hasClipboard: () => clipboardRef.current !== null && clipboardRef.current.nodes.length > 0,
+  }
+}

frontend/src/components/network/hooks/useDiagramCommands.ts

@@ -0,0 +1,206 @@
+import { useCallback } from 'react'
+import type { Node, Edge } from '@xyflow/react'
+
+interface UseDiagramCommandsParams {
+  nodes: Node[]
+  edges: Edge[]
+  pushHistory: (nodes: Node[], edges: Edge[]) => void
+  setNodes: React.Dispatch<React.SetStateAction<Node[]>>
+}
+
+export function useDiagramCommands({
+  nodes,
+  edges,
+  pushHistory,
+  setNodes,
+}: UseDiagramCommandsParams) {
+  const selectedNodes = nodes.filter(n => n.selected)
+
+  // ── Alignment ──────────────────────────────────────────────────────────
+  const alignLeft = useCallback(() => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const minX = Math.min(...selectedNodes.map(n => n.position.x))
+    setNodes(prev => prev.map(n =>
+      n.selected ? { ...n, position: { ...n.position, x: minX } } : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const alignRight = useCallback(() => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const maxX = Math.max(...selectedNodes.map(n => n.position.x + (n.measured?.width ?? 100)))
+    setNodes(prev => prev.map(n =>
+      n.selected ? { ...n, position: { ...n.position, x: maxX - (n.measured?.width ?? 100) } } : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const alignCenterH = useCallback(() => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const minX = Math.min(...selectedNodes.map(n => n.position.x))
+    const maxX = Math.max(...selectedNodes.map(n => n.position.x + (n.measured?.width ?? 100)))
+    const centerX = (minX + maxX) / 2
+    setNodes(prev => prev.map(n =>
+      n.selected ? { ...n, position: { ...n.position, x: centerX - (n.measured?.width ?? 100) / 2 } } : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const alignTop = useCallback(() => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const minY = Math.min(...selectedNodes.map(n => n.position.y))
+    setNodes(prev => prev.map(n =>
+      n.selected ? { ...n, position: { ...n.position, y: minY } } : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const alignBottom = useCallback(() => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const maxY = Math.max(...selectedNodes.map(n => n.position.y + (n.measured?.height ?? 100)))
+    setNodes(prev => prev.map(n =>
+      n.selected ? { ...n, position: { ...n.position, y: maxY - (n.measured?.height ?? 100) } } : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const alignCenterV = useCallback(() => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const minY = Math.min(...selectedNodes.map(n => n.position.y))
+    const maxY = Math.max(...selectedNodes.map(n => n.position.y + (n.measured?.height ?? 100)))
+    const centerY = (minY + maxY) / 2
+    setNodes(prev => prev.map(n =>
+      n.selected ? { ...n, position: { ...n.position, y: centerY - (n.measured?.height ?? 100) / 2 } } : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  // ── Distribution ───────────────────────────────────────────────────────
+  const distributeHorizontally = useCallback(() => {
+    if (selectedNodes.length < 3) return
+    pushHistory(nodes, edges)
+    const sorted = [...selectedNodes].sort((a, b) => a.position.x - b.position.x)
+    const minX = sorted[0].position.x
+    const maxX = sorted[sorted.length - 1].position.x + (sorted[sorted.length - 1].measured?.width ?? 100)
+    const totalWidth = sorted.reduce((sum, n) => sum + (n.measured?.width ?? 100), 0)
+    const gap = (maxX - minX - totalWidth) / (sorted.length - 1)
+    let cursor = minX
+    const positions: Record<string, number> = {}
+    for (const n of sorted) {
+      positions[n.id] = cursor
+      cursor += (n.measured?.width ?? 100) + gap
+    }
+    setNodes(prev => prev.map(n =>
+      n.selected && positions[n.id] !== undefined
+        ? { ...n, position: { ...n.position, x: positions[n.id] } }
+        : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const distributeVertically = useCallback(() => {
+    if (selectedNodes.length < 3) return
+    pushHistory(nodes, edges)
+    const sorted = [...selectedNodes].sort((a, b) => a.position.y - b.position.y)
+    const minY = sorted[0].position.y
+    const maxY = sorted[sorted.length - 1].position.y + (sorted[sorted.length - 1].measured?.height ?? 100)
+    const totalHeight = sorted.reduce((sum, n) => sum + (n.measured?.height ?? 100), 0)
+    const gap = (maxY - minY - totalHeight) / (sorted.length - 1)
+    let cursor = minY
+    const positions: Record<string, number> = {}
+    for (const n of sorted) {
+      positions[n.id] = cursor
+      cursor += (n.measured?.height ?? 100) + gap
+    }
+    setNodes(prev => prev.map(n =>
+      n.selected && positions[n.id] !== undefined
+        ? { ...n, position: { ...n.position, y: positions[n.id] } }
+        : n
+    ))
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  // ── Helpers ────────────────────────────────────────────────────────────
+  const canAlign = selectedNodes.length >= 2
+  const canDistribute = selectedNodes.length >= 3
+
+  // ── Grouping ───────────────────────────────────────────────────────────
+  const groupSelection = useCallback((groupType: string = 'custom') => {
+    if (selectedNodes.length < 2) return
+    pushHistory(nodes, edges)
+    const PADDING = 24
+    const minX = Math.min(...selectedNodes.map(n => n.position.x)) - PADDING
+    const minY = Math.min(...selectedNodes.map(n => n.position.y)) - PADDING
+    const maxX = Math.max(...selectedNodes.map(n => n.position.x + (n.measured?.width ?? 100))) + PADDING
+    const maxY = Math.max(...selectedNodes.map(n => n.position.y + (n.measured?.height ?? 100))) + PADDING
+    const groupId = `group-${Date.now()}`
+    const groupNode: Node = {
+      id: groupId,
+      type: 'group',
+      position: { x: minX, y: minY },
+      style: { width: maxX - minX, height: maxY - minY },
+      data: { label: groupType.charAt(0).toUpperCase() + groupType.slice(1), groupType },
+      selected: false,
+    }
+    setNodes(prev => [
+      groupNode,
+      ...prev.map(n =>
+        n.selected
+          ? {
+              ...n,
+              parentId: groupId,
+              extent: 'parent' as const,
+              position: { x: n.position.x - minX, y: n.position.y - minY },
+              selected: false,
+            }
+          : n
+      ),
+    ])
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const ungroupSelection = useCallback(() => {
+    const selectedGroups = selectedNodes.filter(n => n.type === 'group')
+    if (selectedGroups.length === 0) return
+    pushHistory(nodes, edges)
+    const groupIds = new Set(selectedGroups.map(g => g.id))
+    setNodes(prev => {
+      const groupPositions: Record<string, { x: number; y: number }> = {}
+      for (const n of prev) {
+        if (groupIds.has(n.id)) groupPositions[n.id] = n.position
+      }
+      return prev
+        .filter(n => !groupIds.has(n.id))
+        .map(n => {
+          if (n.parentId && groupIds.has(n.parentId)) {
+            const gPos = groupPositions[n.parentId] ?? { x: 0, y: 0 }
+            return {
+              ...n,
+              parentId: undefined,
+              extent: undefined,
+              position: { x: gPos.x + n.position.x, y: gPos.y + n.position.y },
+            }
+          }
+          return n
+        })
+    })
+  }, [nodes, edges, selectedNodes, pushHistory, setNodes])
+
+  const canGroup = selectedNodes.length >= 2 && !selectedNodes.some(n => n.type === 'group')
+  const canUngroup = selectedNodes.some(n => n.type === 'group')
+
+  return {
+    alignLeft,
+    alignRight,
+    alignCenterH,
+    alignTop,
+    alignBottom,
+    alignCenterV,
+    distributeHorizontally,
+    distributeVertically,
+    canAlign,
+    canDistribute,
+    selectedNodes,
+    groupSelection,
+    ungroupSelection,
+    canGroup,
+    canUngroup,
+  }
+}

frontend/src/components/network/nodes/DeviceNode.tsx

@@ -0,0 +1,180 @@
+import { memo, useState, useRef, useEffect } from 'react'
+import { Position, NodeResizer, useReactFlow, type NodeProps } from '@xyflow/react'
+import { BaseNode, BaseNodeHeader, BaseNodeContent } from '../ui/base-node'
+import { BaseHandle } from '../ui/base-handle'
+import { NodeStatusIndicator, type NodeStatus } from '../ui/node-status-indicator'
+import { NodeTooltip, NodeTooltipTrigger, NodeTooltipContent } from '../ui/node-tooltip'
+import { getDeviceRenderConfig, CATEGORY_LABELS } from './deviceRegistry'
+import { cn } from '@/lib/utils'
+import type { DeviceProperties } from '@/types'
+
+export interface DeviceNodeData {
+  label: string
+  deviceType: string
+  category?: string
+  properties: DeviceProperties
+  [key: string]: unknown
+}
+
+function TooltipRow({ label, value }: { label: string; value: string | null | undefined }) {
+  if (!value) return null
+  return (
+    <div className="flex gap-2">
+      <span className="text-[10px] uppercase tracking-wider text-muted-foreground">{label}</span>
+      <span className="text-xs font-mono text-primary">{value}</span>
+    </div>
+  )
+}
+
+const NODE_DEFAULT = 120  // default square side in px
+const NODE_MIN = 80       // minimum square side in px
+const NODE_MAX = 280      // maximum square side in px
+
+function DeviceNodeComponent({ id, data, selected, width, height }: NodeProps) {
+  const nodeData = data as unknown as DeviceNodeData
+  const { icon: Icon, color, accentClass, surfaceClass, category } = getDeviceRenderConfig(nodeData.deviceType, nodeData.category)
+  const status = (nodeData.properties?.status || 'unknown') as NodeStatus
+  const ip = nodeData.properties?.ip
+  const props = nodeData.properties || {}
+
+  // Use the shorter dimension so content never overflows a non-square node
+  const size = Math.min(width ?? NODE_DEFAULT, height ?? NODE_DEFAULT)
+  const scale = size / NODE_DEFAULT
+
+  // Icon: 28px at default, clamped to [14, 72]
+  const iconPx = Math.round(Math.max(14, Math.min(72, scale * 28)))
+  // Label font: 11px at default, clamped to [9, 20]
+  const labelPx = Math.max(9, Math.min(20, Math.round(scale * 11)))
+  // IP font: 9px at default, clamped to [8, 16]
+  const ipPx = Math.max(8, Math.min(16, Math.round(scale * 9)))
+  const metaPx = Math.max(8, Math.min(11, Math.round(scale * 8)))
+  const iconPlateSize = Math.round(Math.max(34, Math.min(82, scale * 50)))
+
+  const [editing, setEditing] = useState(false)
+  const [labelValue, setLabelValue] = useState(nodeData.label ?? '')
+  const inputRef = useRef<HTMLInputElement>(null)
+  const { updateNodeData } = useReactFlow()
+
+  useEffect(() => {
+    if (editing) {
+      inputRef.current?.focus()
+      inputRef.current?.select()
+    }
+  }, [editing])
+
+  // Sync if data.label changes externally (e.g. undo/redo)
+  useEffect(() => {
+    if (!editing) setLabelValue(nodeData.label ?? '')
+  }, [nodeData.label, editing])
+
+  const hasTooltipContent = props.hostname || props.ip || props.vendor || props.model || props.role || props.notes
+
+  return (
+    <>
+      <NodeResizer
+        isVisible={selected}
+        minWidth={NODE_MIN}
+        minHeight={NODE_MIN}
+        maxWidth={NODE_MAX}
+        maxHeight={NODE_MAX}
+        keepAspectRatio
+        lineStyle={{ borderColor: 'var(--color-accent)', borderWidth: 1 }}
+        handleStyle={{ width: 8, height: 8, borderColor: 'var(--color-accent)', background: 'var(--color-card)' }}
+      />
+      <NodeStatusIndicator status={status}>
+        <NodeTooltip>
+          <NodeTooltipTrigger>
+            <BaseNode className="group h-full w-full bg-card">
+              <div className={cn('pointer-events-none absolute inset-x-0 top-0 h-10 bg-gradient-to-b opacity-80', surfaceClass)} />
+              <BaseNodeHeader className="flex h-full flex-col items-center justify-center gap-2 px-2 py-3">
+                <div
+                  className={cn(
+                    'relative flex items-center justify-center rounded-xl border transition-colors',
+                    accentClass,
+                  )}
+                  style={{ width: iconPlateSize, height: iconPlateSize }}
+                >
+                  <div className="absolute inset-[4px] rounded-[10px] border border-white/[0.06] bg-sidebar/50" />
+                  <div className="relative z-10">
+                    <Icon size={iconPx} style={{ color }} />
+                  </div>
+                </div>
+                {editing ? (
+                  <input
+                    ref={inputRef}
+                    value={labelValue}
+                    onChange={e => setLabelValue(e.target.value)}
+                    onBlur={() => {
+                      setEditing(false)
+                      if (labelValue !== nodeData.label) {
+                        updateNodeData(id, { ...nodeData, label: labelValue })
+                      }
+                    }}
+                    onKeyDown={e => {
+                      if (e.key === 'Enter') inputRef.current?.blur()
+                      if (e.key === 'Escape') {
+                        setLabelValue(nodeData.label ?? '')
+                        setEditing(false)
+                      }
+                      e.stopPropagation()
+                    }}
+                    style={{ fontSize: labelPx }}
+                    className="bg-transparent border-none outline-none text-center text-primary font-medium w-4/5"
+                  />
+                ) : (
+                  <span
+                    style={{ fontSize: labelPx }}
+                    className="max-w-[88%] cursor-default text-center font-medium leading-tight text-primary line-clamp-2"
+                    onDoubleClick={e => {
+                      e.stopPropagation()
+                      setEditing(true)
+                    }}
+                  >
+                    {labelValue}
+                  </span>
+                )}
+                <span
+                  style={{ fontSize: metaPx }}
+                  className="text-[9px] uppercase tracking-[0.16em] text-muted"
+                >
+                  {CATEGORY_LABELS[category] ?? nodeData.deviceType.replace(/-/g, ' ')}
+                </span>
+              </BaseNodeHeader>
+              {ip && (
+                <BaseNodeContent className="items-center pt-0 pb-2">
+                  <span
+                    className="rounded-full border border-default bg-page/70 px-2 py-0.5 font-mono text-muted-foreground"
+                    style={{ fontSize: ipPx }}
+                  >
+                    {ip}
+                  </span>
+                </BaseNodeContent>
+              )}
+              <BaseHandle type="target" position={Position.Top} />
+              <BaseHandle type="source" position={Position.Bottom} />
+              <BaseHandle type="target" position={Position.Left} id="left" />
+              <BaseHandle type="source" position={Position.Right} id="right" />
+            </BaseNode>
+          </NodeTooltipTrigger>
+          {hasTooltipContent && (
+            <NodeTooltipContent position={Position.Top}>
+              <div className="flex flex-col gap-1 min-w-[140px]">
+                <TooltipRow label="Host" value={props.hostname} />
+                <TooltipRow label="IP" value={props.ip} />
+                {(props.vendor || props.model) && (
+                  <TooltipRow label="HW" value={[props.vendor, props.model].filter(Boolean).join(' ')} />
+                )}
+                <TooltipRow label="Role" value={props.role} />
+                {props.notes && (
+                  <TooltipRow label="Notes" value={props.notes.length > 100 ? props.notes.slice(0, 100) + '...' : props.notes} />
+                )}
+              </div>
+            </NodeTooltipContent>
+          )}
+        </NodeTooltip>
+      </NodeStatusIndicator>
+    </>
+  )
+}
+
+export const DeviceNode = memo(DeviceNodeComponent)

frontend/src/components/network/nodes/GroupNode.tsx

@@ -0,0 +1,86 @@
+import { memo, useState, useRef, useEffect } from 'react'
+import { NodeResizer, useReactFlow, type NodeProps } from '@xyflow/react'
+import type { GroupNodeData } from '@/types/network-diagram'
+
+const GROUP_COLORS: Record<string, string> = {
+  subnet: '#60a5fa',
+  vlan:   '#a78bfa',
+  site:   '#34d399',
+  dmz:    '#f87171',
+  custom: '#94a3b8',
+}
+
+const GroupNodeComponent = ({ data, selected, id }: NodeProps) => {
+  const groupData = data as GroupNodeData
+  const color = GROUP_COLORS[groupData.groupType] ?? GROUP_COLORS.custom
+  const [editing, setEditing] = useState(false)
+  const [labelValue, setLabelValue] = useState(groupData.label ?? '')
+  const inputRef = useRef<HTMLInputElement>(null)
+  const { updateNodeData } = useReactFlow()
+
+  useEffect(() => {
+    if (editing) inputRef.current?.focus()
+  }, [editing])
+
+  // Sync if external data.label changes
+  useEffect(() => {
+    if (!editing) setLabelValue(groupData.label ?? '')
+  }, [groupData.label, editing])
+
+  const handleLabelCommit = () => {
+    setEditing(false)
+    if (labelValue !== groupData.label) {
+      updateNodeData(id, { ...groupData, label: labelValue })
+    }
+  }
+
+  return (
+    <>
+      <NodeResizer
+        isVisible={selected}
+        minWidth={120}
+        minHeight={80}
+        lineStyle={{ border: `1px solid ${color}` }}
+        handleStyle={{ width: 8, height: 8, borderRadius: 2, background: color }}
+      />
+      <div
+        className="w-full h-full rounded-lg relative"
+        style={{
+          border: `1.5px dashed ${color}`,
+          background: `${color}0d`,
+          boxSizing: 'border-box',
+        }}
+      >
+        <div className="absolute top-0 left-2 -translate-y-full pb-0.5">
+          {editing ? (
+            <input
+              ref={inputRef}
+              value={labelValue}
+              onChange={e => setLabelValue(e.target.value)}
+              onBlur={handleLabelCommit}
+              onKeyDown={e => {
+                if (e.key === 'Enter' || e.key === 'Escape') handleLabelCommit()
+                e.stopPropagation()
+              }}
+              className="rounded-sm px-1.5 py-0.5 text-[11px] font-semibold bg-card/90 border-none outline-none min-w-[40px] max-w-[200px]"
+              style={{ color }}
+            />
+          ) : (
+            <span
+              className="inline-block rounded-sm bg-card/90 px-1.5 py-0.5 text-[11px] font-semibold cursor-text select-none tracking-wide"
+              style={{ color }}
+              onDoubleClick={() => setEditing(true)}
+            >
+              {labelValue || groupData.groupType}
+            </span>
+          )}
+        </div>
+      </div>
+    </>
+  )
+}
+
+GroupNodeComponent.displayName = 'GroupNode'
+
+export const GroupNode = memo(GroupNodeComponent)
+export default GroupNode

frontend/src/components/network/nodes/deviceRegistry.ts

@@ -0,0 +1,161 @@
+import type { LucideIcon } from 'lucide-react'
+import {
+  Router, Network, BrickWallFire, Wifi, Server, Monitor, Boxes, Package, Cloud,
+  Printer, Smartphone, HardDrive, Gauge, Database, CloudCog,
+  Cpu, Tablet, Laptop, BatteryCharging, RectangleVertical,
+  Cable, Camera, KeyRound, Globe, Video, PlugZap, Radio,
+} from 'lucide-react'
+
+export interface DeviceRenderConfig {
+  icon: LucideIcon
+  color: string
+  accentClass: string
+  surfaceClass: string
+  category: string
+}
+
+// Category-semantic color palette — each color carries meaning:
+// Network  (blue)   — backbone connectivity layer
+// Security (orange) — critical/protective elements
+// Compute  (emerald)— running workloads and VMs
+// Endpoint (amber)  — user-facing devices
+// Storage  (violet) — data at rest
+// Cloud    (cyan)   — external/internet-connected
+// Infra    (steel)  — physical/passive hardware
+export const NETWORK_COLOR  = '#60a5fa'
+export const SECURITY_COLOR = '#f87171'
+export const COMPUTE_COLOR  = '#34d399'
+export const ENDPOINT_COLOR = '#fbbf24'
+export const STORAGE_COLOR  = '#a78bfa'
+export const CLOUD_COLOR    = '#67e8f9'
+export const INFRA_COLOR    = '#94a3b8'
+
+const CATEGORY_STYLES: Record<string, Pick<DeviceRenderConfig, 'accentClass' | 'surfaceClass'>> = {
+  network: {
+    accentClass: 'border-sky-400/40 bg-sky-400/12 text-sky-300',
+    surfaceClass: 'from-sky-400/12 via-sky-400/4 to-transparent',
+  },
+  security: {
+    accentClass: 'border-rose-400/40 bg-rose-400/12 text-rose-300',
+    surfaceClass: 'from-rose-400/12 via-rose-400/4 to-transparent',
+  },
+  compute: {
+    accentClass: 'border-emerald-400/40 bg-emerald-400/12 text-emerald-300',
+    surfaceClass: 'from-emerald-400/12 via-emerald-400/4 to-transparent',
+  },
+  storage: {
+    accentClass: 'border-violet-400/40 bg-violet-400/12 text-violet-300',
+    surfaceClass: 'from-violet-400/12 via-violet-400/4 to-transparent',
+  },
+  cloud: {
+    accentClass: 'border-cyan-400/40 bg-cyan-400/12 text-cyan-300',
+    surfaceClass: 'from-cyan-400/12 via-cyan-400/4 to-transparent',
+  },
+  endpoint: {
+    accentClass: 'border-amber-400/40 bg-amber-400/12 text-amber-300',
+    surfaceClass: 'from-amber-400/12 via-amber-400/4 to-transparent',
+  },
+  infrastructure: {
+    accentClass: 'border-slate-400/40 bg-slate-300/10 text-slate-300',
+    surfaceClass: 'from-slate-300/10 via-slate-300/4 to-transparent',
+  },
+}
+
+function makeConfig(
+  icon: LucideIcon,
+  color: string,
+  category: string,
+): DeviceRenderConfig {
+  return {
+    icon,
+    color,
+    category,
+    accentClass: CATEGORY_STYLES[category]?.accentClass ?? CATEGORY_STYLES.infrastructure.accentClass,
+    surfaceClass: CATEGORY_STYLES[category]?.surfaceClass ?? CATEGORY_STYLES.infrastructure.surfaceClass,
+  }
+}
+
+const SYSTEM_DEVICE_ICONS: Record<string, DeviceRenderConfig> = {
+  // Network layer
+  'router':        makeConfig(Router, NETWORK_COLOR, 'network'),
+  'switch':        makeConfig(Network, NETWORK_COLOR, 'network'),
+  'access-point':  makeConfig(Wifi, NETWORK_COLOR, 'network'),
+  'load-balancer': makeConfig(Gauge, NETWORK_COLOR, 'network'),
+
+  // Security
+  'firewall':      makeConfig(BrickWallFire, SECURITY_COLOR, 'security'),
+  'badge-reader':  makeConfig(KeyRound, SECURITY_COLOR, 'security'),
+
+  // Compute
+  'server':        makeConfig(Server, COMPUTE_COLOR, 'compute'),
+  'vm':            makeConfig(Boxes, COMPUTE_COLOR, 'compute'),
+  'container':     makeConfig(Package, COMPUTE_COLOR, 'compute'),
+
+  // Storage
+  'nas':           makeConfig(Database, STORAGE_COLOR, 'storage'),
+  'san':           makeConfig(HardDrive, STORAGE_COLOR, 'storage'),
+  'cloud-storage': makeConfig(CloudCog, STORAGE_COLOR, 'storage'),
+
+  // Cloud / Internet
+  'cloud':         makeConfig(Cloud, CLOUD_COLOR, 'cloud'),
+  'aws':           makeConfig(Cloud, CLOUD_COLOR, 'cloud'),
+  'azure':         makeConfig(Cloud, CLOUD_COLOR, 'cloud'),
+  'gcp':           makeConfig(Cloud, CLOUD_COLOR, 'cloud'),
+  'isp':           makeConfig(Globe, CLOUD_COLOR, 'cloud'),
+
+  // Endpoints
+  'workstation':   makeConfig(Monitor, ENDPOINT_COLOR, 'endpoint'),
+  'laptop':        makeConfig(Laptop, ENDPOINT_COLOR, 'endpoint'),
+  'tablet':        makeConfig(Tablet, ENDPOINT_COLOR, 'endpoint'),
+  'phone':         makeConfig(Smartphone, ENDPOINT_COLOR, 'endpoint'),
+  'printer':       makeConfig(Printer, ENDPOINT_COLOR, 'endpoint'),
+
+  // Infrastructure / physical
+  'ups':           makeConfig(BatteryCharging, INFRA_COLOR, 'infrastructure'),
+  'pdu':           makeConfig(PlugZap, INFRA_COLOR, 'infrastructure'),
+  'rack':          makeConfig(RectangleVertical, INFRA_COLOR, 'infrastructure'),
+  'patch-panel':   makeConfig(Cable, INFRA_COLOR, 'infrastructure'),
+  'camera':        makeConfig(Camera, INFRA_COLOR, 'infrastructure'),
+  'nvr':           makeConfig(Video, INFRA_COLOR, 'infrastructure'),
+  'iot':           makeConfig(Radio, INFRA_COLOR, 'infrastructure'),
+}
+
+const CATEGORY_DEFAULTS: Record<string, DeviceRenderConfig> = {
+  'network':        makeConfig(Router, NETWORK_COLOR, 'network'),
+  'compute':        makeConfig(Server, COMPUTE_COLOR, 'compute'),
+  'storage':        makeConfig(Database, STORAGE_COLOR, 'storage'),
+  'cloud':          makeConfig(Cloud, CLOUD_COLOR, 'cloud'),
+  'endpoint':       makeConfig(Monitor, ENDPOINT_COLOR, 'endpoint'),
+  'infrastructure': makeConfig(PlugZap, INFRA_COLOR, 'infrastructure'),
+  'security':       makeConfig(BrickWallFire, SECURITY_COLOR, 'security'),
+}
+
+const FALLBACK: DeviceRenderConfig = makeConfig(Cpu, INFRA_COLOR, 'infrastructure')
+
+export function getDeviceRenderConfig(slug: string, category?: string): DeviceRenderConfig {
+  if (SYSTEM_DEVICE_ICONS[slug]) return SYSTEM_DEVICE_ICONS[slug]
+  if (category && CATEGORY_DEFAULTS[category]) return CATEGORY_DEFAULTS[category]
+  return FALLBACK
+}
+
+export const CATEGORY_LABELS: Record<string, string> = {
+  'network':        'Network',
+  'compute':        'Compute',
+  'storage':        'Storage',
+  'cloud':          'Cloud',
+  'endpoint':       'Endpoints',
+  'infrastructure': 'Infrastructure',
+  'security':       'Security',
+}
+
+export const CATEGORY_COLORS: Record<string, string> = {
+  'network':        NETWORK_COLOR,
+  'compute':        COMPUTE_COLOR,
+  'storage':        STORAGE_COLOR,
+  'cloud':          CLOUD_COLOR,
+  'endpoint':       ENDPOINT_COLOR,
+  'infrastructure': INFRA_COLOR,
+  'security':       SECURITY_COLOR,
+}
+
+export const CATEGORY_ORDER = ['network', 'compute', 'storage', 'cloud', 'endpoint', 'infrastructure', 'security']

frontend/src/components/network/nodes/nodeTypes.ts

@@ -0,0 +1,7 @@
+import { DeviceNode } from './DeviceNode'
+import { GroupNode } from './GroupNode'
+
+export const nodeTypes = {
+  device: DeviceNode,
+  group: GroupNode,
+}

frontend/src/components/network/panels/AIAssistPanel.tsx

@@ -0,0 +1,168 @@
+import { useState, useCallback } from 'react'
+import { Sparkles, ChevronUp, ChevronDown, AlertTriangle } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { networkDiagramsApi } from '@/api'
+import type { AIGenerateResponse } from '@/types'
+
+interface AIAssistPanelProps {
+  onGenerate: (result: AIGenerateResponse, mode: 'replace' | 'merge') => void
+  getExistingBounds: () => { minX: number; maxX: number; minY: number; maxY: number } | null
+  hasNodes: boolean
+}
+
+export function AIAssistPanel({ onGenerate, getExistingBounds, hasNodes }: AIAssistPanelProps) {
+  const [expanded, setExpanded] = useState(false)
+  const [description, setDescription] = useState('')
+  const [mode, setMode] = useState<'replace' | 'merge'>('replace')
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [replaceConfirm, setReplaceConfirm] = useState(false)
+
+  const handleGenerate = useCallback(async () => {
+    if (!description.trim()) return
+    setLoading(true)
+    setError(null)
+    setReplaceConfirm(false)
+    try {
+      const result = await networkDiagramsApi.aiGenerate({
+        description: description.trim(),
+        mode,
+        existingBounds: mode === 'merge' ? getExistingBounds() : null,
+      })
+      onGenerate(result, mode)
+      setDescription('')
+      setExpanded(false)
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : 'Generation failed. Please try again.'
+      setError(msg)
+    } finally {
+      setLoading(false)
+    }
+  }, [description, mode, onGenerate, getExistingBounds])
+
+  // Reset confirm state when mode changes or panel collapses
+  const handleModeChange = (newMode: 'replace' | 'merge') => {
+    setMode(newMode)
+    setReplaceConfirm(false)
+  }
+
+  const needsReplaceConfirm = mode === 'replace' && hasNodes
+
+  if (!expanded) {
+    return (
+      <div className="border-t border-default bg-card">
+        <button
+          onClick={() => setExpanded(true)}
+          className="flex w-full items-center justify-center gap-2 px-4 py-2 text-xs text-muted-foreground hover:text-primary"
+        >
+          <Sparkles size={14} />
+          AI Generate
+          <ChevronUp size={14} />
+        </button>
+      </div>
+    )
+  }
+
+  return (
+    <div className="border-t border-default bg-card">
+      <div className="flex items-center justify-between border-b border-default px-4 py-2">
+        <div className="flex items-center gap-2 text-xs font-medium text-heading">
+          <Sparkles size={14} />
+          AI Generate
+        </div>
+        <button
+          onClick={() => { setExpanded(false); setReplaceConfirm(false) }}
+          className="text-muted-foreground hover:text-primary"
+        >
+          <ChevronDown size={14} />
+        </button>
+      </div>
+
+      <div className="flex flex-col gap-3 p-4">
+        <div className="flex gap-2">
+          <button
+            onClick={() => handleModeChange('replace')}
+            className={cn(
+              'rounded px-3 py-1 text-xs font-medium transition-colors',
+              mode === 'replace'
+                ? 'bg-accent text-white'
+                : 'border border-default text-muted-foreground hover:text-primary',
+            )}
+          >
+            Generate New
+          </button>
+          <button
+            onClick={() => handleModeChange('merge')}
+            className={cn(
+              'rounded px-3 py-1 text-xs font-medium transition-colors',
+              mode === 'merge'
+                ? 'bg-accent text-white'
+                : 'border border-default text-muted-foreground hover:text-primary',
+            )}
+          >
+            Add to Diagram
+          </button>
+        </div>
+
+        {needsReplaceConfirm && (
+          <div className="flex items-start gap-2 rounded border border-yellow-500/30 bg-yellow-500/5 px-3 py-2">
+            <AlertTriangle size={14} className="mt-0.5 shrink-0 text-yellow-400" />
+            <p className="text-[11px] text-yellow-400">
+              This will replace your current diagram. Save first if needed.
+            </p>
+          </div>
+        )}
+
+        <textarea
+          value={description}
+          onChange={e => setDescription(e.target.value)}
+          placeholder="Describe the network you want to create... e.g. 'Small office with a firewall, core switch, 3 access points, and a file server'"
+          rows={3}
+          disabled={loading}
+          className="w-full resize-none rounded border border-default bg-input px-3 py-2 text-xs text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none disabled:opacity-50"
+        />
+
+        {error && <p className="text-[11px] text-red-400">{error}</p>}
+
+        {loading ? (
+          <div className="flex items-center justify-center gap-2 py-2">
+            <div className="h-4 w-4 animate-spin rounded-full border-2 border-accent border-t-transparent" />
+            <span className="text-xs text-muted-foreground">Generating your network diagram…</span>
+          </div>
+        ) : needsReplaceConfirm && !replaceConfirm ? (
+          <button
+            onClick={() => setReplaceConfirm(true)}
+            disabled={!description.trim()}
+            className="rounded border border-yellow-500/40 bg-yellow-500/10 px-4 py-2 text-xs font-medium text-yellow-400 hover:bg-yellow-500/20 disabled:opacity-50"
+          >
+            Replace Diagram…
+          </button>
+        ) : needsReplaceConfirm && replaceConfirm ? (
+          <div className="flex gap-2">
+            <button
+              onClick={() => setReplaceConfirm(false)}
+              className="flex-1 rounded border border-default px-3 py-2 text-xs text-primary hover:bg-elevated"
+            >
+              Cancel
+            </button>
+            <button
+              onClick={handleGenerate}
+              disabled={!description.trim()}
+              className="flex-1 rounded bg-red-500/20 px-3 py-2 text-xs font-medium text-red-400 hover:bg-red-500/30 disabled:opacity-50"
+            >
+              Yes, Replace
+            </button>
+          </div>
+        ) : (
+          <button
+            onClick={handleGenerate}
+            disabled={!description.trim()}
+            className="rounded bg-accent px-4 py-2 text-xs font-medium text-white hover:bg-accent/90 disabled:opacity-50"
+          >
+            Generate
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/network/panels/DeviceToolbar.tsx

@@ -0,0 +1,227 @@
+import { useState, useMemo, useCallback } from 'react'
+import { Search, Plus, ChevronDown, ChevronRight, X, LayoutGrid, GripVertical, Globe } from 'lucide-react'
+import { getDeviceRenderConfig, CATEGORY_LABELS, CATEGORY_ORDER } from '../nodes/deviceRegistry'
+import type { DeviceTypeResponse, DeviceTypeCreate } from '@/types'
+import { deviceTypesApi } from '@/api'
+
+interface DeviceToolbarProps {
+  deviceTypes: DeviceTypeResponse[]
+  onDeviceTypesChange: () => void
+}
+
+export function DeviceToolbar({ deviceTypes, onDeviceTypesChange }: DeviceToolbarProps) {
+  const [search, setSearch] = useState('')
+  const [collapsedCategories, setCollapsedCategories] = useState<Set<string>>(new Set())
+  const [showAddForm, setShowAddForm] = useState(false)
+  const [newType, setNewType] = useState<DeviceTypeCreate>({ slug: '', label: '', category: 'network' })
+  const [addError, setAddError] = useState<string | null>(null)
+  const [addLoading, setAddLoading] = useState(false)
+
+  const filteredByCategory = useMemo(() => {
+    const lower = search.toLowerCase()
+    const filtered = search
+      ? deviceTypes.filter(dt => dt.label.toLowerCase().includes(lower) || dt.slug.toLowerCase().includes(lower))
+      : deviceTypes
+
+    const grouped: Record<string, DeviceTypeResponse[]> = {}
+    for (const dt of filtered) {
+      if (!grouped[dt.category]) grouped[dt.category] = []
+      grouped[dt.category].push(dt)
+    }
+    return grouped
+  }, [deviceTypes, search])
+
+  const toggleCategory = useCallback((cat: string) => {
+    setCollapsedCategories(prev => {
+      const next = new Set(prev)
+      if (next.has(cat)) next.delete(cat)
+      else next.add(cat)
+      return next
+    })
+  }, [])
+
+  const handleDragStart = useCallback((e: React.DragEvent, deviceType: DeviceTypeResponse) => {
+    e.dataTransfer.setData('application/reactflow-device', JSON.stringify({
+      slug: deviceType.slug,
+      label: deviceType.label,
+      category: deviceType.category,
+    }))
+    e.dataTransfer.effectAllowed = 'move'
+  }, [])
+
+  const handleAddType = useCallback(async () => {
+    if (!newType.slug || !newType.label) {
+      setAddError('Slug and label are required')
+      return
+    }
+    setAddLoading(true)
+    setAddError(null)
+    try {
+      await deviceTypesApi.create(newType)
+      setNewType({ slug: '', label: '', category: 'network' })
+      setShowAddForm(false)
+      onDeviceTypesChange()
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : 'Failed to create device type'
+      setAddError(msg)
+    } finally {
+      setAddLoading(false)
+    }
+  }, [newType, onDeviceTypesChange])
+
+  return (
+    <div className="flex h-full w-[200px] flex-col border-r border-default bg-sidebar">
+      <div className="relative p-2">
+        <Search size={14} className="absolute left-4 top-1/2 -translate-y-1/2 text-muted-foreground" />
+        <input
+          type="text"
+          placeholder="Search devices..."
+          value={search}
+          onChange={e => setSearch(e.target.value)}
+          className="w-full rounded-md border border-default bg-input pl-8 pr-2 py-1.5 text-xs text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none"
+        />
+      </div>
+
+      <div className="flex-1 overflow-y-auto px-2 pb-2">
+        {CATEGORY_ORDER.map(cat => {
+          const items = filteredByCategory[cat] || []
+          const isCloud = cat === 'cloud'
+          const ispMatchesSearch = !search || 'isp'.includes(search.toLowerCase()) || 'internet service provider'.includes(search.toLowerCase())
+          const showIsp = isCloud && ispMatchesSearch
+          if (!items.length && !showIsp) return null
+          const collapsed = collapsedCategories.has(cat)
+          const totalCount = items.length + (showIsp ? 1 : 0)
+
+          return (
+            <div key={cat} className="mb-1">
+              <button
+                onClick={() => toggleCategory(cat)}
+                className="flex w-full items-center gap-1 rounded px-1 py-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground hover:text-primary"
+              >
+                {collapsed ? <ChevronRight size={12} /> : <ChevronDown size={12} />}
+                {CATEGORY_LABELS[cat] || cat}
+                <span className="ml-auto text-[10px] font-normal">{totalCount}</span>
+              </button>
+              {!collapsed && (
+                <div className="flex flex-col gap-0.5">
+                  {items.map(dt => {
+                    const { icon: Icon, color } = getDeviceRenderConfig(dt.slug, dt.category)
+                    return (
+                      <div
+                        key={dt.id}
+                        draggable
+                        onDragStart={e => handleDragStart(e, dt)}
+                        className="flex cursor-grab items-center gap-2 rounded px-2 py-1.5 text-xs text-primary hover:bg-elevated active:cursor-grabbing active:scale-[0.98] transition-transform"
+                      >
+                        <GripVertical size={12} className="shrink-0 text-muted-foreground/50" />
+                        <Icon size={14} style={{ color }} />
+                        <span>{dt.label}</span>
+                      </div>
+                    )
+                  })}
+                  {showIsp && (
+                    <div
+                      draggable
+                      onDragStart={e => {
+                        e.dataTransfer.setData('application/reactflow-device', JSON.stringify({
+                          slug: 'isp',
+                          label: 'ISP',
+                          category: 'cloud',
+                        }))
+                        e.dataTransfer.effectAllowed = 'move'
+                      }}
+                      className="flex cursor-grab items-center gap-2 rounded px-2 py-1.5 text-xs text-primary hover:bg-elevated active:cursor-grabbing active:scale-[0.98] transition-transform"
+                    >
+                      <GripVertical size={12} className="shrink-0 text-muted-foreground/50" />
+                      <Globe size={14} style={{ color: 'var(--color-accent)' }} />
+                      <span>ISP</span>
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+          )
+        })}
+      </div>
+
+      {/* Grouping section */}
+      <div className="mb-1 mt-2 border-t border-default pt-2">
+        <div className="flex items-center gap-1 px-1 py-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+          Grouping
+        </div>
+        <div className="flex flex-col gap-0.5">
+          {[
+            { slug: 'subnet', label: 'Subnet', color: '#60a5fa' },
+            { slug: 'vlan',   label: 'VLAN',   color: '#a78bfa' },
+            { slug: 'site',   label: 'Site',   color: '#34d399' },
+            { slug: 'dmz',    label: 'DMZ',    color: '#f87171' },
+          ].map(item => (
+            <div
+              key={item.slug}
+              draggable
+              onDragStart={e => {
+                e.dataTransfer.setData('application/reactflow-group', JSON.stringify({ slug: item.slug, label: item.label }))
+                e.dataTransfer.effectAllowed = 'move'
+              }}
+              className="flex cursor-grab items-center gap-2 rounded px-2 py-1.5 text-xs text-primary hover:bg-elevated active:cursor-grabbing active:scale-[0.98] transition-transform"
+            >
+              <GripVertical size={12} className="shrink-0 text-muted-foreground/50" />
+              <LayoutGrid size={14} style={{ color: item.color }} />
+              <span>{item.label}</span>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="border-t border-default p-2">
+        {!showAddForm ? (
+          <button
+            onClick={() => setShowAddForm(true)}
+            className="flex w-full items-center justify-center gap-1 rounded border border-default px-2 py-1.5 text-xs text-muted-foreground hover:border-hover hover:text-primary"
+          >
+            <Plus size={12} />
+            Custom Type
+          </button>
+        ) : (
+          <div className="flex flex-col gap-1.5">
+            <div className="flex items-center justify-between">
+              <span className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">New Type</span>
+              <button onClick={() => { setShowAddForm(false); setAddError(null) }} className="text-muted-foreground hover:text-primary">
+                <X size={12} />
+              </button>
+            </div>
+            <input
+              placeholder="slug (e.g. pacs-server)"
+              value={newType.slug}
+              onChange={e => setNewType(prev => ({ ...prev, slug: e.target.value.toLowerCase().replace(/[^a-z0-9-]/g, '') }))}
+              className="rounded border border-default bg-input px-2 py-1 text-xs text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none"
+            />
+            <input
+              placeholder="Label (e.g. PACS Server)"
+              value={newType.label}
+              onChange={e => setNewType(prev => ({ ...prev, label: e.target.value }))}
+              className="rounded border border-default bg-input px-2 py-1 text-xs text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none"
+            />
+            <select
+              value={newType.category}
+              onChange={e => setNewType(prev => ({ ...prev, category: e.target.value }))}
+              className="rounded border border-default bg-input px-2 py-1 text-xs text-primary focus:border-accent focus:outline-none"
+            >
+              {CATEGORY_ORDER.map(c => (
+                <option key={c} value={c}>{CATEGORY_LABELS[c]}</option>
+              ))}
+            </select>
+            {addError && <p className="text-[10px] text-red-400">{addError}</p>}
+            <button
+              onClick={handleAddType}
+              disabled={addLoading}
+              className="rounded bg-accent px-2 py-1 text-xs font-medium text-white hover:bg-accent/90 disabled:opacity-50"
+            >
+              {addLoading ? 'Adding...' : 'Add Type'}
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/network/panels/PropertiesPanel.tsx

@@ -0,0 +1,554 @@
+import { useCallback, useState, useEffect } from 'react'
+import {
+  Trash2, Minus, Spline, GitBranch, CornerUpRight, BringToFront, SendToBack,
+  AlignStartVertical, AlignCenterHorizontal, AlignEndVertical,
+  AlignStartHorizontal, AlignCenterVertical, AlignEndHorizontal,
+  AlignHorizontalSpaceAround, AlignVerticalSpaceAround,
+  BoxSelect, Ungroup, MousePointer,
+} from 'lucide-react'
+import { cn } from '@/lib/utils'
+import type { DeviceProperties, DiagramEdge } from '@/types'
+import type { Node, Edge } from '@xyflow/react'
+import type { DeviceNodeData } from '../nodes/DeviceNode'
+
+interface PropertiesPanelProps {
+  selectedNode: Node | null
+  selectedEdge: Edge | null
+  onNodeUpdate: (nodeId: string, data: Partial<DeviceNodeData>) => void
+  onEdgeUpdate: (edgeId: string, data: Partial<DiagramEdge>) => void
+  onEdgeTypeChange: (edgeId: string, edgeType: string) => void
+  onBringToFront: (nodeId: string) => void
+  onSendToBack: (nodeId: string) => void
+  onDeleteNode: (nodeId: string) => void
+  onDeleteEdge: (edgeId: string) => void
+  selectedNodeCount: number
+  onAlignLeft: () => void
+  onAlignRight: () => void
+  onAlignCenterH: () => void
+  onAlignTop: () => void
+  onAlignBottom: () => void
+  onAlignCenterV: () => void
+  onDistributeH: () => void
+  onDistributeV: () => void
+  canAlign: boolean
+  canDistribute: boolean
+  canGroup: boolean
+  canUngroup: boolean
+  onGroupSelection: (groupType: string) => void
+  onUngroupSelection: () => void
+}
+
+type NodeStatus = 'online' | 'offline' | 'degraded' | 'unknown'
+
+const STATUS_CONFIG: Record<NodeStatus, { color: string; label: string }> = {
+  online:   { color: '#34d399', label: 'Online' },
+  offline:  { color: '#f87171', label: 'Offline' },
+  degraded: { color: '#fbbf24', label: 'Degraded' },
+  unknown:  { color: '#94a3b8', label: 'Unknown' },
+}
+
+const STATUS_OPTIONS = Object.keys(STATUS_CONFIG) as NodeStatus[]
+const CONNECTION_TYPE_OPTIONS = ['ethernet', 'fiber', 'wifi', 'vpn', 'vlan', 'wan'] as const
+
+function FieldLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <label className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+      {children}
+    </label>
+  )
+}
+
+function FieldInput({ value, onChange, placeholder, mono }: {
+  value: string
+  onChange: (val: string) => void
+  placeholder?: string
+  mono?: boolean
+}) {
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={e => onChange(e.target.value)}
+      placeholder={placeholder}
+      className={cn(
+        'w-full rounded border border-default bg-input px-2 py-1.5 text-xs text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none',
+        mono && 'font-mono',
+      )}
+    />
+  )
+}
+
+function SectionDivider({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-2 pt-1">
+      <span className="whitespace-nowrap text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+        {label}
+      </span>
+      <div className="flex-1 border-t border-default" />
+    </div>
+  )
+}
+
+const GROUP_TYPES = [
+  { value: 'subnet', label: 'Subnet' },
+  { value: 'vlan',   label: 'VLAN' },
+  { value: 'site',   label: 'Site' },
+  { value: 'dmz',    label: 'DMZ' },
+  { value: 'custom', label: 'Custom' },
+]
+
+export function PropertiesPanel({
+  selectedNode,
+  selectedEdge,
+  onNodeUpdate,
+  onEdgeUpdate,
+  onEdgeTypeChange,
+  onBringToFront,
+  onSendToBack,
+  onDeleteNode,
+  onDeleteEdge,
+  selectedNodeCount,
+  onAlignLeft,
+  onAlignRight,
+  onAlignCenterH,
+  onAlignTop,
+  onAlignBottom,
+  onAlignCenterV,
+  onDistributeH,
+  onDistributeV,
+  canAlign,
+  canDistribute,
+  canGroup,
+  canUngroup,
+  onGroupSelection,
+  onUngroupSelection,
+}: PropertiesPanelProps) {
+  const [deleteConfirm, setDeleteConfirm] = useState(false)
+  const [pendingGroupType, setPendingGroupType] = useState('subnet')
+
+  // Reset confirm state whenever the selection changes
+  // eslint-disable-next-line react-hooks/set-state-in-effect
+  useEffect(() => { setDeleteConfirm(false) }, [selectedNode?.id, selectedEdge?.id])
+
+  const handlePropertyChange = useCallback((field: keyof DeviceProperties, value: string) => {
+    if (!selectedNode) return
+    const nodeData = selectedNode.data as unknown as DeviceNodeData
+    onNodeUpdate(selectedNode.id, {
+      properties: { ...nodeData.properties, [field]: value },
+    } as Partial<DeviceNodeData>)
+  }, [selectedNode, onNodeUpdate])
+
+  const handleLabelChange = useCallback((value: string) => {
+    if (!selectedNode) return
+    onNodeUpdate(selectedNode.id, { label: value } as Partial<DeviceNodeData>)
+  }, [selectedNode, onNodeUpdate])
+
+  if (!selectedNode && !selectedEdge && selectedNodeCount >= 2) {
+    return (
+      <div className="w-[260px] border-l border-default bg-sidebar flex flex-col">
+        <div className="px-4 py-3 border-b border-default">
+          <div className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
+            {selectedNodeCount} nodes selected
+          </div>
+        </div>
+        <div className="p-3 flex flex-col gap-4">
+          {canAlign && (
+            <div>
+              <div className="text-[10px] font-medium text-muted uppercase tracking-wider mb-2">Align</div>
+              <div className="grid grid-cols-3 gap-1">
+                {([
+                  { label: 'Left', icon: AlignStartVertical, action: onAlignLeft },
+                  { label: 'Center', icon: AlignCenterHorizontal, action: onAlignCenterH },
+                  { label: 'Right', icon: AlignEndVertical, action: onAlignRight },
+                  { label: 'Top', icon: AlignStartHorizontal, action: onAlignTop },
+                  { label: 'Middle', icon: AlignCenterVertical, action: onAlignCenterV },
+                  { label: 'Bottom', icon: AlignEndHorizontal, action: onAlignBottom },
+                ] as const).map(({ label, icon: Icon, action }) => (
+                  <button
+                    key={label}
+                    onClick={action}
+                    title={`Align ${label}`}
+                    className="flex flex-col items-center gap-1 p-2 rounded bg-elevated hover:bg-card border border-default hover:border-hover transition-colors text-muted-foreground hover:text-primary"
+                  >
+                    <Icon size={14} />
+                    <span className="text-[9px]">{label}</span>
+                  </button>
+                ))}
+              </div>
+            </div>
+          )}
+          {canDistribute && (
+            <div>
+              <div className="text-[10px] font-medium text-muted uppercase tracking-wider mb-2">Distribute</div>
+              <div className="grid grid-cols-2 gap-1">
+                <button
+                  onClick={onDistributeH}
+                  className="flex items-center gap-1.5 px-2 py-1.5 rounded bg-elevated hover:bg-card border border-default hover:border-hover transition-colors text-muted-foreground hover:text-primary text-xs"
+                >
+                  <AlignHorizontalSpaceAround size={13} /> Horizontal
+                </button>
+                <button
+                  onClick={onDistributeV}
+                  className="flex items-center gap-1.5 px-2 py-1.5 rounded bg-elevated hover:bg-card border border-default hover:border-hover transition-colors text-muted-foreground hover:text-primary text-xs"
+                >
+                  <AlignVerticalSpaceAround size={13} /> Vertical
+                </button>
+              </div>
+            </div>
+          )}
+          {(canGroup || canUngroup) && (
+            <div className="flex flex-col gap-2">
+              <div className="text-[10px] font-medium text-muted uppercase tracking-wider">Grouping</div>
+              {canGroup && (
+                <div className="flex flex-col gap-1.5">
+                  <select
+                    value={pendingGroupType}
+                    onChange={e => setPendingGroupType(e.target.value)}
+                    className="w-full rounded border border-default bg-input px-2 py-1.5 text-xs text-primary focus:border-accent focus:outline-none"
+                  >
+                    {GROUP_TYPES.map(gt => (
+                      <option key={gt.value} value={gt.value}>{gt.label}</option>
+                    ))}
+                  </select>
+                  <button
+                    onClick={() => onGroupSelection(pendingGroupType)}
+                    className="flex items-center justify-center gap-1.5 px-2 py-1.5 rounded bg-elevated hover:bg-card border border-default hover:border-hover transition-colors text-muted-foreground hover:text-primary text-xs"
+                  >
+                    <BoxSelect size={13} /> Group into {GROUP_TYPES.find(g => g.value === pendingGroupType)?.label}
+                  </button>
+                </div>
+              )}
+              {canUngroup && (
+                <button
+                  onClick={onUngroupSelection}
+                  className="flex items-center justify-center gap-1.5 px-2 py-1.5 rounded bg-elevated hover:bg-card border border-default hover:border-hover transition-colors text-muted-foreground hover:text-primary text-xs"
+                >
+                  <Ungroup size={13} /> Ungroup
+                </button>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  if (!selectedNode && !selectedEdge) {
+    return (
+      <div className="flex h-full w-[260px] flex-col items-center justify-center border-l border-default bg-sidebar px-6">
+        <div className="mb-3 flex h-9 w-9 items-center justify-center rounded-lg border border-default bg-elevated text-muted-foreground">
+          <MousePointer size={15} />
+        </div>
+        <p className="text-center text-xs font-medium text-muted-foreground">
+          Select a device or connection
+        </p>
+        <p className="mt-1 text-center text-[10px] text-muted-foreground/50 leading-relaxed">
+          Properties appear here. Hover a device to see a quick summary.
+        </p>
+      </div>
+    )
+  }
+
+  if (selectedEdge) {
+    const edgeData = (selectedEdge.data || {}) as Record<string, unknown>
+    const connectionType = (edgeData.connectionType as string) || 'ethernet'
+    const isCustomType = !CONNECTION_TYPE_OPTIONS.includes(connectionType as typeof CONNECTION_TYPE_OPTIONS[number])
+
+    return (
+      <div className="flex h-full w-[260px] flex-col border-l border-default bg-sidebar">
+        <div className="border-b border-default px-3 py-2">
+          <h3 className="text-xs font-semibold text-heading">Connection</h3>
+        </div>
+        <div className="flex flex-1 flex-col gap-3 overflow-y-auto p-3">
+          <div className="rounded border border-default bg-elevated/40 px-2.5 py-2 text-[10px] text-muted-foreground">
+            Drag either end of the line on the canvas to reconnect it to a different asset.
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Label</FieldLabel>
+            <FieldInput
+              value={(selectedEdge.label as string) || ''}
+              onChange={val => onEdgeUpdate(selectedEdge.id, { label: val || null })}
+              placeholder="Connection label"
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Type</FieldLabel>
+            <select
+              value={isCustomType ? '__custom__' : connectionType}
+              onChange={e => {
+                const val = e.target.value
+                if (val !== '__custom__') {
+                  onEdgeUpdate(selectedEdge.id, { connectionType: val })
+                }
+              }}
+              className="w-full rounded border border-default bg-input px-2 py-1.5 text-xs text-primary focus:border-accent focus:outline-none"
+            >
+              {CONNECTION_TYPE_OPTIONS.map(opt => (
+                <option key={opt} value={opt}>{opt.charAt(0).toUpperCase() + opt.slice(1)}</option>
+              ))}
+              <option value="__custom__">Custom…</option>
+            </select>
+            {isCustomType && (
+              <FieldInput
+                value={connectionType}
+                onChange={val => onEdgeUpdate(selectedEdge.id, { connectionType: val })}
+                placeholder="Custom type name"
+              />
+            )}
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Speed</FieldLabel>
+            <FieldInput
+              value={(edgeData.speed as string) || ''}
+              onChange={val => onEdgeUpdate(selectedEdge.id, { speed: val || null })}
+              placeholder="e.g. 1 Gbps"
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Notes</FieldLabel>
+            <FieldInput
+              value={(edgeData.notes as string) || ''}
+              onChange={val => onEdgeUpdate(selectedEdge.id, { notes: val || null })}
+              placeholder="Port info, cable type…"
+              mono
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Line Style</FieldLabel>
+            <div className="flex gap-1">
+              {([
+                { value: null, icon: Minus, label: 'Straight' },
+                { value: 'curved', icon: Spline, label: 'Curved' },
+                { value: 'step', icon: GitBranch, label: 'Step' },
+                { value: 'orthogonal', icon: CornerUpRight, label: 'Ortho' },
+              ] as const).map(({ value, icon: Icon, label }) => {
+                const routing = (edgeData.routing as string | null | undefined) ?? null
+                const active = routing === value
+                return (
+                  <button
+                    key={label}
+                    title={label}
+                    onClick={() => onEdgeUpdate(selectedEdge.id, { routing: value })}
+                    className={cn(
+                      'flex flex-1 items-center justify-center gap-1 rounded border py-1.5 text-[10px] transition-colors',
+                      active
+                        ? 'border-accent bg-accent/10 text-accent'
+                        : 'border-default text-muted-foreground hover:border-hover hover:text-primary',
+                    )}
+                  >
+                    <Icon size={12} />
+                    {label}
+                  </button>
+                )
+              })}
+            </div>
+          </div>
+          <div className="flex items-center justify-between">
+            <FieldLabel>Show Traffic</FieldLabel>
+            <button
+              onClick={() => {
+                const newType = selectedEdge.type === 'animated' ? 'connection' : 'animated'
+                onEdgeTypeChange(selectedEdge.id, newType)
+              }}
+              className={cn(
+                'relative h-5 w-9 rounded-full transition-colors',
+                selectedEdge.type === 'animated' ? 'bg-accent' : 'bg-elevated',
+              )}
+            >
+              <span
+                className={cn(
+                  'absolute top-0.5 left-0.5 h-4 w-4 rounded-full bg-white transition-transform',
+                  selectedEdge.type === 'animated' && 'translate-x-4',
+                )}
+              />
+            </button>
+          </div>
+        </div>
+        <div className="border-t border-default p-3">
+          {deleteConfirm ? (
+            <div className="flex flex-col gap-1.5">
+              <p className="text-center text-[10px] text-muted-foreground">Delete this connection?</p>
+              <div className="flex gap-1.5">
+                <button
+                  onClick={() => setDeleteConfirm(false)}
+                  className="flex-1 rounded border border-default px-2 py-1.5 text-xs text-primary hover:bg-elevated"
+                >
+                  Cancel
+                </button>
+                <button
+                  onClick={() => onDeleteEdge(selectedEdge.id)}
+                  className="flex-1 rounded bg-red-500/20 px-2 py-1.5 text-xs font-medium text-red-400 hover:bg-red-500/30"
+                >
+                  Delete
+                </button>
+              </div>
+            </div>
+          ) : (
+            <button
+              onClick={() => setDeleteConfirm(true)}
+              className="flex w-full items-center justify-center gap-1.5 rounded border border-red-500/30 px-2 py-1.5 text-xs text-red-400 hover:bg-red-500/10"
+            >
+              <Trash2 size={12} />
+              Delete Connection
+            </button>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  const nodeData = selectedNode!.data as unknown as DeviceNodeData
+  const props = nodeData.properties || {} as DeviceProperties
+  const currentStatus = (props.status || 'unknown') as NodeStatus
+
+  return (
+    <div className="flex h-full w-[260px] flex-col border-l border-default bg-sidebar">
+      <div className="border-b border-default px-3 py-2">
+        <h3 className="text-xs font-semibold text-heading">Device Properties</h3>
+      </div>
+
+      <div className="flex flex-1 flex-col gap-3 overflow-y-auto p-3">
+
+        {/* Identity */}
+        <div className="flex flex-col gap-1">
+          <FieldLabel>Name</FieldLabel>
+          <FieldInput value={nodeData.label} onChange={handleLabelChange} placeholder="Device name" />
+        </div>
+
+        {/* Layering */}
+        <div className="flex flex-col gap-1">
+          <FieldLabel>Layer</FieldLabel>
+          <div className="flex gap-1.5">
+            <button
+              onClick={() => onBringToFront(selectedNode!.id)}
+              title="Bring to Front  ]"
+              className="flex flex-1 items-center justify-center gap-1.5 rounded border border-default px-2 py-1.5 text-[10px] text-muted-foreground hover:border-hover hover:text-primary"
+            >
+              <BringToFront size={12} />
+              Bring Front
+            </button>
+            <button
+              onClick={() => onSendToBack(selectedNode!.id)}
+              title="Send to Back  ["
+              className="flex flex-1 items-center justify-center gap-1.5 rounded border border-default px-2 py-1.5 text-[10px] text-muted-foreground hover:border-hover hover:text-primary"
+            >
+              <SendToBack size={12} />
+              Send Back
+            </button>
+          </div>
+        </div>
+
+        {/* Status badge grid */}
+        <div className="flex flex-col gap-1.5">
+          <FieldLabel>Status</FieldLabel>
+          <div className="grid grid-cols-2 gap-1">
+            {STATUS_OPTIONS.map(opt => {
+              const { color, label } = STATUS_CONFIG[opt]
+              const active = currentStatus === opt
+              return (
+                <button
+                  key={opt}
+                  onClick={() => handlePropertyChange('status', opt)}
+                  className={cn(
+                    'flex items-center justify-center gap-1.5 rounded border py-1.5 text-[10px] font-medium transition-colors',
+                    active
+                      ? 'border-transparent text-white'
+                      : 'border-default text-muted-foreground hover:border-hover hover:text-primary',
+                  )}
+                  style={active ? { backgroundColor: color } : undefined}
+                >
+                  <span
+                    className="h-1.5 w-1.5 shrink-0 rounded-full"
+                    style={{ backgroundColor: active ? 'rgba(255,255,255,0.8)' : color }}
+                  />
+                  {label}
+                </button>
+              )
+            })}
+          </div>
+        </div>
+
+        {/* Network section */}
+        <SectionDivider label="Network" />
+        <div className="flex flex-col gap-2">
+          <div className="flex flex-col gap-1">
+            <FieldLabel>IP Address</FieldLabel>
+            <FieldInput value={props.ip || ''} onChange={v => handlePropertyChange('ip', v)} placeholder="e.g. 10.0.0.1" mono />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Subnet</FieldLabel>
+            <FieldInput value={props.subnet || ''} onChange={v => handlePropertyChange('subnet', v)} placeholder="e.g. 10.0.0.0/24" mono />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>VLAN</FieldLabel>
+            <FieldInput value={props.vlan || ''} onChange={v => handlePropertyChange('vlan', v)} placeholder="e.g. 10" mono />
+          </div>
+        </div>
+
+        {/* Hardware section */}
+        <SectionDivider label="Hardware" />
+        <div className="flex flex-col gap-2">
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Hostname</FieldLabel>
+            <FieldInput value={props.hostname || ''} onChange={v => handlePropertyChange('hostname', v)} placeholder="e.g. core-rtr-01" mono />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Vendor</FieldLabel>
+            <FieldInput value={props.vendor || ''} onChange={v => handlePropertyChange('vendor', v)} placeholder="e.g. Cisco" />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Model</FieldLabel>
+            <FieldInput value={props.model || ''} onChange={v => handlePropertyChange('model', v)} placeholder="e.g. ISR 4331" />
+          </div>
+          <div className="flex flex-col gap-1">
+            <FieldLabel>Role</FieldLabel>
+            <FieldInput value={props.role || ''} onChange={v => handlePropertyChange('role', v)} placeholder="e.g. Core gateway" />
+          </div>
+        </div>
+
+        {/* Notes */}
+        <SectionDivider label="Notes" />
+        <div className="flex flex-col gap-1">
+          <textarea
+            value={props.notes || ''}
+            onChange={e => handlePropertyChange('notes', e.target.value)}
+            placeholder="Additional notes…"
+            rows={3}
+            className="w-full resize-none rounded border border-default bg-input px-2 py-1.5 text-xs text-primary placeholder:text-muted-foreground focus:border-accent focus:outline-none"
+          />
+        </div>
+
+      </div>
+
+      <div className="border-t border-default p-3">
+        {deleteConfirm ? (
+          <div className="flex flex-col gap-1.5">
+            <p className="text-center text-[10px] text-muted-foreground">Delete this device?</p>
+            <div className="flex gap-1.5">
+              <button
+                onClick={() => setDeleteConfirm(false)}
+                className="flex-1 rounded border border-default px-2 py-1.5 text-xs text-primary hover:bg-elevated"
+              >
+                Cancel
+              </button>
+              <button
+                onClick={() => onDeleteNode(selectedNode!.id)}
+                className="flex-1 rounded bg-red-500/20 px-2 py-1.5 text-xs font-medium text-red-400 hover:bg-red-500/30"
+              >
+                Delete
+              </button>
+            </div>
+          </div>
+        ) : (
+          <button
+            onClick={() => setDeleteConfirm(true)}
+            className="flex w-full items-center justify-center gap-1.5 rounded border border-red-500/30 px-2 py-1.5 text-xs text-red-400 hover:bg-red-500/10"
+          >
+            <Trash2 size={12} />
+            Delete Device
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/network/ui/animated-svg-edge.tsx

@@ -0,0 +1,131 @@
+import { memo } from 'react'
+import {
+  BaseEdge,
+  getSmoothStepPath,
+  getStraightPath,
+  getBezierPath,
+  type EdgeProps,
+} from '@xyflow/react'
+
+interface AnimatedEdgeData {
+  connectionType?: string
+  duration?: number
+  direction?: 'forward' | 'reverse' | 'alternate' | 'alternate-reverse'
+  path?: 'bezier' | 'smoothstep' | 'step' | 'straight'
+  repeat?: number | 'indefinite'
+  shape?: 'circle' | 'package'
+  speed?: string | null
+  notes?: string | null
+  [key: string]: unknown
+}
+
+const CONNECTION_COLORS: Record<string, string> = {
+  ethernet: '#60a5fa',
+  fiber: '#34d399',
+  wifi: '#a78bfa',
+  vpn: '#eab308',
+  vlan: '#848b9b',
+  wan: '#f87171',
+}
+
+const DEFAULT_COLOR = '#848b9b'
+
+function getPath(
+  props: EdgeProps,
+  pathType: string,
+): [string, number, number] {
+  const params = {
+    sourceX: props.sourceX,
+    sourceY: props.sourceY,
+    sourcePosition: props.sourcePosition,
+    targetX: props.targetX,
+    targetY: props.targetY,
+    targetPosition: props.targetPosition,
+  }
+
+  switch (pathType) {
+    case 'bezier': {
+      const [path, labelX, labelY] = getBezierPath(params)
+      return [path, labelX, labelY]
+    }
+    case 'straight': {
+      const [path, labelX, labelY] = getStraightPath(params)
+      return [path, labelX, labelY]
+    }
+    default: {
+      const [path, labelX, labelY] = getSmoothStepPath(params)
+      return [path, labelX, labelY]
+    }
+  }
+}
+
+function getAnimateMotionProps(data: AnimatedEdgeData) {
+  const duration = data.duration ?? 2
+  const direction = data.direction ?? 'forward'
+  const repeat = data.repeat ?? 'indefinite'
+
+  const keyPoints: Record<string, string> = {
+    forward: '0;1',
+    reverse: '1;0',
+    alternate: '0;1',
+    'alternate-reverse': '1;0',
+  }
+
+  return {
+    dur: `${duration}s`,
+    repeatCount: String(repeat),
+    keyPoints: keyPoints[direction] || '0;1',
+    keyTimes: '0;1',
+  }
+}
+
+function AnimatedSvgEdgeComponent(props: EdgeProps) {
+  const data = (props.data || {}) as AnimatedEdgeData
+  const connectionType = data.connectionType || 'ethernet'
+  const color = CONNECTION_COLORS[connectionType] || DEFAULT_COLOR
+  const pathType = data.path ?? 'smoothstep'
+  const shape = data.shape ?? 'circle'
+
+  const [edgePath] = getPath(props, pathType)
+  const motionProps = getAnimateMotionProps(data)
+
+  return (
+    <>
+      <BaseEdge
+        path={edgePath}
+        style={{
+          stroke: color,
+          strokeWidth: props.selected ? 3 : 2,
+          ...(connectionType === 'wifi' || connectionType === 'wan' || connectionType === 'vpn'
+            ? { strokeDasharray: connectionType === 'wifi' ? '3,3' : '8,4' }
+            : {}),
+        }}
+      />
+      <circle r={0} fill={color}>
+        <animateMotion
+          path={edgePath}
+          calcMode="linear"
+          {...motionProps}
+        />
+        <animate
+          attributeName="r"
+          values="0;3;3;3;0"
+          keyTimes="0;0.05;0.5;0.95;1"
+          dur={motionProps.dur}
+          repeatCount={motionProps.repeatCount}
+        />
+      </circle>
+      {shape === 'package' && (
+        <rect x={-4} y={-4} width={8} height={8} rx={2} fill={color} opacity={0.8}>
+          <animateMotion
+            path={edgePath}
+            calcMode="linear"
+            {...motionProps}
+          />
+        </rect>
+      )}
+    </>
+  )
+}
+
+export const AnimatedSvgEdge = memo(AnimatedSvgEdgeComponent)

frontend/src/components/network/ui/base-handle.tsx

@@ -0,0 +1,21 @@
+import type { ComponentProps } from 'react'
+import { Handle, type HandleProps } from '@xyflow/react'
+import { cn } from '@/lib/utils'
+
+export type BaseHandleProps = HandleProps
+
+export function BaseHandle({ className, children, ...props }: ComponentProps<typeof Handle>) {
+  return (
+    <Handle
+      {...props}
+      className={cn(
+        'h-3 w-3 rounded-full border border-accent/60 bg-card transition-opacity',
+        'opacity-0 group-hover:opacity-100 group-focus-within:opacity-100',
+        '[.rf-connect-mode_&]:opacity-100',
+        className,
+      )}
+    >
+      {children}
+    </Handle>
+  )
+}

frontend/src/components/network/ui/base-node.tsx

@@ -0,0 +1,56 @@
+import type { ComponentProps } from 'react'
+import { cn } from '@/lib/utils'
+
+export function BaseNode({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      className={cn(
+        'bg-card text-heading relative overflow-hidden rounded-xl border border-default',
+        'transition-colors hover:border-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40',
+        'in-[.selected]:border-accent',
+        className,
+      )}
+      tabIndex={0}
+      {...props}
+    />
+  )
+}
+
+export function BaseNodeHeader({ className, ...props }: ComponentProps<'header'>) {
+  return (
+    <header
+      {...props}
+      className={cn('flex flex-row items-center gap-2 px-3 py-2', className)}
+    />
+  )
+}
+
+export function BaseNodeHeaderTitle({ className, ...props }: ComponentProps<'h3'>) {
+  return (
+    <h3
+      data-slot="base-node-title"
+      className={cn('select-none flex-1 text-xs font-semibold text-heading', className)}
+      {...props}
+    />
+  )
+}
+
+export function BaseNodeContent({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="base-node-content"
+      className={cn('flex flex-col gap-y-1 px-3 pb-2', className)}
+      {...props}
+    />
+  )
+}
+
+export function BaseNodeFooter({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="base-node-footer"
+      className={cn('flex flex-col items-center gap-y-1 border-t border-default px-3 pt-1.5 pb-2', className)}
+      {...props}
+    />
+  )
+}

frontend/src/components/network/ui/labeled-group-node.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode, ComponentProps } from 'react'
+import { Panel, NodeResizer, type NodeProps, type PanelPosition } from '@xyflow/react'
+import { BaseNode } from './base-node'
+import { cn } from '@/lib/utils'
+
+export type GroupNodeLabelProps = ComponentProps<'div'>
+
+export function GroupNodeLabel({ children, className, ...props }: GroupNodeLabelProps) {
+  return (
+    <div className="h-full w-full" {...props}>
+      <div className={cn('bg-card text-muted-foreground w-fit p-2 text-[10px] font-semibold uppercase tracking-wider', className)}>
+        {children}
+      </div>
+    </div>
+  )
+}
+
+export interface GroupNodeData {
+  label?: string
+  groupType?: string
+  [key: string]: unknown
+}
+
+export type GroupNodeProps = Partial<NodeProps> & {
+  label?: ReactNode
+  position?: PanelPosition
+}
+
+function getLabelClassName(position?: PanelPosition): string {
+  switch (position) {
+    case 'top-left': return 'rounded-br-sm'
+    case 'top-center': return 'rounded-b-sm'
+    case 'top-right': return 'rounded-bl-sm'
+    case 'bottom-left': return 'rounded-tr-sm'
+    case 'bottom-right': return 'rounded-tl-sm'
+    case 'bottom-center': return 'rounded-t-sm'
+    default: return 'rounded-br-sm'
+  }
+}
+
+export function GroupNode({ data, selected }: NodeProps) {
+  const nodeData = data as unknown as GroupNodeData
+  const label = nodeData.label || 'Group'
+
+  return (
+    <>
+      <NodeResizer
+        isVisible={selected}
+        minWidth={150}
+        minHeight={100}
+        lineStyle={{ borderColor: 'var(--color-accent)', borderWidth: 1 }}
+        handleStyle={{ width: 8, height: 8, borderColor: 'var(--color-accent)', background: 'var(--color-card)' }}
+      />
+      <BaseNode
+        className={cn(
+          'h-full w-full min-h-[100px] min-w-[150px] overflow-hidden rounded-lg bg-elevated/30 border-default/50',
+          selected && 'border-accent',
+        )}
+      >
+        <Panel className="m-0 p-0" position="top-left">
+          <GroupNodeLabel className={getLabelClassName('top-left')}>
+            {label}
+          </GroupNodeLabel>
+        </Panel>
+      </BaseNode>
+    </>
+  )
+}

frontend/src/components/network/ui/labeled-handle.tsx

@@ -0,0 +1,39 @@
+import type { ComponentProps } from 'react'
+import { type HandleProps, Position } from '@xyflow/react'
+import { cn } from '@/lib/utils'
+import { BaseHandle } from './base-handle'
+
+const flexDirections: Record<string, string> = {
+  [Position.Top]: 'flex-col',
+  [Position.Right]: 'flex-row-reverse justify-end',
+  [Position.Bottom]: 'flex-col-reverse justify-end',
+  [Position.Left]: 'flex-row',
+}
+
+export function LabeledHandle({
+  className,
+  labelClassName,
+  handleClassName,
+  title,
+  position,
+  ...props
+}: HandleProps &
+  ComponentProps<'div'> & {
+    title: string
+    handleClassName?: string
+    labelClassName?: string
+  }) {
+  const { ref, ...handleProps } = props
+  return (
+    <div
+      title={title}
+      className={cn('relative flex items-center', flexDirections[position], className)}
+      ref={ref}
+    >
+      <BaseHandle position={position} className={handleClassName} {...handleProps} />
+      <label className={cn('text-muted-foreground text-[10px] font-mono px-1.5', labelClassName)}>
+        {title}
+      </label>
+    </div>
+  )
+}

frontend/src/components/network/ui/node-status-indicator.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react'
+import { cn } from '@/lib/utils'
+
+export type NodeStatus = 'online' | 'offline' | 'degraded' | 'unknown'
+
+const STATUS_BORDER_COLORS: Record<NodeStatus, string> = {
+  online: 'border-emerald-400',
+  offline: 'border-red-400',
+  degraded: 'border-yellow-400',
+  unknown: '',
+}
+
+const STATUS_GLOW: Record<NodeStatus, string> = {
+  online: 'shadow-[0_0_6px_rgba(52,211,153,0.15)]',
+  offline: 'shadow-[0_0_6px_rgba(248,113,113,0.15)]',
+  degraded: 'shadow-[0_0_6px_rgba(250,204,21,0.15)]',
+  unknown: '',
+}
+
+interface NodeStatusIndicatorProps {
+  status?: NodeStatus
+  children: ReactNode
+  className?: string
+}
+
+export function NodeStatusIndicator({ status = 'unknown', children, className }: NodeStatusIndicatorProps) {
+  if (status === 'unknown') {
+    return <>{children}</>
+  }
+
+  return (
+    <div
+      className={cn(
+        'w-full h-full rounded-lg border-2 transition-colors',
+        STATUS_BORDER_COLORS[status],
+        STATUS_GLOW[status],
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}

frontend/src/components/network/ui/node-tooltip.tsx

@@ -0,0 +1,79 @@
+import { createContext, useContext, useState, useCallback, type ReactNode, type ComponentProps } from 'react'
+import { NodeToolbar, type NodeToolbarProps } from '@xyflow/react'
+import { cn } from '@/lib/utils'
+
+interface NodeTooltipContextValue {
+  visible: boolean
+  show: () => void
+  hide: () => void
+}
+
+const NodeTooltipContext = createContext<NodeTooltipContextValue>({
+  visible: false,
+  show: () => {},
+  hide: () => {},
+})
+
+export function NodeTooltip({ children, className, ...props }: ComponentProps<'div'>) {
+  const [visible, setVisible] = useState(false)
+  const show = useCallback(() => setVisible(true), [])
+  const hide = useCallback(() => setVisible(false), [])
+
+  return (
+    <NodeTooltipContext.Provider value={{ visible, show, hide }}>
+      <div className={cn('w-full h-full', className)} {...props}>{children}</div>
+    </NodeTooltipContext.Provider>
+  )
+}
+
+export function NodeTooltipTrigger({
+  children,
+  className,
+  onMouseEnter,
+  onMouseLeave,
+  ...props
+}: ComponentProps<'div'>) {
+  const { show, hide } = useContext(NodeTooltipContext)
+
+  return (
+    <div
+      className={cn('w-full h-full', className)}
+      onMouseEnter={(e) => {
+        show()
+        onMouseEnter?.(e)
+      }}
+      onMouseLeave={(e) => {
+        hide()
+        onMouseLeave?.(e)
+      }}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
+export function NodeTooltipContent({
+  className,
+  position,
+  children,
+  ...props
+}: Omit<NodeToolbarProps, 'children'> & { children: ReactNode }) {
+  const { visible } = useContext(NodeTooltipContext)
+
+  if (!visible) return null
+
+  return (
+    <NodeToolbar
+      position={position}
+      className={cn(
+        'rounded-lg border border-default bg-elevated px-3 py-2',
+        'pointer-events-none',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </NodeToolbar>
+  )
+}

frontend/src/hooks/useFlowPilotSession.ts

@@ -99,9 +99,14 @@ export function useFlowPilotSession(): UseFlowPilotSession {
       setAllSteps([firstStep])
       setCurrentStep(firstStep)
     } catch (e: unknown) {
-      const message = e instanceof Error ? e.message : 'Failed to start session'
+      // Prefer the backend's detail message over the generic axios status string
+      const detail = (e as any)?.response?.data?.detail
+      const message = typeof detail === 'string' ? detail : (e instanceof Error ? e.message : 'Failed to start session')
       setError(message)
-      toast.error(message)
+      // Global axios interceptor already shows a toast for 5xx — skip duplicate
+      if (!(e as any)?.response?.status || (e as any)?.response?.status < 500) {
+        toast.error(message)
+      }
     } finally {
       setIsLoading(false)
     }

frontend/src/index.css

@@ -445,3 +445,42 @@
     scroll-behavior: auto !important;
   }
 }
+
+/* ── Print / PDF export ───────────────────────────────────────────────── */
+@media print {
+  /* Hide everything that isn't the canvas */
+  body > * { display: none !important; }
+
+  /* Show only the React Flow viewport inside the diagram editor page */
+  #root { display: block !important; }
+  #root > * { display: none !important; }
+
+  /* The diagram editor mounts as a child of the app shell — target the canvas wrapper */
+  .react-flow__renderer,
+  .react-flow__viewport,
+  .react-flow {
+    display: block !important;
+  }
+
+  /* Make the canvas fill the printed page */
+  .react-flow {
+    position: fixed !important;
+    inset: 0 !important;
+    width: 100vw !important;
+    height: 100vh !important;
+    background: #ffffff !important;
+  }
+
+  /* Force light backgrounds on nodes so they're readable on white paper */
+  .react-flow__node {
+    print-color-adjust: exact;
+    -webkit-print-color-adjust: exact;
+  }
+
+  /* Hide UI chrome */
+  .react-flow__controls,
+  .react-flow__minimap,
+  .react-flow__panel {
+    display: none !important;
+  }
+}

frontend/src/lib/drawio-export.ts

@@ -0,0 +1,99 @@
+import type { Node, Edge } from '@xyflow/react'
+import type { DeviceNodeData } from '@/components/network/nodes/DeviceNode'
+import type { GroupNodeData } from '@/types/network-diagram'
+
+// Maps our device slugs to draw.io Cisco stencil shape styles
+const SLUG_TO_DRAWIO_STYLE: Record<string, string> = {
+  'router':        'shape=mxgraph.cisco.routers.router;',
+  'switch':        'shape=mxgraph.cisco.switches.layer_3_switch;',
+  'access-point':  'shape=mxgraph.cisco.misc.access_point;',
+  'load-balancer': 'shape=mxgraph.cisco.misc.generic_building;',
+  'firewall':      'shape=mxgraph.cisco.firewalls.firewall;',
+  'badge-reader':  'shape=mxgraph.cisco.misc.generic_building;',
+  'server':        'shape=mxgraph.cisco.servers.standard_server;',
+  'vm':            'shape=mxgraph.cisco.servers.standard_server;',
+  'container':     'shape=mxgraph.cisco.servers.standard_server;',
+  'nas':           'shape=mxgraph.cisco.storage.tape_storage_library;',
+  'san':           'shape=mxgraph.cisco.storage.tape_storage_library;',
+  'cloud-storage': 'shape=mxgraph.cisco.misc.cloud;',
+  'cloud':         'shape=mxgraph.cisco.misc.cloud;',
+  'aws':           'shape=mxgraph.cisco.misc.cloud;',
+  'azure':         'shape=mxgraph.cisco.misc.cloud;',
+  'gcp':           'shape=mxgraph.cisco.misc.cloud;',
+  'isp':           'shape=mxgraph.cisco.misc.cloud;',
+  'workstation':   'shape=mxgraph.cisco.computers_and_peripherals.pc;',
+  'laptop':        'shape=mxgraph.cisco.computers_and_peripherals.laptop;',
+  'tablet':        'shape=mxgraph.cisco.computers_and_peripherals.laptop;',
+  'phone':         'shape=mxgraph.cisco.computers_and_peripherals.ip_phone;',
+  'printer':       'shape=mxgraph.cisco.computers_and_peripherals.printer;',
+  'ups':           'shape=mxgraph.cisco.misc.generic_building;',
+  'pdu':           'shape=mxgraph.cisco.misc.generic_building;',
+  'rack':          'shape=mxgraph.cisco.misc.generic_building;',
+  'patch-panel':   'shape=mxgraph.cisco.misc.generic_building;',
+  'camera':        'shape=mxgraph.cisco.misc.generic_building;',
+  'nvr':           'shape=mxgraph.cisco.misc.generic_building;',
+  'iot':           'shape=mxgraph.cisco.misc.generic_building;',
+}
+
+const BASE_NODE_STYLE =
+  'sketch=0;html=1;pointerEvents=1;dashed=0;fillColor=#036897;strokeColor=#ffffff;strokeWidth=2;verticalLabelPosition=bottom;verticalAlign=top;align=center;outlineConnect=0;'
+const GROUP_STYLE =
+  'swimlane;fontStyle=0;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;collapsible=0;marginBottom=0;swimlaneHead=0;fillColor=none;'
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+export function exportToDrawio(nodes: Node[], edges: Edge[]): string {
+  const cells: string[] = [
+    '<mxCell id="0"/>',
+    '<mxCell id="1" parent="0"/>',
+  ]
+
+  for (const node of nodes) {
+    const w = typeof node.style?.width === 'number' ? node.style.width : (node.measured?.width ?? 120)
+    const h = typeof node.style?.height === 'number' ? node.style.height : (node.measured?.height ?? 120)
+    const x = node.position.x
+    const y = node.position.y
+    const parentId = node.parentId ?? '1'
+
+    if (node.type === 'group') {
+      const gd = node.data as GroupNodeData
+      cells.push(
+        `<mxCell id="${esc(node.id)}" value="${esc(gd.label ?? '')}" style="${GROUP_STYLE}" vertex="1" parent="${esc(parentId)}">` +
+        `<mxGeometry x="${x}" y="${y}" width="${w}" height="${h}" as="geometry"/>` +
+        `</mxCell>`,
+      )
+    } else {
+      const dd = node.data as DeviceNodeData
+      const slug = dd.deviceType ?? 'server'
+      const shapeStyle = SLUG_TO_DRAWIO_STYLE[slug] ?? 'rounded=1;whiteSpace=wrap;html=1;'
+      cells.push(
+        `<mxCell id="${esc(node.id)}" value="${esc(dd.label ?? '')}" style="${shapeStyle}${BASE_NODE_STYLE}" vertex="1" parent="${esc(parentId)}">` +
+        `<mxGeometry x="${x}" y="${y}" width="${w}" height="${h}" as="geometry"/>` +
+        `</mxCell>`,
+      )
+    }
+  }
+
+  for (const edge of edges) {
+    const label = typeof edge.label === 'string' ? edge.label : ''
+    cells.push(
+      `<mxCell id="${esc(edge.id)}" value="${esc(label)}" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" source="${esc(edge.source)}" target="${esc(edge.target)}" parent="1">` +
+      `<mxGeometry relative="1" as="geometry"/>` +
+      `</mxCell>`,
+    )
+  }
+
+  const xml =
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<mxGraphModel><root>\n` +
+    cells.join('\n') +
+    `\n</root></mxGraphModel>`
+
+  return xml
+}

frontend/src/lib/drawio-import.ts

@@ -0,0 +1,142 @@
+import type { DiagramNode, DiagramEdge } from '@/types/network-diagram'
+
+// Maps draw.io shape identifiers (substrings of style) → our device slugs
+const DRAWIO_SHAPE_TO_SLUG: Array<[string, string]> = [
+  ['cisco.routers.router',                     'router'],
+  ['cisco.routers',                             'router'],
+  ['cisco.switches.layer_3_switch',             'switch'],
+  ['cisco.switches.workgroup_switch',           'switch'],
+  ['cisco.switches',                            'switch'],
+  ['cisco.firewalls',                           'firewall'],
+  ['cisco.servers',                             'server'],
+  ['cisco.computers_and_peripherals.laptop',    'laptop'],
+  ['cisco.computers_and_peripherals.ip_phone',  'phone'],
+  ['cisco.computers_and_peripherals.pc',        'workstation'],
+  ['cisco.computers_and_peripherals.printer',   'printer'],
+  ['cisco.misc.access_point',                  'access-point'],
+  ['cisco.misc.cloud',                         'cloud'],
+  ['cisco.storage',                             'nas'],
+  ['shape=router',                             'router'],
+  ['shape=server',                             'server'],
+  ['shape=firewall',                           'firewall'],
+  ['shape=cloud',                              'cloud'],
+]
+
+function styleToSlug(style: string): string {
+  const lower = style.toLowerCase()
+  for (const [pattern, slug] of DRAWIO_SHAPE_TO_SLUG) {
+    if (lower.includes(pattern)) return slug
+  }
+  return 'server'
+}
+
+function isGroup(style: string): boolean {
+  return style.includes('swimlane') || style.includes('container') || style.includes('group')
+}
+
+export interface DrawioImportResult {
+  nodes: DiagramNode[]
+  edges: DiagramEdge[]
+  warnings: string[]
+}
+
+export function parseDrawioXml(xmlString: string): DrawioImportResult {
+  const parser = new DOMParser()
+  const doc = parser.parseFromString(xmlString, 'application/xml')
+
+  const parseError = doc.querySelector('parsererror')
+  if (parseError) {
+    throw new Error('Invalid draw.io XML: ' + parseError.textContent?.slice(0, 200))
+  }
+
+  const cells = Array.from(doc.querySelectorAll('mxCell'))
+  const warnings: string[] = []
+  const nodes: DiagramNode[] = []
+  const edges: DiagramEdge[] = []
+
+  const geoMap = new Map<string, { x: number; y: number; width: number; height: number }>()
+  for (const cell of cells) {
+    const geo = cell.querySelector('mxGeometry')
+    if (geo) {
+      geoMap.set(cell.getAttribute('id') ?? '', {
+        x: parseFloat(geo.getAttribute('x') ?? '0'),
+        y: parseFloat(geo.getAttribute('y') ?? '0'),
+        width: parseFloat(geo.getAttribute('width') ?? '120'),
+        height: parseFloat(geo.getAttribute('height') ?? '120'),
+      })
+    }
+  }
+
+  const groupIds = new Set<string>()
+
+  for (const cell of cells) {
+    const id = cell.getAttribute('id') ?? ''
+    if (id === '0' || id === '1') continue
+
+    const isEdge = cell.getAttribute('edge') === '1'
+    const isVertex = cell.getAttribute('vertex') === '1'
+    const style = cell.getAttribute('style') ?? ''
+    const value = cell.getAttribute('value') ?? ''
+    const parent = cell.getAttribute('parent') ?? '1'
+    const geo = geoMap.get(id)
+
+    if (isEdge) {
+      const source = cell.getAttribute('source') ?? ''
+      const target = cell.getAttribute('target') ?? ''
+      if (!source || !target) {
+        warnings.push(`Edge "${id}" skipped — missing source or target`)
+        continue
+      }
+      edges.push({
+        id,
+        source,
+        target,
+        label: value || null,
+        connectionType: 'ethernet',
+        speed: null,
+        notes: null,
+        routing: null,
+      })
+      continue
+    }
+
+    if (isVertex && geo) {
+      if (isGroup(style)) {
+        groupIds.add(id)
+        nodes.push({
+          id,
+          type: 'subnet',
+          label: value || 'Group',
+          position: { x: geo.x, y: geo.y },
+          properties: {
+            hostname: null, ip: null, subnet: null, vendor: null,
+            model: null, role: null, vlan: null, notes: null, status: 'unknown',
+          },
+          nodeType: 'group',
+          style: { width: geo.width, height: geo.height },
+        })
+      } else {
+        const slug = styleToSlug(style)
+        const parentId = parent !== '1' && groupIds.has(parent) ? parent : undefined
+        nodes.push({
+          id,
+          type: slug,
+          label: value || slug,
+          position: { x: geo.x, y: geo.y },
+          properties: {
+            hostname: null, ip: null, subnet: null, vendor: null,
+            model: null, role: null, vlan: null, notes: null, status: 'unknown',
+          },
+          ...(parentId ? { parentId } : {}),
+          style: { width: geo.width, height: geo.height },
+        })
+      }
+    }
+  }
+
+  if (nodes.length === 0) {
+    warnings.push('No nodes were found in this draw.io file. Only basic shapes and Cisco stencil shapes are supported.')
+  }
+
+  return { nodes, edges, warnings }
+}

frontend/src/lib/routePrefetch.ts

@@ -9,7 +9,7 @@ const PREFETCH_MAP: Record<string, () => Promise<unknown>> = {
   '/shares': () => import('@/pages/MySharesPage'),
   '/analytics': () => import('@/pages/TeamAnalyticsPage'),
   '/analytics/me': () => import('@/pages/MyAnalyticsPage'),
-  '/assistant': () => import('@/pages/AssistantChatPage'),
+  '/pilot': () => import('@/pages/AssistantChatPage'),
   '/step-library': () => import('@/pages/StepLibraryPage'),
   '/guides': () => import('@/pages/GuidesHubPage'),
   '/feedback': () => import('@/pages/FeedbackPage'),

frontend/src/pages/FlowPilotSessionPage.tsx

@@ -9,6 +9,8 @@ import { StatusUpdateModal } from '@/components/flowpilot/StatusUpdateModal'
 import { HandoffModal } from '@/components/session/HandoffModal'
 import { handoffsApi } from '@/api/handoffs'
 import { aiSessionsApi } from '@/api'
+import { integrationsApi } from '@/api/integrations'
+import type { PSATicketInfo } from '@/types/integrations'
 import { toast } from '@/lib/toast'
 
 export default function FlowPilotSessionPage() {
@@ -17,10 +19,13 @@ export default function FlowPilotSessionPage() {
   const navigate = useNavigate()
   const location = useLocation()
   const prefill = (location.state as { prefill?: string } | null)?.prefill || ''
+  const psaTicketId = (location.state as any)?.psaTicketId as string | undefined
+  const psaTicket = (location.state as any)?.psaTicket as PSATicketInfo | undefined
   const isPickup = searchParams.get('pickup') === 'true'
   const fp = useFlowPilotSession()
   const branching = useBranching()
   const prefillHandledRef = useRef(false)
+  const psaTicketHandledRef = useRef(false)
   const [showOverflow, setShowOverflow] = useState(false)
   const [showResolve, setShowResolve] = useState(false)
   const [showEscalate, setShowEscalate] = useState(false)
@@ -44,6 +49,30 @@ export default function FlowPilotSessionPage() {
       fp.startSession({ intake_type: 'free_text', intake_content: { text: prefill } })
     }
   }, [prefill, sessionId, fp.session, fp.isLoading]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Auto-start when navigating from TicketQueue with a PSA ticket
+  useEffect(() => {
+    if (psaTicketId && psaTicket && !psaTicketHandledRef.current && !sessionId && !fp.session && !fp.isLoading) {
+      psaTicketHandledRef.current = true
+      integrationsApi.getConnection().then((conn) => {
+        if (conn?.id) {
+          fp.startSession({
+            intake_type: 'psa_ticket',
+            intake_content: {
+              ticket_data: {
+                summary: psaTicket.summary,
+                company: psaTicket.company_name,
+                priority: psaTicket.priority_name,
+              },
+            },
+            psa_ticket_id: psaTicketId,
+            psa_connection_id: conn.id,
+          })
+        }
+      })
+    }
+  }, [psaTicketId, psaTicket, sessionId, fp.session, fp.isLoading]) // eslint-disable-line react-hooks/exhaustive-deps
+
   const [pickingUp, setPickingUp] = useState(false)
 
   // Load existing session if ID in URL