Make the connectors page task-based

[tgrunnagle]

Description

Rewrites docs/connector-gateway/connectors.mdx as a task-based how-to, per #1184. Stacked on #1205; retarget to main after it merges.

Label fixes

• The list section names the real columns (Name, Verification, Endpoint, Transport, Groups with access, Created), plus search and the Verification filter.
• The states table adds Verifying, so it matches the console's four values (Draft, Verifying, Verified, Broken).
• Grant access uses Add groups on the Access tab, with Grant access as the dialog's confirm button. Revoke uses Revoke access from the group's actions menu.
• Manual add ends with Add connector, the create dialog's submit label.

Several items in the issue's label table (Activate, Your workspace, Re-authenticate, the three-peer sources list) were already fixed by #1180, so they needed no change.

Structure

The page is now organized around tasks with numbered steps:

• Add a connector: one subsection per method, each stating what the method leaves behind. Import lists remote servers only and publishes with no authentication. Discovery creates drafts with a Setup required banner. Manual add publishes on create.
• Verify and publish a connector: the states table, Save and verify steps, and a Connect to in-cluster endpoints subsection (the former transport and private-network content, reshaped into the two settings an in-cluster endpoint needs).
• Set up authentication: a short summary that links to the authentication page, managed secrets, and identity providers.
• Grant and revoke access: default-deny, inheritance (linked to Users and groups), revoke, and the Cedar-mode read-only state.
• Review activity: the Activity tab's columns, outcome filter, period picker, and user filter. It's described as best-effort and not an audit log, with a link to audit log forwarding.
• Edit or delete a connector: delete is permanent and revokes every group's access.
• When changes take effect: access on the next request (the gateway denies if it can't reach the Enterprise Manager), connectors within about 30 seconds, and rotated credentials within credentialRefreshInterval (15 minutes by default).

The order differs slightly from the issue's list. Authentication comes before access, matching the prerequisite order on the authentication page and the fact that imported connectors arrive with no authentication.

Next steps now link to identity providers, managed secrets, and rolling out gateway clients. The description is rewritten. One inbound anchor in connector-authentication.mdx is updated to the new heading.

Verification

Console labels and behavior were checked in stacklok-enterprise-platform at e3da432, under enterprise/toolhive-cloud-ui/src/features/connectors-admin/:

• List columns: lib/columns.tsx
• Chooser: add-connector-dialog.tsx
• Import behavior (remote only, none auth, published on create, transport choice): import-connectors-dialog.tsx and actions.ts
• Discovery drafts and the Setup required banner: discover-connectors-dialog.tsx and configuration-tab.tsx
• Access, revoke, and Cedar warning: access-tab.tsx and add-group-dialog.tsx
• Delete text: delete-connector-dialog.tsx
• Activity tab: components/metering/connector-activity-table.tsx and lib/metering/activity-period.ts

The timing values come from the comments on refreshInterval and credentialRefreshInterval in enterprise/connector-gateway/helm/values.yaml. The deny-on-unreachable behavior comes from ErrPolicyDecisionUnavailable in internal/infra/directory/adapter.go.

npm run build passes, and Prettier and ESLint are clean.

Needs SME eyes

• The page says the Activity tab stays empty until tool call recording is on. I inferred this because the tab reads from the same metering API as Tool Usage; I didn't test it.

Type of change

• Documentation update

Related issues/PRs

Closes #1184. Part of #1175. Stacked on #1205.

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:33pm UTC

[danbarr]

Editorial review assessed against the final stack at #1208 (a9c7827). The task-based connector guide is a substantial improvement, particularly the distinction between registration methods, verification, and the two checks for in-cluster endpoints.

Please consolidate the access procedure with #1202. In docs/connector-gateway/connectors.mdx, Grant and revoke access repeats the group-grant steps, inheritance explanation, and Cedar-mode read-only behavior from connector-policies.mdx. This page also covers revocation, making it more operationally complete than the dedicated policy guide.

Make the policy guide the canonical home for the complete grant/revoke workflow. Keep a short access checkpoint and a descriptive link in connector management so readers can continue the registration workflow without maintaining two copies of the same instructions.

[tgrunnagle]

Restacked onto the updated #1202. Following review feedback on #1202, 8e4e9bc replaces this page's Grant and revoke access procedure with a short summary that links to the access page (connector-policies.mdx), which now owns those steps.

[github-actions]

Visual regression failed

Commit 751cbb3113a6 changed 1 visual snapshot across 1 screen.

Screen	Route	Viewport	Difference
nav page - Connector Gateway	/connector-gateway	Desktop	Light: 9,031 pixels (ratio 0.01)

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 d195984. 8e4e9bc had already cut Grant and revoke access down to a checkpoint and a link. This commit points the "A user can't see a connector" check at connector-policies.mdx and updates links for the moved pages.

[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.