крупное обновление документации

2026-07-10 18:15:05 +04:00
parent 01953cc25e
commit 0eef72a2c2
28 changed files with 2435 additions and 6 deletions
@@ -12,10 +12,13 @@

 1. Прочитать [`targets/README.md`](targets/README.md).
 2. Прочитать файл текущей цели, указанный там как `Current target`.
-3. Прочитать [`docs/README.md`](docs/README.md) и связанные с задачей нормативные документы.
-4. Для renderer-задач прочитать [`RENDER.md`](RENDER.md).
-5. Проверить рабочее дерево и не перезаписывать чужие изменения.
-6. Перед созданием сложной подсистемы или добавлением dependency проверить [`docs/TOOLING_CATALOG.md`](docs/TOOLING_CATALOG.md), зарегистрировать найденные готовые решения и провести bounded evaluation вместо немедленного вендоринга.
+3. Прочитать [`targets/DEVELOPMENT_ROADMAP.md`](targets/DEVELOPMENT_ROADMAP.md) и соответствующий subsystem plan из `targets/roadmap/`.
+4. Прочитать [`docs/README.md`](docs/README.md) и связанные с задачей нормативные документы.
+5. Прочитать обязательный [`docs/DOCUMENTATION_STANDARD.md`](docs/DOCUMENTATION_STANDARD.md) и определить, какие API docs, module spec и diagrams затрагивает задача.
+6. Для renderer-задач прочитать [`RENDER.md`](RENDER.md).
+7. Проверить рабочее дерево и не перезаписывать чужие изменения.
+8. Перед созданием сложной подсистемы или добавлением dependency проверить [`docs/TOOLING_CATALOG.md`](docs/TOOLING_CATALOG.md), зарегистрировать найденные готовые решения и провести bounded evaluation вместо немедленного вендоринга.
+9. При командной работе прочитать [`docs/TEAM_WORKFLOW.md`](docs/TEAM_WORKFLOW.md), проверить активные claims/draft PRs и объявить стабильный Agent ID до изменений.

 Если задача пользователя противоречит target-порядку, прямое указание пользователя имеет приоритет, но агент обязан сохранить архитектурные границы и отметить влияние на roadmap.

@@ -30,10 +33,16 @@
 - Любой новый формат, публичный контракт или несовместимое решение требует обновления документации и при необходимости ADR.
 - Исправление дефекта должно получать regression test, когда это технически возможно.
 - Не писать крупную подсистему с нуля до поиска готовых libraries, reference implementations, fixtures и tooling; результат исследования фиксируется в `docs/TOOLING_CATALOG.md`.
+- Не начинать claimed work package другого агента и не редактировать его exclusive paths без явного handoff.
+- Не работать двум агентам в одном worktree. Каждый агент использует собственную ветку и clone/worktree.
+- Статус milestone, Evidence и `OPENWC_TARGET_DONE` изменяет только назначенный интегратор.
+- Каждый новый/существенно изменённый модуль обязан иметь актуальную specification в `docs/modules/`, inline documentation публичного API и data-flow diagram по `docs/DOCUMENTATION_STANDARD.md`.
+- Stateful/async/cross-layer работа обязана документировать state/sequence diagram, ownership, threading, failure и recovery paths.
+- Документация обновляется в том же work package, что код. Handoff без обязательной документации имеет статус только `PARTIAL`.

 ## Метки состояния

-В каждом `targets/*.md` присутствует ровно одна метка:
+В каждом исполняемом target-файле `targets/[0-9][0-9]-*.md` присутствует ровно одна метка. Справочные документы `targets/DEVELOPMENT_ROADMAP.md` и `targets/roadmap/*.md` меток состояния не имеют:

 - `<!-- OPENWC_TARGET:OPEN -->` — цель ещё не начата.
 - `<!-- OPENWC_TARGET:ACTIVE -->` — единственная текущая цель.
@@ -53,6 +62,7 @@
 3. В Evidence записаны команды, результаты и изменённые файлы.
 4. Не осталось обязательных незакрытых пунктов или скрытых заглушек.
 5. Обновлены `targets/README.md` и матрица функций, если применимо.
+6. Публичный API, module spec, input/output tables и обязательные diagrams соответствуют фактической реализации.

 Агент НЕ ДОЛЖЕН ставить `DONE` только потому, что код компилируется. Если пользователь явно принял частичный результат, статус остаётся `ACTIVE`, а принятое ограничение записывается в Evidence.

@@ -64,4 +74,5 @@
 - что изменено;
 - какие проверки выполнены;
 - fidelity evidence для поведения 3.3.5a;
- оставшиеся риски или следующий незакрытый checklist item.
+- оставшиеся риски или следующий незакрытый checklist item;
+- какие API/module docs и diagrams созданы или обновлены.
@@ -0,0 +1,14 @@
+# OpenWC Coordination
+
+Основные правила находятся в [`../docs/TEAM_WORKFLOW.md`](../docs/TEAM_WORKFLOW.md).
+
+Предпочтительно вести claims в issue и draft PR/MR общего Git forge. Каталог `claims/` — fallback, если issue tracker недоступен. Один claim — один файл; не использовать общий изменяемый board.
+
+## Создание fallback claim
+
+1. Скопировать [`TASK_TEMPLATE.md`](TASK_TEMPLATE.md) в `claims/<work-package-id>.md`.
+2. Заполнить owner, lease, paths, contracts и tests.
+3. Опубликовать claim до production edits.
+4. После интеграции заменить состояние на `accepted` или удалить claim отдельным coordination commit, сохранив историю в Git.
+
+Claim-файлы не заменяют target Evidence и не меняют milestone status.
@@ -0,0 +1,66 @@
+# <WORK-PACKAGE-ID> — <Title>
+
+<!-- OPENWC_CLAIM:<WORK-PACKAGE-ID>:<AGENT-ID>:<YYYY-MM-DD> -->
+
+## Ownership
+
+- Target:
+- Program:
+- Owner/Agent ID:
+- Branch:
+- Lease expires UTC:
+- Integrator:
+
+## Outcome
+
+
+## Non-goals
+
+
+## Paths
+
+- Exclusive:
+- Shared/hotspots:
+- Generated/ignored:
+
+## Contracts and data
+
+- Public API/events:
+- Schema/format version:
+- Migration/compatibility:
+- Consumers:
+
+## Dependencies
+
+- Requires:
+- Blocks:
+- External state:
+
+## Verification
+
+- Commands:
+- Fixtures:
+- Fidelity evidence:
+- Performance budget:
+
+## Documentation deliverables
+
+- Inline public API docs:
+- Module specification:
+- Data-flow diagram:
+- Sequence/state/dependency diagrams:
+- Source map/status updates:
+
+## Status
+
+- State: claimed
+- Done:
+- Next:
+- Blocked by:
+
+## Handoff
+
+- Commit:
+- Results:
+- Remaining risks:
+- Documentation updated:
@@ -0,0 +1,5 @@
+# Fallback claims
+
+Этот каталог используется только когда общий issue/PR tracker недоступен. Каждый активный work package создаёт отдельный Markdown-файл по [`../TASK_TEMPLATE.md`](../TASK_TEMPLATE.md).
+
+Файл без валидного `OPENWC_CLAIM` marker не считается claim. Не хранить здесь secrets, credentials, proprietary data или большие логи.
@@ -37,6 +37,7 @@
 - Packed GUIDs, update fields, create/update/out-of-range/destroy.
 - Movement flags, heartbeat, jump/fall/swim/fly, transports, knockback и spline movement.
 - Server time, tutorial flags, account data и feature capability detection.
+- Warden handshake/module compatibility для явно поддерживаемых test/private server profiles с sandbox и без ориентации на official servers.

 ## Player и camera

@@ -0,0 +1,278 @@
+# OpenWC Documentation Standard
+
+## Цель
+
+Документация является частью реализации. Код без актуального объяснения публичного API, данных, ownership и поведения считается незавершённым, даже если компилируется и проходит тесты.
+
+Документация должна позволить человеку ответить:
+
+- зачем существует модуль;
+- какие данные он получает и откуда;
+- что он создаёт или изменяет;
+- кто владеет состоянием и ресурсами;
+- какие зависимости допустимы;
+- что происходит по шагам;
+- как модуль завершается, отменяется и восстанавливается после ошибки;
+- как проверить fidelity, correctness и performance;
+- какие части реализованы, запланированы или известны как gap.
+
+## Уровни документации
+
+### 1. Inline API documentation
+
+Находится рядом с кодом и является источником истины для точной сигнатуры:
+
+- публичные classes/interfaces;
+- public methods/functions;
+- signals/events;
+- exported properties/configuration;
+- commands, events и read models;
+- ownership/lifetime/threading requirements;
+- error/return semantics;
+- non-obvious invariants.
+
+### 2. Module specification
+
+Находится в `docs/modules/<module>.md` и объясняет назначение, архитектуру, data flow, state/lifecycle, extension points и verification. Шаблон: [`modules/TEMPLATE.md`](modules/TEMPLATE.md).
+
+### 3. Data/schema documentation
+
+Описывает persisted/wire/content formats: fields, types, units, optionality, version, migration, provenance и compatibility. Нельзя объяснять schema только примером JSON или SQL.
+
+### 4. ADR
+
+Фиксирует значимое решение, варианты и последствия. ADR не заменяет актуальное описание модуля: после решения module spec обновляется до текущего состояния.
+
+### 5. Operational documentation
+
+Команды build/test/import/bake/deploy/recovery, expected outputs и diagnostics. Команда без условий запуска и интерпретации результата недостаточна.
+
+## Обязательная module specification
+
+Новый самостоятельный модуль или существенно выделенная подсистема обязаны иметь документ со следующими разделами:
+
+1. Metadata/status.
+2. Purpose и non-goals.
+3. Context и architecture boundaries.
+4. Public API.
+5. Inputs и outputs.
+6. Data flow diagram.
+7. State/lifecycle или sequence diagram, если применимо.
+8. Ownership, threading и resource lifetime.
+9. Errors, cancellation и recovery.
+10. Configuration/capabilities/profiles.
+11. Persistence/cache/migrations.
+12. Diagnostics и observability.
+13. Tests, fidelity evidence и performance budgets.
+14. Extension points.
+15. Known gaps.
+16. Source map.
+
+`Status` принимает только:
+
+- `Planned`;
+- `Prototype`;
+- `Partial`;
+- `Implemented`;
+- `Verified`;
+- `Deprecated`.
+
+`Implemented` не означает fidelity; `Verified` требует evidence и ссылок на тесты.
+
+## Обязательные схемы
+
+### Data flow diagram
+
+Обязательна для каждого module spec. Показывает реальные имена contracts и направление данных:
+
+```mermaid
+flowchart LR
+    Source[ADT bytes] --> Parser[ADTLoader]
+    Parser --> Data[AdtTileData]
+    Data --> Planner[StreamingTargetPlanner]
+    Planner --> Queue[RenderFinalizeCommand]
+    Queue --> Renderer[TerrainRenderer]
+```
+
+Диаграмма должна показывать:
+
+- внешние источники;
+- входные contracts;
+- преобразования;
+- выходные contracts/side effects;
+- persistence/cache, если участвует;
+- запрещённое направление, если оно является важной границей.
+
+### Sequence diagram
+
+Обязательна, если операция пересекает два и более из следующих boundary:
+
+- thread/job queue;
+- network;
+- gameplay;
+- renderer/UI/audio;
+- Editor;
+- server/database;
+- filesystem/build pipeline.
+
+```mermaid
+sequenceDiagram
+    participant Net as WorldSession
+    participant Game as WorldState
+    participant View as EntityPresenter
+    participant Render as WorldRenderFacade
+    Net->>Game: EntityCreated
+    Game-->>View: EntityReadModel change
+    View->>Render: spawn_entity(descriptor)
+```
+
+### State diagram
+
+Обязательна для lifecycle/state machine с тремя и более состояниями, reconnect/retry или rollback:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Disconnected
+    Disconnected --> Connecting
+    Connecting --> Authenticated
+    Connecting --> Failed
+    Authenticated --> Disconnected
+    Failed --> Connecting: retry
+```
+
+### Dependency diagram
+
+Обязательна при изменении архитектурной границы или модуле с тремя и более downstream consumers. Она показывает compile/runtime dependencies, а не случайное расположение Node в сцене.
+
+## Public API documentation
+
+Для каждого public symbol указываются:
+
+- краткое назначение;
+- параметры с единицами и coordinate space;
+- return value или emitted event;
+- preconditions/postconditions;
+- ownership и mutability;
+- допустимый thread;
+- failure behavior;
+- profile/capability restrictions;
+- пример только если контракт остаётся неочевидным.
+
+### GDScript
+
+- Использовать `##` documentation comments для class, public methods, signals и exported properties.
+- Всегда указывать типы аргументов/return, где Godot API позволяет.
+- `@export` property объясняет units/range/profile и runtime mutability.
+- Signal документирует момент emission, arguments и ordering guarantees.
+- Internal helper получает комментарий, если содержит сложный invariant, coordinate conversion, ownership или performance assumption.
+
+### C++/GDExtension
+
+- Public headers используют Doxygen-compatible `///`/`/** */`.
+- Документировать ownership указателей/references/buffers, thread safety и error transport.
+- Binary structs указывают source format/build, packing/endianness и validation.
+- Native/Godot boundary описывает allocation и lifetime Variant/PackedArray/Resource.
+- Implementation comments объясняют `why` и invariant, а не пересказывают строку кода.
+
+### Shaders/materials
+
+- Uniform/global parameter: coordinate/color space, range, units и producer.
+- Material profile: supported WoW shader/blend modes и approximations.
+- Expensive branch/texture dependency имеет cost/fallback note.
+- Blizzlike и Enhanced behavior документируются отдельно.
+
+### Network codecs
+
+- Opcode/direction/session phase.
+- Exact build/profile.
+- Field order/type/endianness/conditional presence.
+- Domain events на выходе.
+- Malformed/unknown handling.
+- Fixture/reference source без sensitive payload.
+
+### Content/server schemas
+
+- Canonical field и mapping на каждый core adapter.
+- Unit, default, null/optional semantics и flags.
+- Numeric ID allocation и references.
+- Migration/rollback и unsupported degradation.
+
+## Документация потока данных
+
+Inputs/outputs оформляются таблицей:
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+| Input | `EntityMoved` | `WorldSession` | `WorldState` | Immutable event | Game-thread apply |
+| Output | `EntityReadModel` | `WorldState` | Presenter/UI | Snapshot | Until next revision |
+
+Side effects перечисляются отдельно:
+
+- scene tree mutation;
+- RenderingServer RID creation/free;
+- filesystem/cache write;
+- network send;
+- DB query/apply;
+- settings/SavedVariables mutation.
+
+Скрытый side effect является дефектом документации и API.
+
+## Статус реализации
+
+Документ не должен выдавать roadmap за существующий код. Каждый важный capability помечается:
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+
+После изменения кода статус и `Last verified` обновляются в том же work package. Если документацию нельзя подтвердить, ставится `Unknown`/`Planned`, а не предположение.
+
+## Documentation change rules
+
+Документация обновляется в том же work package, если изменились:
+
+- public API/signal/event;
+- data flow или ownership;
+- state/lifecycle;
+- thread boundary;
+- format/schema/cache version;
+- configuration/capability;
+- diagnostics/error/recovery;
+- fidelity или performance behavior;
+- extension point.
+
+Переименование symbol/path требует обновить source map, diagrams и ссылки. Stale documentation считается regression.
+
+## Code comments
+
+Хороший комментарий объясняет:
+
+- почему решение отличается от очевидного;
+- форматное или protocol ограничение;
+- ownership/thread invariant;
+- причину batching/budget;
+- источник fidelity behavior;
+- временный compatibility path и условие удаления.
+
+Плохой комментарий:
+
+- пересказывает код;
+- обещает будущую работу без target/work package ID;
+- содержит устаревшую сигнатуру;
+- маскирует magic number без source/unit;
+- утверждает `Blizzlike` без evidence.
+
+TODO/FIXME должен содержать target/work package или diagnostic code.
+
+## Review gate
+
+Reviewer/integrator проверяет:
+
+- public symbols имеют inline docs;
+- module spec существует или обновлён;
+- input/output и side effects перечислены;
+- diagrams соответствуют реальным contracts;
+- state/error/recovery paths показаны;
+- tests/evidence и known gaps честны;
+- документы не дублируют противоречивые источники истины.
+
+Если хотя бы один обязательный пункт отсутствует, handoff остаётся `PARTIAL`, а target не может получить `DONE`.
@@ -0,0 +1,120 @@
+# Godot Best Practices for OpenWC
+
+## Статус
+
+Это нормативные правила применения Godot в OpenWC. Они дополняют общую архитектуру и основаны на официальных Godot practices с учётом большого streaming world, native parsers и встроенного Editor tooling.
+
+## Nodes только на границах
+
+- Domain, packet codecs, validators, coordinate math, build graph и canonical content не должны быть Nodes.
+- Node/Control используются для lifecycle, scene composition, input, rendering/audio presentation и Editor UI.
+- Большой объём однородных данных хранится в typed objects/packed arrays/resources, а не в тысячах служебных Nodes.
+- Scene не ищет глобально dependency по имени; parent composition передаёт contract/reference явно.
+
+## Scene organization
+
+- Каждая scene имеет одну ответственность и может запускаться в isolation с test doubles.
+- Parent-child означает ownership: удаление parent логично удаляет child. Иначе системы являются siblings/services.
+- Scene наружу публикует небольшой API/signals, а внутренние NodePaths не становятся публичным контрактом.
+- Runtime, render sandbox, preview и capture scenes собираются из общих presenters/services.
+- Generated world preview не сохраняется как authoring source.
+
+## Dependency injection и signals
+
+- Dependencies передаются composition root, initializer или exported interface reference.
+- Signals используются для notification; commands/intents вызываются через явные методы/bus contracts.
+- Signal connections снимаются симметрично при unload/plugin disable.
+- Не использовать SceneTree groups как скрытый service locator для core architecture.
+
+## Autoload policy
+
+Autoload разрешён только для действительно process-wide lifecycle:
+
+- composition/bootstrap coordinator;
+- глобальная immutable build/version information;
+- crash/diagnostic sink, если ему нужен process lifetime.
+
+Gameplay state, network session, renderer world, editor session, caches конкретного проекта и audio emitters не должны становиться неявными глобальными managers. Они создаются/освобождаются владельцем режима.
+
+## Resources and data
+
+- Resource подходит для immutable/imported descriptors и editor-inspectable configuration.
+- Runtime mutable authoritative state не хранится в shared Resource, который может быть случайно разделён сценами.
+- Resource schema имеет version и migration, если сохраняется пользователем.
+- Original extracted corpus и bulk caches не следует заставлять Godot массово импортировать без необходимости; применять `.gdignore`, custom import staging или native repository.
+- Importer проверяет malformed input и записывает dependency/profile metadata.
+
+## Background work
+
+- Blocking `load()` не используется в frame-critical streaming path; применяются threaded load/jobs.
+- Worker выполняет file I/O, parsing, decompression, grouping и pure data generation.
+- SceneTree mutation, Node attach и большинство GPU/RID finalization выполняются main thread budget.
+- Один Resource не модифицируется несколькими workers.
+- GDScript container resize/mutation между threads защищается mutex или заменяется message passing.
+- Все worker tasks ожидаются/очищаются; session cancellation не оставляет orphan work.
+
+## Rendering performance
+
+- Сначала измерять SceneTree/CPU/GPU bottleneck, затем переходить к RenderingServer.
+- Repeated static M2 группировать spatial MultiMesh cells; один MultiMesh на весь мир ухудшает culling.
+- Large transform buffers готовить линейно/в native code и отправлять батчем.
+- Visibility ranges/HLOD, occlusion и automatic mesh LOD использовать совместно по профилю.
+- Unique materials/textures минимизировать; descriptor/resource counts являются budget metric.
+- RenderingServer RIDs имеют явного владельца и освобождаются в deterministic shutdown test.
+- Shader/material profiles разделяют Blizzlike и Enhanced; runtime не компилирует тяжёлые варианты при пересечении ADT boundary.
+
+## EditorPlugin lifecycle
+
+- Любая регистрация в `_enter_tree()` имеет соответствующее удаление в `_exit_tree()`.
+- Docks, inspectors, importers, gizmos, debugger plugins, signals и jobs снимаются при disable/reload.
+- Editor UI не пишет файлы/SQL напрямую — только создаёт application commands.
+- Mutation интегрирована с EditorUndoRedoManager или общей command history.
+- Preview nodes считаются disposable; stable content IDs не равны instance IDs.
+- Долгая операция имеет progress, cancellation и staging output.
+
+## Editor imports and inspectors
+
+- Custom import plugin применяется для формата, которому действительно нужен first-class Godot Resource lifecycle.
+- Один extension/type имеет стабильный importer name и version.
+- Platform/profile variants фиксируются явно.
+- Custom inspectors редактируют canonical data через commands и показывают field-level validation.
+- Gizmos не владеют сущностью и создают одну undoable logical operation на drag/stroke.
+
+## UI
+
+- Control tree не читает network packets и не ищет world nodes.
+- View models immutable на frame/update boundary.
+- Layout использует anchors/containers/theme tokens, а не hardcoded pixel positions вне fidelity backend.
+- FrameXML compatibility layout изолирован от modern Godot-native screens.
+- Input consumption и focus/modal context тестируются сценами.
+
+## Profiling and diagnostics
+
+- Использовать Godot profiler для script/physics и Visual Profiler для render CPU/GPU.
+- Headless/CLI runs сохраняют JSON metrics; GPU runs фиксируют backend/device/driver/resolution.
+- Performance changes сравниваются cold/warm и p50/p95/p99, а не одним FPS.
+- GPU validation, memory tracking и RenderDoc workflow документируются для shader/backend defects.
+- Custom monitors публикуют streaming queues, cache hits, entities, materials, RIDs и job latency.
+
+## Tests
+
+- Pure logic тестируется без SceneTree.
+- Scene runner используется только для lifecycle/input/signals/layout/presentation.
+- EditorPlugin имеет enable/disable/reload и undo/save/reload tests.
+- Headless является обязательным CI path; visual tests запускаются отдельно на GPU runner.
+- GdUnit4 рассматривается как кандидат для GDScript/scene tests; native tests остаются отдельным target.
+
+## Official references
+
+- [Godot Best practices](https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html)
+- [Scene organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/scene_organization.html)
+- [Autoloads versus regular nodes](https://docs.godotengine.org/en/stable/tutorials/best_practices/autoloads_versus_regular_nodes.html)
+- [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html)
+- [Thread-safe APIs](https://docs.godotengine.org/en/stable/tutorials/performance/thread_safe_apis.html)
+- [Optimization using MultiMeshes](https://docs.godotengine.org/en/stable/tutorials/performance/using_multimesh.html)
+- [RenderingServer](https://docs.godotengine.org/en/stable/classes/class_renderingserver.html)
+- [Import plugins](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/import_plugins.html)
+- [Inspector plugins](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/inspector_plugins.html)
+- [3D gizmo plugins](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/3d_gizmos.html)
+- [Command line tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html)
+- [Debugging tools](https://docs.godotengine.org/en/stable/tutorials/scripting/debug/overview_of_debugging_tools.html)
@@ -4,6 +4,8 @@

 Исполняемая последовательность текущих целей находится в [`../targets/README.md`](../targets/README.md). Все агенты обязаны следовать корневому [`../AGENTS.md`](../AGENTS.md).

+Полная инженерная карта проекта находится в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md); она раскрывает renderer, protocol, gameplay, UI/Lua/audio, Editor tooling, server emulators и quality/release workstreams.
+
 ## Статус документов

 Документы описывают целевую архитектуру. Реализованное состояние рендера зафиксировано отдельно в [`../RENDER.md`](../RENDER.md). Если описание целевого решения расходится с кодом, это считается известным архитектурным долгом, а не разрешением обходить границы слоёв.
@@ -23,6 +25,10 @@
 | [ROADMAP.md](ROADMAP.md) | Последовательность вертикальных срезов и критерии готовности |
 | [REFERENCES.md](REFERENCES.md) | Использованные локальные reference-проекты и правила работы с ними |
 | [TOOLING_CATALOG.md](TOOLING_CATALOG.md) | Реестр готовых библиотек, редакторов, test oracles и кандидатов на интеграцию |
+| [GODOT_BEST_PRACTICES.md](GODOT_BEST_PRACTICES.md) | Нормативные правила scenes, data, jobs, rendering, EditorPlugin, profiling и tests |
+| [TEAM_WORKFLOW.md](TEAM_WORKFLOW.md) | Ветки/worktree, task claims, ownership, handoff, integration и conflict protocol |
+| [DOCUMENTATION_STANDARD.md](DOCUMENTATION_STANDARD.md) | Обязательные API docs, module specs, data-flow/state/sequence diagrams и documentation gate |
+| [modules/README.md](modules/README.md) | Реестр фактических модулей и шаблон их спецификаций |

 ## Обязательный workflow изменения функции

@@ -67,6 +67,22 @@ Reference-код используется для исследования фор

 Подробные статусы и evaluation cards ведутся в [`TOOLING_CATALOG.md`](TOOLING_CATALOG.md).

+### Godot, GdUnit4 и server tooling
+
+- [Godot best practices](https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html) — основной источник engine-specific правил; принятые решения собраны в [`GODOT_BEST_PRACTICES.md`](GODOT_BEST_PRACTICES.md).
+- [`godot-gdunit-labs/gdUnit4`](https://github.com/godot-gdunit-labs/gdUnit4) — кандидат для GDScript/scene/Editor/CI тестов.
+- [`azerothcore/Keira3`](https://github.com/azerothcore/Keira3) — reference существующего редактора world DB и SQL generation.
+- [AzerothCore database and module documentation](https://www.azerothcore.org/wiki/documentation-index) — primary reference для AzerothCore adapter/deployment workflow.
+- [WowBench](https://sourceforge.net/projects/wowbench/) — исторический offline WoW XML/Lua API emulator и источник addon test ideas.
+
+### Warcraft format ecosystem
+
+- [`wowemulation-dev/warcraft-rs`](https://github.com/wowemulation-dev/warcraft-rs) — современный Rust CLI/library set для MPQ/DBC/BLP/ADT/WDT/WDL/M2/WMO и независимый кандидат на format oracle.
+- [`wowdev/WoWDBDefs`](https://github.com/wowdev/WoWDBDefs) — versioned definitions client database tables; полезны для schema generation и coverage.
+- [`gtker/wow_dbc`](https://github.com/gtker/wow_dbc) — независимый 1.12/2.4.3/3.3.5 DBC reader/writer и converter reference.
+
+Используем для differential testing текущих native parsers и поиска coverage gaps. Новый Rust dependency не принимается только из-за более широкого списка поддерживаемых форматов: сначала требуются build-specific fixtures и измеренное преимущество.
+
 ## Правила исследования

 1. Для protocol semantics приоритет имеют wire fixtures и соответствующая версия server core.
@@ -2,6 +2,8 @@

 > Этот документ объясняет стратегию на высоком уровне. Исполняемый порядок, текущий статус, checklist и доказательства завершения ведутся только в [`../targets/README.md`](../targets/README.md). При расхождении `targets/` имеет приоритет.

+Полный roadmap с точки зрения разработки, contracts, subsystem dependencies и gates находится в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md).
+
 ## Стратегия

 Работа идёт вертикальными срезами. Каждый срез включает data, domain, adapter, presentation, editor support, diagnostics и tests. Горизонтальная реализация всех opcodes или всех editor-панелей без пользовательского результата не считается milestone.
@@ -0,0 +1,343 @@
+# Командная разработка OpenWC
+
+## Цель
+
+Этот workflow позволяет нескольким людям и Codex-агентам работать параллельно, не перезаписывая изменения друг друга и не разрушая архитектурные границы. Единица параллельной работы — не milestone целиком, а ограниченный `work package`.
+
+## Основные правила
+
+1. Каждый агент работает в отдельном clone или Git worktree и собственной ветке.
+2. Никто не разрабатывает напрямую в `master`.
+3. До изменений задача получает ID, владельца, claim и список затрагиваемых путей.
+4. Один work package имеет только одного активного владельца.
+5. Общие contracts согласуются до параллельной реализации producers/consumers.
+6. Статус milestone и `OPENWC_TARGET_DONE` изменяет только интегратор.
+7. Merge выполняется только после handoff, локальных проверок и синхронизации с актуальным `master`.
+
+## Идентификаторы
+
+### Agent ID
+
+Каждый человек/агент выбирает стабильный ID на весь work package:
+
+```text
+<human>-<machine>-codex
+```
+
+Примеры:
+
+```text
+sindo-main-codex
+alex-laptop-codex
+```
+
+ID записывается в claim, ветке, PR/MR и handoff. Нельзя использовать просто `codex`, потому что таких агентов несколько.
+
+### Work Package ID
+
+```text
+<TARGET>-<PROGRAM>-<SHORT-NAME>-<NNN>
+```
+
+Примеры:
+
+```text
+M01-FND-COORDS-001
+M03-RND-SCHEDULER-001
+M08-NET-SRP-001
+M12-UIA-LUA-SPIKE-001
+```
+
+Program codes определены в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md).
+
+## Claim protocol
+
+Предпочтительный канал координации — issue + ранний draft PR/MR на общем Git forge. Если forge недоступен, используется отдельный файл в `coordination/claims/`, который сначала публикуется в общей ветке.
+
+Claim marker:
+
+```text
+<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-13 -->
+```
+
+Последнее поле — дата истечения claim в UTC. Рекомендуемый срок — 48 часов; владелец продлевает его коротким status update. Истёкший claim нельзя забирать молча: сначала оставить сообщение владельцу и интегратору.
+
+Claim содержит:
+
+- target и work package;
+- owner/agent ID;
+- outcome и non-goals;
+- exclusive paths;
+- shared/hotspot paths;
+- contracts/schema/format changes;
+- dependencies и blockers;
+- verification commands;
+- expected fidelity evidence.
+- documentation deliverables: inline API, module spec, diagrams и source map.
+
+## Ветки и worktrees
+
+Имя ветки:
+
+```text
+work/<agent-id>/<target>-<short-name>
+```
+
+Пример:
+
+```text
+work/sindo-main-codex/m01-coordinate-mapper
+```
+
+Начало работы:
+
+```powershell
+git fetch origin
+git worktree add ..\open-wc-m01 -b work/sindo-main-codex/m01-coordinate-mapper origin/master
+```
+
+Правила:
+
+- один worktree принадлежит одному агенту;
+- не запускать двух агентов в одном dirty worktree;
+- не менять и не удалять чужой worktree;
+- generated caches и proprietary data не переносятся commit/cherry-pick;
+- перед handoff ветка синхронизируется с актуальным `origin/master`.
+
+## Разделение задач
+
+Хороший work package:
+
+- даёт один наблюдаемый результат;
+- принадлежит преимущественно одной подсистеме;
+- имеет явные входы/выходы;
+- меняет не более одного публичного contract одновременно;
+- имеет собственные tests/diagnostics;
+- может быть review и merged независимо либо после одной явно указанной dependency.
+
+Плохое разделение:
+
+- «сделать сеть»;
+- один агент меняет protocol и UI напрямую;
+- два агента одновременно рефакторят один monolithic file;
+- задача зависит от незаписанного устного соглашения;
+- work package оставляет временный второй источник истины.
+
+## Parallelization patterns
+
+### Contract first
+
+Для cross-layer feature сначала отдельным маленьким work package фиксируются:
+
+- domain types;
+- commands/events/read models;
+- version/capabilities;
+- failure states;
+- contract tests.
+
+После merge независимо работают producer и consumers.
+
+Пример:
+
+```text
+WP-A: MovementSnapshot contract
+  ├─ WP-B: network movement decoder
+  ├─ WP-C: gameplay reconciliation
+  └─ WP-D: character/camera presentation
+```
+
+### Fixtures in parallel
+
+Пока один агент реализует pure logic, второй может готовить:
+
+- synthetic fixtures;
+- original-client comparison procedure;
+- server-core matrix;
+- visual checkpoints;
+- documentation/reference analysis.
+
+Fixture agent не изменяет production contract без согласования.
+
+### Adapter split
+
+После merge canonical interface допустимо параллельно реализовать TrinityCore и AzerothCore adapters, если у каждого разные файлы и общая contract suite.
+
+### Hotspot extraction first
+
+Если работа требует одного большого файла, сначала один владелец извлекает стабильный seam. Параллельная работа начинается только после merge seam, а не внутри разных участков монолита.
+
+## Hotspot-файлы
+
+Следующие пути требуют явного указания в claim и согласования с интегратором:
+
+- `project.godot`;
+- `AGENTS.md`, `docs/README.md`, `targets/README.md`;
+- текущий `targets/[0-9][0-9]-*.md`;
+- `RENDER.md`;
+- `src/scenes/streaming/streaming_world_loader.gd` до декомпозиции;
+- native registration/CMake/GDExtension manifests;
+- editor `plugin.cfg` и root plugin lifecycle;
+- shared schema/version/format constants;
+- dependency lockfiles и submodules.
+
+Два активных work packages не должны редактировать один hotspot. При необходимости интегратор выделяет serial integration window.
+
+## Изменение contracts и форматов
+
+Contract/schema change обязан иметь:
+
+- owner и потребителей;
+- backward compatibility или migration;
+- old/new fixtures;
+- version bump policy;
+- rollout order;
+- ADR для существенного решения.
+
+Merge order:
+
+1. contract + compatibility layer;
+2. producers;
+3. consumers;
+4. removal deprecated path отдельным work package.
+
+Нельзя одновременно удалить старый API и ожидать, что незамердженная ветка другого агента уже использует новый.
+
+## Commits
+
+Формат заголовка:
+
+```text
+<program>(<target>): <imperative summary>
+```
+
+Примеры:
+
+```text
+fnd(M01): add canonical coordinate mapper
+net(M08): decode auth challenge safely
+rnd(M03): extract streaming target planner
+test(M00): add paired checkpoint manifest
+```
+
+Описание commit/PR содержит:
+
+```text
+Work-Package: M01-FND-COORDS-001
+Agent: sindo-main-codex
+Tests: <commands/results>
+Fidelity: <evidence/gap>
+```
+
+Не смешивать formatting unrelated files, generated artifacts и функциональное изменение в одном commit.
+
+## Handoff protocol
+
+Готовый work package получает marker:
+
+```text
+<!-- OPENWC_HANDOFF:READY:M01-FND-COORDS-001:<commit> -->
+```
+
+Handoff обязан содержать:
+
+- точный commit/branch;
+- outcome и изменённые paths;
+- публичные contracts/schema changes;
+- verification commands и результаты;
+- fidelity evidence/known gaps;
+- migration/cache/rebuild requirements;
+- unresolved risks;
+- recommended merge order;
+- updated API/module documentation и перечень diagrams.
+
+Если работа частичная:
+
+```text
+<!-- OPENWC_HANDOFF:PARTIAL:M01-FND-COORDS-001:<commit> -->
+```
+
+`PARTIAL` не считается завершением и не разрешает ставить target `DONE`.
+
+## Integration protocol
+
+Интегратор:
+
+1. Проверяет claim и отсутствие overlapping ownership.
+2. Проверяет diff на unrelated/user changes.
+3. Синхронизирует branch с `master` без уничтожения чужой истории.
+4. Запускает package verification и затронутые общие gates.
+5. Проверяет docs, migrations, cache versions и fidelity statement.
+6. Проверяет documentation gate из `docs/DOCUMENTATION_STANDARD.md`: API docs, inputs/outputs, diagrams, ownership и recovery.
+7. Merge/squash выполняет в соответствии с историей work package.
+8. После merge запускает post-merge smoke.
+9. Закрывает claim marker-ом:
+
+```text
+<!-- OPENWC_INTEGRATION:ACCEPTED:M01-FND-COORDS-001:<merge-commit> -->
+```
+
+Только после интеграции всех обязательных work packages интегратор обновляет target Evidence/status.
+
+## Конфликты
+
+При обнаружении overlapping edits агент должен остановить изменение затронутого файла и связаться с владельцем. Запрещено:
+
+- разрешать конфликт через слепое `ours/theirs`;
+- копировать чужой файл поверх своего;
+- делать `reset --hard` или checkout чужих изменений;
+- «временно» дублировать contract без migration plan.
+
+Порядок разрешения:
+
+1. определить semantic owner;
+2. выбрать merge order;
+3. первый владелец публикует минимальный contract/seam;
+4. второй rebase и адаптирует свою ветку;
+5. integration tests подтверждают совместимость.
+
+## Status updates и stale work
+
+Владелец обновляет claim после значимого результата или не реже срока lease. Status краткий:
+
+```text
+State: active | waiting | ready | partial
+Done: ...
+Next: ...
+Blocked by: ...
+Touched paths: ...
+```
+
+Если работа прекращена, claim явно освобождается. Незавершённую ветку не удаляют до handoff с описанием пригодных commits и известных проблем.
+
+## Минимальная схема для двух разработчиков
+
+- Один человек назначается интегратором текущего milestone.
+- Второй берёт work package без пересечения файлов либо готовит fixtures/reference/adapter.
+- Роль интегратора можно менять после каждого milestone.
+- Перед началом дня оба выполняют `git fetch` и сверяют claims/draft PRs.
+- Перед merge второй агент не начинает работу поверх непроверенного commit, если dependency не опубликована как contract branch.
+
+Пример для M01:
+
+```text
+Developer A / integrator:
+  M01-FND-COORDS-001 — coordinate types and mapper
+
+Developer B:
+  M01-QAR-COORD-FIXTURES-001 — known ADT/server points and tests
+
+После merge contract:
+  A — StreamingFocus migration
+  B — placement/SQL conversion audit
+```
+
+## Автоматическая проверка
+
+Перед handoff и merge запускать:
+
+```powershell
+.\tools\verify_coordination.ps1
+.\tools\verify_documentation.ps1
+```
+
+Первая проверка требует ровно один `ACTIVE` numbered target, соответствие `Current target`, валидные и уникальные fallback claim markers. Вторая проверяет обязательные documentation files, структуру module specs, наличие data-flow diagram и относительные ссылки. Истёкший claim выдаёт warning и требует человеческого решения, но не удаляется автоматически.
@@ -47,9 +47,15 @@ Decision/ADR:
 | wow.export | REFERENCE | Asset conversion | M2/WMO/material/export edge cases | Web-specific pipeline |
 | Blender WoW Studio | REFERENCE | Authoring/conversion | WMO/M2/ADT authoring knowledge | Blender-specific UI/data model |
 | [Wowser](https://github.com/wowserhq/wowser) | REFERENCE | 3.3.5a web client | Auth/realm/character/world protocol, binary parsing, asset pipeline и render research | Старый JS/WebGL proof-of-concept, неполный клиент |
+| [warcraft-rs](https://github.com/wowemulation-dev/warcraft-rs) | CANDIDATE | WoW formats/CLI | Independent MPQ/DBC/BLP/ADT/WDT/WDL/M2/WMO validation и conversion oracle | Rust/tool duplication; claims require fixtures |
+| [WoWDBDefs](https://github.com/wowdev/WoWDBDefs) | REFERENCE | Client DB schemas | Versioned DBC definitions и typed-code generation input | Definitions still require build-specific validation |
+| [wow_dbc](https://github.com/gtker/wow_dbc) | REFERENCE | DBC | 1.12/2.4.3/3.3.5 read/write и SQLite conversion ideas | Older release, Rust integration unnecessary by default |
 | [recast-rs](https://github.com/wowemulation-dev/recast-rs) | CANDIDATE | Navigation | Offline navmesh, reachability и dungeon validation | Server mmap compatibility не доказана |
 | [rilua](https://github.com/wowemulation-dev/rilua) | CANDIDATE | Lua/addons | Lua 5.1.1 runtime candidate и headless compatibility oracle | Taint/WoW API/FrameXML отсутствуют; Rust bridge |
 | PUC-Rio Lua 5.1.1 | CANDIDATE | Lua reference/runtime | Authoritative Lua oracle и альтернативный embedded VM | Нужны WoW sandbox, taint и безопасный C++ boundary |
+| [GdUnit4](https://github.com/godot-gdunit-labs/gdUnit4) | CANDIDATE | Godot tests | GDScript, scene, Editor и CI test runner для Godot 4.6 | Plugin/toolchain pin и adoption spike |
+| [Keira3](https://github.com/azerothcore/Keira3) | REFERENCE | AzerothCore DB editor | Field semantics, SQL generation и DB editor UX | AGPL; schema-specific web architecture |
+| [WowBench](https://sourceforge.net/projects/wowbench/) | REFERENCE | WoW UI/API | Offline XML/Lua API emulation и addon test ideas | Старый и неполный implementation |

 ## rilua — карточка кандидата

@@ -79,6 +85,22 @@ Decision/ADR:
 - **Known gaps:** совместимость `.mmap/.mmtile` и параметров TrinityCore/AzerothCore не доказана.
 - **Spike:** synthetic + one WoW tile comparison с C++ Recast; затем отдельный server mmap compatibility experiment.

+## warcraft-rs — карточка кандидата
+
+- **Problem solved:** единый CLI/library set для MPQ, DBC, BLP, ADT, WDT, WDL, M2 и WMO версий 1.12.1–5.4.8, включая заявленную full support 3.3.5a.
+- **Planned boundary:** сначала внешний pinned CLI как independent parser/validator oracle; не заменять текущий native pipeline автоматически.
+- **License:** MIT OR Apache-2.0.
+- **Spike:** сравнить OpenWC и warcraft-rs на synthetic/corrupt/real local fixtures: parsed counts, bounds, flags, alpha, materials, animations и diagnostics.
+- **Decision policy:** отдельные crates рассматриваются только если дают доказанное преимущество; Rust runtime/toolchain не вводится ради дублирования работающего C++ parser.
+
+## GdUnit4 — карточка кандидата
+
+- **Problem solved:** Godot 4 GDScript/scene tests, assertions, mocks, input simulation, command-line and JUnit reports.
+- **Planned boundary:** development/test plugin only; production export не зависит от test framework.
+- **License:** MIT.
+- **Spike:** закрепить совместимую с Godot 4.6.1 версию; проверить pure GDScript, scene lifecycle, input, EditorPlugin и headless CI sample; измерить startup overhead.
+- **Decision policy:** ADOPTED только после воспроизводимого Windows/headless run и отсутствия конфликта с project plugins.
+
 ## Процесс добавления инструмента

 1. Добавить карточку со статусом `REFERENCE` или `CANDIDATE`.
@@ -0,0 +1,18 @@
+# OpenWC Module Documentation
+
+Модульные спецификации создаются по [`TEMPLATE.md`](TEMPLATE.md) и правилам [`../DOCUMENTATION_STANDARD.md`](../DOCUMENTATION_STANDARD.md).
+
+## Registry
+
+| Module | Current status | Primary specification |
+|---|---|---|
+| Foundation/data | Planned/Partial | [`../../targets/roadmap/01-foundation-and-data.md`](../../targets/roadmap/01-foundation-and-data.md) |
+| Renderer | Partial | [`world-renderer.md`](world-renderer.md), [`../../RENDER.md`](../../RENDER.md) |
+| Network/session | Planned | [`../../targets/roadmap/03-network-and-session.md`](../../targets/roadmap/03-network-and-session.md) |
+| Gameplay | Prototype/Planned | [`../../targets/roadmap/04-gameplay-systems.md`](../../targets/roadmap/04-gameplay-systems.md) |
+| UI/Lua/audio | Prototype/Planned | [`../../targets/roadmap/05-ui-lua-audio.md`](../../targets/roadmap/05-ui-lua-audio.md) |
+| Editor/content tools | Prototype/Planned | [`../../targets/roadmap/06-editor-and-content-tools.md`](../../targets/roadmap/06-editor-and-content-tools.md) |
+| Server adapters | Planned | [`../../targets/roadmap/07-server-emulator-integration.md`](../../targets/roadmap/07-server-emulator-integration.md) |
+| Quality/release | Partial | [`../../targets/roadmap/08-quality-and-release.md`](../../targets/roadmap/08-quality-and-release.md) |
+
+Roadmap-файл описывает полную целевую программу. При начале реализации самостоятельной подсистемы создаётся отдельный module spec, показывающий фактический статус и текущий data flow.
@@ -0,0 +1,127 @@
+# <Module Name>
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Planned / Prototype / Partial / Implemented / Verified / Deprecated |
+| Target/work package | |
+| Owners | |
+| Last verified | `<commit>, YYYY-MM-DD` |
+| Profiles/capabilities | |
+
+## Purpose
+
+
+## Non-goals
+
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Input[Input contract] --> Module[Module]
+    Module --> Output[Output contract]
+```
+
+Allowed dependencies:
+
+-
+
+Forbidden dependencies:
+
+-
+
+## Public API
+
+| Symbol | Kind | Purpose | Thread/lifetime | Errors |
+|---|---|---|---|---|
+
+## Inputs and outputs
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+
+Side effects:
+
+-
+
+## Data flow
+
+```mermaid
+flowchart LR
+    Source --> Transform --> Result
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created
+    Created --> Ready
+    Ready --> Stopped
+    Stopped --> [*]
+```
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant A as Producer
+    participant M as Module
+    participant B as Consumer
+    A->>M: Input
+    M-->>B: Output
+```
+
+## Ownership, threading and resources
+
+
+## Errors, cancellation and recovery
+
+| Failure | Detection | Behavior | Diagnostic | Recovery |
+|---|---|---|---|---|
+
+## Configuration and capabilities
+
+| Setting/capability | Default | Profile | Runtime mutable | Effect |
+|---|---|---|---|---|
+
+## Persistence, cache and migration
+
+
+## Diagnostics and observability
+
+- Logs:
+- Metrics:
+- Debug views:
+- Correlation IDs:
+
+## Verification
+
+- Unit/contract tests:
+- Integration/E2E:
+- Fidelity evidence:
+- Performance budgets:
+- Manual diagnostics:
+
+## Extension points
+
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+
+## Known gaps and risks
+
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+
+## Related decisions and references
+
+- ADR:
+- Upstream/reference:
@@ -0,0 +1,248 @@
+# World Renderer
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Partial |
+| Target/work package | M00 active; декомпозиция M01–M03 |
+| Owners | Renderer workstream / milestone integrator |
+| Last verified | `93bfe11` + M00 worktree baseline, 2026-07-10 |
+| Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |
+
+## Purpose
+
+Загрузить и визуализировать мир WoW 3.3.5a вокруг streaming focus: terrain, ADT placements, M2, WMO, liquids, sky/light и character/world presentation experiments. Система должна скрывать I/O/parsing/finalization latency за prewarm и per-frame budgets.
+
+## Non-goals
+
+- Не владеет gameplay/world authoritative state.
+- Не читает network packets или server DB.
+- Не определяет player input/movement rules.
+- Не является Content Project или editor source of truth.
+- Текущий module не заявляет визуальное соответствие `1:1`; gaps ведутся в [`../../RENDER.md`](../../RENDER.md).
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Focus[Camera/player/editor focus] --> Loader[StreamingWorldLoader]
+    Assets[Extracted WDT/ADT/M2/WMO/BLP] --> Native[Native loaders]
+    Cache[Baked terrain/M2/WMO caches] --> Loader
+    Native --> Parsed[Parsed tile/model data]
+    Parsed --> Loader
+    Loader --> Scene[SceneTree nodes]
+    Loader --> RS[RenderingServer RIDs/MultiMesh]
+    Sky[DBC sky/light data] --> SkyController[WowSkyController]
+    SkyController --> Scene
+```
+
+Allowed dependencies:
+
+- native format loaders;
+- render builders/material helpers;
+- immutable/cached render resources;
+- renderer configuration and focus;
+- Godot rendering/scene APIs.
+
+Forbidden dependencies:
+
+- packet codecs/world session;
+- gameplay reducers/quest/combat state;
+- runtime UI Controls;
+- direct TrinityCore/AzerothCore database access.
+
+## Public API
+
+Текущая система ещё не имеет стабильного facade. Фактический integration surface — `StreamingWorldLoader` Node3D и exported properties. M03 должен заменить этот surface на `WorldRenderFacade`.
+
+| Symbol | Kind | Purpose | Thread/lifetime | Errors |
+|---|---|---|---|---|
+| `map_name` | Exported property | WDT/map directory name | Set before world load | Missing WDT produces diagnostic/empty world |
+| `extracted_dir` | Exported property | Root of legally extracted client data | Session lifetime | Missing files reported per loader path |
+| `camera_path` | Exported property | Current streaming focus compatibility path | Main thread, scene lifetime | Missing camera prevents normal focus update |
+| `quality_preset` | Exported property | Applies renderer budgets/radii | Before/at runtime depending property | Invalid combination should be diagnosed |
+| `runtime_stats_enabled` | Exported property | Enables periodic performance snapshot | Runtime mutable | Logging overhead only |
+| `hitch_profiler_enabled` | Exported property | Enables named hitch sections | Runtime mutable | Logging overhead only |
+
+Публичным contract не считаются внутренние dictionaries, queues, job records и generated node names.
+
+## Inputs and outputs
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+| Input | Map/focus/configuration | Scene/app/editor | `StreamingWorldLoader` | Caller config, copied/read | Main thread/session |
+| Input | WDT/ADT/M2/WMO/BLP bytes | Extracted asset repository | Native loaders/builders | Loader result owns parsed data | Worker or controlled load |
+| Input | Baked resources | Cache build tools | Streamer/builders | Shared immutable resource/cache entry | Session/cache lifetime |
+| Output | Desired tile/detail operations | Streaming planner inside loader | Finalize queues | Loader-owned | Cross-frame |
+| Output | Terrain/M2/WMO/liquid instances | Loader/builders | Godot world/renderer | Loader/world owner | Main-thread attach |
+| Output | Metrics/diagnostics | Hitch/stat instrumentation | Logs/baseline tools | Immutable records | Periodic/frame |
+
+Side effects:
+
+- reads extracted files and generated caches;
+- creates/frees scene nodes, meshes, materials, MultiMeshes and RIDs;
+- submits worker tasks;
+- mutates shader globals/environment through render/sky paths;
+- writes logs and baseline captures through tools.
+
+## Data flow
+
+```mermaid
+flowchart TD
+    F[Streaming focus] --> T[Compute desired ADT tiles]
+    WDT[WDT tile catalog] --> T
+    T --> Q[Tile load queue]
+    Q --> P[Worker parse/cache load]
+    P --> R[Result queues]
+    R --> B[Per-frame budget scheduler]
+    B --> Terrain[Terrain attach/upgrade]
+    B --> M2[M2 group/MultiMesh attach]
+    B --> WMO[WMO instance/group attach]
+    B --> Liquid[Liquid attach]
+    Terrain --> World[Godot world]
+    M2 --> World
+    WMO --> World
+    Liquid --> World
+    F --> E[Eviction/retention decisions]
+    E --> World
+```
+
+## Lifecycle/state
+
+```mermaid
+stateDiagram-v2
+    [*] --> Initializing
+    Initializing --> Ready: WDT/catalog/config ready
+    Initializing --> Degraded: missing loaders/data/cache
+    Ready --> Streaming: focus update
+    Streaming --> Streaming: load/finalize/evict ticks
+    Streaming --> SwitchingMap: map/focus reset
+    SwitchingMap --> Initializing
+    Ready --> ShuttingDown
+    Degraded --> ShuttingDown
+    Streaming --> ShuttingDown
+    ShuttingDown --> [*]
+```
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant Focus as Camera/Player/Editor
+    participant Stream as StreamingWorldLoader
+    participant Worker as Worker task
+    participant Budget as Main-thread budget
+    participant Render as SceneTree/RenderingServer
+    Focus->>Stream: focus position changed
+    Stream->>Stream: desired tiles and priorities
+    Stream->>Worker: parse/load tile and detail data
+    Worker-->>Stream: immutable result
+    Stream->>Budget: enqueue finalize operations
+    Budget->>Render: attach bounded terrain/M2/WMO/liquid work
+    Stream->>Render: evict outside retention range
+```
+
+## Ownership, threading and resources
+
+- `StreamingWorldLoader` владеет tile states, queues, task registries, active world instances и render caches session scope.
+- Worker tasks не должны менять SceneTree и shared Resource concurrently.
+- Parsed/grouped results передаются обратно через guarded result queues.
+- Mesh/material/node/RID finalization выполняется main thread и ограничивается exported budgets.
+- Shutdown/map switch обязан отменить/дождаться jobs и освободить RIDs; M00 всё ещё фиксирует leaked-resource risk.
+- Cache resources считаются immutable после публикации.
+
+## Errors, cancellation and recovery
+
+| Failure | Detection | Behavior | Diagnostic | Recovery |
+|---|---|---|---|---|
+| Missing WDT/ADT | File/catalog check | Tile/map unavailable | Loader warning/error | Fix extraction/profile, reload |
+| Cache version mismatch | Required format constant | Reject stale cache/fallback | Version diagnostic | Rebuild matching cache |
+| Worker failure | Task result/empty data | Skip/degrade affected asset | Queue/task warning | Retry/rebuild source |
+| Main-thread hitch | Named section timing | Frame spike, work remains queued | `HITCH` log | Lower budget/fix finalize path |
+| D3D12 descriptor exhaustion | Rendering backend error | Render failure/fallback backend | Godot error + baseline report | Dedup resources/fix settings |
+| Teleport/map change | Focus/session transition | Old jobs become stale | Target/session generation | Cancel/drop stale results |
+| Shutdown leak | Godot leak/RID diagnostics | Resource retained | Shutdown report | Ownership cleanup before DONE |
+
+## Configuration and capabilities
+
+| Setting/capability | Default | Profile | Runtime mutable | Effect |
+|---|---|---|---|---|
+| Quality preset | Scene-specific | All | Limited | Applies radii and finalize budgets |
+| Terrain control splat | Enabled in current High paths | Render | Limited | Near terrain texture quality |
+| M2/WMO/liquids | Scene/profile-specific | Render | Debug/config | Enables asset categories |
+| Runtime stats/hitch profiler | Usually debug | Dev/test | Yes | Observability cost |
+| Shadow flags | Mostly disabled/limited | Blizzlike/Enhanced | Profile | CPU/GPU cost and visuals |
+
+Exact exported settings and cache versions remain documented in [`../../RENDER.md`](../../RENDER.md) until extracted services receive individual specs.
+
+## Persistence, cache and migration
+
+- Renderer reads caches under `data/cache`; caches are not committed.
+- Format changes require `FORMAT_VERSION`/required-version bump and rebuild instructions.
+- Atomic cache publication and unified manifest are target-state work from FND/M03.
+- Material-only changes may refresh without geometry rebake only when documented safe.
+
+## Diagnostics and observability
+
+- Logs: `HITCH`, `PERF`, `TERRAIN_QUALITY`, `SKY_LIGHT`, `SKYBOX_MODEL`.
+- Metrics: queue depths, active tiles/assets, named finalize times, frame percentiles and max hitch.
+- Debug views: render checkpoint scenes/captures; future streaming/LOD/portal overlays.
+- Correlation IDs: currently mostly tile/path keys; target architecture adds session/job IDs.
+
+## Verification
+
+- Unit/contract tests: material mapping, unique-ID dedupe, placement probes, baseline manifest.
+- Integration/E2E: Eastern Kingdoms/Kalimdor streaming scenes and seven cold/warm checkpoints.
+- Fidelity evidence: current fixed-position captures exist; approved original-client paired screenshots are still missing.
+- Performance budgets: M00 report records cold/warm p95 and max hitch; no final acceptance threshold yet.
+- Manual diagnostics: [`../RENDER_BASELINE.md`](../RENDER_BASELINE.md) and [`../../RENDER.md`](../../RENDER.md).
+
+## Extension points
+
+- Target `WorldRenderFacade` for runtime/editor/capture callers.
+- Target `StreamingFocus` independent of Camera3D.
+- Extracted planner, budget scheduler, terrain, M2, WMO, liquid, sky and character services.
+- Separate Blizzlike/Enhanced material and quality profiles.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| ADT streaming/terrain | Partial | M00 checkpoints and current scenes | Fidelity/performance gaps remain |
+| Static M2 placement | Partial | MultiMesh/dedupe probes | Full materials/animation/effects |
+| WMO rendering | Partial | Cached group rendering | Portals/rooms/material parity |
+| Liquids | Partial | MH2O/MLIQ paths | LiquidType/depth/shore fidelity |
+| Sky/light | Partial | DBC controller/logs | Zone transition paired validation |
+| Character presentation | Prototype | Character creator/player experiment | Full customization/equipment states |
+| Stable renderer facade | Planned | M03 | Current caller uses monolithic Node API |
+
+## Known gaps and risks
+
+- Monolithic streamer mixes planning, jobs, caches and presentation.
+- Direct camera path remains until M01/M03.
+- Original-client paired fidelity evidence incomplete.
+- D3D12 descriptor and shutdown RID/resource issues remain.
+- M2/WMO/material/particle/ribbon/portal parity incomplete.
+- Public API is mostly exported configuration rather than stable contracts.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/scenes/streaming/streaming_world_loader.gd` | Current runtime orchestration, queues, caches and attachment |
+| `addons/mpq_extractor/loaders/adt_builder.gd` | Terrain/material/liquid construction |
+| `addons/mpq_extractor/loaders/m2_builder.gd` | Static M2 mesh/material construction |
+| `addons/mpq_extractor/loaders/m2_native_animated_builder.gd` | Native animated M2 experiment |
+| `addons/mpq_extractor/loaders/wmo_builder.gd` | WMO groups/doodads/liquids construction |
+| `src/scenes/sky/wow_sky_controller.gd` | DBC-driven sky/light/environment |
+| `src/native/src/*_loader.cpp` | Native binary parsing |
+| `src/tools/build_*cache.gd`, `src/tools/bake_*cache.gd` | Offline cache generation |
+| `tools/run_render_baseline.ps1` | Unified M00 baseline runner |
+
+## Related decisions and references
+
+- [`../../RENDER.md`](../../RENDER.md)
+- [`../RENDER_BASELINE.md`](../RENDER_BASELINE.md)
+- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)
+- [`../GODOT_BEST_PRACTICES.md`](../GODOT_BEST_PRACTICES.md)
@@ -6,6 +6,8 @@

 Последовательно закрыть всю матрицу `docs/CLIENT_FEATURES.md` до подтверждённой совместимости.

+Работа выполняется completeness waves C1–C8 из [`DEVELOPMENT_ROADMAP.md`](DEVELOPMENT_ROADMAP.md) с обязательным чтением gameplay, UI/audio, server и quality subsystem plans. Этот target не разрешает массово реализовывать все пункты одновременно.
+
 ## Required order

 - [ ] Combat, spells, casting, cooldowns, auras, death/resurrection.
@@ -0,0 +1,150 @@
+# OpenWC Full Development Roadmap
+
+## Назначение
+
+Этот документ — полная инженерная карта разработки OpenWC. Статусы и последовательность исполняемых milestones остаются в [`README.md`](README.md); детальные subsystem plans находятся в [`roadmap/`](roadmap/). При расхождении текущий target определяет, что делать сейчас, а этот roadmap — как решение должно развиваться целиком.
+
+Godot-specific implementation rules обязательны из [`../docs/GODOT_BEST_PRACTICES.md`](../docs/GODOT_BEST_PRACTICES.md).
+
+## Итоговый продукт
+
+OpenWC должен предоставить четыре согласованных режима:
+
+1. `Blizzlike335` — клиент WoW 3.3.5a build 12340 с максимально точным наблюдаемым поведением.
+2. `Enhanced` — opt-in графические, UX и accessibility улучшения, не меняющие wire protocol и server authority без отдельного profile.
+3. `AuthoringStudio` — инструменты мира, контента, БД и playtest внутри Godot Editor.
+4. `HeadlessTools` — import, validation, bake, packet replay, content build и CI без GUI.
+
+Один кодовый путь должен обслуживать runtime и editor preview через публичные contracts. Generated preview nodes, DB records и caches не являются источником истины.
+
+## Текущее положение
+
+- MPQ/BLP/ADT/WDT/M2/WMO native parsing и renderer vertical slice уже существуют.
+- Runtime streaming, terrain quality, MultiMesh M2, WMO caches, liquids, sky и character experiments находятся в рабочем состоянии, но сосредоточены в крупных orchestration scripts.
+- Renderer baseline M00 создан; до `DONE` не хватает paired comparison с оригинальным клиентом и закрытия известных diagnostic gaps.
+- Gameplay domain, network protocol, production UI/Lua, audio orchestration и server adapters в основном предстоит реализовать.
+- Editor plugin пока решает extraction/preview задачи, но не является полноценной authoring platform.
+
+## Инженерные программы
+
+| Код | Программа | Детальный план |
+|---|---|---|
+| FND | Foundation, application и data | [01-foundation-and-data.md](roadmap/01-foundation-and-data.md) |
+| RND | Renderer и graphics | [02-rendering-and-graphics.md](roadmap/02-rendering-and-graphics.md) |
+| NET | Protocol, session и synchronization | [03-network-and-session.md](roadmap/03-network-and-session.md) |
+| GMP | Gameplay systems | [04-gameplay-systems.md](roadmap/04-gameplay-systems.md) |
+| UIA | UI, Lua, addons, audio | [05-ui-lua-audio.md](roadmap/05-ui-lua-audio.md) |
+| EDT | Godot Editor и content authoring | [06-editor-and-content-tools.md](roadmap/06-editor-and-content-tools.md) |
+| SRV | TrinityCore/AzerothCore integration | [07-server-emulator-integration.md](roadmap/07-server-emulator-integration.md) |
+| QAR | Fidelity, tests, CI и releases | [08-quality-and-release.md](roadmap/08-quality-and-release.md) |
+
+## Dependency graph
+
+```text
+M00 renderer baseline
+  └─ M01 coordinates/contracts
+      └─ M02 input/movement/camera/presentation split
+          └─ M03 renderer facade
+              ├─ M04 editor shell → M05 content → M06 server adapters → M07 world editor
+              └─ M08 network → M09 gameplay domain → M10 playable client
+                                      M07 + M10 → M11 quest end-to-end
+                                                       └─ M12 completeness waves
+                                                            └─ M13 dungeon authoring
+```
+
+M12 не является одним большим этапом. Он выполняется последовательными completeness waves:
+
+1. `C1 Core loop` — combat, spells, auras, death, loot, inventory, quests.
+2. `C2 Character` — creation/customization, equipment, animation, pets, mounts.
+3. `C3 World` — map/minimap, exploration, taxi, transports, weather, audio.
+4. `C4 Services` — gossip, vendors, trainers, bank, mail, auction, professions.
+5. `C5 Social` — chat, friends, ignore, party, raid, guild, calendar.
+6. `C6 Instances/PvP` — lockouts, LFG, vehicles, battlegrounds, arenas, outdoor PvP.
+7. `C7 UI/addons` — FrameXML, Lua 5.1.1, secure execution, default UI, compatibility tiers.
+8. `C8 Fidelity/polish` — complete render/material/audio coverage, recovery, accessibility, localization и performance.
+
+Каждая wave должна завершаться работающим gameplay scenario, а не количеством реализованных opcodes или таблиц.
+
+## Milestone delivery matrix
+
+| Milestone | Основные work packages | Обязательный результат |
+|---|---|---|
+| M00 | RND baseline, QAR metrics/fidelity lab | Воспроизводимые checkpoints и gaps |
+| M01 | FND typed coordinates/IDs/contracts | Server/ADT/Godot round-trip и StreamingFocus |
+| M02 | FND composition, GMP movement, RND presenters | Player split без visual/control regression |
+| M03 | RND facade/planner/scheduler, FND jobs | Renderer доступен через API и сохраняет budgets |
+| M04 | EDT plugin shell, QAR editor tests | Reload-safe workspace, commands, undo/recovery |
+| M05 | FND content schemas/cache, EDT project | Deterministic Content Project build/migration |
+| M06 | SRV environments/snapshots/adapters | Two-core read/diff/dry-run round-trip |
+| M07 | EDT world editing/navigation/deploy | NPC placement на dev-core без ручного SQL |
+| M08 | NET transport/auth/protocol/entities | Headless auth → world и deterministic replay |
+| M09 | GMP world state/movement/targeting | Packet replay → deterministic gameplay snapshot |
+| M10 | FND app lifecycle, RND/UIA presentation | Игрок входит, видит entities и перемещается |
+| M11 | GMP quests, EDT quest tools, SRV deploy, UIA quest UI | Author → deploy → complete quest своим клиентом |
+| M12 C1–C8 | NET/GMP/RND/UIA completeness + QAR | Feature matrix `Compatible/Verified` по waves |
+| M13 | EDT dungeon/encounter, SRV modules, GMP instances | Custom dungeon group playtest end-to-end |
+
+## Recommended implementation rhythm
+
+Каждая feature внутри milestone проходит один и тот же цикл:
+
+1. `Research` — original behavior, core expectations, готовые tools/references.
+2. `Contract` — owner, types, commands/events, capabilities и error states.
+3. `Fixture` — golden input/output или reproducible live scenario до production code.
+4. `Pure implementation` — parser/reducer/validator без Node where possible.
+5. `Adapter` — network, renderer, UI, Editor или server boundary.
+6. `Vertical integration` — минимальный observable player/author outcome.
+7. `Failure/recovery` — malformed, cancel, disconnect, rollback, missing asset.
+8. `Fidelity/performance` — comparison evidence и budgets.
+9. `Documentation` — coverage status, known gaps, tooling decision и target evidence.
+
+## Cross-cutting contracts
+
+- `BuildProfile` — `Blizzlike335`, `Enhanced`, authoring и test capabilities.
+- `CoordinateMapper` — единственное преобразование WoW/Godot/ADT/server coordinates.
+- `AssetRepository` — original assets, overlays, caches и provenance.
+- `ProtocolProfile` — build, opcodes, update fields, codecs и server capabilities.
+- `WorldState` — authoritative client-side projection без Node dependencies.
+- `WorldRenderFacade` — presentation boundary.
+- `ViewModel/Intent` — единственная граница UI с gameplay.
+- `LuaRuntime` — заменяемый Lua backend.
+- `ContentProject` — stable IDs, schemas, dependencies и user-authored source.
+- `ServerSchemaAdapter` — canonical content ↔ core schema/change set.
+- `JobScheduler` — bounded background work, cancellation, progress и main-thread finalize.
+- `Diagnostic` — code, severity, location, context, suggested fix и correlation ID.
+
+## Архитектурные gates
+
+Перед переходом между крупными фазами обязательны:
+
+- `Architecture gate`: запрещённые зависимости отсутствуют.
+- `Fidelity gate`: есть comparison evidence, а gaps зарегистрированы.
+- `Data gate`: schema/version/migration и deterministic build проверены.
+- `Performance gate`: budgets измерены на cold/warm и stress scenarios.
+- `Recovery gate`: failure/reconnect/cancel/rollback проверены.
+- `Authoring gate`: изменения можно создать, проверить, diff, undo и воспроизвести.
+- `Server gate`: обе схемы не предполагаются одинаковыми, capabilities обнаружены явно.
+
+## Правило улучшений
+
+Современное улучшение допускается, если:
+
+1. исходное поведение `Blizzlike335` уже измерено или gap отмечен;
+2. улучшение включается отдельным setting/profile;
+3. оно не меняет protocol/server authority скрыто;
+4. есть before/after visual/performance/accessibility evidence;
+5. Content Project указывает required capability и fallback.
+
+Примеры допустимых opt-in улучшений: modern shadows, higher terrain texture resolution, anisotropy, enhanced water, longer draw distance, FSR/upscaling, color-blind palettes, scalable UI, richer editor diagnostics. Новые gameplay rules требуют server module/profile, а не только client toggle.
+
+## Definition of complete client
+
+Клиент считается полным не тогда, когда перечислены все packet handlers, а когда:
+
+- все строки [`../docs/CLIENT_FEATURES.md`](../docs/CLIENT_FEATURES.md) имеют evidence-backed статус;
+- основные сценарии оригинального клиента воспроизводятся end-to-end;
+- default UI и выбранные addons проходят compatibility tiers;
+- supported TrinityCore/AzerothCore profiles проходят contract matrix;
+- renderer, audio, input, localization и recovery имеют утверждённые gaps/budgets;
+- AuthoringStudio может создать, проверить, развернуть и протестировать новый quest/location/dungeon package;
+- release не содержит proprietary assets и требует легально полученную установку клиента.
@@ -4,12 +4,18 @@

 Этот каталог задаёт обязательную последовательность реализации. Архитектура описана в `docs/`, фактическое состояние renderer — в `RENDER.md`, а здесь находятся исполняемые milestones.

+Полная инженерная декомпозиция всех подсистем находится в [`DEVELOPMENT_ROADMAP.md`](DEVELOPMENT_ROADMAP.md). Перед работой над milestone агент читает соответствующий subsystem plan из `targets/roadmap/`, но статус меняет только в исполняемом target-файле M00–M13.
+
+Параллельная командная работа выполняется по [`../docs/TEAM_WORKFLOW.md`](../docs/TEAM_WORKFLOW.md): отдельные worktrees, claims, exclusive paths, contract-first и интегратор milestone.
+
 ## Current target

 `M00` — [00-render-baseline.md](00-render-baseline.md)

 Одновременно `ACTIVE` может быть только одна цель. Следующая цель становится `ACTIVE` после появления валидной `OPENWC_TARGET_DONE` метки у предыдущей.

+Статусные метки применяются только к исполняемым файлам `targets/[0-9][0-9]-*.md`. `DEVELOPMENT_ROADMAP.md` и `targets/roadmap/` являются нормативной декомпозицией, но не создают параллельную систему статусов.
+
 ## Definition of fidelity 1:1

 `1:1` означает совпадение наблюдаемого поведения с оригинальным клиентом WoW 3.3.5a build 12340 для выбранного сценария:
@@ -42,6 +48,8 @@
 | M12 | [WoW 3.3.5a completeness](12-client-completeness.md) | M11 | OPEN |
 | M13 | [Dungeon authoring](13-dungeon-authoring.md) | M12 foundation | OPEN |

+M12 выполняется восемью completeness waves, определёнными в [`DEVELOPMENT_ROADMAP.md`](DEVELOPMENT_ROADMAP.md), а не одной массовой реализацией.
+
 M07 и M08 могут выполняться параллельными командами только после M06/M03 соответственно и только если пользователь явно разрешил параллельную работу. Их результаты сходятся в M11.

 `recast-rs` запланирован как optional navigation backend в M05, исследовательский CLI spike и world validation в M07, затем полноценная dungeon navigation validation в M13. Он не блокирует M00–M04 и не считается автоматически совместимым с server `mmaps`.
@@ -59,6 +67,8 @@ Wowser зарегистрирован как независимый MIT referenc
 - renderer checkpoints при изменении рендера;
 - отсутствие новых нарушений dependency rules;
 - обновлённые документы и diagnostics;
+- выполнен documentation gate: inline public API, module spec, inputs/outputs и обязательные diagrams;
+- проходят `tools/verify_coordination.ps1` и `tools/verify_documentation.ps1`;
 - воспроизводимость без proprietary данных в Git.

 ## Evidence format
@@ -0,0 +1,86 @@
+# FND — Foundation, Application and Data
+
+## Цель
+
+Создать стабильную платформу, на которой renderer, client runtime и Godot Editor могут развиваться независимо, используя одинаковые типы и build artifacts.
+
+## FND-1. Project profiles и configuration
+
+- Ввести `BuildProfile` и `CapabilitySet`.
+- Отделить user settings, developer settings, server connection profiles и content project settings.
+- Secrets хранить вне Git/Resource; поддержать environment/OS credential provider.
+- Настройки иметь schema version, defaults, validation, migration и reset-by-section.
+- `Blizzlike335` сделать неизменяемым базовым профилем; enhanced settings наследуют его явно.
+
+## FND-2. Application lifecycle
+
+- Реализовать state machine `Boot → DataCheck → Login → Realm → Character → Loading → InWorld → Disconnect/Recovery`.
+- Editor, sandbox и headless modes запускать разными composition roots.
+- Dependency injection выполнять composition layer; не использовать scene lookup как service locator.
+- Autoload ограничить действительно process-wide lifecycle services. Gameplay, renderer и editor sessions должны инстанцироваться и освобождаться явно.
+- Каждое состояние иметь cancellation, timeout, diagnostics и deterministic cleanup.
+
+## FND-3. Domain primitives
+
+- Typed IDs: content, server entry, entity, GUID, map, area, spell, item, quest, display и sound.
+- Typed coordinates и orientation; запретить `Vector3` как межслойный wire/domain contract.
+- Value objects для locale, money, duration, percentage, level, power type и flags.
+- Commands/events/read models не наследуют Node/Resource.
+- Serialization version и unknown-field policy определить до сохранения snapshots/replays.
+
+## FND-4. Asset repository
+
+- Описать archive chain/locale/patch precedence для 3.3.5a.
+- Отделить `original source → parsed canonical data → imported Godot resource → runtime cache`.
+- Ввести provenance: source archive/path/hash, parser version, import profile и dependency hashes.
+- Не изменять extracted upstream files; custom content подключать ordered overlays.
+- Dedup textures/materials/meshes по canonical key, а не по случайной Node lifetime.
+- Missing/corrupt asset policy: placeholder только в dev profile, structured error в fidelity runs.
+
+## FND-5. Binary formats и typed tables
+
+- MPQ: archive ordering, locale, listfile absence, encrypted/compressed entries.
+- BLP: paletted/DXT, alpha depths, mip chains, color space и wrap/filter metadata.
+- DBC: schema descriptors, localized strings, relationships, hot reload только в authoring mode.
+- WDT/WDL/ADT: tile existence, terrain, holes, layers, placements, liquids, distant data.
+- M2/SKIN/WMO: versioned structs, bounds, batches, materials, animation, attachments, portals.
+- Audio/interface assets: MP3/WAV, fonts, XML, Lua, TOC и SavedVariables formats.
+- Parser API возвращает typed result + diagnostics; partial parse не маскируется как success.
+- Differential tests сравнивают текущие parsers с независимыми implementations (`warcraft-rs`, `wow_dbc`, WowDBDefs-driven schemas) на одинаковых fixtures; reference disagreement регистрируется, а не выбирается по большинству.
+
+## FND-6. Cache and build pipeline
+
+- Единый content-addressed cache manifest для terrain/M2/WMO/characters/audio/navigation/UI.
+- Atomic staging → verify → publish; crash не оставляет валидно выглядящий partial artifact.
+- Cache version включает schema, parser, shader/material contract и profile.
+- Headless commands используют те же services, что Editor actions.
+- Добавить dependency graph и incremental rebuild по hash.
+- Папки generated/cache исключить из Git и при необходимости из Godot import через `.gdignore`.
+
+## FND-7. Native boundary
+
+- GDExtension использовать для binary parsing, compression/crypto, large buffer transforms и измеренных hot paths.
+- GDScript использовать для orchestration, Editor UI и presentation composition.
+- Перед добавлением Rust/C/C++ dependency фиксировать ABI boundary и ownership.
+- Через native boundary передавать packed arrays/immutable result objects, избегать вызова на каждый vertex/instance.
+- Версию Godot/GDExtension API закрепить; обновление проходит compatibility matrix.
+
+## FND-8. Jobs and concurrency
+
+- Общий `JobScheduler`: priority, bounded capacity, cancellation, progress, correlation ID.
+- Pure CPU work выполняется workers; scene tree и GPU resources финализируются main thread budget.
+- Один resource не модифицируется конкурентно; shared mutable collections защищаются.
+- Каждый submitted worker task дожидается completion/cleanup.
+- Session/world unload отменяет jobs и освобождает RIDs/resources детерминированно.
+
+## Deliverables
+
+- Foundation package без renderer/network dependencies.
+- Headless data probe и cache inspector.
+- Coordinate/parser/cache fixtures.
+- Architecture dependency checker.
+- Документированные memory/thread ownership rules.
+
+## Gate
+
+Одинаковые входы дают одинаковые manifests; application modes собираются разными roots; domain тестируется без SceneTree; cancellation и shutdown не оставляют jobs/RIDs.
@@ -0,0 +1,102 @@
+# RND — Rendering and Graphics
+
+## Цель
+
+Воспроизвести визуальные правила WoW 3.3.5a и дать opt-in улучшения, сохранив frame pacing на больших мирах Godot.
+
+## RND-1. Renderer architecture
+
+- `WorldRenderFacade` принимает focus, environment snapshot и entity presentation commands.
+- `StreamingTargetPlanner` вычисляет desired state без Node creation.
+- `RenderBudgetScheduler` ограничивает main-thread finalize по типам операций.
+- Terrain, M2, WMO, liquid, sky, character, effects и debug overlays — отдельные services.
+- RenderingServer/RIDs применяются только там, где profiler доказал overhead scene tree.
+- Ownership каждого RID и cache entry документируется; world unload проверяет leaks.
+
+## RND-2. World streaming
+
+- WDT-driven tile catalog, priority по position/direction/velocity/camera frustum.
+- Prewarm, retain и hysteresis исключают churn на ADT boundaries.
+- Separate budgets для I/O, parse, mesh/material load, main-thread attach и eviction.
+- Cold/warm cache scenarios, teleport, rapid flight и camera rotation stress.
+- Cancellation stale jobs при teleport/map change.
+- Streaming focus не обязан быть Camera3D: player, spectator, editor viewport, capture tool.
+
+## RND-3. Terrain
+
+- Точная 145-vertex MCNK topology, holes, normals и coordinate seams.
+- Texture layer order, MCAL alpha variants, animation flags, repeat и mip behavior.
+- Control-splat/array implementation как Godot optimization с fidelity tests.
+- WDL/distant terrain и hierarchical LOD.
+- Terrain collision/query representation отдельно от visual mesh.
+- Editing path: sculpt, smooth, flatten, holes, texture paint, seam repair и rebake.
+
+## RND-4. M2
+
+- Static geometry, SKIN batches, blend modes, flags, UV transforms и texture lookup.
+- Native pivot-based skeletal animation, bone palettes, global sequences и animation lookup.
+- Billboards, attachments, key bones, events, cameras и bounding volumes.
+- Particles, ribbons, texture animation и material combiners.
+- Static doodads группировать spatial MultiMesh cells; animated/interactive entities не смешивать со static batching.
+- MultiMesh buffer updates выполнять батчем; cell size выбирать по culling, а не только draw-call minimum.
+
+## RND-5. WMO
+
+- Root/group materials, batches, vertex colors, multiple UV sets и doodad sets.
+- Portals/rooms, indoor/outdoor, BSP/collision, fog и group visibility.
+- MLIQ, skybox, lights и ambient color semantics.
+- Lightweight render cache для больших WMO и incremental group attach.
+- Editor tools для group/portal/doodad validation.
+
+## RND-6. Characters and creatures
+
+- Race/gender/customization from DBC.
+- Geosets, skin regions, hair/facial features и composited textures.
+- Equipment component models/textures, attachment points, sheath, enchant visuals.
+- Animation state resolver: locomotion, combat, casting, emotes, death, swim, mount, vehicle.
+- CreatureDisplayInfo/Extra/ModelData, NPC equipment, pets и shapeshift.
+- Character preview uses same presenter as world runtime.
+
+## RND-7. Liquids
+
+- MH2O/MCLQ layers, existence masks, heights, depth и liquid type.
+- Отдельные profiles water/ocean/magma/slime.
+- Blizzlike material: texture animation, alpha, lighting и fog behavior.
+- Enhanced material: normals, reflections, depth/shore blending — opt-in.
+- Liquid collision/swim state принадлежит gameplay/physics query, не shader.
+
+## RND-8. Environment
+
+- DBC-driven Light/LightParams/LightIntBand/LightFloatBand interpolation.
+- Server time, day/night, zone/subzone transitions.
+- Skyboxes, fog, ambient/directional light, weather visual state.
+- Blizzlike cheap shadow policy; enhanced selective character/object shadows отдельно.
+- Camera far plane, fog и streaming distances согласованы профилем.
+
+## RND-9. Effects and presentation
+
+- SpellVisual/SpellVisualKit-driven cast/impact/aura effects.
+- Projectiles, decals, dynamic objects, combat text и selection circles.
+- Weather particles и world emitters.
+- Cinematic/model cameras и loading transitions.
+- Effects have pooling, lifetime, visibility и per-frame budgets.
+
+## RND-10. Graphical extensions
+
+- Higher-resolution content overlays без модификации originals.
+- Anisotropy, extended draw distance, improved water/shadows, post-processing и upscaling.
+- Optional PBR approximation only when it does not replace Blizzlike material profile.
+- Graphics settings expose measurable cost and fallback.
+- Editor comparison viewport: Blizzlike/Enhanced side-by-side, screenshot и metric capture.
+
+## Verification
+
+- Paired checkpoints с original 3.3.5a по position/time/weather/camera.
+- Material/animation fixtures from independent references.
+- Perceptual diff плюс human approval для intentional deviations.
+- p50/p95/p99, max hitch, draw calls, visible objects, GPU/CPU memory и RID leak checks.
+- D3D12/Vulkan and quality profile matrix.
+
+## Gate
+
+Видимый мир не деградирует при декомпозиции; under-foot/near-field quality готова до появления в кадре; long traversal не создаёт recurring hitches/leaks; Enhanced всегда отключаем.
@@ -0,0 +1,94 @@
+# NET — Network, Protocol and Session
+
+## Цель
+
+Реализовать точный клиентский протокол WoW 3.3.5a build 12340, изолировав транспорт и packet layout от gameplay/UI.
+
+## NET-1. Transport
+
+- Native TCP auth/world connections, DNS/IPv4/IPv6 policy и configurable endpoints.
+- Non-blocking read/write, bounded buffers, packet fragmentation/coalescing.
+- Cancellation, connect/read/write timeouts, keepalive и orderly shutdown.
+- Network thread работает с bytes; domain events применяются game thread.
+- Proxy mode только как explicit development adapter, не основной transport.
+
+## NET-2. Authentication
+
+- Logon challenge/proof SRP6 values и exact endian/normalization rules.
+- Realm list parsing, build/locale/platform fields и error mapping.
+- World auth digest, session key и header encryption state.
+- Credentials не логируются; session material очищается при disconnect.
+- Golden vectors и сравнение с TrinityCore/AzerothCore/Wowser/Whoa implementations.
+
+## NET-3. Packet framework
+
+- `PacketReader/Writer` с checked boundaries и explicit endianness.
+- Typed opcode registry generated/validated для build 12340.
+- Header framing, ARC4/drop policy, zlib compressed packets.
+- Packed GUID, bit masks, CString/fixed strings и localized text.
+- Unknown/unsupported opcode telemetry rate-limited; policy зависит от criticality.
+- Packet handlers возвращают domain events, не меняют scenes/UI.
+
+## NET-4. Update fields and entity lifecycle
+
+- Generated object/item/container/unit/player/gameobject/dynamicobject/corpse field descriptors.
+- `SMSG_UPDATE_OBJECT` blocks: values, movement, create, create2, out-of-range, near objects.
+- Partial mask application сохраняет неизвестные/необновлённые поля корректно.
+- Entity type/entry/display/faction/health/power/flags/ownership relationships.
+- Despawn/out-of-range/map transfer не оставляют presentation entities.
+
+## NET-5. Movement synchronization
+
+- Полный movement flags set, timestamps, position/orientation, pitch, fall/jump, spline elevation.
+- Start/stop/strafe/turn/pitch/jump/fall/land/swim/fly/heartbeat packets.
+- Transport GUID/seat/relative coordinates и server spline movement.
+- Client prediction history, acknowledgements и reconciliation metrics.
+- Teleport/worldport handshake и map transfer.
+- Anti-cheat-sensitive fields формируются строго по profile; client не симулирует authoritative NPC path.
+
+## NET-6. Session domains
+
+- Character enum/create/delete/rename/login/logout.
+- Time/account data/tutorial/action bars/initial spells.
+- Chat/channel/social/group/guild.
+- Combat/spells/auras/threat.
+- Items/inventory/loot/trade/vendor/mail/auction.
+- Quests/gossip/POI/taxi.
+- Instances/LFG/PvP/vehicles/calendar.
+- Каждый domain имеет отдельный handler module, fixtures и unsupported coverage report.
+
+## NET-7. Reliability and diagnostics
+
+- State-aware disconnect reason и recovery path.
+- Reconnect только когда protocol/server допускает; иначе безопасный возврат к login.
+- Packet trace modes: metadata-only default, redacted payload для tests, encrypted secrets never.
+- Correlation IDs session/request/entity.
+- Replay transport воспроизводит timing или deterministic step mode.
+- Network impairment harness: latency, jitter, loss, duplication, fragmentation и abrupt close.
+
+## NET-8. Core compatibility
+
+- Baseline protocol один, но server capabilities/quirks задаются adapter profile.
+- Не ветвить handlers по строке `if azerothcore` без documented capability.
+- Test matrix фиксирует core commit, DB revision, modules и config.
+- Custom opcodes располагаются в namespaced extension profile и не включены в Blizzlike335.
+
+## NET-9. Warden compatibility
+
+- Зафиксировать фактические требования Warden у supported TrinityCore/AzerothCore profiles.
+- Реализовывать только compatibility с тестовыми/private server environments и документированным build 12340 flow; OpenWC не предназначен для official/retail servers.
+- Module challenge/response, crypto/state и platform behavior изолировать в optional security adapter.
+- Любое исполнение загружаемого module code sandboxed, size/hash checked и отключаемо в development profile.
+- Добавить fixtures и failure UX для unsupported/invalid challenge; не использовать subsystem для обхода чужих защитных механизмов.
+
+## Tools and references
+
+- TrinityCore/AzerothCore source — authoritative server-side packet expectations.
+- Whoa — reverse-engineered client semantics.
+- Wowser — независимый auth/world proof-of-concept и test ideas.
+- WoWee/WowUnreal — coverage и lifecycle comparison.
+- Packet captures используются только легально, минимально и с redaction.
+
+## Gate
+
+Headless client проходит auth → realm → character → world; replay создаёт одинаковые domain events; malformed packets не читаются за границы; secrets отсутствуют в logs; обе core configurations проходят contract suite.
@@ -0,0 +1,112 @@
+# GMP — Gameplay Systems
+
+## Цель
+
+Создать детерминированную клиентскую проекцию серверного gameplay и полный набор player intents WoW 3.3.5a без переноса authoritative правил на клиент.
+
+## GMP-1. World model
+
+- Typed entity registry и object hierarchy.
+- Components/read models: identity, transform, unit, player, item, gameobject, corpse, dynamic object.
+- Ownership, charm, pet, target, creator, transport и group relationships.
+- Reducers применяют domain events; presentation подписывается на changesets.
+- Snapshot/replay позволяют восстановить состояние без live socket.
+
+## GMP-2. Input and movement
+
+- Remappable action layer, keyboard/mouse и optional gamepad/accessibility mappings.
+- Walk/run/backpedal/strafe/turn/jump/fall/swim/fly/autorun.
+- Camera-relative или character-relative policy строго по original behavior.
+- Ground/collision query abstraction, slopes, water transition и falling.
+- Prediction/reconciliation только локального movement; corrections имеют smoothing/snap thresholds.
+- Debug flight/speed отделены от production profile.
+
+## GMP-3. Selection and interaction
+
+- Mouse/world picking, tab target, target/focus и target-of-target.
+- Hostility/faction/dead/visibility/selectability filters.
+- Facing, range, line-of-sight и interaction intents.
+- NPC flags определяют available services; client не выдумывает доступную функцию.
+- Gameobject use, gossip, trainer, vendor, mailbox, auctioneer, binder и flight master.
+
+## GMP-4. Combat
+
+- Auto attack/auto shot, swing state и attack stop.
+- Damage/heal/miss/absorb/resist/block/crit feedback.
+- Threat presentation, combat state, evade и unit flags.
+- Resources, regeneration presentation и combo points/runes where applicable.
+- Combat log canonical events отделены от floating text/UI formatting.
+- Server validates hit, damage и death; client показывает pending/cast state.
+
+## GMP-5. Spells and auras
+
+- Spellbook, ranks, passive/active, known/disabled spells.
+- Target requirements, range, facing, resource и client-predictable validation messages.
+- Cast/channel/interrupt/pushback, GCD и cooldowns.
+- Aura add/update/remove, stacks, duration, caster, dispel type и visibility.
+- Totems, shapeshift, pets, tracking, tradeskill casts.
+- Spell visual/audio descriptors separate from spell mechanics state.
+
+## GMP-6. Death and recovery
+
+- Death/release spirit, ghost, corpse, graveyard, reclaim delay.
+- Resurrection request/accept, spirit healer penalties.
+- Durability loss/repair и instance wipe/reset presentation.
+- Failure during map transfer/reconnect does not duplicate corpse/player state.
+
+## GMP-7. Items and economy
+
+- Inventory slots, bags, bank, keyring, equipment, ammo и currencies.
+- Stack/split/swap/equip/use/destroy with pending/server-confirmed states.
+- Loot windows, group rolls, master loot, disenchant и loot release.
+- Item fields, random properties, enchants, gems, durability, sets и cooldowns.
+- Vendor/buyback/repair, trade, mail, auction и guild bank.
+- Money formatting/display separated from authoritative transaction.
+
+## GMP-8. Quests and progression
+
+- Quest availability, accept, abandon, track, objectives, complete и reward choice.
+- Kill, item, gameobject, explore, spell, escort, timed, reputation objectives.
+- Chains, prerequisites, exclusive groups, repeatable/daily/weekly и conditions.
+- XP/rested/level, reputation, honor, achievements.
+- Skills, talents, glyphs, professions, recipes и trainers.
+- Quest state drives view models; authoring graph compiles to server-supported representation.
+
+## GMP-9. World activities
+
+- Area/subzone/exploration state и rest areas.
+- Taxi discovery/routes/flight, transports, elevators и boats.
+- Fishing, gathering, tracking, world events и scripted gameobjects.
+- Weather/time events feed render/audio but are owned by world state.
+- Minimap/world map POI and quest markers are projections, not quest logic.
+
+## GMP-10. Social
+
+- Chat types, channels, whispers, system messages и links.
+- Friends, ignore, who, AFK/DND.
+- Party/raid invites, leader, roles, loot rules, ready check, raid targets.
+- Guild roster, ranks, notes, MOTD, event/calendar.
+- Presence/reconnect updates and privacy/error handling.
+
+## GMP-11. Instances, PvP and vehicles
+
+- Difficulty, instance binds, lockouts, encounters, reset и transfer aborted.
+- LFG queue/proposal/roles/teleport/vote kick/rewards.
+- Duel, PvP flags, battleground queue/status/score/resurrection и arena teams.
+- Outdoor PvP objectives.
+- Vehicle seats, enter/exit/switch, possession action bar и transport-relative movement.
+
+## GMP-12. Cinematics and scripted presentation
+
+- Cinematic/movie start/stop, camera control и skippability.
+- Server-driven scripted sequences reflected as safe presentation commands.
+- Loading screens and map transitions preserve session state.
+- Gameplay input contexts prevent actions during restricted states.
+
+## Testing order
+
+Для каждой системы: reducer unit tests → packet/domain contract → offline scenario → live core integration → original-client comparison → latency/reconnect scenario.
+
+## Gate
+
+Gameplay state воспроизводим replay-ом; UI/render не владеют authoritative values; все intents имеют pending/confirmed/rejected lifecycle; core gameplay loop проходит end-to-end без оригинального клиента.
@@ -0,0 +1,97 @@
+# UIA — UI, Lua, Addons and Audio
+
+## Цель
+
+Воспроизвести UI/addon semantics клиента 3.3.5a, сохранив возможность modern UI overlays и полноценную audio presentation.
+
+## UIA-1. UI architecture
+
+- Screen flow отделён от in-world HUD.
+- UI читает immutable view models и отправляет intents.
+- Godot Control tree является presentation backend, а не gameplay model.
+- Input contexts: login, character, world, chat, modal, targeting, vehicle, cinematic.
+- Scale, safe area, resolution, font и localization учитываются на уровне layout system.
+
+## UIA-2. Frontend screens
+
+- Data/license check, login, realm list и connection errors.
+- Character selection/create/delete/rename.
+- Race/class/customization previews тем же character renderer.
+- Loading screens по map/instance, progress и cancellation policy.
+- Disconnect/reconnect dialogs и account/server notices.
+
+## UIA-3. FrameXML
+
+- TOC parser: metadata, dependencies, optional deps, SavedVariables и load order.
+- XML includes, templates, `virtual`, inheritance и named/anonymous objects.
+- Frames, Regions, Textures, FontStrings, Layers и Scripts.
+- Anchors, dimensions, strata, frame level, draw layers, clipping и scale.
+- Widget types: Button, CheckButton, EditBox, Slider, StatusBar, ScrollFrame, MessageFrame, Tooltip, Cooldown, Model и Minimap.
+- Handler scripts: OnLoad, OnEvent, OnUpdate, mouse/keyboard/drag/show/hide/value events.
+
+## UIA-4. Lua runtime
+
+- Внутренний `LuaRuntime` позволяет сравнить/заменить PUC-Rio 5.1.1 и `rilua`.
+- Restricted libraries, byte strings, number semantics, globals, `bit` и error formatting.
+- VM lifetime: one UI environment per client session/profile with controlled reset.
+- Incremental GC имеет frame budget и metrics.
+- Native functions возвращают stable Lua values, а не Godot/Rust/C++ objects напрямую.
+- VM backend выбирается ADR после official + WoW-specific corpus.
+
+## UIA-5. WoW API and event system
+
+- API inventory строится из 3.3.5a FrameXML/Lua usage и независимых references.
+- Реализация группируется: unit, spell, aura, item, quest, group, chat, map, CVar, bindings, frames.
+- Event dispatcher имеет deterministic ordering, argument contracts и registration lifecycle.
+- `OnUpdate` throttling не меняет original semantics в Blizzlike335.
+- API, требующий server state, читает gameplay read model или создаёт intent; raw packets недоступны.
+- Missing API выдаёт диагностируемую ошибку/coverage report, а не silent nil where incompatible.
+
+## UIA-6. Security, taint and addons
+
+- Secure/insecure execution origins.
+- Protected functions/actions, secure templates и combat lockdown.
+- Taint propagation through variables/tables/functions в пределах подтверждённой 3.3.5a модели.
+- Addon memory/CPU/error isolation и configurable script limits без скрытого изменения default behavior.
+- SavedVariables account/character scopes, serialization, corruption recovery и atomic writes.
+- Addon compatibility tiers: loads, renders, functional, secure-combat verified.
+- Headless addon runner и UI inspector входят в AuthoringStudio/Test Center.
+
+## UIA-7. Default UI coverage
+
+- Unit/player/target/focus/party/raid frames.
+- Action bars, stance/pet/vehicle bars, cooldowns и keybindings.
+- Buffs/debuffs, cast bars, combat text и errors.
+- Bags, character, spellbook, talents, glyphs, skills, professions.
+- Quest log/tracker/gossip, map/minimap/taxi.
+- Chat, social, guild, calendar, LFG, PvP score.
+- Vendor, trainer, bank, mail, auction, trade, loot и roll.
+- Game menu, settings, macros, addons и help.
+
+## UIA-8. Audio
+
+- Typed DBC wrappers for SoundEntries, ZoneMusic, IntroMusic, Ambience and related tables.
+- Decoder/streaming/cache for MP3/WAV with category budgets.
+- Music day/night/zone transitions and crossfade.
+- Ambient loops, random emitters, indoor/outdoor и weather.
+- Positional world sounds, footsteps, water, spells, combat, NPC voice и UI feedback.
+- Audio events come from presentation descriptors; UI/gameplay do not manipulate players directly.
+- Device change, focus/mute policy, category volumes и missing sound diagnostics.
+
+## UIA-9. Localization and accessibility
+
+- Locale-aware fonts, fallback, text encoding и layout expansion.
+- Keybindings fully remappable; mouse sensitivity/inversion and optional gamepad.
+- UI scale, contrast/color-blind profiles, subtitle/text alternatives where possible.
+- Critical state does not rely only on color/audio.
+- Enhanced accessibility remains compatible with server and can coexist with Blizzlike visuals.
+
+## References
+
+- Original 3.3.5a FrameXML/Lua extracted from legally owned data is primary behavior corpus.
+- `rilua`/PUC-Rio are VM candidates/oracles, not complete WoW UI.
+- WowBench/Wowser/WowUnreal/WoWee provide API/event/loader test ideas.
+
+## Gate
+
+Default UI boots deterministically; selected real addons pass declared tiers; secure actions fail correctly during combat; Lua GC/OnUpdate remain within budgets; UI is replaceable without changing gameplay/network.
@@ -0,0 +1,109 @@
+# EDT — Godot Editor and Content Authoring
+
+## Цель
+
+Превратить Godot Editor в единую среду расширения мира, gameplay, UI, audio и graphics с безопасным build/deploy/playtest workflow.
+
+## EDT-1. Plugin platform
+
+- `addons/openwc_editor` регистрирует workspace, docks, inspector/import/gizmo/debugger plugins.
+- `_enter_tree/_exit_tree` симметричны: все controls/plugins/signals/jobs снимаются без leaks.
+- UI вызывает authoring application services; не пишет SQL/files/scene tree напрямую.
+- Editor selection отделена от runtime preview nodes.
+- Shared services получают context через dependency injection, не global editor singleton.
+
+## EDT-2. Workspace and UX
+
+- World viewport, Content Browser, Outliner, Inspector, Validation, History, Build, Database, Test Center.
+- Search/filter/favorites/recent items и stable links между сущностями.
+- Multi-selection и bulk edits показывают scope/diff.
+- Diagnostics имеют severity/code/location/fix; double-click открывает field/node/world position.
+- Layout/workspace preferences сохраняются отдельно от Content Project.
+
+## EDT-3. Commands, undo and recovery
+
+- Любая mutation — command с execute/undo/description/affected IDs.
+- Terrain strokes агрегируются в bounded deltas; большие операции используют snapshots/chunks.
+- Autosave recovery journal атомарный и имеет schema version.
+- External changes обнаруживаются через hashes; merge/overwrite требует решения пользователя.
+- Quick Fix всегда previewable и undoable.
+
+## EDT-4. Import and asset browser
+
+- MPQ/archive browser, locale/patch source provenance и extraction jobs.
+- Preview BLP, DBC rows, M2 animations/materials, WMO groups/portals, ADT layers и audio.
+- Godot import plugins применяются только к authoring source formats, где lifecycle `.import` полезен.
+- Raw extracted corpus не должен вызывать неконтролируемый массовый Godot reimport.
+- Batch conversion использует staging, cancellation, cache hash и report.
+
+## EDT-5. World editing
+
+- Map/tile/chunk navigation и coordinate overlays.
+- Terrain sculpt/smooth/flatten/noise/stamps/holes.
+- Texture layers, alpha painting, shading и liquids.
+- M2/WMO placement, snapping, transforms, doodad sets и unique ID allocation.
+- Creature/gameobject spawns, groups, formations, patrol/escort paths.
+- Areas, triggers, graveyards, teleports, taxi/transport points, sound/weather volumes.
+- Collision/navmesh/streaming/render-cost visualization.
+
+## EDT-6. Data editors
+
+- Creature/gameobject templates, models, equipment, movement and text.
+- Item/loot/vendor/trainer/profession editors.
+- Quest form + dependency/progression graph + localization.
+- Gossip/conditions/SmartAI graph with raw representation inspector.
+- Spawn/pool/game event/phase editor.
+- Dungeon package, encounter state graph, doors/triggers/lockouts/loot.
+- UI/addon manifest, CVar/keybinding и audio zone configuration.
+
+## EDT-7. Navigation
+
+- `recast-rs` optional offline backend behind navigation build interface.
+- Bake profiles: agent size/climb/slope/cell/region/tile parameters.
+- Walkability, disconnected islands, path cost, off-mesh links и dynamic door states.
+- Quest giver/objective/turn-in reachability; patrol/escort validation.
+- OpenWC cache отделён от server mmap until compatibility proven.
+
+## EDT-8. Graphics extension tools
+
+- Material/shader profile editor с Blizzlike/Enhanced comparison.
+- Texture replacement/upscale overlays и mip/alpha/color-space validation.
+- Water/sky/weather/light preview with fixed time and reference capture.
+- Character/equipment/animation/attachment preview.
+- Spell visual/particle/ribbon authoring where formats permit.
+- Quality preset cost preview и automatic render checkpoint generation.
+
+## EDT-9. Content Project
+
+- Git-friendly files, schema version, symbolic IDs, dependencies и capability requirements.
+- Original data referenced, never copied silently.
+- Overlay priority/conflict report и semantic merges.
+- Deterministic numeric ID allocation per server profile.
+- Localization bundles, scripts, client assets, tests и package manifests.
+- Schema migrations with backup, fixture and loss policy.
+
+## EDT-10. Build, deploy and playtest
+
+```text
+Validate → Compile → Bake → Diff → Package → Dry-run
+→ Apply dev DB/module/assets → Start/reload core → Launch client at context
+→ Collect logs/results → Roll back disposable environment
+```
+
+- Jobs cancellable, progress-aware and identical to headless CI services.
+- Production target physically/logically separated and disabled by default.
+- Server reload used only for tables known to support it; otherwise restart.
+- Playtest bundle records content/core/client revisions and profile.
+- One-click convenience never hides SQL/module/client artifact diff.
+
+## EDT-11. Extensibility
+
+- `ContentTypeDescriptor`: schema, icon, inspector, validator, compiler, presenter.
+- `EditorTool`: selection contract, command factory, gizmo/overlay.
+- `BuildStep`: inputs/outputs/cache key/cancellation/diagnostics.
+- Plugin declares API version, dependencies, permissions and migrations.
+- User plugins cannot mutate production DB or original assets outside approved services.
+
+## Best-practice gate
+
+Plugin reload clean; undo/save/reload deterministic; long jobs do not block Editor; preview nodes disposable; every deployment reproducible headless; common scenarios require no manual SQL.
@@ -0,0 +1,84 @@
+# SRV — TrinityCore and AzerothCore Integration
+
+## Цель
+
+Поддержать server emulators как versioned backends: protocol-compatible runtime, безопасное редактирование данных и расширение mechanics через modules/scripts.
+
+## SRV-1. Environment model
+
+- `ServerEnvironment`: family, core commit, DB revision, modules, config profile, endpoints и data artifact versions.
+- Отдельные disposable, local-dev, shared-test, staging и production classes.
+- Credentials/secrets вне Content Project.
+- Capability discovery проверяет schema fingerprint и optional modules/tables/hooks.
+- Unknown environment всегда read-only.
+
+## SRV-2. Database snapshots
+
+- Read-only import world schema subsets с provenance/checksum.
+- Auth/characters DB открываются только для нужных test/admin сценариев и никогда не становятся content source.
+- Snapshot filters reproducible; personal/account data excluded.
+- Canonical entities preserve supported fields and explicitly record unsupported/raw extras.
+- Incremental snapshot возможен, но full consistency snapshot остаётся verification path.
+
+## SRV-3. Canonical mappings
+
+- Creature/gameobject templates, models, spawns, addons, formations, movement, texts.
+- Quests, relations, objectives, POI, conditions, gossip.
+- Loot/reference loot, vendors, trainers, items, reputation.
+- SmartAI, script names, waypoint/script tables.
+- Instances, encounters, LFG, graveyards, teleports, game events, weather, transports.
+- Каждая mapping имеет per-core capability table и round-trip tests.
+
+## SRV-4. Change sets and SQL
+
+- Immutable change set: target fingerprint, preconditions, ordered operations, checksum.
+- SQL generation соответствует conventions целевого core/profile.
+- Custom SQL хранится в version control и compatible custom/module directory, не только применяется напрямую.
+- Dry-run на disposable DB, targeted post-apply queries, core startup smoke.
+- Idempotent migration или безопасное precondition failure.
+- Rollback где возможен; destructive/irreversible operations требуют backup и явного подтверждения.
+
+## SRV-5. Scripts and modules
+
+- DB/SmartAI для выразимых data-driven mechanics.
+- C++ module/script skeleton для mechanics, требующих server hooks.
+- AzerothCore modules namespaced config/SQL/hooks; core patch — только если hook принципиально отсутствует.
+- TrinityCore adapter следует его текущим script/customization conventions отдельно.
+- Build artifact включает source, config.dist, SQL, tests и compatibility manifest.
+- Client extension capability договаривается явно; hidden custom opcode запрещён.
+
+## SRV-6. Server data artifacts
+
+- DBC/maps/vmaps/mmaps versions связываются с ContentBundleManifest.
+- Custom map требует согласованного client terrain, server maps/collision/pathfinding и DB Map/Area data.
+- OpenWC navmesh не объявляется mmap до binary/query/live behavior compatibility.
+- Asset/map IDs распределяются стабильно и проверяются на collision.
+- Client/server package mismatch блокирует playtest с actionable diagnostic.
+
+## SRV-7. Protocol compatibility
+
+- Baseline 3.3.5a build 12340 остаётся общим.
+- Core-specific quirks описываются named capabilities и fixtures.
+- Custom extensions используют versioned handshake/profile и fallback/rejection.
+- Server authority одинаково соблюдается для обеих families.
+- Compatibility matrix закрепляет tested commits, а не расплывчатое «поддерживает AzerothCore».
+
+## SRV-8. Test environments
+
+- Docker/managed local environment для repeatable DB/core setup, где поддерживается.
+- Seed accounts/characters synthetic и не содержат реальные credentials.
+- Reset DB через assembler/base + project migrations.
+- Logs world/auth/database/client собираются с correlation metadata.
+- DB-only change test, module build test, startup smoke, scripted client scenario и cleanup.
+
+## SRV-9. Existing tools
+
+- Keira3 — reference для field semantics, SQL generation и AzerothCore DB UX.
+- AzerothCore wiki/schema/module template — primary backend documentation.
+- TrinityCore source/schema/tools — primary для Trinity profile.
+- Noggit/WoW modding tools — client-world authoring reference, но не server schema oracle.
+- OpenWC Editor объединяет workflow, но сохраняет raw SQL preview и ссылки на upstream docs.
+
+## Gate
+
+Одна canonical сущность проходит import → edit → diff → dry-run → apply → reimport на каждом supported profile без silent loss; module/content packages воспроизводимы; production write disabled by default; test environment очищается.
@@ -0,0 +1,113 @@
+# QAR — Fidelity, Quality, CI and Release
+
+## Цель
+
+Сделать точность, производительность и расширяемость проверяемыми свойствами, а не обещаниями.
+
+## QAR-1. Fidelity lab
+
+- Каталог сценариев original client 3.3.5a: setup, input, server state, expected output.
+- Paired screenshots/video/log/packet/state evidence с provenance.
+- Поведение классифицируется: `Unknown`, `Observed`, `Matched`, `Intentional deviation`, `Blocked`.
+- Independent references могут подсказать hypothesis, но не повышают статус без evidence.
+- Blizzlike bugs/exploits обрабатываются policy decision: protocol compatibility отдельно от harmful behavior.
+
+## QAR-2. Test layers
+
+- Native unit tests: parsers, crypto, compression, coordinates, math, caches.
+- GDScript/domain unit tests: reducers, validators, commands, view models.
+- Contract tests: packets, DB adapters, Lua API, content schemas, renderer facade.
+- Scene tests: lifecycle, input, UI, renderer attachment, EditorPlugin reload.
+- Integration: disposable core/DB, import/build/deploy, login/world/gameplay.
+- E2E: leveling loop, dungeon, PvP/service flows и authoring vertical slices.
+- Visual/performance and exploratory design tests complement automation.
+
+## QAR-3. Godot testing stack
+
+- Оценить GdUnit4 как candidate для Godot 4.6 GDScript/scene/CI tests.
+- Native GDExtension tests используют подходящий C++ test runner отдельно от engine-internal doctest unless Godot itself is rebuilt.
+- Headless commands возвращают non-zero и machine-readable JUnit/JSON reports.
+- Scene tests не зависят от proprietary assets: synthetic fixtures or locally resolved optional corpus.
+- Flaky retries не превращают failure в success; instability измеряется и исправляется.
+
+## QAR-4. Golden and property testing
+
+- Golden binary structures and exact-byte packet vectors.
+- Parser round-trip where format permits; malformed/truncated/fuzz corpus.
+- Coordinate transform property tests and known world points.
+- Deterministic content manifests, SQL diff and migration before/after fixtures.
+- Lua oracle corpus, navmesh reference counts/queries, material descriptor mappings.
+
+## QAR-5. Performance budgets
+
+- Startup/data check/login/world entry.
+- Streaming cold/warm traversal and teleport.
+- CPU/GPU frame p50/p95/p99/max hitch, draw calls, memory и descriptors.
+- Network decode/apply queues and reconciliation error.
+- UI `OnUpdate`, event fan-out, Lua allocations/GC.
+- Editor import/bake/validation latency and cancellation responsiveness.
+- Server deployment/playtest turnaround.
+- Budgets hardware/profile-specific and trend tracked.
+
+## QAR-6. Observability
+
+- Structured logging categories and stable diagnostic codes.
+- Correlation IDs session/job/entity/content change set.
+- Runtime metrics: queues, entities, cache hit, resource counts, RIDs, packet rate.
+- Editor metrics: jobs, diagnostics, artifact hashes, DB operations.
+- Debug overlays and Godot profiler/visual profiler capture workflow.
+- Payload, credentials, chat/personal content redacted by default.
+
+## QAR-7. CI pipeline
+
+Pull request gates:
+
+1. formatting/static analysis/document links/target marker validation;
+2. native build and unit tests;
+3. headless Godot load and GDScript tests;
+4. affected parser/protocol/content/adapter contracts;
+5. deterministic artifact check;
+6. renderer smoke if visual code changed;
+7. license/dependency audit.
+
+Nightly/weekly:
+
+- disposable TrinityCore/AzerothCore integration;
+- full packet/Lua/parser replay corpus;
+- visual checkpoints on available GPU runners;
+- long traversal, reconnect, cache migration and soak;
+- previous schema/Godot/core compatibility matrix.
+
+## QAR-8. Security and robustness
+
+- Bounds checked binary parsing and fuzzing.
+- Lua sandbox/taint/protected actions.
+- DB least privilege, read-only default, production protection.
+- Untrusted addon/content/plugin permission model.
+- Dependency license/advisory/source pin audit.
+- Atomic files, backup, recovery and rollback.
+- No proprietary assets, secrets or production dumps in repository/artifacts.
+
+## QAR-9. Documentation and decisions
+
+- Architecture/API/schema changes update docs and ADR в том же work package.
+- Каждый самостоятельный module имеет specification по `docs/DOCUMENTATION_STANDARD.md`: purpose, boundaries, public API, inputs/outputs, data flow, ownership, errors, tests и source map.
+- Data-flow diagram обязательна всегда; state/sequence/dependency diagrams обязательны по сложности/lifecycle rules стандарта.
+- Inline docs являются источником точной сигнатуры, module spec — источником концепции и фактического статуса.
+- Tooling candidates tracked in `docs/TOOLING_CATALOG.md` with status and pinned version.
+- Feature coverage links implementation, tests, fidelity evidence and known gaps.
+- Generated API docs for documented GDScript/GDExtension public surface включаются в quality gate, когда pipeline подготовлен.
+- Contributor workflow describes smallest reproducible diagnostic commands.
+
+## QAR-10. Packaging and release
+
+- Client ships without Blizzard data and guides user to select legally owned install.
+- Import/cache first-run is resumable and reports disk/time requirements.
+- Platform packages include matching GDExtension libraries and dependency notices.
+- Content package and server module releases version independently with compatibility manifest.
+- Save/settings/content schema migrations tested from supported previous versions.
+- Release channels: developer, preview, stable; fidelity gaps visible in notes.
+
+## Exit gate
+
+Release candidate passes required core/platform/profile matrix; no critical unowned diagnostic; performance regression within approved bounds; artifacts reproducible and license-clean; known fidelity deviations documented.
@@ -0,0 +1,92 @@
+param(
+    [string]$Root = (Split-Path -Parent $PSScriptRoot)
+)
+
+$ErrorActionPreference = 'Stop'
+$failures = [System.Collections.Generic.List[string]]::new()
+$warnings = [System.Collections.Generic.List[string]]::new()
+
+$targetsDir = Join-Path $Root 'targets'
+$targetIndex = Join-Path $targetsDir 'README.md'
+$targetFiles = Get-ChildItem -LiteralPath $targetsDir -File |
+    Where-Object { $_.Name -match '^\d\d-.*\.md$' } |
+    Sort-Object Name
+
+$activeTargets = [System.Collections.Generic.List[object]]::new()
+$statusPattern = '<!-- OPENWC_TARGET:(OPEN|ACTIVE|BLOCKED|DONE) -->'
+
+foreach ($file in $targetFiles) {
+    $content = Get-Content -Raw -Encoding UTF8 -LiteralPath $file.FullName
+    $matches = [regex]::Matches($content, $statusPattern)
+    if ($matches.Count -ne 1) {
+        $failures.Add("$($file.Name): expected exactly one target status marker, found $($matches.Count)")
+        continue
+    }
+    if ($matches[0].Groups[1].Value -eq 'ACTIVE') {
+        $activeTargets.Add($file)
+    }
+}
+
+if ($activeTargets.Count -ne 1) {
+    $failures.Add("Expected exactly one ACTIVE target, found $($activeTargets.Count)")
+}
+
+if (-not (Test-Path -LiteralPath $targetIndex)) {
+    $failures.Add('targets/README.md is missing')
+} else {
+    $indexContent = Get-Content -Raw -Encoding UTF8 -LiteralPath $targetIndex
+    $currentMatch = [regex]::Match($indexContent, '(?s)## Current target\s+`(M\d\d)`[^\r\n]*\[[^\]]+\]\(([^)]+)\)')
+    if (-not $currentMatch.Success) {
+        $failures.Add('Could not parse Current target from targets/README.md')
+    } elseif ($activeTargets.Count -eq 1) {
+        $expectedId = $currentMatch.Groups[1].Value
+        $expectedFile = $currentMatch.Groups[2].Value
+        $activeFile = $activeTargets[0].Name
+        $activeId = 'M' + $activeFile.Substring(0, 2)
+        if ($expectedId -ne $activeId -or $expectedFile -ne $activeFile) {
+            $failures.Add("Current target points to $expectedId/$expectedFile but ACTIVE is $activeId/$activeFile")
+        }
+    }
+}
+
+$claimsDir = Join-Path $Root 'coordination\claims'
+$claimIds = @{}
+$claimPattern = '<!-- OPENWC_CLAIM:([A-Z0-9-]+):([a-z0-9-]+):(\d{4}-\d{2}-\d{2}) -->'
+
+if (Test-Path -LiteralPath $claimsDir) {
+    $claimFiles = Get-ChildItem -LiteralPath $claimsDir -Filter '*.md' -File |
+        Where-Object { $_.Name -ne 'README.md' }
+    foreach ($file in $claimFiles) {
+        $content = Get-Content -Raw -Encoding UTF8 -LiteralPath $file.FullName
+        $matches = [regex]::Matches($content, $claimPattern)
+        if ($matches.Count -ne 1) {
+            $failures.Add("coordination/claims/$($file.Name): expected exactly one valid OPENWC_CLAIM marker")
+            continue
+        }
+        $claimId = $matches[0].Groups[1].Value
+        if ($claimIds.ContainsKey($claimId)) {
+            $failures.Add("Duplicate claim ID $claimId in $($claimIds[$claimId]) and $($file.Name)")
+        } else {
+            $claimIds[$claimId] = $file.Name
+        }
+        $expiryText = $matches[0].Groups[3].Value
+        $expiry = [datetime]::ParseExact($expiryText, 'yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture)
+        if ($expiry.Date -lt (Get-Date).ToUniversalTime().Date) {
+            $warnings.Add("Claim $claimId expired on $expiryText")
+        }
+    }
+}
+
+foreach ($warning in $warnings) {
+    Write-Warning $warning
+}
+
+if ($failures.Count -gt 0) {
+    foreach ($failure in $failures) {
+        Write-Error $failure
+    }
+    exit 1
+}
+
+Write-Output "Coordination check passed: targets=$($targetFiles.Count) active=$($activeTargets.Count) fallback_claims=$($claimIds.Count) warnings=$($warnings.Count)"
+exit 0
@@ -0,0 +1,101 @@
+param(
+    [string]$Root = (Split-Path -Parent $PSScriptRoot)
+)
+
+$ErrorActionPreference = 'Stop'
+$failures = [System.Collections.Generic.List[string]]::new()
+
+$requiredFiles = @(
+    'AGENTS.md',
+    'docs\README.md',
+    'docs\DOCUMENTATION_STANDARD.md',
+    'docs\modules\README.md',
+    'docs\modules\TEMPLATE.md',
+    'targets\DEVELOPMENT_ROADMAP.md'
+)
+
+foreach ($relative in $requiredFiles) {
+    if (-not (Test-Path -LiteralPath (Join-Path $Root $relative))) {
+        $failures.Add("Missing required documentation file: $relative")
+    }
+}
+
+$agentGuide = Join-Path $Root 'AGENTS.md'
+if (Test-Path -LiteralPath $agentGuide) {
+    $agentContent = Get-Content -Raw -Encoding UTF8 -LiteralPath $agentGuide
+    if ($agentContent -notmatch 'DOCUMENTATION_STANDARD\.md') {
+        $failures.Add('AGENTS.md does not reference docs/DOCUMENTATION_STANDARD.md')
+    }
+}
+
+$requiredHeadings = @(
+    '## Metadata',
+    '## Purpose',
+    '## Non-goals',
+    '## Context and boundaries',
+    '## Public API',
+    '## Inputs and outputs',
+    '## Data flow',
+    '## Ownership, threading and resources',
+    '## Errors, cancellation and recovery',
+    '## Verification',
+    '## Known gaps and risks',
+    '## Source map'
+)
+
+$modulesDir = Join-Path $Root 'docs\modules'
+$moduleCount = 0
+if (Test-Path -LiteralPath $modulesDir) {
+    $moduleFiles = Get-ChildItem -LiteralPath $modulesDir -Filter '*.md' -File |
+        Where-Object { $_.Name -notin @('README.md', 'TEMPLATE.md') }
+    foreach ($file in $moduleFiles) {
+        ++$moduleCount
+        $content = Get-Content -Raw -Encoding UTF8 -LiteralPath $file.FullName
+        foreach ($heading in $requiredHeadings) {
+            if (-not $content.Contains($heading)) {
+                $failures.Add("docs/modules/$($file.Name): missing heading '$heading'")
+            }
+        }
+        if ($content -notmatch '(?s)```mermaid\s+flowchart') {
+            $failures.Add("docs/modules/$($file.Name): missing Mermaid data-flow diagram")
+        }
+        if ($content -notmatch '\| Status \|') {
+            $failures.Add("docs/modules/$($file.Name): missing Status metadata")
+        }
+        if ($content -notmatch '\| Last verified \|') {
+            $failures.Add("docs/modules/$($file.Name): missing Last verified metadata")
+        }
+    }
+}
+
+$documentationRoots = @('docs', 'targets', 'coordination')
+foreach ($relativeRoot in $documentationRoots) {
+    $path = Join-Path $Root $relativeRoot
+    if (-not (Test-Path -LiteralPath $path)) {
+        continue
+    }
+    foreach ($file in Get-ChildItem -LiteralPath $path -Recurse -Filter '*.md' -File) {
+        $content = Get-Content -Raw -Encoding UTF8 -LiteralPath $file.FullName
+        foreach ($match in [regex]::Matches($content, '\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)')) {
+            $target = $match.Groups[1].Value
+            if ($target -match '^(https?:|mailto:)') {
+                continue
+            }
+            $resolved = Join-Path $file.DirectoryName $target
+            if (-not (Test-Path -LiteralPath $resolved)) {
+                $relativeFile = Resolve-Path -LiteralPath $file.FullName -Relative
+                $failures.Add("$relativeFile`: broken relative link '$target'")
+            }
+        }
+    }
+}
+
+if ($failures.Count -gt 0) {
+    foreach ($failure in $failures) {
+        Write-Error $failure
+    }
+    exit 1
+}
+
+Write-Output "Documentation check passed: module_specs=$moduleCount required_files=$($requiredFiles.Count)"
+exit 0