🤖 feat: add docs site, Pages deploy, and docs quality checks

.cspell.json

@@ -0,0 +1,37 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "Diátaxis",
+    "GOFLAGS",
+    "apiregistration",
+    "apiserverapp",
+    "apiserver",
+    "apiservice",
+    "clusterrole",
+    "clusterrolebinding",
+    "coder-k8s",
+    "codercontrolplane",
+    "codercontrolplanes",
+    "codertemplate",
+    "codertemplates",
+    "coderworkspace",
+    "coderworkspaces",
+    "controllerapp",
+    "devshell",
+    "gofumpt",
+    "javascripts",
+    "kubeconfig",
+    "kubebuilder",
+    "metav",
+    "mkdocs",
+    "pymdownx",
+    "superfences"
+  ],
+  "ignorePaths": [
+    ".git/**",
+    "node_modules/**",
+    "site/**",
+    "vendor/**"
+  ]
+}

.github/workflows/docs.yaml

@@ -0,0 +1,137 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .cspell.json
+      - .markdownlint-cli2.yaml
+      - .github/workflows/docs.yaml
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .cspell.json
+      - .markdownlint-cli2.yaml
+      - .github/workflows/docs.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  docs-quality:
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '22'
+
+      - name: Install docs lint tools
+        run: npm install --global cspell@8.19.4 markdownlint-cli2@0.18.1
+
+      - name: Lint Markdown
+        run: markdownlint-cli2 "docs/**/*.md"
+
+      - name: Spell-check docs
+        run: cspell --no-progress --config .cspell.json "docs/**/*.md" "mkdocs.yml"
+
+      - name: Check links (including external)
+        uses: lycheeverse/lychee-action@885c65f3dc543b57c898c8099f4e08c8afd178a2 # v2.6.1
+        with:
+          fail: true
+          args: >-
+            --verbose
+            --no-progress
+            --accept 200,429
+            --max-retries 2
+            --retry-wait-time 2
+            --exclude '^https://github.com/coder/coder-k8s$'
+            docs/*.md docs/*/*.md docs/*/*/*.md
+            mkdocs.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build:
+    if: github.event_name == 'pull_request'
+    needs: docs-quality
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: '3.x'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build docs (strict)
+        run: mkdocs build --strict
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: docs-quality
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: '3.x'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build docs (strict)
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -12,3 +12,7 @@
 
 # Temporary external clones/forks
 /tmpfork/
+
+# MkDocs
+/site/
+/.cache/

.markdownlint-cli2.yaml

@@ -0,0 +1,3 @@
+config:
+  default: true
+  MD013: false

AGENTS.md

@@ -66,6 +66,8 @@ Run from repository root.
 - **Vendor consistency:** `make verify-vendor`
 - **Manifest generation:** `make manifests` (or `bash ./hack/update-manifests.sh`)
 - **Code generation:** `make codegen` (or `bash ./hack/update-codegen.sh`)
+- **Docs (serve):** `make docs-serve`
+- **Docs (strict build):** `make docs-check`
 - **Clean:** `go clean -cache -testcache && rm -f ./coder-k8s && rm -rf ./dist`
 - **Shell scripts:** `find . -type f -name '*.sh' -not -path './vendor/*'`
 
@@ -89,6 +91,9 @@ Run from repository root.
 - **Do** keep controller, aggregated API server, and storage changes paired with focused tests (`main_test.go`, `internal/controller/*_test.go`, and package tests under `internal/app/`/`internal/aggregated/`).
   **Don’t** add behavior without coverage for critical assumptions.
 
+- **Do** update the docs in `docs/` when you change user-facing behavior (APIs, flags, manifests, deployment).
+  **Don’t** let docs drift from the implementation.
+
 ## Anti-patterns
 
 - Unpinned GitHub Action versions in workflow files (CI uses SHA-pinned actions).
@@ -111,6 +116,8 @@ Run from repository root.
 4. Run `make lint` (or explain why it was skipped).
 5. If API types changed, run `make codegen` and `make manifests`, then include generated updates.
 6. If `.github/workflows/*` changed, run `go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.10`.
+7. If your change affects user-facing behavior (APIs, flags, manifests, deployment), update the documentation in `docs/` and run `make docs-check`.
+
 
 ### Commit messages
 - Match repository history style: short imperative summary, optionally prefixed by type (e.g., `chore: ...`).

Makefile

@@ -4,7 +4,7 @@ MODULE_FILES := go.mod $(wildcard go.sum)
 ENVTEST_K8S_VERSION ?= 1.35.x
 ENVTEST_ASSETS_DIR := $(shell pwd)/bin/envtest
 
-.PHONY: vendor test test-integration setup-envtest build lint vuln verify-vendor codegen manifests
+.PHONY: vendor test test-integration setup-envtest build lint vuln verify-vendor codegen manifests docs-serve docs-build docs-check
 
 $(VENDOR_STAMP): $(MODULE_FILES)
 	go mod tidy
@@ -47,3 +47,16 @@ manifests: $(VENDOR_STAMP)
 
 codegen: $(VENDOR_STAMP)
 	bash ./hack/update-codegen.sh
+
+
+docs-serve:
+	@command -v mkdocs >/dev/null || (echo "mkdocs not found; use nix develop" && exit 1)
+	mkdocs serve
+
+docs-build:
+	@command -v mkdocs >/dev/null || (echo "mkdocs not found; use nix develop" && exit 1)
+	mkdocs build
+
+docs-check:
+	@command -v mkdocs >/dev/null || (echo "mkdocs not found; use nix develop" && exit 1)
+	mkdocs build --strict

README.md

@@ -2,7 +2,10 @@
 
 ## Project description
 
-`coder-k8s` is a Go-based Kubernetes operator for managing `CoderControlPlane` resources (`coder.com/v1alpha1`). It is built with `sigs.k8s.io/controller-runtime`.
+`coder-k8s` is a Go-based Kubernetes control-plane project with two app modes:
+
+- A `controller-runtime` operator for managing `CoderControlPlane` resources (`coder.com/v1alpha1`).
+- An aggregated API server for `CoderWorkspace` and `CoderTemplate` resources (`aggregation.coder.com/v1alpha1`).
 
 ## Prerequisites
 
@@ -20,7 +23,7 @@ make manifests
 kubectl apply -f config/crd/bases/
 
 # Run the controller locally (uses your kubeconfig context)
-GOFLAGS=-mod=vendor go run .
+GOFLAGS=-mod=vendor go run . --app=controller
 
 # In another terminal: apply the sample CR
 kubectl apply -f config/samples/coder_v1alpha1_codercontrolplane.yaml
@@ -40,6 +43,8 @@ kubectl get codercontrolplanes -A
 | `make verify-vendor` | Verify vendor consistency |
 | `make lint` | Run linter (requires `golangci-lint`) |
 | `make vuln` | Run vulnerability check (requires `govulncheck`) |
+| `make docs-serve` | Serve the documentation site locally (requires `mkdocs`) |
+| `make docs-check` | Build docs in strict mode (CI-equivalent) |
 
 ## Testing strategy
 

docs/explanation/architecture.md

@@ -0,0 +1,38 @@
+# Architecture
+
+`coder-k8s` builds a single binary (`coder-k8s`) that can run in one of two modes:
+
+- `--app=controller`
+- `--app=aggregated-apiserver`
+
+The dispatch logic lives in `app_dispatch.go`. The `--app` flag is required, and the code intentionally fails fast with an `assertion failed:` error when it is missing or invalid.
+
+## Controller mode
+
+In controller mode, the binary runs a `controller-runtime` manager and registers the `CoderControlPlane` API types:
+
+- API group: `coder.com/v1alpha1`
+- Kind: `CoderControlPlane`
+
+Key code paths:
+
+- `internal/app/controllerapp/` — scheme construction and manager startup
+- `internal/controller/` — reconciliation logic (`CoderControlPlaneReconciler`)
+
+## Aggregated API server mode
+
+In aggregated API server mode, the binary starts an aggregated API server that installs storage for:
+
+- API group: `aggregation.coder.com/v1alpha1`
+- Resources: `coderworkspaces`, `codertemplates`
+
+Key code paths:
+
+- `internal/app/apiserverapp/` — API server bootstrap and API group installation
+- `internal/aggregated/storage/` — storage implementations (currently hardcoded in-memory objects)
+
+## Manifests and generated assets
+
+- `config/` — generated CRDs and RBAC (via `make manifests`)
+- `deploy/` — example deployment manifests for controller and aggregated API server
+- `vendor/` — vendored dependencies (required by the repo workflow)

docs/how-to/deploy-aggregated-apiserver.md

@@ -0,0 +1,61 @@
+# Deploy the aggregated API server (in-cluster)
+
+This guide shows how to deploy the `coder-k8s` **aggregated API server** and register it with the Kubernetes API aggregation layer.
+
+The aggregated API server serves:
+
+- API group: `aggregation.coder.com`
+- Version: `v1alpha1`
+- Resources: `coderworkspaces`, `codertemplates`
+
+## 1. Create the namespace
+
+```bash
+kubectl create namespace coder-system
+```
+
+## 2. Apply RBAC
+
+The RBAC manifest includes service accounts for both the controller and the aggregated API server.
+
+```bash
+kubectl apply -f deploy/rbac.yaml
+```
+
+## 3. Deploy the service and deployment
+
+```bash
+kubectl apply -f deploy/apiserver-service.yaml
+kubectl apply -f deploy/apiserver-deployment.yaml
+```
+
+## 4. Register the APIService
+
+```bash
+kubectl apply -f deploy/apiserver-apiservice.yaml
+```
+
+## 5. Verify
+
+Wait for the deployment:
+
+```bash
+kubectl rollout status deployment/coder-k8s-apiserver -n coder-system
+```
+
+Check the APIService:
+
+```bash
+kubectl get apiservice v1alpha1.aggregation.coder.com
+```
+
+List resources served by the aggregated API server:
+
+```bash
+kubectl get coderworkspaces.aggregation.coder.com -A
+kubectl get codertemplates.aggregation.coder.com -A
+```
+
+## TLS note
+
+`deploy/apiserver-apiservice.yaml` currently sets `insecureSkipTLSVerify: true`, which is convenient for development but not appropriate for production.