Agent Handbook

Welcome! This document describes how automated helpers should operate when working on the homepage repository.

Required Reading Order

1. Skim this AGENTS.md document in full before doing anything else.
2. Re-read the top-level README.md to confirm runtime expectations and external dependencies.
3. Only then begin planning or modifying files.

Operating Principles

• Prefer incremental changes over sweeping rewrites. Modify existing files in place and preserve user-written content.
• The repo targets standard POSIX tooling (make, awk, rsync, cmark-gfm); avoid introducing extra build dependencies.
• Always run make assets && make after touching Markdown, templates, or build scripts unless instructed otherwise.
• make deploy is reserved for publishing—never call it unless explicitly asked and the git worktree is clean.
• Ensure tools/mdlink2html.awk and build helpers continue to support wiki-style intra-site links.
• Keep the generated out/Index.html in sync; the tools/gen_index.sh helper runs automatically from make.
• Keep updates idempotent: don’t delete generated output or vendor directories unless instructed.

Blog Post Style Guidelines

When drafting or editing Markdown articles under md/:

• Begin with a level-one heading that matches the filename (e.g., # HomepageDesign).
• Use short, conversational paragraphs aimed at technical readers; prefer present tense and active voice.
• Link to related wiki pages using relative Markdown links (./PageName.md) so the generator can rewrite them.
• For historical notes, include dates or context in plain prose rather than YAML front matter.
• Tables should follow GitHub-style pipe syntax; the build pipeline will handle them.
• Avoid HTML unless necessary for layout—stick to Markdown headings, lists, and links.
• Signatures are not required; rely on the build footer for publication metadata.

Communication Notes

• If you encounter unexpected files, stop and ask rather than deleting them.
• Mention any new helper scripts or tooling in commit notes and README.md when appropriate.
• Keep responses in a friendly teammate tone; summarize actions, call out verification steps, and suggest next moves.

Thanks for keeping the blog tidy and consistent!