Перша сесія¶
Кроки названо іменами операцій: nysh op <ім'я> дістане будь-яку з них, а
nysh op <ім'я> --describe покаже аргументи, нічого не виконуючи. Там, де є
дружня команда (nysh doctor, nysh profile), вона зручніша — друкує для ока.
Сім кроків, приблизно п'ять хвилин. Кожен існує тому, що пропуск саме цього кроку вже коштував комусь роботи — не тому, що «так заведено».
Формат кожного: що робиш → чому це не формальність → ✅ приймач → якщо приймач червоний.
0. Розкажи людині, що відбувається¶
Перш ніж виконати першу команду, у п'ять-сім речень поясни людині, що таке Нишпорка і що буде далі. Це помічник генеалога на її комп'ютері: каталоги архівів, читання рукописних сканів, пошук роду в прочитаному з показом рядка на скані, родовід. Вікно в браузері показує, що зроблено, а дослідження ведеш ти. Далі буде знайомство на кілька кроків: машина, прізвище роду, скани, пробний пошук.
Людина щойно поставила програму і бачить лише потік команд. Без цього пояснення вона не розуміє, де вона й навіщо кожен крок (відеоурок, 16.10.2026).
✅ Приймач: людина відповіла, що можна починати.
1. Де я і хто ще тут¶
workspace.info
Простір — це тека з дослідженням: скани, машинний текст, облік переглянутого. Він не там, де лежить пакет, і не там, звідки тебе запустили.
✅ Приймач: у відповіді є root, case_roots і — головне — locked_by.
"origin": "env:NYSHPORKA_WORKSPACE",
"case_roots": ["…/data/raw"],
"locked_by": null
locked_by: null— простір вільний.locked_by: {...}— людина працює в браузері просто зараз. Твої записи ляжуть поруч із її, реєстр під тобою мінятиметься, а твій зріз старітиме швидше, ніж ти його читаєш. Це не заборона працювати, це причина частіше перезбирати реєстр і не робити висновків про «нічого не змінилось».
🔴 Якщо origin — package або last-used, простір знайдено здогадом.
Перепитай людину, чи це справді її дослідження: працювати не в тій теці гірше,
ніж не працювати зовсім. ⚠ last-used тепер трапляється по-справжньому — його
пише nysh init, — але здогадом бути не перестав: простір міг бути створений
іншою сесією для іншого дослідження.
Надійні походження — explicit, env:NYSHPORKA_WORKSPACE (і легасі
env:MEGEN_ROOT) та marker: перші два назвала людина, третій означає, що ти
стоїш усередині простору.
Червоний приймач: якщо приходить попередження empty_workspace — простору
ще немає як дослідження. Створює його людина: nysh init <тека>. Якщо простір
Є, а команду треба спрямувати саме в нього разово —
nysh --workspace <тека> <команда>.
2. Чи ця машина потягне¶
nysh doctor --json (команда; операція — setup.check)
Сім перевірок, і кожна стереже тиху поломку. Гучні себе виявляють самі; ці ні — вони виглядають як «повільно», «нічого не знайшлось» або «модель зламана».
✅ Приймач: жодної перевірки з рівнем fail.
Дві, які варто прочитати, навіть якщо все зелене:
- хмарна синхронізація — простір у теці OneDrive/Dropbox означає, що файли підвантажуються з мережі на вимогу. Обхід двох тисяч сторінок «зависає» без жодної помилки;
- PDF справ у хмарі — PDF, які хмара вивантажила («лише онлайн»), реєстр
не відкриває, бо відкриття стягнуло б їх цілком. Знаменник таких справ
неточний. Порада в рядку: людина позначає теки «Always Keep on This Device»
або один раз запускає
nysh cases build --fetch-cloud. Пораховане запам'ятовується, і вдруге файл не відкривається. Те саме попередження друкує й сама перебудова; - прискорення (GPU) — перевіряється не «чи встановлено torch», а чи бачить він карту. CPU-збірка не падає, вона просто рахує вчетверо довше: щільна сторінка ~1 хв замість ~15 с (заміряно 01.10.2026: 6-ядерний ноутбук проти GTX 1650). Справа на 300 аркушів — це різниця між годиною і п'ятьма, і саме її потім описують як «зависло».
Червоний приймач: порада на лікування стоїть у тому самому рядку. Виконує її людина, не ти, — це зміна її машини.
3. Чиє прізвище шукаємо¶
nysh profile (команда; операція — profile.show)
Найпропущеніший крок у всій сесії.
Профіль — це форми шуканого прізвища, його корені й те, як воно змінюється у відмінках.
⚠ Чого він НЕ робить: підставити чуже прізвище замість твого. q у пошуку
обов'язкове, дефолтного прізвища в пакеті немає ніде, і взятись йому нема
звідки. Ціна відсутнього профілю інша й тихіша: усі написання доводиться
пригадувати самому — а рушій калічить саме середину слова, тож половина форм
не спадає на думку взагалі, і нуль виходить із неповного набору.
✅ Приймач: команда друкує, скільки форм складено; самі форми й написання —
nysh profile show --json (поля forms і spellings), і в них ти впізнаєш те,
що просила людина.
Порожній приймач — це не відмова, а нормальний стан свіжої установки:
профіль дослідження не задано і немає `fallback` у …/config/research_profile.yaml
завести: `nysh profile init <Прізвище>` або у вікні застосунку, розділ «Рід»
🛑 Зупинись і спитай людину, яке прізвище шукаємо і в яких написаннях. Не здогадуйся з назви теки й не бери прізвище з першої знайденої справи.
✅ Приймач у вікні: після запису профілю (файлом чи nysh profile init)
прізвище стоїть у вікні Нишпорки, у розділі «Рід», а крок на головній зелений.
Нічого підключати не треба: застосунок перечитує файл, щойно той змінився.
Прізвища у вікні немає? Значить, вікно запущене старшою версією, і людина
перезапускає Нишпорку.
4. Що ввімкнено¶
nysh sections (команда; операція — sections.show)
Застосунок ставлять наборами: комусь потрібні лише каталоги, комусь читання рукопису, комусь усе. Вимкнена частина вимкнена всюди — і в браузері, і в командному рядку, і в тебе.
✅ Приймач: секції, потрібні для задачі, у переліку ввімкнених.
Червоний приймач: дізнаєшся про це не тут, а посеред роботи, відмовою виду «секція «читання» вимкнена у профілі простору». Увімкнення — рішення людини: воно тягне встановлення важких залежностей.
5. Що вже зроблено¶
cases.list
✅ Приймач — не перелік справ, а поле stale.
"stale": {"is": true, "reasons": ["у просторі щось міняли після збірки"],
"fix": "nysh cases build"}
Якщо stale.is — true, реєстр відстав, і будь-яке «декоду немає» в цій
відповіді ненадійне. Реєстр — зліпок кількох сховищ; він старіє за
хвилини, і застарілий небезпечніший за відсутній, бо виглядає як відповідь.
Червоний приймач: nysh cases build, і перепитай перелік.
Окремий випадок: попередження no_registry_yet — реєстру ще не збирали
жодного разу. Це нормальний стан щойно створеного простору, а не поламка.
6. Скани, які лежать не в просторі¶
nysh roots add <тека> — ціла тека зі сканами, без шифри
nysh case <тека> --shifra «…» --adopt — одна справа з описом
(операція є лише в другого: case.register, поле adopt)
Бібліотека обходить data/raw і оголошені корені справ — більше нічого.
Тека на зовнішньому диску, в мережевій шарі чи просто на робочому столі в цей
перелік не входить, а саме туди й показує людина, яка щойно поставила
застосунок.
Поразка тут мовчазна: опис у теку запишеться, ✅ покажеться, справи в переліках не буде. Далі кожен наступний крок відмовляє з власної причини — реєстр порожній, обліку нема куди лягти, пошук нічого не знаходить, — і жодна з причин не називає справжньої.
✅ Приймач: шлях з'явився в case_roots у відповіді workspace.info.
Червоний приймач: попередження outside_workspace означає, що теку описано,
але під облік не взято. Перелік оголошеного — nysh roots list; він називає й
корінь, чия тека зникла (від'єднаний диск), бо інакше справи просто пропадають
із реєстру без причини.
🛑 Оголошення кореня — це розширення зони, у якій застосунок дозволяє собі
читати диск, тож рішення людини: спитай, перш ніж оголошувати. Файли при цьому
не переносяться, тека лишається там, де лежить, а зняти оголошення можна
nysh roots remove.
⚠ Шифра потрібна лише для однієї справи. Тека-контейнер, у якій лежать десятки
книг, справою не є: дати їй шифру означало б оголосити їх однією справою, тому
контейнер бере саме nysh roots add.
7. Що вже бачило око¶
pages.status <справа> — перед будь-яким переглядом, не після.
Найдорожча помилка в довгій справі — передивитись ті самі аркуші вдруге.
Сторінки зі станом full уже розібрані: прізвища з них виписані, і шукати їх
треба пошуком по обліку, а не очима по сканах.
✅ Приймач: ти знаєш, скільки аркушів лишилось, і дивишся тільки їх.
Безкоштовна репетиція¶
Якщо в просторі є вкладена зразкова справа, пройди на ній увесь ланцюг перш ніж братись за справжній матеріал:
nysh sample # розгорне три аркуші з готовим машинним текстом
Далі: cases.list → search.run (знайди будь-яке прізвище з тексту)
→ page.view по line_index з хіта → pages.note. Командним рядком це
nysh op search.run --args ..., і так само для решти.
Це коштує хвилину й перевіряє найважливіше: що ти правильно зрозумів зв'язок
«хіт пошуку → рядок на зображенні». Прочитати ці аркуші заново можна після
nysh models get — але все, що йде після читання, працює й без ваг, бо декод
зразка вкладено в пакет.
Далі¶
- конвеєри роботи —
workflows.md - як читати відповіді —
envelope.md - чого я не вмію —
surface.md - як я вже помилявся —
antipatterns.md, і це варто прочитати до першого висновку, а не після нього