Revise Registry Server authz docs and section IA#1050
Open
danbarr wants to merge 2 commits into
Open
Conversation
Document how registry, entry, and source claims interact, and the v1.5.0 publish source-claims gate that requires a caller's JWT to satisfy the managed source's claims. Correct the misleading publish framing in the worked example. Closes #1033. Restructure the section navigation to match real dependencies rather than a single linear chain: - Reorder the sidebar: database beside the deploy pages, skills beside publishing, the secure trio (authentication, authorization, audit logging) grouped, telemetry last. - Rewire every page's Next steps into an explicit forward path (publish/skills to authentication to authorization to audit logging to telemetry to API reference), moving off-path links to Related information and removing backward-to-setup edges. - Reframe database.mdx as operational reference instead of a deploy prerequisite, and give the manual deploy guide a Prerequisites section so all three deploy guides are structurally consistent. Includes editorial tightening across the section (action-first descriptions, Registry Server capitalization, and de-duplication). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the ToolHive Registry Server documentation to accurately explain how registry, entry, and source claim scopes interact (including the v1.5.0 managed-source publish gate), and restructures the Registry Server section navigation to match real-world usage dependencies and a forward “Next steps” path across pages.
Changes:
- Documented claim scopes and clarified managed-source publishing behavior (source-claims gate) across authorization and publishing-related guides.
- Reordered the Registry Server sidebar and rewired “Next steps”/“Related information” links to reflect a hub-and-spoke dependency graph with a clear forward path.
- Editorial tightening across the section (action-first descriptions, consistent “Registry Server” capitalization, reframed database page).
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars.ts | Reorders Registry Server sidebar items and updates section description capitalization. |
| docs/toolhive/guides-registry/telemetry-metrics.mdx | Updates description and simplifies “Next steps” to point forward to API reference. |
| docs/toolhive/guides-registry/skills.mdx | Updates descriptions/navigation and documents managed-source publish gating in the claims section. |
| docs/toolhive/guides-registry/publish-servers.mdx | Updates claims/publish wording to include managed-source claim gating and rewires navigation links. |
| docs/toolhive/guides-registry/intro.mdx | Tightens IA by focusing “Next steps” on quickstart/deployment/configuration. |
| docs/toolhive/guides-registry/index.mdx | Refines landing-page positioning and adds Cloud UI pointer in “Where to start”. |
| docs/toolhive/guides-registry/deployment.mdx | Removes backward “next” chain and keeps deployment overview focused on method selection. |
| docs/toolhive/guides-registry/deploy-operator.mdx | Makes deprecation more explicit in description and updates capitalization + next-step flow. |
| docs/toolhive/guides-registry/deploy-manual.mdx | Adds prerequisites for structural consistency and adjusts forward navigation + related links. |
| docs/toolhive/guides-registry/deploy-helm.mdx | Updates description to action-first phrasing. |
| docs/toolhive/guides-registry/database.mdx | Reframes as operational reference and updates “Next steps” accordingly. |
| docs/toolhive/guides-registry/configuration.mdx | Adds cross-reference to claim scopes and updates claim-gating wording for publishing. |
| docs/toolhive/guides-registry/authorization.mdx | Adds “Claim scopes” overview and documents managed-source publish gate semantics. |
| docs/toolhive/guides-registry/authentication.mdx | Tightens description/wording and adjusts navigation to match new forward path. |
| docs/toolhive/guides-registry/audit-logging.mdx | Moves prior backward links into “Related information” and keeps “Next steps” forward. |
The publish notes on the configuration, publish-servers, and skills pages listed the claim requirements but not the manageEntries role, so a reader satisfying the claim checks could still hit a 403. Add the role as an explicit prerequisite on each. Addresses Copilot review feedback on #1050. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents how the Registry Server's three claim scopes interact and brings the section's navigation in line with how the product is actually used.
Authorization (closes #1033). The authorization guide never stated the division of responsibility between registry, entry, and source claims, and its worked example implied source claims gate publishing when they didn't. That premise changed: stacklok/toolhive-registry-server#849 shipped in v1.5.0, so publishing into a managed source now requires the caller's JWT to satisfy the source's claims (visibility rule; an untagged managed source is publishable only by a super-admin). This adds a "Claim scopes" overview, documents the synced-inherits vs. managed-explicit split, documents the publish source-claims gate across the authorization, configuration, publish-servers, and skills pages, and corrects the misleading worked-example framing. The v1.5.0 docs PR (#1039) covered the visibility/subset split (#848) but missed this gate.
Information architecture. The section was wired as one linear chain, but the real dependency graph is hub-and-spoke, which produced contradictions (the nav ordered database after security even though it's a deploy prerequisite; terminal pages like audit logging pointed backward to authentication). This reorders the sidebar to match dependencies (database beside the deploy pages, skills beside publishing, the secure trio grouped, telemetry last) and rewires every page's Next steps into an explicit forward path: publish/skills → authentication → authorization → audit logging → telemetry → API reference. Off-path links (CLI skill install, Cloud UI) moved to Related information.
Supporting cleanup.
database.mdxis reframed as operational reference rather than a deploy prerequisite (deploy guides own the minimal connection settings); the manual deploy guide gains a Prerequisites section so all three deploy guides are structurally consistent; plus editorial tightening across the section (action-first descriptions, "Registry Server" capitalization, de-duplication).A follow-up will make the deploy guides fully self-contained (a complete bootstrap
values.yamlpresented before the install command, across all three guides + quickstart framing).Type of change
Related issues/PRs
Screenshots
N/A - sidebar reorder is visible in the Vercel preview.
Submitter checklist
Content and formatting
Navigation
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (no slugs changed; none needed)Reviewer checklist
Content