| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 20 | 4 | 19 | 47% |
| Commands | 1 | 0 | 17 | 6% |
| Section tags | 4 | 1 | 7 | 33% |
What each file covers
Sections
20 shared · 4 only in A · 19 only in B- − Commands
- − CRM Agent APIs
- − Discover Capabilities
- − Upload CRM Documents
- + Development Commands (wodsmith-start)
- + Build and Development
- + Code Quality
- + Database Operations
- + Testing
- + Cloudflare
- + Architecture Overview (wodsmith-start)
- + Tech Stack
- + Project Structure (wodsmith-start)
- + Multi-Tenancy
- + Database Schema
- + Development Guidelines
- + Code Style
- + Database
- + Authentication & Authorization
- + State Management
- + API Patterns
- + TanStack Start Server Functions (wodsmith-start)
- + Skill mappings - when working in these areas, load the linked skill file into context.
- Before starting work
- Post-task checklist (REQUIRED — do not skip)
- What is lat.md?
- Syntax primer
- Test specs
- Tests
- User login
- Rejects expired tokens
- Handles missing password
- @lat: [[tests#User login#Rejects expired tokens]]
- @lat: [[tests#User login#Handles missing password]]
- Section structure
- Good Section
- Child heading
- Bad Section
- GitNexus — Code Intelligence
- Always Do
- Never Do
- Resources
- CLI
Commands
1 shared · 0 only in A · 17 only in B- + pnpm dev
- + pnpm build
- + pnpm preview
- + pnpm lint
- + pnpm format
- + pnpm check
- + pnpm type-check
- + pnpm db:push
- + pnpm db:generate --name=X
- + pnpm db:studio
- + pnpm db:migrate:local
- + pnpm test
- + pnpm cf-typegen
- + npx alchemy deploy
- + pnpm alchemy:dev
- + pnpm
- + pnpm db:generate --name=feature-name
- npx gitnexus analyze
Section tags
4 shared · 1 only in A · 7 only in B- − agent-behaviour
- + build
- + lint-format
- + types
- + git-pr
- + security
- + database
- + api
- test
- code-style
- architecture
- do-not
Line diff
wodsmith/thewodapp · AGENTS.md
@@ −17 @@
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# Commands
21
22```bash
23lat locate "Section Name" # find a section by name (exact, fuzzy)
24lat refs "file#Section" # find what references a section
@@ −104 @@
104
105The 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.
106
107## CRM Agent APIs
108
109The CRM exposes authenticated JSON endpoints for automation. Agents should prefer these endpoints over native browser file-picker automation.
110
111### Discover Capabilities
112
113`GET /api/crm/agent-capabilities`
114
115Requires an authenticated CRM session cookie. Returns machine-readable capabilities, including the document upload endpoint and request body shape.
116
117### Upload CRM Documents
118
119`POST /api/crm/documents`
120
121Requires an authenticated CRM session cookie. Use this endpoint to attach local files to CRM entries, especially transcript files referenced in interaction notes.
122
123Body:
124
125- `entryId`: CRM entry id, such as an interaction id.
126- `fileName`: original file name.
127- `fileBase64`: base64-encoded file contents.
128- `fileSize`: byte size.
129- `contentType`: MIME type, usually `text/markdown` for transcripts.
130- `title`: optional display label.
131
132Example:
133
134```json
135{
136 "entryId": "meet_nathan_cff_20260403_000",
137 "fileName": "2026-04-03-nathan-crossfit-fullerton.md",
138 "fileBase64": "...",
139 "fileSize": 50732,
140 "contentType": "text/markdown",
141 "title": "2026-04-03 Nathan CrossFit Fullerton transcript"
142}
143```
144
145The CRM document panel also exposes DOM hints:
146
147- `data-agent-capabilities="/api/crm/agent-capabilities"`
148- `data-agent-document-upload-api="/api/crm/documents"`
149- `data-agent-entry-id="<current entry id>"`
150- `data-agent-preferred-action="uploadCrmDocument"` on the upload form.
151- `data-agent-api="/api/crm/documents"` on the upload form.
152
153<!-- gitnexus:start -->
154# GitNexus — Code Intelligence
wodsmith/thewodapp · CLAUDE.md
@@ +17 @@
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
@@ +251 @@
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
@@ −17 +17 @@
1717
1818 This 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.
1919
20−# Commands
20+## Development Commands (wodsmith-start)
2121
22+Run 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+```
70+apps/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+
97+Database 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
159+import {env} from 'cloudflare:workers'
160+
161+env.HYPERDRIVE // PlanetScale via Hyperdrive
162+env.KV_SESSION // KV namespace binding
163+env.APP_URL // Environment variable
164+env.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+
22169 ```bash
23170 lat locate "Section Name" # find a section by name (exact, fuzzy)
24171 lat refs "file#Section" # find what references a section
@@ −104 +251 @@
104251
105252 The 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.
106253
107−## CRM Agent APIs
108−
109−The CRM exposes authenticated JSON endpoints for automation. Agents should prefer these endpoints over native browser file-picker automation.
110−
111−### Discover Capabilities
112−
113−`GET /api/crm/agent-capabilities`
114−
115−Requires an authenticated CRM session cookie. Returns machine-readable capabilities, including the document upload endpoint and request body shape.
116−
117−### Upload CRM Documents
118−
119−`POST /api/crm/documents`
120−
121−Requires an authenticated CRM session cookie. Use this endpoint to attach local files to CRM entries, especially transcript files referenced in interaction notes.
122−
123−Body:
124−
125−- `entryId`: CRM entry id, such as an interaction id.
126−- `fileName`: original file name.
127−- `fileBase64`: base64-encoded file contents.
128−- `fileSize`: byte size.
129−- `contentType`: MIME type, usually `text/markdown` for transcripts.
130−- `title`: optional display label.
131−
132−Example:
133−
134−```json
135−{
136− "entryId": "meet_nathan_cff_20260403_000",
137− "fileName": "2026-04-03-nathan-crossfit-fullerton.md",
138− "fileBase64": "...",
139− "fileSize": 50732,
140− "contentType": "text/markdown",
141− "title": "2026-04-03 Nathan CrossFit Fullerton transcript"
142−}
143−```
144−
145−The CRM document panel also exposes DOM hints:
146−
147−- `data-agent-capabilities="/api/crm/agent-capabilities"`
148−- `data-agent-document-upload-api="/api/crm/documents"`
149−- `data-agent-entry-id="<current entry id>"`
150−- `data-agent-preferred-action="uploadCrmDocument"` on the upload form.
151−- `data-agent-api="/api/crm/documents"` on the upload form.
254+<!-- intent-skills:start -->
255+# Skill mappings - when working in these areas, load the linked skill file into context.
256+skills:
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 -->
152278
153279 <!-- gitnexus:start -->
154280 # GitNexus — Code Intelligence
