docs(ai-sessions): document AI design sessions in context files and README

README.md

@@ -21,6 +21,18 @@ curl -X POST http://localhost:3000/api/trigger/hello \
 
 Task source files live in `src/trigger/` and Trigger.dev config is in `trigger.config.ts`.
 
+## AI design agent (local)
+
+1. Set `GOOGLE_GENERATIVE_AI_API_KEY` in `.env.local`, and optionally `GOOGLE_GENERATIVE_AI_MODEL`
+   (default `gemini-3.5-flash`; Gemini 2.x and 3.x models both work).
+2. Run `pnpm prisma migrate dev` so the `AiSession` and `AiMessage` tables exist.
+3. Run `pnpm dev` and `pnpm trigger:dev` together. The worker reads `.env.local` only when it starts, so restart it
+   after changing the model or any key.
+4. In production, set `CRON_SECRET` in the Vercel project so the daily AI session cleanup in `vercel.json` can
+   authenticate.
+
+`docs.md` → **AI** explains sessions, turns, and how generation works.
+
 ## Getting Started
 
 First, run the development server:

context/architecture-context.md

@@ -28,6 +28,26 @@
   removed by a daily Vercel Cron (`/api/cron/ai-sessions/cleanup`, `CRON_SECRET`). Reads ignore expired rows, so
   expiry holds even before cleanup runs. Deleting a project cascades to its sessions.
 
+## AI Design Agent
+
+- **One turn = one Trigger.dev run** (`design-agent`). Routes validate input and access, trigger the run, and
+  return `202`; they never call the model.
+- **A turn** reads the Liveblocks room read-only and summarises it (`lib/ai/canvas-summary.ts`), then analyzes the
+  message (updates the requirements brief and decides ask / plan / generate), drafts or revises a plan, or
+  generates the diagram for the approved plan, validates it (`lib/ai/graph-validation.ts`), makes at most one repair
+  call, and writes it with `mutateFlow`.
+- **Code enforces the rules** the model is asked to follow (question rounds, skip, no generating without a plan) and
+  fills in everything render-related: node and edge types, sizes, fills from `NODE_ROLES`, dashed async edges,
+  connection points, and layout. Existing components are referenced by `ex-N` refs; generated duplicates fold into
+  existing nodes.
+- **Turns settle on read.** The turns route stores a `PENDING` reply with the run id; reading the session retrieves
+  the run, validates its output with zod, and stores `QUESTIONS`, `PLAN`, or `RESULT`. The task has no database
+  access and never writes blobs.
+- **Reliability:** per-call timeouts (analyze 90s, plan 150s, generate 120s), task `maxDuration` 300s, a single task
+  attempt, one retry per call on a schema mismatch, list limits trimmed in code instead of `maxItems`, and friendly
+  failure messages with raw provider errors kept in server logs.
+- **Model:** `GOOGLE_GENERATIVE_AI_MODEL`, with a thinking level (Gemini 3+) or thinking budget (Gemini 2.x) per step.
+
 ## Auth and Access Model
 
 - Every user signs in via Clerk to establish identity.
@@ -40,4 +60,9 @@
 2. Metadata belongs in the database; large assets must be offloaded to blob/file storage.
 3. API routes must validate authentication and resource ownership before any mutation.
 4. Foundation components (`components/ui/*`) must remain generic and default.
+5. Generated canvas content reaches clients only through Liveblocks, never through an HTTP response.
+6. The design task never writes to the database or blob storage; the session routes store AI turns.
+7. A project's id is its Liveblocks room id.
+8. Run tokens are minted only by `POST /api/ai/design/token`, after a `TaskRun` ownership check.
+9. Model output is validated (zod) before it is stored or drawn.
 

context/progress-tracker.md

@@ -11,8 +11,9 @@ Update this file whenever the current phase, active feature, or implementation s
 - Persistent, multi-turn AI design sessions (plan: storage → wire sessions → turn engine → UI cards → generation
   quality → docs). Steps 1 (storage, PR #21), 2 (sessions in the sidebar, PR #22) and 3 (clarify → plan → generate
   turn engine, PR #23) and 4 (question/plan/result cards, PR #25) are done; step 5 (generation quality: canvas
-  context, roles and kickers, async edges, validate-and-repair) is built on `feat/ai-generation-quality` and
-  awaiting its live run; step 6 (docs) follows, then the Specs tab.
+  context, roles and kickers, async edges, validate-and-repair, PR #26) is done; step 6 (docs) is on
+  `feat/ai-sessions-docs`. Next: the Specs tab (Generate Spec + automatic Markdown download), which can reuse the
+  plan decisions stored in RESULT payloads.
 - After that: the Specs tab (Generate Spec + automatic Markdown download), which remains inert.
 
 ## Completed
@@ -1426,3 +1427,42 @@ Update this file whenever the current phase, active feature, or implementation s
       `design-agent-engine.ts` now strips parenthesised refs ("(ex-7)", "(ex-4, ex-5)") from the plan summary,
       responsibilities, flows, decisions, and assumptions after drafting; other parentheses are left alone. Covered
       by 3 more offline checks.
+- AI sessions, step 6: documentation refresh (2026-09-16, branch `feat/ai-sessions-docs`, docs only, no code):
+    - `docs.md` is listed in `.gitignore` (and has never been committed), so its refresh below stays in the local
+      working copy by decision; the branch commits `README.md` and the context files only.
+    - `docs.md`:
+      - AI category rewritten: **AI design sessions** (flow diagram, guide through the questions / plan / result
+        cards, stages, code-enforced rules, the Microservices extend example from the live run, error messages),
+        **How generation works** (turn steps with files, output contract with roles / kickers / delivery / refs,
+        validation checks, models, thinking, timeouts, retries), **Sessions & storage** (models, limits, settle on
+        read, cleanup cron), **Run tracking & tokens** (example now `useAiSession` + turns route), and **Spec
+        generation** (still planned; notes the stored plan decisions). The planned "AI sessions" page and "Diagram
+        from prompt" are gone; the sidebar nav matches.
+      - Getting started: goal 4, core user flow rows 5–6, and the worked example describe clarify → plan → draw.
+        Quickstart adds Vercel Cron / `CRON_SECRET`, the AI session migrations, and restarting the worker after a
+        model change.
+      - Reference: API routes (session and turns routes and the cleanup cron replace `/api/ai/design`), data models
+        (`AiSession`, `AiMessage`, `Project.aiSessions`), canvas types (`SHAPE_KICKERS`, fills, roles, edge colours,
+        text nodes, legacy palette), hooks (`useAiSession`), environment variables (`CRON_SECRET`, model notes).
+      - Contributing: spec index rows S1–S6 with their PRs; stack (`generateText` + `Output.object`, Vercel Cron),
+        `lib/ai/` boundary, storage table row for AI chats, invariant 6 widened and invariant 9 added; the stale note
+        about `project-overview.md` saying "filesystem" removed.
+      - Roadmap: AI design sessions and chat sessions are `BETA`; known issues replace the fixed ones (no run
+        timeout, conversation lost on reload, "filesystem" wording) with current ones (adds only, private sessions,
+        free-tier quota, preview-model timeouts); five new architecture decisions; a 2026-09-15 → 16 history row.
+    - `context/architecture-context.md`: new "AI Design Agent" section (turn = run, turn steps, code-enforced rules,
+      settle on read, reliability, model config) and invariants 5–9.
+    - `context/project-overview.md`: canvas snapshots are in Vercel Blob (was "filesystem"); AI section adds the
+      chat cards and canvas-aware generation, and notes it does not edit or remove existing components.
+    - `context/ui-context.md`: the AI sidebar session bar, saved-chat list, and chat cards follow the paper conventions.
+    - `README.md`: "AI design agent (local)" setup — API key and model, migrations, running and restarting the worker,
+      `CRON_SECRET` in production.
+    - Validation:
+      - A grep for stale references (`/api/ai/design` outside the token route, `useDesignAgent`, `generateObject`,
+        "Diagram from prompt", "lost on reload", "filesystem") across `docs.md`, `README.md`, and the context files
+        found one: the Collaboration → Thinking indicator paragraph, now describing AI turns and linking to
+        "AI design sessions". The only other match is the intended legacy-palette row in Canvas types.
+      - A check of every in-doc anchor link in `docs.md` against its headings: all resolve after that fix.
+      - Section order after the splice: Getting started, Platform, AI, Authentication, Design system, Reference,
+        Contributing, Roadmap.
+      - No code changed, so lint, typecheck, and build were not re-run.

context/project-overview.md

@@ -39,7 +39,7 @@ Ghost AI is a real-time collaborative system design workspace. Users describe a
 
 - Shared real-time canvas using Liveblocks and React Flow.
 - Live cursors, presence indicators, and node/edge editing.
-- Canvas snapshots persisted to the filesystem.
+- Canvas snapshots persisted to blob storage (Vercel Blob).
 
 ### Starter System Designs
 
@@ -58,6 +58,11 @@ Ghost AI is a real-time collaborative system design workspace. Users describe a
     that the user approves or asks to revise before anything is drawn.
 - AI chat sessions are saved per user per project for 7 days after last use, so a conversation and an in-flight
   generation survive a reload.
+- The AI sidebar shows clarifying questions (suggested answers, skip), plans (key decisions highlighted, draw
+  button), and results as interactive cards.
+- Follow-up requests see the current canvas: the AI adds only new components, connected to the existing ones,
+  using the starter templates' conventions (role-based paper fills, kickers, dashed async links), and checks the
+  diagram with one repair attempt before drawing. It does not edit or remove existing components.
 
 ### Spec Generation
 

context/ui-context.md

@@ -10,7 +10,11 @@ Two separate visual systems live in this app and must not be mixed:
    ink type and CTAs, JetBrains Mono chrome, `rounded-paper`, `shadow-flat`) with `scheme-light`.
    The canvas ground (cream with ink dots), AI sidebar, shape panel, control bar, minimap and the top-right
    canvas status panel use the brand tokens too, and so do the project, share and starter-templates dialogs
-   (all built on `PaperDialog` in `components/editor/paper-dialog.tsx`) and the Clerk user menu (`UserMenuButton`). Live
+   (all built on `PaperDialog` in `components/editor/paper-dialog.tsx`) and the Clerk user menu (`UserMenuButton`).
+   Inside the AI sidebar, the session bar, saved-chat list (`AiSessionHistory`) and chat cards (`QuestionsCard`,
+   `PlanCard`, `ResultCard` in `components/editor/ai-chat-cards.tsx`) follow the same paper conventions:
+   `paper-bright` cards with ink hairlines, mono chrome kickers, chips that fill ink when selected, ink primary
+   buttons, and a plan's key decisions on marker-amber paper. Live
    cursors, the AI thinking indicator and Clerk's "Manage account" profile modal are still product-dark.
 2. **Marketing (`app/(marketing)`) and auth (`app/(auth)`)** — the Lab-site brand & craft system v1 defined in
    `app/globals.css` (Sept 2026). Marketing surfaces use **only** the brand tokens