AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Cooking Converter Agent Guide

Agent guide for cooking volume and weight conversion with incompatible category handling.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Cooking Converter in the alexandrai-tools project.

Project overview

This guide covers src/tools/cooking-converter/index.ts. The tool separates volume units from weight units, converts volume through milliliters, converts weight through grams, returns same-unit values unchanged, and returns NaN when a volume unit is converted to a weight unit or the reverse.

Primary source files

  • src/tools/cooking-converter/index.ts defines meta, CookingUnit, VOLUME_UNITS, WEIGHT_UNITS, TO_ML, TO_G, isVolume, and convert.
  • src/tools/cooking-converter/index.test.ts covers cup to ml, tbsp to tsp, ml to liter, fluid ounce to ml, ounce to gram, pound to ounce, identity conversion, and cross-category NaN.
  • src/tools/cooking-converter/Body.astro owns browser controls.
  • src/tools/cooking-converter/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

  • Use ml as the volume base unit.
  • Use grams as the weight base unit.
  • Keep cup as 236.588 ml.
  • Keep tbsp as 14.7868 ml and tsp as 4.92892 ml.
  • Keep fluid ounce as 29.5735 ml.
  • Return NaN for volume-to-weight and weight-to-volume conversions.
  • If ingredient density support is added, make it explicit and do not change the category guard silently.

Testing

Test volume conversions, weight conversions, same-unit identity, category mismatch NaN, all unit constants, fractional recipes, zero quantities, and future density-aware conversions if added.

PR checklist

  • npm test passes for cooking-converter.
  • Unit constants, lookup tables, and rounding rules are covered by tests.
  • Same-unit and invalid-input behavior remain documented.
  • UI labels, metadata, and pure conversion logic stay in sync.