# ABOUTME: Operational notes for Ralph autonomous development loops.
# ABOUTME: Contains build/test commands and codebase patterns specific to PhaseFlow.

## Build & Run

- Dev server: `pnpm dev`
- Build: `pnpm build`
- Start production: `pnpm start`

## Validation

Run these after implementing to get immediate feedback:

- Tests: `pnpm test:run`
- Lint: `pnpm lint`
- Lint fix: `pnpm lint:fix`
- Typecheck: `pnpm tsc --noEmit`

## Operational Notes

- Database: PocketBase at `NEXT_PUBLIC_POCKETBASE_URL` env var
- Deployment config: `../alo-cluster/services/phaseflow.hcl` (Nomad job)
- Garmin tokens encrypted with AES-256 using `ENCRYPTION_KEY` (32 chars)
- Path aliases: `@/*` maps to `./src/*`
- Pre-commit hooks: Biome lint + Vitest tests via Lefthook
- CI/CD: Automatic deployment on git push to main (do not manually trigger Nomad jobs)

## Production Logs

Access production logs via Nomad CLI:

```bash
# Check job status and get current allocation ID
nomad job status phaseflow

# View app logs (replace ALLOC_ID with current allocation)
nomad alloc logs ALLOC_ID app

# Tail recent logs
nomad alloc logs ALLOC_ID app | tail -100

# Filter for specific log patterns
nomad alloc logs ALLOC_ID app | grep -E "pattern"
```

The allocation has two tasks: `app` (Next.js) and `pocketbase` (database).

## Database Setup

PocketBase requires these collections: `users`, `period_logs`, `dailyLogs`.

To create missing collections:
```bash
POCKETBASE_ADMIN_EMAIL=admin@example.com \
POCKETBASE_ADMIN_PASSWORD=yourpassword \
pnpm db:setup
```

The script reads `NEXT_PUBLIC_POCKETBASE_URL` from your environment and creates any missing collections. It's safe to run multiple times - existing collections are skipped.

## Codebase Patterns

- TDD required: Write tests before implementation
- All files start with 2-line ABOUTME comments
- No mock mode: Use real data and APIs only
- Never use `--no-verify` for git commits
- Commit format: Descriptive message + Claude footer

## Tech Stack

| Layer | Choice |
|-------|--------|
| Framework | Next.js 16 (App Router) |
| Runtime | Node.js 24 |
| Database | PocketBase |
| Validation | Zod |
| Testing | Vitest + jsdom |
| Linting | Biome |

## File Structure

- `src/app/` - Next.js pages and API routes
- `src/components/` - React UI components
- `src/lib/` - Business logic utilities
- `src/types/` - TypeScript type definitions
- `specs/` - Feature specifications for Ralph