docs: refresh architecture documentation

docs/architecture/README.md

@@ -1,15 +1,92 @@
 # Architecture
 
-Kagent defines portable agent behavior with `AgentTemplate` and compiles it
-through an admitted `Harness`. The resulting revision is applied to a Substrate
-ActorTemplate. PostgreSQL-backed `AgentInstance` records own lifecycle and public
-A2A contexts; they are not Kubernetes resources.
+Kagent is a Kubernetes-native control plane for defining, compiling, running,
+and invoking agents. Kubernetes stores desired agent configuration. PostgreSQL
+stores runtime identity, A2A history, and lifecycle state. Substrate Actors run
+the agent processes.
 
-Detailed documents:
+## Resource ownership
 
-- [Human in the loop](human-in-the-loop.md)
-- [Prompt templates](prompt-templates.md)
+| Resource | Owner | Purpose |
+| --- | --- | --- |
+| `Harness` | Kubernetes (`kagent.dev/v1alpha3`) | Runtime implementation, workload, credentials, capacity, and admission policy |
+| `AgentTemplate` | Kubernetes (`kagent.dev/v1alpha3`) | Portable agent behavior: model, prompt, tools, skills, and plugins |
+| prepared revision | PostgreSQL and ate-api | Immutable compiled runtime input and its Substrate ActorTemplate |
+| `AgentInstance` | PostgreSQL, exposed by gRPC | Ephemeral compute identity and lifecycle |
+| A2A context, task, and events | PostgreSQL, exposed by A2A | Durable interaction and audit history |
+| checkpoint | PostgreSQL plus a Substrate snapshot tag | Immutable, named restart boundary |
+| Actor and durable directory | Substrate | Process lifecycle and private runtime state |
+
+`AgentInstance` is not a Kubernetes resource. A2A owns public interaction
+semantics; kagent does not maintain a parallel session or task API.
+
+## Public surfaces
+
+| Surface | Role |
+| --- | --- |
+| Kubernetes API | Author Harnesses, AgentTemplates, models, prompts, and remote MCP servers |
+| gRPC / gRPC-Web | Manage AgentInstances, sharing, checkpoints, and control-plane reads |
+| A2A | Invoke agents and manage durable tasks and streams |
+| MCP | Discover, invoke, checkpoint, and fork AgentInstances through A2A semantics |
+
+## End-to-end flow
+
+```mermaid
+flowchart LR
+    AT[AgentTemplate] --> R[resolve tree]
+    H[Harness] --> R
+    R --> B[build harness inputs]
+    B --> C[registered harness compiler]
+    C --> REV[immutable revision]
+    REV --> ATE[ate-api ActorTemplate]
+    ATE --> SNAP[golden snapshot ready]
+    SNAP --> AI[AgentInstance]
+    AI --> ACTOR[Substrate Actor]
+    CLIENT[A2A client] --> GW[public A2A gateway]
+    GW --> ACTOR
+    GW --> DB[(tasks and events)]
+    GW --> QUIESCE[auto-suspend at quiescence]
+    QUIESCE --> CKPT[checkpoint tag]
+    CKPT --> FORK[forked AgentInstance]
+```
+
+Compilation and application are separate. The translator produces an immutable
+revision; the controller applies it through ate-api. At runtime, the public A2A
+gateway is the sole owner of task ingestion, durable event ordering, and
+quiescence. It reaches Actors through the private runtime network.
+
+## Component boundaries
+
+- API types describe agent behavior without exposing backend mechanics.
+- The v2 translator resolves references and compiles explicit runtime inputs.
+- The controller reconciles compiled revisions to ate-api ActorTemplates.
+- AgentInstance services and workflows own lifecycle orchestration.
+- The A2A gateway owns public task routing, persistence, streaming, and
+  auto-suspend boundaries.
+- The store owns transactional invariants and never performs network work.
+- Substrate adapters own Actor, snapshot, and private-network operations.
+
+## Documents
+
+- [Configuration and compilation](configuration-and-compilation.md)
+- [Runtime and lifecycle](runtime-and-lifecycle.md)
+- [A2A gateway](a2a-gateway.md)
+- [Persistence, checkpoints, and forks](persistence-checkpoints-and-forks.md)
+- [MCP](mcp.md)
 - [A2A agent tools](a2a-subagents.md)
+- [Human in the loop](human-in-the-loop.md)
+- [Prompt resolution](prompt-templates.md)
+
+The documents describe implemented behavior. Deferred work, including full
+cross-AgentInstance delegation and Dedicated agents, belongs in the
+[API v2 execution plan](../plans/api-v2-execution-plan.md).
+
+## Current boundaries
+
+Implemented end to end: kagent, Codex, Claude, and BYO compilation; ate-api
+ActorTemplates; AgentInstance lifecycle; durable A2A tasks; auto-suspend;
+checkpoint/fork; and MCP Tasks continuation.
 
-The implementation roadmap and dependency graph live in
-[the API v2 execution plan](../plans/api-v2-execution-plan.md).
+Not implemented: Dedicated agent bindings, policy-enforced public
+cross-AgentInstance delegation, checkpoint sharing, and multi-replica gateway
+coordination.

docs/architecture/a2a-gateway.md

@@ -0,0 +1,49 @@
+# A2A Gateway
+
+The public gateway implements the upstream A2A handler for message send/stream,
+task get/list/cancel, and subscription. It also serves the extended Agent Card
+compiled into the instance's prepared revision.
+
+## Routing and execution
+
+Authentication establishes namespace and AgentInstance authority. The gateway
+loads the instance and prepared revision, derives the private Actor route, and
+forwards upstream A2A requests. Actor addresses and runtime credentials remain
+internal.
+
+Each running task has one event ingester. It alone owns runtime event consumption,
+durable persistence, and the final quiescence transition; client streams and
+subscribers only observe its queue. This permits multiple observers without
+creating multiple Actor readers or suspending the same turn twice.
+
+```mermaid
+flowchart LR
+    ACTOR[private Actor stream] --> INGEST[one task event ingester]
+    INGEST -->|1. append event and update task| DB[(PostgreSQL)]
+    DB -->|2. committed| INGEST
+    INGEST -->|3. publish| Q[event queue]
+    Q --> SEND[original send stream]
+    Q --> SUB1[subscriber]
+    Q --> SUB2[subscriber]
+    INGEST -->|at quiescence| SUSPEND[AgentInstance workflow]
+```
+
+## Durable ordering
+
+The gateway persists the task and every ordered event before publishing the event
+to observers. The store atomically applies an event to materialized task state and
+appends its history row. Malformed durable events fail rather than being silently
+discarded.
+
+The persistence model enforces:
+
+- one non-quiescent task per A2A context;
+- message-ID idempotency using the request hash;
+- conflict rejection when an ID is reused for different content; and
+- an exact snapshot identity and history sequence at each quiescent boundary.
+
+Tasks contain current materialized A2A state. Complete message history is rebuilt
+from ordered event rows, not stored as one history blob.
+
+The implementation is in
+[`go/core/v2/a2agateway`](../../go/core/v2/a2agateway).

docs/architecture/a2a-subagents.md

@@ -1,19 +1,41 @@
 # A2A Agent Tools
 
-Kagent runtimes can expose another A2A agent as a tool. Each invocation sends an
-A2A message with a context ID and returns the child result together with that
-context ID. A binding may reuse one context for consecutive calls or isolate each
-call in a fresh context.
+Kagent has two distinct subagent mechanisms. They should not be confused.
 
-If the child task enters `input_required`, the tool records the child task and
-context IDs in the parent's approval state. Continuing the parent forwards the
-answer to that same child task. Authentication, user identity, and lineage headers
-are forwarded by A2A client interceptors.
+```mermaid
+flowchart TB
+    PARENT[Parent agent]
+    PARENT -->|Shared binding compiled into one runtime| LOCAL[Native in-process subagent]
+    PARENT -->|remote A2A tool call| REMOTE[Addressable A2A agent]
+    REMOTE -->|task + context IDs retained| CONTINUE[input-required continuation]
+    DEDICATED[Dedicated binding] -. deferred .-> SEPARATE[separate AgentInstance]
+    PUBLIC[Public cross-instance delegation] -. deferred .-> POLICY[credential and lineage policy]
+```
 
-The Go and Python implementations are:
+## Shared agent tools
 
-- `go/adk/pkg/tools/remote_a2a_tool.go`
-- `python/packages/kagent-adk/src/kagent/adk/_remote_a2a_tool.py`
+An `AgentTemplate` can bind another template as a `Shared` agent tool. The
+translator resolves the referenced template in the same compilation tree and
+the selected harness compiler emits its native, in-process representation.
+Kagent, Codex, and Claude support Shared bindings according to their runtime
+capabilities.
 
-Public cross-AgentInstance delegation remains tracked in the API v2 execution
-plan; this runtime tool does not replace gateway-level delegation policy.
+Tree resolution detects missing references and cycles before compilation.
+`Dedicated` bindings are represented in the API but are currently rejected;
+they do not create a separate AgentInstance today.
+
+## Runtime remote A2A tools
+
+The Go and Python ADKs also contain a remote A2A tool. Each call sends an A2A
+message to an already-addressable remote agent and preserves the child task and
+context IDs. If the child enters `input-required`, the parent can retain those
+identifiers and continue the same child task after receiving human input.
+
+Implementations:
+
+- [`go/adk/pkg/tools/remote_a2a_tool.go`](../../go/adk/pkg/tools/remote_a2a_tool.go)
+- [`python/packages/kagent-adk/src/kagent/adk/_remote_a2a_tool.py`](../../python/packages/kagent-adk/src/kagent/adk/_remote_a2a_tool.py)
+
+This runtime helper is not public cross-AgentInstance delegation. Gateway-level
+delegation still requires scoped credentials, lineage/depth/cycle enforcement,
+and streamed child execution; that work is deferred in the execution plan.

docs/architecture/configuration-and-compilation.md

@@ -0,0 +1,77 @@
+# Configuration and Compilation
+
+## Public configuration
+
+`Harness` describes how to run a class of agents. It selects exactly one runtime
+variant—kagent, Codex, Claude, or BYO—and contains workload image/command/args,
+environment and credential references, WorkerPool configuration, snapshot
+location, and an admission selector.
+
+`AgentTemplate` describes what the agent does. It contains model configuration,
+description and prompt, MCP tool bindings, skills, plugins, and Shared or
+Dedicated agent bindings. Model configuration may be omitted for BYO images;
+pair compilation rejects managed harness combinations without one.
+
+Both are `kagent.dev/v1alpha3` Kubernetes resources. Infrastructure-derived
+values such as runtime addresses and inferred egress do not belong in the public
+API.
+
+## Prepared revision pipeline
+
+The v2 controller collects admitted Harness/AgentTemplate pairs and compiles each
+pair through one pipeline:
+
+```mermaid
+flowchart TD
+    H[Harness] --> MATCH{admission selector matches}
+    AT[AgentTemplate] --> MATCH
+    MATCH --> RESOLVE[resolve template tree and references]
+    RESOLVE --> INPUTS[build explicit inputs]
+    INPUTS --> REGISTRY{runtime type}
+    REGISTRY --> K[kagent compiler]
+    REGISTRY --> X[Codex compiler]
+    REGISTRY --> C[Claude compiler]
+    REGISTRY --> B[BYO compiler]
+    K --> REV[immutable revision and digest]
+    X --> REV
+    C --> REV
+    B --> REV
+    REV --> ATE[ate-api ActorTemplate]
+    ATE --> GOLDEN[golden snapshot]
+    GOLDEN -->|ready| LATEST[latest successful revision]
+    RESOLVE -->|error| STATUS[pair status]
+    ATE -->|error| STATUS
+```
+
+1. Resolve the template tree and referenced Kubernetes objects.
+2. Build explicit, harness-independent inputs.
+3. Select the harness compiler from the runtime-type registration map.
+4. Produce an immutable revision containing workload, configuration, Agent Card,
+   capacity, snapshot, provenance, and inferred egress inputs.
+5. Hash the revision and apply it as an ate-api ActorTemplate.
+6. Wait for the golden snapshot to become ready.
+7. Persist the revision and advance the pair's latest-successful pointer.
+
+A failed compile or apply leaves the previous successful revision available.
+AgentInstances pin a prepared revision, so later template edits do not mutate a
+running instance.
+
+Harness compilers only translate inputs. The controller and Substrate adapter own
+application and readiness. The central entry points are
+[`translator/compiler.go`](../../go/core/v2/translator/compiler.go) and
+[`controller/reconciler.go`](../../go/core/v2/controller/reconciler.go).
+
+## Harness-specific output
+
+- **kagent** emits Go ADK configuration, Shared native subagents, and the kagent
+  HITL extension.
+- **Codex** emits native App Server configuration, OpenAI or Bedrock model setup,
+  Streamable HTTP MCP servers, Shared agents, and skills. Approvals are currently
+  disabled by policy.
+- **Claude** emits Anthropic, Bedrock, or Vertex model setup, HTTP/SSE MCP
+  servers, Shared agents, and skills.
+- **BYO** runs a digest-pinned user image that implements private A2A gRPC and
+  `/readyz`. Optional model, prompt, tool, skill, and plugin configuration is
+  supplied in the ADK-shaped format when requested.
+
+Dedicated agent bindings are not compiled yet.