Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 06:00 UTC
docs: record the documentation AEO triage and migration gaps
Brendan O'Leary committed
Nov 11, 2026 at 17:07 UTC
246820641c64cb9b3f3dcf47f8ec0b300944b189
1 file changed
+68
docs/aeo/rob-hoffman-11.md
new
+68
@@ -0,0 +1,68 @@
1
+# Documentation AEO review
2
+
3
+Reviewed on November 11, 2026, against `next` at `e1f47b0a1` and the live docs site.
4
+This is a bounded review of the shared layout, agent endpoints, and representative pages.
5
+"Done" means the mechanism exists in the inspected paths, not that every page passed an accessibility or content audit.
6
+
7
+The source is [Rob Hoffman's post](https://x.com/RobHoffman_/status/2112212215583658420), retrieved in full through [FxTwitter](https://api.fxtwitter.com/RobHoffman_/status/2112212215583658420).
8
+The recommendations below are paraphrased. They are recommendations, not measured results or guarantees about answer engines.
9
+The companion [landing PR #769](https://github.com/ComposioHQ/landing/pull/769) covers composio.dev.
10
+Its report now lives on `cos/rob-hoffman-aeo`, at commit `7edb1590f6f99ecf4b54008ed9b5798e4287b5be`; the supplied `cos/aeo-rob-hoffman-2` ref returns 404.
11
+
12
+## The 11 recommendations
13
+
14
+Paths in this table are relative to `docs/`.
15
+
16
+| # | Recommendation | Status | Evidence and action |
17
+| --- | --- | --- | --- |
18
+| 1 | Name controls and fields, describe images, and keep essential information readable. | applied | `components/toolkits/managed-auth-list.tsx` had a placeholder but no label for its search field. Add an associated label and hide the decorative search icon. `components/copy-button.tsx`, `components/package-install.tsx`, `components/eve-message.tsx`, and Fumadocs's default codeblock already name copy controls. `components/heading.tsx` names section-link controls. `components/kb/knowledge-search-form.tsx` labels its input. This is not a full accessibility audit. |
19
+| 2 | Deliver essential product information in the initial HTML. | needs decision | `app/(home)/docs/[[...slug]]/page.tsx` renders MDX on the server. Curl confirms product definitions in `/docs` and `/docs/authentication` outside scripts. However, `components/quickstart/quickstart-flow.tsx` registers frameworks in effects and `FrameworkOption` returns null until selected. The live quickstart's install commands are absent outside scripts, while `/docs/quickstart.md` contains them. The Mintlify preview's quickstart already includes install commands in HTML. Make no old-stack selector rewrite; verify complete examples in the chosen migration output. |
20
+| 3 | Put the reader's question in the first H2 below the title. | applied | `content/docs/sessions-vs-direct-execution.mdx` previously reached `## Sessions` only after definitions and the comparison table. Its first H2 now asks "Should I use sessions or direct execution?" Existing section anchors remain. The homepage's imperative H2 and its different Markdown heading remain a migration content follow-up because open PR #5255 owns `lib/home-navigation.ts`. |
21
+| 4 | Follow the question with a conditional answer under 100 words. | applied | The same comparison page now answers the new-integration, fixed-tool-set, and existing-integration cases in 53 whitespace-separated words, before the definitions. Move the existing recommendation out of its later callout and remove the duplicate fixed-tool-set sentence. No SDK behavior or examples change. |
22
+| 5 | Define the product, audience, and function in plain language. | done | `components/docs-hero-v2.tsx` describes tools, managed authentication, and execution. `lib/home-navigation.ts` distinguishes Platform applications from personal For You use. `content/docs/toolkits.mdx` defines toolkit and tool in its opening paragraph; `content/docs/providers/index.mdx` defines a provider. No sitewide slogan or title rewrite. |
23
+| 6 | Publish customer quotes as text. | n/a | The inspected docs entry points, quickstart, and authentication guide contain technical guidance, not customer testimonials. Do not add testimonials to documentation. Landing #769 owns the customer-story review. |
24
+| 7 | Verify volatile claims and attach meaningful "as of" dates. | needs decision | `lib/toolkit-count.ts` derives a rounded toolkit count from the checked-in catalog; this is not a live availability count. `public/data/toolkits-list.json` has 1,722 entries at this revision. PR #5308 owns catalog and API snapshot updates. KB facts use `lastVerifiedAt` and `reviewAfter` in `kb/manifest.json`. A product owner must confirm effective dates for commercial, limit, security, and availability claims. An edit date cannot stand in for verification. |
25
+| 8 | Allow answer-engine crawlers, including meta-webindexer. | done | `public/robots.txt` and live `/robots.txt` have `User-agent: *` with `Allow: /` and advertise `/sitemap.xml`. That includes meta-webindexer. Adding a redundant crawler group buys nothing. Robots permission does not prove indexing or bypass upstream access controls. |
26
+| 9 | Fix broken internal links and preserve redirects. | done | `bun run lint:links` reports zero errors for docs and SDK links. A bounded live GET audit of the 49 distinct internal hrefs on `/docs`, `/docs/quickstart`, and `/docs/authentication` returned 49 HTTP 200 responses after redirects. `next.config.mjs` and `proxy.ts` already handle legacy and Markdown routes. No blanket redirect or host work, and no claim about all external links. |
27
+| 10 | Use native navigation, heading, link, and button semantics. | done | Live `/docs` and `/docs/quickstart` contain navigation, header, main, and article elements. `components/product-docs-layout.tsx` uses Fumadocs `DocsLayout`; `components/page-actions.tsx` uses native buttons and links. `components/kb/kb-article-shell.tsx` has a named article navigation landmark. No old-stack layout rebuild. |
28
+| 11 | Review content regularly and show honest publication and revision dates. | needs decision | `lib/content-freshness-build.ts`, `lib/content-freshness.ts`, `app/sitemap.ts`, and `lib/markdown-response.ts` share source-history dates. `source.config.ts` and the docs page template support a `written` stamp. `components/kb/kb-article-shell.tsx` displays verification dates. Ordinary guides have no general visible last-updated line. Live `/docs.md` and `/docs/authentication.md` return `last_updated: null`; the live sitemap has 2,415 URLs and no `lastmod`, while local generation establishes dates for 230 pages. Assign ownership for deployment verification and content review, and settle date display in Mintlify before adding current-stack UI. |
29
+
30
+Totals: 4 done, 3 applied, 3 need a decision or owner, 1 not applicable.
31
+
32
+## How agents get the content
33
+
34
+The site uses Next.js App Router with Fumadocs MDX, configured in `next.config.mjs` and `source.config.ts`.
35
+`lib/source.ts` loads docs, reference, examples, toolkit, KB, and changelog collections and converts components into Markdown.
36
+`mdx-components.tsx` supplies Fumadocs codeblocks, custom headings, and interactive examples.
37
+`app/layout.tsx` supplies the title template and site metadata; each docs page adds its frontmatter title, description, social metadata, canonical URL, and Markdown alternate.
38
+
39
+The existing agent endpoints have distinct jobs:
40
+
41
+- `app/llms.txt/route.ts` provides a concise routing map with current-session and REST-version guidance.
42
+- `app/llms-index.txt/route.ts` lists guides, references, toolkit links, and knowledge discovery paths, with legacy guidance separated.
43
+- `app/llms-full.txt/route.ts` combines current docs, KB, examples, authored references, and authored toolkit pages. It excludes legacy REST v3.0 and legacy sidebar sections. It is not an export of every dynamic toolkit tool schema or generated API operation.
44
+- `app/llms.mdx/[[...slug]]/route.ts` provides individual Markdown pages, including generated API and toolkit representations. `proxy.ts` routes `.md`, `.mdx`, and negotiated Markdown requests here.
45
+
46
+Live `llms-full.txt` returned about 1.6 MB and included quickstart, session SDK reference, and KB content.
47
+`curl -H 'Accept: text/markdown' https://docs.composio.dev/docs/quickstart` returned HTTP 200, `Content-Type: text/markdown; charset=utf-8`, and `Vary: Accept`.
48
+The quickstart Markdown contains the installation and session examples missing from its current initial HTML.
49
+Keep these representations, version distinctions, and redirects as migration acceptance checks; don't build duplicate infrastructure on the outgoing stack.
50
+
51
+## Freshness and migration limits
52
+
53
+Source edit times record edits, not reviews. Historical examples in `content/docs/migration-guide/` carry `written` or `legacy` labels.
54
+The quickstart explicitly distinguishes the current Python `composio` package from legacy `composio-core`.
55
+REST version metadata identifies v3.1 as current and v3.0 as legacy; those labels are not SDK package versions.
56
+No version contradiction was established in the inspected entry pages. This review does not certify every historical example or pinned provider version.
57
+
58
+The [Mintlify preview](https://composio-preview.mintlify.site/docs) already carries the same imperative homepage heading.
59
+Its quickstart includes installation commands in raw HTML. That observation does not certify parity for every framework, language, or interactive example.
60
+Carry the comparison copy to the migration. Preserve the search field's accessible name if that custom component survives.
61
+Freshness ownership and claim verification still require people after a framework change.
62
+
63
+This change leaves all paths listed by the open docs PRs inspected on November 11 untouched, including #5253, #5254, #5255, #5308, and #5320 through #5323.
64
+It adds no dependencies, Changeset, SDK behavior, generated data, or landing-host redirects.
65
+`kb/semantic-index.json` must be rebuilt through its generator after the content edit; never patch embedding values or hashes by hand.
66
+The PR records the actual check results and any rebuild limitation.
67
+
68
+No AEO improvement is claimed. Evaluate after the next weekly baseline in ComposioHQ/devrel-tools.