Menu
Use when adding, modifying, or debugging API endpoints, request/response schemas, payload formats, or the chat and search route handlers.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
YAAWC design system rules and tokens. MUST be used whenever editing or creating UI — any .tsx component, Tailwind class change, styling work, color/spacing/radius/shadow/typography decision, or globals.css edit. Activates on terms like "component", "style", "UI", "button", "card", "modal", "color", "theme", "dark mode", "Tailwind", "CSS", "layout", "padding", "spacing", "rounded", "shadow", "hover", "focus", "MessageBox", "Sidebar", "Navbar", "ChatWindow", or any work under src/components or src/app.
Use when modifying React UI components, ChatWindow, MessageBox, MarkdownRenderer, frontend state/streaming event handling, styling, or debugging UI rendering.
Build, run, and drive YAAWC (the Next.js AI search app in this repo). Use when asked to start YAAWC, launch the dev server, build it, smoke-test it, screenshot or inspect the home/dashboard UI, or interact with the running app in a browser.
Use when working on tool-call lifecycle events, todo updates, subagent streaming, SimplifiedAgent/ChatWindow event handling, MarkdownRenderer ToolCall, TodoWidget, or debugging missing or broken streaming output.
Use when working on image upload/display, the uploads API, MessageInput image/clipboard paste, multimodal chat messages, or vision model integration.
Use when adding or extending agent tools, LLM providers, API routes, or focus modes in YAAWC, or when asked how to add new functionality.
| name | api-endpoints |
| description | Use when adding, modifying, or debugging API endpoints, request/response schemas, payload formats, or the chat and search route handlers. |
POST /api/chat)Source: src/app/api/chat/route.ts
Request body:
{
message: {
messageId: string; // Unique message ID
chatId: string; // Chat session ID
content: string; // User message text
};
focusMode: string; // "webSearch" | "localResearch" | "chat"
files: string[]; // Attached file references
chatModel: { provider: string; name: string; contextWindowSize?: number };
systemModel?: { provider: string; name: string; contextWindowSize?: number };
embeddingModel: { provider: string; name: string };
selectedSystemPromptIds: string[]; // Persona prompt IDs (legacy name)
selectedMethodologyId?: string;
messageImageIds?: string[];
messageImages?: Array<{ imageId: string; fileName: string; mimeType: string }>;
// Server-authoritative: route reads these from the DB (app_settings) and
// overwrites any client value; the UI no longer sends them. Private sessions strip them.
userLocation?: string;
userProfile?: string;
memoryEnabled?: boolean;
memoryAutoDetection?: boolean;
isPrivate?: boolean;
workspaceId?: string | null;
imageCapable?: boolean;
invokedSkills?: string[]; // Skill names user explicitly triggered
}
Idempotency: If message.messageId already has a live run (running or awaiting_user), the request re-subscribes to the existing run's event stream instead of starting a duplicate.
Response: SSE stream of newline-delimited JSON objects (text/event-stream):
{"type":"response","data":"token text","messageId":"..."}
{"type":"sources","data":[...],"searchQuery":"...","searchUrl":"...","messageId":"..."}
{"type":"sources_added","data":[...],"messageId":"..."}
{"type":"tool_call_started","data":{...},"messageId":"..."}
{"type":"tool_call_success","data":{...},"messageId":"..."}
{"type":"tool_call_error","data":{...},"messageId":"..."}
{"type":"subagent_started","executionId":"...","name":"...","task":"...","messageId":"..."}
{"type":"subagent_data","subagentId":"...","data":{...},"messageId":"..."}
{"type":"subagent_completed","id":"...","summary":"...","messageId":"..."}
{"type":"subagent_error","id":"...","error":"...","messageId":"..."}
{"type":"chart_spec","data":{"chartId":"...","spec":{...}},"messageId":"..."}
{"type":"todo_update","data":{...},"messageId":"..."}
{"type":"code_execution_pending","data":{...},"messageId":"..."}
{"type":"code_execution_result","data":{...},"messageId":"..."}
{"type":"user_question_pending","data":{...},"messageId":"..."}
{"type":"user_question_answered","data":{...},"messageId":"..."}
{"type":"ask_user_pending","data":{"approvalId":"...","toolCallId":"...",...},"messageId":"..."}
{"type":"ask_user_answered","data":{...},"messageId":"..."}
{"type":"ask_user_cancelled","data":{"approvalId":"..."},"messageId":"..."}
{"type":"workspace_edit_pending","data":{...},"messageId":"..."}
{"type":"workspace_edit_answered","data":{...},"messageId":"..."}
{"type":"workspace_create_pending","data":{...},"messageId":"..."}
{"type":"workspace_create_answered","data":{...},"messageId":"..."}
{"type":"skill_edit_pending","data":{...},"messageId":"..."}
{"type":"skill_edit_answered","data":{...},"messageId":"..."}
{"type":"context_grew","kind":"...","tokens":...,"totalEstimated":...,"messageId":"..."}
{"type":"workspace_file_changed","data":{...},"messageId":"..."}
{"type":"progress","data":"...","messageId":"..."}
{"type":"stats","data":{"modelName":"...","usageChat":{...},"usageSystem":{...},...},"messageId":"..."}
{"type":"memory_updated","data":{"saved":...,"updated":...,"memoryIds":[...]},"messageId":"..."}
{"type":"messageEnd","messageId":"...","modelStats":{...},"searchQuery":"...","usedLocation":...,"usedPersonalization":...,"memoriesUsed":[...],"projectedNextInputTokens":...}
{"type":"error","data":"..."}
{"type":"gone"}
Note: The old {"type":"init"}, {"type":"modelStats"}, and {"type":"end"} event types are gone. messageEnd replaces end/modelStats. stats carries live model stats mid-stream.
| Endpoint | Method | Purpose |
|---|---|---|
/api/chat/cancel | POST | Hard-cancel a run. Body: { messageId: string } |
/api/chat/compact | POST | Summarize a chat's history to compress context. Body: { chatId, instructions?, chatModel?, systemModel? }. Returns { compactionSummary, compactedMessageCount, lastCompactedId, tokensBefore, tokensAfter } |
/api/chat/runs/active | GET | List running/awaiting_user runs (excluding scheduled tasks). Returns { active, stale, unreadCount, awaitingAttentionCount } |
/api/chat/runs/[messageId]/stream | GET | Re-attach to a run's event stream. Query params: from=<seq>, chatId=<id>. Returns SSE stream or {"type":"gone"} |
/api/chat/runs/resume | POST | Resume a paused (awaiting_user) run. Body: { approvalId, response } or { resumeMap: { approvalId: response, ... } } |
/api/approvals/pending | GET | List pending (unresolved) interrupt approvals. Query param: chatId=<id> (optional) |
| Endpoint | Method | Purpose |
|---|---|---|
/api/chats | GET | List chats. Params: limit, offset, q (search), pinned=1, scheduled=0/1, workspaceId, workspaceIds. Returns { chats, total, totalMessages, limit, offset, hasMore } |
/api/chats/[id] | GET/DELETE | Get or delete individual chat |
/api/chats/[id]/seen | POST | Mark a chat's latest run as viewed. Returns { historyCount, scheduledCount } |
/api/chats/search | GET | Dedicated full-text search across chat content |
/api/messages/[messageId] | GET/DELETE | Get or delete individual message |
| Endpoint | Method | Purpose |
|---|---|---|
/api/config | GET | Server configuration |
/api/models | GET | Available models per provider |
/api/tools | GET | Available tool listing |
| Endpoint | Method | Purpose |
|---|---|---|
/api/suggestions | POST | Generate follow-up suggestions. Body: { chatHistory: [{role,content}][], chatModel?, selectedSystemPromptIds? } |
/api/autocomplete | GET | Browser autocomplete passthrough. Param: q. Returns OpenSearch suggestions JSON |
| Endpoint | Method | Purpose |
|---|---|---|
/api/system-prompts | GET/POST | List or create persona/system prompts |
/api/system-prompts/[id] | PUT/DELETE | Update or delete a prompt |
| Endpoint | Method | Purpose |
|---|---|---|
/api/uploads/images | POST | Upload images (multipart form). Returns { images: [{imageId, fileName, mimeType}] } |
/api/uploads/images/[imageId] | GET | Serve uploaded image (validates hex-only ID) |
/api/uploads | POST | Generic file upload |
| Endpoint | Method | Purpose |
|---|---|---|
/api/images | POST | Image search |
/api/videos | POST | Video search |
| Endpoint | Method | Purpose |
|---|---|---|
/api/workspaces | GET/POST | List (param: archived=true) or create workspaces. POST body: { name, ...opts }. Returns { workspaces } / { workspace } |
/api/workspaces/[id] | GET/PUT/DELETE | Get, update, or delete a workspace |
/api/workspaces/[id]/archive | POST | Archive a workspace |
/api/workspaces/[id]/unarchive | POST | Unarchive a workspace |
/api/workspaces/[id]/files | GET/POST | List or upload workspace files |
/api/workspaces/[id]/files/[fileId] | GET/PUT/DELETE | Get, update, or delete a workspace file |
/api/workspaces/[id]/system-prompts | GET | List system prompts scoped to a workspace |
/api/workspaces/[id]/urls | GET/POST | Manage workspace URL sources |
/api/workspaces/[id]/urls/check | POST | Validate a URL |
| Endpoint | Method | Purpose |
|---|---|---|
/api/memories | GET | List memories. Params: q, category, workspaceId, sort (createdAt/lastAccessedAt/accessCount), limit, offset. Returns { data, total, limit, offset, hasMore } |
/api/memories | POST | Create memory. Body: { content: string, workspaceId?: string }. Returns created memory (201) |
/api/memories | DELETE | Delete all memories |
/api/memories/[id] | GET/PUT/DELETE | Get, update, or delete a memory |
/api/memories/reindex | POST | Re-embed all memories (e.g., after embedding model change) |
| Endpoint | Method | Purpose |
|---|---|---|
/api/skills | GET | List skills. Params: workspaceId (includes global + workspace), enabled=true (only enabled). Returns array |
/api/skills | POST | Create skill. Body: { name, description, content, workspaceId?, disableModelInvocation? }. Returns skill (201) |
/api/skills/[id] | GET/PUT/DELETE | Get, update, or delete a skill |
| Endpoint | Method | Purpose |
|---|---|---|
/api/scheduled-tasks | GET | List scheduled tasks (with running: bool field) |
/api/scheduled-tasks | POST | Create task. Required: name, prompt, cronExpression, chatModel, embeddingModel. Optional: focusMode, systemModel, sourceUrls, selectedSystemPromptIds, selectedMethodologyId, timezone, enabled, retentionMode, retentionValue |
/api/scheduled-tasks/[id] | GET/PUT/DELETE | Get, update, or delete a scheduled task |
/api/scheduled-tasks/[id]/run | POST | Manually trigger a task run |
/api/scheduled-tasks/[id]/runs | GET | List run history for a task |
/api/scheduled-tasks/runs | GET | List all scheduled task runs |
/api/scheduled-tasks/runs/[chatId]/view | POST | Mark a scheduled task run chat as viewed |
/api/scheduled-tasks/runs/unread | GET | Count unread scheduled task runs |
| Endpoint | Method | Purpose |
|---|---|---|
/api/dashboard/process-widget | POST | Process/render a dashboard widget |
| Endpoint | Method | Purpose |
|---|---|---|
/api/respond-now | POST | Soft-stop / early synthesis trigger. Body: { messageId } |
/api/opensearch | GET | OpenSearch description XML for browser search integration |
User → POST /api/chat
→ Idempotency check (getRun): if live run exists, re-subscribe
→ resolveChatAndEmbedding() → chatLlm, systemLlm, embedding
→ Memory retrieval (if memoryEnabled)
→ handleHistorySave() — persists user message to DB
→ resolveSkillsForChat() + persistToolContextRow() for invoked skills
→ buildHistoryFromDb() (with compaction support via compactionRows)
→ new SimplifiedAgent(...) + startRun() + attachRunHost()
→ handler.searchAndAnswer() [fire-and-forget via LangGraph React Agent]
→ subscribe(run, 0, req.signal) → SSE stream to client
Backgrounded runs: A run persists in the DB even if the client disconnects. The client reconnects via GET /api/chat/runs/[messageId]/stream?from=<seq> to replay missed events.
Interrupts: When the agent needs human approval (file edit, code execution, user question), the run pauses (awaiting_user). The client resumes via POST /api/chat/runs/resume.
If systemModel is omitted, falls back to chatModel. Both support contextWindowSize. selectedSystemPromptIds is treated as persona prompt IDs (despite the legacy name).