@devries-cameron20 / composio-1 / commits / f7397e07c
Fork 0

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)

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>

Rahul Tarak committed Jul 9, 2026 at 00:34 UTC f7397e07cadaf2cf52992cbd240e96636ff130ef
11 files changed +77 -6
docs/app/(home)/docs/[[...slug]]/page.tsx
+10 -1
@@ -36,7 +36,16 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
36 >
37 {!isLanding && (
38 <>
39 - {data.legacy && <LegacyBadge />}
39 + {(data.legacy || data.written) && (
40 + <div className="mb-3 flex flex-wrap items-center gap-2">
41 + {data.legacy && <LegacyBadge />}
42 + {data.written && (
43 + <span className="not-prose text-xs font-medium text-fd-muted-foreground">
44 + Written {data.written}
45 + </span>
46 + )}
47 + </div>
48 + )}
49 {data.experimental && <ExperimentalBadge />}
50 <DocsTitle>{data.title}</DocsTitle>
51 <PageActions path={page.url} />
docs/components/legacy-badge.tsx
+5 -3
@@ -1,13 +1,15 @@
1 /**
2 * "Legacy" badge rendered at the top of a docs page (under the title) when the
3 - * page frontmatter sets `legacy: true`. Used for the Direct Tool Execution
4 - * guides, which are superseded by sessions.
3 + * page frontmatter sets `legacy: true` — for guides superseded by sessions but
4 + * kept for existing integrations. The "Written <date>" stamp is separate (see
5 + * the `written` frontmatter field), so a current, dated guide can show its date
6 + * without being marked legacy.
7 */
8 export function LegacyBadge() {
9 return (
10 <span
11 title="Legacy: superseded by sessions; kept for existing integrations"
10 - 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"
12 + 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"
13 >
14 Legacy
15 </span>
docs/content/docs/migration-guide/direct-to-sessions.mdx
+1
@@ -2,6 +2,7 @@
2 title: Migrating from Direct Tools to Sessions
3 description: Move from direct tool execution to the sessions paradigm
4 keywords: [migrate, sessions, direct tools, upgrade]
5 +written: "February 2026"
6 ---
7
8 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).
docs/content/docs/migration-guide/index.mdx
+1
@@ -1,6 +1,7 @@
1 ---
2 title: Migration guides
3 description: Guides for migrating to newer versions of Composio
4 +written: "December 2025"
5 ---
6
7 ## Available migration guides
docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
+1
@@ -2,6 +2,7 @@
2 title: Migrating from MCP servers to Sessions
3 description: Move from per-toolkit MCP server configs to the sessions paradigm
4 keywords: [migrate, mcp, mcp server, sessions, upgrade]
5 +written: "June 2026"
6 ---
7
8 This guide is for developers using Composio's **MCP servers** (`composio.mcp.create` /
docs/content/docs/migration-guide/new-sdk.mdx
+2
@@ -1,6 +1,8 @@
1 ---
2 title: Our next generation SDKs
3 description: Learn more about Composio's next generation SDKs and how to migrate
4 +legacy: true
5 +written: "December 2025"
6 ---
7
8 <Callout type="info">
docs/content/docs/migration-guide/tool-router-beta.mdx
+2
@@ -2,6 +2,8 @@
2 title: Migrating from Experimental Tool Router
3 description: Migrate from the experimental tool router to Composio sessions
4 keywords: [upgrade, migrate, experimental, beta, tool router]
5 +legacy: true
6 +written: "January 2026"
7 ---
8
9 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.
docs/content/docs/migration-guide/toolkit-versioning.mdx
+1
@@ -1,6 +1,7 @@
1 ---
2 title: Toolkit versioning migration
3 description: Migrate to the new toolkit versioning system
4 +written: "October 2025"
5 ---
6
7 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.
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+4
@@ -14,6 +14,10 @@ While developing, you want trigger events on your machine. The best option forwa
14
15 `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.
16
17 +<Callout>
18 +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.
19 +</Callout>
20 +
21 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22 <Tab value="Python">
23 ```python
docs/lib/source.ts
+45 -2
@@ -5,6 +5,7 @@ import { openapi, openapiV3 } from './openapi';
5 import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';
6 import { getGuardrails } from './llm-guardrails';
7 import { HIDDEN_API_TAGS } from './filter-api-version';
8 +import { FILE_BUILDS } from './file-builds';
9
10 /**
11 * True if a reference URL belongs to an intentionally-hidden API tag
@@ -273,6 +274,35 @@ export function mdxToCleanMarkdown(content: string): string {
274 (_, name) => `## ${name}\n`
275 );
276
277 + // FileBuildup renders an example's file growing step by step. The JSX can't
278 + // serialize to markdown, so the .md an agent reads would otherwise lose every
279 + // line of real code. Emit the actual source from the FILE_BUILDS registry:
280 + // `<FileBuildup name="bot" step={2} />` -> the full file at that step;
281 + // without `step` -> the final complete file.
282 + result = result.replace(
283 + /<FileBuildup\s+name="([^"]+)"(?:\s+step=\{(\d+)\})?\s*\/>/g,
284 + (_, name: string, step?: string) => {
285 + const build = FILE_BUILDS[name];
286 + if (!build || !build.stages?.length) return '';
287 + const lang = /\.tsx?$/.test(build.file)
288 + ? 'typescript'
289 + : /\.py$/.test(build.file)
290 + ? 'python'
291 + : '';
292 + const idx = step ? Number(step) - 1 : build.stages.length - 1;
293 + const stage = build.stages[idx];
294 + if (!stage) return '';
295 + const label = step ? ` — step ${step}: ${stage.title}` : ' — complete file';
296 + return `\n**\`${build.file}\`${label}**\n\n\`\`\`${lang}\n${stage.code.trim()}\n\`\`\`\n`;
297 + }
298 + );
299 +
300 + // RepoBrowser is an interactive file tree; point agents at the real repo instead.
301 + result = result.replace(
302 + /<RepoBrowser\b[^>]*\/>/g,
303 + '\n> The complete project is on GitHub: [composio-slack-bot](https://github.com/ComposioHQ/composio-slack-bot).\n'
304 + );
305 +
306 result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g, '');
307
308 result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');
@@ -401,10 +431,23 @@ ${page.data.description || ''}`;
431 ? `\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)`
432 : '';
433
404 - const guardrails = includeGuardrails ? getGuardrails(page.data.llmGuardrails) : '';
434 + // Legacy pages (frontmatter `legacy: true`) document point-in-time migrations
435 + // and may show outdated APIs. Mark the .md so an agent reading it knows, and
436 + // skip the "enforce the CURRENT patterns" guardrail block — appending it to a
437 + // legacy guide contradicts the guide's own (older) content.
438 + const isLegacy = page.data.legacy === true;
439 + const written = page.data.written;
440 + const topNote = isLegacy
441 + ? `\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`
442 + : written
443 + ? `\n> _Written ${written}._\n`
444 + : '';
445 +
446 + const guardrails =
447 + includeGuardrails && !isLegacy ? getGuardrails(page.data.llmGuardrails) : '';
448
449 return `# ${page.data.title} (${page.url})
407 -
450 +${topNote}
451 ${cleanContent}${footer}${guardrails}`;
452 }
453
docs/source.config.ts
+5
@@ -23,6 +23,11 @@ const docsSchema = frontmatterSchema.extend({
23 isNew: z.boolean().optional(),
24 /** When true, the page shows a "Legacy" badge at the top of the page. */
25 legacy: z.boolean().optional(),
26 + /** Human-readable date the page/guide was written (e.g. "December 2025").
27 + * Renders a "Written <date>" stamp at the top of the page, independent of the
28 + * `legacy` flag, so time-sensitive guides carry their own date whether or not
29 + * they're legacy. */
30 + written: z.string().optional(),
31 /** Controls which LLM guardrail set is appended to the .md output.
32 * - undefined / omitted → default session-based guardrails
33 * - "direct-execution" → softer guardrails acknowledging this is the low-level API