Part 2: Update Registry Server docs for v1.0.0–v1.1.0

[rdimitrov]

Summary

Updates the Registry Server documentation to reflect the v1.0.0, v1.0.1, and v1.1.0 releases, which introduced a new configuration model, claims-based authorization, skills sync, an internal probe server, and auth-only mode.

Configuration model (v1.0.0)

• Rewrite configuration.mdx for the new two-level config model: sources (data origins with sync/filter/claims) + registries (named API surfaces referencing sources)
• Update all YAML examples across deploy-manual.mdx and related pages
• Add DNS subdomain naming requirement for source names
• Rename "Server filtering" to "Entry filtering" — filters now apply to both servers and skills

Authorization (v1.0.0)

• New authorization.mdx page covering RBAC roles (superAdmin, manageSources, manageRegistries, manageEntries), claims-based access control, claim containment logic, publish claim validation, admin API scoping, and a complete multi-tenant example
• Document GET /v1/sources/{name}/entries and GET /v1/registries/{name}/entries admin endpoints
• Add authz cross-references from authentication, configuration, deployment, intro, skills, and index pages
• Add to sidebar between authentication and database

Per-entry Kubernetes claims (v1.0.1)

• Replace removed claimMapping config with toolhive.stacklok.dev/authz-claims annotation documentation
• Add authz-claims to the Kubernetes annotation table
• Document that annotation claims replace (not merge with) source claims, and entries without the annotation have no claims
• Document multiple Kubernetes sources support

Skills (v1.0.0–v1.0.1)

• Document that skills now sync from upstream-format Git, API, and File sources (not only managed sources)
• Add missing status query parameter to skills listing endpoint
• Add thv_reg_srv_skills_total Prometheus metric to telemetry docs
• Update intro, skills, and configuration pages

Internal probe server (v1.1.0)

• Document new --internal-address CLI flag (default :8081) in configuration
• Update deploy-manual.mdx Kubernetes manifest: probes now target port 8081
• Update authentication.mdx public paths: /health, /readiness, /version moved to internal server
• Update telemetry-metrics.mdx excluded endpoints section

Auth-only mode (v1.1.0)

• New section in authorization.mdx documenting auth-only mode (OAuth enabled, auth.authz omitted): all authenticated callers see all entries, startup warning logged

Other

• Document GET /v1/me endpoint in authorization page
• Fix roles vs role claim key mismatch in authorization example
• Fix missing article in intro.mdx
• Fix broken #kubernetes-registry anchor in remote-mcp-proxy.mdx
• Fix terminology: "registry views" → "registries", "managed registry" → "managed source"
• Fix front matter descriptions and heading capitalization
• Update stale Registry Server description in contributing.mdx

Changed files

File	Change
guides-registry/authorization.mdx	New — RBAC, claims, auth-only mode, admin entry endpoints, /v1/me
guides-registry/configuration.mdx	Rewrite for sources/registries, claims, K8s annotations, --internal-address flag, entry filtering
guides-registry/authentication.mdx	Add authorization callout, update public paths for internal server
guides-registry/intro.mdx	Add authorization feature, skills sync, fix grammar
guides-registry/skills.mdx	Add claims section, status query param, skills sync from external sources
guides-registry/deploy-operator.mdx	Fix terminology, heading, Next steps
guides-registry/deploy-manual.mdx	Update probes to port 8081, add internal-http port
guides-registry/telemetry-metrics.mdx	Add skills_total metric, update excluded endpoints for internal server
guides-registry/deployment.mdx	Add authorization link
guides-registry/index.mdx	Add authorization link, fix description
sidebars.ts	Add authorization page entry
guides-k8s/remote-mcp-proxy.mdx	Fix broken anchor link
contributing.mdx	Update stale Registry Server description

Test plan

• Prettier formatting passes on all changed files
• ESLint passes on all changed MDX files
• Multiple rounds of docs-review skill with all issues addressed
• All factual claims verified against source code at v1.0.1 and v1.1.0 tags
• PR review comments addressed (2 valid fixes, 2 rejected with source code evidence)
• Verify site builds successfully (blocked by missing thv CLI in local env — CI will validate)

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 13, 2026 7:53pm

[Copilot]

Pull request overview

Adds initial documentation for Registry Server authorization and updates the Registry Server guide set to reflect the new “sources + registries” configuration model.

Changes:

• Introduces a new Registry Server Authorization guide (RBAC + claims-based scoping).
• Updates existing Registry Server docs to use sources/registries terminology and configuration examples.
• Wires the new authorization page into navigation and cross-links it from related guides.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sidebars.ts	Adds the new authorization doc to the Registry Server sidebar section.
docs/toolhive/guides-registry/skills.mdx	Updates prerequisites/403 semantics and documents claims on skill publishing.
docs/toolhive/guides-registry/intro.mdx	Refreshes intro terminology (“managed source”) and adds authorization as a feature.
docs/toolhive/guides-registry/index.mdx	Updates landing page description and adds link to Authorization.
docs/toolhive/guides-registry/deployment.mdx	Updates “next steps” to include authorization and new terminology.
docs/toolhive/guides-registry/deploy-operator.mdx	Reworks wording around configuring sources and updates next-step links (incl. authz).
docs/toolhive/guides-registry/deploy-manual.mdx	Updates the sample config to the new sources + registries structure.
docs/toolhive/guides-registry/configuration.mdx	Major rewrite to document sources vs. registries, claims, and new examples.
docs/toolhive/guides-registry/authorization.mdx	New page describing RBAC + claims model, configuration, and examples.
docs/toolhive/guides-registry/authentication.mdx	Adds a callout and next-step link pointing readers to Authorization.

[danbarr]

Summary

Strong, well-structured update — the new authorization.mdx page is clear and thorough, the configuration rewrite is accurate, and cross-linking across the section is solid. One factual contradiction needs resolving before merge; the rest are polish.

Primary issues

1. Git version precedence contradiction

configuration.mdx and deploy-operator.mdx give conflicting precedence orders for branch/tag/commit when multiple are specified.

• configuration.mdx (Git repository source tip): commit > branch > tag
• deploy-operator.mdx (Git source tip): commit > tag > branch

These should be verified against the source code and made consistent. One of them is wrong.

Secondary issues

#	Location	Issue	Recommendation
1	authorization.mdx, intro + "How authorization works"	The opening 3-layer claims description and the "How authorization works" section cover the same ground from slightly different angles (one uses 3 layers, one uses 2 levels). Readers hit duplicate framing before reaching the flowchart.	Collapse them: keep the flowchart and a single concise framing. The numbered list in the intro can be cut if "How authorization works" + the Mermaid diagram covers it.
2	authorization.mdx, "Claim containment" section (bottom paragraph)	The behavior "entries with no claims are invisible to authenticated callers" is a counterintuitive gotcha — readers setting up Kubernetes or managed sources will naturally assume "no claims = public." It's buried in the final paragraph of a section about the containment algorithm.	Promote to a :::warning callout so it stands out. Something like: "Entries with no claims are not accessible to authenticated callers — only anonymous mode can see them. Attach claims to entries (via annotation or publish payload) to make them visible."
3	configuration.mdx, Kubernetes source :::info[How does it work?] admonition	This admonition contains a full YAML example, a 9-row annotations reference table, a JSON response structure, and prose explanation. Per the project's style guide, admonitions that contain the only documentation for a concept should be promoted to a proper section with a heading and ToC entry.	Promote to a ## Kubernetes annotations reference section (or similar) so it's discoverable in the ToC. The "how it works" prose can stay as a brief note or be folded into the section intro.
4	skills.mdx, "API base path" section	The section states all skills endpoints use /{registryName}/v0.1/x/dev.toolhive/skills, but the publish example uses POST /v1/entries and the delete example uses DELETE /v1/entries/skill/... — neither matches the stated base path. Pre-existing, but surfaces on any reading.	Clarify that publish/delete use the /v1/entries admin endpoint, not the skills browse path, or correct the base path description to reflect that it applies only to GET operations.

[danbarr]

Follow-up on front matter descriptions: Two pages have description fields that start with "How to," which is a filler opener per the style guide.

• authorization.mdx (new page): "How to configure role-based access control and claims-based authorization for the Registry Server"
• configuration.mdx (rewritten): "How to configure the ToolHive Registry Server with sources, registries, and sync policies"

Suggested fixes:

• authorization.mdx: "Configure role-based access control and claims-based authorization for the Registry Server"
• configuration.mdx: "Configure the ToolHive Registry Server with sources, registries, and sync policies"

[danbarr]

Two items still outstanding from the earlier review:

1. Git version precedence contradiction (primary)

The two pages still give different precedence orders for branch/tag/commit:

• configuration.mdx: commit > branch > tag
• deploy-operator.mdx: commit > tag > branch

One of these is wrong. Please verify against the source code and align them.

2. Oversized admonition in configuration.mdx

The :::info[How does it work?] block under the Kubernetes source section contains a full YAML example, a 9-row annotations reference table, and a JSON response structure. This is primary reference documentation, not a tip — it's invisible to the page ToC and easy to miss. It should be a proper ## section (e.g., "Kubernetes annotations reference") so it's discoverable in navigation.