TextMachine — документация

Проект: издательский художественный перевод крупных текстов (книги, ранобэ, вебновеллы) мультиагентным пайплайном поверх LLM API; пара языков — данные, не код, сегодня боевая zh→ru. Go-бэкенд + веб-фронт ридер-IDE (Ф3) + платформа (SaaS control plane, platform/, D39.81). Цели и мерило — канон в ../CLAUDE.md; онбординг сессий — там же. Стартовый бриф владельца: ../START_PROMT.MD — живой документ, его V-идеи разобраны в реестр требований (ниже).

Состояние проекта НЕ здесь — кроме таблицы активных промтов ниже, и это осознанное исключение: она отвечает на вопрос «какой файл мой», без которого холодная сессия выбирает роль сама (проверено слепым замером входа). Всё остальное состояние — Очередь, курс, бэклог — CURRENT-STATE в шапке PROGRESS.md; решения — architecture/05-decisions-log.md (при конфликте с любым доком побеждает он). Эта страница — только карта «что где лежит».

Карта

• glossary.md — жаргон и сокращения (D-номер, паки, банк, голден, K/DC/H/L…) одним экраном.

• dev-stand.md — поднять проект на чистой машине: что поставить, в каком порядке, что требует root и чего стенд НЕ проверяет. Версий и рецептов зон не дублирует — называет носитель и команду чтения.

• product-requirements.md — реестр «что продукт обязан уметь»: производное живого брифа владельца и его находок, статусы сверены кодом.

• architecture/ — синтез и контракты:

  • 05-decisions-log.md — источник истины по решениям: ратифицированный контракт, при конфликте побеждает он. Дисциплина чтения (грепать номер, не читать целиком, баннер прежде тела) — в каноне ../CLAUDE.md, здесь не дублируется. Статус и тело ЛЮБОГО номера одним хопом — реестр 05-decisions-index.md (все ноты, колонка тем для грепа «какой закон по X»).
  • 09-target-architecture.md — целевая 7-слойная архитектура (статус стройки — шапка-таблица; §3 — карта находок H/L) · 10-prompt-architecture.md — промпт-слой · 12-go-style-notes.md — норматив общности §0 · 13-tech-debt-anchors.md — якоря техдолга + археология выселенных строк бэклога §Б-* (справочник к бэклогу, НЕ трекер) · 14-api-contract/ — контракт API v0 фронт↔платформа (D39.99): нормативная спека OpenAPI 3.1 (типы фронта генерятся из неё) + компаньон-README с провенансом каждой строки (легенда — в нём самом; зонная копия frontend/docs/api-contract/ — байт-зеркало, сверять при лендинге).
  • Топикальные входы (D39.126; НЕ источники истины, при конфликте побеждает D-лог): 15-money-path.md — деньги от гранта до settle одним маршрутом · 16-events-emitter.md — сборка-норматив эмиттера шва — обязательное пре-чтение перед кодом эмиттера · 17-seam-inbound-law.md — закон ВХОДНОЙ двери шва движок↔платформа — РАТИФИЦИРОВАН D39.156: семь пунктов дисциплины, двери встают паками без нового решения владельца · STACK.md — карта «роль → модель → конфиг → квирки».
  • Исторические, читать через ⚠-баннеры: 01-decisions.md (Р1–Р10) · 02-mvp-plan.md · 03-implementation-notes.md · 04-unhappy-paths.md · 06-memory-risk-registry.md.

• experiments/ — эмпирика полигона: 00-provider-quirks.md — читать перед любым вызовом провайдера; 08-cost-model-v2.md — денежная модель; 09-pilot-protocol.md — пилот Ф2.5; остальные — отчёты экспериментов. ⚠ У каждого отчёта статус в его ревью-шапке: читай шапку прежде тела — она первична и говорит, ратифицированы выводы или заморожены.

• research/ — фактура ресёрчей; у принятых — ревью-шапки, часть тел под ⚠ superseded: читай баннер прежде содержимого. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа · 25 холодное ревью шва — читать перед любым кодом стыка · 24 арбитраж банка · 26 официальные практики Anthropic · 28 контракт-ревью API v0 — носитель для исполняющих сессий, читать оригинал, не пересказ.

• PROGRESS.md — журнал: CURRENT-STATE + ЕДИНЫЙ БЭКЛОГ (единственный трекер) + живой хвост хроники. НЕ источник решений.

• scripts/counts.py — производные числа доков считаются им, а не руками (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы · полнота реестра нот); --check даёт ненулевой код на расхождении; --lint — линтер file:line-якорей живых доков (D39.126). Его же зовёт зонный хук scripts/githooks/pre-commit: --lint якорей — при коммите, задевающем ЛЮБОЙ док или CLAUDE.md; --check чисел и головы — при коммите с D-логом или PROGRESS (оба --from-index, предупреждает, не блокирует). ⚠ Шапка систематически отстаёт от хвоста у ЛЮБОГО автора — потому проверка механическая, а не «посмотрю внимательно».

• Активные хендофф-промты — какой файл ТВОЙ (состав обновляется при каждом лендинге, D39.80; здесь — только то, что отвечает на вопрос «какой файл мой»; хроника, причины и статусы РАБОТ — CURRENT-STATE и D-лог):

  Роль	Активный промт	Статус
  Оркестратор	ORCHESTRATOR_SESSION_PROMPT.md	роль и нормы; счётчик роли — CURRENT-STATE
  Бэкенд	BACKEND_SEAM_PACK_SESSION_PROMPT.md	движковая половина закона входной двери шва (D39.156); запуск по слову владельца
  Платформа	PLATFORM_P8_REVIEW_SESSION_PROMPT.md	read-only ревью четырёх осей; запуск по слову владельца
  Полигон	POLYGON_EXP2223_REDO_SESSION_PROMPT.md (отложенный — POLYGON_PACKAGE4_SESSION_PROMPT.md, строка 85)	фаза Д ИДЁТ; ⚠ живой носитель курса — в eval/dovodka/, какой именно называет зона (⚠ POLYGON_PHASE_D_HANDOFF.md — перекрытый снимок, читать не как курс)
  Фронт	активного НЕТ	ЗОНА ЗАМОРОЖЕНА (D39.136 п.2 + D39.147: разморозка отдельным словом владельца, не привязана к P7); перечень первого касания — в зонном журнале
  Контракт	активного НЕТ	канон ратифицирован (версия — в самом openapi.yaml); следующий минор — ПОСЛЕ движкового пака и одним куском (D39.156)

  Отработанные промты — archive/prompts/, отчёты с ревью-шапками — archive/reports/. Зонные журналы фронта и платформы — frontend-PROGRESS.md / platform-PROGRESS.md в их зонах (прогресс зон только там, D39.100).

• Чужие зоны — фронт и платформа (читать при касании стыка; каждая ведёт СВОЙ зонный бэклог — единый бэклог их строк не принимает, D39.84): ../frontend/ — веб-интерфейс: промт фронт-сессий + STACK_DECISIONS.md (пины версий точными числами и ловушки) + BACKLOG.md · ../platform/ — SaaS control plane: README + BACKLOG.md + docs/ (зонный журнал platform-PROGRESS.md · регистр дефектов · STACK_DECISIONS.md с рецептом стенда и инвентарём каналов шва · ENGINEERING_STANDARDS.md — ратифицирован; КАЖДЫЙ промт платформенной сессии обязан на него ссылаться, отступление = пинг · PLATFORM_DIRECTION.md — ратифицированное направление зоны: аутентификация, деньги, стандарты, скорость · архив промтов).

• archive/ — история (правила архива): закрытые промты (prompts/) · отчёты с ревью-шапками (reports/ — на них ссылаются приёмки) · исполненные арх-доки (architecture/) · слайсы хроники PROGRESS-*.md. Инструкции оттуда не исполнять.

• Диаграммы: ../backend/docs/components.puml · ../backend/docs/pipeline.puml — дом рядом с кодом (D39.80), правятся бэкендом одним коммитом с кодом; вручную НЕ рендерить — их смотрят нативно, рендер не нужен.

Ключи провайдеров

Имена переменных per-провайдер — поле api_key_env в backend/configs/models.yaml (носитель, который читает КОД, поэтому разойтись с реальностью резолва не может). У полигона свои дополнительные провайдеры — имена в его же скриптах, движковый носитель их не покрывает и не должен. Наполненность ключей — .env деплоя, его НЕ читать; при сомнении спрашивать владельца. ⚠ Ручной перечень здесь не держим: он уже лгал умолчанием — называл семь имён, когда в ходу было девять.