Artifacts Playbook

This repository builds the Artifacts platform—a system for LLM-generated, schema-driven documents with rich interactive rendering across multiple surfaces (ChatGPT, Universal App, Claude, Gemini).

Key concept: Artifacts are created and edited conversationally by LLM agents, not manually by users.

Documentation structure: All agent-facing documentation (instructions for LLM agents like Claude Code) is located in ./.agents/docs at the monorepo root. Package/app-specific agent docs are in packages/*/.agents/docs/ and apps/*/.agents/docs/. The /docs directory is reserved for immutable upstream/reference documentation.

Critical Documentation

@.agents/docs/artifacts/architecture.md - System architecture & implementation status @.agents/docs/artifacts/schema-reference.md - Complete schema specification: artifact envelope structure, node types (vstack, markdown, line-chart), validation rules, serialization constraints, ResponsiveGap system

Reference Documentation (Read as Needed)

Design Philosophy Contains: Why JSON schema, architectural decisions, LLM-generated approach rationale, multi-surface design Read when: Understanding core design decisions or explaining platform choices

Development Guide Contains: Monorepo setup: JIT packages, pnpm workspaces, Turbo tasks, dev workflows, troubleshooting Read when: Working on build/dependency issues or setting up development environment

Authentication Contains: OAuth flow details with Clerk integration, JWT handling Read when: Implementing auth or debugging login flows

MCP Server Contains: MCP route handler patterns, tool implementation Read when: Adding new MCP tools or modifying ChatGPT integration

Widget Rendering Contains: Next.js widget implementation, Apps SDK integration Read when: Working on ChatGPT widget display or Apps SDK features

Schema Extension Contains: Adding new node types: Zod patterns, components, testing Read when: Creating new artifact node types

Artifact Service Contains: Supabase integration patterns (Next.js, MCP), RLS bypass guardrails, validation/update policy, CRUD patterns Read when: Using @chatgpt-artifacts/artifact-service in tools/apps or debugging persistence/auth

Working with Specific Surfaces

• ChatGPT integration: See apps/chatgpt-app/
• Universal App: See apps/expo-app/
• Component development: See packages/artifact-kit/

Upstream Documentation

ChatGPT Apps SDK Contains: Upstream platform guides for human developers (generic MCP patterns, widget tutorials, OAuth guides) Read when: Looking up platform API references not covered in our project-specific implementation docs

Research Tooling

• Prefer the Tavily MCP server fetching the full contents of URLs, and exploring site structures (use its extract and map modes as appropriate).
• Keep Brave Search MCP as an optional fallback if Tavily cannot surface the needed results.
• Firecrawl MCP access is available but costly—only use it after exhausting Tavily (and Brave, if needed) and document why the fallback was necessary.
• Use the Context7 MCP server to pull the latest library documentation before implementing or modifying code that depends on external packages.
• When you need real-world examples from public GitHub repos, query the Grep MCP server instead of scanning locally; it indexes over a million repositories.