release(ai-gateway): AI Gateway 2.0

.claude/skills/ai-gateway-migration-review/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: ai-gateway-migration-review
+description: >
+  Reviews AI Gateway documentation files for correctness during the v1 → v2 migration.
+  Use this skill whenever you need to audit or fix AI Gateway docs for migration issues —
+  whether reviewing specific files or all AI Gateway files across how-tos, landing pages,
+  and reference pages. Triggers on requests like "review this ai-gateway file", "check
+  my migration", "audit ai-gateway docs for v2", "find v1 references in ai-gateway pages",
+  "update this file for AI Gateway v2", or any time someone is working on AI Gateway
+  content under app/_how-tos/ai-gateway, app/_landing-pages/ai-gateway, or app/ai-gateway.
+---
+
+# AI Gateway Migration Review Skill
+
+This skill audits and optionally fixes AI Gateway documentation files for the v1 → v2 migration.
+
+## Step 1: Ask the user two questions upfront
+
+Before doing any work, ask (you can ask both in one message):
+
+1. **Scope**: Do they want to review a specific files or directories or all AI Gateway files?
+   - If specific files or directories, ask for the path.
+   - If all files, you'll scan these directories:
+     - `app/_how-tos/ai-gateway/`
+     - `app/_landing_pages/ai-gateway/`
+     - `app/ai-gateway/`
+
+2. **Mode**: Should you make changes directly, or produce a report of issues to fix?
+
+## Step 2: Perform the review
+
+Apply the rules below. For **report mode**, collect all findings and present them as a structured report at the end. For **edit mode**, apply fixes directly and summarize what changed.
+
+---
+
+## Rules for v1 files (under any `v1/` subdirectory)
+
+These files are the legacy v1 content. They need their own internal consistency:
+
+- **Breadcrumbs and links**: Any breadcrumbs or links starting with `/ai-gateway/` must use `/ai-gateway/v1/` (not the bare `/ai-gateway/` path).
+- **Permalinks**: If the file has a `permalink:` frontmatter field, it must contain `/v1/` in the path.
+- **Include and data file references**: References to AI Gateway include files (`{% include_content ... %}`, `{% include ... %}`) and data files must use the `/v1/` variant, e.g. `ai-gateway/v1/some-include` not `ai-gateway/some-include`.
+
+---
+
+## Rules for v2 files (current, non-v1 AI Gateway files)
+
+### Frontmatter requirements
+
+Every v2 AI Gateway page must have this exact frontmatter shape for these fields:
+
+```yaml
+products:
+    - ai-gateway          # Only ai-gateway, no other products
+works_on:
+    - konnect             # Only konnect, no on-prem
+tools:
+    - konnect-api         # Optional field, if it exists, must be only konnect-api
+min_version:
+    ai-gateway: '2.0'
+```
+
+Flag any deviation:
+- `products` containing anything other than `ai-gateway`
+- `works_on` containing `on-prem` or anything other than `konnect`
+- `tools` containing `deck`, `admin-api`, or anything other than `konnect-api`
+- Missing or wrong `min_version` (must be `ai-gateway: '2.0'`)
+
+#### `content_type` on AI Policy pages
+
+Pages under `app/_ai_gateway_policies/` are auto-generated as stubs with the default `content_type: plugin`. When you author real overview content for one of these pages (i.e. the file has hand-written body prose, not just frontmatter), set `content_type: policy`.
+
+- If you are adding or editing overview prose on an `_ai_gateway_policies/` page, change `content_type: plugin` → `content_type: policy`.
+- Leave untouched stubs alone — do **not** flip `content_type` on pages that still have an empty body. The stub default stays `plugin` until the page gets real content.
+
+### Plugin → AI Policy migration
+
+Plugins have been replaced by AI Policies in v2. The four plugins that do **not** exist as policies are exceptions:
+- AI A2A Proxy
+- AI MCP Proxy
+- AI Proxy
+- AI Proxy Advanced
+
+For everything else:
+
+- **Rename in prose**: Replace "X plugin" with "X Policy". For example:
+  - "AI Request Transformer plugin" → "AI Request Transformer Policy"
+  - "AI Prompt Guard plugin" → "AI Prompt Guard Policy"
+
+- **Links to plugins**: Replace `/plugins/` path with `/ai-gateway/policies/`. For example:
+  - `/plugins/ai-prompt-guard/` → `/ai-gateway/policies/ai-prompt-guard/`
+  - `/plugins/?category=ai` → `/ai-gateway/policies/`
+
+- **Links to the Plugin entity**: When a link points at the Gateway Plugin entity page `/gateway/entities/plugin/` *but refers to an AI Policy*, replace it with the AI Policy entity page `/ai-gateway/entities/ai-policy/`. For example:
+  - `[AI Policy](/gateway/entities/plugin/)` → `[AI Policy](/ai-gateway/entities/ai-policy/)`
+  - `[AI Prompt Guard Policy](/gateway/entities/plugin/)` → `[AI Prompt Guard Policy](/ai-gateway/entities/ai-policy/)`
+
+  Be careful: `/gateway/entities/plugin/` can also be a legitimate reference to the generic Gateway Plugin entity — for instance when a page contrasts AI Policies with how {{site.base_gateway}} plugins work. Only rewrite when the link is genuinely about an AI Policy. **Flag ambiguous cases for manual review** rather than rewriting automatically.
+
+- **Exception — flag these**: Any reference to AI A2A Proxy, AI MCP Proxy, AI Proxy, or AI Proxy Advanced as plugins should be flagged for manual review (these don't have policy equivalents).
+
+- **Landing page plugin blocks**: In YAML landing pages (`.yaml` files under `_landing_pages/`), replace `type: plugin` blocks with `type: aigw_policy`. Example:
+  ```yaml
+  # Before (v1)
+  - type: plugin
+    config:
+      slug: ai-prompt-guard
+
+  # After (v2)
+  - type: aigw_policy
+    config:
+      slug: ai-prompt-guard
+  ```
+
+### Include and data file references
+
+References to AI Gateway include files and data files must use `/v2/`. For example:
+- `ai-gateway/circuit-breaker` → `ai-gateway/v2/circuit-breaker`
+- `_includes/md/ai-gateway/circuit-breaker.md` → `_includes/md/ai-gateway/v2/circuit-breaker.md`
+
+Flag any `{% include /plugins/` tags — v2 AI Gateway pages must not pull in plugin includes. These should be removed or replaced with the appropriate AI Policy equivalent. For example:
+
+```
+{% include /plugins/ai-a2a-proxy/log-output-fields.md %}
+```
+
+This should be replaced with a corresponding AI Policy include (e.g. under `_includes/md/ai-gateway/v2/`) or removed if no equivalent exists.
+
+### Code block style
+
+Example codeblocks in how-to guides should use `{% konnect_api_request %}` rather than raw curl or deck commands where they're making API calls. Flag any `curl` commands or `deck` commands in example steps that should be `{% konnect_api_request %}` blocks.
+
+### Konnect-only deployments
+
+v2 AI Gateway is Konnect-only. Flag any references to on-premises deployments, self-hosted Kong Gateway, or any instructions that only apply to on-prem.
+
+### Kong Gateway → AI Gateway
+
+Most references to Kong Gateway or `{{site.base_gateway}}` should be replaced with `{{site.ai_gateway}}`. However, some are legitimate — when a sentence genuinely compares or contrasts AI Gateway with Kong Gateway (e.g. "When operating {{site.ai_gateway}} alongside {{site.base_gateway}}…"), the `{{site.base_gateway}}` reference may be intentional. Flag these for manual review rather than replacing them automatically.
+
+### AI Gateway entity names
+
+All AI Gateway entity names (from `app/_ai_gateway_entities/`) must be capitalized and prefixed with "AI". Known entities:
+- AI Agent
+- AI Consumer
+- AI Consumer Credential
+- AI Consumer Group
+- AI Data Plane Certificate
+- AI Data Plane Node
+- AI Gateway
+- AI MCP Server
+- AI Model
+- AI Policy
+- AI Provider
+- AI Vault
+
+Flag any references to these entities without the "AI" prefix, in both singular and plural forms. For example:
+- "model" or "models" → "AI Model" / "AI Models"
+- "provider" or "providers" → "AI Provider" / "AI Providers"
+- "policy" or "policies" → "AI Policy" / "AI Policies"
+- "agent" or "agents" → "AI Agent" / "AI Agents"
+- "consumer" or "consumers" → "AI Consumer" / "AI Consumers"
+- "vault" → "AI Vault"
+
+**Check the entire file including frontmatter** — FAQs, `related_resources` links, and all entity references in link text must use the full "AI" prefix (e.g., `[AI Policies](/ai-gateway/entities/ai-policy/)` not `[Policies](/ai-gateway/entities/ai-policy/)`).
+
+### Links to unmigrated how-to guides
+
+Not all v1 how-to guides have been migrated to v2. Before checking links, build a list of invalid v1 permalinks by reading every `.md` file under `app/_how-tos/ai-gateway/v1/` and extracting their `permalink:` frontmatter values.
+
+Then, in the file being reviewed, flag any link whose URL appears in that list. These point to legacy v1 pages and should be removed or updated to point to the v2 equivalent if one exists.
+
+### v1 release tracking (`app/_config/releases/ai-gateway/v1.yml`)
+
+This file tracks every v1 page and whether a v2 equivalent has been written. Each entry looks like:
+
+```yaml
+app/_how-tos/ai-gateway/v1/some-guide.md:
+  status: pending       # still needs a v2 equivalent
+  canonical_url:        # should point to the v2 page once written
+```
+
+When a new v2 page is created, the corresponding v1 entry in this file must be updated:
+- Remove `status: pending`
+- Set `canonical_url` to the new v2 page's permalink
+
+When reviewing a newly created v2 file, check whether its v1 counterpart exists in `v1.yml` and still has `status: pending`. If so, flag it: the reviewer should remove `status: pending` and set `canonical_url` to the new page's permalink.
+
+When reviewing all files, read `app/_config/releases/ai-gateway/v1.yml` and report all entries that still have `status: pending` — these are v1 pages that have not yet been migrated.
+
+---
+
+## Reporting format
+
+When producing a **report**, structure it like this for each file reviewed:
+
+```
+### <filepath>
+
+**Frontmatter issues:**
+- <issue description>
+
+**Plugin → AI Policy issues:**
+- <issue description>
+
+**Include/data file references (including `{% include /plugins/` tags):**
+- <issue description>
+
+**Unmigrated how-to links:**
+- <link> — not yet migrated, remove or update
+
+**v1 release tracking (`v1.yml`):**
+- <v1 file path> — still has `status: pending`, set `canonical_url` to <v2 permalink>
+
+**On-prem references:**
+- Line N: <quote> — flag for removal
+
+**Entity naming:**
+- <issue description>
+
+**No issues found** (if clean)
+```
+
+For a **single-file edit**, after making changes, produce a brief summary of every change made.
+
+For **all-files edit**, process files one at a time and produce a per-file summary at the end.

.github/styles/base/Dictionary.txt

@@ -11,6 +11,7 @@ ai_rate_limiting_policy
 agentic
 Agno
 Agno's
+AIGateway
 Alertmanager
 Alibaba
 allow_terminated
@@ -427,6 +428,8 @@ kiali
 Kibana
 kibibytes
 kic
+kimi
+Kimi
 knative
 Knative's
 Knatives
@@ -488,6 +491,7 @@ M_Account
 M_Link
 M_Resource
 maglev
+major_version
 managedfields
 matchers
 max_args
@@ -607,6 +611,7 @@ PDFs
 pg_max_concurrent_queries
 pgdump
 pgvector
+Pinecone
 pipeline
 pipelined
 pipelines
@@ -918,6 +923,8 @@ Valkey
 vendored
 vararg
 vc
+vercel
+Vercel
 viewport
 viewports
 vllm

.github/styles/frontmatter/Dictionary.txt

@@ -1,4 +1,5 @@
 ai_gateway_enterprise
+ai_gateway_url
 graphql
 hmac
 how_to

.github/workflows/automated-tests.yaml

@@ -48,7 +48,7 @@ jobs:
         env:
           KONG_LICENSE_DATA: ${{ steps.getLicense.outputs.license }}
           DEPLOYMENT_MODEL: on-prem
-          PRODUCTS: ai-gateway,gateway
+          PRODUCTS: gateway
           GATEWAY_VERSION: ${{ matrix.gateway }}
         run: |
           DEBUG=tests:*,debug npm run run-tests

.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

CLAUDE.md

@@ -73,6 +73,11 @@ When writing UI steps, follow the formats in `docs/ui-steps-standards.md`.
 
 When adding frontmatter `tags:`, follow the schema in `docs/update-tag-schema.md`.
 
+## Prose style
+
+- Don't use em dashes, en dashes, or dashes as sentence punctuation (e.g. "X — Y"). Rewrite as two sentences, or use a comma, colon, semicolon, or parentheses instead. (Hyphens in compound words like `well-known` or in code/YAML are fine.)
+- Don't use positional language like "below" or "above" to refer to other content on the page (e.g. "the table below", "see above"). Content gets reordered, so these references go stale. Use "the following" for content that comes next, or just link/name the section (e.g. "see [Set up an AI Consumer](#set-up-an-ai-consumer)") instead of describing where it sits on the page.
+
 ## PR review standards
 
 - Provide GitHub suggestions with actionable code, not vague feedback.

Gemfile

@@ -27,3 +27,8 @@ end
 group :jekyll_plugins do
   gem 'jekyll-contentblocks'
 end
+
+group :test do
+  gem 'rspec'
+  gem 'capybara'
+end

Gemfile.lock

@@ -21,11 +21,21 @@ GEM
     bigdecimal (4.1.1)
     byebug (13.0.0)
       reline (>= 0.6.0)
+    capybara (3.40.0)
+      addressable
+      matrix
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.11)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
     coderay (1.1.3)
     colorator (1.1.0)
     concurrent-ruby (1.3.7)
     connection_pool (2.5.5)
     csv (3.3.5)
+    diff-lcs (1.6.2)
     drb (2.2.3)
     dry-cli (1.4.1)
     em-websocket (0.5.3)
@@ -85,8 +95,10 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
+    matrix (0.4.3)
     mercenary (0.4.0)
     method_source (1.1.0)
+    mini_mime (1.1.5)
     mini_portile2 (2.8.9)
     minitest (5.26.2)
     mutex_m (0.3.0)
@@ -115,6 +127,8 @@ GEM
     rack (3.2.6)
     rack-proxy (0.8.2)
       rack
+    rack-test (2.2.0)
+      rack (>= 1.3)
     rackup (0.2.3)
       rack (>= 3.0.0.beta1)
       webrick
@@ -128,6 +142,19 @@ GEM
       io-console (~> 0.5)
     rexml (3.4.2)
     rouge (4.7.0)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
     rubocop (1.87.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -162,6 +189,8 @@ GEM
       rack-proxy (~> 0.6, >= 0.6.1)
       zeitwerk (~> 2.2)
     webrick (1.8.2)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
     zeitwerk (2.8.2)
 
 PLATFORMS
@@ -170,6 +199,7 @@ PLATFORMS
 DEPENDENCIES
   activesupport
   byebug
+  capybara
   csv
   foreman
   jekyll
@@ -185,6 +215,7 @@ DEPENDENCIES
   pry
   puma
   rouge (~> 4.3)
+  rspec
   rubocop
   vite_ruby (~> 3.10)