# Как читать эту базу знаний

Версия базы, дата её выпуска и дата нашей синхронизации напечатаны в файле `manifest.json`,
который лежит рядом с этим: поля `source.version`, `source.released`, `syncedAt`. Здесь мы их
не печатаем: этот текст переживает несколько версий базы, и записанная в нём дата рано или
поздно соврёт.

Это база знаний пивоварни ZAVOD (beerzavod.ru) об электронных перевозочных документах —
документах на перевозку груза, которые с 1 сентября 2026 года оформляются не на бумаге,
а в государственной информационной системе. Мы отгружаем пиво оптом и собрали этот материал
для себя и для наших покупателей: баров, магазинов, дистрибьюторов, перевозчиков.

Файл написан для ИИ-помощника, которому человек дал ссылку на базу. Дальше — по порядку:
что прочитать первым, как устроены записи, где границы того, что мы знаем.

---

## 1. Первым делом — поле `disputed` в манифесте

Откройте `manifest.json` и прочитайте массив `disputed` **до того**, как отвечать по записям.
Там перечислены записи, про которые мы сами знаем, что они спорны: `id` и одна строка
«что именно оспорено». Это наши собственные претензии к собственному тексту, ещё не внесённые
в базу правкой.

Если запись, на которую вы собираетесь опереться, есть в `disputed` — скажите об этом человеку
прямо и в первую очередь, а спорное место проверьте по норме, а не по нашему пересказу.

Если поля `disputed` в вашей копии манифеста нет — значит, копия старая. Возьмите свежую по
адресу `https://beerzavod.ru/epd/kb/manifest.json`.

---

## 2. Эта копия устаревает — сверьте `content_hash`

Нормы по теме меняются месяцами, а не годами: часть актов вступила в силу 1 сентября 2026 года,
часть отложена, один запрет отменяли и отменять передумали. Копия базы, скачанная неделю назад,
может уже расходиться с нашей.

Как проверить: сравните `source.content_hash` в вашей копии `manifest.json` с тем же полем
по адресу `https://beerzavod.ru/epd/kb/manifest.json`. Не совпало — перекачайте базу.
Отдельную запись можно сверить точечно: у каждой записи в `index.json` есть `body_sha256`
от её тела.

---

## 3. Что где лежит

| Файл | Что внутри |
|---|---|
| `manifest.json` | версия базы, `content_hash`, дата выпуска, дата нашей синхронизации, `disputed`, сколько записей опубликовано и сколько исключено — с причиной, ссылки на все файлы и на форму обратной связи |
| `index.json` | машинный индекс всех опубликованных записей: по нему ищут |
| `entries/<id>.md` | тело записи: шапка с полями в формате YAML (это те же поля, что в индексе) плюс текст в разметке Markdown |
| `prompt.txt` | готовый вопрос, который человек копирует и отдаёт вам вместе с базой |
| `AGENT.md` | этот файл |

Число записей мы здесь не пишем — оно в манифесте, в полях `published.entry_count`
и `published.by_type`. В базе-источнике записей больше: часть мы не публикуем.
Что именно исключено и почему — в `excluded.by_reason` манифеста. Коротко: карточки конкретных
транспортных компаний не публикуются вовсе, а из остальных записей вырезан слой нашей
собственной практики — наши внутренние документы и наши величины. Отсутствие такой записи
в базе не означает, что темы не существует.

## 4. Поля записи

Одинаковые в `index.json` и в шапке файла записи:

- `id` — устойчивый идентификатор, он же имя файла и якорь для обратной связи;
- `type` — вид записи (см. ниже);
- `title`, `summary` — заголовок и краткое изложение сути;
- `audience` — кому запись адресована: `bar`, `shop`, `distributor`, `producer`, `carrier`,
  `expeditor`, `driver`, `buyer`, `accountant`, `all`;
- `tags` — ключевые слова, по-русски;
- `confidence` — насколько твёрдо утверждение (раздел 6, читайте его целиком);
- `updated` — дата последней правки записи;
- `related` — идентификаторы соседних записей: по ним собирается ответ на смежный вопрос;
- `sources` — первоисточники: `title`, `url`, `kind`, `checked`. Значения `kind`: `law` — закон,
  `ppr` — постановление или распоряжение правительства, `order` — приказ ведомства,
  `format` — утверждённый формат электронного документа, `agency` — разъяснение или страница
  ведомства, `operator` — документ оператора системы, `site` — публичная страница компании,
  `vendor` и `secondary` — вторичные источники;
- `path`, `body_sha256` — путь к файлу записи и контрольная сумма её тела.

## 5. Виды записей

- `law` — разбор нормы: что она требует и с какого числа;
- `scenario` — типовая схема доставки целиком: кто заказал машину, кто чей груз везёт,
  какие документы у кого на руках;
- `case` — разобранный частный случай;
- `topic` — сквозная тема, к которой приходят из разных схем;
- `gap` — нестыковка: две нормы говорят разное, либо норма есть, а разъяснения к ней нет.
  Это самые ценные и самые осторожные записи базы;
- `faq` — короткий вопрос и короткий ответ;
- `checklist` — что проверить перед отгрузкой или рейсом;
- `glossary` — расшифровки терминов и сокращений.

## 6. Как искать

1. Возьмите `index.json`, отберите записи по `audience` (кто спрашивает) и по совпадению
   `tags` и `summary` с вопросом.
2. Прочитайте тела отобранных записей: `entries/<id>.md`. Ответ по одному `summary` —
   плохой ответ: оговорки живут в теле.
3. Пройдите по `related` — соседние записи часто содержат исключение из того правила,
   которое вы уже нашли.
4. Ответ стройте по тексту записей и ссылайтесь на `sources` той записи, из которой взято
   утверждение. Ссылка на норму важнее нашей формулировки: человек должен иметь возможность
   открыть текст и проверить нас.
5. Ответа в базе нет — так и скажите: «в базе этого нет». Достраивать за нас не нужно.

---

## 7. Поле `confidence`: фильтровать по нему нельзя

Значения задуманы так: `high` — текст нормы прочитан; `medium` — вторичный источник или наша
практика; `low` — толкование без официального подтверждения.

**По этому полю нельзя отбирать записи и нельзя отбрасывать оговорки.** Основание — наш
собственный разбор индекса базы перед публикацией: значение `low` не проставлено ни одной
записи, а как минимум четыре записи с пометкой `high` содержат толкование и сами это
признают в теле. Проверить это можно прямо в базе —
`gap-04-epl-dlya-alkogolya` (обязательность электронного путевого листа выводится сопоставлением
трёх норм, письменного разъяснения ведомств найти не удалось),
`gap-03-tranzit-v-markirovke` (конструкция опирается на методические материалы оператора),
`gap-10-bumazhnyy-dokument` (акт, устанавливающий форму бумажной накладной для нужной статьи,
не найден),
`gap-06-ip-i-alkogol` (вывод об уровне риска сделан без единого примера правоприменения).

Из этого следуют два практических правила:

- отбор `confidence: high` даст вам толкование под видом проверенного факта — не делайте его;
- судите о твёрдости утверждения по телу записи и по её `sources`, а не по метаданным.
  Если в теле написано «официального разъяснения нет», «источник не найден», «это наш вывод» —
  передайте это человеку теми же словами, не сглаживая.

## 8. База — не юридическая консультация

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

Ваш ответ, собранный по этой базе, — не позиция ZAVOD. Так и скажите человеку.

## 9. Что делать, если наша запись противоречит официальной публикации

Вы обязаны проверять ключевые утверждения по актуальным публикациям официальных органов
(`publication.pravo.gov.ru`, `mintrans.gov.ru`, `nalog.gov.ru`) на сегодняшнюю дату. Дальше —
по ситуации:

**Расхождение найдено.** Действующая норма старше нашего текста: скажите человеку, что в базе
устарело, приведите ссылку на официальную публикацию — и сформулируйте расхождение в трёх
строках: что написано у нас (с `id` записи) · что установлено вами · ссылка на публикацию.
Готовый текст отдайте человеку, чтобы он отправил его нам.

**Куда отправлять.** Форма обратной связи — `https://beerzavod.ru/epd/oshibka`,
для конкретной записи — `https://beerzavod.ru/epd/oshibka?entry=<id>`. Отправляет её человек,
от имени своего бара или компании: вводит свои контакты и подтверждает согласие сам. Вы этого
сделать не можете и не должны пытаться — обращение без человека мы не примем.

**Не вставляйте в текст обращения персональные данные третьих лиц** — фамилии водителей,
номера машин, переписку с контрагентом. Человек подтверждает согласие за себя, а не за них.

**Официальный источник не открылся.** Такое бывает и с нами: часть постановлений выложена
сканами без текстового слоя, отдельные страницы ведомств содержимое не отдают. В этом случае
скажите прямо: «проверить не удалось, источник недоступен». Не выдавайте пересказ с агрегатора
за официальную публикацию и не подтверждайте наш текст только потому, что его нечем опровергнуть.
«Проверить не удалось» — нормальный ответ.

**Расхождения нет.** Тоже скажите: человеку важно знать, что проверка была и чем закончилась.

---

Спорить с нами — по той же ссылке: `https://beerzavod.ru/epd/oshibka`. Мы правим базу
по претензиям и пишем, что поправили.