create-windy 0.3.4 → 0.3.5

package/template/docs/development/business-web-routes.md

@@ -0,0 +1,66 @@
+# project-owned 业务 Web 路由
+
+Windy Starter 把平台 Router 和访问快照 Guard 保留在
+`apps/web/src/router/`，客户业务路由只注册到
+`apps/web/src/app/business-routes.ts`。整个 `apps/web/src/app/` 在
+`.windy/files.json` 中属于 `project-owned`：更新器不会覆盖客户新增、修改或删除的
+路由注册与页面源码。
+
+## 注册一个页面
+
+先在业务 Module Manifest 中用同一个能力基础 Key 声明 Feature、Permission、菜单和
+Admin Route，再在 `installedBusinessAdminRoutes` 中注册页面实现：
+
+```ts
+import CaseRecordsPage from "./case-records/CaseRecordsPage.vue";
+
+export const installedBusinessAdminRoutes = [
+  {
+    key: "case.record",
+    path: "/cases",
+    name: "case-records",
+    title: "案件",
+    component: CaseRecordsPage,
+    featureKey: "case.record",
+    permissionKey: "case.record.read",
+  },
+] satisfies readonly BusinessAdminRouteRegistration[];
+```
+
+注册表必须与 Module Manifest 使用相同的 `key`、`path`、`featureKey` 和
+`permissionKey`。服务端仍是最终授权边界；Web Router 会把注册项统一转换为
+`layout: "admin"` 路由，并在每次导航时使用访问快照检查 Feature 与 Permission。
+空 Guard、重复业务 Route Key、相对路径和业务兜底路径会在启动组合时被拒绝。
+
+页面组件及其 composable、表单和状态放在 `apps/web/src/app/` 下。不要为了增加业务
+页面修改以下 shared-scaffold：
+
+- `apps/web/src/router/index.ts`
+- `apps/web/src/router/business-routes.ts`
+- `apps/web/src/layout/AppSidebar.vue`
+- `apps/web/src/layout/navigation.ts`
+
+## 导航来源
+
+侧栏和导航搜索不会读取 Web 注册表来复制一份菜单。服务端启动时从已安装业务 Module
+Manifest 同步菜单，`/api/foundation` 返回经过 License、Feature 和 RBAC 裁剪的访问
+快照，Web 外壳据此渲染导航。这样路径、权限、Feature 和菜单身份仍由 Manifest
+统一治理，客户只在 project-owned 注册表绑定 Vue 页面实现。
+
+如果页面可直达但侧栏没有入口，优先检查服务端
+`apps/server/src/installed-business-modules.ts` 是否已经安装对应业务 Module、Manifest
+是否声明菜单，以及当前账号是否具有 Permission；不要在 AppSidebar 手写菜单。
+
+## 升级行为
+
+首次生成时，`business-routes.ts` 会记为 `project-owned`。后续 target 即使提供了新的
+默认内容，也不能把 source manifest 中的该路径降级成 `shared-scaffold` 或
+`windy-managed`：
+
+- 客户修改继续保留；
+- 客户删除会以 tombstone 跨版本保留；
+- 客户重新创建后，清单刷新采纳新正文 hash，但仍保持 `project-owned`；
+- 平台只升级 Router Adapter 与 Guard，实现变更通过 shared-scaffold 三方合并进入。
+
+升级前可运行 `bun run windy update --dry-run` 查看所有权和冲突计划。纯业务页面与
+注册表变更不应产生平台侧源码覆盖。

package/template/docs/development/custom-login-page.md

@@ -78,9 +78,9 @@ composable。
 先提交当前业务改动并保持 Git 工作区干净，然后执行：
 
 ```bash
-bunx --bun create-windy@0.3.2 update --check --cwd .
-bunx --bun create-windy@0.3.2 update --dry-run --cwd .
-bunx --bun create-windy@0.3.2 update --cwd .
+bunx --bun create-windy@latest update --check --cwd .
+bunx --bun create-windy@latest update --dry-run --cwd .
+bunx --bun create-windy@latest update --cwd .
 bun install
 ```
 

package/template/docs/development/module-lifecycle.md

@@ -0,0 +1,71 @@
+# 部署期模块生命周期
+
+Windy 已部署项目通过项目锁定版本的 `create-windy` 管理模块，不重新运行创建命令，
+也不手工复制源码：
+
+```bash
+bun run windy module list
+bun run windy module add work-order --dry-run
+bun run windy module add work-order
+bun run windy module update work-order
+bun run windy module remove work-order --dry-run
+bun run windy module remove work-order --confirm-data-disposition
+```
+
+## 计划与事务
+
+模块命令读取 `.windy/generation.json` 的当前集合，再用
+`ModuleDistributionManifest` 解析依赖、冲突、Windy 兼容范围、package、文件、
+Schema、migration 与卸载策略。目标组合仍由 immutable template 生成，之后进入与
+`windy update` 相同的 Base/Ours/Theirs 计划、文件 expectation、workspace 检查、
+CAS 写入、验证、Project Lock/受管清单提交和 `doctor --repair` 恢复流程。
+
+模块命令要求项目的 `windyVersion`、`generatorVersion` 与当前 CLI 的 template 版本
+完全一致；旧项目先运行 `bun run windy update`。这样目录、recipe 和目标模板不会跨
+版本混用。
+
+`add` 与 `remove` 是幂等操作：集合已满足时不启动事务。`update` 不改变集合，用当前
+CLI 重建所选模块并应用目录声明的更新 recipe。正式操作要求 Git 工作区干净；客户
+修改过的受管文件或模块 project-owned 扩展点会形成冲突，不会被静默覆盖。
+
+## 数据处置
+
+卸载首先输出数据处置计划。`--dry-run` 只展示文件和冲突；正式卸载必须显式传入
+`--confirm-data-disposition`。
+
+| 策略           | 行为                                                               |
+| -------------- | ------------------------------------------------------------------ |
+| `retain-data`  | 默认；保留业务表与记录，不执行 down migration                      |
+| `archive-data` | 目录要求外部先归档；通过 `--data-plan <文件>` 绑定已审阅的处置文档 |
+| `manual`       | 目录要求人工决定；同样必须绑定处置文档                             |
+
+CLI 不连接生产数据库，确认参数表示部署操作人已完成并审阅相应动作，不代表 Windy
+自动执行 SQL 或数据库归档。即使策略名为 `archive-data`，CLI 对数据库本身仍是
+retain：数据删除或归档由处置文档约束的外部运维流程负责。目录策略只能被提高，不能
+从 `archive-data` 或 `manual` 降为 `retain-data`。
+
+卸载不会删除已发布 migration。模块自有 migration 源文件按原相对路径保存到
+`.windy/module-history/<module>/`；模块重装时历史仍保留，数据库运行期继续以
+`windy_migration_history` 的 migration id 与 checksum 判定，不会因为代码重装而
+重复执行已应用迁移。历史目录受清单 hash 保护，缺失登记、符号链接或内容修改都会
+fail closed。
+
+## 物理残留边界
+
+目标组合会重新物化 package、workspace、宿主 Adapter、Composition、Module
+Manifest、Feature、Permission、菜单、任务、Provider、Tool、Schema 和文档。卸载后
+这些运行时或生成期引用不得残留；允许保留的只有：
+
+- 数据库中的业务数据与 migration ledger；
+- `.windy/module-history/` 下的不可执行迁移证据；
+- `.windy/reports/` 下的生命周期报告。
+
+如果其它已安装模块仍依赖待卸载模块，计划在写文件前拒绝。`system` 与
+`system.identity` 是 profile 核心，不支持卸载。
+
+## H3 证据
+
+通用 CLI 的存在不自动提升所有模块可靠度。`work-order` 的 H3 回归从纯核心项目开始，
+覆盖安装、重复安装、更新、保留数据卸载、重复卸载和重装，并检查 package、
+Project Lock 与 migration history artifact。其它模块保持 H2，直到分别通过同等级的
+安装、数据库、Server、卸载残留和恢复门禁。

package/template/docs/operations/observability.md

@@ -15,7 +15,11 @@
 
 `/api/health` 和 `/health` 只为已有调用方保留；新编排必须分别使用 liveness 和 readiness。Dockerfile 的 `HEALTHCHECK` 使用 readiness；根目录开发 Compose 也用 readiness 控制服务依赖，但它仍然不是生产编排。
 
-Server readiness 同时返回审计 writer 状态，便于对 `degraded`、队列积压或丢弃计数告警。审计降级当前不会自动把实例摘流；关键写入仍由业务 Guard fail closed，处置方式见[平台审计可靠写入](../platform/audit-reliability.md)。
+Server readiness 同时返回审计 writer 状态，便于对 `degraded`、队列积压或丢弃计数告警。审计降级当前不会自动把实例摘流；关键写入仍由业务 Guard fail closed。
+<!-- @windy-module system.audit begin -->
+
+处置方式见[平台审计可靠写入](../platform/audit-reliability.md)。
+<!-- @windy-module system.audit end -->
 
 ## Request 与 Job 关联
 

package/template/docs/platform/agent-runtime.md

@@ -222,17 +222,17 @@ SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，
 `run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
 cursor 恢复；不要重新创建 Run 或重复执行 Tool。
 
-## 从 create-windy 0.2.34 升级到 0.3.2
+## 升级既有 Starter
 
-目标 CLI 会一次解析 `0.2.34 → 0.3.0 → 0.3.1 → 0.3.2` 连续 recipe，不需要逐个安装中间
-CLI。确认 npm registry 已能解析精确的 `0.3.2` artifact 后，先检查计划，再应用：
+目标 CLI 会一次解析 source 到 target 的连续 recipe，不需要逐个安装中间 CLI。确认
+npm registry 已能解析目标 artifact 后，先检查计划，再应用：
 
 ```bash
-bunx --bun create-windy@0.3.2 update --check
-bunx --bun create-windy@0.3.2 update
+bunx --bun create-windy@latest update --check
+bunx --bun create-windy@latest update
 bun install
 ```
 
 升级器会更新受管模板文件；本地修改产生冲突时会 fail closed 并保留事务备份，不会静默
 覆盖。升级后按上面的环境变量启用 `agent` profile；`agent-debug` 仍只用于无业务 Tool
-的本机调试。自动化部署应固定精确版本，不能用未核验的 `latest` 替代。
+的本机调试。自动化部署应把已审阅的 `latest` 替换为精确版本。

package/template/docs/platform/agent-tool-sandbox.md

@@ -0,0 +1,58 @@
+# Agent Tool 隔离执行
+
+## 目标与边界
+
+Tool Sandbox 用于执行不需要业务状态和外部服务的纯计算 Tool。它降低模型生成参数触发
+进程级能力的风险，但不替代 Manifest、License、Feature、RBAC、Data Scope、Schema、
+超时和审计 Guard。
+
+只有通过 `InstallableServerModule.setupSandbox()` 注册的 Handler 会进入隔离 Worker。
+普通 `setup()` 中的 Tool 仍在 Server 进程执行，不自动获得操作系统隔离保证。业务必须
+逐个确认依赖边界后显式迁移，不能用名称或配置开关假装已经隔离。
+
+## 执行链
+
+1. Server 的统一 Tool Registry 完成 Actor、License、Feature、Permission、Scope 和
+   Schema 校验。
+2. Sandbox Client 为调用生成随机 Invocation ID，通过 Worker 每次启动生成的 32 字节
+   密钥签发短时 HMAC Grant。
+3. 请求经只挂载 IPC Volume 的 Unix Domain Socket 进入 Worker。Actor、权限、数据范围、
+   Secret、Repository 和原始审计上下文都不会进入 Worker。
+4. Worker 只加载 `setupSandbox()` 注册表，复验 Grant、截止时间、Tool Key 和输入大小，
+   再执行 Handler。
+5. Server 复验输出大小和 Manifest Schema，并写入不包含原始输入输出的审计摘要。
+
+Worker 重启会轮换密钥。Client 在连接中断或密钥轮换竞态时用相同 Invocation ID
+重试一次；已经收到的业务失败或执行超时不会在传输层自动重放。Sandbox Handler 只能
+使用输入、`idempotencyKey` 和 `AbortSignal`，并应保持确定性和无外部副作用。
+
+## 运行时隔离
+
+开发和生产 Compose 都将 Tool Worker 配置为：
+
+- `network_mode: none`，不连接应用、数据库或外部网络；
+- 只读 RootFS、移除全部 Linux capabilities、启用 `no-new-privileges`；
+- 不注入数据库、模型 Provider、内部服务 Token 或 Artifact 加密密钥；
+- 不挂载 Server 数据、源码目录或宿主业务文件，只挂载
+  `/run/windy-tool-sandbox` IPC Volume；
+- `/tmp` 为小容量、`noexec`、`nosuid`、`nodev` 的临时文件系统。
+
+镜像中仍包含应用程序本身。模块构造和 `setupSandbox()` 因此必须同步、无副作用，不能
+读取宿主路径或依赖导入时初始化的外部连接。
+
+命名 Volume 初始由 root 持有。一次性的 `tool-sandbox-init` 仅挂载该 IPC Volume，
+使用 `CHOWN` capability 将目录交给镜像内固定的 `bun` 用户后退出；它同样无网络、
+无 Secret、只读 RootFS。常驻 Worker 与 Server 随后以相同非 root UID 访问权限为
+`0700` 的目录，HMAC 密钥文件权限为 `0600`。
+
+## 失败与审计
+
+- 未注册 Tool、出网失败等隔离边界拒绝记为 `policy-denied`；
+- Handler 抛错、返回非对象或输出超限记为 `business-failure`；
+- Worker 不可用、授权材料轮换和协议错误使用稳定的 `SANDBOX_*` 错误码；
+- 审计只记录 Tool Key、执行模式、结果分类和受控摘要，不记录 Tool 原始参数、结果、
+  HMAC 密钥或 Grant。
+
+发版门禁的 `test:ops:tool-sandbox` 会从实际 Compose 启动 Worker，检查无网络、无平台
+Secret、最小挂载和 Worker 重启后的 Socket 恢复。该检查属于发布验证，不在普通提交
+门禁中运行。

package/template/docs/platform/document-ai-runtime.md

@@ -0,0 +1,204 @@
+# Document AI Runtime
+
+更新时间：2026-07-27。
+
+Windy 的 Document AI 是可选的独立故障域。业务模块声明稳定的
+`kind=document` Operation，并先把当前 Actor 有权读取的业务资源换成短时
+`ArtifactRef`；Southwind Server 完成 Feature、RBAC、License、数据范围、业务对象绑定
+和审计后，才把任务交给 Document Server。未安装或未配置 Document Server 时，对应
+Operation 稳定返回 `CAPABILITY_UNAVAILABLE`，普通业务和文本 Agent 仍可启动。
+
+首个实现返回受输出 Schema 约束的结构化 JSON：页级文本、坐标、Block、版面树、表格和
+标量元数据。搜索型 PDF 等二进制派生物必须等平台输出 Artifact Sink 签发后再作为
+`ArtifactRef` 返回；Document Adapter 不得自行返回文件 URL、主机路径或伪造引用。
+
+## 责任边界
+
+业务模块负责：
+
+- 在 Manifest 注册 Operation、Feature、Permission、Audit、输入/输出 Schema、
+  capability、数据分类、出网策略和 limits；
+- 注册业务资源到平台文件的授权策略，从 project-owned Repository 回查
+  `resourceId` 与 `fileId` 的真实绑定；
+- 使用 `context.aiArtifacts.issue(...)` 换取 opaque `ArtifactRef`；
+- 校验领域选项、解析领域结果并保存人工校正、来源回链和业务状态。
+
+平台负责：
+
+- 每次签发和回取 Artifact 时重新解析 Actor、Feature、Permission、License、数据范围
+  与业务对象绑定；
+- Artifact 引用加密、完整性元数据、短 TTL 和内部认证下载；
+- Operation capability 摘要校验、Actor + Operation 隔离的幂等键、页级进度、取消、
+  稳定错误和启动审计；
+- 输入字节、输出字节、页数/处理单元、时长、Deployment 与出网策略。
+
+Document Server 负责：
+
+- 有界下载 Artifact 并再次核对字节数和 SHA-256；
+- 持久化 Run、事件 cursor、幂等指纹和终态结果；
+- 调用已配置的本地/内网 Document Adapter；
+- 校验页级结构、坐标、版面树、表格、输出大小和页数；
+- 重启时把未完成任务稳定终止，防止把半成品误报为成功。
+
+业务不得导入 OCR SDK、启动模型进程、传 Base64、Blob Key、宿主绝对路径或任意公网
+URL，也不得把文本 Agent 或浏览器文本提取宣称为 OCR。
+
+## Module 接入
+
+Document Operation 的 `limits.maxUnits` 必填；对文档表示最大页数。离线或内网
+Deployment 使用 `providerEgress: { mode: "forbidden" }`。若受控 Provider 出网，
+Manifest 还必须声明稳定 `deploymentKey` 和最小 `providerDataPolicy`，业务不能提交
+Endpoint、模型名或 Secret。
+
+```ts
+const operation = {
+  key: "evidence.transcript.ocr",
+  kind: "document",
+  featureKey: "evidence.transcript.ocr",
+  permissionKey: "evidence.transcript.ocr.execute",
+  auditAction: "evidence.transcript.ocr.execute",
+  inputSchemaKey: "evidence.transcript.ocr.input.v1",
+  outputSchemaKey: "evidence.transcript.ocr.output.v1",
+  requiredCapabilities: ["document.ocr", "document.layout"],
+  allowedToolKeys: [],
+  dataClassification: "sensitive",
+  execution: "background",
+  providerEgress: { mode: "forbidden" },
+  limits: {
+    maxDurationSeconds: 600,
+    maxInputBytes: 64 * 1024 * 1024,
+    maxOutputBytes: 16 * 1024 * 1024,
+    maxUnits: 500,
+  },
+} as const;
+```
+
+模块路由先换取 Artifact：
+
+```ts
+const source = await context.aiArtifacts.issue({
+  fileId,
+  purpose: "evidence.transcript-source",
+  resourceType: "evidence.transcript",
+  resourceId: transcriptId,
+});
+```
+
+该调用只有在同一模块已注册对应 `ModuleResourceFileAccessPolicy`，且策略从业务
+Repository 证明当前 Actor 可访问真实资源并绑定该文件时才会成功。客户端只把返回值交给
+`@southwind-ai/ai-client/document`，不能解析或持久化其中的内部位置。
+
+模块还要为同一 Operation 注册 `prepareDocument`。受控出网 Operation 的 Handler 只
+接收经过 `providerDataPolicy.inputFields` 裁剪/DLP 的选项；完全断网 Operation 接收
+领域选项。两者都不接收 Provider、Artifact Token 或平台 Repository。
+
+## HTTP 与事件协议
+
+浏览器通过同源 Southwind Server 调用：
+
+```text
+POST /api/document/runs
+GET  /api/document/runs/:runId/events?after=<sequence>
+GET  /api/document/runs/:runId/result
+POST /api/document/runs/:runId/cancel
+```
+
+单文档任务传 `source`；图片合并等多源任务传 `sources`。二者不能同时出现。平台会逐个
+轮换、核对并下载 Artifact，按 Operation 的 `limits.maxArtifacts` 和总输入字节预算
+fail closed；Adapter 的单源 multipart 字段为 `file`，多源字段为重复的 `files`。
+
+创建请求需要 `idempotency-key`。平台把外部键按 Actor 与 Operation 做不可逆作用域化；
+相同作用域、Artifact 哈希、选项和 capability 重放返回原 Run，语义漂移返回
+`RUN_CONFLICT`。事件包含：
+
+- `run.started`
+- `document.page.completed`
+- `run.completed`
+- `run.failed`
+- `run.cancelled`
+
+每个事件都有单调 `sequence`。客户端断线后使用最后确认的 sequence 恢复，不重新提交
+任务。取消会记录终态并取消当前 Adapter 协程；已进入终态的 Run 不会再次完成。
+
+## Document Adapter 契约
+
+`DOCUMENT_ADAPTER_URL` 只允许 localhost、私网 IP 或 `.internal` 主机。Document Server
+以 `multipart/form-data` 调用：
+
+```text
+POST <DOCUMENT_ADAPTER_URL>/v1/document/process
+```
+
+请求包含单个 `file` 以及 `operationKey`、`options`、`dataClassification`、
+`providerEgress`、`providerDataPolicy` 和 `limits`。Adapter 返回 JSON：
+
+```json
+{
+  "pages": [
+    {
+      "pageNumber": 1,
+      "text": "第一页文本",
+      "blocks": [
+        {
+          "id": "b1",
+          "text": "第一页文本",
+          "confidence": 0.98,
+          "bounds": {
+            "x": 0.1,
+            "y": 0.1,
+            "width": 0.8,
+            "height": 0.1,
+            "unit": "normalized"
+          }
+        }
+      ],
+      "layout": []
+    }
+  ],
+  "tables": [],
+  "artifacts": [],
+  "metadata": { "engine": "intranet-ocr" }
+}
+```
+
+页码必须唯一且不超过 `maxUnits`；坐标非负，置信度在 0–1，版面树深度最多 32。表格只能
+引用已存在页码，单元格必须是字符串。当前 `artifacts` 必须为空，防止 Adapter 绕过
+平台签发链。
+
+## 配置与启动
+
+选择 `system.agent` 的 Starter 会分发 Agent 与 Document 两个独立进程。`.env` 至少
+配置：
+
+```dotenv
+PLATFORM_ENABLE_AI=true
+AGENT_SERVER_INTERNAL_TOKEN=<随机内部令牌>
+AI_ARTIFACT_ENCRYPTION_SECRET=<至少 32 字符的随机值>
+DOCUMENT_SERVER_URL=http://document-server:8090
+DOCUMENT_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+DOCUMENT_ADAPTER_URL=http://ocr.internal:9000
+DOCUMENT_ADAPTER_TOKEN=<可选内部令牌>
+DOCUMENT_ADAPTER_CAPABILITIES=document.ocr,document.layout,document.table
+DOCUMENT_MAX_UNITS=500
+```
+
+受控 Provider Deployment 还要设置 `DOCUMENT_DEPLOYMENT_KEY`，并与 Manifest 的稳定
+Key 完全一致。启动：
+
+```bash
+bun run dev:document
+```
+
+Document Server 的 `/health/ready` 需要内部 Bearer Token，只返回 ready/unavailable、
+capability 和非敏感 limits。没有 Adapter 时返回 unavailable；不会回显 Token、内部
+文件 URL、业务正文或底层异常。
+
+## 运维与取舍
+
+- Run 与事件当前使用 Document Server 自有 SQLite，适合单副本；多副本持久化与平台侧
+  Run 授权恢复由统一 Agent 持久化能力继续收敛。
+- Artifact 默认短时有效，并在每次读取时重算授权；任务时长不能超过 3600 秒。
+- Adapter 地址被限制为本地/内网。需要云 Provider 时由受审计的内网 Adapter 承接，
+  不允许业务直接配置公网 URL。
+- 当前选择结构化 JSON 作为首个稳定结果，不伪造搜索型 PDF Artifact。后续输出文件必须
+  通过平台 Artifact Sink、TTL、下载权限和审计后再开放。

package/template/docs/platform/governed-export-renderers.md

@@ -0,0 +1,132 @@
+# 受治理导出 Renderer
+
+更新时间：2026-07-27。
+
+## 适用边界
+
+业务 Module 可以在 `registerGovernedResources()` 的 `export.renderers` 中注册服务端
+Renderer，把同一条受治理导出链生成 PDF、DOCX、XLSX 或其它受控格式。Renderer 是版式
+实现，不是新的授权或存储入口：
+
+- 平台固化请求 Actor、Policy、查询、Scope 与 Renderer 版本；
+- 平台处理审批、Durable Job、重试、取消、Artifact、TTL、失败清理和下载审计；
+- Worker 在开始和读取每一页前重新检查用户、权限、Feature、License 与 Scope；
+- Renderer 只能读取平台提供的 `AsyncIterable` 记录、水印、`AbortSignal` 和
+  `heartbeat()`，不能取得 Repository、BlobStore、Workflow、平台 Secret 或下载凭据。
+
+未声明 `renderers` 的已有 Module 保持 NDJSON 契约。声明 Renderer 后，请求必须显式提供
+已注册的 `formatKey`；缺少、未知或执行时未绑定的格式均 fail closed，不回退到 NDJSON。
+
+## 注册契约
+
+每个 Renderer 声明以下不可变元数据：
+
+- `formatKey`：资源内稳定、唯一的小写格式 Key；
+- `templateKey`：当前 Module 命名空间内的模板 Key；
+- `templateVersion`：不可变模板版本；修改版式时递增，不覆盖历史版本；
+- `inputSchemaKey`：当前 Manifest `jsonSchemas` 已登记的记录输入 Schema；
+- `contentType` 与不含点号的 `filenameExtension`；
+- `maxRecords`、`maxOutputBytes` 和 `timeoutSeconds`；
+- `render()`：消费平台记录流并返回 `ReadableStream<Uint8Array>`。
+
+示例：
+
+```ts
+host.registerGovernedResources([
+  {
+    policyKey: "reports.official.fields",
+    readPath: "/api/reports/official/:id",
+    revealPath: "/api/reports/official/:id/plaintext",
+    revealAuditAction: "reports.official.reveal",
+    authorize,
+    read,
+    export: {
+      basePath: "/api/reports/official/exports",
+      validateQuery,
+      readPage,
+      renderers: [
+        {
+          formatKey: "pdf",
+          templateKey: "reports.official.pdf",
+          templateVersion: "2026.07",
+          inputSchemaKey: "reports.official.input.v1",
+          contentType: "application/pdf",
+          filenameExtension: "pdf",
+          limits: {
+            maxRecords: 10_000,
+            maxOutputBytes: 20 * 1024 * 1024,
+            timeoutSeconds: 120,
+          },
+          async render({ records, watermark }, { signal, heartbeat }) {
+            return renderOfficialPdf({
+              records,
+              watermark,
+              signal,
+              heartbeat,
+            });
+          },
+        },
+      ],
+    },
+  },
+]);
+```
+
+`renderOfficialPdf()` 属于业务 package，但必须是纯服务端流式 Renderer。它可以使用随
+业务 package 分发的模板和字体，不得在执行时绕回业务 Repository 补查数据，也不得自行
+上传、发布或签发下载链接。
+
+## 请求与版本固化
+
+创建请求的 body 在原有 `idempotencyKey`、`reason`、`query` 之外接受 `formatKey`。
+平台在校验 Host 注册后，把以下快照持久化并纳入请求 fingerprint：
+
+- 格式、模板 Key 与模板版本；
+- 输入 Schema Key；
+- MIME 与扩展名；
+- 记录、输出字节和超时上限。
+
+相同幂等键改选格式、模板或上限会形成语义冲突。Worker 执行时把持久化快照与当前 Host
+注册逐项比对；部署遗漏 Renderer 或模板版本漂移会终止任务，避免恢复任务静默套用另一套
+版式。
+
+## 流、取消与资源限制
+
+平台逐页调用业务 `readPage()`，在每页读取前重新授权，再把记录逐条交给 Renderer。
+Renderer 应使用 `for await` 消费记录，不应先汇总完整数组。Renderer 未完整消费记录流
+即返回产物时，平台拒绝发布。
+
+平台同时施加以下硬边界：
+
+- 超过 `maxRecords` 时终止记录流；
+- 读取输出流时累计实际字节数，超过 `maxOutputBytes` 时终止；
+- `timeoutSeconds` 到期或 Durable Job 取消时中止同一个 `AbortSignal`；
+- 每页完成后更新 heartbeat 与 Durable Job progress；
+- 渲染、流读取或 Artifact 发布失败时删除已经写入但尚未发布的 Blob。
+
+Renderer 必须把 `signal` 继续传给支持取消的模板、压缩或文档库。忽略 Signal 的库仍会在
+平台读取输出时被终止，但可能延迟释放其内部 CPU 或内存，因此不应作为生产 Adapter。
+
+## Artifact 与审计
+
+发布后的 Durable Artifact 记录真实文件名、MIME、SHA-256、字节数，并在受控 metadata
+中记录 `formatKey`、`templateKey`、`templateVersion`、`inputSchemaKey` 和 Renderer
+返回的有限 `contentMetadata`。`contentMetadata` 只允许有界 JSON，不得包含记录原文、
+敏感字段、完整 ID 集或模板生成的正文。
+
+请求审计记录格式和模板版本；生成 intent 审计还记录输入 Schema 与 MIME；下载审计记录
+同一格式、模板版本和内容摘要。下载前仍重新检查 owner、Permission、Feature、审批、
+TTL、Artifact 引用和 Blob 完整性，Renderer 不能改变这些顺序。
+
+## 测试要求
+
+业务 Renderer 至少覆盖：
+
+- 正文、来源引用和水印内容，而不只断言文件存在；
+- 请求缺少格式、未知格式、注册丢失和模板版本漂移；
+- 多页记录按流消费，记录/输出上限与超时；
+- 取消、权限撤销、Scope 变化、渲染失败和发布失败不留下可下载半成品；
+- 下载 MIME、文件名、SHA-256、字节数与模板元数据一致。
+
+PDF、DOCX、XLSX 应使用对应解析库回读断言正文和水印。平台的测试 Renderer 只证明 Port
+及治理生命周期；具体文档格式正确性由实现该格式的业务 Module 负责。

package/template/docs/platform/navigation-registry.md

@@ -34,3 +34,8 @@ PUT /api/system/menus/:id/placement
 ## 扩展约束
 
 新增页面时先在所属 Module Manifest 用同一能力 Key 注册 Feature、权限、菜单和 API 绑定，再新增 Router 页面。Router 契约测试会比较所有 `type=menu` 的 Manifest 路径与 Web 路由，避免出现“菜单有入口但页面不存在”或“页面绕过注册表”的漂移。
+
+客户业务页面不直接修改 shared-scaffold Router 或侧栏。页面实现注册到
+project-owned 的 `apps/web/src/app/business-routes.ts`，平台 Router Adapter 统一补齐
+Feature/RBAC Guard；侧栏仍从服务端 Manifest 快照生成。完整接入与升级边界见
+[project-owned 业务 Web 路由](../development/business-web-routes.md)。

package/template/docs/platform/organization-membership.md

@@ -9,7 +9,8 @@ Windy V1 采用单组织、单租户的企业私有化模型。canonical schema
 - `roles.data_scope` 和 `roles.department_ids` 表示角色数据范围策略；
 - 岗位、兼职部门和多组织成员关系属于后续独立模型，不复用 `department_id` 暗中表达。
 
-这些边界延续 [RuoYi-Vue 兼容与迁移设计](../adapters/ruoyi-vue-compatibility.md) 的 Adapter 原则，也与 [Starter 产品缺口分析](../product/starter-product-gap-analysis.md) 中“单组织 V1”和“数据权限必须进入查询约束”的结论一致。
+这些边界延续 [RuoYi-Vue 兼容与迁移设计](../adapters/ruoyi-vue-compatibility.md) 的
+Adapter 原则；数据权限必须进入查询约束，不能只依赖 Web 菜单或按钮隐藏。
 
 ## 用户表单闭环