README.md

@@ -1,3 +1,69 @@
 # quartermaster
 
-Household budget tracker: sections for incomes, bills, debt, essentials, subscriptions. FastAPI + HTMX + SQLite.
+Household budget tracker. FastAPI + HTMX frontend, SQLite backend.
+
+## Sections
+
+The budget page shows one card per section. Every section accepts a name and
+amount per entry and displays a running total, except *Primary Debt Target*,
+which is a pointer to one of the *Debt Minimums* rows.
+
+* Incomes
+* Fixed Amount Bills
+* Debt Minimums
+* Primary Debt Target (pointer)
+* Food and Essentials
+* Subscriptions
+* Other
+
+## Requirements
+
+* Python 3.12+
+* [uv](https://github.com/astral-sh/uv) for dependency management
+
+## Setup
+
+```sh
+uv sync
+uv run alembic upgrade head
+```
+
+The SQLite file lives at `./quartermaster.db` by default. Override with the
+`QUARTERMASTER_DB_URL` environment variable (any SQLAlchemy URL).
+
+## Run
+
+```sh
+uv run uvicorn quartermaster.main:app --reload
+```
+
+Open http://127.0.0.1:8000.
+
+## Tests
+
+```sh
+uv run pytest
+```
+
+Tests run against an in-memory SQLite database; no migration step needed.
+
+## Project Layout
+
+```
+src/quartermaster/
+  main.py         FastAPI app factory
+  routes.py       HTTP handlers, HTMX partials
+  service.py      Queries, totals, target logic
+  models.py       SQLAlchemy models and Section enum
+  db.py           Engine, session, PRAGMA foreign_keys=ON
+  config.py       DB URL resolution
+  templates/      Jinja2 templates (base, index, partials)
+  static/         CSS
+alembic/          Migrations
+tests/            pytest suite
+```
+
+## Scope
+
+Single-month budget. Multi-month support is planned for a later milestone
+and is intentionally not modelled yet.