Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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.tsx
index 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.tsx
index 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 (
<span
title="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.mdx
index 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 Sessions
description: Move from direct tool execution to the sessions paradigm
keywords: [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.mdx
index 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 guides
description: Guides for migrating to newer versions of Composio
+written: "December 2025"
---
## Available migration guides
diff --git a/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx b/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
index 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 Sessions
description: Move from per-toolkit MCP server configs to the sessions paradigm
keywords: [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.mdx
index 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 SDKs
description: 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.mdx
index 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 Router
description: Migrate from the experimental tool router to Composio sessions
keywords: [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.mdx
index 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 migration
description: 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.mdx
index 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">
```python
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 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.ts
index 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