Imported from DudeDope/dudedope.github.io (AGENTS.md). Install upstream with npx skills add DudeDope/dudedope.github.io. Copyright stays with the author.

Agent Guidelines for al-folio (v1.x)

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.

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.

Route your change

Find your change on the left; edit only what is on the right.

docs/BOUNDARIES.md is the authoritative area-to-gem table. docs/ARCHITECTURE.md explains how the pieces connect.

Content authoring rules

• Every course-note file under _pages/notes/ must follow docs/NOTES_MARKDOWN_GUIDE.md.
• Every blog-post file under _posts/ must follow docs/BLOG_MARKDOWN_GUIDE.md.

Treat these as the authoritative, website-specific rules for front matter, structure, MathJax, callouts, links, media, and final validation. Link to them instead of duplicating their instructions elsewhere.

Stop sign

If your change would create any of these paths in this repo, it belongs in a gem instead:

_layouts/   _includes/   _sass/   _scripts/   assets/tailwind/   tailwind.config.js   assets/webfonts/

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.

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

Three failures that produce no error message

Read docs/ARCHITECTURE.md for the full explanation. The short version:

1. 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.
2. 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).
3. 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/.

Validated local command set

Run from the repo root, in this order:

bundle install
npm ci
npm run lint:prettier
npm run lint:style-contract
bundle exec jekyll build --baseurl /al-folio
bash test/integration_comments.sh
bash test/integration_plugin_toggles.sh
bash test/integration_distill.sh
bash test/integration_bootstrap_compat.sh
bash test/integration_upgrade_cli.sh
bash test/integration_css_minify.sh
npx playwright install chromium webkit
npm run test:visual
bundle exec al-folio upgrade audit
bundle exec al-folio upgrade overrides audit
bundle exec al-folio upgrade report
docker compose up -d
curl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null
docker compose logs --tail=80
docker compose down

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

Before you open a PR

• Keep starter work here; route runtime behavior to the owning plugin repo.
• Run npm run lint:prettier (Prettier with @shopify/prettier-plugin-liquid, printWidth: 150). npx prettier . --write fixes formatting.
• Keep docs aligned with v1 ownership, and keep each fact in one place — link rather than restate.
• 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.

Further reading

• docs/ARCHITECTURE.md — how the starter and gems fit together, silent failure modes, the v1 config contract, local overrides.
• docs/BOUNDARIES.md — authoritative area-to-gem ownership table and PR triage playbook.
• docs/CONTRIBUTING.md — contributor workflow and agent tooling.
• docs/README.md — index of all user and maintainer guides.
• .agents/skills/al-folio-bootstrap/SKILL.md — new-site setup workflow.
• .agents/skills/al-folio-v1-migration/SKILL.md — customized-fork migration and override drift auditing.
• .codex/skills and .claude/skills are symlinks to .agents/skills for agent-specific discovery.