docs: add spec-PDF→KNX case study (EN+RU, anonymised)

A 96% structural match of an auto-designed GA structure vs a professional
reference, from a 42-page spec alone — 662 GA, 0 validation errors, HA package.
No client data/files; reference used only as an anonymous benchmark.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -11,6 +11,7 @@ It reads your `.knxproj`, analyzes group addresses / DPTs / topology, generates
 [![Live demo](https://img.shields.io/badge/live%20demo-online-brightgreen?logo=homeassistant&logoColor=white)](https://nickoscope.github.io/nickol-knx-mcp/)
 [![Join the discussion](https://img.shields.io/badge/💬_join_the-discussion-8957e5?logo=github&logoColor=white)](https://github.com/NickoScope/nickol-knx-mcp/discussions/1)
 [![nickol-knx-mcp MCP server](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp)
+[![Case study](https://img.shields.io/badge/📐_case_study-spec_PDF_→_KNX_(96%25)-0b3d2e)](docs/case-study.md)
 
 🇷🇺 **Русская версия:** [README.ru.md](README.ru.md)
 

README.ru.md

@@ -6,6 +6,7 @@
 Читает `.knxproj`, анализирует group addresses / DPT / топологию, генерирует Home Assistant KNX YAML и ETS-импортируемые group-address файлы (XML/CSV), делает человекочитаемые отчёты — **никогда не подключаясь к живой шине KNX.**
 
 [![nickol-knx-mcp MCP server](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp)
+[![Кейс](https://img.shields.io/badge/📐_кейс-ТЗ_PDF_→_KNX_(96%25)-0b3d2e)](docs/case-study.ru.md)
 
 > ⚠️ **Статус: BETA.** Сервис проверен на синтетическом проекте (16 GA) и проходит end-to-end тест, но **на реальных `.knxproj` пока тестировался ограниченно**. Нужны тестировщики — см. [CONTRIBUTING.md](CONTRIBUTING.md).
 >

docs/case-study.md

@@ -0,0 +1,55 @@
+# Case study — from a spec PDF to a validated 662-GA KNX structure, in minutes
+
+🇷🇺 **Русская версия:** [case-study.ru.md](case-study.ru.md)
+
+## The question
+How far can a project **specification alone** be turned into a finished, standards-correct KNX
+group-address structure — and how close would it get to professional work?
+
+## Input
+A real residential project — **14 rooms (~155 m²)**, Zennio-based: switched + dimmed lighting,
+electric underfloor heating, ventilation with heat recovery, motorised curtains,
+water / electricity / heat metering, leak & fire safety — described **only in a 42-page technical
+specification (PDF)**. No group addresses, no DPTs, no naming were given: the spec lists equipment
+and functions, not a KNX structure.
+
+## The workflow
+```
+spec PDF
+   │  an AI assistant, grounded in the KNX Association standard + industry practice,
+   ▼  DESIGNS the full group-address structure
+GA structure (taxonomy · naming · DPTs · command/status pairs · scenes · reserves)
+   │  nickol-knx-mcp VALIDATES it and GENERATES the outputs
+   ▼
+Home Assistant package  +  ETS-importable group-address XML
+```
+
+## Output
+- **662 group addresses** across **10 functional domains**, as a `ga-export/01` XML ready for ETS
+  *Import Group Addresses* → place devices → export `.knxproj`.
+- Produced in **minutes**.
+
+## The check — against a professional reference implementation of the same project
+| Metric | Result |
+|---|---|
+| Structural match | **96 %** (662 vs 687 GA) |
+| Domain taxonomy | **10 / 10 identical** |
+| Address names | **118 byte-identical**, 68 % with a close analog |
+| DPT discipline | exact sub-types throughout; DPT 5.001 ≈ 1 : 1 |
+| Validation (nickol-knx-mcp) | **0 errors**; reserve / logic noise auto-classified |
+| Home Assistant | **9 climate zones · 11 shutters · 12 dimmers** + sensors, generated directly |
+
+## What it shows
+The standardised, time-consuming **"skeleton"** of a KNX project — the part defined by the standard
+and the equipment — can be auto-designed to **near-professional quality in minutes, vs the days** of
+manual group-address work. That frees the engineer's time for the genuinely creative part: the
+project-specific logic, which stays the engineer's craft (the residual few % are exactly those
+one-off logic functions).
+
+## Honesty notes
+- **No client data or project files are shared.** The reference implementation is used only as an
+  anonymous benchmark; the case study reports parameters and match figures, nothing identifying.
+- The **design** is produced by an AI assistant grounded in KNX knowledge (the KNX Association
+  standard + broad industry practice). **nickol-knx-mcp's role** is read-only validation and
+  Home Assistant / ETS export — it never connects to a live bus.
+- Figures are from a structure that actually passed the tool's own checks (0 errors).

docs/case-study.ru.md

@@ -0,0 +1,54 @@
+# Кейс — из PDF-ТЗ в выверенную KNX-структуру на 662 GA, за минуты
+
+> 🌍 **English version:** [case-study.md](case-study.md)
+
+## Вопрос
+Насколько далеко можно **из одного ТЗ** получить готовую, корректную по стандарту KNX-структуру
+групповых адресов — и насколько близко к работе профессионала?
+
+## Вход
+Реальный жилой проект — **14 помещений (~155 м²)**, на оборудовании Zennio: коммутируемый и
+диммируемый свет, электрический тёплый пол, вентиляция с рекуперацией, моторизованные шторы,
+учёт воды / электро / тепла, протечки и пожарная безопасность — описан **только в 42-страничном
+ТЗ (PDF)**. Ни группадресов, ни DPT, ни нейминга в ТЗ нет: там оборудование и функции, не KNX-структура.
+
+## Конвейер
+```
+PDF-ТЗ
+   │  AI-ассистент, опираясь на стандарт KNX Association + мировую практику,
+   ▼  ПРОЕКТИРУЕТ полную структуру групповых адресов
+GA-структура (таксономия · нейминг · DPT · пары команда/статус · сцены · резервы)
+   │  nickol-knx-mcp ВАЛИДИРУЕТ её и ГЕНЕРИРУЕТ выходные файлы
+   ▼
+пакет Home Assistant  +  ETS-импортируемый XML групповых адресов
+```
+
+## Выход
+- **662 групповых адреса** в **10 функциональных доменах**, как `ga-export/01` XML, готовый для ETS
+  *Import Group Addresses* → размещение устройств → экспорт `.knxproj`.
+- Получено за **минуты**.
+
+## Сверка — с профессиональной эталонной реализацией того же объекта
+| Метрика | Результат |
+|---|---|
+| Структурное совпадение | **96 %** (662 против 687 GA) |
+| Таксономия доменов | **10 из 10 совпали** |
+| Имена адресов | **118 дословных**, 68 % с близким аналогом |
+| DPT-дисциплина | точные под-типы у всех; DPT 5.001 ≈ 1 : 1 |
+| Валидация (nickol-knx-mcp) | **0 ошибок**; шум (резервы/логика) распознан автоматически |
+| Home Assistant | **9 климат-зон · 11 штор · 12 диммеров** + датчики, собраны сразу |
+
+## Что это показывает
+Стандартизованный и трудоёмкий **«скелет»** KNX-проекта — то, что определяется стандартом и
+оборудованием — проектируется автоматически до **почти профессионального уровня за минуты против
+дней** ручной работы с группадресами. Это освобождает время инженера для по-настоящему творческой
+части — проектной логики, которая остаётся его ремеслом (оставшиеся проценты — ровно эти одноразовые
+логические функции).
+
+## Честные оговорки
+- **Никакие клиентские данные и файлы проектов не публикуются.** Эталонная реализация используется
+  только как анонимный ориентир; в кейсе — параметры и проценты совпадения, ничего идентифицирующего.
+- **Проектирование** выполняет AI-ассистент, заземлённый на знания KNX (стандарт KNX Association +
+  мировая практика). **Роль nickol-knx-mcp** — валидация только на чтение и экспорт в Home Assistant /
+  ETS; к живой шине он не подключается.
+- Цифры — со структуры, которая реально прошла проверки инструмента (0 ошибок).