From d3e46e7d6119ff62da785630b074c0a892dd16e8 Mon Sep 17 00:00:00 2001 From: suharshit singh Date: Wed, 16 Sep 2026 01:04:20 +0530 Subject: [PATCH] docs(ai-sessions): document AI design sessions in context files and README Brings the tracked docs in line with AI sessions steps 1-5. Docs only. docs.md is gitignored, so its matching refresh stays local. - context/architecture-context.md: 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 in Vercel Blob (was "filesystem"); chat cards and canvas-aware generation - context/ui-context.md: AI sidebar session bar, saved chats and cards follow the paper conventions - context/progress-tracker.md: step 6 entry and current goal - README.md: local AI design agent setup Co-Authored-By: Claude Opus 5 --- README.md | 12 +++++++++ context/architecture-context.md | 25 +++++++++++++++++++ context/progress-tracker.md | 44 +++++++++++++++++++++++++++++++-- context/project-overview.md | 7 +++++- context/ui-context.md | 6 ++++- 5 files changed, 90 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7bf5e7a..54c26f2 100644 --- a/README.md +++ b/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: diff --git a/context/architecture-context.md b/context/architecture-context.md index 44bb7b4..f0a633f 100644 --- a/context/architecture-context.md +++ b/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. diff --git a/context/progress-tracker.md b/context/progress-tracker.md index d44846b..32e4e1d 100644 --- a/context/progress-tracker.md +++ b/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. diff --git a/context/project-overview.md b/context/project-overview.md index dbf1d82..c3f5549 100644 --- a/context/project-overview.md +++ b/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 diff --git a/context/ui-context.md b/context/ui-context.md index 0701d2c..c6cb15c 100644 --- a/context/ui-context.md +++ b/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