;;; skill.lisp --- Agent-facing usage guide (`chirp skill').
;;;
;;; SPDX-License-Identifier: GPL-3.0-or-later
;;;
;;; Copyright (C) 2026 Anthony Green
;;;
;;; `chirp skill' prints a self-contained guide teaching a coding agent how to
;;; drive chirp: the journal-as-source-of-truth model, the account annotations
;;; that unlock cross-border treatment, and what each subcommand answers.  The
;;; same text is exposed to MCP clients as the `skill' tool (see mcp.lisp).

(in-package #:chirp)

(defparameter *skill-guide*
  "# chirp — cross-border (Canada/US) finance & retirement planning

chirp reads a **ledger-cli journal** (the single source of truth) and produces
cross-border, dual-currency, dual-tax reports for someone with ties to both
Canada and the US. It never writes to your journal. Every command takes
`-f <journal>` (or the `LEDGER_FILE` env var). If prices live in a separate
ledger price database, pass `--price-db <file>` (or set `LEDGER_PRICE_DB`).

## How chirp understands your accounts

chirp classifies each account by name, but you get correct treatment by adding
**metadata to `account` directives**. ledger ignores these `;` comments; chirp
reads them. Keys:

- `; class:` — force a tax class (rrsp, rrif, lira, tfsa, fhsa, resp, rdsp,
  ca-nonreg, ca-cash, 401k, traditional-ira, roth-ira, hsa, us-brokerage,
  us-cash, ca-realestate, us-realestate, mortgage). Overrides name guessing.
- `; country:` — ca or us.
- `; owner:` — who owns it (a name; used for ACB pooling, net-worth grouping,
  and per-owner tax). Put it on the Income account too, to attribute income.
- `; use:` — for real estate only: primary | rental | vacation.

Example:

    account Assets:CA:RRSP:Anthony
        ; class: rrsp
        ; owner: anthony

## Two things that are easy to get wrong

### Real estate — book it as a named commodity
Do NOT carry a property as a plain currency balance (chirp can't compute its
gain). Instead model it as ONE unit of a named commodity, priced at cost:

    account Assets:CA:RealEstate:Home
        ; class: ca-realestate
        ; use: primary
    2015-06-01 * buy home
        Assets:CA:RealEstate:Home    1 HOME @ CAD 500000.00
        Assets:CA:Cash
    2026-06-01 * sell home
        Assets:CA:RealEstate:Home   -1 HOME @ CAD 1000000.00
        Assets:CA:Cash

With `use: primary`, `chirp gains` applies Canada's principal-residence
exemption (gain tax-free) and the US §121 exclusion ($250k single / $500k mfj),
so the residual US gain is shown. `use: rental` is fully taxable and counts
toward T1135. For a CAD mortgage classed `mortgage`, `chirp networth` computes
the realized IRC §988 exchange gain on each principal repayment, and `chirp tax`
includes it as US ordinary income in the repayment year (US persons only).

### Mixed households — declare each owner's tax profile
By default chirp assumes one filer: a US citizen resident in Canada. If a
spouse is NOT a US person (e.g. Canadian-only), declare it so they aren't taxed
as one — their TFSA is genuinely tax-free, no FBAR/FTC, Canadian tax only:

    account Owner:sam
        ; citizen: ca
        ; resident: ca
    account Owner:anthony
        ; citizen: us,ca
        ; resident: ca

Then `chirp tax` prints a per-owner breakdown plus a household total, taxing
each person under their own profile.

## Commands

- `chirp networth`  — consolidated net worth by country/class/owner, plus
  FBAR / Form 8938 / T1135 threshold flags and §988 mortgage warnings.
- `chirp fbar`      — FBAR (FinCEN 114) *maximum* value of each foreign account
  over a `--year` (the peak balance, not a snapshot), with the $10k threshold.
- `chirp t1135`     — CRA T1135 specified foreign property on a *cost* basis:
  the max ACB cost over a `--year` and the year-end cost, with the CAD 100k
  threshold.
- `chirp income`    — income by type and source country, dual-currency (the
  groundwork the foreign tax credit rests on).
- `chirp gains`     — realized capital gains, dual-method (CRA/ACB in CAD and
  IRS/FIFO in USD), with real-estate exemptions. `--filing single|mfj`.
- `chirp tax`       — federal income-tax estimate, US and Canada, per owner,
  including NIIT (3.8%), the OAS clawback, and multi-year capital-loss
  carryforward. `--year --filing --province --state`.
- `chirp ftc`       — US Form 1116 foreign-tax-credit position and multi-year
  carryover. `--resource` applies treaty re-sourcing.
- `chirp optimize`  — tax-minimising withdrawal-source mix for a one-year
  after-tax `--spend` target.
- `chirp plan`      — multi-year drawdown plan (`--spend --years --province`),
  with `--montecarlo N` for success probability and CPP/OAS/SS claiming timing.
  Real-dollar model (fully-indexed brackets by default); `--bracket-drift` models
  under-indexation. Accounts for the OAS clawback band.
- `chirp classify`  — show how each account is classified.
- `chirp mcp`       — run as an MCP server (stdio) exposing these as tools.

## Workflow for an agent

1. Read the user's journal; check `chirp classify -f FILE` to see how accounts
   resolve. Add `; class:`/`; country:`/`; owner:`/`; use:` where wrong.
2. For real estate, ensure it is a named commodity with a `use:` annotation.
3. For a mixed household, add `Owner:` profile directives.
4. Run `networth`, `income`, `gains`, `tax`, `ftc` to build the picture.
5. Use `optimize`/`plan` for forward-looking drawdown and claiming questions.

All figures are estimates on 2025 brackets — informational, not tax advice.
"
  "The `chirp skill' guide text, also served as the MCP `skill' tool.")

(defun skill-report (&key (stream *standard-output*))
  "Print the agent-facing usage guide."
  (write-string *skill-guide* stream)
  (values))