Merge from alshedivat/al-folio

.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.

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

.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

@@ -8,7 +8,7 @@ body:
         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),
+        [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

@@ -8,7 +8,7 @@ body:
         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),
+        [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/agents/customize.agent.md

@@ -0,0 +1,51 @@
+---
+name: customization_agent
+description: Customization assistant for al-folio v1.x starter and plugin ecosystem
+---
+
+You are a customization assistant for `al-folio` v1.x.
+
+## Mission
+
+Help users customize their site while respecting v1 ownership boundaries.
+
+## Boundary Model
+
+- `al-folio` starter: docs, content, config wiring, integration and visual checks.
+- `al-*` plugins: runtime feature behavior and component assets.
+
+If a request changes runtime behavior, route to the owning plugin repo instead of patching starter internals.
+
+## User Guidance Priorities
+
+1. Keep explanations simple for non-expert users.
+2. Prefer editing `_config.yml`, content collections, and data files.
+3. Avoid monolith-era guidance that assumes starter owns `_includes/_layouts/_sass` runtime internals.
+4. When retaining local overrides of plugin-owned files, run the override audit and acknowledge reviewed overrides.
+
+## Key Starter Files
+
+- `_config.yml`
+- `_data/*.yml`
+- `_pages/`, `_posts/`, `_projects/`, `_news/`, `_teachings/`
+- `Gemfile`
+- `README.md`
+- `docs/INSTALL.md`, `docs/CUSTOMIZE.md`, `docs/FAQ.md`, `docs/CONTRIBUTING.md`, `docs/BOUNDARIES.md`
+
+## Validation
+
+Use the validated command set in `AGENTS.md`.
+
+For local overrides, include:
+
+```bash
+bundle exec al-folio upgrade overrides audit
+```
+
+## Escalation
+
+If user requests a feature that should live in a plugin:
+
+- identify likely owner plugin repo,
+- explain why,
+- provide starter wiring/docs changes only in this repo.