Add GitHub Actions workflows for MkDocs build validation and GitHub Pages deploy

- add a CI workflow to build the MkDocs site on pull requests and pushes to main/hot-fix
- install Python 3.10 and project dev dependencies in CI using the repo pyproject configuration
- validate sanitize output with tools/sanitize.py --check before site build
- validate generated visual docs are up to date with tools/docs/build_visual_docs.py --check
- run pytest before building docs to keep the docs pipeline aligned with repo quality gates
- build the MkDocs site with strict mode enabled and upload the generated site directory as a workflow artifact
- add a separate GitHub Pages deployment workflow for pushes to main and manual runs
- configure official GitHub Pages actions permissions and deployment environment
- publish the built site from the generated site directory to GitHub Pages using the actions-based Pages flow
 - 2026-02-22 17:28:32

Author: mgarcia01752

.github/workflows/mkdocs-pages-deploy.yml

@@ -0,0 +1,66 @@
+name: MkDocs Pages Deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -e ".[dev]"
+
+      - name: Validate visual sanitization
+        run: python tools/sanitize.py --check
+
+      - name: Validate generated visual docs
+        run: python tools/docs/build_visual_docs.py --check
+
+      - name: Run tests
+        run: python -m pytest -q
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/mkdocs-site-build.yml

@@ -0,0 +1,48 @@
+name: MkDocs Site Build
+
+on:
+  push:
+    branches:
+      - main
+      - hot-fix
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build-mkdocs-site:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -e ".[dev]"
+
+      - name: Validate visual sanitization
+        run: python tools/sanitize.py --check
+
+      - name: Validate generated visual docs
+        run: python tools/docs/build_visual_docs.py --check
+
+      - name: Run tests
+        run: python -m pytest -q
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: mkdocs-site
+          path: site/
+          if-no-files-found: error

CODING_AGENTS.md

@@ -23,4 +23,7 @@
 - When the user asks for a commit message, provide plain text for direct paste into the terminal or UI text box.
 - Do not wrap commit message suggestions in quotes (`"`), backticks (`` ` ``), or code fences unless the user explicitly asks for that format.
 - Prefer detailed commit messages that describe the current change set clearly.
+- Do not default to a one-line commit message when the change set is broad; provide a title plus concise bullet points.
 - Avoid redundant wording and avoid repeating the exact prior commit message suggestion unless the diff is unchanged and the user explicitly asks to reuse it.
+- If the user asks for "in a text box", return plain text only (no markdown fence).
+- If the user asks for "in a markdown text box", return the commit message inside a fenced code block with `text`.