feat(api): improve install UX clarity and expose reachability policy

[khalidsaidi]

Summary

• add reachabilityPolicy to /rag/stats
• add claudeDesktopNote to /rag/install for clearer remote-vs-stdio guidance
• update /browse install UX to show primary transport badge and a collapsible Claude Desktop note
• extend tests for new /rag/stats and /rag/install fields

Changes

API (apps/api/src/app.ts)

• /rag/stats response now includes:
  • reachabilityPolicy (strict | loose)
• /rag/install response now includes:
  • claudeDesktopNote
• claudeDesktopNote behavior:
  • remote (streamable-http/sse): explains Connectors UI requirement caveat
  • stdio: notes config-file flow works

Browse UI (docs/hosting/api/browse/index.html)

• on install/config fetch, renders inline install info panel with:
  • primary transport badge (Remote (SSE) / Remote (Streamable HTTP) / Local (stdio))
  • primary remote URL (when present)
  • collapsible Claude Desktop note section when present
• keeps existing copy-config behavior

Tests (apps/api/tests/api.test.ts)

• /rag/stats test now asserts reachabilityPolicy
• /rag/install tests now assert claudeDesktopNote behavior for:
  • local stdio server
  • remote SSE server

Docs (docs/DEPLOYMENT.md)

• note that /rag/install emits claudeDesktopNote for UI guidance

Validation

• pnpm -r lint
• pnpm -r typecheck
• pnpm -r test

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 83b0d7b415

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid rendering install info by mutable list index

The install-info panel is keyed to the transient array index (install-info-${i}), and the async /rag/install callback renders using parseInt(b.dataset.idx, 10); if a user runs a new search before an earlier request returns, the old response can populate transport/URL/note details into a different card that now occupies the same index. This introduces incorrect per-server install guidance in the UI; use a stable key (for example server name) or verify the result set hasn’t changed before updating the panel.

Useful? React with 👍 / 👎.