# AGENTS.md

This file defines how AI coding agents should work in this repository.

## Core Principles

1. Correctness comes before speed.
2. Preserve the scanner-first product goal: reduce artifact decisions, guide hopping, and manual bookkeeping.
3. Prefer small, reviewable changes over broad rewrites.
4. Do not invent Genshin game data, API behavior, OCR confidence, or optimization rules without documenting the assumption.
5. Keep all game interaction read-only by default. Never add delete, feed, enhance, memory-read, hook, or game-modification behavior.
6. Keep user work and local app state intact.
7. Validate Electron main-process changes with a build and, when practical, a manual Smart Capture smoke test.

## Read Before Write

Before editing code, inspect the relevant source files and the project documents:

- `docs/PROJECT.md`
- `docs/ARCHITECTURE.md`
- `docs/CONVENTIONS.md`
- `docs/DECISIONS.md`
- `docs/CHECKLISTS.md`

Use `rg` or `rg --files` for search.

## Product Safety

The app may capture the Genshin window or screen and may later support optional input automation. Treat those areas as high risk.

- Capture must not require memory reads, hooks, injection, or game file modification.
- Input automation, if added, must be opt-in, reversible, whitelisted, and stoppable.
- The app must never delete, feed, enhance, or spend in-game resources.
- Uncertain OCR data must remain reviewable instead of being silently trusted.

## Implementation Expectations

- Keep Electron main-process code focused on OS integration, capture, and IPC.
- Keep React code focused on UI state and presentation.
- Keep parsing, scoring, and recommendation logic in `src/lib`.
- Keep domain types in `src/types`.
- Prefer deterministic parsers and data packages over hardcoded one-off exceptions.
- When OCR requires heuristics, record the limitation in docs or code comments.

## Validation

Run the strongest practical checks for the change:

- `npm run lint`
- `npm test`
- `npm run build`

For scanner changes, also manually verify Smart Capture against an open artifact detail view when possible.

## Definition Of Done

A task is done when:

- The requested behavior exists.
- The implementation follows the documented architecture and conventions.
- Relevant checks passed or skipped checks are explained.
- Scanner/OCR changes fail safely into review or uncertainty.
- The final summary names the changed areas and remaining risks.