vat-summary

name	vat-summary
description	Produce a VAT / sales-tax summary for a period from a Well workspace's posted ledger. Use when the user asks for a VAT return, VAT summary, sales tax owed, output vs input VAT, or tax declaration figures for a period.

VAT summary from Well

A VAT return is a byproduct of closed books, not a separate project. If the ledger is posted and correct, the figures already exist — the work is presentation. Work backward from the filing deadline and forward from the posted ledger, and surface uncertainty rather than reporting a number you're not sure of.

Build it from the posted ledger + tax rates

1. Discover the schema first (see well:querying-well-data).
2. Output VAT (collected on sales) — from issued invoices / invoice_items and their tax_rates, or the corresponding VAT ledger_accounts / journal_entries for the period. Group by rate (standard / reduced / zero / exempt).
3. Input VAT (paid on purchases) — from received invoices / invoice_items + tax_rates, or the input-VAT ledger accounts.
4. Net VAT due = output VAT − recoverable input VAT, per the period's date filter.
5. By rate and jurisdiction — break the totals down by VAT rate and, for multi-jurisdiction workspaces, by jurisdiction. Read the rate from the data (tax_rates), don't assume it.

Rules — conservative by design

• "The books are not closed yet." If the period's journal_entries are still DRAFT / unposted, say so before producing a final figure — declarations fall out of closed books. Offer a provisional figure clearly labelled as such.
• Surface uncertainty, don't file it. Where a rate, exemption, or jurisdiction treatment is ambiguous, flag it for human review rather than guessing.
• Read rates and jurisdictions from tax_rates / the data; never hardcode a percentage.
• Don't sum across currencies without converting (exchange_rates).

Present it

Output VAT (by rate) → total; Input VAT (by rate) → total; Net VAT due; the period and jurisdiction; a books-closed/draft status line; and any flagged uncertainties for review.