# AGENTS.md

## Scope

- This repository is a Foundry VTT system for Unknown Armies 2nd Edition targeting Foundry 13.
- Keep changes small and consistent with the current ES module plus HandlebarsApplicationMixin structure. Do not introduce build tooling, transpilers, or framework layers unless explicitly requested.

## Architecture Map

- `unknown-armies-v2.mjs` is the init entrypoint. It registers document classes, data models, sheets, token bars, and Handlebars helpers.
- `module/data-models.mjs` owns Actor and Item schemas, migrations, and derived data such as `woundPoints.max` and `maxSkillRating`.
- `module/documents.mjs` owns gameplay behavior on documents: initiative, skill and stress rolls, damage, and stress notch updates.
- `module/rolls.mjs` owns percentile roll evaluation, roll dialogs, and chat-card rendering. Keep roll-rule changes here instead of duplicating logic in sheets.
- `module/sheets.mjs` owns sheet context preparation and UI action handlers. UI wiring belongs here; core mechanics should stay in documents or roll helpers.
- `templates/actor/`, `templates/item/`, and `templates/chat/` are tightly coupled to sheet context and localization keys.
- `styles/ua2e.css` is globally scoped through the `.ua2e` prefix; keep new selectors under that prefix to avoid Foundry or system collisions.

## Edit Rules

- Treat `character` as the only Actor type and `skill`, `gear`, `weapon`, `strangeness`, `stressAffliction`, `spell`, and `avatarChannel` as the supported Item types unless the task explicitly adds a new type.
- When changing schemas in `module/data-models.mjs`, check the corresponding sheet context in `module/sheets.mjs`, affected templates, and `system.json` html field declarations.
- Player-facing text should be localized. Add or update keys in `lang/en.json`, and keep `lang/fr.json` aligned when practical.
- Template form bindings should continue to use Foundry field paths such as `system.fieldName` so sheet auto-submit keeps working.
- The obsession and avatar path links are stored as item IDs (`system.obsessionSkillId`, `system.avatarPathSkillId`). Changes that rename, delete, or replace skills need to preserve or repair those links.
- Initiative is a derived sheet row based on `speed`; it is not a persistent skill item.
- Stress meters track `hardened` and `failed` notches separately. Preserve their distinct caps and update paths.
- Keep wound logic consistent with the derived `woundPoints.max` from Body.

## Validation

- There is no build, lint, or test suite in this repo.
- Validate changes by reloading the system in Foundry VTT 13 and exercising the affected flow: sheet render, form submit, roll dialog, chat card, or item interaction.
- For schema or localization edits, watch the browser console for init-time or render-time errors after reload.

## Reference Docs

- Link to game and system reference material instead of copying it into agent responses:
- `adept.md`
- `avatar.md`
- `ua2e_rules.md`
- `system_guide.md`