Address PR review findings from Dan Barr

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rdimitrov

docs/toolhive/guides-registry/authorization.mdx

@@ -10,7 +10,9 @@ who can manage sources, registries, and entries. Authorization builds on top of
 [authentication](./authentication.mdx) — you need OAuth authentication enabled
 before configuring authorization.
 
-Claims operate at three layers, checked in order when a client reads entries:
+## How authorization works
+
+When a client accesses registry data, the server checks three layers in order:
 
 1. **Registry claims** (access gate) — can the caller access this registry at
    all? If the registry has claims and the caller's JWT doesn't satisfy them,
@@ -23,17 +25,6 @@ Claims operate at three layers, checked in order when a client reads entries:
    operation? Publishing, deleting, and managing sources/registries require
    specific [roles](#configure-roles).
 
-## How authorization works
-
-Authorization in the Registry server operates at two levels:
-
-1. **Role-based access control (RBAC)**: Determines which admin operations a
-   caller can perform (manage sources, manage registries, publish/delete
-   entries).
-2. **Claims-based scoping**: Limits visibility and access to specific sources,
-   registries, and entries based on key-value claims attached to both resources
-   and callers.
-
 When a caller makes an API request, the server:
 
 1. Extracts the caller's claims from their JWT token
@@ -221,16 +212,21 @@ caller's claims must be a superset of the resource's claims. For example:
 | `{org: "acme"}`                   | `{org: "contoso"}`                | Denied  |
 
 Registries and sources with no claims are accessible to all authenticated
-callers. However, **entries** with no claims behave differently: they are
-visible in anonymous mode and [auth-only mode](#auth-only-mode), but invisible
-when full authorization is enabled. With authorization, the per-entry filter
-requires both sides to have claims for a match — so entries without claims are
-filtered out. To make entries visible to authorized callers, attach claims to
-the source (for synced sources) or to individual entries (via the publish
+callers.
+
+:::warning[Entries without claims are invisible when authorization is enabled]
+
+Entries with no claims are visible in anonymous mode and
+[auth-only mode](#auth-only-mode), but **invisible** when full authorization is
+enabled. The per-entry filter requires both sides to have claims for a match —
+entries without claims are filtered out. To make entries visible, attach claims
+to the source (for synced sources) or to individual entries (via the publish
 payload or the
 [`authz-claims` annotation](./configuration.mdx#per-entry-claims-via-annotation)
 for Kubernetes sources).
 
+:::
+
 ## Claims on published entries
 
 When you publish an MCP server version or skill to a managed source, you can

docs/toolhive/guides-registry/configuration.mdx

@@ -429,16 +429,12 @@ is fixed.
 See [Authorization](./authorization.mdx) for how claims control entry
 visibility.
 
-:::info[How does it work?]
+#### Workload annotations
 
-Kubernetes workload discovery works by looking for annotations in a specific set
-of workloads. The types being watched are
+Kubernetes workload discovery watches for annotations on
 [`MCPServer`](../guides-k8s/run-mcp-k8s.mdx),
 [`MCPRemoteProxy`](../guides-k8s/remote-mcp-proxy.mdx), and
-[`VirtualMCPServer`](../guides-vmcp/configuration.mdx).
-
-The Registry server will receive events when a resource among those listed above
-is annotated with the following annotations:
+[`VirtualMCPServer`](../guides-vmcp/configuration.mdx) resources.
 
 ```yaml {7-16}
 apiVersion: toolhive.stacklok.dev/v1alpha1
@@ -472,7 +468,7 @@ spec:
 | `toolhive.stacklok.dev/tool-definitions`     | No       | JSON array of tool definitions with MCP tool metadata (name, description, schema) |
 | `toolhive.stacklok.dev/authz-claims`         | No       | JSON object of authorization claims for per-entry visibility control              |
 
-**Tool definitions format:**
+#### Tool definitions format
 
 The `tool-definitions` annotation accepts a JSON array containing tool metadata
 that follows the MCP specification. Each tool definition can include:
@@ -512,8 +508,6 @@ This feature requires the Registry server to be granted access to those
 resources via a Service Account. See the
 [deployment section](./deploy-manual.mdx#workload-discovery) for details.
 
-:::
-
 **Use cases:**
 
 - Discover MCP servers deployed via ToolHive Operator

docs/toolhive/guides-registry/deploy-operator.mdx

@@ -174,8 +174,8 @@ spec:
 :::tip
 
 You can use `branch`, `tag`, or `commit` to pin to a specific version. If
-multiple are specified, `commit` takes precedence over `tag`, which takes
-precedence over `branch`.
+multiple are specified, `commit` takes precedence over `branch`, which takes
+precedence over `tag`.
 
 :::
 

docs/toolhive/guides-registry/skills.mdx

@@ -21,13 +21,13 @@ upstream registry format.
 - If authentication is enabled, a valid bearer token (see
   [Authentication](./authentication.mdx))
 
-## API base path
+## API paths
 
-All skills endpoints use the following base path:
+Skills use two API path families:
 
-```text
-/{registryName}/v0.1/x/dev.toolhive/skills
-```
+- **Browse endpoints** (list, get, search) use the registry-scoped path:
+  `/{registryName}/v0.1/x/dev.toolhive/skills`
+- **Admin endpoints** (publish, delete) use the `/v1/entries` path
 
 Replace `{registryName}` with the `name` of the registry as defined in your
 [configuration file](./configuration.mdx) (for example, `my-registry` if your