# Project pack: Firefly III @ b9c3100

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

> Firefly III is a personal money manager. You record your bank accounts, spending and income, and it shows where your money goes with budgets, categories, charts and reports. Rules can sort your spending for you, and "piggy banks" help you save towards a goal. It runs on your own computer or server, so your bank data never has to go to the cloud.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Self-managed PHP + database install is documented; judged too heavy for a one-sitting non-technical setup. 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://github.com/firefly-iii/firefly-iii
- 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/firefly-iii/firefly-iii
- Pinned commit: `b9c31006e8d3008df3d12e23de86b66088c9480e`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/firefly-iii/firefly-iii/archive/b9c31006e8d3008df3d12e23de86b66088c9480e.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://docs.firefly-iii.org
- Live demo: https://demo.firefly-iii.org. Public demo with an example administration already filled in. Shared with everyone, so don't enter anything real.
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

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

  ```sh
  git clone https://github.com/firefly-iii/firefly-iii bespoke-firefly-iii
  cd bespoke-firefly-iii
  git checkout --detach b9c31006e8d3008df3d12e23de86b66088c9480e
  # Prepare development requirements and local configuration first.
  # Follow development setup in this checkout’s README and agents.md; configure a local database first.
  ```

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

  ```sh
  Download docker-compose.yml and database.env (save as .db.env) from github.com/firefly-iii/docker, and .env.example from this repo (save as .env). Set APP_KEY to a random 32-character string, and set the same database password in .env (DB_PASSWORD) and .db.env (MYSQL_PASSWORD). Then run: docker compose -f docker-compose.yml up -d --pull=always # then open http://localhost and create the first account
  ```
- Tools these commands use: Docker with Docker Compose, or for development PHP 8.5 + Composer + Node + MySQL/PostgreSQL/SQLite
- Test: `composer unit-test && composer integration-test`
- Stack: php, javascript, blade (Laravel 13, Alpine.js, Bootstrap 5, AdminLTE 4, Vite). Difficulty for a non-developer with an AI: **advanced**. A large Laravel app (PHP 8.5) with a strict double-entry bookkeeping model, a big REST API and many tests. Most personal changes are better done through rules, webhooks or the API than in the code.
- The project's own AI instructions, in the repository: `agents.md`.
Personal data: **yes**. Stored in: MySQL/MariaDB (default Docker setup), PostgreSQL or SQLite; uploaded files in the firefly_iii_upload volume. Secrets are entered by the person, never in chat.

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