skills/skills/using-wiki/SKILL.md

name, author, version, description

name	author	version	description
using-wiki	ours	2.0.0	Policy skill for working with the project wiki in Mappa (Karpathy LLM Wiki pattern, channel = mappa-сущности, решения 14/15 спеки mappa). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says «use project wiki», «обнови вики», «проверь вики», «запроси вики», «заингесть», «query the wiki». Also use when modifying any wiki page — the workflow and formats below are mandatory, and project-specific conventions live in the `CLAUDE` wiki-сущности проекта. Wiki = сущности `type=wiki` в сервисе (чтение — карв-аут лиза; запись — под лизом проекта, решение 19). Файлового `.wiki/` больше нет; `setup-wiki` умер (нечего настраивать).

using-wiki

Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) whose pages live in Mappa as type=wiki сущности (решение 14/15), not in files. Knowledge is compiled once and kept current: three named operations (ingest / query / lint), strict page formats that keep the wiki parseable and grep-friendly, and a cross-linked graph (refs → рёбра, решение 4).

Prerequisites

Wiki проекта = сущности в сервисе Mappa (HTTP-ядро, MCP-адаптер mcp__mappa__*). Слаг страницы = путь от корня вики без расширения (index, log, CLAUDE, concepts/foo, entities/bar, packages/baz, sources/doc, overview). Body = frontmatter + markdown как есть (content-модель сохраняется, решение 2).

Проектная вики (scope=project) читается/пишется с параметром проекта; общая вики (scope=shared) — без проекта. Чей именно вики трогаем, определяет контекст: wiki.get(project, slug) — проектная, wiki.get(slug) — shared.

Файловый .wiki/ в репозиториях — легаси: источник истины — сервис. Если вики проекта пуста (нет сущностей) — ничего настраивать не надо (setup-wiki умер): первый ingest сам создаёт CLAUDE, index, log (см. Ingest).

MCP-поверхность

Операция	Тул	Примечание
Чтение страницы	mcp__mappa__wiki_get(project?, slug)	чтение — карв-аут лиза (решение 19)
Поиск страниц	mcp__mappa__entity_search(q, type='wiki', project?, scope?, limit)	ILIKE по body/title
Захват лиза для записи	mcp__mappa__task_claim_next(project, owner)	→ token (лиз проекта, решение 19); таска может отсутствовать
Продление лиза	mcp__mappa__task_heartbeat(project, claim_token)	долгие ingest-циклы
Создать страницу	mcp__mappa__wiki_create(project, slug, body, claim_token)	под лизом
Обновить страницу	mcp__mappa__wiki_update(project, id, title?, body?, claim_token)	под лизом; id — internal (см. ниже)

Запись всегда под лизом. Мутации wiki гейтятся лизом проекта: без валидного claim_token — 422 busy. Лиз экспирится по TTL (дефолт 600s); закрыть вручную нечем (кроме admin_release_lease для залипших) — пиши, затем отпусти (не держи лиз на время чтения/размышлений).

Рефы и id (#1037). Публичная поверхность несёт per-type реф первым полем: ref: "w:3" (тип+номер, решение 20), num следом, глобальный id — internal (последним полем). Для wiki.update нужен internal id — бери его из ответа wiki_get/entity_search. В тексте страниц ссылайся викилинками по слагу ([[concepts/foo]], решение 4) или per-type рефами ([[i:N]]/[[t:N]]).

Три слоя (не смешивать)

1. Raw-источники — sources/<slug> страницы. Иммутабельны: читай, не редактируй (единственное исключение — блок-цитата > Status по явной просьбе пользователя).
2. Вики — все остальные страницы (entities/concepts/packages/…).
3. Схема — сущность CLAUDE (slug CLAUDE). Конвенции проекта. Читай её первой; она перекрывает этот скил при конфликте.

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

1. mcp__mappa__wiki_get(project, 'CLAUDE') — если есть, читай (схема).
2. mcp__mappa__wiki_get(project, 'index') — каталог, найди нужные страницы.
3. Только потом действуй.

Если CLAUDE нет — вики либо новая, либо неухоженная: не импровизируй структуру, создай CLAUDE/index/log при первом ingest (см. ниже).

Три операции

Ingest — «заингесть X»

1. Прочитай источник полностью.
2. Извлеки: entities, concepts, packages, кросс-резы.
3. Создай sources/<slug> — одну страницу-резюме на источник (~50–150 строк; ссылку на raw клади в frontmatter raw_path + ingested:).
4. Для каждой затронутой страницы:
   • есть → обнови (wiki_update(project, id, body, claim_token)). Противоречия помечай явно блоком > **Противоречие:** источник A говорит X, источник B — Y. Не затирай молча.
   • нет → создай (wiki_create).
5. Обнови index (каталог: одна строка на страницу).
6. Допиши одну строку в log (формат ниже).
7. Отчитайся пользователю: что создано, что обновлено, какие противоречия.

Один ingest может затронуть 10–15 страниц. Это нормально — для того LLM и нужны.

Порядок записи: сначала лиз (task_claim_next), затем все wiki-мутации одним циклом (не бери лиз на чтение), затем отпусти (лиз живёт TTL — просто закончи писать; heartbeat только если цикл реально долгий).

Query — вопрос по вики

1. Читай index сначала, затем углубляйся в страницы (wiki_get по слагу).
2. Отвечай с цитатами-викилинками: [[concepts/foo]] (рёбра создаются при записи, решение 4).
3. Компаундируй вики. Если ответ — реальный синтез (сравнение, анализ, новая связь) — спроси пользователя: «Сохранить как страницу wiki?» Хорошие вопросы становятся страницами в concepts/.
4. Допиши строку в log.

Lint — «проверь вики»

Ищи:

• Противоречия между страницами.
• Сирот — страницы без входящих ссылок: mcp__mappa__graph_backlinks(id) (id из wiki_get) → нет входящих рёбер = сирота (подробнее — using-wiki-graph).
• Stale-claims — updated_at страницы старше источника, который она резюмирует.
• Потерянные сущности — понятия из текста без своей страницы (entity_search по имени → пусто).
• Пустые/TODO-секции.

Отчёт — панч-лист. Ничего не удаляй автоматически. Допиши строку в log с итогом.

Форматы страниц (ОБЯЗАТЕЛЬНО)

Frontmatter

---
title: Человекочитаемое имя
type: entity | concept | package | source | contradiction | open-question | overview
tags: [short, tokens]
sources: [concepts/mappa.md]
updated: 2026-08-24
---

Страницы sources/ дополнительно несут ingested: YYYY-MM-DD и raw_path: …. contradictions/ — status: open | resolved | accepted-divergence и affects:. open-questions/ — status: open | answered | obsolete и touches:.

Слаги

• kebab-case, только латиница. Кириллицу/др. скрипты транслитерируй (план переписывания → ozon-client-rewrite). Оригинальный title — в H1 и frontmatter.
• entities/<name>, concepts/<name>, packages/<name>, sources/<slug>, contradictions/<slug>, open-questions/<slug>.

log — append-only, grep-parseable

Каждая запись обязана начинаться с:

## [YYYY-MM-DD] <operation> | <short description>

Операции: ingest, query, lint, refactor, decision, init. Парсится: entity_search(q="## [", type="wiki", project=…) по сущности log.

index

Каталог, не нарратив. Одна строка на страницу: - [Title](concepts/foo.md) — hook. Секции по типам. Обновляется на каждом ingest.

Quick reference

Ситуация	Что трогаем
Ingest одного документа	sources/<slug> (новая) + 3–15 entities/concepts/packages + index + log
Query	(чтение) + возможно новая страница + log
Lint	(чтение) + log
Новая вики проекта	первый ingest создаёт CLAUDE/index/log + контент

Частые ошибки

• Правка sources/. Нельзя. Только статус-блок по явной просьбе.
• Дамп сырья в sources/. Резюме — это резюме. Ссылайся на raw, не копируй.
• Молчаливые перезаписи. Новый источник противоречит странице — пометь блоком > **Противоречие:**; не затирай.
• Нарративный log. «Сегодня я добавил…» — неверно. Формат: ## [YYYY-MM-DD] ingest | <что>.
• Не-ASCII слаги. Ломают grep и кросс-платформенность. Транслитерируй.
• Забытый index. Страницы без записи в каталоге невидимы для будущих query.
• Пропущенные противоречия в lint. Ценность вики — в вскрытых напряжениях, а не в ложном консенсусе.
• Запись без лиза. Wiki-мутации без claim_token → 422 busy; не пытайся писать «напрямую».
• Держать лиз на чтение/раздумья. Лиз — на время записи. Чтение — карв-аут.

Когда НЕ использовать этот скил

• Проект без вики в mappa (нет сущностей type=wiki) — обычная документация, не LLM Wiki.
• Пользователь хочет однофайловый README/ADR — скил для персистентной связной базы знаний.
• Разовые вопросы по коду — обычное чтение файлов, не вики-воркфлоу.
• Реляционные/структурные вопросы о вики (связи, сироты, пути) — это using-wiki-graph (mcp__mappa__graph_*).