[Liebmann5]

What this changes

Adds a search builder: a person picks an engine, a job board, a hiring platform or one company's careers page, and AA composes the search-bar text and/or link for them to copy or open. It ships on both surfaces: the CLI (--search plus scriptable --search-* flags) and the GUI (File → Build a Search…). It automates nothing; the only outward call is opening a link on an explicit click. The branch also updates kimicli.py (root tooling: per-run model choice and a saved default model, K3 still the default).

Why

Users had no way to build a precise search for a given site without knowing each engine's operators, and no way to tell which searches AA can stand behind. The builder offers only searches whose mechanics are documented, labels what is unverified, and refuses (rather than silently weakening) any restriction a surface cannot carry.

How it was verified

Full suite on Windows at the branch head:

2415 passed, 5 skipped, 1 xfailed

• Each step was applied to a copy of the tree and the suite run before it touched the repo; the Windows count matched the prediction at every step (2371 → 2402 → 2415).
• +173 tests over main.
• tests/adapters/test_engine_url_byte_identity.py is green and untouched: automated discovery sends the same URL bytes as before.
• CLI checked by hand: --search-platform jobvite|bamboohr|gusto --search-terms "Software Engineer" prints site:jobs.jobvite.com ("Software Engineer"), site:bamboohr.com/careers ("Software Engineer") and site:jobs.gusto.com/boards ("Software Engineer"); an Indeed platform search prints its refusal and exits 1.
• GUI window opened under a virtual display: built the Jobvite search on Google, showed the location note, Keep stored the resolved site: query, and the window rendered fully in English and Spanish.

Checklist

• All four gates pass locally (the F821 and both mypy gates run inside the suite: test_lint_gate, test_mypy_gate)
• Documentation updated in this PR if behaviour changed (user guide building_searches.md, reference/cli.md, ui_port_layer.md, the Bible, README, verifying_platform_search.md)
• CHANGELOG.md updated under Unreleased
• An ADR is included, or none is needed: ADR-019, search-surface catalog and query builder
• Nothing was deleted — no file is removed in this branch
• No personal data in the diff, the tests, or the fixtures

Pins added or changed

Test	Label (teeth / differential / coverage / characterisation / guard)	Shown failing first?
tests/domain/test_query_composer.py	teeth + guard (composer, refusal-both, location/phrase notes)	Stated per pin in the change; not independently re-checked
tests/infrastructure/test_search_surface_registry.py	teeth (catalog loading, bundled-only for automation)	Stated per pin; not independently re-checked
tests/infrastructure/test_ats_platforms.py	teeth + guard (platform descriptors, search restrictions)	Stated per pin; not independently re-checked
tests/application/test_query_builder_service.py, test_query_builder_platforms.py	teeth + guard (build writes nothing; remember is the only writer)	Stated per pin; not independently re-checked
tests/adapters/test_search_builder_cli.py	teeth + guard (three known queries, refusals exit non-zero, remember only on copy/open/keep, GUI-free and offline)	Stated per pin; not independently re-checked
tests/adapters/test_gui_search_window.py	teeth (widget-free helpers, CLI/GUI parity, resolved replay)	Stated per pin; not independently re-checked
tests/adapters/test_engine_url_byte_identity.py	differential (automation URLs unchanged)	Passed before and after by design
test_ui_contract.py, test_ui_port_conformance.py, test_safety_pins.py	guard (port surface 17 → 27, data-only DTO modules, one new commented reach)	Updated with the port

Predicted suite count after this change: 2242 → 2415 passed (5 skipped, 1 xfailed), +173 tests over main

Risk

• Renamed service methods. QueryBuilderService's builder methods now use the UI port's names (build_query, remember_query, …). Every caller in the repo was updated and the suite is green; anything outside the repo calling the old names would break.
• UIPort grew from 17 to 27 methods. Conformance and data-only pins hold it, but every new port implementer must provide them.
• GUI keyboard and screen-reader behaviour (real Tab order, announcements) is not testable headless; the pins cover the widget-free rules only. Needs a manual pass.
• Composer notes are English only. A Spanish user sees English notes; localising them is a follow-up.
• Platform coverage is unverified for all platforms except Jobvite. The mechanism is documented; the reach is not. Each is labelled as such in the picker.
• Search sites change syntax without notice, so a verified mark is only as good as its date.
• Tier trade: none intended. Automated discovery is byte-identical; the builder is user-driven only.

Screenshots

None attached.

[sourcery-ai]

Sorry @Liebmann5, your pull request is larger than the review limit of 300,000 diff characters