# Project pack: Beaver Habit Tracker @ 332a453

Facts about **Beaver Habit Tracker** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Beaver Habit Tracker is a simple checklist for the things you want to do regularly, like a walk, reading or calling your mum. Each habit has a row of days you tick, plus a calendar and heatmap that show how you've been doing. There are no targets or scores, just a record. It runs on your own computer or server and works well on a phone.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://raw.githubusercontent.com/daya0576/beaverhabits/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/daya0576/beaverhabits
- Pinned commit: `332a45336158a4a50885b4d3bc6146cd27528fc9`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/daya0576/beaverhabits/archive/332a45336158a4a50885b4d3bc6146cd27528fc9.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://github.com/daya0576/beaverhabits/wiki
- Live demo: https://beaverhabits.com/demo. Official demo on the author's hosted service. Nothing you enter there is private.
- Licence: **BSD-3-Clause**. Very permissive. You can use, change and share it, even commercially. If you pass on copies, keep the copyright notice and licence text, and don't use the author's name to promote your version.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/daya0576/beaverhabits bespoke-beaverhabits
  cd bespoke-beaverhabits
  git checkout --detach 332a45336158a4a50885b4d3bc6146cd27528fc9
  # Prepare development requirements and local configuration first.
  # Setup notes: app on http://localhost:9001 with auto-reload
  uv venv && uv sync && ./start.sh dev
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  mkdir -p beaver && docker run -d --name beaverhabits -u $(id -u):$(id -g) -e HABITS_STORAGE=USER_DISK -v ./beaver/:/app/.user/ -p 8080:8080 daya0576/beaverhabits:latest # then open http://localhost:8080 and register your account
  ```
- Tools these commands use: Docker, or for development Python 3.12+ and uv
- Develop: `uv venv && uv sync && ./start.sh dev   # app on http://localhost:9001 with auto-reload`
- Test: `uv sync --group fly && DATABASE_URL="sqlite+aiosqlite:///:memory:" HABITS_STORAGE="USER_DISK" uv run pytest`
- Stack: python (FastAPI, NiceGUI, Quasar, SQLAlchemy, fastapi-users). Difficulty for a non-developer with an AI: **easy**. A small, single-language project (about 60 Python files). The screens are written in Python with NiceGUI, so there is no separate JavaScript build. Display options are environment variables and per-user custom CSS. Code changes live in beaverhabits/frontend/ (screens) and beaverhabits/storage/ (data).
- The project's own AI instructions, in the repository: `.github/copilot-instructions.md`.
Personal data: **yes**. Stored in: The /app/.user folder in the container: one JSON file per user (HABITS_STORAGE=USER_DISK) or habits.db (SQLite). PostgreSQL is possible through DATABASE_URL. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/beaverhabits/332a453/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/beaverhabits/332a453/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/beaverhabits/332a453/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/beaverhabits/332a453/r3/SKILL.md)