{"owner":"alshedivat","repo":"al-folio","hasSkills":true,"totalSkillsCount":8,"totalTokensCount":4644,"categories":["claude-rule","copilot-instructions","codex-rule","anthropic-skill","root-instruction","subagent-persona"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md",".github/copilot-instructions.md",".codex/skills",".agents/skills/al-folio-v1-migration/SKILL.md",".agents/skills/al-folio-bootstrap/SKILL.md","AGENTS.md",".github/agents/docs.agent.md",".github/agents/customize.agent.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n@AGENTS.md\n\n`AGENTS.md` (imported above) is the **authoritative** agent entry point: change routing, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. Keep it short and ecosystem-neutral. Cross-repo architecture — the wrapper/tag/gem delegation table, feature gating, the v1 config contract, local overrides — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); area-to-gem ownership lives in [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md).\n\n**Read those three before editing anything.** Everything below is Claude-specific or longer-form operational detail that does not belong in the short entry point. Do not restate facts from those files here — link to them.\n\n## Daily dev loop\n\n```bash\nbundle install                                # ruby gems\nbundle exec jekyll serve                      # dev server → http://localhost:4000/al-folio/  (NOTE baseurl)\nbundle exec jekyll build --baseurl /al-folio  # production-style build to _site/\nbash test/integration_distill.sh              # run ONE integration test (any of the seven in test/)\nnpm run test:visual:update                    # refresh playwright snapshots after intentional UI change\nbundle exec al-folio upgrade apply --safe     # deterministic codemods (font-weight-* → font-*, remote→local URLs)\nbundle exec al-folio upgrade overrides diff <path>    # then `overrides accept <path>` to acknowledge an override\n```\n\n## Optional toolchains\n\n- **Jupyter posts.** `bin/setup-python-deps` installs _only_ `jupyter` and `nbconvert` (via `pip --user --break-system-packages`) for `jekyll-jupyter-notebook`. It does **not** read `requirements.txt`. Missing `jupyter-nbconvert` is warn-and-continue; notebook rendering is skipped.\n- **Everything else Python.** [`requirements.txt`](requirements.txt) is the fuller list and must be installed separately (`python3 -m pip install -r requirements.txt`): `rendercv[full]` for CV rendering, `scholarly` for `bin/update_scholar_citations.py`, plus `nbconvert` and `pyyaml`.\n- **Responsive images.** `imagemagick.enabled: true` needs ImageMagick `convert` on `PATH`.\n- **Manual deploy.** `bin/deploy` is the manual `gh-pages` build + purgecss + force-push path; CI normally deploys. `purgecss` is not a devDependency — install it with `npm install -g purgecss`.\n\n## Docker serving model (v1-specific)\n\n`docker compose up -d` bind-mounts the repo to `/srv/jekyll` and runs `bin/entry_point.sh`, which serves with `--force_polling --destination /tmp/_site`. The build output deliberately goes to **container-local `/tmp/_site`, not the bind-mounted `_site`** — writing `_site` back across the host bind mount caused write deadlocks. The container also `inotifywait`s `_config.yml` and restarts Jekyll on change (config edits aren't hot-reloaded by `--watch`). Verify with the `/al-folio` baseurl: `curl -fsS http://127.0.0.1:8080/al-folio/`. `docker-compose-slim.yml` pulls a prebuilt `:slim` image instead of building locally.\n\n## CI gates and the style contract\n\n`npm run lint:style-contract` (`test/style_contract.js`) is the automated enforcement of the thin-starter boundary and will fail CI if you cross it. Beyond the forbidden paths listed in `AGENTS.md`, it also asserts that `_config.yml` keeps `theme: al_folio_core` and the required plugins, that the `third_party_libraries` SRI pins are present, and that the `al_math` Gemfile pin stays on a released version rather than a git branch.\n\nOther gates:\n\n- `unit-tests.yml` — style contract plus all seven `test/integration_*.sh` scripts (`comments`, `plugin_toggles`, `distill`, `bootstrap_compat`, `upgrade_cli`, `css_minify`, `new_plugins`).\n- `visual-regression.yml` — Playwright on chromium + webkit, diffing the candidate build against a `v0.16.3` baseline worktree served on `:4100` via `BASELINE_URL`.\n- `upgrade-check.yml` — `bundle exec al-folio upgrade audit`.\n- `prettier.yml` — Prettier with `@shopify/prettier-plugin-liquid` and `printWidth: 150`. Run `npm run lint:prettier` before pushing; `npx prettier . --write` fixes.\n- `update-tocs.yml` — regenerates `<!--ts-->…<!--te-->` blocks in changed root and `docs/` Markdown files. If you add or rename a heading, expect a follow-up auto-commit on `main`.\n\n## Gem version pins\n\n`Gemfile` pins every `al-*` gem to an exact released version in `group :al_folio_plugins`, and `_config.yml` lists the same gems under `plugins:`. Read the current pins from the `Gemfile` rather than trusting any version quoted in prose — including here. To test a gem fix against this site, repoint the `Gemfile` at a sibling checkout (`path:`, `git:`, or `branch:`) and `bundle install`; see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#working-on-a-gem-alongside-the-starter). Revert the pin before committing.\n",".github/copilot-instructions.md":"# Copilot Coding Agent Instructions (v1.x)\n\n**Read [`AGENTS.md`](../AGENTS.md) first — it is the authoritative entry point for all coding agents in this repo.** It carries the change-routing table, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. This file previously duplicated that content; it is now a pointer so the rules cannot drift apart.\n\nIn short: `al-folio` v1.x is a **thin Jekyll starter, not a theme**. It owns starter wiring (`Gemfile`, `_config.yml`), example content, docs, integration tests, and visual parity tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems under [`al-org-dev`](https://github.com/al-org-dev). Route runtime changes to the owning gem.\n\n## Where to look\n\n| Question                             | File                                                                                          |\n| ------------------------------------ | --------------------------------------------------------------------------------------------- |\n| Which repo does my change belong in? | [`AGENTS.md`](../AGENTS.md#route-your-change)                                                 |\n| Which gem owns this area?            | [`docs/BOUNDARIES.md`](../docs/BOUNDARIES.md)                                                 |\n| Which gem owns this Liquid tag?      | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation)            |\n| Why did my feature render nothing?   | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) |\n| What commands should I run?          | [`AGENTS.md`](../AGENTS.md#validated-local-command-set)                                       |\n| How do I contribute?                 | [`docs/CONTRIBUTING.md`](../docs/CONTRIBUTING.md)                                             |\n\n## Copilot-specific paths\n\n- `.github/agents/` — custom agents (`customize.agent.md`, `docs.agent.md`).\n- `.github/instructions/` — per-file-type instruction files (Liquid, YAML, BibTeX, Markdown, JavaScript).\n- `.github/workflows/copilot-setup-steps.yml` — pre-installs Ruby, Python, Node, ImageMagick, and nbconvert for the coding agent.\n- `.agents/skills/` — canonical agent skills, also exposed via the `.codex/skills` and `.claude/skills` symlinks.\n\n## CI expectations\n\nKeep these workflows aligned when changing starter behavior: `unit-tests.yml` (style contract plus all six `test/integration_*.sh` scripts), `visual-regression.yml`, `upgrade-check.yml`, `prettier.yml`, and `deploy.yml`.\n",".codex/skills":"../.agents/skills",".agents/skills/al-folio-v1-migration/SKILL.md":"# al-folio v1 Migration\n\nUse this skill when a user asks an agent to migrate an existing customized al-folio fork to v1.x.\n\n## Workflow\n\n1. Work in a disposable branch, fork, or clone. Do not overwrite the user's original site.\n2. Start from the v1 starter contract, then bring over site-owned files:\n   - `_config.yml` values\n   - `_data`\n   - `_bibliography`\n   - content collections\n   - site assets\n   - intentional local `_includes`, `_layouts`, and `_sass` overrides\n3. Keep v1 plugin wiring from the starter:\n   - `theme: al_folio_core`\n   - bundled `al_*` and `al_folio_*` gems in `Gemfile`\n   - bundled plugin entries in `_config.yml`\n4. Remove stale copied runtime files now owned by plugins unless they are intentional overrides.\n5. Run upgrade checks:\n\n```bash\nbundle exec al-folio upgrade audit --no-fail\nbundle exec al-folio upgrade overrides audit\n```\n\n6. For each stale or unacknowledged override:\n\n```bash\nbundle exec al-folio upgrade overrides diff LOCAL_PATH\nbundle exec al-folio upgrade overrides accept LOCAL_PATH\n```\n\n7. Build and inspect key pages: home, CV, publications, repositories, projects, posts, and any custom routes.\n\n## Migration Notes\n\nCommit `.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.\n\n## Handoff\n\nReport removed stale runtime files, retained local overrides, unresolved visual differences, and exact validation commands.\n",".agents/skills/al-folio-bootstrap/SKILL.md":"# al-folio Bootstrap\n\nUse this skill when a user asks an agent to create, configure, or personalize a new al-folio v1.x website.\n\n## Workflow\n\n1. Read `AGENTS.md` and `docs/BOUNDARIES.md` before editing.\n2. Keep the starter small: customize `_config.yml`, `_data`, content collections, and site assets first.\n3. 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.\n4. For local visual/content customization, prefer:\n   - `_config.yml` feature flags and site metadata\n   - `_data/*.yml`\n   - `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_bibliography`\n   - local `_includes`, `_layouts`, and `_sass` overrides only when config/content cannot express the change\n5. Run validation before handing work back:\n\n```bash\nnpm ci\nnpm run lint:prettier\nbundle exec al-folio upgrade audit --no-fail\nbundle exec jekyll build --baseurl /al-folio\n```\n\n## Routing\n\n- Starter wiring/docs/examples/tests: edit `al-folio`.\n- Shared layouts/includes/assets: use `al_folio_core`.\n- CV rendering: use `al_folio_cv`.\n- Distill runtime: use `al_folio_distill`.\n- Search/icons/math/comments/analytics/citations/external posts/newsletter/charts/images: use the owning `al-*` plugin repo.\n\n## Handoff\n\nSummarize changed files, validation results, and any local overrides created.\n","AGENTS.md":"# Agent Guidelines for al-folio (v1.x)\n\n**This file is the authoritative entry point for coding agents working in this repo.** Read it before making any change. It is intentionally short and tool-neutral; it links to the one place each longer-form fact lives.\n\n`al-folio` v1.x is a **thin Jekyll starter, not a theme**. This repo owns starter wiring, example content, docs, and cross-plugin tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems published under [`al-org-dev`](https://github.com/al-org-dev).\n\n## Route your change\n\nFind your change on the left; edit only what is on the right.\n\n| Your change                                                                                                              | Goes in                                                                                                       |\n| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |\n| Dependency pin, plugin activation, feature flag                                                                          | this repo: `Gemfile` **and** `_config.yml` (both — see below)                                                 |\n| Example/demo content, bibliography, data files                                                                           | this repo: `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_books`, `_data`                          |\n| Documentation                                                                                                            | this repo: `docs/` (long-form) or this file (agent rules)                                                     |\n| Cross-plugin integration test, visual parity test                                                                        | this repo: `test/integration_*.sh`, `test/visual/`                                                            |\n| Plugin catalog metadata                                                                                                  | this repo: `_data/featured_plugins.yml`                                                                       |\n| A layout, include, or Sass partial                                                                                       | the owning gem — start with `al_folio_core`                                                                   |\n| A Liquid tag or filter, or what a tag renders                                                                            | the gem that registers it — see the [delegation table](docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation) |\n| Feature behavior (search, math, charts, comments, cookies, icons, CV, distill, analytics, images, newsletter, citations) | that feature's gem — see [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md)                                           |\n| Component/unit test for gem-owned behavior                                                                               | the owning gem, not here                                                                                      |\n| A feature with no existing owner                                                                                         | open a plugin proposal issue first, then a standalone plugin repo                                             |\n\n[`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) is the authoritative area-to-gem table. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) explains how the pieces connect.\n\n## Stop sign\n\n**If your change would create any of these paths in this repo, it belongs in a gem instead:**\n\n```\n_layouts/   _includes/   _sass/   _scripts/   assets/tailwind/   tailwind.config.js   assets/webfonts/\n```\n\n`npm run lint:style-contract` fails CI when any of them exists here, and it also rejects `build:css` / `build:tailwind` npm scripts. Do not add a starter-local Tailwind or CSS build pipeline.\n\nThis restriction applies to **this repo only**. A user's own site created from this template _may_ legally shadow gem-owned files — see [local overrides: your site vs. this repo](docs/ARCHITECTURE.md#local-overrides-your-site-vs-this-repo).\n\n## Three failures that produce no error message\n\nRead [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) for the full explanation. The short version:\n\n1. **Features fail silently.** A feature renders only when its gem is loaded _and_ its flag is on _and_ the page opts in. Otherwise the Liquid tag emits an empty string — no warning, no error.\n2. **`Gemfile` and `_config.yml` are two lists that must agree.** A plugin in only one of them is inert. Adding or removing a plugin means editing both. Repo dirs use hyphens (`al-folio-core`); gem/plugin ids use underscores (`al_folio_core`).\n3. **This repo's effective baseurl is `/al-folio`.** `_config.yml` already sets it, so a plain `bundle exec jekyll build` is correct — that is what `deploy.yml`, `broken-links-site.yml` and `axe.yml` run. Passing `--baseurl /al-folio` is redundant but harmless; blanking the baseurl out is what renders the site unstyled with broken links. Dev server is at `http://localhost:4000/al-folio/`.\n\n## Validated local command set\n\nRun from the repo root, in this order:\n\n```bash\nbundle install\nnpm ci\nnpm run lint:prettier\nnpm run lint:style-contract\nbundle exec jekyll build --baseurl /al-folio\nbash test/integration_comments.sh\nbash test/integration_plugin_toggles.sh\nbash test/integration_distill.sh\nbash test/integration_bootstrap_compat.sh\nbash test/integration_upgrade_cli.sh\nbash test/integration_css_minify.sh\nbash test/integration_new_plugins.sh\nnpx playwright install chromium webkit\nnpm run test:visual\nbundle exec al-folio upgrade audit\nbundle exec al-folio upgrade overrides audit\nbundle exec al-folio upgrade report\ndocker compose up -d\ncurl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null\ndocker compose logs --tail=80\ndocker compose down\n```\n\nAll seven `test/integration_*.sh` scripts are gated by `unit-tests.yml`; run the ones your change touches. Docker note: v1 uses `/srv/jekyll/bin/entry_point.sh` and serves from container-local `/tmp/_site` to avoid host bind-mount write deadlocks.\n\n## Before you open a PR\n\n- Keep starter work here; route runtime behavior to the owning plugin repo.\n- Run `npm run lint:prettier` (Prettier with `@shopify/prettier-plugin-liquid`, `printWidth: 150`). `npx prettier . --write` fixes formatting.\n- Keep docs aligned with v1 ownership, and keep each fact in one place — link rather than restate.\n- If you create or keep local overrides of plugin-owned files, run `bundle exec al-folio upgrade overrides audit` and commit `.al-folio-overrides.yml` after review.\n\n## Further reading\n\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how the starter and gems fit together, silent failure modes, the v1 config contract, local overrides.\n- [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) — authoritative area-to-gem ownership table and PR triage playbook.\n- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — contributor workflow and agent tooling.\n- [`docs/README.md`](docs/README.md) — index of all user and maintainer guides.\n- `.agents/skills/al-folio-bootstrap/SKILL.md` — new-site setup workflow.\n- `.agents/skills/al-folio-v1-migration/SKILL.md` — customized-fork migration and override drift auditing.\n- `.codex/skills` and `.claude/skills` are symlinks to `.agents/skills` for agent-specific discovery.\n",".github/agents/docs.agent.md":"---\nname: docs_agent\ndescription: Documentation specialist for al-folio v1.x\n---\n\nYou are the documentation specialist for `al-folio` v1.x.\n\n## Documentation Objective\n\nKeep starter docs accurate for the pluginized architecture.\n\n## Non-Negotiable Rules\n\n- Do not document `al-folio` as a monolithic runtime theme.\n- Reflect starter-vs-plugin boundaries from `docs/BOUNDARIES.md`.\n- Keep contributor routing explicit: starter changes here, feature/runtime changes in owning plugin repos.\n- Avoid stale bootstrap-era instructions unless clearly marked compatibility-only.\n- Keep migration guidance aligned with `al_folio_upgrade`, including the local override audit workflow.\n\n## Core Docs to Maintain\n\n- `README.md`\n- `docs/README.md`\n- `docs/INSTALL.md`\n- `docs/CUSTOMIZE.md`\n- `docs/FAQ.md`\n- `docs/CONTRIBUTING.md`\n- `docs/BOUNDARIES.md`\n- `.github/copilot-instructions.md`\n- `.agents/skills/al-folio-bootstrap/SKILL.md`\n- `.agents/skills/al-folio-v1-migration/SKILL.md`\n\n## Validation\n\nUse commands from `AGENTS.md` and ensure documented commands are current and runnable.\n\n## Style\n\n- Be concise and practical.\n- Prefer links over duplicated long instructions.\n- Use repository-real file paths and commands.\n",".github/agents/customize.agent.md":"---\nname: customization_agent\ndescription: Customization assistant for al-folio v1.x starter and plugin ecosystem\n---\n\nYou are a customization assistant for `al-folio` v1.x.\n\n## Mission\n\nHelp users customize their site while respecting v1 ownership boundaries.\n\n## Boundary Model\n\n- `al-folio` starter: docs, content, config wiring, integration and visual checks.\n- `al-*` plugins: runtime feature behavior and component assets.\n\nIf a request changes runtime behavior, route to the owning plugin repo instead of patching starter internals.\n\n## User Guidance Priorities\n\n1. Keep explanations simple for non-expert users.\n2. Prefer editing `_config.yml`, content collections, and data files.\n3. Avoid monolith-era guidance that assumes starter owns `_includes/_layouts/_sass` runtime internals.\n4. When retaining local overrides of plugin-owned files, run the override audit and acknowledge reviewed overrides.\n\n## Key Starter Files\n\n- `_config.yml`\n- `_data/*.yml`\n- `_pages/`, `_posts/`, `_projects/`, `_news/`, `_teachings/`\n- `Gemfile`\n- `README.md`\n- `docs/INSTALL.md`, `docs/CUSTOMIZE.md`, `docs/FAQ.md`, `docs/CONTRIBUTING.md`, `docs/BOUNDARIES.md`\n\n## Validation\n\nUse the validated command set in `AGENTS.md`.\n\nFor local overrides, include:\n\n```bash\nbundle exec al-folio upgrade overrides audit\n```\n\n## Escalation\n\nIf user requests a feature that should live in a plugin:\n\n- identify likely owner plugin repo,\n- explain why,\n- provide starter wiring/docs changes only in this repo.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n@AGENTS.md\n\n`AGENTS.md` (imported above) is the **authoritative** agent entry point: change routing, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. Keep it short and ecosystem-neutral. Cross-repo architecture — the wrapper/tag/gem delegation table, feature gating, the v1 config contract, local overrides — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); area-to-gem ownership lives in [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md).\n\n**Read those three before editing anything.** Everything below is Claude-specific or longer-form operational detail that does not belong in the short entry point. Do not restate facts from those files here — link to them.\n\n## Daily dev loop\n\n```bash\nbundle install                                # ruby gems\nbundle exec jekyll serve                      # dev server → http://localhost:4000/al-folio/  (NOTE baseurl)\nbundle exec jekyll build --baseurl /al-folio  # production-style build to _site/\nbash test/integration_distill.sh              # run ONE integration test (any of the seven in test/)\nnpm run test:visual:update                    # refresh playwright snapshots after intentional UI change\nbundle exec al-folio upgrade apply --safe     # deterministic codemods (font-weight-* → font-*, remote→local URLs)\nbundle exec al-folio upgrade overrides diff <path>    # then `overrides accept <path>` to acknowledge an override\n```\n\n## Optional toolchains\n\n- **Jupyter posts.** `bin/setup-python-deps` installs _only_ `jupyter` and `nbconvert` (via `pip --user --break-system-packages`) for `jekyll-jupyter-notebook`. It does **not** read `requirements.txt`. Missing `jupyter-nbconvert` is warn-and-continue; notebook rendering is skipped.\n- **Everything else Python.** [`requirements.txt`](requirements.txt) is the fuller list and must be installed separately (`python3 -m pip install -r requirements.txt`): `rendercv[full]` for CV rendering, `scholarly` for `bin/update_scholar_citations.py`, plus `nbconvert` and `pyyaml`.\n- **Responsive images.** `imagemagick.enabled: true` needs ImageMagick `convert` on `PATH`.\n- **Manual deploy.** `bin/deploy` is the manual `gh-pages` build + purgecss + force-push path; CI normally deploys. `purgecss` is not a devDependency — install it with `npm install -g purgecss`.\n\n## Docker serving model (v1-specific)\n\n`docker compose up -d` bind-mounts the repo to `/srv/jekyll` and runs `bin/entry_point.sh`, which serves with `--force_polling --destination /tmp/_site`. The build output deliberately goes to **container-local `/tmp/_site`, not the bind-mounted `_site`** — writing `_site` back across the host bind mount caused write deadlocks. The container also `inotifywait`s `_config.yml` and restarts Jekyll on change (config edits aren't hot-reloaded by `--watch`). Verify with the `/al-folio` baseurl: `curl -fsS http://127.0.0.1:8080/al-folio/`. `docker-compose-slim.yml` pulls a prebuilt `:slim` image instead of building locally.\n\n## CI gates and the style contract\n\n`npm run lint:style-contract` (`test/style_contract.js`) is the automated enforcement of the thin-starter boundary and will fail CI if you cross it. Beyond the forbidden paths listed in `AGENTS.md`, it also asserts that `_config.yml` keeps `theme: al_folio_core` and the required plugins, that the `third_party_libraries` SRI pins are present, and that the `al_math` Gemfile pin stays on a released version rather than a git branch.\n\nOther gates:\n\n- `unit-tests.yml` — style contract plus all seven `test/integration_*.sh` scripts (`comments`, `plugin_toggles`, `distill`, `bootstrap_compat`, `upgrade_cli`, `css_minify`, `new_plugins`).\n- `visual-regression.yml` — Playwright on chromium + webkit, diffing the candidate build against a `v0.16.3` baseline worktree served on `:4100` via `BASELINE_URL`.\n- `upgrade-check.yml` — `bundle exec al-folio upgrade audit`.\n- `prettier.yml` — Prettier with `@shopify/prettier-plugin-liquid` and `printWidth: 150`. Run `npm run lint:prettier` before pushing; `npx prettier . --write` fixes.\n- `update-tocs.yml` — regenerates `<!--ts-->…<!--te-->` blocks in changed root and `docs/` Markdown files. If you add or rename a heading, expect a follow-up auto-commit on `main`.\n\n## Gem version pins\n\n`Gemfile` pins every `al-*` gem to an exact released version in `group :al_folio_plugins`, and `_config.yml` lists the same gems under `plugins:`. Read the current pins from the `Gemfile` rather than trusting any version quoted in prose — including here. To test a gem fix against this site, repoint the `Gemfile` at a sibling checkout (`path:`, `git:`, or `branch:`) and `bundle install`; see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#working-on-a-gem-alongside-the-starter). Revert the pin before committing.\n",".github/copilot-instructions.md":"# Copilot Coding Agent Instructions (v1.x)\n\n**Read [`AGENTS.md`](../AGENTS.md) first — it is the authoritative entry point for all coding agents in this repo.** It carries the change-routing table, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. This file previously duplicated that content; it is now a pointer so the rules cannot drift apart.\n\nIn short: `al-folio` v1.x is a **thin Jekyll starter, not a theme**. It owns starter wiring (`Gemfile`, `_config.yml`), example content, docs, integration tests, and visual parity tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems under [`al-org-dev`](https://github.com/al-org-dev). Route runtime changes to the owning gem.\n\n## Where to look\n\n| Question                             | File                                                                                          |\n| ------------------------------------ | --------------------------------------------------------------------------------------------- |\n| Which repo does my change belong in? | [`AGENTS.md`](../AGENTS.md#route-your-change)                                                 |\n| Which gem owns this area?            | [`docs/BOUNDARIES.md`](../docs/BOUNDARIES.md)                                                 |\n| Which gem owns this Liquid tag?      | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation)            |\n| Why did my feature render nothing?   | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) |\n| What commands should I run?          | [`AGENTS.md`](../AGENTS.md#validated-local-command-set)                                       |\n| How do I contribute?                 | [`docs/CONTRIBUTING.md`](../docs/CONTRIBUTING.md)                                             |\n\n## Copilot-specific paths\n\n- `.github/agents/` — custom agents (`customize.agent.md`, `docs.agent.md`).\n- `.github/instructions/` — per-file-type instruction files (Liquid, YAML, BibTeX, Markdown, JavaScript).\n- `.github/workflows/copilot-setup-steps.yml` — pre-installs Ruby, Python, Node, ImageMagick, and nbconvert for the coding agent.\n- `.agents/skills/` — canonical agent skills, also exposed via the `.codex/skills` and `.claude/skills` symlinks.\n\n## CI expectations\n\nKeep these workflows aligned when changing starter behavior: `unit-tests.yml` (style contract plus all six `test/integration_*.sh` scripts), `visual-regression.yml`, `upgrade-check.yml`, `prettier.yml`, and `deploy.yml`.\n",".codex/skills":"../.agents/skills",".agents/skills/al-folio-v1-migration/SKILL.md":"# al-folio v1 Migration\n\nUse this skill when a user asks an agent to migrate an existing customized al-folio fork to v1.x.\n\n## Workflow\n\n1. Work in a disposable branch, fork, or clone. Do not overwrite the user's original site.\n2. Start from the v1 starter contract, then bring over site-owned files:\n   - `_config.yml` values\n   - `_data`\n   - `_bibliography`\n   - content collections\n   - site assets\n   - intentional local `_includes`, `_layouts`, and `_sass` overrides\n3. Keep v1 plugin wiring from the starter:\n   - `theme: al_folio_core`\n   - bundled `al_*` and `al_folio_*` gems in `Gemfile`\n   - bundled plugin entries in `_config.yml`\n4. Remove stale copied runtime files now owned by plugins unless they are intentional overrides.\n5. Run upgrade checks:\n\n```bash\nbundle exec al-folio upgrade audit --no-fail\nbundle exec al-folio upgrade overrides audit\n```\n\n6. For each stale or unacknowledged override:\n\n```bash\nbundle exec al-folio upgrade overrides diff LOCAL_PATH\nbundle exec al-folio upgrade overrides accept LOCAL_PATH\n```\n\n7. Build and inspect key pages: home, CV, publications, repositories, projects, posts, and any custom routes.\n\n## Migration Notes\n\nCommit `.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.\n\n## Handoff\n\nReport removed stale runtime files, retained local overrides, unresolved visual differences, and exact validation commands.\n",".agents/skills/al-folio-bootstrap/SKILL.md":"# al-folio Bootstrap\n\nUse this skill when a user asks an agent to create, configure, or personalize a new al-folio v1.x website.\n\n## Workflow\n\n1. Read `AGENTS.md` and `docs/BOUNDARIES.md` before editing.\n2. Keep the starter small: customize `_config.yml`, `_data`, content collections, and site assets first.\n3. 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.\n4. For local visual/content customization, prefer:\n   - `_config.yml` feature flags and site metadata\n   - `_data/*.yml`\n   - `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_bibliography`\n   - local `_includes`, `_layouts`, and `_sass` overrides only when config/content cannot express the change\n5. Run validation before handing work back:\n\n```bash\nnpm ci\nnpm run lint:prettier\nbundle exec al-folio upgrade audit --no-fail\nbundle exec jekyll build --baseurl /al-folio\n```\n\n## Routing\n\n- Starter wiring/docs/examples/tests: edit `al-folio`.\n- Shared layouts/includes/assets: use `al_folio_core`.\n- CV rendering: use `al_folio_cv`.\n- Distill runtime: use `al_folio_distill`.\n- Search/icons/math/comments/analytics/citations/external posts/newsletter/charts/images: use the owning `al-*` plugin repo.\n\n## Handoff\n\nSummarize changed files, validation results, and any local overrides created.\n","AGENTS.md":"# Agent Guidelines for al-folio (v1.x)\n\n**This file is the authoritative entry point for coding agents working in this repo.** Read it before making any change. It is intentionally short and tool-neutral; it links to the one place each longer-form fact lives.\n\n`al-folio` v1.x is a **thin Jekyll starter, not a theme**. This repo owns starter wiring, example content, docs, and cross-plugin tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems published under [`al-org-dev`](https://github.com/al-org-dev).\n\n## Route your change\n\nFind your change on the left; edit only what is on the right.\n\n| Your change                                                                                                              | Goes in                                                                                                       |\n| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |\n| Dependency pin, plugin activation, feature flag                                                                          | this repo: `Gemfile` **and** `_config.yml` (both — see below)                                                 |\n| Example/demo content, bibliography, data files                                                                           | this repo: `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_books`, `_data`                          |\n| Documentation                                                                                                            | this repo: `docs/` (long-form) or this file (agent rules)                                                     |\n| Cross-plugin integration test, visual parity test                                                                        | this repo: `test/integration_*.sh`, `test/visual/`                                                            |\n| Plugin catalog metadata                                                                                                  | this repo: `_data/featured_plugins.yml`                                                                       |\n| A layout, include, or Sass partial                                                                                       | the owning gem — start with `al_folio_core`                                                                   |\n| A Liquid tag or filter, or what a tag renders                                                                            | the gem that registers it — see the [delegation table](docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation) |\n| Feature behavior (search, math, charts, comments, cookies, icons, CV, distill, analytics, images, newsletter, citations) | that feature's gem — see [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md)                                           |\n| Component/unit test for gem-owned behavior                                                                               | the owning gem, not here                                                                                      |\n| A feature with no existing owner                                                                                         | open a plugin proposal issue first, then a standalone plugin repo                                             |\n\n[`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) is the authoritative area-to-gem table. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) explains how the pieces connect.\n\n## Stop sign\n\n**If your change would create any of these paths in this repo, it belongs in a gem instead:**\n\n```\n_layouts/   _includes/   _sass/   _scripts/   assets/tailwind/   tailwind.config.js   assets/webfonts/\n```\n\n`npm run lint:style-contract` fails CI when any of them exists here, and it also rejects `build:css` / `build:tailwind` npm scripts. Do not add a starter-local Tailwind or CSS build pipeline.\n\nThis restriction applies to **this repo only**. A user's own site created from this template _may_ legally shadow gem-owned files — see [local overrides: your site vs. this repo](docs/ARCHITECTURE.md#local-overrides-your-site-vs-this-repo).\n\n## Three failures that produce no error message\n\nRead [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) for the full explanation. The short version:\n\n1. **Features fail silently.** A feature renders only when its gem is loaded _and_ its flag is on _and_ the page opts in. Otherwise the Liquid tag emits an empty string — no warning, no error.\n2. **`Gemfile` and `_config.yml` are two lists that must agree.** A plugin in only one of them is inert. Adding or removing a plugin means editing both. Repo dirs use hyphens (`al-folio-core`); gem/plugin ids use underscores (`al_folio_core`).\n3. **This repo's effective baseurl is `/al-folio`.** `_config.yml` already sets it, so a plain `bundle exec jekyll build` is correct — that is what `deploy.yml`, `broken-links-site.yml` and `axe.yml` run. Passing `--baseurl /al-folio` is redundant but harmless; blanking the baseurl out is what renders the site unstyled with broken links. Dev server is at `http://localhost:4000/al-folio/`.\n\n## Validated local command set\n\nRun from the repo root, in this order:\n\n```bash\nbundle install\nnpm ci\nnpm run lint:prettier\nnpm run lint:style-contract\nbundle exec jekyll build --baseurl /al-folio\nbash test/integration_comments.sh\nbash test/integration_plugin_toggles.sh\nbash test/integration_distill.sh\nbash test/integration_bootstrap_compat.sh\nbash test/integration_upgrade_cli.sh\nbash test/integration_css_minify.sh\nbash test/integration_new_plugins.sh\nnpx playwright install chromium webkit\nnpm run test:visual\nbundle exec al-folio upgrade audit\nbundle exec al-folio upgrade overrides audit\nbundle exec al-folio upgrade report\ndocker compose up -d\ncurl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null\ndocker compose logs --tail=80\ndocker compose down\n```\n\nAll seven `test/integration_*.sh` scripts are gated by `unit-tests.yml`; run the ones your change touches. Docker note: v1 uses `/srv/jekyll/bin/entry_point.sh` and serves from container-local `/tmp/_site` to avoid host bind-mount write deadlocks.\n\n## Before you open a PR\n\n- Keep starter work here; route runtime behavior to the owning plugin repo.\n- Run `npm run lint:prettier` (Prettier with `@shopify/prettier-plugin-liquid`, `printWidth: 150`). `npx prettier . --write` fixes formatting.\n- Keep docs aligned with v1 ownership, and keep each fact in one place — link rather than restate.\n- If you create or keep local overrides of plugin-owned files, run `bundle exec al-folio upgrade overrides audit` and commit `.al-folio-overrides.yml` after review.\n\n## Further reading\n\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how the starter and gems fit together, silent failure modes, the v1 config contract, local overrides.\n- [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) — authoritative area-to-gem ownership table and PR triage playbook.\n- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — contributor workflow and agent tooling.\n- [`docs/README.md`](docs/README.md) — index of all user and maintainer guides.\n- `.agents/skills/al-folio-bootstrap/SKILL.md` — new-site setup workflow.\n- `.agents/skills/al-folio-v1-migration/SKILL.md` — customized-fork migration and override drift auditing.\n- `.codex/skills` and `.claude/skills` are symlinks to `.agents/skills` for agent-specific discovery.\n",".github/agents/docs.agent.md":"---\nname: docs_agent\ndescription: Documentation specialist for al-folio v1.x\n---\n\nYou are the documentation specialist for `al-folio` v1.x.\n\n## Documentation Objective\n\nKeep starter docs accurate for the pluginized architecture.\n\n## Non-Negotiable Rules\n\n- Do not document `al-folio` as a monolithic runtime theme.\n- Reflect starter-vs-plugin boundaries from `docs/BOUNDARIES.md`.\n- Keep contributor routing explicit: starter changes here, feature/runtime changes in owning plugin repos.\n- Avoid stale bootstrap-era instructions unless clearly marked compatibility-only.\n- Keep migration guidance aligned with `al_folio_upgrade`, including the local override audit workflow.\n\n## Core Docs to Maintain\n\n- `README.md`\n- `docs/README.md`\n- `docs/INSTALL.md`\n- `docs/CUSTOMIZE.md`\n- `docs/FAQ.md`\n- `docs/CONTRIBUTING.md`\n- `docs/BOUNDARIES.md`\n- `.github/copilot-instructions.md`\n- `.agents/skills/al-folio-bootstrap/SKILL.md`\n- `.agents/skills/al-folio-v1-migration/SKILL.md`\n\n## Validation\n\nUse commands from `AGENTS.md` and ensure documented commands are current and runnable.\n\n## Style\n\n- Be concise and practical.\n- Prefer links over duplicated long instructions.\n- Use repository-real file paths and commands.\n",".github/agents/customize.agent.md":"---\nname: customization_agent\ndescription: Customization assistant for al-folio v1.x starter and plugin ecosystem\n---\n\nYou are a customization assistant for `al-folio` v1.x.\n\n## Mission\n\nHelp users customize their site while respecting v1 ownership boundaries.\n\n## Boundary Model\n\n- `al-folio` starter: docs, content, config wiring, integration and visual checks.\n- `al-*` plugins: runtime feature behavior and component assets.\n\nIf a request changes runtime behavior, route to the owning plugin repo instead of patching starter internals.\n\n## User Guidance Priorities\n\n1. Keep explanations simple for non-expert users.\n2. Prefer editing `_config.yml`, content collections, and data files.\n3. Avoid monolith-era guidance that assumes starter owns `_includes/_layouts/_sass` runtime internals.\n4. When retaining local overrides of plugin-owned files, run the override audit and acknowledge reviewed overrides.\n\n## Key Starter Files\n\n- `_config.yml`\n- `_data/*.yml`\n- `_pages/`, `_posts/`, `_projects/`, `_news/`, `_teachings/`\n- `Gemfile`\n- `README.md`\n- `docs/INSTALL.md`, `docs/CUSTOMIZE.md`, `docs/FAQ.md`, `docs/CONTRIBUTING.md`, `docs/BOUNDARIES.md`\n\n## Validation\n\nUse the validated command set in `AGENTS.md`.\n\nFor local overrides, include:\n\n```bash\nbundle exec al-folio upgrade overrides audit\n```\n\n## Escalation\n\nIf user requests a feature that should live in a plugin:\n\n- identify likely owner plugin repo,\n- explain why,\n- provide starter wiring/docs changes only in this repo.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Agent Guidelines for al-folio (v1.x)\n\n**This file is the authoritative entry point for coding agents working in this repo.** Read it before making any change. It is intentionally short and tool-neutral; it links to the one place each longer-form fact lives.\n\n`al-folio` v1.x is a **thin Jekyll starter, not a theme**. This repo owns starter wiring, example content, docs, and cross-plugin tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems published under [`al-org-dev`](https://github.com/al-org-dev).\n\n## Route your change\n\nFind your change on the left; edit only what is on the right.\n\n| Your change                                                                                                              | Goes in                                                                                                       |\n| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |\n| Dependency pin, plugin activation, feature flag                                                                          | this repo: `Gemfile` **and** `_config.yml` (both — see below)                                                 |\n| Example/demo content, bibliography, data files                                                                           | this repo: `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_books`, `_data`                          |\n| Documentation                                                                                                            | this repo: `docs/` (long-form) or this file (agent rules)                                                     |\n| Cross-plugin integration test, visual parity test                                                                        | this repo: `test/integration_*.sh`, `test/visual/`                                                            |\n| Plugin catalog metadata                                                                                                  | this repo: `_data/featured_plugins.yml`                                                                       |\n| A layout, include, or Sass partial                                                                                       | the owning gem — start with `al_folio_core`                                                                   |\n| A Liquid tag or filter, or what a tag renders                                                                            | the gem that registers it — see the [delegation table](docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation) |\n| Feature behavior (search, math, charts, comments, cookies, icons, CV, distill, analytics, images, newsletter, citations) | that feature's gem — see [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md)                                           |\n| Component/unit test for gem-owned behavior                                                                               | the owning gem, not here                                                                                      |\n| A feature with no existing owner                                                                                         | open a plugin proposal issue first, then a standalone plugin repo                                             |\n\n[`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) is the authoritative area-to-gem table. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) explains how the pieces connect.\n\n## Stop sign\n\n**If your change would create any of these paths in this repo, it belongs in a gem instead:**\n\n```\n_layouts/   _includes/   _sass/   _scripts/   assets/tailwind/   tailwind.config.js   assets/webfonts/\n```\n\n`npm run lint:style-contract` fails CI when any of them exists here, and it also rejects `build:css` / `build:tailwind` npm scripts. Do not add a starter-local Tailwind or CSS build pipeline.\n\nThis restriction applies to **this repo only**. A user's own site created from this template _may_ legally shadow gem-owned files — see [local overrides: your site vs. this repo](docs/ARCHITECTURE.md#local-overrides-your-site-vs-this-repo).\n\n## Three failures that produce no error message\n\nRead [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) for the full explanation. The short version:\n\n1. **Features fail silently.** A feature renders only when its gem is loaded _and_ its flag is on _and_ the page opts in. Otherwise the Liquid tag emits an empty string — no warning, no error.\n2. **`Gemfile` and `_config.yml` are two lists that must agree.** A plugin in only one of them is inert. Adding or removing a plugin means editing both. Repo dirs use hyphens (`al-folio-core`); gem/plugin ids use underscores (`al_folio_core`).\n3. **This repo's effective baseurl is `/al-folio`.** `_config.yml` already sets it, so a plain `bundle exec jekyll build` is correct — that is what `deploy.yml`, `broken-links-site.yml` and `axe.yml` run. Passing `--baseurl /al-folio` is redundant but harmless; blanking the baseurl out is what renders the site unstyled with broken links. Dev server is at `http://localhost:4000/al-folio/`.\n\n## Validated local command set\n\nRun from the repo root, in this order:\n\n```bash\nbundle install\nnpm ci\nnpm run lint:prettier\nnpm run lint:style-contract\nbundle exec jekyll build --baseurl /al-folio\nbash test/integration_comments.sh\nbash test/integration_plugin_toggles.sh\nbash test/integration_distill.sh\nbash test/integration_bootstrap_compat.sh\nbash test/integration_upgrade_cli.sh\nbash test/integration_css_minify.sh\nbash test/integration_new_plugins.sh\nnpx playwright install chromium webkit\nnpm run test:visual\nbundle exec al-folio upgrade audit\nbundle exec al-folio upgrade overrides audit\nbundle exec al-folio upgrade report\ndocker compose up -d\ncurl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null\ndocker compose logs --tail=80\ndocker compose down\n```\n\nAll seven `test/integration_*.sh` scripts are gated by `unit-tests.yml`; run the ones your change touches. Docker note: v1 uses `/srv/jekyll/bin/entry_point.sh` and serves from container-local `/tmp/_site` to avoid host bind-mount write deadlocks.\n\n## Before you open a PR\n\n- Keep starter work here; route runtime behavior to the owning plugin repo.\n- Run `npm run lint:prettier` (Prettier with `@shopify/prettier-plugin-liquid`, `printWidth: 150`). `npx prettier . --write` fixes formatting.\n- Keep docs aligned with v1 ownership, and keep each fact in one place — link rather than restate.\n- If you create or keep local overrides of plugin-owned files, run `bundle exec al-folio upgrade overrides audit` and commit `.al-folio-overrides.yml` after review.\n\n## Further reading\n\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how the starter and gems fit together, silent failure modes, the v1 config contract, local overrides.\n- [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) — authoritative area-to-gem ownership table and PR triage playbook.\n- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — contributor workflow and agent tooling.\n- [`docs/README.md`](docs/README.md) — index of all user and maintainer guides.\n- `.agents/skills/al-folio-bootstrap/SKILL.md` — new-site setup workflow.\n- `.agents/skills/al-folio-v1-migration/SKILL.md` — customized-fork migration and override drift auditing.\n- `.codex/skills` and `.claude/skills` are symlinks to `.agents/skills` for agent-specific discovery.\n","isInternal":false,"tokens":1541,"sizeBytes":7621},{"name":"SKILL.md","path":".agents/skills/al-folio-bootstrap/SKILL.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/.agents/skills/al-folio-bootstrap/SKILL.md","title":"al-folio-bootstrap","category":"anthropic-skill","format":"markdown","content":"# al-folio Bootstrap\n\nUse this skill when a user asks an agent to create, configure, or personalize a new al-folio v1.x website.\n\n## Workflow\n\n1. Read `AGENTS.md` and `docs/BOUNDARIES.md` before editing.\n2. Keep the starter small: customize `_config.yml`, `_data`, content collections, and site assets first.\n3. 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.\n4. For local visual/content customization, prefer:\n   - `_config.yml` feature flags and site metadata\n   - `_data/*.yml`\n   - `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_bibliography`\n   - local `_includes`, `_layouts`, and `_sass` overrides only when config/content cannot express the change\n5. Run validation before handing work back:\n\n```bash\nnpm ci\nnpm run lint:prettier\nbundle exec al-folio upgrade audit --no-fail\nbundle exec jekyll build --baseurl /al-folio\n```\n\n## Routing\n\n- Starter wiring/docs/examples/tests: edit `al-folio`.\n- Shared layouts/includes/assets: use `al_folio_core`.\n- CV rendering: use `al_folio_cv`.\n- Distill runtime: use `al_folio_distill`.\n- Search/icons/math/comments/analytics/citations/external posts/newsletter/charts/images: use the owning `al-*` plugin repo.\n\n## Handoff\n\nSummarize changed files, validation results, and any local overrides created.\n","isInternal":false,"tokens":341,"sizeBytes":1395},{"name":"SKILL.md","path":".agents/skills/al-folio-v1-migration/SKILL.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/.agents/skills/al-folio-v1-migration/SKILL.md","title":"al-folio-v1-migration","category":"anthropic-skill","format":"markdown","content":"# al-folio v1 Migration\n\nUse this skill when a user asks an agent to migrate an existing customized al-folio fork to v1.x.\n\n## Workflow\n\n1. Work in a disposable branch, fork, or clone. Do not overwrite the user's original site.\n2. Start from the v1 starter contract, then bring over site-owned files:\n   - `_config.yml` values\n   - `_data`\n   - `_bibliography`\n   - content collections\n   - site assets\n   - intentional local `_includes`, `_layouts`, and `_sass` overrides\n3. Keep v1 plugin wiring from the starter:\n   - `theme: al_folio_core`\n   - bundled `al_*` and `al_folio_*` gems in `Gemfile`\n   - bundled plugin entries in `_config.yml`\n4. Remove stale copied runtime files now owned by plugins unless they are intentional overrides.\n5. Run upgrade checks:\n\n```bash\nbundle exec al-folio upgrade audit --no-fail\nbundle exec al-folio upgrade overrides audit\n```\n\n6. For each stale or unacknowledged override:\n\n```bash\nbundle exec al-folio upgrade overrides diff LOCAL_PATH\nbundle exec al-folio upgrade overrides accept LOCAL_PATH\n```\n\n7. Build and inspect key pages: home, CV, publications, repositories, projects, posts, and any custom routes.\n\n## Migration Notes\n\nCommit `.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.\n\n## Handoff\n\nReport removed stale runtime files, retained local overrides, unresolved visual differences, and exact validation commands.\n","isInternal":false,"tokens":345,"sizeBytes":1500},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n@AGENTS.md\n\n`AGENTS.md` (imported above) is the **authoritative** agent entry point: change routing, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. Keep it short and ecosystem-neutral. Cross-repo architecture — the wrapper/tag/gem delegation table, feature gating, the v1 config contract, local overrides — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); area-to-gem ownership lives in [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md).\n\n**Read those three before editing anything.** Everything below is Claude-specific or longer-form operational detail that does not belong in the short entry point. Do not restate facts from those files here — link to them.\n\n## Daily dev loop\n\n```bash\nbundle install                                # ruby gems\nbundle exec jekyll serve                      # dev server → http://localhost:4000/al-folio/  (NOTE baseurl)\nbundle exec jekyll build --baseurl /al-folio  # production-style build to _site/\nbash test/integration_distill.sh              # run ONE integration test (any of the seven in test/)\nnpm run test:visual:update                    # refresh playwright snapshots after intentional UI change\nbundle exec al-folio upgrade apply --safe     # deterministic codemods (font-weight-* → font-*, remote→local URLs)\nbundle exec al-folio upgrade overrides diff <path>    # then `overrides accept <path>` to acknowledge an override\n```\n\n## Optional toolchains\n\n- **Jupyter posts.** `bin/setup-python-deps` installs _only_ `jupyter` and `nbconvert` (via `pip --user --break-system-packages`) for `jekyll-jupyter-notebook`. It does **not** read `requirements.txt`. Missing `jupyter-nbconvert` is warn-and-continue; notebook rendering is skipped.\n- **Everything else Python.** [`requirements.txt`](requirements.txt) is the fuller list and must be installed separately (`python3 -m pip install -r requirements.txt`): `rendercv[full]` for CV rendering, `scholarly` for `bin/update_scholar_citations.py`, plus `nbconvert` and `pyyaml`.\n- **Responsive images.** `imagemagick.enabled: true` needs ImageMagick `convert` on `PATH`.\n- **Manual deploy.** `bin/deploy` is the manual `gh-pages` build + purgecss + force-push path; CI normally deploys. `purgecss` is not a devDependency — install it with `npm install -g purgecss`.\n\n## Docker serving model (v1-specific)\n\n`docker compose up -d` bind-mounts the repo to `/srv/jekyll` and runs `bin/entry_point.sh`, which serves with `--force_polling --destination /tmp/_site`. The build output deliberately goes to **container-local `/tmp/_site`, not the bind-mounted `_site`** — writing `_site` back across the host bind mount caused write deadlocks. The container also `inotifywait`s `_config.yml` and restarts Jekyll on change (config edits aren't hot-reloaded by `--watch`). Verify with the `/al-folio` baseurl: `curl -fsS http://127.0.0.1:8080/al-folio/`. `docker-compose-slim.yml` pulls a prebuilt `:slim` image instead of building locally.\n\n## CI gates and the style contract\n\n`npm run lint:style-contract` (`test/style_contract.js`) is the automated enforcement of the thin-starter boundary and will fail CI if you cross it. Beyond the forbidden paths listed in `AGENTS.md`, it also asserts that `_config.yml` keeps `theme: al_folio_core` and the required plugins, that the `third_party_libraries` SRI pins are present, and that the `al_math` Gemfile pin stays on a released version rather than a git branch.\n\nOther gates:\n\n- `unit-tests.yml` — style contract plus all seven `test/integration_*.sh` scripts (`comments`, `plugin_toggles`, `distill`, `bootstrap_compat`, `upgrade_cli`, `css_minify`, `new_plugins`).\n- `visual-regression.yml` — Playwright on chromium + webkit, diffing the candidate build against a `v0.16.3` baseline worktree served on `:4100` via `BASELINE_URL`.\n- `upgrade-check.yml` — `bundle exec al-folio upgrade audit`.\n- `prettier.yml` — Prettier with `@shopify/prettier-plugin-liquid` and `printWidth: 150`. Run `npm run lint:prettier` before pushing; `npx prettier . --write` fixes.\n- `update-tocs.yml` — regenerates `<!--ts-->…<!--te-->` blocks in changed root and `docs/` Markdown files. If you add or rename a heading, expect a follow-up auto-commit on `main`.\n\n## Gem version pins\n\n`Gemfile` pins every `al-*` gem to an exact released version in `group :al_folio_plugins`, and `_config.yml` lists the same gems under `plugins:`. Read the current pins from the `Gemfile` rather than trusting any version quoted in prose — including here. To test a gem fix against this site, repoint the `Gemfile` at a sibling checkout (`path:`, `git:`, or `branch:`) and `bundle install`; see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#working-on-a-gem-alongside-the-starter). Revert the pin before committing.\n","isInternal":false,"tokens":1227,"sizeBytes":4906},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Copilot Coding Agent Instructions (v1.x)\n\n**Read [`AGENTS.md`](../AGENTS.md) first — it is the authoritative entry point for all coding agents in this repo.** It carries the change-routing table, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. This file previously duplicated that content; it is now a pointer so the rules cannot drift apart.\n\nIn short: `al-folio` v1.x is a **thin Jekyll starter, not a theme**. It owns starter wiring (`Gemfile`, `_config.yml`), example content, docs, integration tests, and visual parity tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems under [`al-org-dev`](https://github.com/al-org-dev). Route runtime changes to the owning gem.\n\n## Where to look\n\n| Question                             | File                                                                                          |\n| ------------------------------------ | --------------------------------------------------------------------------------------------- |\n| Which repo does my change belong in? | [`AGENTS.md`](../AGENTS.md#route-your-change)                                                 |\n| Which gem owns this area?            | [`docs/BOUNDARIES.md`](../docs/BOUNDARIES.md)                                                 |\n| Which gem owns this Liquid tag?      | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation)            |\n| Why did my feature render nothing?   | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) |\n| What commands should I run?          | [`AGENTS.md`](../AGENTS.md#validated-local-command-set)                                       |\n| How do I contribute?                 | [`docs/CONTRIBUTING.md`](../docs/CONTRIBUTING.md)                                             |\n\n## Copilot-specific paths\n\n- `.github/agents/` — custom agents (`customize.agent.md`, `docs.agent.md`).\n- `.github/instructions/` — per-file-type instruction files (Liquid, YAML, BibTeX, Markdown, JavaScript).\n- `.github/workflows/copilot-setup-steps.yml` — pre-installs Ruby, Python, Node, ImageMagick, and nbconvert for the coding agent.\n- `.agents/skills/` — canonical agent skills, also exposed via the `.codex/skills` and `.claude/skills` symlinks.\n\n## CI expectations\n\nKeep these workflows aligned when changing starter behavior: `unit-tests.yml` (style contract plus all six `test/integration_*.sh` scripts), `visual-regression.yml`, `upgrade-check.yml`, `prettier.yml`, and `deploy.yml`.\n","isInternal":false,"tokens":560,"sizeBytes":2601},{"name":"skills","path":".codex/skills","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/.codex/skills","title":"Codex Directive: skills","category":"codex-rule","format":"markdown","content":"../.agents/skills","isInternal":false,"tokens":5,"sizeBytes":17},{"name":"customize.agent.md","path":".github/agents/customize.agent.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/.github/agents/customize.agent.md","title":"customization_agent","category":"subagent-persona","format":"markdown","content":"---\nname: customization_agent\ndescription: Customization assistant for al-folio v1.x starter and plugin ecosystem\n---\n\nYou are a customization assistant for `al-folio` v1.x.\n\n## Mission\n\nHelp users customize their site while respecting v1 ownership boundaries.\n\n## Boundary Model\n\n- `al-folio` starter: docs, content, config wiring, integration and visual checks.\n- `al-*` plugins: runtime feature behavior and component assets.\n\nIf a request changes runtime behavior, route to the owning plugin repo instead of patching starter internals.\n\n## User Guidance Priorities\n\n1. Keep explanations simple for non-expert users.\n2. Prefer editing `_config.yml`, content collections, and data files.\n3. Avoid monolith-era guidance that assumes starter owns `_includes/_layouts/_sass` runtime internals.\n4. When retaining local overrides of plugin-owned files, run the override audit and acknowledge reviewed overrides.\n\n## Key Starter Files\n\n- `_config.yml`\n- `_data/*.yml`\n- `_pages/`, `_posts/`, `_projects/`, `_news/`, `_teachings/`\n- `Gemfile`\n- `README.md`\n- `docs/INSTALL.md`, `docs/CUSTOMIZE.md`, `docs/FAQ.md`, `docs/CONTRIBUTING.md`, `docs/BOUNDARIES.md`\n\n## Validation\n\nUse the validated command set in `AGENTS.md`.\n\nFor local overrides, include:\n\n```bash\nbundle exec al-folio upgrade overrides audit\n```\n\n## Escalation\n\nIf user requests a feature that should live in a plugin:\n\n- identify likely owner plugin repo,\n- explain why,\n- provide starter wiring/docs changes only in this repo.\n","frontmatter":{"name":"customization_agent","description":"Customization assistant for al-folio v1.x starter and plugin ecosystem"},"isInternal":false,"tokens":345,"sizeBytes":1488},{"name":"docs.agent.md","path":".github/agents/docs.agent.md","rawUrl":"https://raw.githubusercontent.com/alshedivat/al-folio/HEAD/.github/agents/docs.agent.md","title":"docs_agent","category":"subagent-persona","format":"markdown","content":"---\nname: docs_agent\ndescription: Documentation specialist for al-folio v1.x\n---\n\nYou are the documentation specialist for `al-folio` v1.x.\n\n## Documentation Objective\n\nKeep starter docs accurate for the pluginized architecture.\n\n## Non-Negotiable Rules\n\n- Do not document `al-folio` as a monolithic runtime theme.\n- Reflect starter-vs-plugin boundaries from `docs/BOUNDARIES.md`.\n- Keep contributor routing explicit: starter changes here, feature/runtime changes in owning plugin repos.\n- Avoid stale bootstrap-era instructions unless clearly marked compatibility-only.\n- Keep migration guidance aligned with `al_folio_upgrade`, including the local override audit workflow.\n\n## Core Docs to Maintain\n\n- `README.md`\n- `docs/README.md`\n- `docs/INSTALL.md`\n- `docs/CUSTOMIZE.md`\n- `docs/FAQ.md`\n- `docs/CONTRIBUTING.md`\n- `docs/BOUNDARIES.md`\n- `.github/copilot-instructions.md`\n- `.agents/skills/al-folio-bootstrap/SKILL.md`\n- `.agents/skills/al-folio-v1-migration/SKILL.md`\n\n## Validation\n\nUse commands from `AGENTS.md` and ensure documented commands are current and runnable.\n\n## Style\n\n- Be concise and practical.\n- Prefer links over duplicated long instructions.\n- Use repository-real file paths and commands.\n","frontmatter":{"name":"docs_agent","description":"Documentation specialist for al-folio v1.x"},"isInternal":false,"tokens":280,"sizeBytes":1213}],"systemPromptSnippet":"<yakaai_skills repo=\"alshedivat/al-folio\">\n<!-- File: AGENTS.md (Tokens: ~1541 | Category: root-instruction) -->\n# Agent Guidelines for al-folio (v1.x)\n\n**This file is the authoritative entry point for coding agents working in this repo.** Read it before making any change. It is intentionally short and tool-neutral; it links to the one place each longer-form fact lives.\n\n`al-folio` v1.x is a **thin Jekyll starter, not a theme**. This repo owns starter wiring, example content, docs, and cross-plugin tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems published under [`al-org-dev`](https://github.com/al-org-dev).\n\n## Route your change\n\nFind your change on the left; edit only what is on the right.\n\n| Your change                                                                                                              | Goes in                                                                                                       |\n| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |\n| Dependency pin, plugin activation, feature flag                                                                          | this repo: `Gemfile` **and** `_config.yml` (both — see below)                                                 |\n| Example/demo content, bibliography, data files                                                                           | this repo: `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_books`, `_data`                          |\n| Documentation                                                                                                            | this repo: `docs/` (long-form) or this file (agent rules)                                                     |\n| Cross-plugin integration test, visual parity test                                                                        | this repo: `test/integration_*.sh`, `test/visual/`                                                            |\n| Plugin catalog metadata                                                                                                  | this repo: `_data/featured_plugins.yml`                                                                       |\n| A layout, include, or Sass partial                                                                                       | the owning gem — start with `al_folio_core`                                                                   |\n| A Liquid tag or filter, or what a tag renders                                                                            | the gem that registers it — see the [delegation table](docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation) |\n| Feature behavior (search, math, charts, comments, cookies, icons, CV, distill, analytics, images, newsletter, citations) | that feature's gem — see [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md)                                           |\n| Component/unit test for gem-owned behavior                                                                               | the owning gem, not here                                                                                      |\n| A feature with no existing owner                                                                                         | open a plugin proposal issue first, then a standalone plugin repo                                             |\n\n[`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) is the authoritative area-to-gem table. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) explains how the pieces connect.\n\n## Stop sign\n\n**If your change would create any of these paths in this repo, it belongs in a gem instead:**\n\n```\n_layouts/   _includes/   _sass/   _scripts/   assets/tailwind/   tailwind.config.js   assets/webfonts/\n```\n\n`npm run lint:style-contract` fails CI when any of them exists here, and it also rejects `build:css` / `build:tailwind` npm scripts. Do not add a starter-local Tailwind or CSS build pipeline.\n\nThis restriction applies to **this repo only**. A user's own site created from this template _may_ legally shadow gem-owned files — see [local overrides: your site vs. this repo](docs/ARCHITECTURE.md#local-overrides-your-site-vs-this-repo).\n\n## Three failures that produce no error message\n\nRead [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) for the full explanation. The short version:\n\n1. **Features fail silently.** A feature renders only when its gem is loaded _and_ its flag is on _and_ the page opts in. Otherwise the Liquid tag emits an empty string — no warning, no error.\n2. **`Gemfile` and `_config.yml` are two lists that must agree.** A plugin in only one of them is inert. Adding or removing a plugin means editing both. Repo dirs use hyphens (`al-folio-core`); gem/plugin ids use underscores (`al_folio_core`).\n3. **This repo's effective baseurl is `/al-folio`.** `_config.yml` already sets it, so a plain `bundle exec jekyll build` is correct — that is what `deploy.yml`, `broken-links-site.yml` and `axe.yml` run. Passing `--baseurl /al-folio` is redundant but harmless; blanking the baseurl out is what renders the site unstyled with broken links. Dev server is at `http://localhost:4000/al-folio/`.\n\n## Validated local command set\n\nRun from the repo root, in this order:\n\n```bash\nbundle install\nnpm ci\nnpm run lint:prettier\nnpm run lint:style-contract\nbundle exec jekyll build --baseurl /al-folio\nbash test/integration_comments.sh\nbash test/integration_plugin_toggles.sh\nbash test/integration_distill.sh\nbash test/integration_bootstrap_compat.sh\nbash test/integration_upgrade_cli.sh\nbash test/integration_css_minify.sh\nbash test/integration_new_plugins.sh\nnpx playwright install chromium webkit\nnpm run test:visual\nbundle exec al-folio upgrade audit\nbundle exec al-folio upgrade overrides audit\nbundle exec al-folio upgrade report\ndocker compose up -d\ncurl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null\ndocker compose logs --tail=80\ndocker compose down\n```\n\nAll seven `test/integration_*.sh` scripts are gated by `unit-tests.yml`; run the ones your change touches. Docker note: v1 uses `/srv/jekyll/bin/entry_point.sh` and serves from container-local `/tmp/_site` to avoid host bind-mount write deadlocks.\n\n## Before you open a PR\n\n- Keep starter work here; route runtime behavior to the owning plugin repo.\n- Run `npm run lint:prettier` (Prettier with `@shopify/prettier-plugin-liquid`, `printWidth: 150`). `npx prettier . --write` fixes formatting.\n- Keep docs aligned with v1 ownership, and keep each fact in one place — link rather than restate.\n- If you create or keep local overrides of plugin-owned files, run `bundle exec al-folio upgrade overrides audit` and commit `.al-folio-overrides.yml` after review.\n\n## Further reading\n\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how the starter and gems fit together, silent failure modes, the v1 config contract, local overrides.\n- [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) — authoritative area-to-gem ownership table and PR triage playbook.\n- [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) — contributor workflow and agent tooling.\n- [`docs/README.md`](docs/README.md) — index of all user and maintainer guides.\n- `.agents/skills/al-folio-bootstrap/SKILL.md` — new-site setup workflow.\n- `.agents/skills/al-folio-v1-migration/SKILL.md` — customized-fork migration and override drift auditing.\n- `.codex/skills` and `.claude/skills` are symlinks to `.agents/skills` for agent-specific discovery.\n\n<!-- File: .agents/skills/al-folio-bootstrap/SKILL.md (Tokens: ~341 | Category: anthropic-skill) -->\n# al-folio Bootstrap\n\nUse this skill when a user asks an agent to create, configure, or personalize a new al-folio v1.x website.\n\n## Workflow\n\n1. Read `AGENTS.md` and `docs/BOUNDARIES.md` before editing.\n2. Keep the starter small: customize `_config.yml`, `_data`, content collections, and site assets first.\n3. 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.\n4. For local visual/content customization, prefer:\n   - `_config.yml` feature flags and site metadata\n   - `_data/*.yml`\n   - `_pages`, `_posts`, `_projects`, `_news`, `_teachings`, `_bibliography`\n   - local `_includes`, `_layouts`, and `_sass` overrides only when config/content cannot express the change\n5. Run validation before handing work back:\n\n```bash\nnpm ci\nnpm run lint:prettier\nbundle exec al-folio upgrade audit --no-fail\nbundle exec jekyll build --baseurl /al-folio\n```\n\n## Routing\n\n- Starter wiring/docs/examples/tests: edit `al-folio`.\n- Shared layouts/includes/assets: use `al_folio_core`.\n- CV rendering: use `al_folio_cv`.\n- Distill runtime: use `al_folio_distill`.\n- Search/icons/math/comments/analytics/citations/external posts/newsletter/charts/images: use the owning `al-*` plugin repo.\n\n## Handoff\n\nSummarize changed files, validation results, and any local overrides created.\n\n<!-- File: .agents/skills/al-folio-v1-migration/SKILL.md (Tokens: ~345 | Category: anthropic-skill) -->\n# al-folio v1 Migration\n\nUse this skill when a user asks an agent to migrate an existing customized al-folio fork to v1.x.\n\n## Workflow\n\n1. Work in a disposable branch, fork, or clone. Do not overwrite the user's original site.\n2. Start from the v1 starter contract, then bring over site-owned files:\n   - `_config.yml` values\n   - `_data`\n   - `_bibliography`\n   - content collections\n   - site assets\n   - intentional local `_includes`, `_layouts`, and `_sass` overrides\n3. Keep v1 plugin wiring from the starter:\n   - `theme: al_folio_core`\n   - bundled `al_*` and `al_folio_*` gems in `Gemfile`\n   - bundled plugin entries in `_config.yml`\n4. Remove stale copied runtime files now owned by plugins unless they are intentional overrides.\n5. Run upgrade checks:\n\n```bash\nbundle exec al-folio upgrade audit --no-fail\nbundle exec al-folio upgrade overrides audit\n```\n\n6. For each stale or unacknowledged override:\n\n```bash\nbundle exec al-folio upgrade overrides diff LOCAL_PATH\nbundle exec al-folio upgrade overrides accept LOCAL_PATH\n```\n\n7. Build and inspect key pages: home, CV, publications, repositories, projects, posts, and any custom routes.\n\n## Migration Notes\n\nCommit `.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.\n\n## Handoff\n\nReport removed stale runtime files, retained local overrides, unresolved visual differences, and exact validation commands.\n\n<!-- File: CLAUDE.md (Tokens: ~1227 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n@AGENTS.md\n\n`AGENTS.md` (imported above) is the **authoritative** agent entry point: change routing, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. Keep it short and ecosystem-neutral. Cross-repo architecture — the wrapper/tag/gem delegation table, feature gating, the v1 config contract, local overrides — lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); area-to-gem ownership lives in [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md).\n\n**Read those three before editing anything.** Everything below is Claude-specific or longer-form operational detail that does not belong in the short entry point. Do not restate facts from those files here — link to them.\n\n## Daily dev loop\n\n```bash\nbundle install                                # ruby gems\nbundle exec jekyll serve                      # dev server → http://localhost:4000/al-folio/  (NOTE baseurl)\nbundle exec jekyll build --baseurl /al-folio  # production-style build to _site/\nbash test/integration_distill.sh              # run ONE integration test (any of the seven in test/)\nnpm run test:visual:update                    # refresh playwright snapshots after intentional UI change\nbundle exec al-folio upgrade apply --safe     # deterministic codemods (font-weight-* → font-*, remote→local URLs)\nbundle exec al-folio upgrade overrides diff <path>    # then `overrides accept <path>` to acknowledge an override\n```\n\n## Optional toolchains\n\n- **Jupyter posts.** `bin/setup-python-deps` installs _only_ `jupyter` and `nbconvert` (via `pip --user --break-system-packages`) for `jekyll-jupyter-notebook`. It does **not** read `requirements.txt`. Missing `jupyter-nbconvert` is warn-and-continue; notebook rendering is skipped.\n- **Everything else Python.** [`requirements.txt`](requirements.txt) is the fuller list and must be installed separately (`python3 -m pip install -r requirements.txt`): `rendercv[full]` for CV rendering, `scholarly` for `bin/update_scholar_citations.py`, plus `nbconvert` and `pyyaml`.\n- **Responsive images.** `imagemagick.enabled: true` needs ImageMagick `convert` on `PATH`.\n- **Manual deploy.** `bin/deploy` is the manual `gh-pages` build + purgecss + force-push path; CI normally deploys. `purgecss` is not a devDependency — install it with `npm install -g purgecss`.\n\n## Docker serving model (v1-specific)\n\n`docker compose up -d` bind-mounts the repo to `/srv/jekyll` and runs `bin/entry_point.sh`, which serves with `--force_polling --destination /tmp/_site`. The build output deliberately goes to **container-local `/tmp/_site`, not the bind-mounted `_site`** — writing `_site` back across the host bind mount caused write deadlocks. The container also `inotifywait`s `_config.yml` and restarts Jekyll on change (config edits aren't hot-reloaded by `--watch`). Verify with the `/al-folio` baseurl: `curl -fsS http://127.0.0.1:8080/al-folio/`. `docker-compose-slim.yml` pulls a prebuilt `:slim` image instead of building locally.\n\n## CI gates and the style contract\n\n`npm run lint:style-contract` (`test/style_contract.js`) is the automated enforcement of the thin-starter boundary and will fail CI if you cross it. Beyond the forbidden paths listed in `AGENTS.md`, it also asserts that `_config.yml` keeps `theme: al_folio_core` and the required plugins, that the `third_party_libraries` SRI pins are present, and that the `al_math` Gemfile pin stays on a released version rather than a git branch.\n\nOther gates:\n\n- `unit-tests.yml` — style contract plus all seven `test/integration_*.sh` scripts (`comments`, `plugin_toggles`, `distill`, `bootstrap_compat`, `upgrade_cli`, `css_minify`, `new_plugins`).\n- `visual-regression.yml` — Playwright on chromium + webkit, diffing the candidate build against a `v0.16.3` baseline worktree served on `:4100` via `BASELINE_URL`.\n- `upgrade-check.yml` — `bundle exec al-folio upgrade audit`.\n- `prettier.yml` — Prettier with `@shopify/prettier-plugin-liquid` and `printWidth: 150`. Run `npm run lint:prettier` before pushing; `npx prettier . --write` fixes.\n- `update-tocs.yml` — regenerates `<!--ts-->…<!--te-->` blocks in changed root and `docs/` Markdown files. If you add or rename a heading, expect a follow-up auto-commit on `main`.\n\n## Gem version pins\n\n`Gemfile` pins every `al-*` gem to an exact released version in `group :al_folio_plugins`, and `_config.yml` lists the same gems under `plugins:`. Read the current pins from the `Gemfile` rather than trusting any version quoted in prose — including here. To test a gem fix against this site, repoint the `Gemfile` at a sibling checkout (`path:`, `git:`, or `branch:`) and `bundle install`; see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#working-on-a-gem-alongside-the-starter). Revert the pin before committing.\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~560 | Category: copilot-instructions) -->\n# Copilot Coding Agent Instructions (v1.x)\n\n**Read [`AGENTS.md`](../AGENTS.md) first — it is the authoritative entry point for all coding agents in this repo.** It carries the change-routing table, the stop sign for gem-owned paths, the three silent failure modes, and the validated command set. This file previously duplicated that content; it is now a pointer so the rules cannot drift apart.\n\nIn short: `al-folio` v1.x is a **thin Jekyll starter, not a theme**. It owns starter wiring (`Gemfile`, `_config.yml`), example content, docs, integration tests, and visual parity tests. All runtime — layouts, includes, Sass, Liquid tags, filters, feature JS — lives in versioned gems under [`al-org-dev`](https://github.com/al-org-dev). Route runtime changes to the owning gem.\n\n## Where to look\n\n| Question                             | File                                                                                          |\n| ------------------------------------ | --------------------------------------------------------------------------------------------- |\n| Which repo does my change belong in? | [`AGENTS.md`](../AGENTS.md#route-your-change)                                                 |\n| Which gem owns this area?            | [`docs/BOUNDARIES.md`](../docs/BOUNDARIES.md)                                                 |\n| Which gem owns this Liquid tag?      | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#wrapper-to-tag-to-gem-delegation)            |\n| Why did my feature render nothing?   | [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md#failure-modes-that-produce-no-error-message) |\n| What commands should I run?          | [`AGENTS.md`](../AGENTS.md#validated-local-command-set)                                       |\n| How do I contribute?                 | [`docs/CONTRIBUTING.md`](../docs/CONTRIBUTING.md)                                             |\n\n## Copilot-specific paths\n\n- `.github/agents/` — custom agents (`customize.agent.md`, `docs.agent.md`).\n- `.github/instructions/` — per-file-type instruction files (Liquid, YAML, BibTeX, Markdown, JavaScript).\n- `.github/workflows/copilot-setup-steps.yml` — pre-installs Ruby, Python, Node, ImageMagick, and nbconvert for the coding agent.\n- `.agents/skills/` — canonical agent skills, also exposed via the `.codex/skills` and `.claude/skills` symlinks.\n\n## CI expectations\n\nKeep these workflows aligned when changing starter behavior: `unit-tests.yml` (style contract plus all six `test/integration_*.sh` scripts), `visual-regression.yml`, `upgrade-check.yml`, `prettier.yml`, and `deploy.yml`.\n\n<!-- File: .codex/skills (Tokens: ~5 | Category: codex-rule) -->\n../.agents/skills\n\n<!-- File: .github/agents/customize.agent.md (Tokens: ~345 | Category: subagent-persona) -->\n---\nname: customization_agent\ndescription: Customization assistant for al-folio v1.x starter and plugin ecosystem\n---\n\nYou are a customization assistant for `al-folio` v1.x.\n\n## Mission\n\nHelp users customize their site while respecting v1 ownership boundaries.\n\n## Boundary Model\n\n- `al-folio` starter: docs, content, config wiring, integration and visual checks.\n- `al-*` plugins: runtime feature behavior and component assets.\n\nIf a request changes runtime behavior, route to the owning plugin repo instead of patching starter internals.\n\n## User Guidance Priorities\n\n1. Keep explanations simple for non-expert users.\n2. Prefer editing `_config.yml`, content collections, and data files.\n3. Avoid monolith-era guidance that assumes starter owns `_includes/_layouts/_sass` runtime internals.\n4. When retaining local overrides of plugin-owned files, run the override audit and acknowledge reviewed overrides.\n\n## Key Starter Files\n\n- `_config.yml`\n- `_data/*.yml`\n- `_pages/`, `_posts/`, `_projects/`, `_news/`, `_teachings/`\n- `Gemfile`\n- `README.md`\n- `docs/INSTALL.md`, `docs/CUSTOMIZE.md`, `docs/FAQ.md`, `docs/CONTRIBUTING.md`, `docs/BOUNDARIES.md`\n\n## Validation\n\nUse the validated command set in `AGENTS.md`.\n\nFor local overrides, include:\n\n```bash\nbundle exec al-folio upgrade overrides audit\n```\n\n## Escalation\n\nIf user requests a feature that should live in a plugin:\n\n- identify likely owner plugin repo,\n- explain why,\n- provide starter wiring/docs changes only in this repo.\n\n<!-- File: .github/agents/docs.agent.md (Tokens: ~280 | Category: subagent-persona) -->\n---\nname: docs_agent\ndescription: Documentation specialist for al-folio v1.x\n---\n\nYou are the documentation specialist for `al-folio` v1.x.\n\n## Documentation Objective\n\nKeep starter docs accurate for the pluginized architecture.\n\n## Non-Negotiable Rules\n\n- Do not document `al-folio` as a monolithic runtime theme.\n- Reflect starter-vs-plugin boundaries from `docs/BOUNDARIES.md`.\n- Keep contributor routing explicit: starter changes here, feature/runtime changes in owning plugin repos.\n- Avoid stale bootstrap-era instructions unless clearly marked compatibility-only.\n- Keep migration guidance aligned with `al_folio_upgrade`, including the local override audit workflow.\n\n## Core Docs to Maintain\n\n- `README.md`\n- `docs/README.md`\n- `docs/INSTALL.md`\n- `docs/CUSTOMIZE.md`\n- `docs/FAQ.md`\n- `docs/CONTRIBUTING.md`\n- `docs/BOUNDARIES.md`\n- `.github/copilot-instructions.md`\n- `.agents/skills/al-folio-bootstrap/SKILL.md`\n- `.agents/skills/al-folio-v1-migration/SKILL.md`\n\n## Validation\n\nUse commands from `AGENTS.md` and ensure documented commands are current and runnable.\n\n## Style\n\n- Be concise and practical.\n- Prefer links over duplicated long instructions.\n- Use repository-real file paths and commands.\n</yakaai_skills>"}