skills/skills/using-wiki/SKILL.md

name, author, version, description

name	author	version	description
using-wiki	ours	2.1.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); оп-лог вести не нужно — сервис пишет его в таблицу logs автоматически (решение 12, ратификация 2026-08-24).

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 при первом ingest (см. ниже). Каталог — через entity_search (решение 1); index-страница опциональна (для ориентации).

Три операции

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 (каталог: одна строка на страницу) — опционально; каталог по умолчанию — entity_search (решение 1).
6. Отчитайся пользователю: что создано, что обновлено, какие противоречия.

Оп-лог — автоматический. Каждая write-операция уже пишется сервисом в таблицу logs (component=тип сущности, message=slug+operation; смотреть — mcp__mappa__admin_logs). Ручную log-страницу НЕ веди — это дубль, аудит-след живёт в сервисе (решение 12, ратификация 2026-08-24).

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

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

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

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

Оп-лог в query — автоматический (logs-таблица); строку вручную не дописывай.

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

Ищи:

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

Отчёт — панч-лист. Ничего не удаляй автоматически. Оп-лог в lint — автоматический (logs-таблица); строку вручную не дописывай.

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

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>.

Оп-лог — таблица logs, не страница

File-based log.md мёртв (решение 12/15, ратификация 2026-08-24). Сервис пишет оп-лог сам при каждой write-операции: mcp__mappa__admin_logs (фильтры level/since/component/entity, retention 14d). Ручную log-страницу не заводи, не дописывай, не парси.

index — каталог через поиск

Каталог = entity_search(q, type='wiki', project) (решение 1). index-страница — опциональная опора для ориентации: одна строка на страницу - [Title](concepts/foo.md) — hook., секции по типам. Обновляй только если страница уже существует; не плоди каталог-дубли.

Quick reference

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

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

• Правка sources/. Нельзя. Только статус-блок по явной просьбе.
• Дамп сырья в sources/. Резюме — это резюме. Ссылайся на raw, не копируй.
• Молчаливые перезаписи. Новый источник противоречит странице — пометь блоком > **Противоречие:**; не затирай.
• Нарративный оп-лог. Не веди его руками: сервис пишет logs сам (admin.logs). «Сегодня я добавил…» — даже вручную писать не надо.
• Не-ASCII слаги. Ломают grep и кросс-платформенность. Транслитерируй.
• Забытый index. Страницы без записи в каталоге невидимы для будущих query (если index-страница ведётся; дефолтный каталог — entity_search).
• Пропущенные противоречия в lint. Ценность вики — в вскрытых напряжениях, а не в ложном консенсусе.
• Запись без лиза. Wiki-мутации без claim_token → 422 busy; не пытайся писать «напрямую».
• Держать лиз на чтение/раздумья. Лиз — на время записи. Чтение — карв-аут.

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

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