flightdeckdev · Gsbreddy · May 26, 2026
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -0,0 +1,55 @@
+# Builds MkDocs site from docs/ and deploys to GitHub Pages.
+#
+# One-time repo setup (maintainer): Settings → Pages → Build and deployment →
+# Source: GitHub Actions. The first successful run publishes the site.
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  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: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install MkDocs
+        run: pip install -r docs/requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - 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
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,9 @@ web/node_modules/
 .tools/
 build/
 dist/
+
+# MkDocs (local `mkdocs build`; GitHub Pages uploads `site/` from CI only)
+/site/
 *.egg-info/
 .coverage
 htmlcov/

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ This project follows [Semantic Versioning](https://semver.org/). From **v1.0.0**
 
 ### Added
 
+- **Documentation (GitHub Pages):** workflow **`.github/workflows/pages.yml`** builds **`docs/`** with MkDocs Material on pushes to **`main`**; published URL on **`[project.urls] Documentation`**, README, **`DEVELOPMENT.md`**, and **`CONTRIBUTING.md`**. The static site includes a dismissible **Ask AI** banner (Perplexity / ChatGPT / repo) and a floating **Ask AI** shortcut (Perplexity with docs + repo context); no FlightDeck servers are involved.
 - **Web UI (`flightdeck serve`):** **`/#/settings`** for appearance (Light / Dark / System, **`flightdeck-theme`**); collapsible sidebar (**`flightdeck-sidebar-collapsed`**); **offline system font stack** (no remote font CSS); sidebar + favicon use **bundled** **`/assets/flightdeck-icon-*.png`** with stable **`GET /flightdeck-icon.png`** fallback; **`html[data-theme="dark"]`** tokens and Playwright **`web/e2e/`** (`smoke` icon checks, `theme.spec.ts`, `sidebar.spec.ts`).
 - **`flightdeck pricing check`** — reports **`flightdeck-bundled-*`** snapshot age vs **`--max-age-days`** (default **90**); **`--fail`** for CI. **`release diff`** / **`POST /v1/diff`** append **`pricing.warnings`** when bundled snapshots exceed the same age threshold.
 - **`flightdeck.integrations.telemetry.configure_otel_tracing()`** — optional OTLP HTTP **`TracerProvider`** wiring when the **`telemetry`** extra is installed (see **`docs/sdk-integrations.md`**).

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -55,6 +55,10 @@ If you change **`pyproject.toml`** dependencies, run **`uv lock`** and commit **
 
 Details, Windows notes, and doctrine: **`AGENTS.md`** (Verification), **`DEVELOPMENT.md`**, **`web/README.md`**.
 
+## GitHub Pages (maintainers)
+
+The **Deploy documentation to GitHub Pages** workflow publishes **`docs/`** on pushes to **`main`**. In the GitHub repo, use **Settings → Pages → Build and deployment → Source: GitHub Actions** so the workflow can attach the **`github-pages`** environment. The live URL is linked from the root **`README.md`** and **`pyproject.toml`** **`Documentation`** URL.
+
 ## Private files and pushing to GitHub
 
 Do not commit credentials, customer data, internal strategy docs, or local ledger data. The repo ignores **`.flightdeck/`**, **`.env*`**, optional **`private/`** / **`secrets/`**, and common key/credential patterns—see **`.gitignore`** and **[SECURITY.md](SECURITY.md)**.

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -282,3 +282,14 @@ Use **`uv run python -m pytest`** from the repo root so imports like **`from tes
 | `VITE_FLIGHTDECK_LOCAL_API_TOKEN` | Web dev server | Build-time variable for the React UI dev server (Vite). Copy `web/.env.example` → `web/.env.local` to set it when testing mutations through `npm run dev` against a token-protected server. |
 | `VITE_DEV_PROXY_TARGET` | Web dev server | Overrides the Vite proxy target for `/v1` (default: `http://127.0.0.1:8765`). |
 | `TMPDIR` / `TEMP` / `TMP` | Tests / OS | Standard temp directory environment variables. Set any of these to a repo-local `.tmp/` path if the OS default is restricted or permissions cause pytest failures. |
+
+## Documentation site (MkDocs)
+
+The Markdown under **`docs/`** is also built as a static site for **[GitHub Pages](https://flightdeckdev.github.io/flightdeck/)** (workflow **`.github/workflows/pages.yml`**). To preview locally:
+
+```bash
+pip install -r docs/requirements.txt
+mkdocs serve
+```
+
+Then open the URL MkDocs prints (usually **http://127.0.0.1:8000/**). The build output directory **`site/`** is gitignored; CI uploads it as the Pages artifact.
diff --git a/README.md b/README.md
@@ -115,6 +115,8 @@ Bundled pricing from `init` is a **convenience snapshot**—`flightdeck pricing
 
 ## Documentation
 
+**Published site (GitHub Pages):** [flightdeckdev.github.io/flightdeck](https://flightdeckdev.github.io/flightdeck/) — built from `docs/` on each push to `main` (`.github/workflows/pages.yml`). Enable **Pages → GitHub Actions** in the repository settings if the site is not live yet.
+
 | Area | Links |
 |------|--------|
 | CLI | [docs/cli.md](docs/cli.md) |

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,33 @@
+# FlightDeck documentation
+
+FlightDeck helps teams **ship AI agents safely** with **release diffs**, **runtime evidence**, and **policy gates**.
+
+This site mirrors the Markdown guides in the [flightdeck repository](https://github.com/flightdeckdev/flightdeck). Use the navigation on the left for the full reference. Repository-only pages (for example `SECURITY.md` at the repo root) are linked from the guides where relevant—open those on GitHub when you need the latest wording.
+
+## Ask AI
+
+Use the **dismissible banner** at the top to open **Perplexity** or **ChatGPT** in a new tab. Mention this documentation site or the GitHub repo so answers stay grounded in the real product surface (CLI, `release.yaml`, HTTP `/v1` routes, policy).
+
+## Quick links
+
+| Topic | Doc |
+|--------|-----|
+| Commands, flags, exit codes | [CLI reference](cli.md) |
+| `flightdeck serve` JSON API | [HTTP API](http-api.md) |
+| Diff, promote, rollback, SQLite | [Operations & policy](operations-and-policy.md) |
+| `release.yaml`, workspace config | [Release artifact](release-artifact.md) |
+| Optional pricing catalog YAML | [Pricing catalog](pricing-catalog.md) |
+| `flightdeck` Python client | [Python SDK](sdk.md) |
+| Experimental adoption hooks | [SDK integrations](sdk-integrations.md) |
+| Shipped web UI vs roadmap | [Web UI](web-ui.md) · [UI roadmap](ui-roadmap.md) |
+| Common failures | [Troubleshooting](troubleshooting.md) |
+
+## Install (local)
+
+```bash
+uv sync --extra dev
+uv run flightdeck --help
+uv run flightdeck-quickstart-verify
+```
+
+See [DEVELOPMENT.md](https://github.com/flightdeckdev/flightdeck/blob/main/DEVELOPMENT.md) on GitHub for full contributor setup, web bundle rebuild, and CI parity.
diff --git a/docs/javascripts/ask-ai.js b/docs/javascripts/ask-ai.js
@@ -0,0 +1,31 @@
+/* Floating “Ask AI” — opens Perplexity with repo + docs context (no FlightDeck servers). */
+(function () {
+  var url =
+    "https://www.perplexity.ai/search?q=" +
+    encodeURIComponent(
+      "FlightDeck: AI agent release governance (CLI, SQLite ledger, policy gates, diff, promote). Official docs site https://flightdeckdev.github.io/flightdeck/ and source https://github.com/flightdeckdev/flightdeck — answer using those when possible."
+    );
+
+  function addButton() {
+    if (document.getElementById("fd-floating-ask-ai")) {
+      return;
+    }
+    var a = document.createElement("a");
+    a.id = "fd-floating-ask-ai";
+    a.href = url;
+    a.target = "_blank";
+    a.rel = "noopener noreferrer";
+    a.textContent = "Ask AI";
+    a.setAttribute(
+      "aria-label",
+      "Ask AI about FlightDeck in Perplexity (new tab)"
+    );
+    document.body.appendChild(a);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", addButton);
+  } else {
+    addButton();
+  }
+})();
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+# Pinned for reproducible GitHub Pages builds (not part of the Python package).
+mkdocs==1.6.1
+mkdocs-material==9.6.14
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -0,0 +1,30 @@
+/* Slightly stronger “Ask AI” strip (Material theme `extra.announce`) */
+.md-banner {
+  font-size: 0.85rem;
+}
+
+.md-banner a {
+  font-weight: 600;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+/* Floating Perplexity shortcut (paired with docs/javascripts/ask-ai.js) */
+#fd-floating-ask-ai {
+  position: fixed;
+  bottom: 1.25rem;
+  right: 1.25rem;
+  z-index: 200;
+  padding: 0.45rem 1rem;
+  border-radius: 999px;
+  background: var(--md-primary-fg-color);
+  color: var(--md-primary-bg-color) !important;
+  font-weight: 600;
+  font-size: 0.8rem;
+  box-shadow: var(--md-shadow-z2);
+  text-decoration: none !important;
+}
+
+#fd-floating-ask-ai:hover {
+  opacity: 0.92;
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,82 @@
+site_name: FlightDeck documentation
+site_description: Release diffs, runtime evidence, and policy gates for AI agents.
+site_url: https://flightdeckdev.github.io/flightdeck/
+repo_url: https://github.com/flightdeckdev/flightdeck
+repo_name: flightdeckdev/flightdeck
+edit_uri: edit/main/docs/
+
+docs_dir: docs
+site_dir: site
+
+strict: true
+
+# Guides intentionally link to repo-root files (SECURITY.md, schemas/, …) for GitHub
+# readers; those paths are not copied into the MkDocs tree.
+validation:
+  links:
+    not_found: ignore
+    anchors: ignore
+
+nav:
+  - Home: index.md
+  - CLI: cli.md
+  - HTTP API: http-api.md
+  - Operations & policy: operations-and-policy.md
+  - Release artifact: release-artifact.md
+  - Pricing catalog: pricing-catalog.md
+  - Python SDK: sdk.md
+  - SDK integrations: sdk-integrations.md
+  - Web UI: web-ui.md
+  - UI roadmap: ui-roadmap.md
+  - Troubleshooting: troubleshooting.md
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.expand
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+plugins:
+  - search
+
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - toc:
+      permalink: true
+
+extra:
+  generator: false
+  # Dismissible strip with outbound “Ask AI” helpers (no FlightDeck backend).
+  announce: >-
+    <strong>Ask AI</strong> about FlightDeck (paste the question after the page loads):
+    <a target="_blank" rel="noopener noreferrer" href="https://www.perplexity.ai/search?q=FlightDeck%20AI%20release%20governance%20flightdeck%20CLI%20policy%20gates%20site%3Aflightdeckdev.github.io%2Fflightdeck%20OR%20site%3Agithub.com%2Fflightdeckdev%2Fflightdeck">Perplexity</a>
+    ·
+    <a target="_blank" rel="noopener noreferrer" href="https://chatgpt.com/">ChatGPT</a>
+    ·
+    <a target="_blank" rel="noopener noreferrer" href="https://github.com/flightdeckdev/flightdeck">Repository</a>
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/ask-ai.js
diff --git a/pyproject.toml b/pyproject.toml
@@ -68,6 +68,7 @@ integrations-ci = [
 
 [project.urls]
 Homepage = "https://github.com/flightdeckdev/flightdeck"
+Documentation = "https://flightdeckdev.github.io/flightdeck/"
 Repository = "https://github.com/flightdeckdev/flightdeck"
 Issues = "https://github.com/flightdeckdev/flightdeck/issues"
 Changelog = "https://github.com/flightdeckdev/flightdeck/blob/main/CHANGELOG.md"