fix(ai-gateway): Update AI Entities docs

app/_ai_gateway_entities/ai-agent.md

@@ -39,7 +39,7 @@ faqs:
       Use `a2a` when the upstream speaks the A2A protocol and you want observability tied to A2A
       task and message semantics.
 
-  - q: Does the Agent entity modify request routing or aggregate responses?
+  - q: Does the AI Agent entity modify request routing or aggregate responses?
     a: |
       No. The runtime behind an Agent operates as a transparent proxy. It detects A2A requests,
       records telemetry, and rewrites agent-card URLs to the gateway address. It does not change
@@ -63,11 +63,6 @@ faqs:
     a: |
       Set the [`acls`](#schema-aigateway-agent-acls) field on the AI Agent with allow or deny lists. Each entry is a string that
       references an AI Consumer, AI Consumer Group, or Authenticated Group by name.
-
-  - q: Can the same plugin run on an AI Agent that I'd attach to a route or service?
-    a: |
-      Plugin configuration that applies to the AI Agent goes through the [AI Policy entity](/ai-gateway/entities/ai-policy/).
-      Attach AI Policies to the AI Agent through its [`policies`](#schema-aigateway-agent-policies) field.
 ---
 
 ## What is an AI Agent?
@@ -76,7 +71,7 @@ An AI Agent is a first-class {{site.ai_gateway}} entity that represents an upstr
 
 For `http` type AI Agents, requests are proxied without A2A-specific processing. For `a2a` type AI Agents, {{site.ai_gateway}} adds protocol-aware behavior on top of plain proxying: it detects A2A requests across both JSON-RPC and REST bindings, rewrites agent-card URLs so clients discover the gateway as the canonical endpoint, and emits structured A2A telemetry to {{site.konnect_short_name}} analytics and OpenTelemetry.
 
-AI Agents can be created and managed through the {{site.konnect_short_name}} UI, the {{site.ai_gateway}} API, or decK:
+AI Agents can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} API:
 
 {% table %}
 columns:
@@ -136,7 +131,7 @@ sequenceDiagram
         Gateway->>Client: Response (unchanged)
     end
 
-    Note over Gateway: Finish OTel span<br>Emit ai.a2a metrics to log plugins
+    Note over Gateway: Finish OTel span<br>Emit ai.a2a metrics to logs
 {% endmermaid %}
 <!-- vale on -->
 
@@ -243,9 +238,9 @@ When an upstream agent returns an agent card, the runtime rewrites the [`url`](#
 
 ## Logging and observability
 
-When Statistics logging is enabled, {{site.ai_gateway}} records structured A2A telemetry per request and exposes it in {{site.konnect_short_name}} analytics, attached log plugins, and OpenTelemetry when [{{site.base_gateway}} tracing](/gateway/tracing/) is configured. For the canonical metric and attribute list, see [A2A metrics](/ai-gateway/ai-otel-metrics/#a2a-metrics).
+When Statistics logging is enabled, {{site.ai_gateway}} records structured A2A telemetry per request and exposes it in {{site.konnect_short_name}} analytics and attached logging policies. For the canonical metric and attribute list, see [A2A metrics](/ai-gateway/ai-otel-metrics/#a2a-metrics).
 
-The runtime emits this data into the `ai.a2a` namespace consumed by {{site.konnect_short_name}} analytics and any attached logging plugins, and creates a `kong.a2a` child span when [{{site.base_gateway}} tracing](/gateway/tracing/) is configured.
+The runtime emits this data into the `ai.a2a` namespace consumed by {{site.konnect_short_name}} analytics and any attached logging Policies.
 
 {:.info}
 > When statistics logging is enabled, the runtime removes the `Accept-Encoding` request header
@@ -262,13 +257,13 @@ You can view A2A analytics in {{site.konnect_short_name}} Explorer and Dashboard
 
 ### Log output fields
 
-{% include /plugins/ai-a2a-proxy/log-output-fields.md %}
+{% include md/ai-gateway/v2/entities/log-output-fields.md %}
 
 ### OpenTelemetry span attributes
 
-When statistics logging is enabled and {{site.base_gateway}} tracing is configured, the runtime creates a `kong.a2a` child span with the following attributes:
+When statistics logging is enabled and {{site.ai}} tracing is configured, the runtime creates a `kong.a2a` child span with the following attributes:
 
-{% include /plugins/ai-a2a-proxy/otel-span-attributes.md %}
+{% include md/ai-gateway/v2/entities/otel-span-attributes.md %}
 
 ### Task states
 
@@ -284,11 +279,11 @@ For per-request authentication and identity, attach an authentication AI Policy
 
 Attach AI Policies through the AI Agent's [`policies`](#schema-aigateway-agent-policies) field. Each entry is a string that references an AI Policy by name or ID. Multiple AI Policies can attach to one AI Agent; each runs independently.
 
-For details, see the [Policy entity](/ai-gateway/entities/ai-policy/) reference.
+For details, see the [AI Policy entity](/ai-gateway/entities/ai-policy/) reference.
 
 ## Set up an Agent
 
-The following example creates an `a2a` Agent that proxies traffic to an upstream A2A agent at `https://booking-agent.internal.kongair.com`, with statistics logging enabled and access restricted to the `internal-teams` Consumer Group.
+The following example creates an `a2a` AI Agent that proxies traffic to an upstream A2A agent at `https://booking-agent.internal.kongair.com`, with statistics logging enabled and access restricted to the `internal-teams` AI Consumer Group.
 
 {% entity_example %}
 type: agent

app/_ai_gateway_entities/ai-consumer-credential.md

@@ -29,19 +29,19 @@ related_resources:
   - text: AI Policy entity
     url: /ai-gateway/entities/ai-policy/
 faqs:
-  - q: Why are credentials a separate entity instead of a field on the Consumer?
+  - q: Why are credentials a separate entity instead of a field on the AI Consumer?
     a: |
       Each credential has its own lifecycle, identifier, and (for API keys) TTL. Modeling them as
-      a sub-entity of the Consumer lets you list, rotate, and revoke individual credentials
-      independently of the Consumer record.
+      a sub-entity of the AI Consumer lets you list, rotate, and revoke individual credentials
+      independently of the AI Consumer record.
 
   - q: What credential types are supported?
     a: |
-      Two types: `api-key` and `oauth`. The [`type`](#schema-aigateway-consumer-credential-type) of the Credential must match the Consumer's
+      Two types: `api-key` and `oauth`. The [`type`](#schema-aigateway-consumer-credential-type) of the Credential must match the AI Consumer's
       `type`. An `api-key` credential carries the [`api_key`](#schema-aigateway-consumer-credential-api-key) value (and an optional [`ttl`](#schema-aigateway-consumer-credential-ttl)). An
-      `oauth` credential is paired with a Consumer that maps to an OAuth identity through the Consumer's `custom_id` field.
+      `oauth` credential is paired with an AI Consumer that maps to an OAuth identity through the AI Consumer's `custom_id` field.
 
-  - q: Can a Consumer have multiple credentials?
+  - q: Can an AI Consumer have multiple credentials?
     a: |
       Yes. Issue one Credential per environment, client, or rotation cycle, and revoke individual
       Credentials without affecting the others.
@@ -52,16 +52,16 @@ faqs:
       ([`name`](#schema-aigateway-consumer-credential-name), [`display_name`](#schema-aigateway-consumer-credential-display-name), [`ttl`](#schema-aigateway-consumer-credential-ttl), timestamps) but not the secret. Distribute the key value at
       creation time, and rotate by issuing a new Credential and revoking the old one.
 
-  - q: What's the relationship between `ttl` and the Consumer's lifecycle?
+  - q: What's the relationship between `ttl` and the AI Consumer's lifecycle?
     a: |
       [`ttl`](#schema-aigateway-consumer-credential-ttl) controls how long the API key value remains valid in seconds. When it elapses, the
-      Credential stops authenticating but the Credential record (and the parent Consumer) remain.
-      Issue a new Credential to keep the Consumer authenticating.
+      Credential stops authenticating but the Credential record (and the parent AI Consumer) remain.
+      Issue a new Credential to keep the AI Consumer authenticating.
 ---
 
-## What is a Consumer Credential?
+## What is an AI Consumer Credential?
 
-A Consumer Credential is the {{site.ai_gateway}} entity that represents the secret material a [Consumer](/ai-gateway/entities/ai-consumer/) presents to authenticate to {{site.ai_gateway}}.
+An AI Consumer Credential is the {{site.ai_gateway}} entity that represents the secret material an [AI Consumer](/ai-gateway/entities/ai-consumer/) presents to authenticate to {{site.ai_gateway}}.
 
 Credentials are nested under their owning AI Consumer: each Credential belongs to exactly one AI Consumer, and removing the AI Consumer removes its Credentials.
 
@@ -83,7 +83,7 @@ rows:
 The [`type`](#schema-aigateway-consumer-credential-type) field on a Credential must match the parent Consumer's `type`:
 
 * **`api-key`**: the Credential carries an [`api_key`](#schema-aigateway-consumer-credential-api-key) value the client presents on each request. An optional [`ttl`](#schema-aigateway-consumer-credential-ttl) (seconds) bounds the validity period; once it elapses, the value no longer authenticates.
-* **`oauth`**: the Credential type for OAuth Consumers. The parent Consumer's `custom_id` field maps to an OAuth identity issued by an external provider. {{site.ai_gateway}} works with any standards-compliant OAuth 2.0 / OpenID Connect provider configured through the [OpenID Connect plugin](/plugins/openid-connect/), or, for MCP traffic, the [AI MCP OAuth2 plugin](/plugins/ai-mcp-oauth2/). The `custom_id` is typically the OIDC `sub` claim or the Client ID issued by the OAuth provider. The actual access token is issued and validated by the OAuth provider, not stored on the Credential.
+* **`oauth`**: the Credential type for OAuth Consumers. The parent Consumer's `custom_id` field maps to an OAuth identity issued by an external provider. {{site.ai_gateway}} works with any standards-compliant OAuth 2.0 / OpenID Connect provider configured through the [OpenID Connect AI Policy](/ai-gateway/policies/openid-connect/), or, for MCP traffic, the [AI MCP OAuth2 AI Policy](/ai-gateway/policies/ai-mcp-oauth2/). The `custom_id` is typically the OIDC `sub` claim or the Client ID issued by the OAuth provider. The actual access token is issued and validated by the OAuth provider, not stored on the Credential.
 
 The [`api_key`](#schema-aigateway-consumer-credential-api-key) field is write-only and cannot be retrieved after creation. Treat creation responses as the only opportunity to capture the key value.
 

app/_ai_gateway_entities/ai-consumer-group.md

@@ -42,21 +42,21 @@ faqs:
       No. The generated Kong Consumer Group is protected from direct modification through the
       standard `/consumer-groups` Admin API. Update the AI Consumer Group instead.
 
-  - q: How do I assign a Consumer to a Consumer Group?
+  - q: How do I assign an AI Consumer to an AI Consumer Group?
     a: |
-      You add a Consumer to a Consumer Group through the Consumer Group entity.
-      See the [Consumer entity](/ai-gateway/entities/ai-consumer/) and
-      [Consumer Group entity](/ai-gateway/entities/ai-consumer-group/) references.
+      You add an AI Consumer to an AI Consumer Group through the AI Consumer Group entity.
+      See the [AI Consumer entity](/ai-gateway/entities/ai-consumer/) and
+      [AI Consumer Group entity](/ai-gateway/entities/ai-consumer-group/) references.
 
-  - q: Can a Consumer belong to multiple Consumer Groups?
+  - q: Can an AI Consumer belong to multiple AI Consumer Groups?
     a: |
-      Yes. The Consumer's `consumer_groups` array accepts one or more references.
+      Yes. The AI Consumer's `consumer_groups` array accepts one or more references.
 
-  - q: How do I attach Policies to a Consumer Group?
+  - q: How do I attach AI Policies to an AI Consumer Group?
     a: |
-      Add the Policy's `name` or `id` to the Consumer Group's [`policies`](#schema-aigateway-consumer-group-policies) array.
+      Add the AI Policy's `name` or `id` to the AI Consumer Group's [`policies`](#schema-aigateway-consumer-group-policies) array.
       The policy runs when a member of the group is identified during a request.
-      See the [Policy entity](/ai-gateway/entities/ai-policy/) reference.
+      See the [AI Policy entity](/ai-gateway/entities/ai-policy/) reference.
 
   - q: How do I gate access to an AI Model, AI Agent, or AI MCP Server with an AI Consumer Group?
     a: |
@@ -71,7 +71,7 @@ An AI Consumer Group is the {{site.ai_gateway}} entity that represents a collect
 
 Use AI Consumer Groups to scope group-wide behavior, such as rate limits, prompt guards, or content moderation, without configuring each AI Consumer individually. AI Consumer Groups can appear in the `acls` field of AI Model, AI Agent, and AI MCP Server entities, where they gate access to those parent entities.
 
-AI Consumer Groups can be created and managed through the {{site.konnect_short_name}} UI, the {{site.ai_gateway}} API, or decK:
+AI Consumer Groups can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} API:
 
 {% table %}
 columns:

app/_ai_gateway_entities/ai-consumer.md

@@ -37,15 +37,15 @@ faqs:
     a: |
       The runtime entity is a regular Kong Consumer. The {{site.ai_gateway}} surface uses the
       {{site.ai_gateway}} entity convention ([`display_name`](#schema-aigateway-consumer-display-name), [`name`](#schema-aigateway-consumer-name), [`labels`](#schema-aigateway-consumer-labels)), requires an
-      authentication [`type`](#schema-aigateway-consumer-type) field, accepts inline Consumer Group assignment, and lets you
-      reference Policies. Credentials are managed as a separate sub-entity rather than embedded
+      authentication [`type`](#schema-aigateway-consumer-type) field, accepts inline AI Consumer Group assignment, and lets you
+      reference AI Policies. Credentials are managed as a separate sub-entity rather than embedded
       on the Consumer.
 
   - q: How do I add credentials to an AI Consumer?
     a: |
       Credentials are a separate sub-entity, not a field on the Consumer. Create them under the
       Consumer's nested credentials endpoint. See the
-      [Consumer Credential entity](/ai-gateway/entities/ai-consumer-credential/) reference.
+      [AI Consumer Credential entity](/ai-gateway/entities/ai-consumer-credential/) reference.
 
   - q: "What's the difference between `type: api-key` and `type: oauth`?"
     a: |
@@ -62,7 +62,7 @@ faqs:
   - q: How do I attach AI Policies to an AI Consumer?
     a: |
       Add the Policy's `name` or `id` to the Consumer's [`policies`](#schema-aigateway-consumer-policies) array.
-      See the [Policy entity](/ai-gateway/entities/ai-policy/) reference.
+      See the [AI Policy entity](/ai-gateway/entities/ai-policy/) reference.
 ---
 
 ## What is an AI Consumer?
@@ -71,7 +71,7 @@ An AI Consumer is the {{site.ai_gateway}} entity that represents a downstream cl
 
 You can use AI Consumers and AI Consumer Groups to authenticate clients, attach AI Policies, and gate access to AI Models, AI Agents, and AI MCP Servers through those parent entities' `acls` field.
 
-AI Consumers can be created and managed through the {{site.konnect_short_name}} UI, the {{site.ai_gateway}} API, or decK:
+AI Consumers can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} API:
 
 {% table %}
 columns:
@@ -89,25 +89,25 @@ rows:
 The [`type`](#schema-aigateway-consumer-type) field declares which credential family the Consumer authenticates with. Supported values are:
 
 * `api-key`: the Consumer authenticates with one or more API key Credentials.
-* `oauth`: the Consumer authenticates through an OAuth identity issued by an external OIDC provider. {{site.ai_gateway}} accepts any standards-compliant OAuth 2.0 / OpenID Connect provider configured through the [OpenID Connect plugin](/plugins/openid-connect/), or, for MCP traffic, through the [AI MCP OAuth2 plugin](/plugins/ai-mcp-oauth2/). The Consumer Credential carries a `custom_id` that maps to the OAuth provider's user identifier (for example, an OIDC Client ID or `sub` claim).
+* `oauth`: the Consumer authenticates through an OAuth identity issued by an external OIDC provider. {{site.ai_gateway}} accepts any standards-compliant OAuth 2.0 / OpenID Connect provider configured through the [OpenID Connect policy](/ai-gateway/policies/openid-connect/), or, for MCP traffic, through the [AI MCP OAuth2 policy](/ai-gateway/policies/ai-mcp-oauth2/). The AI Consumer Credential carries a `custom_id` that maps to the OAuth provider's user identifier (for example, an OIDC Client ID or `sub` claim).
 
-The `type` of every Credential issued to the Consumer must match the Consumer's `type`. See the [Consumer Credential entity](/ai-gateway/entities/ai-consumer-credential/) reference for credential management.
+The `type` of every Credential issued to the Consumer must match the Consumer's `type`. See the [AI Consumer Credential entity](/ai-gateway/entities/ai-consumer-credential/) reference for credential management.
 
-## Consumer Group membership
+## AI Consumer Group membership
 
-A Consumer can belong to multiple Consumer Groups. Consumer Group membership is managed through the Consumer Group entity. See the [Consumer Group entity](/ai-gateway/entities/ai-consumer-group/) reference for how to assign Consumers to groups.
+An AI Consumer can belong to multiple AI Consumer Groups. AI Consumer Group membership is managed through the AI Consumer Group entity. See the [AI Consumer Group entity](/ai-gateway/entities/ai-consumer-group/) reference for how to assign AI Consumers to groups.
 
 ## Attach Policies
 
 Attach a Policy by adding its `name` or `id` to the Consumer's [`policies`](#schema-aigateway-consumer-policies) array. The policy runs in the request lifecycle when the Consumer is identified.
 
 You can attach multiple Policies to a single Consumer. Each Policy runs independently.
 
-For supported policy types and how Policies attach to other entities, see the [Policy entity](/ai-gateway/entities/ai-policy/) reference.
+For supported policy types and how Policies attach to other entities, see the [AI Policy entity](/ai-gateway/entities/ai-policy/) reference.
 
 ## Set up an AI Consumer
 
-The following example creates an AI Consumer assigned to a single AI Consumer Group. Credentials are issued separately through the [Consumer Credential entity](/ai-gateway/entities/ai-consumer-credential/).
+The following example creates an AI Consumer assigned to a single AI Consumer Group. Credentials are issued separately through the [AI Consumer Credential entity](/ai-gateway/entities/ai-consumer-credential/).
 
 {% entity_example %}
 type: consumer

app/_ai_gateway_entities/ai-data-plane-certificate.md

@@ -22,9 +22,9 @@ tools:
 related_resources:
   - text: "About {{site.ai_gateway}}"
     url: /ai-gateway/
-  - text: Provider entity
+  - text: AI Provider entity
     url: /ai-gateway/entities/ai-provider/
-  - text: Vault entity
+  - text: AI Vault entity
     url: /ai-gateway/entities/ai-vault/
 faqs:
   - q: Why is there no update operation?
@@ -118,6 +118,22 @@ To rotate a certificate without downtime:
 
 Deleting a Data Plane Certificate immediately invalidates the trust for any data plane still using it. Existing connections are dropped and reconnect attempts using the deleted certificate are rejected.
 
+## Set up a Data Plane Certificate
+
+The following example registers a public X.509 certificate as a trusted client identity for an {{site.ai_gateway}}.
+
+{% entity_example %}
+type: data_plane_certificate
+data:
+  title: My AI Gateway Data Plane Certificate
+  description: Certificate for data plane nodes in production
+  cert: |
+    -----BEGIN CERTIFICATE-----
+    MIIDXTCCAkWgAwIBAgIJAJC1/iNAZwqDMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV
+    ...
+    -----END CERTIFICATE-----
+{% endentity_example %}
+
 ## Schema
 
 {% entity_schema %}