Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: mark migration guides legacy + timestamp; surface example code & legacy status in llms output (#3775)
Rahul Tarakf7397e07cada
diff --git a/docs/app/(home)/docs/[[...slug]]/page.tsx b/docs/app/(home)/docs/[[...slug]]/page.tsxindex f8381e67c..cd5162b6f 100644--- a/docs/app/(home)/docs/[[...slug]]/page.tsx+++ b/docs/app/(home)/docs/[[...slug]]/page.tsx@@ -36,7 +36,16 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {>{!isLanding && (<>- {data.legacy && <LegacyBadge />}+ {(data.legacy || data.written) && (+ <div className="mb-3 flex flex-wrap items-center gap-2">+ {data.legacy && <LegacyBadge />}+ {data.written && (+ <span className="not-prose text-xs font-medium text-fd-muted-foreground">+ Written {data.written}+ </span>+ )}+ </div>+ )}{data.experimental && <ExperimentalBadge />}<DocsTitle>{data.title}</DocsTitle><PageActions path={page.url} />diff --git a/docs/components/legacy-badge.tsx b/docs/components/legacy-badge.tsxindex 78a13f6b3..536dc52e9 100644--- a/docs/components/legacy-badge.tsx+++ b/docs/components/legacy-badge.tsx@@ -1,13 +1,15 @@/*** "Legacy" badge rendered at the top of a docs page (under the title) when the- * page frontmatter sets `legacy: true`. Used for the Direct Tool Execution- * guides, which are superseded by sessions.+ * page frontmatter sets `legacy: true` — for guides superseded by sessions but+ * kept for existing integrations. The "Written <date>" stamp is separate (see+ * the `written` frontmatter field), so a current, dated guide can show its date+ * without being marked legacy.*/export function LegacyBadge() {return (<spantitle="Legacy: superseded by sessions; kept for existing integrations"- className="not-prose mb-3 inline-flex w-fit items-center gap-1.5 rounded-md border border-fd-border bg-fd-muted px-2 py-0.5 text-xs font-medium uppercase tracking-wide text-fd-muted-foreground"+ className="not-prose inline-flex w-fit items-center gap-1.5 rounded-md border border-fd-border bg-fd-muted px-2 py-0.5 text-xs font-medium uppercase tracking-wide text-fd-muted-foreground">Legacy</span>diff --git a/docs/content/docs/migration-guide/direct-to-sessions.mdx b/docs/content/docs/migration-guide/direct-to-sessions.mdxindex d4358868c..ab0e8cd48 100644--- a/docs/content/docs/migration-guide/direct-to-sessions.mdx+++ b/docs/content/docs/migration-guide/direct-to-sessions.mdx@@ -2,6 +2,7 @@title: Migrating from Direct Tools to Sessionsdescription: Move from direct tool execution to the sessions paradigmkeywords: [migrate, sessions, direct tools, upgrade]+written: "February 2026"---This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**. For a comparison of the two patterns, see [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution).diff --git a/docs/content/docs/migration-guide/index.mdx b/docs/content/docs/migration-guide/index.mdxindex 364ce1abd..bb03261bc 100644--- a/docs/content/docs/migration-guide/index.mdx+++ b/docs/content/docs/migration-guide/index.mdx@@ -1,6 +1,7 @@---title: Migration guidesdescription: Guides for migrating to newer versions of Composio+written: "December 2025"---## Available migration guidesdiff --git a/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx b/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdxindex f182013f7..61a770ed0 100644--- a/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx+++ b/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx@@ -2,6 +2,7 @@title: Migrating from MCP servers to Sessionsdescription: Move from per-toolkit MCP server configs to the sessions paradigmkeywords: [migrate, mcp, mcp server, sessions, upgrade]+written: "June 2026"---This guide is for developers using Composio's **MCP servers** (`composio.mcp.create` /diff --git a/docs/content/docs/migration-guide/new-sdk.mdx b/docs/content/docs/migration-guide/new-sdk.mdxindex 456543ed4..6e5eef69c 100644--- a/docs/content/docs/migration-guide/new-sdk.mdx+++ b/docs/content/docs/migration-guide/new-sdk.mdx@@ -1,6 +1,8 @@---title: Our next generation SDKsdescription: Learn more about Composio's next generation SDKs and how to migrate+legacy: true+written: "December 2025"---<Callout type="info">diff --git a/docs/content/docs/migration-guide/tool-router-beta.mdx b/docs/content/docs/migration-guide/tool-router-beta.mdxindex 6bfc048ec..43b827c86 100644--- a/docs/content/docs/migration-guide/tool-router-beta.mdx+++ b/docs/content/docs/migration-guide/tool-router-beta.mdx@@ -2,6 +2,8 @@title: Migrating from Experimental Tool Routerdescription: Migrate from the experimental tool router to Composio sessionskeywords: [upgrade, migrate, experimental, beta, tool router]+legacy: true+written: "January 2026"---This guide is for users who adopted the **experimental tool router** (`composio.experimental.tool_router`) during its beta period. The tool router has now graduated to a stable, first-class feature called **sessions** — with a simpler API, better auth handling, and full framework support.diff --git a/docs/content/docs/migration-guide/toolkit-versioning.mdx b/docs/content/docs/migration-guide/toolkit-versioning.mdxindex 595c4f540..eca19a60c 100644--- a/docs/content/docs/migration-guide/toolkit-versioning.mdx+++ b/docs/content/docs/migration-guide/toolkit-versioning.mdx@@ -1,6 +1,7 @@---title: Toolkit versioning migrationdescription: Migrate to the new toolkit versioning system+written: "October 2025"---Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.diff --git a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdxindex eb1380c68..e82a4da76 100644--- a/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx+++ b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx@@ -14,6 +14,10 @@ While developing, you want trigger events on your machine. The best option forwa`subscribe()` streams events straight to your process over a WebSocket, with no webhook URL, no tunnel, and no signing. It's the fastest way to eyeball what a trigger sends, but it bypasses your real webhook handler. Use it only for basic prototyping; for anything you intend to ship, forward events to your handler with one of the options below.+<Callout>+Under the hood `subscribe()` opens the WebSocket via [Pusher](https://pusher.com/). This is an implementation detail, but worth knowing if your runtime restricts WebSocket clients — prefer the webhook/forwarding options below for anything you ship.+</Callout>+<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```pythondiff --git a/docs/lib/source.ts b/docs/lib/source.tsindex c32a5bdf0..071828eac 100644--- a/docs/lib/source.ts+++ b/docs/lib/source.ts@@ -5,6 +5,7 @@ import { openapi, openapiV3 } from './openapi';import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';import { getGuardrails } from './llm-guardrails';import { HIDDEN_API_TAGS } from './filter-api-version';+import { FILE_BUILDS } from './file-builds';/*** True if a reference URL belongs to an intentionally-hidden API tag@@ -273,6 +274,35 @@ export function mdxToCleanMarkdown(content: string): string {(_, name) => `## ${name}\n`);+ // FileBuildup renders an example's file growing step by step. The JSX can't+ // serialize to markdown, so the .md an agent reads would otherwise lose every+ // line of real code. Emit the actual source from the FILE_BUILDS registry:+ // `<FileBuildup name="bot" step={2} />` -> the full file at that step;+ // without `step` -> the final complete file.+ result = result.replace(+ /<FileBuildup\s+name="([^"]+)"(?:\s+step=\{(\d+)\})?\s*\/>/g,+ (_, name: string, step?: string) => {+ const build = FILE_BUILDS[name];+ if (!build || !build.stages?.length) return '';+ const lang = /\.tsx?$/.test(build.file)+ ? 'typescript'+ : /\.py$/.test(build.file)+ ? 'python'+ : '';+ const idx = step ? Number(step) - 1 : build.stages.length - 1;+ const stage = build.stages[idx];+ if (!stage) return '';+ const label = step ? ` — step ${step}: ${stage.title}` : ' — complete file';+ return `\n**\`${build.file}\`${label}**\n\n\`\`\`${lang}\n${stage.code.trim()}\n\`\`\`\n`;+ }+ );++ // RepoBrowser is an interactive file tree; point agents at the real repo instead.+ result = result.replace(+ /<RepoBrowser\b[^>]*\/>/g,+ '\n> The complete project is on GitHub: [composio-slack-bot](https://github.com/ComposioHQ/composio-slack-bot).\n'+ );+result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g, '');result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');@@ -401,10 +431,23 @@ ${page.data.description || ''}`;? `\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference)`: '';- const guardrails = includeGuardrails ? getGuardrails(page.data.llmGuardrails) : '';+ // Legacy pages (frontmatter `legacy: true`) document point-in-time migrations+ // and may show outdated APIs. Mark the .md so an agent reading it knows, and+ // skip the "enforce the CURRENT patterns" guardrail block — appending it to a+ // legacy guide contradicts the guide's own (older) content.+ const isLegacy = page.data.legacy === true;+ const written = page.data.written;+ const topNote = isLegacy+ ? `\n> **Legacy${written ? ` · written ${written}` : ''}.** This is a point-in-time migration/legacy guide and may describe outdated APIs. For current guidance, see https://docs.composio.dev.\n`+ : written+ ? `\n> _Written ${written}._\n`+ : '';++ const guardrails =+ includeGuardrails && !isLegacy ? getGuardrails(page.data.llmGuardrails) : '';return `# ${page.data.title} (${page.url})-+${topNote}${cleanContent}${footer}${guardrails}`;}diff --git a/docs/source.config.ts b/docs/source.config.tsindex 0330c1d3a..98d557e58 100644--- a/docs/source.config.ts+++ b/docs/source.config.ts@@ -23,6 +23,11 @@ const docsSchema = frontmatterSchema.extend({isNew: z.boolean().optional(),/** When true, the page shows a "Legacy" badge at the top of the page. */legacy: z.boolean().optional(),+ /** Human-readable date the page/guide was written (e.g. "December 2025").+ * Renders a "Written <date>" stamp at the top of the page, independent of the+ * `legacy` flag, so time-sensitive guides carry their own date whether or not+ * they're legacy. */+ written: z.string().optional(),/** Controls which LLM guardrail set is appended to the .md output.* - undefined / omitted → default session-based guardrails* - "direct-execution" → softer guardrails acknowledging this is the low-level API