docs(ui): apps 页停止教 17.0.0 已退役的 version / mobileNavigation,两个 os:check 块改用 defineApp() (#5313)

[os-zhuang]

Fixes #5313

前提复核(origin/main @ 61fde5e)

单子的四处现场逐一核过,全部仍然成立:

位置	内容	墓碑
apps.mdx:17(第 12 行 os:check 块内)	version: '1.0.0'	app.zod.ts:1116
apps.mdx:45(App Properties 表)	version / string / optional	同上
apps.mdx:217-227(整节 Mobile Navigation)	mobileNavigation: { mode, bottomNavItems } + mode 取值说明	app.zod.ts:1262
apps.mdx:235(第 230 行 os:check 块内)	version: '2.0.0'	同 version

把两个 os:check 块原样喂 getMetadataTypeSchema('app')(一次性 harness,已删):

--- apps.mdx:14 (crmApp) parses: false
    version :: `App.version` was removed in @objectstack/spec 17.0.0 (2026-06 liveness audit — no consumer in framework or objectui). An app is versioned by its owning package: use `manifest.version`. Delete the key.
--- apps.mdx:232 (projectApp) parses: false
    version :: `App.version` was removed in @objectstack/spec 17.0.0 ...

墓碑是 retiredKey()(z.never().optional()),所以照抄本页示例不是「多写一个没用的键」,是整条 save 硬失败。

改法(PM 已裁定走 A:修示例 + 加类型标注,不动门本体)

处置一律以 origin/main 上墓碑自己的处方为准:

• version —— 墓碑写「An app is versioned by its owning package: use manifest.version. Delete the key.」→ 两个示例里的 version 行删除,App Properties 表的 version 行删除。
• mobileNavigation —— 墓碑写「fully unimplemented; no renderer, including packages/mobile, ever read it. Delete the key; the block returns if/when a real mobile navigation ships.」→ 无替代能力可指向,故整节 ## Mobile Navigation 删除(而不是改写成指路)。
• App Properties 表后新增一个 warn Callout,点名这两个键 + 各自处方,并指回本页正文已经交代过的 homePageId(清空剩余 6 条 authorWarn 死键 —— book ×2 / job.id / translation.validationMessages / app.homePageId / app.areas[].order（ADR-0049，v17 限时） #4667 / app.homePageId 退役的前提写错了 —— objectui 的 resolveLandingRoute() 一直在读它，现在成了永远走不到的死分支 #4709)。形制照刚合并的 docs(protocol): widget-contract 的 Theme 段停止教 #3494 已删除的 density,token 词表按 #5021 重写 (#5291) #5454(widget-contract)那一版。

类型标注用 defineApp({ … }):它是 app.zod.ts:482 自称的「documented authoring entry point」,签名 defineApp(config: z.input< typeof AppSchema >),且该页变量名(const crmApp = …)与 defineApp 的 JSDoc 示例完全同形;邻近页的惯例也是这一类(views.mdx 用 defineView,ui/index.mdx 用 App.create)。AppInput 确实是真类型而不是 unknown —— app.nav-type-assertions.ts 的探针把这件事钉住了(#4171/#4221/#4227),所以 never 入参这次真的会参与推断。

双向证明

改前方向(先只加标注、不删 version) —— 同一个门当场红:

✗ Prose TypeScript examples do not compile against @objectstack/spec:

  content/docs/ui/apps.mdx:19:3
      error TS2322: Type 'string' is not assignable to type 'undefined'.
  content/docs/ui/apps.mdx:239:3
      error TS2322: Type 'string' is not assignable to type 'undefined'.

这一步正是本单要害的证据:加标注之前,同样两个块喂给同一个门是 ✅ 绿的 —— 门只做 tsc,而无标注的对象字面量与 AppSchema 之间没有任何关联,retiredKey() 的 never 永不参与推断,所以「os:check 覆盖的是示例能否编译,不是示例是否合规」。标注本身就是本次修复的护栏。

改后:

✅ 204 prose examples type-check against @objectstack/spec
--- apps.mdx:14 (crmApp) parses: true
--- apps.mdx:238 (projectApp) parses: true

其余门:check:doc-authoring ✓ 362 files clean;check:nul-bytes OK(5447 files);MDX 用 @mdx-js/mdx 实编过一遍(Callout 与其中的 markdown 列表都正常渲染,没有被当成缩进代码块)。

范围

• 只动 content/docs/ui/apps.mdx + 一个 docs-only changeset(空 frontmatter)。
• 不动 packages/spec/scripts/check-skill-examples.ts(单子里的 B 方案:块级 safeParse。覆盖更广,但要先解决「哪个块对应哪个 schema」的归属推断,是独立的一次设计,留给维护者决定是否另立项)。
• 不碰 packages/spec/**、content/docs/references/**、content/docs/releases/。
• 已核:全仓(除 references/ 生成物与 releases/)再无第二处教 mobileNavigation;本页也没有指向被删章节的锚点链接。本页 App Properties 表其余各行与 AppSchema 的活键逐一对过,无第二个退役键。

🤖 Generated with Claude Code

https://claude.ai/code/session_01GX3sL71LFq8m2usg6VqTSE

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 5, 2026 1:11pm