@synity/bitrix-skills 1.3.9 → 1.3.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.3.11
+
+### Patch Changes
+
+- 1260083: docs(bx-crm): add deal optional products flow to onboard.md + routing table; fix TypeScript null assertion in update command
+
+## 1.3.10
+
+### Patch Changes
+
+- feat(features): promote bx, bx-crm, bx-calendar from planned to active — now installable via `install --all`
+
 ## 1.3.9
 
 ### Patch Changes
@@ -22,6 +34,12 @@
 
   docs(task-sync): document --key flag and fix stale package name (@synity/bitrix-task-sync → @synity/bitrix-skills) in SKILL.md and README to prevent agent hallucinating --token flag
 
+## 1.3.2
+
+### Patch Changes
+
+- Restore `--all` flag on `install` command and fix non-TTY safety guard. Both behaviors were dropped in 1.3.0 cleanup but remained under test contract — `install --all` previously errored with "unknown option", and CI runs would silently bulk-install everything. Also repairs `sync-assets.mjs` so test/build pipelines populate `assets/scripts/` correctly after the single-repo migration.
+
 ## 1.3.1
 
 ### Patch Changes

package/dist/cli.js

@@ -1186,7 +1186,7 @@ var InstallCommand = class extends Command {
     ]
   });
   key = Option.String("--key", { description: "License key to unlock paid tier features" });
-  all = Option.Boolean("--all", false, { description: "Install all available features" });
+  all = Option.Boolean("--all", false, { description: "Install all installable features (required in non-TTY)" });
   featuresFlag = Option.String("--features", { description: "Comma-separated feature names" });
   featureArgs = Option.Rest({ required: 0 });
   async execute() {
@@ -1227,8 +1227,13 @@ var InstallCommand = class extends Command {
       selectedNames = this.featuresFlag.split(",").map((s) => s.trim()).filter(Boolean);
     } else if (this.featureArgs.length > 0) {
       selectedNames = this.featureArgs;
-    } else {
+    } else if (this.all || process.stdin.isTTY) {
       selectedNames = installable.map((f) => f.name);
+    } else {
+      this.context.stderr.write(
+        chalk.red("Refusing to install in non-TTY without explicit selection.\n") + chalk.gray("  Pass --all, --features <csv>, or feature names as positional args.\n")
+      );
+      return 1;
     }
     const availableNames = new Set(available.map((f) => f.name));
     const invalid = selectedNames.filter((n) => !availableNames.has(n));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synity/bitrix-skills",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "description": "Multi-feature Bitrix24 tooling CLI for Synity projects",
   "type": "module",
   "bin": {
@@ -47,15 +47,22 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
+    "@eslint/js": "^9.39.4",
     "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^9.39.4",
+    "globals": "^17.6.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
+    "typescript-eslint": "^8.59.3",
     "vitest": "^2.1.0"
   },
   "scripts": {
     "prebuild": "node scripts/prebuild-bash-sync.mjs && node scripts/sync-assets.mjs",
     "build": "tsup --config tsup.config.ts",
     "dev": "tsup --config tsup.config.ts --watch",
+    "pretest": "node scripts/prebuild-bash-sync.mjs && node scripts/sync-assets.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src --ext .ts",

package/src/features/bx/feature.json

@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "target": "global",
   "description": "Claude Code hub skill \u2014 routes to bx:crm, bx:task, bx:calendar. Install for discovery UX.",
-  "status": "planned",
+  "status": "active",
   "requires": {},
   "tier": 0
 }

package/src/features/bx-calendar/feature.json

@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "target": "global",
   "description": "Claude Code skill for Bitrix24 Calendar: meetings, reminders, team availability, CRM activity sync",
-  "status": "planned",
+  "status": "active",
   "requires": {
     "env": [
       "BITRIX_WEBHOOK_URL"

package/src/features/bx-crm/assets/SKILL.md

@@ -2,11 +2,10 @@
 name: bx:crm
 description: "Bitrix24 CRM via MCP Synity: contacts, companies, deals, leads, estimates, invoices, customer 360, pipeline reports. NOT for project tasks (bx:task) or calendar events (bx:calendar)."
 argument-hint: "<intent or operation>"
-version: "2.0.0"
+version: "2.2.0"
 ---
 
 # /bx:crm — Bitrix24 CRM via MCP Synity
-
 Use this skill for CRM entities only: contacts, companies, deals, leads, estimates, invoices, customer analysis, and pipeline reports.
 
 **Tool:** MCP Synity at `b24-mcp.synity.so`. Start with `codemode.search()` then execute the selected helper.
@@ -15,11 +14,14 @@ Use this skill for CRM entities only: contacts, companies, deals, leads, estimat
 
 | User intent | Load file | Key helpers |
 |---|---|---|
-| create/update contact, company, deal, lead | `onboard.md` | `upsertContact`, `upsertCompanyByTaxCode`, `createDealWithParties` |
+| create/update contact, company, deal, lead | `onboard.md` | `upsertContact`, `upsertCompanyByTaxCode`, `createDealWithParties`, `setDealProducts`, `findProducts` |
 | VN phone, honorific, address, MST format | `vn-norms.md` | normalization rules |
 | convert/qualify lead to deal | `convert.md` | `convertLeadToDeal` |
 | estimate, báo giá, invoice, payment link | `commerce.md` | `createEstimate`, `approveEstimate`, `createSmartInvoice` |
 | document, contract, PDF generation | `document.md` | `codemode.request` for `crm.documentgenerator.*` |
+| referral mention, "giới thiệu bởi", recommend | `referral.md` (+ `onboard.md` § Referral UFs) | SOP: ensure UFs → resolve referrer → forward + reverse link |
+| auto-detect source / source unclear | `referral.md` § Source Auto-Detection | SOP: keyword score + confidence threshold + ask fallback |
+| contact/company lifecycle, customer journey, MQL/SQL/Customer classification | `lifecycle.md` (+ `onboard.md` § Lifecycle UF) | SOP: ensure UF → detect stage → write enum ID |
 | customer 360, signals, meeting prep | `research.md` | `customer360`, `contactSignals`, `dealSignals` |
 | pipeline report, forecast, AR, overdue | `report.md` | `dealForecast`, `stuckInStage`, `arReport` |
 | multi-step CRM workflows | `flows.md` | combo orchestration |
@@ -38,6 +40,8 @@ Use this skill for CRM entities only: contacts, companies, deals, leads, estimat
 ## Mandatory Workflow
 
 1. Detect intent and load the right subfile.
+   - First-time referral mention this session → run `ensureReferralUFs` (onboard.md § Referral UFs).
+   - First-time contact/company create this session → perform `onboard.md` § Lifecycle UF SOP.
 2. Confirm helper schema with `codemode.search()` before writes.
 3. Ask user confirmation before MCP writes or irreversible status changes.
 4. Execute through helper first; use raw REST only when a subfile marks an MCP gap.

package/src/features/bx-crm/assets/lifecycle.md

@@ -0,0 +1,198 @@
+# bx:crm — Contact + Company Lifecycle
+
+Detection + classification of customer-journey stage. Load when creating contact/company, or when user mentions lifecycle, MQL, SQL, customer, subscriber, or customer journey.
+
+UF prerequisite lives in [onboard.md § Lifecycle UF](./onboard.md#lifecycle-uf-prerequisite). Perform that SOP once per session before writing lifecycle fields.
+
+---
+
+## Stages
+
+| XML_ID | Meaning | SORT | Default |
+|---|---|---:|---|
+| `SUBSCRIBER` | Opted into content, newsletter, community, or follows | 100 | N |
+| `LEAD` | New or low-context prospect | 200 | Y |
+| `MQL` | Marketing-qualified from content, webinar, form, ebook | 300 | N |
+| `SQL` | Sales-qualified: demo, meeting, quote, consultation requested | 400 | N |
+| `OPPORTUNITY` | Active commercial opportunity or negotiation | 500 | N |
+| `CUSTOMER` | Paid, signed, existing, or active customer | 600 | N |
+| `EVANGELIST` | Advocate/referrer/loyal customer generating referrals | 700 | N |
+| `OTHER` | Explicit user override not covered above | 800 | N |
+
+Default fallback is `LEAD`. User can always override.
+
+## Keyword Table
+
+| XML_ID | Triggers |
+|---|---|
+| `SUBSCRIBER` | "đăng ký nhận tin", "subscribe", "newsletter", "follow page", "theo dõi fanpage" |
+| `LEAD` | "lead mới", "khách mới", "potential", "vừa biết tới", "first contact" |
+| `MQL` | "mql", "marketing qualified", "đã tải tài liệu", "đăng ký webinar", "tải ebook" |
+| `SQL` | "sql", "sales qualified", "đã demo", "đã book meeting", "muốn báo giá", "asking for quote" |
+| `OPPORTUNITY` | "deal đang chạy", "đang đàm phán", "negotiating", "active deal", "có cơ hội" |
+| `CUSTOMER` | "đã mua", "đã ký hợp đồng", "khách hàng hiện tại", "existing customer", "paying customer", "đã thanh toán" |
+| `EVANGELIST` | "giới thiệu nhiều khách", "khách trung thành", "referrer", "advocate", "loyal customer" |
+| `OTHER` | "stage khác", "other", "khác", "không phân loại" |
+
+## Detection Algorithm
+
+Reuse Source Auto-Detection constants for predictable behavior. Pseudocode only; do not call a fictional helper.
+
+```
+INPUT: userRequestText, entityType ('CONTACT'|'COMPANY'), referralActive
+CONST gap = 0.2
+CONST scoreUnit = 5
+CONST confidenceThreshold = 0.8
+CONST defaultStage = "LEAD"
+
+IF referralActive:
+  RETURN {
+    needsAsk: true,
+    candidates: top5Default(),
+    reason: "referral capture in progress; lifecycle should be user-confirmed"
+  }
+
+normalized = norm(userRequestText)
+scores = []
+FOR each stage IN keywordTable:
+  score = 0; matched = []
+  FOR each keyword IN keywordTable[stage]:
+    IF normalized.includes(norm(keyword)):
+      score += keyword.length / scoreUnit
+      matched.push(keyword)
+  IF score > 0: scores.push({ stage, score, matched })
+
+top = scores.sort(desc by score).slice(0, 3)
+IF top.length === 0:
+  RETURN { lifecycle: defaultStage, confidence: 0.5, reason: "no keyword match → default LEAD" }
+
+confidence = top[0].score / sum(scores.score)
+IF confidence >= confidenceThreshold AND (top[0].score - (top[1]?.score || 0)) > gap:
+  RETURN { lifecycle: top[0].stage, confidence, reason: top[0].matched }
+
+RETURN { needsAsk: true, candidates: top, reason: "ambiguous match" }
+```
+
+`top5Default()` = `[LEAD, MQL, SQL, CUSTOMER, OTHER]`.
+
+## Diacritic Normalization
+
+```js
+const norm = s => s.toLowerCase()
+  .normalize('NFD')
+  .replace(/[\u0300-\u036f]/g, '')
+  .replace(/đ/g, 'd');
+```
+
+## Heuristic Shortcuts
+
+| Signal | Auto-pick | Confidence |
+|---|---|---:|
+| "stage là MQL" / "lifecycle = SQL" | Exact XML_ID | 1.0 |
+| "đã thanh toán invoice" / "deal WON" | `CUSTOMER` | 0.95 |
+| "form webinar" + "newsletter" | `MQL` | 0.85 |
+| Phone-only contact, no other context | `LEAD` | 0.5 |
+| "giới thiệu cho 3 người" / referrer-themself | `EVANGELIST` | 0.85 |
+
+Apply exact user-declared stage before keyword scoring. If declared stage is invalid, ask.
+
+## Referral-Active Suppression
+
+When `referralActive === true`, do not auto-pick from referral words. Ask user instead.
+
+Reason: referral capture is attribution, not lifecycle. A referrer mention may mean the new contact was referred, not that the referrer is an `EVANGELIST`.
+
+## Ask Fallback
+
+`needsAsk: true` → `AskUserQuestion`:
+
+- Header: "Lifecycle"
+- Question: "Giai đoạn nào phù hợp với {entityType.toLowerCase()} này? (matched: {keywords})"
+- Options:
+  - Top-3 candidates with matched keywords
+  - `Other`
+  - "Skip lần này"
+
+Descriptions:
+
+| Option | Description |
+|---|---|
+| Lead | New/low-context prospect |
+| MQL | Marketing-qualified from form/content/webinar |
+| SQL | Ready for sales conversation |
+| Customer | Already paid/signed/current customer |
+| Other | User-defined stage outside default taxonomy |
+
+## Integration Hooks
+
+Contact create/update path after phone normalization, before write:
+
+```js
+// Pseudocode: apply Detection Algorithm above, then AskUserQuestion if needsAsk.
+const lifecycle = applyLifecycleDetection({ text: userRequestText, entityType: 'CONTACT', referralActive });
+const lifecycleXmlId = lifecycle.needsAsk ? AskUserQuestion(lifecycle.candidates) : lifecycle.lifecycle;
+
+let enumId = enumCache.CONTACT[lifecycleXmlId];
+if (!enumId) {
+  // Re-fetch crm.contact.userfield.list once and rebuild CONTACT cache.
+  enumId = enumCache.CONTACT[lifecycleXmlId];
+}
+if (enumId) fields.UF_CRM_LIFECYCLE = enumId;
+// Else omit lifecycle and show UF spec/cache-miss warning.
+```
+
+Company create/update path is identical with `entityType: 'COMPANY'` and `enumCache.COMPANY[...]`:
+
+```js
+let enumId = enumCache.COMPANY[lifecycleXmlId];
+if (!enumId) {
+  // Re-fetch crm.company.userfield.list once and rebuild COMPANY cache.
+  enumId = enumCache.COMPANY[lifecycleXmlId];
+}
+if (enumId) fields.UF_CRM_LIFECYCLE = enumId;
+// Else omit lifecycle and show UF spec/cache-miss warning.
+```
+
+If user selects "Skip lần này", omit `UF_CRM_LIFECYCLE`; Bitrix UI default may still show Lead if the field exists.
+
+## Enum-ID Resolution
+
+Never write raw XML_ID string to `UF_CRM_LIFECYCLE`.
+
+Correct runtime contract:
+
+```js
+const enumId = enumCache[entityType][xmlId];
+if (!enumId) {
+  // Re-fetch crm.{entity}.userfield.list once, rebuild cache, then ask if still missing.
+}
+```
+
+Bitrix assigns independent numeric IDs per entity. `CONTACT.LEAD` and `COMPANY.LEAD` usually differ.
+
+## Logging
+
+Do not log names, phone, email, tax code, or raw user text.
+
+```
+[Lifecycle] auto-picked "MQL" for contact 12345 (confidence 0.88, matched: "đã tải tài liệu", "webinar")
+[Lifecycle] asked user for company 6789 (ambiguous: SQL 0.62 vs OPPORTUNITY 0.55)
+```
+
+## Entity Coupling
+
+- CONTACT and COMPANY lifecycle are independent in V1.
+- Do not auto-sync company lifecycle from primary contact.
+- Do not auto-advance from deal `STAGE_ID`.
+- V2 can add reconciliation/history once real usage patterns are known.
+
+## Edge Cases
+
+| Case | Handling |
+|---|---|
+| No keyword signal | Default `LEAD`, confidence 0.5 |
+| Multiple weak signals | Ask top-3 |
+| Referral flow active | Ask, do not auto-pick |
+| Explicit invalid stage | Ask user to pick valid stage |
+| Cache missing enum ID | Re-fetch once; if still missing, skip lifecycle and show UF spec |
+| Existing contact/company found | Confirm before changing lifecycle; do not overwrite silently |

package/src/features/bx-crm/assets/onboard.md

@@ -58,7 +58,7 @@ Use `createDealWithParties` for atomic contact + company + deal.
 | `OPPORTUNITY` | user input number | `588` |
 | `SOURCE_ID` | mapping below | `OTHER` |
 
-**SOURCE_ID mapping:** Event/offline=`OTHER`, website/form=`WEB`, partner=`PARTNER`, call=`CALL`, social/ad=`ADVERTISING`.
+**SOURCE_ID:** Use § Source Auto-Detection algorithm; falls back to ask when ambiguous. Force `RECOMMENDATION` if referrer detected.
 
 **COMMENTS — BANT template:**
 ```text
@@ -69,6 +69,42 @@ Timeline: <start date>
 Notes: <context>
 ```
 
+## Deal — Optional Products
+
+Add products only when the user explicitly mentions product names or asks for products on the deal.
+
+```js
+// 1. Extract short keyword (1-2 words) from user's product name — do NOT pass full name
+// name = substring match; "%keyword%" wildcard syntax breaks the param
+const matches = await findProducts({ name: "<short keyword>", limit: 5 })
+// → [{ id, name, sku, price, currency, vatRate, matched }]
+
+// 2. Confirm match with user if multiple or ambiguous results
+// 3. Add to deal (currency omitted — Bitrix inherits from deal)
+await setDealProducts({
+  dealId,
+  items: [{ productId: matches[0].id, price: matches[0].price, quantity: 1 }],
+  mode: "replace"
+})
+```
+
+**MCP gap fallback** — use only when `setDealProducts` is absent from `codemode.catalog()`:
+```js
+codemode.request({
+  method: "POST",
+  path: "/crm.deal.productrows.set",
+  body: { id: dealId, rows: [{ PRODUCT_ID: id, PRICE: price, QUANTITY: quantity }] }
+})
+```
+
+**Rules:**
+- Products are optional — add only when user mentions specific product names.
+- Always `findProducts` to resolve name → id; never hardcode `PRODUCT_ID`.
+- Pass a short keyword (1-2 words) to `findProducts({ name })`, not the full product name.
+- Omit `currency` in items — Bitrix inherits it from the deal automatically.
+- Custom line items (no catalog id): pass `{ name, price, quantity }` without `id`.
+- Commerce catalog variants (SKU variants) require `catalog` scope on the MCP token; if 401, fall back to custom line item and note the MCP gap.
+
 ## Lead — Create + Products
 
 Use lead when the prospect is unqualified or missing deal-level budget/timeline.
@@ -92,6 +128,203 @@ setLeadProducts({
 
 For qualification, convert via [convert.md](./convert.md).
 
+---
+
+## Referral UFs (Prerequisite)
+
+First-time referral mention each session → run `ensureReferralUFs` to verify the 5 user-fields exist on portal. Missing → confirm with user → `userfield.add`. Idempotent.
+
+### Required UFs
+
+| Entity | FIELD_NAME | XML_ID | USER_TYPE_ID | MULTIPLE | SETTINGS |
+|---|---|---|---|---|---|
+| CRM_CONTACT | UF_CRM_REFERRER | REFERRER | crm | N | `{ CONTACT: "Y" }` |
+| CRM_COMPANY | UF_CRM_REFERRER | REFERRER | crm | N | `{ CONTACT: "Y" }` |
+| CRM_DEAL | UF_CRM_REFERRER | REFERRER | crm | N | `{ CONTACT: "Y" }` |
+| CRM_LEAD | UF_CRM_REFERRER | REFERRER | crm | N | `{ CONTACT: "Y" }` |
+| CRM_CONTACT | UF_CRM_REFERRED_CONTACTS | REFERRED_CONTACTS | crm | **Y** | `{ CONTACT: "Y" }` |
+
+`USER_TYPE_ID="crm"` binds UF → CRM **entity records** (not UF↔UF). Reverse sync is app logic.
+
+### Discovery — filter by XML_ID, not FIELD_NAME
+
+```js
+async function ensureReferralUFs() {
+  const required = [
+    { entity: 'CONTACT', list: 'crm.contact.userfield.list', add: 'crm.contact.userfield.add', xmlIds: ['REFERRER', 'REFERRED_CONTACTS'] },
+    { entity: 'COMPANY', list: 'crm.company.userfield.list', add: 'crm.company.userfield.add', xmlIds: ['REFERRER'] },
+    { entity: 'DEAL',    list: 'crm.deal.userfield.list',    add: 'crm.deal.userfield.add',    xmlIds: ['REFERRER'] },
+    { entity: 'LEAD',    list: 'crm.lead.userfield.list',    add: 'crm.lead.userfield.add',    xmlIds: ['REFERRER'] },
+  ];
+  const missing = [];
+  for (const r of required) {
+    const res = await codemode.request({ method: 'POST', path: `/${r.list}/`, body: { filter: {} } });
+    const fields = res.result || res;
+    for (const xml of r.xmlIds) {
+      if (!fields.find(f => f.XML_ID === xml)) missing.push({ entity: r.entity, xml, add: r.add });
+    }
+  }
+  return missing;
+}
+```
+
+After first successful verify in a session → set `referralUFsReady = true`, skip subsequent calls.
+
+### User confirm gate
+
+If `missing.length > 0`, MUST `AskUserQuestion`:
+
+- Header: "UF setup"
+- Question: "Portal thiếu N userfield cần thiết cho referral tracking. Tạo bây giờ?"
+- Options:
+  - "Tạo tất cả ({list})" — call `userfield.add` per missing
+  - "Skip lần này" — abort referral flow, continue plain create
+  - "Hiển thị chi tiết" — show full spec, ask again
+
+### Create payloads
+
+REFERRER (single, forward — applies to contact/company/deal/lead):
+
+```js
+{
+  fields: {
+    FIELD_NAME: "UF_CRM_REFERRER",
+    USER_TYPE_ID: "crm",
+    XML_ID: "REFERRER",
+    MULTIPLE: "N",
+    MANDATORY: "N",
+    SHOW_FILTER: "I",
+    SHOW_IN_LIST: "Y",
+    EDIT_IN_LIST: "Y",
+    SETTINGS: { CONTACT: "Y" },
+    EDIT_FORM_LABEL: { vi: "Người giới thiệu", en: "Referrer" },
+    LIST_COLUMN_LABEL: { vi: "Người giới thiệu", en: "Referrer" },
+    SORT: 100
+  }
+}
+```
+
+REFERRED_CONTACTS (multiple, reverse — contact only):
+
+```js
+{
+  fields: {
+    FIELD_NAME: "UF_CRM_REFERRED_CONTACTS",
+    USER_TYPE_ID: "crm",
+    XML_ID: "REFERRED_CONTACTS",
+    MULTIPLE: "Y",
+    MANDATORY: "N",
+    SHOW_FILTER: "I",
+    SHOW_IN_LIST: "Y",
+    EDIT_IN_LIST: "Y",
+    SETTINGS: { CONTACT: "Y" },
+    EDIT_FORM_LABEL: { vi: "Khách đã giới thiệu", en: "Referred Customers" },
+    LIST_COLUMN_LABEL: { vi: "Khách đã giới thiệu", en: "Referred" },
+    SORT: 101
+  }
+}
+```
+
+### Error handling
+
+| Error | Action |
+|---|---|
+| `Access denied` (non-admin webhook) | Stop flow, show UF spec, ask admin to create manually |
+| `INTERNAL_SERVER_ERROR` (UF limit / timeout) | Show count from `userfield.list`, suggest cleanup |
+| Duplicate `FIELD_NAME` (race) | Treat as success, re-fetch to confirm XML_ID match |
+
+---
+
+## Lifecycle UF (Prerequisite)
+First-time contact/company create each session → perform this SOP to verify `UF_CRM_LIFECYCLE` exists on both entities. Missing/schema mismatch → confirm with user → `userfield.add` with 8-stage enumeration. After first verify → `lifecycleUFsReady = true`.
+
+### Required UFs
+- CONTACT + COMPANY runtime field: `UF_CRM_LIFECYCLE`; add payload field code: `FIELD_NAME=LIFECYCLE`; `USER_TYPE_ID=enumeration`, `MULTIPLE=N`, default `LEAD`.
+
+### Discovery + enum-ID cache
+
+```js
+// Pseudocode SOP: execute with codemode.request; not a named MCP helper.
+const lifecycleXmlIds = ['SUBSCRIBER', 'LEAD', 'MQL', 'SQL', 'OPPORTUNITY', 'CUSTOMER', 'EVANGELIST', 'OTHER'];
+const validLifecycleUF = f => {
+  const list = f?.LIST || [], ids = new Set(list.map(x => x.XML_ID));
+  return f?.FIELD_NAME === 'UF_CRM_LIFECYCLE' && f.USER_TYPE_ID === 'enumeration' && f.MULTIPLE === 'N'
+    && lifecycleXmlIds.every(x => ids.has(x)) && list.find(x => x.XML_ID === 'LEAD')?.DEF === 'Y';
+};
+async function lifecycleUfSop() {
+  const required = [{ entity: 'CONTACT', list: 'crm.contact.userfield.list', add: 'crm.contact.userfield.add' },
+    { entity: 'COMPANY', list: 'crm.company.userfield.list', add: 'crm.company.userfield.add' }];
+  const missing = [], enumCache = { CONTACT: {}, COMPANY: {} };
+
+  for (const r of required) {
+    try {
+      const res = await codemode.request({ method: 'POST', path: `/${r.list}/`, body: { filter: {} } });
+      const f = (res.result || res).find(x => x.XML_ID === 'LIFECYCLE');
+      if (!validLifecycleUF(f)) missing.push({ entity: r.entity, add: r.add, reason: f ? 'schema mismatch' : 'missing' });
+      else for (const item of f.LIST) enumCache[r.entity][item.XML_ID] = item.ID;
+    } catch (error) {
+      return { ok: false, error, missing: [{ entity: r.entity, add: r.add, reason: 'list failed' }], enumCache };
+    }
+  }
+  return { ok: true, missing, enumCache };
+}
+```
+Cache shape: `{ CONTACT: { LEAD: 1102 }, COMPANY: { LEAD: 1202 } }`. Resolve XML_ID → numeric before write. After `userfield.add`, re-fetch `userfield.list`.
+
+### Create payload
+```js
+{
+  fields: {
+    FIELD_NAME: "LIFECYCLE",
+    USER_TYPE_ID: "enumeration",
+    XML_ID: "LIFECYCLE",
+    MULTIPLE: "N",
+    MANDATORY: "N",
+    SHOW_FILTER: "I",
+    SHOW_IN_LIST: "Y",
+    EDIT_IN_LIST: "Y",
+    EDIT_FORM_LABEL: { vi: "Giai đoạn vòng đời", en: "Lifecycle Stage" },
+    LIST_COLUMN_LABEL: { vi: "Vòng đời", en: "Lifecycle" },
+    SORT: 110,
+    LIST: [
+      { VALUE: "Subscriber",  DEF: "N", SORT: 100, XML_ID: "SUBSCRIBER" },
+      { VALUE: "Lead",        DEF: "Y", SORT: 200, XML_ID: "LEAD" },
+      { VALUE: "MQL",         DEF: "N", SORT: 300, XML_ID: "MQL" },
+      { VALUE: "SQL",         DEF: "N", SORT: 400, XML_ID: "SQL" },
+      { VALUE: "Opportunity", DEF: "N", SORT: 500, XML_ID: "OPPORTUNITY" },
+      { VALUE: "Customer",    DEF: "N", SORT: 600, XML_ID: "CUSTOMER" },
+      { VALUE: "Evangelist",  DEF: "N", SORT: 700, XML_ID: "EVANGELIST" },
+      { VALUE: "Other",       DEF: "N", SORT: 800, XML_ID: "OTHER" }
+    ]
+  }
+}
+```
+### User confirm gate
+If `missing.length > 0`, MUST `AskUserQuestion`: header "UF setup"; question "Portal thiếu UF_CRM_LIFECYCLE trên N entity. Tạo bây giờ với 8 giai đoạn HubSpot-style?"; options "Tạo tất cả ({list})" / "Skip lần này" / "Hiển thị chi tiết".
+
+### Error handling
+
+| Error | Action |
+|---|---|
+| `Access denied` | Stop lifecycle flow, show UF spec, ask admin to create manually |
+| `INTERNAL_SERVER_ERROR` | Show `userfield.list` count, suggest cleanup/retry |
+| Duplicate `FIELD_NAME` | Treat as success, re-fetch to confirm XML_ID match |
+| Cache miss for XML_ID | Re-fetch field LIST once; if still missing, ask user to pick a valid stage |
+
+Lifecycle classification + integration → [lifecycle.md](./lifecycle.md). Load when creating contact/company.
+
+---
+
+## Referral Flow + Source Auto-Detection
+
+Moved to [referral.md](./referral.md):
+- **Referral Flow** — detect "do/được X giới thiệu" → resolve referrer → forward + reverse UF linking.
+- **Source Auto-Detection** — keyword-scored `SOURCE_ID` pick with confidence threshold + ask fallback. Forces `RECOMMENDATION` when referrer active.
+
+Load `referral.md` when: user mentions referrer; OR when creating lead/deal and SOURCE_ID is unclear.
+
+---
+
 ## Update Existing Entity
 
 1. Search before update: `codemode.search({ keywords, entities: ["contact","company","deal","lead"], intent: "read" })`.
@@ -129,6 +362,10 @@ Omit `idempotencyKey`. **Verified 2026-05-15:** D1 table `idempotency_keys` miss
 - [ ] Contact: VN phone stored with `+84`; HONORIFIC matches [vn-norms.md](./vn-norms.md).
 - [ ] Company: `RQ_VAT_ID` populated, address entity exists, MST format valid.
 - [ ] Deal: `STAGE_ID` set, `OPPORTUNITY > 0`, payer linked.
+- [ ] Deal (with products): products set; `OPPORTUNITY` matches product total.
+- [ ] Deal/Lead: `SOURCE_ID` non-empty; matches detect result or user pick.
+- [ ] Referral: `UF_CRM_REFERRER` populated if referrer mentioned; referrer's `UF_CRM_REFERRED_CONTACTS` updated (contact target only).
+- [ ] Lifecycle: `UF_CRM_LIFECYCLE` set on contact/company; numeric enum ID resolved from cache (not raw XML_ID).
 - [ ] Lead: `SOURCE_ID` set, phone/email present, products set when user requested products.
 - [ ] Update: only intended fields changed.
 
@@ -142,4 +379,8 @@ Omit `idempotencyKey`. **Verified 2026-05-15:** D1 table `idempotency_keys` miss
 | `crm.contact.add` directly | No dedup, phone not normalized | `upsertContact` |
 | `crm.company.add` directly | Requisite missing tax fields + address | `upsertCompanyByTaxCode` |
 | Passed `idempotencyKey` | D1 table error at runtime | Omit the field |
+| Webhook user not admin | `Access denied` on `userfield.add` | Document UF spec, ask admin to add manually |
+| Set REFERRER without reverse update | Referrer can't see who they referred in UI | Run forward + reverse UF write (referral.md steps 4-5) |
+| Force `RECOMMENDATION` without referrer | Wrong attribution | Only force when `referralActive` flag true |
+| Wrote XML_ID string to `UF_CRM_LIFECYCLE` | Bitrix rejects / silently stores wrong value | Resolve XML_ID → numeric via `enumCache[entity][XML_ID]` before write |
 | Skipped verify step | Bugs discovered sessions later | Always verify |

package/src/features/bx-crm/assets/referral.md

@@ -0,0 +1,231 @@
+# bx:crm — Referral + Source Detection
+
+Detection, linking, and SOURCE_ID auto-pick. Load when user mentions referrer or when SOURCE_ID is unclear during lead/deal creation. UF prereq lives in [onboard.md § Referral UFs](./onboard.md#referral-ufs-prerequisite) — run `ensureReferralUFs` once per session before the flows below.
+
+---
+
+## Referral Flow
+
+Detect "do/được X giới thiệu" mentions → resolve referrer contact → set forward UF on target → append reverse UF on referrer.
+
+### Trigger keywords (case-insensitive, substring)
+
+| Pattern | Capture |
+|---|---|
+| `(được\|do)\s+(.+?)\s+giới thiệu` | $2 |
+| `giới thiệu (bởi\|từ)\s+(.+)` | $2 |
+| `(khách\|người)\s+của\s+(anh\|chị)\s+(.+)` | $3 |
+| `từ cộng đồng (của\|c\.)\s+(.+)` | $2 |
+| `referral from\s+(.+)` | $1 |
+| `introduced by\s+(.+)` | $1 |
+| `refer(red)? (by\|từ)\s+(.+)` | $3 |
+| `partner contact\s+(.+)` | $1 |
+
+**Negation guard:** "không có ai giới thiệu" / "no referrer" → skip flow.
+
+Strip trailing tokens ("ạ", "nha", "anh ấy"...) and trim. Show extracted name to user for verification before search.
+
+### Flow
+
+```mermaid
+flowchart TD
+    A[Mention detected] --> B[Extract name]
+    B --> C{Confirm with user}
+    C -->|adjust| B
+    C -->|OK| D[Search existing contacts]
+    D --> E{Found?}
+    E -->|1 match| F[Confirm referrer]
+    E -->|N matches| G[User picks from list]
+    E -->|none| H[Collect name+phone/email+HONORIFIC]
+    H --> I[upsertContact create]
+    F --> J[referrerContactId]
+    G --> J
+    I --> J
+    J --> K[Create target with UF_CRM_REFERRER]
+    K --> L[Force SOURCE_ID=RECOMMENDATION on lead/deal]
+    L --> M[Read referrer's REFERRED_CONTACTS]
+    M --> N[Append targetId if target=contact]
+    N --> O[Write merged array back]
+```
+
+### Steps
+
+**1. Confirm name.** `AskUserQuestion` header "Referrer": "Người giới thiệu tên là '{extracted}' đúng không?" — options: ["Đúng", "Đổi tên...", "Bỏ qua referral"].
+
+**2. Find referrer.**
+
+```js
+codemode.search({
+  keywords: [referrerName, ...nameTokens(referrerName)],
+  entities: ["contact"],
+  intent: "read",
+  topK: 5
+})
+```
+
+- 1 exact + similarity ≥ 95% → confirm "Anh/chị X (0xxx...xxx) phải không?"
+- N matches → list with phone/email masked, user picks
+- 0 → create flow
+
+**3. Create referrer (if not found).** Collect: name (have), phone OR email, HONORIFIC (per [vn-norms.md](./vn-norms.md)). Then:
+
+```js
+upsertContact({
+  name: extractedName,
+  phone: collected.phone,
+  email: collected.email,
+  HONORIFIC: collected.honorific,
+  match: collected.phone ? { phone: collected.phone } : { email: collected.email }
+})
+```
+
+**4. Link forward UF on target.**
+
+- **Contact:** `crm.contact.update` with `fields: { UF_CRM_REFERRER: referrerContactId }`
+- **Company:** `crm.company.update` same shape
+- **Deal:** via `createDealWithParties` add `UF_CRM_REFERRER` + `SOURCE_ID: "RECOMMENDATION"` to `fields`
+- **Lead:** via `createLeadWithParties` add `UF_CRM_REFERRER` + `sourceId: "RECOMMENDATION"`
+
+**5. Reverse append on referrer.** Read → merge dedup → write:
+
+```js
+// Guard: self-refer not allowed
+if (String(referrerContactId) === String(targetContactId)) {
+  throw new Error('Referrer cannot reference itself; ask user to re-confirm');
+}
+
+const r = await codemode.request({ method: 'POST', path: '/crm.contact.get/', body: { id: referrerContactId } });
+const raw = r.result?.UF_CRM_REFERRED_CONTACTS;
+const current = Array.isArray(raw) ? raw : []; // never-set multi UF may return false/null
+if (targetEntityType === 'CONTACT') {
+  const merged = [...new Set([...current, String(targetContactId)])];
+  await codemode.request({
+    method: 'POST', path: '/crm.contact.update/',
+    body: { id: referrerContactId, fields: { UF_CRM_REFERRED_CONTACTS: merged } }
+  });
+  // Race verify: re-read; if targetContactId missing, retry merge once.
+}
+```
+
+Reverse field stores **contact IDs only**. For deal/lead/company targets, link forward only; optionally append the deal's primary contact party if attached.
+
+### Race condition
+
+2 concurrent referrals for same referrer → may lose 1 ID. Mitigation: re-read after write, retry merge once if mismatch.
+
+### SOURCE_ID coupling
+
+Referral active → Lead/Deal force `SOURCE_ID = "RECOMMENDATION"` (skip auto-detect). Contact/Company: no SOURCE_ID field, skip. Log: "Source set to RECOMMENDATION (referrer detected)".
+
+### Edge cases
+
+| Case | Handling |
+|---|---|
+| Ambiguous ("anh X" no surname) | List top-5 named X, user picks |
+| Self-refer (referrer == target) | Reject + ask user re-confirm |
+| User skips mid-flow | Skip UF link, plain create, run Source Auto-Detection |
+| upsertContact dedup hit existing | Reuse found ID, no duplicate |
+
+---
+
+## Source Auto-Detection
+
+Auto-pick `SOURCE_ID` for lead/deal from user context. Referrer present → force `RECOMMENDATION`. Else keyword score → top-1 if confidence ≥80%, else `AskUserQuestion` top-3.
+
+### Keyword → STATUS_ID
+
+| STATUS_ID | Triggers |
+|---|---|
+| `RECOMMENDATION` | (forced when referral active) |
+| `PARTNER` | "khách cũ", "existing", "đối tác", "partner" |
+| `WEB` | "website", "web", "trang chủ", "homepage" |
+| `WEBFORM` | "form", "crm form", "đăng ký form" |
+| `CALL` | "gọi", "call", "điện thoại", "phone call" |
+| `EMAIL` | "email", "mail", "thư điện tử" |
+| `ADVERTISING` | "quảng cáo", "ad", "ads", "advertising" |
+| `TRADE_SHOW` | "sự kiện", "event", "exhibition", "triển lãm", "hội chợ" |
+| `STORE` | "store", "shop", "cửa hàng" |
+| `REPEAT_SALE` | "mua lại", "repeat", "tái mua" |
+| `OTHER` | (final fallback) |
+
+### Channel-specific (open-channel sources)
+
+| STATUS_ID | Match |
+|---|---|
+| `*\|FACEBOOK` | "facebook", "fb", "messenger" |
+| `*\|FACEBOOKCOMMENTS` | "comment fb", "fb comment" |
+| `24\|SYNITY_ZALO_OA_CHAT` | "zalo oa", "zalo official", "zalo synity" |
+| `26\|SYNITY_ZALO_BOT` | "zalo bot" |
+| `28\|SYNITY_ZALO_PERSONAL` | "zalo cá nhân chinh" |
+| `*\|TELEGRAM` | "telegram", "tele" |
+| `*\|OPENLINE` | "live chat", "livechat" |
+
+Runtime fetch `crm.status.list ENTITY_ID=SOURCE` to avoid stale list.
+
+### Algorithm
+
+```
+INPUT: userRequestText, referralActive
+CONST gap = 0.2          # min score-delta to consider top[0] clearly ahead of top[1]
+CONST scoreUnit = 5      # keyword.length / scoreUnit; longer keyword = stronger signal
+IF referralActive:
+  RETURN { sourceId: "RECOMMENDATION", confidence: 1.0, reason: "referrer detected" }
+
+sources = crm.status.list ENTITY_ID=SOURCE
+scores = []
+FOR each source IN sources:
+  score = 0; matched = []
+  FOR each keyword IN keywordTable[source.STATUS_ID]:
+    IF normalize(userRequestText).includes(normalize(keyword)):
+      score += keyword.length / scoreUnit
+      matched.push(keyword)
+  IF score > 0: scores.push({ source, score, matched })
+
+top = scores.sort(desc by score).slice(0, 3)
+IF top.length === 0:
+  RETURN { needsAsk: true, candidates: defaultTop5(), reason: "no keyword match" }
+
+confidence = top[0].score / sum(scores.score)
+IF confidence >= 0.8 AND (top[0].score - (top[1]?.score || 0)) > gap:
+  RETURN { sourceId: top[0].source.STATUS_ID, confidence, reason: top[0].matched }
+
+RETURN { needsAsk: true, candidates: top, reason: "ambiguous match" }
+```
+
+### Heuristic shortcuts
+
+| Signal | Auto-pick |
+|---|---|
+| Explicit "source là facebook" | Exact match, confidence=1.0 |
+| Phone-only contact | Default `CALL`, confidence=0.7 → ask |
+| Form submission | `WEBFORM`, confidence=0.9 |
+| Email-only inbound | `EMAIL`, confidence=0.85 |
+| "mua lại" exact | `REPEAT_SALE` over `PARTNER` |
+
+### Diacritic normalization (VN)
+
+```js
+const norm = s => s.toLowerCase()
+  .normalize('NFD')
+  .replace(/[\u0300-\u036f]/g, '')
+  .replace(/đ/g, 'd');
+```
+
+"quang cao" or "quảng cáo" → same match.
+
+### Ask fallback
+
+`needsAsk: true` → `AskUserQuestion` header "Source", question "Source nào phù hợp nhất? (matched: {keywords})", options = top-3 source NAME + matched keywords. Zero match → default top-5: `CALL, WEB, RECOMMENDATION, ADVERTISING, OTHER`.
+
+### Logging
+
+```
+[Source] auto-picked "Facebook - FB Page" (confidence 0.92, matched: "facebook", "fb page")
+```
+
+User can override → revert to ask.
+
+### Entity coupling
+
+- **Lead/Deal:** `SOURCE_ID` required (1 per entity).
+- **Contact/Company:** no SOURCE_ID field; skip. If part of `createDealWithParties` → apply to the deal.

package/src/features/bx-crm/feature.json

@@ -1,14 +1,14 @@
 {
   "name": "bx-crm",
   "displayName": "Bitrix CRM Skill",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "target": "global",
   "description": "Claude Code skill for Bitrix24 CRM: contacts, companies, deals, leads, estimates, invoices, customer analysis, pipeline reports",
-  "status": "planned",
+  "status": "active",
   "requires": {
     "mcp": [
       "bitrix-synity-mcp"
     ]
   },
   "tier": 0
-}
+}