docs: add CLAUDE.md agent guidance

[stefanb]

Summary

Adds CLAUDE.md — repository guidance for Claude Code (and useful orientation for any newcomer). Generated by analyzing the codebase, workflows, and docs/; it deliberately captures what is not discoverable from a single file:

• Commands: yarn dev/build/test flows (incl. single-test), the snapshot + fixture harnesses, uv/invoke data tasks, and the Docker base-image-first gotcha
• Architecture: the two independently-shipped images (website vs datasette), the component → api.ts → datasette → precompute → raw CSV number-tracing chain, island layout (noting / mounts the legacy island and /ali-je-vroce/ the ERA5 one), climate-si's generated-not-committed tables
• Known traps: silent empty results from unknown datasette filter columns, URL-keyed fixtures, Solid's style() dropping camelCase keys, snapshot-baseline discipline, reanalysis-lag forecast fallback
• CI gates & deployment: the exact-allowlist typecheck gate, the four independent CI jobs, stage-auto/prod-pinned Helm promotion

Notes for reviewers

• Code comments across the repo cite "CLAUDE.md ground rule 2" and PROGRESS.md/DECISIONS.md, none of which exist on main (an earlier CLAUDE.md existed only on the unmerged chore/prepare-repo-for-agents branch as an @AGENTS.md pointer). This file states the snapshot-baseline rule in its own words and flags the T-x.y/D-n ticket IDs as provenance markers only. If the original ground-rules document exists somewhere, it would be worth folding in.
• Docs-only change; no code or data touched.

🤖 Generated with Claude Code

[stefanb]

Will likely be replaced by

• chore: set up shared agent tooling (Copilot + Claude Code) #416

[jalezi]

Went through this carefully and spot-checked the falsifiable claims against the repo (yarn scripts, tests/typecheck-allowlist.txt contents, allow_sql in tasks.py, the /ali-je-vroce-era5/ README staleness, paths-ignore on both docker workflows, the spend-quota dispatch guard, the no-VITE_DATASETTE_URL-in-prod claim, fixture count). Everything checked out — no hallucinated details found. This is unusually well-grounded generated documentation, especially the "known traps" and workflow sections.

One thing worth addressing before/after merge, not blocking:

main currently has live references to "CLAUDE.md ground rule 2" in three places — .github/workflows/build.yaml:55, code/ali-je-vroce-era5/i18n/format.ts:45, and scripts/snapshot/main.mjs (three call sites, including a user-facing error string telling people to log a DECISIONS.md entry "per ground rule 2"). This PR states the underlying rule in prose (the snapshot-baseline section) but doesn't number it, so those citations will still dangle after merge. Could we add a short numbered "Ground rules" section (rule 2 = the snapshot/published-number rule) so the existing references actually resolve to something?

Minor, non-blocking:

• The "GitHub workflows" section currently documents seven workflows. Heads up that chore: set up shared agent tooling (Copilot + Claude Code) #416 (shared agent tooling) adds an eighth (copilot-setup-steps.yml) once it lands — whoever picks that up next will want a one-line addition.

• Heads up separately: chore: set up shared agent tooling (Copilot + Claude Code) #416 establishes .github/copilot-instructions.md as the single canonical instruction body, with both AGENTS.md and CLAUDE.md reduced to a one-line @.github/copilot-instructions.md import. The reasoning: this repo is meant to be worked on by multiple agent tools (Copilot, Claude Code, others), and .github/copilot-instructions.md is the location GitHub Copilot itself reads by convention — so rather than maintain near-duplicate guidance in AGENTS.md and CLAUDE.md that inevitably drifts (one gets updated, the other doesn't), every tool-specific file just imports the one real doc. AGENTS.md is also the emerging cross-tool standard other agents look for, so it made sense as the second pointer.

  That'll conflict with this PR's CLAUDE.md on merge, since this one is Claude-specific content with no import line. Given how much of what's in this file (commands, architecture, known traps, CI gates) isn't actually Claude-specific — any agent or human contributor would want it — it'd fit the "single canonical doc" model better as the body of .github/copilot-instructions.md (or a doc it links to) than as a Claude-only file. That's a bigger ask than this PR should have to absorb though, so I'd suggest: land this PR as-is first, and let chore: set up shared agent tooling (Copilot + Claude Code) #416 append @AGENTS.md onto what's here rather than overwrite it. Migrating the content into the canonical location can be a follow-up if we want it.

[jalezi]

Btw, found this — a good prompt for auditing/fixing AGENTS.md/CLAUDE.md files: https://www.aihero.dev/a-complete-guide-to-agents-md#fix-a-broken-agentsmd-with-this-prompt

[stefanb]

note, this PR was done (before noticing your #416) entirely via Claude's /init and a few follow-up investigatin prompts for areas of interest (in separate committs) before implementing

• feat: environment-aware datasette base URL #604

[overlordtm]

My 2 cents, i would usualy put that into AGENTS.md and CLAUDE.md would be just See @AGENTS.md pointer, to make it work also in non Claude Code harnesses. And another thing, I like to make this file self updating, by including something like

- Keep documentation in sync with changes. When changing something described in @README.md or @AGENTS.md, offer to update/amend related docs.

[stefanb]

@overlordtm Agree, I too prefer agent-agnostic instructions, but I put it there anyway (as default) because

• it seems that we all currently use Claude
• i did not notice the @jalezi's more elaborate PR chore: set up shared agent tooling (Copilot + Claude Code) #416 (i remember seeing it in the past, but didn't notice it this time)

Closing in favor of #416. Feel free to reuse the content from this PR or we can regenerate it later.

btw, Claude updates the docs by default, if it exists, with no specific instructions, but it may indeed be better to be explicit about it for other AI agents.