docs(assets): document reusable asset package contract

.trellis/spec/config/index.md

@@ -68,11 +68,14 @@ cp config/examples/template.json config/areas/my-area.json
 | `intermediates` | `true` | 旧名 `qgis` 仍被接受 |
 | `blender` | `true` | |
 | `cesium` | `true` | |
+| `compress` | `true` | 压缩 staged GLB，供随后发布使用 |
+| `package` | `true` | 将通过校验的静态模型原子发布到 `package/` |
+| `preview` | `true` | 基于已发布 package 写验证预览及 `_preview/` 动态资源 |
 
-`reimport` 和 `preview` **在这里配也没用**——`normalizeAreaConfig` 把它们
-硬编码为 `false`，只能靠 `--stages` 显式请求。`compress` 始终默认开启。
+`reimport` **在这里配也没用**——`normalizeAreaConfig` 把它硬编码为 `false`，只能靠
+`--stages` 显式请求。`compress`、`package` 和 `preview` 始终默认开启。
 
-> 恢复动作（reimport）和补丁动作（preview）不该被一份配置文件变成默认行为；压缩是标准交付链的一部分。
+> 恢复动作（reimport）不该被一份配置文件变成默认行为；压缩、发布和验证预览是标准交付链的一部分。
 
 `--stages` 会整体覆盖这里的默认值。
 
@@ -133,7 +136,8 @@ cp config/examples/template.json config/areas/my-area.json
 ### `compress`
 
 完整构建和显式 `--stages compress` 都使用此配置。默认压缩链是 texture resize + WebP
-transcode，成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML；未压缩源只保留在构建临时目录。
+transcode，成功后替换**package staging** 中的主 GLB 与 manifest；未压缩源只保留在构建临时目录。
+只有随后的 `package` 阶段才会原子发布到 `package/`。
 
 | 字段 | 默认 | 说明 |
 |---|---|---|
@@ -161,14 +165,16 @@ transcode，成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML；未
 
 ### `outputs`（逃生舱）
 
-默认全部从 `id` 推导为 `<outputRoot>/<id>/<fileStem>.<ext>`。需要定制时逐项覆盖：
+默认全部从 `id` 推导。发布给下游的静态资产固定在
+`<outputRoot>/<id>/package/`，临时静态资产在 `_pipeline/package-staging/`，预览专用动态资源在
+`<outputRoot>/<id>/_preview/`。需要定制时逐项覆盖：
 
 ```json
 {
   "outputs": {
     "areaDir": "/absolute/path/to/custom-area",
     "blend":   "/absolute/path/to/custom.blend",
-    "glb":     "/absolute/path/to/custom.glb",
+    "packageDir": "/absolute/path/to/custom-package",
     "cesiumPreview": "/absolute/path/to/custom-preview.html"
   }
 }
@@ -178,6 +184,11 @@ transcode，成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML；未
 `qgisProject`、`qgisPreview`、`blend`、`render`、`glb`、`metadata`、`cesiumPreview`、
 `vehicleRoute`、`vehicleModel`、`pipelineDir`、`stageManifestDir`。
 
+静态发布路径另有 `packageDir`、`packageStagingDir`、`packageManifest`、
+`packageStagingManifest`、`packageModelDir`、`packageStagingModelDir` 与
+`packagePrimaryGlb`；预览路径另有 `previewDir` 与 `previewDescriptor`。除非在迁移旧调用，
+不要覆盖 `glb` / `metadata`：它们是 staging 内部路径，不是下游资产入口。
+
 **优先改 `fileStem` 或 `areaDir`**——它们能一次性影响全部派生路径。逐个覆盖容易漏。
 
 ---
@@ -219,7 +230,8 @@ transcode，成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML；未
 | 布尔字段用 `\|\|` 兜底 | `false` 被翻转 |
 | 给新字段造顶层平铺别名 | 扩大历史包袱 |
 | 逐个覆盖 `outputs` 而不用 `fileStem` | 漏掉某个产物路径 |
-| 在 `stages` 里配 `reimport` / `preview` | 无效，被硬编码为 false |
+| 将 `glb` / `metadata` 当作下游入口 | 它们位于 staging；应只读取 `package/manifest.json` |
+| 在 `stages` 里配 `reimport` | 无效，被硬编码为 false |
 | 加数值字段不做范围校验 | 错配置在中途才崩，输出已被破坏 |
 
 ---