Канон роду: як його вести¶

Канон — це те, що дослідження вже знає про рід: особи, родини, місця, джерела, і кожен факт із цитатою. Лежить у просторі, у data/canonical/:

data/canonical/
  persons/<ID>.md      особа
  families/<ID>.md     родина: чоловік, дружина, діти
  places/<ID>.md       місце
  sources/<ID>.md      джерело: справа, книга, сайт, розповідь
  regions.yml          (не обов'язково) реєстр губерній і повітів для карти покриття

Правиш його ти, файлами. Команд «додай особу» чи «зміни факт» немає навмисно. Пакет дає лише механіку навколо правки:

що	команда
чи цілий канон	`nysh canon check` (код 1 на помилках)
перебудувати базу роду	`nysh canon index`
ID нової картки	`nysh canon new-id person\\|family\\|place`
доказ у постійний стор	`nysh evidence add <кроп> -p <походження>`
засіяти порожній канон з GEDCOM	`nysh canon import <файл.ged>`
сайт роду з канону	`nysh site build [--public]` (скіл `build-site`)
git pre-commit: аркуш замість вирізки, зламана картка в коміті	`nysh canon hook --install`

Канон читають пошук (якорі роду, самоперевірка), дашборд, реєстр справ і сайт роду. Порожній канон робить самоперевірку пошуку сліпою, тож засівати його варто з першого дня.

🔴 Порядок роботи з однією знахідкою¶

Спершу прочитати канон. Зазвичай більшість «знахідок» у ньому вже є. nysh text grep "<регекс>" --where canon і самі картки осіб, яких стосується знахідка. Уже є — дописуєш цитату до наявного факту, а не новий факт.
Вердикт — за людиною. «Це наш рід», «це та сама особа» виносить дослідник. Ти кладеш підтверджене ним як confirmed, а власний висновок — як hypothesis.
Доказ у стор ДО факту. nysh text crop <справа> <скан> <рядок> → nysh evidence add <png> -p <архів>. Цитата ніколи не посилається на кроп у теці прогону, кеш чи чернетку: їх чистять, і цитата провисає, виглядаючи живою.
ID нової картки — з nysh canon new-id, картку писати одразу.
Правка картки (формат нижче).
nysh canon check — нуль помилок, попередження прочитати.
nysh canon index, потім nysh cases build.

Формат картки¶

Шапка YAML — дані, тіло Markdown — нотатки (notes). Поля й допустимі значення задає модель (nyshporka.models); canon check лається на все, що модель не приймає.

---
id: I9001
names:
- form: Іван Петрович Коваль
  lang: uk
  primary: true
  given: Іван
  surname: Коваль
- form: Иоаннъ Ковалевъ
  lang: ru
  primary: false
sex: M
private: false
facts:
- type: birth
  date: {value: '1832', precision: year, qualifier: about}
  place_id: PL9001
  status: confirmed
  citations:
  - source_id: S_<АРХІВ>_<ФОНД>_<СПРАВА>
    page: скан 0142, рядок 7
    quote: Иоаннъ сынъ Петра Ковалева 23 лѣтъ
    confidence: indirect
    accessed: 2026-09-29
    note: 'Вік зі сповідки, рік вирахувано. Звірено по кропу. Доказ: `data/source/citations/<архів>/<файл>.jpg`'
parent_family: F9001
spouse_families: [F9002]
media:
- path: data/source/citations/<архів>/<файл>.jpg
  sha256: <з відповіді evidence add>
  type: document
  caption: Сповідний розпис, рядок про Іоанна
aliases: []
---

Вільні нотатки. Посилання на інші картки — `[[I9002]]`, `[[F9001]]`.

Ім'я файлу = id. Скопійована заготовка з незміненим id — найчастіша помилка; check її ловить.
page цитати називає скан («скан 0142.jpg, рядок 7»), а raw_path картки джерела — теку справи. Так самоперевірка пошуку (--selfcheck) знаходить аркуш, де рід уже знайдено, і міряє на ньому, чи бачить пошук відоме.
Прізвище — як у джерелі, у своєму names-варіанті з lang. Не нормалізувати в одне написання: інакше пошук втрачає написання, яким рід записаний у книзі.
Дата — рядок ISO (1832, 1832-05, 1832-05-14) + precision (day|month|year|decade|century) + qualifier (exact|about|before|after|between|estimated|calculated, для between — range_end).
Родина (families/): husband, wife, children, facts (шлюб). Зв'язок записується в обох картках: children родини ↔ parent_family дитини, husband/wife ↔ spouse_families.
Джерело (sources/): type (archive|book|periodical|website|oral|…), title, repository_ref (архів, фонд, опис, справа), url. ID — читабельний slug, наприклад S_<АРХІВ>_<ФОНД>_<СПРАВА>.
Живі й недавні — private: true. Приватна версія сайту показує їх лише десятиліттями, відкрита не показує зовсім. check попереджає (maybe_living) про особу без смерті, народжену за останні 100 років, без цієї позначки.

Рубрика: `confidence` цитати¶

рівень	коли
`direct`	джерело прямо фіксує саме цей факт про саме цю особу (запис хрещення дитини — її народження), і ти звірив рядок по зображенню
`indirect`	факт виводиться з джерела, яке прямо про нього не каже: рік народження з віку в сповідці, батько з по батькові, село з приписки
`circumstantial`	збіг обставин без запису, що зв'язує: те саме ім'я, село, десятиліття
`speculative`	робоча здогадка, яку ще треба перевірити
`negative`	прошукано — не знайдено. Лише зі знаменником у `note`: яка справа, скільки сторінок, яким каналом (`nysh text find` дає журнал)

Рубрика: `status` факту¶

статус	коли
`confirmed`	є хоча б одна цитата `direct` або `indirect`, звірена оком, і їй ніщо не суперечить
`hypothesis`	усе інше; це значення за замовчуванням
`disputed`	джерела суперечать одне одному. Лишаються ОБИДВІ цитати, пояснення в `note`, і обов'язково поле `hypothesis: H…` — картка, що каже, чим суперечність вирішиться

check попереджає про confirmed без цитати або лише зі слабкими цитатами: у дереві такий факт виглядає так само, як доведений.

Зв'язки: підтверджені й гіпотетичні¶

parent_family, spouse_families, husband/wife/children — лише коли зв'язок прямо записаний у джерелі (метричний запис, ревізія, де сказано «син», «жена»).
Усе виведене — у hypothetical_parent_family, hypothetical_spouse_families і hypothetical_husband/_wife/_children родини. Сайт і дерево показують їх окремо.
Гіпотезу записують в обох картках. Спростували — прибирають з обох і пишуть у notes, чим спростовано. Однобічне ребро check показує як one_sided.
Кожне гіпотетичне ребро має картку гіпотези, у чиєму about стоїть ця особа чи родина (інакше check — hypothetical_unlinked).

Гіпотеза: картка `H…`, а не нотатка¶

Усе, що про рід не доведено, живе в картці data/canonical/hypotheses/H0001.md. Нотатки, звіти й пам'ять агента для цього не годяться: їх ніхто не перевіряє, і за місяць вони показують закрите як відкрите. Картку перевіряє canon check, а git-хук канону не пускає в коміт картку з помилкою.

id: H0001
claim: Петро — син Івана, що до 1806 вибув із двору     # одне речення
status: awaiting          # open — шукаємо · awaiting — є хіти, чекає людини · closed
about: [I9012, F9003]     # про кого
basis: Лише Спісок 1802; клірові 1806 і 1809 його не знають   # на чому тримається
decides: Метрика смертей села 1802–1806                  # що розв'яже — ОБОВ'ЯЗКОВО
versus: [H0002]           # конкурентна гіпотеза (в обох картках)
hits:                     # не більше 5: лише ті, від яких щось залежить
- case: REPO/1/2/3        # ключ справи, як у сховищі сторінок
  scan: '0082'
  line: 52
  reading: «…Ковальського…» # дослівно, непевне в [ ]
  strength: strong        # strong | weak — твоя оцінка, людина виправляє
  eye: true               # кроп дивилися оком
verdict: ''               # закрита: що вирішено, ким, коли
reopen_if: ''             # закрита: який НОВИЙ доказ її відкриває
updated: 2026-10-12

Правила, які тримає check (ERROR):

відкрита гіпотеза без decides;
закрита без verdict і reopen_if;
awaiting без хітів, понад 5 хітів;
хіт із ключем справи не в канонічній формі (тоді вердикт до нього не знайдеться);
факт disputed без hypothesis.

Попередження (WARN):

hyp_verdict_ready — на хіт уже є вердикт у журналі гортача, а гіпотеза досі чекає. Онови стан і виріж хіт.
hyp_stale — відкрита гіпотеза, якої не торкались 60 днів.
hypothetical_unlinked — гіпотетичне ребро без гіпотези.

Що показувати людині. nysh canon next ранжує відкрите: спершу те, що чекає вердикту і має сильний хіт, далі за вагою (скільки фактів і осіб від гіпотези залежить). Людині показувати не більше трьох рішень за раз, кожне з кропом. Кандидат пошуку, що не рухає жодної гіпотези, людині не показується: він лишається у звіті заходу.

Шапка тримає чинний стан, а не історію. Розв'язаний хіт вирізається, хід міркувань пишеться в тіло картки. Закрита гіпотеза лишається: вона боронить від повторного розслідування того самого.

🔴 Чого не робити¶

Не переносити цифру чи дату з декоду без зображення. Прозу рушію виправляє мовна модель, число — ні: помилка в цифрі виглядає так само впевнено, як правильна. Звірка по кропу, або факт іде як hypothesis з позначкою «не звірено».
Не вирішувати за людину, що кандидат — «наш» чи «не наш». Твоє — покласти кандидата з кропом (nysh text sheet, nysh text verdicts).
Хибне читання виправляти начисто: правильне значення на місце хибного, без «було → стало» в картці. Історію тримає git.
Не цитувати аркуш цілим. Доказ — вирізка рядка: аркуш важить мегабайти, а читач однаково шукає на ньому один рядок. evidence add понад 2 МБ не приймає.
Не переписувати cited_by у маніфесті руками — його дописує canon index.