## Summary
Automated sync of backend data into the docs site. Triggered by:
`workflow_dispatch`.
## 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 staging
- **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/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
This PR:
- fixes the `docs.composio.dev/toolkits` search returning 0 results for
toolkits like Workday that exist in the catalog
- paginates `fetchToolkits()` in `generate-toolkits.ts` by following
`next_cursor`: `GET /api/v3/toolkits` silently caps `limit` at 1000 per
page and defaults to usage ordering, so the previous single-request
fetch shipped only the top-1000 toolkits — about half of the ~2.1k
catalog
- dedupes across pages by slug (pages can overlap when the catalog
shifts between cursor fetches) and throws instead of silently truncating
if the catalog ever outgrows the page guard, mirroring the dashboard's
`listToolkits` procedure
- fixes the `docs-update-data.yml` workflow, broken since the
sessions-first docs rewrite
(https://github.com/ComposioHQ/composio/pull/3637) moved the generated
meta-tools MDX to `docs/content/toolkits/meta-tools/`:
`create-pull-request` aborted on the stale
`docs/content/reference/meta-tools/` pathspec, so every scheduled data
sync since then failed at the Create Pull Request step and docs data
went stale
- updates the request-volume notes in `fetch-with-retry.ts` and
`scripts/README.md` (~3000 → ~6500 requests per run); the existing 429
backoff already absorbs the larger run
## Context
The toolkits landing page filters a build-time snapshot
(`public/data/toolkits-list.json`) client-side, so every toolkit missing
from the snapshot is unsearchable and its detail page has no data. The
snapshot regenerates via the scheduled `docs-update-data.yml` workflow;
with both fixes in place the automated data PR picks up the full catalog
and the "Browse N toolkits" count grows from 1000 to the real catalog
size.
Verified offline by running the script against a stubbed paginated
backend (1500 toolkits across 2 pages): all pages are fetched, ordering
is preserved, no duplicates. `bun run types:check` and eslint pass. A
manual `workflow_dispatch` of the fixed workflow on this branch produced
the full-catalog data PR.
## Summary
Automated docs update triggered by SDK source changes on `next`.
- Claude reviewed the SDK diff and updated guides, FAQs, or examples
that reference changed APIs or features.
- The docs `@composio/*` dependencies were realigned to their latest
published releases so Twoslash snippets and example apps validate
against versions users can actually install.
## Review checklist
- [ ] Changes accurately reflect the new SDK behavior
- [ ] No unrelated docs were modified
- [ ] Code examples are correct and complete
- [ ] If a documented feature is not published yet, the Twoslash build
will fail — wait for the release instead of working around it
Generated by Claude Code via GitHub Actions.
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
## Summary
- Refresh the checked-in v3.1 and v3 OpenAPI snapshots from the live
backend specs using `bun run scripts/fetch-openapi.mjs`.
- Regenerate API reference index pages with `bun run
generate:api-index`.
- Surfaces `DELETE /api/v3.1/tool_router/session/{session_id}` in the
Tool Router API reference.
- Includes the other upstream generated spec changes from the same
auto-fetch, including generated API Keys and Organization Management
section indexes.
## Verification
- `bun run scripts/fetch-openapi.mjs`
- `bun run generate:api-index`
- `git diff --check`
- `bun run build`
## Notes before merge
- This is intentionally the full auto-generated OpenAPI refresh, not the
surgical two-file patch.
- The generated backend OpenAPI still contains some `internal` wording
in descriptions; left as-is to preserve the auto-generated output.
- Confirm the newly generated API Keys / Organization Management
sections are intended to publish with this refresh.
---------
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
Auto-generated Python SDK reference docs from `python/composio/`.
Regenerates pages at `docs/content/reference/sdk-reference/python/` to
reflect changes in the Python package's public API (new methods, updated
signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Documents session deletion (`session.delete()`) and realigns the docs
site's `@composio/*` dependencies so the new snippet type-checks against
a published SDK.
## Changes
- **`docs/content/docs/configuring-sessions.mdx`** — adds a `###
delete()` section with Python and TypeScript examples and a
version-requirement callout (`@composio/core` ≥ `0.13.1` / `composio` ≥
`0.17.1`).
- **`docs/package.json` + `docs/bun.lock`** — bumps `@composio/core`
`^0.9.1` → `^0.13.1` (the release that adds `delete()`) and aligns the
provider packages to their `^0.10.x`/`^0.11.0` releases (peer
`@composio/core >=0.10.0 <1.0.0`).
## Why the dependency bump
The docs site type-checks every Twoslash snippet against the
`@composio/*` versions pinned in `docs/package.json`. Those pins were
stale (`@composio/core@0.9.1`), and `delete()` only exists on the
`Session` type from `0.13.1`, so the snippet didn't compile. The
original sync run worked around this with a `DeletableSession` cast;
this PR fixes the root cause by bumping the pins to published releases
that expose `delete()` natively and dropping the cast. The full docs
build (Twoslash validation) passes against the bump.
## Review checklist
- [ ] `delete()` examples accurately reflect the SDK behavior
- [ ] Version callout matches the releases that introduce `delete()`
- [ ] No unrelated docs were modified
## Notes
- Originally produced by the `Docs - Sync guides on SDK changes` run.
- Follow-up https://github.com/ComposioHQ/composio/pull/3709 prevents
this pin drift from recurring by realigning the docs `@composio/*` deps
automatically on each SDK sync.
---------
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
This PR:
- replaces the duplicated repo-local skill set with the requested
canonical `.agents/skills` taxonomy and short router `SKILL.md` files
backed by first-level references
- makes `.claude/skills` a compatibility symlink to `.agents/skills` and
removes hand-maintained Claude skill/rule copies
- moves docs agent guidance and decisions into neutral
`docs/agent-guidance/` and `docs/decisions/`, with `docs/CLAUDE.md`
reduced to a shim
- retires CLI Cursor rules after migrating CLI design, Effect source,
and client-cache sync guidance into `AGENTS.md` and `cli-command`
- adds nested `AGENTS.md` files for TS, core, providers, e2e, Python,
Python providers, and docs
- adds `pnpm validate:agent-skills` to validate skill frontmatter,
taxonomy, references, symlink invariants, stale paths, and command names
- implements missing Python `tst` and `snt` nox sessions that existing
Makefile targets already exposed
- no changeset: repository guidance/tooling only, no published SDK
package behavior
## Verification
- `pnpm validate:agent-skills` -> `Validated 14 canonical agent skills
and guidance invariants.`
- `for skill in .agents/skills/*; do python
/Users/jkomyno/.codex/skills/.system/skill-creator/scripts/quick_validate.py
"$skill" || exit 1; done` -> 14x `Skill is valid!`
- `pnpm --dir ts/packages/cli validate:skills` -> `Validated
composio-cli skill builds for stable and beta.`
- `cd python && uv run nox --list` -> includes `tst` and `snt`
- `cd python && uv run nox -s snt` -> 18 passed
- `cd python && uv run nox -s tst -- tests/test_imports.py` -> 8 passed
- `git diff --check` / `git diff --cached --check` -> clean
- stale reference search for retired docs/Claude/Cursor paths -> no
matches
## Forward Tests
- TypeScript core bug: loaded `bug-fixing`, `typescript-sdk`,
`typescript-testing`; found correct root/ts/core `AGENTS.md` route.
- Python provider: loaded `python-providers`, `python-testing`; found
missing nox sessions, fixed here.
- CLI command: loaded `cli-command`; found recording/changeset wording
gaps, fixed here.
- Cross-SDK drift: loaded `cross-sdk-parity`; again found Python nox
drift, fixed here.
- Docs + decision: loaded `docs-decisions`; found decision
template/index and Twoslash path gaps, fixed here.
## Notes
The first normal `git commit` attempt hit a lint-staged/Git stash
limitation while replacing `.claude/skills/` with a symlink (`path ...
beyond a symbolic link`). The final commit used `--no-verify` after the
validators and formatting checks above passed.
## Summary
Auto-generated TypeScript SDK reference docs from
`ts/packages/core/src/`.
Regenerates pages at `docs/content/reference/sdk-reference/typescript/`
to reflect changes in the core package's public API (new methods,
updated signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
This PR:
- normalizes Python SDK reference examples generated from source
docstrings
- rewrites the `Triggers.parse()` docstring so the generated
Flask/FastAPI examples are copy-pasteable
- strips nested Markdown fences before wrapping generated examples in
MDX code fences
- regenerates `docs/content/reference/sdk-reference/python/`
- adds regression coverage for the `Triggers.parse()` generated example
and fenced example normalization
- does not include a changeset because this only changes docs
generation, generated docs, and tests
## Verification
- `cd python && .venv/bin/python -m pytest tests/test_generate_docs.py
-q`
- `cd python && .venv/bin/ruff check --config config/ruff.toml
composio/core/models/triggers.py scripts/generate-docs.py
tests/test_generate_docs.py`
- `cd python && .venv/bin/ruff format --check --config config/ruff.toml
composio/core/models/triggers.py scripts/generate-docs.py
tests/test_generate_docs.py`
- `cd python && .venv/bin/python scripts/generate-docs.py`
- `cd docs && bun install --frozen-lockfile`
- `cd docs && bun run types:check`
## Summary
- Switch the docs Eve agent from the AI Gateway `openai/gpt-5.4-mini`
string to an Inception Labs Mercury 2 OpenAI-compatible chat model.
- Keep tool calling on the chat-completions path and pass Mercury's
`reasoning_effort=medium` through the AI SDK OpenAI adapter.
- Add `DOCS_AGENT_MODEL_FLOW` so the same agent can run either `mercury`
or the old AI Gateway flow for eval comparisons.
- Add docs-agent eve evals covering grounded docs answers, docs
retrieval, citations, and account-specific support refusal.
- Replace the docs-agent retriever with an in-process BM25-style lexical
ranker that returns bounded full content for the top results, so Mercury
gets rich context in one fast tool call instead of a serial
`search_docs` → `read_doc` round trip.
- Precompute BM25 term counts/document frequencies into the generated
`agent/lib/docs-index.ts` snapshot at build time, removing deployed
cold-start corpus construction while keeping retrieval in-process.
- Add opt-in search perf logging (`DOCS_AGENT_SEARCH_PERF_LOG=1`,
optional `DOCS_AGENT_SEARCH_LOG_QUERY=1`) with timings for tokenization,
corpus load/cache, ranking, hydration, total duration, corpus source,
and top URLs.
- Add `eval:agent` and `eval:agent:flows` scripts; `eval:agent:flows`
can run local model-flow comparisons or remote target comparisons via
`DOCS_AGENT_EVAL_TARGETS`.
- Add `INCEPTION_API_KEY` / optional Mercury and gateway model knobs to
`docs/.env.example`, and move `@ai-sdk/openai` to runtime dependencies
for the agent import.
## Notes
- This is intentionally an experiment to see how Mercury's diffusion
model behaves with Eve tool calling (`search_docs` and `read_doc`).
- Preview/runtime environments need `INCEPTION_API_KEY`;
`INCEPTION_MODEL` and `INCEPTION_BASE_URL` are optional overrides.
- The custom fetch prevents accidentally falling back to
`OPENAI_API_KEY` against Inception's endpoint.
- The docs search is lexical/in-memory, not vector search. The slow path
was mostly serial model/tool round trips and cold index construction,
not embedding lookup.
- The generated BM25 snapshot is process-local once loaded: warm for the
lifetime of the running Node/Vercel function instance, and reset on cold
starts, redeploys, or process restarts. The expensive term-count corpus
is now built at docs build time.
- Perf logs omit raw user queries by default; set
`DOCS_AGENT_SEARCH_LOG_QUERY=1` only when you explicitly want raw
query/term logging.
- Local A/B-style eval run:
```bash
DOCS_AGENT_EVAL_FLOWS=gateway,mercury bun run eval:agent:flows --
--strict
```
- Live target comparison:
```bash
DOCS_AGENT_EVAL_TARGETS=baseline=https://<prod>,mercury=https://<preview>
bun run eval:agent:flows -- --strict
```
## Tests
- `bunx eslint scripts/build-agent-index.ts agent/lib/docs.ts
agent/tools/search_docs.ts`
- `bun scripts/build-agent-index.ts` (wrote 133 pages + 1000 toolkits +
1139 BM25 rows)
- `DOCS_AGENT_SEARCH_PERF_LOG=1 EVE_FORCE_BUNDLE=1 bun -e "const
tool=(await import('./agent/tools/search_docs.ts?log=' +
Date.now())).default; await tool.execute({query:'create a session with
github tools'}); await tool.execute({query:'auth config connected
account'});"` (logs cold and warm timing JSON)
- `EVE_FORCE_BUNDLE=1 bun -e "const tool=(await
import('./agent/tools/search_docs.ts?bundle=' + Date.now())).default;
const started=performance.now(); const r=await
tool.execute({query:'create a session with github tools'});
console.log(r.retrieval, r.results[0].url, r.results[0].content.length,
Math.round(performance.now()-started)+'ms');"` (precomputed bundle path,
~12ms)
- `bun -e "const tool=(await import('./agent/tools/search_docs.ts?live='
+ Date.now())).default; const started=performance.now(); const r=await
tool.execute({query:'create a session with github tools'});
console.log(r.retrieval, r.results[0].url, r.results[0].content.length,
Math.round(performance.now()-started)+'ms');"` (live-content path,
~34ms)
- `EVE_FORCE_BUNDLE=1 bun -e "const tool=(await
import('./agent/tools/search_docs.ts')).default; await
tool.execute({query:'create a session with github tools'}); const
started=performance.now(); const r=await tool.execute({query:'auth
config connected account'}); console.log(r.results[0].url,
r.results[0].content.length,
Math.round(performance.now()-started)+'ms');"` (warm path ~2ms)
-
`PATH=/Users/cryogenicplanet/.vite-plus/js_runtime/node/24.15.0/bin:$PATH
./node_modules/.bin/eve info --json` (reports `status: ready`, `model:
inception/mercury-2`, `errors: 0`)
- `DOCS_AGENT_MODEL_FLOW=gateway
PATH=/Users/cryogenicplanet/.vite-plus/js_runtime/node/24.15.0/bin:$PATH
./node_modules/.bin/eve info --json` (reports `status: ready`, `model:
openai/gpt-5.4-mini`, `errors: 0`)
-
`PATH=/Users/cryogenicplanet/.vite-plus/js_runtime/node/24.15.0/bin:$PATH
./node_modules/.bin/eve eval --list`
-
`PATH=/Users/cryogenicplanet/.vite-plus/js_runtime/node/24.15.0/bin:$PATH
bun scripts/eval-agent-flows.ts --list`
- `bun test tests/static/` (16 passed)
- `bun run types:check` currently fails on existing docs type-generation
errors in `app/(home)/docs/changelog/[...slug]/page.tsx`,
`app/(home)/examples/[[...slug]]/page.tsx`,
`app/(home)/toolkits/[[...slug]]/page.tsx`,
`app/llms.mdx/[[...slug]]/route.ts`, `lib/search-index.ts`, and
`lib/source.ts`; no new eval or `docs/agent/agent.ts` errors were
reported.
## Not run
- Real live model evals, because this local environment does not have
`INCEPTION_API_KEY` or AI Gateway credentials.
## Latest update
- Added default eager docs retrieval in the Eve HTTP channel: the server
runs the same BM25 search on the user's message before the first model
step and injects the results as one-turn context.
- Kept `search_docs` and `read_doc` available so Mercury can still
search/read more when the eager context is weak, ambiguous, or missing.
- Added `DOCS_AGENT_EAGER_SEARCH=0` as an escape hatch and labeled perf
logs with `invocation: "eager_context" | "tool"`.
- Updated the loading copy from “Searching the docs…” to “Thinking with
the docs…” so UI latency is not attributed solely to the search call.
## Latest tests
- `bun run lint -- agent/channels/eve.ts agent/tools/search_docs.ts
agent/lib/docs-search.ts components/eve-chat.tsx
evals/docs-agent/grounded-answers.eval.ts`
-
`PATH=/Users/cryogenicplanet/.vite-plus/js_runtime/node/24.15.0/bin:$PATH
node_modules/eve/bin/eve.js info --json` (reports `status: ready`,
`errors: 0`)
- `DOCS_AGENT_SEARCH_PERF_LOG=1 EVE_FORCE_BUNDLE=1 bun -e "import {
searchDocs } from './agent/lib/docs-search'; const r = searchDocs('How
do I create a session in Composio? Keep it brief.', { invocation:
'eager_context' }); console.log(JSON.stringify({count:r.results.length,
top:r.results[0]?.url, content: !!r.results[0]?.content}, null, 2));"`
- `DOCS_AGENT_SEARCH_PERF_LOG=1 bun -e "import { searchDocs } from
'./agent/lib/docs-search'; searchDocs('How do I create a session in
Composio? Keep it brief.', { invocation: 'eager_context' });
searchDocs('How do I create a session in Composio? Keep it brief.', {
invocation: 'tool' });"`
- `bun run types:check` still fails only on the pre-existing docs
type-generation issues listed above.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## The bug
The live Algolia index was renamed to **`docs_composio`**, but every
default in the repo still pointed at the old
**`docs_composio_dev_62hi9pqz1l_pages`** in three places:
1. `.github/workflows/docs-search-sync.yml` — `ALGOLIA_INDEX_NAME`
fallback
2. `docs/lib/search-index.ts` — `ALGOLIA_DEFAULT_INDEX_NAME` (used by
the sync script)
3. `docs/components/custom-search-dialog.tsx` — client query fallback
(×2)
So unless the `ALGOLIA_INDEX_NAME` Actions variable happened to be set,
the **docs-search-sync** workflow rebuilt the dead old index on every
push to `next`, while the live site queried a different one. Net effect:
search index updates never showed up.
## The fix
Repoint the default to `docs_composio` in all three spots (+ README /
CLAUDE.md docs). The env overrides still take precedence, so nothing
breaks if a variable is set.
## Env to set (so it actually publishes & reads the right index)
The code now defaults to `docs_composio`, so the only things that
**must** be configured:
**GitHub Actions (repo → Settings → Secrets and variables → Actions):**
- `ALGOLIA_ADMIN_API_KEY` *(secret, required)* — without it the workflow
skips the sync.
- `ALGOLIA_APP_ID` *(variable, optional)* — defaults to `62HI9PQZ1L`.
- `ALGOLIA_INDEX_NAME` *(variable, optional)* — now defaults to
`docs_composio`; set only to override.
**Vercel (Production env) — for the live search to query the same
index:**
- `NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY` *(required; without it the client
falls back to `/api/search`)*
- `NEXT_PUBLIC_ALGOLIA_APP_ID` = `62HI9PQZ1L` *(optional, defaulted)*
- `NEXT_PUBLIC_ALGOLIA_INDEX_NAME` = `docs_composio` *(optional now that
the default matches; set it to be explicit)*
> If `NEXT_PUBLIC_ALGOLIA_INDEX_NAME` was previously set to the old name
in Vercel, update or remove it — otherwise the client keeps reading the
old index regardless of this PR.
## Testing
- `bun run types:check` passes.
- `grep` confirms no remaining references to the old index name.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## What
Reworks the `/examples` index into a Modal-style **featured gallery**,
styled to the Composio brand (pulled from `~/composio/landing`): flat
editorial cards, sharp corners, mono uppercase category tags in accent
colors, the signature brand offset-shadow on hover, and real toolkit
logos on white chips.
| Light | Dark |
|---|---|
| Big `font-sans` hero, filter pills with live counts, responsive card
grid | Same, brand-consistent |
### Highlights
- **`<ExamplesGallery>`** — hero, category filter pills (Featured /
General agents / Background agents / Coding agents) with live counts,
responsive 1–3 col grid, staggered load-in.
- **Data-driven from frontmatter.** Card title/description come from
each page's own `title`/`description`. Presentation metadata lives in a
new optional `gallery` block in the frontmatter schema:
```yaml
gallery:
categories: [General agents, Background agents]
logos: [slack]
featured: true
order: 0
```
Examples can belong to **multiple category lanes** (the Pi bot is both
General + Background).
- The index route renders the gallery; nested example pages keep the
standard docs renderer.
### Drive-by fix
`PageActions` lifts a **full-width** row over the page title (`-mt-12`)
to place the "Copy page" button beside it. That invisible overlay sat on
top of the title and blocked selecting/copying it. Fixed by making the
overlay `pointer-events-none` and re-enabling them only on the button
wrapper. Affects every docs page.
## Testing
- `bun run types:check` passes.
- Verified in light + dark: titles/descriptions match page frontmatter,
multi-tag cards, filter counts, logo visibility (GitHub on white chips),
title now selectable, Copy button still clickable.
## Notes
- Category lanes are a fixed enum in two spots (`source.config.ts` enum
+ `CATEGORY_STYLES` color map in `examples-gallery.tsx`) — adding a new
lane is a two-place edit.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
Adds a **Security and Data** docs section (below Triggers and webhooks)
with two pages:
- **Security** (`/docs/security/overview`) — posture, compliance and the
[Trust Center](https://trust.composio.dev), org/project isolation,
credential protection (AES-256-GCM at rest, TLS), token redaction,
webhook signing, responsibilities, and vulnerability reporting.
- **Data retention** (`/docs/security/data-retention`) — what Composio
stores, **1-year** retention, the per-project **Log storage → "Don't
store data"** option (Composio keeps an audit record but does not store
tool-call payloads), an honest **"Where your data goes"** section (data
still flows to the destination provider and sub-processors during
execution; links the [Trust Center sub-processor
list](https://trust.composio.dev/subprocessors)), and a contact-sales
path for contractual arrangements. Includes a redacted dashboard
screenshot.
Note: "Don't store data" controls what Composio retains; it is not
framed as a zero-data-retention guarantee.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Keep the default 1-hour file TTL description; remove the per-project
Settings → File TTL configurability sentence until that dashboard control
ships.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Split the "Where your data goes" file/trigger bullet: file payloads live in
object storage only for the file TTL (1h default) then expire, distinct from
trigger destinations which receive events in real time.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per the data-storage/privacy review:
- Document that the Log storage setting is forward-looking (pause/resume):
switching to "Don't store data" stops storing new payloads but does NOT
delete logs already stored, and switching back does not backfill the gap.
- Add file availability: tool-execution files are presigned URLs with a
default 1-hour TTL, configurable 1-24h per project in Settings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New docs page: **Rate limits & usage**
(`docs/content/docs/rate-limits.mdx`, registered under "Other topics").
Closes the recurring "rate limits / suspension / SLA" support questions
(Plain SUP-807 theme) with one canonical, honest answer.
All numbers/headers verified against `apps/apollo/src/lib/ratelimit/`
(constants.ts + middleware.ts):
- **Platform limits:** per-org, fixed 1-min window; live limit in
`X-RateLimit` / `-Remaining` / `-Window-Size`; `429` + `Retry-After` on
exceed. Plan defaults (Hobby/Starter 2k, Growth 10k, Enterprise
effectively unlimited) shown as **defaults with the header as
authoritative**.
- **No automated suspension** — throttle only; the only hard block is a
manual `403`.
- **Upstream provider 429s** (Gmail/Slack/Ads) distinguished from
platform limits → BYO-OAuth (custom auth) for prod.
- **Multi-tenant**: single account + `userId` per end-user is
recommended.
- Honest gaps: **no public status page / health webhook invented**; SLA
routed to Enterprise.
Approach informed by how Nango/OpenAI/Stripe/GitHub document limits
(mechanism + headers as the contract, not a brittle per-plan matrix).
### Before merge
- [ ] **Confirm the Vercel preview build is green.** Local `bun run
build` could not be run this session due to an environment-level `bun`
`CouldntReadCurrentDirectory` fault (reproduced across worktrees,
unrelated to this change). The page **compiled + typechecked** via `node
next build`, and it contains **no twoslash code blocks** (only
python/json/bash fences), so the usual compile-break risk is absent —
but please let the preview confirm full static generation.
- [ ] Sanity-check the plan-default numbers are OK to publish (they're
real but can drift; the doc labels them defaults and points to the
header as source of truth).
- [ ] Decide whether to add a real status-page link if/when one exists
(currently omitted on purpose).
- [ ] Preview: `docs-git-docs-rate-limits-usage.preview.composio.dev`
Adds a changelog entry: the PostHog **region** (`us`/`eu`) is now a
per-connection field instead of an auth-config field. Existing
connections were migrated (default `us` stays default; non-default
values carried over), so no user action and no re-auth.
Pairs with the customer FYI email (Linear PRO-310) and Mercury PR #24717
(field relabel "Region" + corrected `us`/`eu` description).
### Before merge
- [ ] Preview renders + appears in the changelog index:
`docs-git-changelog-06-17-26-posthog-region.preview.composio.dev`
- [ ] Links resolve in preview (Link/Initiate API refs, PostHog toolkit
docs)
- [ ] Publish date `2026-06-17` still correct at merge time
- [ ] Mercury PR #24717 merged (so the dashboard field already reads
"Region" / `us`,`eu`)
Local `bun run build` green (1412/1412 static pages).
## Summary
Automated documentation updates triggered by new changelog entries
merged to next.
Generated by Codex via GitHub Actions.
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Follow-up to #2941. The "Renamed enum slugs" section of the 2026-03-28
changelog
(`docs/content/changelog/03-28-26-tool-consolidation-enum-renames.mdx`)
lists 347 Old Enum → New Enum pairs that don't line up with the actual
class-name-derived slugs delivered by mercury PR #17949 (commit
`12d585aa7e`, "fix: rename low-usage action class names to cleaner
slugs"). This PR replaces that section with the verified table.
### How slugs are formed
```python
enum = inflection.underscore(cls.__name__).upper()
slug = enum if enum.startswith(TOOLKIT) else f"{TOOLKIT}_{enum}"
```
Slug is derived from the **class name** of the action, not the file name
and not the `name` attribute. (Source: `mercury/tools/_base/action.py`
`set_metadata` / `set_tool`.)
### Audit results vs. existing docs section
| Category | Count |
|---|---|
| Original docs pairs that match PR #17949 exactly | 291 |
| Pairs with **wrong New Enum** (PR's actual new differs) | 1 |
| Pairs whose **old class never existed** in any commit | 5 |
| Pairs that refer to renames done in **other PRs** (or tool removals) |
20 |
| Pairs claiming a rename **that never happened** (old class still
present at HEAD with original slug) | 30 |
| **Real PR #17949 renames missing from docs and still valid at HEAD** |
**1,153** |
| Total entries originally listed | 347 |
| Total entries in this rewrite | **1,445** |
### Notable corrections
- `SUPABASE_UPDATES_PROJECT_S_SUPAVISOR_CONFIG` → docs said
`SUPABASE_UPDATE_SUPAVISOR_CONFIG`; **actual** is
`SUPABASE_UPDATE_PROJECT_SUPAVISOR_CONFIG` (class
`UpdateProjectSupavisorConfig` at
`apps/supabase/actions/generated/updates_project_s_supavisor_config.py`).
- `SLACK_DELETE_MESSAGE` is **not a real slug**. The chat-deletion
action is class `DeletesAMessageFromAChat`, slug
`SLACK_DELETES_A_MESSAGE_FROM_A_CHAT`. Removed from the table.
- All eight `PIPEDRIVE_*A_*` entries (`ADD_A_DEAL`, `ADD_A_NOTE`,
`DELETE_A_PERSON`, `GET_DETAILS_OF_A_PERSON`,
`LIST_PARTICIPANTS_OF_A_DEAL`, `UPDATE_A_DEAL`, `UPDATE_A_LEAD`,
`UPDATE_A_PERSON`) still exist at HEAD with their original slugs —
removed from the renames table.
- 14 Slack entries that claimed renames (e.g. `SLACK_FETCH_TEAM_INFO` →
`SLACK_GET_TEAM_INFO`) were never executed; class names still match the
original slug. Removed.
- Whole toolkits previously omitted that PR #17949 actually renamed and
that remain valid at HEAD: PostHog (179), Trello (63), Salesforce (41),
Vercel (39), Twitter (36), Google Analytics (25), Dropbox (18), Icypeas
(5), Reddit (2), YouTube (2), Apollo, Facebook, Hyperbrowser, Telegram
(1 each).
### Front-matter description / intro paragraphs
Updated count from "1,545 enum slugs across 24 toolkits" → "1,445 enum
slugs across 37 toolkits" to match the rewritten table.
### Out of scope
This PR does **not** change the "Deprecated tools" or "Consolidated
(removed) tools" sections — those describe a different consolidation
effort and are unrelated to the class-rename audit.
## Test plan
- [ ] Spot-check 10–20 random entries from the rewritten table against
the actual class definition in `mercury` (`apps/<toolkit>/actions/`) to
confirm `inflection.underscore(cls.__name__).upper()` matches the listed
New Enum.
- [ ] Confirm `<Accordions>...</Accordions>` block renders correctly on
`docs.composio.dev` preview.
- [ ] Confirm none of the 30 "rename never happened" entries listed in
the audit show up in the new table.
---------
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
Fold the guide content (platform vs upstream-provider 429s, backoff recipe,
no-automated-suspension note, multi-tenant guidance) into the existing
reference/rate-limits.mdx + its v3 copy. Remove the new docs/rate-limits.mdx
and its nav entry. Single source of truth, no cross-page drift.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
## Summary\n- show project API key permission endpoints with
/api/{version}/... placeholders instead of duplicating versioned rows\n-
keep proxy execute documented for direct and session proxy paths\n\n##
Verification\n- bun run lint:links from docs/\n- git diff --check
## What
Removes the incorrect `alias` references from the initiate-to-link
migration guide
(`docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx`).
## Why
The `alias` parameter does **not** exist on either method:
- TS: `composio.connectedAccounts.link()` /
`composio.connectedAccounts.initiate()`
- Python: `composio.connected_accounts.link()` /
`composio.connected_accounts.initiate()`
This was verified against the SDK source and the generated client. The
doc should not claim the parameter exists. Real alias/label support may
be added later; this change only corrects the docs for now.
## Changes
- Dropped `alias` from the sentence: `` `callback_url` / `callbackUrl`
works the same way on both methods. ``
- Deleted the `` | `alias` | ✓ | ✓ | `` row from the comparison table.
No other content changed (`callback_url`, `allow_multiple`, `config`
rows are intact).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
- Add a Notion FAQ entry for connection expiry reasons.
- Cover user-initiated revocation/removal from Notion workspace
connections.
- Cover the same-user/same-OAuth-app reconnection pattern that can leave
older Composio-managed connections with stale tokens.
## Validation
- `git diff --check`
- `bun run scripts/validate-links.ts` could not run because `bun install
--frozen-lockfile` fails with existing docs lockfile drift: `lockfile
had changes, but lockfile is frozen`.
This PR:
- consolidates and bumps TypeScript/npm dependencies across the
monorepo, docs, examples, and e2e fixtures — no runtime behavior changes
- **cleanup:** remove the unused `ansis` dependency from `@composio/cli`
(`picocolors` is the actual color lib), drop the dead `uuid` catalog
entry, catalog `dotenv` + `@types/bun` and repoint drifting examples/e2e
onto them, and replace `chalk` with `picocolors` in `@composio/core`
(smaller, ESM, already used by the CLI)
- **TypeScript 6:** bump `typescript` `5.9 → 6.0.3` everywhere (catalog,
CLI test fixtures, docs); drop vestigial `declaration`/`outDir` from the
provider `tsconfig.json`s to fix the TS 6 `rootDir` regression
(`TS6059`); add `ignoreDeprecations: "6.0"` in docs for the `baseUrl`
deprecation
- **toolchain:** `tsdown 0.18 → 0.22.3`, `vitest` + `@vitest/ui →
4.1.9`, `publint → 0.3.21`, `wrangler → 4.101.0` (each the latest
version within the 3-day `minimumReleaseAge` gate)
- **Effect + hono:** `effect 3.21.3`, `@effect/cli 0.75.2`,
`@effect/platform 0.96.1`, `platform-bun 0.90.0`, `platform-node-shared
0.60.0`, `language-service 0.86.2`, `@effect/vitest 0.29.0`, `hono
4.12.25`; pin the Effect peer cohort
(`printer`/`printer-ansi`/`typeclass`/`rpc`/`sql`/`cluster`/`experimental`/`workflow`)
as `@composio/cli` devDeps so the auto-installed peers resolve
coherently, and bump `@cloudflare/workers-types` to satisfy `wrangler`'s
peer
- changesets: `@composio/cli` patch (ansis removal) and `@composio/core`
patch (chalk → picocolors)
- verified: `build`, `typecheck` (tsgo + real `tsc` 6.0.3), and local
tests (excluding e2e) all pass
## Summary
The TypeScript SDK reference generator (`generate-docs.ts`) strips every
`api/vN/...` substring from JSDoc descriptions to keep raw endpoint
paths out
of user-facing docs. The blanket regex also strips paths that live
**inside
intentional inline-code spans**, mangling them.
Concretely, `ConnectedAccounts.initiate()`'s JSDoc:
> The legacy `` `POST /api/v3/connected_accounts` `` endpoint that this
method …
currently renders in the generated reference as:
> The legacy `` `POST `` endpoint that this method …
— content lost and an unclosed code span. (Visible today in
`docs/content/reference/sdk-reference/typescript/connected-accounts.mdx`.)
## Fix
In `extractDescription`, split the text on inline-code spans and only
strip
bare API paths **outside** backticks; deliberate route references inside
code
spans are left intact. The path regex is also tightened to stop at
code-span
and punctuation boundaries (`` ` ``, `)`, `,`, `.`, `;`).
The single affected reference page is regenerated in the same commit.
## Verification
- `pnpm --filter @composio/core generate:docs` → only
`connected-accounts.mdx`
changes, restoring the full `` `POST /api/v3/connected_accounts` ``
span.
## Context
Salvaged from the now-superseded #3518 — re-derived against the current
generator. The rest of #3518 (drift-gate workflow, regenerated MDX,
generator
rework) is obsoleted by the post-merge auto-regeneration workflow
(`generate-sdk-docs.yml`) and #3613.
## Summary
Auto-generated TypeScript SDK reference docs from
`ts/packages/core/src/`.
Regenerates pages at `docs/content/reference/sdk-reference/typescript/`
to reflect changes in the core package's public API (new methods,
updated signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Auto-generated Python SDK reference docs from `python/composio/`.
Regenerates pages at `docs/content/reference/sdk-reference/python/` to
reflect changes in the Python package's public API (new methods, updated
signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
This PR:
- adds a shared `fetchWithRetry` helper for the docs data-sync scripts
that retries `429` and transient 5xx responses, honoring `Retry-After`
(with jitter) and falling back to exponential backoff
- routes every request in `generate-toolkits.ts` and
`generate-meta-tools.ts` through it, so the `Docs - Update Data`
workflow rides out the staging rate limit (2000 req/min) instead of
hard-failing
- lowers toolkit fetch `batchSize` 10 → 5 (~30 → ~15 concurrent
requests) to soften burst pressure on the rate limit
- caps retry attempts so CI still fails fast when the backend is
genuinely down
- fixes the current `429 Too Many Requests` failure in `Generate meta
tools reference`, which inherited the rate-limit window exhausted by the
high-volume `generate-toolkits.ts` run
- verified with `bun run types:check` and an offline retry/backoff
behavior test (real end-to-end run needs the staging key in CI: `gh
workflow run docs-update-data.yml`)
- follow-up (separate PR): reduce per-toolkit request volume in
`generate-toolkits.ts` — left out here because it needs consumer and
search-quality validation
## What
Move the **Changelog** entry in the API Reference sidebar so it sits
**immediately below Overview** (second item from the top), instead of
after **Errors**.
## Why
Requested placement — Changelog should be pinned right under Overview at
the top of the Reference nav for visibility.
## How
The Changelog node is injected programmatically in
`app/(home)/reference/(v31)/layout.tsx` (it's not a `meta.json` page).
Previously it was inserted at `errorsIdx + 1`; now it's inserted at
`overviewIdx + 1`, with a safe fallback to position 1 if "Overview"
isn't found.
Before: `Overview → Authentication → Rate Limits → Errors → Changelog →
API Reference → …`
After: `Overview → Changelog → Authentication → Rate Limits → Errors →
API Reference → …`
Only affects the v3.1 (default) Reference layout; the v3 layout doesn't
inject a Changelog node.
## Verification
- `bun run types:check` passes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
- stop loading the Decimal widget globally from the docs root layout
- load the Decimal script only when the user clicks Ask AI or uses the
shortcut
- preserve Decimal theme syncing after the widget has loaded
## Why
Slack/GSC investigation pointed at mobile CLS regressions on docs pages.
Lighthouse trace comparison isolated the layout shift to the Decimal
iframe/sidebar; blocking Decimal took /docs CLS from ~0.302 to 0, while
blocking PostHog did not change CLS.
## Validation
- bun run types:check
- bunx eslint app/layout.tsx components/ask-ai-button.tsx
components/custom-search-dialog.tsx components/decimal-widget.ts
- bun run test
- local Playwright check on http://localhost:3000/docs: no getdecimal
scripts or requests before interaction; after clicking Ask AI the
Decimal script loads and the sidebar opens
## Notes
- full `bun run lint` is still red on existing unrelated docs lint
issues on next, including @next/next/no-html-link-for-pages and
react-hooks compiler rules in other files
Updates the scoped project API key permissions reference with the routes
cataloged in ComposioHQ/platform#10638 (PLEN-2623):
- **Sessions** — now covers MCP server management (`/mcp/servers*`,
`/mcp/{id}`, instances), the MCP runtime transport, and the tool router
MCP transport
- **Tool execution** — adds `POST /files/upload/response` and `GET
/files/list` (file legs of tool execution)
- **Triggers** — adds the SDK/CLI realtime subscribe endpoints
(`triggers.subscribe()` / `composio triggers listen`)
Tables mirror `PROJECT_API_KEY_PERMISSION_CATALOG` as of the platform
merge.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Adds a migration guide for developers moving from **MCP servers**
(`composio.mcp.create` / `composio.mcp.generate`, the "Single Toolkit
MCP" flow) to **sessions**.
New page:
`docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx`
(registered in `migration-guide/meta.json` after `direct-to-sessions`).
### What it covers
- What carries over (tools, auth configs/connected accounts — no
re-auth, the MCP URL pattern, per-user isolation, fixed tool lists)
- Old → new mapping table + the *why*
- 3-step migration (`composio.create` replaces server+generate · point
the client at `session.mcp.url` · direct-tools preset for a fixed tool
list)
- Things to know: reuse one session, `session.tools()` as native
framework tools, `session.execute()` for tool execution without an LLM,
shared connections, tenant params, white-labeling, triggers, and a
pointer to **Composio For You** (connect.composio.dev) for
no-code/personal app connections
### Before merge
- [ ] Confirm cross-links resolve in preview
(`/docs/configuring-sessions`,
`/docs/authenticating-users/shared-connections`,
`/docs/white-labeling-authentication`, `/docs/how-composio-works`)
- [ ] Sanity-check the `session.execute` / `session.tools` /
direct-tools-preset snippets against the current SDK
- [ ] Confirm the `https://connect.composio.dev` link + product-switcher
wording for Composio For You
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Catalog additions from ComposioHQ/platform#10638 (PLEN-2623):
- sessions now covers MCP server management and both MCP transports
- tool execution adds files upload/response and files list
- triggers adds the SDK/CLI realtime subscribe endpoints
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
github-actions[bot]