Upgrade al-folio to v1.0

.github/copilot-instructions.md

@@ -1,253 +1,92 @@
 # Copilot Coding Agent Instructions
 
-## Repository Overview
+## Repository Role
 
-**al-folio** is a simple, clean, and responsive [Jekyll](https://jekyllrb.com/) theme for academics and researchers. It enables users to create professional portfolio and blog websites with minimal configuration. The repository serves both as a template and as a reference implementation.
+`al-folio` is a **starter kit** for the v1 pluginized architecture.
 
-- **Type:** Jekyll static site generator template
-- **Target Users:** Academics, researchers, and professionals
-- **Key Features:** CV display, publication bibliography, blog posts, projects, news/announcements, course listings
+- Runtime/theme internals are gem-owned (`al_folio_core`, `al_folio_distill`, `al_cookie`, other `al-*` plugins).
+- This repo owns starter wiring, sample content, docs, integration tests, and visual regression tests.
 
-## Tech Stack & Versions
+## Ownership Boundaries
 
-**Core Technologies:**
+Follow [`BOUNDARIES.md`](../BOUNDARIES.md) strictly.
 
-- **Jekyll:** v4.x (Ruby static site generator)
-- **Ruby:** 3.3.5 (primary CI/CD version), 3.2.2 (some workflows)
-- **Python:** 3.13 (for nbconvert, jupyter notebook support)
-- **Node.js:** Latest (for purgecss and prettier)
-- **Docker:** Uses prebuilt image `amirpourmand/al-folio:v0.16.3` (Ruby slim-based)
+- Starter (`al-folio`):
+  - integration tests
+  - visual regression tests
+  - docs and starter config
+- Gem repos:
+  - component/unit correctness tests
+  - runtime asset packaging/contract tests
+  - feature-specific logic
 
-**Build Dependencies (from Gemfile):**
+Do not reintroduce gem-owned component runtime files into this starter unless intentionally overriding behavior.
 
-- `classifier-reborn` – Related posts calculation
-- `jekyll-archives-v2` – Archive page generation
-- `jekyll-jupyter-notebook` – Jupyter notebook embedding
-- `jekyll-minifier` – CSS/JS minification
-- `jekyll-paginate-v2` – Pagination
-- `jekyll-scholar` – Bibliography management
-- `jekyll-tabs` – Tab UI components
-- `jekyll-toc` – Table of contents generation
-- `jemoji` – Emoji support
-- Multiple other specialized jekyll plugins
+## Core Stack
 
-**Code Quality Tools:**
+- Jekyll (Ruby)
+- Node only for tooling (`prettier`, Playwright test runtime)
+- No starter-local Tailwind build pipeline in v1
 
-- **Prettier:** v3.8.0+ with `@shopify/prettier-plugin-liquid` – Code formatter (mandatory for PRs)
-- **Purgecss:** CSS purification for production builds
+## Starter Layout (high-signal paths)
 
-## Building & Local Development
+- `_config.yml` - starter wiring, plugin list, feature flags
+- `_data/`, `_pages/`, `_posts/`, `_projects/`, `_news/` - starter content
+- `assets/` - starter-owned content assets
+- `test/visual/` - visual parity suite (Playwright)
+- `test/integration_*.sh` - cross-gem integration checks
+- `test/style_contract.js` - starter contract checks only
+- `.github/workflows/` - CI for starter integration and visual checks
 
-### Docker (Recommended Approach)
+## Local Validation
 
-**Always use Docker for local development.** This ensures consistency with CI/CD and avoids Ruby/Python environment issues.
-
-**Initial Setup:**
-
-```bash
-docker compose pull                    # Pull prebuilt image
-docker compose up                      # Start development server
-# Site runs at http://localhost:8080
-```
-
-**Rebuilding with Updated Dependencies:**
+Common checks for starter changes:
 
 ```bash
-docker compose up --build              # Rebuilds Docker image from Dockerfile
-docker compose up --force-recreate     # Forces complete rebuild
+npm ci
+npm run lint:prettier
+npm run lint:style-contract
+./bin/setup-python-deps
+bundle exec jekyll build
+bash test/integration_comments.sh
+bash test/integration_plugin_toggles.sh
+bash test/integration_distill.sh
+bash test/integration_bootstrap_compat.sh
+bash test/integration_upgrade_cli.sh
 ```
 
-**For slim Docker image (if image size is critical):**
+Visual checks:
 
 ```bash
-docker compose -f docker-compose-slim.yml up
+npx playwright install chromium webkit
+npm run test:visual
 ```
 
-**If Docker build fails:**
-
-- Check disk space and available RAM
-- Kill any existing jekyll processes: `docker compose down`
-- For M1/M2 Mac: Ensure Docker Desktop is up-to-date
-- Linux users may need Docker group permissions: `sudo usermod -aG docker $USER` (then logout/login)
-
-### Bundle/Jekyll (Legacy, Use Docker Instead)
-
-```bash
-bundle install                         # Install Ruby gems
-pip install jupyter                    # Install Python dependencies
-bundle exec jekyll serve --port 4000   # Run at http://localhost:4000
-```
+## CI Expectations
 
-### Important Build Requirements
-
-- **ImageMagick must be installed** – Required for image processing plugins
-  - Docker: Installed automatically
-  - Local: `sudo apt-get install imagemagick` (Linux) or `brew install imagemagick` (Mac)
-- **nbconvert must be upgraded before build** – `pip3 install --upgrade nbconvert`
-- **Always set JEKYLL_ENV=production for production builds** – Required for CSS/JS minification
-
-## Project Layout & Key Files
-
-### Root Directory Structure
-
-- `_bibliography/papers.bib` – BibTeX bibliography for publications
-- `_config.yml` – **Primary configuration file** (title, author, URLs, baseurl, feature flags)
-- `_data/` – YAML data files (socials.yml, coauthors.yml, cv.yml, citations.yml, venues.yml, repositories.yml)
-- `_includes/` – Reusable Liquid template components
-- `_layouts/` – Page layout templates (about.liquid, post.liquid, bib.liquid, distill.liquid, cv.liquid, etc.)
-- `_news/` – News/announcement entries
-- `_pages/` – Static pages (about.md, cv.md, publications.md, projects.md, teaching.md, etc.)
-- `_posts/` – Blog posts (format: YYYY-MM-DD-title.md)
-- `_projects/` – Project showcase entries
-- `_sass/` – SCSS stylesheets
-- `_scripts/` – JavaScript files for functionality
-- `_teachings/` – Course and teaching entries
-- `assets/img/` – Images, profile pictures
-- `docker-compose.yml` – Docker compose configuration
-- `Dockerfile` – Docker image definition
-- `Gemfile` & `Gemfile.lock` – Ruby dependency specifications
-- `package.json` – Node.js dependencies (prettier only)
-- `purgecss.config.js` – PurgeCSS configuration for production CSS optimization
-
-### Configuration Priority
-
-When making changes:
-
-1. **Always start with `_config.yml`** for site-wide settings
-2. **Feature flags are in `_config.yml`** – Look for `enabled: true/false` options
-3. **Social media links:** `_data/socials.yml`
-4. **Content data:** Respective `_data/*.yml` files
-5. **Styling:** `_sass/` directory (uses SCSS)
-
-## CI/CD Pipeline & Validation
-
-### GitHub Workflows (in `.github/workflows/`)
-
-- **deploy.yml** – Main deployment workflow (runs on push/PR to main/master)
-  - Sets up Ruby 3.3.5, Python 3.13
-  - Installs imagemagick, nbconvert
-  - Runs `bundle exec jekyll build` with JEKYLL_ENV=production
-  - Runs purgecss for CSS optimization
-  - Commits built site to gh-pages branch
-  - **Triggers on:** Changes to site files, assets, config (NOT documentation files alone)
-- **prettier.yml** – Code formatting validation (mandatory)
-  - Runs prettier on all files
-  - **Fails PRs if code is not properly formatted**
-  - Generates HTML diff artifact on failure
-  - Must install prettier locally to avoid failures: `npm install prettier @shopify/prettier-plugin-liquid`
-- **broken-links.yml, broken-links-site.yml** – Link validation
-- **axe.yml** – Accessibility testing
-- **codeql.yml** – Security scanning
-- **update-citations.yml** – Automatic citation updates
-- **render-cv.yml** – CV rendering from RenderCV format
-
-### Pre-commit Requirements
-
-**You must run these locally before pushing:**
-
-1. **Prettier formatting (mandatory):**
+When editing starter behavior, keep these workflows aligned:
 
-```bash
-npm install --save-dev prettier @shopify/prettier-plugin-liquid
-npx prettier . --write
-```
+- `unit-tests.yml` (integration + starter contract lint)
+- `visual-regression.yml` (visual parity)
+- `upgrade-check.yml` (upgrade audit contract)
+- `deploy.yml` (starter deploy build)
 
-2. **Local build test with Jekyll:**
+Do not add no-op npm build scripts back into `package.json`.
 
-```bash
-docker compose pull && docker compose up
-# Let it build (wait 30-60 seconds)
-# Visit http://localhost:8080 and verify site renders correctly
-# Exit with Ctrl+C
-```
+## Upgrade and Migration
 
-3. **Or run full build simulation:**
+Use upgrade CLI for migration checks:
 
 ```bash
-docker compose up --build
-bundle exec jekyll build
-# Check for errors in output
+bundle exec al-folio upgrade audit
+bundle exec al-folio upgrade apply --safe
+bundle exec al-folio upgrade report
 ```
 
-## Common Pitfalls & Workarounds
-
-### YAML Syntax Errors in \_config.yml
-
-- **Problem:** Special characters (`:`, `&`, `#`) in values cause parse errors
-- **Solution:** Quote string values: `title: "My: Cool Site"`
-- **Debug:** Run locally to see detailed error: `bundle exec jekyll build`
-
-### "Unknown tag 'toc'" Error on Deployment
-
-- **Problem:** Deploy succeeds locally but fails on GitHub Actions
-- **Cause:** Jekyll plugins don't load properly
-- **Solution:** Verify gh-pages branch is set as deployment source in Settings → Pages
-
-### CSS/JS Not Loading After Deploy
-
-- **Problem:** Site loads but has no styling
-- **Cause:** Incorrect `url` and `baseurl` in `_config.yml`
-- **Fix:**
-  - Personal site: `url: https://username.github.io`, `baseurl:` (empty)
-  - Project site: `url: https://username.github.io`, `baseurl: /repo-name/`
-  - Clear browser cache (Ctrl+Shift+Del or private browsing)
-
-### Prettier Formatting Failures
-
-- **Problem:** PR fails prettier check after local builds passed
-- **Solution:** Run prettier before committing:
-  ```bash
-  npx prettier . --write
-  git add . && git commit -m "Format code with prettier"
-  ```
-
-### Port 8080 or 4000 Already in Use
-
-- **Docker:** `docker compose down` then `docker compose up`
-- **Ruby:** Kill process: `lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill`
-
-### Related Posts Errors ("Zero vectors cannot be normalized")
-
-- **Cause:** Empty blog posts or posts with only stop words confuse classifier-reborn
-- **Solution:** Add meaningful content to posts, or set `related_posts: false` in post frontmatter
-
-## File Format Specifications
-
-### Blog Post Frontmatter (\_posts/)
-
-```yaml
----
-layout: post
-title: Post Title
-date: YYYY-MM-DD
-categories: category-name
----
-```
-
-### Project Frontmatter (\_projects/)
-
-```yaml
----
-layout: page
-title: Project Name
-description: Short description
-img: /assets/img/project-image.jpg
-importance: 1
----
-```
-
-### BibTeX Format (papers.bib)
-
-- Standard BibTeX format
-- al-folio supports custom keywords: `pdf`, `code`, `preview`, `doi`, etc.
-- Check CUSTOMIZE.md for custom bibtex keyword documentation
-
-## Trust These Instructions
-
-This guidance documents the tested, working build process and project structure. **Trust these instructions and only perform additional searches if:**
+Generated report path: `al-folio-upgrade-report.md`.
 
-1. Specific information contradicts what you observe in the codebase
-2. You need implementation details beyond what's documented
-3. Error messages reference features or files not mentioned here
+## Editing Guidance
 
-The instructions are designed to reduce unnecessary exploration and allow you to focus on code changes.
+- Prefer starter wiring/config/content changes in this repo.
+- For runtime/layout/style/pipeline fixes, route to the owning gem repo.
+- Keep docs consistent with thin-starter architecture.

.github/workflows/deploy.yml

@@ -7,8 +7,6 @@ on:
       - main
     paths:
       - "assets/**"
-      - "_sass/**"
-      - "_scripts/**"
       - "**.bib"
       - "**.html"
       - "**.js"
@@ -36,8 +34,6 @@ on:
       - main
     paths:
       - "assets/**"
-      - "_sass/**"
-      - "_scripts/**"
       - "**.bib"
       - "**.html"
       - "**.js"
@@ -81,6 +77,13 @@ jobs:
         with:
           python-version: "3.13"
           cache: "pip" # caching pip dependencies
+      - name: Setup Node 🧰
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+      - name: Install JS deps 📦
+        run: npm ci
       - name: Update _config.yml ⚙️
         uses: fjogeleit/yaml-update-action@main
         with: