# AGENTS.md

## Stack
- This is a single-file Flask app. The real application entrypoint is `app.py`; there is no package layout, test suite, or separate config module.
- Runtime dependency is only `Flask==3.0.3` from `requirements.txt`.

## Run
- Create the environment exactly as documented in `README.md`: `python3 -m venv .venv`, `source .venv/bin/activate`, `pip install -r requirements.txt`.
- Start the app with `python3 app.py`. `app.py` calls `app.run(debug=True)` directly under `if __name__ == "__main__"`.
- Default local URL is `http://127.0.0.1:5000`.

## Data And Side Effects
- The app writes to repo-local files next to `app.py`: SQLite database `inventory.db` and log file `inventory.log`.
- `init_db()` runs on every request via `@app.before_request`, so schema creation and the default admin bootstrap happen lazily through web traffic, not a separate init command.
- The first admin user is auto-created with username `admin` and no password; first login redirects to `/set-password`.

## Architecture Notes
- `app.py` owns routes, auth, schema management, logging, and business logic in one file. Read it before making cross-cutting changes.
- Templates live in `templates/`; static assets are in `static/`.
- Auth uses Flask session key `staff_user_id`. Access control is enforced with `login_required` and `admin_required` decorators in `app.py`.
- The transaction history stores `handled_by`; `init_db()` also contains a lightweight migration that adds this column if missing. Preserve this pattern if making schema changes against existing `inventory.db` files.
- Successful `/assign` and `/return` posts redirect to `/transactions/<id>/print`; the printable receipt flow is part of the normal workflow, not an optional extra page.
- Admin-only behavior exists in both routes and templates: only admins can reach `/admin/staff`, and only admins see recent log entries on the dashboard.

## Verification
- There are no configured tests, linters, type checks, CI workflows, or task runners in the repo.
- For changes, the practical verification step is to run `python3 app.py` and exercise the relevant route flows manually in the browser.

## Editing Cautions
- Treat `inventory.db`, `inventory.log`, and `__pycache__/` as runtime artifacts, not source files.
- `SECRET_KEY` is hardcoded to `dev-secret-key` in `app.py`; do not assume environment-based config already exists.