Document external import roots and checked tidy migration

content/docs/cli/package-manager/index.mdx

@@ -33,6 +33,38 @@ Module commands and <code>get</code> find the nearest ancestor <code>protobuf.mo
 
 Major versions use Go-style identities: v0/v1 are unsuffixed; v2+ requires matching <code>/vN</code>. The <code>+incompatible</code> exception requires verified pre-native metadata; it never bypasses a native manifest. See [exact grammar and Git mapping](/docs/reference/protobuf-mod).
 
+## Dependencies without import-root metadata
+
+Roots normally come from the pinned dependency's `protobuf.mod`, Buf or legacy EasyP config. A native manifest with omitted roots still declares `.`. Invalid metadata is an error.
+
+For an already declared dependency without root metadata, resolution identifies roots only from imports inside that dependency. If `api/service/v1/a.proto` imports `service/v1/b.proto`, the matching dependency file `api/service/v1/b.proto` establishes root `api`. External consumer imports only validate the resolved namespace; they never choose its roots. Without enough internal evidence, the default `.` remains or an explicit hint is required:
+
+~~~bash
+easyp get --import-root api/svc/v1 gitlab/products/svc
+~~~
+
+Repeat `--import-root` for multiple directories. Fetched Git hints are relative to the pinned repository snapshot: for `repo/sub/protobuf.mod` declaring `roots proto`, use `--import-root sub/proto`. Local replacement hints are relative to the replacement directory. Producer roots remain relative to their declaring manifest and are rebased by the Git adapter. Hints must stay within the source boundary and agree with authoritative roots. Verified fallback roots are recorded in the dependency's `protobuf.lock` entry. Frozen and cold-cache operations replay that choice; resolution failures leave the manifest and lock unchanged.
+
+To generate the required dependency, select its identity in `easyp.gen.yaml`:
+
+~~~yaml
+version: v1
+generate:
+  modules:
+    - gitlab/products/svc
+plugins: []
+~~~
+
+Resolved roots determine protobuf filenames. Module-local `paths` and `packages` restrict generation; paths refer to the external module directory. Add your local module to `modules` when both should generate. Root selection does not rewrite source imports or require a generation filter repeating the root.
+
+## Root changes during dependency updates
+
+When a new revision introduces authoritative roots, EasyP compares their protobuf filenames with the prior pinned fallback namespace. This also covers the metadata-free default `.`, even when the old lock omits `roots`. Moving physical directories while keeping the same import names is valid. A namespace shift stops implicit update before writing manifest/lock and reports old/new revisions, roots and representative renamed imports.
+
+To accept the new revision, change its requirement in `protobuf.mod` and run `easyp mod tidy`. Tidy updates consumer import declarations when the old and new pinned namespaces prove one source binding, including when another file has taken the old import name. It validates the proposed imports before committing source edits and manifest/lock together, then reports applied renames. Comments, line endings and unrelated strings remain intact. Tidy uses declared versions; it does not upgrade them by itself.
+
+An ambiguous mapping or deleted imported source stops before project writes and explains which import needs attention. Dependencies and cached source files are never rewritten. Review generation selectors and SDK output paths separately. If imports are already adjusted, explicitly adopt with `easyp get --import-root api gitlab/products/svc@<new-version>`, or keep the prior version. Producer metadata remains authoritative; hints must match it and import/integrity checks still pass.
+
 ## Commands
 
 | Command | Behavior |
@@ -59,7 +91,7 @@ Commit <code>protobuf.mod</code> and <code>protobuf.lock</code> for repeatable b
 
 ## Dependencies using Buf or older EasyP
 
-A Git dependency may declare its proto roots in <code>buf.work.yaml</code>, Buf v1 or v2 <code>buf.yaml</code>, or an older EasyP <code>easyp.yaml</code>. Older EasyP <code>protobuf.mod</code> requirements are also read transitively. If none of those files exists, its repository root is used. This compatibility applies to dependency metadata; the consuming project uses v1 <code>protobuf.mod</code>.
+A Git dependency may declare its proto roots in <code>buf.work.yaml</code>, Buf v1 or v2 <code>buf.yaml</code>, or an older EasyP <code>easyp.yaml</code>. Older EasyP <code>protobuf.mod</code> requirements are also read transitively. Without root metadata, dependency-internal import evidence or checked hints may establish fallback roots; otherwise its repository root is used. Recorded fallback roots are replayed from <code>protobuf.lock</code>. This compatibility applies to dependency metadata; the consuming project uses v1 <code>protobuf.mod</code>.
 
 When adapting an older <code>easyp.yaml</code>, both <code>deps</code> and generation Git inputs contribute requirements. Exact source/version duplicates are removed; different minimums remain visible to MVS, and malformed deps fail explicitly. A matching native <code>protobuf.mod</code> takes precedence. Only metadata is read; dependency plugins are never executed.
 

content/docs/cli/package-manager/index.ru.mdx

@@ -33,6 +33,38 @@ require (
 
 Мажорные версии используют идентичность как в Go: v0/v1 — без суффикса, v2+ — с соответствующим <code>/vN</code>. Исключение <code>+incompatible</code> требует проверки домодульных метаданных и не обходит нативный manifest. См. [точную грамматику и Git mapping](/ru/docs/reference/protobuf-mod).
 
+## Зависимости без метаданных корней импортов
+
+Обычно roots берутся из закреплённого `protobuf.mod`, Buf или legacy-конфига EasyP зависимости. Native-манифест без явного roots всё равно задаёт корень `.`. Некорректные метаданные вызывают ошибку.
+
+Для уже объявленной зависимости без метаданных корней резолвер определяет roots только по импортам внутри самой зависимости. Если `api/service/v1/a.proto` импортирует `service/v1/b.proto`, файл зависимости `api/service/v1/b.proto` задаёт root `api`. Импорты внешнего потребителя только проверяют разрешённое пространство имён и не выбирают его roots. Если внутренних данных недостаточно, сохраняется корень `.` либо требуется явная подсказка:
+
+~~~bash
+easyp get --import-root api/svc/v1 gitlab/products/svc
+~~~
+
+Для нескольких каталогов повторите `--import-root`. У загруженной Git-зависимости путь считается от закреплённого снимка репозитория: для `repo/sub/protobuf.mod` с `roots proto` используйте `--import-root sub/proto`. У локальной замены путь считается от каталога замены. Корни производителя остаются относительными к объявляющему manifest; Git-адаптер приводит их к координатам снимка. Подсказки должны оставаться внутри границы источника и согласовываться с его метаданными. Проверенные fallback-корни записываются в запись зависимости в `protobuf.lock`. Frozen и холодный кеш используют этот выбор; ошибки оставляют manifest и lock неизменными.
+
+Для генерации объявленной зависимости укажите её идентификатор в `easyp.gen.yaml`:
+
+~~~yaml
+version: v1
+generate:
+  modules:
+    - gitlab/products/svc
+plugins: []
+~~~
+
+Разрешённые roots определяют protobuf-имена файлов. Module-local `paths` и `packages` ограничивают генерацию; paths считаются от каталога внешнего модуля. Для совместной генерации добавьте в `modules` и свой локальный модуль. Выбор корней не переписывает исходные импорты и не требует повторять root в фильтре генерации.
+
+## Изменение корней при обновлении зависимости
+
+Если новая ревизия задаёт собственные корни, EasyP сравнивает protobuf-имена с fallback-пространством прежней закреплённой ревизии. Это касается и корня `.` модуля без метаданных, даже если старый lock не содержит `roots`. Перемещение физических каталогов при сохранении import-имён допустимо. Смена пространства имён останавливает неявное обновление до записи manifest/lock; ошибка показывает прежнюю и новую ревизии, roots и примеры переименованных импортов.
+
+Чтобы принять новую ревизию, измените её `require` в `protobuf.mod` и выполните `easyp mod tidy`. Tidy обновляет import-декларации потребителя, если прежнее и новое закреплённые пространства имён доказывают однозначную связь с исходным контрактом, в том числе когда старое имя занял другой файл. Команда проверяет предложенные импорты до совместной записи исходников и manifest/lock, затем показывает выполненные замены. Комментарии, переводы строк и остальные строковые значения сохраняются. Tidy использует объявленные версии и сам их не повышает.
+
+Неоднозначное соответствие или удалённый импортируемый исходник останавливают запись с объяснением проблемного импорта. Исходники зависимостей и кеша не переписываются. Отдельно проверьте selectors генерации и выходные пути SDK. Если импорты уже исправлены, явно примите root командой `easyp get --import-root api gitlab/products/svc@<новая-версия>` либо сохраните прежнюю версию. Метаданные производителя сохраняют приоритет; подсказка должна совпадать с ними, а проверки импортов и целостности продолжают действовать.
+
 ## Команды
 
 | Команда | Поведение |
@@ -59,7 +91,7 @@ easyp generate
 
 ## Зависимости на Buf или старом EasyP
 
-Git-зависимость может объявлять корни <code>.proto</code> через <code>buf.work.yaml</code>, Buf v1/v2 <code>buf.yaml</code> или старый EasyP <code>easyp.yaml</code>. Транзитивные требования из старого EasyP <code>protobuf.mod</code> также читаются. Если ни одного такого файла нет, корнем считается каталог репозитория. Совместимость относится к метаданным зависимости; проект-потребитель использует v1 <code>protobuf.mod</code>.
+Git-зависимость может объявлять корни <code>.proto</code> через <code>buf.work.yaml</code>, Buf v1/v2 <code>buf.yaml</code> или старый EasyP <code>easyp.yaml</code>. Транзитивные требования из старого EasyP <code>protobuf.mod</code> также читаются. Без метаданных корни могут определяться по внутренним импортам зависимости или проверенной подсказке; иначе используется каталог репозитория. Записанные fallback roots воспроизводятся из <code>protobuf.lock</code>. Совместимость относится к метаданным зависимости; проект-потребитель использует v1 <code>protobuf.mod</code>.
 
 При адаптации старого <code>easyp.yaml</code> требования берутся и из <code>deps</code>, и из Git-входов генерации. Точные дубликаты источник/версия удаляются, разные минимумы сохраняются для MVS; некорректные deps вызывают ошибку. Совпадающий нативный <code>protobuf.mod</code> имеет приоритет. Читаются только метаданные, плагины зависимости не запускаются.
 

content/docs/migration/easyp-v0.mdx

@@ -53,6 +53,34 @@ The converter preserves the effective selected lint rules, exceptions, rule sett
 
 Legacy <code>direct</code> and <code>indirect</code> requirements are converted to native <code>require</code> directives. The tool proves that local generation keeps the same protobuf files and import paths, using whole roots, literal generation paths or exact package selectors.
 
+## Git inputs and custom roots
+
+Each `git_repo.url` becomes a `require` and a generation module selection, preserving its version and historical pin. `root` is an import-root resolution hint; `sub_directory` becomes a module-local generation path after verification.
+
+~~~yaml
+generate:
+  inputs:
+    - git_repo:
+        url: gitlab/products/svc
+        root: api/svc/v1
+        sub_directory: api/svc/v1/service
+~~~
+
+The initial preview accepts these selectors without dependency access. Authorized verification checks the pinned sources, historical hash and import-name mapping. Existing dependency roots retain priority. A metadata-free dependency can use the verified legacy root, recorded in `protobuf.lock`. Corrections appear in the verified preview; ambiguous or unrepresentable namespaces fail before files are written.
+
+The selected subtree can become:
+
+~~~yaml
+version: v1
+generate:
+  modules:
+    - module: gitlab/products/svc
+      paths: [api/svc/v1/service]
+plugins: []
+~~~
+
+Paths are relative to the dependency module directory, while files keep import names such as `service/svc.proto` relative to root `api/svc/v1`. A plain module identity selects the full resolved module. Mixed local/Git inputs get separate module filters.
+
 ## Keep default roots and source locations
 
 An omitted or empty legacy root means <code>.</code>. Native <code>protobuf.mod</code> has the same default when <code>roots</code> is omitted; there is no need to move proto files into a new directory.
@@ -70,7 +98,7 @@ plugins:
       paths: source_relative
 ~~~
 
-Import roots stay unchanged and generated files keep their source-relative paths. The wizard first tries whole-root equality, then literal directory paths, then complete package selectors for mixed-root cases. Each choice must select exactly the same physical files with the same import names. Paths can preserve part of a package: ignored Gradle build copies outside `mcp` stay out of generation. Hidden/vendor/nested-module boundary changes and inferred local filters mixed with whole-module Git inputs remain blocked. Sources and fixed paths/packages are checked again before apply.
+Import roots stay unchanged and generated files keep their source-relative paths. The wizard first tries whole-root equality, then literal directory paths, then complete package selectors for mixed-root cases. Each choice must select exactly the same physical files with the same import names. Paths can preserve part of a package: ignored Gradle build copies outside `mcp` stay out of generation. Hidden/vendor/nested-module boundary changes that cannot preserve the original selection remain blocked. Sources and fixed paths/packages are checked again before apply.
 
 `generate.paths` matches literal module-directory-relative files or directory subtrees, with `.` meaning all sources; `mcp` does not select `mcp-copy`. Paths intersect optional package selectors, and every selector must match a resulting source across the selected modules. Unknown selectors fail before plugins or descriptor writes, even without plugins or under `--all`. Required imports outside these paths remain available. These paths are separate from plugin `opts.paths`, which controls output layout.
 
@@ -88,7 +116,7 @@ A full commit SHA is preserved, including a full SHA embedded in an old pseudo-v
 
 Git's annotated-tag spelling, such as `v0.4.0^{}`, is accepted for a full SemVer tag in the historical lock. The tag, commit and original hash are still verified, and the old lock stays byte-identical. Peeled branches, abbreviated refs, repeated suffixes and pseudo-version-shaped peeled tags are rejected.
 
-Released v0 installers archived Git's <code>*.proto</code> pathspec and stripped legacy root prefixes before hashing. Migration reproduces that archive at the pinned revision; it also retains verification of the existing whole-tree hash format. Git archive attributes that omit or alter proto files require manual migration because a native checkout would change the contract.
+Released v0 installers archived Git's <code>*.proto</code> pathspec and stripped legacy root prefixes before hashing. Migration reproduces that archive at the pinned revision; it also retains verification of the existing whole-tree hash format. Omitted selected or reachable proto sources and changes to verified archive bytes require manual migration. An unused <code>export-ignore</code> source outside a verified filtered Git selection is permitted when historical hash, target names and reachable bindings match. A whole input that would gain an extra target still fails.
 
 The v1 content hash is then calculated independently over the materialized logical snapshot. Old and new hashes cover different path layouts and cannot be copied or compared as interchangeable values. A missing historical dependency pin is not replaced with current HEAD.