Add GitHub Pages documentation site

.github/workflows/pages.yml

@@ -0,0 +1,57 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/site/**"
+      - "assets/logo/**"
+      - "assets/brand/**"
+      - "requirements-docs.txt"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install MkDocs
+        run: pip install -r requirements-docs.txt
+
+      - name: Build site
+        run: mkdocs build --strict -f docs/site/mkdocs.yml
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -20,3 +20,6 @@ Thumbs.db
 # Env
 .env
 .env.*
+
+# MkDocs build output
+/site/

README.md

@@ -18,6 +18,8 @@
 </p>
 
 <p align="center">
+  <a href="https://theworker02.github.io/shiftlock/"><strong>Docs site</strong></a>
+  ·
   <a href="https://pkg.go.dev/github.com/theworker02/shiftlock"><strong>Go module docs</strong></a>
   ·
   <a href="https://github.com/theworker02/shiftlock/releases/tag/v0.8.0">v0.8.0</a>
@@ -185,10 +187,28 @@ go run ./cmd/shiftlock-inspect readiness-report -format json
 
 Destructive recovery requires `--expected-owner`, `--expected-token`, `--reason`, and `--confirm` — never a blind force-unlock.
 
+## Documentation site
+
+Human-oriented docs are published with MkDocs Material to GitHub Pages:
+
+**[https://theworker02.github.io/shiftlock/](https://theworker02.github.io/shiftlock/)**
+
+Sources live under [`docs/site/`](docs/site/). Preview locally:
+
+```bash
+pip install -r requirements-docs.txt
+mkdocs serve -f docs/site/mkdocs.yml
+```
+
+Deploy uses [`.github/workflows/pages.yml`](.github/workflows/pages.yml). In the
+repo **Settings → Pages**, set the source to **GitHub Actions** (not a branch
+folder). Site Python deps are in `requirements-docs.txt` only — not `go.mod`.
+
 ## Documentation
 
 | Topic | Link |
 |-------|------|
+| **Docs site** | **[theworker02.github.io/shiftlock](https://theworker02.github.io/shiftlock/)** |
 | Architecture | [docs/architecture.md](docs/architecture.md) |
 | Handoff protocol | [docs/handoff-protocol.md](docs/handoff-protocol.md) |
 | Fencing tokens | [docs/fencing-tokens.md](docs/fencing-tokens.md) |

docs/site/README.md

@@ -1,7 +1,24 @@
 # ShiftLock Documentation Site
 
-Markdown documentation hierarchy for Phase 6. Intended for MkDocs / similar static
-generators later; until then browse these pages directly in the repository.
+Published with **MkDocs Material** from this tree. Live site:
+[https://theworker02.github.io/shiftlock/](https://theworker02.github.io/shiftlock/).
+
+## Local preview
+
+From the repository root (Python 3.10+):
+
+```bash
+pip install -r requirements-docs.txt
+mkdocs serve -f docs/site/mkdocs.yml
+```
+
+Build:
+
+```bash
+mkdocs build --strict -f docs/site/mkdocs.yml
+```
+
+Site dependencies stay in `requirements-docs.txt` — never in `go.mod`.
 
 ## Navigation
 
@@ -38,24 +55,25 @@ generators later; until then browse these pages directly in the repository.
 | Production Checklist | [production-checklist/](production-checklist/) |
 | API Reference | [api-reference/](api-reference/) |
 | Examples | [examples/](examples/) |
+| Problem guides | [problems/](problems/) |
 
-## Site goals
+## Deploy
 
-- Strong hierarchy and side navigation (not a card wall)
-- Security warnings call out fail-closed defaults
-- Backend capability tables and failure scenarios
-- Copyable Go examples and CLI snippets
-- Migration notes from Phase 5
+GitHub Actions workflow [`.github/workflows/pages.yml`](../../.github/workflows/pages.yml)
+builds on pushes to `main` that touch docs/site (and related paths) and on
+`workflow_dispatch`.
 
-See also:
+**GitHub Pages source must be GitHub Actions** (Settings → Pages → Build and
+deployment → Source: GitHub Actions).
 
-- [Security model](../security-model.md)
-- [Threat model](../threat-model.md)
-- [Dependency discipline](../dependency-discipline.md)
-- [Phase 6 audit](../audits/phase-6-audit.md)
+## Branding
 
-## Future tooling
+Theme colors follow [brand guidelines](../../assets/brand/brand-guidelines.md)
+(Lock Cyan `#27C2D1`, Transfer Blue `#2D72E8`, Deep Navy `#0A1830`). Logos under
+`assets/` are copies of `assets/logo/` for MkDocs `docs_dir` constraints.
+
+See also:
 
-Planned: search, version selector, and branded MkDocs Material theme using
-`assets/logo/shiftlock-horizontal.svg`. Content stubs are authoritative until
-the generator is wired.
+- [Security model](https://github.com/theworker02/shiftlock/blob/main/docs/security-model.md)
+- [Threat model](https://github.com/theworker02/shiftlock/blob/main/docs/threat-model.md)
+- [Dependency discipline](https://github.com/theworker02/shiftlock/blob/main/docs/dependency-discipline.md)

docs/site/api-reference/index.md

@@ -1,5 +1,17 @@
 # API Reference
 
-Primary module: [pkg.go.dev/github.com/theworker02/shiftlock](https://pkg.go.dev/github.com/theworker02/shiftlock)
+Published Go docs:
 
-Key packages: `capability`, `guard`, `audit`, `supervise`, `election`, `barrier`, `configlock`, `control/*`, `security/*`.
+- **Module:** [pkg.go.dev/github.com/theworker02/shiftlock](https://pkg.go.dev/github.com/theworker02/shiftlock)
+- **Repository:** [github.com/theworker02/shiftlock](https://github.com/theworker02/shiftlock)
+
+Key packages:
+
+| Area | Packages |
+|------|----------|
+| Core | root module (`New`, `Coordinator`, `NewRuntime`) |
+| Security | `capability`, `guard`, `security/*`, `configlock` |
+| Control plane | `audit`, `control/*`, `supervise`, `election`, `barrier` |
+| Backends | `backend/memory`, `backend/postgres`, `backend/redis`, `backend/kubernetes` |
+
+Start with [Quick Start](../quick-start/index.md) for copy-paste examples.

docs/site/index.md

@@ -1,12 +1,45 @@
-# ShiftLock Docs
+# ShiftLock
 
-ShiftLock is a **security-first runtime coordination and control module** for
-production Go systems. It protects who may perform sensitive work, when that
-work may run, and how responsibility moves safely between instances.
+![ShiftLock](assets/shiftlock-horizontal.svg){: .sl-hero-logo }
 
-Start with [Quick Start](quick-start/index.md), then [Concepts](concepts/index.md).
+**Security-first runtime coordination and control for Go.**
+
+ShiftLock protects who may perform sensitive work, when that work may run, and
+how responsibility moves safely between instances — without a hosted control
+plane.
+
+<div class="sl-links" markdown>
+
+[Quick Start](quick-start/index.md) ·
+[Introduction](introduction/index.md) ·
+[Go package docs](https://pkg.go.dev/github.com/theworker02/shiftlock) ·
+[GitHub](https://github.com/theworker02/shiftlock)
+
+</div>
 
 !!! warning "Opt-in security"
     Advanced control-plane features are **opt-in**. `shiftlock.New` / Coordinator
     APIs remain unchanged. Deny privileged operations by default when security
     subsystems are enabled.
+
+## What it is
+
+| It is | It is not |
+|-------|-----------|
+| Ownership handoff + fencing for Go processes | A hosted control plane |
+| An opt-in runtime supervisor & security layer | A Kubernetes-only framework |
+| A shared fabric around DBs, queues, APIs, files | A replacement for those systems |
+| Importable as a normal Go module | A SaaS product |
+
+```bash
+go get github.com/theworker02/shiftlock@latest
+```
+
+Module path: [`github.com/theworker02/shiftlock`](https://pkg.go.dev/github.com/theworker02/shiftlock).
+
+## Next steps
+
+1. [Introduction](introduction/index.md) — positioning and package layout
+2. [Quick Start](quick-start/index.md) — install, run examples, first coordinator
+3. [Concepts](concepts/index.md) — claims, fencing, capabilities, lockdown
+4. [API Reference](api-reference/index.md) — packages on pkg.go.dev

docs/site/introduction/index.md

@@ -1,11 +1,39 @@
 # Introduction
 
-ShiftLock coordinates **ownership**, **fencing**, and (optionally) a **runtime control plane** for Go services.
+ShiftLock is a **security-first runtime coordination and control module** for
+production Go systems. It coordinates **ownership**, **fencing**, and (optionally)
+a **runtime control plane** so sensitive work has a clear owner, a monotonic
+fencing token, and a safe handoff path between instances.
 
-It is not a hosted SaaS control plane, remote shell, or SIEM. Import it as a normal module:
+It is not a hosted SaaS control plane, remote shell, or SIEM. Import it as a
+normal module:
 
 ```go
 import "github.com/theworker02/shiftlock"
 ```
 
-Core stays lightweight (stdlib). Advanced packages live under `capability/`, `guard/`, `audit/`, `control/`, `supervise/`, `election/`, `security/`.
+| | |
+|---|---|
+| **Module** | [`github.com/theworker02/shiftlock`](https://pkg.go.dev/github.com/theworker02/shiftlock) |
+| **Repository** | [github.com/theworker02/shiftlock](https://github.com/theworker02/shiftlock) |
+| **Package docs** | [pkg.go.dev](https://pkg.go.dev/github.com/theworker02/shiftlock) |
+
+## Design stance
+
+- **Core stays lightweight** — stdlib-first; no third-party requires in the root
+  `go.mod`.
+- **Advanced packages are opt-in** — `capability/`, `guard/`, `audit/`, `control/`,
+  `supervise/`, `election/`, `security/`, and resource/workflow adapters.
+- **Fail closed when enabled** — privileged operations default to deny once
+  security subsystems are turned on.
+- **Coordinator APIs stay stable** — `shiftlock.New` and the Phase 5 Coordinator
+  surface remain unchanged when you adopt Phase 6 runtime features.
+
+## What ShiftLock decides
+
+Graceful shutdown stops an old process. ShiftLock decides who may perform
+protected work next — with fencing tokens so a stale process cannot keep acting
+after losing ownership — and optionally extends that model to supervisors,
+workflows, databases, queues, and APIs.
+
+Continue with [Quick Start](../quick-start/index.md) or [Concepts](../concepts/index.md).