Parse a .knxproj file (read-only) and cache it for the session.

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').

List parsed group addresses with classification.

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

List devices: individual address, name, order number, manufacturer.

Return the area/line/device topology tree.

Validate naming conventions and 3-level structure.

Detect controllable GAs lacking a status/feedback counterpart.

Detect missing, inconsistent or mismatched DPTs.

Propose concrete fixes for the project's findings — repair, don't just flag.

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.

Summarise KNX Data Secure posture + the keyring handover checklist.

Reports how many group addresses are secured vs plaintext, flags middle groups that mix secure and plaintext addresses (a function is only as secure as its weakest GA), and emits the ETS/HA keyring workflow as a checklist. Report-only — this server never touches key material.

Run every check and return the report summary plus all findings.

Generate a Home Assistant KNX package YAML.

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

Generate an ETS-importable Group Address export.

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

Produce the human-readable Markdown report (review before any import).

Generate a project handover pack (as-built deliverable for commissioning).

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.

Expand a device into its group-address decomposition recipe.

A KNX actuator channel is not one GA — it expands into command/status/dimming/ position/mode objects, each with its DPT. Given a device order number, type or alias (e.g. 'ZIO-MB24', 'dimmer', 'JRA/S', 'presence detector') and a channel count, returns the objects a professional wires per channel and the total GA count. Use when turning a spec/ТЗ device list into a group-address structure.

List the device decomposition recipes in the built-in device library.

Extract exact device object models from a .knxproj / .knxprod application programs.

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).

Matter-readiness lint: which controllable functions round-trip to a Matter cluster (have command + status + a decodable DPT) and which won't.

Grade the project: bare functional skeleton vs as-built grade — by the presence of the professional patterns (central macros, device tuning, astro/meteo, monitoring, deep metering, scenes, reserves, a debug main).

Check the metering/energy domain (energy DPTs 13.x / 14.056) and suggest a per-circuit / PV / battery / EVSE structure for the HA energy dashboard.

Naming hygiene suggestions (empty names, status GAs missing a status keyword).

Draft a functional acceptance protocol (per function: command → expected status, pass/fail/sign-off) as Markdown. Execution is manual/on-site; this only drafts it.

Semantic diff between two .knxproj files (path_a = base/old, path_b = new): added / removed GAs, DPT changes, renames, security-flag changes. Read-only.

Export a KNX IoT semantic view (Turtle/RDF) of the project's functional datapoints — a pragmatic skeleton for the IP-native model, for review.

Show the confined output workspace and the safety guarantees.