docs(xdto-guide): примеры задачами, а не синтаксисом команд

Гайд адресован неподготовленному читателю, а основной сценарий — задача
в произвольной форме или её часть внутри большей. Синтаксис вызовов такого
читателя скорее отпугнёт, к тому же он уже описан в SKILL.md каждого навыка
и в гайде дублировался.

Каждый сценарий теперь начинается с того, как задачу формулируют словами
(«сформируй платёжку в формате клиент-банка», «обращение к Смена.Сотрудник
возвращает что-то бесструктурное»), дальше — что за этим происходит и на что
обратить внимание. За точным синтаксисом — ссылки на SKILL.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/xdto-guide.md

@@ -5,6 +5,9 @@
 Встречается везде, где 1С обменивается данными наружу: ЭДО, ЕГАИС, ВЕТИС, ФСС,
 клиент-банк, веб-сервисы, `EnterpriseData`.
 
+Навыки вызываются агентом сами — задачу можно ставить обычными словами. Ниже
+примеры формулировок и того, что за ними происходит.
+
 ## Навыки
 
 | Навык | Задача |
@@ -22,115 +25,94 @@
 
 ### Написать код, который заполняет объект XDTO
 
-Самая частая задача. Нужны namespace, имя типа и состав свойств — какой тип значения
+> «Сформируй платёжное поручение в формате клиент-банка и выгрузи в файл»
-присваивать, что обязательно, где создавать вложенный объект.
+>
+> «Напиши обработку выгрузки заказов по нашему обмену с маркетплейсом»
 
-```powershell
+Самая частая задача, и обычно она часть большей. Прежде чем писать код, агент
-# известны namespace и тип (например, из строки ФабрикаXDTO.Тип(...) в чужом коде)
+смотрит структуру типа: какой тип значения присваивать каждому свойству, что
-/xdto-info src -Namespace "urn:1C.ru:ClientBankExchange" -Name ПлатежныйДокумент -Depth 2
+обязательно, где нужно создать вложенный объект, какие значения допустимы.
 
-# только обязательное — скелет для заполнения
+Выводится это уже в терминах 1С — `Строка(6)`, `Число(18,2)`, `[обязательный]`, —
-/xdto-info src -Namespace "urn:1C.ru:ClientBankExchange" -Name ПлатежныйДокумент -RequiredOnly
+поэтому переводить `xs:decimal` и `lowerBound="0"` в голове не приходится.
-```
+Если тип большой, помогает срез только обязательных свойств: получается готовый
-
+скелет заполнения.
-Вывод даёт типы уже в нотации 1С (`Строка(6)`, `Число(18,2)`), помечает обязательные
-свойства и коллекции, перечисляет допустимые значения и подсказывает вызовы фабрики.
-Читать `Package.bin` при этом не нужно.
-
-Если имя пакета неизвестно, а тип известен — `-Name` по корню исходников найдёт его
-по всем пакетам конфигурации.
 
 ### Разобрать входящий XML
 
-Нужно понять, какому типу соответствует корень документа. Это **точки входа** —
+> «Разбери входящий файл ЕГАИС и создай по нему документы»
-глобальные объявления пакета:
+>
+> «Какому типу соответствует корень этого XML?»
 
-```powershell
+Чтобы прочитать документ, надо знать, с какого типа начинать. Это **точки входа**
-/xdto-info src -Namespace "urn:partner:orders"
+пакета — его глобальные объявления; агент покажет их вместе со списком типов.
-```
-
-Дальше по имени типа — состав свойств, как в предыдущем сценарии.
 
 ### Добавить пакет по схеме контрагента
 
-```powershell
+> «Контрагент прислал схему обмена заказами, добавь её в конфигурацию»
-/xdto-compile -XsdPath partner.xsd -OutputDir src -Name ЗаказыКонтрагента
+>
-/xdto-validate src/XDTOPackages/ЗаказыКонтрагента
+> «Нужен пакет XDTO по вот этой XSD от ФСС»
-```
 
-**Читай предупреждения компилятора.** XML Schema выразительнее модели XDTO, и часть
+Пакет собирается по схеме и сразу регистрируется в конфигурации.
-конструкций переносится приближённо: вложенные `xs:choice` уплощаются, `xs:all`
-становится последовательностью, кратность на частице отбрасывается. Навык печатает,
-что именно упростилось; если упрощение недопустимо — меняй схему, а не игнорируй.
 
-Схема ссылается на чужой namespace через `<xs:import>` — сначала собери пакет-зависимость.
+**Обрати внимание на предупреждения.** XML Schema выразительнее модели XDTO, и часть
-Иначе платформа при загрузке молча подменит тип на `xs:anyType`, и обнаружится это
+конструкций переносится приближённо: вложенный `xs:choice` уплощается (ветки при этом
-только в рантайме.
+становятся необязательными), `xs:all` превращается в последовательность, кратность
+на частице отбрасывается. Агент об этом сообщит — если упрощение недопустимо,
+схему надо менять, а не игнорировать сообщение.
+
+Если схема ссылается на чужое пространство имён через `<xs:import>`, сначала нужен
+пакет-зависимость. Иначе платформа откажется принимать конфигурацию либо молча
+подменит тип на «произвольный», и всплывёт это уже в рантайме.
 
 ### Поправить существующий пакет
 
-Точечно — `/xdto-edit`, схему целиком читать не нужно:
+> «Добавь в платёжное поручение необязательный комментарий, не длиннее 200 символов»
+>
+> «Убери из обмена устаревшее поле СтарыйКод»
+>
+> «Добавь в перечисление видов документов значение Инкассо»
 
-```powershell
+Точечная правка не требует читать схему целиком — для больших пакетов вроде
-/xdto-edit src/XDTOPackages/ОбменСБанком -Operation add-property -Target "ПлатежныйДокумент" `
+`EnterpriseData` это единственный практичный путь. После правки автоматически
-           -Value '<xs:element name="Комментарий" type="xs:string" minOccurs="0"/>'
+запускается проверка.
-```
 
-Многострочный фрагмент передавай файлом: `-Value "@frag.xsd"`.
+Перед изменением существующего типа полезно узнать, кого оно затронет: агент
+покажет, какие типы и пакеты на него ссылаются.
 
-Перед правкой существующего типа полезно посмотреть, кого она затронет:
+Если переработка широкая — «перепиши обмен под новую версию формата» — схема
-
+выгружается целиком, правится и собирается обратно. Пара выгрузка-сборка
-```powershell
+замыкается без потерь, включая имя, синоним и комментарий объекта метаданных.
-/xdto-info src -Mode used-by -Name СуммаТип
-```
-
-Если переработка широкая или сначала надо разобраться в схеме — выгрузи её целиком:
-
-```powershell
-/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd
-# правка bank.xsd
-/xdto-compile -XsdPath bank.xsd -OutputDir src -Name ОбменСБанком -Force
-```
-
-Пара замыкается без потерь, включая имя, синоним и комментарий объекта метаданных.
 
 ### Новая версия пакета
 
-Типовой приём в обменах: рядом со старым пакетом появляется новый с другим
+> «Сделай версию 2.0 нашего обмена, старая должна продолжать работать»
-пространством имён (`EnterpriseData_1_19` → `_1_20`). Старые потребители продолжают
-смотреть на прежний namespace.
 
-```powershell
+Типовой приём: рядом со старым пакетом появляется новый с другим пространством
-/xdto-decompile src/XDTOPackages/Обмен_1_0 -OutFile v2.xsd
+имён (`EnterpriseData_1_19` → `_1_20`), а старые потребители продолжают смотреть
-# правка targetNamespace и содержимого в v2.xsd
+на прежний namespace.
-/xdto-compile -XsdPath v2.xsd -OutputDir src -Name Обмен_2_0
-```
 
-Если же нужно сменить namespace **у существующего** пакета — `/xdto-edit -Operation
+Если же надо сменить namespace **у существующего** пакета, агент перепишет все
-set-namespace`. Он перепишет все внутренние ссылки и перечислит пакеты, которые
+внутренние ссылки и перечислит пакеты, которые импортируют старый — но менять
-импортируют старый namespace, но менять их не станет.
+их не станет, потому что при версионировании это было бы ошибкой.
 
 ### Отдать схему контрагенту
 
-```powershell
+> «Выгрузи схему нашего обмена, отправлю партнёру»
-/xdto-decompile src/XDTOPackages/ОбменСБанком -OutFile bank.xsd
-```
 
-Схема валидна и ничего не теряет. Штатный «Экспорт XML-схемы» в Конфигураторе для
+Получается валидная XSD, ничего не теряющая. Штатный «Экспорт XML-схемы»
-этого хуже: он теряет `nillable` у свойств-атрибутов.
+в Конфигураторе для этого хуже: он теряет признак `nillable` у свойств-атрибутов.
 
 ### Разобраться, почему обмен ведёт себя странно
 
-Симптом «свойство возвращает что-то бесструктурное» почти всегда означает, что тип
+> «Обращение к Смена.Сотрудник возвращает что-то бесструктурное, разберись»
-не разрешился и стал `xs:anyType`:
+>
+> «Пакет вроде загрузился, а обмен не работает»
 
-```powershell
+Такой симптом почти всегда означает, что тип не разрешился и стал «произвольным».
-/xdto-validate src/XDTOPackages/ПодозрительныйПакет -Detailed
+Платформа об этом молчит: при импорте XML-схемы неразрешённый чужой тип заменяется
-```
+без единой ошибки, пакет выглядит загруженным. Проверка называет и симптом,
-
+и причину — объявленный, но неиспользуемый импорт.
-Платформа такие вещи не диагностирует: при импорте XML-схемы неразрешённый чужой тип
-заменяется молча, пакет выглядит загруженным. Валидатор называет и симптом, и причину —
-объявленный, но неиспользуемый `<import>`.
 
 ## Структура файлов
 
@@ -146,10 +128,12 @@ XDTOPackages/
 
 ## Рабочий цикл
 
-1. `/xdto-info` — понять, что есть
+1. Посмотреть, что есть — `/xdto-info`
-2. `/xdto-compile` или `/xdto-edit` — изменить
+2. Изменить — `/xdto-compile` или `/xdto-edit`
-3. `/xdto-validate` — проверить до загрузки
+3. Проверить до загрузки — `/xdto-validate`
-4. `/db-load-xml` + `/db-update` — применить
+4. Применить — `/db-load-xml` + `/db-update`
+
+Точный синтаксис параметров каждого навыка — в его `SKILL.md` по ссылкам выше.
 
 ## Спецификации