From 726bb61453913a753b9d44c7ffd285212d59ebfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Dworzy=C5=84ski?= <adam.dworzynski@cloudfiber.app>
Date: Thu, 9 Jul 2026 07:49:21 +0200
Subject: [PATCH] ci(docs): add MkDocs site and GitHub Pages deploy

---
 .github/workflows/docs.yml | 46 ++++++++++++++++++++++++
 .gitignore                 |  4 +++
 docs/README.md             |  4 +++
 mkdocs.yml                 | 72 ++++++++++++++++++++++++++++++++++++++
 pyproject.toml             |  1 +
 5 files changed, 127 insertions(+)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 mkdocs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..e3cb4d0
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install docs dependencies
+        run: pip install -e '.[docs]'
+      - name: Build site
+        run: mkdocs build --site-dir _site
+      - 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:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index d149ebd..a17f4aa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,10 @@ __pycache__/
 build/
 dist/
 
+# MkDocs build output
+/site/
+/_site/
+
 # gate evidence (pre-GitHub era): curated records live at tag archive/pre-github;
 # raw session captures are local-only
 /gates/
diff --git a/docs/README.md b/docs/README.md
index c0351bf..bbc2b8c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,9 @@
 # EAaC Documentation
 
+> Practice enterprise architecture as versioned, validated, code-like discipline — a deterministic
+> engine that **proves** your architecture is consistent, with AI supplying only judgment, never the
+> proof.
+
 **Start here:** [architecture.md](architecture.md) — what EAaC is and how the pieces fit.
 
 ## Living truth
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..01d9a1f
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,72 @@
+site_name: Enterprise Architecture as Code
+site_description: >-
+  Enterprise architecture as versioned, validated code — a deterministic engine that proves
+  your architecture is consistent; AI supplies only judgment.
+site_url: https://adworzynski.github.io/ea-as-a-code/
+repo_url: https://github.com/adworzynski/ea-as-a-code
+repo_name: adworzynski/ea-as-a-code
+edit_uri: edit/main/docs/
+docs_dir: docs
+
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+    - toc.follow
+    - search.highlight
+
+markdown_extensions:
+  - admonition
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+
+nav:
+  - Home: README.md
+  - Principles: principles.md
+  - Architecture: architecture.md
+  - Reference:
+      - CLI contract: reference/cli.md
+      - Repository: reference/repository.md
+      - Method packs: reference/packs.md
+      - Manifest: reference/manifest.md
+      - Surfaces: reference/surfaces.md
+  - Guides:
+      - Quickstart: guides/quickstart.md
+      - Tailoring: guides/tailoring.md
+  - Decisions:
+      - Overview: decisions/README.md
+      - 0001 · Dry-run confirm token: decisions/0001-dry-run-confirm-token.md
+      - 0002 · Methods selected, not packs: decisions/0002-methods-selected-not-packs.md
+      - 0003 · Scaffold from types, no templates: decisions/0003-scaffold-from-types-no-templates.md
+      - 0004 · Closed rule vocabulary: decisions/0004-closed-rule-vocabulary.md
+      - 0005 · Location-independent references: decisions/0005-location-independent-references.md
+      - 0006 · No hosted registry: decisions/0006-no-hosted-registry.md
+      - 0007 · Org overlays, not author namespacing: decisions/0007-org-overlays-not-author-namespacing.md
+      - 0008 · Governance in the manifest: decisions/0008-governance-in-manifest-enforced-at-create.md
+      - 0009 · Judgment stays on the surface: decisions/0009-judgment-stays-on-the-surface.md
+      - 0010 · Diff and review in the core: decisions/0010-diff-and-review-in-the-core.md
diff --git a/pyproject.toml b/pyproject.toml
index 6692c83..ea53aa8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -20,6 +20,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest>=7.4"]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5,<10"]
 
 [project.scripts]
 ea = "ea_core.cli:main"