# Agent Instructions

## Mission

Build and maintain the Pokémon Inventory & Sales Reference Catalog according to the documentation in `docs/`.

The documentation is the source of truth. Do not invent requirements when an authoritative project rule exists.

## Before changing code

1. Read the relevant documentation.
2. Identify affected domain modules and tests.
3. Preserve the Product → Inventory Item → Listing → Sale separation.
4. Check public/private data boundaries.
5. Check accessibility requirements.
6. Add or update automated tests with the change.

## Architecture rules

- Use the modular-monolith architecture.
- Keep HTTP handling in routes.
- Keep application behavior in services.
- Keep business invariants in domain logic.
- Keep persistence in repositories.
- Keep external integrations behind provider/storage interfaces.
- Keep asynchronous work in the worker.
- Do not introduce microservices without an explicit architecture decision.
- Do not bypass the API from the browser.
- Do not put server-only business logic in shared browser packages.

## Security

- The frontend is never the security boundary.
- Enforce authorization server-side.
- Use secure HttpOnly SameSite sessions.
- Never store authentication tokens in localStorage.
- Never commit credentials or secrets.
- Treat uploads, user input, and provider data as untrusted.

## Domain rules

- Physical inventory copies are separate Inventory Item records.
- Provider mappings belong to Products, not physical copies.
- Sales are manual records; there is no checkout.
- Sold history is retained.
- Financial values use integer minor units.
- USD is the canonical stored/calculated currency.
- Public DTOs must never expose private financial, buyer, provider-debugging, or audit data.

## Change discipline

Prefer small, focused changes. Avoid unrelated refactoring.

When a decision changes the architecture or requirements, update the relevant documentation before or with the implementation.