# Project pack: Sure @ c7a3748

Facts about **Sure** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Sure is a personal finance app for the whole family. It brings your bank accounts, cards, savings, investments and property into one picture, shows your net worth over time, and helps you budget, spot regular bills and save towards goals. It is the community-run continuation of Maybe Finance. You can run it on your own computer or server, and AI help is optional.

## Version and source
- Repository: https://github.com/we-promise/sure
- Pinned commit: `c7a3748aa87df7ffe7422a9132d538ac2ed45bdb`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/we-promise/sure/archive/c7a3748aa87df7ffe7422a9132d538ac2ed45bdb.zip
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just your household), you must offer them your source code under the same licence. "Maybe" is a trademark of Maybe Finance Inc., so a fork must not use that name or logo and must say it isn't affiliated with Maybe Finance.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/we-promise/sure bespoke-sure
  cd bespoke-sure
  git checkout --detach c7a3748aa87df7ffe7422a9132d538ac2ed45bdb
  # Prepare development requirements and local configuration first.
  # Setup notes: app on :3000; optional demo data: rake demo_data:default
  cp .env.local.example .env.local && bin/setup && bin/dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  mkdir sure && cd sure && curl -fsSL -o compose.yml https://raw.githubusercontent.com/we-promise/sure/c7a3748aa87df7ffe7422a9132d538ac2ed45bdb/compose.example.yml && docker compose up -d
  # then open http://localhost:3000 and create your account.
  # Before using it outside your home network, set SECRET_KEY_BASE and POSTGRES_PASSWORD in a .env file (see docs/hosting/docker.md).
  ```

- Needs: Docker with Docker Compose, or for development Ruby 3.4.9 + PostgreSQL + Redis + Node
- Develop: `cp .env.local.example .env.local && bin/setup && bin/dev   # app on :3000; optional demo data: rake demo_data:default`
- Test: `bin/rails test`
- Check/lint: `bin/rubocop && bundle exec erb_lint ./app/**/*.erb && npm run lint && bin/brakeman --no-pager`
- Stack: ruby, javascript, erb, css (Ruby on Rails, Hotwire (Turbo and Stimulus), ViewComponent, Tailwind CSS, Sidekiq). Difficulty for a non-developer with an AI: **advanced**. A large Rails app with a database, a background worker, Redis and many bank-sync providers. Upstream keeps detailed agent guides (AGENTS.md and docs/llm-guides/) and a strict design system, which helps an AI agent work safely.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`, `docs/llm-guides/architecture.md`, `docs/llm-guides/design-system.md`.

## Customisation points (settings → extend → code)
- **preferences** [settings]: Currency, language, date format and theme (light or dark) for the household. → `Settings → Preferences (app/views/settings/preferences/); translations in config/locales/`
- **rules** [settings]: Automatically set the category, merchant, tags or name of transactions, or send an email when one matches. → `Settings → Rules (actions in app/models/rule/action_executor/)`
- **budgets-bills-goals** [settings]: Monthly budgets by category, automatically spotted regular bills, and savings goals. → `Budgets, Bills (recurring transactions) and Goals pages; see docs/hosting/recurring-bills.md`
- **self-hosting-settings** [settings]: Sign-up rules, market-data provider, logo lookups and the AI provider. → `Settings → Self-Hosting (app/views/settings/hostings/show.html.erb) and the .env file`
- **rebrand** [settings]: Show your own name for the app, such as "Patel Family Money". → `PRODUCT_NAME and BRAND_NAME environment variables (config/initializers/brand.rb)`
- **api-and-mcp** [extend]: Scripts, phone shortcuts and outside AI assistants that read or add transactions. → `REST API in app/controllers/api/v1/ (docs/api/openapi.yaml); MCP server for AI assistants (docs/hosting/mcp.md)`
- **imports** [extend]: Bring in bank statements or connect a bank, card or crypto account. → `Imports (CSV and other files; app/models/import.rb) and bank-sync providers (app/models/*_item.rb)`
- **screens-and-components** [code]: New screens and widgets, using the design-system components and colour tokens in app/assets/tailwind/sure-design-system.css. → `app/views/**, app/components/** (shared DS components in app/components/DS/), app/javascript/controllers/`
- **models-and-data** [code]: New data or calculations, scoped to the family. → `app/models/**, app/controllers/**, db/migrate/`

## Must keep working
- Existing accounts, balances, transactions and history. Back up the database before any code change.
- Family scoping. One family must never see another family's data; use Current.family as AGENTS.md says.
- Bank-sync providers and imports (docs/llm-guides/providers.md).
- The REST API and MCP endpoint, used by the mobile app, the desktop app and outside AI assistants.
- New database changes need a new migration; leave old migrations alone.

## Staying updatable
Use settings, rules, the PRODUCT_NAME and BRAND_NAME variables, the API and the MCP server first. For code, follow AGENTS.md and the design-system guide (DS components and colour tokens only), keep changes small, and add tests. Upstream welcomes contributions, so a useful feature can go back to the community.

## Data, costs and safety
- Personal data: **yes**. Stored in: PostgreSQL (postgres-data volume), Redis for background jobs, uploaded files in the app-storage volume. This is your full financial picture. Back up the PostgreSQL database (docs/hosting/docker.md describes an optional backup container using bin/db-backup.sh) before upgrades or code changes. Settings → Exports gives you a copy of your data.
- Service: OpenAI-compatible AI provider (OpenAI, or a local model such as Ollama), or Anthropic (optional, pay-per-use (or free with a local model)): The built-in AI assistant that answers questions about your money, and automatic categorising.
- Service: Bank connections (Plaid, SimpleFIN, Enable Banking, Lunch Flow, Monobank and others) (optional, varies; some free, some paid): Pull in transactions automatically instead of importing CSV files.
- Service: Market data (Yahoo Finance by default, or Twelve Data) (optional, free (Twelve Data has a free tier)): Exchange rates and share prices for investment accounts.
- Service: Brandfetch (optional, free tier): Logos for banks and shops.
- Service: Email (SMTP) (optional, free with most providers): Invitations, password resets and rule-based email alerts.
- Setting `SECRET_KEY_BASE` (**secret**: the person enters it themselves, never in chat): A long random key that protects logins. Generate it with openssl rand -hex 64. Never paste it into an AI chat.
- Setting `POSTGRES_PASSWORD` (**secret**: the person enters it themselves, never in chat): The database password. Set it before the first start if the app will be reachable from outside your home.
- Setting `ONBOARDING_STATE`: Who can sign up (open, closed or invite_only).
- Setting `APP_DOMAIN`: The address your Sure instance is hosted at, used for links in emails.
- Setting `PRODUCT_NAME`: The app's display name (defaults to "Sure").
- Setting `BRAND_NAME`: The brand name shown alongside the product name (defaults to "FOSS").
- Setting `OPENAI_ACCESS_TOKEN` (**secret**: the person enters it themselves, never in chat): Only if you turn on the AI assistant with an OpenAI-compatible provider. Use OPENAI_URI_BASE and OPENAI_MODEL for a local model.
- Setting `EXCHANGE_RATE_PROVIDER`: Where exchange rates come from (yahoo_finance by default, or Twelve Data).
- Holds complete financial records. Set SECRET_KEY_BASE and a database password, use HTTPS (RAILS_ASSUME_SSL) and set ONBOARDING_STATE to closed or invite_only before exposing it to the internet.
- The AI assistant and bank-sync providers send financial data to outside services. Use a local model to keep AI questions at home.
- API keys, bank-provider tokens and SMTP passwords are secrets. Never paste them into an AI chat.

---

# Customising Sure

Sure is a large Rails app (the community fork of Maybe Finance). **Most household adaptations are settings, rules and environment variables.** Upstream has excellent agent guides, so code changes are well signposted, but they still need merging on every update.

## Level 1: Settings (no code)
- **Preferences:** Settings → Preferences. Currency, language, date format and theme (light, dark or system).
- **Name:** set `PRODUCT_NAME` (and `BRAND_NAME`) in the environment to show your own name for the app (see `config/initializers/brand.rb`).
- **Rules:** Settings → Rules. Set the category, merchant, tags or name of matching transactions, mark transfers, or send an email when one matches. Rules can run on past transactions too.
- **Budgets, Bills and Goals:** monthly category budgets; Sure spots regular bills from your history and asks you to confirm them (`docs/hosting/recurring-bills.md`); savings goals can track one or more accounts.
- **Self-Hosting settings:** Settings → Self-Hosting. Who can sign up (`ONBOARDING_STATE`), market data provider, Brandfetch logos and the AI provider.
- **AI assistant:** optional. Use OpenAI, Anthropic or any OpenAI-compatible server such as Ollama (`OPENAI_URI_BASE`, `OPENAI_MODEL`). See `docs/hosting/ai.md`.

## Level 2: Extend (no fork)
- **Imports:** Settings → Imports takes CSV files from your bank, plus other formats. Mappings can be reused.
- **Bank connections:** Plaid, SimpleFIN, Enable Banking, Lunch Flow, Monobank and more. Each has a guide in `docs/hosting/`.
- **REST API:** documented in `docs/api/openapi.yaml` and `docs/api/*.md`. Good for phone shortcuts, spreadsheets and scripts.
- **MCP server:** lets an outside AI assistant (such as Claude Desktop) read and act on your data (`docs/hosting/mcp.md`).
- **Other apps:** a desktop app and a mobile app use the same server (`docs/clients.md`).

## Level 3: Code
Read upstream `AGENTS.md` and `docs/llm-guides/architecture.md` first. For any screen change, read `docs/llm-guides/design-system.md`.

| Change | Where |
|---|---|
| New page | `config/routes.rb` → `app/controllers/**` → `app/views/**` (keep logic out of ERB) |
| Shared UI pieces | `app/components/DS/` (use these first), other components in `app/components/` |
| Colours and styles | Functional tokens in `app/assets/tailwind/sure-design-system.css` (changing this file needs upstream's permission if you plan to contribute) |
| Front-end behaviour | Stimulus controllers in `app/javascript/controllers/` |
| Business logic | `app/models/**` (models, concerns, plain Ruby objects); rule actions in `app/models/rule/action_executor/` |
| API | `app/controllers/api/v1/` + Minitest + rswag docs in `spec/requests/api/v1/` |
| New data | a new migration in `db/migrate/` |
| Text | `config/locales/**/en.yml`, used through `t()` |

## Running locally
- **Just use it:**
  1. Make a folder and download `compose.example.yml` into it as `compose.yml`.
  2. Run `docker compose up -d` and open http://localhost:3000.
  3. Before using it outside your home network, create a `.env` with `SECRET_KEY_BASE` (from `openssl rand -hex 64`) and `POSTGRES_PASSWORD`, and follow `docs/hosting/docker.md`.
- **Develop:** Ruby 3.4.9, PostgreSQL and Redis. Run `cp .env.local.example .env.local`, `bin/setup`, then `bin/dev`, and open http://localhost:3000. `rake demo_data:default` loads demo data (login `user@example.com` / `Password1!`).
- **Check:** `bin/rails test`, `bin/rubocop`, `bundle exec erb_lint ./app/**/*.erb`, `npm run lint`, `bin/brakeman --no-pager`.

## Pitfalls
- Back up PostgreSQL first. The optional backup container in `compose.example.yml` uses `bin/db-backup.sh`.
- Use `Current.family` and `Current.user`. Never bypass family scoping.
- Use DS components and colour tokens. No raw Tailwind colours or hex codes; upstream reviewers reject them.
- Don't rename the app "Maybe" or use its logo. It's a trademark.
- AGENTS.md asks agents not to start the Rails server or run migrations on their own. Ask the user first.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/sure/c7a3748/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/sure/c7a3748/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/sure/c7a3748/r2/SKILL.md)