jekyll-theme-zer0 0.22.21 → 0.22.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aacda403198b850de5d92f7772711bb966a67f97cb631e5004c858c5b0e7abe
-  data.tar.gz: 1a650590947487377be84dc2c02fb56d18f443f4e60c470869393ffe013c10cf
+  metadata.gz: f5ef694da326e1ac7f10b1deed5494c749d5d28019158356306d07eec00b78dc
+  data.tar.gz: 84efeba1948bc0a9e6f87fae10b6581febcb91725cfd241fdfb7a2977276d8e5
 SHA512:
-  metadata.gz: c33bdf8c1943e8a52b35fc70290b4f895449b3fed491ff3869ffdd0b86d4989e89924eeb4bd0b590259badce91f2c89c32f3e353580b19de4660346bb095a544
-  data.tar.gz: 90bcf614157a4208fb86152fd3f403065a3f6bb906bf51151bbef8536ebb4e3d1093427768cf62c0027bf332bbc35333248f0fa5851b743bed51b5ada80b34cf
+  metadata.gz: 63221ca36a87bea421089ce50e7b9556b94e9a5e4fd4e75e80f2493b0e4d51f24378dfa25b50033bc0cfb5fd8577da7f90c072d625197b9228d756b757539916
+  data.tar.gz: 31c6b963de682056a37292e9467873bcae14803efea508432756fccd0176c0668c80e8045e7459d30ed5549ac97adc2a03d9f8bebc9d320423b7e2605482fe05

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [0.22.22] - 2026-04-21
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- 36cd015 feat(installer)!: modular installer + AI + deploy targets + test matrix (#76)
+- 555bead docs(readme): add AI-native branding and GitHub Actions automation section
+
+
+## [Unreleased — targeting 1.0.0]
+
+### ⚠️ Breaking changes (1.0.0 prep)
+
+- **Modular installer.** The 2,400-line monolithic `install.sh` is decomposed into a CLI dispatcher (`scripts/bin/install`) backed by focused library modules (`scripts/lib/install/*.sh`) and declarative YAML profiles (`templates/profiles/*.yml`). The legacy `curl | bash` one-liner still works — it bootstraps the same pipeline.
+- **Legacy mode flags deprecated.** `--full`, `--minimal`, `--fork`, `--remote`, `--github` continue to work in 1.0.x with a one-line deprecation warning. They map 1:1 to `install init --profile <name>`. Targeted removal: 2.0.
+- **`--azure` flag removed.** Replaced by `install deploy azure-swa`. Old flag emits a clear error pointing at the new command.
+- **Templates are the single source of truth.** Embedded heredoc fallbacks in `install.sh` are gone. A stripped distribution (theme tarball without `templates/`) will fail; the bootstrap downloads the templates tarball alongside `install.sh` for `curl | bash`.
+
+See [`docs/installation/migration-from-0.x.md`](docs/installation/migration-from-0.x.md) for the full flag-by-flag mapping.
+
+### Added (Phases 1-7 of the installer refactor)
+
+- **`scripts/bin/install`** — canonical CLI with subcommands: `init`, `wizard [--ai]`, `agents`, `deploy`, `doctor [--ai] [--quiet] [--json]`, `diagnose [--ai]`, `upgrade`, `list-profiles`, `list-targets`, `version`, `help`.
+- **`scripts/lib/install/`** — focused modules: `core`, `platform`, `template`, `fs`, `config`, `pages`, `profile`, `wizard_interactive`, `doctor`, `upgrade`, `agents`, `ai/{openai,wizard,diagnose,suggest}`, `deploy/{registry,github-pages,azure-swa,docker-prod}`. All bash 3.2 compatible.
+- **`templates/profiles/*.yml`** — declarative profile manifests (`full`, `minimal`, `fork`, `remote`, `github`).
+- **`templates/deploy/<target>/`** — pluggable deploy templates (workflow YAMLs, Dockerfile, nginx.conf).
+- **`templates/agents/`** — distributable AI agent guidance (CLAUDE.md, aider.conf.yml templates).
+- **`templates/ai/prompts/`** — system prompts for AI subcommands.
+- **`.zer0-installed` marker file** — tracks installed theme version for idempotent `install upgrade`.
+- **AI integration (opt-in, sandboxed):** `install wizard --ai` (OpenAI-backed `_config.yml` generation), `install diagnose --ai` (unified-diff patch proposals), `install deploy --ai-suggest` (deploy-target recommendation). Honors `ZER0_NO_AI=1` kill switch. All payloads sanitized; all writes diffed before confirmation.
+- **`install doctor`** — platform/tooling/site/AI health check with PASS/WARN/FAIL counters, `--quiet` and `--json` modes. Used as preflight in `install init` (opt out with `--skip-doctor`).
+- **`install upgrade`** — idempotent in-place upgrade tracked via `.zer0-installed`. `--from`, `--force`, `--dry-run`, `--auto-accept`. Refreshes agents and checks deploy-workflow drift.
+- **`docs/installation/`** — full doc tree: `index`, `architecture`, `profiles`, `deploy-targets`, `ai-features`, `migration-from-0.x`, `customization`.
+- **`.github/instructions/install.instructions.md`** — agent guidance for installer code (`applyTo: scripts/lib/install/**, scripts/bin/install, install.sh, templates/{profiles,deploy,agents,ai}/**`).
+- **`.github/workflows/doctor.yml`** — CI matrix (ubuntu-latest, macos-latest) running `install doctor --json` on every push/PR touching installer code.
+- **`.github/workflows/install-matrix.yml`** — full installer e2e matrix (ubuntu-latest + macos-latest × ruby 2.7/3.0/3.2) plus a `curl|bash` bootstrap smoke job. Runs on installer-touching PRs, weekly drift schedule, and `workflow_dispatch`.
+- **Installer e2e suites** under `test/`:
+  - `test_install_profiles.sh` — every profile produces its expected file tree
+  - `test_install_deploy.sh` — every deploy target writes valid workflow YAML / Dockerfile
+  - `test_install_ai_mock.sh` — `doctor --ai` and `diagnose` survive without `OPENAI_API_KEY`
+  - `test_install_legacy_flags.sh` — `install.sh --minimal` / `--full` still produce expected layouts
+  - `test_install_idempotency.sh` — re-running install is safe; `_config.yml` stays parseable; backup creep guarded
+- **`scripts/bin/test install`** — new test-suite group that executes all `test/test_install_*.sh` files.
+
+### Fixed
+
+- `install.sh` — `gh_args[@]: unbound variable` crash when invoking the github profile with no fork environment variables set (`set -u` + empty array). Guarded with `${gh_args[@]+"${gh_args[@]}"}`.
+
+### Changed
+
+- `README.md` Installation Methods section now references the modular CLI alongside the legacy one-liner.
+- `docs/FORKING.md` includes an `install init --profile fork` flow alongside the standalone `fork-cleanup.sh` script.
+- `AGENTS.md` instruction map adds the new install instructions row.
+
 ## [0.22.21] - 2026-04-19
 
 ### Changed

data/README.md

@@ -1,20 +1,26 @@
 ---
 title: zer0-mistakes
-sub-title: Jekyll Theme
-description: GitHub Pages compatible Jekyll theme with Bootstrap 5.3, featuring automated installation and comprehensive documentation.
-version: 0.22.21
+sub-title: AI-Native Jekyll Theme
+description: AI-native Jekyll theme for GitHub Pages — Docker-first development, AI-powered installation, multi-agent integration (Copilot, Codex, Cursor, Claude), AI preview-image generation, and AIEO content optimization with Bootstrap 5.3.
+version: 0.22.22
 layout: landing
 tags:
   - jekyll
   - docker
   - remote-theme
   - github-pages
+  - ai
+  - ai-automation
+  - ai-integration
+  - copilot
+  - aieo
 categories:
   - jekyll-theme
   - docker
   - bootstrap
+  - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-04-19T17:07:38.000Z
+lastmod: 2026-04-21T04:05:24.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -23,13 +29,19 @@ keywords:
   - docker
   - remote-theme
   - github-pages
+  - ai-native jekyll theme
+  - ai-powered installation
+  - github copilot integration
+  - cursor agent
+  - aieo optimization
+  - ai preview image generation
 date: 2026-03-29T12:00:00.000Z
-snippet: GitHub Pages compatible Jekyll theme with Bootstrap 5
+snippet: AI-native Jekyll theme — automated, agent-friendly, AIEO-optimized
 comments: true
 mermaid: true
 preview: /assets/images/wizard-on-journey.png
 hero_image: /assets/images/wizard-on-journey.png
-excerpt: "Professional Jekyll theme for GitHub Pages with Bootstrap 5.3, automated installation, and 43 documented features"
+excerpt: "AI-native Jekyll theme for GitHub Pages — multi-agent ready (Copilot, Codex, Cursor, Claude), AI-powered install & preview images, AIEO-optimized, with Docker-first development and 43 documented features"
 ---
 
 [![pages-build-deployment](https://github.com/bamr87/zer0-mistakes/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/bamr87/zer0-mistakes/actions/workflows/pages/pages-build-deployment)
@@ -38,14 +50,18 @@ excerpt: "Professional Jekyll theme for GitHub Pages with Bootstrap 5.3, automat
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://github.com/bamr87/zer0-mistakes/blob/main/docker-compose.yml)
 [![Bootstrap](https://img.shields.io/badge/Bootstrap-5.3.3-purple.svg)](https://getbootstrap.com/)
+[![AI-Native](https://img.shields.io/badge/AI--Native-Copilot%20%7C%20Codex%20%7C%20Cursor%20%7C%20Claude-8A2BE2)](AGENTS.md)
+[![AIEO](https://img.shields.io/badge/AIEO-Optimized-ff69b4)](#-aieo-optimized--built-for-ai-citation)
 
 # 🚀 zer0-mistakes
 
-### GitHub Pages & Bootstrap 5 Ready
+### The AI-Native Jekyll Theme for GitHub Pages
 
-**GitHub Pages compatible • Bootstrap 5.3 • Privacy-compliant • Zero-configuration**
+**AI-augmented • Agent-ready • Docker-first • Bootstrap 5.3 • Privacy-compliant • Zero-configuration**
 
-[Quick Start](#-quick-start) • [Features](#-key-features) • [Documentation](#-documentation) • [Contributing](CONTRIBUTING.md)
+Built from the ground up to **automate, facilitate, and integrate** with modern AI workflows — from one-line self-healing install to multi-agent code guidance ([Copilot](https://github.com/features/copilot), [Codex](https://openai.com/codex), [Cursor](https://cursor.com/), [Claude Code](https://www.claude.com/product/claude-code), [Aider](https://aider.chat/)) to AI-generated preview images and AIEO content optimization for AI citation.
+
+[Quick Start](#-quick-start) • [AI Workflow](#-ai-native-workflow) • [Features](#-key-features) • [Documentation](#-documentation) • [Contributing](CONTRIBUTING.md)
 
 ---
 
@@ -53,6 +69,7 @@ excerpt: "Professional Jekyll theme for GitHub Pages with Bootstrap 5.3, automat
 
 - [Overview](#overview)
 - [Quick Start](#-quick-start)
+- [AI-Native Workflow](#-ai-native-workflow)
 - [Architecture](#-architecture)
 - [Key Features](#-key-features)
 - [Installation Methods](#-installation-methods)
@@ -72,7 +89,15 @@ excerpt: "Professional Jekyll theme for GitHub Pages with Bootstrap 5.3, automat
 
 ## Overview
 
-**zer0-mistakes** is a professional Jekyll theme engineered to eliminate setup friction and provide a seamless development experience. With Docker containerization, 43 documented features, and comprehensive automation, you can go from zero to deployed in under 5 minutes.
+**zer0-mistakes** is an **AI-native** Jekyll theme engineered to eliminate setup friction and accelerate every stage of the content lifecycle with AI automation, facilitation, and integration. Docker containerization, multi-agent guidance files, AI-powered tooling, and 43 documented features take you from zero to deployed — and zero to AI-collaborative — in under 5 minutes.
+
+**AI is a first-class citizen, not an afterthought:**
+
+- 🤖 **AI-powered installation** — `install.sh` self-heals across macOS / Linux / Windows (WSL) with ~95% success rate
+- 🧠 **Multi-agent integration** — Drop-in [`AGENTS.md`](AGENTS.md) + `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` + `.github/prompts/*.prompt.md` + `.cursor/commands/` work with Copilot, Codex, Cursor, Claude Code, Aider, Jules, Continue
+- 🎨 **AI preview-image generation** — Jekyll plugin + script generate OpenAI/DALL·E images for posts missing previews ([`_plugins/preview_image_generator.rb`](_plugins/preview_image_generator.rb))
+- 🤝 **AI-facilitated releases** — Conventional-commit analyzer auto-determines semantic version bumps and writes the changelog ([`scripts/analyze-commits.sh`](scripts/analyze-commits.sh))
+- 🔍 **AIEO-optimized output** — Structured data, entity density, FAQ schema, and definitional precision so AI engines cite your site accurately
 
 ```mermaid
 graph LR
@@ -106,6 +131,10 @@ graph LR
 | **Platform Support** | Limited | **Universal** ([macOS, Linux, Windows/WSL via Docker](https://github.com/bamr87/zer0-mistakes/blob/main/docker-compose.yml)) |
 | **Error Handling** | Manual debugging | **Automated** |
 | **Dependencies** | Ruby + Bundler + Jekyll | **Docker only** |
+| **AI Agent Integration** | None / DIY | **Built-in** ([`AGENTS.md`](AGENTS.md) + Copilot / Codex / Cursor / Claude / Aider guidance) |
+| **AI Content Tooling** | None | **First-class** (AI preview images, AIEO schema, prompt library) |
+| **Release Automation** | Manual versioning | **AI-facilitated** ([commit-analyzer](scripts/analyze-commits.sh) → semantic bump + changelog) |
+| **AI Discoverability** | None | **AIEO-optimized** ([structured data, FAQ schema, entity density](#-aieo-optimized--built-for-ai-citation)) |
 
 ---
 
@@ -152,6 +181,89 @@ sequenceDiagram
 
 ---
 
+## 🤖 AI-Native Workflow
+
+zer0-mistakes treats AI as core infrastructure across **install → author → build → release → discover**. Every layer is wired for **automation, facilitation, and integration** with the AI tools you already use.
+
+```mermaid
+flowchart LR
+    subgraph Install["🤖 AI Install"]
+        I1[install.sh<br/>self-healing]
+    end
+    subgraph Author["🧠 AI Authoring"]
+        A1[Copilot]
+        A2[Codex]
+        A3[Cursor]
+        A4[Claude Code]
+        A5[Aider]
+    end
+    subgraph Build["🎨 AI Content"]
+        B1[OpenAI<br/>Preview Images]
+        B2[AI Frontmatter<br/>Maintainer prompt]
+    end
+    subgraph Release["🚀 AI Release"]
+        R1[Commit Analyzer]
+        R2[Auto Changelog]
+        R3[Semantic Bump]
+    end
+    subgraph Discover["🔍 AIEO Discovery"]
+        D1[JSON-LD Schema]
+        D2[FAQ + Glossary]
+        D3[Entity Density]
+    end
+
+    Install --> Author --> Build --> Release --> Discover
+
+    style Install fill:#e3f2fd
+    style Author fill:#f3e5f5
+    style Build fill:#fff3e0
+    style Release fill:#e8f5e9
+    style Discover fill:#fce4ec
+```
+
+### What's wired for AI
+
+| Capability | What it does | Where it lives |
+|---|---|---|
+| **Self-healing install** | Detects platform, fixes Docker/Jekyll issues, retries with fallbacks | [`install.sh`](install.sh) |
+| **Cross-tool agent guide** | Single entry point for any [agents.md](https://agents.md/)-aware AI tool | [`AGENTS.md`](AGENTS.md) |
+| **Copilot project context** | Architecture, conventions, commands, release flow | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) |
+| **File-scoped instructions** | `applyTo:` globs auto-load guidance for `_layouts/`, `_includes/`, `scripts/`, `test/`, `docs/`, version files | [`.github/instructions/`](.github/instructions/) |
+| **Reusable agent prompts** | `commit-publish`, `frontmatter-maintainer`, `seed` (full-rebuild blueprint) | [`.github/prompts/`](.github/prompts/) |
+| **Cursor slash-commands** | Mirrors prompts as `/commit-publish`, `/frontend-run-improve` | [`.cursor/commands/`](.cursor/commands/) |
+| **AI preview images** | Jekyll plugin + script generate OpenAI/DALL·E images for posts missing previews | [`_plugins/preview_image_generator.rb`](_plugins/preview_image_generator.rb), [`scripts/generate-preview-images.sh`](scripts/generate-preview-images.sh) |
+| **AI release pipeline** | Conventional-commit analyzer chooses MAJOR/MINOR/PATCH, writes CHANGELOG, tags & publishes | [`scripts/analyze-commits.sh`](scripts/analyze-commits.sh), [`scripts/bin/release`](scripts/bin/release) |
+| **AIEO content layer** | `SoftwareApplication`, `WebPage`, `FAQPage`, `Person` JSON-LD; glossary; FAQ; dated roadmap | [See AIEO section](#-aieo-optimized--built-for-ai-citation) |
+
+### Quick AI tasks
+
+```bash
+# Generate AI preview images for posts missing previews (needs OPENAI_API_KEY)
+./scripts/generate-preview-images.sh --collection posts
+
+# Preview before generating (no API calls)
+./scripts/generate-preview-images.sh --dry-run --verbose
+
+# Let AI analyze commits and propose the next version bump
+./scripts/analyze-commits.sh HEAD~10..HEAD
+
+# Run the AI-facilitated release pipeline (validate → version → changelog → publish)
+./scripts/bin/release patch --dry-run
+```
+
+### Drop-in for any AI editor
+
+Clone the repo (or fork) and your editor's AI agent will pick up project context automatically:
+
+- **GitHub Copilot / VS Code** → reads [`.github/copilot-instructions.md`](.github/copilot-instructions.md) + `.github/instructions/*.instructions.md`
+- **Cursor** → reads `.cursor/commands/` for slash-commands; falls back to `AGENTS.md`
+- **Claude Code / Codex / Aider / Jules / Continue** → read [`AGENTS.md`](AGENTS.md) per the [agents.md](https://agents.md/) convention
+- **Custom agents** → Load layered guidance from [`.github/`](.github/) on demand
+
+> No configuration required. The guidance is layered — agents read only what's needed for the file they're touching.
+
+---
+
 ## 🏗 Architecture
 
 ### System Overview
@@ -209,10 +321,11 @@ flowchart TB
 
 ```mermaid
 pie title Technology Distribution
-    "Jekyll (Static Gen)" : 30
-    "Bootstrap 5.3 (UI)" : 25
-    "Docker (Dev Env)" : 20
-    "Liquid (Templates)" : 15
+    "Jekyll (Static Gen)" : 25
+    "Bootstrap 5.3 (UI)" : 20
+    "Docker (Dev Env)" : 18
+    "AI Tooling & Agents" : 15
+    "Liquid (Templates)" : 12
     "PostHog (Analytics)" : 10
 ```
 
@@ -223,6 +336,10 @@ pie title Technology Distribution
 | **Icons** | Bootstrap Icons | Unified iconography |
 | **Development** | Docker | Cross-platform consistency |
 | **Templates** | Liquid | Dynamic content rendering |
+| **AI Agents** | Copilot · Codex · Cursor · Claude Code · Aider · Jules · Continue | Multi-tool agentic development via [`AGENTS.md`](AGENTS.md) + `.github/instructions/` |
+| **AI Content** | OpenAI Images API | AI-generated preview images via [`_plugins/preview_image_generator.rb`](_plugins/preview_image_generator.rb) |
+| **AI Automation** | Conventional-commit analyzer | Auto semantic versioning + changelog ([`scripts/analyze-commits.sh`](scripts/analyze-commits.sh)) |
+| **AIEO** | JSON-LD + FAQ + Glossary schema | Optimized for AI citation and retrieval |
 | **Analytics** | PostHog | Privacy-first tracking |
 | **Diagrams** | Mermaid 10+ | Documentation visuals |
 | **Navigation** | ES6 Modules | Modular JavaScript architecture |
@@ -387,12 +504,27 @@ Built-in GDPR/CCPA compliant documentation:
 
 ## 📦 Installation Methods
 
+> **New in 1.0:** the installer is now a modular CLI (`scripts/bin/install`) with subcommands and declarative profiles. The classic `curl | bash` one-liner still works — it bootstraps the same pipeline. See [docs/installation/](docs/installation/index.md) for the full guide and [docs/installation/migration-from-0.x.md](docs/installation/migration-from-0.x.md) for the 0.x → 1.0 flag mapping.
+
 ### Method 1: AI-Powered Install (Recommended)
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
 ```
 
+### Method 1b: Modular CLI (Local Clone)
+
+```bash
+git clone https://github.com/bamr87/zer0-mistakes.git
+./zer0-mistakes/scripts/bin/install help
+./zer0-mistakes/scripts/bin/install init --profile full /path/to/new-site
+./zer0-mistakes/scripts/bin/install deploy github-pages,docker-prod /path/to/new-site
+./zer0-mistakes/scripts/bin/install doctor /path/to/new-site     # health check
+./zer0-mistakes/scripts/bin/install agents /path/to/new-site --all   # AI agent guidance
+```
+
+Available subcommands: `init`, `wizard [--ai]`, `agents`, `deploy`, `doctor`, `diagnose [--ai]`, `upgrade`, `list-profiles`, `list-targets`, `version`, `help`.
+
 ### Method 2: Remote Theme (GitHub Pages)
 
 ```yaml
@@ -706,6 +838,137 @@ bash scripts/release major  # 0.21.5 → 1.0.0
 
 ---
 
+## ⚙️ GitHub Actions Automation
+
+zer0-mistakes ships with a **complete CI/CD and automation suite** powered by [GitHub Actions](https://github.com/bamr87/zer0-mistakes/actions). Every workflow is opinionated, tested, and ready to fork — push to `main` and the entire pipeline (test → version → publish → release) runs automatically.
+
+### Workflow Catalogue
+
+All workflows live under [`.github/workflows/`](.github/workflows/).
+
+| # | Workflow | File | Trigger | Purpose |
+|---|----------|------|---------|---------|
+| 1 | **Comprehensive CI Pipeline** | [`ci.yml`](.github/workflows/ci.yml) | push / PR / dispatch | Detect changes → fast checks → quality control → matrix test suite (Ruby 3.3) → integration tests → build & validate |
+| 2 | **TEST (Latest Dependencies)** | [`test-latest.yml`](.github/workflows/test-latest.yml) | scheduled / dispatch | Zero-pin Docker build with bleeding-edge gems; promotes only passing images |
+| 3 | **Update Dependencies** | [`update-dependencies.yml`](.github/workflows/update-dependencies.yml) | weekly schedule | Refreshes `Gemfile.lock` to latest compatible versions and opens an automated PR |
+| 4 | **CodeQL Security Scanning** | [`codeql.yml`](.github/workflows/codeql.yml) | push / PR on code paths | Static security analysis across Ruby, JavaScript, TypeScript, Python, YAML, plugins, scripts |
+| 5 | **Version Bump** | [`version-bump.yml`](.github/workflows/version-bump.yml) | push to main / dispatch | Analyzes conventional commits, determines MAJOR/MINOR/PATCH bump, updates `version.rb` + CHANGELOG, creates tag |
+| 6 | **Release (Gem + GitHub)** | [`release.yml`](.github/workflows/release.yml) | tag `v*` / dispatch | Pre-release validation → build assets → publish to [RubyGems](https://rubygems.org/gems/jekyll-theme-zer0) → create GitHub Release |
+| 7 | **Convert Jupyter Notebooks** | [`convert-notebooks.yml`](.github/workflows/convert-notebooks.yml) | push to `pages/_notebooks/**.ipynb` | Auto-converts `.ipynb` → Jekyll-friendly Markdown with extracted images |
+| 8 | **Roadmap Sync** | [`roadmap-sync.yml`](.github/workflows/roadmap-sync.yml) | push affecting `_data/roadmap.yml` | Regenerates the README roadmap section from data; fails PRs with stale README |
+| 9 | **New Site Setup** | [`setup-template.yml`](.github/workflows/setup-template.yml) | first push after template/fork | Creates a PR with prefilled `_config.yml` so a new site is ready to merge & go |
+
+> 💡 GitHub Pages adds an additional managed `pages-build-deployment` run on every push to `main`.
+
+### Pipeline Topology
+
+```mermaid
+flowchart LR
+    subgraph Devloop["🧑‍💻 Developer Loop"]
+        PR[Pull Request]
+        PUSH[Push to main]
+    end
+
+    subgraph Continuous["🧪 Continuous Integration"]
+        CI[ci.yml<br/>Comprehensive CI]
+        CODEQL[codeql.yml<br/>Security Scan]
+        TESTLATEST[test-latest.yml<br/>Latest Deps]
+    end
+
+    subgraph Maintenance["🔧 Maintenance"]
+        DEPS[update-dependencies.yml<br/>Weekly Bump]
+        ROADMAP[roadmap-sync.yml<br/>README Sync]
+        NOTEBOOKS[convert-notebooks.yml<br/>.ipynb → .md]
+    end
+
+    subgraph Releaseflow["🚀 Release Pipeline"]
+        BUMP[version-bump.yml<br/>Semantic Bump]
+        RELEASE[release.yml<br/>Gem + GitHub Release]
+        PAGES[pages-build-deployment<br/>GitHub Pages]
+    end
+
+    subgraph Bootstrap["🌱 Bootstrap"]
+        SETUP[setup-template.yml<br/>New Site Setup]
+    end
+
+    PR --> CI
+    PR --> CODEQL
+    PUSH --> CI
+    PUSH --> CODEQL
+    PUSH --> ROADMAP
+    PUSH --> NOTEBOOKS
+    PUSH --> BUMP
+    BUMP -->|tag v*| RELEASE
+    PUSH --> PAGES
+    DEPS -.->|opens PR| PR
+    SETUP -.->|first push| PR
+
+    style Continuous fill:#e3f2fd
+    style Maintenance fill:#fff3e0
+    style Releaseflow fill:#e8f5e9
+    style Bootstrap fill:#f3e5f5
+```
+
+### What it looks like
+
+#### 🗂 Actions overview — every workflow at a glance
+
+![All workflows view in the GitHub Actions tab showing recent runs of Release, pages-build-deployment, TEST, CodeQL, New Site Setup, Comprehensive CI, Version Bump, and Roadmap Sync](docs/images/workflows/actions-overview.png)
+
+The Actions tab gives you a real-time activity feed — every push to `main` triggers a coordinated set of workflows that you can audit, re-run, or dispatch manually.
+
+#### 🚀 Release pipeline — automated gem + GitHub release
+
+![Successful Release (Gem + GitHub) #49 run showing the four-stage pipeline: Pre-release Validation → Build Release Assets → Publish to RubyGems → Create GitHub Release, completed in 1m 40s with one artifact](docs/images/workflows/release-run-detail.png)
+
+A single tag (`v0.22.21`) — or one click on **Run workflow** — runs the entire publish pipeline in under two minutes. The job graph makes the dependency chain visible: validate → build → publish to [RubyGems](https://rubygems.org/gems/jekyll-theme-zer0) → cut the [GitHub Release](https://github.com/bamr87/zer0-mistakes/releases). No manual `gem push`, no manual changelog edit, no missed step.
+
+#### 🧪 Comprehensive CI — parallel quality gates
+
+![Comprehensive CI Pipeline run showing the workflow graph with parallel jobs: Detect Changes, Fast Checks, Quality Control, matrix Test Suite (Ruby 3.3), Integration Tests, and Build & Validate, with annotations panel underneath](docs/images/workflows/ci-run-detail.png)
+
+CI fans out across **change detection → fast checks → quality control → matrix test suite → integration tests → build & validate**, with annotations surfacing test failures and deprecations directly in the run summary.
+
+#### 🚦 Per-workflow run history
+
+![Comprehensive CI Pipeline workflow run history with branch filters, status indicators, and individual run timings](docs/images/workflows/ci-pipeline.png)
+
+Each workflow has its own run history with branch filters, status badges, and per-job durations — easy to spot regressions or compare runs across branches.
+
+### Trigger guide
+
+Use these to invoke automation without leaving your terminal:
+
+```bash
+# List recent workflow runs
+gh run list --repo bamr87/zer0-mistakes --limit 10
+
+# Manually dispatch a release
+gh workflow run release.yml --ref main -f tag=v0.22.21
+
+# Trigger an automatic version bump on demand
+gh workflow run version-bump.yml --ref main
+
+# Re-run the most recent failed CI run
+gh run rerun --failed --repo bamr87/zer0-mistakes
+
+# Watch a workflow run live
+gh run watch --repo bamr87/zer0-mistakes
+```
+
+### Forking these workflows
+
+When you fork the theme as a starter, the workflows come with you. To make them safe and useful in your fork:
+
+1. **Add `RUBYGEMS_API_KEY`** in `Settings → Secrets and variables → Actions` if you plan to publish your own gem; otherwise disable [`release.yml`](.github/workflows/release.yml).
+2. **Tune triggers** in [`update-dependencies.yml`](.github/workflows/update-dependencies.yml) (default: weekly).
+3. **Disable** [`setup-template.yml`](.github/workflows/setup-template.yml) after the first run — it's a one-shot bootstrap.
+4. **GitHub Pages** is auto-enabled when you push to `main` if your repo is `<username>.github.io`.
+
+> 📸 Screenshots above are real runs captured from [github.com/bamr87/zer0-mistakes/actions](https://github.com/bamr87/zer0-mistakes/actions). Re-capture them for your fork by running `./scripts/test/capture-workflow-screenshots.sh` (or just take fresh screenshots) and replacing the files in [`docs/images/workflows/`](docs/images/workflows/).
+
+---
+
 ## 🗺 Roadmap
 
 The diagram and table below are auto-generated from [`_data/roadmap.yml`](_data/roadmap.yml) by [`scripts/generate-roadmap.sh`](scripts/generate-roadmap.sh). See the full [Roadmap page](/roadmap/) for per-version detail and the [PRD](docs/PRD.md) for product context.
@@ -803,7 +1066,7 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 0.22.21 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 0.22.22 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
 | **Documented Features** | 43 ([Feature Registry](https://github.com/bamr87/zer0-mistakes/blob/main/_data/features.yml)) |
 | **Setup Time** | 2-5 minutes ([install.sh benchmarks](https://github.com/bamr87/zer0-mistakes/blob/main/install.sh)) |
 | **Documentation Pages** | 70+ ([browse docs](/pages/)) |
@@ -835,17 +1098,25 @@ All AIEO enhancements are backward-compatible, follow existing code style (Boots
 
 Built with these amazing technologies:
 
-- [Jekyll](https://jekyllrb.com/) - Static site generation
-- [Bootstrap](https://getbootstrap.com/) - UI framework
-- [Docker](https://docker.com/) - Containerization
-- [PostHog](https://posthog.com/) - Privacy-first analytics
-- [Mermaid](https://mermaid.js.org/) - Diagram rendering
-- [GitHub Copilot](https://github.com/features/copilot) - AI assistance
+- [Jekyll](https://jekyllrb.com/) — Static site generation
+- [Bootstrap](https://getbootstrap.com/) — UI framework
+- [Docker](https://docker.com/) — Containerization
+- [PostHog](https://posthog.com/) — Privacy-first analytics
+- [Mermaid](https://mermaid.js.org/) — Diagram rendering
+
+And these AI partners that make zer0-mistakes truly AI-native:
+
+- [GitHub Copilot](https://github.com/features/copilot) — Project-wide instructions & file-scoped guidance
+- [OpenAI Codex](https://openai.com/codex) — Cross-tool agent integration via `AGENTS.md`
+- [Cursor](https://cursor.com/) — Slash-command workflows in `.cursor/commands/`
+- [Claude Code](https://www.claude.com/product/claude-code) — Anthropic agent compatibility
+- [Aider](https://aider.chat/), [Continue](https://continue.dev/), [Jules](https://jules.google/) — Additional [agents.md](https://agents.md/)-aware tools
+- [OpenAI Images API](https://platform.openai.com/docs/guides/images) — AI-generated preview images
 
 ---
 
-**Built with ❤️ for the Jekyll community**
+**Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
 
-**v0.22.21** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md)
+**v0.22.22** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)