[Gap]: UI guides gap analysis

[danbarr]

Summary

A systematic comparison of the UI guides (docs/toolhive/guides-ui/) against the current ToolHive Studio desktop app at its last released version (v0.30.0, shipped 2026-04-20). Unlike the CLI (#654) and operator (#655) analyses, the UI has no auto-generated reference to diff against — the ground truth is the app source (routes, feature modules, forms, IPC handlers, deep-link intents, settings screens). Every gap below has been verified by reading the code at v0.30.0 and cross-checking the docs at HEAD.

Related issues and PRs

• [Gap]: CLI guides gap analysis #654 — Companion CLI guides gap analysis
• [Gap]: Kubernetes Operator guides gap analysis #655 — Companion Kubernetes Operator guides gap analysis
• Add agent skills management documentation #656 — Added CLI guides-cli/skills-management.mdx; no UI equivalent exists yet
• Deprecate MCP Optimizer in UI, remove UI tabs from tutorial #717 — Deprecated MCP Optimizer in UI, removed UI tabs from tutorial
• [Bug]: Update UI docs to reflect new location of Secrets #626 — Existing issue to document Secrets relocation
• refactor: toolhive-ui img after rebranding #563 — Draft PR (open since 2026-02-18) to refresh UI screenshots post-rebrand. Refreshed 6 of 8 guides-ui/ images but stalled before guides-mcp/ images, and has not been re-refreshed against UI changes since. Any visual-drift items below should be reconciled with this PR rather than starting a new refresh

---

High-priority gaps

Entire features, screens, or flows with no coverage in UI guides.

1. Secrets moved into Settings (see #626)

secrets-management.mdx is still written as if Secrets is a top-level navigation page ("the Secrets page", line 15 and line 43). At v0.30.0 it is a tab inside the Settings screen (/settings?tab=secrets) — alongside General, Registry, CLI, Version, and Logs. Every entry-point reference in the guide needs to be updated.

2. Update-available / upgrade flow for local MCP servers

When a server's registry entry has a newer image than the installed version, the server card renders a visible amber up-arrow button (ArrowUpCircle) next to the start/stop toggle, with tooltip Update available: {localTag} → {registryTag}, plus an Update to {tag} entry in the kebab menu. Source: renderer/src/features/mcp-servers/components/card-mcp-server/index.tsx:29-72 and .../server-actions/items/update-version-menu-item.tsx. Zero mention in any guide. Belongs in run-mcp-servers.mdx under "Manage MCP servers."

3. Bearer token auth for remote MCP servers

The remote-MCP auth dropdown exposes four options: Auto-Discovered, Bearer Token, OIDC, OAuth2 (AUTH_FIELD_MATRIX in renderer/src/features/mcp-servers/components/remote-mcp/form-fields-auth.tsx). run-mcp-servers.mdx lines 137-180 document only Auto-Discovered, OAuth2, OIDC. Bearer Token is absent. Companion to #456.

4. Settings — Version tab / auto-update UX

The Settings page at v0.30.0 has six tabs: General, Registry, Secrets, CLI, Version, Logs (renderer/src/common/components/settings/tabs/settings-tabs.tsx). The Version tab has an auto-update toggle, current/latest version badges with a "Latest" indicator, a manual-update button, an update-state indicator (checking/downloading), and a blue-dot ArrowUpCircle badge on the tab trigger when a new version is available. install.mdx says only "view version information" (line 114-115); none of the auto-update UX is documented.

5. Settings — Registry tab, Registry Server API type

registry.mdx lines 100-114 describes three registry source options (Default / Remote URL / Local File Path) and, in a tip at line 119-126, suggests pointing the "Remote Registry (URL)" option at a self-hosted Registry Server. At v0.30.0 the dropdown exposes four options (REGISTRY_TYPE_OPTIONS in renderer/src/common/components/settings/registry/utils.ts):

1. Default Registry
2. Remote Registry (JSON URL)
3. Local Registry (JSON File Path)
4. Registry Server API — intended specifically for the ToolHive Registry Server

Selecting "Registry Server API" reveals OIDC fields (client_id, issuer_url) and an allow_private_ip checkbox that are not exposed on any other type. The guide's tip telling users to use "Remote Registry (URL)" for the Registry Server steers users away from the purpose-built option.

6. Deep links

The app ships a toolhive-gui://v1/... URL scheme (common/deep-links.ts) with two user-facing intents:

• open-registry-server-detail?serverName=<id> → /registry/{name}
• open-registry-server-install?serverName=<id> → /registry/{name}?install=true

Zero documentation in any UI guide. Users integrating ToolHive with browsers or automation have no way to discover these.

7. Skills management UI (experimental)

The Skills experience at v0.30.0 — /skills (tabs: registry, installed, builds), skill detail (/skills/$namespace/$skillName), build detail (/skills/builds/$tag), plus Install / Build / Uninstall / Delete-build dialogs — is currently gated behind the SKILLS feature flag in top-nav (renderer/src/common/components/layout/top-nav/index.tsx:71), so it's only visible to users who enable it in Settings → General → Experimental Features. The CLI got guides-cli/skills-management.mdx via #656 but there is no UI equivalent.

Recommend treating this the same way mcp-optimizer.mdx handled its experimental status: either add a flagged guide now (with a clear "experimental, opt in via Settings" banner) or defer until the flag flips on by default.

8. Remote MCP — Proxy Mode and Proxy Port fields

The local-MCP and remote-MCP forms both render Proxy mode (sse / streamable-http dropdown — visible only for stdio transport with non–Bearer-Token auth) and Proxy port (number input, with tooltip "Port for the HTTP proxy to listen on. If not specified, ToolHive will automatically assign a random port"). Source: renderer/src/common/components/workloads/form-fields-proxy.tsx. Neither is mentioned in run-mcp-servers.mdx, which documents target port (line 269-273) but not proxy port — these are different concepts.

---

Medium-priority gaps

Missing fields or flows inside existing guides.

customize-tools.mdx

• Registry drift detection for tools. When a registry-sourced server's tool set has changed upstream (tools added or removed), the customize-tools page renders a DriftDetails component that surfaces the diff. Source: renderer/src/features/mcp-servers/sub-pages/customize-tools/page.tsx:293 and renderer/src/features/mcp-servers/components/drift-details.tsx. Not documented.

playground.mdx

• Thread management. The sidebar supports creating, renaming, deleting, and starring/unstarring threads (renderer/src/features/chat/components/playground-sidebar.tsx, thread-title-bar.tsx). None of this is mentioned; the guide describes only "begin chatting."
• Attachments. The prompt input supports file attachments via PromptInputActionAddAttachments / PromptInputAttachments, with an AttachmentPreview component. Not documented.
• Cancel streaming. The chat input exposes onStopGeneration to abort an in-flight response. Not documented.
• Provider list currency. Guide names OpenAI, Anthropic, Google, xAI, Ollama, LM Studio, OpenRouter — verify against renderer/src/features/chat/components/provider-icons.tsx before each release.

install.mdx

• Settings screen structure. Lines 99-115 describe the Settings screen as a flat list of four options plus "version information and download the application log file." The actual UI has six tabs (General, Registry, Secrets, CLI, Version, Logs). Rewrite to acknowledge the tabbed layout and link each tab to the relevant topic guide (Registry → registry.mdx, Secrets → secrets-management.mdx, CLI → cli-access.mdx, Version → see high-priority Bump aquasecurity/trivy-action from 0.30.0 to 0.31.0 #4, Logs → current log-download content).
• Tray menu items. Lines 93-97 list Start-on-login, Show/Hide, Quit. The v0.30.0 tray (main/src/system-tray.ts:136-192) also includes a running-state indicator (🟢), the current version, and Check for Updates... — three items missing from the guide.

secrets-management.mdx

• 1Password note placement. The 1Password note (lines 18-25) is accurate; leave it in. But it sits above the "Enter secrets during MCP installation" section while the preceding paragraph (line 15) points readers to the non-existent top-level Secrets page. Fix the location reference before readers hit the 1Password note.

---

Inaccuracies in existing docs

#	Issue	Location	Details
1	Secrets described as top-level page	secrets-management.mdx lines 15, 43	Secrets is a Settings tab at v0.30.0 (see high-priority #1)
2	Registry settings lists three options	registry.mdx lines 100-114	App exposes four: Default, Remote URL, Local File Path, Registry Server API (see high-priority #5)
3	Registry Server guidance points to wrong option	registry.mdx lines 119-126	Tip tells users to use "Remote Registry (URL)" for the Registry Server; the purpose-built option is "Registry Server API"
4	Remote MCP auth lists three options	run-mcp-servers.mdx lines 137-180	App exposes four; Bearer Token missing (see high-priority #3)

---

Deprecated features still in guides

Guide	Status	Action
mcp-optimizer.mdx	Deprecated, removal April 22, 2026 per the doc's own banner; UI tabs already removed in #717	Plan guide deletion for the scheduled removal date

---

Methodology

This analysis compared three sources:

1. UI guides in docs/toolhive/guides-ui/ (13 files at HEAD on 2026-04-21)
2. ToolHive Studio application source at tag v0.30.0 (SHA c9e85c53) — routes (renderer/src/routes/), feature modules (renderer/src/features/), settings screens (renderer/src/common/components/settings/), main-process IPC (main/), deep-link intents (common/deep-links.ts), system tray (main/src/system-tray.ts)
3. Form schemas — registry form (registry/schema.ts, utils.ts), remote-MCP auth matrix (form-fields-auth.tsx), proxy fields (form-fields-proxy.tsx), deep-link Zod schemas (common/deep-links.ts)

Out of scope: tutorials (tutorials/), concepts (concepts/), CLI guides (covered by #654), K8s operator guides (covered by #655), registry-server guides (covered separately by its own section).

Feature-flag-gated surfaces are noted inline — Skills is currently behind the SKILLS experimental flag.