From 941ccb2cb34944e1321b3dc23731bfa93018d74f Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Wed, 1 Jul 2026 12:13:42 +0200
Subject: feat: tx list --flat, account create --if-not-exists, --since/--until
 doc (v0.3.6)

Three smaller ISSUES.md items, one PATCH (two optional flags + a doc fix; no
existing caller or JSON shape changes).

- tx list --flat: emit one top-level object per split (journal id repeated),
  dropping the transactions[] nesting so single-split journals script cleanly.
  JSON-only; --human already explodes splits into a table.
- account create --if-not-exists: resolve the name first; on a clash return the
  existing account with "existed": true (exit 0) instead of surfacing Firefly's
  422, so import scripts are idempotent. Detects via resolver, not by parsing
  the error string.
- SKILL.md documents that --since/--until filter on the transaction date (the
  value date); Firefly journals have a single date field, no separate book date
  (verified against firefly-iii TimeCollection setRange).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 SKILL.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'SKILL.md')

diff --git a/SKILL.md b/SKILL.md
index 4cf40bb..53ebd6f 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -105,7 +105,10 @@ firefly account create Rent --type expense
 ```
 Supports asset, expense, revenue. asset accounts get the default role
 automatically. Unlike categories/tags, accounts are NOT auto-created by
-`tx add`, create them explicitly here first.
+`tx add`, create them explicitly here first. For idempotent import scripts add
+`--if-not-exists`: if an account with that name already exists it returns that
+account's JSON with `"existed": true` (exit 0) instead of erroring on the name
+clash, so a re-run is safe.
 
 **Validate a batch before writing any of it:** when importing many rows in a
 loop, a mid-batch failure (a `--to` account that doesn't exist yet) leaves the
@@ -136,6 +139,19 @@ firefly account balance test01 --at 2026-05-31  # historical: balance as of that
 ```bash
 firefly tx list --account test01 --since 2026-06-01 --until 2026-06-30
 ```
+`--since`/`--until` filter on the transaction date (the date set on the tx),
+inclusive on both ends. Firefly journals have a single date field, so this is
+the value date used for reconciliation; there is no separate book/entry date.
+
+**Flatten output for scripting.** `tx list` nests each journal's splits under
+`transactions[]` even for the single-split common case. Add `--flat` to get one
+top-level object per split (the journal `id` repeated), with the split fields
+(`amount`, `source_name`, `destination_name`, `category_name`, ...) at the top
+level and no `transactions[]` key:
+```bash
+firefly tx list --account test01 --flat
+```
+`--flat` affects JSON only; `--human` already renders one row per split.
 
 **Look up a transaction by id** (ids come from `tx add`/`tx list` output):
 ```bash
-- 
cgit v1.2.3