chore: Merge al-folio v1.0 upstream updates

Author: garywei944

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

.claude/skills

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

.codex/skills

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

.gemini/settings.json

@@ -6,10 +6,12 @@
       ".github/agents/customize.agent.md",
       ".github/agents/docs.agent.md",
       ".github/instructions/**/*.md",
-      "CUSTOMIZE.md",
-      "INSTALL.md",
-      "TROUBLESHOOTING.md",
-      "QUICKSTART.md"
+      "docs/README.md",
+      "docs/CUSTOMIZE.md",
+      "docs/INSTALL.md",
+      "docs/TROUBLESHOOTING.md",
+      "docs/QUICKSTART.md",
+      "docs/BOUNDARIES.md"
     ]
   }
 }

.github/GIT_WORKFLOW.md

@@ -26,7 +26,7 @@ All commit messages should follow this format:
 ```
 feat: Add dark mode toggle button to header
 fix: Correct baseurl in project site configuration
-docs: Update INSTALL.md with Docker troubleshooting
+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

.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