phaseflow/AGENTS.md

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

• Production URL: https://phaseflow.v.paler.net
• 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:

# 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:

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