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/sitegen.py continues to support wiki-style intra-site links.
• Keep the generated out/Index.html in sync; the site-wide generator runs automatically from make.
• Keep updates idempotent: don’t delete generated output or vendor directories unless instructed.
• When in doubt about improvements, have the AI tour the site like a new reader (browser pass, no edits) and capture TODOs for confusing spots or visual glitches before proposing changes.
• Backlinks: every page renders a “Backlinks” block built from the cmark AST; keep it working whenever you touch build tooling.

Blog Post Style Guidelines

When drafting or editing Markdown articles under md/:

• Begin with a level-one human-readable page title. Legacy CamelCase filenames keep their stable routes while the heading may use spaces (for example, OpenSource.md may begin with # Open Source).
• 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.
• When publishing a listed article, add a dated entry near the top of the md/Home.md Updates table with a relative Markdown link to the article.
• For a shareable unlisted preview, use md/_PageName.md (or an underscore-prefixed directory). It renders at the corresponding HTML URL with noindex metadata, outside the index, feed, and backlinks. Do not link to it from listed pages; the build rejects those links. Keep source-only drafts in drafts/.
• Store article-specific assets in a sibling directory named after the article stem (e.g., md/PageName/image.png for md/PageName.md) and reference them relatively (./PageName/image.png) so make assets copies them correctly.
• 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.
• Skip em-dash pivots like “This isn’t X—it’s Y.” Write the contrast plainly instead.
• Prefer generic “AI coding agent” phrasing over specific product names when writing about AI unless a brand is central to the point.
• Excise common “AI sound” patterns during editorial passes: overly balanced contrast templates (not just X, but Y, less like X and more like Y), generic outline headings (What Comes Next, The Hard Part Moves), throat-clearing hedges (of course, as far as I can tell, in general), abstract noun stacks, and summary-like aphorisms. Prefer concrete nouns, active verbs, shorter sentences, and headings that sound specific to the essay rather than like a generated outline.

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!