Salute Speech TTS Generation

Overview

Generate natural-sounding Russian narration audio for scientific trail POIs using Sber Salute Speech API with SSML markup for pauses, emphasis, and prosody control.

Engine Selection (auto)

Before generating audio, the build script checks Salute Speech credentials:

1. Salute Speech available (SALUTE_AUTH_DATA in env → token request succeeds): use Salute Speech API (Bys_24000 voice, best quality, SSML support)
2. Salute Speech unavailable (no creds or auth fails): fallback to Microsoft Edge TTS (edge-tts CLI, voice ru-RU-DmitryNeural, free, no API key)

The script prints which engine is active at startup. Both engines produce MP3 output.

Quick Reference

Available Voices

Authentication

Token lives 30 min. Always get fresh before batch.

import requests, uuid, os

AUTH_DATA = os.environ.get('SALUTE_AUTH_DATA')  # from /root/config/.env
resp = requests.post(
    'https://ngw.devices.sberbank.ru:9443/api/v2/oauth',
    headers={
        'Authorization': f'Basic {AUTH_DATA}',
        'RqUID': str(uuid.uuid4()),
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data='scope=SALUTE_SPEECH_PERS',
    verify=False, timeout=10
)
token = resp.json()['access_token']

Synthesis

resp = requests.post(
    'https://smartspeech.sber.ru/rest/v1/text:synthesize',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/ssml'  # or 'application/text' for plain
    },
    params={'voice': 'Bys_24000'},
    data=ssml_text.encode('utf-8'),
    verify=False, timeout=20
)
# resp.content = WAV audio bytes

SSML Best Practices for Scientific Narration

Structure

Always wrap in <speak> root tag:

<speak>
First paragraph text.
<break time="400ms"/>
Second paragraph text.
</speak>

Pauses

Emphasis

Asterisk directly before word (no space):

<speak>Ошибка в *одну миллионную долю секунды</speak>

Stress Marks (Russian) — CRITICAL

TTS часто ошибается в ударениях научных и редких слов. Апостроф после ударной гласной:

<speak>Закон Фараде'я. Ковариа'нция. Трилатера'ция.</speak>

Обязательно проверять и размечать:

Правило: перед генерацией прослушать тестовый фрагмент с каждым непростым словом. Если ударение неправильное — добавить апостроф. Лучше поставить лишний апостроф, чем пропустить ошибку.

Prosody Control

<paint pitch="4" speed="3" loudness="4">важная фраза</paint>

Attributes: pitch (1-5), speed (1-5), loudness (1-5).

Emotions

<voice mode="happy">радостная фраза</voice>

Modes: sad, annoyed, happy, whisper.

Numbers and Formulas — Always as Words

Special Content

<say-as interpret-as="cardinal">42</say-as>
<say-as interpret-as="date" detail="d.m.y">25.01.2000</say-as>
<sub alias="мартэновских">мартеновских</sub>

Narration Writing Rules (Gasnikov Style)

Cardinal Rule: Eyes-Free

All narrations MUST be fully comprehensible without looking at a screen, card, or stend. The listener is walking, looking around, not reading. This means: - Formulas are spoken as words: $\rho g h$ → "ро жэ аш", $T_{60} \approx 1.6$ → "тэ шестьдесят — примерно одна и шесть" - Visual references ("посмотри на график", "как показано на схеме") are FORBIDDEN - Spatial references are OK if they point to the physical world: "посмотри на деревья вокруг", "хлопни в ладоши здесь" - Structure conveyed by voice: pauses between sections, prosody changes for key points - Each level is a self-contained audio experience, not a supplement to a card

Three Levels of Audio

Style Rules

1. Start with local binding: "Посмотри на...", "Ты только что..."
2. One baffling opener per POI
3. Numbers as words, formulas as speech
4. Short sentences for audio (max 25 words)
5. Pause after questions and before key reveals
6. End with bridge to next concept
7. L2: formula explained step by step BEFORE stating it — "расстояние равно скорости, умноженной на время задержки... записывается как ро равно цэ умножить на дельта тэ"
8. L3: each micro-story has its own intro pause (500ms) and slightly different energy

Pipeline: Anti-AI → SSML → TTS

Audio production is a TWO-SKILL pipeline. Skipping the first skill produces robotic, AI-sounding narrations.

Step 1: Anti-AI Check (MANDATORY before TTS)

Before converting any text to SSML, run it through the anti-ai-text skill (/root/tropa/skills/anti-ai-text/SKILL.md). This catches: - Канцелярит: "является", "представляет собой", "обеспечивает" - AI patterns: "важно отметить", "в рамках данного", "таким образом" - Faux-academic filler: "демонстрирует", "содействует", "подчёркивает" - Structural tells: rule-of-three adjectives, trailing participles

Process: Take the l1/l2/l3 text from YAML → scan with anti-ai-text rules → rewrite flagged phrases → THEN convert to SSML.

A narration that passes TTS but fails anti-ai is worse than no narration — the listener will hear "AI voice reading AI text" and tune out.

Step 2: SSML Conversion

Convert cleaned text to SSML with stress marks, breaks, emphasis, numbers-as-words per rules above.

Step 3: TTS Generation

See build_audio.py in this directory for the complete pipeline script.

Validation Checklist

Before committing audio: - [ ] Source text passed anti-ai scan (0 flags) - [ ] All formulas spoken as words (no symbols read as-is) - [ ] All scientific terms have stress marks - [ ] Narration makes sense without looking at screen - [ ] Duration within level range (L1: 40-90s, L2: 90-180s, L3: 180-300s)

Usage:

cd /root/tropa
python skills/salute-tts/build_audio.py                    # all POIs
python skills/salute-tts/build_audio.py --poi 01 05        # specific POIs
python skills/salute-tts/build_audio.py --voice Nec_24000  # different voice

Common Mistakes

Anti-AI Text Skill (EN + RU)

A detection-and-rewrite skill grounded in: - English: Wikipedia:Signs of AI writing - Russian: Википедия:Признаки сгенерированности текста - Practical rules from the crimeacs/ai-tells-validator skill and Russian humanizer research

Workflow: Detect → Flag → Rewrite

Step 1: DETECT — scan for markers

Read the text and check against all categories below. Count violations.

Step 2: FLAG — report findings

For each violation, output:

[CATEGORY] "offending quote" → explanation

Step 3: REWRITE — eliminate tells

Apply rewrite rules (Section III) to produce clean text that: - Preserves meaning and factual content - Sounds like a competent human author - Passes re-scan with zero flags

I. English AI Tells

A. Banned Words

B. Banned Phrases

• "I hope this email finds you well"
• "circling back" / "touching base" / "just checking in"
• "in conclusion" / "in summary" / "to summarize"
• "it is important to note" / "it's worth noting"
• "in today's fast-paced / rapidly evolving / digital age"
• "plays a vital/crucial/pivotal/key role"
• "navigate the complexities"
• "in the realm of" / "in the world of" / "when it comes to"
• "at its core" / "at its heart"
• "a powerful tool" / "best-in-class" / "world-class"
• "value proposition" / "thought leadership"
• "looking forward to hearing from you"
• "hope this helps"
• "let me know your thoughts"
• "a deep dive" / "a treasure trove" / "a wealth of"

C. Structural Patterns

D. Punctuation & Formatting

• Em-dash overuse: more than 1 per paragraph = flag. Em-dash is the #1 punctuation tell in 2026.
• Smart/curly quotes: ""'' instead of straight quotes
• Thematic breaks: --- inside body text
• Excessive bold: bolding every key term
• Emoji as structure: emoji bullets or separators in professional text

II. Russian AI Tells (Признаки ИИ-текста)

A. Слова-маркеры (Banned Words)

B. Фразы-маркеры (Banned Phrases)

Канцелярит и наукообразие: - "В рамках" (данного исследования/проекта/статьи) - "Важно отметить" / "Стоит отметить" / "Стоит подчеркнуть" - "Необходимо учитывать" - "На основании вышеизложенного" - "В контексте" (чего-либо) - "Таким образом" (как вводное к выводу) - "В заключение следует отметить" - "Представляет собой" - "Играет важную/ключевую/значительную роль" - "Оказывает влияние на" - "Носит характер"

Рекламный язык: - "Может похвастаться" - "Расположенный в самом сердце" - "Потрясающая природная красота" - "Вековое наследие" - "Богатый, яркий, разнообразный" - "Уникальный" (без обоснования)

Ложная глубина: - "Это не просто X, это Y" - "Не только... но и..." - "Неизгладимый след" - "Поворотный момент" - "Служит напоминанием" - "Свидетельство мастерства/эпохи"

Диалоговые артефакты: - "Конечно!" / "Безусловно!" - "Я надеюсь, это помогло" - "Если хотите узнать больше, дайте знать" - "Сообщите мне" - "Давайте рассмотрим"

Ложные кальки с английского: - "В конце дня" (at the end of the day) - "Давайте нырнём" (let's dive in) - "За пределами коробки" (outside the box) - "На одной странице" (on the same page)

C. Структурные паттерны

D. Пунктуация и оформление

• Тире вместо запятых: плотность > 5 на 1000 символов = флаг (норма для человека ~2-3)
• Списки вместо текста: если >40% текста — маркированные списки
• Жирный шрифт россыпью: выделение каждого термина жирным
• Эмодзи как структура: 🚀 📌 ✅ как маркеры списков в серьёзном тексте
• Markdown-артефакты: ##, **, --- в тексте не предназначенном для рендеринга
• Заголовки С Большой Буквы Каждого Слова: калька с Title Case

III. Правила перезаписи (Rewrite Rules)

Универсальные (EN + RU)

1. Убить em-dash: заменить на запятую, точку с запятой, двоеточие, или перестроить предложение
2. Разбить Rule of Three: оставить 2 элемента или переформулировать
3. Убить trailing participle: сделать отдельным предложением или убрать
4. Убить negative parallelism: прямое утверждение вместо "не X, а Y"
5. Разнообразить длину: чередовать короткие (5-8 слов) и длинные (15-25 слов) предложения
6. Убрать вводные-паразиты: "Важно отметить" → просто написать утверждение

Русскоязычные

Англоязычные

IV. Detection Checklist

Use this checklist when reviewing text:

[ ] Banned words (EN): delve, tapestry, leverage, seamless, etc.
[ ] Banned words (RU): является, данный, обеспечивает, осуществляет, etc.
[ ] Banned phrases (EN): "important to note", "plays a key role", etc.
[ ] Banned phrases (RU): "В рамках", "Важно отметить", "Стоит подчеркнуть", etc.
[ ] Structural: Rule of Three present?
[ ] Structural: Trailing participle clauses?
[ ] Structural: Negative parallelism ("not just X, but Y")?
[ ] Structural (RU): Genitive chains (3+ in a row)?
[ ] Structural (RU): Nominalizations instead of verbs?
[ ] Structural (RU): Depricipal clause pileup?
[ ] Punctuation: Em-dash density (>1 per paragraph EN, >5/1000 chars RU)?
[ ] Punctuation: Smart/curly quotes?
[ ] Formatting: Excessive bold, emoji bullets, markdown artifacts?
[ ] Formatting: Title Case headings in Russian?
[ ] Sentence variety: all similar length? (burstiness check)
[ ] Tone: forced optimism at the end?
[ ] Tone: promotional language without substance?
[ ] Dialogue artifacts: "Конечно!", "Let me know", etc.?
[ ] English calques in Russian text?

V. Severity Levels

• CRITICAL (instant fail): dialogue artifacts ("Конечно, я помогу!"), knowledge-cutoff disclaimers, em-dash density >8/1000, markdown artifacts in non-markdown context, "delve"
• HIGH (fix required): "является" density >2 per page, "В рамках" anywhere, banned phrase from top-20 list, Rule of Three + trailing participle in same paragraph
• MEDIUM (should fix): single banned word, minor genitive chain, one em-dash too many
• LOW (optional): borderline synonym variety, slightly formulaic structure

VI. Context-Specific Presets

Academic Russian (диссертация, статья)

• Allow: "Таким образом" (1x in conclusions), "В рамках" (1x in intro if specifying scope)
• Strict on: номинализация, цепочки Р.п., деепричастные нагромождения, "является"
• Extra rule: avoid anglicisms, prefer established Russian terminology

Habr / Tech Blog

• Strict on: em-dash density, listicle structure, bold spam, emoji bullets
• Allow: some informal constructions, code terms
• Extra rule: vary section structures, intersperse personal narrative

Telegram Post

• Strict on: dialogue artifacts, promotional language, calques
• Allow: short sentences, colloquial tone
• Extra rule: no "Важно отметить" — just say it

Cold Outbound Email (EN)

• Zero em-dashes allowed
• Zero banned phrases from email category
• Strict on: "I hope this finds you well", "looking forward to hearing"
• Extra rule: first sentence = substance, not pleasantry

Marketing Copy

• Strict on: all SaaS-speak (leverage, unlock, seamless, synergy)
• Strict on: Rule of Three, trailing participles
• Extra rule: replace every buzzword with a concrete claim

VII. References

1. Wikipedia:Signs of AI writing — English catalog (community-maintained, updated frequently)
2. Википедия:Признаки сгенерированности текста — Russian catalog
3. crimeacs/ai-tells-validator — Claude Code skill with live Wikipedia prefetch + regex enforcement
4. 7 метрик AI-хуманизатора (Habr) — Russian structural metrics: dash density, burstiness, genitive chains
5. Wikipedia выпустила гайд (Habr) — Russian commentary on the Wikipedia guide

VIII. Usage Examples

Example 1: Russian academic text

Before (flagged):

В рамках данного исследования важно отметить, что предложенный метод является эффективным инструментом, обеспечивающим существенное улучшение качества обслуживания клиентов компании, демонстрируя при этом устойчивость к различным возмущениям.

Flags: - [PHRASE] "В рамках" → канцелярит - [WORD] "данного" → канцелярит - [PHRASE] "важно отметить" → дидактический маркер - [WORD] "является" → избыточная связка - [WORD] "обеспечивающим" → шаблонный глагол - [STRUCTURE] цепочка Р.п. "улучшение качества обслуживания клиентов компании" - [WORD] "демонстрируя" → шаблонный глагол

After (clean):

Предложенный метод улучшает обслуживание клиентов и устойчив к возмущениям.

Example 2: English outbound email

Before (flagged):

I hope this finds you well. I wanted to reach out because we've built a transformative, seamless, and robust platform that helps companies leverage AI to unlock growth — driving efficiency across the entire pipeline.

Flags: - [PHRASE] "I hope this finds you well" - [PHRASE] "wanted to reach out" - [WORD] "transformative" + "seamless" + "robust" → triple banned word - [PATTERN] Rule of Three: "transformative, seamless, and robust" - [WORD] "leverage" - [WORD] "unlock" - [PUNCTUATION] em-dash - [PATTERN] trailing participle: ", driving efficiency"

After (clean):

We built a tool that cuts pipeline review time from 4 hours to 20 minutes. Three teams at [Company] use it today. Worth a 10-min call this week?

POI Generation Skill

What is a POI

A POI (Point of Interest) is a single station on a scientific trail. Each POI has: - A scientific storyline tied to a physical location - Three levels of narration (L1 basic, L2 formulas, L3 deep facts) - A physical interactive — something visitors build, touch, or measure - Audio narration generated via TTS - A PDF card for print

Pipeline

Storyline candidate → GROUND ON REAL POI → Critical-visitor test → Feasibility check →
   Text (3 levels) → Anti-AI scan → SSML → TTS → Audio (MP3)
                                                ↘ Typst → PDF card

Step 0: GROUND ON REAL POI (mandatory — fail-fast filter)

The single biggest mistake: extracting a "cool idea" from a lecture/book and adding it to the bank without first checking it lands on a real POI on a real route. A storyline without a place to live on the trail is useless — the bank is not a museum catalog, it is a deployment queue.

Two routes currently exist: - bot/config/poi.innopolis.yaml — Innopolis University, 8 POIs (entrance, atrium, robot path, Tesla marker, boulevard fork, sports zone, forest edge, data-center view) - bot/config/poi.skolkovo.yaml — Skolkovo Big Boulevard, 7 POIs (MCD station, Tehnopark, World Class, central square, Hypercube, Matrex, Skoltech)

For each candidate storyline, BEFORE anything else, answer:

1. Which existing POI does this refine or extend? Open both YAMLs. Find a point with a visible physical object that anchors the story. Cite the POI id.
2. If no existing POI fits — does this justify a new POI on one of these routes? Propose specific GPS coordinates. If the only honest answer is "would need a hypothetical site that doesn't exist on either route" → archive, do not add to bank.
3. Critical-visitor test: imagine you are a sceptical, time-pressed walker passing this point. Would you stop and listen? If the honest answer is "only if I'm already into the topic" — archive. The trail is for the random kid, not for fans.

Common failure modes that trigger archive: - Pure abstract algorithm / pure game theory without a physical object on the route (e.g. tit-for-tat, Gale–Shapley, Arrow's theorem, Conway's Life, HyperLogLog, k-means). - Politics, voting systems, sociological models. - "Cool number trick" that needs paper/pencil and a quiet desk (Karatsuba, Newton division, Schwarz triangle). - Anything requiring a TV/screen/keyboard/touch device on the trail. - Anything where the only interactive is "read this text and think about it".

Common passes: - A story that uses a real lake, tree, rock, sky, building, fork in the path, bridge, statue as its anchor. - An abstract idea that has a bodily demo on a small stand (coin rotation paradox, Platonic-solid sculptures, Fermat-Torricelli weighted strings, complex number = rotation on a clock face).

Step 1: Select storyline from bank

Source: content/storylines.yaml.

Pick by: - Route location (what's physically visible at the point) - Section variety (don't cluster 5 geometry POIs in a row) - Feasibility rating (prefer "easy", avoid "hard") - Budget (aim for <500₽ per POI on average)

Step 2: Feasibility check (three gates)

Every POI must pass ALL three gates:

Gate 1 — School workshop:

Gate 2 — Budget-accounted, non-exotic:

Still fails Gate 2: food, soap, fresh paper that gets wet daily, anything that can't be re-bought from a known shop.

Gate 3 — Any weather outdoors:

Adaptation rule: If an idea is great but fails Gate 2/3, try: paper → metal engraving, cardboard → welded wire, loose objects → chained/mounted, flashlight → sunlight, water → dry alternative. If no viable adaptation exists → remove.

If a storyline fails any gate and can't be adapted → remove.

Step 3: Write three narration levels

All narrations follow the Gasnikov style (see bot/config/style.md):

Rules: 1. Start with local binding: "Посмотри на...", "Прямо здесь..." 2. One baffling opener per POI — a counter-intuitive claim 3. Numbers always with units. Formulas spoken as words in audio. 4. Short sentences (max 25 words for audio) 5. No filler: "очень интересный эффект" = forbidden 6. Eyes-free: narration must work without looking at a screen 7. Focus on ideas, not names — don't name-drop scientists unless the name IS the story

Step 4: Anti-AI check (MANDATORY)

Before converting to SSML, run text through skills/anti-ai-text/SKILL.md.

Kill: "является", "данный", "важно отметить", "представляет собой", "обеспечивает", trailing participles, rule-of-three adjectives.

A narration that passes TTS but fails anti-AI is worse than no narration.

Step 5: SSML + TTS

Use skills/salute-tts/SKILL.md for the full TTS pipeline.

The build script auto-selects engine: - Salute Speech if SALUTE_AUTH_DATA available (best quality, SSML support) - Edge TTS as fallback (free, no API key, ru-RU-DmitryNeural voice)

# Generate all levels for specific POIs
python3 skills/salute-tts/build_audio.py --poi 01 05

# Generate everything
python3 skills/salute-tts/build_audio.py

SSML files go in skills/salute-tts/narrations/ as {nn}_{poi_id}_{level}.xml. Audio output: site/audio/{nn}_{poi_id}_{level}.mp3.

Step 6: Physical interactive design

Each POI needs a hands-on element. Design principles from docs/physical-interactives.md:

Do: - One effect, large parts, no fragile electronics - Materials: plywood, metal, acrylic, rope, magnets, anti-vandal fasteners - Understandable in 20 seconds without instructions - Works in rain, wind, direct sun

Don't: - Touchscreens, small removable parts, long instructions - Anything dependent on power supply - Decoration without an experiment

Step 7: Budget estimation

Target: average 500₽ per POI, max 2000₽ for complex items.

Budget categories on the site: - до 300₽ — found/basic materials - до 600₽ — hardware store - до 1000₽ — wood workshop - свыше 1000₽ — specialty items

POI YAML format

- id: 1
  name: "university_entrance"
  lat: 55.7527
  lon: 48.7440
  trigger_radius_m: 30
  topic: "GPS/ГЛОНАСС, трилатерация"
  scenario_brief: "One-sentence hook"
  level1_seed: "L1 narration text"
  level2_seed: "L2 narration with formulas"
  level3_seed: "L3 narration with stories"
  physical_interactive: "Description of hands-on element"
  sources: ["source1", "source2"]
  verified: false
  budget_rub: 500

Quality checklist

Before marking a POI as done:

• [ ] Tied to a real visible object at the location
• [ ] Has a number with units in every level
• [ ] Has a formula (spoken as words) in L2
• [ ] Physical interactive works without power
• [ ] Budget estimated and reasonable (<2000₽)
• [ ] Anti-AI scan passed (0 flags)
• [ ] Audio generated for all 3 levels
• [ ] Audio comprehensible without looking at screen
• [ ] Duration within range (L1: 40-90s, L2: 90-180s, L3: 180-300s)
• [ ] Cross-section link to another field of science

Outdoor Scipop Architect

Обзор

Проектировщик уличной научпоп-инфраструктуры по манифесту: вандалоустойчивые объекты, поперечное сечение реальности, метод вместо энциклопедии, локальный ландшафт как часть смысла, тексты трёх уровней в каноне русского научпопа. Главный сценарий — генерация концепции по «тема + локация»; вспомогательные сценарии — аудит существующих объектов и генерация текстов для готовых конструкций.

Когда активируется

• «Проект» (по умолчанию) — «придумай экспонат», «спроектируй стенд про X на Y», «есть идея и место».
• «Аудит» — «проверь стенд», «прошёл бы это манифест», «разбери концепцию».
• «Тексты» — «напиши А/Б/В», «перепиши под канон» (только если конструктив и сечение уже есть).

Алгоритм

1. Загрузить фундамент. Прочитать references/manifesto-filters.md — обязательно при любом формате. Без 8 фильтров скилл скатится в типовой занимательный научпоп, что манифест прямо отвергает.
2. Определить формат. По формулировке запроса. Если неоднозначно — спросить через ask_user_input_v0 с тремя вариантами (Проект / Аудит / Тексты).
3. Выполнить алгоритм формата. Открыть соответствующий reference: format-project.md, format-audit.md или format-texts.md.
4. Проверить поперечное сечение. Обязательный шаг при любом формате. Открыть references/cross-section-method.md и пройти все 5 шагов алгоритма. Если сечение не вытаскивается — отбраковка с диагностикой.
5. Опереться на каталоги. При проектировании — landscape-context.md и construction-patterns.md. При работе с текстами — levels-a-b-c.md и stylistic-playbook.md (восемь приёмов канона Перельмана/Ливанова).
6. Применить шаблон вывода соответствующего формата.

Ключевой принцип проверки

Перед выдачей ответа проверить два пункта:

• Сечение (фильтр 3) — структура сформулирована одной фразой без называния объектов? Есть ≥3 явления из разных доменов с механизмом?
• Метод (фильтр 5) — посетитель уносит способ рассуждать, а не очередной факт? Когнитивный сдвиг сформулирован как «он увидит, что…» или «он сам выведет, что…», а не «он узнает, что…»?

Если хотя бы один не пройден — это не доработка, а отбраковка сюжета. Манифест категоричнее музейной педагогики.

Ограничения

• НЕ предлагать решения с активной электроникой, юстировкой, тонкой оптикой на открытом доступе — фильтр 1 (честность) их отсекает.
• НЕ натягивать сечение из живого мира, если на тропе оно невидимо — это случай отбраковки, см. examples/engineer-of-nature-rejected.md.
• НЕ копировать стиль эталона WP003 буквально; понимать, почему он работает, и применять приёмы канона (stylistic-playbook.md).
• НЕ путать с science-museum-curator: тот — для музейных экспозиций под крышей; здесь — открытое пространство, тиражируемая сеть.

Справочные материалы

Storyline Proofread — quality gate

Философия

Это не инструкция «что сделать», а планка качества и цикл обратной связи. Задача скилла — не «пройтись разок», а крутить цикл правок столько, сколько нужно, пока каждый из критически настроенных проверщиков — текстовых и визуальных — не подтвердит, что придраться больше не к чему. Артефакт готов не когда «я внёс правки», а когда я сам открыл результат (HTML и PDF) и ни один критик не нашёл ни одного дефекта два круга подряд.

Категорически запрещены shortcut'ы. Нельзя: проверить часть и экстраполировать на остальное; «на глаз» решить что и так нормально; принять свою же правку без повторного рендера и просмотра; остановиться на первом чистом круге. Лучше потратить много времени и итераций, чем выпустить «почти готово».

Что на входе и что значит «готово»

• Вход: один сюжет content/storylines/<slug>.md (или список).
• Готово (стоп-условие): для каждого уровня и его PDF выполнены ВСЕ критерии всех критиков из references/critic-panel.md — включая покрытие визуалом (где идея просит схему — она есть и доведена до книжного качества по references/figure-style.md), — и два полных круга подряд не дали ни одной находки. Только тогда сюжет считается вычитанным.

Цикл (повторять до стоп-условия)

loop:
  1. RENDER   — пересобрать сайт (python3 build.py) → HTML + PDF уровней.
  2. CRITICS  — прогнать ВСЮ панель критиков (references/critic-panel.md):
                каждый критик независимо, адверсариально, ищет дефекты.
                Визуальные критики ОБЯЗАТЕЛЬНО открывают рендер
                (см. references/visual-review.md) — скриншот HTML каждого
                таба + просмотр PDF каждого уровня. Чтение исходника не
                заменяет просмотр рендера.
  3. COLLECT  — собрать все находки в один список с severity (blocker/major/minor).
  4. if находок == 0:
        clean_rounds += 1
        if clean_rounds >= 2: → ГОТОВО, выйти.
     else:
        clean_rounds = 0
        FIX — устранить ВСЕ находки в исходнике .md (или в build.py/шаблоне,
              если дефект системный — тогда чинить корень, а не симптом).
  5. → loop

Параллелить критиков и сюжеты разумно (один субагент = один критик или один сюжет), но синтез находок и решение «готово/не готово» — централизованно. При большом объёме (вычитка всех сюжетов разом) запускать через Workflow: pipeline по сюжетам, внутри — панель критиков, цикл до чистоты.

Панель критиков (кратко; полностью — references/critic-panel.md)

Каждый критик настроен скептически: его работа — найти, к чему придраться, а не подтвердить, что «нормально». Пустой отчёт критика допустим только если он реально не нашёл дефектов, просмотрев рендер.

Жёсткие правила

• «Sent» ≠ «verified». Любая правка считается применённой только после пересборки и повторного просмотра рендера тем критиком, чью находку чинили.
• Корень, а не симптом. Если дефект повторяется в нескольких сюжетах — чинить в build.py/шаблоне/формате, а не править каждый файл вручную.
• Не фабриковать факты. Восстанавливать можно только то, что уже сказано словами в тексте (стандартная формула, арифметика). Спорное — флагать, не выдумывать. См. правило no_unfounded_claims.
• Не ломать смысл. Перед удалением блока — понять, что это; «на согласовании»/внутренние пометки убирать из публички, но сообщать об этом.
• Самоэволюция скилла. Если в цикле всплыл класс дефектов, которого нет в critic-panel.md или format-contract.md, — дописать его туда. Скилл улучшается вместе с сюжетами.

Справочные материалы

Narration Generation

Full pipeline: storyline → L1/L2/L3 text → anti-AI → SSML → audio.

Quick start

# Generate narrations + SSML for storyline #5, POI "hilltop", prefix 01
python3 skills/narration-gen/generate.py --storyline 5 --poi hilltop --nn 01

# Same + generate audio
python3 skills/narration-gen/generate.py --storyline 5 --poi hilltop --nn 01 --tts

Output: skills/salute-tts/narrations/{nn}_{poi}_{l1,l2,l3}.xml

Manual generation (Claude Code agent)

When generating narrations directly (without the script), follow this exact structure.

Step 1: Read the storyline

From content/storylines.yaml, grab: - title — the hook question - topic — scientific domain - cross_section — where else this principle appears - section — category

Step 2: Write L1 (40-90 sec, 80-150 words)

Structure: 1. Local binding (1 sentence) — "Посмотри на...", "Прямо здесь..." 2. Baffling claim (1 sentence) — counter-intuitive, makes listener stop 3. Action (1-2 sentences) — what to do right now (look, touch, listen, count) 4. Explanation (2-3 sentences) — how it works, with one number+unit 5. Bridge (1 sentence) — where else this works

Example (GPS point):

Открой бот — он уже знает, что ты у главного входа. Но ни один спутник тебя не видел. Ни камеры, ни луча, ни фотографии. Спутники не ищут тебя. Каждый передаёт одно: сейчас такое-то время, я в такой-то точке. Телефон ловит сигналы и замеряет задержку. Один спутник — расстояние. Три спутника — три сферы. Точка пересечения — ты. Ошибка в миллионную долю секунды сдвигает на 300 метров. Поэтому на орбите — атомные часы. Так же охотится летучая мышь: крик, задержка, расстояние.

Step 3: Write L2 (90-180 sec, 150-300 words)

Structure: 1. Recap mechanism from L1 (1-2 sentences, don't repeat verbatim) 2. Formula step-by-step: explain what each symbol means BEFORE writing the formula 3. Numerical estimate: plug in real numbers, get a result with units 4. Cross-section: same math in another domain (1-2 sentences)

Formula rule: explain THEN name. "Расстояние равно скорости, умноженной на время задержки... записывается как ро равно цэ умножить на дельта тэ."

Step 4: Write L3 (180-300 sec, 300-500 words)

Five micro-stories, each 2-4 sentences: 1. Historical anecdote — who discovered this and how 2. Surprising application — where else this principle works (unexpected domain) 3. Record/extreme — biggest, smallest, fastest example 4. Paradox or failure — when it breaks or gives counter-intuitive result 5. Open question — what we still don't know

Each micro-story starts with a bold hook. Separate with pauses.

Step 5: Anti-AI check

Scan EVERY generated text. Kill on sight:

If ANY flag remains after one rewrite pass, rewrite again. Zero tolerance.

Step 6: Convert to SSML

Wrap in <speak> tags. Rules:

<speak>
First paragraph text.
<break time="400ms"/>
Second paragraph. Use *emphasis before key words.
<break time="400ms"/>
Third paragraph.
</speak>

• <break time="400ms"/> between paragraphs
• <break time="500ms"/> before dramatic reveal in L3
• * before emphasized words (no space: *триста метров)
• Stress marks: apostrophe after stressed vowel for tricky words

Stress dictionary (always apply):

трилатерация → трилатера'ция
реверберация → ревербера'ция
ковариация → ковариа'ция
когезия → коге'зия
кавитация → кавита'ция
ксилема → ксиле'ма
Фарадей → Фараде'й
Торричелли → Торриче'лли
Бернулли → Берну'лли
Вардроп → Вардро'п
Браесс → Бра'есс

Numbers as words: "300 м" → "триста метров", "10⁻³" → "десять в минус третьей", "ρgh" → "ро же аш".

Step 7: Save and build

skills/salute-tts/narrations/{nn}_{poi_id}_l1.xml
skills/salute-tts/narrations/{nn}_{poi_id}_l2.xml
skills/salute-tts/narrations/{nn}_{poi_id}_l3.xml

Then:

python3 skills/salute-tts/build_audio.py --poi {nn}

Validation

Before committing: - [ ] L1: 80-150 words, no formulas, one number+unit - [ ] L2: has formula explained step-by-step, numerical estimate - [ ] L3: 5 distinct micro-stories, each with own hook - [ ] Anti-AI: 0 flags on all three levels - [ ] SSML: stress marks on all tricky words - [ ] Listens well without looking at screen - [ ] No "посмотри на график" or "как показано на схеме"