{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/budget-coach",
  "slug": "adapters/domain/budget-coach",
  "kind": "capabilities",
  "bucket": "package",
  "title": "budget-coach",
  "name": "Budget Coach",
  "eyebrow": null,
  "chip": null,
  "summary": "Personal-budgeting and money-coaching microservice: split take-home income into the 50/30/20 rule (needs/wants/savings) or any custom ratio; build a zero-based envelope budget across custom spending...",
  "keywords": [
    "budget-coach",
    "personal-budgeting",
    "money-coaching",
    "income",
    "zero-based",
    "snowball",
    "smallest-balance-first",
    "avalanche"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# budget-coach\n\nA **personal-budgeting & money-coaching microservice**. Deterministic household-finance math:\nallocate income by the 50/30/20 rule, build zero-based envelope budgets, plan debt payoff with the\nsnowball **and** avalanche methods (and compare them), project savings growth, size an emergency\nfund, and compute a savings rate. Coaching tools *also* attach an optional plain-English LLM tip and\nsilently fall back offline; results are tagged `mode: 'heuristic' | 'llm'`. The numbers are always\npure math — a model never affects them.\n\n## Tools\n\n| Tool | Input | Output |\n|---|---|---|\n| `allocate` | `{ income, options:{needs?,wants?,savings?} \\| {ratios} }` | Income split into needs/wants/savings (50/30/20 default) or a custom ratio, summing exactly to income. **+optional tip.** |\n| `envelope` | `{ income, categories }` | Zero-based envelope budget; per-category % of income + surplus/overspent/balanced status. |\n| `debtSnowball` | `{ debts:[{name,balance,apr,minPayment}], extra? }` | Payoff simulation, smallest-balance-first: months to payoff, total interest, per-debt order. |\n| `debtAvalanche` | `{ debts, extra? }` | Same simulation, highest-APR-first (cheapest total interest) — compare against snowball. |\n| `savingsProjection` | `{ monthly, rate, months, options:{principal?} }` | Compound growth of a monthly contribution: future value, interest earned, yearly milestones. **+optional tip.** |\n| `emergencyFund` | `{ expenses, options:{targetMonths?,current?} }` | Target fund = expenses × months of runway; the gap and a funding rating. |\n| `savingsRate` | `{ income, savings }` | Savings ÷ income %, with a health rating against the 15–20% benchmark. |\n\nAPR accepts either a decimal (`0.1999`) or a percent (`19.99`).\n\n## Usage\n\n```js\nimport pack from './index.js';\n\npack.adapters.allocate({ income: 4000 });\n// -> { rule:'50/30/20', buckets:{ needs:2000, wants:1200, savings:800 }, ... }\n\npack.adapters.debtAvalanche({\n  debts: [\n    { name: 'Card A', balance: 2000, apr: 22, minPayment: 50 },\n    { name: 'Card B', balance: 5000, apr: 8,  minPayment: 100 },\n  ],\n  extra: 300,\n});\n// -> { strategy:'avalanche', monthsToPayoff: N, totalInterest: X, payoffOrder:[...] }\n```\n\n## DRY boundaries\n\n- **Distinct from `finance`.** `finance` owns loan amortization, mortgages, time-value-of-money\n  (PV/FV/NPV/IRR/PMT), depreciation, and currency formatting. `budget-coach` owns *household\n  budgeting*, *debt-payoff ordering/comparison*, and *savings / emergency-fund planning*. The\n  savings-projection compounding here is a budgeting tool (recurring contribution + goal framing),\n  not a TVM primitive.\n- Self-contained: the only cross-pack import is `../_shared/llm.js`.\n- Pure ESM, Node built-ins only, zero npm deps.\n",
  "source": {
    "path": "shared/engines/adapters/domain/budget-coach/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 2979,
    "hash": "513751b4e81b68b0b4ec99835533a18b38cfc510"
  },
  "urls": {
    "html": "/p/adapters/domain/budget-coach",
    "json": "/docs/adapters/domain/budget-coach.json",
    "md": "/docs/adapters/domain/budget-coach.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}