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: review AEO readiness and clarify the execution choice (#5325)
> Written by an AI agent at Brendan's request. Human review is pending. ## Summary The execution comparison buried its recommendation below definitions, and the managed OAuth catalog's search field had no associated label. This PR names that field and puts a reader question and a short conditional answer before the comparison details. It also records which of Rob Hoffman's 11 recommendations are already covered and which need an owner or a migration decision. Companion work: [landing #769](https://github.com/ComposioHQ/landing/pull/769). That PR covers composio.dev. The [full source post](https://api.fxtwitter.com/RobHoffman_/status/2112212215583658420) and the landing report were read before this review. The supplied landing branch name was stale; #769 now uses `cos/rob-hoffman-aeo`, head `7edb1590f6f99ecf4b54008ed9b5798e4287b5be`. This is Brendan's requested docs work. No reviewers requested. Please review the full diff before submitting or merging it. ## The 11 recommendations Evidence paths below are relative to `docs/`. "Done" describes the inspected mechanisms and pages, not a sitewide certification. "Applied" describes a concrete fix, not a measured ranking or citation gain. | # | Recommendation | Status | Evidence and action | | --- | --- | --- | --- | | 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. | | 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. | | 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`. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | 4 done, 3 applied, 3 need a decision or owner, 1 not applicable. ## Changes Each applied optimization is a separate commit so it can be dropped: - Item 1, `ef8919447`: associate a hidden label with the managed OAuth toolkit search and hide its decorative icon from assistive technology. - Item 3, `639c2a847`: put "Should I use sessions or direct execution?" in the comparison's first H2. Keep its existing section anchors. - Item 4, `31f5c32ab`: move the recommendation to a 53-word answer that distinguishes new integrations, fixed tool sets, and existing direct execution. Remove the later duplicate callout and sentence. - `246820641`: record the triage, framework and endpoint map, migration limits, and freshness findings in `docs/aeo/rob-hoffman-11.md`. No dependencies, SDK behavior changes, Changeset, generated data edits, or landing host redirects. The branch started at `origin/next` `e1f47b0a1`. Open docs PR file lists were read through GitHub, including #5253, #5254, #5255, #5308, and #5320 through #5323. No files from those PRs or the other inspected open docs PRs are changed. In particular, the homepage MDX, `lib/home-navigation.ts`, `lib/source.ts`, `next.config.mjs`, security/auth copy, catalog snapshots, and generated KB files stay with their existing owners. ## Type of change - [x] Documentation - [x] Bug fix, accessible field label ## How Has This Been Tested? Commands below ran from `docs/`, except the two agent-guidance checks and Git checks, which ran at the repository root. Output excerpts are copied from their logs. `bun install --frozen-lockfile` exited 0: ```text 852 packages installed [6.18s] ``` `bun run test` exited 0 before and after the implementation. Final output: ```text 833 pass 0 fail 34489 expect() calls Ran 833 tests across 79 files. [66.70s] ``` `bun run lint` exited 0 and emitted existing warnings, including: ```text components/home-features.tsx:121:12: warning next(no-img-element): Using `<img>` could result in slower LCP and higher bandwidth. help: Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. ``` `bun run lint:links` exited 0: ```text $ bun scripts/validate-links.ts && bun run lint:links:sdk 0 errored file, 0 errors $ bun scripts/validate-sdk-doc-links.ts 0 errored file, 0 errors ``` `bun run types:check` exited 0: ```text Persisted trustworthy freshness for 230 pages. Generating route types... ✓ Types generated successfully ``` `bun run check:kb-semantic --allow-stale` exited 0 with this warning: ```text Warning: Semantic artifact docs content hash mismatch. Search falls back to keyword results until the artifact is rebuilt. Run bun run build:kb-semantic with OPENAI_API_KEY, or use the Docs - Rebuild KB Semantic Artifact workflow. ``` `OPENAI_API_KEY` is unavailable in this session. I did not rebuild `docs/kb/semantic-index.json` or edit its values/hashes. The existing **Docs - Rebuild KB Semantic Artifact** workflow can regenerate it for an eligible same-repository PR after **Docs - Tests** runs. `bun run check:code-examples` exited 0: ```text No code example violations in 448 file(s). ``` `bun run validate:agent-skills` and `bun run validate:skill-routing` exited 0: ```text Validated 20 canonical agent skills and guidance invariants. Skill-routing smoke test passed (20 probes over 20 skills). ``` `GITHUB_ACTIONS=true bun run build` exited 0, using the repository's existing two-worker CI setting. Output excerpts: ```text ✓ Compiled successfully in 2.6min Finished TypeScript in 20.7s ... ✓ Generating static pages using 2 workers (2576/2576) in 16.7s Turbopack build encountered 1 warning: ./agent/lib/docs.ts:510:21 Warning: Dynamic filesystem access causes tracing of the whole project ``` The build had no `COMPOSIO_API_KEY` and used the checked-in toolkit snapshots. It reported that detailed live tool/trigger fetching was skipped. The existing filesystem tracing warning is outside this diff. With `PORT=3214 bun run start`, `TEST_BASE_URL=http://localhost:3214 bun run test:integration` exited 0: ```text 1 tests skipped: (skip) toolkit snapshot fallback > production-only fallback requires COMPOSIO_API_KEY 243 pass 1 skip 0 fail 733 expect() calls Ran 244 tests across 12 files. [25.80s] ``` `curl -fsSL http://localhost:3214/docs/sessions-vs-direct-execution -o /tmp/aeo-changed.html` and the equivalent `.md` request exited 0. `python /tmp/aeo-check-rendered.py` exited 0: ```text Built HTML and Markdown: first H2 is the reader question; matching answer is 53 words. Existing #sessions and #direct-execution anchors preserved. ``` <details><summary>Reproduce the rendered HTML and Markdown check</summary> After the two curl requests above, save this as `/tmp/aeo-check-rendered.py`: ```python from html.parser import HTMLParser from pathlib import Path import re class Text(HTMLParser): def __init__(self): super().__init__() self.parts = [] def handle_data(self, text): self.parts.append(text) def plain(fragment): parser = Text() parser.feed(fragment) return ' '.join(''.join(parser.parts).split()) html = Path('/tmp/aeo-changed.html').read_text() html = re.sub(r'<(script|style)\b[^>]*>[\s\S]*?</\1>', '', html) question = 'Should I use sessions or direct execution?' match = re.search(r'<h2\b[^>]*>([\s\S]*?)</h2>\s*<p>([\s\S]*?)</p>', html) assert match and plain(match[1]) == question answer = plain(match[2]) markdown = Path('/tmp/aeo-changed.md').read_text() heading = re.search(r'^## (.+)$', markdown, re.M) assert heading and heading[1].split(' [#')[0] == question md_answer = markdown[heading.end():].strip().split('\n\n')[0] md_answer = re.sub(r'\[([^]]+)\]\([^)]+\)', r'\1', md_answer) assert ' '.join(md_answer.split()) == answer assert len(answer.split()) <= 100 assert 'fixed set' in answer and 'existing integrations' in answer assert all(f'id="{anchor}"' in html for anchor in ['sessions', 'direct-execution']) print(f'Built HTML and Markdown: first H2 is the reader question; matching answer is {len(answer.split())} words.') print('Existing #sessions and #direct-execution anchors preserved.') ``` </details> The live link audit used GET with redirects and checked the 49 distinct internal hrefs collected from `/docs`, `/docs/quickstart`, and `/docs/authentication`. Output: ```text Checked 49 distinct internal hrefs from /docs, /docs/quickstart and /docs/authentication: 49 HTTP 200 after redirects; 0 failures [] ``` <details><summary>Reproduce the bounded live link audit</summary> Save this as `/tmp/aeo-live-link-audit.py` and run `python /tmp/aeo-live-link-audit.py`. It uses only Python's standard library and curl. ```python from concurrent.futures import ThreadPoolExecutor from html.parser import HTMLParser import subprocess from urllib.request import urlopen class Links(HTMLParser): def __init__(self): super().__init__() self.paths = set() def handle_starttag(self, tag, attrs): href = dict(attrs).get('href', '') if tag == 'a' and href.startswith('/') and not href.startswith('//'): self.paths.add(href.split('#')[0]) links = Links() for path in ['/docs', '/docs/quickstart', '/docs/authentication']: with urlopen('https://docs.composio.dev' + path, timeout=35) as response: links.feed(response.read().decode()) def check(path): result = subprocess.run([ 'curl', '-sS', '-L', '--max-time', '35', '-o', '/dev/null', '-w', '%{http_code} %{url_effective}', 'https://docs.composio.dev' + path, ], capture_output=True, text=True) return path, result.stdout, result.returncode with ThreadPoolExecutor(max_workers=8) as pool: results = list(pool.map(check, sorted(links.paths))) failures = [item for item in results if not item[1].startswith('200 ') or item[2]] print(f'Checked {len(results)} distinct internal hrefs from /docs, /docs/quickstart and /docs/authentication: {len(results)-len(failures)} HTTP 200 after redirects; {len(failures)} failures') print(failures) raise SystemExit(bool(failures)) ``` </details> `curl -fsSL -D /tmp/aeo-negotiated.headers -H 'Accept: text/markdown' https://docs.composio.dev/docs/quickstart -o /tmp/aeo-negotiated.md` exited 0. Relevant headers: ```text HTTP/2 200 content-type: text/markdown; charset=utf-8 vary: Accept ``` `git diff --check origin/next...HEAD` exited 0 with no output. Comparing changed paths with the inspected open PR file lists returned: ```text Protected files changed: [] ``` The prose and label edits do not add branching logic. No new test suite or dependency was added. Existing static, link, type, and integration checks plus rendered output checks cover the changed representations. ## Screenshots No browser capture or visual approval is claimed. Item 1 adds a screen-reader label without visible text. Items 3 and 4 change document flow; rendered HTML and Markdown were inspected as described above. ## Risks and decisions | Applied item | Risk | | --- | --- | | 1 | Assistive tools announce the new field name. Filtering behavior stays the same. The small fix applies to the current custom catalog; preserve the name only if this component survives the migration. | | 3 | An extra heading changes the table of contents and vertical spacing. Existing anchors and the URL stay the same. Carry this MDX copy into Mintlify. | | 4 | The recommendation loses its callout box and moves before the definitions. Review its positioning. The three use cases and links come from existing guidance; examples and API behavior stay the same. | NEEDS BRENDAN: assign the product/docs owner who verifies volatile facts, approves effective dates, and owns the review cadence. Source edit timestamps are not review dates. That owner should also resolve the live freshness deployment gap before treating null dates as intentional. NEEDS BRENDAN: decide the Mintlify migration acceptance owner. Require complete quickstart examples in initial HTML, the existing Markdown/LLM/version/redirect behavior, and an honest date-display policy. Do not fund a selector or freshness-UI rebuild on the current stack while that decision is pending. ## Measurement No AEO improvement is claimed. None can be measured until the next weekly baseline in ComposioHQ/devrel-tools. These checks establish the content and accessibility changes, not outcomes in ChatGPT, Gemini, Perplexity, or Meta. A reader can now find the execution recommendation before reading the details. Assistive tools can identify the managed OAuth catalog's search field. ## Checklist - [x] Agent read the full diff and the contribution guidance; human review is pending. - [x] Source links document the requested audit; no promotional links added. - [x] Relevant local checks and their limits are listed above. - [x] Documentation updated; no SDK release note needed. - [x] Generated artifact requires an authorized rebuild, recorded above.
No changes.