Harden toolkit docs generation and indexing by jottakka · Pull Request #1060 · ArcadeAI/docs

jottakka · 2026-07-13T01:48:33Z

Split tracker

This implementation PR has been decomposed into reviewable source PRs. Do not merge this aggregate branch; review and merge the replacements in dependency order.

Independent PRs

Harden toolkit-doc generation against destructive failures #1064 — Harden toolkit-doc generation against destructive failures
Validate and canonicalize generated toolkit routes #1065 — Validate and canonicalize generated toolkit routes
Render toolkit documentation chunks consistently #1068 — Render toolkit documentation chunks consistently
Stabilize Algolia search feedback #1069 — Stabilize Algolia search feedback
Verify toolkit docs before publishing #1070 — Verify toolkit docs before publishing

Stacked PRs

Keep generated sidebar links aligned with toolkit routes #1066 — Keep generated sidebar links aligned with toolkit routes (base: Validate and canonicalize generated toolkit routes #1065)
Publish canonical toolkit URLs in llms.txt #1067 — Publish canonical toolkit URLs in llms.txt (base: Validate and canonicalize generated toolkit routes #1065)
Document the CI-driven llms.txt workflow #1071 — Document the CI-driven llms.txt workflow (base: Publish canonical toolkit URLs in llms.txt #1067)

Generated artifact

public/llms.txt is deliberately not copied into a source PR. Its diff in this aggregate branch contains pre-existing trailing whitespace; the idempotent generation workflow introduced in #1067 should create the artifact after the source behavior lands.

Verification

On the original aggregate head:

pnpm run toolkit-docs:check — 46 files / 585 tests passed
pnpm test — 60 files / 790 tests passed
pnpm build — passed
pnpm lint — exited 0 with three pre-existing complexity warnings in untouched generator files

Each replacement PR also has a focused test command recorded in its body. The workflow PR uses an isolated generator-test root so it remains independently green from main.

Fail closed on unsafe or incomplete inputs, reuse one Engine snapshot, and expose generated routes to crawlers. Replace the redundant site build with focused generator validation and document the Vercel and Algolia flow. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel · 2026-07-13T01:48:40Z

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 13, 2026 10:36pm

jottakka · 2026-07-13T01:49:45Z

@cursor review

cursor · 2026-07-13T01:49:52Z

Current version of PR was reviewed by /review-bugbot with additional instructions on Jul 12, 22:44 GMT-3. It flagged 0 findings.

^{Bugbot on commit b0a39fa is skipped.}

Keep last-known-good output on failures while returning nonzero status, publish real toolkit routes to llms.txt, and align Markdown, sidebar, slug, and subpage handling across consumers. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-13T16:17:07Z

@cursor review

Skip llms generation when its own bot commit synchronizes the PR, while retaining full-history diffs and fork safety. Co-authored-by: Cursor <cursoragent@cursor.com>

Ignore metadata-only changes so generated commits preserve the prior source SHA and do not trigger another artifact commit. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-13T16:36:47Z

@cursor review

Allow manual workflow dispatches to target a dedicated branch and base ref without changing the shared automation PR. Co-authored-by: Cursor <cursoragent@cursor.com>

Request InstantSearch-compatible highlight markers and suppress stale results until they match the current typed query. Co-authored-by: Cursor <cursoragent@cursor.com>

Collapse rapid keystrokes into one request so the result list no longer repeatedly unmounts and rerenders during input. Co-authored-by: Cursor <cursoragent@cursor.com>

Exercise rapid query replacement and immediate clearing with fake timers so the anti-flicker request behavior cannot regress. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-13T21:37:44Z

Algolia search regression verification

Reproduced on the preview before the fix:

Algolia returned <em> highlights because the request omitted InstantSearch marker tags.
Stale results and Searching… alternated repeatedly while typing.
The dialog performed 13 DOM state transitions for github, exposing literal HTML tags and causing visible jank.

Fixed by requesting __ais-highlight__ markers, suppressing stale-query results, and debouncing input by 150 ms.

Final generated preview measurement:

1 Algolia request for typing github.
2 states only: Searching… → results.
0 literal-tag renders.
0 console errors.
0 search-time long tasks.

jottakka · 2026-07-13T21:41:35Z

@cursor review

Group generated integrations in llms.txt, reject invalid empty slugs, and preserve UI chunk placement and replacement semantics in Markdown exports. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-13T22:08:35Z

@cursor review

Handle failed Algolia requests explicitly and preserve null safety when lightweight documentation chunks share sort priority. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-13T22:21:23Z

@cursor review

Target the dispatch ref only for explicit verification branches while keeping shared automation PRs on the repository default branch. Co-authored-by: Cursor <cursoragent@cursor.com>

jottakka · 2026-07-13T22:34:37Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 63c423c. Configure here.}

vercel Bot deployed to Preview July 13, 2026 01:51 View deployment

fix: close toolkit docs publishing gaps

2ed985f

Keep last-known-good output on failures while returning nonzero status, publish real toolkit routes to llms.txt, and align Markdown, sidebar, slug, and subpage handling across consumers. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added 3 commits July 13, 2026 16:17

🤖 Regenerate LLMs.txt

5fff026

🤖 Regenerate LLMs.txt

f8f5862

🤖 Regenerate LLMs.txt

0307162

cursor Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread scripts/generate-llmstxt.ts

github-actions Bot added 2 commits July 13, 2026 16:19

🤖 Regenerate LLMs.txt

1ca0440

🤖 Regenerate LLMs.txt

b3b797b

vercel Bot deployed to Preview July 13, 2026 16:22 View deployment

jottakka and others added 13 commits July 13, 2026 13:22

fix: stop llms workflow commit loops

3c4bc88

Skip llms generation when its own bot commit synchronizes the PR, while retaining full-history diffs and fork safety. Co-authored-by: Cursor <cursoragent@cursor.com>

🤖 Regenerate LLMs.txt

39487e3

🤖 Regenerate LLMs.txt

1d8d487

🤖 Regenerate LLMs.txt

0384fb9

🤖 Regenerate LLMs.txt

6f687f3

🤖 Regenerate LLMs.txt

25029d9

🤖 Regenerate LLMs.txt

2a99723

🤖 Regenerate LLMs.txt

f1df760

🤖 Regenerate LLMs.txt

0a24fa4

🤖 Regenerate LLMs.txt

8879e86

🤖 Regenerate LLMs.txt

229069d

🤖 Regenerate LLMs.txt

1bb98dd

fix: make llms generation idempotent

ab6d2f4

Ignore metadata-only changes so generated commits preserve the prior source SHA and do not trigger another artifact commit. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 16:34 View deployment

cursor Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread app/_lib/toolkit-slug.ts Outdated

Comment thread app/_lib/toolkit-markdown.ts

feat: support isolated toolkit docs verification PRs

ee4d519

Allow manual workflow dispatches to target a dedicated branch and base ref without changing the shared automation PR. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 20:32 View deployment

fix: stop Algolia result flicker and literal tags

b8702d8

Request InstantSearch-compatible highlight markers and suppress stale results until they match the current typed query. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 21:14 View deployment

fix: debounce Algolia search while typing

43f3c40

Collapse rapid keystrokes into one request so the result list no longer repeatedly unmounts and rerenders during input. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 21:24 View deployment

test: verify Algolia debounce behavior

e0a0e6a

Exercise rapid query replacement and immediate clearing with fake timers so the anti-flicker request behavior cannot regress. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 21:32 View deployment

jottakka self-assigned this Jul 13, 2026

cursor Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread app/_lib/toolkit-markdown.ts

fix: resolve Bugbot docs publishing findings

37501a0

Group generated integrations in llms.txt, reject invalid empty slugs, and preserve UI chunk placement and replacement semantics in Markdown exports. Co-authored-by: Cursor <cursoragent@cursor.com>

🤖 Regenerate LLMs.txt

7ad8777

vercel Bot deployed to Preview July 13, 2026 22:11 View deployment

cursor Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread app/_components/toolkit-docs/lib/documentation-chunks.ts Outdated

Comment thread app/_components/algolia-search.tsx

fix: resolve remaining Bugbot edge cases

ca1a640

Handle failed Algolia requests explicitly and preserve null safety when lightweight documentation chunks share sort priority. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 22:23 View deployment

cursor Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread .github/workflows/generate-toolkit-docs.yml

fix: isolate manual docs verification branches

63c423c

Target the dispatch ref only for explicit verification branches while keeping shared automation PRs on the repository default branch. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview July 13, 2026 22:36 View deployment

cursor Bot reviewed Jul 13, 2026

View reviewed changes

jottakka marked this pull request as ready for review July 15, 2026 17:35

jottakka mentioned this pull request Jul 16, 2026

Publish canonical toolkit URLs in llms.txt #1067

Closed

jottakka closed this Jul 16, 2026

Uh oh!

Conversation

jottakka commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Split tracker

Independent PRs

Stacked PRs

Generated artifact

Verification

Uh oh!

vercel Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

cursor Bot commented Jul 13, 2026

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

Uh oh!

Uh oh!

jottakka commented Jul 13, 2026

Algolia search regression verification

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

Uh oh!

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

Uh oh!

jottakka commented Jul 13, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jottakka commented Jul 13, 2026 •

edited

Loading

vercel Bot commented Jul 13, 2026 •

edited

Loading