jekyll-theme-zer0 1.9.9 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86cb3c511931220626d99a0337f07a6b164ee1711f00ade31ee39dd5f35eeb33
-  data.tar.gz: 845e2f28937fe45bbe613162d94296c36dfd03dbe309922a401c280a5465ada2
+  metadata.gz: 7e3dadf187dfaae9c1186aa1e0864f19ca74e9564cee0b0fa3136657fda6cf03
+  data.tar.gz: '024782a85ed83017188dac310e4aa75ed22f41d604576758f4f7f49564cba984'
 SHA512:
-  metadata.gz: 3f2b1e8ff7072e48393e5b609aab4626e23d41d173462c686e84a5f528cfff35eafd7d9e9546ff29e644be66408c694b0acba3fe501c884217a55c7621a9e291
-  data.tar.gz: a56899f63265999ccbee428e44348cabed30a038ff6bbb6dc12cb8826d9c145dd827658bc24aa1f06b8960ce6753ef2d1a98db27e447acabff038393f769bf98
+  metadata.gz: 692271e54f6065325496b8bcfc9956194e085bd07d7a53f3c9adc108b146e846f712d126e5794b52cdbd1cad75e4dbfa91260767820fee2903894472b76af7a7
+  data.tar.gz: f0dd37b5871364845af1f663f41f59910f5e9e4ed2d5a6c3033fe56433f9f5006d8e99bcd3054c1f4352b542d9857232082c1a219d15a7cb5f1a1defedc72ecc

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.10.0] - 2026-06-01
+
+### Changed
+- Version bump: minor release
+
+### Commits in this release
+- 309202f2 feat(roadmap): add --validate mode, catch-up milestones v1.0–1.9, README accuracy fixes (#113)
+
+
+## [1.9.10] - 2026-05-31
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- ef6a3f39 fix: update copyright year range in LICENSE file
+
+
 ## [1.9.9] - 2026-05-31
 
 ### Changed

data/LICENSE

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

data/README.md

@@ -2,7 +2,7 @@
 title: zer0-mistakes
 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: 1.9.9
+version: 1.10.0
 layout: landing
 tags:
   - jekyll
@@ -20,7 +20,7 @@ categories:
   - bootstrap
   - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-05-31T22:33:36.000Z
+lastmod: 2026-06-01T03:29:07.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -217,9 +217,9 @@ Jump to a topic:
 - [AI-native workflow](#-ai-native-workflow) — multi-agent guidance, AI install wizard, AI preview images, AIEO discovery
 - [Architecture & technology stack](#-architecture)
 - [Key features in depth](#-key-features) — installer CLI, site scraper, Docker, analytics, search, navigation, dark mode
-- [Installation methods](#-installation-methods) — one-liner, modular CLI, remote theme, fork, Ruby gem
+- [Installation methods](#-installation-methods--reference-card) — one-liner, modular CLI, remote theme, fork, Ruby gem
 - [Project structure](#-project-structure)
-- [Migration utility](#️-migration-utility--add-admin-pages-to-an-existing-site)
+- [Migration utility](#-migration-utility--add-admin-pages-to-an-existing-site)
 - [Development workflow & testing](#-development-workflow)
 - [Deployment options](#-deployment)
 - [Documentation map](#-documentation)
@@ -289,7 +289,7 @@ Clone the repo (or fork) and your editor's AI agent will pick up project context
 
 ## 🏗 Architecture
 
-> **Who this is for:** developers, theme customizers, and anyone integrating zer0-mistakes into a larger system. If you only want to publish a blog, you can skip ahead to [Key Features](#-key-features) or [Installation Methods](#-installation-methods).
+> **Who this is for:** developers, theme customizers, and anyone integrating zer0-mistakes into a larger system. If you only want to publish a blog, you can skip ahead to [Key Features](#-key-features) or [Installation Methods](#-installation-methods--reference-card).
 
 zer0-mistakes is a layered system: your content (Markdown + YAML) flows through the theme's templates, gets compiled by Jekyll, and is published as a fully static site that any host can serve. Every layer is replaceable without affecting the others.
 
@@ -407,7 +407,7 @@ docker-compose down -v           # clean up volumes and gem cache
 docker-compose down && docker-compose up --build   # full rebuild after Gemfile changes
 ```
 
-A separate [`docker-compose.test.yml`](docker-compose.test.yml) provides an isolated environment for CI-style test runs, and [`docker-compose.prod.yml`](docker-compose.prod.yml) (referenced in the [Deployment](#-deployment) section) builds a production image.
+A separate [`docker-compose.test.yml`](docker-compose.test.yml) provides an isolated environment for CI-style test runs.
 
 ### 🔒 Privacy-First Analytics
 
@@ -583,7 +583,7 @@ The repository follows Jekyll convention with a few additions for tooling and AI
 
 | Directory | Purpose | Key Files |
 |-----------|---------|-----------|
-| `_layouts/` | Page templates | `default.html`, `journals.html`, `landing.html`, `notebook.html` |
+| `_layouts/` | Page templates | `default.html`, `article.html`, `landing.html`, `notebook.html` |
 | `_includes/` | Reusable components | `core/`, `components/` (see `_includes/components/README.md`), `analytics/`, `navigation/` |
 | `_sass/` | Stylesheets | `tokens/` (design tokens), `components/`, `layouts/`, `utilities/`, `custom.scss` (legacy barrel), `core/`, `theme/` |
 | `_data/` | Data-driven content | `landing.yml` (homepage copy), `navigation/*.yml`, `ui-text.yml` (i18n), `features.yml`, `authors.yml`, `theme_backgrounds.yml` |
@@ -647,13 +647,13 @@ git commit -m "feat: add new component"
 
 ```bash
 # Quick validation
-./test/validate_installation.sh
+./test/test_installation.sh
 
 # Full test suite
 ./test/test_runner.sh --verbose
 
 # Docker-specific tests
-./test/test_docker_deployment.sh
+./test/test_deployment.sh
 
 # Frontend smoke tests (Playwright; starts Jekyll on :4011 unless BASE_URL is set)
 npm run test:smoke
@@ -680,7 +680,7 @@ Three supported targets, in order of recommendation:
 | Target | Cost | Setup | Best for |
 |---|---|---|---|
 | **GitHub Pages user site** | Free | Push to `main` of `<username>.github.io` (see [Path A](#path-a--easiest-fork-on-github-no-terminal-required)) | Most users; personal sites, docs, blogs, portfolios |
-| **Docker production image** | Self-hosted | `docker-compose -f docker-compose.prod.yml up -d` | Self-hosted servers, intranet, air-gapped environments |
+| **Docker production image** | Self-hosted | `JEKYLL_ENV=production docker-compose up -d` | Self-hosted servers, intranet, air-gapped environments |
 | **Custom static host** | Varies | `docker-compose run --rm jekyll jekyll build` → upload `_site/` | Netlify, Vercel, Cloudflare Pages, S3 + CloudFront, Azure Static Web Apps |
 
 ---
@@ -706,6 +706,25 @@ zer0-mistakes documentation is split across three audiences. Pick the layer that
 | [📝 PRD](docs/PRD.md) | Product requirements & roadmap |
 | [🔒 Privacy Policy](https://zer0-mistakes.com/privacy-policy/) | GDPR/CCPA compliant privacy docs |
 
+### Contributor Technical Reference
+
+These files live in the repo under `docs/` and are intended for theme contributors and forks:
+
+| File | Topic |
+|------|-------|
+| [docs/design-system.md](docs/design-system.md) | Design system overview |
+| [docs/design-tokens.md](docs/design-tokens.md) | Design tokens reference |
+| [docs/components.md](docs/components.md) | UI component catalogue |
+| [docs/layouts-and-navigation.md](docs/layouts-and-navigation.md) | Layout hierarchy & navigation |
+| [docs/theming.md](docs/theming.md) | Sass / Bootstrap theming guide |
+| [docs/customization.md](docs/customization.md) | Site customization patterns |
+| [docs/configuration.md](docs/configuration.md) | `_config.yml` reference |
+| [docs/code-blocks.md](docs/code-blocks.md) | Syntax highlighting setup |
+| [docs/extending.md](docs/extending.md) | Adding layouts, includes & plugins |
+| [docs/js-api.md](docs/js-api.md) | JavaScript module API |
+| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues & fixes |
+| [docs/FORKING.md](docs/FORKING.md) | Forking & personalization guide |
+
 ---
 
 ## 🔧 Release System
@@ -784,7 +803,7 @@ When you fork the theme as a starter, the workflows come with you. To make them
 
 ## 🗺 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.
+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](https://zer0-mistakes.com/roadmap/) for per-version detail and the [PRD](docs/PRD.md) for product context.
 
 <!-- ROADMAP_MERMAID:START -->
 
@@ -798,13 +817,23 @@ gantt
     v0.19 Feature Discovery      :done, 2026-01, 2026-01
     v0.20 Navigation Redesign    :done, 2026-02, 2026-02
     v0.21 Env Switcher           :done, 2026-02, 2026-03
+    v0.22 AIEO & Customization   :done, 2026-04, 2026-04
+    v1.0 Modular Installer & First Stable :done, 2026-04, 2026-04
+    v1.1 Copilot Agent Prompts   :done, 2026-04, 2026-04
+    v1.2 Bare-Minimum Starter    :done, 2026-04, 2026-04
+    v1.3 Obsidian Vault Integration :done, 2026-04, 2026-04
+    v1.4 Obsidian Graph View     :done, 2026-04, 2026-04
+    v1.5 Example Posts & AI Previews :done, 2026-04, 2026-04
+    v1.6 About Page & Search Cleanup :done, 2026-04, 2026-04
+    v1.7 Build Performance & MathJax 3 :done, 2026-05, 2026-05
+    v1.8 Design Tokens & Navigation Chrome :done, 2026-05, 2026-05
     section Current
-    v0.22 AIEO & Customization   :active, 2026-03, 2026-04
+    v1.9 Installer v2 & Site Scraper :active, 2026-05, 2026-05
     section Future
-    v0.23 CMS Integration        :2026-05, 2026-07
-    v0.24 i18n Support           :2026-07, 2026-09
-    v0.25 Advanced Analytics     :2026-09, 2026-11
-    v1.0 Stable Release          :milestone, 2027-01, 1d
+    v2.0 CMS Integration         :2026-06, 2026-08
+    v2.1 i18n Support            :2026-08, 2026-10
+    v2.2 Advanced Analytics      :2026-10, 2026-12
+    v3.0 Stable LTS              :milestone, 2027-02, 1d
 ```
 
 <!-- ROADMAP_MERMAID:END -->
@@ -818,11 +847,21 @@ gantt
 | **v0.19** | ✅ Completed | Jan 2026 | 43 documented features with a comprehensive feature registry. |
 | **v0.20** | ✅ Completed | Feb 2026 | Local Docker publishing pipeline and CI variable abstraction. |
 | **v0.21** | ✅ Completed | Feb 2026 | Environment switcher, settings modal redesign, and RubyGems API-key auth. |
-| **v0.22** | 🚧 In Progress | Q1–Q2 2026 | AI Engine Optimization (AIEO), structured data, and visual customization tools. |
-| **v0.23** | 🗓 Planned | Q2 2026 | Headless CMS integration with a content API and admin dashboard. |
-| **v0.24** | 🗓 Planned | Q3 2026 | Multi-language content support with locale-aware routing. |
-| **v0.25** | 🗓 Planned | Q4 2026 | Visual theme customizer, A/B testing, and conversion funnels. |
-| **v1.0** | 🎯 Milestone | Q1 2027 | Stable public API, 90%+ test coverage, and long-term support commitment. |
+| **v0.22** | ✅ Completed | Apr 2026 | AI Engine Optimization (AIEO), structured data, and visual customization tools. |
+| **v1.0** | ✅ Completed | Apr 2026 | First stable major release — the monolithic installer rewritten as a modular, spec-driven CLI. |
+| **v1.1** | ✅ Completed | Apr 2026 | Data-driven Copilot Agent prompt registry focused on frontend and CMS workflows. |
+| **v1.2** | ✅ Completed | Apr 2026 | Three-file remote-theme starter with an in-browser configuration wizard. |
+| **v1.3** | ✅ Completed | Apr 2026 | Edit content as an Obsidian vault with identical rendering on GitHub Pages. |
+| **v1.4** | ✅ Completed | Apr 2026 | Force-directed knowledge graph mirroring Obsidian's local graph view. |
+| **v1.5** | ✅ Completed | Apr 2026 | Richer sample content and regenerated AI preview images. |
+| **v1.6** | ✅ Completed | Apr 2026 | Expanded About page and removal of the Algolia search dependency. |
+| **v1.7** | ✅ Completed | May 2026 | Significant Jekyll build speedups and a MathJax 3 inline-math fix. |
+| **v1.8** | ✅ Completed | May 2026 | Sass design-token system, refreshed navigation chrome, and a docs overhaul. |
+| **v1.9** | 🚧 In Progress | Current (1.9.x) | Modular installer v2 with deploy plugins, AI wizard pipeline, and a site scraper. |
+| **v2.0** | 🗓 Planned | Q3 2026 | Headless CMS integration with a content API and admin dashboard. |
+| **v2.1** | 🗓 Planned | Q4 2026 | Multi-language content support with locale-aware routing. |
+| **v2.2** | 🗓 Planned | Q4 2026 | Visual theme customizer, A/B testing, and conversion funnels. |
+| **v3.0** | 🎯 Milestone | Q1 2027 | Stable public API, 90%+ test coverage, and long-term support commitment. |
 
 <!-- ROADMAP_TABLE:END -->
 
@@ -862,10 +901,10 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 1.9.9 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 1.10.0 ([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/)) |
+| **Documentation Pages** | 70+ ([browse docs](https://zer0-mistakes.com/pages/)) |
 | **RubyGems Downloads** | 3,000+ ([rubygems.org](https://rubygems.org/gems/jekyll-theme-zer0)) |
 | **Lighthouse Score** | 95+ ([measured via Chrome DevTools](https://developer.chrome.com/docs/lighthouse/)) |
 
@@ -883,10 +922,10 @@ Key patterns applied (see [glossary entry](https://zer0-mistakes.com/glossary/#a
 |---|---|
 | **Structured Data** | JSON-LD `SoftwareApplication`, `WebPage`, `Person`, and `FAQPage` schemas in every page head |
 | **Entity Density** | Author profiles, technology names, and version numbers linked to canonical sources |
-| **E-E-A-T Signals** | Visible [author block](/glossary/#e-e-a-t) on the landing page with social proof links |
-| **FAQ Injection** | Dedicated [FAQ page](/faq/) with 12 question-answer pairs and FAQPage schema |
-| **Definitional Precision** | Machine-readable [Glossary](/glossary/) with 20+ key term definitions |
-| **Temporal Anchoring** | Dated [Roadmap](/roadmap/) with past, present, and future milestones |
+| **E-E-A-T Signals** | Visible [author block](https://zer0-mistakes.com/glossary/#e-e-a-t) on the landing page with social proof links |
+| **FAQ Injection** | Dedicated [FAQ page](https://zer0-mistakes.com/faq/) with 12 question-answer pairs and FAQPage schema |
+| **Definitional Precision** | Machine-readable [Glossary](https://zer0-mistakes.com/glossary/) with 20+ key term definitions |
+| **Temporal Anchoring** | Dated [Roadmap](https://zer0-mistakes.com/roadmap/) with past, present, and future milestones |
 | **Substantiated Claims** | Project stats table links to RubyGems, CHANGELOG, and Feature Registry as evidence |
 | **Procedural Clarity** | Step-by-step installation with Mermaid sequence diagrams and comparison tables |
 
@@ -917,6 +956,6 @@ And these AI partners that make zer0-mistakes truly AI-native:
 
 **Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
 
-**v1.9.9** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
+**v1.10.0** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
 
 

data/_data/roadmap.yml

@@ -16,10 +16,23 @@
 # To update the roadmap:
 #   1. Edit this file.
 #   2. Run `./scripts/generate-roadmap.sh` to refresh the README.
-#   3. Commit both this file and the resulting README.md changes.
+#   3. Run `./scripts/generate-roadmap.sh --validate` to confirm the roadmap
+#      is internally consistent and still tracks the shipped gem version.
+#   4. Commit both this file and the resulting README.md changes.
 #
 # A GitHub Actions workflow (`.github/workflows/roadmap-sync.yml`) also runs
-# the generator automatically on push when this file changes.
+# the generator and the validator automatically: it regenerates the README on
+# push, fails PRs whose README is stale, and flags whenever the roadmap drifts
+# behind the version in `lib/jekyll-theme-zer0/version.rb`.
+#
+# Tracking rules enforced by `--validate`:
+#   - `status` must be one of: completed | active | planned | milestone
+#   - `status` must match its `section` (completed=Completed, active=Current,
+#     planned/milestone=Future)
+#   - exactly one `active` milestone; its version must equal the gem's
+#     major.minor series
+#   - no `planned`/`milestone` version at or below the shipped gem version
+#   - `start`/`end` are valid YYYY-MM with end >= start; `meta.updated` is fresh
 #
 # =============================================================================
 # Schema
@@ -47,7 +60,7 @@
 meta:
   title: "zer0-mistakes Roadmap"
   tagline: "Past releases, current focus, and future plans for the zer0-mistakes Jekyll theme."
-  updated: 2026-04-18
+  updated: 2026-05-30
 
 milestones:
   # --- Completed -------------------------------------------------------------
@@ -119,40 +132,171 @@ milestones:
       - "RubyGems API-key authentication"
       - "Dependency updates"
 
-  # --- Current ---------------------------------------------------------------
+  # --- Completed (continued) -------------------------------------------------
 
   - version: "0.22"
     title: "AIEO & Customization"
-    status: active
-    section: Current
-    start: 2026-03
+    status: completed
+    section: Completed
+    start: 2026-04
     end: 2026-04
-    target: "Q1–Q2 2026"
+    released: 2026-04-21
     summary: "AI Engine Optimization (AIEO), structured data, and visual customization tools."
     features:
       - "JSON-LD `SoftwareApplication`, `WebPage`, `Person`, and `FAQPage` schemas"
       - "Author E-E-A-T visibility block on the landing page"
-      - "FAQ page with FAQPage schema"
-      - "Glossary with key term definitions"
-      - "Roadmap page with temporal anchoring"
-      - "Citation hooks on project stats"
+      - "FAQ page with FAQPage schema and glossary with key term definitions"
       - "Skin editor with live color pickers and palette generator"
       - "Admin layout and configuration dashboards"
       - "Playwright visual regression tests"
       - "Vendored assets (Bootstrap, Icons, Mermaid — no runtime CDN)"
       - "Copilot Agent prompt button with data-driven prompt registry"
-      - "Universal installer (remote / github / codespaces modes)"
       - "Dynamic collection-based navigation fallback for zero-config sites"
 
+  - version: "1.0"
+    title: "Modular Installer & First Stable"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-20
+    summary: "First stable major release — the monolithic installer rewritten as a modular, spec-driven CLI."
+    features:
+      - "Modular installer CLI (`scripts/bin/install`) with library modules"
+      - "Declarative YAML profiles (full / minimal / fork / remote / github)"
+      - "Pluggable deploy targets (GitHub Pages, Azure SWA, Docker)"
+      - "`wizard --ai`, `doctor`, `diagnose`, and `upgrade` subcommands"
+      - "Hardened version analyzer and release automation"
+
+  - version: "1.1"
+    title: "Copilot Agent Prompts"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-21
+    summary: "Data-driven Copilot Agent prompt registry focused on frontend and CMS workflows."
+    features:
+      - "Prompt registry powering the Copilot Agent button"
+      - "Frontend- and CMS-oriented prompt presets"
+
+  - version: "1.2"
+    title: "Bare-Minimum Starter"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-22
+    summary: "Three-file remote-theme starter with an in-browser configuration wizard."
+    features:
+      - "`welcome` layout that detects unconfigured sites"
+      - "Embedded setup wizard that generates a personalised `_config.yml`"
+      - "Smarter unconfigured-site detection heuristics"
+
+  - version: "1.3"
+    title: "Obsidian Vault Integration"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-24
+    summary: "Edit content as an Obsidian vault with identical rendering on GitHub Pages."
+    features:
+      - "Client-side wiki-link resolver (aliases, embeds, callouts, inline tags)"
+      - "Server-side backlinks panel on note layouts"
+      - "Optional Ruby converter for vanilla Jekyll forks"
+
+  - version: "1.4"
+    title: "Obsidian Graph View"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-25
+    summary: "Force-directed knowledge graph mirroring Obsidian's local graph view."
+    features:
+      - "Cytoscape.js graph at `/docs/obsidian/graph/`"
+      - "Standalone collapsible local graph panel"
+
+  - version: "1.5"
+    title: "Example Posts & AI Previews"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-29
+    summary: "Richer sample content and regenerated AI preview images."
+    features:
+      - "12 example posts across Business, Development, Science, Technology, Tutorial, and World"
+      - "All preview images regenerated with the GPT image model"
+
+  - version: "1.6"
+    title: "About Page & Search Cleanup"
+    status: completed
+    section: Completed
+    start: 2026-04
+    end: 2026-04
+    released: 2026-04-29
+    summary: "Expanded About page and removal of the Algolia search dependency."
+    features:
+      - "About page with prerequisites, quick start, FAQ, and architecture diagram"
+      - "Algolia removed in favor of the built-in client-side search"
+      - "Jekyll build performance caching"
+
+  - version: "1.7"
+    title: "Build Performance & MathJax 3"
+    status: completed
+    section: Completed
+    start: 2026-05
+    end: 2026-05
+    released: 2026-05-24
+    summary: "Significant Jekyll build speedups and a MathJax 3 inline-math fix."
+    features:
+      - "Conditional MathJax/Mermaid loading and richer Obsidian cache"
+      - "jQuery removed from page loads"
+      - "Profiled Docker build reduced from ~119s to ~87s"
+
+  - version: "1.8"
+    title: "Design Tokens & Navigation Chrome"
+    status: completed
+    section: Completed
+    start: 2026-05
+    end: 2026-05
+    released: 2026-05-25
+    summary: "Sass design-token system, refreshed navigation chrome, and a docs overhaul."
+    features:
+      - "Sass token layers, component/layout partials, and skins"
+      - "VS Code-style collapsible sidebar rail and TOC"
+      - "Unified Playwright test tiers (smoke / snapshots / regression)"
+      - "Design-system developer docs"
+
+  # --- Current ---------------------------------------------------------------
+
+  - version: "1.9"
+    title: "Installer v2 & Site Scraper"
+    status: active
+    section: Current
+    start: 2026-05
+    end: 2026-05
+    target: "Current (1.9.x)"
+    released: 2026-05-27
+    summary: "Modular installer v2 with deploy plugins, AI wizard pipeline, and a site scraper."
+    features:
+      - "Installer deploy plugins and AI wizard apply pipeline"
+      - "Site scraper — BFS-crawl any website into a zer0-mistakes site"
+      - "Accessibility skin fixes (WCAG AA contrast); `air` default skin"
+      - "Quickstart documentation rewrite with screenshots"
+      - "Hardened one-line installer path"
+
   # --- Future ----------------------------------------------------------------
 
-  - version: "0.23"
+  - version: "2.0"
     title: "CMS Integration"
     status: planned
     section: Future
-    start: 2026-05
-    end: 2026-07
-    target: "Q2 2026"
+    start: 2026-06
+    end: 2026-08
+    target: "Q3 2026"
     summary: "Headless CMS integration with a content API and admin dashboard."
     features:
       - "Headless CMS integration (Decap CMS or Tina)"
@@ -161,13 +305,13 @@ milestones:
       - "Draft preview workflow"
       - "Multi-author collaboration"
 
-  - version: "0.24"
+  - version: "2.1"
     title: "i18n Support"
     status: planned
     section: Future
-    start: 2026-07
-    end: 2026-09
-    target: "Q3 2026"
+    start: 2026-08
+    end: 2026-10
+    target: "Q4 2026"
     summary: "Multi-language content support with locale-aware routing."
     features:
       - "Multi-language content support"
@@ -175,12 +319,12 @@ milestones:
       - "Translated UI strings via `_data/ui-text.yml`"
       - "Right-to-left (RTL) layout support"
 
-  - version: "0.25"
+  - version: "2.2"
     title: "Advanced Analytics"
     status: planned
     section: Future
-    start: 2026-09
-    end: 2026-11
+    start: 2026-10
+    end: 2026-12
     target: "Q4 2026"
     summary: "Visual theme customizer, A/B testing, and conversion funnels."
     features:
@@ -189,12 +333,12 @@ milestones:
       - "Heatmap visualization"
       - "Visual theme customizer enhancements"
 
-  - version: "1.0"
-    title: "Stable Release"
+  - version: "3.0"
+    title: "Stable LTS"
     status: milestone
     section: Future
-    start: 2027-01
-    end: 2027-01
+    start: 2027-02
+    end: 2027-02
     target: "Q1 2027"
     summary: "Stable public API, 90%+ test coverage, and long-term support commitment."
     features:

data/scripts/generate-roadmap.rb

@@ -15,6 +15,7 @@
 # Usage:
 #   ruby scripts/generate-roadmap.rb              # update README.md in place
 #   ruby scripts/generate-roadmap.rb --check      # exit non-zero if README is stale
+#   ruby scripts/generate-roadmap.rb --validate   # check roadmap integrity & version tracking
 #   ruby scripts/generate-roadmap.rb --stdout     # print regenerated sections only
 #
 # This script has no gem dependencies beyond the Ruby stdlib.
@@ -24,9 +25,21 @@ require 'yaml'
 require 'date'
 require 'optparse'
 
-ROOT       = File.expand_path('..', __dir__)
-DATA_FILE  = File.join(ROOT, '_data', 'roadmap.yml')
-README     = File.join(ROOT, 'README.md')
+ROOT        = File.expand_path('..', __dir__)
+DATA_FILE   = File.join(ROOT, '_data', 'roadmap.yml')
+README      = File.join(ROOT, 'README.md')
+VERSION_RB  = File.join(ROOT, 'lib', 'jekyll-theme-zer0', 'version.rb')
+
+# Allowed enum values and the section each status must live in.
+VALID_STATUSES  = %w[completed active planned milestone].freeze
+SECTION_FOR     = {
+  'completed' => 'Completed',
+  'active'    => 'Current',
+  'planned'   => 'Future',
+  'milestone' => 'Future'
+}.freeze
+# How stale meta.updated may get before validation warns (days).
+FRESHNESS_DAYS  = 120
 
 MERMAID_START = '<!-- ROADMAP_MERMAID:START -->'
 MERMAID_END   = '<!-- ROADMAP_MERMAID:END -->'
@@ -90,7 +103,7 @@ def target_label(milestone)
   case milestone['status']
   when 'completed'
     if (released = milestone['released'])
-      Date.parse(released.to_s).strftime('%b %Y')
+      Date.parse(released.to_s).strftime('%b %Y') rescue 'Completed'
     else
       'Completed'
     end
@@ -126,6 +139,150 @@ def render_table(data)
   (header + rows).join("\n")
 end
 
+# ---------------------------------------------------------------------------
+# Tracking / validation helpers
+# ---------------------------------------------------------------------------
+
+# Reads the canonical gem version (e.g. "1.9.8") from lib/.../version.rb.
+# Returns nil if the file or constant can't be found, so validation degrades
+# gracefully on stripped checkouts.
+def current_gem_version
+  return nil unless File.exist?(VERSION_RB)
+
+  m = File.read(VERSION_RB).match(/VERSION\s*=\s*["']([^"']+)["']/)
+  m && m[1]
+end
+
+# "1.9.8" -> "1.9" (the major.minor series a milestone version tracks).
+def minor_series(version_string)
+  parts = version_string.to_s.split('.')
+  "#{parts[0]}.#{parts[1] || '0'}"
+end
+
+def parse_month(value)
+  Date.strptime(value.to_s, '%Y-%m')
+rescue ArgumentError
+  nil
+end
+
+# Validates the roadmap data for internal consistency and tracking accuracy.
+# Returns [errors, warnings] as arrays of strings. Errors are integrity
+# violations (fail CI); warnings flag drift that humans should review.
+def validate_roadmap(data)
+  errors   = []
+  warnings = []
+  milestones = data['milestones'] || []
+
+  errors << 'No milestones defined.' if milestones.empty?
+
+  seen_versions = {}
+  milestones.each do |m|
+    id = "v#{m['version'] || '?'}"
+
+    %w[version title status section start].each do |field|
+      errors << "#{id}: missing required field '#{field}'." if m[field].nil? || m[field].to_s.empty?
+    end
+
+    status = m['status'].to_s
+    unless VALID_STATUSES.include?(status)
+      errors << "#{id}: invalid status '#{status}' (expected #{VALID_STATUSES.join(', ')})."
+    end
+
+    if (expected = SECTION_FOR[status]) && m['section'] != expected
+      errors << "#{id}: status '#{status}' must use section '#{expected}', found '#{m['section']}'."
+    end
+
+    if (v = m['version'])
+      errors << "#{id}: duplicate version '#{v}'." if seen_versions[v]
+      seen_versions[v] = true
+    end
+
+    start_d  = parse_month(m['start'])
+    errors << "#{id}: start '#{m['start']}' is not a valid YYYY-MM date." if m['start'] && start_d.nil?
+    if m['end']
+      end_d = parse_month(m['end'])
+      if end_d.nil?
+        errors << "#{id}: end '#{m['end']}' is not a valid YYYY-MM date."
+      elsif start_d && end_d < start_d
+        errors << "#{id}: end '#{m['end']}' precedes start '#{m['start']}'."
+      end
+    end
+
+    if status == 'completed' && (m['released'].nil? || m['released'].to_s.empty?)
+      warnings << "#{id}: completed milestone has no 'released' date."
+    end
+
+    if status == 'active' && !m['released'].to_s.empty?
+      warnings << "#{id}: active milestone has a 'released' date — should it be marked 'completed'?"
+    end
+  end
+
+  # Exactly one in-flight milestone keeps "Current" unambiguous.
+  active = milestones.select { |m| m['status'] == 'active' }
+  case active.size
+  when 0 then warnings << "No 'active' milestone — nothing marks the current focus."
+  when 1 then nil
+  else errors << "Multiple 'active' milestones (#{active.map { |m| "v#{m['version']}" }.join(', ')}); only one allowed."
+  end
+
+  # Cross-reference the canonical gem version so the roadmap can't drift.
+  if (gem_v = current_gem_version)
+    require 'rubygems'
+    gem_ver = Gem::Version.new(gem_v)
+    series  = minor_series(gem_v)
+
+    if active.size == 1 && active.first['version'].to_s != series
+      warnings << "Active milestone is v#{active.first['version']} but the gem is at v#{gem_v} " \
+                  "(series #{series}). Advance the roadmap to track the shipped version."
+    end
+
+    milestones.each do |m|
+      next unless %w[planned milestone].include?(m['status'].to_s)
+
+      begin
+        next if Gem::Version.new(m['version'].to_s) > gem_ver
+      rescue ArgumentError
+        next
+      end
+      warnings << "v#{m['version']} is still '#{m['status']}' but the gem already shipped v#{gem_v}; " \
+                  'mark it completed or renumber it.'
+    end
+  else
+    warnings << "Could not read gem version from #{File.basename(VERSION_RB)} — skipped version tracking."
+  end
+
+  # Freshness of the last-reviewed date.
+  if (updated = data.dig('meta', 'updated'))
+    updated_d = updated.is_a?(Date) ? updated : (Date.parse(updated.to_s) rescue nil)
+    if updated_d.nil?
+      warnings << "meta.updated '#{updated}' is not a valid date."
+    elsif (Date.today - updated_d).to_i > FRESHNESS_DAYS
+      warnings << "meta.updated (#{updated_d}) is more than #{FRESHNESS_DAYS} days old; review the roadmap."
+    end
+  else
+    warnings << 'meta.updated is not set.'
+  end
+
+  [errors, warnings]
+end
+
+def run_validation(data)
+  errors, warnings = validate_roadmap(data)
+
+  warnings.each { |w| warn "  ⚠ WARN  #{w}" }
+  errors.each   { |e| warn "  ✗ FAIL  #{e}" }
+
+  if errors.empty? && warnings.empty?
+    puts '✓ Roadmap is valid and tracks the current version.'
+  elsif errors.empty?
+    puts "✓ Roadmap valid (#{warnings.size} warning(s) — see above)."
+  else
+    warn "✗ Roadmap validation failed: #{errors.size} error(s), #{warnings.size} warning(s)."
+  end
+
+  errors.empty? ? 0 : 1
+end
+
 def replace_block(content, marker_start, marker_end, replacement)
   pattern = /(#{Regexp.escape(marker_start)})(.*?)(#{Regexp.escape(marker_end)})/m
   unless content.match?(pattern)
@@ -146,8 +303,9 @@ end
 def main
   options = { mode: :write }
   OptionParser.new do |opts|
-    opts.banner = 'Usage: generate-roadmap.rb [--check|--stdout]'
+    opts.banner = 'Usage: generate-roadmap.rb [--check|--validate|--stdout]'
     opts.on('--check', 'Exit non-zero if README would change') { options[:mode] = :check }
+    opts.on('--validate', 'Check roadmap integrity & version tracking') { options[:mode] = :validate }
     opts.on('--stdout', 'Print regenerated sections to stdout') { options[:mode] = :stdout }
   end.parse!
 
@@ -162,6 +320,9 @@ def main
     rescue ArgumentError
       YAML.safe_load(File.read(DATA_FILE), permitted_classes: [Date, Time], aliases: false)
     end
+
+  return run_validation(data) if options[:mode] == :validate
+
   mermaid = render_mermaid(data)
   table   = render_table(data)
 

data/scripts/generate-roadmap.sh

@@ -11,6 +11,7 @@
 # Usage:
 #   ./scripts/generate-roadmap.sh             # update README.md
 #   ./scripts/generate-roadmap.sh --check     # CI-friendly drift detection
+#   ./scripts/generate-roadmap.sh --validate  # check integrity & version tracking
 #   ./scripts/generate-roadmap.sh --stdout    # print regenerated sections only
 #
 # =============================================================================

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.9.9
+  version: 1.10.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-31 00:00:00.000000000 Z
+date: 2026-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll