docs: add kagent 1.0 documentation and version the docs site

.github/workflows/links.yml

@@ -1,7 +1,9 @@
 name: Links
 
 # Scheduled: full check on all built docs pages, creates an issue, posts to Slack.
-# Pull request: local links only on changed files, no issue or Slack.
+# Pull request: local links only, across the whole build — the paths filter
+# below decides whether the job runs, not which pages it scans. No issue or
+# Slack; the job fails the check instead.
 #
 # Scope: kagent-dev/website is a mixed repo — a Next.js marketing worker at the
 # root and a Hugo docs site under docs-site/ that consumes docs-theme-extras.
@@ -48,6 +50,7 @@ on:
       - 'docs-site/layouts/**'
       - 'docs-site/static/**'
       - 'docs-site/hugo.yaml'
+      - 'docs-site/hugo.preview.yaml'
       - 'docs-site/go.mod'
       - 'docs-site/go.sum'
       - '.github/workflows/links.yml'
@@ -108,7 +111,17 @@ jobs:
           # docs-site's CSS pipeline shells out to tooling in its own
           # devDependencies, so install them first so Hugo finds the binaries.
           npm ci
-          hugo --config hugo.yaml --gc --minify
+          # The preview overlay and -D are what put content/kagent/1.x/ in this
+          # build at all. That section is withheld from production by a draft
+          # cascade in 1.x/_index.md, so a plain `hugo --config hugo.yaml`
+          # renders ZERO 1.x pages and this job passes green having scanned
+          # none of them. The overlay also restores the 1.x entry in
+          # params.versions, without which every {{< version include-if="1.x" >}}
+          # renders empty. Both are temporary: at the 1.0 release the draft keys
+          # and hugo.preview.yaml go away, and this line reverts to
+          # `hugo --config hugo.yaml --gc --minify`. The Makefile and
+          # preview.yaml layer the overlay the same way.
+          hugo --config hugo.yaml,hugo.preview.yaml -D --gc --minify
 
       - name: Prepare workspace
         run: mkdir -p artifacts

.github/workflows/playwright-screenshots.yaml

@@ -0,0 +1,255 @@
+name: Refresh kagent UI screenshots
+
+on:
+  workflow_dispatch:
+    inputs:
+      capture:
+        description: Which captures to run
+        type: choice
+        default: mock
+        options: [mock, cluster, both]
+  push:
+    branches:
+      # The 1.x docs live on this branch until the 1.0 release; retarget to main
+      # when 1.x is published and the draft cascade is dropped.
+      - kagent-1-0-docs
+    paths:
+      # Only the inputs that actually determine the pixels. Everything else in the
+      # repo can change without a capture being stale.
+      - docs-site/playwright/tests/**
+      - docs-site/playwright/fixtures/**
+      - docs-site/playwright/playwright.config.ts
+      - docs-site/playwright/docs-image-map.json
+      - docs-site/playwright/package.json
+      - docs-site/playwright/provisioners/**
+      - docs-site/assets/kagent-docs/versions/kagent.md
+      - docs-site/assets/kagent-docs/versions/agent-substrate.md
+      - .github/workflows/playwright-screenshots.yaml
+
+# Queue overlapping runs so two of them can't force-push the same PR branch at once.
+concurrency:
+  group: playwright-screenshots
+  cancel-in-progress: false
+
+# Deliberately NO cron. The chart versions are read from the docs conrefs and released
+# charts are immutable, so a fixed version plus a fixed fixture renders identically every
+# run — nothing changes until an input file changes, and that is a git event. A cron here
+# would produce a nightly no-op or a stream of empty PRs. This is also why
+# @playwright/test is pinned exactly (no caret) in docs-site/playwright/package.json: a
+# caret could pull a different Chromium with no git event, breaking the premise.
+
+env:
+  NODE_VERSION: '24.13.0'   # the kagent UI's own engine floor; its build tooling fails on 18
+  PW_DIR: docs-site/playwright
+
+jobs:
+  # ---------------------------------------------------------------------------------
+  # Mock-backed captures. No cluster, no API key, no cloud dependencies — so this is the
+  # job that can run on every input change.
+  # ---------------------------------------------------------------------------------
+  mock:
+    if: github.event_name == 'push' || inputs.capture == 'mock' || inputs.capture == 'both'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the website
+        uses: actions/checkout@v4
+        with:
+          path: website
+
+      # The mock backend is a service worker the released image does not ship, so the
+      # capture needs the UI source, not a published image.
+      - name: Check out kagent (for the UI source)
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository_owner }}/kagent
+          path: kagent
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install the kagent UI
+        working-directory: kagent/ui
+        run: |
+          corepack enable
+          yarn install --immutable
+
+      - name: Install the harness
+        working-directory: website/${{ env.PW_DIR }}
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+
+      - name: Serve the UI from its mock backend
+        working-directory: kagent/ui
+        run: |
+          # vite directly, not `yarn dev`: one less toolchain pin between here and a
+          # screenshot. Backgrounded because the capture needs it to outlive this step.
+          VITE_API_MODE=mock ./node_modules/.bin/vite --port 8101 > /tmp/ui-dev.log 2>&1 &
+          for i in $(seq 1 60); do
+            if curl -sf http://localhost:8101/ >/dev/null; then echo "UI up after ${i}s"; exit 0; fi
+            sleep 1
+          done
+          echo "UI did not come up:"; cat /tmp/ui-dev.log; exit 1
+
+      - name: Capture
+        working-directory: website/${{ env.PW_DIR }}
+        run: UI_BASE_URL=http://localhost:8101 npm run update:chat
+
+      - name: Publish into the docs img tree
+        working-directory: website/${{ env.PW_DIR }}
+        # sync-docs exits nonzero when the cluster-captured baselines are absent, which
+        # they legitimately are in this job. Publish what this job captured and move on.
+        run: npm run sync-docs || true
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report-mock
+          path: website/${{ env.PW_DIR }}/playwright-report
+          retention-days: 7
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          path: website
+          commit-message: "docs: Refresh kagent UI screenshots (mock)"
+          signoff: true
+          title: "[Automated] Refresh kagent UI screenshots (mock-backed)"
+          body: |
+            Automated refresh of the mock-backed kagent UI screenshots.
+
+            **A diff here means the kagent UI changed.** Review the images before merging, and
+            check whether the prose in the guides that embed them is now wrong too — that
+            judgment is the point of this PR and cannot be automated.
+
+            Captured against the kagent UI's in-browser mock backend, so the fixtures are fixed
+            and the browser clock is pinned: any diff is a real UI change, not drift.
+
+            Generated by the [**Refresh kagent UI screenshots** workflow](https://github.com/${{ github.repository_owner }}/website/actions/workflows/playwright-screenshots.yaml).
+          branch: playwright/screenshot-refresh-mock
+          delete-branch: true
+          base: kagent-1-0-docs
+          labels: |
+            documentation
+            automated pr
+
+  # ---------------------------------------------------------------------------------
+  # Live-cluster captures.
+  #
+  # DISPATCH ONLY. Two separate reasons, and the first one is currently fatal:
+  #
+  # 1. THE CHART THIS INSTALLS DOES NOT EXIST YET. `versions/kagent.md` pins
+  #    `1.0.0-beta0`; the newest published kagent chart is `0.10.1`. This job therefore
+  #    fails at the provisioner's kagent step until 1.0 ships. It deliberately still
+  #    installs the published chart rather than building from source the way the
+  #    provisioner's local KAGENT_CHART_DIR mode can: CI exists to capture what a reader
+  #    installs, and a source build would quietly defeat that.
+  # 2. Even once the chart exists, this is unverified on a hosted runner. Agent Substrate
+  #    runs workers under gVisor nested inside the worker pod, and its own reference
+  #    environment is a GKE node pool, so kind-in-Docker-on-a-runner is an open question.
+  #
+  # Promote it to the `push` trigger once a dispatch run has gone green, and move the
+  # provisioner and version-conref paths onto that trigger at the same time — today they
+  # sit on the push filter but can only affect this job.
+  # ---------------------------------------------------------------------------------
+  cluster:
+    if: github.event_name == 'workflow_dispatch' && (inputs.capture == 'cluster' || inputs.capture == 'both')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the website
+        uses: actions/checkout@v4
+        with:
+          path: website
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install cluster tooling
+        run: |
+          go install sigs.k8s.io/kind@latest || curl -fsSL -o /usr/local/bin/kind \
+            https://kind.sigs.k8s.io/dl/v0.32.0/kind-linux-amd64
+          chmod +x /usr/local/bin/kind || true
+          kind --version
+
+      - name: Install kubectl-ate
+        working-directory: website/docs-site
+        run: |
+          # The same version the install guide tells a reader to download, read from the
+          # same conref, so the tooling matches the charts the provisioner installs.
+          version="$(python3 - assets/kagent-docs/versions/agent-substrate.md <<'PY'
+          import re, sys
+          txt = open(sys.argv[1]).read()
+          m = re.search(r'include-if="[^"]*\b1\.x\b[^"]*"[^>]*>}}([^<{]+)', txt)
+          print((m.group(1) if m else txt).strip())
+          PY
+          )"
+          curl -fsSL -o kubectl-ate \
+            "https://github.com/kagent-dev/substrate/releases/download/v${version}/kubectl-ate-linux-amd64"
+          chmod +x kubectl-ate && sudo mv kubectl-ate /usr/local/bin/
+
+      - name: Stand up the cluster at the docs-pinned versions
+        working-directory: website/${{ env.PW_DIR }}
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: ./provisioners/kagent-kind.sh
+
+      - name: Install the harness
+        working-directory: website/${{ env.PW_DIR }}
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+
+      - name: Port-forward the UI
+        run: |
+          kubectl port-forward -n kagent svc/kagent-ui 8082:8080 &
+          for i in $(seq 1 60); do
+            if curl -sf http://localhost:8082/ >/dev/null; then echo "UI up after ${i}s"; exit 0; fi
+            sleep 1
+          done
+          echo "port-forward never became reachable"; exit 1
+
+      - name: Capture
+        working-directory: website/${{ env.PW_DIR }}
+        run: UI_BASE_URL=http://localhost:8082 npm run update:launch-ui
+
+      - name: Publish into the docs img tree
+        working-directory: website/${{ env.PW_DIR }}
+        run: npm run sync-docs || true
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report-cluster
+          path: website/${{ env.PW_DIR }}/playwright-report
+          retention-days: 7
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          path: website
+          commit-message: "docs: Refresh kagent UI screenshots (cluster)"
+          signoff: true
+          title: "[Automated] Refresh kagent UI screenshots (live cluster)"
+          body: |
+            Automated refresh of the live-cluster kagent UI screenshots.
+
+            **A diff here means the kagent UI changed.** Review the images before merging, and
+            check whether the prose in the guides that embed them is now wrong too.
+
+            Captured against a kind cluster running the chart versions the install guide pins,
+            so these images show what a reader who follows the docs actually gets.
+
+            Relative timestamps ("2 minutes ago") are left visible rather than masked, so a
+            small diff confined to those is expected and not a UI change.
+
+            Generated by the [**Refresh kagent UI screenshots** workflow](https://github.com/${{ github.repository_owner }}/website/actions/workflows/playwright-screenshots.yaml).
+          branch: playwright/screenshot-refresh-cluster
+          delete-branch: true
+          base: kagent-1-0-docs
+          labels: |
+            documentation
+            automated pr

.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