first Commit

AGENTS.md

@@ -0,0 +1,31 @@
+# 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.