# AGENTS.md — fosscat.com Hugo Site

## What This Is

Hugo static site (fosscat.com). Personal blog + projects. Custom vendored Gokarna theme with Kimber base16 color palette and Maple Mono font.

## Essential Commands

```sh
hugo server          # Dev server with live reload
hugo                 # Build to public/
hugo new posts/my-post.md       # New blog post
hugo new projects/my-project.md # New project
```

No Makefile, no package.json, no CI. Nix flake + direnv auto-loads all tools on directory entry.

## Verify Changes

Run `hugo server` and check localhost:1313. Hugo reports template/config errors on build. No test suite — visual verification only.

## Key Files

| File | Purpose |
|------|---------|
| `config.toml` | Hugo config (theme, nav, params, syntax highlighting) |
| `flake.nix` | Nix dev environment (hugo, marksman, prettier, markdownlint, aspell) |
| `archetypes/default.md` | Post front matter template |
| `archetypes/projects.md` | Project front matter template (includes status color reference) |
| `.markdownlint.jsonc` | Markdownlint config |
| `.aspell.en.pws` | Personal spell check dictionary |

## Content

**Posts** (`content/posts/*.md`): Front matter fields: `title`, `date`, `lastmod`, `description`, `tags`, `type: "post"`, `showTableOfContents`, `image`, `image_alt`, `image_caption`, `draft`.

**Projects** (`content/projects/*.md`): Same as posts plus `status` (string) and `statusColor` (hex). Colors: green `#99c899`, blue `#537c9c`, yellow `#d8b56d`, red `#704f4f`, grey `#c3c3b4`, pink `#c88c8c`.

**Homepage about**: `content/index-about.md` (loaded by `layouts/index.html` via `readFile`).

## Layout Overrides (`layouts/`)

Root `layouts/` overrides take precedence over `themes/gokarna/layouts/`. Current overrides:

- `index.html` — 2-column home grid: recent posts + project updates card with status badges
- `partials/post.html` — featured image support
- `partials/page.html` — date/lastmod display logic
- `_default/term.html` — custom taxonomy page
- `projects/list.html` — project listing with status badges
- `projects/single.html` — single project page
- `shortcodes/baseurl.html` — outputs site base URL

## Critical Rules

1. **Never manually set `lastmod`** — the pre-commit hook auto-updates it via `scripts/update-lastmod.sh`
2. **Theme is vendored, NOT a submodule** — edit `themes/gokarna/` files directly
3. **CSS lives in `themes/gokarna/assets/css/`** — `main.css`, `dark.css`, `syntax.css`. Hugo's asset pipeline handles minification and fingerprinting
4. **Pre-commit hook** runs on `.md` files: lastmod update, markdownlint, aspell spell check, link validation. See `.githooks/pre-commit`

## Git Hooks & Scripts

Pre-commit hook auto-installed by `scripts/install_hooks.sh` (runs on nix shell entry). Scripts in `scripts/`:
- `update-lastmod.sh` — updates `lastmod` front matter (RFC3339)
- `check-links.sh` — curl-based dead link checker
- `install_hooks.sh` — symlinks `.githooks/*` into `.git/hooks/`
