Update for v1.0.1

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>

Author: rdimitrov

docs/toolhive/guides-registry/authorization.mdx

@@ -123,8 +123,15 @@ claims satisfy the resource's claims can access it.
 
 ### Source claims
 
-Claims on a source are **inherited by all entries** during sync. This means
-every MCP server or skill ingested from that source carries the source's claims.
+For synced sources (Git, API, File), claims on a source are **inherited by all
+entries** during sync. Every MCP server or skill ingested from that source
+carries the source's claims.
+
+For Kubernetes and managed sources, source claims control who can manage the
+source via the admin API but are **not** inherited by entries. Kubernetes
+entries get claims from the
+[`authz-claims` annotation](./configuration.mdx#per-entry-claims-via-annotation)
+on each CRD. Managed source entries get claims from the publish request payload.
 
 ```yaml title="config-source-claims.yaml"
 sources:
@@ -200,7 +207,15 @@ caller's claims must be a superset of the resource's claims. For example:
 | `{}` (no claims)                  | `{org: "acme"}`                   | Allowed |
 | `{org: "acme"}`                   | `{org: "contoso"}`                | Denied  |
 
-Resources with no claims are accessible to all authenticated callers.
+Registries and sources with no claims are accessible to all authenticated
+callers. However, **entries** with no claims behave differently: they are only
+visible in anonymous mode. When authorization is enabled, an authenticated
+caller's per-entry filter requires both sides to have claims for a match — so
+entries without claims are invisible. To make entries visible to authenticated
+callers, 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
 
@@ -257,6 +272,28 @@ bypassed. There are no JWT claims to validate, so all sources, registries, and
 entries are accessible without restriction. This is suitable for development and
 testing environments only.
 
+## Check your identity and permissions
+
+Use the `GET /v1/me` endpoint to verify your authenticated identity and resolved
+roles:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  https://registry.example.com/v1/me
+```
+
+```json title="Example response"
+{
+  "subject": "user@example.com",
+  "roles": ["manageSources", "manageEntries"]
+}
+```
+
+This is useful for debugging authorization issues — you can confirm which roles
+your JWT grants and whether the expected claims are present. The endpoint
+returns `401 Unauthorized` in anonymous mode since there is no identity to
+report.
+
 ## Complete example
 
 This example shows a multi-team setup with full RBAC and claims-based scoping:

docs/toolhive/guides-registry/configuration.mdx

@@ -82,6 +82,11 @@ You can create multiple registries from the same sources to serve different
 audiences. For example, a `public` registry with no claims and a `team-internal`
 registry with team-scoped claims — both backed by the same source data.
 
+Source names must be valid DNS subdomain labels: lowercase alphanumeric
+characters and hyphens, maximum 63 characters (for example, `toolhive`,
+`platform-tools`, `k8s-prod`). This is required because source names are used as
+Kubernetes lease name suffixes for leader election.
+
 ## Command-line flags
 
 | Flag          | Description                                 | Required | Default |
@@ -354,21 +359,18 @@ registry entries for deployed MCP servers in your cluster.
 
 :::note[Operator-managed source]
 
-When using the ToolHive operator, a single Kubernetes source named `default` is
-automatically created and managed. You cannot configure additional Kubernetes
-sources through the `MCPRegistry` CR or configuration file, as only one
-Kubernetes source instance is supported per Registry Server instance.
-
-The configuration example below is for reference when running the Registry
-Server standalone (without the operator).
+When using the ToolHive operator, a Kubernetes source named `default` is
+automatically created and managed. The configuration examples below are for
+reference when running the Registry Server standalone (without the operator).
 
 :::
 
-By default, the Registry server discovers resources in all namespaces
-(cluster-wide). You can restrict discovery to specific namespaces using the
-`THV_REGISTRY_WATCH_NAMESPACE` environment variable. See
-[Workload discovery](./deploy-manual.mdx#workload-discovery) for configuration
-details and RBAC requirements.
+You can configure multiple Kubernetes sources, each watching different
+namespaces. By default, a Kubernetes source discovers resources in all
+namespaces (cluster-wide). You can restrict discovery to specific namespaces
+using the `namespaces` field or the `THV_REGISTRY_WATCH_NAMESPACE` environment
+variable. See [Workload discovery](./deploy-manual.mdx#workload-discovery) for
+RBAC requirements.
 
 ```yaml title="config-kubernetes.yaml"
 sources:
@@ -383,35 +385,45 @@ registries:
 
 **Configuration options:**
 
-- `kubernetes` (required): Empty object or claim mapping configuration (see
-  below)
+- `kubernetes` (required): Empty object or namespace configuration (see below)
+- `kubernetes.namespaces` (optional): List of Kubernetes namespaces to watch. If
+  empty, falls back to the `THV_REGISTRY_WATCH_NAMESPACE` environment variable,
+  or all namespaces if neither is set
 - No sync policy required (Kubernetes sources query live deployments on-demand)
-- Only one Kubernetes source is supported per Registry Server instance
 
-#### Claim mapping
+#### Per-entry claims via annotation
 
-You can map Kubernetes labels or annotations to authorization claims using the
-`claimMapping` field. This allows entries discovered from Kubernetes workloads
-to inherit claims based on their metadata — for example, mapping a `team` label
-to a claim so that only members of that team can see the entry.
+You can set authorization claims on individual Kubernetes workloads using the
+`toolhive.stacklok.dev/authz-claims` JSON annotation. This controls which
+authenticated callers can see each entry.
 
-```yaml title="config-kubernetes-claims.yaml"
-sources:
-  - name: default
-    format: toolhive
-    kubernetes:
-      claimMapping:
-        'toolhive.stacklok.dev/team': 'team'
-
-registries:
-  - name: default
-    sources: ['default']
+```yaml title="mcp-server-with-claims.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: deploy-helper
+  annotations:
+    toolhive.stacklok.dev/registry-export: 'true'
+    toolhive.stacklok.dev/registry-url: 'https://mcp.example.com/deploy-helper'
+    toolhive.stacklok.dev/registry-description: 'Deployment assistant'
+    # highlight-next-line
+    toolhive.stacklok.dev/authz-claims: '{"org": "acme", "team": "platform"}'
+spec:
+  # ...
 ```
 
-In this example, a workload annotated with
-`toolhive.stacklok.dev/team: platform` would produce entries with
-`claims: {team: "platform"}`. See [Authorization](./authorization.mdx) for how
-claims control entry visibility.
+Entry claims come exclusively from the annotation — source-level claims are
+**not** inherited. Entries without the annotation have no claims, which means
+they are visible in anonymous mode but invisible when authorization is
+configured.
+
+If the annotation contains invalid JSON or unsupported claim value types
+(anything other than strings or arrays of strings), the entry is **skipped
+entirely** and a warning is logged. The entry will not sync until the annotation
+is fixed.
+
+See [Authorization](./authorization.mdx) for how claims control entry
+visibility.
 
 :::info[How does it work?]
 
@@ -454,6 +466,7 @@ spec:
 | `toolhive.stacklok.dev/registry-title`       | No       | Human-friendly display name for the registry entry (overrides the generated name) |
 | `toolhive.stacklok.dev/tools`                | No       | JSON array of tool name strings (e.g., `["get_weather","get_forecast"]`)          |
 | `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:**
 
@@ -492,8 +505,8 @@ The registry URL from the `registry-url` annotation becomes a key in the JSON
 structure.
 
 This feature requires the Registry server to be granted access to those
-resources via a Service Account, check the details in the
-[deployment section](./deploy-manual.mdx#workload-discovery).
+resources via a Service Account. See the
+[deployment section](./deploy-manual.mdx#workload-discovery) for details.
 
 :::
 

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

@@ -610,8 +610,7 @@ kubectl -n <NAMESPACE> describe mcpregistry <NAME>
 - [Configure sources and registries](./configuration.mdx) to set up additional
   data sources and filtering options
 - [Kubernetes source](./configuration.mdx#kubernetes-source) - the operator
-  automatically creates a single Kubernetes source named `default`; you cannot
-  configure additional Kubernetes sources
+  automatically creates a Kubernetes source named `default`
 
 ## Related information
 

docs/toolhive/guides-registry/index.mdx

@@ -2,7 +2,7 @@
 title: ToolHive Registry Server
 description:
   Deploy, configure, and secure the ToolHive Registry Server for MCP server and
-  skill discovery.
+  skill discovery
 ---
 
 import DocCardList from '@theme/DocCardList';

docs/toolhive/guides-registry/intro.mdx

@@ -80,20 +80,20 @@ flowchart LR
 - **Multi-tenant authorization**: Claims-based access control with role-based
   administration, enabling team-scoped registries and entry visibility
 - **Skills registry**: Publish and discover reusable
-  [skills](../concepts/skills.mdx) through the extensions API
+  [skills](../concepts/skills.mdx) via the extensions API and synced sources
 
 ## Registry sources
 
 The server supports five registry source types:
 
 1. **Managed Source** - A fully-managed MCP source
-   - Ideal for private repositories
+   - Ideal for hosting private MCP server catalogs
    - Automatically exposes entries following upstream MCP Registry format
    - Supports adding new MCP servers via `/publish` endpoint
 
 2. **Upstream Registry** - Sync from upstream MCP Registry APIs
    - Supports federation and aggregation scenarios
-   - Format conversion from upstream to ToolHive format
+   - Syncs both MCP servers and skills from upstream sources
    - Does not support publishing
 
 3. **Kubernetes Cluster** - Automatically creates registry entries for running
@@ -105,12 +105,12 @@ The server supports five registry source types:
 
 4. **Git Repository** - Clone and sync from Git repositories
    - Supports branch, tag, or commit pinning
-   - Ideal for version-controlled registries
+   - Syncs both MCP servers and skills (upstream format)
    - Does not support publishing
 
 5. **Local File** - Read from filesystem
    - Ideal for local development and testing
-   - Supports mounted volumes in containers
+   - Syncs both MCP servers and skills (upstream format)
    - Does not support publishing
 
 ## Next steps

docs/toolhive/guides-registry/skills.mdx

@@ -2,17 +2,21 @@
 title: Manage skills
 description:
   How to publish, list, retrieve, and delete skills using the ToolHive Registry
-  server extensions API.
+  server extensions API
 ---
 
 The Registry server provides an extensions API for managing
 [skills](../concepts/skills.mdx). This guide covers the full lifecycle:
 publishing, listing, retrieving, and deleting skills.
 
+Skills can come from two paths: **publishing** to a managed source via the API,
+or **syncing** from external sources (Git, API, File) that contain skills in the
+upstream registry format.
+
 ## Prerequisites
 
 - A running Registry server with at least one **managed** source configured
-  (skills can only be published to managed sources)
+  (required for publishing; synced sources provide skills automatically)
 - `curl` or another HTTP client
 - If authentication is enabled, a valid bearer token (see
   [Authentication](./authentication.mdx))