Rework portfolio around current projects and technical writing

.github/workflows/deploy-mkdocs.yml

@@ -13,6 +13,7 @@ permissions:
   contents: write
   pages: write
   id-token: write
+  pull-requests: write
 
 concurrency:
   group: "pages"
@@ -49,9 +50,14 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v4
 
+      - name: Validate and generate portfolio pages
+        run: |
+          python scripts/validate_projects.py
+          python scripts/generate_portfolio.py
+
       - name: Build with MkDocs
         run: |
-          mkdocs build --clean
+          mkdocs build --clean --strict
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
@@ -77,6 +83,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -89,6 +97,11 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
 
+      - name: Validate and generate portfolio pages
+        run: |
+          python scripts/validate_projects.py
+          python scripts/generate_portfolio.py
+
       - name: Build preview
         run: |
           mkdocs build --clean --strict

README.md

@@ -21,9 +21,13 @@ This repository uses [MkDocs](https://www.mkdocs.org/) with the [Material theme]
 
 ### Building the Site
 
-To build the static site:
+Validate the project registry and generate portfolio pages, then build:
+
 ```bash
-mkdocs build
+pip install -r requirements.txt
+python scripts/validate_projects.py
+python scripts/generate_portfolio.py
+mkdocs build --strict
 ```
 
 The generated site will be in the `site/` directory.

data/projects.yaml

@@ -0,0 +1,313 @@
+# Canonical project registry for sempervent.github.io
+# Edit this file; run `python scripts/generate_portfolio.py` before `mkdocs build`.
+
+schema_version: 1
+
+projects:
+  - slug: parqonaut
+    name: PARQONAUT
+    summary: >-
+      Rust workspace built around `prqnt`: scan and repair Parquet on disk or
+      S3-compatible storage, plus an HTTP API for async scan jobs.
+    status: active
+    category: engineering
+    repo: https://github.com/sempervent/PARQONAUT
+    docs: https://sempervent.github.io/PARQONAUT/
+    image: assets/projects/parqonaut-mascot.png
+    image_alt: PARQONAUT mascot illustration
+    featured: true
+    current: true
+    language: Rust
+
+  - slug: dots
+    name: dots
+    summary: >-
+      Dotfiles and a `./dots` bootstrap for macOS and Linux — shared `shell/`
+      helpers with bash and zsh profiles.
+    status: active
+    category: infrastructure
+    repo: https://github.com/sempervent/dots
+    docs: https://sempervent.github.io/dots/
+    featured: true
+    current: true
+    language: Shell
+
+  - slug: numbrane
+    name: NUMBRANE
+    summary: >-
+      Generative audiovisual work from procedural rules and simulation. No LLM
+      weights in the runtime; NUMBRANE Studio is the canvas-first UI.
+    status: active
+    category: creative
+    repo: https://github.com/sempervent/numbrane
+    featured: true
+    current: true
+    language: Python
+
+  - slug: paraclete
+    name: Paraclete
+    summary: >-
+      Parquet exploration CLI; upstream of much of what became PARQONAUT.
+    status: maintained
+    category: engineering
+    repo: https://github.com/sempervent/paraclete
+    featured: false
+    current: false
+    language: Rust
+
+  - slug: cosmic-architect
+    name: Cosmic Architect
+    summary: >-
+      Browser game about building planets; follows earlier pygame prototypes.
+    status: experimental
+    category: games
+    repo: https://github.com/sempervent/cosmic-architect
+    featured: false
+    current: false
+    language: Python
+
+  - slug: music-rig
+    name: music-rig
+    summary: >-
+      Home studio notes — patch routing, interfaces, MIDI, monitoring.
+    status: maintained
+    category: creative
+    repo: https://github.com/sempervent/music-rig
+    docs: https://sempervent.github.io/music-rig/
+    featured: false
+    current: false
+    language: Markdown
+
+  - slug: blacklake-python
+    name: Blacklake (Python)
+    summary: >-
+      Git-like dataset versioning on S3 with JSON-LD metadata, SHACL validation,
+      and Solr search.
+    status: maintained
+    category: engineering
+    repo: https://github.com/sempervent/blacklake
+    docs: https://sempervent.github.io/blacklake/
+    featured: true
+    current: false
+    language: Python
+
+  - slug: s3-rust-data-portal
+    name: Blacklake (Rust data portal)
+    summary: >-
+      Axum service and CLI in repo `s3-rust-data-portal` for versioned ML
+      artifacts on S3 and Postgres JSONB search. Same name as the Python project,
+      different codebase.
+    status: maintained
+    category: engineering
+    repo: https://github.com/sempervent/s3-rust-data-portal
+    docs: https://sempervent.github.io/s3-rust-data-portal/
+    featured: false
+    current: false
+    language: Rust
+
+  - slug: wildfire-smoke-risk
+    name: Wildfire Smoke Risk Correlator
+    summary: >-
+      Geospatial layers linking wildfire smoke exposure to health-risk indicators.
+    status: experimental
+    category: engineering
+    repo: https://github.com/sempervent/wildfire-smoke-risk-correlator
+    docs: https://sempervent.github.io/wildfire-smoke-risk-correlator/
+    featured: false
+    current: false
+    language: Python
+
+  - slug: postgres-query-autopsy
+    name: Postgres Query Autopsy Tool
+    summary: >-
+      .NET CLI for PostgreSQL plan and workload inspection beyond a bare
+      `EXPLAIN`.
+    status: experimental
+    category: engineering
+    repo: https://github.com/sempervent/postgres-query-autopsy-tool
+    docs: https://sempervent.github.io/postgres-query-autopsy-tool/
+    featured: false
+    current: false
+    language: C#
+
+  - slug: gi
+    name: gi
+    summary: >-
+      Merges `.gitignore` fragments for polyglot repos.
+    status: maintained
+    category: engineering
+    repo: https://github.com/sempervent/gi
+    docs: https://sempervent.github.io/gi/
+    featured: false
+    current: false
+    language: Go
+
+  - slug: agent-llm-wiki-matrix
+    name: Agent LLM Wiki Matrix
+    summary: >-
+      MkDocs notes comparing agentic coding tools and repo-local measurements.
+    status: experimental
+    category: documentation
+    repo: https://github.com/sempervent/agent-llm-wiki-matrix
+    docs: https://sempervent.github.io/agent-llm-wiki-matrix/
+    featured: false
+    current: false
+    language: Markdown
+
+  - slug: smart-farm-wiki
+    name: Smart Farm Wiki
+    summary: >-
+      Homelab and sensor automation wiki.
+    status: experimental
+    category: documentation
+    repo: https://github.com/sempervent/smart-farm-wiki
+    docs: https://sempervent.github.io/smart-farm-wiki/
+    featured: false
+    current: false
+    language: Markdown
+
+  - slug: llm-wiki-template
+    name: LLM Wiki Template
+    summary: >-
+      MkDocs starter for team wikis and agent playbooks.
+    status: maintained
+    category: documentation
+    repo: https://github.com/sempervent/llm-wiki-template
+    docs: https://sempervent.github.io/llm-wiki-template/
+    featured: false
+    current: false
+    language: Markdown
+
+  - slug: generative-midi-workbench
+    name: Generative MIDI Workbench
+    summary: >-
+      Algorithmic MIDI experiments — chord tools and performance hooks.
+    status: experimental
+    category: creative
+    repo: https://github.com/sempervent/generative-midi-workbench
+    docs: https://sempervent.github.io/generative-midi-workbench/
+    featured: false
+    current: false
+    language: Python
+
+  - slug: mqtt-comparison
+    name: MQTT Comparison
+    summary: >-
+      Notes from comparing MQTT brokers; org Pages URL was 404 when last checked.
+    status: experimental
+    category: engineering
+    repo: https://github.com/sempervent/mqtt-comparison
+    featured: false
+    current: false
+    language: Python
+
+  - slug: cockpit
+    name: cockpit
+    summary: >-
+      Go TUI for tmux sessions, SSH hosts, and local homelab tools.
+    status: experimental
+    category: infrastructure
+    repo: https://github.com/sempervent/cockpit
+    featured: false
+    current: false
+    language: Go
+
+  - slug: parqknife
+    name: parqknife
+    summary: >-
+      Older Parquet CLI; folded into PARQONAUT.
+    status: historical
+    category: engineering
+    repo: https://github.com/sempervent/parqknife
+    featured: false
+    current: false
+    language: Rust
+
+  - slug: opensampl
+    name: OpenSAMPL
+    summary: >-
+      ORNL clock-probe aggregation and timing analysis (`ORNL/OpenSAMPL`).
+    status: maintained
+    category: engineering
+    repo: https://github.com/ORNL/OpenSAMPL
+    docs: https://ornl.github.io/OpenSAMPL/
+    featured: false
+    current: false
+    language: Python
+
+  - slug: whereivebeen
+    name: Where I've Been
+    summary: >-
+      Flask/Vue map of US counties visited.
+    status: historical
+    category: engineering
+    repo: https://github.com/sempervent/whereivebeen
+    featured: false
+    current: false
+    language: Python
+
+  - slug: thisisacasino
+    name: This Is A Casino
+    summary: >-
+      2023 stack for semantic features and ML over market data.
+    status: historical
+    category: engineering
+    repo: https://github.com/sempervent/thisisacasino
+    featured: false
+    current: false
+    language: Python
+
+  - slug: dcrs
+    name: Decentralized Content Reward System (DCRS)
+    summary: >-
+      Web3-style content rewards prototype (Flask plus early chain experiments).
+    status: historical
+    category: engineering
+    repo: https://github.com/sempervent/dcrs
+    featured: false
+    current: false
+    language: Python
+
+  - slug: genesis-game
+    name: Genesis
+    summary: >-
+      pygame sketch driven by microphone input.
+    status: historical
+    category: games
+    repo: https://github.com/sempervent/genesis
+    featured: false
+    current: false
+    language: Python
+
+  - slug: colony
+    name: colony
+    summary: >-
+      Rust colony simulation; org GitHub Pages URL was 404 when last checked.
+    status: historical
+    category: games
+    repo: https://github.com/sempervent/colony
+    featured: false
+    current: false
+    language: Rust
+
+  - slug: embers-of-the-earth
+    name: Embers of the Earth
+    summary: >-
+      Pixel-farming game design in a steampunk setting.
+    status: experimental
+    category: games
+    repo: https://github.com/sempervent/embers-of-the-earth
+    featured: false
+    current: false
+    language: Unknown
+
+  - slug: cosmic-garden
+    name: Cosmic Garden
+    summary: >-
+      Cultivation game experiment related to Cosmic Architect.
+    status: experimental
+    category: games
+    repo: https://github.com/sempervent/cosmic-garden
+    featured: false
+    current: false
+    language: Unknown