@kirjapro/mcp-server 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## [0.11.0] - Unreleased
+
+Requires the database migrations `20261002070106`–`20261002071619` (ALV report
+audit batch 2), in particular `book_purchase_with_vat`, and
+`20261002120000`–`20261002120001` (batch 3, the OmaVero field map); release it
+only after `db:deploy`. Version 0.10.0 keeps working against that database: its
+standard purchases book plain vouchers without a VAT fact (listed by the ALV
+reconciliation), the database applies the new sales-account rule, and its ALV
+summary passes the new `omavero` key through. Against a database without the
+batch 3 map, 0.11.0 derives the same fields from the older keys.
+
+- `kirjapro_book_purchase`: for a VAT-registered company a purchase with a rate
+  above 0 is booked with `book_purchase_with_vat`, which writes the voucher and
+  its VAT fact together, so the VAT reaches field 307. `reverseCharge` works
+  again with the new `reverseChargeCategory` (`eu_goods`, `eu_services`,
+  `non_eu_services`, `import`, `construction`, `scrap_metal`) and a Finnish
+  rate. A company that is not VAT-registered is refused a rate above 0 or a
+  reverse charge and books the purchase gross with `vatRate` `0`; the refusal
+  says that the VAT on a service from a foreign seller is still owed and goes
+  on a non-deductible Ostojen ALV row in the web app and on a voucher D expense
+  / K 4210 (Customs collects such a company's import VAT). New optional
+  `supplierName`; the result adds `vat_entry_ids`. The database refuses (P0001)
+  a deduction on law-based non-deductible accounts, a foreign rate and VAT rows
+  that do not match the 2320/4210 lines.
+- `kirjapro_create_from_template`: a purchase template that still debits 2320
+  books its domestic VAT fact through `book_purchase_with_vat`; for a company
+  that is not VAT-registered it is refused. `kirjapro_create_from_template_batch`
+  refuses purchase templates with VAT before any write (the atomic batch cannot
+  write VAT facts). `kirjapro_list_templates` hides `purchase_expense` and
+  `service_expense` from a company that is not VAT-registered.
+- `kirjapro_create_transaction(s_batch)` and the server instructions describe
+  the net sales-account rule (U-3): a net credit on 5000-5499, a sales line
+  with a 4210 or 2320 line and a net 4210 credit are refused; a transfer out of
+  a sales account without a VAT line, such as a fixed-asset disposal, is
+  allowed. They also say that a free 2320 line does not reach field 307.
+- `kirjapro_get_alv_summary` documents `output_vat_non_eu_services`, the VAT on
+  services bought from outside the EU that fields 301-303 now include.
+- `kirjapro_get_alv_summary` returns every official OmaVero field in
+  `omavero_fields` (VSRALVKV v1.10: 301-314 and 318-320) from the database's
+  `omavero` map: 307 is the total deductible VAT including reverse charge and
+  import VAT, 308 = 301+302+303+304+305+306+318 - 307, 309 excludes EU sales,
+  and 311 follows AVL 138 a §. The legacy keys `field_307`…`field_313` (and
+  their `_base` keys), `field_318`-`field_320`, `total_zero_rated` and
+  `reverse_charge_base` are no longer returned: `field_307` was only the
+  domestic deductible VAT and the others were purchase categories, not field
+  numbers. New `exempt_sales_base` (sales without a deduction right, in no
+  field); unclassified legacy reverse-charge invoice lines add a `warning`.
+- `kirjapro://compliance/*`: field 309 excludes EU sales (311, 312) and exempt
+  sales; cash-basis VAT needs no OmaVero opt-in and leaves EU and import items
+  on the accrual basis; a correction within 45 days carries no late-filing fee
+  regardless of the amount; the reverse-charge field list names 301-303 for
+  non-EU services, 304/310 for imports and the base fields.
+- Review the fingerprints of `kirjapro_book_purchase`,
+  `kirjapro_create_from_template(_batch)`, `kirjapro_list_templates`,
+  `kirjapro_create_transaction(s_batch)` and `kirjapro_get_alv_summary`.
+
+## [0.10.0] - 2026-10-02
+
+Requires the database migrations `20261001204555`–`20261001204559` (ALV report
+audit batch 1). Version 0.9.1 keeps working against that database: its sales
+and reverse-charge vouchers of a VAT-registered company are refused by the
+database with the same guidance, and its settlement default date stays the
+old one.
+
+- `kirjapro_book_sale`, the sale templates (`cash_sale_*`, `bank_sale_*`,
+  `invoice_sale_25`) of `kirjapro_create_from_template(_batch)` and
+  `kirjapro_book_purchase` with `reverseCharge` are refused for a
+  VAT-registered (ALV) company before any write: a journal voucher never
+  reaches the ALV report. Sales are created with `kirjapro_create_invoice` and
+  delivered with `kirjapro_send_invoice`; reverse-charge purchases are booked
+  as received invoices in the web app for now. `kirjapro_list_templates` no
+  longer lists the sale templates for such a company. Other companies are
+  unchanged.
+- `kirjapro_create_transaction(s_batch)`: the database refuses lines on sales
+  accounts 5000-5499 and a net 4210 credit for a VAT-registered company; the
+  descriptions say so.
+- `kirjapro_book_vat_settlement` settles the company's VAT period (month,
+  quarter or year from `companies.vat_period`) containing `month`. The default
+  date is the statutory due date (12th of the second month after the period;
+  annual period: end of February), and the fiscal year defaults to the open
+  year containing that date, so a December settlement is booked in the next
+  year. The database now excludes earlier settlements, closing entries and the
+  previous-year import, refuses a settled period, a period whose ledger does
+  not match the ALV report and negative balances, and books only non-zero
+  lines. The result and the dry run name the period. A company that is not
+  VAT-registered is refused.
+- `kirjapro_get_alv_summary` returns `reconciliation`: the 4210/2320 ledger
+  against the report (status `match`, `explained` or `mismatch`, the
+  differences and the explaining vouchers, invoices, fact mismatches and
+  manual rows), and sets `warning` on a mismatch.
+- The server instructions (core and full surface) say that a VAT-registered
+  company books sales as invoices, that `kirjapro_create_transaction` cannot
+  replace `kirjapro_book_sale` for it, and that its sale templates are hidden.
+- Review the fingerprints of `kirjapro_book_sale`, `kirjapro_book_purchase`,
+  `kirjapro_book_vat_settlement`, `kirjapro_create_from_template`,
+  `kirjapro_create_from_template_batch`, `kirjapro_list_templates`,
+  `kirjapro_create_transaction`, `kirjapro_create_transactions_batch` and
+  `kirjapro_get_alv_summary` for their changed descriptions and schemas.
+
 ## [0.9.1] - 2026-09-29
 
 Requires the database migration `20260929120200` (bank reconciliation

package/dist/index.js

@@ -4148,13 +4148,14 @@ var require_fast_uri = __commonJS({
         if (!malformedIPLiteral) {
           malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP);
         }
-        if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
-          if (uri.indexOf("%") !== -1) {
-            if (parsed.host !== void 0 && !malformedIPLiteral) {
-              const host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
-              parsed.host = reescapeHostDelimiters(host, isIP);
-            }
+        if (uri.indexOf("%") !== -1 && parsed.host !== void 0 && !malformedIPLiteral) {
+          let host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
+          if (!isIP) {
+            host = normalizePercentEncoding(host.toLowerCase());
           }
+          parsed.host = reescapeHostDelimiters(host, isIP);
+        }
+        if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
           if (parsed.path) {
             parsed.path = normalizePathEncoding(parsed.path);
           }
@@ -35678,7 +35679,7 @@ var StdioServerTransport = class {
 import { createClient } from "@supabase/supabase-js";
 
 // src/version.ts
-var VERSION = "0.9.1";
+var VERSION = "0.11.0";
 
 // src/auth.ts
 var SUPABASE_PROJECT_URL = "https://tifewzsimmyoiepblhld.supabase.co";
@@ -36881,7 +36882,7 @@ function registerTransactionTools(server2) {
   server2.registerTool(
     "kirjapro_create_transaction",
     {
-      description: "Create a transaction (tosite) with journal entries. Entries must balance (debits = credits). Accepts account numbers resolved to UUIDs server-side. Prefer kirjapro_create_from_template for standard patterns.",
+      description: "Create a transaction (tosite) with journal entries. Entries must balance (debits = credits). Accepts account numbers resolved to UUIDs server-side. Prefer kirjapro_create_from_template for standard patterns. For a VAT-registered (ALV) company the database refuses a net credit on sales accounts 5000-5499, a sales-account line together with a 4210 or 2320 line, and a net 4210 credit: sales are invoices. Moving an amount out of a sales account without a VAT line (e.g. a fixed-asset disposal D 5010 / K 1600) is allowed. A purchase with deductible VAT belongs in kirjapro_book_purchase so the VAT reaches field 307; a free 2320 line is listed by the ALV reconciliation.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         transactionDate: ISO_DATE_SCHEMA.describe("Transaction date (YYYY-MM-DD)"),
@@ -37020,7 +37021,7 @@ function registerTransactionTools(server2) {
   server2.registerTool(
     "kirjapro_create_transactions_batch",
     {
-      description: "Preview or atomically create multiple transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable.",
+      description: "Preview or atomically create multiple transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable. For a VAT-registered (ALV) company the database refuses a net credit on sales accounts 5000-5499, a sales-account line together with a 4210 or 2320 line, and a net 4210 credit: sales are invoices. Moving an amount out of a sales account without a VAT line (e.g. a fixed-asset disposal D 5010 / K 1600) is allowed. A purchase with deductible VAT belongs in kirjapro_book_purchase so the VAT reaches field 307; a free 2320 line is listed by the ALV reconciliation.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         dryRun: external_exports.boolean().default(true).describe(
@@ -38438,6 +38439,83 @@ function registerCustomerTools(server2) {
   );
 }
 
+// src/compliance/omavero-fields.ts
+var OMAVERO_FIELD_NUMBERS = [
+  "301",
+  "302",
+  "303",
+  "304",
+  "305",
+  "306",
+  "307",
+  "308",
+  "309",
+  "310",
+  "311",
+  "312",
+  "313",
+  "314",
+  "318",
+  "319",
+  "320"
+];
+var LEGACY_ALV_SUMMARY_KEYS = [
+  "field_307",
+  "field_307_base",
+  "field_308",
+  "field_308_base",
+  "field_309",
+  "field_309_base",
+  "field_310",
+  "field_310_base",
+  "field_312",
+  "field_312_base",
+  "field_313",
+  "field_313_base",
+  "field_318",
+  "field_319",
+  "field_320",
+  "total_zero_rated",
+  "reverse_charge_base",
+  "omavero"
+];
+function cents(value) {
+  return Math.round(value * 100) / 100;
+}
+function num(value) {
+  const n = typeof value === "number" ? value : Number(value ?? 0);
+  return Number.isFinite(n) ? n : 0;
+}
+function omaveroFieldsFromSummary(s) {
+  const fields = {
+    "301": num(s.field_301),
+    "302": num(s.field_302),
+    "303": num(s.field_303),
+    "304": num(s.output_vat_import),
+    "305": num(s.output_vat_eu_goods),
+    "306": num(s.output_vat_eu_services),
+    "307": num(s.total_input_vat),
+    "308": num(s.net_vat_payable),
+    "309": num(s.zero_vat_turnover),
+    "310": num(s.field_312_base),
+    "311": num(s.eu_goods_sales_base),
+    "312": num(s.eu_service_sales_base),
+    "313": num(s.field_308_base),
+    "314": num(s.field_309_base),
+    "318": num(s.output_vat_construction_scrap),
+    "319": num(s.reverse_charge_sales_base),
+    "320": cents(num(s.field_310_base) + num(s.field_313_base))
+  };
+  const map2 = s.omavero;
+  if (map2 && typeof map2 === "object") {
+    const values = map2;
+    for (const field of OMAVERO_FIELD_NUMBERS) {
+      if (values[field] !== void 0 && values[field] !== null) fields[field] = num(values[field]);
+    }
+  }
+  return fields;
+}
+
 // src/lib/incomeStatementSynthesis.ts
 function synthesizeIncomeStatementLines(lineTypes, currentByLine, previousByLine) {
   const lineAmounts = new Map(currentByLine);
@@ -38592,15 +38670,35 @@ var ALV_SUMMARY_OUTPUT_SHAPE = {
   input_vat: external_exports.unknown().optional(),
   net_vat_payable: external_exports.number().optional(),
   net_vat_payable_formatted: external_exports.string().optional(),
-  omavero_fields: external_exports.record(external_exports.string(), external_exports.number()).optional(),
+  // Every official OmaVero field (VSRALVKV v1.10: 301-314, 318-320), ALV
+  // report audit 2026-10-01, T2-11. The only field-numbered output.
+  omavero_fields: external_exports.record(external_exports.string(), external_exports.number()).describe(
+    "Official OmaVero VAT-return fields 301-314 and 318-320. 307 is all deductible VAT; 308 = 301+302+303+304+305+306+318 - 307."
+  ).optional(),
+  // Sales without a deduction right: in no OmaVero field (informational).
+  exempt_sales_base: external_exports.number().optional(),
   zero_vat_turnover: external_exports.number().optional(),
   eu_goods_sales_base: external_exports.number().optional(),
   reverse_charge_sales_base: external_exports.number().optional(),
   eu_service_sales_base: external_exports.number().optional(),
   unclassified_legacy_reverse_charge_base: external_exports.number().optional(),
+  // VAT on services bought from outside the EU, already inside field_301-303
+  // and total_output_vat (ALV report audit 2026-10-01, T2-13).
+  output_vat_non_eu_services: external_exports.number().optional(),
+  // get_alv_summary.reconciliation: the report against the 4210/2320 ledger
+  // (ALV report audit 2026-10-01, T2-1). Absent on an older database.
+  reconciliation: external_exports.object({ status: external_exports.enum(["match", "explained", "mismatch"]) }).passthrough().optional(),
   warning: external_exports.string().optional(),
   message: external_exports.string().optional()
 };
+var LEGACY_REVERSE_CHARGE_WARNING = "Legacy reverse-charge invoice lines must be reclassified before the fields are complete.";
+function alvReconciliationWarning(reconciliation) {
+  if (!reconciliation || typeof reconciliation !== "object") return void 0;
+  const r = reconciliation;
+  if (r.status !== "mismatch") return void 0;
+  const amount = (value) => (Number(value) || 0).toFixed(2);
+  return `Ledger accounts 4210/2320 differ from the ALV report (output VAT difference ${amount(r.output_difference)} \u20AC, input VAT difference ${amount(r.input_difference)} \u20AC). Review reconciliation before filing.`;
+}
 var BALANCE_SHEET_ROW_SHAPE = external_exports.object({
   account_number: external_exports.string(),
   name: external_exports.string(),
@@ -39076,7 +39174,7 @@ function registerReportTools(server2) {
   server2.registerTool(
     "kirjapro_get_alv_summary",
     {
-      description: "Get VAT (ALV) summary for a date range. Returns output/input VAT breakdown by rate and OmaVero field codes (301-320). For filing deadlines, read kirjapro://compliance/deadlines.",
+      description: "Get the VAT (ALV) summary for a date range. Returns `omavero_fields`, every official OmaVero VAT-return field (VSRALVKV v1.10: 301-314, 318-320). 307 is the total deductible VAT including reverse charge and import VAT; 308 = (301+302+303+304+305+306+318) - 307. 309 excludes 311/312 sales; exempt sales without a deduction right (`exempt_sales_base`) belong in no field. 311 follows AVL 138 a \xA7 (the delivery month when invoiced on or after the delivery in that month; otherwise, including an advance invoice, the next month). Fields 301-303 include the self-assessed VAT on services bought from outside the EU (output_vat_non_eu_services). Copy fields only from `omavero_fields`. Also returns a reconciliation object comparing the 4210/2320 ledger with the report (status match, explained or mismatch, with the differences and the vouchers, invoices, fact mismatches and manual rows that explain them); a mismatch or unclassified legacy reverse-charge lines set warning. For filing deadlines, read kirjapro://compliance/deadlines.",
       inputSchema: {
         dateFrom: ISO_DATE_SCHEMA.describe("Period start date (YYYY-MM-DD)"),
         dateTo: ISO_DATE_SCHEMA.describe("Period end date (YYYY-MM-DD)")
@@ -39116,24 +39214,21 @@ function registerReportTools(server2) {
         });
       }
       const raw = result;
-      const {
-        field_318: _legacyField318,
-        field_319: _legacyField319,
-        field_320: _legacyField320,
-        ...safeResult
-      } = raw;
+      const omaveroFields = omaveroFieldsFromSummary(raw);
+      const legacyKeys = new Set(LEGACY_ALV_SUMMARY_KEYS);
+      const safeResult = Object.fromEntries(
+        Object.entries(raw).filter(([key]) => !legacyKeys.has(key))
+      );
+      const warnings = [
+        alvReconciliationWarning(raw.reconciliation),
+        Number(raw.unclassified_legacy_reverse_charge_base) ? LEGACY_REVERSE_CHARGE_WARNING : void 0
+      ].filter((text) => Boolean(text));
       return toResult({
         ...safeResult,
+        ...warnings.length > 0 && { warning: warnings.join(" ") },
         period: { from: params.dateFrom, to: params.dateTo },
         net_vat_payable_formatted: formatCurrency(result.net_vat_payable || 0),
-        omavero_fields: {
-          "309": Number(raw.zero_vat_turnover) || 0,
-          "311": Number(raw.eu_goods_sales_base) || 0,
-          "312": Number(raw.eu_service_sales_base) || 0,
-          "318": Number(raw.output_vat_construction_scrap) || 0,
-          "319": Number(raw.reverse_charge_sales_base) || 0,
-          "320": (Number(raw.field_310_base) || 0) + (Number(raw.field_313_base) || 0)
-        }
+        omavero_fields: omaveroFields
       });
     }
   );
@@ -39745,6 +39840,35 @@ var ACCOUNTS = {
   VAKUUTUKSET: "7970"
 };
 
+// src/compliance/vat-guard.ts
+var ALV_REGISTERED_SALE_REFUSAL = "This company is VAT-registered (ALV). A sale booked as a journal voucher never reaches the ALV report (fields 301-303 and 309), so Kirjapro refuses it. Create the sale with kirjapro_create_invoice, deliver it with kirjapro_send_invoice and record the payment with kirjapro_record_payment or bank matching.";
+var NOT_VAT_REGISTERED_PURCHASE_REFUSAL = 'This company is not VAT-registered (ALV), so it deducts no VAT on purchases: book the purchase gross with vatRate "0". A service bought from a foreign seller (in another EU country or outside the EU) still makes the company liable for the self-assessed VAT: tell the user to add it as a non-deductible row on the Ostojen ALV page of the Kirjapro web app, to book the same VAT as a voucher debiting the expense account and crediting 4210 (ALV-velka), for example with kirjapro_create_transaction, and to check whether the company must register for VAT. Customs (Tulli) collects the import VAT of such a company. If the company is VAT-registered, update its settings in the Kirjapro web app first.';
+var REVERSE_CHARGE_CATEGORIES = [
+  "eu_goods",
+  "eu_services",
+  "non_eu_services",
+  "import",
+  "construction",
+  "scrap_metal"
+];
+var REVERSE_CHARGE_CATEGORY_REQUIRED = "reverseChargeCategory is required: eu_goods (fields 305/313), eu_services (306/314), non_eu_services (301-303), import (304/310), construction or scrap_metal (318/320).";
+var REVERSE_CHARGE_RATE_REQUIRED = "A reverse-charge purchase needs the Finnish rate the buyer self-assesses (25.5, 13.5 or 10).";
+var PURCHASE_TEMPLATE_NOT_VAT_REGISTERED_REFUSAL = 'This company is not VAT-registered (ALV), so a purchase template with VAT (2320) cannot be used. Book the purchase gross with kirjapro_book_purchase and vatRate "0".';
+function purchaseTemplateBatchRefusal(indexes) {
+  return `Purchase templates with VAT (index ${indexes.join(", ")}) are booked one at a time with kirjapro_create_from_template or kirjapro_book_purchase so the VAT reaches the ALV report; nothing was written.`;
+}
+var NOT_VAT_REGISTERED_SETTLEMENT_REFUSAL = "This company is not VAT-registered (ALV), so it has no VAT settlement to book.";
+async function readCompanyVat(supabase2, companyId2) {
+  const { data, error: error61 } = await supabase2.from("companies").select("alv_registered, vat_period").eq("id", companyId2).single();
+  if (error61 || !data) {
+    return toErrorContent(
+      error61 ? sanitizeDbError("Failed to verify the company VAT registration", error61) : "Failed to verify the company VAT registration."
+    );
+  }
+  const row = data;
+  return { alvRegistered: row.alv_registered === true, vatPeriod: row.vat_period ?? "monthly" };
+}
+
 // src/tools/templates.ts
 function splitVat(gross, vatRate) {
   if (vatRate === 0) return { net: roundCents(gross), vat: 0 };
@@ -39844,24 +39968,28 @@ var TEMPLATES = [
   // Cash sales
   {
     id: "cash_sale_25",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 25,5%",
     vatRate: 25.5,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_25_5, 25.5)
   },
   {
     id: "cash_sale_13_5",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 13,5%",
     vatRate: 13.5,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_13_5, 13.5)
   },
   {
     id: "cash_sale_10",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 10%",
     vatRate: 10,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_10, 10)
   },
   {
     id: "cash_sale_0",
+    kind: "sale",
     description: "K\xE4teismyynti ALV 0%",
     vatRate: 0,
     expand: saleCashTemplate(ACCOUNTS.MYYNTI_0, 0)
@@ -39869,18 +39997,21 @@ var TEMPLATES = [
   // Bank sales
   {
     id: "bank_sale_25",
+    kind: "sale",
     description: "Pankkimyynti ALV 25,5%",
     vatRate: 25.5,
     expand: saleBankTemplate(ACCOUNTS.MYYNTI_25_5, 25.5)
   },
   {
     id: "bank_sale_13_5",
+    kind: "sale",
     description: "Pankkimyynti ALV 13,5%",
     vatRate: 13.5,
     expand: saleBankTemplate(ACCOUNTS.MYYNTI_13_5, 13.5)
   },
   {
     id: "bank_sale_10",
+    kind: "sale",
     description: "Pankkimyynti ALV 10%",
     vatRate: 10,
     expand: saleBankTemplate(ACCOUNTS.MYYNTI_10, 10)
@@ -39888,6 +40019,7 @@ var TEMPLATES = [
   // Invoice sale
   {
     id: "invoice_sale_25",
+    kind: "sale",
     description: "Laskumyynti ALV 25,5% (myyntisaamiset)",
     vatRate: 25.5,
     expand: (amount, opts) => {
@@ -39909,6 +40041,7 @@ var TEMPLATES = [
   // Purchase expenses
   {
     id: "purchase_expense",
+    kind: "purchase",
     description: "Osto ALV 25,5% (pankkitililt\xE4)",
     vatRate: 25.5,
     expand: (amount, opts) => {
@@ -39929,6 +40062,7 @@ var TEMPLATES = [
   },
   {
     id: "service_expense",
+    kind: "purchase",
     description: "Ulkopuolinen palvelu ALV 25,5%",
     vatRate: 25.5,
     expand: (amount, opts) => {
@@ -39950,6 +40084,7 @@ var TEMPLATES = [
   // Rent (no VAT)
   {
     id: "rent_payment",
+    kind: "other",
     description: "Vuokranmaksu (pankkitililt\xE4)",
     vatRate: null,
     expand: (amount, opts) => applyOverrides(
@@ -39971,6 +40106,7 @@ var TEMPLATES = [
   // Bank transfer
   {
     id: "bank_transfer",
+    kind: "other",
     description: "Tilisiirto kassasta pankkitilille",
     vatRate: null,
     expand: (amount, opts) => applyOverrides(
@@ -39991,6 +40127,21 @@ var TEMPLATES = [
   }
 ];
 var TEMPLATE_MAP = new Map(TEMPLATES.map((t) => [t.id, t]));
+function isSaleTemplate(templateId) {
+  return TEMPLATE_MAP.get(templateId)?.kind === "sale";
+}
+function inputVatOf(entries) {
+  return roundCents(
+    entries.filter((e) => e.accountNumber === ACCOUNTS.ALV_SAAMISET).reduce((sum, e) => sum + e.debitAmount - e.creditAmount, 0)
+  );
+}
+function isVatPurchaseTemplate(templateId) {
+  const template = TEMPLATE_MAP.get(templateId);
+  return template?.kind === "purchase" && inputVatOf(template.expand(100)) !== 0;
+}
+function availableTemplates(alvRegistered) {
+  return alvRegistered ? TEMPLATES.filter((t) => t.kind !== "sale") : TEMPLATES.filter((t) => !isVatPurchaseTemplate(t.id));
+}
 function expandTemplate(templateId, amount, opts) {
   const template = TEMPLATE_MAP.get(templateId);
   if (!template) {
@@ -40053,7 +40204,7 @@ function toJournalEntries(entries, accountMap) {
     credit_amount: e.creditAmount
   }));
 }
-async function resolveAndCreate(params) {
+async function preparePosting(params) {
   const supabase2 = getSupabase();
   const companyId2 = getCompanyId();
   let fiscalYearId = params.fiscalYearId;
@@ -40082,16 +40233,41 @@ async function resolveAndCreate(params) {
       `Template produced unbalanced entries: debits ${totalDebit.toFixed(2)} != credits ${totalCredit.toFixed(2)}.`
     );
   }
-  const journalEntries = toJournalEntries(params.entries, accountResult);
-  const { data: transactionId, error: txError } = await supabase2.rpc(
+  return { fiscalYearId, journalEntries: toJournalEntries(params.entries, accountResult) };
+}
+async function resolveAndCreatePurchase(params) {
+  const prepared = await preparePosting(params);
+  if ("isError" in prepared) return prepared;
+  const { data, error: error61 } = await getSupabase().rpc("book_purchase_with_vat", {
+    p_company_id: getCompanyId(),
+    p_fiscal_year_id: prepared.fiscalYearId,
+    p_transaction_date: params.transactionDate,
+    p_description: params.description,
+    p_document_number: params.documentNumber || "",
+    p_entries: prepared.journalEntries,
+    p_vat_rows: params.vatRows,
+    ...params.supplierName ? { p_supplier_name: params.supplierName } : {}
+  });
+  const result = data;
+  if (error61 || !result?.transaction_id) {
+    return toErrorContent(
+      error61 ? sanitizeDbError("Failed to book the purchase", error61) : "Failed to book the purchase: no ID returned."
+    );
+  }
+  return { id: result.transaction_id, vatEntryIds: result.vat_entry_ids ?? [] };
+}
+async function resolveAndCreate(params) {
+  const prepared = await preparePosting(params);
+  if ("isError" in prepared) return prepared;
+  const { data: transactionId, error: txError } = await getSupabase().rpc(
     "create_transaction_with_entries",
     {
-      p_company_id: companyId2,
-      p_fiscal_year_id: fiscalYearId,
+      p_company_id: getCompanyId(),
+      p_fiscal_year_id: prepared.fiscalYearId,
       p_transaction_date: params.transactionDate,
       p_description: params.description,
       p_document_number: params.documentNumber || "",
-      p_entries: journalEntries
+      p_entries: prepared.journalEntries
     }
   );
   if (txError || !transactionId) {
@@ -40105,7 +40281,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_list_templates",
     {
-      description: "List available transaction templates. Templates handle double-entry balancing and VAT splitting automatically.",
+      description: "List available transaction templates. Templates handle double-entry balancing and VAT splitting automatically. Sale templates are not listed for a VAT-registered (ALV) company: its sales are invoices. Purchase templates with VAT are not listed for a company that is not VAT-registered.",
       inputSchema: {},
       outputSchema: {
         templates: external_exports.array(external_exports.object({
@@ -40117,7 +40293,9 @@ function registerTemplateTools(server2) {
       annotations: READ_ONLY_ANNOTATIONS
     },
     async () => {
-      const list = TEMPLATES.map((t) => ({
+      const companyVat = await readCompanyVat(getSupabase(), getCompanyId());
+      if ("isError" in companyVat) return companyVat;
+      const list = availableTemplates(companyVat.alvRegistered).map((t) => ({
         id: t.id,
         description: t.description,
         vatRate: t.vatRate
@@ -40128,7 +40306,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_create_from_template",
     {
-      description: 'Create a transaction from a template. Use kirjapro_list_templates for available templates. accountOverrides swaps default accounts (e.g. {"2320": "2330"}).',
+      description: 'Create a transaction from a template. Use kirjapro_list_templates for available templates. accountOverrides swaps default accounts (e.g. {"2320": "2330"}). Sale templates are refused for a VAT-registered (ALV) company: create an invoice instead. A purchase template with VAT (2320) books its VAT fact so the VAT reaches field 307; for a company that is not VAT-registered it is refused (book the purchase gross).',
       inputSchema: {
         template: external_exports.string().describe('Template ID (e.g. "cash_sale_25", "purchase_expense")'),
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
@@ -40144,6 +40322,16 @@ function registerTemplateTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      const template = TEMPLATE_MAP.get(params.template);
+      let alvRegistered = null;
+      if (template && (template.kind === "sale" || template.kind === "purchase")) {
+        const companyVat = await readCompanyVat(supabase2, companyId2);
+        if ("isError" in companyVat) return companyVat;
+        alvRegistered = companyVat.alvRegistered;
+        if (template.kind === "sale" && alvRegistered) {
+          return toErrorContent(ALV_REGISTERED_SALE_REFUSAL);
+        }
+      }
       return withIdempotency(
         supabase2,
         companyId2,
@@ -40161,7 +40349,27 @@ function registerTemplateTools(server2) {
           if ("error" in result) {
             return toErrorContent(result.error);
           }
-          const createResult = await resolveAndCreate({
+          const inputVat = template?.kind === "purchase" ? inputVatOf(result.entries) : 0;
+          if (inputVat !== 0 && alvRegistered === false) {
+            return toErrorContent(PURCHASE_TEMPLATE_NOT_VAT_REGISTERED_REFUSAL);
+          }
+          const createResult = inputVat !== 0 ? await resolveAndCreatePurchase({
+            fiscalYearId: params.fiscalYearId,
+            transactionDate: params.transactionDate,
+            description: params.description,
+            documentNumber: params.documentNumber,
+            entries: result.entries,
+            vatRows: [
+              {
+                category: "domestic",
+                vat_rate: template?.vatRate ?? 0,
+                tax_base: roundCents(
+                  result.entries.filter((e) => e.accountNumber !== ACCOUNTS.ALV_SAAMISET).reduce((sum, e) => sum + e.debitAmount, 0)
+                ),
+                vat_amount: inputVat
+              }
+            ]
+          }) : await resolveAndCreate({
             fiscalYearId: params.fiscalYearId,
             transactionDate: params.transactionDate,
             description: params.description,
@@ -40175,7 +40383,8 @@ function registerTemplateTools(server2) {
             message: "Transaction created from template",
             template: params.template,
             transaction_id: createResult.id,
-            entries: result.entries
+            entries: result.entries,
+            ..."vatEntryIds" in createResult && { vat_entry_ids: createResult.vatEntryIds }
           });
         }
       );
@@ -40184,7 +40393,7 @@ function registerTemplateTools(server2) {
   server2.registerTool(
     "kirjapro_create_from_template_batch",
     {
-      description: "Preview or atomically create multiple template transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable.",
+      description: "Preview or atomically create multiple template transactions in one call (up to 50). dryRun defaults to true. Commit is always all-or-nothing; partial/best-effort writes are intentionally unavailable. A batch with a sale template is refused for a VAT-registered (ALV) company before any write. Purchase templates with VAT (2320) are refused in a batch: book them one at a time with kirjapro_create_from_template so the VAT reaches the ALV report.",
       inputSchema: {
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
         dryRun: external_exports.boolean().default(true).describe(
@@ -40207,6 +40416,27 @@ function registerTemplateTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      const vatPurchaseIndexes = params.transactions.map((tx, index) => {
+        const template = TEMPLATE_MAP.get(tx.template);
+        if (template?.kind !== "purchase") return -1;
+        const expanded = expandTemplate(tx.template, tx.amount, {
+          accountOverrides: tx.accountOverrides
+        });
+        return "entries" in expanded && inputVatOf(expanded.entries) !== 0 ? index : -1;
+      }).filter((index) => index >= 0);
+      if (vatPurchaseIndexes.length > 0) {
+        return toErrorContent(purchaseTemplateBatchRefusal(vatPurchaseIndexes));
+      }
+      const saleIndexes = params.transactions.map((tx, index) => isSaleTemplate(tx.template) ? index : -1).filter((index) => index >= 0);
+      if (saleIndexes.length > 0) {
+        const companyVat = await readCompanyVat(supabase2, companyId2);
+        if ("isError" in companyVat) return companyVat;
+        if (companyVat.alvRegistered) {
+          return toErrorContent(
+            `${ALV_REGISTERED_SALE_REFUSAL} Sale templates at index ${saleIndexes.join(", ")}; nothing was written.`
+          );
+        }
+      }
       return withIdempotency(
         supabase2,
         companyId2,
@@ -40430,6 +40660,35 @@ function freshnessMeta(rates = FINNISH_RATES_2026, today = /* @__PURE__ */ new D
   };
 }
 
+// src/compliance/vat-settlement-date.ts
+var pad = (value) => String(value).padStart(2, "0");
+function vatPeriodRange(month, vatPeriod) {
+  const [yearText, monthText] = month.split("-");
+  const year = Number(yearText);
+  const monthNumber = Number(monthText);
+  const period = vatPeriod ?? "monthly";
+  const startMonth = period === "yearly" ? 1 : period === "quarterly" ? Math.floor((monthNumber - 1) / 3) * 3 + 1 : monthNumber;
+  const endMonth = period === "yearly" ? 12 : period === "quarterly" ? startMonth + 2 : monthNumber;
+  const lastDay = new Date(Date.UTC(year, endMonth, 0)).getUTCDate();
+  const label = period === "yearly" ? String(year) : period === "quarterly" ? `${year}-Q${(startMonth + 2) / 3}` : month;
+  return {
+    start: `${year}-${pad(startMonth)}-01`,
+    end: `${year}-${pad(endMonth)}-${pad(lastDay)}`,
+    label
+  };
+}
+function defaultSettlementDate(month, vatPeriod) {
+  const { end } = vatPeriodRange(month, vatPeriod);
+  const [endYear, endMonth] = end.split("-").map(Number);
+  if ((vatPeriod ?? "monthly") === "yearly") {
+    const februaryDays = new Date(Date.UTC(endYear + 1, 2, 0)).getUTCDate();
+    return `${endYear + 1}-02-${pad(februaryDays)}`;
+  }
+  const dueMonthIndex = endMonth - 1 + 2;
+  const dueYear = endYear + Math.floor(dueMonthIndex / 12);
+  return `${dueYear}-${pad(dueMonthIndex % 12 + 1)}-12`;
+}
+
 // src/tools/bookings.ts
 function expenseAccountWarning(account) {
   const first = account.trim().charAt(0);
@@ -40456,7 +40715,7 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_purchase",
     {
-      description: "Book a purchase (osto) with automatic VAT splitting. Supports reverse charge (AVL 9\xA7) and entertainment (edustus, AVL 114\xA7). Rate rules: food/restaurants 13.5%, insurance 0% (exempt), alcohol 25.5%.",
+      description: "Book a purchase (osto) with automatic VAT splitting. For a VAT-registered (ALV) company the VAT is recorded as a VAT fact, so it reaches field 307 (and the reverse-charge fields). Reverse charge (reverseCharge=true, with reverseChargeCategory) self-assesses the VAT for EU goods and services, services from outside the EU, import, construction and scrap metal. Entertainment (edustus, AVL 114\xA7) is booked gross. Statutorily non-deductible accounts (wages, insurance, interest, depreciation, taxes, representation) are refused with VAT: book them with vatRate 0. A company that is not VAT-registered books purchases gross with vatRate 0. Rate rules: food/restaurants 13.5%, insurance 0% (exempt), alcohol 25.5%.",
       inputSchema: {
         amount: external_exports.number().finite().positive().max(1e9).describe(
           "EUR amount. Standard purchase: GROSS (VAT-inclusive) \u2014 VAT is split out of this. Reverse charge (reverseCharge=true): NET foreign-invoice amount \u2014 the foreign supplier does not charge Finnish VAT, so the parameter must be net. VAT is self-assessed on top per AVL 9\xA7 producing equal debit to ALV-saamiset and credit to ALV-velka. Entertainment (edustus=true): GROSS (full amount to expense, no VAT deduction per AVL 114\xA7)."
@@ -40465,7 +40724,11 @@ function registerBookingTools(server2) {
         date: ISO_DATE_SCHEMA.describe("Transaction date (YYYY-MM-DD)"),
         vatRate: external_exports.enum(["25.5", "13.5", "10", "0"]).describe("Finnish VAT rate"),
         expenseAccount: external_exports.string().describe('Expense account number (e.g. "8080")'),
-        reverseCharge: external_exports.boolean().default(false).describe(`EU reverse charge: D expense + D ${ACCOUNTS.ALV_SAAMISET} ALV-saamiset + C ${ACCOUNTS.ALV_VELKA} ALV-velka + C bank`),
+        reverseCharge: external_exports.boolean().default(false).describe(`Reverse charge (k\xE4\xE4nnetty verovelvollisuus): D expense + D ${ACCOUNTS.ALV_SAAMISET} ALV-saamiset + C ${ACCOUNTS.ALV_VELKA} ALV-velka + C bank, with a VAT fact of reverseChargeCategory`),
+        reverseChargeCategory: external_exports.enum(REVERSE_CHARGE_CATEGORIES).optional().describe(
+          "Required with reverseCharge: eu_goods (fields 305/313), eu_services (306/314), non_eu_services (services from outside the EU, 301-303), import (304/310), construction or scrap_metal (318/320)"
+        ),
+        supplierName: external_exports.string().max(200).optional().describe("Supplier name, stored on the VAT fact"),
         edustus: external_exports.boolean().default(false).describe("Entertainment expense (AVL 114\xA7): 0% VAT deduction, full gross to expense"),
         paymentAccount: external_exports.string().default(ACCOUNTS.PANKKITILI).describe(`Payment account (default "${ACCOUNTS.PANKKITILI}" Pankkitili)`),
         fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
@@ -40479,6 +40742,16 @@ function registerBookingTools(server2) {
       const rate = Number.parseFloat(params.vatRate);
       const gross = roundCents(params.amount);
       let entries;
+      let vatRows = [];
+      const companyVat = await readCompanyVat(getSupabase(), getCompanyId());
+      if ("isError" in companyVat) return companyVat;
+      if (!params.edustus && !companyVat.alvRegistered && (rate !== 0 || params.reverseCharge)) {
+        return toErrorContent(NOT_VAT_REGISTERED_PURCHASE_REFUSAL);
+      }
+      if (params.reverseCharge && !params.edustus) {
+        if (!params.reverseChargeCategory) return toErrorContent(REVERSE_CHARGE_CATEGORY_REQUIRED);
+        if (rate === 0) return toErrorContent(REVERSE_CHARGE_RATE_REQUIRED);
+      }
       if (params.edustus) {
         entries = [
           { accountNumber: params.expenseAccount, debitAmount: gross, creditAmount: 0 },
@@ -40494,6 +40767,14 @@ function registerBookingTools(server2) {
           // ALV-velka (output)
           { accountNumber: params.paymentAccount, debitAmount: 0, creditAmount: gross }
         ];
+        vatRows = [
+          {
+            category: params.reverseChargeCategory ?? "eu_services",
+            vat_rate: rate,
+            tax_base: gross,
+            vat_amount: vat
+          }
+        ];
       } else if (rate === 0) {
         entries = [
           { accountNumber: params.expenseAccount, debitAmount: gross, creditAmount: 0 },
@@ -40506,6 +40787,7 @@ function registerBookingTools(server2) {
           { accountNumber: ACCOUNTS.ALV_SAAMISET, debitAmount: vat, creditAmount: 0 },
           { accountNumber: params.paymentAccount, debitAmount: 0, creditAmount: gross }
         ];
+        vatRows = [{ category: "domestic", vat_rate: rate, tax_base: net, vat_amount: vat }];
       }
       const purchaseAccountWarning = expenseAccountWarning(params.expenseAccount);
       if (params.dryRun) {
@@ -40516,6 +40798,7 @@ function registerBookingTools(server2) {
           description: params.description,
           date: params.date,
           entries,
+          ...vatRows.length > 0 && { vat_rows: vatRows },
           ...purchaseAccountWarning && { account_warning: purchaseAccountWarning }
         });
       }
@@ -40526,18 +40809,24 @@ function registerBookingTools(server2) {
         params.idempotencyKey,
         params,
         async () => {
-          const result = await resolveAndCreate({
+          const posting = {
             fiscalYearId: params.fiscalYearId,
             transactionDate: params.date,
             description: params.description,
             documentNumber: params.documentNumber,
             entries
-          });
+          };
+          const result = vatRows.length > 0 ? await resolveAndCreatePurchase({
+            ...posting,
+            vatRows,
+            supplierName: params.supplierName
+          }) : await resolveAndCreate(posting);
           if ("isError" in result) return result;
           return toResult({
             message: "Purchase booked",
             transaction_id: result.id,
             entries,
+            ..."vatEntryIds" in result && { vat_entry_ids: result.vatEntryIds },
             ...purchaseAccountWarning && { warning: purchaseAccountWarning }
           });
         }
@@ -40547,11 +40836,11 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_vat_settlement",
     {
-      description: `Book ALV-tilitys (VAT settlement) for a month. Calculates net from ALV accounts (${ACCOUNTS.ALV_SAAMISET}/${ACCOUNTS.ALV_VELKA}) and creates settlement. Default date: 12th of month+1.`,
+      description: `Book ALV-tilitys (VAT settlement) for the company's VAT period that contains the given month. Settles the period's net from ALV accounts (${ACCOUNTS.ALV_SAAMISET}/${ACCOUNTS.ALV_VELKA}) by voucher date, excluding earlier settlements, closing entries and the previous-year import. Default date: the statutory due date (12th of the second month after the period; annual period: end of February), not moved to a business day. The period follows the company's VAT period. Refuses a period already settled, a period whose ledger does not match the ALV report, and negative balances.`,
       inputSchema: {
-        month: external_exports.string().regex(/^\d{4}-\d{2}$/).describe("Settlement month (YYYY-MM)"),
-        fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID (auto-resolved if omitted)"),
-        settlementDate: ISO_DATE_SCHEMA.optional().describe("Settlement date (default: 12th of month+1)"),
+        month: external_exports.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/).describe("A month of the VAT period to settle (YYYY-MM); a quarterly or annual company settles the whole period containing it"),
+        fiscalYearId: external_exports.string().uuid().optional().describe("Fiscal year UUID of the settlement date (default: the open fiscal year containing the settlement date)"),
+        settlementDate: ISO_DATE_SCHEMA.optional().describe("Settlement date (default: the statutory due date, 12th of the second month after the period; annual period: end of February)"),
         paymentAccount: external_exports.string().default(ACCOUNTS.PANKKITILI).describe(`Bank account (default "${ACCOUNTS.PANKKITILI}" Pankkitili)`),
         idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
         dryRun: DRY_RUN_SCHEMA
@@ -40561,16 +40850,25 @@ function registerBookingTools(server2) {
     async (params) => {
       const supabase2 = getSupabase();
       const companyId2 = getCompanyId();
+      const companyVat = await readCompanyVat(supabase2, companyId2);
+      if ("isError" in companyVat) return companyVat;
+      if (!companyVat.alvRegistered) return toErrorContent(NOT_VAT_REGISTERED_SETTLEMENT_REFUSAL);
+      const period = vatPeriodRange(params.month, companyVat.vatPeriod);
+      const dueDate = defaultSettlementDate(params.month, companyVat.vatPeriod);
+      const settlementDate = params.settlementDate ?? dueDate;
       let fiscalYearId = params.fiscalYearId;
       if (!fiscalYearId) {
-        const resolved = await resolveOpenFiscalYear(supabase2, companyId2);
-        if ("isError" in resolved) return resolved;
-        fiscalYearId = resolved.id;
+        const { data: years, error: yearsError } = await supabase2.from("fiscal_years").select("id").eq("company_id", companyId2).eq("is_closed", false).lte("start_date", settlementDate).gte("end_date", settlementDate).order("start_date", { ascending: false }).limit(1);
+        if (yearsError) {
+          return toErrorContent(sanitizeDbError("Failed to query fiscal years", yearsError));
+        }
+        if (!years || years.length === 0) {
+          return toErrorContent(
+            `No open fiscal year contains the settlement date ${settlementDate} (statutory due date for ${period.label}: ${dueDate}). Create that fiscal year or pass settlementDate inside an open fiscal year.`
+          );
+        }
+        fiscalYearId = years[0].id;
       }
-      const [year, monthStr] = params.month.split("-");
-      const monthNum = Number.parseInt(monthStr, 10);
-      const nextMonth = monthNum === 12 ? `${Number.parseInt(year, 10) + 1}-01` : `${year}-${String(monthNum + 1).padStart(2, "0")}`;
-      const settlementDate = params.settlementDate ?? `${nextMonth}-12`;
       const { data: fy } = await supabase2.from("fiscal_years").select("start_date, end_date, is_closed").eq("id", fiscalYearId).eq("company_id", companyId2).single();
       if (!fy) {
         return toErrorContent(
@@ -40584,7 +40882,7 @@ function registerBookingTools(server2) {
       }
       if (settlementDate > fy.end_date) {
         return toErrorContent(
-          `Settlement date ${settlementDate} is after fiscal year end ${fy.end_date}. Pass an explicit settlementDate within ${fy.start_date}..${fy.end_date} (typical: ${fy.end_date}) \u2014 silent clamping would shift the ALV-kausi.`
+          `Settlement date ${settlementDate} is after fiscal year end ${fy.end_date}. Pass an explicit settlementDate within ${fy.start_date}..${fy.end_date} or the fiscal year that contains ${settlementDate} \u2014 silent clamping would shift the ALV-kausi.`
         );
       }
       if (settlementDate < fy.start_date) {
@@ -40596,9 +40894,14 @@ function registerBookingTools(server2) {
         return toDryRunResponse("kirjapro_book_vat_settlement", {
           action: "book_vat_settlement",
           month: params.month,
+          vat_period: companyVat.vatPeriod,
+          period_start: period.start,
+          period_end: period.end,
           settlement_date: settlementDate,
+          statutory_due_date: dueDate,
+          fiscal_year_id: fiscalYearId,
           payment_account: params.paymentAccount,
-          hint: "Call kirjapro_get_alv_summary with the same month to preview the concrete net VAT before committing."
+          hint: `Call kirjapro_get_alv_summary for ${period.start}..${period.end} to preview the net VAT and its reconciliation before committing.`
         });
       }
       return withIdempotency(
@@ -40621,20 +40924,27 @@ function registerBookingTools(server2) {
             );
           }
           const result = data;
+          const periodStart = result.period_start ?? period.start;
+          const periodEnd = result.period_end ?? period.end;
           if (result.direction === "none") {
             return toResult({
-              message: result.message ?? `No VAT entries found for ${params.month}. Nothing to settle.`,
+              message: result.message ?? `No VAT entries found for ${period.label}. Nothing to settle.`,
               alv_saamiset: 0,
-              alv_velka: 0
+              alv_velka: 0,
+              period_start: periodStart,
+              period_end: periodEnd
             });
           }
           return toResult({
-            message: `VAT settlement booked for ${params.month}`,
+            message: `VAT settlement booked for ${period.label}`,
             transaction_id: result.transaction_id,
             alv_saamiset: result.alv_saamiset,
             alv_velka: result.alv_velka,
             net_vat: result.net_vat,
-            direction: result.direction
+            direction: result.direction,
+            period_start: periodStart,
+            period_end: periodEnd,
+            settlement_date: settlementDate
           });
         }
       );
@@ -40643,7 +40953,7 @@ function registerBookingTools(server2) {
   server2.registerTool(
     "kirjapro_book_sale",
     {
-      description: "Book a sale (myynti) with automatic VAT splitting. Payment types: invoice (default, D Myyntisaamiset), cash (D bank), prepaid.",
+      description: "Book a sale (myynti) with automatic VAT splitting for a company that is not VAT-registered. Payment types: invoice (default, D Myyntisaamiset), cash (D bank), prepaid. A VAT-registered (ALV) company is refused: its sales reach the ALV report only as invoices (kirjapro_create_invoice + kirjapro_send_invoice).",
       inputSchema: {
         amount: external_exports.number().finite().positive().max(1e9).describe("Gross EUR amount (VAT-inclusive)"),
         description: external_exports.string().min(1).max(500).describe('Transaction description (e.g. "Konsultointi Acme Oy, 40h \xD7 95 \u20AC")'),
@@ -40660,6 +40970,9 @@ function registerBookingTools(server2) {
       annotations: WRITE_ANNOTATIONS
     },
     async (params) => {
+      const companyVat = await readCompanyVat(getSupabase(), getCompanyId());
+      if ("isError" in companyVat) return companyVat;
+      if (companyVat.alvRegistered) return toErrorContent(ALV_REGISTERED_SALE_REFUSAL);
       const rate = Number.parseFloat(params.vatRate);
       const gross = roundCents(params.amount);
       let entries;
@@ -42187,7 +42500,7 @@ var VAT_COMPLIANCE = {
     ],
     booking: "4 entries: D expense + D ALV-saamiset + C bank + C ALV-velka (k\xE4\xE4nnetty)",
     note: "Net VAT effect is zero but BOTH must be reported on ALV-ilmoitus. Invoice must NOT show VAT rate or VAT amount",
-    omavero_fields: "Foreign: 305 (EU goods), 306 (EU services). Domestic construction/scrap: 318 (VAT amount), 319/320 (tax bases)"
+    omavero_fields: "EU goods: 305 (VAT) / 313 (base); EU services: 306 / 314; services from outside the EU: VAT in 301-303 by rate (no base field); imports: 304 / 310; domestic construction/scrap purchases: 318 / 320, sales 319. The deductible part of each is in 307."
   },
   common_mistakes: [
     "Food/coffee at 25.5% \u2014 should be 13.5% (AVL 85\xA7)",
@@ -42266,14 +42579,18 @@ var FILING_DEADLINES = {
   },
   maksuperusteinen_alv: {
     threshold: 5e5,
-    note: "Revenue under 500,000 \u20AC: may opt for cash-basis VAT (report when payment received/made, not when invoiced)",
-    application: "Opt-in via OmaVero"
+    note: "Turnover up to 500,000 \u20AC per calendar year: domestic sales VAT may be reported when payment is received and purchase VAT deducted when paid (cash basis), consistently for all domestic sales and purchases; imports, exports, intra-EU sales and acquisitions and cross-border reverse-charge services stay on the accrual basis. Kirjapro reports on the accrual basis only.",
+    application: "No application: the business applies the cash basis in its bookkeeping. Since 2025 the VAT return has no cash-basis field.",
+    source: "https://www.vero.fi/yritykset-ja-yhteisot/verot-ja-maksut/arvonlisaverotus/pienyrityksen-maksuperusteinen-alv/",
+    sources_verified_at: "2026-10-02"
   },
   late_penalties: {
-    myohastymismaksu: "3 \u20AC/day for days 1-45 (max 135 \u20AC), then +2% of tax amount (max 15,000 \u20AC per tax type)",
+    myohastymismaksu: "3 \u20AC/day for at most 45 days (135 \u20AC); more than 45 days late: 135 \u20AC + 2 % of the declared payable tax (max 15,000 \u20AC per tax type and period); also for returns with no tax payable",
     viivastyskorko_2026: "9.5% for most taxes, 4.5% for inheritance tax",
-    correction_grace: "Corrections within 45 days of original deadline: no penalty if change \u2264 500 \u20AC",
-    nil_return: "Even when no VAT activity occurred, a nil return must be filed for each verokausi"
+    correction_grace: "A correction return filed within 45 days of the original due date carries no late-filing fee (no amount condition). Later corrections: 2 % of the additional payable tax.",
+    nil_return: "Even when no VAT activity occurred, a nil return must be filed for each verokausi",
+    source: "https://www.vero.fi/syventavat-vero-ohjeet/ohje-hakusivu/48377/seuraamusmaksut-oma-aloitteisessa-verotuksessa5/",
+    sources_verified_at: "2026-10-02"
   },
   payment_deadline: "Same as filing deadline (12th of M+2 for monthly/quarterly, last day of Feb for annual)",
   omavero_field_codes: {
@@ -42291,16 +42608,17 @@ var FILING_DEADLINES = {
       318: "Vero rakentamispalvelun ja metalliromun ostoista (construction/scrap reverse charge VAT)"
     },
     tax_bases: {
-      309: "0-verokannan alainen liikevaihto (zero-rate turnover: exports, EU sales with deduction right)",
+      309: "0-verokannan alainen liikevaihto (zero-rate turnover, e.g. exports of goods outside the EU, AVL 55-72 h \xA7). Does NOT include EU goods sales (311) or EU service sales (312). Exempt sales without a deduction right (healthcare, education, finance, insurance) are reported in no field.",
       310: "Tavaroiden maahantuonnit EU:n ulkopuolelta (goods imports from outside EU)",
-      311: "Tavaroiden myynnit muihin EU-maihin (goods sales to EU)",
+      311: "Tavaroiden myynnit muihin EU-maihin (goods sales to EU; reported for the delivery month when invoiced on or after the delivery in that month, otherwise, including an advance invoice, the next month, AVL 138 a \xA7)",
       312: "Palveluiden myynnit muihin EU-maihin (service sales to EU)",
       313: "Tavaraostot muista EU-maista (goods purchases from EU)",
       314: "Palveluostot muista EU-maista (service purchases from EU)",
       319: "Rakentamispalvelun ja metalliromun myynnit (construction/scrap sales)",
       320: "Rakentamispalvelun ja metalliromun ostot (construction/scrap purchases)"
     },
-    removed_2025: "315, 316, 317 (alarajahuojennus fields) removed from 1.1.2025"
+    removed_2025: "315, 316, 317 (alarajahuojennus fields) removed from 1.1.2025",
+    sources_verified_at: "2026-10-02"
   }
 };
 var SOCIAL_INSURANCE_2026 = {
@@ -42581,7 +42899,7 @@ Do not invent a "closest match" tool for these tasks. A confidently wrong action
 A bank transaction that is already booked (a receipt or purchase booked as paid from the bank account, a manual invoice payment, a paid purchase invoice, a Kirjapro payment batch) is linked, never posted again: \`kirjapro_list_bank_link_candidates\` \u2192 \`kirjapro_link_bank_transaction\`. Never post a manual voucher for an already-booked or skipped bank transaction; a wrong reconciliation is undone in the Kirjapro app (Pankki \u2192 T\xE4sm\xE4ytys \u2192 T\xE4sm\xE4ytetyt \u2192 Pura t\xE4sm\xE4ytys) or, on the full surface, with \`kirjapro_unreconcile_bank_transaction\`, and then matched again.
 
 ### Reports
-\`kirjapro_get_dashboard\` (overview) | \`kirjapro_get_income_statement\` (tuloslaskelma) | \`kirjapro_get_balance_sheet\` (tase \u2014 \`equity.synthetic_tilikauden_tulos\` is the unclosed P/L residual already included in equity; never add it again. The cumulative report groups current earnings under 3600 and retained earnings under 3500. Report rows can differ from raw ledger account balances. Do not present book equity as an approved distribution limit) | \`kirjapro_get_ar_aging\` (bounded myyntisaamisten aggregate; weighted age is not revenue-based DSO) | \`kirjapro_get_alv_summary\` (ALV-yhteenveto with OmaVero field codes 301-320).
+\`kirjapro_get_dashboard\` (overview) | \`kirjapro_get_income_statement\` (tuloslaskelma) | \`kirjapro_get_balance_sheet\` (tase \u2014 \`equity.synthetic_tilikauden_tulos\` is the unclosed P/L residual already included in equity; never add it again. The cumulative report groups current earnings under 3600 and retained earnings under 3500. Report rows can differ from raw ledger account balances. Do not present book equity as an approved distribution limit) | \`kirjapro_get_ar_aging\` (bounded myyntisaamisten aggregate; weighted age is not revenue-based DSO) | \`kirjapro_get_alv_summary\` (ALV-yhteenveto; the official OmaVero fields are in \`omavero_fields\`).
 
 ## Safety Rules
 
@@ -42647,7 +42965,7 @@ var INSTRUCTIONS_CORE_ADDENDUM = `
 The following workflows are NOT exposed in the current (core) surface. When a user asks for them, redirect to the web UI rather than reaching for the closest available tool:
 
 - **Recurring invoice templates** \u2014 created and managed in the web app; cron generates the issued invoices
-- **Booking shortcuts** (book_purchase / book_sale / book_vat_settlement) \u2014 for these, you CAN compose the journal entries manually via \`kirjapro_create_transaction\` with explicit debit/credit lines if the user prefers; otherwise redirect
+- **Booking shortcuts** (book_purchase / book_sale / book_vat_settlement) \u2014 for these, you CAN compose the journal entries manually via \`kirjapro_create_transaction\` with explicit debit/credit lines if the user prefers; otherwise redirect. Exception: a VAT-registered (ALV) company books sales only as invoices (\`kirjapro_create_invoice\` + \`kirjapro_send_invoice\`) and reverse-charge purchases and purchases with deductible VAT in the web app (a free 2320 line on a voucher has no VAT fact and does not reach field 307); the database refuses its vouchers with a net credit on sales accounts 5000-5499, a sales-account line together with a 4210 or 2320 line, or a net 4210 credit; moving an amount out of a sales account without a VAT line (e.g. a fixed-asset disposal D 5010 / K 1600) is allowed
 - **Payroll (palkanlaskenta)** \u2014 Kirjapro does NOT calculate or book payroll. Direct the user to Palkkaus.fi or Palkka.fi for the calculation, then bring the resulting payslip back and book it via \`kirjapro_create_transaction\` with explicit debit/credit lines
 - **Transaction templates** \u2014 manual journal entries via \`kirjapro_create_transaction\`
 - **Manual offer status changes** \u2014 the customer's email-link click sets status server-side; just wait for the user to confirm acceptance
@@ -42666,10 +42984,10 @@ var INSTRUCTIONS_FULL_ADDENDUM = `
 
 ### Booking Shortcuts
 Faster than composing journal entries via \`kirjapro_create_transaction\`:
-- \`kirjapro_book_sale\` / \`kirjapro_book_purchase\` \u2014 one-liner with auto VAT splitting
-- \`kirjapro_book_vat_settlement\` \u2014 reads ALV-saamiset/ALV-velka, creates settlement entry. Call \`kirjapro_get_alv_summary\` first to preview.
+- \`kirjapro_book_sale\` / \`kirjapro_book_purchase\` \u2014 one-liner with auto VAT splitting. A VAT-registered (ALV) company books sales as invoices (\`kirjapro_create_invoice\` + \`kirjapro_send_invoice\`): \`kirjapro_book_sale\` and \`kirjapro_book_purchase\` with \`reverseCharge\` are refused for it
+- \`kirjapro_book_vat_settlement\` \u2014 settles the company's VAT period from ALV-saamiset/ALV-velka. Call \`kirjapro_get_alv_summary\` for the period first to preview the net and its reconciliation.
 - **Payroll is intentionally NOT exposed.** Direct users to Palkkaus.fi / Palkka.fi for salary calculation; the payslip can then be booked manually via \`kirjapro_create_transaction\`.
-- \`kirjapro_list_templates\` \u2192 \`kirjapro_create_from_template\` for common patterns (13 built-in templates)
+- \`kirjapro_list_templates\` \u2192 \`kirjapro_create_from_template\` for common patterns (built-in templates; the sale templates are hidden and refused for a VAT-registered company)
 
 ### Manual Offer Status
 - \`kirjapro_update_offer_status\` \u2014 manual override; usually the customer's email-link click handles accept/reject server-side

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirjapro/mcp-server",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "MCP server for Finnish accounting — exposes Kirjapro bookkeeping, invoicing, and reporting tools to Claude, ChatGPT, Mistral, and other MCP clients.",
   "type": "module",
   "bin": {

package/server.json

@@ -2,7 +2,7 @@
   "name": "@kirjapro/mcp-server",
   "displayName": "Kirjapro - Finnish Accounting",
   "description": "Finnish double-entry bookkeeping, invoicing, and financial reporting for growing businesses. Create transactions, generate invoices with VAT calculation, produce income statements and balance sheets, and validate Finnish business identifiers.",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "homepage": "https://kirjapro.fi",
   "repository": "https://github.com/Jaollo/kirja-pro",
   "license": "MIT",

package/tool-fingerprints.json

@@ -2,15 +2,15 @@
   "fingerprints": [
     {
       "name": "kirjapro_book_purchase",
-      "hash": "21897b2fd6bd8809"
+      "hash": "e6c7bfe42eedc619"
     },
     {
       "name": "kirjapro_book_sale",
-      "hash": "a7ad4daef0e9947b"
+      "hash": "6868bdf46073f442"
     },
     {
       "name": "kirjapro_book_vat_settlement",
-      "hash": "48ab541acbce9e66"
+      "hash": "39f807857fb81e5d"
     },
     {
       "name": "kirjapro_convert_offer_to_invoice",
@@ -22,11 +22,11 @@
     },
     {
       "name": "kirjapro_create_from_template",
-      "hash": "62d7241dbdba511c"
+      "hash": "d410e01e95e20227"
     },
     {
       "name": "kirjapro_create_from_template_batch",
-      "hash": "f10cad13dc519c7c"
+      "hash": "ff8fa037077fac9a"
     },
     {
       "name": "kirjapro_create_invoice",
@@ -42,11 +42,11 @@
     },
     {
       "name": "kirjapro_create_transaction",
-      "hash": "88b052da9babfc50"
+      "hash": "8b6a32983de69413"
     },
     {
       "name": "kirjapro_create_transactions_batch",
-      "hash": "da853c41adf6e4dd"
+      "hash": "a3e71d41bbf437e4"
     },
     {
       "name": "kirjapro_delete_invoice",
@@ -66,7 +66,7 @@
     },
     {
       "name": "kirjapro_get_alv_summary",
-      "hash": "139628cea5a3df31"
+      "hash": "a149fdcb6307923a"
     },
     {
       "name": "kirjapro_get_ar_aging",
@@ -162,7 +162,7 @@
     },
     {
       "name": "kirjapro_list_templates",
-      "hash": "e07b6d21afbccce9"
+      "hash": "91c70a7143aa96ac"
     },
     {
       "name": "kirjapro_list_transactions",