[Automated] Draft docs (kagent): Bump Substrate to 0.5.0-alpha1 and share PostgreSQL via kagent install

[github-actions]

kagent-dev/kagent#2708 — Bump Substrate to 0.5.0-alpha1 and share PostgreSQL via kagent install

Docs versions: 1.x (first shipped in v1.0.0-alpha10)

What changes for users: kagent install now installs kagent, Agent Substrate, the Substrate PodCertificate controller, and a shared development PostgreSQL database that uses Pod Certificates. Direct Helm installs no longer deploy PostgreSQL or Substrate and must use database.postgres.connectionStringSecretRef; checkpoint forks are temporarily rejected with FAILED_PRECONDITION while suspended snapshots include process memory.

What the docs now say: The install, operations, memory, upgrade, uninstall, Substrate, MCP, and UI pages now describe the CLI install path, Secret-based PostgreSQL settings, the development database limits, and the temporary checkpoint fork limitation. Generated environment, Helm, and CLI reference pages were left untouched because the update-ref workflow owns them.

Not verified: No cluster; the installation, Helm values, and checkpoint commands are unrun.

How kagent-2708 was drafted, and what was not verified

• Code PR: Bump Substrate to 0.5.0-alpha1 and share PostgreSQL via kagent install kagent#2708
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha10.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Update the kagent install and PostgreSQL docs for the Substrate 0.5 and shared database change.
• Learned: body.md and the code diff show checkpoint forks are rejected for now, and reference/env-vars.md says the stale reference tables are generated.
• Did: Updated the hand-authored install, operations, memory, migration, uninstall, Substrate, MCP, and UI pages; wrote a breaking-change release note.

Why a documentation change is necessary

The pull request changes the supported installation path: kagent install now creates the development PostgreSQL database, Substrate prerequisites, Substrate releases, and the kagent release. Existing docs said to install Agent Substrate manually, warned that kagent install could not produce a working 1.0 installation, and documented removed Helm values such as database.postgres.url, database.postgres.urlFile, and database.postgres.bundled.*.

The same pull request changes observable runtime behavior for checkpoints. Existing pages told readers to fork checkpoints, but the diff and tests show ForkSession now rejects process-memory checkpoints with FAILED_PRECONDITION until lifecycle v2 restores Data snapshots on suspend.

What changed on disk

• docs-site/content/kagent/1.x/setup/installation.md — Replaced the manual Agent Substrate and Helm flow with the kagent install flow.
• docs-site/content/kagent/1.x/operations/operational-considerations.md — Updated production PostgreSQL guidance to connectionStringSecretRef, role, and Pod Certificate behavior.
• docs-site/content/kagent/1.x/agents/agent-memory.md — Updated memory setup to use a connection Secret instead of urlFile and mounted volumes.
• docs-site/content/kagent/1.x/operations/upgrade-from-0x.md — Updated migration install guidance for the new database Secret values.
• docs-site/content/kagent/1.x/operations/uninstall.md — Updated cleanup guidance for CLI-created PostgreSQL resources, Substrate PodCertificate, and CA pools.
• docs-site/content/kagent/1.x/about/substrate-runtime/suspend-and-resume.md — Documented current Full snapshot behavior and temporary fork rejection.
• docs-site/content/kagent/1.x/about/architecture/agent-substrate.md — Changed the snapshot/tag description so it no longer promises fork availability.
• docs-site/content/kagent/1.x/examples/agent-substrate.md — Removed runnable fork steps and added the current limitation.
• docs-site/content/kagent/1.x/examples/agents-via-mcp.md — Removed MCP fork walkthroughs and marked fork_session as temporarily rejected.
• docs-site/content/kagent/1.x/observability/launch-ui.md — Updated the UI checkpoint controls description for the disabled Fork action.
• docs-site/content/kagent/1.x/about/what-is-kagent.md — Reframed the feature card from fork to checkpoints.
• docs-site/content/kagent/1.x/examples/a2a-byo.md — Updated the Agent Substrate card subtitle.
• docs-site/content/kagent/1.x/get-started/your-first-mcp-tool.md — Updated the Agent Substrate card subtitle.

How to verify this change

1. Install a fresh cluster by following docs-site/content/kagent/1.x/setup/installation.md: run KAGENT_HELM_EXTRA_ARGS="--set controller.grpc.reflection=true" kagent install --namespace kagent.
2. Check that kagent, Agent Substrate, and the development database are present: kubectl get pods -n kagent, kubectl get pods -n ate-system, and kubectl get secret kagent-postgres -n kagent -o jsonpath='{.data.connectionString}'.
3. For external PostgreSQL, create the Secret and values from operations/operational-considerations.md, run the Helm command, and check that the controller pod reads KAGENT_POSTGRES_DATABASE_URL from the named Secret and KAGENT_POSTGRES_DATABASE_ROLE from the configured role.
4. Create a checkpoint with the Agent Substrate example, then call CheckpointService/ForkSession; the response should fail with FAILED_PRECONDITION.

What was not verified

• The configuration was not applied to a cluster; every command in this diff is unrun.
• Generated reference pages still show stale database.postgres.bundled, database.postgres.url, database.postgres.urlFile, and KAGENT_POSTGRES_DATABASE_URL_FILE entries; they were not edited because the update-ref workflow owns them.
• diff-truncated.md says helm/kagent-crds/values.yaml and ui/src/generated/ateapi_pb.ts are not in the code diff.
• The Agent Substrate and kagent version conrefs were not changed because version conref files are generator-owned.

How the pages were chosen (triage report)

Draft a documentation change

kagent-dev/kagent#2708 — Bump Substrate to 0.5.0-alpha1 and share PostgreSQL via kagent install

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Bumps Substrate to 0.5.0-alpha1 and makes kagent install the way to install Kagent, Substrate, and a shared development PostgreSQL database together. Kagent, Substrate, and PostgreSQL authenticate with rotating Pod Certificates instead of passwords. The Kagent Helm chart no longer deploys PostgreSQL or bundles Substrate as a subchart.
• Not tested: no cluster was available, so every command in this diff is unrun
• Stale claims (pages quote text this change removed or re-routed; fix each or dismiss it in the report):
  • "PostgreSQL connection URL. The default applies only to the controller; kagent db requires this variable or --db-url. Helm supplies its configured connection URL." removed from go/core/pkg/env/database.go. Still quoted at:
    • docs-site/content/kagent/1.x/reference/env-vars.md:53
    • docs-site/content/kagent/1.x/reference/env-vars.md:188
    • docs-site/content/kagent/1.x/reference/env-vars.md:208
  • "File containing the PostgreSQL connection URL; takes precedence over KAGENT_POSTGRES_DATABASE_URL in the controller." removed from go/core/pkg/env/database.go. Still quoted at:
    • docs-site/content/kagent/1.x/reference/env-vars.md:54
    • docs-site/content/kagent/1.x/reference/env-vars.md:189
  • "Additional arguments to pass to Helm commands." removed from go/core/pkg/env/cli.go. Still quoted at:
    • docs-site/content/kagent/1.x/reference/env-vars.md:204
• No rule covers 18 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • AGENTS.md
  • DEVELOPMENT.md
  • Makefile
  • README.md
  • contrib/cncf/technical-review.md
  • docs/architecture/persistence-checkpoints-and-forks.md
  • ...and 12 more

Draft branch: pr-tracker-draft-kagent-2708

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. This repository's checks are held as action_required until somebody presses Approve and run on the Checks tab. Checks that come from GitHub Apps rather than Actions, such as DCO, run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.