AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools VAT Calculator Agent Guide

Agent guide for adding tax to net amounts and removing tax from gross amounts.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools VAT Calculator in the alexandrai-tools project.

Project overview

This guide covers src/tools/vat-calculator/index.ts. The tool adds VAT or sales tax to a net amount in add mode, extracts net and tax from a gross amount in remove mode, returns zeros for non-positive amounts or negative rates, and leaves rounding to the caller.

Primary source files

  • src/tools/vat-calculator/index.ts defines meta, VatResult, and calcVat.
  • src/tools/vat-calculator/index.test.ts covers add mode, remove mode, zero percent rate, add-remove inverse behavior, non-positive amounts, negative rates, and fractional rates.
  • src/tools/vat-calculator/Body.astro owns browser controls.
  • src/tools/vat-calculator/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Return zeros when amount is less than or equal to zero.
  • Return zeros when ratePct is negative.
  • In add mode, treat amount as net.
  • In remove mode, treat amount as gross.
  • Compute taxAmount as gross minus net in remove mode.
  • Support zero and fractional tax rates.
  • Do not embed jurisdiction-specific tax advice in pure logic.

Testing

Test add mode, remove mode, zero rate, fractional rate, add-remove inverse, non-positive amounts, negative rates, very large amounts, precision-sensitive decimal values, and UI rounding separately.

PR checklist

  • npm test passes for vat-calculator.
  • Formula, invalid-input policy, and rounding policy remain documented.
  • Pure helpers stay arithmetic-only and browser-local.
  • UI labels, metadata, and tests update together for behavior changes.