This PR:
- fixes a regression introduced by
https://github.com/ComposioHQ/composio/pull/3956: fumadocs-openapi 11's
`groupBy: 'tag'` silently skips operations whose tag is not declared in
the document's top-level `tags` array, which 404'd all 16 Projects and
Organization Management operation pages (e.g.
`/reference/api-reference/projects/postProjectUsageSummary`) on both
v3.1 and v3, and dropped them from the sitemap and search index
- adds `declareOperationTags()` (`docs/lib/openapi-tags.ts`), applied at
spec load time in `lib/openapi.ts` (covers build-time-fetched specs) and
at sync time in `scripts/fetch-openapi.mjs`, which now also warns when
the upstream payload omits tags; the checked-in specs are normalized
accordingly (purely additive)
- adds CI guards in `tests/static/api-reference-routes.test.ts`: spec
invariants (every visible operation has a tag and `operationId`),
bidirectional spec-vs-generated-routes set equality through the
production loader path, a negative test pinning fumadocs' silent-drop
behavior (fails when upstream fixes it, signaling the workaround can be
retired), and validation that every `ApiEndpointsTable` quick-link href
resolves to a generated page
- extends `Docs - Check Links` with a nightly (02:30 UTC) + manual
external-URL sweep via a new `lint:links:external` script; the validator
only fails on evidence a link is dead (404/410 or repeated network
errors, with UA/timeout/GET-fallback/retry and per-URL caching) and
scheduled failures file a deduplicated tracking issue; PR runs keep the
fast internal-only check
- fixes six dead external links the first sweep found (moved Claude
Agent SDK docs, stale dashboard settings URL ×2, a `master`-branch path
now pinned to tag `0.5.0+post.1`, and two removed `ComposioHQ` example
repos whose mentions were dropped — their code is embedded in the pages
via `RepoBrowser`)
## Context
fumadocs-openapi 10 generated a page for any tag string found on an
operation; v11 requires the tag to be declared top-level and skips
silently otherwise (`preset-auto.js`: `builder.fromTagName(tag)` →
`continue`, no warning). The backend spec generator omits `Projects`,
`Organization Management`, and `Invite Codes` from `tags`, so their
operation pages vanished while the checked-in MDX tag landing pages kept
rendering with dead quick links. With the normalizer, the generated URL
set is byte-identical to the pre-#3956 set (234 routes, verified via
`getReferenceSource().getPages()` diff); no revert needed.
Existing checks missed this because `lint:links` only extracts markdown
links and `Card` hrefs (the dead links live in `ApiEndpointsTable`'s
array prop) and validates against the same loader that shrank, and the
integration suite samples fixed routes under tags that survived. The new
completeness guard derives expectations from the specs themselves, so
routine data syncs don't churn it.
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
- **Dark/light theme switcher** in the navbar. Drops `forcedTheme:
'light'` so the toggle actually flips themes; sidebar footer toggle
stays disabled so there's only one switcher.
- **Dark mode color pass.** `--composio-brand` lifts to a muted
`#5B8BF0` (the deep `#0007cd` brand reads as unlit text on `#0f0f0f`).
Card / muted greys nudge to `#1c1c1c` / `#1f1f1f`. Borders drop from 10%
white to 6% so card edges sit back. `--border` / `--sidebar-border`
follow suit.
- **Square navbar.** Search input and the new theme toggle render with
`border-radius: 0` to match the rest of the navbar.
- **Welcome-page scroll reset.** New `ScrollReset` client component
wired into the root layout. Next.js App Router skips its built-in scroll
reset when the new route resolves to the same dynamic `page.tsx` segment
— every link from the welcome page to a `/docs/*` page hits this case,
so users were landing mid-page on the new route. Now `usePathname()`
change ⇒ `window.scrollTo(0, 0)` (skips first render and any
hash-bearing navigation).
- **`platform.composio.dev` → `dashboard.composio.dev`** across docs
content + the direct-execution LLM guardrail (28 files).
`docs/public/openapi*.json` left alone — auto-generated, and the
surviving reference is literally to the legacy dashboard.
## Test plan
- [ ] Toggle theme from the navbar; verify both light and dark render
- [ ] In dark mode, confirm "Docs" nav active state, chip icons,
"CONNECTED" labels, and Ask AI button read clearly against `#0f0f0f`
- [ ] Scroll to the bottom of `/docs`, click any link in HomeResources /
HomeSurfaces / HomeFeatures — the new page should land at scroll 0
- [ ] Click a TOC `#anchor` link inside a docs page — should still
scroll to the anchor (not get clobbered to 0)
- [ ] Spot-check a few rewritten URLs in cookbooks / quickstart — all
`platform.composio.dev` should now be `dashboard.composio.dev`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
- Fix /toolkits/introduction → /toolkits in troubleshooting pages
- Remove broken relative links to source files in cookbooks
- Remove unnecessary "See Authenticating Users" link in errors.mdx
- Add dynamic toolkit slug validation from toolkits.json to link checker
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add authentication page explaining API key usage
- Add errors page with HTTP status codes and error types
- Add rate limits page with plan-based limits and headers
- Improve overview page with REST API table and SDK cards
- Set API Reference and SDK Reference folders to expand by default
- Remove navigation footer from OpenAPI reference pages
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Match Stripe's cleaner table format:
- Separate columns for code, status name, and description
- Remove cluttering backticks
- Group 5xx errors together
- Add more helpful descriptions
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Changed page title from "API Errors" to "Errors"
- Added SEO keywords
- Updated cross-references in troubleshooting section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove internal error codes (not useful to users)
- Remove retry code example
- Focus on what users care about: error messages and how to fix them
- Follow Stripe's clean, focused documentation style
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add comprehensive API errors documentation with error codes, HTTP status codes, and resolutions
- Cross-reference from troubleshooting pages
- Follow Stripe-style documentation approach with tables for error codes
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Alberto Schiabel