CLAUDE.md

@@ -1,3 +1,7 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 # NGU-Web
 
 Website for NGU (Next Generation of Unity), a Unity movement organization with regional chapters in the US and internationally. Full-stack app with a public site and a role-based admin panel.
@@ -7,6 +11,21 @@ Website for NGU (Next Generation of Unity), a Unity movement organization with r
 - Backend: Hono on Node.js, SQLite (WAL mode, STRICT tables) via better-sqlite3 / node:sqlite (in `server/`)
 - Package manager: pnpm only (never npm or yarn)
 
+## Commands
+Frontend (repo root):
+- `pnpm dev` / `pnpm build` / `pnpm preview`: Vite
+- `pnpm format`: oxfmt
+- `pnpm exec tsc`: type-check (`noEmit`; there is no separate lint or typecheck script)
+- There is no test suite.
+
+Backend (`server/`, Node >= 22). The server reads `HOST` (default `127.0.0.1`), `PORT` (default `3001`) and `DB_PATH` (default `./ngu.db`); locally, use `DB_PATH=./dev.db`:
+- `DB_PATH=./dev.db pnpm dev`: run with `node --watch`
+- `DB_PATH=./dev.db pnpm migrate`: apply migrations without starting the server
+- `DB_PATH=./dev.db node src/seed.js`: rebuild content tables from `src/data/`. It wipes every content table first (feedback is kept). Run it from the repo, not the deployed copy.
+- `DB_PATH=./dev.db node src/admin-cli.js add|list|passwd|role|disable|enable ...`: the only way accounts are created
+
+In dev, Vite proxies `/api` to the target set in `vite.config.ts`, so the API must listen on that port.
+
 ## Deployment (production)
 - Ubuntu VPS, nginx reverse proxy, systemd service `ngu-api`
 - App deployed to `/srv/ngu-api`; database at `/var/lib/ngu/ngu.db`
@@ -34,10 +53,10 @@ Website for NGU (Next Generation of Unity), a Unity movement organization with r
 - `src/data/` holds only hardcoded data shared across multiple section files (e.g. `historyDecades.ts`, map grid). Everything else comes from SQLite.
 - `navConfig.js` is the single source of truth for navigation, routes, and actions (header, footer, pages).
 - `api.js` is the shared caching client used by frontend data hooks.
-- Logos: org logos in `/org-logos/`, event logos in `public/event-logos/`. The `<Logo>` component hides itself on load error.
+- Logos: org logos in `public/org-logos/` (served at `/org-logos/`), event logos in `public/event-logos/`. The `<Logo>` component hides itself on load error.
 
 ## Rules and gotchas
-- **Role checks must use ladder comparisons, never equality.** Roles rank viewer → editor → admin → superadmin. Use `roleCanWrite(user)` / `roleCanDelete(user)` from `lib/roles` and the minimum-rank helpers (`canWrite`, `canDelete`, `isSuper`, `atLeast`). `role === "admin"` silently excludes higher roles and has caused repeated bugs.
+- **Role checks must use ladder comparisons, never equality.** Roles rank viewer → editor → admin → superadmin. Use the minimum-rank helpers from `src/lib/roles.ts` (`canWrite`, `canDelete`, `isSuper`, `atLeast`). Where a local variable shadows the name, import with an alias, e.g. `canWrite as roleCanWrite`. `role === "admin"` silently excludes higher roles and has caused repeated bugs.
 - **Imports need explicit extensions** (`.ts`, `.tsx`, `.js`) everywhere.
 - **Vite resolves `.js` before `.ts`**, so a `.js` and `.ts` file with the same base name will import the wrong one. Give new hooks distinct names.
 - **Don't use `fallback: EMPTY` in api.js hooks.** It silently returns empty arrays and hides server errors; let the error state surface.