admin/.agents/skills/admin-runbooks/SKILL.md

name, author, version, description

name	author	version	description
admin-runbooks	ours	1.0.0	Единый контур ранбуков зоны админа (.admin): НАЙТИ нужный ранбук перед любой прод-операцией → ИСПОЛНИТЬ по нему (чек-лист + verify + откат + письмо/таска) → ВЕСТИ (обновлять после инцидентов/изменений) и СОЗДАВАТЬ новые. Поглощает writing-runbooks (v1.0.0, superseded) — секция WRITE это его канон. Trigger (user): деплой/редеплой/рестарт/ротация/миграция любого сайта или стека; «по ранбуку», «как деплоить X», «напиши/обнови ранбук», «есть ли ранбук по X»; любой прод-инцидент на сайте, который может потребовать операции.

admin-runbooks

Один контур: индекс → USE → EXECUTE → WRITE/UPDATE. Цель — устранить «рыскание» (поиск рецепта по сессиям/чатам/grep), когда ранбук есть или должен быть.

⚠️ СЛУЖЕБНАЯ зона .admin. Ранбуки — служебные документы .admin: применять/выполнять может только .admin; другие проекты читают по запросу, не выполняют; наружу не выносить. Прод-операция по ранбуку = таска на борде .admin + письмо от заказчика (исполнитель-не-админ не деплоит сам).

0. ИНДЕКС РАНБУКОВ (всегда первый шаг)

Индекс: .admin/.wiki/concepts/runbooks-index.md (единственный источник «какой ранбук для чего»). Прибит в AGENTS.md — контур обязателен.

Перед ЛЮБОЙ прод-операцией (деплой/редеплой/рестарт/ротация/миграция/инцидент):

1. Прочитай индекс (read .admin/.wiki/concepts/runbooks-index.md) — найди строку по проекту/операции → путь ранбука.
2. Ранбук может жить в трёх местах (индекс указывает, где):
   • .admin/.wiki/concepts/*-runbook*.md — канон для VDS-проектов;
   • <репо-проекта>/.wiki/concepts/docker-deploy.md и т.п. — репо-вики проекта (pilorama98.ru: apps/web/.wiki/concepts/docker-deploy.md);
   • mappa wiki (wiki_search) — если индекса ещё нет, искать там.
3. Нет ранбука → НЕ деплоить молча. Создать (см. WRITE) до/вместе с операцией: отдельной таской или в теле операционной таски (пункт «нужен ранбук»). Это не бюрократия: отсутствие ранбука = повторное рыскание в следующий раз.

1. USE — найти и прочитать ранбук

• Сначала индекс → ранбук. Не начинать grep по сессиям/чатам — это анти-паттерн (источник этой секции: инцидент 2026-08-26 pilonuxt — рыскал, ранбука не было).
• Прочитать ранбук целиком перед операцией (секреты — плейсхолдеры, реальные значения — из pass по указателям; ранбук сам секретов не несёт).
• Сверить актуальность: теги/версии на проде могут обогнать ранбук (пример: stostayer-web ранбук показывал 0.3.23, прод был 0.3.26 → тег брать с проде, а ранбук потом обновить — WRITE). Если расхождение → пометить на апдейт.

2. EXECUTE — деплой/операция по ранбуку

Выполнять шаги ранбука как чек-лист, не пропуская:

1. Предусловия (auth: JWT/токены из pass; docker login; pull-ДО-рестарта; .dockerignore/.yarnrc временные модификации — пометить на возврат).
2. Шаги операции — дословно по ранбуку, порядок важен (gotchas в ранбуке).
3. Verify по секции ранбука (страницы/эндпоинты/логи/uptime) — зелёный перед закрытием. При красном — rollback-путь из ранбука, не импровизация.
4. Фиксация результата:
   • sync source-of-truth compose (если менялся тег) → commit + push;
   • письмо-отчёт заказчику (inbox_send, from .admin, с verify-таблицей);
   • закрыть операционную таску (reason = что сделано + verify);
   • при необходимости — обновить ранбук (WRITE): новый тег, новые gotchas.

Ограничения: одна попытка там, где ранбук велит одну (egress-баны, retry-штормы); не отклоняться от ранбука без причины — отклонение фиксировать в письме.

3. WRITE / UPDATE — создание и ведение ранбуков

Канон (наследие writing-runbooks v1.0.0, поглощено):

Жёсткие правила

1. Ранбук — служебный документ .admin. Применять может только .admin.
2. Из проекта не выносить. Не копировать в другие вики, не публиковать.
3. Деплой = таска + письмо админу. Любая прод-операция — по задаче на борде .admin и письму. Исполнитель-не-админ ставит задачу, не деплоит сам.
4. Служебный блок — в первых абзацах (машиночитаемый маркер служебности):

> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.**
> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять.
> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать.
> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют.

Дословно, без перефразирования.

Гигиена секретов (решение 5, write-тайм сканер mappa)

В ранбуках никогда не бывает реальных секретов. Только плейсхолдеры + указатели на pass: <из pass <path>/<FIELD>>. Сканер блокирует запись (422) на password/token/api_key/secret+значение ≥6 симв., AKIA…, JWT, ssh-ключи. Обход плейсхолдером: значение <6 симв. ('<...>'), либо ключ-слово не латиницей, либо разрыв : коротким словом (PASSWORD: см. pass (…)). После записи — проверить admin_secret_scan (0 хитов).

Структура ранбука

1. Frontmatter: title, type: concept, tags: [.., runbook], related, updated.
2. H1 + служебный блок (обязательно, дословно).
3. Scope (VDS, стек Portainer Id, endpointId, source-of-truth compose).
4. Артефакты (код/образ/стек/БД/эндпоинт; тег = как на проде).
5. Шаги операции (копируемые команды) + таблица «рестарт vs пересборка» если уместно.
6. Verify/smoke после операции.
7. Rollback-путь всегда.
8. Gotchas из практики (нумерованные, с датой).

Ведение (UPDATE)

Обновлять ранбук когда:

• прод ушёл вперёд (новый тег/версия) — поправить инвентарь/таблицы;
• появилась новая gotcha (инцидент с неочевидной причиной);
• изменился канал деплоя (адреса/стек/порядок). После правки: bump updated:, синхронизировать с индексом (что покрывает), проверить secret_scan. Коммит отдельный от операционного («docs(runbook): …»).

Порядок записи (мутации вики)

• Файл ранбука живёт в .admin/.wiki/concepts/ (репо .admin, git). Писать файл → commit → push (проектная дисциплина: push свободно). mappa-импорт подхватит при следующем импорте (индекс/ранбуки доступны и через wiki_search после импорта).
• Секрет-сканер: mcp__mappa__admin_secret_scan после записи — 0 hits.

Место жительства этого скила

Скил лежит в .admin/.agents/skills/admin-runbooks/SKILL.md — проектные скилы .admin (pi: .agents/skills/ в cwd). НЕ дублировать в ~/.agents/skills/ (глобальная установка, перезаписывается update-skills) и НЕ в общий skills-репо. Обновление — правкой файла в проекте + commit/push (.admin).

Связи

• concepts/runbooks-index.md — индекс ранбуков (обязательный первый шаг).
• writing-skills — RED-GREEN-REFACTOR для скилов (если править сам скил).
• using-vds-ops — диагностика контейнеров (read-only), не деплой.
• project-discipline — семвер/пуш-правила при правке версионируемых артефактов.