AI Operations

This page documents the mandatory AI workflow for Wargrid.

Vendor Docs

Before generating code for a third-party dependency:

1. check whether the vendor provides an official llms.txt
2. sync the official source into skills/vendor-docs/<tool>/
3. use that source while generating or refactoring code
4. record any durable lesson in AI-NOTES.md

Run:

bun run vendor-docs:sync

Current vendor snapshots also include:

• Better Auth llms.txt
• Drizzle llms-full.txt
• Elysia llms.txt

Documentation Updates

Every meaningful change must update:

1. human docs in apps/docs/docs/
2. AI notes in AI-NOTES.md when the workflow or constraints change
3. release docs and blog notes for user-visible work

Validation Flow

bun run typecheck
bun run lint
bun run test
bun run storybook:build
bun run docs:build
bun run blog:build

If a task touches Pixi, auth, or UI flows, also run the legacy CDP or image-tooling checks until the new testing package fully replaces them.

Workspace Linking

When an app or package starts importing a sibling workspace package, add the dependency explicitly from the consumer package:

bun add @wargrid/some-package@workspace:*

Do not rely on Bun resolving local package names implicitly.

Shared Runtime Paths

• apps/api owns the Better Auth server mounts under /api/auth/player and /api/auth/admin.
• apps/play consumes GET /api/player/bootstrap.
• apps/play also consumes and mutates:
  • GET /api/player/decks
  • POST /api/player/decks/import
  • POST /api/player/decks/default
  • GET /api/player/social
  • POST /api/player/social/actions
  • GET /api/player/lobbies
  • POST /api/player/lobbies
• apps/admin consumes GET /api/admin/bootstrap.
• Extend those routes and the matching Valibot contracts before introducing frontend-local bootstrap payloads.
• Keep stateful fixture logic in standalone modules that can be tested without booting the HTTP runtime. The current reference implementation is apps/api/src/player-state.ts.