Automation

Updated Apr 17, 2026

[!lexery-hero] Automation !_assets/brand/lexery-wordmark-dark-bg.svg|200 !_assets/brand/lexery-icon.svg|46

Скрипти, стан, прогони maintenance. Lexery - Wiki North Star|North Star · Lexery - Wiki Quality Contract|Quality · Lexery - Data Integrity Dashboard|Integrity · Lexery - Ops Rollup|Rollup

SVG бренду: apps/portal/public/ → _assets/brand/.

[!info] Compiled from

_system/scripts/run-maintenance.mjs (source of truth for order and modes)

Практики спільноти Obsidian + LLM / “compiled wiki” (2025–2026)

Lexery - Automation Architecture

Канонічний опис як вікі сама себе підтримує: шари даних, оркестратор, скрипти, стан і зв’язок із сучасними патернами (не замінює Lexery - Wiki Quality Contract — там сигнали якості й межі automation).

0. Навіщо ця архітектура (не лише «скрипти»)

Автоматизація тут — не самоціль. Вона обслуговує North Star вікі: одна узгоджена картина для інженерів, маркетингу та агентів, з явним циклом ingest → compile → query → verify (див. Lexery - Wiki North Star). Скрипти — це нервова система compile+verify; граф, MCP і CLI — сенсорні органи для навігації та запиту контексту агентами. Якщо прибрати «навіщо», залишиться красивий Obsidian без стійкої правди.

У кожному прогоні karpathy-stack.mjs виконується одразу перед truth-audit.mjs і пише _system/state/karpathy-stack.json: чи живі raw/, чи на місці канонічні сторінки та AGENTS.md — швидкий сигнал, що Karpathy-шар не розвалився; ці ж дані потрапляють у Lexery - Data Integrity Dashboard.

1. Шари (industry alignment)

Патерн у індустрії	Як це в Lexery LLM Wiki
Compiled wiki (сирі артефакти → структуровані нотатки, мінімум “плоского RAG”)	`raw/` лише зчитується скриптами; зміст збирається в `Lexery - *.md` з wikilink-графом
Frontmatter як API для людей і агентів	Обов’язкові `status`, `layer`, `updated`; опційно `type` — див. AGENTS.md
MCP / CLI для запиту вікі з агентів	Локальний stdio MCP + CLI у `tools/lexery-wiki-mcp/` (`pnpm wiki:*`); не замінює cold-pass у `raw/`
Інтерактив / live для “гарячих” зрізів	Supabase/R2 тощо поза щоденним cold-pass; cold — git, GitHub, Linear у `raw/`
Довіра та drift замість лише “красивого графа”	`truth-audit`, `enforce-provenance`, Lexery - Wiki Quality Contract, `truth-history.jsonl`
Digital garden + CI на vault	`run-maintenance.mjs` + `lint.mjs` як локальний/launchd “CI”; deep-режим додає граф-метрики

Три шари Karpathy-стилю в цій вікі:

raw/ — незмінні відносно ручного редагування експорти (джерело для скриптів).
Wiki — зібрані сторінки з посиланнями та таблицями в маркерах auto-fill.
AGENTS.md + ця сторінка — контракт для агентів і операторів.

1.1 MCP і CLI для будь-якого агента (без хостингу)

У монорепо: tools/lexery-wiki-mcp/ — read-only stdio MCP (server.mjs) і CLI (cli.mjs) на тій самій логіці. Корінь вікі задається LEXERY_WIKI_ROOT або LEXERY_MONOREPO_ROOT (див. tools/lexery-wiki-mcp/README.md та docs/lexery-agent-wiki-access.md у репо). З кореня репо: pnpm wiki:doctor, pnpm wiki:brief, pnpm wiki-mcp. Нічого не публікується в інтернет — лише локальні файли vault.

2. Режими оркестратора

Файл: _system/scripts/run-maintenance.mjs.

За замовчуванням кожен 4-й запуск — deep (лічильник у _system/state/maintenance-state.json), решта — lite.
Примусово: WIKI_MAINTENANCE_MODE=lite або deep.
Після успішного циклу оновлюється maintenance-state.json; окремо викликається build-executive-dashboard.mjs (rollup для дашбордів).
Hero дашбордів (wordmark + icon + рядок apps/portal/public/ → _assets/brand/) зашитий у шаблонах: build-executive-dashboard.mjs, truth-audit.mjs, auto-fill.mjs, link-metrics.mjs, suggest-links.mjs, maintenance-rollup.mjs — щоб maintenance не «скидав» візуальну узгодженість. Той самий [!lexery-hero] використовується на статичних hub-сторінках; актуальний склад hub-ів веди узгоджено з Lexery - Index (швидка навігація + таблиці за темами), а не як довгий «заморожений» перелік у цьому документі — інакше з’явиться drift між текстом і vault.
У режимі deep після основного ланцюга додається maintenance-rollup.mjs (пост-обробка логів/зведень).
У кінці logs/maintenance-YYYYMMDD.md дописується загальний wall time циклу; у stdout — один рядок Maintenance lite|deep complete in … ms.

Опційно: WIKI_AUTO_GIT_PUSH=1 — commit + push з кореня vault після прогону.

3. Ланцюг кроків (актуальний порядок)

flowchart TD
  A[scan-codebase] --> B[sync-git]
  B --> C[sync-github]
  C --> D[sync-linear]
  D --> E[scan-supabase]
  E --> F[generate-delta]
  F --> F1[repair-log-structure]
  F1 --> H[ingest]
  H --> G[update-log]
  G --> FD[log-dedupe-sections]
  FD --> I[auto-fill]
  I --> J[enforce-provenance]
  J --> K0[karpathy-stack]
  K0 --> K[truth-audit]
  K --> L[contradiction-audit]
  L --> M[build-executive-dashboard]
  M --> N{deep?}
  N -->|yes| O[suggest-links]
  O --> P[link-metrics]
  N -->|no| Q[apply-pipeline-backbone]
  P --> Q
  Q --> R[prune-logs]
  R --> S[lint]

Таблиця ролей (скорочено; деталі в заголовках скриптів):

Скрипт	Роль
`scan-codebase.mjs`	Знімок monorepo: коміти, гілки, тести, workflow, копії arch docs у `raw/`
`sync-git.mjs`	Відстежувані репо, SHA, дайджести в `logs/`; у `state/repos.json` для плейсхолдера без клону — `"skip_git_scan": true` + порожній `path` (без WARNING у логу)
`sync-github.mjs`	PR через `gh` → `raw/github-prs/`, `state/prs.json`
`sync-linear.mjs`	Linear GraphQL за наявності ключа; без ключа — тихий skip (`console.log`, не warning)
`scan-supabase.mjs`	Запит на ручний/Ops refresh у `raw/codebase-snapshots/`
`generate-delta.mjs`	Зведення дельт (до ~8k символів контексту), LLM + `cost.json`; вихід проходить `wiki-link-sanitize.mjs` (фантомні wikilink → текст або посилання на Index)
`repair-log-structure.mjs`	Нормалізує Lexery - Log: один `# Lexery - Log` одразу після frontmatter, без дублікатів H1
`log-dedupe-sections.mjs`	Після `ingest` + `update-log`: усі `## [та сама дата] ingest \|…` зливає в одну секцію (об’єднання bullet за шляхом); далі прибирає ідентичні заголовки ingest / дублікати `Automated Sync` з тим самим тілом; fenced ``` ігноруються при розбитті
`ingest.mjs`	Облік `raw/` у `ingested.json` за sha256 вмісту; нові шляхи за сьогоднішньою датою зливаються в перший** існуючий `## [date] ingest \|…` (оновлення bullet і лічильника), інакше — prepend; після запису — `ensureLogStructure`
`update-log.mjs`	Вставка дельти одразу після H1, над ingest (sanitize); якщо сьогоднішній `Automated Sync` уже є — пропуск, але оновлює цю секцію, коли `delta-summary` новіший за запис у `state/update-log-delta-stamp.json`
`auto-fill.mjs`	Таблиці PR, швидкості комітів, посилання на Linear у цільових сторінках
`enforce-provenance.mjs`	Перевірка джерел / винятків для observed-сторінок
`karpathy-stack.mjs`	Зріз цілісності Karpathy-шару → `state/karpathy-stack.json` (перед truth-audit)
`truth-audit.mjs`	raw↔wiki drift, provenance, trust → `truth-audit.json`, `truth-history.jsonl`
`contradiction-audit.mjs`	Евристики суперечностей → `contradiction-audit.json`
`build-executive-dashboard.mjs`	Lexery - Executive Ops Dashboard, тренди trust
`suggest-links.mjs`	Deep: пропозиції зв’язків, Neural hub
`link-metrics.mjs`	Deep: Lexery - Graph Metrics, `link-graph.json`
`apply-pipeline-backbone.mjs`	Узгодження міток/каркасу pipeline на сторінках
`prune-logs.mjs`	Ротація старих логів
`lint.mjs`	Биті лінки, сирі сторінки, frontmatter, orphans → `logs/lint-report-*.md`

4. Сховище стану (`_system/state/`)

Файл	Призначення
`repos.json`	Шляхи до monorepo, останні SHA
`prs.json`	Курсор обробки PR
`issues.json`	Linear snapshot
`ingested.json`	Які `raw/` файли вже обліковані
`cost.json`	Накопичена вартість LLM-викликів
`maintenance-state.json`	Лічильник прогонів, останній deep
`update-log-delta-stamp.json`	Дата + mtime останнього `delta-summary`, з яким уже змерджений сьогоднішній `Automated Sync`
`truth-audit.json`	Знімок останнього truth-прогону
`truth-history.jsonl`	Історія trust (trim у скрипті)
`contradiction-audit.json`	Останній contradiction pass
`link-graph.json`	Експорт ребер для графа / зовнішніх інструментів
`karpathy-stack.json`	Здоров’я шару raw + compile + schema (`karpathy-stack.mjs`)
`karpathy-history.jsonl`	Історія score після кожного karpathy-прогону (trim ~800 рядків)

5. Планування (macOS)

Wrapper: _system/scripts/install-schedule.sh → LaunchAgent (логін + щоденний інтервал; деталі в Lexery - Maintenance Runbook).
Логи launchd: _system/logs/launchd-stdout.log, launchd-stderr.log.
Секрети: лише ~/.lexery-wiki-env (див. SECURITY.md і README).

6. Інтерактивне доповнення (MCP)

Автономний цикл збирає cold дані. Hot зрізи (Supabase, R2, …) — під час сесій з MCP; не змішувати з часом оновлення raw/ без явного пояснення на сторінці.

Окремий MCP для самої вікі (будь-який агент — Cursor, Claude, тощо): репозиторій Lexery, каталог tools/lexery-wiki-mcp/ — read-only пошук і читання сторінок vault через LEXERY_WIKI_ROOT; див. README у тому каталозі та розділ MCP у кореневому README вікі.

MCP / інструмент	Типове використання
Supabase (legal agent DB)	Живі метрики run/session/memory для дашбордів
Supabase (legislation)	Корпус, імпорти
Cloudflare R2	Інвентарі файлів case law / legislation

7. Результати прогонів

Конкретні цифри з минулих днів швидко застарівають. Актуальний слід: _system/logs/maintenance-*.md, Lexery - Log, Lexery - Data Integrity Dashboard, Lexery - Executive Ops Dashboard.