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.