CLAUDE.md

1# Before starting work
2 
3- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
4- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
5 
6# Post-task checklist (REQUIRED — do not skip)
7 
8After EVERY task, before responding to the user:
9 
10- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
11- [ ] Run `lat check` — all wiki links and code refs must pass
12- [ ] Do not skip these steps. Do not consider your task done until both are complete.
13 
14---
15 
16# What is lat.md?
17 
18This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
19 
20## Development Commands (wodsmith-start)
21 
22Run these from `apps/wodsmith-start/`:
23 
24### Build and Development
25 
26- `pnpm dev` - Start development server
27- `pnpm build` - Build TanStack Start application
28- `pnpm preview` - Preview production build with Cloudflare
29 
30### Code Quality
31 
32- `pnpm lint` - Run Biome linter
33- `pnpm format` - Format code with Biome
34- `pnpm check` - Run Biome check (lint + format)
35- `pnpm type-check` - Run TypeScript type checking
36 
37### Database Operations
38 
39- `pnpm db:push` - Push schema changes to PlanetScale dev branch (use during development)
40- `pnpm db:generate --name=X` - Generate migration (only before merging to main)
41- `pnpm db:studio` - Open Drizzle Studio
42- `pnpm db:migrate:local` - Apply migrations locally
43 
44### Testing
45 
46- `pnpm test` - Run all tests with Vitest (single run mode)
47- Test files are located in `test/` directory
48 
49### Cloudflare
50 
51- `pnpm cf-typegen` - Generate Cloudflare types (run after wrangler.jsonc changes)
52- `npx alchemy deploy` - Deploy using Alchemy IaC
53- `pnpm alchemy:dev` - Deploy local dev environment with Alchemy (required after changing env vars in `.dev.vars`)
54 
55## Architecture Overview (wodsmith-start)
56 
57### Tech Stack
58 
59- **Framework**: TanStack Start (React 19, TypeScript, Vinxi/Vite)
60- **Database**: PlanetScale (MySQL) with Drizzle ORM via Hyperdrive
61- **Authentication**: Custom auth with KV sessions
62- **Deployment**: Cloudflare Workers via Alchemy IaC
63- **UI**: Tailwind CSS, Shadcn UI, Radix primitives
64- **State**: Zustand (client), TanStack Router loaders (server)
65- **API**: TanStack Start server functions (`createServerFn`)
66 
67### Project Structure (wodsmith-start)
68 
69```
70apps/wodsmith-start/src/
71├── routes/                 # TanStack Router file-based routes
72│   ├── api/               # API routes (server handlers)
73│   └── compete/           # Competition features
74├── components/            # React components
75├── db/                    # Database schema and migrations
76│   ├── schema.ts          # Main schema exports
77│   └── migrations/        # Auto-generated migrations
78├── server/                # Server-only business logic
79├── server-fns/            # Server functions (createServerFn)
80├── lib/                   # Shared utilities
81│   ├── env.ts             # Server-only env access (getAppUrl, etc.)
82│   └── stripe.ts          # Server-only Stripe client
83├── utils/                 # Shared utilities
84├── state/                 # Client state (Zustand)
85└── schemas/               # Zod validation schemas
86```
87 
88### Multi-Tenancy
89 
90- Team-based data isolation with `teamId` filtering
91- Role-based permissions (admin, member roles)
92- Team switching via team-switcher component
93- All database operations must include team context
94 
95### Database Schema
96 
97Database is modularly structured in `src/db/schemas/`:
98 
99- `users.ts` - User accounts and authentication
100- `teams.ts` - Team/organization management
101- `workouts.ts` - Workout management system
102- `programming.ts` - Programming tracks and scheduling
103- `billing.ts` - Credit billing system
104- `scaling.ts` - Workout scaling options
105- `scheduling.ts` - Schedule templates and scheduling
106- Main schema exports from `src/db/schema.ts`
107 
108## Development Guidelines
109 
110### Code Style
111 
112- Use TypeScript everywhere, prefer interfaces over types
113- Functional components, avoid classes
114- Server Components by default, `use client` only when necessary
115- Add `import "server-only"` to server-only files (except page.tsx)
116- Use semantic commit messages: `feat:`, `fix:`, `chore:`
117- Use `pnpm` as package manager
118 
119### Database
120 
121- **Local development**: Use `pnpm db:push` to apply schema changes directly (no migration files)
122- **Before merging**: Generate migrations with `pnpm db:generate --name=feature-name`
123- **Never write SQL migrations manually** - always use drizzle-kit
124- Use `db.transaction()` when multiple writes need to be atomic (PlanetScale supports transactions)
125- Never pass `id` when inserting (auto-generated with CUID2)
126- Always filter by `teamId` for multi-tenant data
127- Use helper functions in `src/server/` for business logic
128- Use standard Drizzle queries with `inArray()` directly — PlanetScale has no restrictive parameter limits
129 
130### Authentication & Authorization
131 
132- Session handling: `getSessionFromCookie()` for server components
133- Client session: `useSession()` from `src/utils/auth-client.ts`
134- Team authorization utilities in `src/utils/team-auth.ts`
135- Protect routes with team context validation
136- When checking roles use available roles from `src/db/schemas/teams.ts`
137 
138### State Management
139 
140- Server state: React Server Components
141- Client state: Zustand stores in `src/state/`
142- URL state: NUQS for search parameters
143- Forms: React Hook Form with Zod validation
144 
145### API Patterns
146 
147- Server functions with TanStack Start: `createServerFn` (see below)
148- Named object parameters for functions with >1 parameter
149- Consistent error handling with proper HTTP status codes
150- Rate limiting on auth endpoints
151 
152### TanStack Start Server Functions (wodsmith-start)
153 
154#### Environment Variables
155 
156**ALWAYS** use `env` from `cloudflare:workers` - never use `process.env`:
157 
158```typescript
159import {env} from 'cloudflare:workers'
160 
161env.HYPERDRIVE // PlanetScale via Hyperdrive
162env.KV_SESSION // KV namespace binding
163env.APP_URL // Environment variable
164env.STRIPE_SECRET_KEY // Secret
165```
166 
167**TypeScript not recognizing env vars?** If you've added new bindings in `alchemy.run.ts` and deployed with `pnpm alchemy:dev`, but TypeScript doesn't see them, run:
168 
169```bash
170lat locate "Section Name"      # find a section by name (exact, fuzzy)
171lat refs "file#Section"        # find what references a section
172lat search "natural language"  # semantic search across all sections
173lat expand "user prompt text"  # expand [[refs]] to resolved locations
174lat check                      # validate all links and code refs
175```
176 
177Run `lat --help` when in doubt about available commands or options.
178 
179If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
180 
181# Syntax primer
182 
183- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
184- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
185- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
186- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
187 
188# Test specs
189 
190Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
191 
192```markdown
193---
194lat:
195  require-code-mention: true
196---
197# Tests
198 
199Authentication and authorization test specifications.
200 
201## User login
202 
203Verify credential validation and error handling for the login endpoint.
204 
205### Rejects expired tokens
206Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
207 
208### Handles missing password
209Login request without a password field returns 400 with a descriptive error.
210```
211 
212Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
213 
214Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
215 
216```python
217# @lat: [[tests#User login#Rejects expired tokens]]
218def test_rejects_expired_tokens():
219    ...
220 
221# @lat: [[tests#User login#Handles missing password]]
222def test_handles_missing_password():
223    ...
224```
225 
226Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
227 
228# Section structure
229 
230Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
231 
232```markdown
233# Good Section
234 
235Brief overview of what this section documents and why it matters.
236 
237More detail can go in subsequent paragraphs, code blocks, or lists.
238 
239## Child heading
240 
241Details about this child topic.
242```
243 
244```markdown
245# Bad Section
246 
247## Child heading
248 
249Details about this child topic.
250```
251 
252The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
253 
254<!-- intent-skills:start -->
255# Skill mappings - when working in these areas, load the linked skill file into context.
256skills:
257  - task: "TanStack Router core concepts, route trees, createRouter, createRoute, file naming conventions"
258    load: "node_modules/@tanstack/router-core/skills/router-core/SKILL.md"
259  - task: "Route protection, auth guards, beforeLoad redirects, RBAC, authenticated layouts"
260    load: "node_modules/@tanstack/router-core/skills/router-core/auth-and-guards/SKILL.md"
261  - task: "Code splitting, lazy routes, .lazy.tsx, autoCodeSplitting, getRouteApi"
262    load: "node_modules/@tanstack/router-core/skills/router-core/code-splitting/SKILL.md"
263  - task: "Route data loading, loaders, loaderDeps, staleTime, pendingComponent, Await, deferred data"
264    load: "node_modules/@tanstack/router-core/skills/router-core/data-loading/SKILL.md"
265  - task: "Link component, useNavigate, preloading, navigation blocking, scroll restoration"
266    load: "node_modules/@tanstack/router-core/skills/router-core/navigation/SKILL.md"
267  - task: "notFound handling, errorComponent, CatchBoundary, route masking"
268    load: "node_modules/@tanstack/router-core/skills/router-core/not-found-and-errors/SKILL.md"
269  - task: "Dynamic path params, splat routes, optional params, useParams"
270    load: "node_modules/@tanstack/router-core/skills/router-core/path-params/SKILL.md"
271  - task: "Search params validation, Zod adapters, search middlewares, retainSearchParams"
272    load: "node_modules/@tanstack/router-core/skills/router-core/search-params/SKILL.md"
273  - task: "SSR, streaming, renderRouterToStream, HeadContent, Scripts, head route option, meta tags"
274    load: "node_modules/@tanstack/router-core/skills/router-core/ssr/SKILL.md"
275  - task: "Router type safety, Register declaration, from narrowing, strict mode, LinkProps"
276    load: "node_modules/@tanstack/router-core/skills/router-core/type-safety/SKILL.md"
277<!-- intent-skills:end -->
278 
279<!-- gitnexus:start -->
280# GitNexus — Code Intelligence
281 
282This project is indexed by GitNexus as **thewodapp** (53782 symbols, 88590 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
283 
284> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
285 
286## Always Do
287 
288- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
289- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
290- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
291- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
292- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
293 
294## Never Do
295 
296- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
297- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
298- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
299- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
300 
301## Resources
302 
303| Resource | Use for |
304|----------|---------|
305| `gitnexus://repo/thewodapp/context` | Codebase overview, check index freshness |
306| `gitnexus://repo/thewodapp/clusters` | All functional areas |
307| `gitnexus://repo/thewodapp/processes` | All execution flows |
308| `gitnexus://repo/thewodapp/process/{name}` | Step-by-step execution trace |
309 
310## CLI
311 
312| Task | Read this skill file |
313|------|---------------------|
314| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
315| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
316| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
317| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
318| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
319| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
320 
321<!-- gitnexus:end -->
322