spltty 0.1.0

data/lib/spltty_cli/totals.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  # Per-person totals + settlement for ledger tables. The Responsible cell is
+  # resolved against split groups — the row's ledger header groups first, then
+  # the global config groups — rather than by parsing a `Both (NN/NN T/C)` string.
+  # A match splits the value by the group's participant percentages; anything
+  # that matches no group is a person (100% to that name).
+  #
+  # Two dimensions are reported: RESPONSIBLE (what each person owes) and PAID BY
+  # (what each fronted). Net = Paid - Owed drives the greedy settlement.
+  module Totals
+    module_function
+
+    EPS = 0.005
+
+    # A **reference ledger** intentionally duplicates rows that already exist in
+    # a primary ledger (a project tracker mirroring shared spend, say). Its rows
+    # are copies, not new spend, so it must never be summed with the primaries.
+    # Marked per ledger with `reference: true` — in the ledger's notes header
+    # (the source of truth) or directly in config.json.
+    def reference?(config, name)
+      entry = config.ledgers[name]
+      entry.is_a?(Hash) && entry["reference"] == true
+    end
+
+    # Names of every ledger flagged as a reference ledger.
+    def reference_ledgers(config)
+      config.ledgers.keys.select { |name| reference?(config, name) }
+    end
+
+    # Build a resolver lambda for one ledger: name -> split Hash (or nil).
+    # The ledger's own groups shadow the global groups.
+    def resolver(config, ledger_key)
+      ledger_groups = (ledger_key && config.ledgers[ledger_key] && config.ledgers[ledger_key]["groups"]) || {}
+      global_groups = config.groups
+      ->(name) { ledger_groups[name] || global_groups[name] }
+    end
+
+    # { person => amount_owed } for one row. Group -> proportional split by
+    # pct/sum(pct); otherwise the whole value goes to the (person) name.
+    def owed_split(value, resp, resolver)
+      split = resolver.call(resp)
+      if split.is_a?(Hash) && !split.empty?
+        total = split.values.sum.to_f
+        return { resp => value } if total.zero?
+
+        split.transform_values { |pct| value * pct / total }
+      else
+        { resp => value }
+      end
+    end
+
+    # Parse a ledger table file -> [{ value:, paid:, responsible: }]: only "|"
+    # lines, skip the separator, first row is the header, columns addressed by
+    # name, rows with a non-numeric value are skipped.
+    def read_rows(path)
+      rows = []
+      header = nil
+      vi = pi = ri = nil
+      File.foreach(path) do |line|
+        next unless line.strip.start_with?("|")
+
+        cells = Table.row_cells(line)
+        next if Table.separator?(cells)
+
+        if header.nil?
+          header = cells
+          idx = header.each_index.to_h { |i| [header[i], i] }
+          vi = idx["Value (R$)"]
+          pi = idx["Paid By"]
+          ri = idx["Responsible"]
+          raise ArgumentError, "#{path}: missing Value (R$)/Responsible header" if vi.nil? || ri.nil?
+
+          next
+        end
+
+        next if cells.length <= [vi, ri].max
+
+        value = (Float(cells[vi]) rescue nil)
+        next if value.nil?
+
+        paid = pi && pi < cells.length ? cells[pi] : ""
+        rows << { value: value, paid: paid, responsible: cells[ri] }
+      end
+      rows
+    end
+
+    # All entry rows for a ledger: a monthly ledger merges every YYYY-MM.md;
+    # a single-file ledger is its one .ledger.md.
+    def ledger_rows(config, name)
+      entry = config.ledgers[name]
+      if entry["type"] == "monthly"
+        dir = File.join(config.accounts_dir, entry["dir"] || name)
+        months = Dir.children(dir).select { |f| f =~ Discovery::MONTH_FILE }.sort
+        months.flat_map { |m| read_rows(File.join(dir, m)) }
+      else
+        file = File.join(config.accounts_dir, entry["file"] || "#{name}.ledger.md")
+        File.exist?(file) ? read_rows(file) : []
+      end
+    end
+
+    # Accumulate paid/owed/spending-breakdown for a set of rows under one resolver.
+    def tally(rows, resolver)
+      t = {
+        count: rows.length, grand: 0.0,
+        paid: Hash.new(0.0), owed: Hash.new(0.0),
+        spent: Hash.new(0.0), individual: Hash.new(0.0),
+        shared: Hash.new(0.0), other: Hash.new(0.0)
+      }
+      rows.each do |r|
+        v = r[:value]
+        t[:grand] += v
+        split = owed_split(v, r[:responsible], resolver)
+        split.each { |person, amt| t[:owed][person] += amt }
+
+        pby = r[:paid]
+        next if pby.nil? || pby.empty?
+
+        t[:paid][pby] += v
+        t[:spent][pby] += v
+        if split.size > 1
+          t[:shared][pby] += v
+        elsif split.keys.first == pby
+          t[:individual][pby] += v
+        else
+          t[:other][pby] += v
+        end
+      end
+      t
+    end
+
+    # Sum several tallies into one (for --combined).
+    def merge(tallies)
+      out = {
+        count: 0, grand: 0.0,
+        paid: Hash.new(0.0), owed: Hash.new(0.0),
+        spent: Hash.new(0.0), individual: Hash.new(0.0),
+        shared: Hash.new(0.0), other: Hash.new(0.0)
+      }
+      tallies.each do |t|
+        out[:count] += t[:count]
+        out[:grand] += t[:grand]
+        %i[paid owed spent individual shared other].each do |k|
+          t[k].each { |person, amt| out[k][person] += amt }
+        end
+      end
+      out
+    end
+
+    # Net balances from one tally: { person => paid - owed }.
+    def net(tally)
+      (tally[:paid].keys | tally[:owed].keys).to_h { |p| [p, tally[:paid][p] - tally[:owed][p]] }
+    end
+
+    # Greedy settlement from net balances (paid - owed). -> [[debtor, creditor, amt]].
+    def settle(net)
+      debtors = net.select { |_, b| b < -EPS }.map { |p, b| [p, -b] }.sort_by { |x| x[1] }
+      creditors = net.select { |_, b| b > EPS }.map { |p, b| [p, b] }.sort_by { |x| -x[1] }
+      i = j = 0
+      transfers = []
+      while i < debtors.length && j < creditors.length
+        d = debtors[i]
+        c = creditors[j]
+        amt = [d[1], c[1]].min
+        transfers << [d[0], c[0], amt]
+        d[1] -= amt
+        c[1] -= amt
+        i += 1 if d[1] <= EPS
+        j += 1 if c[1] <= EPS
+      end
+      transfers
+    end
+
+    # Full report block for one tally.
+    def report(title, t, reference: false)
+      people = (t[:owed].keys | t[:paid].keys).sort
+      out = +"== #{title} ==\n"
+      if reference
+        out << "** REFERENCE/PROJECT LEDGER — duplicates entries from a primary " \
+                "ledger; do NOT combine with others. **\n"
+      end
+      out << "Rows: #{t[:count]}   Grand total: R$ #{fmt(t[:grand])}\n\n"
+      out << ("%-10s%14s%14s%14s\n" % ["Person", "Paid", "Owes", "Net"])
+      people.each do |p|
+        net = t[:paid][p] - t[:owed][p]
+        out << ("%-10s%14s%14s%14s\n" % [p, fmt(t[:paid][p]), fmt(t[:owed][p]), fmt_signed(net)])
+      end
+      out << "  (Net = Paid - Owes; positive means others owe this person)\n\n"
+
+      out << ("%-10s%14s%14s%14s%14s\n" % ["", "Total Spent", "Individual", "Shared", "For Other"])
+      people.each do |p|
+        out << ("%-10s%14s%14s%14s%14s\n" %
+                [p, fmt(t[:spent][p]), fmt(t[:individual][p]), fmt(t[:shared][p]), fmt(t[:other][p])])
+      end
+      out << "  (Total Spent = what each fronted; For Other = paid but the other " \
+             "person bears it)\n\n"
+
+      transfers = settle(net(t))
+      if transfers.empty?
+        out << "Settlement: already even.\n"
+      else
+        out << "Settlement:\n"
+        transfers.each { |d, c, amt| out << "  #{c} is owed — #{d} owes #{c}: R$ #{fmt(amt)}\n" }
+      end
+      out << "\n"
+      out
+    end
+
+    # "%,.2f": comma thousands separators, 2 decimals.
+    def fmt(number)
+      whole, frac = format("%.2f", number.abs).split(".")
+      whole = whole.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      "#{'-' if number.negative?}#{whole}.#{frac}"
+    end
+
+    # "%+,.2f": like fmt but always signed.
+    def fmt_signed(number)
+      "#{number.negative? ? '-' : '+'}#{fmt(number.abs)}"
+    end
+  end
+end

data/lib/spltty_cli/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  VERSION = "0.1.0"
+end

data/lib/spltty_cli.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+require_relative "spltty_cli/version"
+require_relative "spltty_cli/config"
+require_relative "spltty_cli/table"
+require_relative "spltty_cli/discovery"
+require_relative "spltty_cli/ledger"
+require_relative "spltty_cli/notes"
+require_relative "spltty_cli/notes_sync"
+require_relative "spltty_cli/groups"
+require_relative "spltty_cli/totals"
+require_relative "spltty_cli/prompt"
+require_relative "spltty_cli/commands/install"
+require_relative "spltty_cli/commands/add"
+require_relative "spltty_cli/commands/list"
+require_relative "spltty_cli/commands/sync"
+require_relative "spltty_cli/commands/totals"
+require_relative "spltty_cli/commands/settle"
+require_relative "spltty_cli/commands/groups"
+require_relative "spltty_cli/commands/groups_add"
+require_relative "spltty_cli/commands/groups_rm"
+require_relative "spltty_cli/commands/methods"
+require_relative "spltty_cli/commands/methods_add"
+require_relative "spltty_cli/commands/help"
+
+module SplttyCLI
+  # Files bundled with the gem: the workspace CLAUDE.md template, the per-ledger
+  # notes header, the source index, and the /ingest skill.
+  TEMPLATES_DIR = File.expand_path("../templates", __dir__)
+
+  # Entrypoint shared by exe/spltty (gem binary) and bin/spltty (mise launcher).
+  #
+  # `-pr` is normalized before dry-cli parses it: dry-cli would otherwise read
+  # `-pr X` as `-p r` (bundled short flags). Maps to the real
+  # --paid-responsible option, supporting both `-pr X` and `-pr=X`.
+  def self.run(argv = ARGV)
+    $PROGRAM_NAME = "spltty"
+    normalized = argv.map do |arg|
+      if arg == "-pr"
+        "--paid-responsible"
+      elsif arg.start_with?("-pr=")
+        "--paid-responsible=#{arg[4..]}"
+      else
+        arg
+      end
+    end
+    Dry::CLI.new(CLI).call(arguments: normalized)
+  end
+
+  # Load the config for the workspace this command is running against, honoring
+  # --accounts-dir / SPLTTY_ACCOUNTS_DIR. Resolution order for the config path:
+  #
+  #   1. --config / -C
+  #   2. SPLTTY_CONFIG
+  #   3. the nearest .spltty/config.json walking up from the cwd
+  #
+  # With none of those, there is no workspace here — every command except
+  # `install` errors out rather than silently inventing an empty config.
+  def self.load_config(opts)
+    path = opts[:config] || ENV["SPLTTY_CONFIG"]
+    path ||= Config.discover(Dir.pwd)
+    unless path
+      raise Config::Error,
+            "no spltty workspace found in #{Dir.pwd} or any parent directory — " \
+            "run `spltty install` to create one (or pass --config PATH)"
+    end
+
+    config = Config.load(path)
+    override = opts[:accounts_dir] || ENV["SPLTTY_ACCOUNTS_DIR"]
+    config.accounts_dir = File.expand_path(override) if override && !override.empty?
+    config
+  end
+
+  # Single source of truth for commands; used both to register with dry-cli and
+  # to render `spltty help`.
+  COMMAND_SPECS = [
+    { name: "install",     klass: Commands::Install },
+    { name: "add",         klass: Commands::Add },
+    { name: "list",        klass: Commands::List },
+    { name: "sync",        klass: Commands::Sync },
+    { name: "totals",      klass: Commands::Totals },
+    { name: "settle",      klass: Commands::Settle },
+    { name: "groups",      klass: Commands::Groups },
+    { name: "groups add",  klass: Commands::GroupsAdd },
+    { name: "groups rm",   klass: Commands::GroupsRm },
+    { name: "methods",     klass: Commands::Methods },
+    { name: "methods add", klass: Commands::MethodsAdd },
+    { name: "help",        klass: Commands::Help },
+  ].freeze
+
+  module CLI
+    extend Dry::CLI::Registry
+
+    COMMAND_SPECS.each { |spec| register spec[:name], spec[:klass] }
+  end
+end

data/templates/CLAUDE.md.erb

@@ -0,0 +1,229 @@
+# Shared Expense Tracker
+
+Expense tracking for <%= participants_sentence %>. Inputs arrive as text, audio transcripts, images
+or PDFs; outputs are markdown tables plus on-demand compilations. **Add entries and compute totals
+through the `spltty` CLI (see [Tooling](#tooling--the-spltty-cli)) — do not hand-edit the ledger
+tables to record spend, and do not tally by hand.**
+
+## Participants
+
+<%- participants.each do |p| -%>
+- **<%= p %>**
+<%- end -%>
+
+Spell these names exactly as written above — they are matched literally in the `Paid By` and
+`Responsible` columns.
+
+## Ledgers
+
+A **ledger** is one account being tracked. Two shapes exist:
+
+- **Monthly** — a folder under `accounts/` holding one file per month (`YYYY-MM.md`) plus a single
+  `notes.md`. Use for ongoing, open-ended spend.
+- **Single-file** — `accounts/<NAME>.ledger.md` plus `accounts/<NAME>.notes.md`. Use for a project
+  with a beginning and an end (a trip, a renovation, an event).
+
+This workspace has:
+
+| Ledger | Type | Default responsible | Entries | Notes |
+|--------|------|---------------------|---------|-------|
+<%- ledgers.each do |l| -%>
+| `<%= l[:name] %>` | <%= l[:type] == "monthly" ? "monthly" : "single file" %><%= l[:schema] == "montreal" ? " · multi-currency" : "" %> | <%= l[:default_responsible] %> | `<%= l[:entries] %>` | `<%= l[:notes] %>` |
+<%- end -%>
+
+The default ledger (used when `-l` is omitted) is **`<%= default_ledger %>`**.
+
+Each ledger's own rules and split groups live in its `*.notes.md` YAML header — that header is the
+source of truth, reconciled into `.spltty/config.json` by `spltty sync`. Add ledgers by creating the
+files (`spltty add -l NEWNAME` offers to scaffold them) — `spltty list` picks them up automatically.
+
+**Reference ledgers:** if a ledger intentionally *duplicates* rows that already exist in another one
+(e.g. a project tracker that mirrors shared spend so the project cost is visible in one place), its
+rows are copies, not new spend. Never sum it together with the primary ledgers — that double-counts.
+Mark it as such in its notes file and settle it on its own.
+
+## Currency
+
+- Values are stored as plain numbers with two decimals (e.g. `129.90`), no currency symbol inside
+  the cells. The value column is labelled `Value (R$)`.
+- A **multi-currency** ledger adds `Orig. Value` + `Cur.` columns before `Value (R$)` to carry the
+  original foreign amount alongside the converted one. Record the FX rate you used in
+  `sources/INDEX.md`, not in the table.
+
+## Directory layout
+
+```
+.
+├── CLAUDE.md              # this file
+├── .spltty/config.json    # CLI config: participants, groups, payment methods, ledger cache
+├── accounts/
+<%- ledgers.each_with_index do |l, i| -%>
+<%- branch = i == ledgers.length - 1 ? "└──" : "├──" -%>
+<%- if l[:type] == "monthly" -%>
+│   <%= branch %> <%= l[:name] %>/<%= " " * [1, 14 - l[:name].length].max %># monthly ledger — YYYY-MM.md files + notes.md
+<%- else -%>
+│   <%= branch %> <%= l[:name] %>.ledger.md   # single-file ledger (+ <%= l[:name] %>.notes.md)
+<%- end -%>
+<%- end -%>
+└── sources/
+    ├── INDEX.md           # tracker of which source files have been processed
+    └── <pdf|img|txt|audio>  # raw inputs dropped in
+```
+
+**Entries vs. notes.** An **entries** file holds *only* a title, a one-line pointer to its notes, and
+the table — nothing else; rows are added with `spltty add`, never by hand. A **notes** file holds
+*only forward-applicable rules* (split conventions, cross-posting rules, multi-currency handling).
+Per-batch history (methodology, FX rates, exclusions, dedup) lives in `sources/INDEX.md`. Never
+wedge prose between table rows.
+
+## Expense table format
+
+| Date       | Title | Value (R$) | Paid By | Payment Method | Responsible | Source |
+|------------|-------|-----------:|---------|----------------|-------------|--------|
+
+- **Date**: `YYYY-MM-DD`. **For credit-card statement imports, use the date the card bill is paid**
+  (the bill day from *Payment method defaults*), not the per-transaction date in the statement —
+  every row from one bill shares that single date; keep the transaction date in the title if it
+  matters. For everything else, use the day it happened; if unknown, ask.
+- **Title**: short description.
+- **Value**: number with two decimals, right-aligned.
+- **Paid By**: who actually fronted the money. This is *who paid*, independent of who bears the cost.
+- **Payment Method**: where the money came from — a configured card, or a one-off like `cash`/`Pix`.
+- **Responsible**: who bears the cost — either a **split-group name** or a **person's name**. At
+  totals time it resolves against split groups: the ledger's own header groups first, then the
+  global ones. A group divides the cost by its percentages; anything else falls 100% on that name.
+- **Source**: filename in `sources/` when it came from a file; otherwise `text` or `audio`. Rows
+  written by `spltty settle` use `settle`.
+
+### Split groups
+
+<%- if groups.empty? -%>
+No groups are defined yet. Create one with `spltty groups add NAME -s <%= example_split %> --global`
+(or `-l LEDGER` to scope it to one ledger).
+<%- else -%>
+| Group | Split |
+|-------|-------|
+<%- groups.each do |name, hash| -%>
+| `<%= name %>` | <%= hash.map { |p, pct| "#{p} #{pct}%" }.join(" / ") %> |
+<%- end -%>
+
+A ledger may define its own group with the same name in its notes header, which **shadows** the
+global one — that is how one ledger can split `<%= groups.keys.first %>` differently from the rest.
+<%- end -%>
+
+### Payment method defaults
+
+<%- if methods.empty? -%>
+None configured. Add one with:
+
+```sh
+spltty methods add "Visa 1234" -s visa-1234 -p <%= participants.first %> -r <%= default_responsible %> -b 21
+#   -s slug   -p default paid-by   -r default responsible   -b bill day (1-31 or "last")
+```
+<%- else -%>
+| Payment Method | Default Paid By | Default Responsible | Bill payment day |
+|----------------|-----------------|---------------------|------------------|
+<%- methods.each do |name, cfg| -%>
+| `<%= name %>` | <%= cfg["paid_by"] || "—" %> | <%= cfg["responsible"] || "—" %> | <%= cfg["bill_day"] == "last" ? "last day of the month" : (cfg["bill_day"] || "—") %> |
+<%- end -%>
+
+When one of these is named with `-m`, Paid By / Responsible / Date are pre-filled from this table.
+The defaults are a starting point — override any of them per expense.
+<%- end -%>
+
+## Tooling — the `spltty` CLI
+
+All entry input and all totals go through `spltty`. **Never hand-edit a ledger table to add spend,
+and never compute a settlement by hand.** Run `spltty help` for the full reference.
+
+**Add an expense** — title is positional, everything else is a flag. `-y` skips the confirm once you
+have every field:
+
+```sh
+spltty add "Groceries" -l <%= default_ledger %> -v 14.20 -p <%= participants.first %> -m cash -r <%= default_responsible %> -y
+spltty add "Coffee" -l <%= default_ledger %> -v 12.90 -m visa-1234 -y   # Paid By/Responsible/Date from the card
+```
+
+Flags: `-l` ledger · `-v` value · `-p` paid-by · `-m` payment method (name or slug) · `-r`
+responsible (a group name or a person) · `--pr` set both paid-by & responsible · `-d` date
+(defaults to today, or the card's bill day) · `-o`/`-c` original value/currency (multi-currency
+ledgers) · `-s` source.
+
+An unknown `-l` name is treated as a **typo, not a new account**: with `-y` the command fails and
+lists the known ledgers. Never work around that by inventing a ledger — re-read the list and use
+the right name, or confirm first and pass `--create-ledger` when a new one is genuinely wanted.
+
+**Compute totals** — per-person paid/owed/net + settlement:
+
+```sh
+spltty totals                 # one report per ledger
+spltty totals <%= default_ledger %>          # only this one
+spltty totals --combined      # merge all non-reference ledgers into ONE settlement
+```
+
+**Record a settlement** — writes settlement rows (Paid By = debtor, Responsible = creditor) so the
+payment offsets the debt in future `totals` runs:
+
+```sh
+spltty settle <%= default_ledger %>          # cash mode: settle this ledger in full (Pix row)
+spltty settle <%= default_ledger %> -v 500   # partial
+spltty settle                 # offset mode across all non-reference ledgers
+spltty settle -v 2000         # offsets + 2000 cash against the remainder
+```
+
+**Other commands:** `spltty list` (ledgers) · `spltty sync` (notes headers ↔ config) ·
+`spltty groups` / `groups add` / `groups rm` · `spltty methods` / `methods add`.
+
+## Workflow
+
+### Ingesting raw inputs
+
+When a **source file** (PDF, image/screenshot, txt, audio transcript) or **raw expense text** is sent
+straight to the prompt, take it as an instruction to ingest it — don't ask "what should I do with
+this?". Read / OCR / transcribe it, interpret it, and organize it into structured rows before doing
+anything else.
+
+**Checkpoint the inferred work.** As soon as you've interpreted the input, write the structured
+expenses to a temporary **`INGEST-WIP.md`** at the workspace root (one row per expense: extracted
+fields + resolved-or-open ledger / paid-by / responsible + any open questions). It survives
+interruptions and lets the rows be reviewed before they land. It's gitignored — delete it once every
+row has been added.
+
+Two rules govern how much to ask and how much to read:
+
+- **Ask only for what's missing and not inferable.** If the **ledger**, **responsible** or
+  **paid-by** wasn't given and can't be inferred from the payment method, ask — batching the
+  questions for all pending expenses into one confirm. Never guess these.
+- **Read frugally.** Reading a ledger for context (matching a prior categorization, dedup,
+  cross-posting) is fine when the task needs it. Don't read ledger files "just in case".
+
+### Steps
+
+1. **Receive** an expense (text, audio, image, PDF).
+2. **Parse** title + value (+ date). For files, save the raw input under `sources/` and add a row to
+   `sources/INDEX.md`.
+3. **Route** to a ledger — confirm which one when it isn't obvious. Default: `<%= default_ledger %>`.
+4. **Confirm** before writing: (a) who paid + payment method, (b) responsibility — a group name or a
+   person. A configured card pre-fills both.
+5. **Add** each confirmed expense with `spltty add … -y`. Do not hand-edit the table. Per-batch
+   methodology (FX, exclusions, dedup) goes in `sources/INDEX.md`.
+6. **Update** `sources/INDEX.md` to mark the source processed, listing the titles extracted and the
+   ledger they landed in.
+7. **Compile** on demand with `spltty totals` (`--combined` to merge ledgers).
+
+## Source tracker (`sources/INDEX.md`)
+
+Every file dropped into `sources/` must have a row with status `pending` or `processed`. When
+processed, list the expense titles extracted so the trail is reversible. Never delete entries — mark
+superseded files as `superseded` and link the replacement.
+
+## Things to never do
+
+- Never hand-edit a ledger table to record spend — add every expense with `spltty add`. Never
+  compute totals or a settlement by hand — use `spltty totals`. Never record a settlement payment
+  with `spltty add` or a hand edit — use `spltty settle`.
+- Never guess which ledger an expense belongs to — confirm when it isn't obvious.
+- Never guess who is responsible — always confirm.
+- Never conflate **Paid By** (who fronted the money) with **Responsible** (who bears the cost).
+- Never invent expense values from blurry or uncertain source content — ask for clarification.
+- Never misspell a participant's name — they are matched literally.

data/templates/gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+
+# Temporary work-in-progress checkpoint written during ingestion
+INGEST-WIP.md

data/templates/notes.md.erb

@@ -0,0 +1,39 @@
+
+# <%= name %> — notes
+
+> Rules and conventions for the `<%= name %>` ledger. Entries live in <%= entries %> — this file
+> holds **only forward-applicable rules**, never per-batch import history (that goes in
+> `sources/INDEX.md`), and never table rows.
+
+The YAML header above is read by the `spltty` CLI and is the **source of truth** for this ledger's
+configuration — its default responsible party and its split groups. Edit it here and run
+`spltty sync` (or any command that reads ledgers) to reconcile it into `.spltty/config.json`.
+
+## Split
+
+- Default responsible: **<%= default_responsible %>**<% if group_line %> — <%= group_line %><% end %>.
+- A group defined in the header above **shadows** the global group of the same name, so this ledger
+  can split differently from the rest of the workspace.
+- Override per row at entry time with `spltty add -r <group-or-person>`.
+<% if multi_currency -%>
+
+## Currency
+
+- Multi-currency ledger: rows carry `Orig. Value` + `Cur.` (default `<%= default_currency %>`)
+  alongside the converted `Value (R$)`.
+- Record the FX rate and how it was derived in `sources/INDEX.md` for each batch — not here.
+<% end -%>
+
+## Conventions
+
+<!-- Add rules that apply to every future entry in this ledger, e.g.:
+     - which merchants always route here
+     - recurring installments and how they are titled
+     - anything a future import must not get wrong
+-->
+
+<!-- Reference ledger? If this ledger intentionally duplicates rows that already exist in
+     another one (a project tracker mirroring shared spend, say), add `reference: true` to the
+     `spltty:` header above. Reference ledgers are flagged in `spltty totals`, excluded from
+     `--combined`, and never join a cross-ledger `spltty settle` — summing them with the
+     primary ledgers would double-count. -->

data/templates/skills/ingest/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ingest
+description: Ingest a raw source file (PDF, image/screenshot, txt, audio transcript) or pasted expense text into the ledger — read/OCR/interpret it, organize the expenses, and add them with the spltty CLI. Use whenever raw expense inputs are dropped into the prompt for this expense tracker.
+---
+
+# Ingest raw inputs into the ledger
+
+Turn a raw input — a source file (PDF, image/screenshot, `.txt`, audio transcript) or expense text
+pasted straight into the prompt — into ledger rows. This is the ingestion path of the workflow in
+`CLAUDE.md`; that file is the source of truth for the table schema, payment-method defaults, split
+groups and routing. Read it if you need those details.
+
+## When to use
+
+A source file or raw expense text was sent to the prompt. Treat its arrival as "ingest this" — do not
+ask what to do with it. If instead the ask was for totals or a settlement, that's `spltty totals` /
+`spltty settle`, not this skill.
+
+## Do
+
+1. **Read & interpret the input yourself.** OCR images/screenshots, read PDFs (some are
+   password-protected — the password is usually given), transcribe audio. Extract each expense:
+   title, value (two decimals), and date if present. Never invent a value from blurry or uncertain
+   content — ask about that line.
+2. **Checkpoint the inferred work.** As soon as you've interpreted the input, write the structured
+   expenses to **`INGEST-WIP.md`** at the workspace root — one row per expense with the extracted
+   fields plus the resolved (or still-open) ledger / paid-by / responsible and any open questions.
+   This preserves work across interruptions and allows review before it lands. It's gitignored.
+   Delete it once every row has been added with `spltty add`.
+3. **Save file inputs.** If the input is a file (not chat text), make sure it lives under `sources/`
+   and gets a `sources/INDEX.md` row (`pending` now, `processed` at the end).
+4. **Resolve the three routing fields** for each expense — **ledger**, **paid-by**, **responsible**:
+   - If the prompt states them, use them.
+   - Else if the **payment method** matches a configured card, pre-fill paid-by / responsible / date
+     from it (`spltty methods` lists them).
+   - Else **ask** — one batched confirm for all pending expenses. Never guess these three.
+5. **Read for context only when needed.** Reading a ledger's entries/notes is fine to match a prior
+   categorization, dedup against an existing bill, or copy a split convention — but only when the
+   task genuinely requires it. Don't read files speculatively.
+6. **Add each expense with `spltty add`** — never hand-edit a ledger table:
+
+   ```sh
+   spltty add "<title>" -l <LEDGER> -v <value> -p <paid-by> -m "<method>" -r <responsible> -y
+   ```
+
+   - Card entries can omit `-p`/`-r`/`-d` (defaulted from the card).
+   - Multi-currency ledgers take `-o <orig-value> -c <CUR>`.
+   - Set `-s <source-filename>` when the row came from a file in `sources/`.
+   - If it fails with *unknown ledger*, that is a typo guard, not a missing feature: use one of
+     the ledgers it lists. Only pass `--create-ledger` after confirming a new account is wanted.
+7. **Record per-batch methodology** (FX rates, exclusions, dedup, subtotals) in `sources/INDEX.md` —
+   not in the `*.notes.md` files, which hold only forward-applicable rules. Update the source's row
+   to `processed` with the extracted titles and the ledger(s) they landed in.
+
+## Prefer the CLI
+
+If the operation has a `spltty` command (`add`, `totals`, `settle`, `list`, `sync`, `groups`,
+`methods`), use it rather than doing the work by hand — unless explicitly told otherwise.
+
+## Never
+
+- Never guess ledger, paid-by, or responsible — confirm when not inferable.
+- Never conflate **Paid By** (who fronted the money) with **Responsible** (who bears the cost).
+- Never hand-edit a ledger table to record spend, or tally totals by hand.
+- Never invent values from uncertain source content.
+- Never misspell a participant's name — they are matched literally.