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>
## What
Reworks the `/examples` index into a Modal-style **featured gallery**,
styled to the Composio brand (pulled from `~/composio/landing`): flat
editorial cards, sharp corners, mono uppercase category tags in accent
colors, the signature brand offset-shadow on hover, and real toolkit
logos on white chips.
| Light | Dark |
|---|---|
| Big `font-sans` hero, filter pills with live counts, responsive card
grid | Same, brand-consistent |
### Highlights
- **`<ExamplesGallery>`** — hero, category filter pills (Featured /
General agents / Background agents / Coding agents) with live counts,
responsive 1–3 col grid, staggered load-in.
- **Data-driven from frontmatter.** Card title/description come from
each page's own `title`/`description`. Presentation metadata lives in a
new optional `gallery` block in the frontmatter schema:
```yaml
gallery:
categories: [General agents, Background agents]
logos: [slack]
featured: true
order: 0
```
Examples can belong to **multiple category lanes** (the Pi bot is both
General + Background).
- The index route renders the gallery; nested example pages keep the
standard docs renderer.
### Drive-by fix
`PageActions` lifts a **full-width** row over the page title (`-mt-12`)
to place the "Copy page" button beside it. That invisible overlay sat on
top of the title and blocked selecting/copying it. Fixed by making the
overlay `pointer-events-none` and re-enabling them only on the button
wrapper. Affects every docs page.
## Testing
- `bun run types:check` passes.
- Verified in light + dark: titles/descriptions match page frontmatter,
multi-tag cards, filter counts, logo visibility (GitHub on white chips),
title now selectable, Copy button still clickable.
## Notes
- Category lanes are a fixed enum in two spots (`source.config.ts` enum
+ `CATEGORY_STYLES` color map in `examples-gallery.tsx`) — adding a new
lane is a two-place edit.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Integration branch for the next docs release: a **sessions-first
documentation rewrite** — new and rewritten guides, example pages,
interactive components, and docs tooling — plus the supporting SDK
changes that the new docs describe.
The bulk of this PR is docs (~24k lines across ~150 commits); the SDK
changes (~5k lines) back the new guides.
## Documentation (the bulk)
- **Sessions-first restructure** — reorganized navigation and section
structure (incl. the "Sandbox (prev workbench)" section), with
v3-reorganization redirects so old URLs keep resolving.
- **Rewritten core guides** — quickstart, configuring sessions, triggers
(creating + subscribing to events), proxy-execute, toolkits
enable/disable, and common FAQ, rewritten in the house voice.
- **New example pages** — local-sandbox PR reviewer, daily standup bot,
and slack bot, with runnable build-ups.
- **New interactive components & diagrams** — triggers flow animation,
manage-connections visual, connection-refresh visual, and the
terminal-kit components.
- **Docs tooling** — a docs-graph link-graph connectivity checker,
search reprioritization (deprioritize legacy pages), and SDK-reference
regeneration.
## Supporting SDK changes
**`@composio/core` → 0.13.0 (minor)**
- `composio.sessions.create()` as the first-class sessions API
(`composio.create()` kept as an alias).
- **MCP is opt-in:** default `create()` / `use()` return native-tool
sessions (`SessionWithoutMcp`); pass `{ mcp: true }` to surface
`session.mcp`. _Migration: read `session.mcp` only after creating with
`{ mcp: true }`._
- `session.sandbox` is the canonical resolved config;
`session.workbench` kept as a deprecated alias. `sandbox` is the
preferred session-config key (`workbench` still accepted).
- `connectedAccounts.updateAcl()` graduated from experimental (alias
kept).
- `triggers.parse()` (parse + optionally verify an incoming webhook) and
`triggers.setWebhookSubscription()`.
**`@composio/experimental` → minor** — local-workbench helpers moved
onto the `@composio/experimental/workbench` subpath (out of
`@composio/core/experimental`), keeping the ~14 KB embedded Python
helper out of core. Plus the experimental Pi provider.
**`@composio/slim` → minor.**
**Python → 0.17.0** — mirrors the TS surface: `composio.sessions` mount
(`tool_router` deprecated), `triggers.parse()` /
`set_webhook_subscription()`, the `sandbox` config key, and
`connected_accounts.update_acl()`.
## Review response (#3664)
Addressed the `@composio/core` review:
- **Security:** `triggers.parse()` no longer fails open — a
present-but-empty `verifySecret` (e.g. unset `COMPOSIO_WEBHOOK_SECRET`)
now throws instead of silently skipping verification; omitting it stays
an explicit opt-out (both SDKs).
- Removed snake_case leakage from `transformWebhookSubscription` (+ the
index signature that allowed it).
- **Removed** the TS-only `connectedAccounts.link()` toolkit
auto-resolve (shipped with cancellability / orphaned-auth-config bugs
and was effectively undocumented; to be reintroduced properly later).
- Unified Python error types on `ValidationError`; added `mcp=True`
Python tests; fixed runtime-portability + error-type test assertions.
- Polished deprecation messages; fixed the backwards `/experimental`
`@deprecated` note and the `SessionWithMcp` JSDoc.
## Testing
- **TS:** `@composio/core` + `@composio/experimental` typecheck pass;
vitest green for the touched suites.
- **Python:** `test_tool_router.py` + `test_triggers.py` pass (161
tests).
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Kshitij Jhunjhunwala <kj@composio.dev>
Co-authored-by: Malay Vasa <malayvasa@gmail.com>
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
This PR:
- consolidates and bumps TypeScript/npm dependencies across the
monorepo, docs, examples, and e2e fixtures — no runtime behavior changes
- **cleanup:** remove the unused `ansis` dependency from `@composio/cli`
(`picocolors` is the actual color lib), drop the dead `uuid` catalog
entry, catalog `dotenv` + `@types/bun` and repoint drifting examples/e2e
onto them, and replace `chalk` with `picocolors` in `@composio/core`
(smaller, ESM, already used by the CLI)
- **TypeScript 6:** bump `typescript` `5.9 → 6.0.3` everywhere (catalog,
CLI test fixtures, docs); drop vestigial `declaration`/`outDir` from the
provider `tsconfig.json`s to fix the TS 6 `rootDir` regression
(`TS6059`); add `ignoreDeprecations: "6.0"` in docs for the `baseUrl`
deprecation
- **toolchain:** `tsdown 0.18 → 0.22.3`, `vitest` + `@vitest/ui →
4.1.9`, `publint → 0.3.21`, `wrangler → 4.101.0` (each the latest
version within the 3-day `minimumReleaseAge` gate)
- **Effect + hono:** `effect 3.21.3`, `@effect/cli 0.75.2`,
`@effect/platform 0.96.1`, `platform-bun 0.90.0`, `platform-node-shared
0.60.0`, `language-service 0.86.2`, `@effect/vitest 0.29.0`, `hono
4.12.25`; pin the Effect peer cohort
(`printer`/`printer-ansi`/`typeclass`/`rpc`/`sql`/`cluster`/`experimental`/`workflow`)
as `@composio/cli` devDeps so the auto-installed peers resolve
coherently, and bump `@cloudflare/workers-types` to satisfy `wrangler`'s
peer
- changesets: `@composio/cli` patch (ansis removal) and `@composio/core`
patch (chalk → picocolors)
- verified: `build`, `typecheck` (tsgo + real `tsc` 6.0.3), and local
tests (excluding e2e) all pass
Add `postprocess: { includeProcessedMarkdown: true }` to the changelog
collection in source.config.ts. Every other collection (docs, reference,
cookbooks, toolkits) already had this — changelog was the only one
missing it, so getText() was never available on changelog entries and
the .md endpoint only returned title/description without the actual
content.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add jsx: react-jsx compiler option to twoslash config (fixes React UMD global errors)
- Install @ai-sdk/react for useChat type resolution
- Exclude examples/ from tsconfig (twoslash handles type-checking via <include>)
- Allow expected error 2307 for local component import in page-with-tools.tsx
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
FAQ markdown files lack frontmatter and are not Fumadocs pages.
Exclude faq/ subdirectory from the toolkits collection to prevent
build failures from missing title field.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Invisible instructions appended to every .md endpoint that steer AI code
generators toward the session-based pattern (composio.create + session.tools)
and provide correct direct execution patterns on tagged pages.
- Session guardrails (default): correct pattern, ALWAYS/NEVER/DISCOURAGED rules
- Direct execution guardrails: auth link flow, tool execute flow, key rules
- Frontmatter-scoped via llmGuardrails field (Zod-validated)
- llms-full.txt prepends guardrails once at top, not per-page
- 12 MDX pages tagged with llmGuardrails: "direct-execution"
- Remove dead /cookbooks path check from nav components
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a new docs page explaining the organization/project hierarchy,
project management via API, and project settings. Also set up mermaid
diagram rendering for the docs site (remark plugin + client component).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add includeProcessedMarkdown: true to reference, examples, and toolkits sources
- This enables getText('processed') which works in Vercel's serverless environment
- getText('raw') fails in serverless because raw MDX files aren't deployed
- Add fallback error handling: try processed → raw → description
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Configure twoslash with empty renderer to validate types at build
time without adding hover popup markup to the output.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move Tool Router content to main docs section:
- Authentication pages → /docs/authenticating-users/
- Guide pages → /docs/guides/
- Toolkit pages → /docs/toolkits/
- Add MCP and native tool examples to provider pages:
- openai-agents.mdx: Usage with Tools, Usage with MCP, Usage with direct tools
- vercel.mdx: Usage with Tools, Usage with MCP, Usage with direct tools
- anthropic.mdx: Usage with MCP, Usage with direct tools
- Remove Tool Router section entirely:
- Delete content/tool-router/ folder
- Delete app/(home)/tool-router/ routes
- Remove from navigation, search, and LLM routes
- Remove "Usage with direct MCP servers" sections (deprecated approach)
- Update all internal links from /tool-router/* to /docs/*
- Add redirects for old Tool Router URLs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace CopyPage with PageActions component (copy + view as markdown)
- Disable twoslash in dev mode to prevent heap memory issues
- Document twoslash dev/prod behavior in CLAUDE.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Soham Basu