admin/.mappa/share/runbooks/wiki.md

title: Runbook — wiki summary: Как работать с вики mappa: первый шаг (AGENTS/canon), чтение, ингест, обновление (version+409), summary-frontmatter, поиск страниц. Источник: brainstorm:173. type: runbook tags: [mappa, runbook, wiki, agent]

Runbook: wiki

Первый шаг любой операции

1. Прочитать канон-блок AGENTS.md проекта (+ AGENTS-сущность зоны: wiki_get(project, 'AGENTS')), затем каталог/index.
2. Скоупы: project (вики проекта), shared (общая тенанта), private (оператора, RLS). wiki_get без project = shared → project-страница = 404.

Чтение

• Страница: wiki_get(project?, slug) (компакт-excerpt по умолчанию; полное тело — full:true). Slug искать, не угадывать (Г3, К1–К4).
• Поиск: wiki_search(q, scope, project) / entity_search(q, type='wiki') — карточки {ref, slug, summary, snippet} без тел; полное тело — wiki_get/entity_get.
• Реляционные вопросы («что связывает X и Y», backlinks, сироты) — НЕ чтением, а graph_* (BFS сервером): graph_path/neighbors/backlinks/stats.

Запись

• wiki_create(project?, slug, body, scope?) — create (карв-аут). project-скоуп требует project; shared — scope='shared' без project. summary в frontmatter (одна строка) — карточки поиска читают её.
• wiki_update(project, id, body, version) — update ТОЛЬКО с версией (fresh из wiki_get); конфликт → 409 → re-GET → retry. Без версии — last-write-wins, риск затереть чужое.
• Противоречие источников — помечать блоком > **Contradiction:**, не затирать молча.
• Op-log ведёт сервис (admin_logs) — ручной log-страницы не вести.

Ингест

Прочитать источник → извлечь сущности/концепты → summaries/ (иммутабельно) → затронутые страницы create/update → отчёт. Один ингест может трогать 10–15 страниц — нормально. Сырой контент в summaries не дампить (только summary + raw_path).

Связано

runbooks/index · canon/gates (Г1/Г3/Г8) · runbooks/search · контракт wiki:2660 · concepts/wiki-ingest-convention (wiki:3312) · brainstorm:173