docs: freeze particle project governance v1

docs/00_项目总则/README.md

@@ -0,0 +1,32 @@
+# MapLibreParticleLab 项目总则目录
+
+## 定位
+`docs/00_项目总则/` 是本项目长期规则层（Source of Truth）。保存经用户与 GPT 确认的长期设计决策、开发环境、系统构建规范、Codex 协作规则、Step/执行报告规范，以及当前正式基线与路线。普通 Step 默认禁止修改本目录。
+
+## 当前有效文件
+1. `粒子系统项目规则与设计决策_v1.md`
+2. `开发环境与系统构建规范_v1.md`
+3. `Step指令书与执行报告规范_v1.md`
+4. `当前基线与开发路线_v1.md`
+
+## 阅读顺序
+`AGENTS.md` → 本目录 README → 四份当前有效总则 → 当前 Step 指令书 → 上一 Step 执行报告 → 其他阶段文档。
+
+## 维护职责
+- GPT：参考“粒子系统”GPT 项目讨论，提出总则更新。
+- 用户：确认或否决长期规则。
+- Codex：普通 Step 只读；只有明确授权的总则更新任务才可修改。
+
+## 冲突处理
+若 Step 与总则冲突，Codex 停止冲突部分，在执行报告记录，不得自行改总则。
+
+## 版本规则
+同主题仅递增 `_v1`、`_v2`、`_v3`；不使用“最终版/最新版/final/new/修正版”。
+
+## 大阶段目录
+建议：`10_架构调查/`、`20_测试App/`、`30_粒子核心/`、`40_天气数据链/`、`50_渲染与视觉/`、`60_性能与后端/`、`70_NavSea集成/`、`80_iOS与Metal/`、`90_升级与维护/`。进入新大阶段前，GPT 先告诉用户目录名、目的、预计 Step 范围。
+
+## 换窗口/换会话恢复
+1. 读本目录全部当前有效总则；2. 读当前基线；3. 读上一 Step 执行报告；4. 检查 Git branch/commit/working tree/submodule；5. 再继续下一 Step。
+
+分层：GPT 项目讨论=设计过程；项目总则=冻结规则；Step 指令书=工作合同；执行报告=实际事实；Git=最终代码事实。

docs/00_项目总则/Step指令书与执行报告规范_v1.md

@@ -0,0 +1,55 @@
+# Step 指令书与执行报告规范 v1
+
+## 1. 命名
+指令书：`step-xxxx-目的内容.md`。
+报告：`step-xxxx-目的内容-执行报告.md`。
+统一使用“执行报告”。
+
+## 2. 同目录
+指令书与报告放同一个大阶段目的目录。
+
+## 3. 指令书固定章节
+1. Step 编号和目的
+2. 当前已冻结基线
+3. 本 Step 目标
+4. 非目标/禁止事项
+5. 允许修改范围
+6. 禁止修改范围
+7. 实施要求
+8. 构建要求
+9. 测试要求
+10. 验收标准
+11. Git 要求
+12. 必做输出
+13. 执行报告完整文件名
+14. 执行报告固定内容
+15. 阻塞与停止条件
+
+## 4. Codex 前置必读
+AGENTS.md → 本目录 README → 三份长期总则 → 当前基线与路线 → 本阶段已有文档 → 上一 Step 执行报告。
+
+## 5. Jest 特殊规则
+GPT 生成任何正式 Step 指令书之前必须先询问用户是否加入 Jest。未经明确确认不得写入。若加入，先确认测试力度、允许修复范围、是否可改生产代码、最大修复轮数、停止条件。
+
+## 6. 执行报告固定结构
+1. 执行结论：PASS/PARTIAL/BLOCKED/FAIL
+2. Git 基线：branch/start commit/end commit/working tree/submodule
+3. 实际修改文件
+4. 新增文件
+5. 实际实现内容
+6. 与指令书差异（无也写“无”）
+7. 构建记录：command/renderer/build type/JOBS/result/关键日志/耗时
+8. 测试记录
+9. 生成产物：文件名/路径/大小/SHA256/Renderer/Build Type/ABI
+10. 已知问题
+11. 未完成事项
+12. 下一 Step 建议（只建议，不自行创建）
+
+## 7. 报告必须反映事实
+禁止未执行测试写 PASS、计划写成已完成、隐藏失败、用“应该正常”替代结果、把 Win11 人工验证写成 Linux Codex 已完成。若只完成 Linux APK build，必须明确“Win11 Android Simulator 人工验证待用户执行”。
+
+## 8. 总则修改
+普通 Step 禁止修改 `docs/00_项目总则/`。如认为需调整，只在报告提出建议。
+
+## 9. GPT 写新 Step 的依据
+必须参考：“粒子系统”GPT 项目既有设计、项目总则、当前基线、上一 Step 报告、当前 Git 事实、用户最新确认。

docs/00_项目总则/开发环境与系统构建规范_v1.md

@@ -0,0 +1,57 @@
+# 开发环境与系统构建规范 v1
+
+## 1. 正式基线
+源码：`/mnt/sda1/MapLibreParticleLab`；稳定分支：`particle/main`。Linux：Ubuntu 24.04 LTS、x86_64、4 CPU threads、约 8GB RAM、默认 `JOBS=3`。Win11：NavSea、Android 模拟器、Particle Test APK 运行、NavSea Android 手工编译。
+
+## 2. Step 开始前
+记录：`git branch --show-current`、`git rev-parse HEAD`、`git status --short`、`git submodule status`。
+
+## 3. Git 远端
+origin=`ssh://git@192.168.200.230:2222/tei/MapLibreParticleLab.git`；upstream=`https://github.com/maplibre/maplibre-native.git`，只读，push 禁用；保留 `git rerere`。
+
+## 4. Step branch
+建议 `step/0001-...`。流程：particle/main → Step branch → Codex → build/test/report → GPT/用户审查 → PASS → merge particle/main → push → freeze。
+
+## 5. 构建磁盘
+大型 build 必须使用 Linux 本地 SSD；禁止 NAS/SMB/NFS 作为 build root。NAS 只做备份、APK/AAR 中转、归档。
+
+## 6. 环境入口
+构建前 `source /root/.maplibre-particle-env`。Codex 不得自行升级 Node/Java/SDK/NDK/Gradle/AGP/CMake/MapLibre baseline，除非 Step 明确要求。
+
+## 7. 已验证环境
+Linux Native OpenGL PASS；mbgl-render PASS；mbgl-render-test-runner PASS；Android OpenGL Debug AAR PASS；Android Vulkan Debug AAR PASS；Android OpenGL Release AAR PASS。SDK=`/root/Android/Sdk`；NDK=`28.2.13676358`。
+
+## 8. Development Build
+默认 Debug + OpenGL + 增量 + Particle Test App。小改不强制 clean/Release/Vulkan/NavSea/全量回归。
+
+## 9. Gate Build
+关键 Step 才做 Release（按需）、明确 Git commit、完整 build、APK/AAR、Renderer、ABI、大小、SHA256、执行报告、必要时 Vulkan/NavSea。
+
+## 10. OpenGL/Vulkan
+OpenGL 是主开发 backend；Vulkan 在专门 Step 做正式回归。核心必须遵循 MapLibre gfx 抽象。
+
+## 11. Test App 日常链
+MapLibre Native → Particle Test APK → 复制到 Win11 → Android Simulator。NavSea 不参与日常粒子调试。
+
+## 12. 产物
+建议统一 `dist/android/`。示例：`particle-test-step-0005-opengl-debug.apk`、`particle-test-step-0009-opengl-release.apk`、`particle-test-step-0014-vulkan-debug.apk`、`maplibre-particle-step-0016-opengl-release.aar`。Gate 产物记录 SHA256。
+
+## 13. Linux/Win11 边界
+Linux Codex 默认责任到 APK/AAR build PASS、产物存在、大小、SHA256、执行报告。用户负责复制到 Win11、安装模拟器、人工视觉/交互验证。
+
+## 14. NavSea Android
+继续由用户在 Win11 手工编译；Linux Codex 不代替用户编译 NavSea。
+
+## 15. Gate A/B/C
+Gate A：maplibre-react-native 11.3.6 + 官方 Native 13.2.0，PASS。
+Gate B：11.3.6 + 官方 Native 13.4.1，PASS。
+Gate C：11.3.6 + Linux 自编译 Native 13.4.1 OpenGL Release，PASS。
+
+## 16. 当前 Release AAR
+`MapLibreAndroid-opengl-release.aar`，约 156MB，SHA256=`5c67d2751fafe211a0df4b82deded09ab1c07cf6ca0f4a12a880283287f85e5c`，ABI：arm64-v8a/armeabi-v7a/x86/x86_64。
+
+## 17. 构建失败
+只修当前 Step 允许范围；若必须升级工具链/MapLibre、大改 gfx、修改 NavSea/冻结接口、删除测试或降低门槛，STOP 并报告 BLOCKED。
+
+## 18. 禁止项
+普通 Step 禁止自行升级 MapLibre/AGP/Gradle/NDK/Java/Node，禁止修改 NavSea/冻结接口、删除测试、降低门槛、用 CPU 粒子冒充正式 GPU 实现、修改 `docs/00_项目总则/`。

docs/00_项目总则/当前基线与开发路线_v1.md

@@ -0,0 +1,39 @@
+# 当前基线与开发路线 v1
+
+## 1. 冻结日期
+2026-08-29
+
+## 2. Git
+正式分支：`particle/main`。STEP-000 冻结提交：`ea5b8f9d7fc53204a6d7fa088e9cf89be765b5ac`，说明 `chore: freeze MapLibreParticleLab step 0 baseline`。origin=`ssh://git@192.168.200.230:2222/tei/MapLibreParticleLab.git`。upstream=`https://github.com/maplibre/maplibre-native.git`。
+
+## 3. MapLibre Native
+正式粒子开发 baseline：Android 13.4.1。OpenGL 主开发；Vulkan/Metal 后续。
+
+## 4. Linux 构建状态
+Linux Native OpenGL PASS；mbgl-render PASS；mbgl-render-test-runner PASS；Android OpenGL Debug AAR PASS；Android Vulkan Debug AAR PASS；Android OpenGL Release AAR PASS。SDK=`/root/Android/Sdk`；NDK=`28.2.13676358`；JOBS=3。
+
+## 5. Release AAR
+`MapLibreAndroid-opengl-release.aar`，约 156MB，SHA256=`5c67d2751fafe211a0df4b82deded09ab1c07cf6ca0f4a12a880283287f85e5c`，ABI：arm64-v8a/armeabi-v7a/x86/x86_64。
+
+## 6. NavSea
+Win11；React Native 0.85.2；New Architecture=true；`@maplibre/maplibre-react-native@11.3.6`。
+
+## 7. Gate
+Gate A：11.3.6 + 官方 Native 13.2.0，PASS。
+Gate B：11.3.6 + 官方 Native 13.4.1，PASS。
+Gate C：11.3.6 + Linux 自编译 Native 13.4.1 OpenGL Release，PASS。
+
+## 8. 固定分工
+Linux：MapLibre Native/Particle/Test App/APK/AAR/Fixture/Native Debug/Git。Win11：Android Simulator/Particle Test APK/NavSea/NavSea Android 编译/产品 Gate。NavSea 不作为日常 Particle 宿主。
+
+## 9. 下一大阶段
+建议 `10_架构调查/`。正式建立前 GPT 先向用户说明该阶段目的与预计 Step 范围。
+
+## 10. 下一 Step
+`step-0001-MapLibre粒子接入点调查.md`。只读调查 Style Layer、Source/Tile/Bucket、RenderLayer/RenderPass、gfx、Shader、Texture/RenderTarget、OpenGL/Vulkan/Metal、Raster/Heatmap/Hillshade/CustomLayer 等；不实现正式粒子。
+
+## 11. 近期路线
+STEP-0001 接入点调查；0002 Android Particle Test App；0003 Fixture；0004 RasterParticleLayer 骨架；0005 最小 GPU Particle；0006 Camera/Projection；0007 Particle State 冻结；0008 Velocity/RasterArray/Tile；0009 Trail；0010 生命周期与视觉；0011 WeatherColorLayer；0012 Land/Ocean Mask；0013 OpenGL 性能；0014 Vulkan；0015 Test App 第一阶段冻结；0016 NavSea Particle Gate；0017 NavSea API/Adapter；0018 Android 产品回归；0019 iOS/Metal；0020 NavSea iOS；0021 upstream/长期维护。
+
+## 12. 换窗口恢复
+读项目总则 → 当前基线 → 上一 Step 报告 → 检查 Git → 继续下一 Step。

docs/00_项目总则/粒子系统项目规则与设计决策_v1.md

@@ -0,0 +1,55 @@
+# 粒子系统项目规则与设计决策 v1
+
+## DEC-001 Linux 与 Win11 职责分离
+Linux 是 MapLibre Native / Particle Renderer 的主要开发和构建环境，正式源码 `/mnt/sda1/MapLibreParticleLab`。Linux 负责 Native、Particle、Test App、Fixture、AAR/APK、OpenGL/Vulkan、Native 调试、性能与 Git。Win11 负责 NavSea、NavSea Android 编译、Android 模拟器、Particle Test APK 运行和产品 Gate。
+
+## DEC-002 独立 Particle Test App
+必须建立长期维护的独立测试 App。它不是 Demo，而是粒子 Renderer 的开发、调试、回归和性能平台。日常粒子开发不直接使用 NavSea。Android 第一阶段优先原生 Test App。
+
+## DEC-003 NavSea 只用于关键产品 Gate
+NavSea 是最终产品，不作为日常粒子调试宿主。只在自编译等价验证、关键 Particle Gate、真实 Layer Stack、Weather/Mask、产品级回归和最终集成时使用。
+
+## DEC-004 OpenGL 为 Android 主开发 Backend
+初期主开发 OpenGL；架构必须服从 MapLibre `gfx` 抽象，不能锁死 OpenGL。
+
+## DEC-005 Vulkan / Metal 不是后补重写
+Particle State、Velocity、Tile、生命周期、Style/RenderLayer、Coverage、Color Ramp、Mask 尽量共享；后端差异主要放在 Shader、Texture、RenderTarget、RenderPass、gfx backend。iOS/Metal 以后单独设计测试流程。
+
+## DEC-006 WeatherColorLayer 与 RasterParticleLayer 分离
+定量天气色场和粒子流动分为 `WeatherColorLayer` 与 `RasterParticleLayer`。
+
+## DEC-007 天气色场不靠低透明度看底图
+天气定量颜色保持准确；岸线、等深线、航标、航道、文字和导航对象绘制在天气层上方。
+
+## DEC-008 Coverage
+Wind=`GLOBAL`；Wave/Tide/Current/Sea Temperature 等=`OCEAN_ONLY`。
+
+## DEC-009 统一 Land/Ocean Mask
+所有 OCEAN_ONLY 字段共用统一 Mask；海岸线语义尽量与 NavSea/MapLibre 海图一致，不依赖天气模型 nodata。
+
+## DEC-010 正式目标是 GPU Particle Engine
+核心至少包括 Velocity Texture、Particle State Texture A/B、Ping-Pong、Update Pass、Draw Pass、Trail Render Target、Color Ramp。CPU 每粒子循环不能作为正式主实现。
+
+## DEC-011 Camera 正确后再冻结 Particle State Model
+先验证 Pan/Zoom/Rotate/Pitch/Resize/Camera Animation，再冻结状态格式。
+
+## DEC-012 Fixture 优先
+至少：uniform-east/north/west/south、vortex-clockwise/counterclockwise、shear、divergence、convergence、coastal-mask。真实天气服务器不是早期 Renderer 调试前置条件。
+
+## DEC-013 thin-hook 原则
+目标约 95% 粒子代码放新增文件/独立模块；MapLibre 官方现有文件只做必要 Layer/Source/RenderLayer/Shader/Build/Backend 薄接入，降低 upstream merge 冲突。
+
+## DEC-014 普通 Step 禁止修改项目总则
+需要改变长期规则时，只在执行报告提出建议。
+
+## DEC-015 GPT“粒子系统”项目是设计背景来源
+GPT 写设计和指令书时要参考该项目既有讨论；正式权威规则以 Git 仓库本目录为准。
+
+## DEC-016 大阶段目录按目的建立
+使用两位数字前缀；进入新阶段前 GPT 先告知用户目录目的和预计 Step 范围。
+
+## DEC-017 Step 指令书与执行报告同目录
+`step-xxxx-目的内容.md` 与 `step-xxxx-目的内容-执行报告.md` 放同一大阶段目的目录。
+
+## DEC-018 报告由指令书预先定义
+指令书必须事先写清报告完整路径、文件名、章节、Git 信息、构建信息、APK/AAR、大小、SHA256、PASS/PARTIAL/BLOCKED/FAIL。不得执行完后临时追加未定义报告。