@manohub/kit 0.7.1 → 0.8.1

package/README.md

@@ -114,7 +114,7 @@ pnpm build
 ```
 
 类名命名空间表放本仓 `docs/kit-namespaces.md`（per-app 文件，格式见技能包的
-`kit-migrate/references/migration-playbook.md`）—— 原 `appkit-guardrails.config.json` 不再被读取。
+`manohub-kit-migrate/references/migration-playbook.md`）—— 原 `appkit-guardrails.config.json` 不再被读取。
 
 ### 6. 技能包落盘（AI 代理用）
 
@@ -147,9 +147,12 @@ pnpm exec kit install --dry-run  # 先看会写什么
 
 | 技能 | 什么时候用 |
 | --- | --- |
-| `kit` | 不确定该用哪个子技能、问骨架层总体规范、要接入步骤与升级口径 |
-| `kit-dev` | 写/改页面：选模板、选组件与 prop、样式纪律、收工前自检 |
-| `kit-migrate` | 存量应用改造：按契约分层盘点、划批次、逐文件替换、逐层收口 |
+| `manohub-kit` | 不确定该用哪个子技能、问骨架层总体规范、要接入步骤与升级口径 |
+| `manohub-kit-dev` | 写/改页面：选模板、选组件与 prop、样式纪律、收工前自检 |
+| `manohub-kit-migrate` | 存量应用改造：按契约分层盘点、划批次、逐文件替换、逐层收口 |
+
+技能目录名带包名前缀（旧名 `kit` / `kit-migrate` / `kit-dev` 已废弃）：从带旧名的版本升级时，
+先手工删掉技能目录下的这三个旧目录再重跑 `kit install`，否则新旧两份技能会同时在场。
 
 ## 来源
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manohub/kit",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "private": false,
   "type": "module",
   "description": "子应用入口编排层：createSubApp（作用域容器与宿主锚点、pinia/路由/vue-query 装配、宿主挂载协议）、i18n 单实例与语言探测，外加随包分发的接入契约（CONTRACT.md，五层闭集条款 + 自检清单）与三个 AI 技能包。本包**零样式产物**：设计令牌（值）在 @manohub/theme，组件（类与行为）在 @manohub/ui，两者由消费方直接引入。",

package/skills/README.md

@@ -1,78 +1,82 @@
-# @manohub/kit 技能包（随包分发）
-
-本目录是随 npm 包一起发布的 AI 代理技能包，供**消费方**（接入了本包的子应用工程）使用。
-
-契约条款的唯一事实源是包内 `CONTRACT.md`。技能只负责**按场景把代理导到正确的流程与查表入口**。
-
-## 技能里为什么不写条款
-
-`CONTRACT.md` 是唯一的合规判据，它有两条性质：
-
-1. **每条条款都是闭集** —— 白名单（如 L1-5 的属性白名单）或逐字清单（如 L3-1 的允许 import 源），
-   看一眼就能判定「符合 / 不符合」，不需要解释。
-2. **§7 配了一份自检清单** —— 全是能直接回答的问句，收工前逐条过一遍即可。
-
-所以技能里的**条款式描述一律算缺陷**：它必然与契约漂移，而契约才是唯一裁判。技能只写两件事 ——
-**「读契约第 X 节」** 与 **「过 §7 自检清单」**。
-
-## 三个技能
-
-| 技能 | 职责 | 可独立调用 |
-|---|---|---|
-| `kit` | 入口编排：识别意图 → 调 `kit-migrate` 或 `kit-dev`（另有「从零建新应用」导到接入 SOP）；承载跨场景硬约束 | 是（子技能也可直接调） |
-| `kit-migrate` | 存量应用改造到「`@manohub/ui` 组件 + `@manohub/kit` 骨架」（清理 `App*` 旧组件名、`.ak-*` 样式、直连底层组件库的写法）：按契约逐层盘点 → 划批次 → 逐文件替换 → 逐层收口 → 验收；支持**只迁一部分**（典型是「只迁页面骨架」） | 是 |
-| `kit-dev` | 按骨架层规范做日常页面开发：选模板 / 选组件与 prop / 守样式纪律 / 缺件处置 / 自检 | 是 |
-
-## 安装到消费方技能目录
-
-在消费方**工程根**执行（缺省落 `.codebuddy/skills/`）；`kit` 是本包的命令入口（`bin`），
-npm 消费方把 `pnpm exec` 换成 `npx`：
-
-```bash
-pnpm exec kit install
-
-pnpm exec kit install --also-claude   # 同时落 .claude/skills/
-pnpm exec kit install --target .x/skills
-pnpm exec kit install --dry-run       # 只预览不落盘
-```
-
-输出示例（每个技能都会报告内容有没有变）：
-
-```text
-[kit 技能安装]
-  源：…/node_modules/@manohub/kit/skills
-  目标：…/.codebuddy/skills
-    ….codebuddy/skills/kit —— 更新 2（共 3 个文件）
-    ….codebuddy/skills/kit-migrate —— 已是包内最新（内容无变化，共 3 个文件）
-  完成：技能目录已与包内内容对齐（包升级后重跑本命令即刷新）
-```
-
-安装器是幂等的：每次执行**先清理同名技能目录再整体复制**，所以包升级后重跑一次即刷新到新版内容。
-等价写法（老脚本/钩子里可用）：`node node_modules/@manohub/kit/skills/install.mjs`。
-它只管理 `kit` / `kit-migrate` / `kit-dev` 这三个目录，不触碰目标目录下的其它内容。
-每次执行都会报告**技能内容有没有变**（「更新 N / 新增 N」＝本次升级改了技能、已生效；
-「已是包内最新」＝本次升级没动技能包），这样消费方不必靠猜「我的技能是不是旧的」。
-
-## 维护约定（改本目录时遵守）
-
-- 引用规范一律写**消费方视角**路径：`node_modules/@manohub/kit/CONTRACT.md` §x.y。
-  禁止出现本机绝对路径、worktree 路径、仓库内相对路径（技能落盘后与包目录分离，这些路径会失效）。
-- **不复述条款**：不抄白名单、不抄件名清单、不抄 prop 词表、不抄值。
-  需要时写「读契约 §x.y」或指向读取路径（见契约 §0 权威源表）。凡本目录内出现判据式描述，视为缺陷。
-- `SKILL.md` 只放流程与硬约束（控制在 5k 词内）；查表内容（替换映射、场景配方）放各自的 `references/`，按需加载。
-- 三个技能的 `description` 触发条件互不重叠，否则代理会命中错的那个
-  （`kit` 只在「意图还没落到具体任务」时命中，具体任务交给两个子技能）。
-- 技能引用的 `references/` 文件必须真实存在，文件名改动要同步 `SKILL.md`
-  （已由 `verify-pack` 的 `checkSkillPack` 机械校验，跨技能引用 `../<skill>/references/…` 同样校验）。
-- 技能目录下的每个文件都必须真进 tarball（`references/` 漏发时「查表」会整体失效，也已机械校验）。
-- 技能引用的契约章节必须真实存在（改契约标题即需同步本目录，`verify-pack` 会校验章节号可解析）。
-- 技能与文档里的命令一律写**消费方命令** `pnpm exec kit install`（npm 注一句 `npx`）。
-- 本包**只有 `install` 一个子命令**（0.6.0 起 `kit lint` 及其四个校验子命令已下线）。
-  `bin/` 是工具脚本、没有自测，改后手工跑一次确认参数透传（如 `--dry-run`），
-  `verify-pack` 校验 `bin/kit.mjs` 随包分发。
-- 改动后跑门禁与打包校验（在仓库根）：
-
-```bash
-pnpm --filter @manohub/kit test:unit   # 入口编排契约单测
-pnpm release:check                         # build + verify-pack（含技能包结构/引用校验）
-```
+# @manohub/kit 技能包（随包分发）
+
+本目录是随 npm 包一起发布的 AI 代理技能包，供**消费方**（接入了本包的子应用工程）使用。
+
+契约条款的唯一事实源是包内 `CONTRACT.md`。技能只负责**按场景把代理导到正确的流程与查表入口**。
+
+## 技能里为什么不写条款
+
+`CONTRACT.md` 是唯一的合规判据，它有两条性质：
+
+1. **每条条款都是闭集** —— 白名单（如 L1-5 的属性白名单）或逐字清单（如 L3-1 的允许 import 源），
+   看一眼就能判定「符合 / 不符合」，不需要解释。
+2. **§7 配了一份自检清单** —— 全是能直接回答的问句，收工前逐条过一遍即可。
+
+所以技能里的**条款式描述一律算缺陷**：它必然与契约漂移，而契约才是唯一裁判。技能只写两件事 ——
+**「读契约第 X 节」** 与 **「过 §7 自检清单」**。
+
+## 三个技能
+
+| 技能 | 职责 | 可独立调用 |
+|---|---|---|
+| `manohub-kit` | 入口编排：识别意图 → 调 `manohub-kit-migrate` 或 `manohub-kit-dev`（另有「从零建新应用」导到接入 SOP）；承载跨场景硬约束 | 是（子技能也可直接调） |
+| `manohub-kit-migrate` | 存量应用改造到「`@manohub/ui` 组件 + `@manohub/kit` 骨架」（清理 `App*` 旧组件名、`.ak-*` 样式、直连底层组件库的写法）：按契约逐层盘点 → 划批次 → 逐文件替换 → 逐层收口 → 验收；支持**只迁一部分**（典型是「只迁页面骨架」） | 是 |
+| `manohub-kit-dev` | 按骨架层规范做日常页面开发：选模板 / 选组件与 prop / 守样式纪律 / 缺件处置 / 自检 | 是 |
+
+## 安装到消费方技能目录
+
+在消费方**工程根**执行（缺省落 `.codebuddy/skills/`）；`kit` 是本包的命令入口（`bin`），
+npm 消费方把 `pnpm exec` 换成 `npx`：
+
+```bash
+pnpm exec kit install
+
+pnpm exec kit install --also-claude   # 同时落 .claude/skills/
+pnpm exec kit install --target .x/skills
+pnpm exec kit install --dry-run       # 只预览不落盘
+```
+
+输出示例（每个技能都会报告内容有没有变）：
+
+```text
+[kit 技能安装]
+  源：…/node_modules/@manohub/kit/skills
+  目标：…/.codebuddy/skills
+    ….codebuddy/skills/manohub-kit —— 更新 2（共 3 个文件）
+    ….codebuddy/skills/manohub-kit-migrate —— 已是包内最新（内容无变化，共 3 个文件）
+  完成：技能目录已与包内内容对齐（包升级后重跑本命令即刷新）
+```
+
+安装器是幂等的：每次执行**先清理同名技能目录再整体复制**，所以包升级后重跑一次即刷新到新版内容。
+等价写法（老脚本/钩子里可用）：`node node_modules/@manohub/kit/skills/install.mjs`。
+它只管理 `manohub-kit` / `manohub-kit-migrate` / `manohub-kit-dev` 这三个目录，不触碰目标目录下的其它内容。
+
+> **技能目录名带包名前缀**：旧名 `kit` / `kit-migrate` / `kit-dev` 已废弃，安装器**不再管理**它们 ——
+> 从带旧名的版本升级时，须先手工删掉技能目录下的这三个旧目录再重跑 `kit install`，
+> 否则新旧两份技能会同时在场（同名触发条件撞车，代理可能命中旧的那份）。
+每次执行都会报告**技能内容有没有变**（「更新 N / 新增 N」＝本次升级改了技能、已生效；
+「已是包内最新」＝本次升级没动技能包），这样消费方不必靠猜「我的技能是不是旧的」。
+
+## 维护约定（改本目录时遵守）
+
+- 引用规范一律写**消费方视角**路径：`node_modules/@manohub/kit/CONTRACT.md` §x.y。
+  禁止出现本机绝对路径、worktree 路径、仓库内相对路径（技能落盘后与包目录分离，这些路径会失效）。
+- **不复述条款**：不抄白名单、不抄件名清单、不抄 prop 词表、不抄值。
+  需要时写「读契约 §x.y」或指向读取路径（见契约 §0 权威源表）。凡本目录内出现判据式描述，视为缺陷。
+- `SKILL.md` 只放流程与硬约束（控制在 5k 词内）；查表内容（替换映射、场景配方）放各自的 `references/`，按需加载。
+- 三个技能的 `description` 触发条件互不重叠，否则代理会命中错的那个
+  （`kit` 只在「意图还没落到具体任务」时命中，具体任务交给两个子技能）。
+- 技能引用的 `references/` 文件必须真实存在，文件名改动要同步 `SKILL.md`
+  （已由 `verify-pack` 的 `checkSkillPack` 机械校验，跨技能引用 `../<skill>/references/…` 同样校验）。
+- 技能目录下的每个文件都必须真进 tarball（`references/` 漏发时「查表」会整体失效，也已机械校验）。
+- 技能引用的契约章节必须真实存在（改契约标题即需同步本目录，`verify-pack` 会校验章节号可解析）。
+- 技能与文档里的命令一律写**消费方命令** `pnpm exec kit install`（npm 注一句 `npx`）。
+- 本包**只有 `install` 一个子命令**（0.6.0 起 `kit lint` 及其四个校验子命令已下线）。
+  `bin/` 是工具脚本、没有自测，改后手工跑一次确认参数透传（如 `--dry-run`），
+  `verify-pack` 校验 `bin/kit.mjs` 随包分发。
+- 改动后跑门禁与打包校验（在仓库根）：
+
+```bash
+pnpm --filter @manohub/kit test:unit   # 入口编排契约单测
+pnpm release:check                         # build + verify-pack（含技能包结构/引用校验）
+```

package/skills/install.mjs

@@ -25,7 +25,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:pat
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
 /** 本技能包管理的技能目录名（白名单：只有这些名字允许被创建或清理） */
-export const SKILL_NAMES = ['kit', 'kit-migrate', 'kit-dev']
+export const SKILL_NAMES = ['manohub-kit', 'manohub-kit-migrate', 'manohub-kit-dev']
 
 /** 缺省的技能目录（相对消费方工程根） */
 export const TARGET_CODEXBUDDY = ['.codebuddy', 'skills']

package/skills/{kit → manohub-kit}/SKILL.md

@@ -1,85 +1,85 @@
----
-name: kit
-version: 1.0.0
-description: 子应用骨架层 @manohub/kit 的入口技能：识别意图并编排到 kit-migrate（存量应用改造）或 kit-dev（日常页面开发），并承载两个子技能共用的全局硬约束。触发条件：用户提到 kit / 骨架层 / 接入契约本身、询问该怎么接入或改造但尚未落到具体页面或文件、不确定该用哪个 kit 技能、或需要接入步骤/升级口径等跨场景事项时使用；一旦意图明确落到「迁移存量应用」或「写/改页面」，由对应子技能承接。
----
-
-# kit：骨架层入口编排
-
-把「用骨架层做事」收敛到一条路径：先判意图，再交给对应子技能。
-本技能不设计页面、不改代码，只做路由与硬约束。
-
-## 一、先判意图
-
-| 用户意图信号 | 走向 |
-|---|---|
-| 应用还没接本包；或页面里还有 `App*` 组件名 / `.ak-*` 样式 / 直连底层组件库；或出现「迁移」「改造」「接入」「违规盘点」「收口」 | `Skill('kit-migrate')` |
-| 应用已接入，要新增或修改页面、组件；或要求「按规范写」「用 Page / Panel / Table…」 | `Skill('kit-dev')` |
-| 两者交织（边接入边改页面） | 先跑 `kit-migrate` 的接入阶段（契约已落到应用文档），再进 `kit-dev` |
-| 应用还不存在，要从零建一个子应用 | 按 `references/adoption.md` «9. 新应用从零搭建» 走，建成后按上面的表继续 |
-| 问的是组件本身的 prop / 用法（不是页面结构） | 读 `node_modules/@manohub/ui/README.md` 与类型声明；本包的契约只管**页面怎么搭** |
-| 与骨架层无关（纯后端问题、非 Vue 前端工程） | 不使用本技能 |
-
-意图不明时先问一句「是要把存量页面改造过来，还是新写页面」，不要猜。
-
-## 二、先读契约（两个子技能都适用）
-
-**合规判据只有一个地方**：`node_modules/@manohub/kit/CONTRACT.md`。每条条款都是闭集，
-§7 是配套的自检清单。**本技能与两个子技能都不复述条款** —— 需要判据时读契约，
-不要凭记忆或凭本文件的措辞判断。
-
-按顺序读这五节，一次读完，别边写边查：
-
-| # | 去哪读 | 为什么它要排这么前 |
-|---|---|---|
-| 1 | **§0 权威源表** | 值 / 件名 / 成员 / 词表 / 图标名的读取路径全在这里 —— 写任何东西之前先读它，否则你会去抄一份会过期的副本 |
-| 2 | **§2 L0 入口与作用域** | 漏了它，下面三层同时失效（典型症状：组件有框有距，颜色却是浏览器默认灰蓝）；**这一层不可豁免** |
-| 3 | **§3 L1 值** | 样式纪律的全部判据；属性白名单是闭集，逐字照用 |
-| 4 | **§5 L2 结构** | 骨架怎么用（20 条）：页头、成员归位、两级滚动、操作位、分页都在这里 |
-| 5 | **§6 L3 件与词表** | 件 / 成员 / prop 的用法；**件名与成员以 `.d.ts` 为准，不要抄** |
-
-收工前过 **§7 自检清单**（24 问，五层各一组）。答不上来的那一条就是你要回去读的地方。
-
-**冲突时的优先级**：包内 `CONTRACT.md` > `@manohub/ui` 的 README 与类型声明里的 `@example`
-> 消费仓 `AGENTS.md` > 其它文档。发现 `@example` 与契约冲突，按契约写，并把该 `@example` 当缺陷处理。
-
-> 本包 **0.6.0 起不再发布消费侧机器规则**（原先的三条护栏已下线）。合规靠
-> 「契约条款 + §7 自检清单」在写作与评审时把关，不再有自动拦断。
-
-## 三、固定命令（在应用包根执行）
-
-```bash
-pnpm exec kit install         # 把技能包刷到本地技能目录（幂等，包升级后重跑）
-pnpm exec vue-tsc --noEmit       # 类型检查
-pnpm build                       # 生产构建
-```
-
-- `kit` 是本包的命令入口（`package.json` 的 `bin`）；npm 消费方把 `pnpm exec` 换成 `npx`。
-  本包**只有 `install` 一个子命令**。
-- 技能包内容更新后重新落盘（幂等，包升级后重跑即刷新）：
-
-```bash
-pnpm exec kit install         # 等价：node node_modules/@manohub/kit/skills/install.mjs
-```
-
-## 四、失败处理
-
-| 现象 | 处理 |
-|---|---|
-| 找不到 `node_modules/@manohub/kit` | 在应用包根执行 `pnpm add @manohub/kit @manohub/ui @manohub/theme`（三个包在 npm 官方仓公开） |
-| 页面报 `App* is not exported` | 0.6.0 已移除 `App*` 组件名 —— 走 `kit-migrate` 按对照表替换 |
-| 命令式提示样式全丢 | 提示没落回应用容器：确认入口走的是 `createSubApp`（它无条件写 `data-manohub-ui`），别自己手写 `createApp` |
-| 组件有框有距但颜色全是浏览器默认灰蓝 | 容器缺 `data-manohub-ui` 属性（自建容器的场景），或漏引 `@manohub/theme/default.css` |
-| 调子技能报「技能不存在」 | 技能未安装或未刷新，跑上面的 `pnpm exec kit install` |
-| 终端里敲 `kit` 报 command not found | 用 `pnpm exec kit …`（或 npm 的 `npx kit …`） |
-| 类型检查报「无法解析 `*.css`」 | 消费方 tsconfig 的 `types` 需包含 `vite/client`，见 `references/adoption.md` |
-| 想找「某个写法合不合规」的机器判据 | 没有了 —— 读 `CONTRACT.md` 对应层 + §7 自检清单；确需全仓盘点时按 `kit-migrate` 的条款级盘点流程人工过 |
-
-## 五、参考
-
-- `references/adoption.md`：接入 SOP（安装、样式三行、入口、类型配置、验收清单、故障对照、**新应用从零搭建**、升级口径）
-- `references/contract-index.md`：契约速查索引（按主题定位 `CONTRACT.md` 章节，不复制条款）
-- 迁移查表：`../kit-migrate/references/migration-map.md`
-- 开发配方：`../kit-dev/references/page-recipes.md`
-- 组件 API：`node_modules/@manohub/ui/README.md`
-- 自检清单：`node_modules/@manohub/kit/CONTRACT.md` §7
+---
+name: manohub-kit
+version: 1.0.0
+description: 子应用骨架层 @manohub/kit 的入口技能：识别意图并编排到 manohub-kit-migrate（存量应用改造）或 manohub-kit-dev（日常页面开发），并承载两个子技能共用的全局硬约束。触发条件：用户提到 kit / manohub-kit / 骨架层 / 接入契约本身、询问该怎么接入或改造但尚未落到具体页面或文件、不确定该用哪个 manohub-kit 技能、或需要接入步骤/升级口径等跨场景事项时使用；一旦意图明确落到「迁移存量应用」或「写/改页面」，由对应子技能承接。
+---
+
+# manohub-kit：骨架层入口编排
+
+把「用骨架层做事」收敛到一条路径：先判意图，再交给对应子技能。
+本技能不设计页面、不改代码，只做路由与硬约束。
+
+## 一、先判意图
+
+| 用户意图信号 | 走向 |
+|---|---|
+| 应用还没接本包；或页面里还有 `App*` 组件名 / `.ak-*` 样式 / 直连底层组件库；或出现「迁移」「改造」「接入」「违规盘点」「收口」 | `Skill('manohub-kit-migrate')` |
+| 应用已接入，要新增或修改页面、组件；或要求「按规范写」「用 Page / Panel / Table…」 | `Skill('manohub-kit-dev')` |
+| 两者交织（边接入边改页面） | 先跑 `manohub-kit-migrate` 的接入阶段（契约已落到应用文档），再进 `manohub-kit-dev` |
+| 应用还不存在，要从零建一个子应用 | 按 `references/adoption.md` «9. 新应用从零搭建» 走，建成后按上面的表继续 |
+| 问的是组件本身的 prop / 用法（不是页面结构） | 读 `node_modules/@manohub/ui/README.md` 与类型声明；本包的契约只管**页面怎么搭** |
+| 与骨架层无关（纯后端问题、非 Vue 前端工程） | 不使用本技能 |
+
+意图不明时先问一句「是要把存量页面改造过来，还是新写页面」，不要猜。
+
+## 二、先读契约（两个子技能都适用）
+
+**合规判据只有一个地方**：`node_modules/@manohub/kit/CONTRACT.md`。每条条款都是闭集，
+§7 是配套的自检清单。**本技能与两个子技能都不复述条款** —— 需要判据时读契约，
+不要凭记忆或凭本文件的措辞判断。
+
+按顺序读这五节，一次读完，别边写边查：
+
+| # | 去哪读 | 为什么它要排这么前 |
+|---|---|---|
+| 1 | **§0 权威源表** | 值 / 件名 / 成员 / 词表 / 图标名的读取路径全在这里 —— 写任何东西之前先读它，否则你会去抄一份会过期的副本 |
+| 2 | **§2 L0 入口与作用域** | 漏了它，下面三层同时失效（典型症状：组件有框有距，颜色却是浏览器默认灰蓝）；**这一层不可豁免** |
+| 3 | **§3 L1 值** | 样式纪律的全部判据；属性白名单是闭集，逐字照用 |
+| 4 | **§5 L2 结构** | 骨架怎么用（20 条）：页头、成员归位、两级滚动、操作位、分页都在这里 |
+| 5 | **§6 L3 件与词表** | 件 / 成员 / prop 的用法；**件名与成员以 `.d.ts` 为准，不要抄** |
+
+收工前过 **§7 自检清单**（24 问，五层各一组）。答不上来的那一条就是你要回去读的地方。
+
+**冲突时的优先级**：包内 `CONTRACT.md` > `@manohub/ui` 的 README 与类型声明里的 `@example`
+> 消费仓 `AGENTS.md` > 其它文档。发现 `@example` 与契约冲突，按契约写，并把该 `@example` 当缺陷处理。
+
+> 本包 **0.6.0 起不再发布消费侧机器规则**（原先的三条护栏已下线）。合规靠
+> 「契约条款 + §7 自检清单」在写作与评审时把关，不再有自动拦断。
+
+## 三、固定命令（在应用包根执行）
+
+```bash
+pnpm exec kit install         # 把技能包刷到本地技能目录（幂等，包升级后重跑）
+pnpm exec vue-tsc --noEmit       # 类型检查
+pnpm build                       # 生产构建
+```
+
+- `kit` 是本包的命令入口（`package.json` 的 `bin`）；npm 消费方把 `pnpm exec` 换成 `npx`。
+  本包**只有 `install` 一个子命令**。
+- 技能包内容更新后重新落盘（幂等，包升级后重跑即刷新）：
+
+```bash
+pnpm exec kit install         # 等价：node node_modules/@manohub/kit/skills/install.mjs
+```
+
+## 四、失败处理
+
+| 现象 | 处理 |
+|---|---|
+| 找不到 `node_modules/@manohub/kit` | 在应用包根执行 `pnpm add @manohub/kit @manohub/ui @manohub/theme`（三个包在 npm 官方仓公开） |
+| 页面报 `App* is not exported` | 0.6.0 已移除 `App*` 组件名 —— 走 `manohub-kit-migrate` 按对照表替换 |
+| 命令式提示样式全丢 | 提示没落回应用容器：确认入口走的是 `createSubApp`（它无条件写 `data-manohub-ui`），别自己手写 `createApp` |
+| 组件有框有距但颜色全是浏览器默认灰蓝 | 容器缺 `data-manohub-ui` 属性（自建容器的场景），或漏引 `@manohub/theme/default.css` |
+| 调子技能报「技能不存在」 | 技能未安装或未刷新，跑上面的 `pnpm exec kit install` |
+| 终端里敲 `kit` 报 command not found | 用 `pnpm exec kit …`（或 npm 的 `npx kit …`） |
+| 类型检查报「无法解析 `*.css`」 | 消费方 tsconfig 的 `types` 需包含 `vite/client`，见 `references/adoption.md` |
+| 想找「某个写法合不合规」的机器判据 | 没有了 —— 读 `CONTRACT.md` 对应层 + §7 自检清单；确需全仓盘点时按 `manohub-kit-migrate` 的条款级盘点流程人工过 |
+
+## 五、参考
+
+- `references/adoption.md`：接入 SOP（安装、样式三行、入口、类型配置、验收清单、故障对照、**新应用从零搭建**、升级口径）
+- `references/contract-index.md`：契约速查索引（按主题定位 `CONTRACT.md` 章节，不复制条款）
+- 迁移查表：`../manohub-kit-migrate/references/migration-map.md`
+- 开发配方：`../manohub-kit-dev/references/page-recipes.md`
+- 组件 API：`node_modules/@manohub/ui/README.md`
+- 自检清单：`node_modules/@manohub/kit/CONTRACT.md` §7