Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/backend/src/lib/ai/tools/docs.ts`:
- Around line 32-36: The fetch to `${base}/api/internal/docs-tools` needs an
explicit timeout: wrap the request in an AbortController, pass controller.signal
into the fetch options used in the const res = await fetch(...) call in docs
tool function, start a setTimeout that calls controller.abort() after a
reasonable ms (e.g., 5s), and clear the timeout when fetch completes; catch the
abort error and throw or return a bounded tool-specific error (e.g.,
"DocsToolTimeoutError" or a descriptive error message) so the caller of the docs
tool (the AI tool path) can surface a bounded timeout response instead of
waiting for the underlying network/socket timeout.
- Around line 43-50: The function currently treats a 200 response with no usable
text as success; instead validate the parsed DocsToolHttpResult payload and fail
loudly: after parsing (the variable data) and computing text, if text is an
empty string (no text items found) then throw an Error (include context like the
raw data or a descriptive message) rather than returning "" or "Unknown docs
tool error"; keep the existing branch that returns when data.isError === true
but add this explicit validation/throw for missing text to surface contract
drift between the docs app and backend tools.

In `@docs/src/app/api/internal/`[transport]/route.ts:
- Around line 81-98: The capabilities object uses the camelCase key askStackAuth
which doesn't match the registered tool name ask_stack_auth and will cause
"Unknown tool" runtime errors; update the capabilities key from askStackAuth to
ask_stack_auth so it exactly matches the registered tool name (referencing the
registered tool identifier ask_stack_auth and the capabilities entry
askStackAuth in route.ts), ensuring the MCP adapter can invoke the tool.

In `@docs/src/app/api/search/route.ts`:
- Around line 12-24: The helper callDocsToolsSearch should not build a backend
target from the untrusted requestOrigin and swallow failures; instead invoke the
docs-tools operation directly (call the internal handler/function exported by
docs/src/app/api/internal/docs-tools/route.ts) or use a trusted server base URL
and include the STACK_INTERNAL_DOCS_TOOLS_SECRET in the request so auth failures
surface; remove the broad try-catch that returns [] on error and let errors
propagate (or throw a specific error) so failures are loud; apply the same fixes
to the other similar fetches around the result_limit lines referenced (79-82 and
107-109) and ensure the call includes the secret header when using an HTTP
request.
- Around line 116-119: The current comparator in sortedResults reorders results
solely by getPlatformPriority, which overrides upstream relevance from
callDocsToolsSearch; update the sort to preserve upstream relevance and only use
platform priority as a tie-breaker: when sorting filteredResults, first compare
the upstream relevance score (use the score/relevance property returned by
callDocsToolsSearch if present), if equal compare getPlatformPriority(a.url) vs
getPlatformPriority(b.url), and finally fall back to original index to ensure a
stable sort (e.g., attach the original index before sorting). Ensure you
reference filteredResults, sortedResults, callDocsToolsSearch, and
getPlatformPriority when making the change.

In `@docs/src/lib/docs-tools-operations.ts`:
- Around line 413-415: The handler for "search_docs" must sanitize and clamp
input.result_limit before it's used (and before any slice(0, result_limit)
calls) to avoid negative values like -1 turning into slice(0, -1); normalize to
an integer (e.g., parse/Number), enforce a minimum of 0, and apply a sensible
maximum cap (e.g., 100) before passing it into searchDocsImpl or using it in
array slicing; update the code around input.result_limit, the call to
searchDocsImpl, and any downstream slice() usage to use this
clampedPositiveLimit instead of the raw input.value.
- Around line 239-305: The search currently scans allPages and calls readFile
per page inside the loop (see variables allPages, readFile, and textContent)
causing a full disk read on each request; fix by extracting the file-reading and
normalization logic into a precomputed in-memory search index (e.g.,
buildSearchIndex or cachedPages map) that runs at startup or on content changes,
store normalized text, titles, descriptions and toc for each page, and update
the search routine to iterate that in-memory index instead of reading files;
ensure docs/src/app/api/search/route.ts uses the cached index and add
invalidation/update hooks when content changes.

---

Nitpick comments:
In `@docs/src/app/api/internal/`[transport]/route.ts:
- Around line 59-70: The code unsafely casts the fetch response to a specific
shape using "as { finalText?, content? }" when computing the "body" and "text"
variables in route.ts; replace this with runtime validation: after awaiting
res.json(), check res.ok and that the parsed value is an object, then validate
that body.finalText (if present) is a string or that body.content is an array
whose items have type === "text" and text is a string before using them to build
"text"; if validation fails, handle the error path (log or throw) and fall back
to "" (or a safe default). If your codebase uses a runtime schema validator
(e.g., zod), validate the response against a schema instead of the assertion;
update all uses of "body" and the "text" assembly accordingly.

In `@docs/src/app/mcp-browser/page.tsx`:
- Line 50: The current return uses an unsafe cast on response.json() which
bypasses type safety; replace the direct "return await response.json() as {
content: Array<{ type: string, text?: string }> }" with a defensive
parse/validation: call response.json(), verify response.ok, ensure the parsed
value has a "content" property that's an array, and that each item has a string
"type" and optional string "text"; if validation fails, throw a descriptive
error (or return a safe fallback). Consider extracting this into a small helper
(e.g., validateApiResponse or parseResponseFromApi) so callers use a typed,
validated object instead of the unsafe cast.

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@apps/backend/src/lib/ai/tools/docs.ts`:
- Around line 109-118: The PR defines duplicate tools — search and search_docs
(and fetch vs get_docs_by_id) — which overlap and can confuse tool selection;
consolidate by removing one alias or explicitly mark aliases as
backward-compatible. Update the tools registration in
apps/backend/src/lib/ai/tools/docs.ts: either merge search_docs into search (and
remove the duplicate tool) or keep one canonical implementation (e.g., search,
get_docs_by_id) and implement the other names as thin wrapper aliases that call
the canonical function (via postDocsToolAction) while adding clear descriptions
stating they are deprecated/backwards-compatible; also update the description
strings to mention the aliasing so AI models know these are identical.
- Around line 6-9: DocsToolHttpResult is too permissive and is being trusted via
a type assertion elsewhere; define a strict runtime schema (e.g., a Zod schema)
that mirrors DocsToolHttpResult (require content as array of objects with
required type and optional text, and explicit isError boolean) and validate
incoming HTTP responses against that schema instead of asserting the type;
update usages where the assertion occurs (the code that currently casts to
DocsToolHttpResult) to parse/validate with the schema, handle validation
failures (treat as error/isError) and then rely on the validated shape for
downstream logic.