docs: add kagent 1.0 documentation and version the docs site

.github/workflows/preview.yaml

@@ -50,7 +50,7 @@ jobs:
       # OpenNext Worker (which bundles public/ as static assets). HUGO=hugo uses
       # the Hugo installed above instead of the local hugo160 alias.
       - name: Build (Hugo docs + inject into /docs + Worker)
-        run: make build HUGO=hugo
+        run: make build HUGO=hugo HUGO_CONFIG=hugo.yaml,hugo.preview.yaml HUGO_FLAGS=-D
 
       # Derive a stable preview alias from the PR branch name. Cloudflare preview
       # aliases must be a valid subdomain label (lowercase alphanumerics and

Makefile

@@ -37,8 +37,16 @@ install: ## Install web + docs dependencies (npm) and Hugo modules
 
 # ── Docs (Hugo) ────────────────────────────────────────────────────────────
 .PHONY: build-docs
+# HUGO_CONFIG and HUGO_FLAGS let a preview build layer hugo.preview.yaml and pass
+# -D without changing the production defaults. See docs-site/hugo.preview.yaml.
+HUGO_CONFIG ?= hugo.yaml
+# serve-docs layers the preview overlay by default: without it, local authoring
+# renders every {{< version include-if="1.x" >}} conref empty. See docs-site/hugo.preview.yaml.
+HUGO_CONFIG_PREVIEW ?= hugo.yaml,hugo.preview.yaml
+HUGO_FLAGS ?=
+
 build-docs: ## Build the Hugo docs site -> docs-site/public
-	cd $(DOCS_DIR) && $(HUGO) --config hugo.yaml $(if $(DOCS_BASEURL),--baseURL "$(DOCS_BASEURL)") --gc --minify
+	cd $(DOCS_DIR) && $(HUGO) --config $(HUGO_CONFIG) $(HUGO_FLAGS) $(if $(DOCS_BASEURL),--baseURL "$(DOCS_BASEURL)") --gc --minify
 
 .PHONY: inject-docs
 inject-docs: ## Copy built docs into public/docs (preserves tracked assets, e.g. versions/)
@@ -47,8 +55,15 @@ inject-docs: ## Copy built docs into public/docs (preserves tracked assets, e.g.
 	  $(DOCS_OUT)/ $(WEB_DOCS)/
 
 .PHONY: serve-docs
+# --renderToMemory keeps the preview out of $(DOCS_OUT) entirely. Hugo's server
+# otherwise renders to disk and serves from there, so it shares one directory
+# with `build-docs`/`clean`. Anything that empties that directory mid-session --
+# a `make clean` or `make build` in a second terminal -- strands the running
+# server: each later save re-renders only the pages it touched, so pages come
+# back but the stylesheets never do, and the preview degrades edit by edit
+# instead of failing outright. Rendering to memory removes the shared directory.
 serve-docs: ## Preview the docs alone at http://localhost:1313/docs/
-	cd $(DOCS_DIR) && $(HUGO) server --config hugo.yaml -D --disableFastRender
+	cd $(DOCS_DIR) && $(HUGO) server --config $(HUGO_CONFIG_PREVIEW) -D --disableFastRender --renderToMemory
 
 # ── Web (Next.js) ──────────────────────────────────────────────────────────
 .PHONY: serve-web

docs-site/.docs-test.toml

@@ -6,11 +6,10 @@
 # against this file's directory (docs-site/). The harness does NOT build the
 # site — `hugo --config hugo.yaml` runs first and writes to builtRoot.
 #
-# NOTE: docs-site/content is GENERATED from the Next.js MDX source under
-# src/app/docs by `make gen-docs` (scripts/mdx-to-hugo.mjs --out docs-site/content).
-# These checks run against the generated Hugo output, which is the right place
-# to catch shortcode/rendering breaks — but a content fix must land in the MDX
-# source (or the converter), not in docs-site/content, or `gen-docs` overwrites it.
+# docs-site/content is hand-authored Markdown and is the source of truth (the
+# former MDX source under src/app/docs and its mdx-to-hugo.mjs converter were
+# removed once the one-time conversion landed — see "Remove the src/apps/docs
+# directory"). Edit pages directly under docs-site/content.
 
 version = "1"
 name    = "kagent-oss"
@@ -35,10 +34,14 @@ scanRoots = [
   "./content",
 ]
 
-# NOTE: kagent docs are a flat, unversioned set (/<section>/<page>/) with no
-# version segment. There is intentionally no [versioning] block — version-aware
-# specs detect the absence and skip gracefully (same mechanism agentregistry's
-# and ambientmesh's flat docs rely on).
+# kagent docs are versioned (0.x frozen, 1.x in-progress rewrite), nested
+# under /docs/kagent/<version>/... . kmcp, the other product built into this
+# same Hugo site, stays flat/unversioned — see the sections.kagent.versions
+# comment in hugo.yaml for why versions are scoped per-section rather than
+# site-wide.
+[versioning]
+versionFromPath = "^/docs/kagent/(?<version>[^/]+)/"
+versions        = ["0.x", "1.x"]
 
 # All checks default to enabled. No [checks] overrides are needed: kagent runs
 # the full default set. (The former `smoke`/`crossBrowser` toggles were removed

docs-site/assets/css/custom.css

@@ -434,3 +434,64 @@ h6 {
   :where(.dark, .dark *) .hextra-nav-container img[src*="kagent-logo-light"] { display: none; }
   :where(.dark, .dark *) .hextra-nav-container img[src*="kagent-logo-dark"]  { display: block; }
 }
+
+/* ── Mermaid diagram alignment ────────────────────────────────────────────
+   Hextra renders every diagram into a full-width <pre class="mermaid"> that
+   carries the code-block background, while Mermaid sizes its own SVG to the
+   diagram's natural width. A narrow diagram therefore sits against the left
+   edge of a wide, mostly empty panel. Center it instead.
+
+   Note: the panel itself cannot be shrunk to fit from CSS. Mermaid sets
+   width="100%" on the SVG and records the real size only in an inline
+   max-width, so width:fit-content has no definite width to measure and
+   collapses every diagram to the 300px SVG default. Shrinking the panel would
+   require Mermaid's useMaxWidth:false, which means overriding the theme's
+   scripts/mermaid.html partial. */
+pre.mermaid {
+  display: flex;
+  justify-content: center;
+}
+
+/* ── Glossary term indicator ──────────────────────────────────────────────
+   docs-theme-extras marks a {{< gloss >}} term with `border-bottom: 1px
+   dotted #666` and defines no dark-mode variant. Two problems: that color
+   lands near 3:1 on this site's dark page, and a 1px dotted rule is only
+   about half coverage, so it reads as a hairline whatever its contrast.
+
+   Swap the border for a text-decoration underline, which allows a real
+   thickness and an offset that lifts the dots off the baseline, and raise
+   the color per theme. Hover and focus use the OSS brand color in place of
+   the theme's hardcoded #007acc.
+
+   The `html` prefix is load-bearing: glossary.css is a separate <link> that
+   loads AFTER custom.css in both the production and dev pipelines, so a bare
+   `.glossary-term` would lose the cascade at equal specificity. */
+html .glossary-term {
+  border-bottom: none;
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 4px;
+  text-decoration-color: #4b5563;
+}
+html.dark .glossary-term {
+  text-decoration-color: #9ca3af;
+}
+html .glossary-term:hover,
+html .glossary-term:focus {
+  text-decoration-color: var(--theme-primary, #0060cf);
+}
+
+/* Glossary tooltip: keep the definition at normal weight.
+
+   extras' glossary.css sets font-weight on the tooltip's term (`> span strong`)
+   but never on the definition (`> span span`), so the definition inherits from
+   whatever surrounds the trigger. A term glossed inside a bold run — a bold
+   step lead-in, or a `**first mention**` — therefore renders its whole
+   definition bold and loses the term/definition contrast the markup intends.
+
+   Same `html` prefix requirement as above: glossary.css loads after this file,
+   so a bare selector would lose the cascade at equal specificity. */
+html .glossary-term > span span {
+  font-weight: 400;
+}

docs-site/assets/kagent-docs/snippets/artifact-sources.md

@@ -0,0 +1,9 @@
+## Every source is immutable
+
+A skill or a plugin package changes what an agent does, so kagent only accepts artifact references that cannot shift underneath a running agent. Each source names exactly one of three kinds of artifact, and every kind must be pinned in its own way.
+
+- **`oci`**: An image reference pinned to a digest, in the form `<repository>@sha256:<digest>`. A tag alone is rejected, because a tag can be moved to different content later.
+- **`git`**: A repository URL together with a full commit identifier. An abbreviated commit, a branch, or a tag is rejected.
+- **`bucket.s3`**: An endpoint, bucket, and key, together with the `versionId` of that exact object version. A region is included where the service requires one for request signing.
+
+Pinning has a practical consequence worth planning for. Publishing a new version means updating the AgentTemplate to name the new digest, commit, or object version, which compiles a new revision. Agents that are already running keep the content that they started with.

docs-site/assets/kagent-docs/snippets/grpcurl-prerequisites.md

@@ -0,0 +1,13 @@
+1. [Install kagent]({{< link path="setup/installation" >}}), and confirm that your installation sets `controller.grpc.reflection=true`. Reflection lets grpcurl discover the controller's methods without a local copy of kagent's protocol buffer definitions.
+
+2. [Create your first agent]({{< link path="get-started/your-first-agent" >}}), then save the AgentInstance's ID to an environment variable. To find the ID, run `kagent get agent-instance` to list your AgentInstances and copy the value from the `ID` column.
+   ```bash
+   export INSTANCE_ID=<your-agent-instance-id>
+   ```
+
+3. Install [grpcurl](https://github.com/fullstorydev/grpcurl).
+
+4. Port-forward the controller's gRPC port, and leave the command running.
+   ```bash
+   kubectl port-forward -n kagent svc/kagent-controller 8083:8083
+   ```

docs-site/assets/kagent-docs/snippets/snapshot-cycle-diagram.md

@@ -0,0 +1,9 @@
+```mermaid
+flowchart LR
+    pool["WorkerPool"] --> worker1["Worker"]
+    worker1 -->|hosts| actor["Actor<br>(running)"]
+    actor -->|suspend| snapshot["ActorSnapshot<br>(immutable)"]
+    snapshot -->|resume| worker2["Any free Worker<br>in the pool"]
+    snapshot -->|pinned by| tag["ActorSnapshotTag<br>(retention pin)"]
+    tag -->|seeds| newactor["New Actor"]
+```

docs-site/assets/kagent-docs/versions/agent-substrate.md

@@ -0,0 +1 @@
+{{< version include-if="0.x" >}}0.0.9{{< /version >}}{{< version include-if="1.x" >}}0.0.26{{< /version >}}

docs-site/assets/kagent-docs/versions/jaeger.md

@@ -0,0 +1 @@
+4.4.7

docs-site/assets/kagent-docs/versions/kagent-tools.md

@@ -0,0 +1 @@
+0.2.1

docs-site/assets/kagent-docs/versions/kagent.md

@@ -0,0 +1 @@
+{{< version include-if="0.x" >}}0.10.1{{< /version >}}{{< version include-if="1.x" >}}1.0.0-beta0{{< /version >}}

docs-site/assets/kagent-docs/versions/kmcp.md

@@ -0,0 +1 @@
+0.3.0

docs-site/assets/kagent-docs/versions/loki.md

@@ -0,0 +1 @@
+6.24.0

docs-site/assets/kagent-docs/versions/max-kube.md

@@ -0,0 +1 @@
+1.35

docs-site/assets/kagent-docs/versions/otel-collector.md

@@ -0,0 +1 @@
+0.172.0

docs-site/assets/kagent-docs/versions/tempo.md

@@ -0,0 +1 @@
+1.16.0

docs-site/content/kagent/0.x/_index.md

@@ -0,0 +1,37 @@
+---
+title: kagent
+linkTitle: "kagent 0.x"
+description: Concepts, guides, and reference docs for running declarative AI agents on Kubernetes, from install through day-two operations.
+weight: 1
+author: kagent.dev
+---
+
+Your complete guide to the AI agent platform for Kubernetes
+
+## What is kagent?
+
+kagent is an innovative AI agent platform designed specifically for Kubernetes environments. 
+It empowers developers and operations teams to create intelligent, autonomous agents that can 
+monitor, manage, and automate complex Kubernetes workloads using the power of large language models (LLMs).
+
+kagent was created at [Solo.io](https://www.solo.io) in 2025 and is a [Cloud Native Computing Foundation](https://www.cncf.io) sandbox project.
+
+## Key Features
+
+- **AI-Powered Automation** - Create intelligent agents that understand natural language and can perform complex Kubernetes operations
+- **Multi-Provider Support** - Works with OpenAI, Anthropic, Google Vertex AI, Azure OpenAI, Ollama, and custom models
+- **Tool Integration** - Supports Model Context Protocol (MCP) tools, built-in Kubernetes tools, and custom HTTP tools
+- **Agent-to-Agent Communication** - Enable sophisticated workflows through A2A (Agent-to-Agent) interactions
+- **Comprehensive Observability** - Built-in tracing and monitoring to understand agent behavior and performance
+- **Cloud Native** - Designed from the ground up to run natively in Kubernetes environments
+
+## Why Choose kagent?
+
+Whether you're looking to automate routine operations, implement intelligent monitoring, 
+or create sophisticated multi-agent workflows, kagent provides the tools and framework 
+to bring AI to your Kubernetes infrastructure. Start with simple automation and scale 
+to complex, intelligent systems that can reason about your cluster's state and make 
+informed decisions.
+
+## Explore the Documentation
+

docs-site/content/kagent/0.x/concepts/_index.md

@@ -0,0 +1,10 @@
+---
+title: Core Concepts
+description: Understand the fundamental concepts and architecture of kagent.
+weight: 4
+author: kagent.dev
+---
+
+Learn about the AI agent and kagent concepts.
+
+The [Agents]({{< link path="concepts/agents" >}}) page also covers [prompt templates]({{< link path="concepts/agents#prompt-templates" >}}), [Git-based skills]({{< link path="concepts/agents#git-based-skills" >}}), and [context management]({{< link path="concepts/agents#context-management" >}}). For related material, see [What is kagent]({{< link path="introduction/what-is-kagent" >}}), the [Tools Ecosystem]({{< link path="resources/tools-ecosystem" >}}) catalog, [Human-in-the-Loop]({{< link path="examples/human-in-the-loop" >}}) configuration, and the [examples]({{< link path="examples" >}}), which include both the Go and Python runtimes.

docs-site/content/kagent/concepts/agent-harness.md → docs-site/content/kagent/0.x/concepts/agent-harness.md

@@ -5,7 +5,7 @@ weight: 4
 author: kagent.dev
 ---
 
-An `AgentHarness` is a Kubernetes custom resource that asks kagent to provision a long-running remote execution environment on [Agent Substrate](/docs/kagent/concepts/agent-substrate). It is useful when you want a managed sandbox that runs a coding agent (such as OpenClaw or Hermes) that you can chat with and connect to messaging channels, but you do not want kagent to package and run a full agent runtime inside the workload.
+An `AgentHarness` is a Kubernetes custom resource that asks kagent to provision a long-running remote execution environment on [Agent Substrate]({{< link path="concepts/agent-substrate" >}}). It is useful when you want a managed sandbox that runs a coding agent (such as OpenClaw or Hermes) that you can chat with and connect to messaging channels, but you do not want kagent to package and run a full agent runtime inside the workload.
 
 `AgentHarness` resources appear alongside agents in kagent APIs and status views, but they are not the same thing as `Agent` or `SandboxAgent`.
 
@@ -30,7 +30,7 @@ All backends use the same top-level `AgentHarness` shape: `backend`, `substrate`
 
 ## Runtime: Agent Substrate
 
-Every `AgentHarness` runs on [Agent Substrate](/docs/kagent/concepts/agent-substrate). The `spec.substrate` field is required and configures the Substrate provisioning stack:
+Every `AgentHarness` runs on [Agent Substrate]({{< link path="concepts/agent-substrate" >}}). The `spec.substrate` field is required and configures the Substrate provisioning stack:
 
 - `workerPoolRef` — references an existing `WorkerPool` in the harness namespace. When unset, the controller uses its configured default WorkerPool.
 - `snapshotsConfig` — configures where actor memory snapshots are stored. Defaults to `gs://ate-snapshots/<namespace>/<agentharnessname>` when unset.
@@ -94,4 +94,4 @@ The API uses CEL validation to ensure Slack settings match the selected backend.
 
 ## Next steps
 
-For enabling Agent Substrate so the controller can provision harnesses, see [Enable AgentHarness support](/docs/kagent/introduction/installation#enable-agentharness-support). For complete YAML examples, including Slack token references and backend-specific Slack settings, see the [Agent Harness example](/docs/kagent/examples/agent-harness). For the generated schema, see the [API reference](/docs/kagent/resources/api-ref#agentharness).
+For enabling Agent Substrate so the controller can provision harnesses, see [Enable AgentHarness support]({{< link path="introduction/installation#enable-agentharness-support" >}}). For complete YAML examples, including Slack token references and backend-specific Slack settings, see the [Agent Harness example]({{< link path="examples/agent-harness" >}}). For the generated schema, see the [API reference]({{< link path="resources/api-ref#agentharness" >}}).

docs-site/content/kagent/concepts/agent-memory.md → docs-site/content/kagent/0.x/concepts/agent-memory.md

@@ -22,7 +22,7 @@ Agent memory provides the following capabilities.
 
 ### Install kagent with Postgres
 
-To use memory, you must install kagent with a Postgres database that has the `pgvector` extension installed and vector enabled. For more information, see the [Database configuration](/docs/kagent/operations/operational-considerations#database-configuration) section.
+To use memory, you must install kagent with a Postgres database that has the `pgvector` extension installed and vector enabled. For more information, see the [Database configuration]({{< link path="operations/operational-considerations#database-configuration" >}}) section.
 
 Example Helm configuration for your own external Postgres:
 
@@ -71,7 +71,7 @@ The embedding `ModelConfig` does not have to use the same provider as the agent'
 
 To use [Amazon Bedrock Titan embedding models](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html), create a `ModelConfig` with `provider: Bedrock`. 
 
-The Bedrock provider uses the standard AWS credential chain, so no API key secret is required. The agent's pod must have AWS credentials with the `bedrock:InvokeModel` permission for the chosen model. On Kubernetes, the recommended setup is [EKS IRSA on the agent ServiceAccount](/docs/kagent/supported-providers/amazon-bedrock#step-3-configure-the-agent-to-use-an-iam-role). 
+The Bedrock provider uses the standard AWS credential chain, so no API key secret is required. The agent's pod must have AWS credentials with the `bedrock:InvokeModel` permission for the chosen model. On Kubernetes, the recommended setup is [EKS IRSA on the agent ServiceAccount]({{< link path="supported-providers/amazon-bedrock#step-3-configure-the-agent-to-use-an-iam-role" >}}). 
 
 ```yaml
 apiVersion: kagent.dev/v1alpha2
@@ -184,5 +184,5 @@ DELETE /api/memories?agent_name=X&user_id=Y
 
 - **No per-memory deletion.** You can delete all memories for an agent, but you cannot delete individual memory entries.
 - **No cross-agent memory sharing.** Each agent has its own isolated memory store. You cannot share memories across agents.
-- **Not pluggable.** Memory is built on the Google ADK memory implementation and cannot be swapped for an alternative memory solution (such as Cognee). However, if an alternative memory solution exposes an [MCP server](/docs/kagent/concepts/tools#mcp-tools), you can add it as a tool and instruct the agent to use it instead of the built-in memory.
+- **Not pluggable.** Memory is built on the Google ADK memory implementation and cannot be swapped for an alternative memory solution (such as Cognee). However, if an alternative memory solution exposes an [MCP server]({{< link path="concepts/tools#mcp-tools" >}}), you can add it as a tool and instruct the agent to use it instead of the built-in memory.