Що я вмію — і чим саме до цього дотягуюсь¶

Читати згори: спершу про дві поверхні, бо половина розчарувань тут — не «застосунок не вміє», а «я стукав не в ті двері».

🔴 Твоя поверхня — командний рядок¶

Операцій у реєстрі 191, і командний рядок дістає усі:

nysh op workspace.info                                   # без аргументів
nysh op pages.status --args '{"case": "230-1-4"}'        # з аргументами
nysh op search.run --args '{"q": "Іваненко", "where": "decode"}'

поверхня	скільки операцій	як звертатись
командний рядок	усі 191	`nysh op <ім'я> --args '<json>'` або дружня команда (`nysh search …`)
браузер (`nysh serve`)	ті самі, що ввімкнені секцією	кнопки людини

Застосунок (nysh serve) один на Майстерню. Проєкт кожен запит несе сам: вкладка — в адресі (?p=<ім'я>), HTTP-клієнт — заголовком X-Nysh-Project; без нього — проєкт, з якого застосунок запустили.

Простір, де рід лежить у корені (старого типу), переводиться в Майстерню з проєктом роду командою nysh project adopt <ім'я>: спершу план, потім --apply --archive <тека>, відкат — --rollback.

Стартовий перелік (nysh ops --agent) — 25 операцій ядра, з яких починають дослідження. Це карта входу, а не межа: решта реєстру так само доступна через nysh op, і серед неї geog.find (де взагалі є метрики цього села по ВСІХ фондах), church.find (чи була в селі церква ~1772, чия, і де тепер її книги), archive.fond (чи входить опис у ключ справи), parish.in_case (які села всередині зведеної книги — до того, як її читати), read.plan, library.list.

Ядро і пошук: якою командою це робиться¶

Кожна дія має рівень: ядро — те, з чого складається звичайний день дослідження; ситуативне — потрібне під конкретну задачу; рідкісне — службове, людське, лабораторне. До ядра входять і друковані команди поза реєстром (nysh read, nysh cloud go, nysh cloud state, nysh doctor).

nysh ops --map                       # карта ядра «команда — коли брати», групами
nysh ops find зупинити оренду карти  # яка команда під цю ситуацію
nysh ops find метрики села --json    # те саме машинно: tier, when, skill, scope

Карту ядра хук старту сесії друкує сам (nysh project status --agent), тож її не треба вчити напам'ять. Решту не перебирай --help по черзі: ops find шукає по «коли брати», підпису й докстрінгу і відповідає друкованою командою. Карта й пошук показують лише те, що в цьому просторі виконається: вимкнена секція, проєкт, відкритий лише для читання, і проєктний шар у чистій Майстерні відсіяні (--all — показати все).

Ситуацію, яку веде процедура, а не одна команда («куди ще копати», «прийняти куплену зйомку»), ops find відповідає ще й скілом: ▶ скіл <ім'я> — його вантажать цілим, перш ніж діяти. Вимкнений у проєкті скіл (skillOverrides) пошук не радить. Самі скіли переліків команд не тримають: команди — з карти й ops find, у скілі лишаються порядок кроків, ворота й приймачі.

До ядра входять і cases.build (реєстр після будь-якої дії), share.pull (взяти прочитане з Супряги замість прогону), share.pack і share.push (віддати прочитане), share.card (картка справи в пулі) — скіли pull-case і share-case.

Браузер і командний рядок — тонкі обгортки одного реєстру: та сама валідація, той самий конверт відповіді, ті самі попередження. Розійтись вони не можуть — це перевіряється тестом (test_triptych_parity.py), а не домовленістю.

⚠ MCP-сервера (nysh mcp) більше немає — прибрано в 0.19. Якщо в конфігу агента ще прописаний сервер nyshporka, його треба прибрати (claude mcp remove nyshporka або рядок у .mcp.json); порядок переходу — nysh migrate.

🧭 Після оновлення пакета — міграція агента. Якщо workspace.info чи дашборд кажуть agent_migration, частина того, що ти знаєш про Нишпорку, застаріла: nysh migrate (що змінилось і які кроки ще не зелені), nysh migrate --scan (застарілі тези у твоїй пам'яті й нотатках), nysh migrate --done. Операції — migrate.status, migrate.scan, migrate.done; порядок — скіл migrate.

Розвідка: імена, аргументи, причини¶

Найдорожче тут — вгадувати назви полів. Не вгадуй, питай:

nysh ops                       # перелік для ока: ✎ пише · ⏳ довга · 🤖 стартовий
nysh ops --agent               # лише стартовий перелік
nysh ops --json                # усе разом зі схемами аргументів, машинно
nysh op pages.note --describe  # одна операція: схема + ПОВНИЙ докстрінг

--describe нічого не виконує — навіть у мутації. Це важливо: інакше єдиним способом дізнатись аргументи запису лишався б виклик «щоб подивитись, що відповість», тобто запис у чуже сховище заради довідки.

🔴 --describe віддає те, чого немає більше ніде. У переліку nysh ops до тебе доїжджає однорядковий підпис; у докстрінгу операції лежить причина, чому вона така, — із замірами й ціною помилки («дефолт — рядок, бо сторінка коштує моделі вчетверо дорожче», «позиційний розбір уже віддав 2944 справи з нулем аркушів, і за числом рядків це виглядало успіхом»). Якщо поведінка здається дивною — причина майже напевно там, і прочитати її дешевше, ніж здогадуватись.

🔴 Довга робота: два режими, і вибір робиться ДО виклику¶

Читання справи й завантаження кадрів — години. Такі операції не повертають результат, вони повертають посилання на завдання, а завдання живе в черзі. Черга є тільки в піднятому застосунку.

що робиш	черги немає (типово)	черга є (`nysh serve` в іншому вікні)
прочитати справу	`nysh read <тека>` — читає в процесі, друкує прогрес	`nysh op read.start` → стан через `nysh op job.query`
завантажити кадри	`nysh get <джерело> <ref> --out <тека>` — маніфест ДО качання	`nysh op acquire.start` → `nysh op job.query`
перезібрати реєстр	`nysh cases build`	кнопка в застосунку
кілька справ поспіль	`nysh queue add <справи>` → `nysh queue run` — кадри, паспорт, каталог, пул, читання, облік, віддача; стан — `nysh queue`	`nysh queue start` — той самий виконавець у фоні

Синхронний шлях — не запасний, а основний: прогін ставлять на ніч, часто по ssh, і вимагати для найдовшої роботи піднятого браузера означало б зробити її найкрихкішою.

Викликана без черги, довга операція відповідає відмовою «підніміть nysh serve» — чесно, але дізнається про це той, хто вже витратив хід. Тому режим названо в докстрінгу: nysh op read.start --describe каже це перед тим, як ти щось запустиш.

⚠ nysh read не має ідемпотентності. Повторний запуск = другий прогін по тій самій теці, який б'ється з першим за карту. Перед запуском перевір, чи читання вже не йде (nysh op runs.list).

Чотири кроки, які роблять раз на сесію¶

У стартовому переліку їх немає навмисно — це не робота дослідження, а орієнтація в чужому просторі. Через nysh op вони теж доступні (setup.check, profile.show, sections.show), але дружня команда друкує їх зрозуміліше.

потрібно	команда	чому це важливо
стан машини	`nysh doctor --json`	хмарна тека й CPU-збірка torch — усе, що потім виглядатиме як «зависло»
чий рід шукаємо	`nysh profile`	без профілю всі написання прізвища доводиться пригадувати самому — і нуль виходить із неповного набору
увімкнені частини	`nysh sections`	вимкнена секція відмовить посеред роботи, а не на початку
перезібрати реєстр	`nysh cases build`	після твоїх же записів реєстр застаріває

Карта дій¶

Колонка «команда» — як дістати операцію з командного рядка; nysh op <ім'я> працює для будь-якої, дружня команда там, де вона є, друкує зрозуміліше.

Орієнтація¶

операція	команда	що прочитати у відповіді
`workspace.info`	`nysh op workspace.info`	`locked_by`: не `null` — людина працює в браузері просто зараз
`cases.list`	`nysh op cases.list`	`stale` — якщо `is: true`, числам вірити не можна
`material.look`	`nysh op material.look`	чи взагалі придатне до читання: скільки кадрів, одна справа чи багато
`sources.list`	`nysh op sources.list`	`caps` — не кожне джерело вміє все; `about` — клас, межі (`scope`) і що доводить нуль (`zero_means`); `undeclared` — хто без опису
`library.list`	`nysh op library.list`	що вже на руках і який вердикт винесла людина
`runs.list`	`nysh op runs.list`	що вже прочитано і чим

Знайти матеріал¶

операція	команда	що прочитати
`catalog.search`	`nysh op catalog.search`	`coverage` і попередження: у яких каталогах шукали. Без `source` іменні бази (`martyrolog`) не питаються — `coverage.not_asked`; з `source=martyrolog` покриття бази по архівах — `coverage.basis[].by_archive`. Шифра в запиті («127-1078-1662») веде адресним маршрутом: `address` у відповіді, `address_route` у попередженнях, каталоги при цьому НЕ прочісувались
`catalog.browse`	`nysh op catalog.browse`	—
`catalog.manifest`	`nysh op catalog.manifest`	обсяг у байтах: справа буває 30 ГБ
`geog.find`, `geog.card`	`nysh op geog.find` · `nysh op geog.card`	де є метрики села по всіх фондах, а не лише в православному розділі; картка несе `location` (точка з пака `places`, `how=ambiguous` — однойменних в області кілька)
`geog.near`	`nysh op geog.near`	сусідні села газетира в колі, одразу з числом справ; знаменник — лише села з точкою
`church.find`, `church.card`, `church.near`	`nysh op church.find` · `nysh op church.card` · `nysh op church.near`	чи була в селі церква ~1772 (Кольбук, Socjografia), якого деканату, з якою присвятою — і, через зшивку з газетиром, де тепер її книги; `near` — коло сусідніх парафій того ж часу. 🪤 Однойменне село в іншому воєводстві зшивається теж, з позначкою `region=mismatch`
`catalog.search` з `--source sks` / `sks-osoby`	`nysh find "<село>"` · `nysh find "<прізвище> [ім'я]" --source sks-osoby`	покажчики гродських книг XVII–XVIII ст. (пак `courtbooks`): місце чи особа з роллю в акті, книгою ЦДІАК ф.44/ф.40 або загубленою KAC і адресою акта на сторінці укладача; `parish.find` показує згадки села окремим блоком. 🪤 Покажчик, не звірений текст — `[?]` укладача лишається сумнівом
`archive.fond`	`nysh op archive.fond`	🔴 чи входить ОПИС у ключ справи цього архіву — недогляд тут уже злив дві книги в одну справу
`fond.list`, `fond.rows`	`nysh op fond.list` · `nysh op fond.rows`	що описано й що з того вже в нас

Читати й дивитись¶

операція	команда	що прочитати
`page.text`	`nysh op page.text`	`lines` — готовий перелік рядків; `geometry.has`
`page.view`	`nysh op page.view`	`note` — чи не підмінили рядок сторінкою
`page.lines`	`nysh op page.lines`	рамки рядків, коли треба клікати по знімку
`read.plan`	`nysh op read.plan`	чим і як читатимемо — до запуску: письмо, модель, скільки кадрів

🔴 Дефолт page.view — рядок, і не міняй його без потреби. Ціла сторінка коштує моделі приблизно вчетверо дорожче за вирізку рядка, а звірок за сеанс бувають десятки. Сторінку бери свідомо: коли потрібен контекст навколо запису (заголовок, ліва колонка формуляра, сусідні акти).

Навколо рядка домальовується рамка. Без неї ти бачиш кілька рядків і не знаєш, який із них оцінюєш, — і чесно оцінюєш не той.

Подивитись на рядок із термінала можна — перевірено:

nysh op page.view --args '{"run": "…", "page": "0012.jpg", "line": 3}'

Поле image — data URL (data:image/png;base64,…); розкодуй base64 у файл і відкрий його засобами свого середовища. 🔴 Це не обхідний маневр, а нормальний шлях: якщо ти вирішив, що без окремого інструмента звірка неможлива, ти закриєш КРОК 4 — єдиний, на якому кандидат стає знахідкою, — і подаси людині текстовий здогад замість зображення.

Шукати й записувати¶

операція	команда	що прочитати
`search.run`	`nysh op search.run`	знаменник у попередженні + `line_index` кожного хіта; `role`/`rtype`/`axis` звужують і потрапляють у `coverage`. Кожен хіт каже, ЯКИМ написанням знайдений (`stem_origin`) і чи опущений чужим словом (`rank_why`) — опущений НЕ зникає. `anchors` додає другий канал (ім'я + по батькові поруч) окремим списком, `record` — третій (ознаки родини з різних колонок одного запису), `selfcheck` — recall на тому, що вже виписало око; усі три в межах справи. `family` — чий рід (ключ профілю); порожньо — рід, написанням якого є запит, серед усіх профілів файла
`text.grep`	`nysh text grep <регекс> --case <справа>`	регекс по СИРОМУ тексту прочитаного замість `rg` по теці прогонів: та тека в `.gitignore` (ripgrep мовчки віддає нуль) і тримає мільйон файлів (обхід — хвилини). `coverage.prefiltered` каже, чи звужено корпус літералами регексу; нуль — зі знаменником
`text.grep` `--where canon\|opys\|notes\|pages\|all`	— (`nysh text grep <регекс> --where all`)	той самий регекс по канону, реєстрах опису, нотатках `reports/` (без теки прогонів) і сховищу сторінок разом із нотатником справи (`pages`) — «ми це вже знаємо?» одним запитом; `layers.coverage` каже, скільки файлів прочесано в кожному шарі
`text.state`, `text.index`	`nysh text state` · `nysh text index`	скільки прогонів у сторі і скільки застаріло; після нових прогонів — `index`; `index --accept-rules` — прийняти відбиток правил без перебудови, коли мінявся лише спосіб його рахувати. Пошук прізвища (`search.run`) бере стор сам, щойно той покриває область: `coverage.backend`. `state --verify [--sample N] [--case X]` — ДОКАЗ однорідності замість заяви відбитка: кандидати звірених сторінок перераховуються чинним кодом і порівнюються з блобами; `verify.differ[].rules_same=true` означає, що відбиток бреше і `index` цього прогону не побачить — лікує `index --rebuild --case <прогін>`. Код виходу 1 на розбіжності
`text.ctx`, `text.voices`	`nysh text ctx <справа> <скан> [--line N]` · `nysh text voices`	сторінка навколо рядка з УСІМА голосами, сусіди за геометрією (`geo_next`/`geo_prev`), роки справи, чи бачило око; `voices` — рядок до рядка, `agree` означає надійне ЧИТАННЯ, не приналежність
`text.crop`	`nysh text crop <справа> <скан> <рядок>`	PNG рядка з кадру за рамкою рушія, з поворотом і масштабом; типово разом із наступним рядком (перенос). Відповідь несе `frame`, `orient`, `scale_k`, `out`
`text.coverage`, `text.whatis`	`nysh text coverage [--unsearched]` · `nysh text whatis <справа>`	«що не дивились»: кадри → прочитано → у сторі → чим шукали → око, по справах; картка справи з реєстру, паспорта, прогонів і найчастіших слів тексту
`text.find`	`nysh text find <прізвище> [--case <справа>] [--family <ключ>]`	усі канали пакета разом: прізвище всіма написаннями роду (склейки через рядок і колонку вже в кандидатах стору), якорі імен роду у вікні років справи, запис (ознаки родини з колонок одного запису за геометрією), самоперевірка на аркушах ока. Рід — будь-який профіль файла: названий або впізнаний за запитом. `ledger` називає кожен канал: ганяли — з числами, не ганяли — з причиною; нуль без журналу не друкується
`text.sheet`, `text.verdicts` ✎	`nysh text sheet <прізвище> --case <справа>` · `nysh text verdicts <json> --case <справа>`	HTML-гортач кандидатів із контекстом, другим голосом і кропом; вердикт («наш рід», «уже в каноні», «інше прізвище», «не прізвище», «не читається») виносить ЛЮДИНА в полі картки, кнопка збирає JSON; `verdicts` заносить його у сховище сторінок як `partial` — і негативні теж, щоб той самий аркуш не дивились двічі
`pages.status`	`nysh op pages.status`	перед переглядом, не після
`pages.note` ✎	`nysh op pages.note`	—
`note.read`, `note.add` ✎	`nysh note read <справа> <скан> --line N --text …` · `nysh note add <справа> --kind about\\|catalog-error\\|copy\\|note`	нотатник справи (той самий файл сховища): звірене оком читання РЯДКА з рамкою й читанням рушія; опис справи, помилка опису архіву, копія деінде; особисте — `note`. НЕ голос прогону: у знаменник не йде, нуля не дає. Скіл `case-notebook`
`note.push`, `note.pull` ✎	`nysh note push <справа> [--dry-run]` · `nysh note pull <справа>`	у Супрягу їде лише позначене `--share` загальне знання + переглянуті аркуші без коментарів; `push` — дія від імені людини, лише з її згоди
`records.add` ✎	`nysh op records.add`	`replace` стирає всю справу й вимагає `confirm` числом
`export.case`	`nysh op export.case`	кожен рядок несе скан
`pages.show`	`nysh op pages.show`	сховище як воно є: `agent`, `noted`, один запис за `rid`
`case.register` ✎	`nysh op case.register`	—

⚠ line_no і line_index — різні числа. Перше для людини (з одиниці), друге — індекс рамки для page.view (з нуля). Передаси не те — побачиш сусідній рядок і не помітиш цього.

Канон роду¶

Канон — картки осіб, родин, місць і джерел у data/canonical/** (MD з YAML-шапкою). Правиш його ти, файлами: команд «додай особу» немає навмисно, бо текст картки ти правиш краще за будь-яку форму. Операції нижче — механіка навколо правки. Порядок, формат і рубрика впевненості — canon.md, скіл keep-canon. У git-просторі nysh canon hook --install ставить pre-commit, що не пускає аркуш замість вирізки й помилку в картці, яка комітиться.

операція	команда	що прочитати
`canon.check`	`nysh canon check [--hash] [--info]`	після КОЖНОЇ правки: схема, зв'язки в обидва боки, хронологія, місця й джерела, докази на диску й у маніфесті. Помилки — дані, а не збій: `errors` у відповіді, код виходу 1
`canon.index` ✎	`nysh canon index`	перебудувати базу роду (`data/derived`), з якої читають дашборд, реєстр справ і сайт; дописує в маніфест доказів, хто їх цитує
`canon.next`	`nysh canon next [--limit 3]`	що людині вирішити першим: відкриті гіпотези роду (`data/canonical/hypotheses/`) за вагою, з командами кропу хітів. Показуй не більше трьох рішень за раз
`canon.new_id`	— (`nysh canon new-id person\\|family\\|place\\|hypothesis`)	ID нової картки. Не вгадуй: вгаданий ID перетирає чужу картку. Нічого не резервує — пиши картку одразу
`canon.import` ✎	`nysh canon import <файл.ged> [--dry-run]`	засіяти ПОРОЖНІЙ канон із GEDCOM іншої програми; злиття немає. Факти приходять як `hypothesis` з цитатою на сам файл; `--trust-tree` — лише якщо людина сказала вірити дереву
`site.build` ✎	`nysh site build [--public]` · `nysh site serve`	сайт роду з канону: приватний (живі з датами до десятиліття) або відкритий (живих немає, HTML перевіряє сторож — витік видаляє HTML). Скіл `build-site`
`evidence.add` ✎	`nysh evidence add <кроп> -p <походження>`	доказ у постійний стор ДО факту в каноні: сірий JPEG ≤ 2 МБ, хеш, маніфест. Шлях із відповіді йде в `media[]` і в цитату

⚠ Твої записи нічим не стримані¶

Мутації (pages.note, records.add, case.register, evidence.add, правка карток канону) пишуть на диск одразу: без підтвердження, без токена, без блокування. Якщо людина працює в браузері паралельно, ви пишете в те саме сховище.

І кожен твій успішний запис застарює реєстр людини — вона побачить у себе «⚠ зріз застарів». Це нормально й задумано, але означає: після партії записів виконай nysh cases build, інакше і твій наступний cases.list, і її екран показуватимуть учорашню картину.

Позначку «пише на диск» видно до виклику: ✎ у nysh ops, поле "mutates": true у --describe.

🛑 Чого немає навмисно¶

Тут різниця принципова: стартовий перелік — про те, з чого почати; цей розділ — про те, чого для тебе немає ніде.

немає	чому
`cases.bind` серед агентних	прив'язка «нічийого» прогону до справи — рішення людини, яке перебиває всі автоматичні канали. Правдоподібна прив'язка = чужий декод під правильною шифрою, з якого потім цитують знахідки
`library.verdict` серед агентних	вердикт «наше / не наше» виносить дослідник. Твоя частина — покласти кандидата з кропом
`sections.set`, `sample.install` серед агентних	переналаштування застосунку й розгортання зразка — не робота дослідження

Ці операції існують і доступні nysh op, але виконує їх людина, а не ти: побачивши їх у переліку, не роби з цього дозволу.

Якщо тебе питають, чого бракує¶

Не канону: він є, і вести його — твоя робота (canon.md). Знахідка йде з прочитаного в канон у такому порядку: запис аркуша (pages.note, records.add) → кроп (text.crop) → доказ у стор (evidence.add) → картка → canon.check → canon.index. Вердикт «це наш рід» при цьому виносить людина; ти вносиш те, що вона підтвердила, або кладеш гіпотезу з позначкою hypothesis.