Tracking: re-baseline the 1.x docs for kagent 1.0.0-alpha5 #549

kagent 1.0.0-alpha5 is a breaking re-baseline rather than a point release. Four changes each invalidate large parts of the published 1.x doc set, and they land on overlapping pages, so they need sequencing rather than parallel fixes.

Everything below was verified against the v1.0.0-alpha5 tag on a live cluster or read from the tagged source, not from the release notes.

What changed

1. The API group was renamed

kagent.dev becomes api.kagent.dev. The version stays v1alpha3. The old group is gone from the CRD bases and the Helm chart with no compatibility alias, so every YAML example in the doc set is rejected by the API server.

48 occurrences across 30 files.

2. AgentInstance became Session, and Agent is a new kind

kagent#2952 replaces implicit AgentTemplate/Harness label matching with an explicit Agent resource that pairs the two. Each side takes either a reference or an inline spec.

• allowedAgentTemplates is removed from HarnessSpec entirely. Every example that pairs a template to a harness by label is obsolete. The Harness field table on agents/agent-harness.md documents it as required.
• The conversation resource is Session. The rename runs through protobuf services, PostgreSQL tables, Go clients, the CLI and TUI, MCP, and runtime persistence.
• Subagent tools changed shape: tools[].subAgent with exactly one of templateRef or agentRef. The isolation field is removed.
• There is no upgrade migration. The initial core migration defines the new state directly, and development databases must be recreated.

335 mentions across 47 files, plus three CLI reference pages that no longer describe a real command: kagent-create-agent-instance, kagent-get-agent-instance, kagent-delete-agent-instance.

3. Environment variables moved under KAGENT_

kagent#2967 renamed 138 user-configurable settings and generates docs/env.md as their reference. PORT becomes KAGENT_PORT, LOG_LEVEL becomes KAGENT_LOG_LEVEL, POSTGRES_DATABASE_URL becomes KAGENT_POSTGRES_DATABASE_URL. The old names are no longer read.

OTEL_*, provider credentials, and KUBECONFIG are unchanged. Verified: OTEL_EXPORTER_OTLP_* and OTEL_TRACES_EXPORTER still appear unprefixed in docs/env.md.

agents/bring-your-own-agent.md tells readers to set PORT in a Harness spec.env in five places, and both the Go and Python ADK now read KAGENT_PORT.

4. Controller authentication is wired up

kagent#2971 states that the shipped controller "admits unauthenticated requests, so enabling oauth2-proxy does not authenticate controller requests." It restores controller.auth.mode and controller.auth.userIdClaim.

This changes what substrate-runtime/identity.md asserts, which currently describes the permissive posture as simply how the open source build works. A new caveat needs documenting: ProxyAuthenticator decodes claims without verifying signature or expiry, so trusted-proxy mode requires ingress and network isolation.

Also in alpha5

• A2A endpoints moved again. /agents/{namespace}/{name} replaces the per-instance path added in alpha4, and Session.id is the public contextId.
• Standalone sandboxes shipped. SandboxTemplate and Sandbox CRDs, standalone runtimes, and a kagent sandbox command group. The alpha3 note that this was follow-up work no longer applies.
• The UI creates, edits and deletes explicit Agents, and app extensions can replace chat part renderers.
• Agent Substrate moved to v0.3.0-alpha1.

Sequencing

Do these in order. The mechanical renames land on pages the model change rewrites, so running them in parallel means editing the same files three times.

• API group rename, all 30 files. Verify on a cluster that nothing else moved with it.
• Agent and Session model. The conceptual rewrite: core concepts, agent harness, delegation, every AgentInstance page, and the three dead CLI pages.
• KAGENT_ environment variables. Fold each page's renames into whichever pass is already touching it, rather than a separate sweep.
• Controller authentication, including the unverified-claims isolation requirement.
• Standalone sandboxes. Net-new pages.
• UI coverage for explicit Agents. Needs screenshots.

Existing issues this affects

Adjusted for alpha5 in their own descriptions: #538, #537, #539, #534, #531, #530, #519, #517, #499.

Unaffected, verified: #535 (ui.basePath is still in values.yaml at alpha5) and #521.

Content merged or merging during alpha4 is written against the old model and needs sweeping with everything else:

#529 is a special case worth calling out. It corrects four credential configurations that the published pages describe as supported and that the compiler rejects, and those corrections are not invalidated by alpha5 — re-verified on a cluster on 2026-09-29, all four still reject, and docs/architecture/credential-injection.md at the alpha5 tag now states the rejections are by design. Sweeping those pages for the API group rename must not undo them.