docs(customization): 按实况重画 customization/index 的 src/ 目录树并纳入 docs-drift 守卫 (#988)

.changeset/docs-customization-index-src-tree.md

@@ -0,0 +1,26 @@
+---
+'hotcrm': patch
+---
+
+Redraw the customization landing page's `src/` tree from the real repository, and
+put the page under the docs-drift tree guard.
+
+`content/docs/customization/index.mdx` (and both Chinese locales) is the twin of
+the developer page fixed in #984: it drew an `agents/` branch in the `src/` tree
+and listed `*.agent.ts` in the file-suffix table, both of which went away with
+the two app-owned copilots. HotCRM authors skills and the agent comes from the
+platform, so a reader following this page was being pointed at a directory and a
+file suffix that no longer exist.
+
+The tree was reconciled directory by directory rather than only having the dead
+branch cut out, so it now lists all eighteen directories `src/` actually
+contains: `hooks/`, `datasets/`, `mappings/`, `docs/` and `interfaces/` were
+real and missing from it, and every branch states what it actually holds. The
+"What you can build" table billed the AI skills page as "Copilot skills and
+agent wiring"; the wiring it referred to is gone, and exporting from the skills
+barrel is the whole of it.
+
+The page then joins `PRODUCT_TREE_DOCS` in `test/docs-drift.test.ts`, the guard
+#984 built for exactly this defect class and left a note in pointing at this
+page. Membership covers both of that guard's axes at once, since the tree-diagram
+list is derived from the product list.

content/docs/customization/index.mdx

@@ -12,7 +12,7 @@ This section is for developers and technical implementers extending HotCRM with
 | Area | What it covers |
 | --- | --- |
 | [Extending objects](/docs/customization/extending-objects) | Fields, objects, hooks, flows, validation, sharing |
-| [AI skills](/docs/customization/ai-skills) | Copilot skills and agent wiring |
+| [AI skills](/docs/customization/ai-skills) | Skills for the platform assistant, and the barrel that registers them |
 | [UI extensions](/docs/customization/ui-extensions) | Pages, views, dashboards, actions |
 | [Testing and CI](/docs/customization/testing-and-ci) | Metadata validation and automated checks |
 
@@ -22,22 +22,28 @@ HotCRM is a single ObjectStack app. Add or modify metadata under `src/`, then ex
 
 ```text
 src/
-├── objects/        # data model and object hooks
+├── objects/        # *.object.ts schemas and *.hook.ts lifecycle logic
+├── hooks/          # barrel that hands the object hooks to the stack
 ├── actions/        # UI actions and executable action bodies
 ├── flows/          # automation
-├── agents/         # AI agents
 ├── skills/         # AI skills
 ├── apps/
 ├── views/
 ├── pages/
 ├── dashboards/
 ├── reports/
+├── datasets/       # dimensions and measures the dashboards and reports query
+├── mappings/       # import column-to-field projections
 ├── profiles/
 ├── sharing/
 ├── translations/
-└── data/
+├── data/           # seed data
+├── docs/           # package docs stating the business rules the flows implement
+└── interfaces/     # shared types (an empty barrel today)
 ```
 
+HotCRM authors skills, not agents: the two app-owned copilots and the directory that held them were retired, and AI capability now comes from the platform assistant every ObjectStack environment provides. Exporting a skill from `src/skills/index.ts` is the whole wiring step. See [AI Skills](/docs/customization/ai-skills).
+
 ## File suffix protocol
 
 | Suffix | What it defines |
@@ -47,7 +53,6 @@ src/
 | `*.actions.ts` | UI actions and executable actions |
 | `*.flow.ts` | Automation |
 | `*.skill.ts` | AI Copilot skill |
-| `*.agent.ts` | AI agent |
 | `*.page.ts` | UI page |
 | `*.view.ts` | List or kanban view |
 | `*.dashboard.ts` | Dashboard |

content/docs/customization/index.zh-Hans.mdx

@@ -12,7 +12,7 @@ description: 用 ObjectStack 元数据、动作、流程、AI skills 和 UI 定
 | 领域 | 内容 |
 | --- | --- |
 | [扩展对象](/zh-Hans/docs/customization/extending-objects) | 字段、对象、hooks、流程、校验、共享 |
-| [AI skills](/zh-Hans/docs/customization/ai-skills) | Copilot skills 和 agent 接线 |
+| [AI skills](/zh-Hans/docs/customization/ai-skills) | 面向平台助手的 skills，以及注册它们的 barrel |
 | [UI 扩展](/zh-Hans/docs/customization/ui-extensions) | 页面、视图、仪表盘、动作 |
 | [测试与 CI](/zh-Hans/docs/customization/testing-and-ci) | 元数据校验和自动化检查 |
 
@@ -22,22 +22,28 @@ HotCRM 是一个单体 ObjectStack 应用。请在 `src/` 下新增或修改元
 
 ```text
 src/
-├── objects/        # 数据模型和对象 hooks
+├── objects/        # *.object.ts 模型和 *.hook.ts 生命周期逻辑
+├── hooks/          # 把对象 hooks 汇总交给 stack 的 barrel
 ├── actions/        # UI 动作和可执行动作体
 ├── flows/          # 自动化
-├── agents/         # AI agents
 ├── skills/         # AI skills
 ├── apps/
 ├── views/
 ├── pages/
 ├── dashboards/
 ├── reports/
+├── datasets/       # 仪表盘和报表查询的维度与度量
+├── mappings/       # 数据导入的列到字段映射
 ├── profiles/
 ├── sharing/
 ├── translations/
-└── data/
+├── data/           # 种子数据
+├── docs/           # 陈述流程所实现业务规则的应用文档
+└── interfaces/     # 共享类型（目前是空 barrel）
 ```
 
+HotCRM 只定义 skills，不定义 agent：应用自带的两个 copilot 及其所在目录已被移除，AI 能力来自每个 ObjectStack 环境都提供的平台助手。把 skill 从 `src/skills/index.ts` 导出就是全部的接线工作。参见 [AI Skills](/zh-Hans/docs/customization/ai-skills)。
+
 ## 文件后缀协议
 
 | 后缀 | 定义 |
@@ -47,7 +53,6 @@ src/
 | `*.actions.ts` | UI 动作和可执行动作 |
 | `*.flow.ts` | 自动化 |
 | `*.skill.ts` | AI Copilot skill |
-| `*.agent.ts` | AI agent |
 | `*.page.ts` | UI 页面 |
 | `*.view.ts` | 列表或看板视图 |
 | `*.dashboard.ts` | 仪表盘 |

content/docs/customization/index.zh-Hant.mdx

@@ -12,7 +12,7 @@ description: 用 ObjectStack 中繼資料、動作、流程、AI skills 和 UI 
 | 領域 | 內容 |
 | --- | --- |
 | [擴展物件](/zh-Hant/docs/customization/extending-objects) | 欄位、物件、hooks、流程、校驗、共享 |
-| [AI skills](/zh-Hant/docs/customization/ai-skills) | Copilot skills 和 agent 接線 |
+| [AI skills](/zh-Hant/docs/customization/ai-skills) | 面向平台助手的 skills，以及註冊它們的 barrel |
 | [UI 擴展](/zh-Hant/docs/customization/ui-extensions) | 頁面、視圖、儀表板、動作 |
 | [測試與 CI](/zh-Hant/docs/customization/testing-and-ci) | 中繼資料校驗和自動化檢查 |
 
@@ -22,22 +22,28 @@ HotCRM 是一個單體 ObjectStack 應用。請在 `src/` 下新增或修改中
 
 ```text
 src/
-├── objects/        # 資料模型和物件 hooks
+├── objects/        # *.object.ts 模型和 *.hook.ts 生命週期邏輯
+├── hooks/          # 把物件 hooks 彙總交給 stack 的 barrel
 ├── actions/        # UI 動作和可執行動作體
 ├── flows/          # 自動化
-├── agents/         # AI agents
 ├── skills/         # AI skills
 ├── apps/
 ├── views/
 ├── pages/
 ├── dashboards/
 ├── reports/
+├── datasets/       # 儀表板和報表查詢的維度與度量
+├── mappings/       # 資料匯入的欄位對應
 ├── profiles/
 ├── sharing/
 ├── translations/
-└── data/
+├── data/           # 種子資料
+├── docs/           # 陳述流程所實作業務規則的應用文件
+└── interfaces/     # 共享型別（目前是空 barrel）
 ```
 
+HotCRM 只定義 skills，不定義 agent：應用自帶的兩個 copilot 及其所在目錄已被移除，AI 能力來自每個 ObjectStack 環境都提供的平台助手。把 skill 從 `src/skills/index.ts` 匯出就是全部的接線工作。參見 [AI Skills](/zh-Hant/docs/customization/ai-skills)。
+
 ## 檔案後綴協議
 
 | 後綴 | 定義 |
@@ -47,7 +53,6 @@ src/
 | `*.actions.ts` | UI 動作和可執行動作 |
 | `*.flow.ts` | 自動化 |
 | `*.skill.ts` | AI Copilot skill |
-| `*.agent.ts` | AI agent |
 | `*.page.ts` | UI 頁面 |
 | `*.view.ts` | 清單或看板視圖 |
 | `*.dashboard.ts` | 儀表板 |

test/docs-drift.test.ts

@@ -292,14 +292,26 @@ describe('maintainer docs do not point at directories that no longer exist', ()
  * on a page is a pointer is an editorial fact about that page, so pages opt in
  * here one at a time.
  *
- * `customization/index.{mdx,zh-Hans,zh-Hant}` draws the same tree and still
- * carries the retired `agents/` entry plus a `*.agent.ts` row (#988); its three
- * locales join both lists below with that fix.
+ * `customization/index.{mdx,zh-Hans,zh-Hant}` drew the same tree with the same
+ * retired `agents/` entry and `*.agent.ts` row; #988 redrew all three and they
+ * joined here, as the note left above by #984 anticipated.
+ *
+ * Membership costs a page something, and the customization page had to pay it:
+ * the inline check below refuses to pass vacuously, and that page named no
+ * `src/<dir>/` inline at all — its one candidate, the golden rule "export from
+ * the relevant `src/**\/index.ts`", is a glob and matches nothing. What made it
+ * eligible is the barrel sentence #988 added under the tree, which names
+ * `src/skills/index.ts` outright. A page that only DRAWS a tree belongs in
+ * TREE_DIAGRAM_DOCS; being here additionally asserts it points into `src/` in
+ * prose.
  */
 const PRODUCT_TREE_DOCS = [
   'content/docs/getting-started/for-developers.mdx',
   'content/docs/getting-started/for-developers.zh-Hans.mdx',
   'content/docs/getting-started/for-developers.zh-Hant.mdx',
+  'content/docs/customization/index.mdx',
+  'content/docs/customization/index.zh-Hans.mdx',
+  'content/docs/customization/index.zh-Hant.mdx',
 ];
 
 /** Every doc that DRAWS a `src/` tree — the form axis, maintainer and product alike. */