Integration branch for the next docs release: a **sessions-first
documentation rewrite** — new and rewritten guides, example pages,
interactive components, and docs tooling — plus the supporting SDK
changes that the new docs describe.
The bulk of this PR is docs (~24k lines across ~150 commits); the SDK
changes (~5k lines) back the new guides.
## Documentation (the bulk)
- **Sessions-first restructure** — reorganized navigation and section
structure (incl. the "Sandbox (prev workbench)" section), with
v3-reorganization redirects so old URLs keep resolving.
- **Rewritten core guides** — quickstart, configuring sessions, triggers
(creating + subscribing to events), proxy-execute, toolkits
enable/disable, and common FAQ, rewritten in the house voice.
- **New example pages** — local-sandbox PR reviewer, daily standup bot,
and slack bot, with runnable build-ups.
- **New interactive components & diagrams** — triggers flow animation,
manage-connections visual, connection-refresh visual, and the
terminal-kit components.
- **Docs tooling** — a docs-graph link-graph connectivity checker,
search reprioritization (deprioritize legacy pages), and SDK-reference
regeneration.
## Supporting SDK changes
**`@composio/core` → 0.13.0 (minor)**
- `composio.sessions.create()` as the first-class sessions API
(`composio.create()` kept as an alias).
- **MCP is opt-in:** default `create()` / `use()` return native-tool
sessions (`SessionWithoutMcp`); pass `{ mcp: true }` to surface
`session.mcp`. _Migration: read `session.mcp` only after creating with
`{ mcp: true }`._
- `session.sandbox` is the canonical resolved config;
`session.workbench` kept as a deprecated alias. `sandbox` is the
preferred session-config key (`workbench` still accepted).
- `connectedAccounts.updateAcl()` graduated from experimental (alias
kept).
- `triggers.parse()` (parse + optionally verify an incoming webhook) and
`triggers.setWebhookSubscription()`.
**`@composio/experimental` → minor** — local-workbench helpers moved
onto the `@composio/experimental/workbench` subpath (out of
`@composio/core/experimental`), keeping the ~14 KB embedded Python
helper out of core. Plus the experimental Pi provider.
**`@composio/slim` → minor.**
**Python → 0.17.0** — mirrors the TS surface: `composio.sessions` mount
(`tool_router` deprecated), `triggers.parse()` /
`set_webhook_subscription()`, the `sandbox` config key, and
`connected_accounts.update_acl()`.
## Review response (#3664)
Addressed the `@composio/core` review:
- **Security:** `triggers.parse()` no longer fails open — a
present-but-empty `verifySecret` (e.g. unset `COMPOSIO_WEBHOOK_SECRET`)
now throws instead of silently skipping verification; omitting it stays
an explicit opt-out (both SDKs).
- Removed snake_case leakage from `transformWebhookSubscription` (+ the
index signature that allowed it).
- **Removed** the TS-only `connectedAccounts.link()` toolkit
auto-resolve (shipped with cancellability / orphaned-auth-config bugs
and was effectively undocumented; to be reintroduced properly later).
- Unified Python error types on `ValidationError`; added `mcp=True`
Python tests; fixed runtime-portability + error-type test assertions.
- Polished deprecation messages; fixed the backwards `/experimental`
`@deprecated` note and the `SessionWithMcp` JSDoc.
## Testing
- **TS:** `@composio/core` + `@composio/experimental` typecheck pass;
vitest green for the touched suites.
- **Python:** `test_tool_router.py` + `test_triggers.py` pass (161
tests).
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Kshitij Jhunjhunwala <kj@composio.dev>
Co-authored-by: Malay Vasa <malayvasa@gmail.com>
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
- single page docs/content/docs/security-and-data.mdx (replaces the 3-page security/ folder)
- adds redacted Log-storage screenshot (project/org/email/user_id blurred; "Don't store data"
highlighted) at docs/public/images/log-storage-dont-store-data.png
- nav: single "Security and Data" section, below Triggers and webhooks
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
## Summary
Reworks the docs welcome page (`/docs`) into a two-column hero with an
animated agent chat mock + tool overlay, plus four restructured homepage
sections.
### Hero (`DocsHeroV2`)
- Left: headline (`Start building with Composio.`), short sub,
brand-blue chip column (Quickstart, API reference, Toolkits).
- Right (lg+ only): mock chat panel with the v1 hero's per-agent skin
(`Claude Cowork` / `ChatGPT Codex` / `Your AI Agent`), step-by-step
timeline-driven animation (user prompt → thinking dots → tool-trail
items → assistant response), and a floating "active tool" card layered
over the chat's left edge.
- L-shape SVG connector between chat and overlay: muted grey resting
state + brand-blue glow + bright line that re-draw via `pathLength` on
every tool change.
- Mock chat hidden below lg.
### Homepage sections
- **`HomeFeatures`** — `Everything you need to ship production agents.`
2×2 grid with bespoke visuals per pillar: 8×2 toolkit grid with `+1K`
cell, sessions panel (`USER_ID` + connected apps), triggers feed (`LIVE`
indicator + recent events), and a workbench mock with animated 4×2 CPU
lights. `auto-rows-fr` on `sm:` so cards equalize on tablet/desktop but
breathe on mobile.
- **`HomeSurfaces`** — `Three ways to use Composio.` bento: Developer
card spans full width (`md:col-span-3`) and shows 8 provider logos
(Anthropic, OpenAI, Vercel AI, Google, LangChain, CrewAI, LlamaIndex,
Mastra). Row 2: For You (with Claude / Codex / Cursor / Windsurf /
OpenClaw client logos), CLI (with `curl ... | bash` install snippet and
functional copy button), Agents.
- **`HomeResources`** — `Reach for the rest.` six-card footer row with
Quickstart, API reference, Cookbooks, Changelog, Toolkits,
Troubleshooting.
### Other
- Ports the landing-page hero into `components/landing-hero/` (kept
under the original `DocsHero` for easy revert; commented out, V2 wired
in).
- Theme-aware `--hero-*` CSS vars for chat-skin colors so the chat reads
in both light and dark.
- Removes the old `Works with your stack` provider grid (the providers
now live inside the Developer surface card).
## Test plan
- [ ] Verify hero animation cycles through 3 examples on desktop
- [ ] Verify L-shape connector pulses in brand blue on every tool change
- [ ] Verify chat mock is hidden on mobile and left column reads on its
own
- [ ] Verify dark mode (chat skins, connector, card surfaces, code
blocks)
- [ ] Verify CLI install copy button copies and toggles the icon to ✓
- [ ] Verify all chip / card hrefs resolve
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
Three small docs polishes:
- **Hide the disgusting "Ask AI" side tab.** The Decimal widget renders
its own `.decimal-widget-sidebar-tab` launcher (vertical pill with
sideways text) on every page. We already trigger the widget from our own
"Ask AI" button in the nav, so the third-party launcher is redundant
*and* ugly. Hidden via CSS in `app/global.css`.
- **Fix the Playground nav link.** It pointed at
`platform.composio.dev/auth?next_page=/tool-router` — which (a) hits a
dead host now that platform has moved to `dashboard.composio.dev`, and
(b) lost the playground's connect check on the redirect. Repointed to
`https://dashboard.composio.dev/~/project/playground`, which is the
dashboard's smart-resolver route: it handles login (`?next=`), looks up
`last_visited` / default org+project, and lands the user on
`/{org}/{project}/playground` with the connect step intact. Same fix
applied to the toolkits landing CTA and the welcome-page Playground
card.
- **Trim the welcome page.** Dropped the duplicated intro Cards row, the
"Get Started" / "Explore" / "Features" / "Community" headers, and the
secondary Features grid. Now it's: intro → AIToolsBanner → Quickstart →
Toolkits + Playground → Providers. Much cleaner.
## Test plan
- [ ] `bun run scripts/validate-links.ts` passes (already verified
locally — 0 errors)
- [ ] On preview deploy, the side "Ask AI" tab is gone
- [ ] Clicking "Playground" in the nav (logged out) lands on login →
playground; (logged in) lands on `/{org}/{project}/playground`
- [ ] Welcome page renders without missing-icon errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The rightmost box in the triggers-flow figure (the receiver inside
"Your Application") was labelled "Webhook Endpoint", which conflicts
with our docs vocabulary: webhook_endpoint is the Composio-side
resource that owns the ingress URL we register with the provider, not
the URL the customer's app exposes. The customer-side URL is a
webhook_subscription.
Update both the light and dark SVGs to label that box "Webhook
Subscription". Also reword the alt text on the Figure in triggers.mdx
("your webhook endpoint" → "your webhook subscription URL") so the
non-visual experience matches.
The leftmost box "Webhook Receiver" is unchanged — it's a generic
descriptive label for Composio's intake side, not a vocabulary term.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`) — latest v3.1 and v3.0 API specifications
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/reference/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`) — latest v3.1 and v3.0 API specifications
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/reference/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: composio-ci-bot[bot] <272436788+composio-ci-bot[bot]@users.noreply.github.com>
Co-authored-by: Sushmitha Mallesh <sushdec6@gmail.com>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`) — latest v3.1 and v3.0 API specifications
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/reference/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
- Re-fetch OpenAPI spec which now includes v3.1 tool endpoints (hermes#8990)
- Update fetch-openapi.mjs to remove older API versions when a newer one
exists for the same endpoint path (e.g. v3 hidden when v3.1 available)
- Update generate-api-index.ts with the same version deduplication logic
- Regenerate API reference index pages
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CI re-added consumer endpoints that lack x-internal tag on backend.
Remove them until the hermes deploy propagates the tag.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove /api/v3/org/consumer/project/resolve and
/api/v3/org/consumer/connected_toolkits from openapi.json, delete the
Organization Management index page, and remove the consumer resolve
line from the Projects index.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove /api/v3/org/consumer/project/resolve and
/api/v3/org/consumer/connected_toolkits from the public OpenAPI spec
and reference pages. These are internal endpoints that will be tagged
x-internal on the backend side.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove /api/v3/org/consumer/project/resolve and
/api/v3/org/consumer/connected_toolkits from the public OpenAPI spec
and reference pages. These are internal endpoints that will be tagged
x-internal on the backend side.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix required parameter badges by reading JSON Schema `required` array
from parent level instead of per-property boolean (was always undefined)
- Remove stale category/categoryLabel fields from meta-tools.json
- Align meta.json sidebar order with generator script (alphabetical)
- Remove examples display from meta tool detail component
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a programmatic Meta Tools reference under Reference > Meta Tools,
powered by data fetched from the Tool Router API.
- Generator script fetches tool schemas from API, produces JSON + MDX
- CI auto-updates via docs-update-data.yml on Apollo deploys
- Individual tool pages show tags, input parameters, and response schemas
- .md endpoint renders full parameter details for LLM consumers
- Updated existing docs to include COMPOSIO_GET_TOOL_SCHEMAS
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add iconDark prop support to ConnectClientOption (dark:hidden/dark:block pattern)
- Create dark variants for mcp.svg and notion.svg (black fills → white)
- Improve selected tab contrast in dark mode (dark:bg-fd-accent/60)
- Extract shared ClientIcon component for consistent dark mode handling
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a new documentation page for Composio Connect — a consumer-facing
guide for adding Composio tools to AI agents via MCP. Includes setup
instructions for 13 clients (Claude Code, Codex, OpenClaw, Claude
Desktop, ChatGPT, Cursor, Notion, VS Code, Windsurf, Cline, Agent
Builder, n8n, and generic MCP URL).
- New ConnectFlow component with popular tabs + dropdown for other clients
- Client logos copied from dashboard repo
- Fix LLM markdown output: move brace-stripping regex inside
code-block-aware loop to preserve JSON code blocks
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rahul Tarak