[Automated] Draft docs (kagent): core: support cross-namespace ModelConfig and RemoteMCPServer with…

docs-site/content/kagent/1.x/agents/agent-memory.md

@@ -106,7 +106,7 @@ spec:
 
 Add memory to a Harness that already exists. The examples in these steps use `my-first-harness` in the `kagent` namespace, which you create in [Your first agent]({{< link path="get-started/your-first-agent" >}}).
 
-1. Create a `ModelConfig` for the embedding model in the same namespace as your Harness. The model is an embedding model rather than a chat model.
+1. Create a ModelConfig for the embedding model. This example keeps the ModelConfig in the same namespace as your Harness. The model is an embedding model rather than a chat model.
    ```yaml
    kubectl apply -f - <<EOF
    apiVersion: api.kagent.dev/v1alpha3
@@ -137,7 +137,8 @@ Add memory to a Harness that already exists. The examples in these steps use `my
    {{< reuse "kagent-docs/snippets/review-table.md" >}} To review other available Harness fields, see [Agent harness]({{< link path="agents/agent-harness" >}}).
    | Field | Description |
    | ----- | ----------- |
-   | `memory.modelConfigRef.name` | The ModelConfig supplying the embedding model, in the Harness's namespace. Required when `memory` is set. |
+   | `memory.modelConfigRef.name` | The ModelConfig supplying the embedding model. Required when `memory` is set. |
+   | `memory.modelConfigRef.namespace` | Optional. The ModelConfig namespace. Omit this field to use the Harness namespace. A shared ModelConfig in another namespace must permit the Harness namespace with `allowedNamespaces`. |
    | `memory.ttlDays` | How many days a stored memory stays valid. Minimum 1. When omitted, the server applies a default of 15 days. |
 
 3. Create a new Session against an {{< gloss "Agent" >}}Agent{{< /gloss >}} that uses this Harness. Editing the Harness builds a new {{< gloss "Revision" >}}revision{{< /gloss >}}, and an existing Session keeps running the revision it was created from. An agent that was already running does not gain memory until you start a new Session.

docs-site/content/kagent/1.x/agents/context-management.md

@@ -37,7 +37,7 @@ spec:
       # but keep the 10 most recent events uncompacted.
       tokenThreshold: 24000
       eventRetentionSize: 10
-      # Optional: name a ModelConfig (in this Harness's namespace) to write the
+      # Optional: name a ModelConfig to write the
       # summaries. When you omit it, the agent's own model summarizes.
       summarizer:
         modelConfigRef:
@@ -67,7 +67,7 @@ The table below lists the compaction fields and their requirements:
 | `overlapSize` | Optional | The number of already-compacted invocations pulled back into the next sliding window so consecutive summaries overlap. Requires `compactionInterval`. Minimum 0. |
 | `tokenThreshold` | Optional | The prompt token count at which tail-retention compaction summarizes the history before the next model call. Requires `eventRetentionSize`. Minimum 1. |
 | `eventRetentionSize` | Optional | The number of most recent events that tail retention keeps uncompacted. Requires `tokenThreshold`. Minimum 1. |
-| `summarizer.modelConfigRef` | Optional | The {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}} in the Harness namespace that writes the summaries. When you omit it, the agent's own model summarizes. |
+| `summarizer.modelConfigRef` | Optional | The {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}} that writes the summaries. Omit `summarizer.modelConfigRef.namespace` to use the Harness namespace. A shared ModelConfig in another namespace must permit the Harness namespace with `allowedNamespaces`. When you omit `summarizer.modelConfigRef`, the agent's own model summarizes. |
 | `summarizer.promptTemplate` | Optional | Replaces the runtime's default summarization prompt. Must contain `{conversation_history}`, which the runtime replaces with the rendered events. |
 
 ## Admission rules
@@ -87,7 +87,7 @@ Naming an AgentTemplate's own model in `summarizer.modelConfigRef` is semantical
 
 ## Verify the configuration
 
-If the summarizer names a ModelConfig that does not exist in the Harness namespace, the Agent is not ready. The failure surfaces on the Agent as `ResolvedRefs=False`, with a reason such as `resolve summarizer ModelConfig "x": model config "x" not found`. Confirm that the Agent is ready before relying on compaction:
+If the summarizer names a ModelConfig that kagent cannot resolve, or that `allowedNamespaces` does not permit the Harness namespace, the Agent is not ready. The failure surfaces on the Agent as `ResolvedRefs=False`, with a reason such as `resolve summarizer ModelConfig "x": model config "x" not found`. Confirm that the Agent is ready before relying on compaction:
 
 ```bash
 kagent agent get <agent-name>

docs-site/content/kagent/1.x/agents/declarative-agents.md

@@ -43,7 +43,7 @@ Compaction offers two strategies. Tail retention summarizes the older history on
 
 | Field | Description |
 | ----- | ----------- |
-| `memory.modelConfigRef.name` | The {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}} that supplies the embedding model, in the Harness's namespace. Required when `memory` is set. Setting `memory` gives every agent on this Harness memory that persists across conversations. For how agents store and retrieve it, see [Agent memory]({{< link path="agents/agent-memory" >}}). |
+| `memory.modelConfigRef.name` | The {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}} that supplies the embedding model. Required when `memory` is set. Omit `memory.modelConfigRef.namespace` to use the Harness namespace. A shared ModelConfig in another namespace must permit the Harness namespace with `allowedNamespaces`. Setting `memory` gives every agent on this Harness memory that persists across conversations. For how agents store and retrieve it, see [Agent memory]({{< link path="agents/agent-memory" >}}). |
 | `memory.ttlDays` | How many days a stored memory entry stays valid. Minimum 1. When omitted, the server applies a default of 15 days. |
 | `compaction.tokenThreshold` | Tail retention. The prompt token count that triggers a summary. Once the prompt passes this count, kagent summarizes the older history before the next model call. Requires `compaction.eventRetentionSize`. |
 | `compaction.eventRetentionSize` | Tail retention. The number of most recent events that kagent leaves out of that summary, so the latest exchanges reach the model in full. Requires `compaction.tokenThreshold`. |

docs-site/content/kagent/1.x/get-started/your-first-mcp-tool.md

@@ -77,7 +77,8 @@ kagent records what it discovered on the server's status, so the tool names come
    | Field | Description |
    | ----- | ----------- |
    | `mcp.server.kind` | The kind of server resource. `RemoteMCPServer` is the only accepted value. |
-   | `mcp.server.name` | The server's name. A binding resolves in the AgentTemplate's own namespace, so it cannot reach a server in another namespace. |
+   | `mcp.server.name` | The server's name. |
+   | `mcp.server.namespace` | Optional. The server's namespace. Omit this field to use the AgentTemplate namespace. A server in another namespace must set `allowedNamespaces` to permit the AgentTemplate namespace. |
    | `mcp.tools` | Optional. The names of the tools to bind, up to 50. An omitted or empty list exposes every tool on the server. An AgentTemplate takes at most 50 bindings in total. |
 
 3. Confirm that kagent compiled a new {{< gloss "Revision" >}}revision{{< /gloss >}} for the Agent that uses the edited template. Every edit produces a new desired revision, and the Agent is current when the latest successful revision matches it.
@@ -91,7 +92,7 @@ kagent records what it discovered on the server's status, so the tool names come
    7c1f9a2b4e8d3f60a5b7c9e1d2f4a6b8c0d2e4f68a9b1c3d5e7f9a1b3c5d7e9f	7c1f9a2b4e8d3f60a5b7c9e1d2f4a6b8c0d2e4f68a9b1c3d5e7f9a1b3c5d7e9f
    ```
 
-   When the two values differ, kagent is still compiling, or compilation failed. A binding that names a RemoteMCPServer that does not exist in the namespace fails at the `ResolvedRefs` condition with the reason `ReferenceResolutionFailed`.
+   When the two values differ, kagent is still compiling, or compilation failed. A binding that names a RemoteMCPServer that kagent cannot resolve, or that the server's `allowedNamespaces` does not permit the AgentTemplate namespace, fails at the `ResolvedRefs` condition with the reason `ReferenceResolutionFailed`.
 
    kagent resolves the server, but it does not check the tool names against the tools that the server actually serves. A misspelled tool name compiles into a ready revision, and the only symptom is an agent that never calls the tool that you expected. If a bound tool appears to be missing, check the spelling against the server's catalog.
 

docs-site/content/kagent/1.x/operations/debug.md

@@ -68,7 +68,7 @@ Each condition covers one stage, and a stage runs only when the stage before it
 | Condition | Stage it covers | A failure here means |
 | --------- | --------------- | -------------------- |
 | `Accepted` | The Agent selects a template and a Harness. | Nothing. kagent writes this condition only as `True`, because an Agent references both resources explicitly. |
-| `ResolvedRefs` | Every resource that the Agent references was found, including its AgentTemplate, its Harness, its ModelConfig, and any tool servers. | A reference points at something that does not exist, or the controller cannot read it. |
+| `ResolvedRefs` | Every resource that the Agent references was found, including its AgentTemplate, its Harness, its ModelConfig, and any tool servers. | A reference points at something that does not exist, the controller cannot read it, or the referenced resource's `allowedNamespaces` denies the Agent namespace. |
 | `Compatible` | The resolved configuration is valid for the Harness. | The configuration asks for something that its Harness does not support. |
 | `Ready` | The ActorTemplate's golden {{< gloss "Snapshot" >}}snapshot{{< /gloss >}} exists, so Sessions can start from it. | Agent Substrate has not finished capturing the golden snapshot, or capture failed. |
 
@@ -87,6 +87,8 @@ Ready=False  Blocked: blocked by ResolvedRefs
 
 The Agent's status reports two revision fields that answer a different question. `desiredRevision` is the {{< gloss "Revision" >}}revision{{< /gloss >}} that the current spec should produce, and `latestSuccessfulRevision` is the newest revision that finished preparing. A missing `latestSuccessfulRevision` means that the Agent was never ready, and two differing values mean that the newest edit is not yet prepared.
 
+When the latest edit fails because a shared ModelConfig or RemoteMCPServer no longer permits the Agent namespace, `latestSuccessfulRevision` continues to report the last prepared revision. New Sessions can still start from that revision until a replacement prepares successfully.
+
 The status also reports a `warnings` list, which shows the compatibility decisions that kagent made without blocking the revision. A warning does not stop an Agent from becoming ready, and the conditions do not report it.
 
 ```bash

docs-site/content/kagent/1.x/operations/operational-considerations.md

@@ -319,6 +319,8 @@ To watch the sweep, scrape `kagent_session_expired_total`, which counts the Sess
 
 kagent watches the Secrets and ConfigMaps that a {{< gloss "Harness" >}}Harness{{< /gloss >}} and {{< gloss "AgentTemplate" >}}AgentTemplate{{< /gloss >}} reference, such as the API keys and TLS certificates in a {{< gloss "ModelConfig" >}}ModelConfig{{< /gloss >}}. An edit to one of them recompiles the pair into a new revision.
 
+A change to a ModelConfig or RemoteMCPServer `allowedNamespaces` policy also recompiles each Agent that references that resource. When a namespace selector policy changes, a matching label change on the source Namespace recompiles the Agent too. If the new policy denies the reference, the new revision fails, but the Agent keeps its last successful revision for new Sessions.
+
 A new revision does not reach the Sessions that are already running. A Session is pinned to the revision that it was created from and keeps that revision for life. To move an existing conversation onto new configuration, create a new Session.
 
 The model provider API key is the exception. Agents do not hold the key. Instead, the Agent Substrate egress gateway reads the key from the Secret and adds it to each model request, so a rotated key reaches running Sessions after you restart the egress gateway. See [Rotate the model provider API key](#rotate-the-model-provider-api-key).

docs-site/content/kagent/1.x/reference/tools-ecosystem.md

@@ -276,7 +276,7 @@ The kagent and Codex harnesses both honor this tool list. On the Claude {{< glos
 
 ## 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 Agent that runs that template does not become ready. To admit another namespace, set `allowedNamespaces` on the RemoteMCPServer that the chart creates.
+The chart creates the `kagent-tool-server` RemoteMCPServer in the release namespace. By default, a RemoteMCPServer admits references only from its own namespace. When an AgentTemplate in another namespace binds the server, set `mcp.server.namespace` to the release namespace and set `allowedNamespaces` on the RemoteMCPServer that the chart creates. Without that policy, the controller rejects the binding and the Agent that runs that template does not become ready.
 
 ```yaml
 kagent-tools:

docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md

@@ -18,6 +18,7 @@ Every ModelConfig shares the same three parts, regardless of the provider that i
 | `provider` | The provider to use.<ul><li>Accepted values are `OpenAI`, `Anthropic`, `AzureOpenAI`, `Ollama`, `Gemini`, `GeminiVertexAI`, `AnthropicVertexAI`, `Bedrock`, `SAPAICore`, `Foundry`, and `Mistral`.</li><li>Defaults to `OpenAI`.</li><li>`AnthropicVertexAI`, `GeminiVertexAI`, and `SAPAICore` are rejected on every harness.</li></ul>For more information, see [Credentials that kagent rejects](#credentials-that-kagent-rejects). |
 | `model` | The model name, as the provider spells it. |
 | `stream` | Whether the agent streams its model calls. Defaults to `true`. Set `false` for an endpoint that rejects streaming, which otherwise fails every turn. |
+| `allowedNamespaces` | Which namespaces can reference this ModelConfig. Defaults to the ModelConfig's own namespace. |
 | Provider block | A block named after the provider, such as `openAI` or `bedrock`, holding the settings that only that provider takes. An empty block is valid when the provider does not take extra settings. |
 
 Credentials come from a Kubernetes Secret in the same namespace as the ModelConfig. The `apiKeySecret` field names the Secret, and `apiKeySecretKey` names the key within that Secret. For every ModelConfig field, including its type, default, and validation rules, see the [API reference]({{< link path="reference/api-ref#modelconfigspec" >}}).
@@ -106,7 +107,7 @@ For the full matrix, including the per-combination restrictions, see [Agent harn
 
 ## Use a ModelConfig
 
-Reference the ModelConfig by name in an AgentTemplate. The ModelConfig must be in the same namespace as the AgentTemplate.
+Reference the ModelConfig by name in an AgentTemplate. When the ModelConfig is in the same namespace as the AgentTemplate, set only `modelConfig.name`. To reference a shared ModelConfig in another namespace, set `modelConfig.namespace` to the ModelConfig's namespace. The ModelConfig's `allowedNamespaces` must permit the AgentTemplate namespace.
 
 ```yaml
 apiVersion: api.kagent.dev/v1alpha3
@@ -120,4 +121,6 @@ spec:
   systemPrompt: You are a concise, helpful assistant.
 ```
 
+Do not use `namespace/name` format. The `name` and `namespace` fields are separate, and an omitted `namespace` resolves in the AgentTemplate namespace.
+
 Editing a ModelConfig produces a new {{< gloss "Revision" >}}revision{{< /gloss >}} for every {{< gloss "Agent" >}}Agent{{< /gloss >}} whose template references it. A {{< gloss "Session" >}}Session{{< /gloss >}} keeps running the revision that it was created from, so create a new Session to pick up a changed model.

docs-site/content/kagent/1.x/setup/model-providers/amazon-bedrock.md

@@ -30,7 +30,7 @@ The native provider authenticates with a Bedrock API key, which kagent sends as
    export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>
    ```
 
-2. Create a Kubernetes Secret that holds the token under the key `AWS_BEARER_TOKEN_BEDROCK`. kagent looks that key up by name, so no other key works. Create the Secret in the same namespace as the AgentTemplates that use it, such as `kagent`.
+2. Create a Kubernetes Secret that holds the token under the key `AWS_BEARER_TOKEN_BEDROCK`. kagent looks that key up by name, so no other key works. Create the Secret in the namespace where you create the ModelConfig, such as `kagent`.
    ```bash
    kubectl create secret generic bedrock-credentials -n kagent \
      --from-literal AWS_BEARER_TOKEN_BEDROCK=$AWS_BEARER_TOKEN_BEDROCK
@@ -119,7 +119,7 @@ Bedrock also serves an [OpenAI-compatible chat completions API](https://docs.aws
 
 ## Use the ModelConfig
 
-Reference the ModelConfig by name from an AgentTemplate in the same namespace.
+Reference the ModelConfig by name from an AgentTemplate. This example keeps the AgentTemplate in the same namespace as the ModelConfig.
 
 ```yaml
 spec:

docs-site/content/kagent/1.x/setup/model-providers/anthropic.md

@@ -17,7 +17,7 @@ The `Anthropic` provider calls the Anthropic API directly.
    export ANTHROPIC_API_KEY=<your_api_key>
    ```
 
-2. Create a Kubernetes Secret that stores the API key. Create it in the same namespace as the AgentTemplates that use it, such as `kagent`.
+2. Create a Kubernetes Secret that stores the API key. Create it in the namespace where you create the ModelConfig, such as `kagent`.
    ```bash
    kubectl create secret generic kagent-anthropic -n kagent --from-literal ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
    ```
@@ -103,7 +103,7 @@ The setting reaches only the generated ModelConfig. A ModelConfig that you creat
 
 ## Use the ModelConfig
 
-Reference the ModelConfig by name from an AgentTemplate in the same namespace.
+Reference the ModelConfig by name from an AgentTemplate. This example keeps the AgentTemplate in the same namespace as the ModelConfig.
 
 ```yaml
 spec:

docs-site/content/kagent/1.x/setup/model-providers/azure-ai-foundry.md

@@ -14,7 +14,7 @@ The `Foundry` provider calls a model deployment in an Azure AI Foundry resource.
    export FOUNDRY_API_KEY=<your-foundry-api-key>
    ```
 
-2. Create a Kubernetes Secret that stores the API key. Create it in the same namespace as the AgentTemplates that use it, such as `kagent`.
+2. Create a Kubernetes Secret that stores the API key. Create it in the namespace where you create the ModelConfig, such as `kagent`.
    ```bash
    kubectl create secret generic foundry-api-key -n kagent --from-literal api-key=$FOUNDRY_API_KEY
    ```
@@ -95,7 +95,7 @@ kubectl describe modelconfig foundry-model-config -n kagent
 
 ## Use the ModelConfig
 
-Reference the ModelConfig by name from an AgentTemplate in the same namespace.
+Reference the ModelConfig by name from an AgentTemplate. This example keeps the AgentTemplate in the same namespace as the ModelConfig.
 
 ```yaml
 spec:

docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md

@@ -14,7 +14,7 @@ The `AzureOpenAI` provider calls an Azure OpenAI deployment. It differs from the
    export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
    ```
 
-2. Create a Kubernetes Secret that stores the API key. Create it in the same namespace as the AgentTemplates that use it, such as `kagent`.
+2. Create a Kubernetes Secret that stores the API key. Create it in the namespace where you create the ModelConfig, such as `kagent`.
    ```bash
    kubectl create secret generic azure-openai-api-key -n kagent --from-literal api-key=$AZURE_OPENAI_API_KEY
    ```
@@ -113,7 +113,7 @@ A link reaches Azure regardless of its media type. Inline bytes reach Azure as a
 
 ## Use the ModelConfig
 
-Reference the ModelConfig by name from an AgentTemplate in the same namespace.
+Reference the ModelConfig by name from an AgentTemplate. This example keeps the AgentTemplate in the same namespace as the ModelConfig.
 
 ```yaml
 spec: