@manohub/kit 0.7.1 → 0.8.1

package/skills/{kit → manohub-kit}/references/adoption.md

@@ -1,170 +1,170 @@
-# 接入 SOP
-
-把一个新的（或存量的）子应用接到「`@manohub/kit` 入口编排 + `@manohub/theme` 令牌
-+ `@manohub/ui` 组件」上。
-存量改造的逐文件口径另见 `../../kit-migrate/references/migration-map.md`。
-
-契约原文：`node_modules/@manohub/kit/CONTRACT.md`。**本文件是操作步骤，条款以契约为准。**
-
----
-
-## 0. 前置
-
-- Node / pnpm 版本与消费仓要求一致；
-- 消费仓已有 vite + Vue 3 + TypeScript；
-- 知道自己是不是 micro-app 子应用（影响路由 history 模式与挂载协议，§3）。
-
-## 1. 安装
-
-```bash
-pnpm add @manohub/kit @manohub/ui @manohub/theme
-pnpm add vue vue-router pinia vue-i18n @tanstack/vue-query   # peer，由应用提供
-```
-
-- 三个包**并列安装**：kit 管入口编排与契约，ui 管组件与服务，theme 管全局令牌（值）。
-- `@manohub/ui` 自带 `@manohub/icon` 依赖，不必单独声明。
-- **每个引入 kit 的应用都必须声明 `vue-i18n`**，哪怕不传 `i18n` 选项 ——
-  `createSubApp` 所在模块静态引入它，漏装会在构建期报 `Rollup failed to resolve import "vue-i18n"`。
-
-依赖自查（消费仓根执行）：
-
-```bash
-for p in apps/*/package.json packages/*/package.json; do
-  grep -q '"@manohub/kit"' "$p" && ! grep -q '"vue-i18n"' "$p" && echo "MISS $p"
-done
-```
-
-## 2. 样式：两行 + 应用自己一行（顺序即契约）
-
-**`@manohub/kit` 不发布任何样式** —— 样式两行直接引主题包与组件库的公开入口。
-
-应用入口 CSS（如 `src/style.css`）：
-
-```css
-@import "@manohub/theme/default.css";   /* ① 令牌（值）—— 换主题只换这一行 */
-@import "@manohub/ui/styles.css";   /* ② 组件面（类 + 组件令牌基础值） */
-@import "./app.css";                    /* ③ 应用自身（只写布局） */
-```
-
-- **顺序不可换**：先值（令牌）后面（组件面）—— 反过来的话组件面里的 `var(--ui-*)` 全是空值。
-- 换非兜底主题时把 ① 换成对应主题入口（如 `@import "@manohub/theme/farris.css";`），
-  并在入口给 `createSubApp({ theme: 'farris' })`。
-- **reset 与富文本排版归应用自己**：本包不再提供 `reset.css` 与 `.app-markdown` 预设
-  （0.6.0 起 `src/styles/` 整体删除）。应用侧要写时注意仍受样式纪律约束（契约 §3 L1）。
-
-## 3. 入口：走 createSubApp
-
-```ts
-// src/main.ts
-import { createSubApp } from '@manohub/kit/entry'
-import Root from './root'
-import { routes } from './router'
-
-export const { mount, unmount } = createSubApp({
-  rootComponent: Root,
-  routes,
-  i18n: { messages: { zh, en } },   // 纯 messages，无 i18next 的 translation 包装层
-  // history: 'hash',               // 宿主不支持深路径 fallback 时
-  // theme: 'farris',               // 换主题（要同时引那条主题样式）
-  // rootPathAliases: ['/subapp/'], // 宿主兼容前缀
-})
-```
-
-工厂带给你的（**不要自己再写**）：`div.app-container` 包裹与 `data-manohub-ui` / `data-theme` 属性、
-pinia / vue-router / vue-query 装配、宿主挂载协议（`window.mount/unmount` + `microApp.*`）、
-宿主语言同步、首帧路由重置。
-
-> **自建容器（不走 `createSubApp`）必须自己带 `data-manohub-ui`**：主题令牌、组件令牌、
-> 组件库服务层宿主解析全锚它一个。只写类名 `app-container` 已不再被任何一方识别（0.6.0 起）。
-
-单例收敛（三项都要，缺一项会在某台机器上出怪问题）：
-
-| 项 | 怎么做 | 漏了会怎样 |
-|---|---|---|
-| `vue` 单实例 | 消费仓 vite `resolve.dedupe: ['vue']`（monorepo 常见配置） | 组件与业务拿到两套响应式，`provide/inject` 失效 |
-| `vue-i18n` 单实例 | 消费仓 vite `resolve.dedupe: ['vue-i18n']` | **文案全丢且不报错** |
-| `@manohub/kit` / `@manohub/ui` / `@manohub/theme` 唯一副本 | 不要 `link:` 目录链接（会引入第二份 vue 类型） | `vue-tsc` 全量报错 |
-
-## 4. 命名空间表（本仓自建）
-
-自 0.6.0 起 `kit lint` 下线，**类名前缀不再由配置文件登记**，改为本仓自己维护一张命名空间表：
-`docs/kit-namespaces.md`（哪个应用占哪个类名前缀）。格式见
-`../../kit-migrate/references/migration-playbook.md` 的模板。
-
-- 库锚 `[data-manohub-ui]` 与类名 `.app-container` 恒允许、不必登记（但 `app-container` 不是跨包契约）。
-- 表只解决「类名归谁」这一件事；**样式属性本身合不合规由契约 §3 L1-5 判**，与命名空间无关。
-
-## 5. 技能包
-
-```bash
-pnpm exec kit install              # 落到 .codebuddy/skills/
-pnpm exec kit install --also-claude
-pnpm exec kit install --dry-run    # 只预览
-```
-
-包升级后重跑一次即刷新（安装器先清理同名目录再整体复制，幂等）。
-
-## 6. 类型与解析配置
-
-- tsconfig 的 `types` 需含 `vite/client`（否则 `.css` 导入报「无法解析」）；
-- `@manohub/kit`、`@manohub/ui`、`@manohub/theme` 都是**产物分发**（`exports` 指向 `dist`），
-  不需要额外的 `paths` 映射；若要映射到源码，只映射到包根 `src/index.ts`，别映射到内部文件
-  （那等于绕开公开入口，违反契约 §6 L3-1 的 import 源白名单）。
-
-## 7. 验收清单
-
-- [ ] `pnpm exec vue-tsc --noEmit` 0 错
-- [ ] `pnpm build` 成功
-- [ ] **人工过一遍契约 §7 自检清单**（24 问；0.6.0 起没有自动扫描兜底）
-- [ ] 应用能挂载：非 micro-app 下自动挂载；micro-app 下宿主能 `mount/unmount` 重挂
-- [ ] 容器带 `data-manohub-ui` 属性（`createSubApp` 无条件写；自建容器要自己写）
-- [ ] `toast('success', 'ok')` 后 DOM 里 `[data-manohub-ui]` 内有 `.mh-toast`（否则样式会丢）
-- [ ] `showLoading()` → `hideLoading()` 能开关自如（引用计数配平）
-- [ ] 语言切换一处生效（宿主下发 / `applyLocale`），业务文案与组件内建文案一起变
-- [ ] `index.html?xxx=1` 类入口已登记 `rootPathAliases`
-- [ ] 命名空间表 `docs/kit-namespaces.md` 已建
-
-## 8. 常见故障对照
-
-| 现象 | 原因与处理 |
-|---|---|
-| 文案全部显示 key | `vue-i18n` 双实例（缺 `dedupe`），或应用自己 `createI18n` 抢了注册 |
-| 组件渲染出来但没样式 | 样式两行缺失或顺序错（§2，本包已不转发样式）；或浮层落到 `body`（确认入口走 `createSubApp`） |
-| `toast` / `confirm` 的弹层样式全丢 | 同上：服务层宿主解析没落到本应用容器 → 在 `onReady` 里 `configureHost(el)` |
-| `showLoading` 关不掉 | 引用计数没配平：用返回的句柄在 `finally` 里关 |
-| 宿主 `unmount` 后重挂白屏 | 应用侧自己写了 `createApp` / `mount`，与工厂的协议冲突 |
-| 刷新深路径 404 | 宿主不支持 fallback：`history: 'hash'` |
-| 首屏 query 被清空 | `index.html?xxx=1` 入口未登记 `rootPathAliases` |
-| `vue-tsc` 报「两种同名类型不兼容」 | 装了第二份 `vue`（目录 `link:`、或 `.pnpm` 里残留旧副本）：重装 + 清 `.vite` 缓存 |
-
-## 9. 新应用从零搭建（最小骨架）
-
-```text
-my-app/
-├── package.json          依赖：三个包 + 五个 peer
-├── vite.config.ts        dedupe: ['vue', 'vue-i18n']
-├── tsconfig.json         types: ["vite/client"]
-├── docs/
-│   └── kit-namespaces.md   本仓类名命名空间表（§4）
-└── src/
-    ├── main.ts           createSubApp
-    ├── router/index.ts   routes
-    ├── root.tsx          根组件（可以有，也可以直接给页面）
-    ├── style.css         样式两行 + 应用自身（§2）
-    ├── app.css           应用自身布局
-    └── views/            页面（路由页放这里）
-```
-
-`src/main.ts` 见 §3；第一个页面用列表页模板（`../../kit-dev/references/page-recipes.md` 模板 A）。
-建成后：过一遍契约 §7 自检清单 → 按 §7 验收。
-
-## 10. 升级与破坏性变更
-
-- 升级前先读包根 `CONTRACT.md` 的 §12（升级）与包 `README.md` 的破坏性变更提示。
-- **`0.6.0` 是破坏性变更**（上一个是 `@manohub/app-kit@0.4.3`），三个方面**一次做完**：
-  ① 本包不再提供组件 —— `App*` 名与 `.ak-*` 样式全部退场、farris 退场；
-  ② 主题层独立成 `@manohub/theme`、容器锚改名 `data-app-container` → `data-manohub-ui`、
-  kit 不再发布任何样式；③ 消费侧机器规则（`kit lint` 三条护栏）整批下线，合规改为
-  「契约条款 + §7 自检清单」，契约整体重写为五层（L0 / L1 / L1.5 / L2 / L3）。
-  `appkit-guardrails.config.json` 不再被读取 —— 类名前缀迁到本仓 `docs/kit-namespaces.md`。
-- 升级后**务必重建产物再联调**（消费侧装的是 `dist`）；联调流程见包根 `AGENTS.md`。
+# 接入 SOP
+
+把一个新的（或存量的）子应用接到「`@manohub/kit` 入口编排 + `@manohub/theme` 令牌
++ `@manohub/ui` 组件」上。
+存量改造的逐文件口径另见 `../../manohub-kit-migrate/references/migration-map.md`。
+
+契约原文：`node_modules/@manohub/kit/CONTRACT.md`。**本文件是操作步骤，条款以契约为准。**
+
+---
+
+## 0. 前置
+
+- Node / pnpm 版本与消费仓要求一致；
+- 消费仓已有 vite + Vue 3 + TypeScript；
+- 知道自己是不是 micro-app 子应用（影响路由 history 模式与挂载协议，§3）。
+
+## 1. 安装
+
+```bash
+pnpm add @manohub/kit @manohub/ui @manohub/theme
+pnpm add vue vue-router pinia vue-i18n @tanstack/vue-query   # peer，由应用提供
+```
+
+- 三个包**并列安装**：kit 管入口编排与契约，ui 管组件与服务，theme 管全局令牌（值）。
+- `@manohub/ui` 自带 `@manohub/icon` 依赖，不必单独声明。
+- **每个引入 kit 的应用都必须声明 `vue-i18n`**，哪怕不传 `i18n` 选项 ——
+  `createSubApp` 所在模块静态引入它，漏装会在构建期报 `Rollup failed to resolve import "vue-i18n"`。
+
+依赖自查（消费仓根执行）：
+
+```bash
+for p in apps/*/package.json packages/*/package.json; do
+  grep -q '"@manohub/kit"' "$p" && ! grep -q '"vue-i18n"' "$p" && echo "MISS $p"
+done
+```
+
+## 2. 样式：两行 + 应用自己一行（顺序即契约）
+
+**`@manohub/kit` 不发布任何样式** —— 样式两行直接引主题包与组件库的公开入口。
+
+应用入口 CSS（如 `src/style.css`）：
+
+```css
+@import "@manohub/theme/default.css";   /* ① 令牌（值）—— 换主题只换这一行 */
+@import "@manohub/ui/styles.css";   /* ② 组件面（类 + 组件令牌基础值） */
+@import "./app.css";                    /* ③ 应用自身（只写布局） */
+```
+
+- **顺序不可换**：先值（令牌）后面（组件面）—— 反过来的话组件面里的 `var(--ui-*)` 全是空值。
+- 换非兜底主题时把 ① 换成对应主题入口（如 `@import "@manohub/theme/farris.css";`），
+  并在入口给 `createSubApp({ theme: 'farris' })`。
+- **reset 与富文本排版归应用自己**：本包不再提供 `reset.css` 与 `.app-markdown` 预设
+  （0.6.0 起 `src/styles/` 整体删除）。应用侧要写时注意仍受样式纪律约束（契约 §3 L1）。
+
+## 3. 入口：走 createSubApp
+
+```ts
+// src/main.ts
+import { createSubApp } from '@manohub/kit/entry'
+import Root from './root'
+import { routes } from './router'
+
+export const { mount, unmount } = createSubApp({
+  rootComponent: Root,
+  routes,
+  i18n: { messages: { zh, en } },   // 纯 messages，无 i18next 的 translation 包装层
+  // history: 'hash',               // 宿主不支持深路径 fallback 时
+  // theme: 'farris',               // 换主题（要同时引那条主题样式）
+  // rootPathAliases: ['/subapp/'], // 宿主兼容前缀
+})
+```
+
+工厂带给你的（**不要自己再写**）：`div.app-container` 包裹与 `data-manohub-ui` / `data-theme` 属性、
+pinia / vue-router / vue-query 装配、宿主挂载协议（`window.mount/unmount` + `microApp.*`）、
+宿主语言同步、首帧路由重置。
+
+> **自建容器（不走 `createSubApp`）必须自己带 `data-manohub-ui`**：主题令牌、组件令牌、
+> 组件库服务层宿主解析全锚它一个。只写类名 `app-container` 已不再被任何一方识别（0.6.0 起）。
+
+单例收敛（三项都要，缺一项会在某台机器上出怪问题）：
+
+| 项 | 怎么做 | 漏了会怎样 |
+|---|---|---|
+| `vue` 单实例 | 消费仓 vite `resolve.dedupe: ['vue']`（monorepo 常见配置） | 组件与业务拿到两套响应式，`provide/inject` 失效 |
+| `vue-i18n` 单实例 | 消费仓 vite `resolve.dedupe: ['vue-i18n']` | **文案全丢且不报错** |
+| `@manohub/kit` / `@manohub/ui` / `@manohub/theme` 唯一副本 | 不要 `link:` 目录链接（会引入第二份 vue 类型） | `vue-tsc` 全量报错 |
+
+## 4. 命名空间表（本仓自建）
+
+自 0.6.0 起 `kit lint` 下线，**类名前缀不再由配置文件登记**，改为本仓自己维护一张命名空间表：
+`docs/kit-namespaces.md`（哪个应用占哪个类名前缀）。格式见
+`../../manohub-kit-migrate/references/migration-playbook.md` 的模板。
+
+- 库锚 `[data-manohub-ui]` 与类名 `.app-container` 恒允许、不必登记（但 `app-container` 不是跨包契约）。
+- 表只解决「类名归谁」这一件事；**样式属性本身合不合规由契约 §3 L1-5 判**，与命名空间无关。
+
+## 5. 技能包
+
+```bash
+pnpm exec kit install              # 落到 .codebuddy/skills/
+pnpm exec kit install --also-claude
+pnpm exec kit install --dry-run    # 只预览
+```
+
+包升级后重跑一次即刷新（安装器先清理同名目录再整体复制，幂等）。
+
+## 6. 类型与解析配置
+
+- tsconfig 的 `types` 需含 `vite/client`（否则 `.css` 导入报「无法解析」）；
+- `@manohub/kit`、`@manohub/ui`、`@manohub/theme` 都是**产物分发**（`exports` 指向 `dist`），
+  不需要额外的 `paths` 映射；若要映射到源码，只映射到包根 `src/index.ts`，别映射到内部文件
+  （那等于绕开公开入口，违反契约 §6 L3-1 的 import 源白名单）。
+
+## 7. 验收清单
+
+- [ ] `pnpm exec vue-tsc --noEmit` 0 错
+- [ ] `pnpm build` 成功
+- [ ] **人工过一遍契约 §7 自检清单**（24 问；0.6.0 起没有自动扫描兜底）
+- [ ] 应用能挂载：非 micro-app 下自动挂载；micro-app 下宿主能 `mount/unmount` 重挂
+- [ ] 容器带 `data-manohub-ui` 属性（`createSubApp` 无条件写；自建容器要自己写）
+- [ ] `toast('success', 'ok')` 后 DOM 里 `[data-manohub-ui]` 内有 `.mh-toast`（否则样式会丢）
+- [ ] `showLoading()` → `hideLoading()` 能开关自如（引用计数配平）
+- [ ] 语言切换一处生效（宿主下发 / `applyLocale`），业务文案与组件内建文案一起变
+- [ ] `index.html?xxx=1` 类入口已登记 `rootPathAliases`
+- [ ] 命名空间表 `docs/kit-namespaces.md` 已建
+
+## 8. 常见故障对照
+
+| 现象 | 原因与处理 |
+|---|---|
+| 文案全部显示 key | `vue-i18n` 双实例（缺 `dedupe`），或应用自己 `createI18n` 抢了注册 |
+| 组件渲染出来但没样式 | 样式两行缺失或顺序错（§2，本包已不转发样式）；或浮层落到 `body`（确认入口走 `createSubApp`） |
+| `toast` / `confirm` 的弹层样式全丢 | 同上：服务层宿主解析没落到本应用容器 → 在 `onReady` 里 `configureHost(el)` |
+| `showLoading` 关不掉 | 引用计数没配平：用返回的句柄在 `finally` 里关 |
+| 宿主 `unmount` 后重挂白屏 | 应用侧自己写了 `createApp` / `mount`，与工厂的协议冲突 |
+| 刷新深路径 404 | 宿主不支持 fallback：`history: 'hash'` |
+| 首屏 query 被清空 | `index.html?xxx=1` 入口未登记 `rootPathAliases` |
+| `vue-tsc` 报「两种同名类型不兼容」 | 装了第二份 `vue`（目录 `link:`、或 `.pnpm` 里残留旧副本）：重装 + 清 `.vite` 缓存 |
+
+## 9. 新应用从零搭建（最小骨架）
+
+```text
+my-app/
+├── package.json          依赖：三个包 + 五个 peer
+├── vite.config.ts        dedupe: ['vue', 'vue-i18n']
+├── tsconfig.json         types: ["vite/client"]
+├── docs/
+│   └── kit-namespaces.md   本仓类名命名空间表（§4）
+└── src/
+    ├── main.ts           createSubApp
+    ├── router/index.ts   routes
+    ├── root.tsx          根组件（可以有，也可以直接给页面）
+    ├── style.css         样式两行 + 应用自身（§2）
+    ├── app.css           应用自身布局
+    └── views/            页面（路由页放这里）
+```
+
+`src/main.ts` 见 §3；第一个页面用列表页模板（`../../manohub-kit-dev/references/page-recipes.md` 模板 A）。
+建成后：过一遍契约 §7 自检清单 → 按 §7 验收。
+
+## 10. 升级与破坏性变更
+
+- 升级前先读包根 `CONTRACT.md` 的 §12（升级）与包 `README.md` 的破坏性变更提示。
+- **`0.6.0` 是破坏性变更**（上一个是 `@manohub/app-kit@0.4.3`），三个方面**一次做完**：
+  ① 本包不再提供组件 —— `App*` 名与 `.ak-*` 样式全部退场、farris 退场；
+  ② 主题层独立成 `@manohub/theme`、容器锚改名 `data-app-container` → `data-manohub-ui`、
+  kit 不再发布任何样式；③ 消费侧机器规则（`kit lint` 三条护栏）整批下线，合规改为
+  「契约条款 + §7 自检清单」，契约整体重写为五层（L0 / L1 / L1.5 / L2 / L3）。
+  `appkit-guardrails.config.json` 不再被读取 —— 类名前缀迁到本仓 `docs/kit-namespaces.md`。
+- 升级后**务必重建产物再联调**（消费侧装的是 `dist`）；联调流程见包根 `AGENTS.md`。

package/skills/{kit → manohub-kit}/references/contract-index.md

@@ -1,76 +1,76 @@
-# 契约速查索引
-
-用法：先在这里定位章节，再读 `node_modules/@manohub/kit/CONTRACT.md` 的对应段落。
-**本文只做索引，不复述条款** —— 口径冲突时一律以契约原文为准。
-
-组件与服务的 **API 细节不在 kit 的契约里**：它们在 `node_modules/@manohub/ui/README.md`
-与包内类型声明（`dist/**/*.d.ts`）；**全局令牌（值）**在 `node_modules/@manohub/theme/dist/` 的分片 CSS 里
-（契约 §0 权威源表列了全部读取路径）。
-
-## 我想知道…
-
-| 我想知道 | 看哪里 |
-|---|---|
-| 写任何东西前，该去哪个文件取值 / 查件名 / 查词表 | 契约 **§0 权威源表** |
-| 应用怎么接入（装什么、样式三行、入口） | 契约 §1 接入 |
-| 换主题 / 换掉第一行主题样式 | 契约 §1.2 |
-| 容器上到底哪些名字是跨包约定 | 契约 §1.3 入口 |
-| 目录怎么摆（路由页放哪、可复用件放哪） | 契约 §1.4 目录约定 |
-| 包的设计底线（入口唯一、作用域锚、不重复骨架职责） | 契约 §2 L0（**不可豁免**） |
-| 应用侧 CSS 能写什么、不能写什么 | 契约 §3 L1-5 的属性白名单（闭集，逐字照用） |
-| 想改组件外观 / 局部换肤怎么办 | 契约 §3「局部换肤」（重设**已有**令牌的值，不发明新令牌名） |
-| 图标怎么用（来源、尺寸、颜色、方位） | 契约 §4 L1.5 |
-| 一个新页面该怎么搭 | 契约 §5 L2 + 末节「三种页面模板（起手式）」 |
-| 谁滚、滚在哪一层 | 契约 §5 组 4 · 区域 |
-| 搜索框 / 筛选 / 操作按钮该放哪个位置 | 契约 §5 组 4 · 区域 |
-| 分页放页脚还是面板页脚 | 契约 §5 组 4 · 区域 |
-| 页头怎么用（`title` / `subTitle` / `icon` / `extra`） | 契约 §5 组 3 · 页头 |
-| 成员为什么没按我写的顺序渲染 | 契约 §5 组 2 · 归位 |
-| 加载 / 空 / 错三态、遮罩该用哪个件 | 契约 §5 组 5 · 版式 |
-| 表单行、只读摘要行、表单内分组 | 契约 §5 组 5 · 版式 |
-| 行 / 列怎么排、间距档、栅格列数 | 契约 §5 组 5 · 版式（`Layout`） |
-| 弹窗 / 抽屉 / 命令式提示怎么选 | 契约 §6 L3「件怎么用」 |
-| 区域容器与卡片怎么选 | 契约 §5 组 4 · 区域 + §6 |
-| 侧栏导航、树的受控展开 | 契约 §6 L3 |
-| 我用的件 / 成员 / prop 到底存不存在 | 契约 §0 权威源表给的 `.d.ts` 路径 |
-| 某个写法是不是违规 | 契约对应层的「正误对照」段（§3 / §4 / §5 / §6 各有一组） |
-| 需要的能力包里没有怎么办 | 契约 §8 缺件与新增怎么走 |
-| 收工前该核对什么 | 契约 **§7 自检清单**（五层共 24 问） |
-| 文案与语言切换怎么写 | 契约 §9 国际化 |
-| 某些「看起来不对」的地方是不是 bug | 契约 §10 已知偏差与有意取舍 |
-| 哪些文件是被设计定版豁免人工确认的 | 契约 §11 定版文件清单 |
-| **从 `@manohub/app-kit@0.4.3` 升到 `@manohub/kit@0.6.0`** | 契约 §12.1（三组变化一次做完）与 §12.2（迁移顺序）；对照表见 `../../kit-migrate/references/migration-map.md` |
-| 组件有哪些、每个件的 prop 是什么 | `node_modules/@manohub/ui/README.md` + `dist/index.d.ts` |
-| 本仓的类名命名空间归谁 | 本仓 `docs/kit-namespaces.md`（per-app 文件，不在契约里） |
-
-## 注意：0.6.0 起没有自动扫描了
-
-`kit lint` 与三条护栏（style / component / structure）**已下线**，本包不再发布消费侧机器规则。
-合规判据全在 `CONTRACT.md`：每条都是闭集，配合 §7 自检清单在**写作与评审时**把关。
-
-- 别再找「跑一条命令看有多少违规」——没有了。
-- 要全仓盘点时，按 `../../kit-migrate/references/migration-playbook.md` 的**条款级盘点口径**人工过。
-- **库侧**的机械校验（`@manohub/ui` 与 `@manohub/theme` 包内的契约测试）**仍然在跑**，
-  那是库自己的守卫，与消费方无关。
-
-## 最容易踩的几条（先记住这些再动手）
-
-1. **禁 `100vh` / `h-screen`**：子应用被注入宿主容器，高度一律 `100%`（契约 §5 组 5）。
-2. **分页跟承载表格的容器走**：表格在 `Panel` 里 → 分页放 `Panel.Footer`（契约 §5 组 4）。
-3. **筛选字段放 `Panel.Header.toolbar`、操作放 `actions`**；字段 >3 上提 `Page.Filter`（契约 §5 组 4）。
-4. **错误态与空态分开**：加载失败给 `QueryState` 的 `error`，不要塞进 `empty`（契约 §5 组 5）。
-5. **表格不要套 `height:auto` 的 div**：会让整个 Body 滚、表头跟着滚走（契约 §5 组 5）。
-6. **应用侧 CSS 只写布局**：属性白名单是闭集，不在名单里的一律违规（契约 §3 L1-5）。
-7. **别覆写组件库的内部类**：要改外观走契约 §3「局部换肤」（重设已有令牌的值）。
-8. **缺件走建件流程**，不在页面里自绘近似件，也不回去直连底层组件库（契约 §8）。
-9. **命令式提示要落在应用容器里**：用 `@manohub/ui` 的服务层（`toast` / `confirm`），
-   别自己写 `position: fixed` 的遮罩 —— 它拿不到令牌（契约 §2、§6）。
-10. **`index.html?xxx=1` 这类入口必须登记 `rootPathAliases`**，否则首屏守卫清空 query。
-11. **容器上必须有 `data-manohub-ui`**（入口层无条件写）：主题令牌、组件令牌、
-    组件库服务层宿主解析全锚它一个属性。自建容器必须自己写；类名 `app-container` 不是契约（契约 §1.3）。
-12. **`@manohub/kit` 不发布样式**：样式三行（`@manohub/theme` 令牌 → `@manohub/ui` 组件面 →
-    应用自身）由应用自己引；本包不提供 reset 与富文本预设（契约 §1.2、§10）。
-13. **成员必须是 `Page` 的直接子节点**：用 `<template v-if>` 包一层会编译成 Fragment，
-    归位认不出，那个成员会被当自由内容挪进主体区（契约 §5 组 2）。
-14. **`Page.Header` 不传 `title` 时 `extra` 静默不渲染**：不传 `title` 是合法的「自定义页头出口」，
-    但此时右侧位没有意义 —— 要放右侧位就必须传 `title`（契约 §5 组 3）。
+# 契约速查索引
+
+用法：先在这里定位章节，再读 `node_modules/@manohub/kit/CONTRACT.md` 的对应段落。
+**本文只做索引，不复述条款** —— 口径冲突时一律以契约原文为准。
+
+组件与服务的 **API 细节不在 kit 的契约里**：它们在 `node_modules/@manohub/ui/README.md`
+与包内类型声明（`dist/**/*.d.ts`）；**全局令牌（值）**在 `node_modules/@manohub/theme/dist/` 的分片 CSS 里
+（契约 §0 权威源表列了全部读取路径）。
+
+## 我想知道…
+
+| 我想知道 | 看哪里 |
+|---|---|
+| 写任何东西前，该去哪个文件取值 / 查件名 / 查词表 | 契约 **§0 权威源表** |
+| 应用怎么接入（装什么、样式三行、入口） | 契约 §1 接入 |
+| 换主题 / 换掉第一行主题样式 | 契约 §1.2 |
+| 容器上到底哪些名字是跨包约定 | 契约 §1.3 入口 |
+| 目录怎么摆（路由页放哪、可复用件放哪） | 契约 §1.4 目录约定 |
+| 包的设计底线（入口唯一、作用域锚、不重复骨架职责） | 契约 §2 L0（**不可豁免**） |
+| 应用侧 CSS 能写什么、不能写什么 | 契约 §3 L1-5 的属性白名单（闭集，逐字照用） |
+| 想改组件外观 / 局部换肤怎么办 | 契约 §3「局部换肤」（重设**已有**令牌的值，不发明新令牌名） |
+| 图标怎么用（来源、尺寸、颜色、方位） | 契约 §4 L1.5 |
+| 一个新页面该怎么搭 | 契约 §5 L2 + 末节「三种页面模板（起手式）」 |
+| 谁滚、滚在哪一层 | 契约 §5 组 4 · 区域 |
+| 搜索框 / 筛选 / 操作按钮该放哪个位置 | 契约 §5 组 4 · 区域 |
+| 分页放页脚还是面板页脚 | 契约 §5 组 4 · 区域 |
+| 页头怎么用（`title` / `subTitle` / `icon` / `extra`） | 契约 §5 组 3 · 页头 |
+| 成员为什么没按我写的顺序渲染 | 契约 §5 组 2 · 归位 |
+| 加载 / 空 / 错三态、遮罩该用哪个件 | 契约 §5 组 5 · 版式 |
+| 表单行、只读摘要行、表单内分组 | 契约 §5 组 5 · 版式 |
+| 行 / 列怎么排、间距档、栅格列数 | 契约 §5 组 5 · 版式（`Layout`） |
+| 弹窗 / 抽屉 / 命令式提示怎么选 | 契约 §6 L3「件怎么用」 |
+| 区域容器与卡片怎么选 | 契约 §5 组 4 · 区域 + §6 |
+| 侧栏导航、树的受控展开 | 契约 §6 L3 |
+| 我用的件 / 成员 / prop 到底存不存在 | 契约 §0 权威源表给的 `.d.ts` 路径 |
+| 某个写法是不是违规 | 契约对应层的「正误对照」段（§3 / §4 / §5 / §6 各有一组） |
+| 需要的能力包里没有怎么办 | 契约 §8 缺件与新增怎么走 |
+| 收工前该核对什么 | 契约 **§7 自检清单**（五层共 24 问） |
+| 文案与语言切换怎么写 | 契约 §9 国际化 |
+| 某些「看起来不对」的地方是不是 bug | 契约 §10 已知偏差与有意取舍 |
+| 哪些文件是被设计定版豁免人工确认的 | 契约 §11 定版文件清单 |
+| **从 `@manohub/app-kit@0.4.3` 升到 `@manohub/kit@0.6.0`** | 契约 §12.1（三组变化一次做完）与 §12.2（迁移顺序）；对照表见 `../../manohub-kit-migrate/references/migration-map.md` |
+| 组件有哪些、每个件的 prop 是什么 | `node_modules/@manohub/ui/README.md` + `dist/index.d.ts` |
+| 本仓的类名命名空间归谁 | 本仓 `docs/kit-namespaces.md`（per-app 文件，不在契约里） |
+
+## 注意：0.6.0 起没有自动扫描了
+
+`kit lint` 与三条护栏（style / component / structure）**已下线**，本包不再发布消费侧机器规则。
+合规判据全在 `CONTRACT.md`：每条都是闭集，配合 §7 自检清单在**写作与评审时**把关。
+
+- 别再找「跑一条命令看有多少违规」——没有了。
+- 要全仓盘点时，按 `../../manohub-kit-migrate/references/migration-playbook.md` 的**条款级盘点口径**人工过。
+- **库侧**的机械校验（`@manohub/ui` 与 `@manohub/theme` 包内的契约测试）**仍然在跑**，
+  那是库自己的守卫，与消费方无关。
+
+## 最容易踩的几条（先记住这些再动手）
+
+1. **禁 `100vh` / `h-screen`**：子应用被注入宿主容器，高度一律 `100%`（契约 §5 组 5）。
+2. **分页跟承载表格的容器走**：表格在 `Panel` 里 → 分页放 `Panel.Footer`（契约 §5 组 4）。
+3. **筛选字段放 `Panel.Header.toolbar`、操作放 `actions`**；字段 >3 上提 `Page.Filter`（契约 §5 组 4）。
+4. **错误态与空态分开**：加载失败给 `QueryState` 的 `error`，不要塞进 `empty`（契约 §5 组 5）。
+5. **表格不要套 `height:auto` 的 div**：会让整个 Body 滚、表头跟着滚走（契约 §5 组 5）。
+6. **应用侧 CSS 只写布局**：属性白名单是闭集，不在名单里的一律违规（契约 §3 L1-5）。
+7. **别覆写组件库的内部类**：要改外观走契约 §3「局部换肤」（重设已有令牌的值）。
+8. **缺件走建件流程**，不在页面里自绘近似件，也不回去直连底层组件库（契约 §8）。
+9. **命令式提示要落在应用容器里**：用 `@manohub/ui` 的服务层（`toast` / `confirm`），
+   别自己写 `position: fixed` 的遮罩 —— 它拿不到令牌（契约 §2、§6）。
+10. **`index.html?xxx=1` 这类入口必须登记 `rootPathAliases`**，否则首屏守卫清空 query。
+11. **容器上必须有 `data-manohub-ui`**（入口层无条件写）：主题令牌、组件令牌、
+    组件库服务层宿主解析全锚它一个属性。自建容器必须自己写；类名 `app-container` 不是契约（契约 §1.3）。
+12. **`@manohub/kit` 不发布样式**：样式三行（`@manohub/theme` 令牌 → `@manohub/ui` 组件面 →
+    应用自身）由应用自己引；本包不提供 reset 与富文本预设（契约 §1.2、§10）。
+13. **成员必须是 `Page` 的直接子节点**：用 `<template v-if>` 包一层会编译成 Fragment，
+    归位认不出，那个成员会被当自由内容挪进主体区（契约 §5 组 2）。
+14. **`Page.Header` 不传 `title` 时 `extra` 静默不渲染**：不传 `title` 是合法的「自定义页头出口」，
+    但此时右侧位没有意义 —— 要放右侧位就必须传 `title`（契约 §5 组 3）。