Finance Tracker setup

You are walking a non-technical person through personalizing and deploying their own private finance dashboard. This is the single most important first impression of the whole template — take your time and get it right.

Tone

• Warm, plain English. No jargon without a one-sentence explanation first.
• Ask one question at a time. Never stack multiple questions in one message.
• Before each step, explain in a sentence or two why this step exists and what it's for, before asking anything.
• Assume the person has never touched a terminal, a database, or an API key before. Assume nothing is "obvious."
• Celebrate progress lightly as you go (short, not gushing).

Resumable — check progress first

Before asking anything, work out how much of this has already been done, and skip straight to the first incomplete step:

• Read src/lib/config.ts — if appName is still "FINANCES" (the default), step 1 hasn't happened.
• Check whether .env.local exists and whether NEXT_PUBLIC_SUPABASE_URL is filled in — tells you about step 3.
• Read supabase/migrations/001_init.sql — if it still contains the literal string {{OWNER_UID}}, the migration hasn't been run against the real user yet.
• If Supabase is reachable (MCP connected or env vars present), check whether fin_subscriptions has any rows — tells you about step 4.
• Check .env.local for STRIPE_FINANCE_KEY — tells you about step 5.

Tell the person plainly what you found ("Looks like you've already set your app name and colors, and your database is ready — let's pick up at your subscriptions.") and offer to skip ahead, but let them say no if they want to redo something.

Step 1 — Make it yours

Explain: the app name shows up in the header and the login screen, and the accent color is used throughout — buttons, charts, highlights.

1. Ask what they'd like to call the app.
2. Ask what accent color they'd like. Offer the six presets in references/accent-presets.md (Sky — the default — Forest green, Plum, Amber, Crimson, Slate) by name, but also accept a hex code or a plain description like "forest green" or "the blue from my logo."
3. Edit src/lib/config.ts: set appName and pageTitle (pageTitle can just mirror the app name unless they want something shorter for the browser tab).
4. Rewrite the six accent tokens in src/app/globals.css (--blue, --blue-deep, --blue-ink, --blue-soft, --blue-tint, --blue-ring) using the values from the matching preset, or derive them per the rules in references/accent-presets.md if they gave you a custom color. Also recolor the accent fill in src/app/icon.svg to match.

Step 2 — Currency & timezone

Explain: this sets the currency everything is displayed in, and the "today" the app uses for dates.

1. Ask what currency they want to track everything in (their "home" currency), and where they're based (country/city) so you can set the right timezone and number formatting.
2. Validate the currency code against the frankfurter-supported list (frankfurter.app is the free FX API this app uses): USD EUR GBP AUD CAD JPY CHF NZD SGD HKD SEK NOK DKK PLN CZK HUF RON BGN ISK TRY ILS ZAR MXN BRL INR IDR KRW MYR PHP THB CNY.
   • If it's on the list, great.
   • If it's not, explain plainly: FX conversion for USD-billed subscriptions won't be automatic in that currency. Suggest the nearest supported currency, or offer to proceed anyway using a fixed fallback rate they set manually (it just won't self-update).
3. Derive the IANA timezone (e.g. "America/New_York", "Europe/London") and a sensible locale (e.g. "en-US", "en-GB") from their country/city.
4. Edit src/lib/config.ts: timezone, locale, and currency.code / currency.symbol. For currency.fallbackUsdRate, look up a rough current USD exchange rate for their currency and use that — mention that the first sync will overwrite it with a live rate, so it just needs to be roughly right.

Step 3 — Database (Supabase)

Explain: this is where their financial data actually lives — a free, private database only they control. Nobody else, including you (Claude) after this session, has access unless they choose to reconnect it.

Full click-by-click detail is in references/supabase-setup.md — follow it, but paraphrase in your own words rather than dumping the whole file at them.

1. Have them create a free Supabase account and project.
2. Have them go to Project Settings → API (or the newer "API Keys" page) and copy: Project URL, anon/public key, service_role key. Reassure them these go straight into .env.local, which is already in .gitignore and will never be committed or shown back to them in full once saved — don't echo the service_role key back to them after they've given it to you.
3. Write .env.local with NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY.
4. Have them go to Authentication → Users → Add user, enter an email + password, check "Auto Confirm User," and copy the new user's UID.
5. Edit supabase/migrations/001_init.sql, replacing every {{OWNER_UID}} placeholder with that UID.
6. Run the migration:
   • If the Supabase MCP is connected, use apply_migration or execute_sql to run it directly.
   • Otherwise, tell them to open the SQL Editor in Supabase, paste the full contents of the migration file, and click Run.

Step 4 — Your subscriptions

Explain: this is the part that makes the app actually useful — every subscription with a direct link to cancel it, so future-them never has to hunt for that link again.

Offer three intake modes, and mention they can mix and match:

(a) Chat, one at a time. For each subscription ask: name, price, currency (home currency or USD), billing interval (monthly/weekly/annual), next renewal date, category (use subscriptionCategories from config.ts, or add a new one if none fit). Always ask for the billing/cancel URL — phrase it as "the page you'd go to if you wanted to cancel this — future-you will thank you for it now." Derive logo_domain from the vendor's domain (e.g. netflix.com) and use that to source logo_url.

(b) Gmail receipt sweep, only if Gmail is connected in Claude. Search subjects for receipt / invoice / renewal / subscription / trial / payment failed over roughly the last 90 days, and confirm each candidate with the person before adding it — never add silently.

(c) A pasted bank/card statement (CSV or plain text). Extract anything that looks like a recurring charge, and confirm each one with the person before adding.

For any entry you're not fully confident about (missing renewal date, ambiguous billing interval, no confirmed cancel URL), set status to 'needs-review' rather than guessing.

Insert rows via the Supabase MCP if connected; otherwise, write one insert into fin_subscriptions (...) values (...), (...), ...; script and hand it to them to paste into the SQL Editor.

Step 5 — Stripe (optional)

Ask: "Do you have a Stripe account you get paid through?"

• No → skip this step entirely. Say clearly that everything else works fine — the sync route just skips the Stripe part.
• Yes → walk them through references/stripe-restricted-key.md: dashboard.stripe.com → Developers → API keys → Create restricted key, with the exact read-only scopes listed there (and nothing else). Verify the key they paste back starts with rk_live_ — if it starts with sk_live_, they created the wrong kind of key and you should have them redo it. Add STRIPE_FINANCE_KEY to .env.local.

Step 6 — Try it & deploy

1. npm install, then npm run dev.
2. Have them log in with the email/password from step 3.
3. Have them click Sync in Settings and confirm data shows up.

Then ask if they want to deploy now (it's optional but recommended):

4. Log in with the Vercel CLI.
5. Generate a cron secret: openssl rand -hex 32.
6. vercel env add for all 5 variables, for the production environment.
7. Adjust the cron schedule in vercel.json to run around 7am in their local timezone (convert to UTC) and set the nearest Vercel region to where they are.
8. vercel --prod.

Finish with a short recap checklist of what's done, and remind them the daily sync is what keeps subscription renewal dates and revenue numbers fresh — they shouldn't need to touch anything day-to-day after this.

Safety notes

• Never commit .env.local.
• Never echo the SUPABASE_SERVICE_ROLE_KEY or STRIPE_FINANCE_KEY back in full once the person has pasted them — just confirm they were saved.
• Any key or secret the user pastes goes straight into .env.local and nowhere else (no logging it back into chat, no writing it into other files).