Upgrade site to al-folio v1

.agents/skills/al-folio-bootstrap/SKILL.md

@@ -0,0 +1,34 @@
+# al-folio Bootstrap
+
+Use this skill when a user asks an agent to create, configure, or personalize a new al-folio v1.x website.
+
+## Workflow
+
+1. Read `AGENTS.md` and `docs/BOUNDARIES.md` before editing.
+2. Keep the starter small: customize `_config.yml`, `_data`, content collections, and site assets first.
+3. Leave runtime behavior in plugin repos. Do not copy plugin-owned layouts, includes, Sass, JavaScript, or assets into the starter unless the user intentionally wants a local override.
+4. For local visual/content customization, prefer:
+   - `_config.yml` feature flags and site metadata
+   - `_data/*.yml`
+   - `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_bibliography`
+   - local `_includes`, `_layouts`, and `_sass` overrides only when config/content cannot express the change
+5. Run validation before handing work back:
+
+```bash
+npm ci
+npm run lint:prettier
+bundle exec al-folio upgrade audit --no-fail
+bundle exec jekyll build --baseurl /al-folio
+```
+
+## Routing
+
+- Starter wiring/docs/examples/tests: edit `al-folio`.
+- Shared layouts/includes/assets: use `al_folio_core`.
+- CV rendering: use `al_folio_cv`.
+- Distill runtime: use `al_folio_distill`.
+- Search/icons/math/comments/analytics/citations/external posts/newsletter/charts/images: use the owning `al-*` plugin repo.
+
+## Handoff
+
+Summarize changed files, validation results, and any local overrides created.

.agents/skills/al-folio-v1-migration/SKILL.md

@@ -0,0 +1,42 @@
+# al-folio v1 Migration
+
+Use this skill when a user asks an agent to migrate an existing customized al-folio fork to v1.x.
+
+## Workflow
+
+1. Work in a disposable branch, fork, or clone. Do not overwrite the user's original site.
+2. Start from the v1 starter contract, then bring over site-owned files:
+   - `_config.yml` values
+   - `_data`
+   - `_bibliography`
+   - content collections
+   - site assets
+   - intentional local `_includes`, `_layouts`, and `_sass` overrides
+3. Keep v1 plugin wiring from the starter:
+   - `theme: al_folio_core`
+   - bundled `al_*` and `al_folio_*` gems in `Gemfile`
+   - bundled plugin entries in `_config.yml`
+4. Remove stale copied runtime files now owned by plugins unless they are intentional overrides.
+5. Run upgrade checks:
+
+```bash
+bundle exec al-folio upgrade audit --no-fail
+bundle exec al-folio upgrade overrides audit
+```
+
+6. For each stale or unacknowledged override:
+
+```bash
+bundle exec al-folio upgrade overrides diff LOCAL_PATH
+bundle exec al-folio upgrade overrides accept LOCAL_PATH
+```
+
+7. Build and inspect key pages: home, CV, publications, repositories, projects, posts, and any custom routes.
+
+## Migration Notes
+
+Commit `.al-folio-overrides.yml` when the site intentionally keeps local overrides. It records the upstream plugin file checksum last reviewed so future gem updates can flag drift explicitly.
+
+## Handoff
+
+Report removed stale runtime files, retained local overrides, unresolved visual differences, and exact validation commands.

.al-folio-overrides.yml

@@ -0,0 +1,17 @@
+---
+version: 1
+overrides:
+  _includes/footer.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.11
+    upstream_path: _includes/footer.liquid
+    upstream_sha256: 65219faad5445eb4456649d77921acd07845875bbcad4fb8f33b12b3d52d96d2
+    local_sha256: b6061a4217004a3c76854987e94c5118df331751fc182d3dabb7604febf800ab
+    acknowledged_at: '2026-07-26'
+  assets/css/main.scss:
+    owner: al_folio_core
+    gem_version: 1.0.11
+    upstream_path: assets/css/main.scss
+    upstream_sha256: 437c6c911c596391413e435dc0ea7095e682e85c572c1fd3fff69f9597455b3e
+    local_sha256: 8d1cfe2593a7ae21ddfc17d7ad68547d32de05cad002317d67953baee84d1c89
+    acknowledged_at: '2026-07-26'

.all-contributorsrc

@@ -15,14 +15,14 @@
       "login": "alshedivat",
       "name": "Maruan",
       "avatar_url": "https://avatars.githubusercontent.com/u/2126561?v=4",
-      "profile": "http://maruan.alshedivat.com",
+      "profile": "https://maruan.alshedivat.com",
       "contributions": ["design", "code"]
     },
     {
       "login": "rohandebsarkar",
       "name": "Rohan Deb Sarkar",
       "avatar_url": "https://avatars.githubusercontent.com/u/50144004?v=4",
-      "profile": "http://rohandebsarkar.github.io",
+      "profile": "https://rohandebsarkar.github.io",
       "contributions": ["code"]
     },
     {

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

.codex/skills

@@ -0,0 +1 @@
+../.agents/skills

.devcontainer/Dockerfile

@@ -0,0 +1,7 @@
+FROM mcr.microsoft.com/devcontainers/jekyll
+
+# Fix: Remove the broken Yarn repository from the apt sources.
+# This prevents 'apt-get update' from failing due to the missing GPG key.
+# (Yarn is already provided by the dev container features/nvm, so this system repo is unnecessary)
+# See issue #3487
+RUN rm -f /etc/apt/sources.list.d/yarn.list

.devcontainer/devcontainer.json

@@ -2,14 +2,17 @@
 // README at: https://github.com/devcontainers/templates/tree/main/src/jekyll
 {
   "name": "Jekyll",
-  "image": "mcr.microsoft.com/devcontainers/jekyll",
+  // Using a Dockerfile to fix the broken Yarn repository. See issue #3487.
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
 
   // Features to add to the dev container. More info: https://containers.dev/features.
   "features": {
     "ghcr.io/rocker-org/devcontainer-features/apt-packages:1": {
       "packages": "build-essential,imagemagick,inotify-tools,jupyter-nbconvert,procps,ruby-full,zlib1g-dev"
     },
-    "ghcr.io/devcontainers-contrib/features/prettier:1": {}
+    "ghcr.io/devcontainers-extra/features/prettier:1.0.2": {}
   },
 
   // Optionally: run jekyll serve automatically on container entering using the Docker entrypoint

.gemini/settings.json

@@ -0,0 +1,17 @@
+{
+  "context": {
+    "fileName": [
+      "AGENTS.md",
+      ".github/copilot-instructions.md",
+      ".github/agents/customize.agent.md",
+      ".github/agents/docs.agent.md",
+      ".github/instructions/**/*.md",
+      "docs/README.md",
+      "docs/CUSTOMIZE.md",
+      "docs/INSTALL.md",
+      "docs/TROUBLESHOOTING.md",
+      "docs/QUICKSTART.md",
+      "docs/BOUNDARIES.md"
+    ]
+  }
+}

.gitattributes

@@ -0,0 +1,2 @@
+# Force LF line endings, needed for Docker to work on Windows
+*.sh text eol=lf

.github/GIT_WORKFLOW.md

@@ -0,0 +1,47 @@
+# Git Workflow
+
+This document outlines the conventions for using Git and writing commit messages in this project.
+
+## Commit Message Format
+
+All commit messages should follow this format:
+
+```
+<type>: <subject>
+
+<body (optional)>
+```
+
+**Types:**
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
+- `config`: Changes to configuration files
+- `chore`: Changes to the build process or auxiliary tools and libraries
+
+**Examples:**
+
+```
+feat: Add dark mode toggle button to header
+fix: Correct baseurl in project site configuration
+docs: Update docs/INSTALL.md with Docker troubleshooting
+style: Format all Liquid templates with Prettier
+config: Enable blog section in _config.yml
+chore: Update Jekyll dependencies with bundle update --all
+```
+
+## Staging Changes
+
+**Always `git add` files explicitly.** Do not stage everything with `git add .` unless you are certain of what's being committed. Check `git status` first to review your changes.
+
+## What NOT to Commit
+
+**Always obey the project's [`.gitignore`](../.gitignore) file.** It prevents the accidental commit of:
+
+- Build outputs (`_site/`, `.jekyll-cache/`)
+- Dependencies (`node_modules/`, `vendor/`)
+- OS-specific files (`.DS_store`)
+- Editor temporary files (`.idea/`, `.swp`, `.swo`)
+- Secrets and API keys (never commit credentials)

.github/ISSUE_TEMPLATE/1_bug_report.yml

@@ -7,8 +7,8 @@ body:
       value: >
         Before you go any further. Is this really a **🐛 bug**?
 
-        If it's a question about how al-folio works, have a look at our [documentation](https://github.com/alshedivat/al-folio/blob/master/README.md),
-        [frequently asked questions](https://github.com/alshedivat/al-folio/blob/master/FAQ.md),
+        If it's a question about how al-folio works, have a look at our [documentation](https://github.com/alshedivat/al-folio/blob/main/README.md),
+        [frequently asked questions](https://github.com/alshedivat/al-folio/blob/main/docs/FAQ.md),
         [past questions](https://github.com/alshedivat/al-folio/discussions/categories/q-a),
         or [ask a question](https://github.com/alshedivat/al-folio/discussions/new?category=q-a).
 
@@ -20,7 +20,7 @@ body:
         Please check if somebody else has already filed the same issue.
         If you find a similar issue, please add a 👍 reaction or comment on the original post.
       options:
-        - label: I read through [FAQ](https://github.com/alshedivat/al-folio/blob/master/FAQ.md) and searched through the [past issues](https://github.com/alshedivat/al-folio/issues), none of which addressed my issue.
+        - label: I read through [FAQ](https://github.com/alshedivat/al-folio/blob/main/docs/FAQ.md) and searched through the [past issues](https://github.com/alshedivat/al-folio/issues), none of which addressed my issue.
           required: true
         - label: Yes, I have checked that this issue isn't already filed.
           required: true
@@ -81,7 +81,8 @@ body:
       description: select all environments where you have experienced this issue
       multiple: true
       options:
-        - "Running locally with Docker"
+        - "Running locally with Docker (docker compose)"
+        - "Running locally with Docker (devcontainer)"
         - "Running locally without Docker"
         - "Deployed site"
     validations:

.github/ISSUE_TEMPLATE/2_feature_request.yml

@@ -7,8 +7,8 @@ body:
       value: >
         Before you go any further, are you sure that this feature is not already implemented?
 
-        If it's a question about how al-folio works, have a look at our [documentation](https://github.com/alshedivat/al-folio/blob/master/README.md),
-        [frequently asked questions](https://github.com/alshedivat/al-folio/blob/master/FAQ.md),
+        If it's a question about how al-folio works, have a look at our [documentation](https://github.com/alshedivat/al-folio/blob/main/README.md),
+        [frequently asked questions](https://github.com/alshedivat/al-folio/blob/main/docs/FAQ.md),
         [past questions](https://github.com/alshedivat/al-folio/discussions/categories/q-a),
         or [ask a question](https://github.com/alshedivat/al-folio/discussions/new?category=q-a).
 
@@ -20,7 +20,7 @@ body:
         Please check if somebody else has already filed the same 🚀 feature request.
         If you find a similar feature request, please add a 👍 reaction or comment on the original post.
       options:
-        - label: I read through [FAQ](https://github.com/alshedivat/al-folio/blob/master/FAQ.md) and searched through the [past issues](https://github.com/alshedivat/al-folio/issues), none of which addressed my feature request.
+        - label: I read through [FAQ](https://github.com/alshedivat/al-folio/blob/main/docs/FAQ.md) and searched through the [past issues](https://github.com/alshedivat/al-folio/issues), none of which addressed my feature request.
           required: true
         - label: Yes, I have checked that this feature request isn't already filed.
           required: true

.github/ISSUE_TEMPLATE/3_plugin_feature_proposal.yml

@@ -0,0 +1,112 @@
+name: "🔌 Plugin feature proposal"
+description: Propose a plugin to be listed (featured) or bundled in al-folio.
+labels: ["needs triage", "plugin-ecosystem"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Use this template to propose adding a plugin to the `al-folio` ecosystem catalog.
+        Featuring and bundling are separate decisions.
+
+  - type: checkboxes
+    id: requirements
+    attributes:
+      label: Proposal checklist
+      options:
+        - label: I confirmed this plugin is not already listed in `_data/featured_plugins.yml`.
+          required: true
+        - label: I understand that featuring does not automatically mean bundling.
+          required: true
+
+  - type: input
+    id: plugin_name
+    attributes:
+      label: Plugin name
+      description: Human-readable plugin name.
+      placeholder: al_folio_example
+    validations:
+      required: true
+
+  - type: input
+    id: repo_url
+    attributes:
+      label: Repository URL
+      description: Public repository URL for the plugin.
+      placeholder: https://github.com/your-org/al-folio-example
+    validations:
+      required: true
+
+  - type: input
+    id: gem_name
+    attributes:
+      label: Gem name
+      description: Name published on RubyGems.
+      placeholder: al_folio_example
+    validations:
+      required: true
+
+  - type: input
+    id: plugin_id
+    attributes:
+      label: Jekyll plugin ID
+      description: Plugin id used in `_config.yml` plugins list.
+      placeholder: al_folio_example
+    validations:
+      required: true
+
+  - type: dropdown
+    id: plugin_scope
+    attributes:
+      label: Plugin scope
+      description: Does this plugin depend on al-folio-specific runtime contracts?
+      options:
+        - Theme-coupled (al-folio-specific)
+        - Reusable (works outside al-folio)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: requested_track
+    attributes:
+      label: Requested track
+      description: Which listing track are you proposing?
+      options:
+        - Featured-only
+        - Bundled in starter
+    validations:
+      required: true
+
+  - type: input
+    id: compatibility
+    attributes:
+      label: Compatibility range
+      description: al-folio versions supported by this plugin.
+      placeholder: "al_folio_min: 1.0.0, al_folio_max: 1.x"
+    validations:
+      required: true
+
+  - type: input
+    id: demo_path
+    attributes:
+      label: Demo page/post URL
+      description: Public demo path showing the plugin in action.
+      placeholder: https://your-site.example/plugins/my-plugin-demo
+    validations:
+      required: true
+
+  - type: input
+    id: maintainer_contact
+    attributes:
+      label: Maintainer contact
+      description: Primary maintainer handle or contact URL.
+      placeholder: https://github.com/your-handle
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional notes
+      description: Add context, migration notes, or caveats.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -4,5 +4,5 @@ contact_links:
     url: https://github.com/alshedivat/al-folio/discussions/categories/q-a
     about: Ask and answer al-folio related questions.
   - name: 📖 Read the documentation
-    url: https://github.com/alshedivat/al-folio/blob/master/README.md
+    url: https://github.com/alshedivat/al-folio/blob/main/README.md
     about: Please consult the documentation before opening any issues!