Args:
    path: Path to the .knxproj file.
    password: Project password, if the .knxproj is protected.
    language: Optional language code (e.g. 'de-DE', 'ru-RU').

For when you only have the GA list: an ETS "Export Group Addresses" file, or the
ETS import file a planning tool produces (TapPlan and similar). Names, addresses,
DPTs, descriptions, the security flag and the range tree are read; the result
replaces the loaded project for every other tool.

Works: check_naming, check_missing_status, check_dpt, check_policy, check_secure,
analyze_all, suggest_repairs, project_report, generate_ha_package,
generate_ets_group_addresses. Nothing to read (the export has no devices, ETS
Functions or topology): get_devices, get_topology, check_topology,
decompose_device, check_device_parameters, parse_devices_from_project. Pairing
relies on names only, since there are no ETS Function roles.

Args:
    path: Path to the exported .xml file.

Filters: category (lighting/shutter/hvac/sensor/scene/energy/diagnostics),
kind (command/status/sensor), missing_dpt_only.

Paging: results are always sorted by the group address itself (main/middle/sub
numerically, free-style addresses numerically, anything else lexically), so the
order does not depend on how the project happened to parse and a retry returns
the same page. Pass the returned `next_cursor` back as `cursor` for the next
page; `next_cursor` is null on the last page. `total_matched` reports how many
addresses match the filters, so a truncated answer is never silent.

For each issue it suggests a reviewable fix: infer a DPT for a GA that has none,
correct a suspect sub-DPT, synthesise a status/feedback GA in a free address slot,
or add an absolute-brightness GA for a relative-only dimmer. Suggestions only —
a human reviews them; accepted new GAs feed generate_ets_group_addresses. The
server never writes to ETS or the bus.

If output_path is given, the YAML is written into the workspace and the path
returned; otherwise the YAML text is returned inline.

Args:
    fmt: 'xml' (ga-export/01, recommended) or 'csv' (native ETS layout).
    output_path: optional file inside the workspace.

Assembles an equipment inventory, group-address map by domain, command/status
coverage, KNX Secure scope and QA state into ``handover.md``, plus a
``topology.svg`` diagram, the full ``group-addresses.csv`` and the
``ha-package.yaml``. When ``output_dir`` is given (a folder inside the
workspace) all files are written there and the paths returned; otherwise the
handover markdown + SVG are returned inline.

Reads the manufacturer application programs (M-*) embedded in an ETS `.knxproj`
(devices actually used) or a `.knxprod` product database, and returns each device's
order number, app-program version, object counts and detected per-channel blocks —
the EXACT vendor comm-object model, not a generic recipe. Read-only and PII-safe: it
reads only vendor catalog data, never the client project (P-*/0.xml).

Use this to build/grow the local device catalog that `decompose_device` consumes
(set NICKOL_KNX_CATALOG to the catalog dir). If `output_path` is given, the full
catalog is written into the workspace as device-library YAML; the return value is
always a compact per-device summary + coverage manifest (the full object lists are
not inlined). DPT `unverified` = the vendor app-program declares none (never guessed).

Reads per-device parameter values straight from the `.knxproj` project part
(data xknxproject does not expose), groups identical devices by application
program, and returns `clear_outliers` (a strong majority with a small minority —
likely a mistake) and `split_configs` (balanced 2+ variants — review, often two
zones). Numeric config parameters are listed first; names are resolved from the
device application program. Read-only, no ETS/bus. Give a real `.knxproj` `path`
(a password-protected/encrypted project cannot be read).

Pass ``template`` (a built-in template's semantic slot_id, e.g. 'bedroom',
'kitchen') or ``path`` to a custom template YAML. Checks the public contract:
a locale-neutral slot_id, ru/en labels, per-slot basic/comfort presets, known
function types, valid multiplicities, and that ``area_m2`` is a hint with
provenance (never a normative fact). Returns ok + findings; nothing is written.

``rooms`` is a list of specs, each: ``{template, preset?, slot_presets?,
params?, label?}`` — e.g. ``{"template": "bedroom", "preset": "comfort"}``.
``preset`` is basic|comfort (per-room); ``slot_presets`` overrides individual
slots (mix comfort climate with basic lighting); ``params`` overrides template
defaults (window/circuit counts); ``label`` sets a custom zone name.

Pipeline: resolve templates+params to a functional model, allocate group
addresses (main = domain, middle = role, sub sequential), write a real
``.knxproj`` and **re-read it with the standard loader**, then run our linters
on the re-read project. Output: a ``manifest`` (allocation), ETS GA XML/CSV,
and a device ``bom`` proposal from the device library.

R1 builds NEW projects only and is dry-run by default (nothing written). Set
``dry_run=false`` with ``output_dir`` (a folder inside the workspace) to write
the .knxproj, ETS exports, manifest.yaml and bom.yaml. Docking into an
existing project and exact device selection are R2. Never touches a bus.