# 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.

## Vertical slice completion

Each vertical slice must be complete before it is committed and pushed:

- A new or changed Vue visual component must have a colocated Storybook story or an updated existing story covering its meaningful states.
- Stories must use representative fixture data and must not introduce production domain behavior solely for visual coverage.
- Visual slices must pass the web tests, production build, Storybook build, and Storybook interaction/accessibility runner before commit:

	```sh
	npm run test --workspace=@pokemon-inventory/web
	npm run build --workspace=@pokemon-inventory/web
	npm run build-storybook --workspace=@pokemon-inventory/web
	npm run test-storybook
	```

- Storybook stories must cover relevant loading, empty, error, selected, disabled, responsive, light/dark theme, and keyboard states when those states exist in the component.
- Backend-only slices do not require Storybook changes unless they alter a user-facing visual contract.
- The final commit gate includes the appropriate API/domain/integration tests plus all applicable web and Storybook checks.