# Repository Guidelines

## Project Structure & Module Organization
- `pricewatch/app/` contains the core Python package. Key areas: `core/` (Pydantic schema, registry, IO, logging), `scraping/` (HTTP and Playwright fetchers), `stores/` (site-specific parsers), and `cli/` (Typer entrypoint).
- Store assets live under `pricewatch/app/stores/<store>/selectors.yml` and `pricewatch/app/stores/<store>/fixtures/`.
- Tests are in `tests/` with store-specific tests under `tests/stores/`.
- Runtime/debug artifacts (HTML/screenshots) go in `scraped/`. Input/output examples: `scrap_url.yaml`, `scraped_store.json`.

## Build, Test, and Development Commands
- `pip install -e .` installs the package in editable mode.
- `playwright install chromium` installs the browser used for anti-bot fallback.
- `pricewatch doctor` validates the local setup.
- `pricewatch run --yaml scrap_url.yaml --out scraped_store.json` runs the full pipeline.
- `pytest` runs the full test suite; `pytest --cov=pricewatch` adds coverage.

## Coding Style & Naming Conventions
- Python 3.12, 4-space indentation, and a 100-character line length (Black/Ruff settings).
- Use `ruff check .`, `black .`, and `mypy pricewatch` before submitting changes.
- Prefer `snake_case` for modules/functions, `PascalCase` for classes, and `test_*.py` for test files.
- Project language is French for code comments and discussion notes.

## Testing Guidelines
- Test framework: `pytest` with coverage configured in `pyproject.toml`.
- Keep store parsing tests alongside fixtures for reproducibility (e.g., `pricewatch/app/stores/amazon/fixtures/`).
- Name tests `test_*` and favor unit tests for parsing and URL handling before integration tests.

## Commit & Pull Request Guidelines
- No Git history is available in this repository, so use clear, imperative commit subjects (e.g., “Add Cdiscount price parser”).
- PRs should include: a concise description, relevant CLI output or sample JSON, and test results.
- Update `README.md`, `TODO.md`, and `CHANGELOG.md` when behavior or usage changes.

## Agent-Specific Instructions
- Keep decisions justified briefly (1–3 sentences) and avoid silent failure paths.
- Ensure debug information is preserved in `ProductSnapshot.debug` for scraping errors.