docs(runbook): skills-catalog deploy — финализация (команды deploy-catalog.mjs из README, task:1461 done); core-immutable interim до mappa 1466/1467

.wiki/concepts/runbooks-index.md

@@ -47,7 +47,7 @@ updated: 2026-08-26
 | Операция | Ранбук | Что покрывает |
 |---|---|---|
 | Создание Gitea-репо (проект в Gitea) | [`gitea-project-create-runbook.md`](gitea-project-create-runbook.md) | private-репо: admin POST /user/repos → transfer к владельцу; pre-flight; verify; rollback; gotchas (SSH-порт 2222, pass-рефы) |
-| Деплой каталога скилов на сервер mappa | [`skills-catalog-deploy-runbook.md`](skills-catalog-deploy-runbook.md) | синк репо-каталогов (mappa-skills/mappa-vitya-skills) → /skills на mappa.vds.kzntsv.site; стоящее правило «деплой при каждом изменении исходников» (письмо от владельцев); DRAFT — команды после mappa task:1461 |
+| Деплой каталога скилов на сервер mappa | [`skills-catalog-deploy-runbook.md`](skills-catalog-deploy-runbook.md) | синк репо-каталогов (mappa-skills/mappa-vitya-skills) → /skills на mappa.vds.kzntsv.site; deploy-catalog.mjs (dry-run → apply); стоящее правило «деплой при каждом изменении исходников» (письмо от держателя каталога); core-immutable interim до mappa task:1466/1467 |
 | books VDS — оптимизация памяти (OOM → ECONNREFUSED) | [`books-vds-memory-optimize-runbook.md`](books-vds-memory-optimize-runbook.md) | mongo wiredTiger 0.25 / ES heap / CI-остатки buildx; files-compose (НЕ Portainer-kzntsv); verify; rollback; Manticore-задел |
 | MinIO split (books-vds + CMS-media) | [`minio-split-cutover-runbook.md`](minio-split-cutover-runbook.md) | cutover Track A/B, rollback |
 | Общий Portainer-канон VDS kzntsv | [`portainer-stack-management-vds.md`](portainer-stack-management-vds.md) | JWT auth, gotchas 1-10, redeploy-рецепт, инвентарь стеков |

.wiki/concepts/skills-catalog-deploy-runbook.md

@@ -13,10 +13,10 @@ updated: 2026-08-28
 > Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать.
 > Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют.
 
-> ⚠️ **DRAFT (2026-08-28, task:1462).** Секции «Артефакты/Шаги» в части команд
-> заполняются после появления deploy-скриптов в каталогах-репо (mappa **task:1461**,
-> blocked). Scope, стоящее правило, verify/rollback/gotchas — актуальны. Решения
-> оператора по needs-human приняты (см. «Решения оператора»); финализация — после 1461.
+> ✅ **Финализирован (2026-08-28, task:1462).** Команды деплоя — из README каталогов
+> (deploy-catalog.mjs, task:1461 done). Core-immutable — **interim** (ручной шаг только
+> с согласования оператора) до доработки /skills (mappa task:1466/1467): финальный
+> механизм программный, ранбук обновится после их деплоя.
 
 ## Scope
 
@@ -39,26 +39,44 @@ updated: 2026-08-28
 - **Endpoint:** `https://mappa.vds.kzntsv.site/skills` — GET (список), GET `/skills/:name`,
   POST (create). PATCH/DELETE для `kind=core` → **403 (immutable)**.
 - **Токен:** `MAPPA_API_TOKEN` — `<из pass mappa/full-env>` (тот же, что env 3/3 стека mappa).
-- **База deploy-скриптов:** `scripts/seed-skills.ts` (засев-oneshot, task:1448 done).
-  Deploy-скрипты в каждом каталоге-репо (task:1461) — синк изменений вместо oneshot.
-  > DRAFT: точные команды/флаги/ENV — из README репо после 1461.
+- **Deploy-скрипт (task:1461 done):** `scripts/deploy-catalog.mjs` в каждом каталоге-репо
+  (синк изменений вместо oneshot-засева seed-skills.ts, task:1448; kind по имени репо
+  или `--kind`). Тесты: `scripts/deploy-catalog.test.mjs` (`node --test scripts/`).
+  Семантика: отсутствующие → POST (create); изменённые methodology → PATCH (update);
+  изменённый core → `! immutable` (не применяется).
 - **Обратное направление (НЕ этот ранбук):** `scripts/sync-skills.ts` (task:1381) —
   синк каталога mappa → диск харнесса (pi/CC). Разделять: здесь деплой исходников в mappa.
 
-## Шаги (DRAFT — команды заполнить после task:1461)
+## Шаги (команды из README каталогов, task:1461)
 
-0. **Вход:** письмо-уведомление от владельцев репо (что изменилось: скилы/версии) →
-   ops-таска на борде `.admin` (если ещё нет) → прогон по этому ранбуку.
-1. **Pre-flight:** `git pull` каталога-репо; проверить, что README/скрипт 1461 на месте;
-   `admin_secret_scan` — 0 хитов (тела скилов с секретом → 422).
-2. **Dry-run:** прогнать deploy-скрипт каталога в режиме по умолчанию (`--dry-run`) →
-   сверить план: какие скилы создаются/обновляются, нет ли неожиданного.
-3. **Apply:** повторный прогон без dry-run (команда — из README репо, DRAFT).
-4. **Verify** (см. ниже).
-5. **Фиксация:** письмо-отчёт владельцам репо (verify-таблица) + закрытие ops-таски.
+0. **Вход:** письмо-уведомление от проекта-держателя каталога (что изменилось:
+   скилы/версии) → ops-таска на борде `.admin` (если ещё нет) → прогон по ранбуку.
+1. **Pre-flight:** `git pull` каталога-репо (mappa-skills / mappa-vitya-skills);
+   ENV: `MAPPA_API_TOKEN` из `pass mappa/full-env` (+ `MAPPA_CORE_URL` опц., дефолт
+   https://mappa.vds.kzntsv.site); `admin_secret_scan` — 0 хитов (тела с секретом → 422).
+2. **Dry-run** (из чекаута каталога):
+   ```bash
+   node scripts/deploy-catalog.mjs --dry-run   # дефолт тоже dry-run
+   ```
+   Сверить план: `create` / `update` / `immutable (!)` / `up-to-date` — нет ли
+   неожиданного (лишний create = чужой каталог; immutable = правка core).
+3. **Apply:**
+   ```bash
+   node scripts/deploy-catalog.mjs --apply
+   ```
+   Применяет create + update (**methodology** PATCH). Изменённый **core** —
+   `! immutable`, НЕ применяется (см. interim, п.4).
+4. **core-immutable (interim, до деплоя mappa task:1466/1467):** если в плане есть
+   `! immutable` — правки core не применены. Путь: согласование с оператором →
+   обновление сущности вне API (админ-операция .admin / пересоздание) → повторный
+   dry-run подтверждает. **Финал — программный** (после 1466/1467); ручной шаг —
+   только с согласования оператора, не «ограничение навсегда».
+5. **Verify** (см. ниже).
+6. **Фиксация:** письмо-отчёт проекту-держателю (verify-таблица) + закрытие ops-таски.
 
-> Конкретика по каждому каталогу: core-вариант (`mappa-skills`) и methodology-вариант
-> (`mappa-vitya-skills`, фильтр `mappa-vitya-`) — скрипты из task:1461.
+> Конкретика: `mappa-skills` → kind=core (10 скилов), `mappa-vitya-skills` →
+> kind=methodology (2 скила, фильтр mappa-vitya-). Скрипт определяет kind по имени
+> репо (или `--kind core|methodology`).
 
 ## Стоящее правило: деплой при каждом изменении исходников
 
@@ -78,26 +96,30 @@ updated: 2026-08-28
 ## Verify / smoke
 
 - `GET https://mappa.vds.kzntsv.site/skills` (с `MAPPA_API_TOKEN`) — затронутые скилы
-  присутствуют, `version` = актуальная (из frontmatter SKILL.md), `enabled:true`.
-- Прогон без ошибок (created/updated без 4xx/5xx; ошибки → в письме).
+  присутствуют, `version` актуальна (из frontmatter SKILL.md), `enabled:true`.
+- Прогон без ошибок: created/updated без 4xx/5xx (ошибки → в письме); methodology —
+  PATCH применён; изменённый core — остался без применения (interim, зафиксировать в письме).
 - Потребительская сторона: `sync-skills.ts` подхватит обновления на дисках харнессов
-  (методология — после `/reload`, спека wiki:3300 п.11) — это verify-контур, не часть деплоя.
+  (после `/reload`, спека wiki:3300 п.11) — verify-контур, не часть деплоя.
 
 ## Rollback
 
-- **Откат содержимого:** revert коммита в репо-источнике → повторный прогон деплоя
-  (пересинк вернёт прежнее состояние, если механизм обновления 1461 это позволяет).
-- **Удаление ошибочного скила:** `kind=methodology` — DELETE /skills; `kind=core` —
-  **403**, удаление только через механизм 1461 (перезасев/иной путь) или фикс исходника.
-  > DRAFT: уточнить после 1461.
+- **Откат содержимого (methodology):** revert коммита в репо-источнике → повторный
+  `--apply` (PATCH вернёт прежнее тело).
+- **Откат (core):** до деплоя 1466/1467 — только админ-операция вне API (revert
+  исходника → ручной шаг с согласования оператора); после — программный путь из
+  ранбука-апдейта.
+- **Удаление ошибочного скила:** methodology — DELETE /skills; core — 403 (до
+  1466/1467 — админ-операция, после — контролируемый путь).
 
 ## Gotchas
 
-1. **`kind=core` immutable** — PATCH/DELETE `/skills` → 403. Это **пробел сервера**,
-   не «ограничение + ручной шаг» как финал: core обязаны обновляться деплоем по
-   определённому пути → follow-up на доработку `/skills` (требование внесено в task:1461).
-   Ранбук фиксирует финальный механизм, когда 1461 его определит (до этого — DRAFT).
-   Не пытаться PATCH'ить core напрямую. (2026-08-28, решения оператора inbox:2620)
+1. **`kind=core` immutable (interim)** — PATCH/DELETE `/skills` → 403, deploy-catalog
+   помечает правки core как `! immutable` и НЕ применяет. Это **пробел сервера**
+   (решение оператора inbox:2620: «ДОДЕЛАТЬ»): доработка /skills — mappa
+   **task:1466/1467** (ready; в README репо — 1466, в письме inbox:2625 — 1467 —
+   проверить дедуп). До её деплоя — ручной шаг только с согласования оператора.
+   Не пытаться PATCH'ить core напрямую. (2026-08-28)
 2. **422 secret-scan** — тело SKILL.md с секретом (token/password/… ≥6 симв.) →
    `POST /skills` → 422. Перед деплоем прогон `mcp__mappa__admin_secret_scan` (0 hits).
 3. **Направление не путать** — репо → mappa (этот ранбук, deploy) vs mappa → диск
@@ -115,8 +137,10 @@ updated: 2026-08-28
    Проект, пушащий изменения в каталог-репо, шлёт письмо в .admin. Сейчас: mappa (core),
    skills (methodology); сменится владелец каталога — сменится адресант.
 3. **Обновление core (immutable)** — ДОДЕЛАТЬ: core должны обновляться деплоем по
-   определённому пути. 403 = пробел сервера → follow-up на доработку /skills (требование
-   внесено в task:1461), не «ограничение + ручной шаг» как финал. Ранбук фиксирует
-   финальный механизм после 1461 (до этого — плейсхолдер DRAFT).
+   определённому пути. 403 = пробел сервера → доработка /skills (follow-up mappa
+   **task:1466/1467**, ready; дедуп проверить), не «ограничение + ручной шаг» как финал.
+   До деплоя доработки — **interim**: ручной шаг только с согласования оператора.
 
-**Статус:** ждём закрытия mappa **task:1461** → финализация ранбука + снятие blocked (task:1462).
+**Статус (2026-08-28):** task:1461 done → команды деплоя в ранбуке, task:1462
+финализирована; ранбук-апдейт финального core-механизма — после деплоя 1466/1467
+(штатный WRITE-апдейт).