# Development

This document captures the development workflow, test expectations, and UI
quality rules for Iron.

## Setup

```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
```

## Run Locally

```bash
npm run build
.venv/bin/python -m uvicorn app.main:app --reload
```

Open:

```text
http://127.0.0.1:8000/app
```

Default development credentials:

```text
username: admin
password: changeme-iron
```

## Tests

Full suite:

```bash
.venv/bin/python -m pytest
```

Current expected result:

```text
66 passed
```

Browser E2E:

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

Pytest E2E entry:

```bash
.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py
```

## UI Change Standard

Any meaningful Web UI change must be validated against a real running service.

Required workflow:

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

The E2E flow currently covers:

- login
- files page render
- create folder
- upload text file
- authenticated file download
- upload image file
- authenticated inline image preview
- search
- uploads, recycle bin, storage, and jobs page render
- browser `/api` 4xx/5xx failures during the flow

## Runtime Artifacts

Do not commit:

- `.venv/`
- `.uv-cache/`
- `node_modules/`
- `output/`
- `.iron-storage/`
- `.iron-temp/`
- local databases
- Python caches

## Documentation Rules

- Keep `README.md` concise and user-facing.
- Keep contributor instructions in `CONTRIBUTING.md`.
- Keep coding-agent instructions in `AGENTS.md`.
- Keep deeper project docs in `docs/`.
- Use relative links in Markdown.
- Update docs when changing setup, commands, architecture, or user-visible behavior.