Agent Context

This document helps LLM agents understand the codebase structure, environment, and available tooling.

For coding patterns and conventions, see the skills in .agents/skills/.

Task Workflow

Every task must be verified, not just coded. Follow this workflow:

1. Check Environment

Before writing any code, confirm the relevant services are running:

• Run supabase status from the project root to check Supabase (DB, auth, storage, edge runtime)
• List terminal files (ls the terminals folder) and read them to find running processes
• If services are down, start them with the appropriate mise run command and keep the terminal open

Reading logs: Each mise run command runs in a terminal whose output is captured in a text file. To read logs:

1. List the terminals folder to see all active terminals
2. Read the terminal file (or its tail) to see live output, errors, and stack traces
3. After making changes, re-read the same terminal file to check for new errors or successful recompilation

This gives you three verification channels for every change:

• Terminal logs — compile errors, runtime errors, request logs
• Browser MCP — visual state of frontend and Supabase Studio
• Maestro MCP — visual state of the mobile app on the simulator

2. Implement

Write the code changes. Use the skills in .agents/skills/ for coding patterns.

3. Verify

After every change, verify it works using the appropriate tools:

Mobile — two tracks (do not conflate):

4. Report

Summarize what was done, what was verified, and include any screenshots or log output as evidence.

Never skip verification. If a service isn't running and can't be started, report that clearly rather than assuming the code works.

Project Structure

├── frontend/          # Next.js web application
├── mobile/            # React Native (Expo) mobile app
├── supabase/          # Backend: database, auth, edge functions
├── trigger/           # Background jobs and workflows
├── workflows/         # GitHub Actions CI/CD
├── scripts/           # Setup and configuration scripts
└── .agents/skills/    # Agent skills (coding patterns per layer)

Observability

Agent Tooling — MCP Servers

You have three MCP servers available. Use them — these are your eyes into the running app. Discover each server's available tools via the MCP tool descriptors.

Reading Logs (Shell / Terminals)

Each mise run command outputs to a terminal file. Read these for compile errors, runtime errors, and request logs:

• Expo logs: terminal running mise run mobile:ios or mise run mobile:android
• Edge function logs: terminal running mise run supabase:function, or supabase functions logs <name>
• Frontend logs: terminal running mise run frontend, or browser_console_messages via browser MCP

Multi-Layer Workflow

When implementing a cross-cutting feature (e.g. new API + mobile screen + admin view):

1. Write the edge function in supabase/functions/
2. Test via Shell (curl) or browser MCP (Supabase Studio)
3. Build the mobile screen, verify with Maestro MCP on both iOS and Android
4. Build the admin view, verify with browser MCP
5. Read terminal logs across all layers if something fails

Task Runner (mise)

All project tasks are defined in .mise.toml. Run mise tasks to discover all available commands. Use mise run <task> to execute them. Never run services directly (e.g. npx expo start) — always use the mise tasks.

Environment Setup

Run mise run configure to set up environment variables interactively. This script generates .env.local files for each layer:

Never create .env files directly. Always use mise run configure or edit the existing .env.local files. The .env.local convention is used project-wide — all services read from it.

Required for LLM features: OPENAI_API_KEY or ANTHROPIC_API_KEY or GEMINI_API_KEY, plus LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY.

Required for all apps: SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY.