docs: publish documentation as a GitHub Pages site and run a full quality pass

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Docs
+
+# Pull requests build the site in strict mode to catch broken links and nav.
+# The site is published only when a release is published (so it tracks the latest
+# released version), or manually via workflow_dispatch.
+on:
+  release:
+    types:
+      - published
+  pull_request:
+  workflow_dispatch:
+
+# Least privilege: the top level (inherited by the PR build job) is read-only;
+# the Pages and OIDC scopes are granted only to the deploy job below.
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install docs dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Build site (strict)
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -46,3 +46,6 @@ CLAUDE.md
 posts
 # Internal planning artifacts (specs/plans), keep local-only
 docs/superpowers/
+
+# MkDocs build output
+site/

.tool-versions

@@ -2,3 +2,4 @@ golang 1.25.6
 golangci-lint 2.11.2
 nodejs 25.1.0
 kind 0.31.0
+python 3.14.4

Makefile

@@ -101,6 +101,14 @@ $(PRETTIER): $(LOCALBIN)
 		chmod +x $(PRETTIER) ; \
 	}
 
+.PHONY: docs-serve
+docs-serve: ## Serve the documentation site locally with live reload.
+	mkdocs serve
+
+.PHONY: docs-build
+docs-build: ## Build the documentation site in strict mode.
+	mkdocs build --strict
+
 .PHONY: lint ## Run all linters
 lint: lint-go lint-md