# Agent Playbook

Local operating guide for contributors and AI agents working on `kleinanzeigen-bot`.

Prefer tracked repo files and CI as the source of truth. If this file conflicts with them, the tracked docs/workflows win. Make minimal, focused changes that match existing patterns.

## Read First

Before making non-trivial changes, review:

- `README.md`
- `CONTRIBUTING.md`
- `docs/TESTING.md`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/workflows/build.yml`
- `.github/workflows/validate-pr-title.yml`

## Hard Repo Rules

- Never hit `kleinanzeigen.de` in tests.
- Write code, comments, and contributor-facing docs in English by default.
- For runtime/user-facing output, follow the translation rules in `CONTRIBUTING.md` and update translations when messages change.
- Keep log message strings in plain English; do **not** wrap `LOG.*`/`logger.*` strings with `_()`, because logging messages are translated by `TranslatingLogger`.
- New Python files need the full SPDX header block from `CONTRIBUTING.md`.
- Use full type hints (Python 3.10+ syntax).
- Catch `TimeoutError` in browser automation paths.
- Never hardcode credentials or secrets.
- Prefer small, simple changes over speculative abstractions.

## Project Contract

`kleinanzeigen-bot` is a CLI application, not a supported Python library API.

Keep stable from a user perspective:

- CLI commands, options, and exit behavior
- Config files and config defaults
- Generated YAML behavior and persisted ad file mutations
- Runtime/user-facing messages and translation behavior
- Browser workflows and automation outcomes

Do not preserve accidental internal compatibility:

- Package-root imports for helpers, models, or extracted modules
- Monkeypatch paths in tests
- Compatibility aliases for internal helpers
- Wrapper methods or re-exports whose only purpose is preserving old internal import paths

## Repo Patterns

- Browser automation: follow existing `WebScrapingMixin` patterns and use `ensure()` for validation.
- Logging: use `loggers.get_logger(__name__)`.
- Config and file paths: prefer `pathlib.Path` and existing file helpers.
- For Windows-specific cross-platform path logic, prefer `pathlib.PureWindowsPath` when relevant.
- Keep browser-independent domain logic in top-level `src/kleinanzeigen_bot/*.py` modules; reserve `src/kleinanzeigen_bot/utils/` for generic infrastructure helpers.
- Pydantic models belong in `src/kleinanzeigen_bot/model/`.
- Tests belong in `tests/unit/`, `tests/integration/`, or `tests/smoke/`.
- Use the repo's registered pytest markers.

## Testing Guidance

Add or update tests when changing observable behavior, business logic, error handling, or fixing bugs.

Tests may be skipped for:

- log-only wording changes
- diagnostic-only changes with no behavior impact
- trivial wrappers already covered elsewhere

Testing rules:

- Test behavior, not implementation details.
- Prefer extending existing tests over adding duplicates.
- If you touch nearby tests, clean up obvious stale or duplicate coverage when it is cheap and in scope.
- For smoke tests, prefer simple fakes/dummies over mocks and patching.

`docs/TESTING.md` is the authority for test types, execution, and smoke-test conventions.

## Validation Before Work Is Done

Run in this order:

1. `pdm run format`
2. `pdm run lint` — run the repo's configured lint/type-check suite. Use `pdm run lint:fix` first for auto-fixable ruff issues.
3. `pdm run test`

When changing models, config defaults, schema-affecting validators, or `create-config` output, also regenerate committed artifacts:

- `pdm run generate-schemas` — regenerates `schemas/*.json`
- `pdm run generate-config` — regenerates `docs/config.default.yaml`
- `pdm run generate-artifacts` — runs schemas, config, and README usage regeneration

CI and workflows are the source of truth for the exact required checks, coverage gates, generated-artifact verification, and PR title validation.

## PR Expectations

- PR titles must follow the semantic format enforced by `.github/workflows/validate-pr-title.yml`.
- Branch names should use the same conventional type prefix as the PR title, e.g. `docs/update-agent-playbook`, `fix/browser-timeout`, or `feat/price-logging`.
- PR descriptions should use `.github/PULL_REQUEST_TEMPLATE.md` and complete its required sections and checklist.
- Do not open a PR with placeholder sections, missing checklist decisions, or a non-semantic title; fix the title/body before publishing.

## Completion Checklist

- [ ] Change is minimal and focused
- [ ] Tests were added or updated if behavior changed
- [ ] Translations were updated if needed
- [ ] Generated artifacts (`schemas/*.json`, `docs/config.default.yaml`) were updated if models or config defaults changed
- [ ] `pdm run format` passes
- [ ] `pdm run lint` passes
- [ ] `pdm run test` passes
- [ ] No unrelated issues introduced