chore

Author: denisecase

.editorconfig

@@ -1,3 +1,7 @@
+# ============================================================
+# .editorconfig (Standardize files across editors and IDEs)
+# ============================================================
+
 # REQ.UNIVERSAL: All professional GitHub project repositories MUST include .editorconfig.
 # WHY: Establish a cross-editor baseline so diffs stay clean and formatting is consistent.
 # ALT: Repository may omit .editorconfig ONLY if formatting is enforced equivalently by CI and formatter tooling.

.github/dependabot.yml

@@ -1,21 +1,26 @@
+# ============================================================
+# .github/dependabot.yml (Check for GitHub Actions updates)
+# ============================================================
+# SOURCE: https://github.com/denisecase/templates
+#
 # REQ.PROJECT: This repository SHOULD track GitHub Actions updates automatically.
-# WHY: GitHub Actions are executable dependencies and may receive security or behavior updates.
-# OBS: This repository has no language-level dependencies (Python, JS, Rust, etc.).
-# OBS: GitHub Actions are the only dependency class currently in scope.
+# WHY-FILE: GitHub Actions are executable dependencies and may receive security or behavior updates.
+# OBS: Language-level dependencies (e.g., Python packages) are upgraded manually.
+# OBS: GitHub Actions are the only dependency class automated here.
 # ALT: Dependabot could be omitted if workflows are pinned and reviewed manually.
 # CUSTOM: Update interval if CI cadence or security posture changes.
 
-version: 2
+# NOTE: This file automatically updates the versions used in Actions workflows.
+# You don't need to modify this file.
+# To disable: Delete this file or set enabled: false below.
+# enabled: false # Uncomment to disable Dependabot
 
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
+version: 2 # Dependabot configuration version
 
-    # WHY: Monthly cadence balances stability with security updates.
-    # ALT: Use "weekly" for higher-security environments.
+updates:
+  - package-ecosystem: "github-actions" # Dependency type
+    directory: "/" # Location of GitHub Actions workflows
     schedule:
-      interval: "monthly"
-
-    # WHY: Clear commit prefix simplifies changelog review and filtering.
+      interval: "monthly" # ALT: Use "weekly" for higher security when needed
     commit-message:
-      prefix: "(deps)"
+      prefix: "(deps)"  # WHY: enable filtering by commit type

.github/workflows/ci-hygiene-mkdocs.yml

@@ -0,0 +1,85 @@
+# ============================================================
+# .github/workflows/ci-hygiene-mkdocs.yml (Continuous Integration)
+# ============================================================
+# SOURCE: https://github.com/denisecase/templates
+#
+# WHY-FILE: Validate repository hygiene and documentation builds.
+# REQ: Any check that can be run locally MUST be available locally via pre-commit.
+# REQ: CI MUST NOT introduce arbitrary rules that are not reproducible locally.
+# OBS: CI validates only; it never edits files or deploys docs.
+
+name: CI Hygiene (MkDocs Site)
+
+# WHY: Validate docs and repo metadata on PRs and pushes.
+# OBS: This workflow validates only; it never deploys.
+
+on:
+  push:
+    branches: [main] # WHY: Run when pushing to main branch.
+  pull_request:
+    branches: [main] # WHY: Run on pull requests targeting main branch.
+  workflow_dispatch: # WHY: Allow manual triggering from Actions tab.
+
+permissions: # WHY: Use least privileges required.
+  contents: read
+
+env:
+  PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
+  PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
+
+jobs:
+  ci:
+    name: Repository checks (pre-commit)
+    runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
+    timeout-minutes: 30 # WHY: Prevent hanging jobs. If over, it is likely stuck.
+
+
+    steps:
+      # ============================================================
+      # ASSEMBLE: Get code and set up environment
+      # ============================================================
+
+      - name: A1) Checkout repository code
+        # WHY: Needed to access files for checks.
+        uses: actions/checkout@v6
+
+      - name: A2) Run pre-commit (all files)
+        # WHY: Single source of truth for locally runnable quality gates.
+        # OBS: Fails if hooks would modify files; does not commit changes.
+        id: precommit # WHY: Identify step for conditional follow-up.
+        uses: pre-commit/[email protected]
+        with:
+          extra_args: --all-files
+
+      - name: A2f) If pre-commit failed, run it locally
+        if: failure()
+        run: |
+          echo "## Pre-commit failed" >> "$GITHUB_STEP_SUMMARY"
+          echo "Please run pre-commit locally and commit the resulting changes." >> "$GITHUB_STEP_SUMMARY"
+
+
+      - name: A3) Install uv (with caching)
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: A4) Install Python version 3.12
+        run: uv python install 3.12
+
+      - name: A5) Sync to install dependencies
+        run: uv sync --extra dev --extra docs --upgrade
+
+      # === BASELINE CHECKS ===
+
+      - name: B1) Validate pyproject
+        run: uvx validate-pyproject
+
+      # === DEPLOY (SANITY CHECKS ONLY; NO DEPLOY) ===
+
+      - name: D1) Build docs (mkdocs --strict)
+        run: |
+          if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then
+            uv run mkdocs build --strict
+          else
+            echo "No mkdocs config found; skipping docs build."
+          fi

.github/workflows/ci.yml

@@ -1,48 +1,51 @@
-# .github/workflows/deploy-docs.yml
-name: Docs Deploy (MkDocs Python)
-
+# ============================================================
+# .github/workflows/deploy-docs.yml (Deploy MkDocs)
+# ============================================================
+# SOURCE: https://github.com/denisecase/templates
 # WHY: Build and deploy documentation to GitHub Pages on pushes to main.
 # REQ: Repo Settings -> Pages -> Build and deployment -> Source:
 #      Deploy from a branch, Branch = gh-pages, Folder = /.
 
+name: Docs Deploy (MkDocs Python)
+
+# WHY: Deploy project documentation on pushes to main branch.
+
 on:
   push:
-    branches: [main]
-  workflow_dispatch:
+    branches: [main] # WHY: Run when pushing to main branch.
+  workflow_dispatch: # WHY: Allow manual triggering from Actions tab.
 
 permissions:
   contents: write # WHY: Required to push to gh-pages
 
 env:
-  PYTHONUNBUFFERED: "1"
-  PYTHONIOENCODING: "utf-8"
+  PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
+  PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
 
 jobs:
   docs:
+    name: Deploy MkDocs documentation site
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 30 # WHY: Prevent hanging jobs. If over, it is likely stuck.
 
     steps:
-      # === ASSEMBLE ===
+      # ============================================================
+      # ASSEMBLE: Get code and set up environment
+      # ============================================================
 
-      - name: A1) Checkout
+      - name: A1) Checkout repository code
+        # WHY: Needed to access files for checks.
         uses: actions/checkout@v6
 
       - name: A2) Install uv (with caching)
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
-      - name: A3) Pin Python version for consistency
-        run: uv python pin 3.12
-
-      - name: A4) Display versions
-        run: |
-          python --version
-          uv --version
-          uv pip list | head -n 50
+      - name: A3) Install Python version 3.12
+        run: uv python install 3.12
 
-      - name: A5) Sync to install dependencies
+      - name: A4) Sync to install dependencies
         run: uv sync --extra dev --extra docs --upgrade
 
       # === BASELINE CHECKS ===

.github/workflows/deploy-docs.yml

@@ -27,8 +27,8 @@ jobs:
       pull-requests: write
 
     steps:
-      - name: 1) Checkout repository code
-        uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
+      - name: A1) Checkout repository code
+        uses: actions/checkout@v6
 
       - name: 2) Check links with Lychee
         uses: lycheeverse/lychee-action@v2

.github/workflows/links.yml

@@ -1,3 +1,7 @@
+# ============================================================
+# .yamllint.yml (YAML linting configuration)
+# ============================================================
+
 # WHY: Enforce YAML correctness without arbitrary style constraints.
 # OBS: Default yamllint rules conflict with GitHub Actions YAML.
 #      Line length, document start, truthy, and comment spacing are intentionally disabled.

.yamllint.yml

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Denise M. Case
+Copyright (c) 2025-2026 Denise M. Case
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -2,6 +2,8 @@
 
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 [![Deploy Docs](https://github.com/structural-explainability/site/actions/workflows/deploy-docs.yml/badge.svg?branch=main)](https://github.com/structural-explainability/site/actions/workflows/deploy-docs.yml)
+![Build Status](https://github.com/structural-explainability/site/actions/workflows/ci-hygiene-mkdocs.yml/badge.svg?branch=main)
+[![Check Links](https://github.com/structural-explainability/site/actions/workflows/links.yml/badge.svg)](https://github.com/structural-explainability/site/actions/workflows/links.yml)
 [![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/structural-explainability/site/security/dependabot)
 
 > Documentation site for Structural Explainability.
@@ -18,16 +20,11 @@ Initialize once:
 ```shell
 uv self update
 uv python pin 3.12
+uv sync --extra dev --extra docs --upgrade
+
 uvx pre-commit install
+git add -A
 uvx pre-commit run --all-files
-
-# Windows:
-.venv\Scripts\activate
-
-# macOS/Linux:
-# source .venv/bin/activate
-
-uv sync --extra dev --extra docs --upgrade
 ```
 
 Build and serve docs:

README.md

@@ -1,34 +1,44 @@
-# WHY: Configures Lychee link checker behavior for CI/CD
-# OBS: Flat structure required by lychee v0.22+; no nested sections
+# ============================================================
+# lychee.toml (Lychee link checker configuration)
+# ============================================================
+
+# REQ.PROJECT: Automatic link checking using GitHub Actions and Lychee.
+# WHY-FILE: Shared Lychee configuration (lychee.toml) for documentation-heavy repositories.
+# REQ: Link checking MUST be reliable and CI-safe.
+# WHY: Configures Lychee link checker behavior for CI/CD.
+# OBS: Flat structure required by lychee v0.22+; no nested sections.
+# OBS: No path exclusions; all documentation files are expected to be link-clean.
+# OBS: Link integrity preserves stable, reconstructible references over time.
+# OBS: Link integrity maintains connections to external resources.
 
 # WHY: Control verbosity and CI-friendly output
-verbose = "info"     # WHY: Balance between detail and noise
-no_progress = true   # WHY: Progress bars don't work well in CI logs
+verbose = "info"   # WHY: Balance between detail and noise
+no_progress = true # WHY: Progress bars don't work well in CI logs
 
 # WHY: Performance tuning for link checking
-max_concurrency = 6  # WHY: Parallel requests without overwhelming servers
-max_retries = 3      # WHY: Retry flaky connections before failing
-retry_wait_time = 8  # WHY: Wait 8 seconds between retries
-timeout = 30         # WHY: 30 seconds per request before timeout
+max_concurrency = 6 # WHY: Parallel requests without overwhelming servers
+max_retries = 3     # WHY: Retry flaky connections before failing
+retry_wait_time = 8 # WHY: Wait 8 seconds between retries
+timeout = 30        # WHY: 30 seconds per request before timeout
 
 # WHY: Accept common status codes that don't indicate broken links
 # OBS: 403 and 429 reduce false positives
 accept = [
-  200,  # OK
-  206,  # Partial content
-  301,  # Moved permanently
-  302,  # Found (temporary redirect)
-  307,  # Temporary redirect
-  308,  # Permanent redirect
-  403,  # Forbidden (often false positive)
-  429,  # Too many requests (rate limiting)
-  503,  # Service unavailable (temporary)
+  200, # OK
+  206, # Partial content
+  301, # Moved permanently
+  302, # Found (temporary redirect)
+  307, # Temporary redirect
+  308, # Permanent redirect
+  403, # Forbidden (often false positive)
+  429, # Too many requests (rate limiting)
+  503, # Service unavailable (temporary)
 ]
 
 # WHY: Exclude patterns that shouldn't be checked
 exclude = [
-  "example\\.com",    # WHY: Exclude example domains in documentation
-  "localhost",        # WHY: Exclude local development URLs
-  "127\\.0\\.0\\.1",  # WHY: Exclude local loopback
-  "\\.local",         # WHY: Exclude local network domains
+  "example\\.com",   # WHY: Exclude example domains in documentation
+  "localhost",       # WHY: Exclude local development URLs
+  "127\\.0\\.0\\.1", # WHY: Exclude local loopback
+  "\\.local",        # WHY: Exclude local network domains
 ]