@devries-cameron20 / composio-1 / commits / f61d0d4ad
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: record toolkit availability recovery

jkomyno committed Aug 25, 2026 at 03:35 UTC f61d0d4ad7a125acadd67a61ed45e76c96204958
2 files changed +73
docs/decisions/README.md
+2
@@ -9,5 +9,7 @@ Read these when a docs change touches an existing architecture, generated-data p
9 - `llm-guardrails.md` - LLM guardrail injection for markdown endpoints.
10 - `public-knowledge-base.md` - public support publication, unified search, and
11 Composio For You snapshot rules.
12 +- `toolkit-page-availability.md` - docs-sync permissions, optional KB isolation,
13 + and snapshot-miss toolkit page fallback.
14 - `toolkits.md` - toolkit page data and rendering decisions.
15 - `cookbooks-revamp-plan.md` - historical cookbook revamp tracker.
docs/decisions/toolkit-page-availability.md new
+71
@@ -0,0 +1,71 @@
1 +# Toolkit Page Availability
2 +
3 +## Decision
4 +
5 +Keep generated toolkit snapshots authoritative, but allow an individual toolkit
6 +page to query production when its slug is absent from the snapshot. The fallback
7 +is snapshot-first and limited to one validated slug. It is not a live catalog
8 +and does not change how the toolkit landing page, sitemap, search, KB
9 +verification, or `llms.mdx` resolve toolkit data.
10 +
11 +Keep the primary docs-sync GitHub App token limited to repository contents and
12 +pull requests. It must not request `issues`. Steps that create, update, or close
13 +issues in this repository use `github.token` under the workflow's job-level
14 +`issues: write` permission.
15 +
16 +## Context
17 +
18 +The toolkit pages were coupled to the freshness of
19 +`public/data/toolkits.json`. When the docs data sync stopped before generation,
20 +valid production toolkits added after the last snapshot returned 404. The
21 +[toolkit page decisions](./toolkits.md) establish the generated snapshot as the
22 +default data source, and the
23 +[KB freshness decision](./kb-freshness-verification.md) relies on the same
24 +snapshot architecture. The runtime fallback preserves those decisions while
25 +removing snapshot freshness as an availability requirement for individual
26 +toolkit pages.
27 +
28 +The sync failure came from requesting a GitHub App permission that the
29 +installation did not grant. Issue tracking does not need the App token because
30 +it only writes to the current repository. The separate token for
31 +`ComposioHQ/support-knowledge` and every step that consumes it are optional and
32 +non-fatal. A failure in that path can reduce KB freshness evidence, but it cannot
33 +block toolkit, OpenAPI, API index, or meta-tool generation.
34 +
35 +## Consequences
36 +
37 +- A snapshot hit renders without a production catalog request.
38 +- A snapshot miss may issue one production lookup for the validated slug. An
39 + invalid or unknown slug still returns 404.
40 +- Landing, sitemap, search, KB verification, and build behavior remain
41 + snapshot-backed.
42 +- `/llms.mdx/toolkits/<slug>` parity is deferred. A toolkit available only
43 + through the page fallback can still return 404 from that route.
44 +- `COMPOSIO_TOOLKIT_LIVE_FALLBACK=0` disables the production lookup and restores
45 + snapshot-only page resolution. Changing this Vercel environment variable does
46 + not affect the running production deployment. Create a new Vercel deployment
47 + after changing it. Re-enable the fallback by removing the value or setting it
48 + to a value other than `0`, then deploy again.
49 +- The guaranteed code rollback is to revert the toolkit route integration and
50 + deploy the reverted revision.
51 +
52 +## Verification
53 +
54 +A local workflow test cannot prove GitHub App installation permissions. The
55 +required proof is a `workflow_dispatch` run at the exact reviewed head that
56 +passes the token step and reaches `Generate toolkits data`.
57 +
58 +Run `32797593048` at commit `3716bda` passed both the token step and
59 +`Generate toolkits data`. This proves the installation accepted the token
60 +request at that exact head. The hosted runtime contains a `COMPOSIO_API_KEY`
61 +environment variable name, but its production scope has not been verified.
62 +Production fallback behavior therefore remains unverified until a deployed
63 +snapshot-miss toolkit page returns 200 with the expected toolkit data.
64 +
65 +For future changes:
66 +
67 +- Run `bun run lint:links` from `docs/` after editing this record.
68 +- Dispatch `Docs - Update Data` at the exact reviewed head after changing token
69 + permissions.
70 +- After deployment, verify one snapshot-backed slug and one valid production
71 + slug absent from the committed snapshot both return 200.