roux/CLAUDE.md

# CLAUDE.md

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

## Commands

```bash
pnpm install        # installs @tailwindcss/cli; Hugo shells out to it
pnpm dev            # hugo server -D (Hugo compiles Tailwind + hot-reloads)
pnpm build          # hugo --minify → public/
python3 scripts/import-posts.py   # Import issue 01 from ~/projects/ginger/posts.csv → content/posts/01/
python3 scripts/generate-images.py --prompts data/prompts/issue-NN.json --issue NN  # Replicate flux-1.1-pro → content/posts/NN/<slug>/<slug>.png
python3 scripts/faceswap-images.py --issue NN --source ~/Bilder/palina.webp         # FaceFusion: swap one consistent face into every plate (in place)
python3 scripts/upscale-images.py --issue NN                                        # Upscayl + Remacri 4x → clamp to 4992px long edge (in place)
python3 scripts/build-issue.py --issue NN --prompts data/prompts/issue-NN.json      # write content/posts/NN/<slug>/index.md
```

Hugo (≥ 0.161) compiles Tailwind itself during the build — no separate CSS step.

## Architecture

**Hugo Extended** static site with **Tailwind CSS v4** (no config file — design tokens live in `@theme {}` in `assets/css/main.css`).

### CSS pipeline

`layouts/partials/css.html` runs `resources.Get "css/main.css" | css.TailwindCSS`
inside a `templates.Defer` block (invoked from `head.html`). Hugo shells out to
`node_modules/.bin/tailwindcss`, which scans `hugo_stats.json` (written each build
by `[build.buildStats]`, `@source`'d in `main.css`, mounted to
`assets/notwatching/` and cache-busted per `hugo.toml`). Dev serves unminified
`/css/main.css`; production emits a fingerprinted, SRI-hashed file.

`assets/css/main.css` — `@theme {}` defines all design tokens (`--color-paper`,
`--color-roux`, `--font-display`, …); global resets are in `@layer base` so
Tailwind utilities override them.

`pnpm-workspace.yaml` sets `preferSymlinkedExecutables: true` (Hugo rejects pnpm's
default shell shim for `tailwindcss`) and `allowBuilds` for `@parcel/watcher` (so
`pnpm run` doesn't fail on the ignored native build).

### Content model

- `content/posts/<issue>/<slug>/index.md` — page bundles grouped by issue dir (`01/`, `02/`, …); each has a `plate` number, `issues`, `categories` (single item), `tags`, `featured` flag, and a `.png` image resource. Permalink is `/posts/<issue>/<slug>/`.
- `content/posts/<issue>/_index.md` — `build.render: never`; suppresses the intermediate `/posts/<issue>/` list page (the per-issue landing page is the taxonomy term `/issues/<issue>/`).
- `content/issues/<id>/_index.md` — branch bundle for an issue; metadata (`title`, `description`, `issueNumber`, `season`, `status`) drives the homepage hero and issue list page. Only one issue should have `status: "current"`.
- `content/imprint.md` — standalone page using `layout: imprint`.

Taxonomies: `categories`, `tags`, `issues` (defined in `hugo.toml`).

### Layout hierarchy

```
layouts/baseof.html          ← shell: head, header, main, footer, lightbox, roux-data JSON
layouts/index.html           ← homepage: current-issue hero + up to 5 featured plates from that issue
layouts/_default/list.html   ← two branches: kind="taxonomy" (term cards) | kind="term"/section (paginated post grid)
layouts/_default/single.html ← post plate page (triggers lightbox via window.__ROUX_OPEN_SLUG)
layouts/_default/imprint.html← prose page layout
layouts/issues/list.html     ← paginated post grid scoped to an issue
layouts/issues/terms.html    ← issue index, reads issueIds from hugo.toml params
layouts/404.html             ← editorial 404 page
```

Key partials: `head.html`, `css.html` (Tailwind build, see CSS pipeline), `header.html`, `footer.html`, `card.html` (reusable post card), `lightbox.html`, `pagination.html`, `logo.html`.

### JavaScript (`static/js/app.js`)

Single vanilla JS file, no build step. Loaded from `baseof.html`. Reads `#roux-data` (JSON injected by Hugo containing all posts) at runtime.

Responsibilities:
- **Inverted search index** — weighted token scoring across title, tags, categories, description; prefix matching; renders into `#searchpop`.
- **Lightbox** — full-screen plate viewer with keyboard nav, thumbnail strip, share/copy URL, meta panel. Opened automatically when `window.__ROUX_OPEN_SLUG` is set (direct URL to a post).
- **Ribbon** dismiss, tab sync, view transitions (`document.startViewTransition`), masthead date.

### Data flow: homepage featured plates

The homepage hero resolves the current issue via `.Site.Params.issueNumber` → `GetPage "/issues/<num>"`. The featured grid shows up to 5 posts with `featured: true` **within that current issue** (`where $plates ".Params.featured" true | first 5`), so each issue's prompts file flags its own 5.

### Content pipeline

- `scripts/import-posts.py` — issue 01 only; reads `~/projects/ginger/posts.csv` + `~/projects/ginger/images/final/selected/`, writes `content/posts/01/` deterministically (sorted by filename → stable plate numbers).
- `scripts/generate-images.py` — reusable Replicate generator. `--prompts <json> --issue NN`; token from `$REPLICATE_API_TOKEN` or `~/.env`; default model `black-forest-labs/flux-1.1-pro`, 960×1440 PNG (custom aspect); idempotent (skips existing), writes a `<prompts>.generated.json` provenance manifest.
- `scripts/faceswap-images.py` — `--issue NN --source <face>` (default `~/Bilder/palina.webp`). Runs FaceFusion `batch-run` (via `~/Projekte/facefusion/.venv`) once over the whole issue, swapping in one consistent face; writes back in place. `--enhance` adds the face_enhancer pass. Idempotent via `issue-NN.faceswap.json` keyed on the source hash.
- `scripts/upscale-images.py` — `--issue NN`. Runs `upscayl-bin` (`/usr/share/upscayl/bin`) with the `remacri-4x` model once over the issue, then clamps the long edge to `--max-edge` (default 4992 ≈ issue-01 sources) with ImageMagick; writes back in place. Idempotent via `issue-NN.upscale.json`.
- `scripts/build-issue.py` — generic; reads the same prompts JSON, writes `content/posts/NN/<slug>/index.md` (plate numbers by stable slug sort), `featured` sourced from the JSON.
- `data/prompts/issue-NN.json` — array of `{slug, title, category, tags, description, prompt, featured?}`. `data/` is gitignored: the prompts file and the `*.generated/faceswap/upscale.json` manifests are local pipeline scratch, not committed. The plate bundles under `content/posts/NN/` are the tracked output.

Full pipeline order: `generate-images` → `faceswap-images` → `upscale-images` → `build-issue`. All four operate on `content/posts/NN/<slug>/<slug>.png` in place and are individually idempotent; pass `--out DIR` to any of the image scripts to stage results without touching the bundles (that run is then untracked).

### Hugo params (hugo.toml)

`issueNumber`, `issueName`, `issueSeason`, `issueBlurb` are fallback values used when `$.Site.GetPage "/issues/<issueNumber>"` returns nil. `issueIds` (newest-first) drives the issues terms page order. `umamiSrc`/`umamiId` are injected only in production (`hugo.IsProduction`).

### nginx

`nginx.conf` at repo root is the production server config (used in Docker). `error_page 404 /404.html` is already wired. A `location ~ ^/posts/(?!0[12]/)…` block 301-redirects the legacy flat issue-01 plate URLs (`/posts/<slug>/`) to their new home under `/posts/01/<slug>/`; extend the negative-lookahead when adding issue 03+.