Docs: update documentation and samples for VAP enforcement

Remove manual kagenti.io/type labeling from docs, samples, and
comments. All examples now use AgentRuntime CRs, matching the
ValidatingAdmissionPolicy that prevents direct label application.
Fix auto-created AgentCard naming to use the {name}-{kind}-card
pattern produced by AgentCardSync.

Signed-off-by: Daniels Nagornuks <dnagornu@redhat.com>

Author: rh-dnagornuks

kagenti-operator/GETTING_STARTED.md

@@ -40,10 +40,14 @@ This scenario demonstrates the complete lifecycle of an AI agent deployment on t
 ## Overview
 
 ### Kagenti Operator
-The Kagenti Operator discovers, indexes, and secures AI agents deployed in Kubernetes. There are two ways to enroll workloads:
+The Kagenti Operator discovers, indexes, and secures AI agents deployed in Kubernetes. Enroll workloads by creating an `AgentRuntime` CR:
 
-1. **AgentRuntime CR (Recommended)** — Create a Deployment with a `protocol.kagenti.io/a2a` label and an `AgentRuntime` CR pointing to it. The controller applies `kagenti.io/type` labels and triggers sidecar injection automatically. The protocol label enables automatic AgentCard creation for agent discovery.
-2. **Manual labels** — Add the `kagenti.io/type: agent` label directly to your Deployment or StatefulSet. This is simpler for quick tests but does not provide identity or observability configuration.
+1. Create a Deployment with a `protocol.kagenti.io/a2a` label
+2. Create an `AgentRuntime` CR pointing to it
+3. The controller applies `kagenti.io/type` labels and triggers sidecar injection automatically
+4. The protocol label enables automatic AgentCard creation for agent discovery
+
+A `ValidatingAdmissionPolicy` prevents the `kagenti.io/type` label from being set directly on Deployments or StatefulSets — it can only be applied by the operator via an AgentRuntime CR.
 
 > **Note:** The `Agent` Custom Resource is deprecated and will be removed in a future release.
 
@@ -180,86 +184,6 @@ kubectl delete agentruntime weather-agent-runtime -n team1
 
 ---
 
-## Deploy an Agent with Manual Labels (Alternative)
-
-Deploy an agent as a standard Kubernetes Deployment with the required `kagenti.io/type: agent` label. The operator will automatically discover the workload and create an AgentCard for it. This approach does not provide AgentRuntime's identity or observability configuration.
-
-### Quick Example Deployment
-
-```yaml
-kubectl apply -f - <<EOF
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: weather-agent
-  namespace: team1
-  labels:
-    app.kubernetes.io/name: weather-agent
-    kagenti.io/type: agent
-    protocol.kagenti.io/a2a: ""
-    kagenti.io/framework: LangGraph
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: weather-agent
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/name: weather-agent
-        kagenti.io/type: agent
-    spec:
-      containers:
-      - name: agent
-        image: "ghcr.io/kagenti/agent-examples/weather_service:v0.0.1-alpha.3"
-        ports:
-        - containerPort: 8000
-        imagePullPolicy: Always
-        env:
-        - name: PORT
-          value: "8000"
-        - name: UV_CACHE_DIR
-          value: /app/.cache/uv
-        - name: MCP_URL
-          value: http://weather-tool-mcp.team1.svc.cluster.local:8000/mcp
-        - name: LLM_API_BASE
-          value: http://host.docker.internal:11434/v1
-        - name: LLM_API_KEY
-          value: dummy
-        - name: LLM_MODEL
-          value: llama3.2:3b-instruct-fp16
----
-apiVersion: v1
-kind: Service
-metadata:
-  name: weather-agent
-  namespace: team1
-spec:
-  selector:
-    app.kubernetes.io/name: weather-agent
-  ports:
-  - name: http
-    port: 8000
-    targetPort: 8000
-EOF
-
-```
-
-**Check Status**:
-```bash
-
-# Check discovered agent cards
-kubectl get agentcards -n team1
-
-# Check deployment status
-kubectl get deployment weather-agent -n team1
-
-# View logs
-kubectl logs -l app.kubernetes.io/name=weather-agent -n team1
-```
-
----
-
 ## Deploy an MCP Server
 
 MCP (Model Context Protocol) servers provide tools and resources that your agents can use. Deploy an MCP server after your agent is running.
@@ -273,18 +197,15 @@ metadata:
   name: weather-tool
   labels:
     app.kubernetes.io/name: weather-tool
-    kagenti.io/type: tool
 spec:
   replicas: 1
   selector:
     matchLabels:
       app.kubernetes.io/name: weather-tool
-      kagenti.io/type: tool
   template:
     metadata:
       labels:
         app.kubernetes.io/name: weather-tool
-        kagenti.io/type: tool
     spec:
       containers:
       - name: mcp
@@ -306,6 +227,18 @@ spec:
       - name: cache
         emptyDir: {}
 ---
+apiVersion: agent.kagenti.dev/v1alpha1
+kind: AgentRuntime
+metadata:
+  name: weather-tool
+  namespace: team1
+spec:
+  type: tool
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: weather-tool
+---
 apiVersion: v1
 kind: Service
 metadata:
@@ -315,7 +248,6 @@ metadata:
     app.kubernetes.io/name: weather-service
     kagenti.io/framework: LangGraph
     kagenti.io/inject: enabled
-    kagenti.io/type: agent
     kagenti.io/workload-type: deployment
     protocol.kagenti.io/a2a: ""
   name: weather-service

kagenti-operator/config/samples/agent_v1alpha1_agentruntime_skill_discovery.yaml

@@ -29,7 +29,6 @@ metadata:
   name: my-agent
   labels:
     app.kubernetes.io/name: my-agent
-    kagenti.io/type: agent
     protocol.kagenti.io/a2a: ""
   annotations:
     kagenti.io/skills: '["openshift-review"]'

kagenti-operator/demos/agentcard-spire-signing/k8s/agent-deployment.yaml

@@ -69,12 +69,10 @@ spec:
   selector:
     matchLabels:
       app.kubernetes.io/name: weather-agent
-      kagenti.io/type: agent
   template:
     metadata:
       labels:
         app.kubernetes.io/name: weather-agent
-        kagenti.io/type: agent
         protocol.kagenti.io/a2a: ""
         istio.io/dataplane-mode: none
     spec:

kagenti-operator/docs/api-reference.md

@@ -149,9 +149,9 @@ Represents the A2A agent card structure based on the [A2A specification](https:/
 
 ### Examples
 
-#### Deploy Agent as a Standard Deployment (Recommended)
+#### Deploy Agent with AgentRuntime (Recommended)
 
-Create a standard Deployment with agent labels, and an AgentCard with `targetRef`:
+Create a Deployment with a protocol label and an `AgentRuntime` CR to enroll it. The operator applies `kagenti.io/type: agent` to the Deployment, and the AgentCardSync controller auto-creates an AgentCard named `weather-agent-deployment-card` (pattern: `{name}-{kind}-card`):
 
 ```yaml
 apiVersion: apps/v1
@@ -161,7 +161,6 @@ metadata:
   namespace: default
   labels:
     app.kubernetes.io/name: weather-agent
-    kagenti.io/type: agent
     protocol.kagenti.io/a2a: ""
 spec:
   replicas: 1
@@ -183,25 +182,27 @@ spec:
           value: "8000"
 ---
 apiVersion: agent.kagenti.dev/v1alpha1
-kind: AgentCard
+kind: AgentRuntime
 metadata:
-  name: weather-agent-card
+  name: weather-agent
   namespace: default
 spec:
-  syncPeriod: 30s
+  type: agent
   targetRef:
     apiVersion: apps/v1
     kind: Deployment
     name: weather-agent
 ```
 
-#### AgentCard with Identity Binding
+#### Manual AgentCard with Identity Binding
+
+If you need `identityBinding.strict: true` (enforcement mode), create the AgentCard before the workload is labeled. The sync controller will skip auto-creation when it finds an existing card targeting the same workload:
 
 ```yaml
 apiVersion: agent.kagenti.dev/v1alpha1
 kind: AgentCard
 metadata:
-  name: weather-agent-card
+  name: weather-agent-deployment-card
   namespace: default
 spec:
   syncPeriod: "30s"
@@ -213,8 +214,6 @@ spec:
     strict: true
 ```
 
-The AgentCard can also be automatically created by the operator when agent labels are present on the Deployment.
-
 #### View Discovered Agents
 
 ```bash
@@ -308,23 +307,23 @@ status:
 
 ```bash
 # Get agent name from card
-kubectl get agentcard weather-agent-card \
+kubectl get agentcard weather-agent-deployment-card \
   -o jsonpath='{.status.card.name}'
 
 # List all skills
-kubectl get agentcard weather-agent-card \
+kubectl get agentcard weather-agent-deployment-card \
   -o jsonpath='{.status.card.skills[*].name}'
 
 # Get agent endpoint
-kubectl get agentcard weather-agent-card \
+kubectl get agentcard weather-agent-deployment-card \
   -o jsonpath='{.status.card.url}'
 
 # Check signature verification
-kubectl get agentcard weather-agent-card \
+kubectl get agentcard weather-agent-deployment-card \
   -o jsonpath='{.status.validSignature}'
 
 # Check identity binding
-kubectl get agentcard weather-agent-card \
+kubectl get agentcard weather-agent-deployment-card \
   -o jsonpath='{.status.bindingStatus.bound}'
 ```
 
@@ -366,13 +365,13 @@ spec:
 
 ## Required Labels for Workload-Based Agents
 
-For Deployments and StatefulSets to be automatically discovered by the operator, the following labels are required:
+For Deployments and StatefulSets to be automatically discovered by the operator, the following labels are needed on the workload. `kagenti.io/type` is applied by the operator via an AgentRuntime CR (a `ValidatingAdmissionPolicy` prevents setting it directly). Protocol labels are set by the user:
 
-| Label | Value | Required | Description |
-|-------|-------|----------|-------------|
-| `kagenti.io/type` | `agent` | Yes | Identifies the workload as an agent |
-| `protocol.kagenti.io/<name>` | `""` (existence implies support) | Yes (at least one) | Protocol(s) the agent speaks (e.g., `protocol.kagenti.io/a2a`, `protocol.kagenti.io/mcp`) |
-| `app.kubernetes.io/name` | `<agent-name>` | Recommended | Standard Kubernetes app name label |
+| Label | Value | Set By | Description |
+|-------|-------|--------|-------------|
+| `kagenti.io/type` | `agent` or `tool` | Operator (via AgentRuntime) | Classifies the workload. Applied automatically when an AgentRuntime CR targets it. |
+| `protocol.kagenti.io/<name>` | `""` (existence implies support) | User | Protocol(s) the agent speaks (e.g., `protocol.kagenti.io/a2a`, `protocol.kagenti.io/mcp`). Required for AgentCard auto-creation. |
+| `app.kubernetes.io/name` | `<agent-name>` | User | Standard Kubernetes app name label (recommended) |
 
 ---
 

kagenti-operator/docs/controller-webhook-interaction.md

@@ -160,7 +160,7 @@ The webhook performs its own merge at Pod CREATE time, including CR overrides, t
 
 ## Global and Cluster Configuration
 
-When workloads are deployed with the right labels (`kagenti.io/type: agent` or `tool`), the webhook uses two levels of global configuration regardless of whether an AgentRuntime CR exists:
+When workloads have the `kagenti.io/type` label (applied by the operator via an AgentRuntime CR), the webhook uses two levels of global configuration:
 
 ### PlatformConfig (Global Defaults)
 
@@ -195,17 +195,9 @@ When `perWorkloadConfigResolution` is **false** (default), the webhook builds si
 
 When `perWorkloadConfigResolution` is **true**, the webhook resolves all config values at admission time by reading namespace ConfigMaps and AgentRuntime CR overrides, then injects literal environment variable values into the sidecar containers.
 
-## Defaults-Only Path (No AgentRuntime CR)
+## AgentRuntime Required — Admission Policy
 
-When a workload has `kagenti.io/type` labels applied manually (without an AgentRuntime CR):
-
-- The webhook still evaluates the workload for injection using PlatformConfig and feature gates
-- Configuration comes from PlatformConfig (layer 1) and namespace ConfigMaps (layer 2) only
-- No controller manages the config hash — configuration drift is not detected automatically, and changes to cluster/namespace defaults do not trigger rolling updates
-- The controller does not watch or reconcile these workloads
-- Per-workload identity (SPIFFE trust domain) overrides are not available
-
-The AgentRuntime CR is the recommended approach because it provides:
+A `ValidatingAdmissionPolicy` prevents the `kagenti.io/type` label from being set directly on Deployments or StatefulSets. Only the operator's service account (via the AgentRuntime controller) can apply this label. This ensures every enrolled workload has a corresponding AgentRuntime CR, which provides:
 - Automatic rolling updates on config change (any layer)
 - Per-workload identity overrides
 - Status reporting (phase, conditions, configured pod count)

kagenti-operator/docs/dynamic-agent-discovery.md

@@ -40,28 +40,39 @@ Exposes /.well-known/    Enables kubectl get agentcards
 
 ## How It Works
 
-### 1. Workload Labeling
+### 1. Workload Enrollment via AgentRuntime
 
-Agent workloads (Deployments or StatefulSets) must be labeled to enable discovery:
+Agent workloads (Deployments or StatefulSets) are enrolled by creating an `AgentRuntime` CR. The operator's controller applies the `kagenti.io/type` label automatically — a `ValidatingAdmissionPolicy` prevents setting it directly on workloads.
+
+The workload itself carries a protocol label to declare which protocol it speaks:
 
 ```yaml
 apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: weather-agent
   labels:
-    kagenti.io/type: agent             # Identifies as an agent
     protocol.kagenti.io/a2a: ""        # Speaks A2A protocol
     app.kubernetes.io/name: weather-agent
 spec:
   # ... standard Deployment spec
+---
+apiVersion: agent.kagenti.dev/v1alpha1
+kind: AgentRuntime
+metadata:
+  name: weather-agent
+spec:
+  type: agent
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: weather-agent
 ```
 
-Multiple protocols can be declared simultaneously:
+Multiple protocols can be declared simultaneously on the Deployment:
 
 ```yaml
   labels:
-    kagenti.io/type: agent
     protocol.kagenti.io/a2a: ""        # Speaks A2A
     protocol.kagenti.io/mcp: ""        # Also speaks MCP
 ```
@@ -204,7 +215,6 @@ kind: Deployment
 metadata:
   name: assistant-agent
   labels:
-    kagenti.io/type: agent
     protocol.kagenti.io/a2a: ""
     app.kubernetes.io/name: assistant-agent
 spec:
@@ -234,9 +244,20 @@ spec:
     - name: http
       port: 8000
       targetPort: 8000
+---
+apiVersion: agent.kagenti.dev/v1alpha1
+kind: AgentRuntime
+metadata:
+  name: assistant-agent
+spec:
+  type: agent
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: assistant-agent
 ```
 
-The AgentCard is created automatically by the AgentCardSync controller when agent labels are present, or can be created explicitly with `targetRef`.
+The operator applies the `kagenti.io/type: agent` label to the Deployment, and the AgentCard is created automatically by the AgentCardSync controller when both `kagenti.io/type` and a protocol label are present.
 
 ### Query Agent Cards
 

kagenti-operator/docs/operator-managed-client-registration.md

@@ -104,7 +104,7 @@ Other workloads are ignored by this controller.
 ### 3.2 Workload
 
 - **Deployment** or **StatefulSet** (not bare Pods for operator ownership of Secrets).
-- Pod template labels: `kagenti.io/type: agent` or `tool` (subject to `injectTools`). Do **not** set `kagenti.io/client-registration-inject: "true"` unless you require the legacy sidecar.
+- An **AgentRuntime** CR targeting the workload — the operator applies `kagenti.io/type` to the Deployment/StatefulSet and its PodTemplateSpec (a `ValidatingAdmissionPolicy` prevents manual application). Do **not** set `kagenti.io/client-registration-inject: "true"` unless you require the legacy sidecar.
 - For **SPIRE-enabled** namespaces: `spec.template.spec.serviceAccountName` must be a **dedicated** ServiceAccount (not `default`).
 
 ### 3.3 Operator configuration