# 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
74 passed
```

Browser E2E:

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

Real deployment acceptance against a live local OpenList + Iron environment:

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

Optional focused scenarios:

- `scripts/real_openlist_acceptance.py`: baseline upload, reconcile, download, direct WebDAV read
- `scripts/real_openlist_chaos_acceptance.py`: large file, range reads, forced remote recovery, OpenList flap, recycle-bin restore
- `scripts/real_openlist_multi_backend_acceptance.py`: multi-backend placement and enable/disable behavior
- `scripts/real_openlist_multi_backend_chaos.py`: degraded multi-backend recovery and replica healing

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
- file storage replica inspector
- search
- uploads, recycle bin, storage batch checks, backend edit dialog, policies save, and jobs page render
- browser `/api` 4xx/5xx failures during the flow

## Secrets

Backend credentials are encrypted before they are stored in SQLite. Local
development uses a default `IRON_SECRET_KEY`, but real deployments should set a
stable private value before creating S3 or WebDAV backends.

## Runtime Artifacts

Do not commit:

- `.venv/`
- `.uv-cache/`
- `node_modules/`
- `output/`
- `.iron-storage/`
- `.iron-temp/`
- `.iron-cache/`
- 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.