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: add glossary page with filterable term definitions
Stripe-inspired two-column layout with client-side filtering. Markdown converter handles GlossaryTerm→heading conversion for LLM-friendly output. Added glossary link to LLM footer, search shortcuts, and CLAUDE.md documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmitha Mallesh committed
Feb 24, 2026 at 18:29 UTC
904228961bef888d862550bb7727907749722fda
8 files changed
+302
-2
docs/.claude/context/fumadocs.md
+1
@@ -50,6 +50,7 @@ Available globally without imports:
50
- `CapabilityCard`, `CapabilityList`
51
- `ToolkitsLanding`
52
- `StepTitle`
53
+- `Glossary`, `GlossaryTerm` — filterable glossary table (see `components/glossary.tsx`)
54
- Lucide icons: `ShieldCheck`, `RouteIcon`, `Key`, `Wrench`, `Database`, `Zap`, `Rocket`, `Code`, `Blocks`, `Plug`, `Play`, `Terminal`, `Palette`, `BookOpen`
55
56
## Deployment
docs/CLAUDE.md
+4
@@ -74,6 +74,10 @@ Detailed documentation for Claude is organized in `.claude/`:
74
- Dynamic toolkit pages are validated against slugs from `public/data/toolkits.json`
75
- Non-Fumadocs `.md` files (like FAQ snippets) are picked up via `content/**/*.md` glob
76
77
+## Glossary
78
+
79
+`content/docs/glossary.mdx` defines key Composio terms (auth config, session, toolkit, etc.) using `<Glossary>` and `<GlossaryTerm name="...">` components (`components/glossary.tsx`). The component renders a filterable two-column table. The markdown converter in `lib/source.ts` converts `<GlossaryTerm>` tags to `### Term` headings for LLM-friendly output. When adding new Composio concepts, add a `<GlossaryTerm>` entry and update the `keywords` frontmatter array.
80
+
81
## Code Review Guidelines
82
83
**`docs/examples/` is tutorial code.** Review for correctness and clarity, not production-readiness. Skip accessibility (aria attributes, focus management), error boundaries, i18n, comprehensive error handling, and similar concerns that add noise to a teaching example. The goal is to teach Composio integration with minimal code.
docs/app/layout.tsx
+1
@@ -12,6 +12,7 @@ const defaultLinkSlugs = [
12
['quickstart'],
13
['authentication'],
14
['configuring-sessions'],
15
+ ['glossary'],
16
['common-faq'],
17
['troubleshooting'],
18
];
docs/components/glossary.tsx
new
+111
@@ -0,0 +1,111 @@
1
+'use client';
2
+
3
+import {
4
+ useState,
5
+ createContext,
6
+ useContext,
7
+ useRef,
8
+ useEffect,
9
+ type ReactNode,
10
+} from 'react';
11
+import { cn } from '@/lib/utils';
12
+
13
+const FilterContext = createContext('');
14
+
15
+function slugify(text: string): string {
16
+ return text
17
+ .toLowerCase()
18
+ .replace(/[^a-z0-9]+/g, '-')
19
+ .replace(/^-|-$/g, '');
20
+}
21
+
22
+export function Glossary({ children }: { children: ReactNode }) {
23
+ const [filter, setFilter] = useState('');
24
+
25
+ return (
26
+ <FilterContext.Provider value={filter.toLowerCase()}>
27
+ <div className="not-prose mt-6">
28
+ <div className="hidden sm:grid grid-cols-[minmax(180px,1fr)_2fr] gap-4 border-b border-fd-border pb-3 mb-0">
29
+ <div className="text-xs font-semibold text-fd-muted-foreground tracking-wider uppercase">
30
+ Glossary Term
31
+ </div>
32
+ <div className="text-xs font-semibold text-fd-muted-foreground tracking-wider uppercase">
33
+ Definition
34
+ </div>
35
+ </div>
36
+ <div className="border-b border-fd-border py-3">
37
+ <div className="relative max-w-sm">
38
+ <svg
39
+ className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-fd-muted-foreground"
40
+ fill="none"
41
+ stroke="currentColor"
42
+ viewBox="0 0 24 24"
43
+ >
44
+ <path
45
+ strokeLinecap="round"
46
+ strokeLinejoin="round"
47
+ strokeWidth={2}
48
+ d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
49
+ />
50
+ </svg>
51
+ <input
52
+ type="text"
53
+ placeholder="Filter..."
54
+ value={filter}
55
+ onChange={(e) => setFilter(e.target.value)}
56
+ className="w-full pl-9 pr-3 py-1.5 text-sm border border-fd-border rounded-md bg-fd-background text-fd-foreground placeholder:text-fd-muted-foreground focus:outline-none focus:ring-2 focus:ring-fd-ring"
57
+ />
58
+ </div>
59
+ </div>
60
+ {children}
61
+ </div>
62
+ </FilterContext.Provider>
63
+ );
64
+}
65
+
66
+export function GlossaryTerm({
67
+ name,
68
+ children,
69
+}: {
70
+ name: string;
71
+ children: ReactNode;
72
+}) {
73
+ const filter = useContext(FilterContext);
74
+ const definitionRef = useRef<HTMLDivElement>(null);
75
+ const [definitionText, setDefinitionText] = useState('');
76
+ const id = slugify(name);
77
+
78
+ useEffect(() => {
79
+ if (definitionRef.current) {
80
+ setDefinitionText(definitionRef.current.textContent?.toLowerCase() || '');
81
+ }
82
+ }, []);
83
+
84
+ const matches =
85
+ !filter ||
86
+ name.toLowerCase().includes(filter) ||
87
+ definitionText.includes(filter);
88
+
89
+ if (!matches) return null;
90
+
91
+ return (
92
+ <div
93
+ id={id}
94
+ data-glossary-term={name}
95
+ className={cn(
96
+ 'border-b border-fd-border py-4 scroll-mt-20',
97
+ 'grid grid-cols-1 sm:grid-cols-[minmax(180px,1fr)_2fr] gap-1 sm:gap-4',
98
+ )}
99
+ >
100
+ <div className="font-medium text-fd-foreground text-sm">
101
+ {name}
102
+ </div>
103
+ <div
104
+ ref={definitionRef}
105
+ className="text-sm text-fd-muted-foreground leading-relaxed [&_a]:text-fd-primary [&_a]:underline [&_code]:text-xs [&_code]:bg-fd-muted [&_code]:px-1 [&_code]:py-0.5 [&_code]:rounded"
106
+ >
107
+ {children}
108
+ </div>
109
+ </div>
110
+ );
111
+}
docs/content/docs/glossary.mdx
new
+173
@@ -0,0 +1,173 @@
1
+---
2
+title: Glossary
3
+description: Definitions of key Composio terms and concepts.
4
+llmGuardrails: "none"
5
+keywords:
6
+ [
7
+ auth config,
8
+ auth scheme,
9
+ callback url,
10
+ composio api key,
11
+ composio managed auth,
12
+ connect link,
13
+ connected account,
14
+ connection request,
15
+ custom tool,
16
+ in-chat authentication,
17
+ mcp,
18
+ model context protocol,
19
+ meta tools,
20
+ modifiers,
21
+ native tools,
22
+ organization,
23
+ organization api key,
24
+ project,
25
+ provider,
26
+ proxy execute,
27
+ session,
28
+ session id,
29
+ tool,
30
+ tool slug,
31
+ toolkit,
32
+ toolkit slug,
33
+ toolkit versioning,
34
+ trigger,
35
+ trigger instance,
36
+ user id,
37
+ white-labeling,
38
+ workbench,
39
+ glossary,
40
+ ]
41
+---
42
+
43
+<Glossary>
44
+
45
+<GlossaryTerm name="Auth Config">
46
+A blueprint defining how authentication works for a toolkit: auth method (OAuth2, API key, Bearer token, Basic Auth), scopes, and credentials. Created automatically by a session when needed. You can create a custom one to use your own OAuth credentials or non-default scopes.
47
+</GlossaryTerm>
48
+
49
+<GlossaryTerm name="Auth Scheme">
50
+The authentication method used by an auth config, such as `OAUTH2`, `API_KEY`, `BEARER_TOKEN`, or `BASIC`.
51
+</GlossaryTerm>
52
+
53
+<GlossaryTerm name="Callback URL">
54
+The URL a user is redirected to after completing an OAuth flow through a Connect Link. Passed as `callbackUrl` when initiating authentication.
55
+</GlossaryTerm>
56
+
57
+<GlossaryTerm name="Composio API Key">
58
+A project-scoped secret used to authenticate SDK and API requests. All resources created with it are scoped to that project.
59
+</GlossaryTerm>
60
+
61
+<GlossaryTerm name="Composio Managed Auth">
62
+The default mode where Composio provides its own OAuth app credentials for each toolkit. No setup required.
63
+</GlossaryTerm>
64
+
65
+<GlossaryTerm name="Connect Link">
66
+A hosted page where a user authorizes access to a toolkit. Returned as a `redirect_url` from `session.authorize()` or `connectedAccounts.initiate()`. Composio manages the full OAuth flow.
67
+</GlossaryTerm>
68
+
69
+<GlossaryTerm name="Connected Account">
70
+Created when a user authenticates with a toolkit. Stores credentials (OAuth tokens or API keys) linked to a user ID. Composio automatically refreshes OAuth tokens. A user can have multiple connected accounts for the same toolkit. IDs are prefixed `ca_`.
71
+</GlossaryTerm>
72
+
73
+<GlossaryTerm name="Connection Request">
74
+The object returned when you initiate authentication. Contains the Connect Link URL and a `waitForConnection()` method that resolves once the user completes the flow.
75
+</GlossaryTerm>
76
+
77
+<GlossaryTerm name="Custom Tool">
78
+A user-defined tool used alongside Composio's built-in tools. Can be standalone (no auth) or toolkit-based (authenticated API requests). Stored in memory, must be recreated on restart.
79
+</GlossaryTerm>
80
+
81
+<GlossaryTerm name="In-Chat Authentication">
82
+A flow where the AI agent handles authentication by calling `COMPOSIO_MANAGE_CONNECTIONS` to generate a Connect Link and send it to the user in the conversation.
83
+</GlossaryTerm>
84
+
85
+<GlossaryTerm name="MCP (Model Context Protocol)">
86
+An open protocol for connecting AI models to external tools. Every session exposes `session.mcp.url` and `session.mcp.headers`, an MCP-compatible endpoint any MCP client can connect to.
87
+</GlossaryTerm>
88
+
89
+<GlossaryTerm name="Manual Authentication">
90
+Authenticating users from your own code using `session.authorize()` or `connectedAccounts.initiate()`, as opposed to letting the AI agent handle it via in-chat authentication.
91
+</GlossaryTerm>
92
+
93
+<GlossaryTerm name="Meta Tools">
94
+A set of tools included in every session, including `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`, `COMPOSIO_REMOTE_WORKBENCH`, and `COMPOSIO_REMOTE_BASH_TOOL`. They let the agent discover tools, manage auth, execute in parallel, and run code without loading hundreds of tool definitions upfront.
95
+</GlossaryTerm>
96
+
97
+<GlossaryTerm name="Modifiers">
98
+Middleware that transforms tool behavior: **schema modifiers** change a tool's schema before the agent sees it, **before-execution modifiers** modify arguments before a tool runs, **after-execution modifiers** transform the result.
99
+</GlossaryTerm>
100
+
101
+<GlossaryTerm name="Native Tools">
102
+Tools accessed through provider packages via `session.tools()`, as opposed to connecting via MCP (`session.mcp.url`). Both methods give the agent the same capabilities, but native tools integrate directly with your AI framework.
103
+</GlossaryTerm>
104
+
105
+<GlossaryTerm name="Organization">
106
+The top-level Composio account entity. Contains team members and projects.
107
+</GlossaryTerm>
108
+
109
+<GlossaryTerm name="Organization API Key">
110
+A key (`x-org-api-key`) for organization-level operations like creating and managing projects. Distinct from the project-scoped Composio API Key.
111
+</GlossaryTerm>
112
+
113
+<GlossaryTerm name="Project">
114
+An isolated environment within an organization that scopes API keys, connected accounts, auth configs, and webhooks. Resources in one project are inaccessible from another. IDs are prefixed `proj_`.
115
+</GlossaryTerm>
116
+
117
+<GlossaryTerm name="Proxy Execute">
118
+Making authenticated HTTP requests through a toolkit's connected account without a predefined tool. Useful for API endpoints Composio doesn't have a built-in tool for.
119
+</GlossaryTerm>
120
+
121
+<GlossaryTerm name="Provider">
122
+An adapter package that transforms Composio tools into the format expected by an AI framework (OpenAI, Anthropic, LangChain, Vercel AI SDK, etc.).
123
+</GlossaryTerm>
124
+
125
+<GlossaryTerm name="Session">
126
+An ephemeral configuration object from `composio.create(userId)`. Ties together a user ID, available toolkits, auth config, and connected accounts. Immutable. Exposes `tools()`, `mcp.url`, `authorize()`, and `toolkits()`.
127
+</GlossaryTerm>
128
+
129
+<GlossaryTerm name="Session ID">
130
+Unique identifier for a session. Used internally by meta tools to share context across calls within the same session.
131
+</GlossaryTerm>
132
+
133
+<GlossaryTerm name="Tool">
134
+An individual action an agent can execute. Has an input schema and output schema. Named `{TOOLKIT}_{ACTION}` (e.g., `GITHUB_CREATE_ISSUE`).
135
+</GlossaryTerm>
136
+
137
+<GlossaryTerm name="Tool Slug">
138
+A tool's unique identifier, following the `{TOOLKIT}_{ACTION}` pattern, e.g. `GITHUB_CREATE_ISSUE`.
139
+</GlossaryTerm>
140
+
141
+<GlossaryTerm name="Toolkit">
142
+A collection of related tools for a single external service. Users connect to a toolkit via authentication, and all its tools execute with the user's credentials.
143
+</GlossaryTerm>
144
+
145
+<GlossaryTerm name="Toolkit Slug">
146
+The lowercase identifier for a toolkit, e.g. `github`, `gmail`, `slack`. Used when configuring sessions, fetching tools, or creating triggers.
147
+</GlossaryTerm>
148
+
149
+<GlossaryTerm name="Toolkit Versioning">
150
+Pinning a toolkit to a specific version so your integration uses a consistent set of tools even as Composio updates definitions.
151
+</GlossaryTerm>
152
+
153
+<GlossaryTerm name="Trigger">
154
+Sends structured payloads to your application when something happens in a connected app. Two delivery types: **webhook** (the app pushes events in real time, e.g. GitHub, Slack) and **polling** (Composio periodically checks for new data, e.g. Gmail).
155
+</GlossaryTerm>
156
+
157
+<GlossaryTerm name="Trigger Instance">
158
+A specific, active trigger scoped to a user's connected account.
159
+</GlossaryTerm>
160
+
161
+<GlossaryTerm name="User ID">
162
+An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between user IDs.
163
+</GlossaryTerm>
164
+
165
+<GlossaryTerm name="White-Labeling">
166
+Customizing the auth experience so users see your brand during the OAuth flow. You provide your own OAuth credentials, redirect URIs, and branding.
167
+</GlossaryTerm>
168
+
169
+<GlossaryTerm name="Workbench">
170
+A persistent Python sandbox via the `COMPOSIO_REMOTE_WORKBENCH` meta tool. State persists across calls within a session. Used for bulk operations, data transformations, and processing large tool responses.
171
+</GlossaryTerm>
172
+
173
+</Glossary>
docs/content/docs/meta.json
+1
@@ -31,6 +31,7 @@
31
"auth-configuration",
32
"---Resources---",
33
"common-faq",
34
+ "glossary",
35
"debugging-info",
36
"migration-guide",
37
"troubleshooting"
docs/lib/source.ts
+8
-2
@@ -234,6 +234,12 @@ export function mdxToCleanMarkdown(content: string): string {
234
'- [$2]($1): $3'
235
);
236
237
+ // Convert GlossaryTerm to heading + definition
238
+ result = result.replace(
239
+ /<GlossaryTerm[\s\S]*?name="([^"]*)"[\s\S]*?>([\s\S]*?)<\/GlossaryTerm>/g,
240
+ (_, name, content) => `### ${name}\n\n${content.trim()}`
241
+ );
242
+
243
// Convert AIToolsBanner to plain text
244
result = result.replace(
245
/<AIToolsBanner\s*\/>/g,
@@ -248,7 +254,7 @@ export function mdxToCleanMarkdown(content: string): string {
254
255
// Remove wrapper components (ProviderGrid, Tabs, Frame, div, QuickstartFlow, IntegrationTabs, Accordions, ToolTypeFlow, ToolkitsLanding, TemplateGrid, etc.)
256
// Note: Cards wrapper is removed earlier (before Card conversion) to prevent regex conflicts
251
- result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid)[^>]*>/g, '');
257
+ result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary)[^>]*>/g, '');
258
259
// Remove remaining self-closing JSX tags (including those with JSX expressions)
260
result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');
@@ -386,7 +392,7 @@ ${page.data.description || ''}`;
392
const cleanContent = mdxToCleanMarkdown(content);
393
394
const footer = includeFooter
389
- ? `\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)`
395
+ ? `\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/docs/glossary.md) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)`
396
: '';
397
398
const guardrails = includeGuardrails ? getGuardrails(page.data.llmGuardrails) : '';
docs/mdx-components.tsx
+3
@@ -21,6 +21,7 @@ import { TemplateCard, TemplateGrid } from '@/components/template-card';
21
import { ToolkitsLanding } from '@/components/toolkits/toolkits-landing';
22
import { Mermaid } from '@/components/mermaid';
23
import { AIToolsBanner } from '@/components/ai-tools-banner';
24
+import { Glossary, GlossaryTerm } from '@/components/glossary';
25
import {
26
ShieldCheck,
27
Route as RouteIcon,
@@ -89,6 +90,8 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
90
Mermaid,
91
AIToolsBanner,
92
StepTitle,
93
+ Glossary,
94
+ GlossaryTerm,
95
// Lucide icons
96
ShieldCheck,
97
RouteIcon,