composiohq__composio/docs/CLAUDE.md

Composio Documentation

Documentation site for Composio, built with Fumadocs.

Quick Reference

bun install          # Install dependencies
bun run dev          # Dev server (http://localhost:3000)
bun run build        # Production build (validates TS code blocks)
bun run types:check  # Type check
bun run sync:search  # Build and sync Algolia docs search index (requires Algolia env vars)
bun run test:search  # Test live Algolia search relevance from the terminal

Project Structure

docs/
├── app/                  # Next.js app router
├── content/              # MDX content
│   ├── docs/             # Main documentation
│   ├── cookbooks/        # Cookbooks & guides
│   ├── changelog/        # Release notes
│   ├── reference/        # SDK & API reference
│   └── toolkits/         # Toolkit docs + faq/ snippets
├── components/           # React components
├── lib/                  # Utilities
├── public/               # Static assets
├── scripts/              # Build scripts (link checker, etc.)
└── .claude/              # Claude context (see below)

Claude Context

Detailed documentation for Claude is organized in .claude/:

Context (Domain Knowledge)

• fumadocs.md - Framework patterns, design tokens, MDX components
• twoslash.md - TypeScript code block type checking
• sdk-reference.md - SDK doc generation
• api-reference.md - API reference customizations (schema rendering, CSS overrides, upgrade notes)
• pipelines.md - CI/CD workflows reference (cron jobs, auto-PR, AI agents)

Guides (How-To)

• changelog.md - Writing changelog entries

Decisions (ADRs)

• toolkits.md - Toolkits page implementation
• examples.md - Examples/cookbooks page plan
• feedback.md - Feedback system
• llm-guardrails.md - LLM guardrails system (frontmatter-scoped, pipeline-injected)

Git Workflow

Docs branches are always based off next and PRs target next (not master). When creating a new branch for docs work, branch from next. When opening a PR, set the base to next.

Key Rules

1. TypeScript code blocks are type-checked - All TS code in MDX is validated at build time. See twoslash.md.

2. Run build before pushing - bun run build catches type errors that bun dev misses. Also run bun run scripts/validate-links.ts to catch broken internal links.

3. CSS variables - Use var(--composio-orange) not var(--orange). Check app/global.css.

4. Date format - Changelog dates must be YYYY-MM-DD format.

5. Toolkits data - public/data/toolkits.json must exist; errors are thrown, not ignored.

6. Meta tools data - public/data/meta-tools.json and content/reference/meta-tools/ are auto-generated by bun run generate:meta-tools (fetches from Tool Router API). Updated by CI alongside toolkits data. The MetaToolDetailServer component reads from the JSON at build time — do NOT register it in mdx-components.tsx (causes fs to leak into client bundle).

7. Test on mobile - Fumadocs nav differs on mobile. Avoid assumptions about horizontal layout.

8. Toolkit FAQ files - FAQ snippets live in content/toolkits/faq/{slug}.md. They're plain markdown (no frontmatter) embedded in toolkit pages at build time, not standalone Fumadocs pages. They're excluded from the toolkits Fumadocs source via files: ['**/*', '!faq/**'] in source.config.ts but still scanned by the link checker.

9. Link checker - scripts/validate-links.ts validates all internal links. It needs bunfig.toml (Bun preload for fumadocs-mdx) to run. Key details:

   • Populate keys use (home)/ prefix to match the app/(home)/ route group
   • Fragment validation falls back to parsing raw markdown headings (since data.toc is unavailable outside Next.js)
   • Dynamic toolkit pages are validated against slugs from public/data/toolkits.json
   • Non-Fumadocs .md files (like FAQ snippets) are picked up via content/**/*.md glob

10. Internal links use relative paths, never absolute - Write /docs/<section>/<page>, /reference/api-reference/<resource>/<operationId>, /reference/sdk-reference/<lang>/<page>, /docs/changelog/YYYY/MM/DD, /assets/images/<file>. Never https://docs.composio.dev/.... The link checker (rule 9) only validates relative links; absolute URLs silently bypass it and rot over time. API-reference operation IDs are camelCase (getConnectedAccountsByNanoid, postAuthConfigs) — do not guess them; copy the exact href from <ApiEndpointsTable> in content/reference/api-reference/<resource>/index.mdx. Previous changelog entries use zero-padded month/day (/docs/changelog/2026/04/21, not 2026/4/21).

Glossary

content/docs/glossary.mdx defines key Composio terms (auth config, session, toolkit, etc.) using <Glossary> and <GlossaryTerm name="..."> components (components/glossary.tsx). The component renders a filterable two-column table. The markdown converter in lib/source.ts converts <GlossaryTerm> tags to ### Term headings for LLM-friendly output. When adding new Composio concepts, add a <GlossaryTerm> entry and update the keywords frontmatter array.

Search

The docs search dialog uses Algolia in production when NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY is configured. NEXT_PUBLIC_ALGOLIA_APP_ID defaults to 62HI9PQZ1L, and NEXT_PUBLIC_ALGOLIA_INDEX_NAME defaults to docs_composio_dev_62hi9pqz1l_pages. Without a search API key it falls back to /api/search for local development and tests. Algolia searches request clickAnalytics, and the client sends search result view/click events with search-insights.

Run ALGOLIA_APP_ID=62HI9PQZ1L ALGOLIA_ADMIN_API_KEY=... ALGOLIA_INDEX_NAME=docs_composio_dev_62hi9pqz1l_pages bun run sync:search from docs/ to rebuild the Algolia index. The sync script does not use Algolia Crawler: it creates section-sized records from MDX/OpenAPI/toolkit data, configures searchable attributes, customRanking, and attributeForDistinct, then replaces the index objects. Use bun run sync:search --dry-run --samples to inspect generated records and ALGOLIA_SEARCH_API_KEY=... bun run test:search "oauth auth config" to test live relevance.

API Versioning

The API reference supports v3.1 (latest, default) and v3.0 side-by-side:

• v3.1: /reference/api-reference/... (default, all existing URLs unchanged)
• v3.0: /reference/v3/api-reference/...

Version selector in the top nav switches between them. See api-reference.md for full architecture.

Key maintenance notes:

• Non-API pages under content/reference/v3/ (overview, authentication, errors, rate-limits) are manual copies — update both when content changes
• API index pages and OpenAPI specs are auto-generated by CI (docs-update-data.yml)
• SDK Reference and Meta Tools are shared across both versions (not duplicated)

Code Review Guidelines

docs/examples/ is tutorial code. Review for correctness and clarity, not production-readiness. Skip accessibility (aria attributes, focus management), error boundaries, i18n, comprehensive error handling, and similar concerns that add noise to a teaching example. The goal is to teach Composio integration with minimal code.

AI-Native Documentation

Prefer cURL over "click" - Most docs traffic comes from AI crawlers. When documenting API interactions, prefer showing cURL commands over UI instructions like "click this button" or "navigate to settings". cURL is machine-readable and can be directly executed by AI agents.

LLM guardrails - Every .md endpoint appends invisible guardrails steering AI code generators toward the session-based pattern. Controlled via llmGuardrails frontmatter field. See llm-guardrails.md.