docs: add product architecture guides and KB entry points

[Soham Basu (sohambasu963)]

Summary

Adds canonical guidance for common Composio product-integration decisions and makes the main paths easy to find from the Knowledge Base homepage. This PR is independent of #4258 and #4277 and targets next directly.

Changes

• Add guides for the Composio skill, consumer-agent architecture, B2B-agent architecture, and moving from prototype to production
• Expand the white-labeling guide with a minimal setup path and FAQ
• Add five Start here cards to /kb, before support topics and toolkit browsing
• Update OAuth callback examples and add relevant sidebar and quickstart cross-links

Type of change

• Documentation

How Has This Been Tested?

• bun test tests/static/ (528 passed)
• bun run lint:links
• bun run types:check
• bun run lint
• bun run build

Checklist

• I have read the Code of Conduct and this PR adheres to it
• I ran linters/tests locally and they passed
• I updated documentation and structural homepage coverage
• No changeset is required for docs-only changes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 29, 2026 1:36am

[claude]

Claude finished Soham Basu (@sohambasu963)'s task in 4m 28s —— View job

---

Docs Review

• Read docs/agent-guidance/agents/docs-reviewer.md
• Run git diff origin/next...HEAD
• Apply review checklist to changed files
• Verify API usage in the new guides against SDK source
• Run docs checks locally (bun test tests/static/, bun run lint:links)
• Post review

---

Looks good overall — the guides are accurate, the navigation wiring is complete, and I could not find anything that would leave a developer stuck. Two things worth fixing, one of which I'd call a real correctness gap.

Verified

• Session APIs are correct. composio.sessions.create(user_id=..., toolkits=[...]) matches python/composio/core/models/tool_router.py:655; composio.create(userId, {...}) matches the alias at ts/packages/core/src/composio.ts:374. composio.use(), session.session_id / session.sessionId, and session.tools() all exist on both SDKs.
• The v1 → v3 callback URL change is right, and matches what docs/content/docs/migration-guide/new-sdk.mdx:742 already states.
• Navigation is complete. New pages are in meta.json, navigation.test.ts was updated for the Get Started group, and no orphan-file regression was introduced.
• Every internal link resolves — /docs/extending-sessions/shared-connections, /docs/security/data-retention, /docs/configuring-sessions, /docs/authentication#in-chat-authentication, /reference/api-reference/logs, etc.
• Cards, Callout type="warn", and Tabs are all globally provided by docs/mdx-components.tsx — the <Card> → <Cards> change in the white-labeling page is fine.
• Local checks: bun test tests/static/ → 527 pass / 0 fail. bun run lint:links → 0 errors. Matches the PR description.
• The stale api/v1/auth-apps/add entries in docs/kb/semantic-index.json regenerate automatically via .github/workflows/docs-rebuild-kb-semantic.yml, so no manual action needed there.

---

Issue 1: The callback-URL correction misses four other live references

Issue: This PR updates the OAuth callback URL to api/v3/toolkits/auth/callback in the authentication/ pages, but the auth-configuration/ pages still publish the old api/v1/auth-apps/add. Those pages are legacy: true but still shipped in the sidebar (docs/content/docs/meta.json:28, under Direct execution (legacy)). A developer landing on one of them will register the wrong redirect URI in the provider's developer portal, and OAuth will fail with a redirect-URI mismatch that gives no hint about the docs being stale.

Remaining references:

• docs/content/docs/auth-configuration/custom-auth-configs.mdx:82
• docs/content/docs/auth-configuration/white-labeling.mdx:81
• docs/content/docs/auth-configuration/white-labeling.mdx:239
• docs/content/docs/auth-configuration/white-labeling.mdx:249
• python/examples/auth_configs.py:28

Fix:

- https://backend.composio.dev/api/v1/auth-apps/add
+ https://backend.composio.dev/api/v3/toolkits/auth/callback

Fix this →

---

Issue 2: TypeScript tabs use the aliased entrypoint while Python uses the canonical one

Issue: In docs/content/docs/consumer-agents.mdx:20 and docs/content/docs/b2b-agents.mdx:29 the Python tab uses composio.sessions.create(...), but the TypeScript tab in the same block (consumer-agents.mdx:35, b2b-agents.mdx:46) uses composio.create(...). Both work, but ts/packages/core/src/composio.ts:220 says of composio.create: "Prefer composio.sessions.create(...) for new code." Since these are the pages telling people how to structure a production integration, the two tabs should teach the same entrypoint.

Fix:

// Before
const session = await composio.create(appUserId, {
  toolkits: ["gmail", "googlecalendar"],
});

// After
const session = await composio.sessions.create(appUserId, {
  toolkits: ["gmail", "googlecalendar"],
});

Fix this →

---

Non-blocking note

docs/content/docs/using-composio-skill.mdx is titled "Build with the Composio skill" and sits two entries above "Skills" (docs/content/docs/skills.mdx) in the sidebar — but they describe unrelated things. skills.mdx is about execution playbooks returned by COMPOSIO_SEARCH_TOOLS; the new page is about the coding-agent skill at skills/composio/SKILL.md. Consider disambiguating the new title (e.g. "Build with the Composio coding-agent skill") or adding a one-line pointer between the two pages. Not a blocker.

I also could not verify the npx skills add ComposioHQ/composio --skill composio -y invocation offline — it's the only place in the repo that documents installing that skill. The --skill composio selector does match skills/composio/, so it looks right; worth a quick manual run before merge.

---

· branch codex/docs-priority-guides

[claude]

Claude finished Soham Basu (@sohambasu963)'s task in 2m 18s —— View job

---

Docs Review (re-run after a5f0b18)

• Read docs/agent-guidance/agents/docs-reviewer.md
• Diff against merge base 64b1b85
• Review the new commit (a5f0b18 — KB start-here cards)
• Re-check the two issues from the previous review
• Run docs checks locally
• Post review

---

The new commit looks good. The two issues from my previous review are still open, so I'm restating them below rather than repeating the full re-verification of the earlier commit.

New in a5f0b18 — KB start-here guide cards

docs/components/kb/knowledge-hub.tsx:62-78 is a faithful copy of the existing #support-topics section immediately below it (:80-93) — same grid gap-px border treatment, same sm:grid-cols-2 lg:grid-cols-5 responsive breakpoints, same focus-visible:ring-inset treatment on the Link, same aria-hidden on the decorative ArrowRight. Heading hierarchy stays correct (hero h1 → section h2 with aria-labelledby → card h3). No accessibility, mobile, or pattern deviations.

Hardcoding the five hrefs in the component is consistent with components/home-features.tsx:45-63 and components/quickstart/quickstart-flow.tsx:178, so no objection there.

docs/tests/static/knowledge-hub.test.tsx:116-138 pins both the href list and the section ordering (start-here → support-topics → toolkits), which is the right assertion for a section whose whole purpose is placement.

Local checks: bun test tests/static/ → 528 pass / 0 fail (up one, the new ordering test). bun run lint:links → 0 errored files, 0 errors.

---

Still open: the callback-URL correction misses five other live references

Unchanged since my last review. This PR fixes api/v3/toolkits/auth/callback in authentication/, but the auth-configuration/ pages still publish api/v1/auth-apps/add. Those pages are legacy: true but still shipped in the sidebar (docs/content/docs/meta.json:28, under Direct execution (legacy)), so a developer can land on one and register the wrong redirect URI in the provider's portal — OAuth then fails with a redirect-URI mismatch that gives no hint the docs are stale.

• docs/content/docs/auth-configuration/custom-auth-configs.mdx:82
• docs/content/docs/auth-configuration/white-labeling.mdx:81
• docs/content/docs/auth-configuration/white-labeling.mdx:239
• docs/content/docs/auth-configuration/white-labeling.mdx:249
• python/examples/auth_configs.py:28

- https://backend.composio.dev/api/v1/auth-apps/add
+ https://backend.composio.dev/api/v3/toolkits/auth/callback

(ts/docs/api/toolkits.md:116 also carries the old default, but that file is generated — leave it to the generator.)

Fix this →

---

Still open: TypeScript tabs use the aliased entrypoint while Python uses the canonical one

Also unchanged. docs/content/docs/consumer-agents.mdx:20 and docs/content/docs/b2b-agents.mdx:29 use composio.sessions.create(...) in the Python tab, while the TypeScript tab in the same block (consumer-agents.mdx:35, b2b-agents.mdx:46) uses composio.create(...). Both work — ts/packages/core/src/composio.ts:374 binds one to the other — but the doc comment at composio.ts:220-221 says: "Prefer composio.sessions.create(...) for new code. The top-level composio.create(...) method is kept as an alias." These are the pages telling people how to structure a production integration, so both tabs should teach the same entrypoint.

// Before
const session = await composio.create(appUserId, {
  toolkits: ["gmail", "googlecalendar"],
});

// After
const session = await composio.sessions.create(appUserId, {
  toolkits: ["gmail", "googlecalendar"],
});

Fix this →

---

Non-blocking (carried over)

docs/content/docs/using-composio-skill.mdx is titled "Build with the Composio skill" and sits a few entries above "Skills" (docs/content/docs/skills.mdx) in the sidebar, but they describe unrelated things — skills.mdx is about execution playbooks returned by COMPOSIO_SEARCH_TOOLS, the new page is about the coding-agent skill at skills/composio/SKILL.md. Worth disambiguating the title or adding a one-line pointer between them.

I still can't verify npx skills add ComposioHQ/composio --skill composio -y offline. The --skill composio selector matches skills/composio/, so it looks right; worth one manual run before merge.

--- · branch codex/docs-priority-guides