# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Flutter (Dart) + Supabase project.

Stack: Flutter (Dart), Supabase.

## Commands

- Run: `flutter run`
- Analyze: `flutter analyze`
- Tests: `flutter test`
- Format: `dart format .`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## Project structure

- Feature folders under `lib/features/<name>/` with widgets, state and data layers.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Flutter (Dart)

- Code must pass `flutter analyze` with no warnings.
- Use `const` constructors wherever possible.
- Split large `build` methods into small widgets, not helper methods returning widgets.
- Use the state management already in the project (Riverpod, Bloc, Provider). Do not introduce a second one.
- Check `mounted` before using `BuildContext` after an `await`.
- Add packages with `flutter pub add`; prefer well-maintained packages from pub.dev.
- Never hardcode API secrets in the app bundle.

## Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- Initialise `supabase_flutter` once in `main()` and access it via `Supabase.instance.client`.

## Reference docs

- [Flutter docs](https://docs.flutter.dev)
- [Supabase docs](https://supabase.com/docs)