# UVZ Local Library MCP

Локальная база знаний для GigaCode по Jimmer, внутренним библиотекам,
приложениям, конфигурации и инженерным стандартам.

Проект индексирует исходники в SQLite FTS5 и подключает их к агенту через
локальный stdio MCP. Внешняя сеть и удалённый MCP-сервер не нужны.

## Что получает агент

- поиск по Java, Kotlin, frontend-коду, документации и примерам;
- проверенные карточки `project-context.yaml` с назначением проекта;
- общий `system-overview.md` для межпроектных потоков и границ системы;
- проверяемый `knowledge-glossary.yaml` для внутренних терминов, сокращений и
  русско-английских поисковых aliases;
- golden path примеры из `docs/usage/*.md`;
- точные Gradle aliases из `uvz-platform`;
- реальные Gradle consumers внутренних библиотек;
- YAML-конфигурацию из приложений и нескольких наборов `uvz-config`;
- explainable Spring YAML resolution по application name, ordered profiles и
  imports с provenance, `resolution_complete` и SSL bundle inventory;
- source id, repository, commit, path и строки для каждого ответа;
- кликабельные commit-pinned ссылки на source-файлы в GitHub и Bitbucket
  Server, построенные только из фактического индексированного Git remote;
- Git remote, branch, commit time, sync/provenance status каждого repository;
- русско-английскую нормализацию запросов, проверяемое расширение русских
  backend/Jimmer-терминов к англоязычной документации, aliases из
  `project-context.yaml` и безопасный exact → relaxed fallback;
- отдельное объяснение поиска без выдачи исходного текста: normalized terms,
  alias/bilingual expansion, exact/relaxed stages, coverage, ranking и
  provenance;
- измеримый context coverage по каждому Gradle-модулю и автоматически
  проверяемый retrieval case для каждой curated-карточки и usage-примера.

При поиске приоритет такой:

1. `system-overview.md`, `knowledge-glossary.yaml` и `project-context.yaml` —
   архитектурная маршрутизация, термины, назначение и границы использования;
2. `docs/usage/*.md` — рекомендуемый способ подключения;
3. документация и тестовые примеры;
4. исходный код и конфигурация.

## Как устроен процесс

```text
Исходные repositories
        ↓
project-context.yaml + docs/usage
        ↓
Индексация и quality gate
        ↓
knowledge-pack-<version>.zip
        ↓
./install.sh у разработчика
        ↓
GigaCode → local-library-mcp → SQLite
```

Есть две роли:

- **Maintainer** имеет все repositories, готовит контекст, строит и публикует
  knowledge pack.
- **Developer** получает этот проект с готовым pack и запускает только
  `./install.sh`.

## Требования

Для maintainer:

- Git;
- Python 3.9 или новее;
- GigaCode;
- доступ к индексируемым repositories.

Для developer достаточно Python 3.9+ и GigaCode. Docker, Node.js, Rust, Cargo и
Xcode Command Line Tools не нужны. Runtime MCP использует только стандартную
библиотеку Python.

На Windows установку запускай из Git Bash с нативным Python 3.9+. Installer
выполняет stdio smoke test, который отдельно проверяет передачу русского текста
в UTF-8 и останавливает установку при повреждённой кодировке.

## 1. Первая установка maintainer

Все индексируемые Git repositories должны находиться внутри одной workspace:

```text
/path/to/projects/
  uvz-local-library-mcp/
  jimmer/
  jimmer-doc/
  jimmer-examples/
  uvz-platform/
  uvz-config/
  schedulex/
  other-projects/
```

Клонируй MCP-проект:

```bash
PROJECTS=/path/to/projects
cd "$PROJECTS"
git clone git@github.com:asimmetria/uvz-local-library-mcp.git
cd uvz-local-library-mcp
```

Первичная индексация одновременно установит MCP и основной skill:

```bash
./install.sh \
  --workspace "$PROJECTS" \
  --sync \
  --configuration-root "$PROJECTS/uvz-config"
```

Если рабочая ОС использует нестандартные домашнюю папку и Python:

```bash
GIGACODE_HOME="/path/to/.gigacode" \
MCP_RUNTIME_HOME="/path/to/projects/.mcp-runtime" \
PYTHON_BIN="/path/to/.gigacode/.venv/bin/python" \
./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --configuration-root "/path/to/projects/uvz-config"
```

После установки перезапусти GigaCode.

Чтобы после `git pull` обновить только MCP runtime и основной skill, не
переиндексируя workspace и не устанавливая случайно старый pack из `dist`,
используй:

```bash
./install.sh --runtime-only
```

Режим требует существующую `knowledge.db`, запускает transport/UTF-8 smoke test
и гарантированно не заменяет базу.

### Что делает `--workspace`

- находит каждый Git repository рекурсивно и индексирует его один раз;
- обнаруживает Gradle-модули, в том числе библиотеки внутри приложений;
- отдельно индексирует Jimmer docs/examples;
- для Docusaurus пропускает переводы из `i18n`, если есть канонические docs;
- сопоставляет каждый Gradle-модуль с context-карточкой или доказанным
  `no_context_required`;
- объединяет ручные business cases с автоматически созданными context/usage
  cases;
- строит новый индекс во временной папке;
- заменяет рабочую базу только после успешных проверок.

`--configuration-root` не индексирует repository повторно. Он помечает
центральный конфигурационный repository и его наборы конфигураций.

### Общая архитектура и внутренние термины

Для знаний, которые относятся сразу к нескольким repositories, положи в корень
одного индексируемого приватного repository:

```text
system-overview.md
knowledge-glossary.yaml
```

Первый файл описывает приложения, владельцев данных, основные потоки и
платформенные правила. Второй связывает канонические термины из кода с русскими
названиями и внутренними сокращениями. Оба валидируются при индексации и
получают приоритет `context`; glossary aliases участвуют в объяснимом расширении
поискового запроса.

Не создавай эти файлы в каждом проекте. Для общей системы рекомендуется один
reviewed источник, например индексируемый `uvz-ai`; отдельные bounded contexts
могут иметь собственные overview/glossary только при явной необходимости.
Шаблоны и полный контракт: [workspace knowledge](docs/workspace-knowledge.md).

## 2. Подготовка `project-context.yaml`

Authoring skill устанавливается только maintainer-у:

```bash
./scripts/install-project-context-authoring.sh
```

После установки перезапусти GigaCode. Workspace обрабатывает один основной
агент, без субагентов. Shell tool у него отключён, поэтому он не сможет обходить
file-editing policy через heredoc или перенаправление вывода.

### Последовательная обработка всей workspace

Перед запуском проверь через `/mcp`, что `local-library-mcp` подключён и
показывает campaign tools `project_context_campaign_next`, `start`, `finish` и
`report`, а также `validate_project_context`. Затем запусти runner из MCP
repository:

```bash
cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects"
```

Другой разработчик заменяет абсолютные пути на свои.

Runner:

- находит все Git repositories и передаёт их одному основному GigaCode-агенту;
- основной агент обрабатывает repositories строго последовательно и не запускает
  субагентов;
- включает `auto-edit`, заранее разрешает read-only MCP tools
  `suggest_dependency`, `find_library_usages`, `validate_project_context` и
  отдельно четыре ограниченных campaign-state tools;
- полностью отключает agent/subagent и shell tools;
- не проверяет dirty как условие допуска: незакоммиченные repositories тоже
  обрабатываются, а существующие изменения запрещено сбрасывать или затирать;
- перед каждой попыткой controller сохраняет fingerprint файлов вне authoring
  scope; при изменении любого такого файла repository получает terminal
  `failed`, а третья попытка запрещена;
- сразу после каждого repository атомарно записывает `successful`, `failed`
  или `no_context_required`;
- разрешает отдельный итог `no_context_required` только для repository без
  build/source signals, с русской причиной и существующим relative evidence;
- делает не больше двух попыток на один repository;
- требует `VALIDATION_OK` внутри попытки, чтобы агент сразу видел и исправлял
  точные ошибки schema и paths;
- требует русский `summary`, сохраняет явные `unknowns` и независимо проверяет
  полноту module coverage при `finish`;
- после agent session повторно запускает deterministic validator для всех
  успешных карточек;
- создаёт агрегированный review-файл с результатом каждого repository.

State локален и игнорируется Git:

```text
.project-context-authoring-campaign.json
.project-context-authoring-review.json
```

State содержит имя, локальный путь, status, число попыток, summary, unknowns,
coverage и fingerprint релевантных файлов. Review удобен для общего просмотра:
в нём есть totals, агрегированное покрытие, failures и доказанные exemptions.
Оба файла локальны и игнорируются Git.

После прерывания просто повтори ту же команду. Неизменённые `successful` и
`no_context_required` не обрабатываются повторно. Controller автоматически
возвращает ровно нужный repository в `pending`, если изменился его source,
build descriptor, README/docs, `project-context.yaml` или `docs/usage`, либо
если deterministic coverage перестал сходиться. Для переоткрытого repository
начинаются новые две попытки, а причина записывается в `last_invalidation`.
Для сознательного полного перезапуска используй `--restart`: старый state
копируется в timestamped backup.

Чтобы repository индексировался, но authoring-skill не создавал в нём
`project-context.yaml` и `docs/usage/*.md`, используй отдельный список:

```bash
cp project-context-exclude.example.txt project-context-exclude.txt
```

По умолчанию шаблон содержит `uvz-ai`: его документы остаются в индексе, но
authoring-кампания его не обрабатывает. `index-exclude.txt` остаётся общим
исключением: перечисленные там repositories не участвуют ни в индексации, ни в
authoring.

```bash
cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" --restart
```

### Восстановление state после старого validator workflow

Версии до MCP `1.4.0` сохраняли только общую ошибку `Deterministic validation
failed after the agent session`, поэтому повторная попытка не знала, что именно
исправлять. После обновления один раз верни только такие записи в очередь:

```bash
cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" \
  --reset-validation-failures
```

Успешные и ещё не обработанные repositories не сбрасываются. Для возвращённых
записей начинается новый лимит из двух попыток уже с validator feedback внутри
agent session. В следующих запусках этот флаг не нужен.

Версии до single-active state invariant могли оставить несколько repositories
в `running`, если агент вызвал `next/start` до `finish`. После обновления один
раз восстанови только такие прерванные записи:

```bash
cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" \
  --reset-interrupted-failures
```

Controller сначала переводит stale `running` в interrupted `failed`, затем
возвращает только их в `pending`. Успешные repositories и failures с другими
причинами не меняются. Новая версия запрещает второй `running` технически.

### Точечное исправление после неуспешной индексации

Не перезапускай authoring для всей workspace. Построй точную очередь из
coverage-проблем и failed generated retrieval cases:

```bash
cd /path/to/projects/uvz-local-library-mcp
python3 scripts/plan-project-context-repair.py \
  --audit audit-failure.local.json \
  --evaluation evaluation-failure.local.json \
  --output project-context-repair.local.txt
```

Запусти отдельную resumable repair-кампанию только для этого списка:

```bash
PROJECT_CONTEXT_STATE_FILE="$PWD/.project-context-authoring-repair.local.json" \
PROJECT_CONTEXT_REVIEW_FILE="$PWD/.project-context-authoring-repair-review.local.json" \
PROJECT_CONTEXT_OUTPUT_FORMAT=text \
  ./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" \
  --include-file "$PWD/project-context-repair.local.txt"
```

Повторный запуск той же команды продолжает очередь. Каждая попытка получает
coverage-aware validator feedback: точные missing/invalid Gradle module paths и
usage-файлы, которые не находятся по собственному `examples.summary`.

Одна GigaCode API-сессия может завершиться по серверному лимиту времени. Runner
автоматически открывает следующую изолированную сессию с тем же state-файлом и
продолжает очередь. Безопасная остановка происходит после двух сессий без
прогресса либо после 50 сессий; оба лимита можно изменить через
`PROJECT_CONTEXT_MAX_EMPTY_SESSIONS` и `PROJECT_CONTEXT_MAX_SESSIONS`.
Сразу после обработки repository state-watcher печатает компактную строку
`[готово/всего] SUCCESS <repository> — <cards>; <modules>`; повторные попытки и
terminal failures также появляются немедленно.

Если raw live JSON слишком шумный, переключи вывод на обычный текст:

```bash
cd /path/to/projects/uvz-local-library-mcp
PROJECT_CONTEXT_OUTPUT_FORMAT=text \
  ./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects"
```

В `text`-режиме GigaCode печатает полный ответ только после завершения сессии.
Runner раз в 30 секунд выводит heartbeat с прошедшим временем, чтобы длительная
обработка большого repository не выглядела зависшей. Интервал можно изменить
через `PROJECT_CONTEXT_HEARTBEAT_SECONDS`.

Один repository можно обработать отдельно. В этом точечном режиме прежняя
строгая проверка не разрешает посторонние dirty-изменения:

```bash
./skills/project-context-authoring/scripts/run-project-context.sh \
  "/path/to/one-project"
```

### Проверка одного repository без индексации

```bash
python3 validate_project_contexts.py /path/to/project
```

Проверяются schema, русский текст, типы полей, структура suite, обязательные
разделы usage, lexical overlap с `examples.summary` и существование всех
относительных evidence paths. Каждый Gradle-модуль должен иметь карточку, быть
осмысленно включён в `modules` другой карточки либо иметь
`no_context_required` с русской причиной и evidence. Module IDs сверяются с
полными путями deterministic Gradle discovery.

Перед индексацией просмотри изменения и закоммить карточки в их repositories.
Verified-сборка по умолчанию принимает только чистые working trees и отдельно
доказывает, что каждая карточка и usage входят в `HEAD`.

```bash
git status --short
git diff -- .
```

## 3. Повторная и полная переиндексация

После подготовки карточек повтори maintainer-команду:

```bash
cd /path/to/projects/uvz-local-library-mcp

./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --configuration-root "/path/to/projects/uvz-config"
```

Успешная сборка создаёт:

- `knowledge.db`;
- `audit-summary.json`;
- `evaluation-summary.json`;
- `evaluation-cases.built.json`;
- `coverage-policy.built.yaml`;
- `skills/library-knowledge-workflow/generated-catalog.md`.

Если хотя бы одна карточка невалидна или quality gate не пройден, предыдущая
рабочая база не заменяется.

Обычная сборка выводит только три этапа, heartbeat раз в минуту и краткий итог.
Последняя строка самой индексации всегда однозначна:
`INDEX BUILD SUCCEEDED` или `INDEX BUILD FAILED`. Большие audit/evaluation JSON
в терминал не печатаются. При падении quality gate краткие причины остаются в
терминале, а полный отчёт сохраняется в ignored-файл
`evaluation-failure.local.json`. Подробности ingestion и списки проблемных
repository/module сохраняются в `audit-failure.local.json`; успешная следующая
сборка удаляет оба устаревших failure report.

Повторный запуск по умолчанию инкрементальный. Индексатор использует предыдущую
БД как read-only cache только после проверки её schema, SHA-256, audit,
успешного evaluation и publishable provenance. Для clean repository с тем же
commit, ролью configuration root и версией indexer contract переиспользуются
тяжёлые `chunks` и YAML values. Изменённый repository пересобирается целиком.

Cross-repository metadata всегда строится заново, даже для переиспользованного
source: `project-context.yaml`, usage paths, `uvz-platform` aliases, Gradle
consumers, ownership и coverage. Поэтому изменение только `uvz-platform`
обновляет dependency graph без повторного чтения всех исходников. Dirty source
никогда не берётся из verified cache. Повреждённый, устаревший или неполный
cache автоматически отбрасывается; сборка продолжает работу холодным способом.
Indexer contract учитывает отдельные `lexical_normalization.py` и
`configuration_index.py`, которые формируют индексные terms и YAML metadata.
Runtime-only изменения `lexical_search.py` и `configuration_model.py`, включая
query expansions, ranking и `resolve_config`, не обнуляют cache неизменённых
repositories.

Сведения `reused`/`rebuilt` по каждому repository не засоряют терминал и видны
в `audit-summary.json → incremental` и `source_revisions[].cache_status`.
Время стадий и каждого repository сохраняется отдельно в ignored
`build-performance.local.json`; этот недетерминированный файл не попадает в
pack. Он нужен, чтобы решать вопрос о file-level cache по замерам полного
workspace, а не по размеру репозиториев.
Игнорируемые Git-файлы не индексируются. Для диагностики или после изменения
правил индексирования можно явно запретить reuse:

```bash
./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --full-rebuild \
  --configuration-root "/path/to/projects/uvz-config"
```

Переход с schema version 5 на version 6 всегда делает первый запуск холодным:
предыдущая БД автоматически отклоняется как несовместимая. Следующий запуск при
тех же commits уже использует incremental cache.

`audit-summary.json → context_coverage` показывает покрытые, объяснимо
исключённые и missing Gradle-модули по каждому repository. Не-Gradle
repositories (например `jimmer-doc`) индексируются, но не входят в denominator.
Порог задаётся как `thresholds.min_context_coverage` в evaluation definition;
по умолчанию требуется не менее `0.8`. Invalid module claims и broken
`components` всегда блокируют сборку независимо от процента.

Внешние исходники и наборы примеров могут оставаться в поисковом индексе, не
притворяясь внутренними компонентами. Для них используется строгий
[`coverage-policy.yaml`](coverage-policy.yaml): точное имя repository, роль
`reference`, русская причина и committed evidence в одном из индексируемых
repositories. Wildcard запрещён; отсутствующий, неиндексируемый или
незакоммиченный evidence останавливает сборку. Преднастроенные правила покрывают
`jimmer` и `jimmer-examples`. Для внутренней reference-базы можно передать
отдельный файл через `--coverage-policy /path/to/coverage-policy.yaml`.

`evaluation-cases.built.json` создаётся автоматически на каждой сборке: ручные
cases сохраняются, затем добавляется один positive case на каждую
`project-context.yaml` и каждый объявленный `docs/usage/*.md`. Этот built-файл,
а не исходный шаблон, проверяется и попадает в knowledge pack.

Если рядом с `install.sh` существует reviewed `evaluation-cases.local.json`,
установщик автоматически использует его вместо базового definition. Явный
`--evaluation-cases /path/to/cases.json` имеет приоритет. Это не позволяет
случайно пропустить подготовленные dependency/configuration cases.

После первой сборки schema version 6 создай и вручную проверь три реальные
dependency graph cases, затем повтори сборку с локальным definition:

```bash
python3 scripts/draft-dependency-cases.py --limit 3

./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --configuration-root "/path/to/projects/uvz-config" \
  --evaluation-cases evaluation-cases.local.json
```

По умолчанию генератор выбирает только aliases внутренних библиотек, для которых
нашёл владельца в индексируемом workspace. Внешние Spring-зависимости и драйверы
не используются как эталонные cases. Генератор не перезаписывает
`evaluation-cases.local.json`; подробный review-flow
описан в [retrieval evaluation](docs/retrieval-evaluation.md). После проверки
каждого consumer поставь `dependency_case_draft.review_required: false`, иначе
quality gate намеренно не пройдёт.

### Проверка готовых ответов агента

После успешной сборки можно проверить уже не только retrieval engine, но и
реальные финальные ответы GigaCode. Публичные Jimmer cases запускаются так:

```bash
python3 scripts/run-agent-evaluation.py \
  --cases agent-evaluation-cases.json \
  --output agent-answers.local.json

python3 scripts/evaluate-agent-answers.py \
  --db knowledge.db \
  --cases agent-evaluation-cases.json \
  --answers agent-answers.local.json
```

Для полного рабочего индекса сначала создай внутренний draft из проверенных
context cards, связанных `docs/usage` golden paths, dependency graph и Spring
configuration:

```bash
python3 scripts/draft-agent-evaluation-cases.py \
  --db knowledge.db \
  --base agent-evaluation-cases.json \
  --output agent-evaluation-cases.local.json
```

По умолчанию выбираются по три cases каждой внутренней категории с приоритетом
разных repositories. Usage cases требуют точный source/commit и реальные
API/alias/config identifiers из golden path. Configuration cases проверяют не
сырой YAML, а effective value после `resolve_config` с module/configuration
set/profiles, source provenance и `resolution_complete`. Итоговый evaluator
отдельно показывает category-level pass rate, поэтому успех на
Jimmer-документации не маскирует ошибки использования/подключения внутренних
библиотек или разрешения конфигурации.

Просмотри все добавленные cases и поставь
`agent_case_draft.review_required: false`. До явного review runner и evaluator
откажутся использовать draft.

Если `project-context.yaml` или `docs/usage` были созданы или исправлены после
последней сборки, сначала закончи authoring, затем пересобери `knowledge.db` и
только после этого создавай новый draft. Draft хранит SHA-256 базы, поэтому его
нельзя использовать с другой индексацией. Во время уже запущенного benchmark не
обновляй проект, базу или установленный workflow skill.

Runner создаёт отдельную пустую временную workspace на каждый вопрос, исключает
shell/subagent/web search и оставляет в MCP allowlist только read-only tools
`local-library-mcp`. До первой сессии он проверяет schema cases и всё ожидаемое
indexed evidence против установленной `knowledge.db`; stale case не расходует
время модели. Evaluator сверяет cited sources/commits, `libs` aliases и
consumer edges с SQLite, требует явный отказ для неподтверждённого API и
запрещает прямые versioned Gradle dependencies. Answers version 2 привязаны к
точным SHA-256 базы, MCP runtime, workflow skill, runner, cases, модели и версии
GigaCode; `readiness_check.py` не принимает legacy-ответы без этой привязки.
Evaluator дополнительно группирует failures по category, стабильной причине и
области (`context`, usage, dependencies, configuration, provenance или agent
execution), чтобы следующий цикл улучшений опирался на измеримые провалы.
После прерывания повтори runner с `--resume`: он пропустит только успешные cases
при неизменных cases/model/GigaCode/runner/knowledge.db/runtime/skill. Без
`--resume` существующий output никогда не перезаписывается. Технический
`agent_error` или пустой ответ автоматически повторяется один раз; настройка
`--max-case-attempts N` меняет общее число сессий на case в одном запуске.
Во время каждого case runner раз в 30 секунд печатает heartbeat, а после него —
status и длительность; интервал настраивается через `--heartbeat N`.

Два summary сравниваются по fingerprint неизменившихся case definitions:

```bash
python3 scripts/compare-agent-evaluations.py \
  --baseline agent-evaluation-summary.before.local.json \
  --candidate agent-evaluation-summary.after.local.json \
  --fail-on-regression
```

Comparator отдельно показывает улучшенные, регрессировавшие и изменённые cases,
category deltas и изменение failure codes. Подробности — в
[agent answer evaluation](docs/agent-answer-evaluation.md).
Для внутренних вопросов используй ignored
`agent-evaluation-cases.local.json`. Полный формат и review-flow описаны в
[agent answer evaluation](docs/agent-answer-evaluation.md).

### Исключение repositories

Скопируй шаблон и укажи точные имена директорий, по одному на строку:

```bash
cp index-exclude.example.txt index-exclude.txt
```

Пример:

```text
old-project
experimental-service
```

`index-exclude.txt` не коммитится и автоматически применяется при индексации.

### Обновление исходников

Обычный `--sync` безопасен: dirty repositories и ветки с локальными commits он
не обновляет через Git, а причину записывает в audit. Verified-сборка теперь
останавливается на любом dirty repository, чтобы path и commit не противоречили
друг другу.

Для временной локальной проверки можно явно разрешить стабильный dirty working
tree:

```bash
./install.sh \
  --workspace "/path/to/projects" \
  --allow-dirty \
  --configuration-root "/path/to/projects/uvz-config"
```

Такой индекс получает provenance `dirty_allowed` и работает через MCP, но
`package_pack.py` гарантированно откажется его упаковывать. Перед публикацией
закоммить/stash изменения и повтори обычную сборку без флага.

Clean source без sanitised `origin` URL или с commit, отсутствующим в
`origin/*`, также пригоден для локального MCP, но имеет `publishable: false`.
Перед упаковкой каждый индексируемый SHA должен быть опубликован во внутреннем
Git и виден в актуальных remote-tracking refs.

Принудительное обновление всех repositories выполняется отдельно:

```bash
./scripts/force-sync-all.sh /path/to/projects
./scripts/force-sync-all.sh /path/to/projects --apply
```

Первая команда — dry run. Вторая переключает каждый repository на
`origin/master` или `origin/main` и удаляет локальные tracked-изменения. Она
ничего не push-ит и не удаляет untracked-файлы.

## 4. Создание knowledge pack

После успешной индексации:

```bash
python3 package_pack.py --version YYYY.MM.DD
```

Результат:

```text
dist/knowledge-pack-YYYY.MM.DD.zip
```

Pack содержит SQLite, catalog, manifest, audit, evaluation, точный набор
retrieval cases и exact coverage policy. Упаковка блокируется, если их hashes
не согласованы, любой retrieval/dependency/configuration/coverage gate не
пройден, хотя бы один source был dirty или curated-файл не подтверждён
указанным commit. Version допускает только portable имя без path separators;
одинаковые проверенные inputs и version дают побайтно одинаковый knowledge
pack.

Локальный индекс, собранный с `--allow-dirty`, не считается publishable. Для
внутренней проверки его можно упаковать только с явным experimental-флагом:

```bash
python3 package_pack.py \
  --version YYYY.MM.DD-experimental \
  --allow-experimental-provenance

python3 package_distribution.py \
  --pack dist/knowledge-pack-YYYY.MM.DD-experimental.zip \
  --allow-experimental-provenance
```

Experimental-статус записывается в оба manifest. Обычная упаковка, проверка и
установка продолжают его отклонять. Получатель должен явно выполнить
`./install.sh --allow-experimental-provenance`; это не превращает dirty evidence
в publishable и не скрывает provenance.

Для внутреннего trusted release один раз создай RSA-ключ вне repository и
закоммить только public key:

```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  -aes-256-cbc -out /secure/path/uvz-rag-signing-private.pem
openssl rsa -in /secure/path/uvz-rag-signing-private.pem \
  -pubout -out trusted-pack-key.pem
git add trusted-pack-key.pem
```

Приватный ключ никогда не клади в проект. Сборщик developer distribution
дополнительно блокирует любой tracked PEM private key. Перед подписанием
передай пароль ключа через переменную окружения, не через аргумент командной
строки:

```bash
read -r -s PACK_SIGNING_KEY_PASSPHRASE
export PACK_SIGNING_KEY_PASSPHRASE

python3 package_pack.py \
  --version YYYY.MM.DD \
  --signing-key /secure/path/uvz-rag-signing-private.pem \
  --signing-key-pass-env PACK_SIGNING_KEY_PASSPHRASE
```

Signed pack содержит RSA/SHA-256 подпись точных байтов manifest. Public key не
берётся из pack: доверенным считается только tracked `trusted-pack-key.pem` из
внутреннего repository. Поэтому подмена одновременно manifest и checksums
обнаруживается.

Для обновления уже установленной большой базы можно собрать exact page delta
между двумя approved packs:

```bash
python3 package_delta.py \
  --base-pack dist/knowledge-pack-YYYY.MM.DD.zip \
  --target-pack dist/knowledge-pack-YYYY.MM.DD-next.zip \
  --output dist
```

Packager переиспользует совпадающие SQLite pages и сохраняет только изменённые.
Если delta не меньше полного target pack, команда завершается ошибкой — в этом
случае распространяй обычный pack. Для signed packs передаются те же
`--trusted-public-key`, `--require-signature` и `--openssl`.

Для передачи коллегам одним готовым архивом сначала закоммить изменения самого
MCP-проекта, затем собери developer distribution:

```bash
python3 package_distribution.py \
  --pack dist/knowledge-pack-YYYY.MM.DD.zip
```

Результат:

```text
dist/uvz-local-library-mcp-YYYY.MM.DD.zip
```

Сборщик берёт только чистые Git-tracked файлы этого проекта и ровно один
проверенный knowledge pack. Локальные БД, campaign state, `.gigacode`, исходные
repositories и другие untracked/ignored файлы в архив не попадают. Knowledge
pack и внешний ZIP детерминированы: повторная сборка из тех же verified inputs,
version и project commit даёт те же байты. Внутри лежит
`distribution-manifest.json` с SHA-256 каждого файла.

Tracked generated-файлы, которыми управляет pack (`audit-summary.json`, catalog,
evaluation, coverage policy и `knowledge.db`), не считаются runtime-изменениями
и не дублируются во внешнем ZIP: installer атомарно извлекает их из вложенного
knowledge pack. Изменённые tracked runtime-файлы по-прежнему блокируют сборку.

Внутренний индекс содержит производные от исходников данные. Публикуй pack
только во внутренний Bitbucket/artifact storage. Не добавляй внутренний pack в
публичный GitHub repository.

Рекомендуемый способ распространения — developer distribution из предыдущего
шага либо versioned knowledge pack в `dist/` этого проекта во внутреннем
Bitbucket. В обоих вариантах разработчик получает один проект.

## 5. Установка у разработчика

При передаче developer distribution:

```bash
unzip uvz-local-library-mcp-YYYY.MM.DD.zip
cd uvz-local-library-mcp
./install.sh
```

Альтернатива — внутренний repository уже содержит
`dist/knowledge-pack-<version>.zip`:

```bash
git clone <internal-bitbucket>/uvz-local-library-mcp.git
cd uvz-local-library-mcp
./install.sh
```

Installer автоматически:

1. проверяет distribution manifest, если установка идёт из готового архива;
2. выбирает самый новый bundled pack;
3. для signed pack проверяет RSA/SHA-256 по tracked `trusted-pack-key.pem`, затем
   schema, размеры, SHA-256, все quality gates и publishable provenance;
4. атомарно устанавливает SQLite и отчёты;
5. добавляет `local-library-mcp` в GigaCode settings;
6. устанавливает основной `library-knowledge-workflow` skill;
7. запускает настоящий stdio MCP smoke test, включая `explain_search`.

После установки перезапусти GigaCode и проверь `/mcp`.

При прямой установке signed pack вне developer distribution явно передай ключ:

```bash
./install.sh \
  --knowledge-pack /path/to/knowledge-pack-YYYY.MM.DD.zip \
  --trusted-pack-key /path/to/trusted-pack-key.pem \
  --require-pack-signature
```

Разработчик с точной base-версией может установить меньший delta-архив:

```bash
./install.sh \
  --knowledge-delta /path/to/knowledge-delta-OLD--NEW.zip \
  --trusted-pack-key /path/to/trusted-pack-key.pem \
  --require-pack-signature
```

Delta не применяется «примерно к такой же» базе: проверяется SHA-256 каждого
байта base `knowledge.db`. Installer восстанавливает exact target DB во
временной директории, повторно проверяет target signature, hashes, schema и все
quality/provenance gates и только затем заменяет metadata и SQLite. Для первой
установки по-прежнему нужен полный developer distribution или knowledge pack.

Проверочный промт:

```text
Используя local-library-mcp, найди пример Jimmer Fetcher. Назови repository,
source id, path, commit и кратко объясни, что делает пример. Не отвечай без
ссылки на источник из локальной базы.
```

Developer не запускает индексацию и не устанавливает authoring skill.

## MCP-инструменты

| Инструмент | Назначение |
| --- | --- |
| `search_knowledge` | Exact/relaxed поиск context, usage, docs, examples и source; поддерживает точный `path` для перехода из карточки к связанному примеру/evidence |
| `lookup_exact_identifier` | Регистрозависимый literal lookup точного API/class/constant/config key без tokenization и relaxed fallback; возвращает source id, полный commit и provenance |
| `find_usage_example` | Детерминированно выбирает golden path, реальный consumer или официальный examples fallback и сразу возвращает фактический пример |
| `explain_search` | Диагностика normalization, alias expansion, exact/relaxed fallback, ranking и provenance без source content |
| `get_source` | Чтение найденного chunk или всех проиндексированных chunks файла через `whole_file: true` |
| `list_libraries` | Каталог библиотек, приложений и возможностей |
| `list_repositories` | Все repositories и количество проиндексированных данных |
| `suggest_dependency` | Подтверждённый `libs.<alias>` из `uvz-platform` |
| `find_library_usages` | Реальные consumer repositories/modules для библиотеки |
| `search_config` | Поиск исходных YAML/config-файлов |
| `resolve_config` | Explainable Spring YAML resolution: application scope, ordered profiles/imports, provenance и SSL bundles |
| `index_status` | Audit последней индексации |

Основные поисковые, source, usage, dependency и configuration-инструменты
возвращают `source_url`, когда Git remote распознан как GitHub или Bitbucket
Server. Ссылка всегда привязана к commit из индекса; локальные абсолютные пути
в неё не попадают. Для неизвестного Git host MCP не угадывает URL и оставляет
только source id, repository-relative path, commit и provenance.

В `project-context.yaml` не смешиваются внутренние `projects.*` accessors и
внешние `libs.*` aliases. Первые корректно связывают подмодули одного Gradle
build; вторые описывают подключение библиотеки из другого repository через
version catalog `uvz-platform`.

## Проверка проекта MCP

```bash
python3 -m unittest discover -s tests -v
python3 smoke_test.py
```

После сборки или установки запусти единый operational readiness check:

```bash
python3 readiness_check.py
```

Он повторно связывает `knowledge.db` с audit/evaluation/cases/policy, проверяет
schema и quality gates, считает repositories/chunks/aliases/usages/configuration,
а затем запускает настоящий stdio MCP. Для проверки эффективности рабочего
release добавь отчёт grounded-answer benchmark; readiness свяжет его с точной
БД и покажет model/GigaCode identity:

```bash
python3 readiness_check.py \
  --agent-evaluation agent-evaluation-summary.local.json \
  --require-agent-evaluation
```

Для maintainer-проверки полного roadmap добавь завершённую authoring campaign и
её свежий агрегированный review:

```bash
python3 readiness_check.py \
  --campaign-state .project-context-authoring-campaign.json \
  --campaign-review .project-context-authoring-review.json \
  --require-campaign \
  --agent-evaluation agent-evaluation-summary.local.json \
  --require-agent-evaluation
```

Campaign gate требует, чтобы каждый repository имел итоговый статус, не было
failed/pending/running, а каждый discovered module был покрыт карточкой либо
доказанным `no_context_required`. Изменённый или устаревший review отвергается.

В распакованном developer bundle можно также потребовать целостность внешнего
distribution manifest:

```bash
python3 readiness_check.py --require-distribution
```

Exit code `0` и первая строка `READY` означают, что выбранный набор проверок
пройден. `--json` и `--output /path/to/readiness.json` дают машиночитаемый
отчёт без внутренних данных в публичном repository.

## Дополнительная документация

- [План развития](ROADMAP.md)
- [Dependency usage graph](docs/dependency-usage-graph.md)
- [Retrieval и dependency graph evaluation](docs/retrieval-evaluation.md)
- [Модель project context](docs/curated-project-context.md)
- [Quality gate](docs/ingestion-audit.md)
- [Безопасная инкрементальная индексация](docs/incremental-indexing.md)
- [Knowledge packs](docs/knowledge-packs.md)
- [Retrieval evaluation](docs/retrieval-evaluation.md)
- [Agent answer evaluation](docs/agent-answer-evaluation.md)
- [Конфигурация](docs/configuration-model.md)
- [Синхронизация исходников](docs/source-sync.md)