AGENTS.md git:20260824.3bb55e6A

Immutable. This exact content is served forever at /api/v1/blob/bc0a4f30e2d44585.

# Схема вики проекта «Ботинок» (schema)

Этот файл — **схема** вики согласно методике LLM Wiki (см. `llm-wiki.md` в корне репозитория). Он сообщает LLM-агенту, как устроена вики, какие конвенции соблюдать и как выполнять операции (Ingest / Query / Lint). Агент ведёт вики; человек читает её и правит вкус; этот файл коэволюционирует с вики.

## Три слоя

| Слой | Путь | Кто владеет | Назначение |
|------|------|-------------|------------|
| **Raw (исходники)** | `<repo>/` + манифест `wiki/raw/README.md` | Человек, **неизменяемо** | Код, README, CHANGELOG, config, install.sh — источник истины. Агент только читает. |
| **Wiki** | `wiki/` | LLM полностью | Сгенерированные markdown-страницы: обзор, сущности, концепции, сравнения, источники. |
| **Schema** | `AGENTS.md` (этот файл, корень репо) | Человек + LLM совместно | Правила структуры и воркфлоу. |

## Структура директории `wiki/`

```
wiki/
├── index.md           # каталог всех страниц (категории, ссылки, описание 1 строкой)
├── log.md             # хронологический, append-only журнал операций
├── overview.md        # синтез: точка входа, что это за проект, как он устроен
├── raw/               # манифест исходников (ссылки на неизменяемые файлы репозитория)
│   └── README.md
├── entities/          # страницы сущностей — конкретных компонентов/инструментов
│   ├── session_manager.md
│   ├── tool_manager.md
│   ├── botinok_cli.md
│   ├── textual_ui.md
│   ├── openai_compat.md
│   ├── session_directory.md
│   ├── config_system.md
│   ├── ollama_backend.md
│   └── tools/*.md     # по странице на каждый инструмент
├── concepts/          # страницы концепций — абстрактных механизмов/подходов
│   └── *.md
├── comparisons/       # сравнения (Rich vs Textual и т.п.)
│   └── *.md
└── sources/           # резюме источников (README, CHANGELOG, config, install, git)
    └── *.md
```

## Конвенции страницы

- **Имя файла**: kebab-case, отражает имя сущности/концепции (например `session_manager.md`).
- **Frontmatter** (YAML) для Dataview/поиска:
  ```yaml
  ---
  type: entity            # entity | concept | comparison | source | overview | glossary
  tags: [session, llm]
  updated: 2026-08-23
  sources: 2              # число исходников, затронувших страницу
  status: stable          # stable | draft | superseded
  ---
  ```
- **Перекрёстные ссылки**: связи оформляются markdown-ссылками либо в формате `[[page]]`; в index.md они записываются относительными путями.
- **Противоречия / устаревание**: если новый источник противоречит странице, НЕ затирать молча — пометить разделом «Противоречия» и заметкой `status: superseded`, ссылаясь на новый источник.

## Операции

### Ingest (добавление исходника)
1. Новая информация появляется либо из нового файла/фичи, либо из git-коммита.
2. Сначала **прочитай исходник** (код/коммит/документ). Не меняй его.
3. Пошли ключевые выводы человеку (кратко).
4. Обнови затронутые страницы сущностей/концепций по всему wiki.
5. Обнови `index.md` (каталог).
6. Добавь запись в `log.md` с префиксом `## [2026-08-23] ingest | <Что>`.

### Query (ответ на вопрос по вики)
1. Сначала читай `index.md`, чтобы найти релевантные страницы.
2. Читай найденные страницы и синтезируй ответ **с цитатами/ссылками** на страницы.
3. Если ответ — ценная находка (анализ, сравнение), её можно оформить как новую страницу в вики (compounding).

### Lint (health-check вики)
Периодически проверяй: противоречия между страницами, устаревшие утверждения, страницы-сироты без входящих ссылок, упомянутые, но не созданные концепции, отсутствующие перекрёстные ссылки. Для аудита перекрёстных ссылок запусти `grep -rn '\](' wiki --include='*.md'` и проверь, что каждый целевой файл существует. Результаты логируй в `log.md` с тегом `lint`.

## Схема тегов (tags)
- `session` — сессии, контекст, память
- `llm` — механизмы LLM (function calling, streaming)
- `tool` — конкретные инструменты
- `tui` — интерфейсы (Rich, Textual)
- `safety` — dangerous mode, ограничения
- `integration` — бэкенды (Ollama, OpenAI-compat)
- `config` — конфигурация
- `learn` — experience/skills (обучение)

## Проектные факты (справочно, для согласованности)
- Язык проекта: Python 3, интерфейс консольный (Rich + Textual TUI), бэкенд — [Ollama](wiki/entities/ollama_backend.md) (по умолчанию) и OpenAI-совместимые API (`wiki/entities/openai_compat.md`).
- Основная точка входа: `botinok.py` (`wiki/entities/botinok_cli.md`).
- Оркестрация инструментов: `core/tool_manager.py`; сессий: `core/session_manager.py`.
- Версия: 0.3; репозиторий: `github.com/siv237/botinok`.

## История изменений схемы
- **2026-08-23** — создана схема и базовая структура вики.