AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Dice Roller Agent Guide

Agent guide for dice count and sides clamping, Web Crypto rolls, and sum calculation.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Dice Roller in the alexandrai-tools project.

Project overview

This guide covers src/tools/dice-roller/index.ts. The tool clamps dice count to one through one hundred, clamps sides to two through one thousand, fills a Uint32Array with Web Crypto values, maps each value into one through sides, and provides a sum helper.

Primary source files

  • src/tools/dice-roller/index.ts defines meta, rollDice, and sum.
  • src/tools/dice-roller/index.test.ts covers output length, value ranges for common dice, minimum count clamp, and sum behavior.
  • src/tools/dice-roller/Body.astro owns browser controls.
  • src/tools/dice-roller/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

  • Clamp count to one through one hundred.
  • Clamp sides to two through one thousand.
  • Keep roll values one-indexed, not zero-indexed.
  • Use Web Crypto as the random source.
  • Keep sum as a simple reducer over roll results.
  • If exact unbiased dice rolls are required, replace modulo mapping with rejection sampling.
  • Do not store roll history unless a deliberate feature adds it.

Testing

Test output length, count clamps, side clamps, common dice ranges, sum of empty and non-empty arrays, many-run range invariants, and rejection-sampling behavior if added.

PR checklist

  • npm test passes for dice-roller.
  • Web Crypto remains the random source.
  • Input lists or generated values stay browser-local.
  • Current clamping and empty-input semantics remain documented.