# Документация Abulafia

Этот файл является точкой входа в документацию проекта. Abulafia состоит из
CLI-обёртки, интерактивного Pi runtime, workflow-промптов, skills, агентов,
подключаемых пакетов и системы устойчивых артефактов на диске.

## С чего начать

| Задача | Документ |
| --- | --- |
| Установить и впервые запустить Abulafia | [INSTALL_AND_RUN.md](INSTALL_AND_RUN.md) |
| Пользоваться консолью, workflows и stories | [USER_MANUAL.md](USER_MANUAL.md) |
| Узнать, что делает каждый skill и агент | [SKILLS_REFERENCE.md](SKILLS_REFERENCE.md) |
| Понять внутреннюю архитектуру и потоки данных | [ARCHITECTURE.md](ARCHITECTURE.md) |
| Добавить новый skill, workflow, agent или story | [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) |
| Посмотреть общую презентацию проекта | [README.md](README.md) |
| Узнать правила работы с репозиторием | [CONTRIBUTING.md](CONTRIBUTING.md) |

## Краткий словарь

| Термин | Значение |
| --- | --- |
| **Skill** | Markdown-контракт в `skills/<name>/SKILL.md`: когда применять способность, какие правила соблюдать и какой результат создать. |
| **Workflow** | Исполняемый prompt-template в `prompts/<name>.md`. В интерактивной консоли становится slash-командой, например `/deepresearch`. |
| **Agent** | Специализированная роль в `.abulafia/agents/*.md` с описанием задачи, инструментов, уровня reasoning и выходного файла. |
| **Story** | Отдельный продуктовый сценарий A01-A10 или S01-S11 со своим agent-контрактом, skill-контрактом и обязательным артефактом. |
| **Tool** | Конкретная вызываемая функция runtime: чтение файла, web search, запуск процесса, делегирование и т. п. |
| **Package** | Устанавливаемое расширение Pi, которое добавляет tools, commands или runtime-возможности. |
| **Artifact** | Сохранённый результат работы: отчёт, матрица, план, state-файл, provenance или журнал решений. |

## Что использовать в типовых случаях

| Ситуация | Рекомендуемый путь |
| --- | --- |
| Нужен глубокий обзор темы | `/deepresearch <тема>` |
| Нужен обзор научной литературы | `/lit <тема>` |
| Нужно проверить статью перед подачей | `/review <путь>` |
| Нужно сравнить несколько источников | `/compare <источники и критерии>` |
| Нужно подобрать журналы для статьи | `/story S01 <статья> <ограничения>` |
| Известен конкретный журнал | `/story S02 <статья> <журнал>` |
| Получен отказ или R&R | `/story S08 <статья> <письма рецензентов>` |
| Нужно проверить финальный submission package | `/story S10 <рукопись> <журнал>` |
| Нужна локальная демонстрация без API-запроса | `/story-local S01 <статья> <задача>` |
| Нужно оценить готовые story-артефакты | `/evaluate-stories all <каталог>` |

## Источники истины

Документация описывает текущую реализацию. При расхождении ориентируйтесь на:

1. `src/cli.ts` для поведения CLI.
2. `src/pi/runtime.ts` и `src/pi/launch.ts` для запуска Pi.
3. `prompts/*.md` для workflow-команд.
4. `skills/*/SKILL.md` для skill-контрактов.
5. `.abulafia/agents/*.md` для agent-контрактов.
6. `src/workflows/story-runner.ts` для локального story runner и evaluator.
7. `knowledge/journals/` для локальной базы Journal-Yuga.