## Summary
Applies the top findings from a multi-reviewer code review of #4335
(which merged before these could land on the PR branch). Four validated
findings, all small and behavior-preserving outside the fixes
themselves:
- **Cross-tab theme fight (P1):** #4335 routed the product-derived theme
through next-themes' shared `theme` localStorage key -- written by the
root layout's inline head script on every hard load and by `setTheme` on
every client switch. next-themes listens for cross-tab storage events on
that key, so two docs tabs on different products (Platform dark / For
You light) silently repaint each other with no self-heal (the provider
effect's deps are `[product, setTheme]`, so the flipped tab never
corrects). The product theme is derived state, not a preference: this PR
applies it directly to the document element (`applyProductTheme`) and
passes `forcedTheme: initialTheme` from the server-resolved product so
hydration cannot flip a stale stored value. No `theme` localStorage
writes remain anywhere.
- **theme-color meta (P2):** the two `prefers-color-scheme`-keyed metas
meant mobile browser chrome mismatched the forced page theme (white
chrome over dark Platform pages for light-OS users). Now a single meta
keyed to the product theme.
- **Switcher current-option href (P2):** the popover option marked
`aria-current="page"` resolved to the product landing route, so
middle-click, hover status bar, and copy-link all pointed at the wrong
URL. It now hrefs the current pathname.
- **Explore-card aria-label (P3):** `aria-label` replaced the link's
accessible name, so the product description inside the card was not
announced. Dropped; heading + description now form the name.
## Changes
- `docs/app/layout.tsx` -- inline script no longer writes localStorage
(pre-paint class priming unchanged); single product-keyed `theme-color`
meta; `forcedTheme: initialTheme` on `RootProvider`.
- `docs/components/docs-product-context.tsx` -- `setTheme`/`useTheme`
removed; new `applyProductTheme` used in the product effect and the
flushSync commit.
- `docs/components/product-switcher.tsx` -- `destination = isCurrent ?
pathname : docsProductDestination(...)`.
- `docs/components/home-surfaces.tsx` -- Explore-card `aria-label`
removed.
- `docs/tests/static/product-navigation.test.ts` -- pins the new
invariants (`applyProductTheme`, `forcedTheme: initialTheme`, and a
negative assertion that `localStorage.setItem('theme'` stays out).
## Testing
- `bun test tests/static/` -- 541 pass / 0 fail
- `bun run types:check` -- clean
- `bun run lint` -- only pre-existing warnings (`home-surfaces.tsx:102`
`no-img-element` is in `ForYouVisual`, untouched)
- Worth a manual check: two tabs on different products no longer repaint
each other (static tests cannot prove cross-tab storage isolation)
## Notes
- Docs-only change; no changeset required.
- Review context: follow-up to #4335. Remaining review findings
(navigation state-machine races, theme-scope design call, decision
record) are tracked separately.
This PR:
- Closes#4205 (nightly docs external-link check failing)
- demotes bare identifier URLs — Google OAuth scope URIs
(`googleapis.com/auth/*`) and version-only API roots like
`https://api.ahrefs.com/v3` — to inline code spans in the KB generation
layer (`markdownForMdx`), so they stop publishing as links that 404 by
design
- regenerates the two affected guides (`toolkits-ahrefs`,
`toolkits-googlemeet`); explicit markdown links keep their authored form
- adds a regression test covering the exact URLs from #4205 plus
link/autolink/code-span edge cases
- records the rule in `docs/decisions/public-knowledge-base.md`
- makes the scheduled KB workflow rebuild `docs/kb/semantic-index.json`
when it is stale against the checked-in corpus, not only when the
upstream `support-knowledge` commit moves
## Context
The failing URLs are machine identifiers, not documents — fetching them
404s by design, so no link target could ever satisfy the nightly sweep.
Upstream support prose cites them bare, the generator copied them
verbatim, and GFM autolinks published them as clickable links. Sibling
KB articles already used the backtick convention, confirming the
intended presentation.
`check:kb-semantic` is expected to fail on this PR: 4 embedded record
chunks change, and the artifact rebuild needs `OPENAI_API_KEY`
(CI-owned). After merge, the scheduled job (now staleness-aware)
proposes the artifact refresh PR on `docs/auto-update-kb`; until it
merges, that gate stays red for docs PRs.
Verified locally: `bun run lint:links:external` (the failing nightly
command) — 0 errors; `bun test tests/static/` — 506 pass; `lint:links`,
`generate:kb --check`, `types:check`, `lint` — pass.
The docs hero, feature cards, site metadata, and llms.txt all hardcoded
"1,000+" apps, while the published catalog is 1,327 toolkits (the length of
docs/public/data/toolkits-list.json, already rendered by the /toolkits page).
Add a server-only helper docs/lib/toolkit-count.ts that imports that same
JSON and exports TOOLKIT_COUNT_LABEL = Math.floor(len/100)*100 -> "1,300+",
with the locale pinned (toLocaleString('en-US')) so the separator is a comma
on any build host. Six server-side files now consume it. No client bundle
cost: none of the importers is a "use client" module, so the JSON never
reaches the browser.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Nightly external-link sweeps (#4205) failed on four KB URLs that are
machine identifiers, not documents: Google OAuth scope URIs
(googleapis.com/auth/meetings.space.*) and Ahrefs API surface roots
(api.ahrefs.com/v3, the wrong-host ahrefs.com/v3). Support prose cites
them bare, the KB generator copied them verbatim, and GFM autolinks
published them as links that 404 by design — unfixable by pointing them
anywhere.
The generation layer now demotes bare citations and <url> autolinks of
these identifier shapes to inline code spans, matching the convention
sibling KB articles already use. Explicit markdown links keep their
authored form. Regenerated the two affected guides.
Verified: bun run test (506 pass), bun run lint:links,
bun run lint:links:external (0 errors — the failing nightly command),
bun run types:check, bun run generate:kb --check.
Follow-up: docs/kb/semantic-index.json needs a rebuild with
OPENAI_API_KEY (bun run build:kb-semantic) because four embedded record
chunks changed.
## Problem
Provider tool-call helpers always used the globally injected direct
`Tools.execute` function. When a model received tools from
`session.tools()`, calling `handleToolCalls` or `handle_tool_calls`
therefore discarded the Tool Router session context and caused session
meta-tools such as `COMPOSIO_SEARCH_TOOLS` to fail.
Calling `session.execute()` manually preserved the session, but bypassed
provider behavior such as Anthropic input normalization and schema-alias
restoration.
## Root fix
- Add an explicit execution target to the non-agentic provider helpers:
- TypeScript: `handleToolCalls(session, response)` and
`executeToolCall(session, call)`
- Python: `handle_tool_calls(response=response, session=session)` and
`execute_tool_call(tool_call=call, session=session)`
- Route normalized provider arguments through the supplied Tool Router
session.
- Map session responses back to each helper's existing result shape.
- Keep provider-specific normalization before execution, including
Anthropic schema-alias restoration.
- Reject direct-only options and modifiers when the selected target is a
session, including plain JavaScript calls that bypass the TypeScript
overloads.
- Update OpenAI and Anthropic examples to use the session-aware helpers.
- Harden the docs policy test so setup and execution split across fences
in one sample are still detected.
## Docs review follow-ups
- Reword the concepts-page prohibition so it forbids user-ID-bound
helper calls, not the helpers themselves, matching the provider pages in
this PR.
- Add minimum-version callouts to the OpenAI and Anthropic provider
pages (Python `composio` newer than 0.19.0; TypeScript `@composio/core`
≥ 0.17.0 with `@composio/openai` ≥ 0.12.0 / `@composio/anthropic` ≥
0.11.0), pointing older versions at `session.execute()`.
- Bump `docs/package.json` to `@composio/core` `^0.15.0` and
`@composio/openai` `^0.11.0` (the published majors at the time of the
bump; `@composio/core` 0.16.0 and `composio` 0.19.0 have since released
from `next` without this PR, so its changeset will publish core 0.17.0
and the next Python minor) and annotate each `@errors: 2345` Twoslash
marker with a TODO naming the minor version that retires it; since this
changeset releases minors, all three pins need a manual range bump to
retire the markers. This version of twoslash only throws on *unlisted*
errors, so a stale marker cannot break the build — it would only mask
future TS2345s, which the TODOs now track.
- Update `SESSION_GUARDRAILS` (the block appended to `.md` responses for
agents): add a session-execution bullet (scoped to the OpenAI and
Anthropic helpers, with `session.execute()` for every other provider)
and qualify the direct-execution list with "with a user ID". The
session-execution static test now scans the guardrail blocks like the
execute-version test already did.
- Tighten the docs detector: the Python branch is bounded to the helper
call's argument list (tolerating one level of nested calls) instead of
running past the closing paren, and the TypeScript branch catches whole
user-ID identifiers (`userId`, `user_id`, `uid`) without flagging
session variables like `userSession` — each edge has a regression test.
- Note on the Google provider page that its `executeToolCall` is not
session-aware yet.
## Compatibility and release
Existing user-ID calls remain unchanged and continue to use direct tool
execution. The new session call forms are additive.
The changeset applies minor releases to `@composio/core`,
`@composio/openai`, and `@composio/anthropic` — the new session
overloads are a type-level break for provider subclasses, so patch was
too small. The configured fixed group also includes `@composio/slim`.
The docs site intentionally checks examples against currently published
SDK declarations. The three new TypeScript calls therefore carry exact
Twoslash `TS2345` release-skew annotations; remove them (per the inline
TODOs) once `docs/package.json` picks up `@composio/core` ≥ 0.17.0,
`@composio/openai` ≥ 0.12.0, and `@composio/anthropic` ≥ 0.11.0.
## Verification
- `@composio/core`: 1,061 tests passed; typecheck passed
- `@composio/openai`: 34 tests passed; typecheck passed
- `@composio/anthropic`: 53 tests passed; typecheck passed
- Python provider and aliasing suites: 40 passed, 4 skipped
- Focused Python mypy and Ruff checks passed
- Docs static suite: 208 tests passed (including the new guardrail-scan
and detector cases)
- Docs production build passed with the bumped `@composio/core` 0.15.0 /
`@composio/openai` 0.11.0, including Twoslash, TypeScript, and all
generated pages
- Docs lint passed; lint reports only existing warnings
- Changeset status reports the expected minor packages
---------
Co-authored-by: Soumya Medapati <soumyamedapati@soumyas-air.local.meter>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: jkomyno <alberto@composio.dev>
The new AuthDiagram sized its hub (`w-36`) and account cards (`w-44`) with
fixed widths totalling 320px, but the feature-grid pane is not monotonic in
the viewport: ~404px at 1280px, and only ~242px at 640px where the grid goes
two-column. Below ~394px viewport the two blocks shrank until they touched,
`ex === sx` collapsed every wire into `elbowPath`'s straight-line fallback,
and the middle connector became a zero-length, invisible path. The card
rendered as three stray tick marks on every iPhone below Pro Max, and the
account cards overflowed the clip at 360px.
Use proportional widths with caps (`w-[36%] max-w-36` / `w-[52%] max-w-56`)
so ~12% of the pane is always reserved as horizontal run for the elbows.
Measured after: 29px gap at the 242px worst case, 34px at 360px, 50px at
1280px, no overflow and no degenerate paths anywhere in the range. The
account label now hides by container query rather than a viewport
breakpoint, which would gate on the wrong axis.
Also from review:
- Sandbox mock showed `composio.sandbox.run()` in a file chromed `sandbox.ts`.
Per content/docs/sandbox/remote.mdx — where the card links — the sandbox is
a persistent Python environment driven through COMPOSIO_REMOTE_WORKBENCH
with `run_composio_tool` / `invoke_llm`. Rewritten on that real surface and
relabelled `sandbox.py`; `WorkbenchVisual` renamed to `SandboxVisual`.
- `twilio` is not in public/data/toolkits.json, so the tile advertised an app
with no /toolkits page behind it. Swapped for `zendesk`.
- The dark logo was `aria-hidden`, so the heading's accessible name lost
"Composio" in dark mode only. Both variants now carry the same alt.
- Restored the badge style assertions the PR dropped, which still held, and
added regression coverage for the diagram widths, the catalog check, and
the sandbox surface.
- Restored the window resize listener that connection-refresh-visual.tsx
keeps alongside its ResizeObserver.
- Nits: stale "8×2" comment, redundant fragment, shared the duplicated fade
style, renamed the misleading `homeIntentAnchor(title)` parameter.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two-ways-to-start hero: cards now lead with the canonical Composio + product-badge lockup (dashboard-parity) and the same product mocks the dashboard onboarding path step uses — a chat composer flanked by client logos for For You, a code panel for Platform. Right link pane width matches a feature-grid card exactly.
Features grid: whole-card links restored, each mock fades into the card edge with a mask-image, cards live on a single flush bg-fd-card surface. Tools mock bumps from an 8×2 grid of 16 tiles to 10×3 = 30 for more impact, Auth becomes a live schematic — one user identity card wired to three connected-account cards via elbow connectors computed from real DOM geometry (`home-auth-diagram.tsx`), Triggers drops the fake LIVE ping in favor of a plain event list, Sandbox drops the workbench chrome + CPU lights for a clean filename + code panel.
Resources: adds a Platform Dashboard link so the 3×2 grid is complete. Drops the "Get started / What you get / Reach for the rest" eyebrows and section heading — headings stand on their own.
Copy: `audience` → `product`, so llms.txt emits `**Platform**` / `**For You**` instead of `**Platform**` / `**For you**`; matched in `home-navigation.test.ts`.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Review follow-ups on the docs_sidebar_click instrumentation.
usePostHog() resolves to the posthog-js module singleton whether or not a
provider is mounted, so the `!posthog` guard never fired: with no
NEXT_PUBLIC_POSTHOG_KEY the listener still attached and every sidebar
click called capture() on an uninitialized instance, logging "You must
initialize PostHog before calling posthog.capture". Gate the effect on
the same env var components/posthog-provider.tsx gates on.
position threaded through folder recursion, so a collapsed folder's
hidden children counted as rows: Triggers is the 4th visible row under
Core concepts but reported 11, which would inflate any "clicks land in
the top N rows" reading — the same inference error this instrumentation
exists to remove. Count per level instead, so a folder occupies one row
for its siblings and its children get their own 1..n sequence. Making
group and position per-level locals also removes the latent collision
where a separator nested in a folder reset the counter for the folder's
siblings; a test pins that case.
Also: capture auxclick (middle button only) so sidebar links opened in a
new tab are not missing while Cmd/Ctrl+click ones are counted; a folder
with a non-string name now reports folder: null rather than inheriting
its parent's label; and both reference layouts memoize the index instead
of rebuilding it on every render.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The docs app had exactly one posthog.capture call ($pageview), so any
question about how people move through the sidebar had to be answered by
reverse-engineering pageview ordering within a session. $referring_domain
is no help either: pageviews are captured manually on client-side route
change, so document.referrer never updates on internal navigation.
Adds a docs_sidebar_click event carrying href, group, folder, depth,
position and from_path. Group/folder/depth are derived from the fumadocs
page tree at build time and the click handler only does an href lookup —
reading them off the rendered sidebar would mean depending on separators
being <p> and folder triggers being <button>, which is fumadocs-internal
and breaks on upgrade.
Mounted on the docs, examples and both reference sidebars. Nothing fires
when PostHog is unconfigured, for non-sidebar links, or for an href that
is not in the index.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This PR:
- fixes
[UXE-233](https://linear.app/composio/issue/UXE-233/docs-should-explicitly-direct-agents-to-use-v31-apis)
- makes the agent-facing Markdown channels publish concrete REST v3.1
base URLs and endpoint tables while preserving the supported v3.0
reference tree
- centralizes `REST_VERSION_GUIDANCE`, `TOOL_VERSION_GUIDANCE`, and
raw-spec path matching in `lib/api-version-guidance.ts`
- renders `ApiBaseUrl` and `ApiEndpointsTable` in authored MDX and adds
an explicit version pointer to generated OpenAPI operation Markdown
- separates current and legacy REST references in `llms.txt`, excludes
v3.0 page bodies from `llms-full.txt`, and adds v3.1 selection guidance
to Context7
- validates serialized `ApiEndpointsTable` payloads with Zod before
generation while preserving forward-compatible fields
- addresses review feedback for the renamed authentication page,
SDK-reference pointer scope, generator validation behavior, and stale
OpenAPI tool-version descriptions
## Context
REST v3.0 is superseded but remains supported for existing integrations.
This PR changes what new agent-generated code discovers first; it does
not require existing v3.0 callers to migrate.
Authenticated read-only probes against the deployed API confirmed that
the affected v3 endpoints default to `00000000_00`, while their v3.1
counterparts default to `latest`. `POST /tools/scopes/required` is
available only on v3.1 and defaults to `latest`.
This PR does not move public URLs. A future `/reference/v3/` to
`/reference/v3.0/` migration remains separate because it has independent
compatibility and search-indexing risk.
## Verification
- `bun test tests/static/`
- `bun run build`
- `bun run test:integration`
- `bun run types:check`
- `bun run lint`
## Review follow-up
The version-default guidance is intentionally limited to the five
verified tool endpoints. v3.1 is a structural superset of v3, so this PR
does not claim route parity. Static coverage rejects broad non-tool
parity wording in both the shared guidance and Context7 rules.
## What
In three independent eval runs across two rounds
(ctx.composio.io/soumya/docs-agent-eval/), capable agents classified
this block as prompt injection and deliberately ignored it (round 1,
agent-007: "a prompt injection I had to identify and ignore"; round 3,
two more agents unprompted). The ALWAYS/NEVER imperative framing also
contradicted the sessions-vs-direct-execution page — the block forbade
the API that page documents.
## Change
Rewritten in `docs/lib/llm-guardrails/session.ts` — same facts, no
commands:
- Sessions documented as the recommended default (samples unchanged)
- The provider-import gotcha kept — it's the most common real mistake in
generated code
- The managed-auth default kept
- Direct execution acknowledged as a supported lower-level interface,
with a link to the sessions-vs-direct tradeoffs page (this replaces the
"DISCOURAGED — do not generate tools.execute()" section, which
contradicted the docs one click away)
An AI-steering block only works if AI readers trust it.
## Verification
- `bun test tests/static/` passes (the execute-version policy test also
validates the guardrail blocks)
- Every factual claim from the old block is preserved; only the framing
and the tools.execute() discouragement changed
Split out of #4059 (which now carries only the legacy-flag and
REST/SDK-naming changes) so this piece can be decided on its own.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Three independent eval runs across two rounds show capable agents
classify the CRITICAL INSTRUCTIONS block as prompt injection and ignore
it; its ALWAYS/NEVER framing also contradicted the
sessions-vs-direct-execution page. Same facts, no commands: sessions
stay the recommended default, the provider-import gotcha and
managed-auth default are kept, and direct execution is acknowledged as a
supported lower-level interface with a link to the tradeoffs page.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Runtime testing during eval-rerun prep caught that toolkit_versions
'latest' is rejected by tools.execute() (ToolVersionRequiredError:
'"latest" is not supported in manual execution') — the guides recommended
it anyway; only the TS SDK reference documented the real behavior.
Per SDK team (Abir): pass dangerously_skip_version_check=True /
dangerouslySkipVersionCheck: true when running 'latest' manually. All
direct-execution samples now include the flag with a one-line comment;
the version-required callout explains both paths (skip-check for
LLM-consumed outputs, pinned via toolkits.get(slug).meta.version for
parsed outputs); the toolkit-versioning page's 'latest' claims are
corrected; the execute-version static test now fails any page showing
'latest' without the flag. Both patterns runtime-verified against the
live API before shipping.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Eval finding 3: 51/97 agents struggled to identify the right toolkit;
15 abandoned the docs for the raw REST API. Links the toolkits catalog
from the quickstart intro, adds a find-your-toolkit pointer to the
executing-tools and fetching-tools pages, and adds a discovery rule to
the direct-execution LLM guardrails.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This PR:
- builds on top of https://github.com/ComposioHQ/composio/pull/3966
- enables `typescript/no-explicit-any` (error, `fixToUnknown`) for docs
in `docs/.oxlintrc.json` and removes every remaining explicit `any` in
docs code
- parses untyped/external data once at the boundary with zod v4 schemas
and lets `z.infer` types flow downstream — no hand-rolled `'x' in obj`
guard chains, no `as`-casts of untyped page data, no
`docs/lib/unknown-value.ts`
- adds domain schema modules: `docs/lib/toolkit-schema.ts` (recursive
JSON-Schema node, raw tool/trigger payloads, list envelopes) and
`docs/lib/reference-page-data.ts` (fumadocs reference page data for both
reference routes)
- rewrites `validate-links.ts`, `generate-toolkits.ts`,
`generate-meta-tools.ts`, the `llms.mdx` route, and
`deprecated-api-sidebar.tsx` on those schemas with identical validation
outcomes
- carries the pure typing improvements from the earlier attempt (typed
reference source in `source.ts`, `LLMPage`/`PageLike`, typed
`ClientLogo[]` in `logo-bar.tsx`, component `any` removals)
- adds `tests/static/toolkit-schema.test.ts` and
`tests/static/generate-toolkits.test.ts` pinning the transform shapes;
no changeset (docs is not published)
## Context
Second of the three-PR split of #3958, replacing its rejected
structural-guard approach with zod schemas at the data boundaries.
Verified with `bun run lint`, `bun run types:check`, `bun test
tests/static/` (125 pass), `bun run lint:links`, and a full `next
build`.
## Review follow-up
Addressed the regressions reported in [the Zod boundary
re-review](https://github.com/ComposioHQ/composio/pull/3967#issuecomment-5105279224):
scalar JSON Schema enums and auth defaults are preserved as strings,
malformed toolkit page envelopes abort generation, and the pre-refactor
empty-string fallbacks are restored. Regression coverage lives in
`tests/static/toolkit-schema.test.ts` and
`tests/static/generate-toolkits.test.ts`.
Verified on `2f26c40be` with `bun test tests/static/` (125 pass), `bun
run types:check`, and `bun run lint` (0 errors; existing warnings only).
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>
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:
- 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
## 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.
## 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>
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
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>
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.
## 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.
This PR:
- supersedes https://github.com/ComposioHQ/composio/pull/3642 and
credits @shamsharoon for the original Eve provider and iMessage work
- rebases the integration onto the current `next` branch and resolves
its lockfile conflicts
- publishes an isolated `@composio/experimental/eve` entry with the
correct Eve 0.12+ peer contract
- adds recoverable per-session discovery, native Eve context
propagation, and durable approval policies for direct and batched side
effects
- centralizes circular-safe auth-link extraction across Eve and Pi and
replaces dense conditional expressions with named control flow
- hardens the iMessage example against `osascript` option injection,
unsafe trigger scoping, and third-party prompt injection
- preserves completed local-tool results when a mixed local/remote batch
loses its remote transport
- consolidates the example documentation onto shared components,
documents direct model-provider credentials, and clarifies that the
browsable source is not yet a standalone fixture
- verifies the change with 999 core tests, 32 experimental tests,
package builds/typechecks, packed peer-isolation smokes, and a
production docs build
---------
Co-authored-by: shams haroon <144290365+shamsharoon@users.noreply.github.com>
Co-authored-by: shams haroon <shamsharoon7@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: shams haroon <shams@composio.dev>
Follow-up doc fixes from a re-audit of the June "Pi Slack-bot friction"
report against the current docs. Low-risk changes across the migration
guides, the example `.md` output, and legacy handling.
## 1. Migration guides: selective legacy + a "Written {date}" stamp
Migration guides are point-in-time documents, but not all are legacy.
Two mechanisms, decoupled:
- **`legacy: true`** (existing Legacy badge) — only on guides that
migrate off something dead: **new-sdk** (deprecated v1 SDK) and
**tool-router-beta** (removed experimental tool router).
- **`written: "{Month YYYY}"`** (new frontmatter field, dates from git
creation) — renders a standalone **"Written {date}"** stamp on *every*
guide, independent of legacy. So current guides (direct-to-sessions,
mcp-servers-to-sessions, toolkit-versioning, the hub) show their date
without being mislabeled legacy.
Files: `source.config.ts` (new `written` field),
`components/legacy-badge.tsx` (plain badge again), docs page (badge +
date row), 6 migration guides.
## 2. Real example code now in the `.md`/llms output
`<FileBuildup>` / `<RepoBrowser>` render an example's actual source
(`bot.ts`, `install.ts`, …) interactively, but they're React components
that don't serialize to markdown — so
`examples/general-agent-with-pi.md` (what an agent fetches) had all the
prose and **no code**. `mdxToCleanMarkdown` now resolves them from the
`FILE_BUILDS` registry. That example's `.md` grows **6.5 KB → 34 KB**
with the real
`createSessionTools`/`proxyExecute`/`waitForConnections`/`verifyWebhook`
code. Also fixes standup-slackbot and local-workbench.
## 3. Legacy pages: flag in `.md`, skip the current-pattern guardrail
`getLLMText` now prepends "Legacy · written {date}" (or "Written {date}"
for current-dated pages) to the `.md`, and **skips the "enforce ONLY the
current patterns" guardrail block on legacy pages** — appending it to a
legacy guide contradicted the guide's own older content (e.g. new-sdk
showing `tools.execute()` as the v3 target).
## 4. Note that `subscribe()` uses Pusher under the hood
Short aside on the triggers subscribe doc, for readers on runtimes that
restrict WebSocket clients.
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
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>
Alberto Schiabel