diff --git a/docs-site/assets/kagent-docs/versions/agent-substrate.md b/docs-site/assets/kagent-docs/versions/agent-substrate.md
index 3b705c38..fb4164f2 100644
--- a/docs-site/assets/kagent-docs/versions/agent-substrate.md
+++ b/docs-site/assets/kagent-docs/versions/agent-substrate.md
@@ -1 +1 @@
-{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}0.4.0-alpha1{{< /version >}}
\ No newline at end of file
+{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}0.5.0-alpha2{{< /version >}}
\ No newline at end of file
diff --git a/docs-site/assets/kagent-docs/versions/kagent.md b/docs-site/assets/kagent-docs/versions/kagent.md
index 55dd0601..3399c9ac 100644
--- a/docs-site/assets/kagent-docs/versions/kagent.md
+++ b/docs-site/assets/kagent-docs/versions/kagent.md
@@ -1 +1 @@
-{{< version include-if="0.x" >}}0.10.2{{< /version >}}{{< version include-if="1.x" >}}1.0.0-alpha9{{< /version >}}
\ No newline at end of file
+{{< version include-if="0.x" >}}0.10.2{{< /version >}}{{< version include-if="1.x" >}}1.0.0-alpha12{{< /version >}}
\ No newline at end of file
diff --git a/docs-site/assets/kagent-docs/versions/runtime-image-claude.md b/docs-site/assets/kagent-docs/versions/runtime-image-claude.md
index ee59f98b..e857e679 100644
--- a/docs-site/assets/kagent-docs/versions/runtime-image-claude.md
+++ b/docs-site/assets/kagent-docs/versions/runtime-image-claude.md
@@ -1 +1 @@
-ghcr.io/kagent-dev/kagent/claude-harness@sha256:e72d66d9f3b6eafbc59d18cef150fb5d31cb89ead83999a33c06264c21e86d4c
\ No newline at end of file
+ghcr.io/kagent-dev/kagent/claude-harness@sha256:95a5f4839a337aaf78e0eeff480025ed5586d3cfec22277102318826236e3d74
\ No newline at end of file
diff --git a/docs-site/assets/kagent-docs/versions/runtime-image-codex.md b/docs-site/assets/kagent-docs/versions/runtime-image-codex.md
index 17ec3b2a..8ee92613 100644
--- a/docs-site/assets/kagent-docs/versions/runtime-image-codex.md
+++ b/docs-site/assets/kagent-docs/versions/runtime-image-codex.md
@@ -1 +1 @@
-ghcr.io/kagent-dev/kagent/codex-harness@sha256:aef1e913671c65721af8003494afbeacc6c81e41309afbbb1e8d888e1868d8ce
\ No newline at end of file
+ghcr.io/kagent-dev/kagent/codex-harness@sha256:7748610b7eccd94e556e0b9cd7bef93c8961e99d445519135b77513ead81f379
\ No newline at end of file
diff --git a/docs-site/assets/kagent-docs/versions/runtime-image.md b/docs-site/assets/kagent-docs/versions/runtime-image.md
index b755983a..9e3e19da 100644
--- a/docs-site/assets/kagent-docs/versions/runtime-image.md
+++ b/docs-site/assets/kagent-docs/versions/runtime-image.md
@@ -1 +1 @@
-ghcr.io/kagent-dev/kagent/golang-adk@sha256:26ae5c772d4a59b24ecb3619c3499e106e3b28abbc239de25b4ff8d746f97e69
\ No newline at end of file
+ghcr.io/kagent-dev/kagent/golang-adk@sha256:9c2e93b1dc6ac4bfa586cd2636891b5c17e91ca6978338fe02de307098147493
\ No newline at end of file
diff --git a/docs-site/content/kagent/1.x/about/core-concepts.md b/docs-site/content/kagent/1.x/about/core-concepts.md
index 158f6cb4..db49a76b 100644
--- a/docs-site/content/kagent/1.x/about/core-concepts.md
+++ b/docs-site/content/kagent/1.x/about/core-concepts.md
@@ -90,9 +90,9 @@ For the complete AgentTemplate schema, see the [API reference]({{< link path="re
 
 ## Agent
 
-An **Agent** is a Kubernetes custom resource that pairs _one AgentTemplate with one Harness_. For each side, the Agent either names an existing resource or includes a complete spec inline, and it sets exactly one of the two.
+An **Agent** is a Kubernetes custom resource that pairs _one AgentTemplate with one Harness_. Both sides are required. Under `spec.template`, the Agent sets exactly one of `ref`, which names an existing AgentTemplate, or `inline`, which carries a complete template spec. Under `spec.harnessRef`, the Agent names an existing Harness. A Harness has no inline form.
 
-The two sides are independent, so an Agent can name both resources, inline both, or mix the two. An inline spec is a complete definition, not an override of a named resource, and kagent creates no Kubernetes resource to back one. Every name resolves in the Agent's own namespace, including a name nested inside an inline spec. For the fields that express each choice, see the [API reference]({{< link path="reference/api-ref#agent" >}}).
+An inline template is a complete definition rather than an override of a named AgentTemplate, and kagent creates no Kubernetes resource to back one. Every name resolves in the Agent's own namespace, including a name nested inside an inline template. For the fields that express each choice, see the [API reference]({{< link path="reference/api-ref#agent" >}}).
 
 The following Agent resource references both sides:
 
@@ -103,8 +103,9 @@ metadata:
   name: assistant
   namespace: kagent
 spec:
-  templateRef:
-    name: shared-context
+  template:
+    ref:
+      name: shared-context
   harnessRef:
     name: kagent
 ```
diff --git a/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md b/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md
index 32ce0283..4cc382e1 100644
--- a/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md
+++ b/docs-site/content/kagent/1.x/about/substrate-runtime/identity.md
@@ -71,6 +71,10 @@ A share carries one of two permissions.
 - **`READ_ONLY`**: The holder can read the conversation. kagent refuses any call that is not a read before the request reaches the service.
 - **`READ_WRITE`**: The holder can also send messages to the Session.
 
+A client that creates a share can set `CreateSessionShareRequest.ttl` to a positive lifetime, which starts when the share is created. Once that lifetime ends, the token grants no access and a token lookup returns not found. The owner still sees the expired share in `ListSessionShares` and can revoke it.
+
+The returned `SessionShare.expiresAt` field records when the token stops granting access. Omit `ttl` and `expiresAt` stays unset. The share then stays valid until it is revoked or the Session is deleted. An operator caps share lifetimes with `controller.sessionShareMaxTTL`. For more information, see [Expire idle Sessions]({{< link path="operations/operational-considerations#expire-idle-sessions" >}}).
+
 A share widens what the holder can reach to what the owner can see, and the underlying record is read as the owner rather than as the visitor. Revoking the share withdraws that access.
 
 ## The Agent Substrate plane
diff --git a/docs-site/content/kagent/1.x/agents/agent-harness.md b/docs-site/content/kagent/1.x/agents/agent-harness.md
index 4ae914cc..49070c4a 100644
--- a/docs-site/content/kagent/1.x/agents/agent-harness.md
+++ b/docs-site/content/kagent/1.x/agents/agent-harness.md
@@ -46,7 +46,7 @@ EOF
 | `substrate.workerPoolRef.name` | Yes | The {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}} that this Harness's Actors are scheduled onto. An operator must provision one before any agent can run. |
 | `substrate.snapshotPolicy.location` | Yes | The object storage location for Actor {{< gloss "Snapshot" >}}snapshots{{< /gloss >}}. |
 
-A Harness names no AgentTemplate. An {{< gloss "Agent" >}}Agent{{< /gloss >}} pairs the two through either `spec.harnessRef` or an inline `spec.harness`, so whoever writes the Agent decides which template runs on which Harness. For more information about the pairing, see [Core concepts]({{< link path="about/core-concepts#agent" >}}).
+A Harness names no AgentTemplate. An {{< gloss "Agent" >}}Agent{{< /gloss >}} pairs the two through `spec.harnessRef`, so whoever writes the Agent decides which template runs on which Harness. `spec.harnessRef` takes a reference only, so a Harness must exist before an Agent can name it. For more information about the pairing, see [Core concepts]({{< link path="about/core-concepts#agent" >}}).
 
 A command or argument override belongs to the revision that kagent prepares. Changing one prepares a new revision rather than altering a running agent. A {{< gloss "Session" >}}Session{{< /gloss >}} pinned to an earlier revision keeps the command it was prepared with until it moves to the new one.
 
@@ -140,8 +140,9 @@ metadata:
   name: codex-agent
   namespace: kagent
 spec:
-  templateRef:
-    name: codex-template
+  template:
+    ref:
+      name: codex-template
   harnessRef:
     name: codex-harness
 EOF
@@ -194,8 +195,9 @@ metadata:
   name: claude-agent
   namespace: kagent
 spec:
-  templateRef:
-    name: claude-template
+  template:
+    ref:
+      name: claude-template
   harnessRef:
     name: claude-harness
 EOF
diff --git a/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md b/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md
index 3c2098d3..cc743b87 100644
--- a/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md
+++ b/docs-site/content/kagent/1.x/agents/bring-your-own-agent.md
@@ -116,8 +116,9 @@ metadata:
   name: my-byo-agent
   namespace: kagent
 spec:
-  templateRef:
-    name: my-byo-template
+  template:
+    ref:
+      name: my-byo-template
   harnessRef:
     name: my-byo-harness
 EOF
diff --git a/docs-site/content/kagent/1.x/agents/structured-output.md b/docs-site/content/kagent/1.x/agents/structured-output.md
index f5aae00a..439f7e1a 100644
--- a/docs-site/content/kagent/1.x/agents/structured-output.md
+++ b/docs-site/content/kagent/1.x/agents/structured-output.md
@@ -66,8 +66,9 @@ Set `spec.outputSchema` to keep the schema in the AgentTemplate, so that the sch
      name: structured-answer
      namespace: kagent
    spec:
-     templateRef:
-       name: structured-answer
+     template:
+       ref:
+         name: structured-answer
      harnessRef:
        name: my-first-harness
    EOF
@@ -157,8 +158,9 @@ Use `outputSchemaFrom` to keep the schema outside the AgentTemplate, so that sev
      name: structured-answer-shared
      namespace: kagent
    spec:
-     templateRef:
-       name: structured-answer-shared
+     template:
+       ref:
+         name: structured-answer-shared
      harnessRef:
        name: my-first-harness
    EOF
diff --git a/docs-site/content/kagent/1.x/examples/a2a-byo.md b/docs-site/content/kagent/1.x/examples/a2a-byo.md
index 1e8aee4a..a9c76ca4 100644
--- a/docs-site/content/kagent/1.x/examples/a2a-byo.md
+++ b/docs-site/content/kagent/1.x/examples/a2a-byo.md
@@ -109,8 +109,9 @@ A `byo` Harness carries two fields that the other runtimes do not need: an empty
      name: byo-example-agent
      namespace: kagent
    spec:
-     templateRef:
-       name: byo-example-template
+     template:
+       ref:
+         name: byo-example-template
      harnessRef:
        name: byo-example
    EOF
diff --git a/docs-site/content/kagent/1.x/examples/agent-delegation.md b/docs-site/content/kagent/1.x/examples/agent-delegation.md
index 9bad5e6b..e7abd977 100644
--- a/docs-site/content/kagent/1.x/examples/agent-delegation.md
+++ b/docs-site/content/kagent/1.x/examples/agent-delegation.md
@@ -122,8 +122,9 @@ Each binding renames the specialist that it points to, so the coordinator's syst
      name: incident-coordinator
      namespace: kagent
    spec:
-     templateRef:
-       name: incident-coordinator
+     template:
+       ref:
+         name: incident-coordinator
      harnessRef:
        name: my-first-harness
    EOF
diff --git a/docs-site/content/kagent/1.x/examples/agentgateway.md b/docs-site/content/kagent/1.x/examples/agentgateway.md
index b6228d0d..cbb10910 100644
--- a/docs-site/content/kagent/1.x/examples/agentgateway.md
+++ b/docs-site/content/kagent/1.x/examples/agentgateway.md
@@ -189,8 +189,9 @@ Two paths are worth checking in order. Calling the gateway directly isolates the
      name: support-triage
      namespace: kagent
    spec:
-     templateRef:
-       name: support-triage
+     template:
+       ref:
+         name: support-triage
      harnessRef:
        name: my-first-harness
    EOF
diff --git a/docs-site/content/kagent/1.x/examples/documentation-agent.md b/docs-site/content/kagent/1.x/examples/documentation-agent.md
index 3771d138..c3848dc7 100644
--- a/docs-site/content/kagent/1.x/examples/documentation-agent.md
+++ b/docs-site/content/kagent/1.x/examples/documentation-agent.md
@@ -245,8 +245,9 @@ The AgentTemplate binds the tools and sets the system prompt that makes the agen
      name: docs-agent
      namespace: kagent
    spec:
-     templateRef:
-       name: docs-agent
+     template:
+       ref:
+         name: docs-agent
      harnessRef:
        name: my-first-harness
    EOF
diff --git a/docs-site/content/kagent/1.x/examples/skills.md b/docs-site/content/kagent/1.x/examples/skills.md
index 3da4ba96..00df36fd 100644
--- a/docs-site/content/kagent/1.x/examples/skills.md
+++ b/docs-site/content/kagent/1.x/examples/skills.md
@@ -192,8 +192,9 @@ kagent pulls an `oci` source as a container image and unpacks its flattened file
      name: release-writer
      namespace: kagent
    spec:
-     templateRef:
-       name: release-writer
+     template:
+       ref:
+         name: release-writer
      harnessRef:
        name: my-first-harness
    EOF
diff --git a/docs-site/content/kagent/1.x/get-started/your-first-agent.md b/docs-site/content/kagent/1.x/get-started/your-first-agent.md
index 8fc7f70a..5ac082f6 100644
--- a/docs-site/content/kagent/1.x/get-started/your-first-agent.md
+++ b/docs-site/content/kagent/1.x/get-started/your-first-agent.md
@@ -68,13 +68,14 @@ Three resources define a runnable agent: a Harness holds the runtime, an AgentTe
      name: my-first-agent
      namespace: kagent
    spec:
-     templateRef:
-       name: my-first-template
+     template:
+       ref:
+         name: my-first-template
      harnessRef:
        name: my-first-harness
    ```
    > [!NOTE]
-   > Each side of the pairing takes either a reference, as shown here, or a complete spec written inline under `spec.template` or `spec.harness`. The two choices are independent, so an Agent can reference one side and inline the other. An inline spec is a complete value rather than an override, and kagent creates no Kubernetes object to back it.
+   > `spec.template` takes either a reference, as shown here, or a complete AgentTemplate spec under `inline`. An inline template is a complete value rather than an override, and kagent creates no Kubernetes object to back it. `spec.harnessRef` takes a reference only, so a Harness must exist before an Agent can name it.
 
 4. Confirm that the Agent is ready. `READY` reports whether kagent compiled and prepared a runtime {{< gloss "Revision" >}}revision{{< /gloss >}} for the pair.
    ```bash
diff --git a/docs-site/content/kagent/1.x/operations/operational-considerations.md b/docs-site/content/kagent/1.x/operations/operational-considerations.md
index f84eb7ba..3df3cabf 100644
--- a/docs-site/content/kagent/1.x/operations/operational-considerations.md
+++ b/docs-site/content/kagent/1.x/operations/operational-considerations.md
@@ -97,6 +97,42 @@ Leader election keeps the replicas from conflicting. One replica takes a Kuberne
 > [!IMPORTANT]
 > If an installation runs on the development database, extra controller replicas do not make the installation highly available. That database is a single pod backed by one PersistentVolumeClaim, so losing it stops every replica at once. Run an external PostgreSQL instance before counting controller replicas toward availability.
 
+## Sign push notification callbacks
+
+Agent-to-Agent (A2A) push notifications are unsigned by default. A callback carries no `Authorization` header unless you supply an Ed25519 signing key, and the JSON Web Key Set (JWKS) endpoint returns `404`. Push notifications still work without a key, so sign them only where a receiver must verify that a callback came from your installation.
+
+To sign callbacks, generate one unencrypted PKCS#8 Ed25519 key and store it in a Secret in the kagent namespace.
+
+1. Generate the signing key.
+   ```bash
+   openssl genpkey -algorithm ED25519 -out private-key.pem
+   ```
+
+2. Store the key in a Secret. The Secret must hold the key under the `private-key.pem` key.
+   ```bash
+   kubectl create secret generic kagent-push-signing -n kagent \
+     --from-file=private-key.pem
+   ```
+
+Then name that Secret in your {{< reuse "kagent-docs/snippets/name-product.md" >}} Helm values.
+
+```yaml
+controller:
+  push:
+    signing:
+      secretName: kagent-push-signing
+      issuer: https://kagent.example.com
+```
+
+| Setting | Description |
+| ------- | ----------- |
+| `controller.push.signing.secretName` | The Secret that holds `private-key.pem`. Leave it empty to send push notifications without JSON Web Token (JWT) authentication. Helm references a Secret that you create, and neither generates nor rotates signing keys. An invalid key stops the controller from starting. |
+| `controller.push.signing.issuer` | The stable URL that webhook receivers trust as the JWT issuer. Leave it empty to fall back to `ui.externalUrl`, and then to the in-cluster A2A gateway URL. |
+
+With a signing key configured, each callback attempt carries a fresh five-minute Ed25519 JWT in an `Authorization: Bearer` header, and the `/.well-known/jwks.json` endpoint publishes the matching public key.
+
+Every controller replica must load the same key. After you rotate the key, restart all controller pods together, because replicas that run on different keys publish different JSON Web Key Sets.
+
 ## Node operations
 
 A {{< gloss "Worker" >}}Worker{{< /gloss >}} is an ordinary Kubernetes pod, so every node event reaches the {{< gloss "Actor" >}}Actors{{< /gloss >}} that this Worker hosts. What the event costs depends on what each Actor was doing when the node went away.
@@ -161,6 +197,13 @@ Work in progress is never deleted. A Session with a running task survives past t
 
 <!-- REVIEW: the creation request ID behaviour belongs with the Session API rather than on an operations page, so it is parked here until a Sessions reference page exists. The behaviour: an expired Session releases its creation request ID, unlike an explicit client deletion, which keeps a tombstone, so the same caller can reuse that request ID to start a fresh Session. -->
 
+A Session share carries its own lifetime, separate from the Session's idle limit. A client sets `CreateSessionShareRequest.ttl` when it creates a share, and `controller.sessionShareMaxTTL` caps what a client may ask for. A positive cap rejects any request that exceeds it, and supplies the lifetime for a request that omits `ttl`. The default `0` leaves a share unbounded unless the client sets `ttl`, and a negative value is rejected at startup.
+
+```yaml
+controller:
+  sessionShareMaxTTL: "24h"
+```
+
 To watch the sweep, scrape `kagent_session_expired_total`, which counts the Sessions that it removed. Each removal also logs `expired idle session` at debug level with the Session's ID and how long it had been idle.
 
 ## How configuration changes reach agents
diff --git a/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md b/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md
index dad6e7ff..dd9fdd3b 100644
--- a/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md
+++ b/docs-site/content/kagent/1.x/operations/tune-agent-substrate.md
@@ -137,6 +137,63 @@ The same `template` block also accepts `nodeSelector`, `tolerations`, `priorityC
 
 <!-- REVIEW (WorkerPool owner): the CPU and memory figures above are illustrative rather than measured, and the chart ships no defaults to derive them from. Confirm a recommended request and limit per Worker for a pool that carries production traffic, and the scheduling guidance that goes with it, before this section presents either as a recommendation. -->
 
+### Give Workers their own ServiceAccount
+
+Worker pods run as a ServiceAccount that the chart creates, named after the pool. On a default install that name is `kagent-default`. The chart binds no Role or ClusterRole to the account. Its purpose is to keep Workers off the namespace's `default` ServiceAccount, and to give you a Worker identity that you can attach your own policy to, such as an IAM role or an admission rule.
+
+To run Workers as an account that you manage outside the chart, stop the chart from creating one and name your own account instead. That account must already exist in the release namespace, because neither the chart nor Kubernetes creates it on demand.
+
+```yaml
+substrateWorkerPool:
+  serviceAccount:
+    create: false
+    name: my-worker-sa
+```
+
+| Field | Description |
+| ----- | ----------- |
+| `substrateWorkerPool.serviceAccount.create` | Whether the chart creates the Worker ServiceAccount. Defaults to `true`. Set it to `false` to use an account that you manage yourself. |
+| `substrateWorkerPool.serviceAccount.name` | The ServiceAccount that Worker pods run as. Omit it to use the pool name. |
+
+The chart writes `serviceAccountName` into the pool's pod template. A `serviceAccountName` that you set under `substrateWorkerPool.template` is overwritten rather than merged, so set the account through `substrateWorkerPool.serviceAccount.name`.
+
+### Keep placement scoped to the pool's namespace {#workerpool-placement-labels}
+
+kagent selects a WorkerPool by name and namespace when it compiles an ActorTemplate, and the generated ActorTemplate matches Workers on the `kagent.dev/worker-pool-name` and `kagent.dev/worker-pool-namespace` labels. Agent Substrate matches those labels across every pool rather than checking the WorkerPool's namespace, so a pool that carries only the name label can be selected from another namespace.
+
+The chart sets both labels from the pool's name and namespace, and applies them after `substrateWorkerPool.labels`. An extra label that reuses either key is overwritten rather than honored.
+
+```yaml
+substrateWorkerPool:
+  name: kagent-default
+  labels:
+    environment: production
+```
+
+A pool that you manage outside the chart carries no labels of its own. Set both keys yourself, and match each value to the pool's name and namespace.
+
+```yaml
+apiVersion: ate.dev/v1alpha1
+kind: WorkerPool
+metadata:
+  name: external-pool
+  namespace: team-a
+  labels:
+    kagent.dev/worker-pool-name: external-pool
+    kagent.dev/worker-pool-namespace: team-a
+spec:
+  replicas: 2
+  workerImage: "ghcr.io/kagent-dev/substrate/ateom-gvisor:v{{< reuse "kagent-docs/versions/agent-substrate.md" >}}"
+```
+
+Earlier releases placed Actors with a single `kagent.dev/worker-pool` label, and the chart no longer sets it. A Session or Sandbox that is pinned to a revision from one of those releases still selects that key, so keep the old label on the pool until you recreate them.
+
+```yaml
+substrateWorkerPool:
+  labels:
+    kagent.dev/worker-pool: kagent-default
+```
+
 ## Configure snapshot storage
 
 Agent Substrate writes every suspended Actor to an object store, so the bucket stores the Session state that a resume restores. Two places decide where a snapshot lands:
diff --git a/docs-site/content/kagent/1.x/reference/api-ref.md b/docs-site/content/kagent/1.x/reference/api-ref.md
index 6d018c19..40f2c81f 100644
--- a/docs-site/content/kagent/1.x/reference/api-ref.md
+++ b/docs-site/content/kagent/1.x/reference/api-ref.md
@@ -37,18 +37,17 @@ Agent is a runnable definition with an explicit template and harness.
 
 #### AgentSpec
 
-AgentSpec pairs portable behavior with a runner. References are local to the
-Agent's namespace, including references nested in inline specs.
+AgentSpec pairs portable behavior with a platform-managed runtime. References
+are local to the Agent's namespace, including references nested in inline
+template specs.
 
 _Appears in:_
 - [Agent](#agent)
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `template` _[AgentTemplateSpec](#agenttemplatespec)_ |  |  |  |
-| `templateRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ |  |  |  |
-| `harness` _[HarnessSpec](#harnessspec)_ |  |  |  |
-| `harnessRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ |  |  |  |
+| `template` _[AgentTemplateSource](#agenttemplatesource)_ | Template selects the portable behavior this Agent exposes. |  | **Required** <br /> |
+| `harnessRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | HarnessRef selects the platform-managed runtime configuration that executes<br />the behavior. |  | **Required** <br /> |
 
 #### AgentStatus
 
@@ -113,13 +112,25 @@ _Appears in:_
 | `name` _string_ |  |  | MinLength: 1 <br />**Required** <br /> |
 | `source` _[ArtifactSource](#artifactsource)_ |  |  | **Required** <br /> |
 
+#### AgentTemplateSource
+
+AgentTemplateSource selects portable behavior inline or by local reference.
+
+_Appears in:_
+- [AgentSpec](#agentspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `inline` _[AgentTemplateSpec](#agenttemplatespec)_ | Inline defines the Agent's portable behavior directly. It cannot be set<br />together with Ref. |  |  |
+| `ref` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | Ref names an AgentTemplate in the Agent's namespace. It cannot be set<br />together with Inline. |  |  |
+
 #### AgentTemplateSpec
 
 AgentTemplateSpec defines portable agent behavior.
 
 _Appears in:_
-- [AgentSpec](#agentspec)
 - [AgentTemplate](#agenttemplate)
+- [AgentTemplateSource](#agenttemplatesource)
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
@@ -207,12 +218,13 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `azureEndpoint` _string_ | Endpoint for the Azure OpenAI API |  | **Required** <br /> |
-| `apiVersion` _string_ | API version for the Azure OpenAI API |  | **Required** <br /> |
+| `apiVersion` _string_ | API version for the Azure OpenAI API. Required unless apiFormat is responses. |  |  |
 | `azureDeployment` _string_ | Deployment name for the Azure OpenAI API |  |  |
 | `azureAdToken` _string_ | Azure AD token for authentication |  |  |
 | `temperature` _string_ | Temperature for sampling |  |  |
 | `maxTokens` _integer_ | Maximum tokens to generate |  |  |
 | `topP` _string_ | Top-p sampling parameter |  |  |
+| `apiFormat` _[OpenAIAPIFormat](#openaiapiformat)_ | APIFormat selects chatCompletions (default, the dated deployments path) or<br />responses (the /openai/v1 surface, which needs no apiVersion and reads files by link). | chatCompletions | Enum: [chatCompletions responses] <br /> |
 
 #### BYOHarness
 
@@ -442,7 +454,6 @@ _Appears in:_
 HarnessSpec defines a reusable runtime and its infrastructure policy.
 
 _Appears in:_
-- [AgentSpec](#agentspec)
 - [Harness](#harness)
 
 | Field | Description | Default | Validation |
@@ -726,6 +737,7 @@ _Validation:_
 - Enum: [chatCompletions responses]
 
 _Appears in:_
+- [AzureOpenAIConfig](#azureopenaiconfig)
 - [OpenAIConfig](#openaiconfig)
 
 | Field | Description |
@@ -882,19 +894,13 @@ _Appears in:_
 
 #### S3Object
 
+_Underlying type:_ _[struct{Endpoint string "json:\"endpoint\""; Bucket string "json:\"bucket\""; Key string "json:\"key\""; VersionID string "json:\"versionId\""; Region string "json:\"region,omitempty\""}](#struct{endpoint-string-"json:\"endpoint\"";-bucket-string-"json:\"bucket\"";-key-string-"json:\"key\"";-versionid-string-"json:\"versionid\"";-region-string-"json:\"region,omitempty\""})_
+
 S3Object identifies one immutable S3 object version.
 
 _Appears in:_
 - [BucketArtifact](#bucketartifact)
 
-| Field | Description | Default | Validation |
-| --- | --- | --- | --- |
-| `endpoint` _string_ | Endpoint is the HTTP(S) endpoint of an AWS or S3-compatible service. |  | Pattern: `^https?://[^[:space:]]+$` <br />**Required** <br /> |
-| `bucket` _string_ |  |  | MinLength: 1 <br />**Required** <br /> |
-| `key` _string_ |  |  | MinLength: 1 <br />**Required** <br /> |
-| `versionId` _string_ |  |  | MinLength: 1 <br />**Required** <br /> |
-| `region` _string_ | Region is used for request signing when required by the service. |  |  |
-
 #### SAPAICoreConfig
 
 SAPAICoreConfig contains SAP AI Core-specific configuration options.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-invoke.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-invoke.md
index 40b48b05..18a182b8 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-invoke.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-invoke.md
@@ -13,6 +13,8 @@ kagent agent invoke [flags]
 **Flags:**
 - `-f, --file string` - Read task text from a file or - for stdin
 - `-h, --help` - help for invoke
+- `--push-id string` - Callback ID (generated when omitted; requires --push-url)
+- `--push-url string` - Register a callback before task dispatch; return the task immediately
 - `--session string` - Session ID
 - `-S, --stream` - Stream the response
 - `-t, --task string` - Task text
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-create.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-create.md
new file mode 100644
index 00000000..7b6154e4
--- /dev/null
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-create.md
@@ -0,0 +1,27 @@
+---
+title: kagent agent session push create
+description: Add or replace a task callback.
+weight: 110
+---
+
+Add or replace a task callback
+
+```bash
+kagent agent session push create SESSION_ID TASK_ID [flags]
+```
+
+**Flags:**
+- `-h, --help` - help for create
+- `--id string` - Callback ID (generated when omitted)
+- `--url string` - HTTP or HTTPS callback URL
+
+**Global Flags:**
+- `--api-url string` - KAgent control-plane API URL (default "http://localhost:8083")
+- `--ca-file string` - CA certificate file for KAgent endpoints
+- `--gateway-url string` - KAgent A2A and MCP gateway URL (default "http://localhost:8083")
+- `-n, --namespace string` - Namespace (default "kagent")
+- `-o, --output-format string` - Output format (default "table")
+- `--server-name string` - TLS server name for KAgent endpoints
+- `--timeout duration` - Timeout (default 5m0s)
+- `--user-id string` - Caller identity used to select the server-side data partition (default "admin@kagent.dev")
+- `-v, --verbose` - Verbose output
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-delete.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-delete.md
new file mode 100644
index 00000000..614f7bed
--- /dev/null
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-delete.md
@@ -0,0 +1,25 @@
+---
+title: kagent agent session push delete
+description: Remove a task callback.
+weight: 120
+---
+
+Remove a task callback
+
+```bash
+kagent agent session push delete SESSION_ID TASK_ID CONFIG_ID [flags]
+```
+
+**Flags:**
+- `-h, --help` - help for delete
+
+**Global Flags:**
+- `--api-url string` - KAgent control-plane API URL (default "http://localhost:8083")
+- `--ca-file string` - CA certificate file for KAgent endpoints
+- `--gateway-url string` - KAgent A2A and MCP gateway URL (default "http://localhost:8083")
+- `-n, --namespace string` - Namespace (default "kagent")
+- `-o, --output-format string` - Output format (default "table")
+- `--server-name string` - TLS server name for KAgent endpoints
+- `--timeout duration` - Timeout (default 5m0s)
+- `--user-id string` - Caller identity used to select the server-side data partition (default "admin@kagent.dev")
+- `-v, --verbose` - Verbose output
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-get.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-get.md
new file mode 100644
index 00000000..61875904
--- /dev/null
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-get.md
@@ -0,0 +1,25 @@
+---
+title: kagent agent session push get
+description: Get a task callback.
+weight: 130
+---
+
+Get a task callback
+
+```bash
+kagent agent session push get SESSION_ID TASK_ID CONFIG_ID [flags]
+```
+
+**Flags:**
+- `-h, --help` - help for get
+
+**Global Flags:**
+- `--api-url string` - KAgent control-plane API URL (default "http://localhost:8083")
+- `--ca-file string` - CA certificate file for KAgent endpoints
+- `--gateway-url string` - KAgent A2A and MCP gateway URL (default "http://localhost:8083")
+- `-n, --namespace string` - Namespace (default "kagent")
+- `-o, --output-format string` - Output format (default "table")
+- `--server-name string` - TLS server name for KAgent endpoints
+- `--timeout duration` - Timeout (default 5m0s)
+- `--user-id string` - Caller identity used to select the server-side data partition (default "admin@kagent.dev")
+- `-v, --verbose` - Verbose output
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-list.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-list.md
new file mode 100644
index 00000000..17403c4a
--- /dev/null
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push-list.md
@@ -0,0 +1,27 @@
+---
+title: kagent agent session push list
+description: List active task callbacks.
+weight: 140
+---
+
+List active task callbacks
+
+```bash
+kagent agent session push list SESSION_ID TASK_ID [flags]
+```
+
+**Flags:**
+- `-h, --help` - help for list
+- `--page-size int32` - Callbacks per page (default 50, maximum 100)
+- `--page-token string` - Token returned by the previous page
+
+**Global Flags:**
+- `--api-url string` - KAgent control-plane API URL (default "http://localhost:8083")
+- `--ca-file string` - CA certificate file for KAgent endpoints
+- `--gateway-url string` - KAgent A2A and MCP gateway URL (default "http://localhost:8083")
+- `-n, --namespace string` - Namespace (default "kagent")
+- `-o, --output-format string` - Output format (default "table")
+- `--server-name string` - TLS server name for KAgent endpoints
+- `--timeout duration` - Timeout (default 5m0s)
+- `--user-id string` - Caller identity used to select the server-side data partition (default "admin@kagent.dev")
+- `-v, --verbose` - Verbose output
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push.md
new file mode 100644
index 00000000..0045acde
--- /dev/null
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session-push.md
@@ -0,0 +1,31 @@
+---
+title: kagent agent session push
+description: Manage A2A task push callbacks.
+weight: 100
+---
+
+Manage A2A task push callbacks
+
+```bash
+kagent agent session push [command]
+```
+
+**Subcommands:**
+- [`kagent agent session push create`]({{< link path="reference/cli/kagent-agent-session-push-create" >}}) - Add or replace a task callback
+- [`kagent agent session push delete`]({{< link path="reference/cli/kagent-agent-session-push-delete" >}}) - Remove a task callback
+- [`kagent agent session push get`]({{< link path="reference/cli/kagent-agent-session-push-get" >}}) - Get a task callback
+- [`kagent agent session push list`]({{< link path="reference/cli/kagent-agent-session-push-list" >}}) - List active task callbacks
+
+**Flags:**
+- `-h, --help` - help for push
+
+**Global Flags:**
+- `--api-url string` - KAgent control-plane API URL (default "http://localhost:8083")
+- `--ca-file string` - CA certificate file for KAgent endpoints
+- `--gateway-url string` - KAgent A2A and MCP gateway URL (default "http://localhost:8083")
+- `-n, --namespace string` - Namespace (default "kagent")
+- `-o, --output-format string` - Output format (default "table")
+- `--server-name string` - TLS server name for KAgent endpoints
+- `--timeout duration` - Timeout (default 5m0s)
+- `--user-id string` - Caller identity used to select the server-side data partition (default "admin@kagent.dev")
+- `-v, --verbose` - Verbose output
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session.md
index 313a4aa1..07ccdc3c 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-session.md
@@ -15,6 +15,7 @@ kagent agent session [command]
 - [`kagent agent session delete`]({{< link path="reference/cli/kagent-agent-session-delete" >}}) - Delete a Session
 - [`kagent agent session get`]({{< link path="reference/cli/kagent-agent-session-get" >}}) - Get a Session
 - [`kagent agent session list`]({{< link path="reference/cli/kagent-agent-session-list" >}}) - List your Sessions
+- [`kagent agent session push`]({{< link path="reference/cli/kagent-agent-session-push" >}}) - Manage A2A task push callbacks
 
 **Flags:**
 - `-h, --help` - help for session
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-get.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-get.md
index 8dabd61a..4c758f2b 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-get.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-get.md
@@ -1,7 +1,7 @@
 ---
 title: kagent agent template get
 description: Get an AgentTemplate.
-weight: 110
+weight: 160
 ---
 
 Get an AgentTemplate
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-list.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-list.md
index bcbe500b..86228fa3 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-list.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template-list.md
@@ -1,7 +1,7 @@
 ---
 title: kagent agent template list
 description: List AgentTemplates.
-weight: 120
+weight: 170
 ---
 
 List AgentTemplates
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template.md b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template.md
index a5356ede..c75c4896 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-agent-template.md
@@ -1,7 +1,7 @@
 ---
 title: kagent agent template
 description: Discover reusable agent templates.
-weight: 100
+weight: 150
 ---
 
 Discover reusable agent templates
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-apply.md b/docs-site/content/kagent/1.x/reference/cli/kagent-apply.md
index 50b418a4..07533f15 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-apply.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-apply.md
@@ -1,7 +1,7 @@
 ---
 title: kagent apply
 description: Create or update an Agent or AgentTemplate.
-weight: 130
+weight: 180
 ---
 
 Create or update an Agent or AgentTemplate
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-bug-report.md b/docs-site/content/kagent/1.x/reference/cli/kagent-bug-report.md
index ed2e41b7..36af883a 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-bug-report.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-bug-report.md
@@ -1,7 +1,7 @@
 ---
 title: kagent bug-report
 description: Generate a bug report.
-weight: 140
+weight: 190
 ---
 
 Generate a bug report
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-bash.md b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-bash.md
index a9cd4eb5..39b551b9 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-bash.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-bash.md
@@ -1,7 +1,7 @@
 ---
 title: kagent completion bash
 description: Generate the autocompletion script for bash.
-weight: 160
+weight: 210
 ---
 
 Generate the autocompletion script for the bash shell.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-fish.md b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-fish.md
index 0607dc63..9036f001 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-fish.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-fish.md
@@ -1,7 +1,7 @@
 ---
 title: kagent completion fish
 description: Generate the autocompletion script for fish.
-weight: 170
+weight: 220
 ---
 
 Generate the autocompletion script for the fish shell.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-powershell.md b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-powershell.md
index 1de6639d..04c70dfe 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-powershell.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-powershell.md
@@ -1,7 +1,7 @@
 ---
 title: kagent completion powershell
 description: Generate the autocompletion script for powershell.
-weight: 180
+weight: 230
 ---
 
 Generate the autocompletion script for powershell.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-zsh.md b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-zsh.md
index 405fbbb4..b0ce31aa 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-completion-zsh.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-completion-zsh.md
@@ -1,7 +1,7 @@
 ---
 title: kagent completion zsh
 description: Generate the autocompletion script for zsh.
-weight: 190
+weight: 240
 ---
 
 Generate the autocompletion script for the zsh shell.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-completion.md b/docs-site/content/kagent/1.x/reference/cli/kagent-completion.md
index d5831ca2..cd7d9cfc 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-completion.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-completion.md
@@ -1,7 +1,7 @@
 ---
 title: kagent completion
 description: Generate the autocompletion script for the specified shell.
-weight: 150
+weight: 200
 ---
 
 Generate the autocompletion script for kagent for the specified shell.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-dashboard.md b/docs-site/content/kagent/1.x/reference/cli/kagent-dashboard.md
index 449d82da..541826b1 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-dashboard.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: kagent dashboard
 description: Open the kagent dashboard.
-weight: 200
+weight: 250
 ---
 
 Open the kagent dashboard
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-down.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-down.md
index fd4ec8e9..7c86c60e 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-down.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-down.md
@@ -1,7 +1,7 @@
 ---
 title: kagent db migrate down
 description: Roll back the latest N migrations.
-weight: 230
+weight: 280
 ---
 
 Roll back the latest N migrations. A down migration can delete data.
@@ -15,6 +15,7 @@ kagent db migrate down N [flags]
 
 **Global Flags:**
 - `--ca-file string` - CA certificate file for KAgent endpoints
+- `--db-role string` - Stable PostgreSQL role to assume after authentication
 - `--db-url string` - PostgreSQL connection URL
 - `--server-name string` - TLS server name for KAgent endpoints
 - `--source string` - Migration source for down, goto, or version
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-goto.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-goto.md
index 2d1b447c..fb10a9dc 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-goto.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-goto.md
@@ -1,7 +1,7 @@
 ---
 title: kagent db migrate goto
 description: Move one source to version V.
-weight: 240
+weight: 290
 ---
 
 Move one source to version V. Version zero removes its schema.
@@ -15,6 +15,7 @@ kagent db migrate goto V [flags]
 
 **Global Flags:**
 - `--ca-file string` - CA certificate file for KAgent endpoints
+- `--db-role string` - Stable PostgreSQL role to assume after authentication
 - `--db-url string` - PostgreSQL connection URL
 - `--server-name string` - TLS server name for KAgent endpoints
 - `--source string` - Migration source for down, goto, or version
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-status.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-status.md
index 2e7fc9fa..22f03bd1 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-status.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-status.md
@@ -1,7 +1,7 @@
 ---
 title: kagent db migrate status
 description: Show migration status.
-weight: 250
+weight: 300
 ---
 
 Show migration status
@@ -16,6 +16,7 @@ kagent db migrate status [flags]
 
 **Global Flags:**
 - `--ca-file string` - CA certificate file for KAgent endpoints
+- `--db-role string` - Stable PostgreSQL role to assume after authentication
 - `--db-url string` - PostgreSQL connection URL
 - `--server-name string` - TLS server name for KAgent endpoints
 - `--source string` - Migration source for down, goto, or version
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-up.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-up.md
index 71567cee..732e0136 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-up.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-up.md
@@ -1,7 +1,7 @@
 ---
 title: kagent db migrate up
 description: Apply all pending migrations.
-weight: 260
+weight: 310
 ---
 
 Apply all pending migrations
@@ -15,6 +15,7 @@ kagent db migrate up [flags]
 
 **Global Flags:**
 - `--ca-file string` - CA certificate file for KAgent endpoints
+- `--db-role string` - Stable PostgreSQL role to assume after authentication
 - `--db-url string` - PostgreSQL connection URL
 - `--server-name string` - TLS server name for KAgent endpoints
 - `--source string` - Migration source for down, goto, or version
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-version.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-version.md
index 1f233cb9..cd5ff1ff 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-version.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate-version.md
@@ -1,7 +1,7 @@
 ---
 title: kagent db migrate version
 description: Show the applied migration version.
-weight: 270
+weight: 320
 ---
 
 Show the applied migration version
@@ -15,6 +15,7 @@ kagent db migrate version [flags]
 
 **Global Flags:**
 - `--ca-file string` - CA certificate file for KAgent endpoints
+- `--db-role string` - Stable PostgreSQL role to assume after authentication
 - `--db-url string` - PostgreSQL connection URL
 - `--server-name string` - TLS server name for KAgent endpoints
 - `--source string` - Migration source for down, goto, or version
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate.md
index 4a914d4c..a2e8ad15 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db-migrate.md
@@ -1,11 +1,11 @@
 ---
 title: kagent db migrate
 description: Apply, roll back, and inspect database migrations.
-weight: 220
+weight: 270
 ---
 
 Apply, roll back, and inspect database migrations.
-The command reads KAGENT_POSTGRES_DATABASE_URL when --db-url is empty.
+The command reads KAGENT_POSTGRES_DATABASE_URL and KAGENT_POSTGRES_DATABASE_ROLE when their flags are empty.
 
 ```bash
 kagent db migrate [command]
@@ -19,6 +19,7 @@ kagent db migrate [command]
 - [`kagent db migrate version`]({{< link path="reference/cli/kagent-db-migrate-version" >}}) - Show the applied migration version
 
 **Flags:**
+- `--db-role string` - Stable PostgreSQL role to assume after authentication
 - `--db-url string` - PostgreSQL connection URL
 - `-h, --help` - help for migrate
 - `--source string` - Migration source for down, goto, or version
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-db.md b/docs-site/content/kagent/1.x/reference/cli/kagent-db.md
index e0fa71ba..6d5fa517 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-db.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-db.md
@@ -1,7 +1,7 @@
 ---
 title: kagent db
 description: Database operations (migrations, inspection).
-weight: 210
+weight: 260
 ---
 
 Database operations (migrations, inspection)
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-install.md b/docs-site/content/kagent/1.x/reference/cli/kagent-install.md
index 7bcb9507..3c68c0a5 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-install.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-install.md
@@ -1,7 +1,7 @@
 ---
 title: kagent install
 description: Install kagent.
-weight: 280
+weight: 330
 ---
 
 Install kagent
@@ -13,6 +13,7 @@ kagent install [flags]
 **Flags:**
 - `-h, --help` - help for install
 - `--profile string` - Installation profile (minimal)
+- `--skip-database-setup` - Skip bundled PostgreSQL deployment and initialization
 
 **Global Flags:**
 - `--api-url string` - KAgent control-plane API URL (default "http://localhost:8083")
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-add-tool.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-add-tool.md
index a7b89aeb..3f7ac817 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-add-tool.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-add-tool.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp add-tool
 description: Add a new MCP tool to your project.
-weight: 300
+weight: 350
 ---
 
 Generate a new MCP tool that will be automatically loaded by the server.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-build.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-build.md
index 4625db2d..f9605bbe 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-build.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-build.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp build
 description: Build MCP server as a Docker image.
-weight: 310
+weight: 360
 ---
 
 Build an MCP server from the current project.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy-package.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy-package.md
index 7b48b528..048a1780 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy-package.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy-package.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp deploy package
 description: Deploy an MCP server using a package manager (npx, uvx).
-weight: 330
+weight: 380
 ---
 
 Deploy an MCP server using a package manager to run Model Context Protocol servers.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy.md
index 8613aff2..5d739ff6 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-deploy.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp deploy
 description: Deploy MCP server to Kubernetes.
-weight: 320
+weight: 370
 ---
 
 Deploy an MCP server to Kubernetes by generating MCPServer CRDs.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-go.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-go.md
index e54175d2..3089cb31 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-go.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-go.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp init go
 description: Initialize a new Go MCP server project.
-weight: 350
+weight: 400
 ---
 
 Initialize a new MCP server project using the mcp-go framework.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-java.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-java.md
index 8d4d9ae3..05f3e595 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-java.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-java.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp init java
 description: Initialize a new Java MCP server project.
-weight: 360
+weight: 410
 ---
 
 Initialize a new MCP server project using the Java MCP framework.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-python.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-python.md
index a265d009..9bef9b54 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-python.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-python.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp init python
 description: Initialize a new Python MCP server project.
-weight: 370
+weight: 420
 ---
 
 Initialize a new MCP server project using the fastmcp-python framework.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-typescript.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-typescript.md
index 92643f7e..012df3f1 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-typescript.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init-typescript.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp init typescript
 description: Initialize a new TypeScript MCP server project.
-weight: 380
+weight: 430
 ---
 
 Initialize a new MCP server project using the TypeScript MCP framework.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init.md
index 1a5e10d7..066a93aa 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-init.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp init
 description: Initialize a new MCP server project.
-weight: 340
+weight: 390
 ---
 
 Initialize a new MCP server project with dynamic tool loading.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-run.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-run.md
index 5a5d6b79..6bd834b8 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-run.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-run.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp run
 description: Run MCP server locally.
-weight: 390
+weight: 440
 ---
 
 Run an MCP server locally using the Model Context Protocol inspector.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets-sync.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets-sync.md
index f297ca7c..1a196c78 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets-sync.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets-sync.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp secrets sync
 description: Sync secrets to a Kubernetes environment from a local .env file.
-weight: 410
+weight: 460
 ---
 
 Sync secrets from a local .env file to a Kubernetes secret.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets.md
index bac69367..b7aa0dbe 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp-secrets.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp secrets
 description: Manage project secrets.
-weight: 400
+weight: 450
 ---
 
 Manage secrets for MCP server projects.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp.md b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp.md
index ae916921..ff9d324e 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-mcp.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-mcp.md
@@ -1,7 +1,7 @@
 ---
 title: kagent mcp
 description: MCP (Model Context Protocol) server management.
-weight: 290
+weight: 340
 ---
 
 MCP server management commands for creating and managing
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-create.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-create.md
index 1bfc3e74..30b24a8b 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-create.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-create.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox create
 description: Create a sandbox from a prepared template.
-weight: 430
+weight: 480
 ---
 
 Create a sandbox. Retain --request-id and all inputs for retries; each call makes one lifecycle attempt. Activity does not extend the TTL.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-delete.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-delete.md
index 86837956..6306ecf2 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-delete.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-delete.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox delete
 description: delete a sandbox.
-weight: 440
+weight: 490
 ---
 
 Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on transient errors. Get only observes. Suspend can interrupt work; delete removes files.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-download.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-download.md
index 24a222aa..ad7ee989 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-download.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-download.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox download
 description: Download a file, replacing the local destination only after success.
-weight: 450
+weight: 500
 ---
 
 Download a file, replacing the local destination only after success
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-exec.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-exec.md
index 75397ba0..3c199217 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-exec.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-exec.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox exec
 description: Start a command once and wait for its result.
-weight: 460
+weight: 510
 ---
 
 Start a process once. By default, stream available output while waiting. A timeout stops waiting, not the remote process. Retain its process ID and use sandbox wait to reconnect. An uncertain start is never retried. JSON output is a stream of started/output/finished/interrupted records.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-get.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-get.md
index f96ef4a5..88822c73 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-get.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-get.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox get
 description: get a sandbox.
-weight: 470
+weight: 520
 ---
 
 Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on transient errors. Get only observes. Suspend can interrupt work; delete removes files.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-kill.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-kill.md
index f6b5daab..2c0cb6f9 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-kill.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-kill.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox kill
 description: Terminate a process and its children.
-weight: 480
+weight: 530
 ---
 
 Terminate a process and its children
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-list.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-list.md
index c79ee1d9..57bf8c2a 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-list.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-list.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox list
 description: List your sandboxes.
-weight: 490
+weight: 540
 ---
 
 List your sandboxes
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-process.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-process.md
index 73ab5327..4ec5a250 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-process.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-process.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox process
 description: Inspect process status without waiting.
-weight: 500
+weight: 550
 ---
 
 Inspect process status without waiting
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-resume.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-resume.md
index 2fbf9492..e1b213f5 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-resume.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-resume.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox resume
 description: resume a sandbox.
-weight: 510
+weight: 560
 ---
 
 Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on transient errors. Get only observes. Suspend can interrupt work; delete removes files.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-suspend.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-suspend.md
index ba86d3f2..535d1c76 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-suspend.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-suspend.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox suspend
 description: suspend a sandbox.
-weight: 520
+weight: 570
 ---
 
 Inspect or change sandbox lifecycle. Mutations make one attempt; retry the same mutation on transient errors. Get only observes. Suspend can interrupt work; delete removes files.
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-templates.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-templates.md
index 06b3e281..16752b60 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-templates.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-templates.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox templates
 description: List SandboxTemplates in the selected namespace.
-weight: 530
+weight: 580
 ---
 
 List SandboxTemplates in the selected namespace
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-upload.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-upload.md
index fc55c88b..9abfedca 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-upload.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-upload.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox upload
 description: Stream a local file into a sandbox (replaces the remote file).
-weight: 540
+weight: 590
 ---
 
 Stream a local file into a sandbox (replaces the remote file)
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-wait.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-wait.md
index 2f1bd62d..88cf5080 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-wait.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox-wait.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox wait
 description: Collect output and wait for an existing process without restarting it.
-weight: 550
+weight: 600
 ---
 
 Collect output and wait for an existing process without restarting it
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox.md b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox.md
index 006e70a9..0a4287de 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-sandbox.md
@@ -1,7 +1,7 @@
 ---
 title: kagent sandbox
 description: Run commands and transfer files in standalone sandboxes.
-weight: 420
+weight: 470
 ---
 
 Run commands and transfer files in standalone sandboxes
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md b/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md
index 7e2579c0..211e6269 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-uninstall.md
@@ -1,7 +1,7 @@
 ---
 title: kagent uninstall
 description: Uninstall kagent.
-weight: 560
+weight: 610
 ---
 
 Uninstall kagent
diff --git a/docs-site/content/kagent/1.x/reference/cli/kagent-version.md b/docs-site/content/kagent/1.x/reference/cli/kagent-version.md
index 4b726cc3..1766e7e7 100644
--- a/docs-site/content/kagent/1.x/reference/cli/kagent-version.md
+++ b/docs-site/content/kagent/1.x/reference/cli/kagent-version.md
@@ -1,7 +1,7 @@
 ---
 title: kagent version
 description: Print the kagent version.
-weight: 570
+weight: 620
 ---
 
 Print the kagent version
diff --git a/docs-site/content/kagent/1.x/reference/env-vars.md b/docs-site/content/kagent/1.x/reference/env-vars.md
index 5e2fb2d1..cac1ba50 100644
--- a/docs-site/content/kagent/1.x/reference/env-vars.md
+++ b/docs-site/content/kagent/1.x/reference/env-vars.md
@@ -31,10 +31,14 @@ The kagent controller reads these variables at startup. Helm writes most of them
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
+| `KAGENT_A2A_PUSH_ALLOW_HTTP` | Boolean | `false` | Allow HTTP A2A push callbacks. HTTPS is required by default. |
+| `KAGENT_A2A_PUSH_ALLOW_PRIVATE_NETWORKS` | Boolean | `false` | Allow A2A push callbacks to private, loopback, and link-local destinations. |
+| `KAGENT_A2A_PUSH_ISSUER` | String | `(none)` | Stable issuer URL for push notification JWTs. Defaults to KAGENT_GATEWAY_URL. |
+| `KAGENT_A2A_PUSH_SIGNING_PRIVATE_KEY` | String | `(none)` | Unencrypted PKCS#8 PEM Ed25519 private key shared by controller replicas for push notification JWTs. Supply through a Kubernetes Secret. Empty disables JWT signing. |
 | `KAGENT_AUTH_MODE` | String | `insecure` | Controller authentication mode: insecure or trusted-proxy. trusted-proxy requires an upstream credential-validating proxy and network isolation preventing bypass. |
 | `KAGENT_AUTH_USER_ID_CLAIM` | String | `(none)` | JWT claim used for the caller identity in trusted-proxy mode. Empty uses sub; a missing or empty custom claim falls back to sub. |
 | `KAGENT_CONTROLLER_NAME` | String | `kagent-controller` | Name of the kagent controller service. |
-| `KAGENT_DATABASE_VECTOR_ENABLED` | Boolean | `false` | Enable vector database migrations and vector-backed database functionality. The controller defaults to false. When unset in the CLI, migrations read the controller ConfigMap and fall back to true if it is unavailable. |
+| `KAGENT_DATABASE_VECTOR_ENABLED` | Boolean | `false` | Enable vector database migrations and vector-backed database functionality. The controller defaults to false. When unset in the CLI, migrations read the controller ConfigMap and fall back to false if it is unavailable. |
 | `KAGENT_GATEWAY_URL` | String | `(none)` | Base URL for A2A and MCP traffic. The controller falls back to http://127.0.0.1:8083; Python runtimes require a value. |
 | `KAGENT_GRPC_REFLECTION` | Boolean | `false` | Enable gRPC server reflection on the controller. |
 | `KAGENT_HTTP_BIND_ADDRESS` | String | `:8083` | Listen address for the controller HTTP, gRPC, A2A, and MCP server. |
@@ -50,8 +54,10 @@ The kagent controller reads these variables at startup. Helm writes most of them
 | `KAGENT_POSTGRES_DATABASE_MAX_CONN_IDLE_TIME` | Duration | `30m0s` | Duration after which an idle connection will be automatically closed |
 | `KAGENT_POSTGRES_DATABASE_MAX_CONN_LIFETIME` | Duration | `1h0m0s` | Duration since creation after which a connection will be automatically closed |
 | `KAGENT_POSTGRES_DATABASE_MIN_CONNS` | Integer | `0` | Minimum size of the PostgreSQL connection pool |
-| `KAGENT_POSTGRES_DATABASE_URL` | String | `postgres://postgres:kagent@kagent-postgresql.kagent.svc.cluster.local:5432/postgres` | PostgreSQL connection URL. The default applies only to the controller; kagent db requires this variable or --db-url. Helm supplies its configured connection URL. |
-| `KAGENT_POSTGRES_DATABASE_URL_FILE` | String | `(none)` | File containing the PostgreSQL connection URL; takes precedence over KAGENT_POSTGRES_DATABASE_URL in the controller. |
+| `KAGENT_POSTGRES_DATABASE_ROLE` | String | `(none)` | Stable PostgreSQL role assumed after authentication. |
+| `KAGENT_POSTGRES_DATABASE_SCHEMA` | String | `kagent` | PostgreSQL schema for Kagent tables. |
+| `KAGENT_POSTGRES_DATABASE_URL` | String | `(none)` | PostgreSQL connection URL. Required by the controller; kagent db reads it when --db-url is empty. Helm sets it from database.postgres.connectionStringSecretRef. |
+| `KAGENT_POSTGRES_VECTOR_SCHEMA` | String | `extensions` | Schema where the shared pgvector extension is installed. |
 | `KAGENT_RUNTIME_REVISION_GC_INTERVAL` | Duration | `1m0s` | Interval between unreferenced runtime revision cleanup sweeps. Must be positive. |
 | `KAGENT_SANDBOX_CPU` | String | `1` | CPU limit for standalone sandbox runtimes. |
 | `KAGENT_SANDBOX_DEFAULT_TTL` | Duration | `1h0m0s` | Default standalone sandbox lifetime. |
@@ -63,6 +69,7 @@ The kagent controller reads these variables at startup. Helm writes most of them
 | `KAGENT_SCHEDULED_RUN_POLL_INTERVAL` | Duration | `1s` | Interval between reserving due scheduled runs. Must be positive; occurrences more than 30 seconds late are skipped. |
 | `KAGENT_SESSION_EXPIRATION_POLL_INTERVAL` | Duration | `1m0s` | Interval between idle session expiration sweeps. Must be positive. |
 | `KAGENT_SESSION_IDLE_TTL` | Duration | `168h0m0s` | Delete sessions after this idle duration. Zero disables expiration; running and waiting tasks are retained. |
+| `KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL` | Duration | `1m0s` | Recovery interval for missed session quiescence wake-ups. Must be positive; committed settlements wake local workers immediately and blocked work retries within one second. |
 | `KAGENT_SESSION_SHARE_MAX_TTL` | Duration | `0s` | Longest lifetime a session share may request. Shares created without a ttl receive it. Zero leaves shares unbounded. |
 | `KAGENT_SKIP_MIGRATIONS` | Boolean | `false` | Verify required database migrations at startup without applying them. |
 | `KAGENT_SUBSTRATE_ATENET_ROUTER_URL` | String | `http://atenet-router.ate-system.svc:80` | Substrate router endpoint for agent and sandbox guest traffic. |
@@ -100,7 +107,7 @@ The kagent controller supplies these variables to each agent runtime that it sch
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` | String | `(none)` | Python Google ADK span content capture. When absent, derived from OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (true for SPAN_ONLY or SPAN_AND_EVENT, false otherwise). |
+| `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` | String | `false` | Python Google ADK content on its legacy gcp.vertex.agent.* span keys, including tool arguments and results. kagent keeps it off; captured content uses the GenAI convention keys. |
 | `ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN` | String | `2` | Python Google ADK telemetry schema version; set by kagent when absent. |
 | `ANTHROPIC_API_KEY` | String | `(none)` | API key for Anthropic. |
 | `AWS_ACCESS_KEY_ID` | String | `(none)` | AWS access key ID for IAM authentication with Bedrock. |
@@ -112,6 +119,7 @@ The kagent controller supplies these variables to each agent runtime that it sch
 | `AZURE_AD_TOKEN` | String | `(none)` | Azure Active Directory authentication token for Azure OpenAI. |
 | `AZURE_OPENAI_API_KEY` | String | `(none)` | API key for Azure OpenAI. |
 | `AZURE_OPENAI_ENDPOINT` | String | `(none)` | Endpoint URL for Azure OpenAI service. |
+| `CREWAI_DISABLE_TELEMETRY` | String | `true` | CrewAI anonymous telemetry, which exports to CrewAI's own endpoint; kagent turns it off when absent. |
 | `FOUNDRY_API_KEY` | String | `(none)` | API key for Azure AI Foundry. |
 | `FOUNDRY_API_VERSION` | String | `2024-10-21` | Azure AI Foundry OpenAI-compatible data-plane API version. |
 | `FOUNDRY_DEPLOYMENT` | String | `(none)` | Azure AI Foundry model deployment name. |
@@ -162,13 +170,16 @@ The kagent controller supplies these variables to each agent runtime that it sch
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | String | `(none)` | Trace endpoint override. Falls back to OTEL_EXPORTER_OTLP_ENDPOINT; an HTTP override must include its signal path. |
 | `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | String | `(none)` | Trace protocol override: grpc or http/protobuf. Falls back to OTEL_EXPORTER_OTLP_PROTOCOL. |
 | `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` | String | `(none)` | Trace SDK timeout in milliseconds, overriding OTEL_EXPORTER_OTLP_TIMEOUT. Not forwarded by the controller. |
+| `OTEL_INSTRUMENTATION_A2A_SDK_ENABLED` | String | `false` | Python a2a-sdk internal spans; kagent turns them off when absent. |
 | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | String | `NO_CONTENT` | SPAN_ONLY records prompts and responses on agent spans. NO_CONTENT disables capture. Managed runtimes support these two modes; standalone Python ADK also recognizes SPAN_AND_EVENT. Captured content may be sensitive. |
 | `OTEL_LOGS_EXPORTER` | String | `(none)` | Log exporter, otlp or none. Managed runtime export requires explicit otlp and an endpoint; unset disables forwarding. Standalone SDKs may default to otlp. |
 | `OTEL_METRICS_EXPORTER` | String | `(none)` | Metric exporter, otlp or none. Managed runtime export requires explicit otlp and an endpoint; unset disables forwarding. Standalone SDKs may default to otlp. |
 | `OTEL_PROPAGATORS` | String | `tracecontext` | SDK trace propagators. Kagent defaults to W3C tracecontext without baggage and supplies that default to managed runtimes. |
+| `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` | String | `(none)` | Python instrumentation entry point names to skip, such as httpx or openai. |
+| `OTEL_PYTHON_FASTAPI_EXCLUDED_URLS` | String | `/health,/healthz,/readyz,/thread_dump,/\.well-known/agent-card\.json` | Python inbound HTTP paths left untraced; set by kagent when absent. |
 | `OTEL_RESOURCE_ATTRIBUTES` | String | `(none)` | Comma-separated SDK resource attributes for the current process. Helm injects controller identity; kagent constructs runtime identity separately. Use KAGENT_OTEL_RESOURCE_ATTRIBUTES for attributes shared with managed agents. |
 | `OTEL_SDK_DISABLED` | String | `false` | Disable SDK telemetry and forwarding to managed runtimes when true (case-insensitive). Other values are treated as false. |
-| `OTEL_SEMCONV_STABILITY_OPT_IN` | String | `gen_ai_latest_experimental` | Python Google ADK semantic-convention opt-in; set by kagent when absent. |
+| `OTEL_SEMCONV_STABILITY_OPT_IN` | String | `gen_ai_latest_experimental,http` | Python semantic-convention opt-in for GenAI and stable HTTP; set by kagent when absent. |
 | `OTEL_SERVICE_NAME` | String | `(none)` | SDK service name for the current process. Defaults to kagent-controller in the controller; the controller supplies the agent name to managed runtimes. |
 | `OTEL_TRACES_EXPORTER` | String | `(none)` | Trace exporter, otlp or none. Managed runtime export requires explicit otlp and an endpoint; unset disables forwarding. Standalone SDKs may default to otlp. |
 | `SAP_AI_CORE_CLIENT_ID` | String | `(none)` | OAuth2 client ID for SAP AI Core authentication. |
@@ -180,13 +191,15 @@ Both the kagent controller and `kagent db` read these variables. The controller
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `KAGENT_DATABASE_VECTOR_ENABLED` | Boolean | `false` | Enable vector database migrations and vector-backed database functionality. The controller defaults to false. When unset in the CLI, migrations read the controller ConfigMap and fall back to true if it is unavailable. |
+| `KAGENT_DATABASE_VECTOR_ENABLED` | Boolean | `false` | Enable vector database migrations and vector-backed database functionality. The controller defaults to false. When unset in the CLI, migrations read the controller ConfigMap and fall back to false if it is unavailable. |
 | `KAGENT_POSTGRES_DATABASE_MAX_CONNS` | Integer | `Greater of 4 and number of CPUs` | Maximum size of the PostgreSQL connection pool |
 | `KAGENT_POSTGRES_DATABASE_MAX_CONN_IDLE_TIME` | Duration | `30m0s` | Duration after which an idle connection will be automatically closed |
 | `KAGENT_POSTGRES_DATABASE_MAX_CONN_LIFETIME` | Duration | `1h0m0s` | Duration since creation after which a connection will be automatically closed |
 | `KAGENT_POSTGRES_DATABASE_MIN_CONNS` | Integer | `0` | Minimum size of the PostgreSQL connection pool |
-| `KAGENT_POSTGRES_DATABASE_URL` | String | `postgres://postgres:kagent@kagent-postgresql.kagent.svc.cluster.local:5432/postgres` | PostgreSQL connection URL. The default applies only to the controller; kagent db requires this variable or --db-url. Helm supplies its configured connection URL. |
-| `KAGENT_POSTGRES_DATABASE_URL_FILE` | String | `(none)` | File containing the PostgreSQL connection URL; takes precedence over KAGENT_POSTGRES_DATABASE_URL in the controller. |
+| `KAGENT_POSTGRES_DATABASE_ROLE` | String | `(none)` | Stable PostgreSQL role assumed after authentication. |
+| `KAGENT_POSTGRES_DATABASE_SCHEMA` | String | `kagent` | PostgreSQL schema for Kagent tables. |
+| `KAGENT_POSTGRES_DATABASE_URL` | String | `(none)` | PostgreSQL connection URL. Required by the controller; kagent db reads it when --db-url is empty. Helm sets it from database.postgres.connectionStringSecretRef. |
+| `KAGENT_POSTGRES_VECTOR_SCHEMA` | String | `extensions` | Schema where the shared pgvector extension is installed. |
 | `KAGENT_SKIP_MIGRATIONS` | Boolean | `false` | Verify required database migrations at startup without applying them. |
 
 ## CLI
@@ -199,13 +212,22 @@ The `kagent` command line tool reads these variables from the environment that i
 | `AZURE_OPENAI_API_KEY` | String | `(none)` | API key for Azure OpenAI. |
 | `GEMINI_API_KEY` | String | `(none)` | Fallback Gemini API key when GOOGLE_API_KEY is unset; supported by the CLI and Go/Python ADKs. |
 | `GOOGLE_API_KEY` | String | `(none)` | API key for Google Gemini. |
-| `KAGENT_DATABASE_VECTOR_ENABLED` | Boolean | `false` | Enable vector database migrations and vector-backed database functionality. The controller defaults to false. When unset in the CLI, migrations read the controller ConfigMap and fall back to true if it is unavailable. |
+| `KAGENT_BUNDLED_POSTGRES_IMAGE` | String | `postgres:18-alpine@sha256:9a8afca54e7861fd90fab5fdf4c42477a6b1cb7d293595148e674e0a3181de15` | PostgreSQL image that kagent install deploys. Point it at a mirror for air-gapped clusters. |
+| `KAGENT_DATABASE_VECTOR_ENABLED` | Boolean | `false` | Enable vector database migrations and vector-backed database functionality. The controller defaults to false. When unset in the CLI, migrations read the controller ConfigMap and fall back to false if it is unavailable. |
 | `KAGENT_DEFAULT_MODEL_PROVIDER` | String | `openAI` | Default LLM provider for agents (e.g. openAI, anthropic, ollama, azureOpenAI). |
-| `KAGENT_HELM_EXTRA_ARGS` | String | `(none)` | Additional arguments to pass to Helm commands. |
+| `KAGENT_HELM_EXTRA_ARGS` | String | `(none)` | Additional Helm --set overrides for the Kagent chart. |
 | `KAGENT_HELM_REPO` | String | `oci://ghcr.io/kagent-dev/kagent/helm/` | Helm repository URL for kagent charts. |
 | `KAGENT_HELM_VERSION` | String | `(none)` | Helm chart version to deploy. When unset, the CLI uses its own version. |
 | `KAGENT_LOG_LEVEL` | String | `info` | Logging level for the controller, CLI, and Go/Python runtimes, including the Python ADK HTTP server: debug, info, warn, or error. Python also accepts standard Python logging levels. |
-| `KAGENT_POSTGRES_DATABASE_URL` | String | `postgres://postgres:kagent@kagent-postgresql.kagent.svc.cluster.local:5432/postgres` | PostgreSQL connection URL. The default applies only to the controller; kagent db requires this variable or --db-url. Helm supplies its configured connection URL. |
+| `KAGENT_POSTGRES_DATABASE_ROLE` | String | `(none)` | Stable PostgreSQL role assumed after authentication. |
+| `KAGENT_POSTGRES_DATABASE_SCHEMA` | String | `kagent` | PostgreSQL schema for Kagent tables. |
+| `KAGENT_POSTGRES_DATABASE_URL` | String | `(none)` | PostgreSQL connection URL. Required by the controller; kagent db reads it when --db-url is empty. Helm sets it from database.postgres.connectionStringSecretRef. |
+| `KAGENT_POSTGRES_VECTOR_SCHEMA` | String | `extensions` | Schema where the shared pgvector extension is installed. |
+| `KAGENT_SUBSTRATE_HELM_EXTRA_ARGS` | String | `(none)` | Additional Helm --set overrides for the Substrate chart. |
+| `KAGENT_SUBSTRATE_HELM_REPO` | String | `oci://ghcr.io/kagent-dev/substrate/helm/` | Helm repository URL for Substrate charts. |
+| `KAGENT_SUBSTRATE_HELM_VERSION` | String | `(none)` | Substrate Helm chart version to deploy. When unset, the CLI uses its pinned Substrate version. |
+| `KAGENT_SUBSTRATE_PODCERT_HELM_REPO` | String | `(none)` | Helm repository URL for the Substrate PodCertificate chart. When unset, the CLI uses KAGENT_SUBSTRATE_HELM_REPO. |
+| `KAGENT_SUBSTRATE_PODCERT_HELM_VERSION` | String | `(none)` | Substrate PodCertificate Helm chart version to deploy. When unset, the CLI uses KAGENT_SUBSTRATE_HELM_VERSION or its pinned Substrate version. |
 | `KUBECONFIG` | String | `(none)` | Kubernetes client configuration file list for the controller, CLI Kubernetes operations, and tests. When unset, client-go uses its normal in-cluster or user kubeconfig discovery. |
 | `OLLAMA_API_KEY` | String | `(none)` | API key for Ollama Cloud. When set, a cloud-tagged model reaches api.ollama.com directly. |
 | `OPENAI_API_KEY` | String | `(none)` | API key for OpenAI. Upgrade tests fall back to a placeholder when unset or empty. |
diff --git a/docs-site/content/kagent/1.x/reference/helm.md b/docs-site/content/kagent/1.x/reference/helm.md
index 75459814..bf248b50 100644
--- a/docs-site/content/kagent/1.x/reference/helm.md
+++ b/docs-site/content/kagent/1.x/reference/helm.md
@@ -11,8 +11,7 @@ A Helm chart for kagent, built with Google ADK
 
 | Repository | Name | Version |
 |------------|------|---------|
-| `${SUBSTRATE_REPO}` | substrate | `${SUBSTRATE_VERSION}` |
-| file://../tools/grafana-mcp | grafana-mcp | 1.0.0-alpha9 |
+| file://../tools/grafana-mcp | grafana-mcp | 1.0.0-alpha12 |
 | https://oauth2-proxy.github.io/manifests | oauth2-proxy | ~10.7.0 |
 | oci://ghcr.io/kagent-dev/kmcp/helm | kmcp | `${KMCP_VERSION}` |
 | oci://ghcr.io/kagent-dev/tools/helm | kagent-tools | 0.3.0 |
@@ -62,6 +61,10 @@ A Helm chart for kagent, built with Google ADK
 | controller.pdb.unhealthyPodEvictionPolicy | string | "" (defer to the Kubernetes default) | `spec.unhealthyPodEvictionPolicy`, one of `IfHealthyBudget` (the Kubernetes default) or `AlwaysAllow`. `AlwaysAllow` lets unhealthy pods be evicted even when the budget is exhausted, which avoids drains wedging on a crash-looping pod. Requires Kubernetes >= 1.27. Omitted from the manifest when empty. |
 | controller.podAnnotations | object | `{}` |  |
 | controller.podLabels | object | `{}` | Additional labels for the controller pod template, merged over the global `podLabels` (per-key; component keys win). Selector labels can never be overridden. |
+| controller.push.allowHTTP | bool | `false` | Allow plain HTTP callback URLs. HTTPS is required by default. |
+| controller.push.allowPrivateNetworks | bool | `false` | Allow callbacks to private, loopback, and link-local addresses. |
+| controller.push.signing.issuer | string | `""` |  |
+| controller.push.signing.secretName | string | `""` |  |
 | controller.readinessProbe | object | httpGet /health on port http, periodSeconds=30 | Custom readiness probe for the controller container. Setting a value replaces the default probe entirely — include a handler (httpGet / exec / tcpSocket / grpc) when overriding. |
 | controller.replicas | int | `1` |  |
 | controller.resources.limits.cpu | int | `2` |  |
@@ -95,32 +98,20 @@ A Helm chart for kagent, built with Google ADK
 | controller.volumeMounts | list | `[]` |  |
 | controller.volumes | list | `[]` |  |
 | controller.watchNamespaces | list | [] (watches all available namespaces) | Namespaces the controller should watch. If empty, the controller will watch ALL available namespaces. |
-| database.postgres.bundled | object | `{"affinity":{},"enabled":true,"image":{"name":"postgres","pullPolicy":"","registry":"docker.io","repository":"library","tag":"18.6-alpine3.23"},"nodeSelector":{},"podLabels":{},"podSecurityContext":{"fsGroup":999,"runAsGroup":999,"runAsNonRoot":true,"runAsUser":999,"seccompProfile":{"type":"RuntimeDefault"}},"resources":{"limits":{"cpu":"500m","memory":"512Mi"},"requests":{"cpu":"250m","memory":"256Mi"}},"securityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}},"storage":"500Mi","storageClassName":"","tolerations":[]}` | Bundled PostgreSQL instance — for development and evaluation only. Not suitable for production. Deployed when enabled is true and url/urlFile are not set. |
-| database.postgres.bundled.affinity | object | `{}` | [Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) rules for the bundled PostgreSQL pod. |
-| database.postgres.bundled.enabled | bool | `true` | Set to false to disable the bundled database and provide your own via url or urlFile. |
-| database.postgres.bundled.image.name | string | `"postgres"` | Bundled PostgreSQL image name |
-| database.postgres.bundled.image.pullPolicy | string | `""` | Bundled PostgreSQL image pull policy. Empty falls back to the top-level imagePullPolicy, then global.imagePullPolicy, then IfNotPresent. A declared default here would shadow both fallbacks. |
-| database.postgres.bundled.image.registry | string | `"docker.io"` | Bundled PostgreSQL image registry |
-| database.postgres.bundled.image.repository | string | `"library"` | Bundled PostgreSQL image repository (org/namespace) |
-| database.postgres.bundled.image.tag | string | `"18.6-alpine3.23"` | Bundled PostgreSQL image tag |
-| database.postgres.bundled.nodeSelector | object | `{}` | Node labels to match for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). |
-| database.postgres.bundled.podLabels | object | `{}` | Additional labels for the bundled PostgreSQL pod template, merged over the global `podLabels` (per-key; component keys win). Selector labels can never be overridden. |
-| database.postgres.bundled.podSecurityContext | object | `{"fsGroup":999,"runAsGroup":999,"runAsNonRoot":true,"runAsUser":999,"seccompProfile":{"type":"RuntimeDefault"}}` | Pod-level security context for the bundled PostgreSQL deployment. |
-| database.postgres.bundled.resources | object | `{"limits":{"cpu":"500m","memory":"512Mi"},"requests":{"cpu":"250m","memory":"256Mi"}}` | Resource requests/limits for the demo PostgreSQL container |
-| database.postgres.bundled.securityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}}` | Container-level security context for the bundled PostgreSQL container. |
-| database.postgres.bundled.storage | string | `"500Mi"` | PersistentVolumeClaim size for demo PostgreSQL data |
-| database.postgres.bundled.storageClassName | string | `""` | StorageClass for the PostgreSQL PVC. Defaults to the cluster default when empty. |
-| database.postgres.bundled.tolerations | list | `[]` | Node taints which will be tolerated for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). |
+| database.postgres.clientCertificate | object | `{"enabled":false}` | Project the bundled PostgreSQL client certificate. The connection string must reference the files under /run/postgres.podcert.ate.dev. |
+| database.postgres.connectionStringSecretRef | object | `{"key":"connectionString","name":"kagent-postgres"}` | Source the PostgreSQL connection string from a pre-created Secret. Secret changes require restarting the controller. |
 | database.postgres.pool | object | `{"maxConnIdleTime":"","maxConnLifetime":"","maxConns":null,"minConns":null}` | Optional pgxpool settings. Leave unset/null to keep pgx library defaults (MaxConns≈max(4,NumCPU), MinConns=0, MaxConnIdleTime=30m, MaxConnLifetime=1h). |
+| database.postgres.pool.maxConnLifetime | string | `""` | Maximum physical connection lifetime. |
+| database.postgres.role | string | `"kagent_owner"` | Role assumed on each Kagent connection. Set a distinct role for each install sharing a database. |
+| database.postgres.schema | string | `"kagent"` | Schema for Kagent tables. |
 | database.postgres.skipMigrations | bool | `false` | Skip running database migrations at controller startup. The controller instead verifies the database is already migrated and fails if it is not. Migrations must be applied out-of-band (e.g. from a CI/CD pipeline) before install/upgrade. |
-| database.postgres.url | string | `""` | External PostgreSQL connection string. Is always used if set regardless of the `.bundled.enabled` field. |
-| database.postgres.urlFile | string | `""` | Path to a file containing the database URL. Takes precedence over url when set. Is always used if set regardless of the `.bundled.enabled` field. |
 | database.postgres.vectorEnabled | bool | `false` | Enable the pgvector migration Required to use features that depend on database vector capability. (e.g. long-term memory) Set to true when using an external PostgreSQL that has the pgvector extension installed. |
+| database.postgres.vectorSchema | string | `"extensions"` | Schema for the shared pgvector extension. Existing installations must match this value. Kagent needs USAGE on this schema; only trusted administrators should have CREATE on it. |
 | extraObjects | list | [] | Additional arbitrary Kubernetes manifests to deploy alongside the chart. Each list entry is rendered through `tpl`, so values may reference the release context (e.g. `{{ include "kagent.fullname" . }}`, `{{ .Release.Namespace }}`). Both map and multi-line string entries are supported. Use this to manage resources such as ExternalSecret, HTTPRoute, or NetworkPolicy within the same chart lifecycle without maintaining a separate chart.  To use, replace the empty list below with your manifests, e.g.:   extraObjects:     - apiVersion: external-secrets.io/v1       kind: ExternalSecret       metadata:         name: '`{{ include "kagent.fullname" . }}`-openai'         namespace: '`{{ .Release.Namespace }}`'       spec:         secretStoreRef:           name: aws-secretsmanager           kind: ClusterSecretStore         target:           name: kagent-openai         data:           - secretKey: OPENAI_API_KEY             remoteRef:               key: prod/kagent/openai               property: api_key |
 | fullnameOverride | string | `""` |  |
 | global.imagePullPolicy | string | `""` | Fallback imagePullPolicy where neither a component nor the top-level imagePullPolicy sets one. |
 | global.imagePullSecrets | list | `[]` | Pull secrets for every pod. The chart merges this list (union) into each pod's own imagePullSecrets, so a local secret is never removed. Coverage matches imageRegistry above. |
-| global.imageRegistry | string | `""` | Registry that overrides every per-image registry when set. This is the air-gap mirror knob: one value redirects all images. Repository and tag stay per-image. For per-image control, leave this unset and set the per-image registry keys. Covers this chart's own images: controller, sandbox guest, ui, bundled postgres, grafana-mcp, and substrateWorkerPool.workerImage. The vendored subcharts (kagent-tools, kmcp, substrate) adopt it when their pinned versions bump. |
+| global.imageRegistry | string | `""` | Registry that overrides every per-image registry when set. This is the air-gap mirror knob: one value redirects all images. Repository and tag stay per-image. For per-image control, leave this unset and set the per-image registry keys. Covers this chart's own images: controller, sandbox guest, ui, grafana-mcp, and substrateWorkerPool.workerImage. The vendored subcharts (kagent-tools, kmcp) adopt it when their pinned versions bump. |
 | global.watchNamespaces | list | `[]` | Namespace scope for the whole install. A non-empty list replaces ClusterRoles with Roles and scopes the controller's watch. Both derive from this one value, so they cannot disagree. Prefer this value over the per-surface keys. rbac.namespaces overrides it when the key is present. An explicit empty rbac.namespaces restores cluster-scoped RBAC. Mixing in controller.watchNamespaces is validated: the watch must stay inside the RBAC scope. A watched namespace without a Role is a permanent Forbidden loop at runtime. |
 | grafana-mcp.enabled | bool | `true` |  |
 | grafana-mcp.grafana.serviceAccountToken | string | `""` |  |
@@ -137,6 +128,7 @@ A Helm chart for kagent, built with Google ADK
 | kagent-tools.nodeSelector | object | `{}` | Node labels to match for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). |
 | kagent-tools.podSecurityContext.runAsNonRoot | bool | `true` |  |
 | kagent-tools.podSecurityContext.seccompProfile.type | string | `"RuntimeDefault"` |  |
+| kagent-tools.remoteMCPServer.allowedNamespaces | object | `{}` | Namespaces whose Agents may reference the tool server (spec.allowedNamespaces). Unset by default, which allows only the release namespace. Example: allowedNamespaces:   from: Selector   # All | Same | Selector   selector:     matchLabels:       kagent-tools: allowed |
 | kagent-tools.replicaCount | int | `1` |  |
 | kagent-tools.resources.limits.memory | string | `"256Mi"` |  |
 | kagent-tools.resources.requests.cpu | string | `"50m"` |  |
@@ -244,10 +236,10 @@ A Helm chart for kagent, built with Google ADK
 | rbac | object | `{}` |  |
 | registry | string | `"ghcr.io"` |  |
 | securityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true}` | Security context for all containers |
-| substrate.ateApi.extraArgs[0] | string | `"--template-resync-interval=250ms"` |  |
-| substrate.credentialProvider.namespacePolicies | list | `[]` |  |
-| substrate.enabled | bool | `false` |  |
-| substrateWorkerPool | object | `{"create":false,"labels":{},"name":"kagent-default","replicas":1,"sandboxClass":"gvisor","template":{},"workerImage":""}` | Optional Agent Substrate WorkerPool installed by this chart. This is platform capacity and is not owned by individual agents. |
+| substrateWorkerPool | object | `{"create":false,"labels":{},"name":"kagent-default","replicas":1,"sandboxClass":"gvisor","serviceAccount":{"create":true,"name":""},"template":{},"workerImage":""}` | Optional Agent Substrate WorkerPool installed by this chart. This is platform capacity and is not owned by individual agents. |
+| substrateWorkerPool.serviceAccount | object | `{"create":true,"name":""}` | ServiceAccount settings for the worker pods |
+| substrateWorkerPool.serviceAccount.create | bool | `true` | Create the worker ServiceAccount. Set to false to use one managed outside the chart. |
+| substrateWorkerPool.serviceAccount.name | string | `<substrateWorkerPool.name>` | Name of the worker ServiceAccount. |
 | tag | string | `""` |  |
 | tolerations | list | `[]` | Node taints which will be tolerated for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). |
 | ui.additionalForwardedHeaders | list | `[]` | Identity headers the UI's nginx proxy will forward to the backend on /api/, /a2a/, and /mcp. Names are case-insensitive. Authorization is always forwarded; the auth-proxy identity headers (x-auth-request-*, x-forwarded-user, x-forwarded-email, x-forwarded-groups, x-forwarded-preferred-username) are stripped from client requests unless listed here, so a caller cannot spoof an identity the backend trusts. Headers outside that set are forwarded by nginx as normal. In trusted-proxy mode, X-Agent-Name and X-User-Id are always stripped, even if listed here. |
diff --git a/docs-site/content/kagent/1.x/reference/release-notes/1.0.md b/docs-site/content/kagent/1.x/reference/release-notes/1.0.md
index cbbadd23..792a9f94 100644
--- a/docs-site/content/kagent/1.x/reference/release-notes/1.0.md
+++ b/docs-site/content/kagent/1.x/reference/release-notes/1.0.md
@@ -27,7 +27,7 @@ The single 0.10.x `Agent` resource described both what an agent does and how it
 
 - **A {{< gloss "Harness" >}}Harness{{< /gloss >}} defines how an agent is allowed to run**: its runtime, workload image, {{< gloss "WorkerPool" >}}WorkerPool{{< /gloss >}}, and snapshot storage. One Harness serves many agents, so expect fewer Harnesses than you had 0.10.x Agents.
 - **An {{< gloss "AgentTemplate" >}}AgentTemplate{{< /gloss >}} defines what an agent does**: its model, system prompt, tools, skills, and plugins.
-- **An {{< gloss "Agent" >}}Agent{{< /gloss >}} pairs one AgentTemplate with one Harness.** Each side takes either a reference to an existing resource or a complete inline spec. The Agent owns readiness and is what callers address.
+- **An {{< gloss "Agent" >}}Agent{{< /gloss >}} pairs one AgentTemplate with one Harness.** `spec.template` takes either a reference to an existing AgentTemplate or a complete inline spec, while `spec.harnessRef` takes a reference only. The Agent owns readiness, and callers address the Agent rather than the AgentTemplate or the Harness.
 - **A {{< gloss "Session" >}}Session{{< /gloss >}} is one running conversation** with an Agent. Unlike the other three, a Session is not a custom resource: kagent's gRPC API creates it and kagent's database tracks it.
 
 Nothing pairs a Harness and an AgentTemplate implicitly. Neither resource carries a field naming the other, so an Agent is what makes a template runnable on a Harness. For the full model, see [Core concepts]({{< link path="about/core-concepts#agent" >}}).
diff --git a/docs-site/content/kagent/1.x/reference/tools-ecosystem.md b/docs-site/content/kagent/1.x/reference/tools-ecosystem.md
index bb0ab004..15133ea9 100644
--- a/docs-site/content/kagent/1.x/reference/tools-ecosystem.md
+++ b/docs-site/content/kagent/1.x/reference/tools-ecosystem.md
@@ -275,6 +275,34 @@ Because the settings are per-installation, they change what every agent sees. To
 > [!WARNING]
 > A tool binding's tool list does not narrow anything on the Claude {{< gloss "Harness" >}}Harness{{< /gloss >}}. The compiler exposes the whole server instead, and names the tools that you selected in a warning on the AgentTemplate's `status.harnesses[].warnings`. The kagent and Codex harnesses both honor the list. Where an agent runs on the Claude harness and must not reach a tool, narrow the server with `tools.enabledTools` or `--read-only` rather than with the binding.
 
+## Reach kagent-tool-server from another namespace
+
+The chart creates the `kagent-tool-server` RemoteMCPServer in the release namespace, and a RemoteMCPServer admits references from its own namespace only. Where an AgentTemplate in another namespace binds the server, the controller cannot resolve the binding and the AgentTemplate does not become ready. To admit another namespace, set `allowedNamespaces` on the RemoteMCPServer that the chart creates.
+
+```yaml
+kagent-tools:
+  remoteMCPServer:
+    allowedNamespaces:
+      from: Selector
+      selector:
+        matchLabels:
+          kagent-tools: allowed
+```
+
+| Field | Description |
+| ----- | ----------- |
+| `allowedNamespaces.from` | Where a reference may originate, one of `All`, `Same`, or `Selector`. Defaults to `Same`. The default admits the release namespace only. |
+| `allowedNamespaces.selector` | A label selector over namespaces. The server reads this field only where `from` is `Selector`, and the selector takes `matchLabels` and `matchExpressions`. |
+
+The selector follows the Gateway API pattern for cross-namespace attachment, so the label belongs on the Namespace rather than on the AgentTemplate that binds the server.
+
+```bash
+kubectl label namespace my-agents kagent-tools=allowed
+```
+
+> [!NOTE]
+> Admitting a namespace grants every agent in that namespace the server's full cluster authority, because all of the server's callers share one ServiceAccount. Narrow the server with `rbac.readOnly` before you widen `allowedNamespaces`.
+
 ## kagent-grafana-mcp
 
 The `kagent-grafana-mcp` server runs [mcp-grafana](https://github.com/grafana/mcp-grafana), Grafana's own MCP server. The kagent chart packages it as a subchart. Its tools fall into four groups:
diff --git a/docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md b/docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md
index c5674597..757da8f0 100644
--- a/docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md
+++ b/docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md
@@ -46,7 +46,7 @@ The `AzureOpenAI` provider calls an Azure OpenAI deployment. It differs from the
    | `model` | The model that the deployment serves. |
    | `provider` | The provider to use, `AzureOpenAI`. |
    | `azureOpenAI.azureEndpoint` | The endpoint of your Azure OpenAI resource. This field is required. |
-   | `azureOpenAI.apiVersion` | The Azure OpenAI API version to call. This field is required. |
+   | `azureOpenAI.apiVersion` | The Azure OpenAI API version to call. This field is required unless `apiFormat` is `responses`. |
    | `azureOpenAI.azureDeployment` | The name of the deployment within the resource. |
 
 ## Azure OpenAI provider settings
@@ -56,13 +56,42 @@ The `azureOpenAI` block takes the following settings. For every field, including
 | Field | Description |
 | ----- | ----------- |
 | `azureEndpoint` | The endpoint of the Azure OpenAI resource. Required. |
-| `apiVersion` | The Azure OpenAI API version. Required. |
+| `apiFormat` | Which Azure OpenAI HTTP API to call, either `chatCompletions` or `responses`. Defaults to `chatCompletions`. |
+| `apiVersion` | The Azure OpenAI API version. Required unless `apiFormat` is `responses`. |
 | `azureDeployment` | The deployment name within the resource. |
 | `azureAdToken` | A Microsoft Entra ID token to send instead of an API key. |
 | `temperature` | How much randomness the model applies when it picks the next token. |
 | `topP` | The nucleus sampling cutoff. |
 | `maxTokens` | A cap on the tokens generated in one response. |
 
+## Choose an API format
+
+`apiFormat` selects which Azure OpenAI HTTP API the runtime calls. Keep the default unless a model that you deployed serves the Responses API only, because the two formats differ in how they address a deployment and in whether they take a dated API version.
+
+| Value | What the runtime calls | `azureOpenAI.apiVersion` |
+| ----- | ---------------------- | ------------------------ |
+| `chatCompletions` | The dated deployments path, which addresses `azureDeployment` under a pinned API version. This value is the default. | Required. The API server rejects a ModelConfig that omits it. |
+| `responses` | The Azure Responses API at `<azureEndpoint>/openai/v1/`. This surface takes no dated version. | Omit this field. |
+
+The following ModelConfig calls the Responses API.
+
+```yaml
+apiVersion: api.kagent.dev/v1alpha3
+kind: ModelConfig
+metadata:
+  name: azure-openai-responses
+  namespace: kagent
+spec:
+  apiKeySecret: azure-openai-api-key
+  apiKeySecretKey: api-key
+  model: gpt-4o-mini
+  provider: AzureOpenAI
+  azureOpenAI:
+    azureEndpoint: https://<account>.openai.azure.com/
+    apiFormat: responses
+    azureDeployment: gpt-4o-mini
+```
+
 ## Authentication
 
 | Configuration | Credential |