docs: stand up MkDocs Material Pages site

.github/workflows/pages.yml

@@ -0,0 +1,77 @@
+# Builds and deploys the MkDocs documentation site to GitHub Pages on every
+# push to main that touches docs source or this workflow. Pull requests trigger
+# a build-only check to catch broken nav references or config errors early.
+#
+# Least-privilege: read the repo, mint an OIDC token for Pages, write the
+# Pages deployment. No other scopes.
+#
+# Serialize Pages deployments. Do NOT cancel in progress: a half-applied Pages
+# deploy can leave the live site in a broken state, so let each one finish.
+
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/pages.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/pages.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - 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: pip install -r docs/requirements.txt
+
+      - name: Configure Pages base URL
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs-material==9.6.14

docs/versioning.md

@@ -72,12 +72,12 @@ A CLI supports the current schema version and the immediately preceding one
 (N-1). When a new schema major lands, CLIs that ship with it continue to read
 the previous major with a warning. A subsequent major may drop support for the
 oldest major, at which point manifests at that version are rejected with a
-pointer to the migration entry in [CHANGELOG.md](../CHANGELOG.md).
+pointer to the migration entry in [CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md).
 
 ## Migrations
 
 Each `schema_version` bump is recorded with a `Migration` section in
-[CHANGELOG.md](../CHANGELOG.md) describing exactly what changed and the steps to
+[CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md) describing exactly what changed and the steps to
 update a manifest from the previous version. There are no migrations yet: the
 current schema version is the first.
 
@@ -88,7 +88,7 @@ and new capabilities all land here. No stability guarantee is made for the CLI
 command surface or the manifest schema between 0.x releases; additive changes
 arrive without a `schema_version` bump, but breaking changes (field removals,
 type changes, behaviour changes) increment `schema_version` and carry a
-`Migration` entry in [CHANGELOG.md](../CHANGELOG.md).
+`Migration` entry in [CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md).
 
 **1.0** — when cascade reaches v1.0 the following guarantees apply:
 
@@ -101,7 +101,7 @@ type changes, behaviour changes) increment `schema_version` and carry a
   1.x releases.
 
 Older tags outside the current release line do not receive backported fixes.
-See [SECURITY.md](../SECURITY.md) for the security-patch policy.
+See [SECURITY.md](https://github.com/stablekernel/cascade/blob/main/SECURITY.md) for the security-patch policy.
 
 ## Version bump reference
 

mkdocs.yml

@@ -0,0 +1,76 @@
+site_name: Cascade
+site_description: >-
+  Manifest-driven release orchestration for GitHub Actions — coordinate
+  builds, promotions, and releases across any environment topology.
+site_url: https://stablekernel.github.io/cascade/
+repo_url: https://github.com/stablekernel/cascade
+repo_name: stablekernel/cascade
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.code.annotate
+    - content.action.edit
+  icon:
+    repo: fontawesome/brands/github
+
+plugins:
+  - search
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - toc:
+      permalink: true
+
+nav:
+  - Getting Started: getting-started.md
+  - Manifest Reference: configuration.md
+  - Callback Contract: callback-contract.md
+  - Workflows:
+      - Overview: workflows.md
+  - CLI Reference: cli-reference.md
+  - Architecture: architecture.md
+  - Versioning & Schema: versioning.md
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/stablekernel/cascade