Update to 1.1

.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,59 @@
+---
+version: 1
+overrides:
+  _includes/figure.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _includes/figure.liquid
+    upstream_sha256: d094ba62f74e50ec9a3a7aca01d41f3d499f7fb3bc3507ca8aecd946347132bb
+    local_sha256: 54902b218d44582081573b9d469e395e24e8cf3323e148e32f7b08a0207b3ac7
+    acknowledged_at: '2026-07-30'
+  _includes/footer.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _includes/footer.liquid
+    upstream_sha256: 65219faad5445eb4456649d77921acd07845875bbcad4fb8f33b12b3d52d96d2
+    local_sha256: f2d392f9dd6d468a73615d829b381e05ded1c31e77d316050b2d0f60d6121c28
+    acknowledged_at: '2026-07-30'
+  _includes/header.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _includes/header.liquid
+    upstream_sha256: c8663513baded68d9fa5fbe4d6363a976535bbe201efe5138243d0ff03101058
+    local_sha256: aaaacc7589d2a3a8758fcde44efed858b6fff7ebda6b8af18616d5a2b3168a7b
+    acknowledged_at: '2026-07-30'
+  _includes/repository/repo.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _includes/repository/repo.liquid
+    upstream_sha256: ce87ac70cb6a8e2b1ed708b0418c638ebc4e59c4198de68bff0fc39cd5a01087
+    local_sha256: 204440d391995038c509dbefe05c05ab199a7198c71cb6aaaf9e4ebf26195a96
+    acknowledged_at: '2026-07-30'
+  _layouts/about.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _layouts/about.liquid
+    upstream_sha256: 2c28eb83b71fe65f252202c11f0b4a19a9b6f1faccdc870b4f91c4ea51d0c6f1
+    local_sha256: 3f621e36c62f6521f57602e5e711f0b7e1a1d54c02c74cfddff2ceec2fc524b8
+    acknowledged_at: '2026-07-30'
+  _layouts/bib.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _layouts/bib.liquid
+    upstream_sha256: 430311d9b94adf6fb1c2fab7609f6e726efc98e2b50e7b1c4cde0ad654c04506
+    local_sha256: 7119a1649bfc5822a4d111e6b2cdc5c21ec1cc2d4cb84627f3aae78a96f81b88
+    acknowledged_at: '2026-07-30'
+  _layouts/page.liquid:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: _layouts/page.liquid
+    upstream_sha256: eb392ada31cdbe8d1a0f5dbd7229700b5fa7cdf6f4788cbb65d6b746ac3b1231
+    local_sha256: 6088ab8a58b2f3ae7d42068980747e333471800e6493fd9fa0e7e34a1ccc5c1a
+    acknowledged_at: '2026-07-30'
+  assets/css/main.scss:
+    owner: al_folio_core
+    gem_version: 1.0.12
+    upstream_path: assets/css/main.scss
+    upstream_sha256: 437c6c911c596391413e435dc0ea7095e682e85c572c1fd3fff69f9597455b3e
+    local_sha256: 961c4d03034dd7d13dee2c34f2a533110706aaea8931c262ece0cd2f4045546f
+    acknowledged_at: '2026-07-30'

.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,7 +2,10 @@
 // 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": {

.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"
+    ]
+  }
+}

.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/main/README.md),
-        [frequently asked questions](https://github.com/alshedivat/al-folio/blob/main/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/docs/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/main/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

.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/main/README.md),
-        [frequently asked questions](https://github.com/alshedivat/al-folio/blob/main/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/docs/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/main/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,8 @@ 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/main/README.md
+    url: https://github.com/alshedivat/al-folio/blob/main/docs/README.md
     about: Please consult the documentation before opening any issues!
+  - name: ⭐ Add your site to the showcase
+    url: https://github.com/alshedivat/al-folio/discussions
+    about: Request a listing in the Showcase category of GitHub Discussions. Entries are reviewed and added periodically — please do not open a pull request.