docs: migrate docs UI to Astro Starlight

.github/workflows/docs-deploy.yaml

@@ -0,0 +1,64 @@
+name: Deploy docs
+
+# Publishes the Starlight docs site to GitHub Pages on every push to main that
+# touches the docs source or this workflow. Pull requests build the site without
+# deploying, so broken docs are caught before they merge.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-deploy.yaml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-deploy.yaml'
+
+# Least-privilege: read the repo, mint an OIDC token for Pages, write the Pages
+# deployment. No other scopes.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Serialize Pages deployments. Do NOT cancel in progress: a half-applied Pages
+# deploy can leave the live site inconsistent, so let each one finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Build site
+        run: npm run build
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/dist
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push'
+    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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

README.md

@@ -1,22 +1,25 @@
 <h1 align="center">cascade</h1>
 
-<!-- TODO(image): logo. place at docs/images/logo.png once generated -->
-<!-- ![cascade logo](docs/images/logo.png) -->
+<!-- Row 1: identity & quality -->
+<p align="center">
+  <a href="https://pkg.go.dev/github.com/stablekernel/cascade"><img src="https://pkg.go.dev/badge/github.com/stablekernel/cascade.svg" alt="Go Reference"></a>
+  <a href="https://goreportcard.com/report/github.com/stablekernel/cascade"><img src="https://goreportcard.com/badge/github.com/stablekernel/cascade" alt="Go Report Card"></a>
+  <a href="./go.mod"><img src="https://img.shields.io/github/go-mod/go-version/stablekernel/cascade" alt="Go Version"></a>
+  <a href="https://stablekernel.github.io/cascade/"><img src="https://img.shields.io/badge/docs-cascade-36D0C4" alt="Docs"></a>
+</p>
 
-<!-- Row 1: CI/quality -->
+<!-- Row 2: project health & CI -->
 <p align="center">
   <a href="https://github.com/stablekernel/cascade/actions/workflows/validate.yaml"><img src="https://github.com/stablekernel/cascade/actions/workflows/validate.yaml/badge.svg?branch=main" alt="Validate"></a>
   <a href="https://github.com/stablekernel/cascade/actions/workflows/e2e.yaml"><img src="https://github.com/stablekernel/cascade/actions/workflows/e2e.yaml/badge.svg?branch=main" alt="E2E"></a>
+  <a href="https://github.com/stablekernel/cascade/actions/workflows/codeql.yml"><img src="https://github.com/stablekernel/cascade/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL"></a>
   <a href="https://securityscorecards.dev/viewer/?uri=github.com/stablekernel/cascade"><img src="https://api.securityscorecards.dev/projects/github.com/stablekernel/cascade/badge" alt="OpenSSF Scorecard"></a>
-  <a href="https://goreportcard.com/report/github.com/stablekernel/cascade"><img src="https://goreportcard.com/badge/github.com/stablekernel/cascade" alt="Go Report Card"></a>
+  <a href="https://github.com/stablekernel/cascade/releases/latest"><img src="https://img.shields.io/github/v/release/stablekernel/cascade" alt="Latest release"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
 </p>
 
-<!-- Row 2: release/project -->
 <p align="center">
-  <a href="https://github.com/stablekernel/cascade/releases/latest"><img src="https://img.shields.io/github/v/release/stablekernel/cascade" alt="Latest release"></a>
-  <a href="https://github.com/stablekernel/cascade/actions/workflows/codeql.yml"><img src="https://github.com/stablekernel/cascade/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL"></a>
-  <a href="https://stablekernel.github.io/cascade/"><img src="https://img.shields.io/badge/docs-cascade-E8702A" alt="Docs"></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
+  <img src="docs/src/assets/avatar.png" alt="The cascade mascot" width="220">
 </p>
 
 <p align="center"><strong>Declarative trunk-based CI/CD for GitHub Actions.</strong></p>
@@ -31,8 +34,9 @@
 
 ## How it works
 
-<!-- TODO(image): hero/architecture diagram. place at docs/images/architecture.png once generated -->
-<!-- ![cascade architecture](docs/images/architecture.png) -->
+<p align="center">
+  <img src="docs/src/assets/hero.png" alt="Cascade promotes one artifact through every environment" width="640">
+</p>
 
 The **manifest** (`.github/manifest.yaml`) is the single source of truth. It holds both the pipeline configuration and the live deployment state for every environment. You run `cascade generate-workflow` once; after that the generated workflows own their own execution.
 

docs/.gitignore

@@ -0,0 +1,4 @@
+# Astro / Node build artifacts
+node_modules/
+dist/
+.astro/

docs/astro.config.mjs

@@ -0,0 +1,65 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import mermaid from 'astro-mermaid';
+
+// GitHub project page: https://stablekernel.github.io/cascade
+// `site` + `base` must match the Pages URL so generated links and assets resolve.
+export default defineConfig({
+  site: 'https://stablekernel.github.io',
+  base: '/cascade',
+  integrations: [
+    // astro-mermaid renders ```mermaid fenced code blocks client-side at runtime.
+    // It needs no headless browser at build time, keeping `npm run build` fast and
+    // dependency-light. `theme: 'dark'` matches the dark-default Cascade brand and
+    // mermaid auto-syncs when the reader toggles the theme.
+    mermaid({
+      theme: 'dark',
+      autoTheme: true,
+    }),
+    starlight({
+      title: 'Cascade',
+      tagline: 'Declarative trunk-based CI/CD for GitHub Actions.',
+      description:
+        'Cascade is a Go CLI that orchestrates multi-environment release and promotion pipelines from a single manifest by generating GitHub Actions workflows.',
+      logo: {
+        src: './src/assets/logo.png',
+        alt: 'Cascade logo',
+        replacesTitle: false,
+      },
+      favicon: '/favicon.png',
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/stablekernel/cascade',
+        },
+      ],
+      customCss: ['./src/styles/cascade.css'],
+      head: [
+        // Social card / og:image (brand art).
+        {
+          tag: 'meta',
+          attrs: { property: 'og:image', content: '/cascade/social-card.png' },
+        },
+        {
+          tag: 'meta',
+          attrs: { name: 'twitter:card', content: 'summary_large_image' },
+        },
+      ],
+      // Sidebar order mirrors the previous MkDocs nav exactly.
+      sidebar: [
+        { label: 'Getting Started', link: '/getting-started/' },
+        { label: 'Manifest Reference', link: '/configuration/' },
+        { label: 'Callback Contract', link: '/callback-contract/' },
+        {
+          label: 'Workflows',
+          items: [{ label: 'Overview', link: '/workflows/' }],
+        },
+        { label: 'CLI Reference', link: '/cli-reference/' },
+        { label: 'Architecture', link: '/architecture/' },
+        { label: 'Versioning & Schema', link: '/versioning/' },
+      ],
+    }),
+  ],
+});