@devries-cameron20 / composio-1 / commits / 4124f713b
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: stop folders swallowing their siblings in llms.txt; fix auth folder link

Four review fixes on the sidebar restore. Folder headings do not close, so every page emitted after a folder read as one of that folder's children. Making `authentication` a folder mid-list swallowed `triggers` and `skills` into `### Authentication`. Reordering meta.json would fix the output but push Authentication below Skills in the human sidebar, which is what this PR exists to prevent — so walkPageTree now buffers each separator section and flushes its plain pages ahead of its folders. Legacy-separator skipping is unchanged. This also fixes the pre-existing case where `agent-plugins`, `cli` and `composio-connect` read as children of `#### Custom providers`. Drop "index" from authentication/meta.json. Listing it clears `node.index`, so fumadocs renders the folder as a chevron BUTTON plus a duplicate child row instead of a SidebarFolderLink — the row a reader clicks to reach /docs/authentication (1,850 views/month) expanded the folder instead of navigating. Omitting it matches how `providers` and `migration-guide` already render. Verified in the built DOM: an A with href=/docs/authentication, no duplicate row, /docs/authentication.md still emitted exactly once via node.index. Rename the ---Security and data--- separator to ---Security---; it duplicated the folder title directly beneath it, in llms.txt and in the sidebar. Point the last three agent/instructions/context.md bullets at canonical paths rather than redirect-only /docs/authenticating-users/* ones, so that file is internally consistent. Extend the llms.txt section test to assert the nearest preceding heading of any level, and to cover the sibling pages that regressed. It fails against the old walk. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Kshitij Jhunjhunwala committed Aug 14, 2026 at 12:28 UTC 4124f713b3c90b5c89721b5d155e23321c322a22
6 files changed +70 -22
docs/agent/instructions/context.md
+3 -3
@@ -20,14 +20,14 @@ This is your always-on map of Composio's concepts and the canonical page for eac
20
21 - **How auth works** — Composio uses Connect Links (hosted auth pages) and **auth configs** (per-toolkit blueprints) to create **connected accounts** (stored credentials) scoped to a userID. This is the page for "how does authentication work". → [Authentication](/docs/authentication)
22 - **Auth schemes / modes** — a toolkit's auth config uses one of `OAUTH2`, `API_KEY`, `BEARER_TOKEN`, or `BASIC`. When you mention a toolkit's auth mode, link the reference rather than explaining it inline. → [Auth schemes](/reference/api-reference/auth-configs#auth-schemes) for what each mode is and when it's used, [Authentication](/docs/authentication) for how auth works overall, and [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for choosing or bringing your own scheme.
23 -- **In-chat auth** — the agent prompts the user to connect via `COMPOSIO_MANAGE_CONNECTIONS`. → [In-chat authentication](/docs/authenticating-users/in-chat-authentication)
24 -- **Manual auth** — generate Connect Links yourself with `session.authorize()`. → [Manually authenticating users](/docs/authenticating-users/manually-authenticating)
23 +- **In-chat auth** — the agent prompts the user to connect via `COMPOSIO_MANAGE_CONNECTIONS`. → [In-chat authentication](/docs/authentication#in-chat-authentication)
24 +- **Manual auth** — generate Connect Links yourself with `session.authorize()`. → [Manually authenticating users](/docs/authentication/manually-authenticating)
25 - **Managed vs custom auth** — use Composio's managed OAuth apps, or bring your own for branding/scopes. → [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app)
26 - **White-labeling** — remove Composio branding from the auth flow. → [White-labeling authentication](/docs/authentication/white-labeling-authentication)
27 - **Callback identity verification** — opt-in per-project defense against OAuth session fixation, documented in the connected-accounts API overview: set a verifier URL and Composio holds each OAuth connection until the developer's server confirms the returning user (`complete_auth`); once set it covers every OAuth connection in the project. This is the section for "connections from the dashboard stopped completing" and "a real `user_id` is now required". → [Callback identity verification](/reference/api-reference/connected-accounts#callback-identity-verification)
28 - **Importing existing connections** — pass in API keys or bearer tokens you already hold. → [Importing existing connections](/docs/authentication/importing-existing-connections)
29 - **Multiple accounts per user** — e.g. work and personal Gmail. → [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts)
30 -- **Shared connections** — share one connected account across users via an ACL. → [Shared connections](/docs/authenticating-users/shared-connections)
30 +- **Shared connections** — share one connected account across users via an ACL. → [Shared connections](/docs/extending-sessions/shared-connections)
31
32 ## Triggers and webhooks
33
docs/app/llms.txt/route.ts
+21 -4
@@ -47,14 +47,29 @@ function isLegacySeparator(name: ReactNode): boolean {
47 * Walk the fumadocs page tree and generate a markdown index.
48 * Separators become ## headings, pages become URL entries, folders recurse.
49 * Legacy/deprecated sections (and everything under them) are skipped.
50 + *
51 + * A folder emits a heading one level deeper, and markdown headings do not
52 + * close — so a plain page emitted after a folder reads as belonging to that
53 + * folder. `meta.json` order is the human sidebar's order and cannot absorb
54 + * this, so each section's direct pages are buffered and flushed ahead of its
55 + * folders. Within pages, and within folders, `meta.json` order is preserved.
56 */
57 function walkPageTree(nodes: TreeNode[], depth = 2): string {
58 const lines: string[] = [];
59 let skippingSection = false;
60 + let sectionPages: string[] = [];
61 + let sectionFolders: string[] = [];
62 +
63 + function flushSection() {
64 + lines.push(...sectionPages, ...sectionFolders);
65 + sectionPages = [];
66 + sectionFolders = [];
67 + }
68
69 for (const node of nodes) {
70 if (node.type === 'separator') {
71 // A separator starts a new section; skip it and its pages when legacy.
72 + flushSection();
73 skippingSection = isLegacySeparator(node.name);
74 if (skippingSection) continue;
75 const text = nodeText(node.name);
@@ -68,28 +83,30 @@ function walkPageTree(nodes: TreeNode[], depth = 2): string {
83
84 switch (node.type) {
85 case 'page':
71 - lines.push(`- https://docs.composio.dev${node.url}.md`);
86 + sectionPages.push(`- https://docs.composio.dev${node.url}.md`);
87 break;
88
89 case 'folder': {
90 // Folders are sub-sections within separator sections, so one level deeper
91 const text = nodeText(node.name);
92 if (text) {
78 - lines.push('', `${'#'.repeat(depth + 1)} ${text}`, '');
93 + sectionFolders.push('', `${'#'.repeat(depth + 1)} ${text}`, '');
94 }
95 // If folder has an index page, include it
96 if (node.index) {
82 - lines.push(`- https://docs.composio.dev${node.index.url}.md`);
97 + sectionFolders.push(`- https://docs.composio.dev${node.index.url}.md`);
98 }
99 // Recurse into children
100 if (node.children.length > 0) {
86 - lines.push(walkPageTree(node.children, depth + 1));
101 + sectionFolders.push(walkPageTree(node.children, depth + 1));
102 }
103 break;
104 }
105 }
106 }
107
108 + flushSection();
109 +
110 return lines
111 .join('\n')
112 .replace(/\n{3,}/g, '\n\n')
docs/content/docs/authentication/meta.json
-1
@@ -1,7 +1,6 @@
1 {
2 "title": "Authentication",
3 "pages": [
4 - "index",
4 "manually-authenticating",
5 "managing-multiple-connected-accounts",
6 "importing-existing-connections",
docs/content/docs/meta.json
+1 -1
@@ -24,7 +24,7 @@
24 "auth-configuration",
25 "---Migration---",
26 "migration-guide",
27 - "---Security and data---",
27 + "---Security---",
28 "security"
29 ]
30 }
docs/tests/static/navigation.test.ts
+1 -1
@@ -54,7 +54,7 @@ describe("Navigation - meta.json validity", () => {
54 "---Guides---",
55 "---Direct execution (legacy)---",
56 "---Migration---",
57 - "---Security and data---",
57 + "---Security---",
58 ]);
59
60 expect(pages.slice(1, pages.indexOf("---Core concepts---"))).toEqual([
docs/tests/static/start-routing.test.ts
+44 -12
@@ -80,13 +80,19 @@ describe('getting-started routing policy', () => {
80 const { GET } = await import('../../app/llms.txt/route');
81 const llms = await (await GET()).text();
82
83 - for (const url of GUIDE_URLS) {
83 + for (const url of ['/docs/authentication', ...GUIDE_URLS]) {
84 const occurrences = llms.split(`https://docs.composio.dev${url}.md`).length - 1;
85 expect(occurrences, `${url} appears ${occurrences}x in llms.txt`).toBe(1);
86 }
87 });
88
89 - test('files the authentication guides under Core concepts, not a trailing section', async () => {
89 + /**
90 + * `nearest` is the closest preceding heading of any level. Markdown headings
91 + * do not close, so it is what an agent reads a URL as belonging to: a page
92 + * emitted after a folder reads as one of that folder's children even though
93 + * the sidebar shows it as a sibling.
94 + */
95 + test('files each page under the section it belongs to', async () => {
96 const { GET } = await import('../../app/llms.txt/route');
97 const lines = (await (await GET()).text()).split('\n');
98
@@ -94,21 +100,47 @@ describe('getting-started routing policy', () => {
100 const index = lines.findIndex(line => line.endsWith(`${url}.md`));
101 expect(index, `${url} missing from llms.txt`).toBeGreaterThan(-1);
102 const preceding = lines.slice(0, index);
97 - const last = (prefix: string) => preceding.findLast(line => line.startsWith(prefix));
98 - return [last('## '), last('### ')];
103 + return {
104 + section: preceding.findLast(line => line.startsWith('## ')),
105 + nearest: preceding.findLast(line => line.startsWith('#')),
106 + };
107 };
108
109 for (const guide of AUTH_GUIDES) {
102 - expect(sectionOf(`/docs/authentication/${guide}`)).toEqual([
103 - '## Core concepts',
104 - '### Authentication',
105 - ]);
110 + expect(sectionOf(`/docs/authentication/${guide}`)).toEqual({
111 + section: '## Core concepts',
112 + nearest: '### Authentication',
113 + });
114 + }
115 +
116 + expect(sectionOf('/docs/authentication')).toEqual({
117 + section: '## Core concepts',
118 + nearest: '### Authentication',
119 + });
120 +
121 + expect(sectionOf('/docs/extending-sessions/shared-connections')).toEqual({
122 + section: '## Guides',
123 + nearest: '### Extend sessions',
124 + });
125 +
126 + // Siblings that follow the Authentication folder in meta.json. These fell
127 + // under `### Authentication` when folders were emitted in meta.json order.
128 + for (const sibling of ['/docs/triggers', '/docs/skills']) {
129 + expect(sectionOf(sibling)).toEqual({
130 + section: '## Core concepts',
131 + nearest: '## Core concepts',
132 + });
133 + }
134 +
135 + // Same failure mode, pre-dating this folder: Get Started's pages sit after
136 + // the `providers` folder and used to read as SDKs-and-frameworks children.
137 + for (const sibling of ['/docs/agent-plugins', '/docs/cli', '/docs/composio-connect']) {
138 + expect(sectionOf(sibling)).toEqual({
139 + section: '## Get Started',
140 + nearest: '## Get Started',
141 + });
142 }
143
108 - expect(sectionOf('/docs/extending-sessions/shared-connections')).toEqual([
109 - '## Guides',
110 - '### Extend sessions',
111 - ]);
144 expect(lines).not.toContain('## Authentication guides');
145 });
146 });