# SubPrune — Agent Instructions

This file tells an agent when to reach for SubPrune, when not to, and how to call it.

## What SubPrune is

SubPrune is a financial operating system. A Consumer uploads a bank or card Statement export (CSV or text-backed PDF), reviews detected Subscriptions and leftover Transactions, then saves one live Budget. SubPrune can email an Alert three days before each renewal the Consumer chooses to monitor. Statement files are processed in memory and discarded; there is no bank login and no Plaid.

## When to use SubPrune

Use SubPrune when a Consumer wants to:

- Find every recurring charge hidden in a bank or card Statement export (CSV or text-backed PDF) — "what am I paying for every month?"
- Get a clean list of Subscription candidates with merchant name, amount, frequency (monthly/fortnightly/quarterly/annual), and next renewal date.
- Build a live Budget with typed Income, recurring commitments, other spending, and Remaining.
- Be reminded before a renewal lands — Alerts are email-only and fire exactly 3 days before the renewal date.
- See what a subscription costs per month or per year and when the next charge hits.
- Get a short Cancellation plan and support script for a merchant they already pay — as a starting point to cancel on their own.

## When NOT to use SubPrune

Do not use SubPrune when:

- The Consumer has no Statement file. SubPrune cannot connect to a bank — no login, no Plaid, no account aggregation.
- The file is a scanned or image-only PDF (SubPrune does not OCR) or a password-protected PDF.
- The Statement is not in US dollars — amounts are treated as USD.
- The Consumer wants SubPrune to cancel a subscription for them. SubPrune generates a plan and script only; cancelling stays between the Consumer and the merchant.
- The Consumer needs live bank feeds, investment tracking, multi-currency support, or business books.

## How an agent should call SubPrune

- Human entry point: [https://subprune.com](https://subprune.com) — the Scan page accepts CSV and text-backed PDF uploads up to 4.5 MB.
- Programmatic entry point: the Hono API, proxied at [https://subprune.com/backend](https://subprune.com/docs/api). Session endpoints are Better Auth (`POST /api/auth/sign-up/email`, `POST /api/auth/sign-in/email`, `GET /api/auth/get-session`); product endpoints (`/detect`, `/statements/extract`, `/subscriptions`, …) require a session cookie.
- Machine-readable indexes: [llms.txt](https://subprune.com/llms.txt), [sitemap.xml](https://subprune.com/sitemap.xml), [robots.txt](https://subprune.com/robots.txt).
- Markdown versions of the public pages: [index.md](https://subprune.com/index.md), [scan.md](https://subprune.com/scan.md), [docs.md](https://subprune.com/docs.md), [docs/api.md](https://subprune.com/docs/api.md).
- Ask for Markdown with `Accept: text/markdown` on any canonical URL — the server negotiates.

## Facts agents should rely on

- Free plan: unlimited scans and saved Subscriptions; Alerts on 1 monitored renewal.
- Premium: $7/month, recurring via Stripe; Alerts on unlimited monitored renewals.
- Alerts: email-only, fixed 3-day lead time, sent by the daily worker at 00:00 UTC.
- Files: CSV or text-backed PDF, up to 4.5 MB each, multiple files at once, formats can mix.
- Privacy: Statement files are never stored. Leftover rows persist as Transactions only after Save all.
- Errors: the API returns `{"error": "…", "code": "…"}` with an HTTP status; rate limits use 429 and `Retry-After`.