docs(ai-copilot): correct the skill count and stop attributing the forecast buckets to the skill (#897, #898)

.changeset/sales-copilot-counts-buckets.md

@@ -0,0 +1,46 @@
+---
+'hotcrm': patch
+---
+
+Correct the skill count on two pages, and stop attributing the four forecast
+buckets to the revenue-forecasting skill.
+
+**Skill count (#897).** `src/skills/index.ts` registers six skills — Live Data
+joined the registry and the docs never caught up. The capability table in
+`content/docs/index.mdx` still said "5 skills" and its parenthetical list omitted
+Live Data entirely, which is the odd one to lose: Live Data is the skill behind
+Wow #1. It now reads six, with live data named first, matching the order in
+`content/docs/ai-copilot/skills.mdx`. The Sales Copilot / Service Copilot names in
+that same table cell are untouched — they belong to a separate open question about
+persona naming.
+
+On `content/docs/ai-copilot/sales-copilot.mdx` the "Where the personas went" note
+said the capability "lives in five skills registered through `src/skills/`". The
+subject there is the registry, which holds six, but the page itself documents five
+sales-side skills and numbers them 1–5, so writing "six" would have replaced one
+mismatch with another. The sentence now carries no count at all, which is exactly
+what the parallel note on `content/docs/ai-copilot/service-copilot.mdx` already
+says in all three languages.
+
+**Forecast buckets (#898).** The forecasting section presented **Closed / Commit /
+Best Case / Pipeline** as what the skill returns, with probability thresholds
+attached to two of them (Commit above 80%, Best case 40–80%). None of that is the
+skill. `src/skills/revenue-forecasting.skill.ts` groups by stage, computes weighted
+value as amount × probability, names at-risk deals with the signal behind each, and
+gives the forecast as a range from commit-only to full weighted pipeline, optionally
+with a chart. It never reads `forecast_category`.
+
+The four names are real and the page now says where they live rather than dropping
+them: they are options of `crm_opportunity`'s **Forecast Category** field, and the
+amounts carrying those names are written onto **Forecast** records by the scheduled
+forecast snapshot in `src/flows/forecast-snapshot.flow.ts`. The probability
+thresholds had no source anywhere — the snapshot buckets by forecast category, not
+by probability band. Two smaller claims in the same section go with them: "missing
+close dates" was never one of the skill's risk signals, and the manager tip asking
+*"Which reps need coaching?"* described a per-rep rollup the skill does not do —
+stage and the user's period are its only groupings, so that tip now asks for
+slipping deals and says plainly what the skill will not answer.
+
+Documentation only, all three locales. This brings the page into line with the
+skill rows already written in `content/docs/ai-copilot/skills.mdx`, which had been
+describing the same skill differently since those rows landed. Refs #897, #898.

content/docs/ai-copilot/sales-copilot.mdx

@@ -12,9 +12,9 @@ sales skills below are what it knows how to do.
 
 > **Where the personas went.** Earlier versions of this page described a "Sales
 > Copilot" agent. HotCRM no longer defines its own agents: the same capability now
-> lives in five skills registered through `src/skills/`, and the platform assistant
-> selects among them. Nothing was lost — the wiring moved from an app-owned agent to
-> the platform one.
+> lives in skills registered through `src/skills/`, and the platform assistant selects
+> among them. Nothing was lost — the wiring moved from an app-owned agent to the
+> platform one.
 
 ## Who it's for
 
@@ -102,11 +102,21 @@ You always **preview and edit** before sending. The skill never sends on its own
 
 Ask *"What's my forecast for this quarter?"* and you get:
 
-- **Closed** — committed revenue (closed-won this period).
-- **Commit** — opportunities >80% probability in the period.
-- **Best case** — opportunities 40-80% probability.
-- **Pipeline** — everything else.
-- **Risk callouts** — deals slipping, stale opportunities, missing close dates.
+- **Pipeline by stage** — count and summed amount grouped by stage, scoped to the period you name (default: the current quarter).
+- **Weighted value** — amount × probability, computed by the skill from what it read.
+- **At-risk deals** — named one by one with the signal behind each: a close date already past, no activity in 30+ days, or a stage held longer than its typical duration.
+- **A forecast given as a range** — commit-only (high-probability stages) to full weighted pipeline, with the assumption behind the number stated in one line, rather than false precision.
+- **A chart** — via `visualize_data`, when one carries the answer better than prose.
+
+**Where the four buckets actually live.** This page used to present **Closed / Commit /
+Best Case / Pipeline** as the forecasting skill's output. Those names are real, but they
+belong elsewhere: they are options of `crm_opportunity`'s **Forecast Category** field
+(alongside **Omitted**), and the amounts carrying those names are what the scheduled
+forecast snapshot writes onto **Forecast** records. The skill neither reads
+`forecast_category` nor groups by it. The probability thresholds this page attached to
+two of them — Commit at >80%, Best case at 40-80% — had no source anywhere in HotCRM:
+the snapshot buckets by forecast category, not by probability band, and the skill uses
+probability only to compute weighted value.
 
 Forecasts respect your position and sharing rules — a rep sees their own number, a
 manager sees their team's, a director sees the rollup.
@@ -149,7 +159,7 @@ informed.
 
 - ✅ Use *Customer 360* before every customer-facing meeting your team has.
 - ✅ Run *Revenue forecast* mid-week to spot slipping deals before the EOQ scramble.
-- ✅ Ask *"Which reps need coaching?"* — the forecasting skill flags reps with stale pipelines or unusually long stage times.
+- ✅ Ask *"Which deals are slipping this quarter?"* — the forecasting skill names each at-risk deal and the signal behind it. It does not group by rep: stage and the period you name are its only groupings, so *"which reps need coaching?"* is not a question it answers.
 
 ## Limits
 

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

@@ -10,9 +10,8 @@ ObjectStack 环境已经自带的 **平台助手**（`ask`）之上。当你在
 时，下面这些销售技能就是它会做的事。
 
 > **人格设定去哪了。** 本页的早期版本描述过一个"销售 Copilot"智能体。HotCRM 不再定
-> 义自己的智能体：同样的能力现在存在于通过 `src/skills/` 注册的五项技能中，由平台助
-> 手在其中做选择。没有任何能力丢失——只是接线方式从应用自有的智能体挪到了平台的那一
-> 个。
+> 义自己的智能体：同样的能力现在存在于通过 `src/skills/` 注册的技能中，由平台助手在其
+> 中做选择。没有任何能力丢失——只是接线方式从应用自有的智能体挪到了平台的那一个。
 
 ## 它面向谁
 
@@ -95,11 +94,18 @@ ObjectStack 环境已经自带的 **平台助手**（`ask`）之上。当你在
 
 问 *"我这个季度的预测是多少？"*，你会得到：
 
-- **Closed（已成交）**——已承诺收入（本期赢单成交）。
-- **Commit（承诺）**——本期内概率 >80% 的商机。
-- **Best case（最佳情况）**——概率 40-80% 的商机。
-- **Pipeline（管道）**——其余一切。
-- **风险提示**——滑落的交易、陈旧的商机、缺失的成交日期。
+- **按阶段展开的管道**——按阶段分组的数量与金额合计，范围是你指定的周期（默认：本季度）。
+- **加权价值**——金额 × 概率，由技能自己从读到的数据算出。
+- **有风险的交易**——逐条点名，并给出各自背后的信号：预计成交日期已过、30 天以上没有活动，或阶段停留时间超过它通常的时长。
+- **以区间给出的预测**——从仅承诺口径（高概率阶段）到完整加权管道，并用一句话写明这个数字背后的假设，而不是给出虚假的精确值。
+- **图表**——在图表比文字更能说明问题时，用 `visualize_data` 出图。
+
+**那四个桶实际在哪里。** 本页曾把 **已关闭 / 承诺 / 最佳情况 / 管道** 这四个名字当成收入
+预测技能的输出。这些名字是真实存在的，但它们属于别处：它们是 `crm_opportunity` 的
+**预测类别** 字段的选项（同一组里还有 **已排除**），而带着这些名字的金额，是定时的销售预
+测快照写入 **销售预测** 记录的那几个。技能既不读 `forecast_category`，也不按它分组。本页
+给其中两个加上的概率阈值——承诺 >80%、最佳情况 40-80%——在 HotCRM 里没有任何出处：快照
+是按预测类别分桶的，不按概率区间，而技能只把概率用于计算加权价值。
 
 预测遵循你的岗位与共享规则——销售代表看到自己的数字，经理看到团队的，总监看到汇总。
 
@@ -138,7 +144,7 @@ ID（`CASE-01234`、`KA-0007`），便于界面深链。风险必须点名它依
 
 - ✅ 在团队的每次面向客户的会议前使用 *Customer 360*。
 - ✅ 在周中运行 *收入预测*，在季末冲刺前发现滑落的交易。
-- ✅ 问 *"哪些销售代表需要辅导？"*——收入预测技能会标记管道陈旧或阶段停留异常长的销售代表。
+- ✅ 问 *"这个季度哪些交易在滑期？"*——收入预测技能会逐条点名有风险的交易及其背后的信号。它不按销售代表分组：阶段和你指定的周期是它仅有的两个分组维度，所以 *"哪些销售代表需要辅导？"* 不是它能回答的问题。
 
 ## 限制
 

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

@@ -10,8 +10,8 @@ ObjectStack 環境已經自帶的 **平台助手**（`ask`）之上。當你在
 時，下面這些銷售技能就是它會做的事。
 
 > **人格設定去哪了。** 本頁的早期版本描述過一個「銷售 Copilot」智能體。HotCRM 不再定
-> 義自己的智能體：同樣的能力現在存在於透過 `src/skills/` 註冊的五項技能中，由平台助手
-> 在其中做選擇。沒有任何能力遺失——只是接線方式從應用自有的智能體挪到了平台的那一個。
+> 義自己的智能體：同樣的能力現在存在於透過 `src/skills/` 註冊的技能中，由平台助手在其
+> 中做選擇。沒有任何能力遺失——只是接線方式從應用自有的智能體挪到了平台的那一個。
 
 ## 它面向誰
 
@@ -95,11 +95,18 @@ ObjectStack 環境已經自帶的 **平台助手**（`ask`）之上。當你在
 
 問 *「我這一季的預測是多少？」*，你會得到：
 
-- **Closed（已成交）**——已承諾收入（本期贏單成交）。
-- **Commit（承諾）**——本期內機率 >80% 的商機。
-- **Best case（最佳情況）**——機率 40-80% 的商機。
-- **Pipeline（管道）**——其餘一切。
-- **風險提示**——滑落的交易、陳舊的商機、缺失的成交日期。
+- **按階段展開的管道**——按階段分組的數量與金額合計，範圍是你指定的週期（預設：本季度）。
+- **加權價值**——金額 × 機率，由技能自己從讀到的資料算出。
+- **有風險的交易**——逐條點名，並給出各自背後的信號：預計成交日期已過、30 天以上沒有活動，或階段停留時間超過它通常的時長。
+- **以區間給出的預測**——從僅承諾口徑（高機率階段）到完整加權管道，並用一句話寫明這個數字背後的假設，而不是給出虛假的精確值。
+- **圖表**——在圖表比文字更能說明問題時，用 `visualize_data` 出圖。
+
+**那四個桶實際在哪裡。** 本頁曾把 **已關閉 / 承諾 / 最佳情況 / 管道** 這四個名字當成收入
+預測技能的輸出。這些名字是真實存在的，但它們屬於別處：它們是 `crm_opportunity` 的
+**預測類別** 欄位的選項（同一組裡還有 **已排除**），而帶著這些名字的金額，是定時的銷售預
+測快照寫入 **銷售預測** 記錄的那幾個。技能既不讀 `forecast_category`，也不按它分組。本頁
+給其中兩個加上的機率閾值——承諾 >80%、最佳情況 40-80%——在 HotCRM 裡沒有任何出處：快照
+是按預測類別分桶的，不按機率區間，而技能只把機率用於計算加權價值。
 
 預測遵循你的職位與共享規則——銷售代表看到自己的數字，經理看到團隊的，總監看到彙總。
 
@@ -138,7 +145,7 @@ ID（`CASE-01234`、`KA-0007`），便於介面深層連結。風險必須點名
 
 - ✅ 在團隊的每次面向客戶的會議前使用 *Customer 360*。
 - ✅ 在週中執行 *收入預測*，在季末衝刺前發現滑落的交易。
-- ✅ 問 *「哪些銷售代表需要輔導？」*——收入預測技能會標記管道陳舊或階段停留異常長的銷售代表。
+- ✅ 問 *「這個季度哪些交易在滑期？」*——收入預測技能會逐條點名有風險的交易及其背後的信號。它不按銷售代表分組：階段和你指定的週期是它僅有的兩個分組維度，所以 *「哪些銷售代表需要輔導？」* 不是它能回答的問題。
 
 ## 限制
 

content/docs/index.mdx

@@ -65,7 +65,7 @@ This documentation is organised by **what you want to do**. Pick the section tha
 | **Service** | Cases (with SLA and escalation), Tasks, knowledge base for the copilot |
 | **Marketing** | Campaigns (8 types), Campaign Members (lead/contact enrollment), ROI tracking |
 | **Revenue** | Products, Contracts (5 types), Discount Approvals |
-| **AI** | Sales Copilot, Service Copilot, 5 skills (lead qualification, case triage, email drafting, revenue forecasting, customer 360) |
+| **AI** | Sales Copilot, Service Copilot, 6 skills (live data, lead qualification, case triage, email drafting, revenue forecasting, customer 360) |
 | **Analytics** | 4 dashboards (CRM / Sales / Service / Executive), 10+ standard reports |
 | **Security** | 6 user profiles, role hierarchy, sharing rules, multi-step approvals |
 

content/docs/index.zh-Hans.mdx

@@ -64,7 +64,7 @@ description: AI 原生的企业级 CRM——业务变化时它会自我重写。
 | **服务** | 工单（含 SLA 与升级）、任务、面向 Copilot 的知识库 |
 | **市场** | 营销活动（8 种类型）、营销活动成员（线索/联系人纳入）、ROI 追踪 |
 | **营收** | 产品、合同（5 种类型）、折扣审批 |
-| **AI** | 销售 Copilot、服务 Copilot、5 项技能（线索资格判定、工单分流、邮件起草、营收预测、客户 360） |
+| **AI** | 销售 Copilot、服务 Copilot、6 项技能（实时数据、线索资格判定、工单分流、邮件起草、营收预测、客户 360） |
 | **分析** | 4 个仪表盘（CRM / 销售 / 服务 / 高管）、10+ 标准报表 |
 | **安全** | 6 种用户权限档案、角色层级、共享规则、多步审批 |
 

content/docs/index.zh-Hant.mdx

@@ -64,7 +64,7 @@ description: AI 原生的企業級 CRM——業務變化時它會自我重寫。
 | **服務** | 工單（含 SLA 與升級）、任務、面向 Copilot 的知識庫 |
 | **行銷** | 行銷活動（8 種類型）、行銷活動成員（潛客/聯絡人納入）、ROI 追蹤 |
 | **營收** | 產品、合約（5 種類型）、折扣審批 |
-| **AI** | 銷售 Copilot、服務 Copilot、5 項技能（潛客資格判定、工單分流、郵件草擬、營收預測、客戶 360） |
+| **AI** | 銷售 Copilot、服務 Copilot、6 項技能（即時資料、潛客資格判定、工單分流、郵件草擬、營收預測、客戶 360） |
 | **分析** | 4 個儀表板（CRM / 銷售 / 服務 / 高階主管）、10+ 標準報表 |
 | **安全** | 6 種使用者權限設定檔、角色層級、共用規則、多步審批 |