feat: billable expenses, flexible invoice periods, and TUI log/render revamp

[0x054]

This branch grew well beyond its original "billable expenses" scope. It now bundles four related pieces of invoicing/expense work. Base is chore/ferro-0-12-migration (the feature depends on the ferro-orm 0.12 migration).

1. Billable expenses (client chargebacks)

Record purchased items against a project and bill them back as untaxed, pass-through line items on invoices, with optional receipts.

• New Expense / ExpenseReceipt / InvoiceExpenseLine models (plain-id FK convention; receipts stored base64 in a side table because raw bytes can't round-trip through the ORM — ferro-orm#160).
• ttd expense CLI: add / list / edit / rm + a receipt group; history-based recall.
• Invoicing lifecycle: expenses lock on invoice, release on void, and participate in refresh. Tax applies only to the time subtotal; total = subtotal + tax + expenses_subtotal. Invoices with no expenses render byte-identically to before.
• Rendering: PDF/markdown expense section; opt-in receipt pages merged into the PDF via pypdf; invoice format choice (default PDF) with markdown blocked when receipts are included.
• JSON backup (envelope v2) round-trips expenses + receipts (incl. non-UTF-8 binary); v1 backups still import.

2. TUI "log" page (re-scoped timesheet)

The underused timesheet screen became a month-scoped log page (nav 2) with stacked time and expense sections: [/] cycle months, tab switches section, e/x edit/delete the focused row, l adds (time or expense via a chooser). Expenses also show in the new-invoice draft preview.

3. Flexible invoice periods

Richer --period parsing (invoice CLI + TUI): this week/last week, rolling last N days/weeks/months, and month-name ranges (june 16 to june 30, jun, june, june 16 - 30) with a closest-year-never-future rule and cross-year wrap. Separately, an invoice's recorded period now derives from the billed items (min–max of line dates), not the requested window — so a mid-month re-invoice reads the true span. Refresh re-derives.

4. TUI invoice render format modal

e on the invoices screen now opens a render chooser (checkboxes: Include receipts / PDF / Markdown): receipts embed into the PDF, the receipts option is disabled unless the invoice has receipts, and enabling it locks out markdown. A shared load_invoice_receipts helper backs both the CLI and TUI.

Testing

Full suite green throughout: 397 passing, 84.59% coverage, ty + ruff clean. Built brainstorm → spec → plan → subagent implementation with per-task review and an opus whole-branch review per feature. Specs/plans under docs/superpowers/.

Known follow-ups (not in this PR)

• TUI: attach a receipt when adding an expense (drag-and-drop path into the form) — designed-but-deferred to a future session.
• invoice_has_receipts / some services use .all()+filter scans (codebase convention; tied to the relationship migration in Migrate models to Ferro relationships + cascade definitions (retire manual service-layer cascades) #13).
• Multi-currency expense-total footer on the log page (edge case).

Related issues

• ferro-orm#160 (raw bytes can't be saved via the ORM — drove the base64 receipt design).
• Migrate models to Ferro relationships + cascade definitions (retire manual service-layer cascades) #13 (migrate models to Ferro relationships + cascades).

🤖 Generated with Claude Code