This PR:
- builds on top of https://github.com/ComposioHQ/composio/pull/3966
- enables `typescript/no-explicit-any` (error, `fixToUnknown`) for docs
in `docs/.oxlintrc.json` and removes every remaining explicit `any` in
docs code
- parses untyped/external data once at the boundary with zod v4 schemas
and lets `z.infer` types flow downstream — no hand-rolled `'x' in obj`
guard chains, no `as`-casts of untyped page data, no
`docs/lib/unknown-value.ts`
- adds domain schema modules: `docs/lib/toolkit-schema.ts` (recursive
JSON-Schema node, raw tool/trigger payloads, list envelopes) and
`docs/lib/reference-page-data.ts` (fumadocs reference page data for both
reference routes)
- rewrites `validate-links.ts`, `generate-toolkits.ts`,
`generate-meta-tools.ts`, the `llms.mdx` route, and
`deprecated-api-sidebar.tsx` on those schemas with identical validation
outcomes
- carries the pure typing improvements from the earlier attempt (typed
reference source in `source.ts`, `LLMPage`/`PageLike`, typed
`ClientLogo[]` in `logo-bar.tsx`, component `any` removals)
- adds `tests/static/toolkit-schema.test.ts` and
`tests/static/generate-toolkits.test.ts` pinning the transform shapes;
no changeset (docs is not published)
## Context
Second of the three-PR split of #3958, replacing its rejected
structural-guard approach with zod schemas at the data boundaries.
Verified with `bun run lint`, `bun run types:check`, `bun test
tests/static/` (125 pass), `bun run lint:links`, and a full `next
build`.
## Review follow-up
Addressed the regressions reported in [the Zod boundary
re-review](https://github.com/ComposioHQ/composio/pull/3967#issuecomment-5105279224):
scalar JSON Schema enums and auth defaults are preserved as strings,
malformed toolkit page envelopes abort generation, and the pre-refactor
empty-string fallbacks are restored. Regression coverage lives in
`tests/static/toolkit-schema.test.ts` and
`tests/static/generate-toolkits.test.ts`.
Verified on `2f26c40be` with `bun test tests/static/` (125 pass), `bun
run types:check`, and `bun run lint` (0 errors; existing warnings only).
## What
Two changes to the docs install experience:
**1. Package-manager picker on install code blocks.** New
`PackageInstall` client component
(`docs/components/package-install.tsx`): the code block's copy button
opens a dropdown of package managers. Selecting one rewrites the
displayed command and copies it to the clipboard.
- TypeScript blocks: npm (default, `npm install`) / pnpm / bun / yarn
(`<pm> add`)
- Python blocks: uv (default, `uv add`) / pip (`pip install`)
- The menu is portaled to `document.body` so it isn't clipped by the
`Tabs`/`CodeBlock` overflow containers, and closes on outside click,
Escape, or real scroll movement.
**2. `@composio/slim` callout in the quickstart.** The quickstart
TypeScript install blocks carry display-only `#` comment lines noting
that `@composio/core` ships its docs and TypeScript source in the
package (inspectable to coding agents) and that `@composio/slim` is the
smaller install with the same API. Comment lines are rendered muted and
are **never copied** — the picker copies only the command.
## Where
Converted every plain `npm install` / `pip install` code block under
`docs/content` (quickstart, all provider pages, single-toolkit MCP,
custom tools, migration guides, standup example, SDK reference indexes).
The TS reference index's manual npm/pnpm/yarn/bun tabs collapse into one
picker. The two SDK-reference generators
(`ts/packages/core/scripts/generate-docs.ts`,
`python/scripts/generate-docs.py`) emit the new component so
regeneration keeps it. Flagged upgrade commands (`pip install
-U/--upgrade`) and the bun-first examples were left as-is.
## Verification
- `bun run types:check` — pass
- `bun run build` — pass
- `eslint` on touched TS files — clean (remaining repo lint errors are
pre-existing on `next`)
- Visual check via dev server + browser: comment lines render muted
below the command, picker opens npm/pnpm/bun/yarn (uv/pip on Python
tabs), selecting a manager rewrites the command, and the clipboard
receives exactly the command with no comment lines.
Docs-only behavior change; no changeset (generator-script edits don't
touch published code).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This PR:
- supersedes https://github.com/ComposioHQ/composio/pull/3642 and
credits @shamsharoon for the original Eve provider and iMessage work
- rebases the integration onto the current `next` branch and resolves
its lockfile conflicts
- publishes an isolated `@composio/experimental/eve` entry with the
correct Eve 0.12+ peer contract
- adds recoverable per-session discovery, native Eve context
propagation, and durable approval policies for direct and batched side
effects
- centralizes circular-safe auth-link extraction across Eve and Pi and
replaces dense conditional expressions with named control flow
- hardens the iMessage example against `osascript` option injection,
unsafe trigger scoping, and third-party prompt injection
- preserves completed local-tool results when a mixed local/remote batch
loses its remote transport
- consolidates the example documentation onto shared components,
documents direct model-provider credentials, and clarifies that the
browsable source is not yet a standalone fixture
- verifies the change with 999 core tests, 32 experimental tests,
package builds/typechecks, packed peer-isolation smokes, and a
production docs build
---------
Co-authored-by: shams haroon <144290365+shamsharoon@users.noreply.github.com>
Co-authored-by: shams haroon <shamsharoon7@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: shams haroon <shams@composio.dev>
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>
## 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
- Stack this PR on top of #3455 (`docs/love-fixes`).
- Rework the former Core Concepts / Getting Started / Guides / Features
area into a smaller set of sections:
- Build with sessions
- Authenticate users
- Triggers and webhooks
- Direct Tool Execution Guides (Legacy)
- Other topics
- Move conceptual session pages (`how-composio-works`, users/sessions,
tools/toolkits, authentication, workbench, triggers) into the
appropriate grouped sections.
- Merge duplicated custom-auth content into `Managed vs custom auth`
(`/docs/custom-app-vs-managed-app`) and redirect the old
`/docs/using-custom-auth-configuration` URL.
- Trim repeated OAuth-app setup from white-labeling docs so that page
focuses on branding, callback-domain routing, and post-auth redirect UX.
- Clean up “What to read next” cards so non-legacy pages no longer point
at direct-execution docs and first point to the next item in their
section where possible.
- Fix the session lifecycle contradiction in `how-composio-works` so it
matches the current persisted/reusable session model.
## Checks
- `cd docs && bun run lint:links`
- `cd docs && bun test tests/static/navigation.test.ts`
## 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>
Add searchable managed auth page at /toolkits/managed-auth with tabs
for managed vs unmanaged OAuth toolkits, copy slugs, and auto-tab
switching on search. Use fumadocs Cards on toolkits landing page.
Add server-side markdown generation for LLM view. Fix title/back-link
ordering for toolkit MDX pages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a banner component to each quickstart integration flow with
"Skills" link and "Copy prompt" button. Includes 6 detailed prompts
(OpenAI Agents, Claude Agent SDK, Vercel AI × Native/MCP) with
complete working code, install commands, rules, and verify checklists.
The PromptBanner is stripped from .md output for LLM readers.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The "Build an App Connections Dashboard" card was the only card without
an icon in a group where the other three cards all had icons.
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>
Stripe-inspired two-column layout with client-side filtering.
Markdown converter handles GlossaryTerm→heading conversion for
LLM-friendly output. Added glossary link to LLM footer, search
shortcuts, and CLAUDE.md documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add "Build a Chat App" cookbook with external code files via <include>
- Restructure welcome page: hero cards, Get Started, AI tools banner, Explore
- Create AIToolsBanner component with grid pattern, skills command, and context file links
- Add markdown conversion for AIToolsBanner in LLM endpoint
- Add chat-app to cookbooks navigation after templates
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use distinct lucide icons for each card to better communicate
the topic at a glance instead of the same BookOpen everywhere.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add TemplateCard and TemplateGrid components with side-by-side
image/video layout for full-width cards
- Add Templates page under Examples with 9 projects across two sections
- Add TemplateCard conversion to mdxToCleanMarkdown for llms.txt output
- Include media assets (GIFs, videos) for TrustClaw, Atlas, Gamma,
and Data Analyst Agent
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Both Accordion and Accordions now imported from the same place
in faq-section and auth-details-section.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Export the auto-ID Accordion wrapper from mdx-components.tsx and
import it in faq-section.tsx instead of duplicating the slugify logic.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move duplicated slugify logic from mdx-components.tsx and
faq-section.tsx into lib/utils.ts. Also fix import ordering in
mdx-components.tsx.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wrap the fumadocs Accordion component to auto-generate an id from the
title prop, so every accordion gets a copy-link button and can be
deep-linked via URL hash. The link icon is hidden by default and shown
on hover.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a new docs page explaining the organization/project hierarchy,
project management via API, and project settings. Also set up mermaid
diagram rendering for the docs site (remark plugin + client component).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Clicking a section heading now copies the full URL with anchor
to the clipboard and shows a brief checkmark confirmation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace ### headings inside Steps with StepTitle component that
renders visually like a heading but uses a div element, preventing
fumadocs from extracting them into the Table of Contents.
This fixes the issue where each framework tab (OpenAI Agents, Claude
Agent SDK, Vercel AI) with Native/MCP variants was adding duplicate
"Install", "Configure API Keys", and "Create session and run agent"
entries to the TOC.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add connect link auth flow video recording
- Add BookOpen icon for guide cards
- Style cards with subtle gray background and orange hover border
- Add Next steps section with related guide cards
- Update users-and-sessions with BookOpen icons
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create IntegrationTabs component for quickstart page
- Add Native Tools and MCP integration options within each framework
- Use SVG icons matching provider card style
- Merge quickstart content with multi-turn conversation examples
- Support light/dark mode for icons
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create tool-type-selector.tsx component with card-based selection
- Add MCP logo assets (light and dark variants)
- Update OpenAI Agents page with new structure
- Register components in mdx-components.tsx
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create Features section with Triggers, CLI, and MCP
- Move MCP pages to expandable mcp/ folder
- Rename using-triggers.mdx to triggers.mdx
- Update welcome page with cleaner layout (Quickstart, Playground, Toolkits, Auth cards)
- Add redirects for old URLs
- Update toolkit count from 500+ to 800+
- Add Play and Terminal icons to mdx-components
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add QuickstartFlow and FrameworkOption components for framework switching
- Support OpenAI Agents, Claude Agents, LangChain, and Vercel AI
- Code snippets match platform snippets exactly
- Python/TypeScript tabs with language persistence
- Clean component design without unnecessary wrappers
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Alberto Schiabel