# Ledger Intent Format (LIF) v1

When your user says something about their money — *"the transfer from Xiaojuan is rent"*, *"lunch 35 paid with WeChat"* —
write it as one JSON object per line and send it to `POST /v1/ledger/convert` in `intents`.
We turn it into Beancount text, using the user's own accounts, rules and conventions if you send their ledger.

- One JSON object per line (JSON Lines). A JSON array is also accepted. Blank lines and lines starting with `#` are ignored.
- A bad line is skipped and reported in `intent_issues` (with its line number); the other lines still apply.
- Unknown fields are ignored (with a warning), so you can add `"v": 1` or your own notes safely.
- Max 500 intents per call.

## Operations

| op | What it does | Required | Optional |
|---|---|---|---|
| `txn` | Record one transaction | `date`, `amount` | `category`, `account`, `payee`, `narration`, `currency`, `time`, `ref`, `tags` |
| `rule` | From now on, classify matching statement rows this way (saved in `wearcal.json` → `rules`) | `category`, and at least one of `payee` / `narration` / `kind` | `direction` (`in`/`out`), `min`, `max`, `as` (rewrite the narration) |
| `alias` | A name the user uses for an account ("零钱" → WeChat) | `name`, `account` | |
| `self` | Counterparty is the user themself → transfers, not income/expense | `name` | |
| `hint` | A plain-language note for the classifier | `text` | |
| `balance` | Balance assertion at the start of `date` (liabilities are negative) | `date`, `account`, `amount` | `currency` |

### Fields

- `date`: `YYYY-MM-DD` in the user's local time. `time`: `HH:MM` or `HH:MM:SS`.
- `amount`: signed number. **Negative = money leaves `account`** (spending, transfer out); positive = money comes in (income, refund, transfer in).
- `category`: an expense / income category, **or another money account** (then it is a transfer). Accepts a Beancount account
  (`Expenses:Food:Lunch`), a display name (`午饭`, `Lunch`) or a path (`餐饮 › 午饭`, `Food/Lunch`).
  Unknown categories are created by name. Omit it and we classify with the user's rules and conventions (unclassified → flagged `!`).
- `account`: where the money is — Beancount account, display name, alias, or a card description like `招商银行信用卡(5678)`, `微信`, `支付宝`, `现金`.
  Omitted or unrecognised → booked to a placeholder account and flagged `!`.
- `ref`: your own id for the transaction. If the user's ledger already has this ref, the line is skipped (no duplicates on retries).
- `currency`: ISO code or Beancount commodity; defaults to the ledger's operating currency.

## Examples

```jsonl
# "The transfer Xiaojuan sends me is rent" (a standing rule, applied to every statement from now on)
{"op":"rule","payee":"小娟","direction":"in","category":"房租","as":"房租"}
# "Lunch 35, paid with WeChat"
{"op":"txn","date":"2026-11-17","amount":-35,"category":"午饭","account":"微信","payee":"楼下面馆"}
# "I paid 500 from my CMB debit card to my CMB credit card" (a transfer: category is a money account)
{"op":"txn","date":"2026-11-17","amount":-500,"account":"招商银行储蓄卡(1024)","category":"招商银行信用卡(5678)","narration":"信用卡还款"}
# "零钱 means my WeChat balance"
{"op":"alias","name":"零钱","account":"微信"}
# "My credit card owed 3,214.50 on Nov 1"
{"op":"balance","date":"2026-11-01","account":"招商银行信用卡(5678)","amount":-3214.5}
```

## What you get back

- `bean`: Beancount text to append to the user's ledger (for a new ledger: a complete file with `option` and all `open`s).
- `config_json`: the updated `wearcal.json` (rules, aliases, …) — save it next to `main.bean`; `null` if nothing changed.
- `counts.pending`: how many transactions are flagged `!` — ask the user to confirm those.
- `intent_issues`: lines that were skipped or had ignored fields.

Send the user's ledger (`ledger.files`: `main.bean`, the files it includes, `wearcal.json`) so accounts, rules and conventions are reused and
already-recorded transactions are skipped. We read it and forget it — nothing is stored.
