# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
npm run dev            # Start dev server (localhost:4321)
npm run build          # astro check + build + copy-sw (use this to verify changes)
npm run check          # Type check + Biome lint
npm run check:fix      # Type check + Biome lint with auto-fix
npm run stylelint      # Lint CSS/Astro styles
npm run stylelint:fix  # Fix style issues
```

There are no automated tests. Verification is done via `npm run build` (0 errors required) and the preview MCP tools.

## Architecture

Astro 6 site running in SSR mode (Node.js standalone adapter) with static output for most routes. TypeScript strict mode. Path alias `@/*` → `src/*`.

**Formatter/linter:** Biome (not ESLint/Prettier). Run `check:fix` after larger edits.

### Content Collections (`src/content.config.ts`)

Five collections defined with Zod schemas:

| Collection | Path | Notes |
|---|---|---|
| `blog` | `src/content/blog/` | Posts with series support (`seriesParent`, `seriesOrder`), tags, category ref, syndication URLs |
| `categories` | `src/content/categories/` | Referenced by blog posts |
| `notes` | `src/content/notes/` | Short-form with optional cover image |
| `links` | `src/content/links/` | Curated external links |
| `collections_photos` | `src/content/photos/collections/` | Photo collections; photos stored as JPG + JSON sidecar files in `img/` subdirs |

### Key Routing Patterns

- `/blog/[...slug]` — Blog posts use the full content path as slug (e.g. `2026/03/01/post-name`)
- `/og/blog/[...slug].png` — OG images generated server-side via Satori (`src/lib/og.ts`)
- `/rss/blog.xml`, `/rss/notes.xml`, `/rss/links.xml`, `/rss/photos.xml` — Separate RSS feeds per content type
- `/photos/collections/[...slug]` — Nested photo collections with breadcrumb navigation

### Lib Utilities (`src/lib/`)

- `collections.ts` — Photo collection helpers: `collectionSlug()`, `buildCollectionPhotos()`, `buildBreadcrumbs()`, `getChildCollections()`
- `og.ts` — OG image generation using Satori (`buildArticleVNode`, `renderOgImage`)
- `webmentions.ts` — Fetch and filter webmentions from webmention.io
- `photo-albums.ts` — Photo album organisation utilities

### Scripts (`scripts/`)

- `mastodon-syndicate.js` — Scans `src/content/blog` and `src/content/notes` for posts without a `syndication` field, posts to Mastodon, writes the status URL back to frontmatter. Env vars: `MASTODON_BASE_URL`, `MASTODON_ACCESS_TOKEN`, `MASTODON_VISIBILITY`, `MASTODON_DRY_RUN`, `MASTODON_LIMIT`
- `publish-posts.sh` — Full deploy orchestration: rsync content to VPS → rebuild container → send webmentions → run mastodon-syndicate

### IndieWeb / Syndication

Blog posts support POSSE via `mastodon-syndicate.js`. After posting, the Mastodon status URL is written to frontmatter as `syndication: ["https://..."]`. The `SyndicationLinks` component reads this and renders `u-syndication` microformat links. Webmentions are fetched at build time from webmention.io and displayed via `WebMentions.astro`.

---

## Workflow

### 1. Plan First
- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately - don't keep pushing
- Write plan to `tasks/todo.md` with checkable items (not just TodoWrite tool)
- Check in before starting implementation

### 2. Subagent Strategy
- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents

### 3. Self-Improvement Loop
- After ANY correction from the user: update `tasks/lessons.md` with the pattern
- Review `tasks/lessons.md` at session start
- Write rules that prevent the same mistake from recurring

### 4. Verification Before Done
- Never mark a task complete without proving it works
- Run `npm run build` — must complete with 0 errors
- Use preview MCP tools to visually verify UI changes

### 5. Demand Elegance (Balanced)
- For non-trivial changes: pause and ask "is there a more elegant way?"
- Skip for simple, obvious fixes — don't over-engineer

### 6. Autonomous Bug Fixing
- When given a bug report: just fix it. Point at logs/errors, then resolve them.

## Core Principles

- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
- **Minimal Impact**: Changes should only touch what's necessary.