# AGENTS.md

Guidance for coding agents and automated contributors working in this repository.

## Project Snapshot

Iron is a self-hosted personal cloud drive gateway with:

- FastAPI backend under `app/`
- Vite + Vue + TypeScript frontend under `frontend/`
- built frontend assets served from `app/web/dist/`
- Alembic migrations under `alembic/`
- tests under `tests/`
- project docs under `docs/`

The current stage is **Product MVP Candidate**. Preserve the existing
desktop-first drive UX and avoid drifting back toward a generic admin dashboard.

## Required Setup

Use the local virtualenv and `uv` cache:

```bash
UV_CACHE_DIR=.uv-cache uv venv .venv
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python -e '.[dev]'
npm install
```

## Common Commands

```bash
npm run build
.venv/bin/python -m pytest
.venv/bin/python scripts/ui_playwright_smoke.py
.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py
```

## Development Rules

- Keep runtime artifacts out of Git: `.venv/`, `node_modules/`, `output/`,
  `.iron-storage/`, `.iron-temp/`, caches, and local databases.
- Add or update tests in the same change as behavior changes.
- For UI work, run the real-service Playwright flow and review screenshots.
- Do not use naked `/api/files/...` media URLs for browser preview/download.
  Fetch file content with authorization, create an object URL, and revoke it.
- Keep docs current when changing setup, architecture, test counts, or user flows.
- Prefer small, focused changes over broad rewrites.

## UI Quality Standard

For any meaningful Web UI change:

1. build frontend assets with `npm run build`
2. run `./.venv/bin/python scripts/ui_playwright_smoke.py`
3. inspect screenshots in `output/playwright/`
4. fix layout or interaction issues found in screenshots
5. rerun the Playwright flow

See [docs/development.md](docs/development.md).

## Documentation Expectations

- `README.md` should stay user-facing and concise.
- `CONTRIBUTING.md` should describe contributor workflow.
- `docs/README.md` should index deeper docs.
- `docs/development.md` should describe test and UI validation rules.
- Avoid local absolute paths in committed Markdown.

## Verification Before Finishing

At minimum, run:

```bash
npm run build
.venv/bin/python -m pytest
```

If UI behavior changed, also run:

```bash
.venv/bin/python scripts/ui_playwright_smoke.py
```