The **I still need help** section of Composio Connect points users at
`tech@composio.dev`.
It's the only place in the docs that does. Every other reference uses
`support@composio.dev`:
- `docs/content/reference/errors.mdx`
- `docs/content/reference/v3/errors.mdx`
- `docs/content/changelog/12-30-25.mdx`
- `docs/content/changelog/01-29-26-sdk-major-update.mdx`
- `docs/content/changelog/03-25-26-mcp-endpoint-removed.mdx`
Composio Connect is the page consumer users land on when wiring up an
MCP client, so this was the most visible instance of the wrong address.
One line changed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
Session auto-match only considers auth configs with this flag, and the
custom flow has no default (platform#11223 was reverted), so configs
created without it fail session execution with NoActiveConnection. Adds
the auth-config creation step with the flag, a PATCH note for existing
configs, and updates the session and known-gaps guidance from "don't
rely on auto-match" to "auto-match works when the flag is set".
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The is_enabled_for_tool_router step is load-bearing: after the revert of
platform#11223 there is no default, and configs created without the flag
make session execution fail with NoActiveConnection.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Documents OAuth connection security (same-browser binding + callback
identity verification) as a section in the **connected-accounts API
reference**, next to the `complete_auth` endpoint it describes, rather
than a standalone `/docs` page.
Written in the connected-accounts overview's own house style (prose
sections, backticks, one warning callout, no em-dashes), carrying the
code-verified facts.
## What's here
- New **OAuth connection security** section in
`api-overviews/connected-accounts.mdx`, mirrored into both generated
`index.mdx` files (v3.1 + v3).
- Changelog entry, links pointed at
`/reference/api-reference/connected-accounts#...`.
- Agent concept map repointed, and a stale claim fixed: callback
identity verification is opt-in per project and covers every connection
once set, not custom-auth-config-only.
## Notes
- No standalone docs page or nav entry (an earlier revision of this
branch had one; removed).
- The `index.mdx` files are normally emitted by `generate:api-index`;
its deps don't resolve in my worktree, so I mirrored the section
manually. It matches what the generator would produce from the updated
overview, but a local regen on a full checkout is worth doing before
merge.
- The dashboard "Learn more" link (#1187) is repointed to this section.
The earlier standalone-page version lives in #3987 (left open and
untouched for comparison).
When a verifier URL is set, the OAuth handoff carries only session_uri and the
developer's endpoint owns the final redirect, so a callback_url passed at
connection creation is not used. One clause in the reference; regenerated both
index pages.
Same-browser binding is not enabled, so remove it from the connected-accounts
reference and concept map. Keep the OAuth session fixation definition as the
rationale for callback identity verification, which is now the single control
the section documents. Regenerated both index pages; repointed the concept map
to #callback-identity-verification.
Drop same-browser binding and the session-fixation description from the
changelog. It now announces just the opt-in callback identity verification
feature, framed as a capability, with no attack detail.
## What
Content fixes to the tool-execution docs, driven by a 97-agent docs eval
(findings: ctx.composio.io/soumya/docs-agent-eval/findings-97-run.md).
72/97 agents following the executing-tools page hit
`ToolVersionRequiredError` because the samples either omit versions
entirely or pin a GitHub-only mapping that doesn't transfer to any other
toolkit.
## Changes
**`docs/content/docs/tools-direct/executing-tools.mdx`**
1. Add an explicit callout in Direct Tool Execution: a toolkit version
is **required**, the error you get without one, the three ways to set
it, and a link to the version-lookup section. (Previously the page only
implied this via one sample's constructor; the "required" rule lived on
a separate page.)
2. Replace the hardcoded `{"github": "20251027_00"}` pin with `"latest"`
plus a comment showing how to find versions
(`composio.toolkits.get(slug).meta.available_versions`) — the old sample
only worked for GitHub and taught a stale pin.
3. Add `toolkit_versions` / `toolkitVersions` to every file-handling
sample (upload, download, Gmail attachment, manual staging, upload-hook)
— all previously threw `ToolVersionRequiredError` when copied.
4. Remove `dangerouslySkipVersionCheck: true` from the upload-hook
sample — it was working around the missing version; samples shouldn't
model the dangerous flag.
**`docs/lib/llm-guardrails/direct-execution.ts`**
5. The LLM-facing guardrails block appended to direct-execution pages
showed a version-less `tools.execute()` sample and a "signature rule"
omitting `version` — the exact pattern that produced the eval's top
failure. Samples and rules now state the requirement.
**`docs/content/docs/quickstart.mdx`**
6. State the Python 3.10+ requirement at the install step, naming the
cryptic `typing.TypeAlias` failure older versions produce (matches
`python/pyproject.toml` `requires-python = ">=3.10,<4"`).
## Verification
All sample signatures checked against the installed SDK (composio 0.18.0
/ composio_client 1.42.0): per-call `version=`, constructor
`toolkit_versions=`, lookup via `toolkits.get(slug).meta.version` /
`.meta.available_versions`. Eval evidence: 72/97 independent agent runs
reproduced the error; per-run logs available.
## Raised for docs-team decision (deliberately NOT changed here)
- **The session guardrails block**
(`docs/lib/llm-guardrails/session.ts`, "CRITICAL INSTRUCTIONS FOR AI
MODELS", appended to most pages): capable eval agents flagged it as
prompt injection (verbatim: "a prompt injection I had to identify and
ignore") and its framing contradicts the sessions-vs-direct-execution
page. Deliberate design, so untouched — recommend reconciling (both
paths legitimate, state when each applies) and softening ALWAYS/NEVER
framing.
- **`legacy: true` on executing-tools + toolkit-versioning**: these are
the canonical link targets for direct execution, but the legacy flag
stamps the LLM view with "may describe outdated APIs" and suppresses
guardrails — eroding agent trust in the current canonical page. Either
promote the pages or point canonical links elsewhere.
- **REST vs SDK naming**: REST query param is `toolkit_versions`, SDK
per-call param is `version` — a recurring source of agent confusion
(eval Finding 4); worth aligning or calling out in the reference.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## 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>
Ran generate:api-index instead of hand-editing. The one shared overview feeds
both version pages, so the OAuth connection security section now renders on the
v3.1 and v3 connected-accounts reference (chosen over a hand-edit the generator
would undo). Generator output is byte-identical to the prior hand-mirror on v3.1;
no other tags changed.
- complete_auth is a v3.1-only endpoint (no v3 route), so drop the OAuth
connection security section from the v3 connected-accounts index; keep it on v3.1.
- status_reason on mismatch is the enum VALUE 'Callback identity verification
failed', not the key IDENTITY_VERIFICATION_FAILED. Fix both files.
- Changelog no longer claims Composio universally 'stops' the attack. It ships
two controls: same-browser binding (automatic on managed) and opt-in callback
identity verification.
Changelog: run through good-docs-writing — remove every em-dash, drop the salesy
'most reliable way', plainer confident voice.
connected-accounts overview + both index files: correct the completion outcomes.
Per completeFromSession, only an identity mismatch fails the connection (FAILED +
status_reason IDENTITY_VERIFICATION_FAILED); any other error leaves it pending so
the flow can be restarted; the session_uri is consumed either way. The old text
read as if the connection always moved to FAILED.
Drop the standalone /docs/oauth-connection-security page and its nav entry. The
content now lives as a section in the connected-accounts API overview
(api-overviews/connected-accounts.mdx), next to the complete_auth endpoint it
documents, in that overview's house style.
- Add the section (same-browser binding + callback identity verification) to the
overview and mirror it into both generated index.mdx files (v3.1 + v3). The
index generator's deps don't resolve in this worktree, so the mirror is manual;
it matches what generate:api-index would emit from the updated overview.
- Repoint the changelog and the agent concept map at
/reference/api-reference/connected-accounts#...
- Fix a stale concept-map claim: identity verification is opt-in per project and
covers every connection once set, not custom-auth-config-only.
Skill-guided rewrite of the OAuth connection security page: direct second-person
voice, no em-dashes, concept-first sentences, no salesy comparatives.
Also corrects four accuracy issues found while verifying against the Apollo code
(these exist in the sibling PR too):
- the ten-minute figure is the session_uri TTL, not a connection-expiry;
- verification covers API + Connect Link redirects, not marketplace-install
acknowledgements (which return before the verifier fork);
- save-time validation is https + SSRF (private/reserved), not a reachability test;
- the rejection message has no trailing period.
This PR:
- prepares Python SDK core and provider packages for `0.18.1`, including
runtime and lockfile metadata
- adds the canonical combined changelog for Python `0.18.1` and the
TypeScript releases tracked by
https://github.com/ComposioHQ/composio/pull/3906
- documents `@composio/core` `0.14.1` so the generated release PR passes
the release-workflow guard
- refreshes `mise.lock` so the TypeScript audit workflow reaches the
dependency audit
- keeps the pending TypeScript Changesets untouched; the generated
release PR remains responsible for npm versioning and publication
- validates Python with Ruff/mypy, 944 tests, all 13 package builds, and
`twine check`
- validates TypeScript/docs with the full 26-task `pnpm test`,
high-severity production audit, 100 docs static tests, link checks, docs
typecheck, and production build
## 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>
97-agent docs eval: 72/97 agents hit ToolVersionRequiredError copying
version-less tools.execute() samples. Adds an explicit requirement
callout, uses 'latest' with a lookup pointer instead of a hardcoded
GitHub-only pin, adds versions to all file-handling samples, fixes the
LLM guardrails block's version-less signature, and states the Python
3.10+ requirement in the quickstart.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
## Summary
- add an experimental guide for registering customer-hosted MCP servers
- document supported authentication, the registration and sync flow,
toolkit behavior, and customer-facing workarounds for known gaps
- add the guide to the Extending sessions navigation and cross-link it
from the sessions-over-MCP guide
## Why
Custom MCP toolkits now have a working platform lifecycle, but customers
need one place that clearly distinguishes remote MCP servers from
in-process custom tools. The guide also makes the current pilot
limitations explicit so customers know which API version, sync flow,
account selection, and hosting model to use.
## Validation
- `cd docs && bun run lint:links`
- `cd docs && bun run types:check`
- `git diff --check`
Docs-only change, so no changeset is required.
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.
This PR:
- restores TypeDoc generation after
https://github.com/ComposioHQ/composio/pull/3966 by resolving
`@composio/core`'s TypeScript dev dependency from `catalog:ts6`
- keeps core typechecking on the root TypeScript 7 compiler while
TypeDoc receives the TS6 compiler API
- documents the additional compiler-API consumer in the shared
TypeScript catalog
- commits the regenerated `session-files.mdx` output that could not be
produced while the workflow was broken
- verifies `generate:docs`, `typecheck`, and `build` for
`@composio/core`
This PR:
- replaces ESLint with oxlint across the pnpm workspace and the
Bun-based docs site, porting the rules to `.oxlintrc.json` /
`docs/.oxlintrc.json` with behavior parity (restricted-syntax selectors
kept via `oxlint-plugin-eslint`)
- migrates typecheck to TypeScript 7 (`typescript@^7.0.2` catalog) and
keeps a TS6 pin for JS compiler API consumers via a named `ts6` pnpm
catalog (`ts/scripts/validate-examples.ts`, the `@composio/cli` generate
pipeline). The CLI's `typescript` dependency rebinds only the
compiler-API import — its typecheck still runs the root TS7 `tsc`, since
the alias package only ships a `tsc6` bin (documented in
`ts/packages/cli/AGENTS.md`)
- removes the `paths` mappings that pointed `@composio/core` (and, in
`experimental`, `@composio/json-schema-to-zod` plus core-internal
`#`-imports) at sibling `src` directories: under TS7, tsdown's
tsgo-based dts step emitted stray `.d.ts` files next to those
out-of-root sources on every dependent package build. Workspace deps now
resolve through their built dist types, which turbo's `dependsOn:
^build` already guarantees exist — and which the deep-path exports
(`@composio/core/*`) always used anyway
- renames the cli boundary tooling `eslint-boundaries*` →
`lint-boundaries*` and hardens the scanner to reject `oxlint-disable`
spellings so the disable manifest cannot be bypassed
- rewrites inline `eslint-disable` comments to oxlint rule names
(comment-only; no runtime changes), and adds **one new** declared
boundary: `tool-file-uploads.ts` needs `no-restricted-imports` disabled
for `node:crypto` (MD5 for the presigned-upload checksum is not in Web
Crypto), because oxlint also catches dynamic `await import()` where
ESLint did not. The manifest grows 46 → 47 deliberately
- updates CI path filters, `turbo.jsonc` lint inputs, and the docs
typescript-check workflow (renamed to "Docs - Lint and TypeScript
Validation" since it now lints too); drops `eslint`,
`typescript-eslint`, `eslint-config-next`, and `globals` from the
dependency graphs
- ships no changeset: I built `@composio/core` and `@composio/anthropic`
on this branch and on the pre-migration base and diffed the emitted
`dist/**/*.d.mts`. The provider output is byte-identical. Core's output
is **semantically identical but not byte-identical**: TS7 changes quote
style (`"x"` → `'x'`), object-property and union-member ordering in
inferred types, and picks equivalent shorter re-export alias paths for
five signatures (e.g. `OpenAI.Beta.Threads.Runs.Run` →
`OpenAI.Beta.Threads.Run` — verified both names alias the same type in
the shipped typings). Chunk-name hashes shift as a consequence. No type
gains, losses, or shape changes; `attw` and `publint` pass on the TS7
build
## Context
First of a three-PR split of #3958. The type-safety refactors are
stacked on this branch and merge after it:
- docs: https://github.com/ComposioHQ/composio/pull/3967
- `@composio/core`: https://github.com/ComposioHQ/composio/pull/3968
This PR:
- codifies the schema-parsing convention in agent guidance: parse
untyped/external data once at the boundary with zod (`z.infer`
downstream) in the docs site and SDK packages, and with `effect/Schema`
in the CLI
- bans hand-rolled structural guards (`'x' in obj` / `typeof` chains),
`as`-casts of parsed JSON, and fake validators such as `z.custom(() =>
true)`
- updates `docs/AGENTS.md`, `ts/AGENTS.md`,
`ts/packages/core/AGENTS.md`, and the existing trust-boundary rule in
`ts/packages/cli/AGENTS.md`
## Context
Follow-up to the review feedback that led to the #3958 split (#3966 /
#3967 / #3968): the docs type-safety work initially shipped a suite of
conditional structural utility helpers instead of zod schemas. This
records the convention so agents and contributors reach for schemas by
default.
## Summary
- upgrades `fumadocs-openapi` 10 → 11, `fumadocs-mdx` 14 → 15, and
`fumadocs-core` / `fumadocs-ui` 16.4 → 16.13
- migrates the Fumadocs OpenAPI API while preserving the custom schema
renderer
- restores local `$ref` resolution in both the visible API schema UI and
generated LLM markdown
- reduces API-reference client payloads by slicing the bundled OpenAPI
document to each page's reachable operations and components
- restores required badges for GET parameters
- normalizes the OpenAPI `no_auth` sentinel so explicitly public
endpoints render without authentication
- moves to `getOpenAPIPageProps()` / `OpenAPIPageProps` and removes
obsolete CSS overrides
## Correctness fixes
Fumadocs 11 changed the page contract from a server-resolved document id
to a client-side bundled document. That exposed several silent
regressions:
- **Reference resolution:** bundled documents retain local `$ref`s. The
LLM renderer now dereferences them, including alias chains and cycles,
while the custom schema renderer uses Fumadocs' resolver and retains raw
reference identity for stable deduplication.
- **Dereference reuse:** repeated LLM-page requests reuse the
dereferenced copy for each cached bundled document instead of walking
the complete spec per page.
- **Client payload size:** each API page now receives only its selected
operations and transitively reachable components. The slicer falls back
to the complete document for non-component pointers, deep component
pointers, missing operations, or dangling references.
- **Required badges:** `readOnly` cannot distinguish GET inputs from
responses. The renderer now uses the page hook's client name to identify
responses.
- **Recursive rendering:** schema markdown rendering now caps both
structural recursion and nested array type rendering.
- **No-auth normalization:** the undeclared `no_auth` sentinel is
removed without discarding any real security alternatives that may
accompany it.
- **Contract drift:** code consuming `getSchema()` now treats `bundled`
as required, matching the upstream type.
Review follow-up also replaces the new OpenAPI `any` types with typed
Fumadocs page props and a narrow recursive schema model. Historical
Fumadocs 10/11 migration explanations live here in the PR, not as
version-specific source comments; source comments retain only durable
invariants.
## Payload impact
| | before | after |
| --- | --- | --- |
| bundled document | 451 KB | 7.7 KB avg / 30 KB worst |
| served page HTML | 693 KB | 198 KB |
| 10-page sample | 6.55 MB | 2.02 MB (69% smaller) |
## Verification
- `bun install --frozen-lockfile`
- `bun run test` — 89 pass
- `bun run lint:links` — 0 errors
- `bun run lint` — 0 errors (77 existing warnings)
- `bun run types:check`
- `bun run build`
- production server + `bun run test:integration` — 74 pass, including
v3.1/v3 API pages, redirects, search, and LLM endpoints
The production build has one existing Turbopack NFT tracing warning from
`next.config.mjs`; it does not fail the build.
## Production vs preview checks
A live sample comparison between [production](https://docs.composio.dev)
and the [PR
preview](https://docs-git-chore-docs-fumadocs-11.preview.composio.dev)
found no docs regression:
- all 14 representative routes returned 200 with matching titles,
headings, canonical production URLs, and key content
- redirects for `/`, `/api-reference`, `/tools`, and `/docs/welcome`
matched exactly
- the sampled pages exposed the same 1,137 internal-link targets; a
balanced sample of 29 links resolved successfully on both deployments
- sampled v3 and v3.1 OpenAPI pages retained endpoint paths, required
fields, response schemas, and legacy indicators
- the generated OpenAPI LLM page was byte-for-byte identical
- selecting TypeScript in a hydrated browser rendered both inactive-tab
examples and synchronized the language tab groups
- `llms.txt` retained the same 139 unique lines in a different order
- `/docs/quickstart.md` only added an explicit `[#next]` heading anchor
The sampled OpenAPI HTML was roughly 35–42% smaller in the preview,
consistent with document slicing rather than missing rendered content.
## What changed
- Kept the credential-masking explanation and masked-value examples in
the Connected Accounts guide.
- Removed only the dashboard and API instructions for disabling masking.
- Added guidance to use Proxy execute when calling a provider API
directly.
No changelog files are changed.
## Why
Credential masking remains useful product documentation, but the guide
should not direct users to disable it. Proxy execute covers direct
provider API calls while Composio injects the connected account
credentials server-side.
## Impact
Users still understand how credential masking appears in
connected-account responses, while direct provider API use cases are
routed to Proxy execute.
## Validation
- `bun run types:check`
- `bun run lint:links`
- `bun run test` — 33 tests passed
- `git diff --check`
`bun run lint` still reports 23 existing errors in unrelated
React/Next.js files; this PR only changes MDX content.
## Summary
Implements the docs half of **PLEN-2793** — renders a typed public
reference for the payloads Composio delivers to customer webhook URLs,
under **API Reference → Webhook Events**.
Pairs with platform PR ComposioHQ/platform#11389, which generates the
spec.
## What's here
- **`docs/public/openapi-webhooks.json`** — the generated OpenAPI
**3.1** spec (top-level `webhooks`: `composio.trigger.message`,
`composio.connected_account.expired`, `composio.trigger.disabled`),
produced from the webhook payload Zod schemas in Apollo (SSOT). Finishes
the earlier untracked WIP: adds the missing `trigger.disabled` event and
reuses shared schemas as `$ref` (`WebhookEventEnvelope`,
`ConnectedAccountDetailed`).
- **`docs/lib/openapi.ts`** — adds the spec as a **second input** to the
v3.1 reference source. Fumadocs (`fumadocs-openapi`) renders the
`webhooks` block natively; operations group under the "Webhook Events"
tag at `api-reference/webhook-events/*`.
- **`webhook-events/index.mdx`** — landing page listing the three
events, cross-linked to the Webhook Subscriptions API and signature
verification.
## Why a separate 3.1 spec
`webhooks` is a 3.1-only top-level field; the main `openapi.json` is
3.0. A separate file keeps the main spec (and its sync pipeline)
untouched and avoids the docs' union-normalisation pass. See the
platform PR for the full rationale.
## Verified locally
- [x] `bun scripts/validate-links.ts` — **0 errors** (the generated
`handle_composio_*` webhook pages resolve; no collision with the
hand-authored `index.mdx`)
- [x] `bun test tests/static/` — 33 pass / 0 fail
- [x] `bun run types:check` — clean
## Notes
- Setup, subscription, and signature-verification docs already exist
(`setting-up-triggers/*`) and are cross-linked, not rewritten.
- Follow-up (optional): auto-sync the webhooks spec from Apollo on prod
deploy (currently committed by hand), mirroring the main-spec
`docs-update-data` pipeline.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
## 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 production
- **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: sudodaksh <23355449+sudodaksh@users.noreply.github.com>
This PR:
- follows up on https://github.com/ComposioHQ/composio/pull/3838
- renders the existing `Legacy` badge in v3 and v3.1 endpoint headers
when the OpenAPI operation has `deprecated: true`
- centralizes deprecated-endpoint badge copy across API overview tables
and detail pages
- adds static coverage plus running-server assertions for the reported
routes and active control endpoints
- verifies the fix with `bun run test`, `bun run types:check`, `bun run
lint:links`, `bun run build`, and the focused integration suite
Extend the dashboard link policy: no app.composio.dev or
platform.composio.dev anywhere, and any dashboard.composio.dev link with
a path must be a go-link (/~/project/... or /~/org/...) or /login.
Enforced via new no-restricted-syntax selectors for TS/TSX and the
static test (renamed to dashboard-links.test.ts) for MDX.
Rewrite the non-conforming links: quickstart /settings -> go-link for
api-keys (also restores UTM params lost to a stray checkout during
verification), changelog {workspace}/{project}/settings -> go-link for
project settings.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tag every dashboard.composio.dev link in authored docs content and
components with utm_source=docs plus utm_medium/utm_campaign, and enforce
the convention going forward: an ESLint no-restricted-syntax rule covers
TS/TSX and a static bun test covers MDX (runs in docs-tests CI).
- content links use utm_medium=content and utm_campaign=<page-slug>
- content/reference is excluded (generated upstream)
- delete unused landing-hero/_stub-links.ts
- fix the no-html-link-for-pages errors; downgrade the pre-existing
react-hooks compiler violations to warnings until burned down, so
bun run lint exits with zero errors
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
# Description
Removes the DiscordBot FAQ entry
`docs/content/toolkits/faq/discordbot.md`, which documented a "401 on
the default app" caused by the Composio-managed/shared DiscordBot bot
token being rejected by Discord.
That managed default-app bot-token issue has since been **resolved**, so
the FAQ is now stale. Leaving it up is actively misleading — it tells
users the default app is broken and pushes them to create their own
custom DiscordBot credentials, which is unnecessary now and has itself
been a source of support confusion (e.g. Plain T-14278, where a customer
went down the custom-credentials path).
Scope: single content file. FAQ entries are loaded per-toolkit-slug at
`content/toolkits/faq/${slug}.md`; `readToolkitFaq()` already
try/catches a missing file and returns `null`, and `FaqSection`/the
`llms.mdx` route both no-op when the FAQ is empty. There is no
manifest/index listing `discordbot`, so removal is clean with no
dangling references.
# How did I test this PR
- `grep -rni "401 on the default app|DiscordBot return 401|managed
bot-token" docs` after deletion → **no remaining references** anywhere
in the docs (content, components, prebuilt `toolkits.json`, search
index).
- Verified the loader tolerates the missing file:
`docs/app/(home)/toolkits/[[...slug]]/page.tsx:111` `readToolkitFaq()`
catches the read error → returns `null`; `FaqSection` renders nothing on
empty; `docs/app/llms.mdx/[[...slug]]/route.ts:671` gates on
`faqMarkdown && faqMarkdown.trim()`. So the DiscordBot toolkit page +
llms.mdx simply render without a FAQ section — no build break.
- Confirmed FAQ discovery is purely file-existence based (no hardcoded
slug list), so no index needed updating.
Co-authored-by: Zen Agent <zen@composio.dev>
Co-authored-by: abhishek <abhishek@composio.dev>
Lead with what the plugin does (act on 1,000+ apps, cross-app
workflows, managed OAuth) instead of how it is built. Drop the hook
inventory, no-MCP disclaimers, and the comparison table. Correct the
install story: the CLI is not a manual prerequisite — Claude installs
it and walks through login and app OAuth on first use; manual setup
stays as an optional note.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The plugin was redesigned from an MCP-server bundle to a thin CLI-based
plugin; the page still documented the old design — a nonexistent install
command (composio-mcp@composio) and bundled skills that no longer exist.
Rewrite the page around what actually ships: SessionStart/UserPromptSubmit
hooks, the /composio-connect command, and the just-in-time
search -> execute flow driven by the composio CLI.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This PR:
- builds on https://github.com/ComposioHQ/composio/pull/3823 and
https://github.com/ComposioHQ/composio/pull/3824
- bumps the Python SDK and every provider package from `0.17.1` to
`0.18.0`
- synchronizes the runtime version and root `uv.lock`
- adds the canonical July 16 changelog entry, including URL-upload and
telemetry security, trigger connection-resolution behavior, provider
schema fixes, and the `pyautogen` to `ag2` migration
- strengthens release guards for Python workflow invocation, provider
metadata, and current Python and TypeScript changelog coverage
- limits provider packaging to directories containing `pyproject.toml`
- makes provider cleanup, installation, and builds stop on the first
failure
- incorporates the merged TypeScript changelog and missing Changeset
from https://github.com/ComposioHQ/composio/pull/3849
After merging, create and push the annotated `py@0.18.0` tag from the
merged `next` commit.
## Validation
- `pnpm test:release-workflow`
- `uv lock --check`
- `uv run --frozen python -c "import composio; assert
composio.__version__ == \"0.18.0\""`
- `pnpm exec prettier --check
docs/content/changelog/07-16-26-python-sdk-018.mdx
test/release-workflow.test.ts`
- `cd docs && bun run test`
- `cd docs && bun run lint:links`
- `cd docs && bun run types:check`
- `cd python && make build`
- `cd python && uv tool run twine check dist/*`
This PR:
- documents TypeScript `@composio/core` `0.14.0`, prepared in
https://github.com/ComposioHQ/composio/pull/3717
- calls out trigger behavior changes, provider compatibility,
file-upload security, telemetry redaction, and tool-execution
reliability
- adds the missing `@composio/core` patch Changeset for the local-path
fix merged in https://github.com/ComposioHQ/composio/pull/3766
- leaves the Python `0.18.0` changelog with
https://github.com/ComposioHQ/composio/pull/3825 so the release and docs
PRs do not add the same file
- keeps the TypeScript candidate release in the canonical docs changelog
before publishing
After this PR merges into `next`, the Changesets release PR must
regenerate before publishing.
## Validation
- `pnpm test:release-workflow`
- `pnpm changeset status --since=origin/next`
- `bun run test`
- `bun run lint:links`
- `bun run types:check`
- `bun run build`
- `pnpm exec prettier --check
docs/content/changelog/07-15-26-typescript-sdk-014.mdx
.changeset/http-prefixed-local-paths.md`
`bun run lint` remains red on 23 existing React and Next.js errors
outside these files.
## Summary
The LangGraph Python example imports from langchain.agents import
create_agent, but the install command on the same page doesn't include
langchain — and neither langgraph nor langchain_openai pulls it in (they
only depend on langchain-core). Following the docs verbatim in a fresh
environment fails on the example's first import with
ModuleNotFoundError: No module named 'langchain'.
Fixes#3847
## Changes
- docs/content/docs/providers/langchain.mdx: LangGraph Python install
line gains langchain, matching the provider's own README
(python/providers/langgraph/README.md).
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [x] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Fresh venv with the documented install set (langgraph==1.2.9,
langchain-openai==1.3.5, Python 3.12): from langchain.agents import
create_agent fails with ModuleNotFoundError.
- Same venv after adding langchain: the docs example constructs the
agent via create_agent and the wrapped tool invokes correctly, with no
deprecation warnings.
- Docs: bun run build and bun run lint:links from docs/: green.
## Screenshots (if applicable)
## Checklist
- [x] I have read the Code of Conduct and this PR adheres to it
- [x] I ran linters/tests locally and they passed
- [x] I updated documentation as needed
- [ ] I added tests or explain why not applicable
- [x] I added a changeset if this change affects published packages
## Additional context
No changeset: docs-only. No tests: one-word install-command fix,
verified manually as above.
## Summary
Deprecated REST endpoints now surface the existing `Legacy` badge in
generated API-reference indexes, with endpoint-specific tooltip copy
instead of the Sessions-specific default. The generator behavior is
covered end to end for both v3 and v3.1, including rendered table
output.
This branch also restores CI compatibility with the organization Actions
policy: workflow tool versions still come from `mise.toml`, but
installation uses the approved, SHA-pinned setup actions. Secret
scanning pins the repaired organization reusable workflow from
ComposioHQ/.github#13.
## Changes
- Read the OpenAPI `deprecated` flag and emit `legacy: true` only for
deprecated operations.
- Render `LegacyBadge` on affected endpoint rows with accurate lifecycle
tooltip copy.
- Regenerate the affected `files` and `connected-accounts` indexes for
v3 and v3.1.
- Cover the real generator output, active-operation omission, badge
count, and tooltip through a focused regression test.
- Replace disallowed transitive Actions dependencies while retaining
`mise.toml` as the single tool-version source.
Endpoint detail pages continue to use `fumadocs-openapi`'s built-in
deprecated marker. The indexed endpoints are `GET /files/list` and `POST
/connected_accounts/{nanoid}/refresh`; internal operations remain
filtered from the docs.
## Spec data
The committed OpenAPI snapshots lagged the live backend for `POST
/connected_accounts/{nanoid}/refresh`. Both snapshots now carry its
current summary, description, and `deprecated: true`; the next
`fetch-openapi.mjs` run will preserve that state from the live spec.
## Validation
- `bun run test`: 25 passed, 0 failed.
- `bun run types:check`: passed.
- Focused ESLint and generated-index drift checks: clean.
- Composite-action and workflow YAML parsed successfully; extracted tool
pins match `mise.toml`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: jkomyno <alberto@composio.dev>
## What this fixes
This is a follow-up to #3770, not a second root-cause fix.
#3770 moved the docs data workflow from staging to production,
centralized the production API URL, removed staging hosts from the
committed data, and added the hostname guard. The committed toolkit
catalog still retained staging-derived `version` values, however,
because that PR intentionally did not regenerate the full catalog. After
#3770 merged, the scheduled production regeneration began failing with
`401 Unauthorized`: the repository's existing `COMPOSIO_API_KEY` secret
is staging-scoped.
The customer-visible result was that nearly every toolkit page showed
the internal staging version `20260703_00`; Gmail's production version
was `20260702_01`.
## Changes
- Correct every `version` in `docs/public/data/toolkits.json` from the
production toolkit changelog. Toolkits absent from that changelog
receive `null`, matching the full generator's semantics. No other JSON
field changes.
- Move production changelog fetching and version application into shared
`toolkit-versions.ts` logic used by the full catalog generator.
- Add `bun run generate:toolkit-versions` as the narrow, reproducible
generator for version-only repairs.
- Reject any non-production `COMPOSIO_API_BASE` in the toolkit and
meta-tool generators before a request is made.
- Keep the version-distribution check as a smoke signal for the known
whole-catalog staging-bump pattern, while testing the production source
boundary separately. The distribution heuristic is no longer described
as proof of provenance.
- Fail before writing when the production changelog response is
malformed or contains no versions.
## CI policy compatibility
- Replace the enterprise-blocked mise action with allowlisted tool setup
actions while continuing to resolve exact versions from mise.lock.
Install the existing pinned mise CLI release through a checksum-verified
repository script for lock freshness and preinstall validation.
- Run the existing GitHub Advanced Security alert check locally and
notify Slack through the already-allowlisted Slack action, avoiding the
central workflow dependency rejected by the enterprise action policy.
## Verification
- `bun test tests/static/` — 30 passed.
- Targeted ESLint for every changed script/test — passed.
- `bun run types:check` — passed.
- `bun run build` — passed.
- Explicit staging override of `generate-toolkits.ts` — rejected before
network access.
- Verified the JSON data change remains version-only; toolkit ordering,
tools, triggers, descriptions, and counts are unchanged.
## Remaining deployment action
An administrator still needs to replace `COMPOSIO_API_KEY` with a
production-scoped key. The scheduled `docs-update-data` workflow is
correctly pinned to production and therefore fails loudly with the
current staging credential instead of republishing staging data. Once
the secret is corrected, the normal full-catalog generator remains the
authoritative refresh path.
Triggered by: abhishek@composio.dev | Source: slack
Session: https://zen.corp.composio.io/dashboard/#/chat/zen-3a77f73eb146
---------
Co-authored-by: Zen Agent <zen@composio.dev>
Co-authored-by: abhishek <abhishek@composio.dev>
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
The Gemini Python example paired composio_google (which wraps tools as
VertexAI FunctionDeclaration objects) with google-genai client.
GenerateContentConfig silently coerces those VertexAI objects into an
empty genai Tool ({}), so the documented flow sends requests with no
tool schemas at all - the model never sees or calls any Composio tool,
with no error surfaced anywhere.
Fixes#3836
## Changes
- docs/content/docs/providers/google.mdx (Gemini tab, Python only):
- install line: composio_google → composio_gemini
- example: GeminiProvider + Automatic Function Calling; the manual while
response.function_calls: loop is gone because the google-genai SDK
executes the wrapped callables itself
- intro paragraph updated to describe the Python (AFC) and TypeScript
(manual loop) flows separately
The TypeScript tab and the Google ADK section are untouched; both
already target the right SDKs. The new Python example matches the
existing quickstart in python/providers/gemini/README.md.
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [x] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Offline repro of the bug (issue #3836): with composio_google,
config.tools[0].model_dump(exclude_none=True) is {} and genai's
_transformers.t_tools raises AttributeError on the vertexai type.
- Offline verification of the fix: the exact construction path of the
new example (GeminiProvider().wrap_tools → GenerateContentConfig →
chats.create → t_tools) serializes a complete FunctionDeclaration (name,
description, parameters) with composio==0.17.1, google-genai==2.11.0,
Python 3.12.
- Docs: bun run build and bun run lint:links from docs/: green.
## Screenshots (if applicable)
## Checklist
- [x] I have read the Code of Conduct, and this PR adheres to it
- [x] I ran linters/tests locally, and they passed
- [x] I updated documentation as needed
- [x] I added tests or explain why not applicable
- [x] I added a changeset if this change affects published packages
## Additional context
No changeset: docs-only change, no published package affected.
Regression coverage: `docs/tests/static/content.test.ts` now guards the
documented `composio_gemini` + `google-genai` pairing; the example's
construction path was also exercised offline as described above.
The underlying provider split (composio_google targeting the
upstream-deprecated vertexai generative_models SDK vs composio_gemini
targeting google-genai) is flagged in #3836 as an open question for
maintainers; this PR is the docs-only fix.
---------
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
The AutoGen provider examples still used the legacy
`llm_config={"config_list": [...]}` dict form, which ag2 0.14 (the
distribution `composio-autogen` depends on since #3729) only keeps for
backport compatibility and marks deprecated in
`LLMConfig.ensure_config`. The install command also pulled
`autogen-agentchat` (Microsoft's next-gen AutoGen package), which the
provider never imports, while the `ag2` distribution the examples
actually import from was only installed transitively.
Fixes#3831
## Changes
- `docs/content/docs/providers/autogen.mdx`: example migrated to
`LLMConfig({...})`, install line changed to `composio composio_autogen
ag2`, added `ag2` keyword and a one-line note that the provider runs on
the ag2 distribution
- `python/providers/autogen/README.md`: same quickstart and install
fixes
- `python/providers/autogen/autogen_demo.py`: same `LLMConfig` migration
`initiate_chat` is left as is: it isn't deprecated in ag2 0.14, and it's
the flow `register_tools` (caller/executor) is verified against.
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [x] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Verified in a fresh venv with the local `composio` +
`composio-autogen` packages and `ag2==0.14.0`: the updated example
constructs both agents, wraps a Composio tool via `AutogenProvider`,
registers it with `register_tools`, and executes it through the
executor's function map
- `uv run nox -s chk` (ruff + mypy): green
- `ruff format --check providers/autogen/`: clean
- Docs: `bun run build` and `bun run lint:links` from `docs/`: green
## Screenshots (if applicable)
## Checklist
- [x] I have read the Code of Conduct and this PR adheres to it
- [x] I ran linters/tests locally and they passed
- [x] I updated documentation as needed
- [ ] I added tests or explain why not applicable
- [x] I added a changeset if this change affects published packages
## Additional context
No changeset added: docs and Python-only change, no published TypeScript
package affected. No tests added: example/docs change with no runtime
code paths; the updated example was exercised manually against ag2 0.14
as described above.
---------
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
This PR:
- reverts https://github.com/ComposioHQ/composio/pull/3780
- restores the TypeScript `composio.create()` and `composio.use()`
session aliases, with their runtime and type-test coverage
- restores the prior deprecation state for
`BaseProvider.wrapMcpServerResponse`
- removes the pre-v1 breaking-change changeset so the release PR no
longer advertises this removal
The v1 API-freeze change should be recreated later as a draft PR and
kept out of the merge queue until v1 is ready.
## 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>
This PR:
- Adds public docs changelog entries for the Python and TypeScript SDK
releases since May 15, 2026, including the previously unmigrated Python
0.13.1 entry.
- Removes the Python-local changelog and replaces it with canonical
changelog links from the repository and Python READMEs.
- Retargets the Python release guard to the docs changelog, documents
its table contract, and covers prior-version plus PEP 440 version
parsing.
Validation:
- pnpm test:release-workflow
- docs: bun run test
- docs: bun run lint:links
- docs: bun run types:check
- docs: bun run build
- pnpm exec prettier --check test/release-workflow.test.ts
docs/agent-guidance/guides/changelog.md docs/content/changelog/*.mdx
Review:
- ce-code-review completed with correctness, testing, maintainability,
project-standards, agent-native, learnings, and adversarial passes. All
actionable findings were fixed; final adversarial re-review found no
remaining P0-P2 issue.
## Summary
- Ports support-workflows toolkit KB into public toolkit FAQ docs for 85
toolkit FAQ files.
- Creates 46 new toolkit FAQ files for toolkits that had KB but no FAQ
file yet.
- Updates existing toolkit FAQ files without deleting current public
answers.
## General docs updates
- Clarifies connected-account credential redaction and reconnect/refresh
semantics.
- Documents Proxy Execute scoped-key and v3.1/current-SDK requirements.
- Adds retry risk guidance for non-idempotent direct tool executions.
- Adds remote sandbox temporary state/file retention guidance.
- Adds Composio Connect vs developer project boundary guidance for MCP
app connections.
## Verification
- Hygiene grep passed on changed files:
`Plain|T-|SUP-|PRO-|Linear|plain.com|linear.app|/Users/|support-workflows|TODO|FIXME|\[eng:|customer`.
- `git diff --check` passed.
- `bun run lint:links` passed: 0 errored files, 0 errors.
- `bun run build` passed. Build emitted the existing Turbopack NFT
warning plus toolkit-detail fetch skips because `COMPOSIO_API_KEY` is
not set locally.
- Render spot checks passed for Gmail, Apollo, SharePoint, Google
Calendar, connected accounts, and remote sandbox pages.
## Deferred
- PowerPoint KB was not added because the current docs toolkit catalog
has no `powerpoint` toolkit slug/page. The KB describes a possible
future file-operations toolkit rather than an existing public toolkit
page.
---------
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## What and why
This makes the intended v1 API cleanup real rather than postponing it to
v2:
- Remove the TypeScript root aliases `composio.create(...)` and
`composio.use(...)`. Session creation and reuse now live only at
`composio.sessions.create(...)` and `composio.sessions.use(...)`. This
is a deliberate breaking change, reflected by a major changeset.
- Retain `BaseProvider.wrapMcpServerResponse` as the stable v1 provider
SPI. Its earlier deprecation pointed to a method that was never
introduced.
The scope is intentionally narrow: it does **not** remove unrelated
deprecated APIs, and Python keeps its supported `Composio.create/use`
API. The TypeScript docs, examples, providers, runtime fixtures,
generated SDK reference, and API-reference indexes now use the
namespaced TypeScript API. Historical changelog examples are left as
history.
## Verification
- `pnpm typecheck`
- `pnpm --filter @composio/core test -- --run test/core/session.test.ts`
(42 files, 1,018 tests)
- `pnpm exec eslint ts/packages/core/src/composio.ts`
- `pnpm --filter @composio/core generate:docs`
- `cd docs && bun run generate:api-index`
- `cd docs && bun run types:check`
- `git diff --check` and targeted scans for removed TypeScript aliases
I also attempted the affected Node and Cloudflare runtime E2E suites.
They cannot initialize in this checkout without `COMPOSIO_API_KEY` (and,
for Cloudflare, `COMPOSIO_BASE_URL` and `OPENAI_API_KEY`); they did not
report a product assertion failure.
## What was wrong
The API reference docs were shipping staging URLs to users. There were
two separate leaks, both from the same source: the scheduled
`docs-update-data` workflow fetches the OpenAPI specs and toolkit data
from staging every 5 hours and auto-commits them.
The first leak was the curl base URL. `servers[0].url` in `openapi.json`
and `openapi-v3.json` rendered as `http://staging-apollo.composio.dev`
in every curl example. That is what
https://github.com/ComposioHQ/composio/pull/3761 tried to fix.
The second leak was in the toolkit data. `toolkits.json` carried 269
`https://staging-backend.composio.dev/api/v1/auth-apps/add` default
values, surfaced in the white-labeling and auth-config docs. #3761 never
touched this file.
## Which PR caused it
Karan asked on Slack whether we could pin down the PR that introduced
this. We can. It was https://github.com/ComposioHQ/composio/pull/3426
(commit `a3e58a421`, merged 2026-07-03), which flipped `servers[0].url`
from `https://backend.composio.dev` / `PRODUCTION API` to
`http://staging-apollo.composio.dev` / `STAGING API` in both specs.
It was not a hand-written change. #3426 is itself an auto-generated PR
from this same `docs-update-data` workflow, opened by
`github-actions[bot]` on the `docs/auto-update-data` branch. The
workflow fetched from staging, staging serves the staging server URL in
its spec, and the value landed in the committed files where nobody
caught it inside a large auto-generated diff. That is the reason the
real fix belongs in the generator and the workflow, not in a one-off
edit to the JSON.
## Why #3761 was not enough
#3761 pinned `spec.servers` to production inside `fetch-openapi.mjs`.
That closed the first leak, but three things stayed open.
It only covered the OpenAPI specs. The 269 staging hosts in
`toolkits.json` come from a different generator, `generate-toolkits.ts`,
and stayed live on the docs site.
It added no CI guard. The fix was a single line in a generator with
nothing asserting it. A later refactor that dropped or reordered that
line would republish staging on the next 5-hour regeneration, which is
precisely the recurring failure that produced the original report.
And it scrubbed the symptom rather than the source. The workflow kept
fetching from staging; the pin just rewrote one field afterward.
## The fix
I addressed it at four layers, so no single regression brings staging
back.
**Source.** `docs-update-data.yml` no longer overrides the base URL to
staging. The generators default to production, so the docs reflect
production.
**Generators.** The production URL now lives in one place,
`docs/scripts/production-api.mjs`. The toolkit and meta-tools generators
sanitize any staging host to production before writing, so a staging
fetch can no longer republish staging.
**Committed data.** I rewrote the 269 staging hosts already in
`toolkits.json` to production.
**Guard.** `docs/tests/static/production-urls.test.ts` asserts the
OpenAPI `servers` is production and scans both specs and every
`public/data/*.json` for any `staging-*.composio.dev` host. It is an
independent oracle: it hardcodes the expected value and deliberately
does not import the generator constants, so a wrong edit there fails CI
instead of moving both sides together. I verified it catches both the
original `staging-apollo` and the `staging-backend` leaks.
## One thing to confirm before merge
`COMPOSIO_API_KEY` is paired with `COMPOSIO_BASE_URL_STAGING` in every
other workflow, so it is most likely a staging key. If that is the case,
provision a production-capable key before the next scheduled run.
Otherwise that run fails on auth, which is loud and safe, rather than
silently republishing staging. The generator sanitizer and the guard
keep the output correct regardless of which environment the fetch hits,
so there is no risk in the interim.
## Testing
- `bun test tests/static/` passes 21 of 21 (16 existing, 5 new).
- The shared module loads and all three generators build under bun.
- No `staging-*.composio.dev` host remains under `docs/public/`.
- `docs-update-data.yml` re-validated as valid YAML.
## What
Two changes to the docs install experience:
**1. Package-manager picker on install code blocks.** New
`PackageInstall` client component
(`docs/components/package-install.tsx`): the code block's copy button
opens a dropdown of package managers. Selecting one rewrites the
displayed command and copies it to the clipboard.
- TypeScript blocks: npm (default, `npm install`) / pnpm / bun / yarn
(`<pm> add`)
- Python blocks: uv (default, `uv add`) / pip (`pip install`)
- The menu is portaled to `document.body` so it isn't clipped by the
`Tabs`/`CodeBlock` overflow containers, and closes on outside click,
Escape, or real scroll movement.
**2. `@composio/slim` callout in the quickstart.** The quickstart
TypeScript install blocks carry display-only `#` comment lines noting
that `@composio/core` ships its docs and TypeScript source in the
package (inspectable to coding agents) and that `@composio/slim` is the
smaller install with the same API. Comment lines are rendered muted and
are **never copied** — the picker copies only the command.
## Where
Converted every plain `npm install` / `pip install` code block under
`docs/content` (quickstart, all provider pages, single-toolkit MCP,
custom tools, migration guides, standup example, SDK reference indexes).
The TS reference index's manual npm/pnpm/yarn/bun tabs collapse into one
picker. The two SDK-reference generators
(`ts/packages/core/scripts/generate-docs.ts`,
`python/scripts/generate-docs.py`) emit the new component so
regeneration keeps it. Flagged upgrade commands (`pip install
-U/--upgrade`) and the bun-first examples were left as-is.
## Verification
- `bun run types:check` — pass
- `bun run build` — pass
- `eslint` on touched TS files — clean (remaining repo lint errors are
pre-existing on `next`)
- Visual check via dev server + browser: comment lines render muted
below the command, picker opens npm/pnpm/bun/yarn (uv/pip on Python
tabs), selecting a manager rewrites the command, and the clipboard
receives exactly the command with no comment lines.
Docs-only behavior change; no changeset (generator-script edits don't
touch published code).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
palash-c