feat(copilot): build the docs vfs from a generated manifest, rescope search_docs by j15z · Pull Request #5948 · simstudioai/sim

j15z · 2026-07-25T00:37:39Z

Summary

Mounts Sim's public documentation as a read-only docs/ tree in the copilot VFS, and replaces search_documentation with a path-scoped search_docs.

The corpus is navigated like a filesystem. glob matches a checked-in manifest generated from apps/docs/content/docs/en with no network access; read fetches the page live from docs.sim.ai; grep takes exactly one page, since each is a separate request. Manifest entries double as both the docs/ VFS path and the docs.sim.ai URL path, so a read needs no lookup table. Like uploads/, the tree is opt-in — only a pattern or path that explicitly starts with docs/ ever sees it, and only the search agent's prompt advertises it.

search_docs adds an optional path scope (one page or a section) and returns the docs/ path with every hit, so search chains into read. Unscoped searches exclude academy/ and api-reference/, which are indexed but not mounted, and results whose source no longer maps to a live path are dropped — the index is rebuilt on release, so it lags the manifest.

@docs chat tagging is disabled: its query was the raw user message, and its mention UI was already unreachable.

search_documentation is kept in the catalog as a hidden, deprecated entry routed to Sim, so the id still resolves during a mixed-version deploy. It is in no agent's allow list. Remove it, along with the alias in baseServerToolRegistry, once search_docs is live in prod on both sides.

Type of Change

New feature

Testing

Tested manually against the running app. tsc clean, 947 copilot tests, biome clean, and all 11 CI audits pass (boundaries, api-validation:strict, utils, zustand-v5, react-query, client-boundary, bare-icons, icon-paths, realtime-prune, skills, agent-stream-docs).

Reviewers should focus on:

docs-search.ts scope mapping. source_document stores the en-relative mdx path while VFS paths mirror the public URL, so a section overview is docs/workflows.mdx in the VFS but workflows/index.mdx on disk. Both directions are tested, including a round-trip over every manifest entry.
sync-docs-manifest.ts + the CI check. Adding, renaming, or deleting a page without regenerating fails the build; editing page content does not.
search-docs-alias.test.ts. Dispatch gates on catalog membership before consulting the handler registry, so the alias needs the hidden catalog entry to be reachable at all. The test pins every link in that chain.

Checklist

Code follows project style guidelines
Self-reviewed my changes
Tests added/updated and passing
No new warnings introduced
I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Companion PRs

simstudioai/mothership#371

Merge sim first. The alias covers an older Mothership calling this build; the reverse — a new Mothership calling an older Sim — cannot be fixed from either side.

…ocs; serve openapi.json publicly - search_docs server tool: same vector search over docs_embeddings plus an optional docs/documentation/... VFS path prefix mapped onto a source_document scope (covers both <tail>.mdx and <tail>/... layouts); unscoped searches exclude academy/ and api-reference/ rows so the scope is exactly the Documentation tab - @docs chat context repointed to the new tool; display label updated - apps/docs now serves /openapi.json so the mothership can build its docs/api-reference/<tag>.json VFS views from the deployed spec - generated tool catalog/schemas regenerated from the mothership contract Companion: simstudioai/mothership feat/enhance-search-agent Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…tool chips read("docs/documentation/workflows/index.mdx") now renders "Read Workflows/index" instead of the leaf-only fallback ("Read Index"). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

"Searched docs" becomes 'Searched docs for "<query>"' (toolTitle/title preferred, query fallback, truncated at 60 chars). Also adds the missing browser_list_sessions display title the catalog regen surfaced. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A 400 from the chat POST's ChatMessageSchema parse returned the zod issues to the client but logged nothing, making "message disappears on send" undiagnosable from server logs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A workspace_resource tag emitted with id:"" resolved through `??` chains (which keep empty strings), got persisted onto the chat's resources, and then every send attached it and failed the chat request's id min-length validation — the message vanished on send, forever. Resolve chip ids by first non-empty candidate and drop id-less resources when building request attachments. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…search_docs Replaces the mothership's runtime docs corpus (llms.txt + llms-full.txt + openapi.json behind a 15m TTL cache) with a static manifest generated from the docs source, plus live per-page fetches. ~1,000 fewer lines of hand- written code and one repo instead of two. - scripts/sync-docs-manifest.ts walks apps/docs/content/docs/en and emits lib/copilot/generated/docs-manifest.ts. Each entry is simultaneously the docs/ VFS path and the docs.sim.ai URL path, so a read is a plain fetch. Section index pages fold onto their parent (fumadocs serves /workflows, not /workflows/index); academy/ and api-reference/ are excluded — they stay unmounted and unsearchable, reachable only via scrape_page. - docs-manifest:generate / :check, with a CI step so a page added, renamed, or deleted without regenerating fails the build. Content edits don't. - lib/copilot/docs/docs-corpus.ts + tools/handlers/vfs.ts: glob matches the manifest with no network, read fetches the page live, grep takes exactly ONE page (each is a fetch, so there is no corpus-wide grep). Opt-in like uploads/ — only an explicit docs/ prefix ever matches. - search_docs now scopes to the docs/ tree instead of docs/documentation/, validates its path against the manifest (a bad path errors instead of silently returning nothing), and returns the docs/ path with every chunk so search chains into read. Unscoped searches drop rows the agent could not then read: unmounted sections, and pages gone since the last index rebuild. - @docs tagging disabled: its query was the raw user message, a poor embedding query, and the mention UI it fed was already dead code. - Reverts the apps/docs /openapi.json route, added only for the old api-reference VFS views. Companion: simstudioai/mothership feat/enhance-search-agent Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Multi-agent review of the docs/ VFS change. Applied the behavior-preserving fixes plus two agent-facing bugs that made real pages unreadable. - docs read no longer hard-fails on oversized pages. Six+ live integration references exceed the inline cap (github.mdx is 354KB, sportmonks 513KB), so a plain read of them ALWAYS failed and cost a second fetch to recover. Truncate to the largest whole-line prefix that fits, keep the true totalLines, and tell the model how to page. An explicit offset/limit that still overflows is still an error — that one is a caller mistake. - classify docs fetch failures. Everything collapsed to null, so a permanent 404 was reported to the agent as "temporarily unavailable, retry shortly", inviting a retry loop on a page that will never exist. 4xx (except 429) is now permanent and says so; 5xx/429/network/timeout keep the retry wording. - register search_documentation as a transitional alias for search_docs. sim and mothership deploy independently and the rename deleted the old id on both sides, so BOTH deploy orders broke docs lookup for the window between them. Old params are a subset of the new. Remove once both ship. - extract the index-page fold (X/index.mdx <-> X.mdx) into docs-path.ts. It was re-derived in three places — the manifest generator, the source_document reverse mapping, and the search scope filter — which is the hand-synced-duplicate shape that has drifted in this repo before. - grepDocsPage now goes through grepReadResult, the primitive files/ and uploads/ grep already use, instead of calling grep directly. - couldMatchDocsScope delegates to isDocsPath; the bodies were identical. - drop the dead 'docs' member from AgentContextType. Tests: 404-vs-5xx-vs-429 classification, network failure, and a docs-path round-trip asserting one source candidate reproduces every manifest entry. Verified: tsc clean, 932 copilot tests, biome clean, docs-manifest:check, check:utils and check:api-validation:strict both pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The SQL LIMIT is applied before the similarity-threshold and liveness filters, so search_docs can return fewer hits than topK — or none, when every candidate was filtered. An empty array is indistinguishable from "the documentation does not cover this", which sends the agent off to guess instead of rephrasing or falling back to glob. searchDocs now returns the drop counts alongside the results, and the tool attaches a note when anything was dropped: how many candidates the index returned, why they went, and what to try next. Silent on the common path. This does not change which rows are returned or how many — the ordering issue behind the shortfall is a pre-existing bug the deleted search-documentation.ts had too, and pushing the threshold into SQL is its own change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

vercel · 2026-07-25T00:37:45Z

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jul 25, 2026 2:08am

cursor · 2026-07-25T00:37:49Z

PR Summary

Medium Risk
Copilot doc access now depends on live docs.sim.ai fetches and manifest/index alignment; search behavior changes for agents and during the search_documentation rename shim.

Overview
Adds a read-only docs/ copilot VFS backed by a CI-checked generated manifest (docs-manifest:check). Glob lists manifest paths (opt-in via docs/ patterns only); read and grep lazy-fetch page markdown from docs.sim.ai, with truncation, single-page grep limits, and user-facing DocsCorpusError handling wired into existing VFS tools.

search_docs replaces inline search_documentation: vector search over docs_embeddings with optional docs/ path scoping, similarity/stale filtering, topK clamping, and results that include the VFS path to read next. search_documentation stays registered as a hidden transitional alias for mixed deploys.

@docs chat context is disabled (no more server-side doc search injection). Smaller fixes: workspace resource mention IDs prefer non-empty id/path, and Zod validation failures on chat POST log at warn level.

^{Reviewed by Cursor Bugbot for commit 01c4d70. Bugbot is set up for automated code reviews on this repo. Configure here.}

github-actions · 2026-07-25T00:38:20Z

⚠️ Cross-repo companion check

One or more companion PRs aren't merged into staging yet. Merging this without them will leave copilot and sim out of sync — merge them in lockstep.

❌ simstudioai/mothership#371 — OPEN, not merged (targets staging) — feat(search): replace search_documentation with path-scoped search_docs

greptile-apps · 2026-07-25T00:45:46Z

Greptile Summary

The PR completes the documentation-tool migration and repairs the previously reported mixed-version dispatch path.

Retains search_documentation as a hidden, Sim-routed catalog alias backed by the search_docs server handler.
Adds coverage for catalog classification, server registration, legacy parameters, and hidden-tool behavior.
Introduces a manifest-backed read-only docs/ VFS with live page reads, single-page grep, and scoped semantic search.
Adds CI validation to keep the generated documentation manifest synchronized.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported transitional-alias dispatch failure is fully addressed, and no blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/copilot/tools/server/router.ts	Registers both tool identifiers against the new documentation-search handler, completing the previously missing dispatch path.
apps/sim/lib/copilot/tools/server/docs/search-docs-alias.test.ts	Verifies that the legacy identifier remains known, Sim-routed, registered, hidden, and compatible with legacy parameters.
apps/sim/lib/copilot/generated/tool-catalog-v1.ts	Adds the new tool and preserves the old identifier as a hidden transitional catalog entry.
apps/sim/lib/copilot/docs/docs-corpus.ts	Implements the manifest-backed documentation VFS namespace, live reads, globbing, and single-page grep.
apps/sim/lib/copilot/docs/docs-search.ts	Implements manifest-aware semantic documentation search with path scoping and stale-result filtering.

_{Reviews (4): Last reviewed commit: "fix(copilot): make the search_docs topK ..." | Re-trigger Greptile}

The registry alias added for the rename never fired: executeTool gates on isKnownTool(toolId) — membership in the generated TOOL_CATALOG — before it consults baseServerToolRegistry, so an id absent from the catalog is rejected as unknown and routed to the app-tool path instead. The alias was dead code, and worse, it advertised a mixed-version safety net that did not exist. The companion PR restores search_documentation to the contract as a hidden, deprecated entry, so the id now passes the catalog gate and reaches this alias. Marks it hidden in the UI set too — a call only ever arrives from an older Mothership build and renders as the search_docs it maps onto. Adds a test pinning every link in the dispatch chain (catalog membership, sim route, registered handler, hidden, param shape) — the assertion that would have caught this. Remove all of it once search_docs is live in prod on both sides.

j15z · 2026-07-25T00:55:12Z

Confirmed — you're right, and this was a real hole rather than a nit.

executeTool gates on isKnownTool(toolId) (i.e. toolId in TOOL_CATALOG) before it consults baseServerToolRegistry:

const canUseRegisteredHandler =
  isKnownTool(toolId) && (isSimExecuted(toolId) || ...)
if (!canUseRegisteredHandler) return executeAppTool(toolId, appParams)  // → tool not found

So dropping search_documentation from the generated catalog made the registry alias unreachable, and the mixed-version window it was meant to cover was still open — worse than having no alias, because the PR claimed a safety net that didn't exist.

Fixed across both repos:

mothership#371 (aa46b879): registers search_documentation as a hidden, deprecated catalog entry routed to sim. It's in no agent's AllowedTools, so nothing is ever offered it — it exists only so an inbound call from an older build resolves.
this PR (06f3a3756f): regenerated catalog now contains the id, so it passes the gate and reaches the alias. Also added to the UI hidden set, since such a call renders as the search_docs it maps onto.
Added search-docs-alias.test.ts pinning every link in the chain — catalog membership, sim route, registered handler, hidden flag, param shape. That's the assertion that would have caught this.

One thing your flowchart implies that I want to state explicitly: this only fixes the sim-first direction. New Mothership emitting search_docs at an old Sim can't be fixed from either side, so deploy order remains sim first, then mothership. Noted on both PRs.

940 copilot tests, tsc, and all 11 CI audits pass.

j15z · 2026-07-25T00:55:13Z

@greptile

j15z · 2026-07-25T00:55:14Z

@cursor review

…g search A directory scope matched only `<section>/%`, which covers an overview stored as `<section>/index.mdx` but not one stored as a sibling `<section>.mdx`. Fumadocs accepts both layouts and page scope already handles both via docsSourceCandidates, so a scoped section search could silently omit the overview chunks — and the doc comment claimed it did not. Every section in the tree currently uses the index.mdx layout, so nothing is broken today; this closes the gap before someone adds a sibling overview and gets quietly incomplete results.

j15z · 2026-07-25T01:02:48Z

@greptile

j15z · 2026-07-25T01:02:49Z

@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 e52205d. Configure here.}

The clamp guarded magnitude but not type: Math.min/Math.max propagate NaN, so a non-numeric topK reached the query as `.limit(NaN)`. The `?? DEFAULT` only caught undefined. Nothing enforced this but the generated Ajv schema, and searchDocs is also called directly, so it should not depend on that. Extract clampTopK, which falls back to the default for anything non-finite (NaN, Infinity, a string that slipped through) and clamps the rest to [1, 25]. The clamp was completely untested because the db mock's .limit() stub discarded its argument — the mock now records it. Covers default, cap, floor, truncation, and the non-finite fallback. Worth pinning: staging's search_documentation documented "max 10" and enforced nothing, so this bound is new behavior, not just a bigger number.

j15z · 2026-07-25T01:28:48Z

@greptile

Chips read "Searched docs" with no indication of what was searched. The query-aware title existed earlier on this branch and this commit's own predecessor dropped it: removing search_docs from the catalog deleted the display case and its test, and putting the tool back only restored the static map entry. The generic "every visible catalog tool has a title" assertion still passed, because it checks that a title exists, not that it is the useful one. Chips now read: Searching docs for "how to read workflow logs and view executions" -> Searched docs for "...". The gerund flip already preserves the suffix, so the completed state needs no extra handling — the test now pins that too, since it was the part most likely to regress silently.

j15z and others added 8 commits July 24, 2026 17:13

improvement(copilot): label docs corpus reads as Section/filename in …

f5538e9

…tool chips read("docs/documentation/workflows/index.mdx") now renders "Read Workflows/index" instead of the leaf-only fallback ("Read Index"). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

j15z requested a review from a team as a code owner July 25, 2026 00:37

github-actions Bot added the requires-mothership-merge Has a companion PR on the mothership/copilot side — merge in lockstep label Jul 25, 2026

greptile-apps Bot reviewed Jul 25, 2026

View reviewed changes

Comment thread apps/sim/lib/copilot/tools/server/router.ts

vercel Bot temporarily deployed to Preview July 25, 2026 00:55 Inactive

cursor Bot reviewed Jul 25, 2026

View reviewed changes

Comment thread apps/sim/lib/copilot/docs/docs-search.ts

vercel Bot temporarily deployed to Preview July 25, 2026 01:02 Inactive

cursor Bot reviewed Jul 25, 2026

View reviewed changes

vercel Bot temporarily deployed to Preview July 25, 2026 01:27 Inactive

j15z mentioned this pull request Jul 25, 2026

fix(copilot): stop the special-tag parser discarding text it cannot resolve #5952

Open

6 tasks

vercel Bot temporarily deployed to Preview July 25, 2026 02:08 Inactive

j15z mentioned this pull request Jul 25, 2026

test(copilot): catch a tool silently dropping its query from the chip #5953

Draft

6 tasks

Uh oh!

Conversation

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

Uh oh!

Summary

Type of Change

Testing

Checklist

Companion PRs

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

PR Summary

Uh oh!

github-actions Bot commented Jul 25, 2026

⚠️ Cross-repo companion check

Uh oh!

greptile-apps Bot commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

j15z commented Jul 25, 2026

Uh oh!

j15z commented Jul 25, 2026

Uh oh!

j15z commented Jul 25, 2026

Uh oh!

Uh oh!

j15z commented Jul 25, 2026

Uh oh!

j15z commented Jul 25, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

j15z commented Jul 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

j15z commented Jul 25, 2026 •

edited

Loading

vercel Bot commented Jul 25, 2026 •

edited

Loading

cursor Bot commented Jul 25, 2026 •

edited

Loading

greptile-apps Bot commented Jul 25, 2026 •

edited

Loading