PR #4099 dropped 8 auth pages from meta.json. That was a net win for
machines (Loop 5 eval: 84/100 vs 77/100, tool-routing failure mode gone)
but it made the pages unreachable by clicking. PostHog, weekday-matched
and control-adjusted, shows the affected pages down 14-64pp beyond the
site-wide baseline drift.
Restore human navigation without touching the machine-facing wins:
- authentication.mdx becomes authentication/index.mdx and the 7 sibling
auth pages move into the folder. /docs/authentication keeps its URL
(fumadocs serves index.mdx at the folder route), so Core concepts
still shows one row and the top-level sidebar row count stays 20.
- shared-connections moves into extending-sessions: it is experimental
and is a session capability, not a core auth concept.
- "Migration and security" splits into "Migration" and "Security and
data" — separator headings, not clickable rows.
- Drop AUTHENTICATION_GUIDE_URLS from app/llms.txt/route.ts. The pages
are back in the page tree, so they emit automatically under Core
concepts -> Authentication; the hardcoded list would now duplicate.
- 8 permanent redirects for the old URLs (36-42% Google entry rate on
most of them), plus existing redirect destinations repointed so none
of them chain.
- ~90 inbound links rewritten across content, api-overviews, app, lib
and agent instructions. lint:links is the gate: 0 errors.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Summary
Implements the docs half of **PLEN-2793** — renders a typed public
reference for the payloads Composio delivers to customer webhook URLs,
under **API Reference → Webhook Events**.
Pairs with platform PR ComposioHQ/platform#11389, which generates the
spec.
## What's here
- **`docs/public/openapi-webhooks.json`** — the generated OpenAPI
**3.1** spec (top-level `webhooks`: `composio.trigger.message`,
`composio.connected_account.expired`, `composio.trigger.disabled`),
produced from the webhook payload Zod schemas in Apollo (SSOT). Finishes
the earlier untracked WIP: adds the missing `trigger.disabled` event and
reuses shared schemas as `$ref` (`WebhookEventEnvelope`,
`ConnectedAccountDetailed`).
- **`docs/lib/openapi.ts`** — adds the spec as a **second input** to the
v3.1 reference source. Fumadocs (`fumadocs-openapi`) renders the
`webhooks` block natively; operations group under the "Webhook Events"
tag at `api-reference/webhook-events/*`.
- **`webhook-events/index.mdx`** — landing page listing the three
events, cross-linked to the Webhook Subscriptions API and signature
verification.
## Why a separate 3.1 spec
`webhooks` is a 3.1-only top-level field; the main `openapi.json` is
3.0. A separate file keeps the main spec (and its sync pipeline)
untouched and avoids the docs' union-normalisation pass. See the
platform PR for the full rationale.
## Verified locally
- [x] `bun scripts/validate-links.ts` — **0 errors** (the generated
`handle_composio_*` webhook pages resolve; no collision with the
hand-authored `index.mdx`)
- [x] `bun test tests/static/` — 33 pass / 0 fail
- [x] `bun run types:check` — clean
## Notes
- Setup, subscription, and signature-verification docs already exist
(`setting-up-triggers/*`) and are cross-linked, not rewritten.
- Follow-up (optional): auto-sync the webhooks spec from Apollo on prod
deploy (currently committed by hand), mirroring the main-spec
`docs-update-data` pipeline.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@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>
This PR is **part 3 of 3** splitting
https://github.com/ComposioHQ/composio/pull/3505 to make the removal of
the old 2025 custom tools easier to review. It carries the **docs**
slice.
- builds on top of https://github.com/ComposioHQ/composio/pull/3509
(stacked — this PR's base is `remove-ts-custom-tools`)
- deletes the legacy `/docs/tools-direct/custom-tools` page and prunes
its `meta.json` entry
- retargets redirects for `/docs/tools-direct/custom-tools` and the
`:path*` wildcard to `/docs/toolkits/custom-tools-and-toolkits`, with
matching `redirects.test.ts` expectations
- updates migration-guide, glossary, proxy-execute, and executing-tools
prose; fixes the `ctx.proxyExecute` example to include the required
GitHub toolkit
- updates agent guidance (`AGENTS.md`, `building-agents` skills) to the
experimental custom tools API
## Notes
- This slice is a byte-identical subset of #3505 — the three split
branches recombine to that PR's exact tree. Docs link/redirect checks
could not run in the source checkout (missing docs deps); CI runs them
per PR.
## Summary
- Rework the CLI docs around Composio for You / Claude Code usage, with
sections for knowledge work, `run`/sub-agents, trigger listening,
developer workflows, and unsupported direct CLI embedding.
- Move CLI into the top of Other topics and remove single-toolkit MCP
from the Docs sidebar.
- Move Changelog into Reference after Errors, with a grouped single-page
changelog, scroll-based date anchors, and redirects from old
`/docs/changelog` URLs.
- Add the Claude logo to the “Open in Claude” page action.
## Tests
- `cd docs && bun run lint:links`
- `cd docs && bun test tests/static/navigation.test.ts`
- `cd docs && bun run build`
## 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 "Sending users directly to the OAuth provider" section to direct execution white-labeling page
- Rename redirect sections on both pages for clarity: "Routing the callback through your domain"
- Add 301 redirect from /docs/white-labeling to /docs/white-labeling-authentication
- Fix Python code example to use correct ConnectionState structure
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The vercel-chat cookbook pointed to an external repo with outdated patterns.
Build a Chat App covers the same use case with the session-based approach.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove old /docs/providers → /docs/tools-and-toolkits redirect
- Reorder providers index: Agent Frameworks section first, then AI SDKs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Removes wildcards for /reference/api-reference/v3/*, connectedaccounts/*,
/reference/connected-accounts/*, /reference/auth-configs/*, and
/reference/app-connector/* to prevent blocking dynamically generated pages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
These redirects were catching all /reference/api-reference/{tag}/:operationId
URLs and redirecting them to the index page, preventing real OpenAPI-generated
endpoint pages from loading (e.g. projects/getOrgProjectConfig returned 308).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Separate webhook verification and connection expiry events from
triggers into standalone guides, since they are distinct concepts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Analyzed 14K+ Datadog logs from the last week, tested all URLs against
the live site, and added redirects for the 98 confirmed real 404s.
Key fixes:
- /docs/frameworks/claude-code → /docs/providers/anthropic (AI agents hitting this)
- /apps/* → /toolkits/* (old URL scheme)
- /docs/guides/* → their new locations
- /tool-router/* remaining gaps
- Old concept/auth/cryptokit paths from v1 docs
- API reference operation ID gaps (apps, connections, api-keys, etc.)
- Old versioned API paths (v1, v-1, v3)
Build tested locally, all redirects return 308, existing pages unaffected.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update /docs/using-triggers redirect to point to /docs/setting-up-triggers/creating-triggers instead of the old /docs/triggers.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The catch-all :operationId redirects would intercept valid OpenAPI-generated
operation pages (e.g., /reference/api-reference/tool-router/postToolRouterSession)
and incorrectly redirect them to section indexes.
These pages ARE dynamically generated by fumadocs-openapi and linked from
the index.mdx files in each section.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add redirects for old Fern API reference operation ID pages to their
section index pages. These operation-specific pages (e.g.,
postToolRouterSession) don't exist in the new fumadocs structure -
only index.mdx files exist for each section.
Uses :operationId (single segment) pattern to avoid redirecting the
working index pages while catching the broken operation ID URLs.
From Datadog 404 monitoring:
- /reference/api-reference/tool-router/postToolRouterSession → /reference/api-reference/tool-router
- /reference/api-reference/triggers/postTriggerInstancesBySlugUpsert → /reference/api-reference/triggers
- etc.
Also adds redirects for old Fern SDK reference and example URLs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Old Fern URLs like /api-reference/tools/post-tools-execute-by-tool-slug
now redirect to /reference/api-reference/tools/post-tools-execute-by-tool-slug,
where proxy.ts handles the kebab-to-camelCase conversion.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add permanent redirects for old Fern documentation URLs discovered
via Datadog 404 monitoring. Covers old introduction, tool-calling,
framework, python SDK, authentication, changelog, MCP, patterns,
guides, and moved docs pages.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Figure component: Use Next.js Image with fade-in transition
- Video component: Simplify to thin wrapper, use consistently
- next.config: Enable AVIF/WebP formats, add responsive sizes
- Standardize video usage across MDX files
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move mcp/index.mdx to single-toolkit-mcp.mdx (no folder)
- Update all references and redirects
- Remove Multi-toolkit servers section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete quickstart-tool-router.mdx (content merged into quickstart.mdx)
- Remove from navigation meta.json
- Update redirect to point to /docs/quickstart
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Created tools-direct/ folder with all tool-related pages
- Made Tools folder collapsible (defaultOpen: false)
- Added redirects for old URLs
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Created new "Advanced" section after Features
- Moved auth pages to auth-configuration/ folder
- Made Authentication folder collapsible (defaultOpen: false)
- Added redirects for old URLs
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move Tool Router content to main docs section:
- Authentication pages → /docs/authenticating-users/
- Guide pages → /docs/guides/
- Toolkit pages → /docs/toolkits/
- Add MCP and native tool examples to provider pages:
- openai-agents.mdx: Usage with Tools, Usage with MCP, Usage with direct tools
- vercel.mdx: Usage with Tools, Usage with MCP, Usage with direct tools
- anthropic.mdx: Usage with MCP, Usage with direct tools
- Remove Tool Router section entirely:
- Delete content/tool-router/ folder
- Delete app/(home)/tool-router/ routes
- Remove from navigation, search, and LLM routes
- Remove "Usage with direct MCP servers" sections (deprecated approach)
- Update all internal links from /tool-router/* to /docs/*
- Add redirects for old Tool Router URLs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
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>
- Create tool-router-beta.mdx in docs/migration-guide/
- Add to migration guide index and meta
- Remove from tool-router meta.json
- Add redirect from /tool-router/migration-guide
Replace 4 separate routes + 16 rewrites with:
- 1 unified route that handles all sources
- 2 rewrite rules: /:path*.md and /:path*.mdx
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add PageActions to createDocsPage (fixes tool-router, examples)
- Add PageActions to reference pages
- Add .md routes for tool-router, examples, reference
- Extend rewrites to support all sections including index pages
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Following Lee Robinson's Agent-Ready principles:
- Add .md URL extension support (in addition to .mdx)
- Add proxy.ts for Accept: text/markdown header support
- Same URL serves HTML to browsers, Markdown to AI agents
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add route handler and rewrite to serve markdown content at /docs/:path*.mdx
for AI agents to fetch page content directly.
- Add app/llms.mdx/docs/[[...slug]]/route.ts route handler
- Add rewrite rule in next.config.mjs
- Update getLLMText to include page URL in title
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Soham Basu