Replace "Your workspace" with console navigation

[tgrunnagle]

Description

Replaces references to Your workspace, which isn't a console label, with the console's actual navigation, per #1186. Stacked on #1207; retarget to main after it merges.

Some items in the issue were already handled by earlier PRs: connectors.mdx and enterprise-console/index.mdx no longer mention Your workspace, and manage-connections.mdx (#1179) already uses the Connected, Paused, and Reconnect required statuses and the Connect, Reconnect, Pause/Resume, and Disconnect actions. This PR covers the rest:

• roll-out-gateway-clients.mdx: replaces "Setup in each gateway area of Your workspace" with the path to each gateway's Clients tab. Adds a Connector Gateway section covering Ask your AI assistant, Manual setup (Streamable HTTP, OAuth with dynamic client registration), and the setup guides (Claude Code, Claude web and desktop, Codex, Cursor, VS Code, Other clients). It notes that Claude on the web and desktop needs a publicly reachable gateway. A short AI Gateway section covers that tab's Model gateway URL, Get an API key, and setup guides.
• virtual-api-keys.mdx and enterprise-directory/index.mdx: point to the API Keys tab under AI Gateway in the User experience.
• quickstart.mdx and manage-connections.mdx: capitalize "User experience" to match the label and the existing "Administration experience".
• STYLE-GUIDE.md and AGENTS.md: word-list guidance for the Administration and User experiences.

Verification

Checked in stacklok-enterprise-platform at 790e45643, under enterprise/toolhive-cloud-ui/src/:

• User nav (Home, then Connectors and AI Gateway under Gateways): components/console/user-nav.ts
• Tab labels (Connectors: Tools, Usage, Clients; AI Gateway: Budgets, Models, API Keys, Clients): components/console/nav-visibility.ts
• Connectors Clients tab content: features/connector-gateway/components/setup-page.tsx, features/connector-gateway/lib/client-setup-guides.ts
• AI Gateway Clients tab content: features/gateway-setup/components/gateway-setup-page.tsx

npm run build passes, and Prettier and ESLint are clean. The build's one SSG warning is on the existing API reference page.

Type of change

• Documentation update

Related issues/PRs

Closes #1186. Part of #1175. Stacked on #1207.

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

Navigation

• New pages include a frontmatter section with title and description at a minimum
• Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files (no changes needed)
• Redirects added to vercel.json for moved, renamed, or deleted pages (no URLs changed)

Reviewer checklist

Content

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
docs-website	Ready	Preview	Oct 6, 2026 3:46pm UTC

[danbarr]

Overall editorial and information-architecture assessment of the seven-PR stack at a9c7827.

The stack substantially improves the Connector Gateway documentation: it corrects product claims and console labels, adds a concrete quickstart, makes connector management task-based, and separates usage recording, telemetry, and audit logs. The remaining work is to make the assembled documentation a coherent set of reader journeys and address the page-level findings linked below.

Organize around administrator and owner tasks

The audience for these docs is administrators, platform owners, and people supporting their organization's internal users. Routine end-user workflows should be understandable in the app, with contextual in-app help and organization-specific guidance supplementing that experience. Internal users should not need to navigate the full administrator docs site to connect a client or manage their connections.

Document user behavior here when an administrator needs to understand, roll out, or troubleshoot it. Reframe Your connections as support guidance covering connection states, tool choices, reconnection, and administrator checks. Keep client-specific setup instructions in the app; the rollout guide should help owners prepare access, distribute the console URL, and support users. The quickstart can retain its administrator-as-user test to verify the complete flow.

I recommend organizing the canonical pages along these lines:

• Get started: Introduction and an administrator validation Quickstart.
• Configure and secure: Connectors, Managed secrets, Identity providers, Authentication, and Policies.
• Roll out and support: Rollout preparation and guidance for supporting users' connector access.
• Operate: Tool usage, Telemetry, and Audit logs.

Expose these administrator/owner starting routes early in the introduction. This replaces the earlier recommendation for a separate end-user "Use the gateway" journey.

The Managed secrets and Identity providers sidebar entries currently replace the Connector Gateway sidebar with Platform navigation. I reproduced this in the preview. These pages principally describe connector credentials, and the console also groups them under Connectors. Place their canonical guides in this product section, update Platform cross-links and redirects, and retain corporate platform sign-in configuration under Platform. Avoid creating duplicate guides to populate both sections. The specific sidebar finding is on #1205; this is the corresponding ownership decision for the assembled result.

Findings on the owning PRs

• #1201 review: earlier editorial assessment stands; API spec match verified; no additional editorial finding specific to this PR.
• #1202 review: distinguish console-supported authentication from API-only types and make policy management actionable.
• #1204 review: reframe connection guidance for administrators supporting internal users and remove the quickstart's assumption that DeepWiki becomes the busiest connector.
• #1205 review: fix sidebar context switches, route readers earlier, and qualify the structured/Cedar group-model statement.
• #1206 review: consolidate grant/revoke instructions in the dedicated policy guide, coordinating with #1202.
• #1207 review: qualify top-100 totals and shares, and remove the inference that an absent connector has zero usage.

Please resolve those findings on their owning PRs and reassess the combined navigation after the fixes propagate through the stack.

Validation boundaries

This assessment includes the final Connector Gateway pages, the cumulative diff, related Platform content, preview navigation, and targeted upstream source checks. It does not establish live validation of the quickstart, Helm deployment, or log-shipping examples.

At the reviewed head, lint/format checks and Vercel deployment pass, but the visual regression run fails on the Connector Gateway navigation snapshot. Review and settle the final navigation before refreshing that baseline.

[danbarr]

Blocking on the capitalization guidance added to AGENTS.md and STYLE-GUIDE.md. "Administration experience" and "User experience" are generic descriptions, so running prose should use lowercase under our existing capitalization rules. Preserve exact capitalization and bold formatting when referring to the selectable UI labels Administration, User, and Experience. Inline suggestions update both guidance entries; please also lowercase the running-prose occurrences introduced by this PR. The other editorial and organizational findings remain in the earlier comment reviews.

[danbarr]

Adding the corresponding prose suggestions for the capitalization issue in my request-changes review. These five changes keep generic experience descriptions lowercase while preserving exact, bolded UI labels in selection instructions.

[github-actions]

Visual regression failed

Commit 1f956aa8715d changed 1 visual snapshot across 1 screen.

Screen	Route	Viewport	Difference
nav page - Connector Gateway	/connector-gateway	Desktop	Light: 15,630 pixels (ratio 0.02)

Open the failed visual job · Download the full Playwright report

If the change is intentional, a repository collaborator can comment /update-snapshots to regenerate the baselines.

[tgrunnagle]

Addressed in 8f2998b, with the page-level findings fixed on their owning PRs (links in each PR's reply). The rollout guide now covers preparing access, network reachability, pointing users to the console, and supporting them; client-specific setup stays in the console. The Connector Gateway sidebar is grouped into Configure and secure, Roll out and support, and Operate. The rollout guide stays under Platform because it covers both gateways, and the intro links to it. I haven't refreshed the visual baseline, so it can be refreshed once the navigation is settled.

[danbarr]

/update-snapshots

[github-actions]

📸 Regenerated visual baselines per your /update-snapshots request and pushed a new commit.

[danbarr]

Approved from an editorial and information-architecture perspective. The findings from the stack review are addressed in the assembled result: administrator/owner audience, coherent navigation and credential-guide ownership, canonical access instructions, explicit API-only authentication, qualified usage reporting, and lowercase experience descriptions in prose. This approval does not assert live end-to-end validation of the deployment or examples.