eryao/AGENTS.md

# Project AGENTS Router

Root `AGENTS.md` is routing + cross-domain policy only.
Do not place backend/frontend implementation details here.

## Scope

- Applies to repository root and cross-domain tasks.
- Subdomain rules: `backend/AGENTS.md`, `apps/AGENTS.md`.
- If rules conflict, use the stricter one.

## Rule Order

1. System / developer / platform safety instructions
2. Workspace runtime rules (`AGENTS.md` + `rules/*`)
3. This file (routing + project-level constraints)
4. Subdomain rules (backend/apps)

## Mandatory Routing

- `backend/**` must follow `backend/AGENTS.md`.
- `apps/**` must follow `apps/AGENTS.md`.
- Cross-domain changes must satisfy all relevant subdomain rules.
- `infra/**` follows this file plus `infra/` conventions.

## Project-Wide Constraints

- Default development branch is `dev`; do not develop directly on `main`.
- Never push unless explicitly requested by the user.
- Keep AGENTS layered and lean: shared rules at root, domain rules in sub-AGENTS.
- **No Error Swallowing**: All exceptions must propagate or be converted to typed errors. Never catch an exception, log it, and silently continue. This destroys debuggability.

## Git Safety (CRITICAL)

- **NEVER execute `git checkout -- <file>` or any git command that modifies files without explicit user approval.**
- **NEVER reset, revert, or discard uncommitted changes without user consent.**
- If you need to discard changes, ask the user first and explain exactly what will be lost.
- Before any destructive git operation, list the affected files and get confirmation.
- This rule is non-negotiable. Violation will cause irreversible loss of user work.

## Protocol Source of Truth

`docs/protocols/` is the single source of truth for protocol and data format.

- Update protocol docs before changing data/API/UI contracts.
- Document compatibility strategy (backward-compatible vs migration).
- Keep frontend/backend implementations aligned with documented protocol.

## Database Access

When viewing data in the database, use `supabase mcp` tools (`supabase_execute_sql`, `supabase_list_tables`, etc.) instead of direct queries or other methods.

## Image Handling

When reading images, check whether the model has native multimodal capability first. If it does, use `Read` tool to read images directly. If it does not, fall back to `understand_image` tool. Only use `Read` tool for non-image files.

<!-- TRELLIS:START -->
# Trellis Instructions

These instructions are for AI assistants working in this project.

Use the `/trellis:start` command when starting a new session to:
- Initialize your developer identity
- Understand current project context
- Read relevant guidelines

Use `@/.trellis/` to learn:
- Development workflow (`workflow.md`)
- Project structure guidelines (`spec/`)
- Developer workspace (`workspace/`)

Keep this managed block so 'trellis update' can refresh the instructions.

<!-- TRELLIS:END -->