# Elysium Project Notes

## CI Requirements

**Never commit without first confirming the full pipeline passes locally:**
1. `pnpm lint` — zero errors, zero warnings
2. `pnpm build` — all packages build cleanly
3. `pnpm test` — all tests pass with 100% coverage on `apps/api` and `packages/types`

## Art Assets

Game art is generated via the Gemini API (`gemini-3-pro-image-preview`, ~$0.134/image at 1K resolution) and hosted on the CDN at `https://cdn.nhcarrigan.com/elysium/`.

### Process
1. Generate images with `curl` to `https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key=<API_KEY>`, requesting soft-shaded anime style
2. Save responses to `/home/naomi/code/naomi/elysium/img/<category>/<id>.jpg`
3. Upload to R2 with: `AWS_ACCESS_KEY_ID=dd0a3d73969143ada84d50f8940cc5e2 AWS_SECRET_ACCESS_KEY=f73e9907da1b2297e93e17f786d6446d33d4ac60e185879578a0d5020899b18e aws s3 sync img/ s3://nhcarrigan-cdn/elysium/ --endpoint-url https://751c386661d378cc032093493cfb0869.r2.cloudflarestorage.com`
4. Delete the local `img/` directory before committing (images live on CDN only)

### CDN URL Helper
`apps/web/src/utils/cdn.ts` exports `cdnImage(folder, id)` → `https://cdn.nhcarrigan.com/elysium/<folder>/<id>.jpg`

### Directory → Category Mapping
| Game entity | CDN folder |
|---|---|
| Zones | `zones` |
| Bosses | `bosses` |
| Quests | `quests` |
| Adventurers | `adventurers` |
| Companions | `companions` |
| Equipment | `equipment` |
| Upgrades | `upgrades` |
| Prestige upgrades | `prestige-upgrades` |
| Transcendence upgrades | `transcendence-upgrades` |
| Achievements | `achievements` |
| Explorations | `explorations` |
| Materials | `materials` |
| Recipes | `recipes` |
| Story chapter banners | `story-chapters` |

### API Rate Limits
- 250 images/day per API key — use a second key if quota is hit
- Free-tier keys cannot use `gemini-3-pro-image-preview`; key must be on a billing-linked project

## About Page

The About page (`apps/web/src/components/game/aboutPanel.tsx`) contains a **How to Play** guide that should be kept up to date as new features are added to the game. When implementing new game systems, zones, mechanics, or significant UI features, update the `HOW_TO_PLAY` array in `aboutPanel.tsx` to include a description of the new feature.