AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Decision Wheel in the alexandrai-tools project.

Project overview

This guide covers src/tools/decision-wheel. pickWeighted returns an empty string for empty options, sums option weights, draws a browser crypto-random number over that total, walks accumulated weights, and returns the selected label. parseOptions trims newline-separated text, skips blanks, and assigns weight one to each parsed option.

Primary source files

• src/tools/decision-wheel/index.ts defines meta, PickOption, cryptoRandom, pickWeighted, and parseOptions.
• src/tools/decision-wheel/index.test.ts covers valid random results, empty options, single-option behavior, repeated pick invariants, newline parsing, and blank-line skipping.
• src/tools/decision-wheel/Body.astro owns option input, spin interaction, visual result, and reset behavior.
• src/tools/decision-wheel/i18n.ts owns localized labels.
• src/lib/tools.ts registers the tool metadata.

Setup commands

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

Change rules

• Return an empty string when options are empty.
• Use crypto.getRandomValues for random selection.
• Select proportionally to option weight values.
• Use the final option as a fallback if accumulation misses because of numeric edge cases.
• Parse newline input by trimming lines and skipping blanks.
• Assign parsed options a default weight of one.
• Add validation before accepting zero or negative weights in the UI.

Testing

Test empty options, single option, valid label invariants, weighted options, blank lines, whitespace trimming, zero and negative UI weights if added, and repeated spin behavior.

PR checklist

• npm test passes for decision-wheel.
• Randomness, math, lookup tables, or Unicode behavior is documented exactly.
• Browser-local behavior and copy/output paths remain private.
• Invalid inputs and edge cases are covered by tests.