chore: release v0.7.0 (develop → main)

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,15 @@
+# Disables blank issues so contributors choose one of the structured
+# templates above. Routes "I have a question" / "I have an idea" to
+# Discussions instead of issues.
+blank_issues_enabled: false
+
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/amcheste/claude-teams-operator/discussions
+    about: For general questions, design discussions, or help requests, please open a Discussion instead of an issue.
+  - name: Documentation site
+    url: https://kagents.dev
+    about: Tutorials, how-to guides, concept pages, and CRD reference are at kagents.dev.
+  - name: Security vulnerability
+    url: https://github.com/amcheste/claude-teams-operator/security/advisories/new
+    about: Report security vulnerabilities privately via GitHub Security Advisories — see SECURITY.md.

.github/ISSUE_TEMPLATE/docs_issue.yml

@@ -0,0 +1,42 @@
+name: Documentation Issue
+description: Something on https://kagents.dev (or in-repo docs) is wrong, missing, confusing, or out of date.
+labels: [documentation]
+body:
+  - type: dropdown
+    id: location
+    attributes:
+      label: Where did you encounter this?
+      options:
+        - kagents.dev (docs site)
+        - README.md
+        - ARCHITECTURE.md
+        - CONTRIBUTING.md
+        - In-repo docs (docs/ tree)
+        - kubectl explain output (CRD docstring)
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: page
+    attributes:
+      label: Page or section
+      placeholder: e.g. https://kagents.dev/tutorials/getting-started/ or "Resource model > AgentTeamRun"
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong?
+      description: Describe the issue. Wrong instruction? Stale info? Confusing wording? Missing example?
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Proposed fix (optional)
+      description: If you have a specific suggestion — wording, an example, a diagram — share it here. PRs welcome too.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,6 +2,15 @@
 
 <!-- What does this change do and why? -->
 
+## Linear
+
+<!-- Replace XXX with the Linear issue number, e.g. "Fixes AMC-82". The CI
+     check requires either an AMC-N reference or, for genuinely untracked
+     work (trivial doc fix, dependency bump, release promotion), a
+     "No-Linear-Issue: <reason>" trailer. -->
+
+Fixes AMC-XXX
+
 ## Changes
 
 <!-- Bullet list of key changes -->

.github/release-announcements/v0.7.0-rc.1.md

@@ -0,0 +1,83 @@
+# v0.7.0-rc.1 — Documentation Site preview
+
+> Draft announcement for the v0.7.0 release candidate. Tone is transparency-first: this is a preview, we want feedback, here's what's in it. Edit this file freely before posting — it's a working draft, not a contract.
+
+---
+
+## Short version (Discussions / Slack / social card)
+
+**kagents v0.7.0-rc.1 is live — first preview of the documentation site at https://kagents.dev.**
+
+Six weeks of work to replace the README-only experience with a proper docs site: tutorials, how-to guides, an auto-generated CRD reference, and concept pages on the architecture. Built with mkdocs-material, deployed via GitHub Pages.
+
+This is a **preview release** — we're shaking out polish items before the stable v0.7.0 cut. Please poke at it and tell us what's broken, missing, or confusing:
+
+- Found a typo or broken link? [Docs issue](https://github.com/amcheste/claude-teams-operator/issues/new?template=docs_issue.yml)
+- Confused by a concept? [Discussion](https://github.com/amcheste/claude-teams-operator/discussions/categories/q-a)
+- Have an idea for a missing tutorial? [Idea](https://github.com/amcheste/claude-teams-operator/discussions/categories/ideas)
+
+We'll hold the stable cut until the rough edges are smoothed.
+
+— Alan
+
+---
+
+## Long version (GitHub release body)
+
+### What's in this preview
+
+The v0.7.0 milestone ships a [polished documentation site at kagents.dev](https://kagents.dev), structured around the [Diátaxis framework](https://diataxis.fr) — four sections, each with a clear purpose:
+
+**📘 [Tutorials](https://kagents.dev/tutorials/)**
+- [Getting Started](https://kagents.dev/tutorials/getting-started/) — install kagents on a Kind cluster and run your first AgentTeam end-to-end. ~15 minutes, no cloud accounts needed.
+
+**🔧 [How-to guides](https://kagents.dev/how-to/)**
+- [Install on Amazon EKS](https://kagents.dev/how-to/install/eks/) (EFS CSI driver + EFS file system + Access Points)
+- [Install on Google GKE](https://kagents.dev/how-to/install/gke/) (Filestore CSI driver + Filestore instance)
+- [Install on Azure AKS](https://kagents.dev/how-to/install/aks/) (Azure Files CSI driver + Premium NFS share)
+- [Expose the dashboard](https://kagents.dev/how-to/operate/expose-dashboard/) (port-forward, Ingress + basic auth, oauth2-proxy)
+- [Configure shared storage](https://kagents.dev/how-to/operate/shared-storage/) (sizing, backup, perf tuning per backend)
+- [Set budget alerts](https://kagents.dev/how-to/operate/budget-alerts/) (per-team limits, webhook events, Prometheus rules)
+
+**📚 [Reference](https://kagents.dev/reference/)**
+- [API reference](https://kagents.dev/reference/api/) — auto-generated from the kubebuilder markers in `api/v1alpha1/`. CI's `Check API reference docs are up to date` step keeps it in lockstep with the code.
+
+**💡 [Explanation](https://kagents.dev/explanation/)**
+- [Resource model](https://kagents.dev/explanation/resources/) — the `AgentTeam` / `AgentTeamTemplate` / `AgentTeamRun` CRDs and how they relate, with a worked "3-agent security review across multiple repos" example.
+- [Coordination protocol](https://kagents.dev/explanation/coordination/) — the load-bearing design choice. File-based mailboxes over RWX PVCs, per-teammate git worktrees as a concurrency primitive, the single-node fallback story.
+- [Operations](https://kagents.dev/explanation/operations/) — honest breakdown of estimation-based budget tracking, per-agent RBAC's threat model, and the eight Prometheus metrics the operator exposes.
+
+### Other v0.7.0 changes
+
+- **`make docs-api`** — new make target regenerates the API reference from kubebuilder markers via [`crd-ref-docs`](https://github.com/elastic/crd-ref-docs). Wired into the lint job's drift check, mirrors the existing `make manifests` pattern.
+- **mkdocs-material site infrastructure** — `docs/` tree, `mkdocs.yml`, `docs/requirements.txt`, and `.github/workflows/docs.yml` (deploys to `gh-pages` on every push to `main`).
+- **Community baseline** — adopted [Contributor Covenant v2.1](https://github.com/amcheste/claude-teams-operator/blob/main/CODE_OF_CONDUCT.md), polished CONTRIBUTING.md with Linear ↔ GitHub guidance for contributors, hardened SECURITY.md with explicit coordinated-disclosure expectations, added a docs-issue template, enabled GitHub Discussions.
+- **kagents brand introduced** — README, KUBECON.md, and CFP draft all aligned around the new public name. Repo, Helm chart, image names, and CRD group (`claude.amcheste.io/v1alpha1`) intentionally unchanged — same pattern as Argo CD, Knative, Kueue.
+
+### Upgrade notes
+
+This release is **docs-only** — zero functional changes to the operator, dashboard, or CRDs. Existing v0.6.0 installs continue to work without any migration. Helm chart version is bumped purely for tagging cohesion.
+
+### What's not yet in v0.7.0 (and won't block the stable cut)
+
+- The "Helm chart values" page under [Reference](https://kagents.dev/reference/) — the existing in-repo [`docs/helm-values.md`](https://github.com/amcheste/claude-teams-operator/blob/main/docs/helm-values.md) is still the source of truth. Migration to the docs site is tracked for a future minor release.
+
+### What we want feedback on
+
+Please tell us if you find:
+
+- **Broken anything** — links, code blocks that don't run, commands that fail. [Docs issue template](https://github.com/amcheste/claude-teams-operator/issues/new?template=docs_issue.yml).
+- **Confusing concepts** — a passage you read three times. [Q&A discussion](https://github.com/amcheste/claude-teams-operator/discussions/categories/q-a).
+- **Missing tutorials** — a use case you'd want a step-by-step guide for. [Ideas discussion](https://github.com/amcheste/claude-teams-operator/discussions/categories/ideas).
+- **Wrong or stale technical details** — especially in the cloud-install guides. The author wrote them based on documented patterns; real platform engineers on each cloud will catch nuances that haven't been hit yet.
+
+### What's next
+
+We'll hold the v0.7.0 stable cut until the obvious rough edges are smoothed — likely 1–2 weeks. After that:
+
+- **v0.4.0/v0.5.0/v0.6.0 retrospective** — these milestones are all 100% complete in code; we'll close out any straggling Linear hygiene.
+- **v1.0.0 — KubeCon Demo Polish** (target: Oct 2026). The on-stage demo script, real-API E2E gating in CI, OCI skill distribution, and a presentation-mode dashboard view. KubeCon NA 2026 is Nov 9–12 in Salt Lake City.
+
+Thanks for reading. Try the [Getting Started tutorial](https://kagents.dev/tutorials/getting-started/) and let us know how it goes.
+
+— Alan, with help from the Claude Code agent team that built it

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          # Required for git-revision-date-localized to read commit history.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install mkdocs-material
+        run: pip install -r docs/requirements.txt
+
+      - name: Configure git for gh-deploy
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      # mkdocs gh-deploy builds the site and force-pushes to the gh-pages
+      # branch in a single command. The branch is created on first run.
+      - name: Build + deploy to gh-pages
+        run: mkdocs gh-deploy --force --no-history

.github/workflows/release-drafter.yml

@@ -16,6 +16,6 @@ jobs:
     name: Update Release Draft
     runs-on: ubuntu-latest
     steps:
-      - uses: release-drafter/release-drafter@6a93d829887aa2e0748befe2e808c66c0ec6e4c7 # v6
+      - uses: release-drafter/release-drafter@c2e2804cc59f45f57076a99af580d0fedb697927 # v7.3.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/scorecard.yml

@@ -5,7 +5,7 @@ on:
   schedule:
     - cron: '30 1 * * 1'  # Every Monday at 01:30 UTC
   push:
-    branches: [main]
+    branches: [main, develop]
   workflow_dispatch:
 
 permissions: read-all
@@ -28,14 +28,14 @@ jobs:
         with:
           results_file: results.sarif
           results_format: sarif
-          publish_results: ${{ github.ref == 'refs/heads/main' }}
+          publish_results: ${{ github.ref_name == github.event.repository.default_branch }}
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: SARIF file
           path: results.sarif
           retention-days: 5
 
-      - uses: github/codeql-action/upload-sarif@d4b3ca9fa7f69d38bfcd667bdc45bc373d16277e # v4
+      - uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4
         with:
           sarif_file: results.sarif

.github/workflows/validate.yml

@@ -65,6 +65,11 @@ jobs:
           make manifests generate
           git diff --exit-code || (echo "CRD manifests or generated code is out of date. Run 'make manifests generate' and commit the result." && exit 1)
 
+      - name: Check API reference docs are up to date
+        run: |
+          make docs-api
+          git diff --exit-code docs/reference/api/ || (echo "API reference docs are out of date. Run 'make docs-api' and commit the result." && exit 1)
+
       - name: Helm lint
         run: |
           curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

.gitignore

@@ -30,5 +30,8 @@ Thumbs.db
 # Build
 dist/
 
+# mkdocs build output
+site/
+
 # Kind
 kubeconfig

AGENTS.md

@@ -1,24 +1,24 @@
-# AGENTS.md — Agent Team Guidelines for claude-teams-operator
+# AGENTS.md. Agent Team Guidelines for claude-teams-operator
 
 ## When working as a teammate on this project
 
-1. **Check the task list first** — before starting work, check what's assigned to you
-2. **Respect module boundaries** — each internal package has a clear scope:
-   - `internal/controller/` — only reconciliation logic
-   - `internal/claude/` — only Claude Code file I/O and session management
-   - `internal/budget/` — only cost estimation
-   - `internal/webhook/` — only external notifications
-   - `internal/metrics/` — only Prometheus metrics
-3. **Use kubebuilder markers** — all CRD types in `api/v1alpha1/` must have proper `+kubebuilder:` annotations
-4. **Test with envtest** — controller tests should use controller-runtime's envtest framework
-5. **Follow Kubernetes conventions** — conditions use `metav1.Condition`, status updates are separate from spec changes
+1. **Check the task list first**. Before starting work, check what's assigned to you
+2. **Respect module boundaries**. Each internal package has a clear scope:
+   - `internal/controller/`. Only reconciliation logic
+   - `internal/claude/`. Only Claude Code file I/O and session management
+   - `internal/budget/`. Only cost estimation
+   - `internal/webhook/`. Only external notifications
+   - `internal/metrics/`. Only Prometheus metrics
+3. **Use kubebuilder markers**. All CRD types in `api/v1alpha1/` must have proper `+kubebuilder:` annotations
+4. **Test with envtest**. Controller tests should use controller-runtime's envtest framework
+5. **Follow Kubernetes conventions**. Conditions use `metav1.Condition`, status updates are separate from spec changes
 
 ## Architecture rules
 
-- The operator NEVER makes Anthropic API calls directly — it only manages pods that run Claude Code
-- All inter-agent communication goes through the shared PVC filesystem — the operator just creates and monitors the volumes
-- Budget tracking is estimation-based — we can't read real-time token counts from Claude Code
-- Pods use `RestartPolicy: Never` — crashed agents get re-spawned fresh, not restarted
+- The operator NEVER makes Anthropic API calls directly. It only manages pods that run Claude Code
+- All inter-agent communication goes through the shared PVC filesystem. The operator just creates and monitors the volumes
+- Budget tracking is estimation-based. We can't read real-time token counts from Claude Code
+- Pods use `RestartPolicy: Never`. Crashed agents get re-spawned fresh, not restarted
 
 ## Build verification