docs: align README/copilot pages with the shipped skills-only surface (#589)

.changeset/docs-align-retired-agents.md

@@ -0,0 +1,34 @@
+---
+'hotcrm': patch
+---
+
+Docs alignment: correct the metadata counts in the README, rewrite the AI copilot
+pages as skill docs, and disclaim the archived Salesforce comparison.
+
+The README advertised "2 AI agents (sales-copilot, service-copilot), 20 flows,
+5 sharing rules" three paragraphs above a repository-layout block that correctly
+called the AI surface skills-only with 23 flows. The real numbers, taken from
+`objectstack.config.ts`, are **0 app-owned agents, 6 AI skills, 23 flows and 9
+sharing rules**; both README passages now say that, and the `8 datasets` count was
+added so the two lists agree.
+
+The published `ai-copilot/sales-copilot` and `ai-copilot/service-copilot` pages (en,
+zh-Hans, zh-Hant) still described two AI personas that were retired in #512 — "it
+lives in the right-side chat panel and as inline buttons" for capabilities that ship
+today as six skills on the platform `ask` assistant. They are rewritten as skill docs
+at their existing URLs, with the activation rules taken from each skill's real
+`triggerConditions` and the write paths named as the actual HotCRM actions
+(`convert_lead`, `schedule_followup`, `escalate_case`, `close_case`) the skills call.
+The AI Copilot index, the Skills page, the glossary's "Agent (AI)" entry, the
+customization guide (which told developers to edit a long-deleted
+`src/agents/sales-copilot.agent.ts`) and every inbound link label were updated to
+match.
+
+`docs/archive/2026-02/SALESFORCE_FEATURE_COMPARISON.md` now opens with a
+retired-architecture banner. It describes a ~148-object, 13-package product and marks
+`sla_policy`, `queue`, `email_to_case` and `pricebook` as implemented — none exist —
+so its "~95% Salesforce parity" headline was actively misleading anyone evaluating the
+repo. Finally `docs/ARCHITECTURE.md` was corrected: the diagram no longer draws the
+deleted `src/agents` or the never-created `src/cubes`, the manifest table reads
+`2.2.2` instead of `1.0.5`, and `requires` no longer lists the `ai` capability that
+was removed in 2.2.0.

README.md

@@ -5,7 +5,7 @@
 # HotCRM
 
 > **The reference app for AI-written enterprise software.** A complete CRM —
-> 15 objects, 20 flows, 4 dashboards, 2 AI copilots, 4 languages — is roughly
+> 15 objects, 23 flows, 4 dashboards, 6 AI skills, 4 languages — is roughly
 > **170k tokens** of typed [ObjectStack](https://github.com/objectstack-ai/objectstack)
 > metadata (~18,000 lines): the entire enterprise CRM fits in a single agent
 > context window, so an AI can hold it whole, reason about it, and refactor it.
@@ -57,7 +57,7 @@ HotCRM is a complete, opinionated CRM built as the **first official application*
 | `crm_product` | | | |
 | `crm_forecast` | | | |
 
-Plus **2 AI agents** (sales-copilot, service-copilot), **4 dashboards**, **20 flows**, **13 actions**, **6 AI skills**, **4 language bundles** (en, zh-CN, es-ES, ja-JP), **6 permission profiles**, **12 positions**, and **5 sharing rules**.
+Plus **6 AI skills** (a skills-only surface — HotCRM defines no agents of its own; the skills attach to the platform `ask` assistant), **4 dashboards**, **23 flows**, **13 actions**, **8 datasets**, **4 language bundles** (en, zh-CN, es-ES, ja-JP), **6 permission profiles**, **12 positions**, and **9 sharing rules**.
 
 > **Business reader?** The ObjectStack docs tour every one of these capabilities in plain business language — [What Can It Do?](https://objectstack.ai/docs/capabilities) — with HotCRM as the running example on every page.
 

content/docs/ai-copilot/index.mdx

@@ -5,47 +5,58 @@ description: The AI assistant embedded throughout HotCRM — what it can do, whe
 
 # AI Copilot
 
-HotCRM is **AI-native** — the assistant is built in, not bolted on. Two specialised copilots ship out of the box:
+HotCRM is **AI-native** — the assistant is built in, not bolted on. But the assistant
+itself is not something HotCRM ships: it is the **platform assistant** (`ask`) that
+every ObjectStack environment already provides. What HotCRM contributes is **six
+skills** that teach that assistant your CRM.
 
-- The **Sales Copilot** helps reps qualify leads, draft emails, forecast revenue, and get a 360° view of accounts.
-- The **Service Copilot** helps agents triage cases, see the full customer history, and draft customer responses.
+> **No app-owned agents.** HotCRM used to define two agents of its own — a "Sales
+> Copilot" and a "Service Copilot". They were retired, and their capability moved into
+> skills that attach to the platform assistant. Everything on this page still works;
+> only the wiring changed.
 
-Both run on top of your CRM data — they read from the same objects you see in the UI, and they know your products, knowledge bases, and process rules.
+The six skills read from the same objects you see in the UI, and they know your
+products, knowledge bases, and process rules.
 
 ## Where you'll find it
 
-- 🪄 **Copilot panel** — a chat panel that opens from the right edge of every page.
-- ⚡ **Inline actions** — buttons like *"Qualify this lead"*, *"Draft reply"*, *"Summarize case"* on record detail pages.
-- 📋 **Suggestions** — automatic insights in dashboards (*"3 deals are at risk this week"*).
+- 🪄 **Assistant panel** — the chat panel the platform opens from the right edge of every page.
+- 🎯 **Context activation** — skills declare the record they belong to, so opening a lead and asking *"is this worth a call?"* runs Lead Qualification without you naming it.
+- 📈 **Dashboard questions** — the forecasting skill also activates on dashboards, so you can ask *"what's at risk this week?"* where the numbers already are.
 
 ## How it works (in plain terms)
 
-The Copilot has three ingredients:
+The assistant has three ingredients:
 
 1. **Skills** — bite-sized abilities like *Draft an email*, *Qualify this lead*, *Triage this case*. See [Skills](/docs/ai-copilot/skills).
 2. **Knowledge bases** — searchable libraries of product info, sales playbooks, support articles, and competitive intel. See [Knowledge Bases](/docs/ai-copilot/knowledge-bases).
-3. **Your live CRM data** — the Copilot reads from the same accounts, contacts, opportunities, and cases you do, respecting the same sharing rules.
+3. **Your live CRM data** — the assistant reads from the same accounts, contacts, opportunities, and cases you do, respecting the same sharing rules.
 
-When you ask a question, the Copilot picks the right skill, pulls relevant knowledge, and combines it with your CRM data to produce a grounded answer — with citations back to the source records and articles.
+When you ask a question, the assistant picks the right skill, pulls relevant
+knowledge, and combines it with your CRM data to produce a grounded answer — with
+citations back to the source records and articles.
 
 ## What it won't do
 
 - ❌ See records you can't see — it respects sharing and field-level security.
 - ❌ Take actions without your confirmation — drafted emails and updates are previewed first.
 - ❌ Fabricate data — every claim is traceable to a record or knowledge source.
+- ❌ Reach for tools of its own — skills declare no bespoke tools, so every write goes through a real HotCRM action with the same permission checks as the button.
 
-## Two flavours
+## Two groupings of skills
 
-| Copilot | Audience | Built-in skills |
-| --- | --- | --- |
-| [**Sales Copilot**](/docs/ai-copilot/sales-copilot) | Sales reps, sales managers | Lead qualification, email drafting, revenue forecasting, 360° customer view |
-| [**Service Copilot**](/docs/ai-copilot/service-copilot) | Service agents, support managers | Case triage, 360° customer view, email drafting |
+The six skills are documented in two role-shaped groups. This is a documentation
+convenience, not a runtime boundary — one assistant runs all six, and it will use a
+"sales" skill on a service question whenever that is the right answer.
 
-Both copilots can call each other's skills when relevant — for example, the Service Copilot can use the Sales Copilot's *Customer 360°* skill to show what the customer has bought.
+| Group | Audience | Skills |
+| --- | --- | --- |
+| [**Sales Skills**](/docs/ai-copilot/sales-copilot) | Sales reps, sales managers | Live Data, Lead Qualification, Email Drafting, Revenue Forecasting, Customer 360° |
+| [**Service Skills**](/docs/ai-copilot/service-copilot) | Service agents, support managers | Live Data, Case Triage, Customer 360°, Email Drafting |
 
 ## Start here
 
-- [Sales Copilot](/docs/ai-copilot/sales-copilot) — what reps and managers can do.
-- [Service Copilot](/docs/ai-copilot/service-copilot) — what agents can do.
+- [Sales Skills](/docs/ai-copilot/sales-copilot) — what reps and managers can do.
+- [Service Skills](/docs/ai-copilot/service-copilot) — what agents can do.
 - [Skills](/docs/ai-copilot/skills) — the full skill library.
-- [Knowledge Bases](/docs/ai-copilot/knowledge-bases) — the RAG indexes the Copilot reads from.
+- [Knowledge Bases](/docs/ai-copilot/knowledge-bases) — the RAG indexes the assistant reads from.

content/docs/ai-copilot/index.zh-Hans.mdx

@@ -5,47 +5,53 @@ description: 嵌入 HotCRM 各处的 AI 助手——它能做什么、在哪里
 
 # AI Copilot
 
-HotCRM 是 **AI 原生**的——助手是内置的，而非外挂的。开箱即用地提供两个专门的 Copilot：
+HotCRM 是 **AI 原生**的——助手是内置的，而非外挂的。但助手本身并非由 HotCRM 提供：它
+是每个 ObjectStack 环境已经自带的 **平台助手**（`ask`）。HotCRM 贡献的是 **六项技
+能**，让这个助手学会你的 CRM。
 
-- **销售 Copilot** 帮助销售代表判定线索资格、撰写邮件、预测收入，并获得客户的 360° 全景视图。
-- **服务 Copilot** 帮助客服坐席分流工单、查看完整的客户历史，并撰写客户回复。
+> **没有应用自有的智能体。** HotCRM 曾定义过两个自己的智能体——"销售 Copilot"和"服务
+> Copilot"。它们已被退役，其能力迁移到了附着于平台助手的技能中。本页描述的一切依然有
+> 效；变的只是接线方式。
 
-两者都运行在你的 CRM 数据之上——它们从你在 UI 中看到的同一批对象读取数据，并且了解你的产品、知识库和流程规则。
+这六项技能从你在 UI 中看到的同一批对象读取数据，并且了解你的产品、知识库和流程规则。
 
 ## 你会在哪里找到它
 
-- 🪄 **Copilot 面板**——一个从每个页面右侧边缘打开的聊天面板。
-- ⚡ **内联操作**——记录详情页上的按钮，如*"判定此线索资格"*、*"撰写回复"*、*"总结工单"*。
-- 📋 **建议**——仪表盘中的自动洞察（*"本周有 3 笔交易存在风险"*）。
+- 🪄 **助手面板**——平台从每个页面右侧边缘打开的聊天面板。
+- 🎯 **上下文激活**——技能声明了自己所属的记录，因此打开一条线索并问 *"这条值得打个电话吗？"*，无需点名就会运行线索资格判定。
+- 📈 **在仪表盘上提问**——收入预测技能也会在仪表盘上激活，你可以就地问 *"本周有什么风险？"*。
 
 ## 它如何运作（通俗地说）
 
-Copilot 有三大要素：
+助手有三大要素：
 
 1. **技能**——细分到点的能力，如*撰写邮件*、*判定此线索资格*、*分流此工单*。参见 [技能](/zh-Hans/docs/ai-copilot/skills)。
 2. **知识库**——可搜索的产品信息、销售剧本、支持文章和竞争情报库。参见 [知识库](/zh-Hans/docs/ai-copilot/knowledge-bases)。
-3. **你的实时 CRM 数据**——Copilot 从你看到的同一批客户、联系人、商机和工单读取数据，并遵循相同的共享规则。
+3. **你的实时 CRM 数据**——助手从你看到的同一批客户、联系人、商机和工单读取数据，并遵循相同的共享规则。
 
-当你提出问题时，Copilot 会选择合适的技能、拉取相关知识，并将其与你的 CRM 数据结合，生成有依据的答案——并附带回溯到源记录和文章的引用。
+当你提出问题时，助手会选择合适的技能、拉取相关知识，并将其与你的 CRM 数据结合，生成有
+依据的答案——并附带回溯到源记录和文章的引用。
 
 ## 它不会做什么
 
 - ❌ 查看你看不到的记录——它遵循共享和字段级安全。
 - ❌ 未经你确认就执行操作——撰写好的邮件和更新会先预览。
 - ❌ 编造数据——每一条声明都可追溯到一条记录或一个知识来源。
+- ❌ 使用自带的专属工具——技能不声明任何专属工具，每一次写入都经由真实的 HotCRM 操作完成，权限校验与点击按钮时完全一致。
 
-## 两种形态
+## 技能的两种分组
 
-| Copilot | 受众 | 内置技能 |
-| --- | --- | --- |
-| [**销售 Copilot**](/zh-Hans/docs/ai-copilot/sales-copilot) | 销售代表、销售经理 | 线索资格判定、邮件撰写、收入预测、360° 客户视图 |
-| [**服务 Copilot**](/zh-Hans/docs/ai-copilot/service-copilot) | 服务坐席、支持经理 | 工单分流、360° 客户视图、邮件撰写 |
+六项技能按角色分成两组来编写文档。这只是文档上的便利，而非运行时边界——同一个助手运行
+全部六项技能，只要"销售"技能是正确答案，它也会用它来回答服务问题。
 
-两个 Copilot 在相关时可以互相调用对方的技能——例如，服务 Copilot 可以使用销售 Copilot 的 *Customer 360°* 技能来展示客户购买过什么。
+| 分组 | 受众 | 技能 |
+| --- | --- | --- |
+| [**销售技能**](/zh-Hans/docs/ai-copilot/sales-copilot) | 销售代表、销售经理 | 实时数据、线索资格判定、邮件撰写、收入预测、Customer 360° |
+| [**服务技能**](/zh-Hans/docs/ai-copilot/service-copilot) | 服务坐席、支持经理 | 实时数据、工单分流、Customer 360°、邮件撰写 |
 
 ## 从这里开始
 
-- [销售 Copilot](/zh-Hans/docs/ai-copilot/sales-copilot)——销售代表和经理能做什么。
-- [服务 Copilot](/zh-Hans/docs/ai-copilot/service-copilot)——坐席能做什么。
+- [销售技能](/zh-Hans/docs/ai-copilot/sales-copilot)——销售代表和经理能做什么。
+- [服务技能](/zh-Hans/docs/ai-copilot/service-copilot)——坐席能做什么。
 - [技能](/zh-Hans/docs/ai-copilot/skills)——完整的技能库。
-- [知识库](/zh-Hans/docs/ai-copilot/knowledge-bases)——Copilot 读取的 RAG 索引。
+- [知识库](/zh-Hans/docs/ai-copilot/knowledge-bases)——助手读取的 RAG 索引。

content/docs/ai-copilot/index.zh-Hant.mdx

@@ -5,47 +5,53 @@ description: 嵌入 HotCRM 各處的 AI 助手——它能做什麼、在哪裡
 
 # AI Copilot
 
-HotCRM 是 **AI 原生**的——助手是內建的，而非外掛的。開箱即用地提供兩個專門的 Copilot：
+HotCRM 是 **AI 原生**的——助手是內建的，而非外掛的。但助手本身並非由 HotCRM 提供：它
+是每個 ObjectStack 環境已經自帶的 **平台助手**（`ask`）。HotCRM 貢獻的是 **六項技
+能**，讓這個助手學會你的 CRM。
 
-- **銷售 Copilot** 幫助銷售代表判定潛在客戶資格、撰寫郵件、預測收入，並獲得客戶的 360° 全景視圖。
-- **服務 Copilot** 幫助客服坐席分流工單、查看完整的客戶歷史，並撰寫客戶回覆。
+> **沒有應用自有的智能體。** HotCRM 曾定義過兩個自己的智能體——「銷售 Copilot」和「服
+> 務 Copilot」。它們已被退役，其能力遷移到了附著於平台助手的技能中。本頁描述的一切依
+> 然有效；變的只是接線方式。
 
-兩者都執行在你的 CRM 資料之上——它們從你在 UI 中看到的同一批物件讀取資料，並且了解你的產品、知識庫和流程規則。
+這六項技能從你在 UI 中看到的同一批物件讀取資料，並且了解你的產品、知識庫和流程規則。
 
 ## 你會在哪裡找到它
 
-- 🪄 **Copilot 面板**——一個從每個頁面右側邊緣開啟的聊天面板。
-- ⚡ **內聯操作**——記錄詳情頁上的按鈕，如*「判定此潛在客戶資格」*、*「撰寫回覆」*、*「總結工單」*。
-- 📋 **建議**——儀表板中的自動洞察（*「本週有 3 筆交易存在風險」*）。
+- 🪄 **助手面板**——平台從每個頁面右側邊緣開啟的聊天面板。
+- 🎯 **情境啟用**——技能宣告了自己所屬的記錄，因此打開一筆潛在客戶並問 *「這筆值得打個電話嗎？」*，無需點名就會執行潛在客戶資格判定。
+- 📈 **在儀表板上提問**——收入預測技能也會在儀表板上啟用，你可以就地問 *「本週有什麼風險？」*。
 
 ## 它如何運作（通俗地說）
 
-Copilot 有三大要素：
+助手有三大要素：
 
 1. **技能**——細分到點的能力，如*撰寫郵件*、*判定此潛在客戶資格*、*分流此工單*。參見 [技能](/zh-Hant/docs/ai-copilot/skills)。
 2. **知識庫**——可搜尋的產品資訊、銷售劇本、支援文章和競爭情報庫。參見 [知識庫](/zh-Hant/docs/ai-copilot/knowledge-bases)。
-3. **你的即時 CRM 資料**——Copilot 從你看到的同一批客戶、聯絡人、商機和工單讀取資料，並遵循相同的共享規則。
+3. **你的即時 CRM 資料**——助手從你看到的同一批客戶、聯絡人、商機和工單讀取資料，並遵循相同的共享規則。
 
-當你提出問題時，Copilot 會選擇合適的技能、拉取相關知識，並將其與你的 CRM 資料結合，生成有依據的答案——並附帶回溯到來源記錄和文章的引用。
+當你提出問題時，助手會選擇合適的技能、拉取相關知識，並將其與你的 CRM 資料結合，生成有
+依據的答案——並附帶回溯到來源記錄和文章的引用。
 
 ## 它不會做什麼
 
 - ❌ 查看你看不到的記錄——它遵循共享和欄位級安全。
 - ❌ 未經你確認就執行操作——撰寫好的郵件和更新會先預覽。
 - ❌ 編造資料——每一條聲明都可追溯到一條記錄或一個知識來源。
+- ❌ 使用自帶的專屬工具——技能不宣告任何專屬工具，每一次寫入都經由真實的 HotCRM 操作完成，權限校驗與點擊按鈕時完全一致。
 
-## 兩種形態
+## 技能的兩種分組
 
-| Copilot | 受眾 | 內建技能 |
-| --- | --- | --- |
-| [**銷售 Copilot**](/zh-Hant/docs/ai-copilot/sales-copilot) | 銷售代表、銷售經理 | 潛在客戶資格判定、郵件撰寫、收入預測、360° 客戶視圖 |
-| [**服務 Copilot**](/zh-Hant/docs/ai-copilot/service-copilot) | 服務坐席、支援經理 | 工單分流、360° 客戶視圖、郵件撰寫 |
+六項技能按角色分成兩組來編寫文件。這只是文件上的便利，而非執行時邊界——同一個助手執行
+全部六項技能，只要「銷售」技能是正確答案，它也會用它來回答服務問題。
 
-兩個 Copilot 在相關時可以互相呼叫對方的技能——例如，服務 Copilot 可以使用銷售 Copilot 的 *Customer 360°* 技能來展示客戶購買過什麼。
+| 分組 | 受眾 | 技能 |
+| --- | --- | --- |
+| [**銷售技能**](/zh-Hant/docs/ai-copilot/sales-copilot) | 銷售代表、銷售經理 | 即時資料、潛在客戶資格判定、郵件撰寫、收入預測、Customer 360° |
+| [**服務技能**](/zh-Hant/docs/ai-copilot/service-copilot) | 服務坐席、支援經理 | 即時資料、工單分流、Customer 360°、郵件撰寫 |
 
 ## 從這裡開始
 
-- [銷售 Copilot](/zh-Hant/docs/ai-copilot/sales-copilot)——銷售代表和經理能做什麼。
-- [服務 Copilot](/zh-Hant/docs/ai-copilot/service-copilot)——坐席能做什麼。
+- [銷售技能](/zh-Hant/docs/ai-copilot/sales-copilot)——銷售代表和經理能做什麼。
+- [服務技能](/zh-Hant/docs/ai-copilot/service-copilot)——坐席能做什麼。
 - [技能](/zh-Hant/docs/ai-copilot/skills)——完整的技能庫。
-- [知識庫](/zh-Hant/docs/ai-copilot/knowledge-bases)——Copilot 讀取的 RAG 索引。
+- [知識庫](/zh-Hant/docs/ai-copilot/knowledge-bases)——助手讀取的 RAG 索引。