# CLAUDE.md

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

## Status

Rust (edition 2024) workspace + React SPA collection-management system. Backend crates: `domain`, `db`, `api`, `auth`, `search`, `server` (axum 0.8 + sqlx/Postgres + Meilisearch). Frontend in `web/` (React 19 + Vite + pnpm). Tests need the docker-compose stack up (Postgres on **:5442**, Meilisearch on **:7700**); each `#[sqlx::test]` provisions its own temp DB.

## Commands

```bash
just check                       # fmt + lint + test — the standard pre-commit gate
docker compose up -d             # start Postgres (:5442) + Meilisearch (:7700) for tests
cargo build --workspace          # build
cargo run -p server              # run the server (or: just run — loads .env)
cargo nextest run --workspace    # run all tests — PREFERRED (per-test isolation, live output, hang timeouts)
cargo nextest run -E 'test(<name>)'   # run tests matching a name substring
cargo test --workspace --doc     # doctests (nextest does not run these)
cargo +nightly fmt               # format — always nightly, not stable
cargo clippy --workspace --all-targets -- -D warnings   # lint before committing
```

(`just test` runs nextest + doctests; config in `.config/nextest.toml`.)

## Conventions

- **CLI args & env vars:** use `clap` with the `derive` feature.
- **Code navigation:** prefer the insikt LSP server over grep/glob — it resolves macro-generated symbols that text search misses. (insikt runs standalone, not via the gateway MCP.)
- **Dependencies:** manage via the `cargo-mcp` server rather than editing `Cargo.toml` by hand.
- **Formatting:** `cargo +nightly fmt` (nightly toolchain required).
- **Frontend guardrails:** before touching `web/`, read **[web/GUARDRAILS.md](web/GUARDRAILS.md)** — it covers the CI gate (`check:size` 250 KB-gz budget, `check:colors` design-token enforcement) and the test-harness quirks (MSW `onUnhandledRequest: "error"`, the jsdom/storybook vitest split, RTL accessible-name collisions, Storybook nested-router and portal handling, and the `components/ui/` code-style split).