Write Docs

• Every Surface Area Needs Documentation: Anything that an engineering change touches that involves a customer-facing change in any product surface area[s] need to be documented.
• Keep docs current: Documentation is a living artifact. When code changes, existing docs must be updated in the same change. Stale docs are misleading docs.
• Accuracy over speed: Incorrect documentation erodes trust faster than missing documentation. Cross-reference source code to verify that types, parameter names, and described behavior match the actual implementation.
• Consistency: Use the same terminology, structure, and formatting patterns across all docs. If we call it a "project" in one place, don't call it a "workspace" in another.
• For the right audience: Tailor voice, depth, and framing to who will read the page. A developer integrating an SDK needs different context than an admin configuring a project.
• Good information architecture: The right audiences find the right content.
• Clarity over assumption: Don't assume prior knowledge. Be explicit about prerequisites and context.
• Direct and practical: Get to the point. Documentation exists to help users accomplish goals, not to showcase everything we know.
• Progressive disclosure: Build up concepts before diving into details.
• Scoped and targeted: Each doc has a clear outcome. Provide the context needed—nothing more, nothing less.
• Right detail, right place: Avoid duplication. If something is explained elsewhere, link to it or reuse it in some way as appropriate.

Workflow

1. Understand context - Fully map out the scope of what needs to be changed. Consider all procuct surface areas plausibly affected, and identify existing documentation or documentation sections that may need updating or new articles.
2. Identify documentation type — Determine if this is reference, tutorial, integration, or overview content (see Step 1)
3. Write frontmatter — Add required title and optional fields like sidebarTitle, description, keywords (see Step 2)
4. Structure content — Use the appropriate pattern template for your doc type (see Step 3)
5. Use components correctly — Apply <Steps>, <Tabs>, <Cards>, callouts as needed (see Step 4)
6. Write code examples — Ensure examples are runnable with language tags and realistic values (see Step 5)
7. Handle navigation — Update meta.json if needed; add redirects for moves/renames (see File Organization)
8. Verify — Check against the verification checklist before completing

Step 0: Identify Relevant Surface Areas

Before writing anything, map out which surface areas the change touches. Review the engineering or product changes (staged files, PR diff, or task description) and ask:

1. What changed? — Identify the modified packages, APIs, schemas, or UI components
2. Who is affected? — Determine which user-facing surfaces consume or expose this change. For example (not exhaustive!):
   • SDK/CLI users (types, builder APIs, commands)
   • Dashboard users (UI forms, views, workflows)
   • API consumers (endpoints, request/response shapes, streaming formats)
   • Widget/chat users (runtime behavior, rendering)
   • Self-hosting users (env vars, deployment config)
3. What docs already exist? — Search agents-docs/content/ for pages that reference the affected feature; these may need updates
4. What's new vs. changed? — New surface areas need new pages; changed behavior needs existing page updates

If a change touches multiple surface areas, create or update a doc for each. Don't bundle unrelated surfaces into one page unless it's a natural fit with the existing document or similar analogous docs.

Step 1: Identify Documentation Type

Step 2: Write Frontmatter

Every .mdx file must have frontmatter with at least a title.

Required

---