nickol-knx

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

Find the device whose ETS **parameter** settings differ from its N identical siblings — the odd thermostat/sensor out (e.g. one thermostat with a different setpoint/hysteresis, one presence detector with a different detection time). 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).

Detect missing, inconsistent or mismatched DPTs.

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.

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

Detect controllable GAs lacking a status/feedback counterpart.

Validate naming conventions and 3-level structure.

Validate the loaded project against a **Project Policy Profile** — *your* agreed rules (main-group taxonomy, naming regex, command/status exemptions), not one universal "standard". Flags GAs whose domain doesn't match the main group your policy assigns, and names that don't match your pattern. Pass `profile_path` to a YAML profile (omit to validate against the taxonomy inferred from the project itself). Set `write_example_to` to drop a commented example profile into the workspace — **seeded from the loaded project's own main groups** (mains that do not exist in the project are not written). Report-only.

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.

Check topology capacity and individual-address validity (KNX Handbook). Flags lines over the TP1 segment (64) / line (256) limits, invalid or duplicate individual addresses, and multi-line projects missing a coupler.

Compose a **new** KNX project from a list of room templates (constructor). ``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.

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.

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

**Provenance** for one group address — why the tool classified it the way it did. Replays the classification and shows, per decision (category / kind / status pairing), the signals that fired with a **confidence tier**: authoritative (an ETS Function role) > structural (the KNX DPT) > heuristic (a name keyword). Flags **conflicts** (e.g. a GA the DPT calls `lighting` while its name says "AC") — the hotspot for silent misclassification. Read-only; use before trusting a category or generating an entity.

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.

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

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

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.

List devices (individual address, name, order number, manufacturer), sorted by individual address (area/line/device numerically). Same paging contract as `list_group_addresses`: `next_cursor` / `total_matched` / `returned`.

Return the area/line/device topology tree.

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

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

List parsed group addresses with classification, in a **stable order**. 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.

Load an ETS group-address export (ga-export/01 XML) instead of a full .knxproj. 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.

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

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

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

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

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.

Validate a Room Library template against the R1 schema (report-only). 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.

Show the confined output workspace and the safety guarantees.