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>
## Summary
- Add a Project API key permissions reference page under `Reference >
Authentication`.
- List the routes covered by each permission area and access level.
- Add stable anchor links for dashboard Learn more links, for example
`/reference/authentication/project-api-key-permissions#webhooks`.
- Link the new page from the Reference authentication overview and the
Projects page.
- Fix two existing docs build blockers that prevented local
preview/build: quote SDK reference frontmatter and use `zod/v3` in the
migration-guide custom tool sample.
## Validation
- `bun run lint:links`
- `bun run types:check`
- `bun run build`
- `curl -I
http://localhost:3000/reference/authentication/project-api-key-permissions`
returned `200` locally.
Disclosed low-key in the "Where your data goes" list, scoped to "if you use the workbench",
deferring specifics to the Trust Center.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- security/overview.mdx: posture, compliance/Trust Center, isolation, credential protection
- security/data-retention.mdx: what's stored, 1-year retention, the Log storage "Don't store
data" option, and an honest "Where your data goes" section (data still flows to sub-processors
during execution; defers the list to the Trust Center)
- frames "Don't store data" as controlling what Composio retains, not a Zero-Data-Retention
guarantee; contractual ZDR is a contact-sales option only
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- single page docs/content/docs/security-and-data.mdx (replaces the 3-page security/ folder)
- adds redacted Log-storage screenshot (project/org/email/user_id blurred; "Don't store data"
highlighted) at docs/public/images/log-storage-dont-store-data.png
- nav: single "Security and Data" section, below Triggers and webhooks
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Alberto Schiabel