From 95c27e360f38d6963dc9a0f1558711a01bbe25d3 Mon Sep 17 00:00:00 2001
From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com>
Date: Mon, 31 Aug 2026 10:35:10 -0500
Subject: [PATCH 1/4] docs: refresh kongctl documentation for v1.14

---
 .../manage-ai-gateway-with-kongctl.md         | 279 ++++++++++++
 app/_indices/kongctl.yaml                     |   1 +
 app/_landing_pages/kongctl.yaml               |  16 +-
 app/_landing_pages/konnect.yaml               |   1 +
 app/kongctl/adopt/ai-gateway.md               |   4 +
 app/kongctl/adopt/api.md                      |   1 -
 app/kongctl/adopt/auth-strategy.md            |   1 -
 app/kongctl/adopt/control-plane.md            |   1 -
 app/kongctl/adopt/konnect.md                  |   1 -
 app/kongctl/adopt/organization.md             |   1 -
 app/kongctl/adopt/portal.md                   |   1 -
 app/kongctl/api/delete.md                     |   1 -
 app/kongctl/api/get.md                        |   1 -
 app/kongctl/api/patch.md                      |   1 -
 app/kongctl/api/post.md                       |   1 -
 app/kongctl/api/put.md                        |   1 -
 app/kongctl/apply/konnect.md                  |   1 -
 app/kongctl/audit-logs.md                     | 169 ++++++-
 app/kongctl/authentication.md                 |  83 +++-
 app/kongctl/config.md                         |  68 ++-
 app/kongctl/declarative.md                    | 415 ++++++++++++++++--
 app/kongctl/diff/konnect.md                   |   1 -
 app/kongctl/dump/declarative.md               |  17 +-
 app/kongctl/dump/tf-import.md                 |   1 -
 app/kongctl/explain/index.md                  |  11 +-
 app/kongctl/get/ai-gateway.md                 |   7 +-
 app/kongctl/get/api.md                        |   1 -
 app/kongctl/get/audit-logs.md                 |   7 +-
 app/kongctl/get/auth-strategy.md              |   1 -
 app/kongctl/get/catalog.md                    |   1 -
 app/kongctl/get/gateway.md                    |   1 -
 app/kongctl/get/index.md                      |   4 +
 app/kongctl/get/konnect.md                    |   1 -
 app/kongctl/get/me.md                         |   1 -
 app/kongctl/get/organization.md               |   1 -
 app/kongctl/get/portal.md                     |   1 -
 app/kongctl/get/regions.md                    |   1 -
 app/kongctl/list/ai-gateway.md                |   7 +-
 app/kongctl/list/api.md                       |   1 -
 app/kongctl/list/auth-strategy.md             |   1 -
 app/kongctl/list/gateway.md                   |   1 -
 app/kongctl/list/index.md                     |   4 +
 app/kongctl/list/konnect.md                   |   1 -
 app/kongctl/list/organization.md              |   1 -
 app/kongctl/list/portal.md                    |   1 -
 app/kongctl/listen/audit-logs.md              |   5 +-
 app/kongctl/listen/konnect.md                 |   1 -
 app/kongctl/login/konnect.md                  |   1 -
 app/kongctl/logout/konnect.md                 |   1 -
 app/kongctl/plan/konnect.md                   |   1 -
 app/kongctl/scaffold/index.md                 |  10 +-
 app/kongctl/supported-resources.md            |  94 +++-
 app/kongctl/sync/konnect.md                   |   1 -
 app/kongctl/tail/audit-logs.md                |   8 +-
 app/kongctl/tail/konnect.md                   |   1 -
 app/kongctl/troubleshooting.md                |   4 +-
 app/kongctl/view/index.md                     |   4 +
 57 files changed, 1124 insertions(+), 129 deletions(-)
 create mode 100644 app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md

diff --git a/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md b/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
new file mode 100644
index 0000000000..ab7c512b69
--- /dev/null
+++ b/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
@@ -0,0 +1,279 @@
+---
+title: Manage {{site.ai_gateway}} with kongctl
+description: >-
+  Create {{site.ai_gateway}} and route an OpenAI chat request through a local
+  data plane.
+content_type: how_to
+permalink: /kongctl/manage-ai-gateway/
+
+breadcrumbs:
+  - /kongctl/
+
+products:
+  - ai-gateway
+  - konnect
+
+works_on:
+  - konnect
+
+tools:
+  - kongctl
+
+min_version:
+  ai-gateway: '2.0'
+  kongctl: '1.14'
+
+tags:
+  - ai
+  - declarative-config
+  - openai
+
+tldr:
+  q: How do I manage an AI Gateway with kongctl?
+  a: |
+    Declare the AI Gateway, Model Provider, Model, and data-plane certificate
+    in YAML, apply the configuration with kongctl, and connect a data plane.
+
+automated_tests: false
+
+prereqs:
+  skip_product: false
+  show_works_on: false
+  inline:
+    - title: "{{site.konnect_product_name}}"
+      content: |
+        You need a {{site.konnect_short_name}} account and kongctl 1.14 or
+        later authenticated with `kongctl login`.
+      icon_url: /assets/icons/gateway.svg
+    - title: Local tools
+      content: |
+        Install Docker and OpenSSL. You also need an
+        [OpenAI API key](https://platform.openai.com/api-keys).
+      icon_url: /assets/icons/ai.svg
+
+related_resources:
+  - text: Use kongctl to manage {{site.ai_gateway}}
+    url: /ai-gateway/kongctl/
+  - text: Declarative configuration with kongctl
+    url: /kongctl/declarative/
+  - text: kongctl declarative resource reference
+    url: /kongctl/supported-resources/#ai-gateway
+
+next_steps:
+  - text: Manage additional AI Gateway resources
+    url: /ai-gateway/kongctl/
+  - text: Learn about kongctl sync
+    url: /kongctl/sync/
+---
+
+This tutorial creates an {{site.ai_gateway}}, an OpenAI Model Provider and
+Model, and a data-plane certificate. You then run a local data plane and send
+an OpenAI-compatible chat request through it.
+
+## Create a working directory
+
+Create a directory for the configuration and certificate:
+
+```sh
+mkdir kongctl-ai-gateway
+```
+
+Change into the directory:
+
+```sh
+cd kongctl-ai-gateway
+```
+
+Create a certificate directory:
+
+```sh
+mkdir certs
+```
+
+Generate a self-signed certificate and private key:
+
+```sh
+openssl req -new -x509 -nodes -newkey rsa:2048 -days 365 \
+  -subj "/CN=openai-llm-data-plane/C=US" \
+  -keyout certs/data-plane.key \
+  -out certs/data-plane.crt
+```
+
+Allow the data-plane container group to read the private key:
+
+```sh
+chgrp "$(id -g)" certs/data-plane.key
+chmod 640 certs/data-plane.key
+```
+
+Keep `certs/data-plane.key` private and out of version control. kongctl sends
+only the public certificate to {{site.konnect_short_name}}.
+
+## Declare {{site.ai_gateway}}
+
+Create `ai-gateway.yaml` with the following configuration:
+
+```yaml
+_defaults:
+  kongctl:
+    namespace: openai-llm-example
+
+ai_gateways:
+  - ref: openai-llm
+    name: openai-llm
+    display_name: OpenAI LLM Gateway
+    deployment_type: hybrid
+    description: Routes OpenAI-compatible chat traffic to OpenAI
+    proxy_urls:
+      - host: localhost
+        port: 8000
+        protocol: http
+    labels:
+      example: openai-llm
+    data_plane_certificates:
+      - ref: openai-llm-data-plane
+        title: openai-llm-data-plane
+        description: Local Docker data plane
+        cert: !file ./certs/data-plane.crt
+    model_providers:
+      - ref: openai
+        name: openai
+        display_name: OpenAI
+        type: openai
+        config:
+          auth:
+            type: basic
+            headers:
+              - name: Authorization
+                value: !secret
+                  parts:
+                    - "Bearer "
+                    - !env OPENAI_API_KEY
+    models:
+      - ref: my-gpt-4o
+        name: my-gpt-4o
+        display_name: My GPT-4o
+        type: model
+        formats:
+          - type: openai
+        config:
+          route:
+            paths:
+              - /v1
+            model:
+              body_param: model
+              values:
+                - my-gpt-4o
+        targets:
+          - name: gpt-4o
+            provider: openai
+            config:
+              type: openai
+        policies: []
+        capabilities:
+          - generate
+```
+
+Set your OpenAI API key:
+
+```sh
+export OPENAI_API_KEY='YOUR_OPENAI_API_KEY'
+```
+
+Preview the changes:
+
+```sh
+kongctl diff --mode apply -f ai-gateway.yaml
+```
+
+Apply the configuration:
+
+```sh
+kongctl apply -f ai-gateway.yaml
+```
+
+The `!secret` value is resolved only during execution. The resolved OpenAI
+key isn't stored in the configuration or plan.
+
+## Connect the data plane
+
+Read the configuration endpoint from {{site.ai_gateway}}:
+
+```sh
+export AIGW_CONTROL_PLANE="$(kongctl get ai-gateway \
+  'OpenAI LLM Gateway' --output json --jq \
+  '.endpoints.configuration | sub("^https://"; "") | sub(":443$"; "")' \
+  --jq-raw-output)"
+```
+
+Read the telemetry endpoint:
+
+```sh
+export AIGW_TELEMETRY="$(kongctl get ai-gateway \
+  'OpenAI LLM Gateway' --output json --jq \
+  '.endpoints.telemetry | sub("^https://"; "") | sub(":443$"; "")' \
+  --jq-raw-output)"
+```
+
+Start a {{site.ai_gateway}} 2.0 data plane:
+
+```sh
+docker run --detach --rm --name openai-llm-data-plane \
+  --group-add "$(id -g)" \
+  --env KONG_ROLE=data_plane \
+  --env KONG_DATABASE=off \
+  --env KONG_VITALS=off \
+  --env KONG_CLUSTER_MTLS=pki \
+  --env "KONG_CLUSTER_CONTROL_PLANE=$AIGW_CONTROL_PLANE:443" \
+  --env "KONG_CLUSTER_SERVER_NAME=$AIGW_CONTROL_PLANE" \
+  --env "KONG_CLUSTER_TELEMETRY_ENDPOINT=$AIGW_TELEMETRY:443" \
+  --env "KONG_CLUSTER_TELEMETRY_SERVER_NAME=$AIGW_TELEMETRY" \
+  --env KONG_CLUSTER_CERT=/etc/kong/certs/data-plane.crt \
+  --env KONG_CLUSTER_CERT_KEY=/etc/kong/certs/data-plane.key \
+  --env KONG_LUA_SSL_TRUSTED_CERTIFICATE=system \
+  --env KONG_KONNECT_MODE=on \
+  --volume "$PWD/certs:/etc/kong/certs:ro" \
+  --publish 8000:8000 \
+  --publish 8443:8443 \
+  kong/kong-ai-gateway:2.0.2
+```
+
+Confirm that the data plane connects:
+
+```sh
+kongctl get ai-gateway nodes --gateway-name "OpenAI LLM Gateway"
+```
+
+## Send a chat request
+
+Send an OpenAI-compatible request through the local proxy:
+
+```sh
+curl --no-progress-meter --fail-with-body \
+  --request POST http://localhost:8000/v1/chat/completions \
+  --header "Accept: application/json" \
+  --json '{
+    "model": "my-gpt-4o",
+    "messages": [
+      {"role": "user", "content": "Say this is a test!"}
+    ]
+  }'
+```
+
+A successful response contains a chat completion from `gpt-4o`.
+
+## Clean up
+
+Stop and remove the local data plane:
+
+```sh
+docker stop openai-llm-data-plane
+```
+
+Delete {{site.ai_gateway}} and its managed child resources:
+
+```sh
+kongctl delete -f ai-gateway.yaml
+```
+
+Delete the local certificate files when you no longer need them.
diff --git a/app/_indices/kongctl.yaml b/app/_indices/kongctl.yaml
index e24a958be6..67df548c2f 100644
--- a/app/_indices/kongctl.yaml
+++ b/app/_indices/kongctl.yaml
@@ -28,6 +28,7 @@ groups:
         items:
           - path: /kongctl/declarative/
           - path: /kongctl/supported-resources/
+          - path: /kongctl/manage-ai-gateway/
           - path: /kongctl/kongctl-and-deck/
       - title: Other References
         items:
diff --git a/app/_landing_pages/kongctl.yaml b/app/_landing_pages/kongctl.yaml
index 0872e51893..097581181f 100644
--- a/app/_landing_pages/kongctl.yaml
+++ b/app/_landing_pages/kongctl.yaml
@@ -30,7 +30,7 @@ rows:
             The tool provides both declarative and imperative style resource management capabilities along with
             other developer friendly features. 
 
-            The declarative configuration feature allows you to define API Platform infrastructure as code using a YAML based syntax and a state free reconciliation system. The tool supports a growing list of {{site.konnect_short_name}} resource types including Dev Portals, control planes, APIs, and more.
+            The declarative configuration feature lets you define API platform infrastructure as code using YAML and a stateless reconciliation system. kongctl manages APIs, Dev Portals, control planes, {{site.ai_gateway}}, {{site.event_gateway_short}}, organization, and {{site.konnect_catalog}} resources.
 
             kongctl also ships installable AI agent skills that help coding agents generate, review, and operate kongctl configuration from a repository.
             
@@ -92,6 +92,8 @@ rows:
             **AI Agent Skills**: Install bundled skills that help coding agents discover resource schemas, generate
             declarative configuration, build extensions, and preview changes with kongctl workflows.
 
+            **Audit Logs**: Pull a finite audit-log history, follow new organization events, or receive Dev Portal events with a webhook listener.
+
             **Flexible Authorization**: kongctl communicates with {{site.konnect_short_name}} via its APIs and supports authentication
             through browser-based device flow or personal access tokens.
 
@@ -293,6 +295,7 @@ rows:
                 - /kongctl/authentication/
                 - /kongctl/audit-logs/
                 - /kongctl/declarative/
+                - /kongctl/manage-ai-gateway/
                 - /kongctl/skills/
                 - /kongctl/supported-resources/
                 - /kongctl/kongctl-and-deck/
@@ -326,18 +329,21 @@ rows:
                 Yes, but with caution. Since kongctl's declarative engine is stateless and calculates changes by querying live {{site.konnect_short_name}} resources, concurrent processes operating on the same resources could conflict. Use namespace isolation to separate resources managed by different processes or teams.
             - q: What resources can kongctl manage declaratively?
               a: |
-                The list of {{site.konnect_short_name}} resources supported is growing. The current list includes (but not limited to):
+                kongctl manages these {{site.konnect_short_name}} resource families:
                 * **APIs**: Including versions, publications, implementations, and documents
                 * **Dev Portals**: Including pages, teams, snippets, customizations, authentication strategies, and custom domains
                 * **Control planes**: For {{site.base_gateway}} control plane management _and_ decK integration
+                * **{{site.ai_gateway}}**: Including Model Providers, Auth Strategies, Policies, Agents, Consumers, Models, MCP Servers, Config Stores, secrets, Vaults, and data-plane certificates
+                * **{{site.event_gateway_short}}**: Including clusters, listeners, policies, certificates, schema registries, and keys
+                * **{{site.konnect_catalog}} and organization**: Including Catalog services, teams, roles, and custom dashboards
 
-                Support for additional resource types is planned for future releases.
+                Run `kongctl explain` for the version-specific resource list and see the [declarative resource reference](/kongctl/supported-resources/).
             - q: How does kongctl authentication work?
               a: |
                 kongctl supports two authentication methods:
 
                 * **Device Flow (Recommended)**: Run `kongctl login` to authenticate via your browser. Tokens are stored locally and refreshed automatically.
-                * **Personal Access Token**: Use the `--pat` flag or `KONGCTL_DEFAULT_KONNECT_PAT` environment variable for automation scenarios like CI/CD pipelines.
+                * **Personal or system account access token**: Create PATs and sPATs with kongctl, then use the `--pat` flag or `KONGCTL_DEFAULT_KONNECT_PAT` environment variable for automation.
 
                 Configuration and device flow authentication credentials are stored in `$XDG_CONFIG_HOME/kongctl/` (typically `~/.config/kongctl/`).
             - q: Can I use kongctl in CI/CD pipelines?
@@ -379,6 +385,8 @@ rows:
             - text: kongctl releases and changelog
               type: github
               url: https://github.com/kong/kongctl/releases
+            - text: Hands-on kongctl learning guide
+              url: https://kong.github.io/kongctl/
             - text: Announcement blog
               type: blog
               url: https://konghq.com/blog/product-releases/kongctl
diff --git a/app/_landing_pages/konnect.yaml b/app/_landing_pages/konnect.yaml
index bc9d0886a3..68b780dc08 100644
--- a/app/_landing_pages/konnect.yaml
+++ b/app/_landing_pages/konnect.yaml
@@ -182,6 +182,7 @@ rows:
               blocks:
               - type: unordered_list
                 items:
+                    - "[kongctl](/kongctl/): Manage {{site.konnect_short_name}} resources with imperative commands or declarative, plan-based workflows"
                     - "[decK](/deck/): Manage {{site.base_gateway}} configuration in {{site.konnect_short_name}} through declarative state files"
                     - "[Terraform](/terraform/): Manage infrastructure as code and automated deployments to streamline setup and configuration of {{site.konnect_short_name}}, {{site.base_gateway}}, and {{site.mesh_product_name}}"
                     - "[KIC](/kubernetes-ingress-controller/): Manage ingress traffic and routing rules for your services"
diff --git a/app/kongctl/adopt/ai-gateway.md b/app/kongctl/adopt/ai-gateway.md
index 23ac99e192..b811e3b432 100644
--- a/app/kongctl/adopt/ai-gateway.md
+++ b/app/kongctl/adopt/ai-gateway.md
@@ -17,6 +17,10 @@ breadcrumbs:
 related_resources:
   - text: kongctl adopt commands
     url: /kongctl/adopt/
+  - text: Manage an AI Gateway with kongctl
+    url: /kongctl/manage-ai-gateway/
+  - text: Declarative configuration with kongctl
+    url: /kongctl/declarative/
 ---
 
 Apply the KONGCTL-namespace label to an existing {{site.konnect_short_name}} {{site.ai_gateway}} that is not currently managed by kongctl.
diff --git a/app/kongctl/adopt/api.md b/app/kongctl/adopt/api.md
index 667bf5547f..658bc02c70 100644
--- a/app/kongctl/adopt/api.md
+++ b/app/kongctl/adopt/api.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/adopt/auth-strategy.md b/app/kongctl/adopt/auth-strategy.md
index df42cc2cf9..215b486865 100644
--- a/app/kongctl/adopt/auth-strategy.md
+++ b/app/kongctl/adopt/auth-strategy.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/adopt/control-plane.md b/app/kongctl/adopt/control-plane.md
index c456c4f9a4..e94c2335bd 100644
--- a/app/kongctl/adopt/control-plane.md
+++ b/app/kongctl/adopt/control-plane.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/adopt/konnect.md b/app/kongctl/adopt/konnect.md
index 2698a4cd48..c497ca3271 100644
--- a/app/kongctl/adopt/konnect.md
+++ b/app/kongctl/adopt/konnect.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/adopt/organization.md b/app/kongctl/adopt/organization.md
index a463b5050d..417d523e43 100644
--- a/app/kongctl/adopt/organization.md
+++ b/app/kongctl/adopt/organization.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/adopt/portal.md b/app/kongctl/adopt/portal.md
index 5a132f169d..46cb44b829 100644
--- a/app/kongctl/adopt/portal.md
+++ b/app/kongctl/adopt/portal.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/api/delete.md b/app/kongctl/api/delete.md
index 134db73878..ca067dc7d9 100644
--- a/app/kongctl/api/delete.md
+++ b/app/kongctl/api/delete.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/api/get.md b/app/kongctl/api/get.md
index 9fb28bc67f..62d4e7df70 100644
--- a/app/kongctl/api/get.md
+++ b/app/kongctl/api/get.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/api/patch.md b/app/kongctl/api/patch.md
index 0f08194fa3..5316c8e253 100644
--- a/app/kongctl/api/patch.md
+++ b/app/kongctl/api/patch.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/api/post.md b/app/kongctl/api/post.md
index 925b7ef9f9..5fd978c626 100644
--- a/app/kongctl/api/post.md
+++ b/app/kongctl/api/post.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/api/put.md b/app/kongctl/api/put.md
index 83cbeddc1d..bf17b14814 100644
--- a/app/kongctl/api/put.md
+++ b/app/kongctl/api/put.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/apply/konnect.md b/app/kongctl/apply/konnect.md
index e869afec2d..42b2ba2920 100644
--- a/app/kongctl/apply/konnect.md
+++ b/app/kongctl/apply/konnect.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/audit-logs.md b/app/kongctl/audit-logs.md
index 7c94b1ec2f..fadfea2ee1 100644
--- a/app/kongctl/audit-logs.md
+++ b/app/kongctl/audit-logs.md
@@ -1,7 +1,9 @@
 ---
-title: Listen to {{site.konnect_short_name}} audit logs with kongctl
+title: Manage {{site.konnect_short_name}} audit logs with kongctl
 
-description: Learn how to use kongctl to listen to {{site.konnect_short_name}} audit logs.
+description: >-
+  Pull, follow, and listen to {{site.konnect_short_name}} audit logs with
+  kongctl.
 
 content_type: reference
 layout: reference
@@ -24,7 +26,7 @@ related_resources:
     url: /kongctl/declarative/
 next_steps:
   - text: Example declarative configurations
-    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative
+    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative
   - text: Learn about managing declarative configuration with kongctl
     url: /kongctl/declarative/
   - text: Learn about kongctl authorization options
@@ -39,11 +41,14 @@ next_steps:
     url: /konnect-api/
 ---
 
-This page documents the {{site.konnect_short_name}} audit-log listener feature in kongctl,
-including detached process management with `kongctl ps`.
+This page explains how to retrieve organization audit logs and receive audit-log
+webhooks with kongctl.
 
 kongctl can:
 
+- Pull organization audit logs on demand.
+- Retrieve every cursor page in a result set.
+- Follow new organization audit logs until interrupted.
 - Create a {{site.konnect_short_name}} audit-log destination.
 - Configure the regional {{site.konnect_short_name}} audit-log webhook.
 - Start a local HTTP listener to receive webhook events.
@@ -51,8 +56,6 @@ kongctl can:
 - Optionally stream events to STDOUT.
 - Optionally run the listener detached in the background.
 
-The feature is exposed through `listen` and `tail`.
-
 ## Command forms
 
 Supported forms ({{site.konnect_short_name}}-first):
@@ -63,12 +66,143 @@ Supported forms ({{site.konnect_short_name}}-first):
 - `kongctl tail`
 - `kongctl tail audit-logs`
 - `kongctl tail konnect audit-logs`
+- `kongctl tail audit-logs listener`
+- `kongctl get audit-logs`
+- `kongctl get konnect audit-logs`
+- `kongctl get audit-logs destinations`
+- `kongctl get audit-logs destination <id|name>`
+- `kongctl get audit-logs webhook`
+- `kongctl ps`
+
+Use `get audit-logs` to retrieve a finite set of organization audit logs.
+kongctl follows cursor pagination automatically.
+
+Use `tail audit-logs` to retrieve a five-minute catch-up window and then poll
+for new organization audit logs until interrupted. This command is equivalent
+to `kongctl get audit-logs --since 5m --follow`.
 
-Important:
+Use `listen audit-logs` to create a temporary webhook destination and start a
+local listener. Use `tail audit-logs listener` for the same webhook workflow
+with records streamed to STDOUT.
+
+The listener commands have these requirements:
 
 - Provide the endpoint from either `--endpoint` or `--public-url` + `--path`.
-- `--jq` requires `--tail`.
-- `--detach` is not compatible with `--tail`.
+- `--endpoint` must contain the complete public listener URL and path.
+- Listener `--jq` requires listener `--tail`.
+- Listener `--detach` isn't compatible with listener `--tail`.
+
+## Pull organization audit logs
+
+Retrieve the 50 most recent events:
+
+```sh
+kongctl get audit-logs
+```
+
+Retrieve the last 24 hours as JSONL:
+
+```sh
+kongctl get audit-logs --since 24h --output jsonl > audit-logs.jsonl
+```
+
+Use inclusive RFC3339 bounds and an event type filter:
+
+```sh
+kongctl get audit-logs \
+  --start-time 2026-08-23T00:00:00Z \
+  --end-time 2026-08-24T00:00:00Z \
+  --type authorization
+```
+
+Supported event types are `authentication`, `authorization`, and
+`gateway_access`. Complete API records include their ED25519 signatures.
+kongctl doesn't verify signatures or retrieve JWKS.
+
+### Pagination and limits
+
+`--page-size` controls the maximum number of records requested in each API
+call. It defaults to 100 and accepts values from 1 through 1,000. kongctl
+continues through the returned cursor until it reaches the final page.
+
+`--limit` controls the total records returned by the client. It defaults to 50
+when you don't specify a time window. Time-window queries are unlimited unless
+you specify `--limit`. Set `--limit 0` explicitly for unlimited retrieval.
+
+JSON and YAML output include `metadata.count` and `metadata.truncated`.
+`truncated` is `true` when a limit stops collection while more records exist.
+
+### Time filters
+
+`--start-time` and `--end-time` accept inclusive RFC3339 timestamps. `--since`
+accepts a Go duration, such as `30m` or `24h`, and can't be combined with an
+absolute bound. kongctl resolves `--since` once at startup for finite pulls.
+
+Go durations don't support `d` or `w`. Use `24h` for one day and `168h` for
+one week.
+
+### Output and partial failures
+
+Finite pulls support `text`, `json`, `yaml`, and `jsonl`:
+
+- JSON and YAML are buffered and written after every required page succeeds.
+- JSONL writes completed pages immediately. If a later page fails, STDOUT
+  contains a partial collection and kongctl exits with a nonzero status.
+- Text output provides a compact summary. Use repeated
+  `--columns HEADER=.field` flags to select fields.
+- JSON and YAML apply `--jq` to the output envelope. JSONL applies it to each
+  record independently.
+
+Automation must check the exit status instead of relying on the output file's
+presence:
+
+```sh
+if kongctl get audit-logs --since 24h --output jsonl > audit-logs.jsonl; then
+  echo "Audit-log collection completed"
+else
+  echo "Audit-log collection failed or is partial" >&2
+  exit 1
+fi
+```
+
+## Follow organization audit logs
+
+Start with a five-minute catch-up and continue polling:
+
+```sh
+kongctl tail audit-logs
+```
+
+Equivalent forms are:
+
+```sh
+kongctl get audit-logs --since 5m --follow
+kongctl get audit-logs --since 5m -F
+kongctl tail konnect audit-logs
+```
+
+Follow mode supports `text` and `jsonl`. `--poll-interval` defaults to 10
+seconds. Press Ctrl-C to stop it.
+
+Each successful polling cycle records a checkpoint. The next cycle overlaps
+that checkpoint by one minute, deduplicates records by signature or record
+hash, and emits new records in timestamp order. Temporary network, rate-limit,
+and server errors preserve the checkpoint and use exponential backoff capped
+at one minute. Non-retryable authentication, authorization, and client errors
+stop the command with a nonzero status.
+
+## Migrate webhook tail commands
+
+`tail audit-logs` now follows the organization pull API. Add the `listener`
+child to use the previous webhook-based behavior:
+
+```sh
+kongctl tail audit-logs listener \
+  --endpoint https://example.com/audit-logs \
+  --authorization "Bearer <token>"
+```
+
+`kongctl listen` and `kongctl listen audit-logs` are unchanged.
 
 ## End-to-end flow
 
@@ -118,17 +252,19 @@ No additional kongctl event envelope is added.
 
 ## Tailing and jq
 
-Use `tail` to stream records to STDOUT:
+Use the webhook listener child to stream records to STDOUT:
 
 ```shell
-kongctl tail --endpoint https://example.tld/audit-logs
+kongctl tail audit-logs listener \
+  --endpoint https://example.com/audit-logs \
+  --authorization "Bearer <token>"
 ```
 
 Filter JSON records with `jq` expression support:
 
 ```shell
-kongctl tail \
-  --endpoint https://example.tld/audit-logs \
+kongctl tail audit-logs listener \
+  --endpoint https://example.com/audit-logs \
   --log-format json \
   --jq '{ts:.event_ts, name, request:(.request // null)}'
 ```
@@ -275,4 +411,7 @@ tail -n 200 ~/.config/kongctl/logs/kongctl-listener-${pid}.log
 
 - Event file retention and rotation are not implemented yet.
 - Replay jobs are not implemented yet.
-- `kongctl ps` currently manages tracked detached processes only.
\ No newline at end of file
+- `kongctl ps` currently manages tracked detached processes only.
+- Pull and follow cover organization audit logs. Dev Portal audit logs remain
+  webhook-based.
+- Audit-log retention is controlled by the service.
diff --git a/app/kongctl/authentication.md b/app/kongctl/authentication.md
index 105221539d..08d22325f4 100644
--- a/app/kongctl/authentication.md
+++ b/app/kongctl/authentication.md
@@ -99,11 +99,84 @@ System Access Tokens (sPAT). PATs grant access to APIs as your personal user acc
 sPATs grant access based on the permissions of a system account, which may be more
 limited than a user account. 
 
-Use the {{site.konnect_short_name}} UI to create the token type of your choice, and 
-copy the secret value:
-- Create a PAT in the [personal access token page](https://cloud.konghq.com/global/account/tokens)
-- Create an sPAT in the [system accounts page](https://cloud.konghq.com/global/account/system-tokens)
-  or with the [System Accounts API](/api/konnect/identity/#/operations/post-system-accounts-id-access-tokens)
+You can manage PATs and sPATs directly with kongctl. You can also create them
+in the {{site.konnect_short_name}} UI:
+
+- Create a PAT on the
+  [personal access token page](https://cloud.konghq.com/global/account/tokens).
+- Create an sPAT on the
+  [system accounts page](https://cloud.konghq.com/global/account/system-tokens).
+
+## Manage personal access tokens
+
+Create a PAT for the authenticated user:
+
+```sh
+kongctl create pat --name ci --expires-in 30d --output token
+```
+
+You must provide exactly one expiration option:
+
+- `--expires-in` accepts a duration from 1 through 365 days.
+- `--expires-at` accepts an RFC3339 timestamp from 1 through 365 days in the
+  future.
+
+The token value is returned only by the create operation. Store it in a secret
+manager immediately. `get` and `list` output contain safe token metadata and
+never reveal the token value.
+
+Use the `env` output format to print an export command for the active profile:
+
+```sh
+kongctl create pat --name local --expires-in 7d --output env
+```
+
+List PAT metadata or retrieve one token record by ID or exact name:
+
+```sh
+kongctl get pat
+```
+
+```sh
+kongctl get pat <id-or-name>
+```
+
+Delete a PAT:
+
+```sh
+kongctl delete pat <id-or-name> --auto-approve
+```
+
+## Manage system account access tokens
+
+Create an sPAT by selecting its system account by name:
+
+```sh
+kongctl create spat \
+  --system-account-name ci-bot \
+  --name deployment \
+  --expires-in 30d \
+  --output env
+```
+
+You can use `--system-account-id` instead of `--system-account-name`. sPATs
+have the same expiration limits and one-time secret output behavior as PATs.
+
+List, retrieve, or delete sPAT metadata within a system account:
+
+```sh
+kongctl get spat --system-account-name ci-bot
+```
+
+```sh
+kongctl get spat deployment --system-account-name ci-bot
+```
+
+```sh
+kongctl delete spat deployment \
+  --system-account-name ci-bot \
+  --auto-approve
+```
 
 ### Configure authentication via flag
 
diff --git a/app/kongctl/config.md b/app/kongctl/config.md
index b93499fef8..1a5fba09cb 100644
--- a/app/kongctl/config.md
+++ b/app/kongctl/config.md
@@ -107,6 +107,69 @@ default:
     region: eu
 ```
 
+## Configure command output
+
+Most resource commands support `text`, `json`, and `yaml` output. Text
+output is optimized for reading in a terminal and can omit fields or truncate
+long values. Use JSON or YAML when automation needs the complete response.
+
+Configure the default output format for a profile:
+
+```yaml
+default:
+  output: json
+```
+
+Text output has two profile settings:
+
+{% table %}
+columns:
+  - title: Configuration path
+    key: path
+  - title: Flag
+    key: flag
+  - title: Values
+    key: values
+  - title: Behavior
+    key: behavior
+rows:
+  - path: "`text.layout`"
+    flag: "`--text-layout`"
+    values: "`compact`, `auto`, `wide`"
+    behavior: Controls how many safe fields static text tables display.
+  - path: "`text.id-format`"
+    flag: "`--text-id-format`"
+    values: "`compact`, `full`"
+    behavior: Controls whether UUID columns are shortened or shown in full.
+{% endtable %}
+
+For example:
+
+```yaml
+default:
+  output: text
+  text:
+    layout: auto
+    id-format: full
+```
+
+`compact` is the default layout. `auto` adds fields when the output is a
+wide enough terminal and otherwise uses the compact layout. `wide` selects
+every safe text field. The default ID format is `compact`.
+
+On commands that support it, repeat `--columns HEADER=.field` to replace the
+built-in text columns:
+
+```sh
+kongctl get apis \
+  --columns NAME=.name \
+  --columns UPDATED=.updated_at
+```
+
+`--columns` works only with text output and can't be combined with `--jq`.
+Use `--jq` with JSON or YAML output when you need to transform structured
+output.
+
 ## Environment variables
 
 When values are loaded via environment variables, the variable names
@@ -121,8 +184,9 @@ KONGCTL_DEFAULT_KONNECT_REGION=eu
 ```
 
 {:.info}
-> **Note**: The `KONGCTL_` prefix is for configuring the kongctl CLI itself.
-> To inject environment variable values into declarative resource configuration files, use the [`!env` YAML tag](/kongctl/declarative/#loading-values-from-environment-variables) instead.
+> **Note:** The `KONGCTL_` prefix configures the kongctl CLI. To inject an
+> environment variable into a declarative resource, use the
+> [`!env` YAML tag](/kongctl/declarative/#loading-values-from-environment-variables).
 
 
 ## Configuration file
diff --git a/app/kongctl/declarative.md b/app/kongctl/declarative.md
index 6c488d962e..e3a495377d 100644
--- a/app/kongctl/declarative.md
+++ b/app/kongctl/declarative.md
@@ -27,10 +27,10 @@ related_resources:
   - text: Troubleshooting kongctl
     url: /kongctl/troubleshooting/
   - text: Examples directory
-    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/
+    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/
 next_steps:
   - text: Example declarative configurations
-    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative
+    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative
   - text: Use kongctl with AI agent skills
     url: /kongctl/skills/
   - text: Learn about supported resources
@@ -286,11 +286,15 @@ of them support child resources underneath them.
 - `portal.email_config`
 - `portal.email_templates`
 - `ai_gateway.model_providers`
-- `ai_gateway.models`
+- `ai_gateway.auth_strategies`
 - `ai_gateway.policies`
+- `ai_gateway.agents`
 - `ai_gateway.consumers`
+- `ai_gateway.consumer_groups`
+- `ai_gateway.models`
 - `ai_gateway.mcp_servers`
-- `ai_gateway.agents`
+- `ai_gateway.config_stores`
+- `ai_gateway.vaults`
 
 See the [kongctl declarative resource reference](/kongctl/supported-resources/) for more details on supported resources.
 
@@ -335,6 +339,30 @@ api_publications:
     portal_id: !ref main-portal
 ```
 
+### Configuration sources
+
+Pass local files, directories, standard input, or HTTP and HTTPS URLs with
+`--filename` or `-f`. Repeat the flag to combine sources. Use
+`--recursive` to discover YAML files below a directory.
+
+```sh
+kongctl plan \
+  -f ./shared.yaml \
+  -f ./environments/production \
+  -f https://config.example.com/portals.yaml
+```
+
+Relative `!file` paths are resolved from the source that contains the tag.
+For remote sources, kongctl downloads referenced relative files into the
+remote-file save directory. Use `--remote-file-save-dir` to select that
+directory and `--force` to replace existing downloads.
+
+Remote authentication defaults to automatic behavior. kongctl sends the
+active {{site.konnect_short_name}} token only to HTTPS
+{{site.konnect_short_name}} API hosts. It doesn't send the token to arbitrary
+hosts. Use `--remote-auth none` when the source must be fetched without
+authentication.
+
 ## kongctl metadata
 
 The kongctl section provides metadata for resource management.
@@ -433,8 +461,11 @@ These flags help prevent accidentally operating on unexpected namespaces, especi
 
 ## External resources and namespaces
 
-External resources (`_external` pseudo-resource) are references to {{site.konnect_short_name}} objects that are managed elsewhere
-but are "selected" by the kongctl declarative engine so they can be referenced by other resources under management.
+External resources are {{site.konnect_short_name}} objects managed elsewhere
+but selected by kongctl for use by managed resources. Use `_external` when
+the object needs a reusable declarative `ref` or managed children. Use
+`!lookup` to resolve an existing object directly in a relationship field.
+`!external` is an exact alias for `!lookup`.
 
 ```yaml
 # External portal definition - this tells kongctl that this portal
@@ -447,14 +478,50 @@ portals:
           name: "Shared Developer Portal"
 ```
 
-Because kongctl doesn't own those resources:
-- External resources **cannot** declare kongctl metadata. Supplying `kongctl.namespace` or `kongctl.protected`
-  on an external resource results in a parsing error. File-level defaults are ignored for externals.
-- External references do **not** add their namespaces to sync planning. Only namespaces from managed parent
-  resources are considered when sync mode calculates deletes.
-- Child resources (portal pages, customizations, etc.) are still planned by resolving the external parent's {{site.konnect_short_name}} ID.
-  Ensure the owning team labels the parent (for example via `kongctl adopt`) so the ID can be resolved, but you do not
-  need to (and cannot) assign a namespace to the external definition itself.
+Catalog APIs and application Auth Strategies can also be external. An external
+API can own managed versions, publications, implementations, and documents:
+
+```yaml
+apis:
+  - ref: shared-api
+    _external:
+      selector:
+        matchFields:
+          name: Shared API
+    versions:
+      - ref: shared-api-v2
+        version: v2
+        spec: !file ./openapi.yaml
+```
+
+Because kongctl doesn't own external resources:
+
+- External resources can't declare `kongctl` metadata. File-level defaults
+  are ignored for them.
+- External references don't add namespaces to sync planning.
+- kongctl never changes or deletes the external parent.
+- Child collections explicitly included in sync scope are fully reconciled,
+  including stale child deletion. Omitted child collections remain untouched.
+
+Inline lookups use a `field:value` scalar or a mapping. The target resource is
+inferred from the relationship field:
+
+```yaml
+ai_gateway_model_providers:
+  - ref: shared-provider
+    ai_gateway: !lookup {name: shared-ai-gateway}
+    name: openai
+    type: openai
+    display_name: OpenAI
+    config: {}
+```
+
+A mapping can contain multiple selectors, all of which must match. An
+`id:<uuid>` selector binds a known ID directly and can't be combined with
+another selector. Other selectors must match exactly one resource.
+
+Lookups run during planning and are cached for that plan. Saved plans contain
+the resolved IDs instead of tag placeholders.
 
 ## Resources managed by decK
 
@@ -505,6 +572,129 @@ Important notes for decK integration:
 
 For more information, see [kongctl and decK](/kongctl/kongctl-and-deck/).
 
+## Manage {{site.ai_gateway}} declaratively
+
+kongctl manages {{site.ai_gateway}} resources in
+{{site.konnect_product_name}}. The supported declarative model includes:
+
+- {{site.ai_gateway}} instances and data-plane certificates
+- Model Providers and Models
+- Auth Strategies and Policies
+- Agents and MCP Servers
+- Consumers, Consumer Credentials, and Consumer Groups
+- Config Stores, Config Store Secrets, and Vaults
+
+{{site.ai_gateway}} nodes are imperative, read-only resources. Inspect them with
+`kongctl get ai-gateway nodes`; don't include them in declarative
+configuration.
+
+Declare children under their gateway when one file owns the complete hierarchy:
+
+```yaml
+ai_gateways:
+  - ref: shared-ai-gateway
+    name: shared-ai-gateway
+    display_name: Shared AI Gateway
+    deployment_type: hybrid
+    model_providers:
+      - ref: openai
+        name: openai
+        display_name: OpenAI
+        type: openai
+        config: {}
+    models:
+      - ref: gpt-4o
+        name: gpt-4o
+        display_name: GPT-4o
+        type: model
+        formats:
+          - type: openai
+        targets:
+          - name: gpt-4o
+            provider: openai
+            config:
+              type: openai
+```
+
+Root-level child declarations use a parent field such as `ai_gateway`,
+`ai_gateway_consumer`, or `ai_gateway_config_store`. The value can be a
+`ref`, `!ref`, or supported `!lookup`:
+
+```yaml
+ai_gateway_policies:
+  - ref: shared-rate-limit
+    ai_gateway: !lookup {name: shared-ai-gateway}
+    name: shared-rate-limit
+    display_name: Shared rate limit
+    type: rate-limiting-advanced
+    enabled: true
+    config: {}
+```
+
+Child collections follow the normal sync-scope rules. Omit a collection to
+leave it unmanaged, or provide an empty collection under an identified parent
+to delete its managed children. Root-level empty {{site.ai_gateway}} child
+collections are rejected because they don't identify a parent.
+
+Policy `display_name` values must be explicit. Model targets identify their
+Model Provider by API `name`. Agents, Models, and MCP Servers reference Auth
+Strategies through `access.auth_strategies` and can reference same-gateway
+Policies with `!ref`.
+
+Use `--include-child-resources` when dumping {{site.ai_gateway}}. Direct
+{{site.ai_gateway}}
+child selectors are not supported:
+
+```sh
+kongctl dump declarative \
+  --resources ai_gateways \
+  --include-child-resources
+```
+
+For the complete resource model, see
+[kongctl declarative resource reference](/kongctl/supported-resources/#ai-gateway).
+For the product workflow, see
+[Use kongctl to manage {{site.ai_gateway}}](/ai-gateway/kongctl/).
+
+## Configuration templates
+
+Define reusable configuration blocks under the top-level `_templates` key.
+Select one from a resource or nested configuration block with `_extends`:
+
+```yaml
+_templates:
+  private-portal:
+    authentication_enabled: true
+    default_api_visibility: private
+    labels:
+      managed-by: kongctl
+
+portals:
+  - _extends: private-portal
+    ref: developer-portal
+    name: Developer Portal
+    labels:
+      team: platform
+```
+
+All files supplied to one command share one template registry. Template names
+must be unique, and a template can extend another template. Each consuming
+block can extend exactly one template. Unknown names and inheritance cycles are
+errors.
+
+Consumer values take precedence:
+
+- Objects merge recursively.
+- Scalars, arrays, values of a different type, and explicit `null` replace
+  inherited values.
+- Arrays never append or merge by element.
+- Omitted keys retain the inherited value.
+
+Templates expand before schema validation and sync-scope capture. An inherited
+empty child collection has the same deletion behavior as one written directly.
+Tags in a template use the template definition file's context. `_templates`
+is shared across sources, while `_defaults` remains automatic and file-local.
+
 ## YAML tags
 
 YAML tags are like preprocessors for YAML file data. They allow you to
@@ -513,6 +703,33 @@ from environment variables, and extract specific values from structured
 data. Over time more tags may be added to support various functions and
 use cases.
 
+Relationship tags include:
+
+- `!ref`: Reference a resource declared in the same configuration.
+- `!lookup`: Resolve one existing remote resource during planning.
+- `!external`: An exact alias for `!lookup`.
+
+`kongctl explain <resource>.<field>` reports the supported tags, target
+resource type, selectors, and required scope for a field.
+
+### Compose YAML tags
+
+A lookup mapping can use `!env` directly as a selector value:
+
+```yaml
+portal_id: !lookup
+  name: !env PORTAL_NAME
+```
+
+`!secret` can use `!env` as its source or as an item in `parts`.
+Other nested combinations, including `!file` or `!ref` inside a lookup, are
+rejected. Use mapping syntax when nesting a tag; the scalar
+`field:value` lookup form can't contain another tag.
+
+kongctl resolves a nested lookup's environment value during planning. Saved
+plans retain only the resolved resource ID and don't repeat the lookup during
+execution.
+
 ### Loading file content to YAML fields
 
 Load the entire content of a file as a string:
@@ -657,7 +874,7 @@ api_documents:
 reading the requested field path.
 
 A runnable example is available in
-[docs/examples/declarative/env/](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/env/).
+[docs/examples/declarative/env/](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/env/).
 
 #### !env behavior
 
@@ -685,30 +902,133 @@ A runnable example is available in
 
 ## Write-only secret fields
 
-Some {{site.konnect_short_name}} APIs accept secret values on create or update but do not return
-them from `get` or `list` responses. Common examples include:
+Some {{site.konnect_short_name}} APIs accept secret values but don't return them
+from `get` or `list`. Common examples include:
 
 - Portal identity provider `config.client_secret`
 - DCR provider secrets such as `dcr_token`, `api_key`, and
   `initial_client_secret`
+- {{site.ai_gateway}} Model Provider authentication values
+- {{site.ai_gateway}} Auth Strategy OpenID Connect `config.client_secret`
+- {{site.ai_gateway}} Vault authentication credentials
+- {{site.ai_gateway}} Consumer Credential `api_key`
 - Event Gateway schema registry authentication `password`
 
-For these fields, kongctl prefers idempotent planning over perpetual
-updates. When the API doesn't expose the current value, the planner skips
-that field during diff calculation instead of assuming drift on every run.
+Secret material in a write-only field must use `!secret`. Literal secret
+values and eager `!file` values are rejected because they could enter a saved
+plan:
+
+```yaml
+client_secret: !secret
+  source: !env PORTAL_OIDC_CLIENT_SECRET
+```
+
+Compose public text with deferred secret sources by using `parts`:
+
+```yaml
+value: !secret
+  parts:
+    - "Bearer "
+    - !env AI_PROVIDER_TOKEN
+```
+
+Don't place secret material in literal parts. Saved plans retain source
+metadata, such as environment variable names, but never resolved values.
+Planning doesn't require the secret environment variables. Execution validates
+every source before making the first API change.
+
+Declaring a secret source and authorizing a write are separate operations.
+Creates send each configured secret once. To rotate an existing write-only
+field, select it while generating the plan:
+
+```sh
+kongctl plan -f config.yaml \
+  --write-secret workforce-idp#config.client_secret \
+  --output-file rotation.json
+```
+
+Select every configured secret on one resource by omitting the field:
+
+```sh
+kongctl plan -f config.yaml \
+  --write-secret workforce-idp \
+  --output-file rotation.json
+```
+
+Select every eligible secret in the configuration:
+
+```sh
+kongctl plan -f config.yaml \
+  --write-secrets \
+  --output-file rotation.json
+```
+
+Exact `--write-secret` selectors fail if the requested field isn't writable.
+`--write-secrets` is best effort and reports ineligible fields as warnings.
+A saved plan already contains its write intents, so write-selection flags can't
+be combined with `--plan`. Delete mode doesn't accept secret selection.
+
+The planner can't compare a write-only field with its remote value. Without a
+write selector, it omits the field and remains idempotent. Human-readable plans
+report `write requested` without displaying the value.
+
+{{site.ai_gateway}} Config Store Secrets are managed children. New secrets require a
+`value: !secret`; an existing secret can omit `value` to retain its current
+value. Use `--write-secret` or `--write-secrets` to rotate it. Imperative
+`get` and `list` operations return safe metadata and never reveal values.
+
+{{site.ai_gateway}} Consumer Credential `api_key` is create-only. Omit it to let
+{{site.konnect_short_name}} generate a key, or provide it with `!secret`
+while creating the credential. Rotate it by creating a replacement credential
+and deliberately removing the old one.
+
+## Sync scope and deletion safety
+
+`sync` reconciles only collections whose YAML keys are present:
+
+- An omitted root or child collection is ignored.
+- A populated collection creates or updates the declared resources and removes
+  other managed resources in that collection and namespace.
+- An empty root list, such as `apis: []`, requests deletion of managed
+  resources in the selected namespace.
+- Parent and child collections are independent. Omitting `pages` leaves
+  Portal Pages untouched; `pages: []` requests that the identified Portal
+  have no managed Pages.
+- Map-shaped children use `{}` as the empty collection. For example,
+  `email_templates: {}` requests no customized email templates.
+- Optional, delete-capable singletons such as `custom_domain`,
+  `email_config`, and `audit_log_webhook` use `{}` to request deletion.
+  Omission ignores the singleton and `null` is invalid.
+- Update-only singletons such as `customization` can't be deleted with
+  `{}`.
+- Empty child collections must be nested under an identified parent. A
+  root-level `api_documents: []` is invalid.
+
+For federated ownership, declare the managed or `_external` parent and include
+only the child collection owned by that configuration:
+
+```yaml
+portals:
+  - ref: shared-docs-portal
+    _external:
+      selector:
+        matchFields:
+          name: Shared Docs Portal
+    pages: []
+```
 
-This means:
+The external parent is never changed or deleted, but its explicitly scoped
+Pages are fully reconciled. Namespace defaults don't apply to the external
+parent; managed collections in the same input still use their namespaces.
 
-- The initial create or update still sends the configured secret value.
-- Re-applying the same declarative configuration will usually be a no-op
-  instead of planning an update forever.
-- Changing only a write-only secret may not be detectable from live state, so
-  `plan` may show no changes even though the configured secret value differs
-  from what is currently stored in {{site.konnect_short_name}}.
+Preview every destructive sync before approving it:
+
+```sh
+kongctl sync -f config.yaml --dry-run
+```
 
-When you need to rotate a write-only secret declaratively, make the change
-alongside another observable field, or recreate the resource if the API does
-not provide a safe observable signal for that update.
+For more examples, see [Synchronize configurations with
+kongctl](/kongctl/sync/).
 
 ## Commands reference
 
@@ -717,6 +1037,36 @@ Start with the following commands for most use cases:
 
 {% include_cached /kongctl/commands-reference-table.md %}
 
+Use the execution command that matches a saved plan's mode:
+
+- `kongctl apply --plan` accepts apply-mode plans.
+- `kongctl sync --plan` accepts sync-mode plans.
+- `kongctl delete --plan` accepts delete-mode plans.
+- `kongctl diff --plan` can inspect a plan from any mode.
+
+Use `adopt --overwrite-namespace` only when you intend to transfer a resource
+that already has a kongctl namespace label:
+
+```sh
+kongctl adopt api billing-api \
+  --namespace platform \
+  --overwrite-namespace
+```
+
+Use `--skip-defaults` to omit literal API defaults from a declarative dump.
+Use `--include-child-resources` to include children of the selected parent
+types:
+
+```sh
+kongctl dump declarative \
+  --resources portal,api,ai_gateways \
+  --include-child-resources \
+  --skip-defaults > konnect.yaml
+```
+
+`--skip-defaults` preserves explicit `null` and non-default values. It
+doesn't change planning, apply, sync, or Terraform import output.
+
 See the CLI help at `kongctl --help` for all possible commands, or check out the [kongctl CLI reference](/index/kongctl/#cli-reference) documentation.
 
 ## CI/CD integration
@@ -920,4 +1270,7 @@ Common field name errors:
 
 kongctl provides a global `--log-level` flag that you can pass with any command.
 
-See the [troubleshooting reference](/kongctl/troubleshooting/) for help resolving common issues, and see the [debugging reference](/kongctl/troubleshooting/#debugging) for more information on the debugging workflow.
\ No newline at end of file
+See the [troubleshooting reference](/kongctl/troubleshooting/) for help
+resolving common issues. See the [debugging
+reference](/kongctl/troubleshooting/#debugging) for more information on the
+debugging workflow.
diff --git a/app/kongctl/diff/konnect.md b/app/kongctl/diff/konnect.md
index adbfc32532..4536247aee 100644
--- a/app/kongctl/diff/konnect.md
+++ b/app/kongctl/diff/konnect.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/dump/declarative.md b/app/kongctl/dump/declarative.md
index 1e76c01643..98298948ff 100644
--- a/app/kongctl/dump/declarative.md
+++ b/app/kongctl/dump/declarative.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
@@ -20,7 +19,21 @@ related_resources:
     url: /kongctl/dump/
 ---
 
-Export declarative configuration.
+Export declarative configuration from {{site.konnect_short_name}}.
+
+Use `--include-child-resources` to include children of the selected parent
+resource types. Use `--skip-defaults` to omit literal API defaults while
+preserving explicit `null` and non-default values.
+
+To dump {{site.ai_gateway}} and its children, select the parent:
+
+```sh
+kongctl dump declarative \
+  --resources ai_gateways \
+  --include-child-resources
+```
+
+Direct {{site.ai_gateway}} child selectors aren't supported.
 
 
 ## Command usage
diff --git a/app/kongctl/dump/tf-import.md b/app/kongctl/dump/tf-import.md
index d89ac64e77..f029afaa5d 100644
--- a/app/kongctl/dump/tf-import.md
+++ b/app/kongctl/dump/tf-import.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/explain/index.md b/app/kongctl/explain/index.md
index 08906dd539..d98c310619 100644
--- a/app/kongctl/explain/index.md
+++ b/app/kongctl/explain/index.md
@@ -21,9 +21,16 @@ related_resources:
     url: /kongctl/get-started/
 ---
 
-Explain shows the declarative schema for a supported resource type or field path.
+Explain shows the declarative schema for a supported resource type or field
+path.
 
-Use text output for human-readable field summaries. Use json or yaml output to retrieve the same machine-readable schema document in different serializations.
+Run `kongctl explain` without a path to list every available declarative
+resource path. Use text output for human-readable field summaries. Use JSON or
+YAML to retrieve the same machine-readable schema.
+
+Lower-maturity resources and operations include a maturity label. Unlabeled
+resources are GA. JSON and YAML schema output exposes maturity through
+`x-kongctl-maturity`.
 
 ## Command usage
 
diff --git a/app/kongctl/get/ai-gateway.md b/app/kongctl/get/ai-gateway.md
index da65e94ca4..189b922035 100644
--- a/app/kongctl/get/ai-gateway.md
+++ b/app/kongctl/get/ai-gateway.md
@@ -17,6 +17,10 @@ breadcrumbs:
 related_resources:
   - text: kongctl get commands
     url: /kongctl/get/
+  - text: Manage an AI Gateway with kongctl
+    url: /kongctl/manage-ai-gateway/
+  - text: kongctl declarative resource reference
+    url: /kongctl/supported-resources/#ai-gateway
 ---
 
 Use the `get` verb with the `ai-gateway` command to query {{site.konnect_short_name}} {{site.ai_gateway}}s.
@@ -48,9 +52,6 @@ rows:
   - command: |
       [kongctl get ai-gateway data-plane-certificates](#kongctl-get-ai-gateway-data-plane-certificates)
     description: "Use the `data-plane-certificates` command to list or retrieve data plane certificates for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
-  - command: |
-      [kongctl get ai-gateway identity-providers](#kongctl-get-ai-gateway-identity-providers)
-    description: "Use the `identity-providers` command to list or retrieve identity providers for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
   - command: |
       [kongctl get ai-gateway mcp-servers](#kongctl-get-ai-gateway-mcp-servers)
     description: "Use the `mcp-servers` command to list or retrieve MCP Servers for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
diff --git a/app/kongctl/get/api.md b/app/kongctl/get/api.md
index 81c3752ad9..f50e669e0b 100644
--- a/app/kongctl/get/api.md
+++ b/app/kongctl/get/api.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/audit-logs.md b/app/kongctl/get/audit-logs.md
index 5a10fed3c5..4f5ea26e88 100644
--- a/app/kongctl/get/audit-logs.md
+++ b/app/kongctl/get/audit-logs.md
@@ -1,12 +1,11 @@
 ---
 title: kongctl get audit-logs
-description: "Get audit logs."
+description: "Pull organization audit logs and inspect audit-log configuration."
 content_type: reference
 layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
@@ -19,9 +18,11 @@ breadcrumbs:
 related_resources:
   - text: kongctl get commands
     url: /kongctl/get/
+  - text: Manage audit logs with kongctl
+    url: /kongctl/audit-logs/
 ---
 
-Get audit logs.
+Pull organization audit logs or inspect webhook destinations and configuration.
 
 ## Command usage
 
diff --git a/app/kongctl/get/auth-strategy.md b/app/kongctl/get/auth-strategy.md
index fa02086720..5fe82c5e2b 100644
--- a/app/kongctl/get/auth-strategy.md
+++ b/app/kongctl/get/auth-strategy.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/catalog.md b/app/kongctl/get/catalog.md
index 9a875e1fb3..df34d0ff59 100644
--- a/app/kongctl/get/catalog.md
+++ b/app/kongctl/get/catalog.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/gateway.md b/app/kongctl/get/gateway.md
index ceaa548ae3..46b7a98fdf 100644
--- a/app/kongctl/get/gateway.md
+++ b/app/kongctl/get/gateway.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/index.md b/app/kongctl/get/index.md
index 80ce8be3ec..21eaafe9a0 100644
--- a/app/kongctl/get/index.md
+++ b/app/kongctl/get/index.md
@@ -23,6 +23,10 @@ related_resources:
 
 kongctl provides the following tools for retrieving resources and resource details:
 
+Text output is optimized for terminals and can omit fields. Use
+`--output json` or `--output yaml` for complete structured output. Use
+repeated `--columns HEADER=.field` flags to select custom text columns.
+
 {% table %}
 columns:
   - title: Command
diff --git a/app/kongctl/get/konnect.md b/app/kongctl/get/konnect.md
index 6025d260dd..823f8eb910 100644
--- a/app/kongctl/get/konnect.md
+++ b/app/kongctl/get/konnect.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/me.md b/app/kongctl/get/me.md
index 983b96260f..4cdc074c05 100644
--- a/app/kongctl/get/me.md
+++ b/app/kongctl/get/me.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/organization.md b/app/kongctl/get/organization.md
index 87ea1cdefe..8d271ca838 100644
--- a/app/kongctl/get/organization.md
+++ b/app/kongctl/get/organization.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/portal.md b/app/kongctl/get/portal.md
index 3717dd37c0..daef34a2f5 100644
--- a/app/kongctl/get/portal.md
+++ b/app/kongctl/get/portal.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/get/regions.md b/app/kongctl/get/regions.md
index 0d2de3ebf7..6ed55136a9 100644
--- a/app/kongctl/get/regions.md
+++ b/app/kongctl/get/regions.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/list/ai-gateway.md b/app/kongctl/list/ai-gateway.md
index 1aec1f2d8a..7043e388c0 100644
--- a/app/kongctl/list/ai-gateway.md
+++ b/app/kongctl/list/ai-gateway.md
@@ -17,6 +17,10 @@ breadcrumbs:
 related_resources:
   - text: kongctl list commands
     url: /kongctl/list/
+  - text: Manage an AI Gateway with kongctl
+    url: /kongctl/manage-ai-gateway/
+  - text: kongctl declarative resource reference
+    url: /kongctl/supported-resources/#ai-gateway
 ---
 
 Use the `list` verb with the `ai-gateway` command to list {{site.konnect_short_name}} {{site.ai_gateway}}s.
@@ -48,9 +52,6 @@ rows:
   - command: |
       [kongctl list ai-gateway data-plane-certificates](#kongctl-list-ai-gateway-data-plane-certificates)
     description: "Use the `data-plane-certificates` command to list or retrieve data plane certificates for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
-  - command: |
-      [kongctl list ai-gateway identity-providers](#kongctl-list-ai-gateway-identity-providers)
-    description: "Use the `identity-providers` command to list or retrieve identity providers for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
   - command: |
       [kongctl list ai-gateway mcp-servers](#kongctl-list-ai-gateway-mcp-servers)
     description: "Use the `mcp-servers` command to list or retrieve MCP Servers for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
diff --git a/app/kongctl/list/api.md b/app/kongctl/list/api.md
index 6cd7eb3213..e111fa3ad5 100644
--- a/app/kongctl/list/api.md
+++ b/app/kongctl/list/api.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/list/auth-strategy.md b/app/kongctl/list/auth-strategy.md
index b22ee631e3..bc53a6d26d 100644
--- a/app/kongctl/list/auth-strategy.md
+++ b/app/kongctl/list/auth-strategy.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/list/gateway.md b/app/kongctl/list/gateway.md
index b7c437b999..9309df41cc 100644
--- a/app/kongctl/list/gateway.md
+++ b/app/kongctl/list/gateway.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/list/index.md b/app/kongctl/list/index.md
index 3ed4ce7b14..ec48b0e84e 100644
--- a/app/kongctl/list/index.md
+++ b/app/kongctl/list/index.md
@@ -23,6 +23,10 @@ related_resources:
 
 kongctl provides the following tools for listing resources:
 
+Text output is optimized for terminals and can omit fields. Use
+`--output json` or `--output yaml` for complete structured output. Use
+repeated `--columns HEADER=.field` flags to select custom text columns.
+
 {% table %}
 columns:
   - title: Command
diff --git a/app/kongctl/list/konnect.md b/app/kongctl/list/konnect.md
index 7426d34493..5df91917d9 100644
--- a/app/kongctl/list/konnect.md
+++ b/app/kongctl/list/konnect.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/list/organization.md b/app/kongctl/list/organization.md
index 833dca4363..a87936afdb 100644
--- a/app/kongctl/list/organization.md
+++ b/app/kongctl/list/organization.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/list/portal.md b/app/kongctl/list/portal.md
index 7bad1e1761..01e23c470b 100644
--- a/app/kongctl/list/portal.md
+++ b/app/kongctl/list/portal.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/listen/audit-logs.md b/app/kongctl/listen/audit-logs.md
index c4b19c1f47..cc7f2245b8 100644
--- a/app/kongctl/listen/audit-logs.md
+++ b/app/kongctl/listen/audit-logs.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
@@ -18,6 +17,8 @@ breadcrumbs:
 related_resources:
   - text: kongctl listen commands
     url: /kongctl/listen/
+  - text: Manage audit logs with kongctl
+    url: /kongctl/audit-logs/
 ---
 
 Listen to the audit log stream.
@@ -25,4 +26,4 @@ Listen to the audit log stream.
 
 ## Command usage
 
-{% include_cached /kongctl/help/listen/audit-logs.md %}
\ No newline at end of file
+{% include_cached /kongctl/help/listen/audit-logs.md %}
diff --git a/app/kongctl/listen/konnect.md b/app/kongctl/listen/konnect.md
index 01a24c3ca5..cc0c39f33e 100644
--- a/app/kongctl/listen/konnect.md
+++ b/app/kongctl/listen/konnect.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/login/konnect.md b/app/kongctl/login/konnect.md
index 009ee61b88..ef0ea63942 100644
--- a/app/kongctl/login/konnect.md
+++ b/app/kongctl/login/konnect.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/logout/konnect.md b/app/kongctl/logout/konnect.md
index 2907ba0145..c609d0aca9 100644
--- a/app/kongctl/logout/konnect.md
+++ b/app/kongctl/logout/konnect.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/plan/konnect.md b/app/kongctl/plan/konnect.md
index 8f4efac5b6..cb31eedd7f 100644
--- a/app/kongctl/plan/konnect.md
+++ b/app/kongctl/plan/konnect.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/scaffold/index.md b/app/kongctl/scaffold/index.md
index 6661d91044..b8d150eb2d 100644
--- a/app/kongctl/scaffold/index.md
+++ b/app/kongctl/scaffold/index.md
@@ -21,9 +21,15 @@ related_resources:
     url: /kongctl/get-started/
 ---
 
-Scaffold emits a commented YAML starter configuration for a supported declarative resource path.
+Scaffold emits a commented YAML starter configuration for a supported
+declarative resource path.
 
-The output is intended to be edited and then used with declarative commands such as apply or sync.
+Run `kongctl scaffold` without a path to list the available resource paths.
+The output is intended to be edited and then used with declarative commands
+such as `apply` or `sync`.
+
+Scaffolds for beta or tech-preview resources begin with a maturity comment. GA
+scaffolds don't include a maturity warning.
 
 ## Command usage
 
diff --git a/app/kongctl/supported-resources.md b/app/kongctl/supported-resources.md
index 383bdbc969..29e3c42d6a 100644
--- a/app/kongctl/supported-resources.md
+++ b/app/kongctl/supported-resources.md
@@ -24,7 +24,7 @@ related_resources:
     url: /kongctl/declarative/
 next_steps:
   - text: Example declarative configurations
-    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative
+    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative
   - text: Learn about managing declarative configuration with kongctl
     url: /kongctl/declarative/
   - text: Learn about kongctl authorization options
@@ -69,6 +69,31 @@ _defaults:
     protected: false
 ```
 
+## Configuration templates
+
+Define reusable configuration blocks under the top-level `_templates` key and
+select one with `_extends`:
+
+```yaml
+_templates:
+  private-portal:
+    authentication_enabled: true
+    default_api_visibility: private
+
+portals:
+  - _extends: private-portal
+    ref: developer-portal
+    name: Developer Portal
+```
+
+Templates are shared across all sources loaded by one command. Consumer
+objects recursively override template objects. Scalars, arrays, explicit
+`null`, and values of a different type replace inherited values. Arrays don't
+append.
+
+See [Configuration templates](/kongctl/declarative/#configuration-templates)
+for discovery, inheritance, tag, and sync-scope behavior.
+
 ## YAML tags
 
 Use YAML tags in field values to load files or reference other resources.
@@ -79,10 +104,18 @@ Use YAML tags in field values to load files or reference other resources.
   Supports `VAR#extract.path` and `var`/`extract` map form.
 - `!ref`: Reference another declarative resource by `ref`.
   `resource-ref#field` is supported; the default field is `id`.
+- `!lookup`: Resolve an existing resource directly in a relationship field.
+- `!external`: An exact alias for `!lookup`.
+- `!secret`: Defer a write-only value until execution and keep the resolved
+  value out of saved plans.
 - `!ref` is intended for string fields.
 - `string (uuid)` and `array[string(uuid)]` annotations in this document describe API value types. 
   In declarative config, prefer `!ref` and avoid literal UUID values.
-- For unmanaged/external resources, prefer `_external.selector` and then reference that resource by `!ref` from other fields.
+- For reusable unmanaged resources or external parents with managed children,
+  use `_external.selector` and reference the resource with `!ref`.
+- For a one-off unmanaged relationship, use `!lookup`.
+- Sync never changes or deletes an external parent. Explicitly scoped child
+  collections are still fully reconciled.
 - Large text/spec fields are commonly loaded with `!file`.
 - `!file` paths are resolved relative to the config file and must remain within the configured base directory boundary.
 
@@ -101,6 +134,19 @@ apis:
         portal_id: !ref docs-portal
 ```
 
+Use mapping syntax to compose `!env` inside `!lookup` or `!external`, or
+inside `!secret`:
+
+```yaml
+portal_id: !lookup
+  name: !env PORTAL_NAME
+
+value: !secret
+  parts:
+    - "Bearer "
+    - !env AI_PROVIDER_TOKEN
+```
+
 ## Audit logs
 
 Audit log webhook destinations are organization-scoped {{site.konnect_short_name}} resources.
@@ -108,7 +154,7 @@ Declarative config supports them as external references so managed portal audit
 
 * [Reference for listening to audit logs with kongctl](/kongctl/audit-logs/)
 * [API specification](/api/konnect/audit-logs/)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/audit-logs)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/audit-logs)
 
 ```yaml
 audit-logs:
@@ -128,12 +174,14 @@ Audit log webhook destinations **cannot** declare kongctl metadata and are not c
 ## APIs
 
 * [API specification](/api/konnect/api-builder/#/operations/create-api)
-* [Example](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/basic/api.yaml)
+* [Example](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/basic/api.yaml)
 
 ```yaml
 apis:
   - ref: string
     name: string required (1-255 chars)
+    _external: # alternative to managed API fields
+      id: string # API UUID, or use selector.matchFields.name
     description: string (nullable)
     version: string (1-255 chars, nullable)
     slug: string (pattern: ^[\w-]+$, nullable)
@@ -155,14 +203,18 @@ apis:
         visibility: One of (public | private)
     implementations: # /api/konnect/api-builder/v3/#/operations/create-api-implementation
       - ref: string
-        type: service
+        type: service # optional when service is present
         service:
           id: string required (uuid) # prefer: !ref <gateway-service-ref>
           control_plane_id: string required (uuid) # prefer: !ref <control-plane-ref>
+      - ref: string
+        type: control_plane # optional when control_plane is present
+        control_plane:
+          control_plane_id: string required (uuid) # prefer: !ref <control-plane-ref>
     documents: # /api/konnect/api-builder/v3/#/operations/create-api-document
       - ref: string
         content: string required (markdown) # prefer: !file ./docs/page.md
-        title: string
+        title: string required unless content has a YAML frontmatter title
         slug: string (pattern: ^[\w-]+$)
         status: One of (published | unpublished)
         parent_document_id: string (uuid, nullable) # prefer: !ref <document-ref>
@@ -179,10 +231,16 @@ API specifications must be declared on API versions with `versions[].spec` or
 root-level `api_versions[].spec`; `apis[].spec_content` is not supported in
 declarative configuration.
 
+An external API can own managed versions, publications, implementations, and
+documents. kongctl resolves the API and plans only the declared children; it
+never creates, updates, or deletes the API. Each implementation defines exactly
+one of `service` or `control_plane`. When `type` is present, it must match
+the selected payload.
+
 ## Application auth strategies
 
 * [API specification](/api/konnect/application-auth-strategies/#/operations/create-app-auth-strategy)
-* [Example](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/portal/auth-strategies.yaml)
+* [Example](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/portal/auth-strategies.yaml)
 
 ```yaml
 application_auth_strategies:
@@ -209,7 +267,7 @@ application_auth_strategies:
 ## DCR providers
 
 * [API specification](/api/konnect/application-auth-strategies/#/operations/create-dcr-provider)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/dcr-providers)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/dcr-providers)
 
 ```yaml
 dcr_providers:
@@ -226,7 +284,7 @@ dcr_providers:
 ## Catalog services
 
 * [API specification](/api/konnect/service-catalog/v1/#/operations/create-catalog-service)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/catalog/service.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/catalog/service.yaml)
 
 ```yaml
 catalog_services:
@@ -260,7 +318,7 @@ The field accepts that API-shaped object either inline or loaded from a JSON/YAM
 
 * [Custom dashboards](/custom-dashboards/)
 * [API specification](/api/konnect/analytics-dashboards/)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/analytics/dashboards/dashboard.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/analytics/dashboards/dashboard.yaml)
 
 ```yaml
 analytics:
@@ -290,7 +348,7 @@ analytics:
 For {{site.event_gateway_short}} control planes, see [{{site.event_gateway_short}}s](#event-gateways).
 
 * [API specification](/api/konnect/control-planes/#/operations/create-control-plane)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/control-plane/control-plane.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/control-plane/control-plane.yaml)
 
 ```yaml
 control_planes:
@@ -352,7 +410,7 @@ the authoritative schema for nested {{site.event_gateway_short}} resources and
 fields, and use `kongctl scaffold event_gateway` to generate starter YAML.
 
 * [API specification](/api/konnect/event-gateway/v1/#/operations/create-event-gateway)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/event-gateway)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/event-gateway)
 
 ```yaml
 event_gateways:
@@ -424,7 +482,12 @@ event_gateways:
              - type: One of (glob | exact_list) required
                glob: string # if type=glob
                exact_list: array[object] (min 1 item) # if type=exact_list
-                 - value: string required
+               - value: string required
+       topic_aliases:
+         - alias: string required
+           topic: string required
+           condition: string
+           conflict: One of (warn | ignore) (default: warn)
        acl_mode: One of (enforce_on_gateway | passthrough) required
        dns_label: string required (1-63 chars, RFC1035 label)
        labels: object [string]string
@@ -583,7 +646,7 @@ event_gateways:
 ## Organization
 
 * [API specification](/api/konnect/identity/v3/#/)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/organization/)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/organization/)
 
 ```yaml
 organization:
@@ -620,7 +683,7 @@ organization_team_roles:
 ## Portals
 
 * [API specification](/api/konnect/portal-management/v3/#/operations/create-portal)
-* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/portal/portal.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/portal/portal.yaml)
 
 ```yaml
 portals:
@@ -635,6 +698,7 @@ portals:
    default_application_auth_strategy_id: string (uuid, nullable) # prefer: !ref <app-auth-strategy-ref>
    auto_approve_developers: boolean (default: false)
    auto_approve_applications: boolean (default: false)
+   sipr_enabled: boolean (default: false)
    labels: object [string]string
      key: value
    customization: # /api/konnect/portal-management/v3/#/operations/replace-portal-customization
diff --git a/app/kongctl/sync/konnect.md b/app/kongctl/sync/konnect.md
index 948a34cf2e..8c04a4f6a4 100644
--- a/app/kongctl/sync/konnect.md
+++ b/app/kongctl/sync/konnect.md
@@ -5,7 +5,6 @@ content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/tail/audit-logs.md b/app/kongctl/tail/audit-logs.md
index 61a2743154..d687b41267 100644
--- a/app/kongctl/tail/audit-logs.md
+++ b/app/kongctl/tail/audit-logs.md
@@ -1,11 +1,10 @@
 ---
 title: kongctl tail audit-logs
-description: Tail audit logs.
+description: Follow organization audit logs.
 content_type: reference
 layout: reference
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
@@ -18,9 +17,12 @@ breadcrumbs:
 related_resources:
   - text: kongctl tail commands
     url: /kongctl/tail/
+  - text: Manage audit logs with kongctl
+    url: /kongctl/audit-logs/
 ---
 
-Tail audit logs.
+Follow organization audit logs. To stream events from a webhook listener, use
+`kongctl tail audit-logs listener`.
 
 
 ## Command usage
diff --git a/app/kongctl/tail/konnect.md b/app/kongctl/tail/konnect.md
index f749e366bc..0e5e02f8a4 100644
--- a/app/kongctl/tail/konnect.md
+++ b/app/kongctl/tail/konnect.md
@@ -6,7 +6,6 @@ layout: reference
 
 
 works_on:
-  - on-prem
   - konnect
 
 tools:
diff --git a/app/kongctl/troubleshooting.md b/app/kongctl/troubleshooting.md
index f70647b31d..0874cb0352 100644
--- a/app/kongctl/troubleshooting.md
+++ b/app/kongctl/troubleshooting.md
@@ -110,10 +110,10 @@ kongctl apply -f publications.yaml
    kongctl login
    ```
 
-3. If using a PAT, verify it's set:
+3. If you're using a PAT or sPAT, verify that it is set without printing it:
    
    ```bash
-   echo $KONGCTL_DEFAULT_KONNECT_PAT | head -c 20
+   test -n "$KONGCTL_DEFAULT_KONNECT_PAT" && echo "Token is set"
    ```
 
 4. Check that the token hasn't expired in {{site.konnect_short_name}}.
diff --git a/app/kongctl/view/index.md b/app/kongctl/view/index.md
index 6d5a2c739a..958b8129d1 100644
--- a/app/kongctl/view/index.md
+++ b/app/kongctl/view/index.md
@@ -23,6 +23,10 @@ related_resources:
 
 Launch the {{site.konnect_short_name}} interactive viewer.
 
+Navigate to a resource and press `d` to export declarative configuration.
+Choose the output file, namespace, and whether to include child resources
+before confirming the dump.
+
 ## Command usage
 
 {% include_cached /kongctl/help/view/index.md %}

From 0177da91a509f11d213cc0c7996dde5a2c7f633f Mon Sep 17 00:00:00 2001
From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com>
Date: Mon, 31 Aug 2026 11:11:00 -0500
Subject: [PATCH 2/4] docs: fix kongctl lint and links

---
 .../manage-ai-gateway-with-kongctl.md             | 15 ++++++++-------
 app/kongctl/adopt/ai-gateway.md                   |  2 +-
 app/kongctl/declarative.md                        |  2 +-
 app/kongctl/get/ai-gateway.md                     |  2 +-
 app/kongctl/list/ai-gateway.md                    |  2 +-
 5 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md b/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
index ab7c512b69..248ef05782 100644
--- a/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
+++ b/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
@@ -29,10 +29,11 @@ tags:
   - openai
 
 tldr:
-  q: How do I manage an AI Gateway with kongctl?
+  q: How do I manage {{site.ai_gateway}} with kongctl?
   a: |
-    Declare the AI Gateway, Model Provider, Model, and data-plane certificate
-    in YAML, apply the configuration with kongctl, and connect a data plane.
+    Declare {{site.ai_gateway}}, a Model Provider, a Model, and a data-plane
+    certificate in YAML, apply the configuration with kongctl, and connect a
+    data plane.
 
 automated_tests: false
 
@@ -52,16 +53,16 @@ prereqs:
       icon_url: /assets/icons/ai.svg
 
 related_resources:
-  - text: Use kongctl to manage {{site.ai_gateway}}
-    url: /ai-gateway/kongctl/
+  - text: Learn about {{site.ai_gateway}}
+    url: /ai-gateway/
   - text: Declarative configuration with kongctl
     url: /kongctl/declarative/
   - text: kongctl declarative resource reference
     url: /kongctl/supported-resources/#ai-gateway
 
 next_steps:
-  - text: Manage additional AI Gateway resources
-    url: /ai-gateway/kongctl/
+  - text: Explore {{site.ai_gateway}}
+    url: /ai-gateway/
   - text: Learn about kongctl sync
     url: /kongctl/sync/
 ---
diff --git a/app/kongctl/adopt/ai-gateway.md b/app/kongctl/adopt/ai-gateway.md
index b811e3b432..137a9d1b33 100644
--- a/app/kongctl/adopt/ai-gateway.md
+++ b/app/kongctl/adopt/ai-gateway.md
@@ -17,7 +17,7 @@ breadcrumbs:
 related_resources:
   - text: kongctl adopt commands
     url: /kongctl/adopt/
-  - text: Manage an AI Gateway with kongctl
+  - text: Manage {{site.ai_gateway}} with kongctl
     url: /kongctl/manage-ai-gateway/
   - text: Declarative configuration with kongctl
     url: /kongctl/declarative/
diff --git a/app/kongctl/declarative.md b/app/kongctl/declarative.md
index e3a495377d..4dc77649f3 100644
--- a/app/kongctl/declarative.md
+++ b/app/kongctl/declarative.md
@@ -654,7 +654,7 @@ kongctl dump declarative \
 For the complete resource model, see
 [kongctl declarative resource reference](/kongctl/supported-resources/#ai-gateway).
 For the product workflow, see
-[Use kongctl to manage {{site.ai_gateway}}](/ai-gateway/kongctl/).
+[Manage {{site.ai_gateway}} with kongctl](/kongctl/manage-ai-gateway/).
 
 ## Configuration templates
 
diff --git a/app/kongctl/get/ai-gateway.md b/app/kongctl/get/ai-gateway.md
index 189b922035..5bbb9ace72 100644
--- a/app/kongctl/get/ai-gateway.md
+++ b/app/kongctl/get/ai-gateway.md
@@ -17,7 +17,7 @@ breadcrumbs:
 related_resources:
   - text: kongctl get commands
     url: /kongctl/get/
-  - text: Manage an AI Gateway with kongctl
+  - text: Manage {{site.ai_gateway}} with kongctl
     url: /kongctl/manage-ai-gateway/
   - text: kongctl declarative resource reference
     url: /kongctl/supported-resources/#ai-gateway
diff --git a/app/kongctl/list/ai-gateway.md b/app/kongctl/list/ai-gateway.md
index 7043e388c0..f9a7493020 100644
--- a/app/kongctl/list/ai-gateway.md
+++ b/app/kongctl/list/ai-gateway.md
@@ -17,7 +17,7 @@ breadcrumbs:
 related_resources:
   - text: kongctl list commands
     url: /kongctl/list/
-  - text: Manage an AI Gateway with kongctl
+  - text: Manage {{site.ai_gateway}} with kongctl
     url: /kongctl/manage-ai-gateway/
   - text: kongctl declarative resource reference
     url: /kongctl/supported-resources/#ai-gateway

From 1123aeb9636872a8e4dccf7e14b03c737d36e6b5 Mon Sep 17 00:00:00 2001
From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com>
Date: Mon, 31 Aug 2026 12:26:55 -0500
Subject: [PATCH 3/4] docs: address kongctl review feedback

---
 app/kongctl/audit-logs.md          | 25 ++-------
 app/kongctl/declarative.md         |  6 +--
 app/kongctl/supported-resources.md | 83 ++++++++++++++++++++++++------
 3 files changed, 75 insertions(+), 39 deletions(-)

diff --git a/app/kongctl/audit-logs.md b/app/kongctl/audit-logs.md
index fadfea2ee1..5374daa9af 100644
--- a/app/kongctl/audit-logs.md
+++ b/app/kongctl/audit-logs.md
@@ -26,7 +26,7 @@ related_resources:
     url: /kongctl/declarative/
 next_steps:
   - text: Example declarative configurations
-    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative
+    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative
   - text: Learn about managing declarative configuration with kongctl
     url: /kongctl/declarative/
   - text: Learn about kongctl authorization options
@@ -46,9 +46,8 @@ webhooks with kongctl.
 
 kongctl can:
 
-- Pull organization audit logs on demand.
-- Retrieve every cursor page in a result set.
-- Follow new organization audit logs until interrupted.
+- Retrieve organization audit logs on demand.
+- Tail new organization audit logs until interrupted.
 - Create a {{site.konnect_short_name}} audit-log destination.
 - Configure the regional {{site.konnect_short_name}} audit-log webhook.
 - Start a local HTTP listener to receive webhook events.
@@ -75,7 +74,6 @@ Supported forms ({{site.konnect_short_name}}-first):
 - `kongctl ps`
 
 Use `get audit-logs` to retrieve a finite set of organization audit logs.
-kongctl follows cursor pagination automatically.
 
 Use `tail audit-logs` to retrieve a five-minute catch-up window and then poll
 for new organization audit logs until interrupted. This command is equivalent
@@ -191,19 +189,6 @@ and server errors preserve the checkpoint and use exponential backoff capped
 at one minute. Non-retryable authentication, authorization, and client errors
 stop the command with a nonzero status.
 
-## Migrate webhook tail commands
-
-`tail audit-logs` now follows the organization pull API. Add the `listener`
-child to use the previous webhook-based behavior:
-
-```sh
-kongctl tail audit-logs listener \
-  --endpoint https://example.com/audit-logs \
-  --authorization "Bearer <token>"
-```
-
-`kongctl listen` and `kongctl listen audit-logs` are unchanged.
-
 ## End-to-end flow
 
 When you run `kongctl listen`:
@@ -252,7 +237,7 @@ No additional kongctl event envelope is added.
 
 ## Tailing and jq
 
-Use the webhook listener child to stream records to STDOUT:
+Use the webhook listener sub-command to stream records to STDOUT:
 
 ```shell
 kongctl tail audit-logs listener \
@@ -412,6 +397,4 @@ tail -n 200 ~/.config/kongctl/logs/kongctl-listener-${pid}.log
 - Event file retention and rotation are not implemented yet.
 - Replay jobs are not implemented yet.
 - `kongctl ps` currently manages tracked detached processes only.
-- Pull and follow cover organization audit logs. Dev Portal audit logs remain
-  webhook-based.
 - Audit-log retention is controlled by the service.
diff --git a/app/kongctl/declarative.md b/app/kongctl/declarative.md
index 4dc77649f3..51861e112f 100644
--- a/app/kongctl/declarative.md
+++ b/app/kongctl/declarative.md
@@ -27,10 +27,10 @@ related_resources:
   - text: Troubleshooting kongctl
     url: /kongctl/troubleshooting/
   - text: Examples directory
-    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/
+    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/
 next_steps:
   - text: Example declarative configurations
-    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative
+    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative
   - text: Use kongctl with AI agent skills
     url: /kongctl/skills/
   - text: Learn about supported resources
@@ -874,7 +874,7 @@ api_documents:
 reading the requested field path.
 
 A runnable example is available in
-[docs/examples/declarative/env/](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/env/).
+[docs/examples/declarative/env/](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/env/).
 
 #### !env behavior
 
diff --git a/app/kongctl/supported-resources.md b/app/kongctl/supported-resources.md
index 29e3c42d6a..963f4ec435 100644
--- a/app/kongctl/supported-resources.md
+++ b/app/kongctl/supported-resources.md
@@ -24,7 +24,7 @@ related_resources:
     url: /kongctl/declarative/
 next_steps:
   - text: Example declarative configurations
-    url: https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative
+    url: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative
   - text: Learn about managing declarative configuration with kongctl
     url: /kongctl/declarative/
   - text: Learn about kongctl authorization options
@@ -154,7 +154,7 @@ Declarative config supports them as external references so managed portal audit
 
 * [Reference for listening to audit logs with kongctl](/kongctl/audit-logs/)
 * [API specification](/api/konnect/audit-logs/)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/audit-logs)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/audit-logs)
 
 ```yaml
 audit-logs:
@@ -174,7 +174,7 @@ Audit log webhook destinations **cannot** declare kongctl metadata and are not c
 ## APIs
 
 * [API specification](/api/konnect/api-builder/#/operations/create-api)
-* [Example](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/basic/api.yaml)
+* [Example](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/basic/api.yaml)
 
 ```yaml
 apis:
@@ -240,7 +240,7 @@ the selected payload.
 ## Application auth strategies
 
 * [API specification](/api/konnect/application-auth-strategies/#/operations/create-app-auth-strategy)
-* [Example](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/portal/auth-strategies.yaml)
+* [Example](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/portal/auth-strategies.yaml)
 
 ```yaml
 application_auth_strategies:
@@ -267,7 +267,7 @@ application_auth_strategies:
 ## DCR providers
 
 * [API specification](/api/konnect/application-auth-strategies/#/operations/create-dcr-provider)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/dcr-providers)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/dcr-providers)
 
 ```yaml
 dcr_providers:
@@ -284,7 +284,7 @@ dcr_providers:
 ## Catalog services
 
 * [API specification](/api/konnect/service-catalog/v1/#/operations/create-catalog-service)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/catalog/service.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/catalog/service.yaml)
 
 ```yaml
 catalog_services:
@@ -318,7 +318,7 @@ The field accepts that API-shaped object either inline or loaded from a JSON/YAM
 
 * [Custom dashboards](/custom-dashboards/)
 * [API specification](/api/konnect/analytics-dashboards/)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/analytics/dashboards/dashboard.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/analytics/dashboards/dashboard.yaml)
 
 ```yaml
 analytics:
@@ -348,7 +348,7 @@ analytics:
 For {{site.event_gateway_short}} control planes, see [{{site.event_gateway_short}}s](#event-gateways).
 
 * [API specification](/api/konnect/control-planes/#/operations/create-control-plane)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/control-plane/control-plane.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/control-plane/control-plane.yaml)
 
 ```yaml
 control_planes:
@@ -410,7 +410,7 @@ the authoritative schema for nested {{site.event_gateway_short}} resources and
 fields, and use `kongctl scaffold event_gateway` to generate starter YAML.
 
 * [API specification](/api/konnect/event-gateway/v1/#/operations/create-event-gateway)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/event-gateway)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/event-gateway)
 
 ```yaml
 event_gateways:
@@ -646,7 +646,7 @@ event_gateways:
 ## Organization
 
 * [API specification](/api/konnect/identity/v3/#/)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/organization/)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/organization/)
 
 ```yaml
 organization:
@@ -683,7 +683,7 @@ organization_team_roles:
 ## Portals
 
 * [API specification](/api/konnect/portal-management/v3/#/operations/create-portal)
-* [Examples](https://github.com/Kong/kongctl/tree/v1.14.0/docs/examples/declarative/portal/portal.yaml)
+* [Examples](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/portal/portal.yaml)
 
 ```yaml
 portals:
@@ -933,7 +933,13 @@ audit-logs:
 ## {{site.ai_gateway}}
 
 This section covers the {{site.ai_gateway}} resources supported by kongctl.
-Use `kongctl explain ai_gateways --output yaml` as the authoritative schema for nested {{site.ai_gateway}} resources and fields, and use `kongctl scaffold ai_gateways` to generate starter YAML.
+Use `kongctl explain ai_gateway --output yaml` as the authoritative schema for
+nested {{site.ai_gateway}} resources and fields, and use
+`kongctl scaffold ai_gateway` to generate starter YAML.
+
+{{site.ai_gateway}} nodes are imperative, read-only resources. Inspect them
+with `kongctl get ai-gateway nodes`; don't include them in declarative
+configuration.
 
 * [{{site.ai_gateway}} entities reference](/ai-gateway/entities/)
 * [Using kongctl to manage {{site.ai_gateway}}](/ai-gateway/kongctl/)
@@ -949,6 +955,7 @@ ai_gateways:
     name: string required
     display_name: string required
     description: string (nullable)
+    deployment_type: One of (hybrid | managed | serverless) (default: hybrid)
     proxy_urls: array[object]
       - host: string required
         port: integer required
@@ -956,13 +963,14 @@ ai_gateways:
     labels: object [string]string
       key: value
     model_providers: # see AI Model Providers
-    identity_providers: # see AI Identity Providers
+    auth_strategies: # see AI Auth Strategies
     policies: # see AI Policies
     agents: # see AI Agents
     consumers: # see AI Consumers
     consumer_groups: # see AI Consumer Groups
     models: # see AI Models
     mcp_servers: # see AI MCP Servers
+    config_stores: # see AI Config Stores
     vaults: # see AI Vaults
     data_plane_certificates:
       - ref: string
@@ -1095,7 +1103,7 @@ ai_gateway_models:
         oneOf:
           allow: array[string] # consumer group names
           deny: array[string]
-      identity_providers: array[string] # identity provider names
+      auth_strategies: array[string] # Auth Strategy names; prefer: !ref values
     capabilities: array[string] # for example [generate]
     policies: array[string] # policy names; prefer: !ref values
     labels: object [string]string
@@ -1164,7 +1172,7 @@ ai_gateway_consumers:
     ai_gateway: string required # prefer: !ref <ai-gateway-ref>
     name: string required
     display_name: string required
-    type: One of (api-key) required
+    type: One of (api-key | oauth) required
     custom_id: string (nullable)
     policies: array[string] # policy names; prefer: !ref values
     credentials:
@@ -1173,6 +1181,7 @@ ai_gateway_consumers:
         name: string required
         display_name: string required
         type: One of (api-key) required
+        api_key: string # create-only; must use !secret when provided
         ttl: integer
         labels: object [string]string
           key: value
@@ -1273,6 +1282,7 @@ ai_gateway_mcp_servers:
         oneOf:
           allow: array[string]
           deny: array[string]
+      auth_strategies: array[string] # Auth Strategy names; prefer: !ref values
     policies: array[string] # policy names
     labels: object [string]string
       key: value
@@ -1316,12 +1326,43 @@ ai_gateway_agents:
         oneOf:
           allow: array[string] # consumer group names
           deny: array[string]
+      auth_strategies: array[string] # Auth Strategy names; prefer: !ref values
     policies: array[string] # policy names; prefer: !ref values
     labels: object [string]string
       key: value
 ```
 {:.collapsible}
 
+### AI Config Stores
+
+AI Config Stores contain secrets that can be referenced by other
+{{site.ai_gateway}} resources. Config Store names are immutable after creation.
+
+```yaml
+ai_gateway_config_stores:
+  - ref: string
+    ai_gateway: string required # prefer: !ref <ai-gateway-ref>
+    name: string required
+    display_name: string required
+    secrets:
+      - ref: string
+        key: string required
+        value: string # write-only; must use !secret
+```
+
+Config Store Secrets can also be declared at the root with an
+`ai_gateway_config_store` parent. Secret values are never returned. Creating a
+secret requires `value`; rotating one also requires `--write-secret` or
+`--write-secrets`.
+
+```yaml
+ai_gateway_config_store_secrets:
+  - ref: string
+    ai_gateway_config_store: string required # prefer: !ref <config-store-ref>
+    key: string required
+    value: string # write-only; must use !secret
+```
+
 ### AI Vaults
 
 [AI Vaults](/ai-gateway/entities/ai-vault/) store secrets and credentials for use by {{site.ai_gateway}} resources.
@@ -1356,3 +1397,15 @@ ai_gateway_vaults:
     # config: # provider-specific; run `kongctl explain ai_gateway_vaults` for full detail
 ```
 {:.collapsible}
+
+Omit a child collection to leave it outside sync scope. Use an empty collection
+under an identified gateway, consumer, or Config Store to delete that parent's
+managed children. A root-level empty child collection is invalid because it
+doesn't identify its parent.
+
+Use `--resources ai_gateways --include-child-resources` to dump
+{{site.ai_gateway}}s and their children. Direct child dump selectors aren't
+supported.
+
+For examples, see the
+[{{site.ai_gateway}} declarative configurations](https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/ai-gateway).

From ec388e137e47d54b1af480299c6cef1a8adb7328 Mon Sep 17 00:00:00 2001
From: Angel <angel.guarisma@konghq.com>
Date: Wed, 2 Sep 2026 15:16:40 -0400
Subject: [PATCH 4/4] changes

---
 .../manage-ai-gateway-with-kongctl.md         |  2 ++
 app/_indices/kongctl.yaml                     |  1 -
 app/_landing_pages/kongctl.yaml               |  1 -
 app/kongctl/adopt/ai-gateway.md               |  2 --
 app/kongctl/audit-logs.md                     | 22 +++++++++----------
 app/kongctl/authentication.md                 |  2 +-
 app/kongctl/config.md                         | 10 ++++-----
 app/kongctl/declarative.md                    |  8 +++----
 app/kongctl/get/ai-gateway.md                 |  7 +++---
 app/kongctl/get/audit-logs.md                 |  1 -
 app/kongctl/list/ai-gateway.md                |  7 +++---
 app/kongctl/troubleshooting.md                | 16 +++++++-------
 12 files changed, 38 insertions(+), 41 deletions(-)

diff --git a/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md b/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
index 248ef05782..27113f0016 100644
--- a/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
+++ b/app/_how-tos/konnect-platform/manage-ai-gateway-with-kongctl.md
@@ -28,6 +28,8 @@ tags:
   - declarative-config
   - openai
 
+published: false
+
 tldr:
   q: How do I manage {{site.ai_gateway}} with kongctl?
   a: |
diff --git a/app/_indices/kongctl.yaml b/app/_indices/kongctl.yaml
index 67df548c2f..e24a958be6 100644
--- a/app/_indices/kongctl.yaml
+++ b/app/_indices/kongctl.yaml
@@ -28,7 +28,6 @@ groups:
         items:
           - path: /kongctl/declarative/
           - path: /kongctl/supported-resources/
-          - path: /kongctl/manage-ai-gateway/
           - path: /kongctl/kongctl-and-deck/
       - title: Other References
         items:
diff --git a/app/_landing_pages/kongctl.yaml b/app/_landing_pages/kongctl.yaml
index 097581181f..0eab1a6ff2 100644
--- a/app/_landing_pages/kongctl.yaml
+++ b/app/_landing_pages/kongctl.yaml
@@ -295,7 +295,6 @@ rows:
                 - /kongctl/authentication/
                 - /kongctl/audit-logs/
                 - /kongctl/declarative/
-                - /kongctl/manage-ai-gateway/
                 - /kongctl/skills/
                 - /kongctl/supported-resources/
                 - /kongctl/kongctl-and-deck/
diff --git a/app/kongctl/adopt/ai-gateway.md b/app/kongctl/adopt/ai-gateway.md
index 137a9d1b33..69246baab8 100644
--- a/app/kongctl/adopt/ai-gateway.md
+++ b/app/kongctl/adopt/ai-gateway.md
@@ -17,8 +17,6 @@ breadcrumbs:
 related_resources:
   - text: kongctl adopt commands
     url: /kongctl/adopt/
-  - text: Manage {{site.ai_gateway}} with kongctl
-    url: /kongctl/manage-ai-gateway/
   - text: Declarative configuration with kongctl
     url: /kongctl/declarative/
 ---
diff --git a/app/kongctl/audit-logs.md b/app/kongctl/audit-logs.md
index 5374daa9af..e146a6c744 100644
--- a/app/kongctl/audit-logs.md
+++ b/app/kongctl/audit-logs.md
@@ -193,14 +193,14 @@ stop the command with a nonzero status.
 
 When you run `kongctl listen`:
 
-1. Determines endpoint from `--endpoint` or `--public-url` + `--path`.
-1. Checks that a webhook does not already exist for the region (due to one
-   webhook per region limitation).
-1. Creates audit-log destination in {{site.konnect_short_name}}.
-1. Configures and enables regional webhook to use that destination.
-1. Starts local listener on `--listen-address` and `--path`.
+1. Determines the endpoint from `--endpoint` or `--public-url` + `--path`.
+1. Checks that a webhook doesn't already exist for the region, because
+   {{site.konnect_short_name}} allows only one webhook per region.
+1. Creates an audit-log destination in {{site.konnect_short_name}}.
+1. Configures and enables the regional webhook to use that destination.
+1. Starts a local listener on `--listen-address` and `--path`.
 1. Persists events to local storage.
-1. On shutdown, attempts webhook/destination cleanup.
+1. On shutdown, attempts to clean up the webhook and destination.
 
 ### Startup guard
 
@@ -214,7 +214,7 @@ If webhook state is already configured, startup fails fast.
 
 ## Event storage and format
 
-Default config profile-scoped storage directory:
+The default storage directory is scoped to the config profile:
 
 - `~/.config/kongctl/audit-logs/<sanitized-profile>/`
 - `<sanitized-profile>` is the profile name with unsupported path
@@ -276,7 +276,7 @@ About TLS:
 
 - The local listener is plain HTTP by default.
 - HTTPS is usually terminated by your tunnel or reverse proxy.
-- `--skip-ssl-verification` affects {{site.konnect_short_name}} delivery to destination endpoint.
+- `--skip-ssl-verification` affects {{site.konnect_short_name}} delivery to the destination endpoint.
 
 ## Tailscale example
 
@@ -304,13 +304,13 @@ Equivalent pattern:
 
 ## Detached listener mode
 
-Run listener in the background:
+Run the listener in the background:
 
 ```shell
 kongctl listen --endpoint https://example.tld/audit-logs --detach
 ```
 
-Parent process prints:
+The parent process prints:
 
 - child `pid`
 - child log file path
diff --git a/app/kongctl/authentication.md b/app/kongctl/authentication.md
index 08d22325f4..587f5dbb1e 100644
--- a/app/kongctl/authentication.md
+++ b/app/kongctl/authentication.md
@@ -193,7 +193,7 @@ set the `KONGCTL_DEFAULT_KONNECT_PAT` environment variable:
 
 {:.info}
 > See the [environment variable configuration reference](/kongctl/config#environment-variables) 
-> for full details on environment variables and the kongctl configuration system 
+> for full details on environment variables and the kongctl configuration system.
 
 ```bash
 export KONGCTL_DEFAULT_KONNECT_PAT="YOUR PAT HERE"
diff --git a/app/kongctl/config.md b/app/kongctl/config.md
index 1a5fba09cb..f35a0a85c8 100644
--- a/app/kongctl/config.md
+++ b/app/kongctl/config.md
@@ -30,13 +30,13 @@ related_resources:
     url: /kongctl/kongctl-and-deck/
 ---
 
-kongctl provides a flexible system for configuring the CLI behavior which allows
-you to customize behavior for different machines, {{site.konnect_short_name}} organizations, 
+kongctl provides a flexible system for configuring CLI behavior, so you can
+customize settings for different machines, {{site.konnect_short_name}} organizations, 
 environments, and automation pipelines.
 
 {:.info}
-> **Note:** The term _configuration_ in this document describes altering of the behavior of the CLI itself, 
-> not to be confused with _declarative configuration_ used to manage the state of 
+> **Note:** The term _configuration_ in this document refers to changing the behavior of the CLI itself, 
+> not to be confused with _declarative configuration_, which is used to manage the state of 
 > {{site.konnect_short_name}} resources. 
 > For declarative configuration, see the [declarative configuration guide](/kongctl/declarative/).
 
@@ -176,7 +176,7 @@ When values are loaded via environment variables, the variable names
 must start with the `KONGCTL_` prefix, then the desired profile,
 and finally the config path in uppercase with underscores instead of dots.
 
-For example, to set the same region value for the default profiles,
+For example, to set the same region value for the default profile,
 set the following environment variable:
 
 ```text
diff --git a/app/kongctl/declarative.md b/app/kongctl/declarative.md
index 51861e112f..96d91cddbf 100644
--- a/app/kongctl/declarative.md
+++ b/app/kongctl/declarative.md
@@ -61,7 +61,7 @@ YAML declaration files and a state-free CLI tool.
 
 1. **Configuration manifests**: Configuration is expressed as simple YAML files that describe the desired state of your {{site.konnect_short_name}} resources.
    Configuration files can be split into multiple files and directories for modularity and reuse.
-1. **Plan-based**: Plans are objects that represent required changes to move a set of resources from one state to another, desired, state.
+1. **Plan-based**: Plans are objects that represent required changes to move a set of resources from their current state to a desired state.
    In kongctl, plan artifacts are first-class concepts that can be created, stored, reviewed, and applied. Plans are represented as JSON objects
    and can be generated and stored as files for later application. When running declarative commands, if plans are not provided
    they are generated implicitly and executed immediately.
@@ -446,7 +446,7 @@ are specified or omitted. The following tables summarize the behavior.
 | true         | false          | false        | Resource overrides |
 | false        | true           | true         | Resource overrides |
 
-Child resources automatically inherit the metadata of their parent resource:
+Child resources automatically inherit the metadata of their parent resource.
 
 ### Namespace enforcement flags
 
@@ -653,8 +653,6 @@ kongctl dump declarative \
 
 For the complete resource model, see
 [kongctl declarative resource reference](/kongctl/supported-resources/#ai-gateway).
-For the product workflow, see
-[Manage {{site.ai_gateway}} with kongctl](/kongctl/manage-ai-gateway/).
 
 ## Configuration templates
 
@@ -1067,7 +1065,7 @@ kongctl dump declarative \
 `--skip-defaults` preserves explicit `null` and non-default values. It
 doesn't change planning, apply, sync, or Terraform import output.
 
-See the CLI help at `kongctl --help` for all possible commands, or check out the [kongctl CLI reference](/index/kongctl/#cli-reference) documentation.
+See the CLI help at `kongctl --help` for all possible commands, or check out the [kongctl CLI reference](/index/kongctl/#cli-references) documentation.
 
 ## CI/CD integration
 
diff --git a/app/kongctl/get/ai-gateway.md b/app/kongctl/get/ai-gateway.md
index 5bbb9ace72..e6a095c5a9 100644
--- a/app/kongctl/get/ai-gateway.md
+++ b/app/kongctl/get/ai-gateway.md
@@ -17,8 +17,6 @@ breadcrumbs:
 related_resources:
   - text: kongctl get commands
     url: /kongctl/get/
-  - text: Manage {{site.ai_gateway}} with kongctl
-    url: /kongctl/manage-ai-gateway/
   - text: kongctl declarative resource reference
     url: /kongctl/supported-resources/#ai-gateway
 ---
@@ -37,6 +35,9 @@ rows:
   - command: |
       [kongctl get ai-gateway agents](#kongctl-get-ai-gateway-agents)
     description: "Use the `agents` command to list or retrieve Agents for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
+  - command: |
+      [kongctl get ai-gateway auth-strategies](#kongctl-get-ai-gateway-auth-strategies)
+    description: "Use the `auth-strategies` command to list or retrieve Auth Strategies for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
   - command: |
       [kongctl get ai-gateway config-stores](#kongctl-get-ai-gateway-config-stores)
     description: "Use the `config-stores` command to list or retrieve Config Stores for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
@@ -90,7 +91,7 @@ Use the `auth-strategies` command to list or retrieve Auth Strategies for a spec
 
 ### kongctl get ai-gateway config-stores
 
-Use the `config-stores` command to list or retrieve Config Stores for a {{site.konnect_short_name}} {{site.ai_gateway}}.
+Use the `config-stores` command to list or retrieve Config Stores for a specific {{site.konnect_short_name}} {{site.ai_gateway}}.
 
 {% include_cached /kongctl/help/get/ai-gateway/config-stores.md %}
 
diff --git a/app/kongctl/get/audit-logs.md b/app/kongctl/get/audit-logs.md
index 4f5ea26e88..c0510016f0 100644
--- a/app/kongctl/get/audit-logs.md
+++ b/app/kongctl/get/audit-logs.md
@@ -4,7 +4,6 @@ description: "Pull organization audit logs and inspect audit-log configuration."
 content_type: reference
 layout: reference
 
-
 works_on:
   - konnect
 
diff --git a/app/kongctl/list/ai-gateway.md b/app/kongctl/list/ai-gateway.md
index f9a7493020..332ec9f8c4 100644
--- a/app/kongctl/list/ai-gateway.md
+++ b/app/kongctl/list/ai-gateway.md
@@ -17,8 +17,6 @@ breadcrumbs:
 related_resources:
   - text: kongctl list commands
     url: /kongctl/list/
-  - text: Manage {{site.ai_gateway}} with kongctl
-    url: /kongctl/manage-ai-gateway/
   - text: kongctl declarative resource reference
     url: /kongctl/supported-resources/#ai-gateway
 ---
@@ -37,6 +35,9 @@ rows:
   - command: |
       [kongctl list ai-gateway agents](#kongctl-list-ai-gateway-agents)
     description: "Use the `agents` command to list or retrieve Agents for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
+  - command: |
+      [kongctl list ai-gateway auth-strategies](#kongctl-list-ai-gateway-auth-strategies)
+    description: "Use the `auth-strategies` command to list or retrieve Auth Strategies for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
   - command: |
       [kongctl list ai-gateway config-stores](#kongctl-list-ai-gateway-config-stores)
     description: "Use the `config-stores` command to list or retrieve Config Stores for a specific {{site.konnect_short_name}} {{site.ai_gateway}}."
@@ -90,7 +91,7 @@ Use the `auth-strategies` command to list or retrieve Auth Strategies for a spec
 
 ### kongctl list ai-gateway config-stores
 
-Use the `config-stores` command to list or retrieve Config Stores for a {{site.konnect_short_name}} {{site.ai_gateway}}.
+Use the `config-stores` command to list or retrieve Config Stores for a specific {{site.konnect_short_name}} {{site.ai_gateway}}.
 
 {% include_cached /kongctl/help/list/ai-gateway/config-stores.md %}
 
diff --git a/app/kongctl/troubleshooting.md b/app/kongctl/troubleshooting.md
index 0874cb0352..1c1ab3f1c8 100644
--- a/app/kongctl/troubleshooting.md
+++ b/app/kongctl/troubleshooting.md
@@ -24,7 +24,7 @@ related_resources:
      url: /kongctl/declarative/
    - text: kongctl configuration reference guide
      url: /kongctl/config/
-   - text: Using kongctl and deck for full API platform management
+   - text: Using kongctl and decK for full API platform management
      url: /kongctl/kongctl-and-deck/
 ---
 
@@ -130,9 +130,9 @@ kongctl apply -f publications.yaml
 	
 2. If timeout occurs, start over:
 
-	```bash
-	kongctl login
-  ```
+   ```bash
+   kongctl login
+   ```
 
 3. Verify that your browser isn't blocking the redirect.
 
@@ -532,7 +532,7 @@ kongctl apply -f config.yaml --log-level trace
 You can also set these via environment variables:
 
 ```bash
-export KONGCTL_LOG_LEVEL=debug
+export KONGCTL_DEFAULT_LOG_LEVEL=debug
 kongctl plan -f config/
 ```
 
@@ -603,7 +603,7 @@ Ensure you're running the [latest version](https://github.com/kong/kongctl/relea
 kongctl version --full
 ```
 
-Update kongctl if needed [following the install instructions for your platform](/kongctl).
+Update kongctl if needed [following the install instructions for your platform](/kongctl/).
 
 ## Quick reference
 
@@ -649,8 +649,8 @@ rows:
 ### Useful environment variables
 
 ```bash
-# Set log level globally
-export KONGCTL_LOG_LEVEL=debug
+# Set log level for the default profile
+export KONGCTL_DEFAULT_LOG_LEVEL=debug
 
 # Use a specific profile
 export KONGCTL_PROFILE=production