---
name: add-academic-references-to-markdown
description: Add academic citation markers [1], [2], ... to a markdown document and build a full references section at the end. Scans the document for scientific/philosophical concepts, matches them to real academic papers, inserts numbered citation markers in the text, and appends a formatted reference list.
---

# Добавление академических references в markdown-документ

Когда пользователь просит добавить академические ссылки (как в книгах — звёздочка/номерок) в markdown-документ, используй этот workflow.

## Workflow

### 1. Прочитай документ целиком

Прочитай весь файл, чтобы увидеть все научные/философские концепции:

```python
with open(path, "r", encoding="utf-8") as f:
    content = f.read()
lines = content.split("\n")
```

### 2. Составь список references

Определи, какие концепции упоминаются. Для каждой найди реальную работу:
- Автор(ы), название, журнал/издательство, год, DOI (если есть)
- Используй web_search для верификации, если не уверен

Формат записи:
```
[1] Author A.B. Title // Journal. Year. Vol. X, No. Y. P. Z–W.
[2] Author C.D. Book Title. Publisher, Year.
```

### 3. Сделай резервную копию

```bash
cp document.md document_backup.md
```

### 4. Программная вставка маркеров

Используй `execute_code` с `str.replace()` для вставки `[N]` после первого упоминания каждой концепции.

**Критическое правило:** вставляй маркеры **после** закрывающей скобки markdown-ссылок. Если строка содержит `[...](...)`, маркер должен быть за пределами `]`:

```
Правильно: [Запрос №5: Парадокс Больцмановского мозга](#link) [1]
Неправильно: [Запрос №5: Парадокс Больцмановского мозга [1]](#link)
```

Паттерн замены:
```python
replacements = [
    ("текст с концепцией", "текст с концепцией [N]"),
    ...
]
for old, new in replacements:
    if old in content:
        content = content.replace(old, new, 1)
```

### 5. Сборка references-блока

Сформируй markdown-блок:

```markdown
## N. Список научных references

[1] Author. Title // Journal. Year. Vol. — описание.
[2] ...
```

Сгруппируй по категориям (Физика, Нейробиология, Философия и т.д.).

### 6. Вставка в документ

Найди подходящее место — обычно перед заключительным колофоном или перед "Продолжение:":

```python
pos = content.rfind("Ключевое слово")
before = content[:pos]
after = content[pos:]
content = before + refs_block + "\n" + after
```

### 7. Верификация

Проверь выборочно несколько мест с маркерами, чтобы убедиться, что:
- Маркеры не сломали markdown-ссылки `[...](...)`
- Маркеры не попали внутрь URL
- References-блок отформатирован корректно

Используй `read_file` для проверки ключевых строк.

## Pitfalls

1. **Маркеры внутри URL** — самое частое повреждение. Если строка содержит `[текст](url)`, маркер `[N]` должен быть за `](url)`, а не внутри.
2. **Маркеры в оглавлении (ToC)** — особая разновидность URL-проблемы. Markdown-оглавление: `[Текст](#якорь)`. Маркер должен быть ПОСЛЕ закрывающей скобки ссылки, иначе ломается якорь:

   ```
   ✅ [Запрос №5: Парадокс Больцмановского мозга](#link) [1]
   ❌ [Запрос №5: Парадокс Больцмановского мозга [1]](#link)
   ```

3. **Маркеры в таблицах** — не должны ломать pipe-разделители `|`. Если замена попадает в ячейку таблицы, убедись что маркер внутри ячейки, а не за pipe:

   ```
   ✅ | Текст концепции [N] | Другая ячейка |
   ❌ | Текст концепции | [N] Другая ячейка |
   ```

4. **Дублирующиеся замены** — используй `replace(old, new, 1)` (счётчик=1) чтобы заменить только первое вхождение.
5. **Не спамить маркерами** — достаточно одного маркера per концепция per раздел (или вообще одного на весь документ при первом значимом упоминании). Не нужно ставить на каждое повторение.
6. **Реальные работы** — не выдумывай статьи. Используй только реально существующие публикации с правильными авторами, журналами и годами. Если не уверен — проверь через web_search.
7. **Regex-поиск слишком широк** — не используй regex для поиска русских слов, если паттерн может совпасть как часть другого слова. Например, поиск `РАС` найдёт все слова, содержащие «рас» (расстояние, рассказ, растрата). Используй **точное строковое совпадение** (`in` / `str.replace`), а не `re.search(r"РАС", ...)`. Для английских терминов regex безопаснее, но всё равно проверяй.
8. **Двухфазный подход** — сначала просканируй весь документ и составь список всех научных отсылок. Затем **вручную** отбери 20-30 ключевых мест для вставки маркеров. Не пытайся автоматически найти все вхождения — это приведёт к переспаму и поломанным ссылкам. Лучшие результаты даёт ручная курация замен списком:

   ```python
   replacements = [
       ("точная строка в тексте", "точная строка с [N] маркером"),
       ...
   ]
   for old, new in replacements:
       if old in content:
           content = content.replace(old, new, 1)
   ```

9. **Мульти-частная книга** — если документ собран из нескольких частей (например, ФЕНИКС-1 = Часть 1 + Часть 2 + ... + Манифест), одна концепция может упоминаться в нескольких частях. Добавляй маркеры в **каждой части при первом упоминании** — читатель не должен перелистывать всю книгу чтобы найти ссылку. Но не спамь: одного маркера на часть достаточно.

10. **Единый references-раздел** — если в объединённом документе есть несколько секций references (из исходных файлов), удали старые и замени одним сводным разделом в конце книги. Используй `content.rfind("## N. Список научных references")` для поиска последнего references-блока и замены.

11. **iCloud-синхронизация** — на macOS файлы на рабочем столе могут исчезнуть из-за iCloud sync. Если `read_file` говорит «File not found», проверь:
    - `/Users/valen/.Trash/Рабочий стол/`
    - `/Users/valen/iCloud Drive (архив)/Desktop/`
    - `/Users/valen/Downloads/Рабочий стол/`
    Ищи через `find /Users/valen -name "имя_файла*" -type f 2>/dev/null`.

12. **MD → HTML конвертация** — после всех правок сгенерируй HTML-версию для мобильного чтения:
    ```bash
    pip install markdown  # если ещё не установлен
    python3 -c "
    import markdown
    with open('book.md','r') as f: md=f.read()
    html=markdown.markdown(md,extensions=['tables','fenced_code','codehilite','toc','nl2br'])
    # обернуть в <!DOCTYPE html> с адаптивным CSS (clamp(), @media ≤600px, ≤380px)
    "
    ```
    Используй `clamp()` для fluid-типографики, `-webkit-overflow-scrolling: touch` для скролла таблиц на iOS. Отправляй HTML через `MEDIA:path` для скачивания на телефон.

## Пример

Было:
```
...феномен квантовой запутанности — частицы...
```

Стало:
```
...феномен квантовой запутанности [4] — частицы...
```

И в конце документа:
```
## 13. Список научных references

[4] Aspect A., Grangier P., Roger G. Experimental realization... // Phys. Rev. Lett. 1982. Vol. 49, No. 2. P. 91–94.
```
