AGENTS.md — guidance for agents in this repo

Tech stack: Jekyll 3.9.1 + Bundler + jekyll-pandoc. Static site with Markdown, Liquid, and SCSS.

Build/serve
- Setup: gem install bundler && bundle install
- Build: bundle exec jekyll build
- Serve (local): bundle exec jekyll serve --livereload
- Optional: Makefile provides dev helpers only: `make build`, `make serve`, `make serve-drafts`.
- Deploy: managed exclusively by CI/CD (GitHub Actions → S3 + CloudFront). Do not use a Makefile or rsync for deployment.
- CI/CD (GitHub Actions → S3 + CloudFront):
  - Workflow: `.github/workflows/build_and_deploy.yml` (name: "CI / CD"). Triggers on push to `master` and can be run manually via `workflow_dispatch` from the Actions tab.
  - Build: runs `bundle exec jekyll build` with `JEKYLL_ENV=production`, then strips `.html` extensions from non-index pages.
  - Deploy target (S3 path): `s3://${{ secrets.AWS_S3_BUCKET_NAME }}` in region `us-west-2`.
    - Sync pass 1 (files with extensions): `aws s3 sync ./_site/ s3://${{ secrets.AWS_S3_BUCKET_NAME }} --exclude "*" --include "*.*" --delete --no-progress`
    - Sync pass 2 (extensionless HTML): `aws s3 sync ./_site/ s3://${{ secrets.AWS_S3_BUCKET_NAME }} --exclude "*.*" --content-type "text/html" --delete --no-progress`
  - CDN cache busting: CloudFront invalidation with `${{ secrets.AWS_CLOUDFRONT_DISTRIBUTION_ID }}` on path `/*`.
  - Required repository secrets: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_BUCKET_NAME`, `AWS_CLOUDFRONT_DISTRIBUTION_ID`. Default region is set via `AWS_DEFAULT_REGION=us-west-2`.

Linting and “tests”
- No unit tests configured. Use html-proofer as site checks (optional dependency):
  - All pages: bundle exec jekyll build && bundle exec htmlproofer ./_site --check-html
  - Single page: bundle exec htmlproofer ./_site/path/to/page/index.html (adjust path)
- Optional: markdownlint for .markdown posts; SCSS lint is not configured.

Code style
- Structure: use _layouts and _includes; avoid large inline HTML; prefer partials.
- Markdown: front matter required; wrap ~100 cols; fenced code blocks with language.
- SCSS: 2 spaces; kebab-case class names; keep partials in _sass and import from main.scss.
- Liquid: snake_case variables; prefer filters over complex logic; keep includes pure.
- Naming: posts YYYY-MM-DD-title.markdown; files/partials kebab-case; images in images/YYYY.
- Error handling: build with --trace when debugging; treat html-proofer failures as blockers; keep Gemfile versions pinned; always use bundle exec.