@@ -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.
@@ -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.
@@ -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'
@@ -0,0 +1 @@
+../.agents/skills
@@ -0,0 +1 @@
+../.agents/skills
@@ -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
@@ -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": {
 
@@ -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"
+    ]
+  }
+}
@@ -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)
@@ -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