docs+meta: codify namespace conventions and centralize world namespace bridge

Author: 129s

docs/README.md

@@ -12,6 +12,7 @@
 - 故障排查（GUI/运行时常见问题）：`docs/troubleshooting/`（GUI：`docs/troubleshooting/sandbox_gui.md`）
 
 - 文档组织与边界：`docs/handbook/DOCS_ORGANIZATION.md`
+- 代码约定（Namespace 等）：`docs/handbook/CODING_CONVENTIONS.md`
 - 内核回归闭环（Headless 优先）：`docs/handbook/CORE_REGRESSION.md`
 - 架构概览：`docs/architecture/README.md`
 - 愿景与设计原则：`docs/architecture/meta/vision.md`

docs/handbook/CODING_CONVENTIONS.md

@@ -0,0 +1,42 @@
+# 代码约定（Coding Conventions）
+
+本文档用于固化“新增代码默认遵循”的工程约定，避免风格分裂导致的维护成本与重构摩擦。
+
+## 1) 命名空间（Namespace）
+
+目标：对外/跨模块引用统一使用 `Genesis::` 根命名空间；内部实现仍允许保持 `genesis::`，并以渐进方式迁移。
+
+### 1.1 规则（新增代码必须遵守）
+- **跨模块引用优先使用 `Genesis::`**（而不是 `genesis::`）。
+- **使用 `Genesis::X` 前必须包含对应模块的 `genesis/<module>/Namespace.hpp`**（避免靠“碰巧某个头文件定义了别名”）。
+- **不要新增新的全局 alias 聚合头**（避免与已有 `Namespace.hpp` 发生冲突）。
+
+示例（推荐写法）：
+```cpp
+#include "genesis/world/Namespace.hpp"
+#include "genesis/world/WorldTypes.hpp"
+
+Genesis::World::MapId map = 1;
+```
+
+Agents（带 Components 子命名空间）：
+```cpp
+#include "genesis/agents/Namespace.hpp"
+#include "genesis/agents/Needs.hpp"
+
+Genesis::Agents::NeedType need = Genesis::Agents::NeedType::Hunger;
+```
+
+### 1.2 可用的 Namespace 过渡头
+- `include/genesis/agents/Namespace.hpp` → `Genesis::Agents`（含 `Genesis::Agents::Components`）
+- `include/genesis/base/Namespace.hpp` → `Genesis::Base`
+- `include/genesis/core/Namespace.hpp` → `Genesis::Core`
+- `include/genesis/diagnostics/Namespace.hpp` → `Genesis::Diagnostics`
+- `include/genesis/messaging/Namespace.hpp` → `Genesis::Messaging`
+- `include/genesis/simulation/Namespace.hpp` → `Genesis::Simulation`
+- `include/genesis/telemetry/Namespace.hpp` → `Genesis::Telemetry`
+- `include/genesis/world/Namespace.hpp` → `Genesis::World`
+- `include/genesis/worldgen/Namespace.hpp` → `Genesis::Worldgen`
+
+> 迁移策略与阶段计划见：`docs/architecture/proposals/meta/namespace-strategy.md`。
+

include/genesis/runtime/Runtime.hpp

@@ -19,11 +19,12 @@
 #include "genesis/runtime/RuntimeEvents.hpp"
 #include "genesis/runtime/SimulationService.hpp"
 #include "genesis/simulation/AgentApi.hpp"
-#include "genesis/simulation/Namespace.hpp"
-#include "genesis/agents/Namespace.hpp"
-#include "genesis/world/WorldDatabaseLoader.hpp"
-#include "genesis/world/WorldDatabaseSaver.hpp"
-#include "genesis/agents/Movement2D.hpp"
+#include "genesis/simulation/Namespace.hpp"
+#include "genesis/agents/Namespace.hpp"
+#include "genesis/telemetry/Namespace.hpp"
+#include "genesis/world/WorldDatabaseLoader.hpp"
+#include "genesis/world/WorldDatabaseSaver.hpp"
+#include "genesis/agents/Movement2D.hpp"
 
 namespace genesis { namespace world { class WorldDatabase; } }
 

include/genesis/runtime/SimulationSnapshot.hpp

@@ -4,11 +4,12 @@
 #include <atomic>
 #include <chrono>
 #include <cstdint>
-#include <optional>
+#include <optional>
 #include <utility>
 #include <vector>
 
 #include "genesis/runtime/RuntimeEvents.hpp"
+#include "genesis/telemetry/Namespace.hpp"
 #include "genesis/telemetry/TelemetryBuffer.hpp"
 
 namespace Genesis::Runtime {

include/genesis/runtime/SnapshotDiff.hpp

@@ -1,10 +1,11 @@
 #pragma once
 
-#include <chrono>
-#include <cstdint>
+#include <chrono>
+#include <cstdint>
 #include <optional>
 #include <vector>
 
+#include "genesis/telemetry/Namespace.hpp"
 #include "genesis/runtime/SimulationSnapshot.hpp"
 
 namespace Genesis::Runtime {

include/genesis/world/WorldDatabase.hpp

@@ -8,6 +8,7 @@
 #include <utility>
 #include <vector>
 
+#include "genesis/world/Namespace.hpp"
 #include "genesis/world/WorldTypes.hpp"
 
 namespace genesis::world {
@@ -138,7 +139,3 @@ class InMemoryWorldDatabase final : public WorldDatabase {
 };
 
 } // namespace genesis::world
-
-namespace Genesis {
-namespace World = genesis::world;
-} // namespace Genesis

include/genesis/world/WorldTypes.hpp

@@ -2,6 +2,8 @@
 
 #include <cstdint>
 
+#include "genesis/world/Namespace.hpp"
+
 namespace genesis::world {
 
 // 资源类型：保留为运行时系统共享的最小枚举。
@@ -14,7 +16,3 @@ enum class ResourceType : std::uint8_t {
 };
 
 } // namespace genesis::world
-
-namespace Genesis {
-namespace World = genesis::world;
-} // namespace Genesis