Update to BTC DCA Engine

{
  "name": "dca-simulations",
  "description": "Use when someone asks what a regular buying plan would have been worth — \"what if I'd put $50 a week into Bitcoin since 2018\" — or wants to compare assets, buying schedules or start dates against real price history. Covers how to call the BTC DCA Engine tools and how to report what comes back.",
  "included_files": [],
  "skill_md_contents": "---\nname: dca-simulations\ndescription: Use when someone asks what a regular buying plan would have been worth — \"what if I'd put $50 a week into Bitcoin since 2018\" — or wants to compare assets, buying schedules or start dates against real price history. Covers how to call the BTC DCA Engine tools and how to report what comes back.\n---\n\n# Running a dollar-cost-averaging simulation\n\nThe BTC DCA Engine answers one question with arithmetic: given an asset, an amount, a schedule and a\nstart date, what would that plan be worth now? It reads published daily closes. It does not forecast,\nrecommend or trade.\n\n## Start with the catalogue\n\nCall `list_assets` before composing a plan unless you already know the exact key. It returns each\nasset's key, the dates its price series covers, and how often that series has a value. Two things go\nwrong without it:\n\n- **Asset keys are exact strings.** Bitcoin is `btc_daily`; the S&P 500 is `S&P 500`. A guessed name\n  is refused rather than silently matched to something close.\n- **A start date before an asset's first close is refused**, and the refusal names the first date.\n  Solana begins in April 2020, Ethereum in November 2017; several macro series are quarterly, so a\n  weekly plan on them buys on the dates that exist.\n\n## Composing a run\n\n`run_dca` takes one plan, `compare_plans` takes several and ranks them by final value.\n\n- `amount` is money per purchase, not a total.\n- `frequency` is `daily`, `weekly`, `monthly` or `quarterly`.\n- `start_date` and the optional `end_date` are `YYYY-MM-DD`.\n- `as_of` pins the run to a data vintage. Use it whenever the figure will be written down or compared\n  later: without it, the same request returns a slightly different answer tomorrow, because the\n  underlying data has moved on.\n- `include` asks for the per-purchase ledger (`head` for the first 20, `all` up to 200) and\n  end-of-year checkpoints. Ask for the ledger only when someone wants to see individual buys.\n\n## Reporting the result\n\nLead with what was put in and what it is worth, then the returns:\n\n- `total_invested` and `final_value`, and `net_profit` between them.\n- `simple_annualized_pct` is the growth of the whole pot per year. `money_weighted_pct` accounts for\n  money arriving over time, and is the honest figure for a plan that bought gradually. If you quote\n  only one, quote the money-weighted one, and say which it is.\n- `units` is how much of the asset the plan accumulated.\n- `data_as_of` is the date the prices run to. Say it — a value \"today\" means the last completed day.\n\n**Always pass on the `share_url`.** It reopens the identical run in the web app, pinned to the same\ndata, so the person can see the chart and check the numbers rather than take them on trust.\n\nKeep the answer readable: short labelled lines rather than a wide table, and the link on its own.\n\n## What needs an account\n\nWithout one, seven assets are available — Bitcoin, Ethereum, Solana, XRP, the S&P 500, the Nasdaq 100\nand gold — and two plans per comparison. The rest of the catalogue, larger comparisons, and the\nlump-sum, inflation, Mayer Multiple, risk and buy-rule settings need a paid account. A request beyond\nthe free plan is refused with a message naming what it needs; relay that plainly and move on. Do not\npush the paid tier, and do not retry the same request hoping it goes through.\n\n## Saying it accurately\n\n- These are historical outcomes, not predictions. Never present a result as advice or a forecast.\n- Past returns say nothing about future ones, and the engine's own results carry that note.\n- If someone asks \"should I\", answer what the history shows and leave the decision with them.\n"
}