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

2026-07-10 18:15:05 +04:00
parent 01953cc25e
commit 0eef72a2c2
28 changed files with 2435 additions and 6 deletions
@@ -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)