@synity/bitrix-skills 1.3.0 → 1.3.2

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

@@ -0,0 +1,103 @@
+# bx:crm — Document Template Fill
+
+Covers document and PDF generation for contracts, quotes, invoices, and CRM templates.
+
+---
+
+## Trigger Phrases
+
+- "render document", "fill contract", "generate PDF"
+- "tạo báo giá PDF", "fill hợp đồng", "xuất PDF", "tạo hợp đồng từ deal"
+
+---
+
+## Strategy
+
+Primary flow: use Bitrix native `crm.documentgenerator.*` REST via `codemode.request`.
+
+Fallback flow: user provides a template file/link/text; fetch CRM data, propose a mapping table, and let the user run the final fill in their template tool.
+
+---
+
+## Primary Flow — Bitrix Document Generator
+
+```js
+// 1. List templates
+codemode.request({
+  method: "GET",
+  path: "/crm.documentgenerator.template.list/"
+})
+
+// 2. Pick template by NAME and supported entity type.
+
+// 3. Render document
+codemode.request({
+  method: "POST",
+  path: "/crm.documentgenerator.document.add/",
+  body: {
+    templateId,
+    entityTypeId,
+    entityId,
+    values: {}
+  }
+})
+```
+
+Typical return: `{ document: { id, fileUrl } }`.
+
+Use Bitrix `entityTypeId` values discovered from the portal; do not hardcode if uncertain.
+
+---
+
+## Verify Checklist — Primary
+
+- [ ] Template supports the selected `entityTypeId`.
+- [ ] `entityId` belongs to the intended customer/deal.
+- [ ] `fileUrl` returned and is accessible to the intended user.
+- [ ] Visual check confirms placeholders are filled.
+
+---
+
+## Fallback Flow — User Paste
+
+1. Ask user for template path, URL, or pasted fields.
+2. Fetch CRM data with read helpers only: deal, contact, company, products, estimate/invoice if needed.
+3. Present a mapping table:
+
+```text
+| Placeholder | CRM source | Value preview |
+|---|---|---|
+| {{CompanyName}} | company.RQ_COMPANY_FULL_NAME | ... |
+| {{TaxCode}} | company.RQ_VAT_ID | ... |
+| {{DealTotal}} | deal.OPPORTUNITY + CURRENCY_ID | ... |
+```
+
+4. Ask user to confirm mapping before any generated document is shared.
+
+---
+
+## Verify Checklist — Fallback
+
+- [ ] Mapping table reviewed by user.
+- [ ] No placeholder left unmapped unless user accepts it.
+- [ ] Sensitive data appears only for the intended entity.
+- [ ] Final document is visually checked before sending.
+
+---
+
+## Pitfalls
+
+| Pitfall | Risk | Action |
+|---|---|---|
+| Hardcoded `templateId` | Wrong portal template | Always list templates first |
+| Entity type mismatch | 4xx or blank fields | Match template to entity type |
+| Wrong `entityId` | PII leak | Verify ownership before render |
+| Synity Docs MCP assumed | Tool unavailable | Use generic fallback flow |
+
+---
+
+## See Also
+
+- Entity preparation: [onboard.md](./onboard.md)
+- Estimate/invoice context: [commerce.md](./commerce.md)
+- Contract PDF combos: [flows.md](./flows.md)

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

@@ -0,0 +1,144 @@
+# bx:crm — Cross-Flow Combos
+
+Use this file when the user asks for a multi-helper CRM workflow.
+
+---
+
+## Combo Template
+
+Each combo includes trigger phrases, sequence, verify checks, and underlying SOP files. On failure mid-chain, stop and report created IDs.
+
+---
+
+## Combo 1 — Deal + Estimate
+
+**Trigger:** "tạo deal kèm báo giá", "deal with quote".
+
+**Sequence:**
+```js
+const deal = await createDealWithParties({ contact, company, deal })
+await setDealProducts({ dealId: deal.dealId, products })
+const estimate = await createEstimate({ dealId: deal.dealId, title, currency })
+await setEstimateProducts({ estimateId: estimate.estimateId, products })
+```
+
+**Verify:** dealId + estimateId returned; products and currency match.
+
+**See also:** [onboard.md](./onboard.md), [commerce.md](./commerce.md)
+
+---
+
+## Combo 2 — Deal + Invoice
+
+**Trigger:** "tạo deal kèm invoice", "deal with invoice".
+
+**Sequence:**
+```js
+const deal = await createDealWithParties({ contact, company, deal })
+await setDealProducts({ dealId: deal.dealId, products })
+// Run commerce.md steps 1-7: estimate -> confirmation -> approve -> invoice.
+// Do not create an invoice directly from a new deal.
+```
+
+**Verify:** estimate approved first; invoice status is `N`; payer and products are linked.
+
+**See also:** [onboard.md](./onboard.md), [commerce.md](./commerce.md)
+
+---
+
+## Combo 3 — Lead → Deal
+
+**Trigger:** "convert lead", "qualify lead", "chuyển lead thành deal".
+
+**Sequence:**
+```js
+await setLeadProducts({ leadId, products }) // only if products are provided
+const result = await convertLeadToDeal({
+  leadId,
+  createDealParams: { stageId, categoryId },
+  upsertContact: true,
+  upsertCompany: true
+})
+```
+
+**Verify:** lead is converted; deal exists; contact/company linked; warnings reviewed.
+
+**See also:** [convert.md](./convert.md), [onboard.md](./onboard.md)
+
+---
+
+## Combo 4 — Báo Giá → Hợp Đồng PDF
+
+**Trigger:** "duyệt báo giá rồi tạo hợp đồng PDF", "quote to contract PDF".
+
+**Sequence:**
+```js
+await approveEstimate({ estimateId })
+await closeEstimatesForDeal({ dealId })
+// Then run document.md Primary Flow: list templates, verify entity, render.
+```
+
+**Verify:** estimate approved; other estimates closed; document URL returned.
+
+**See also:** [commerce.md](./commerce.md), [document.md](./document.md)
+
+---
+
+## Combo 5 — Quote-to-Cash Full
+
+**Trigger:** "full quote to cash", "đầy đủ báo giá đến hóa đơn".
+
+**Sequence:**
+```js
+const deal = await createDealWithParties({ contact, company, deal })
+await setDealProducts({ dealId: deal.dealId, products })
+const estimate = await createEstimate({ dealId: deal.dealId, title, currency })
+await setEstimateProducts({ estimateId: estimate.estimateId, products })
+// STOP. Do not continue until customer/user confirms the estimate.
+```
+
+**Post-confirmation sequence:**
+```js
+await approveEstimate({ estimateId: estimate.estimateId })
+await closeEstimatesForDeal({ dealId: deal.dealId })
+const invoice = await createSmartInvoice({ dealId: deal.dealId, contactId: deal.contactId, companyId: deal.companyId })
+await copyDealProductsToInvoice({ dealId: deal.dealId, invoiceId: invoice.invoiceId })
+// Then run document.md Primary Flow for invoice PDF.
+```
+
+**Verify:** deal, estimate, invoice, products, payer, and document URL all pass their subfile checklists.
+
+**See also:** [onboard.md](./onboard.md), [commerce.md](./commerce.md), [document.md](./document.md)
+
+---
+
+## Combo 6 — Payment Link Send
+
+**Trigger:** "gửi link thanh toán", "send payment link".
+
+**Sequence:**
+```js
+// Start from an existing approved invoice or run Combo 5 through invoice creation.
+const paysystems = await codemode.request({ method: "GET", path: "/sale.paysystem.list/" })
+// Only use a portal-approved payment URL generator/API. Do not hand-construct signed URLs.
+```
+
+**Verify:** invoice exists; payer linked; URL belongs to invoice and intended customer.
+
+**See also:** [commerce.md](./commerce.md)
+
+---
+
+## Global Cross-Flow Rules
+
+- If any write fails mid-chain, stop and report partial state with IDs.
+- Never auto-rollback; helpers do not guarantee rollback support.
+- Do not use `idempotencyKey` until MCP D1 migration is fixed.
+- Keep currency consistent through deal, estimate, invoice, and product rows.
+
+## Verify Checklist
+
+- [ ] Every write step had user confirmation or an approved prior checkpoint.
+- [ ] Invoice was created only after estimate approval unless user supplied an existing approved invoice.
+- [ ] Document rendering followed [document.md](./document.md) template/entity checks.
+- [ ] Partial failures reported created IDs and next manual action.

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

@@ -1,32 +1,12 @@
 # bx:crm — Onboard (Write SOP)
 
-Covers: contact, company (VN), deal, lead creation.
+Covers: contact, company (VN), deal, lead creation, and safe updates.
 
----
-
-## Phone Normalization (CRITICAL)
-
-`upsertContact` auto-normalizes — **pass raw phone, never pre-format**.
-
-| Input | Stored as |
-|-------|-----------|
-| `0977680550` | `+84977680550` |
-| `0977 68 0550` | `+84977680550` |
-| `84977680550` | `+84977680550` |
-| `+84977680550` | `+84977680550` (idempotent) |
-| `+6591234567` | `+6591234567` (non-VN: keep) |
+## Phone + VN Normalization
 
----
-
-## HONORIFIC
+See [vn-norms.md](./vn-norms.md) for phone `+84`, HONORIFIC, address, and MST rules.
 
-| Input | Value |
-|-------|-------|
-| Anh / Mr | `Anh` |
-| Chị / Ms / Mrs | `Chị` |
-| Ông (senior male) | `Ông` |
-| Bà (senior female) | `Bà` |
-| Unknown | omit field |
+`upsertContact` auto-normalizes phone numbers. Pass raw phone, never pre-format.
 
 ---
 
@@ -35,93 +15,131 @@ Covers: contact, company (VN), deal, lead creation.
 ```js
 upsertContact({
   name: "Nguyen Van A",
-  phone: "0977680550",      // raw — helper normalizes
+  phone: "0977680550",
   email: "a@example.com",
   HONORIFIC: "Anh",
-  match: { phone }          // dedup check before create
+  match: { phone }
 })
 ```
 
-Minimum: `name` + (`phone` OR `email`) + `HONORIFIC` (if determinable).
-
----
+Minimum: `name` + (`phone` OR `email`) + `HONORIFIC` if determinable. See [vn-norms.md](./vn-norms.md) for the HONORIFIC table.
 
 ## Company — VN Rule (CRITICAL)
 
-**NEVER `crm.company.add` directly for VN companies with MST.**
+**Never call `crm.company.add` directly for VN companies with MST.**
 
 `upsertCompanyByTaxCode` auto-does:
-1. VietQR lookup → legal name + address from GDT tax registry
-2. Sets `RQ_INN` = `RQ_VAT_ID` = taxCode on requisite
-3. Creates address entity (needed for `{CompanyAddressLegal}` in document templates)
+1. VietQR lookup → legal name + address from GDT tax registry.
+2. Sets `RQ_INN` = `RQ_VAT_ID` = taxCode on requisite.
+3. Creates address entity for document templates.
 
 ```js
 upsertCompanyByTaxCode({
-  taxCode: "0315427733",   // MST — REQUIRED
-  title: "Pegasus Realty", // optional, VietQR fills if missing
+  taxCode: "0315427733",
+  title: "Pegasus Realty",
   phone: "...",
-  email: "...",
+  email: "..."
 })
 ```
 
-**Verify checklist for company:**
-- `RQ_INN` populated
-- `RQ_VAT_ID` populated (same value)
-- `RQ_COMPANY_FULL_NAME` populated (legal name from registry)
-- Address entity exists (ENTITY_TYPE_ID=8)
-
----
+**Verify company:**
+- `RQ_INN` and `RQ_VAT_ID` populated.
+- `RQ_COMPANY_FULL_NAME` populated from registry.
+- Address entity exists (`ENTITY_TYPE_ID=8`).
 
 ## Deal — Required Fields
 
-Use `createDealWithParties` for atomic contact + company + deal in one call.
+Use `createDealWithParties` for atomic contact + company + deal.
 
 | Field | How to get | Example |
-|-------|-----------|---------|
-| `STAGE_ID` | `codemode.entityIds()` → dealStageSemanticId | **never hardcode** |
-| `CURRENCY_ID` | from user input | `USD`, `VND` |
-| `OPPORTUNITY` | from user input (number) | `588` |
-| `SOURCE_ID` | see mapping below | `OTHER` |
-
-**SOURCE_ID mapping:**
-
-| Context | Value |
-|---------|-------|
-| Event / offline meeting | `OTHER` |
-| Website / form | `WEB` |
-| Referral / partner | `PARTNER` |
-| Cold call / outreach | `CALL` |
-| Social / ad | `ADVERTISING` |
+|---|---|---|
+| `STAGE_ID` | `codemode.entityIds()` | never hardcode |
+| `CURRENCY_ID` | user input | `USD`, `VND` |
+| `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`.
 
 **COMMENTS — BANT template:**
+```text
+Budget: <amount/range/unknown>
+Authority: <decision maker>
+Need: <problem or goal>
+Timeline: <start date>
+Notes: <context>
 ```
-Budget: <amount or range, or "unknown">
-Authority: <who makes the decision>
-Need: <specific problem / goal>
-Timeline: <when they want to start>
-Notes: <additional context>
+
+## Lead — Create + Products
+
+Use lead when the prospect is unqualified or missing deal-level budget/timeline.
+
+```js
+createLeadWithParties({
+  title: "Nguyen Van A - CRM training",
+  name: "Nguyen Van A",
+  phone: "0977680550",
+  email: "a@example.com",
+  companyTitle: "ABC Training",
+  sourceId: "WEB",
+  comments: "Need: CRM training\nTimeline: Q2"
+})
+
+setLeadProducts({
+  leadId,
+  products: [{ name: "Workshop", price: 5000000, quantity: 1, currency: "VND" }]
+})
 ```
 
-> **Omit `idempotencyKey`** — causes D1 table error at runtime.
+For qualification, convert via [convert.md](./convert.md).
+
+## Update Existing Entity
+
+1. Search before update: `codemode.search({ keywords, entities: ["contact","company","deal","lead"], intent: "read" })`.
+2. Read current entity by ID and validate target ownership.
+3. Discover allowed fields with `crm.{entity}.fields` when field names are uncertain.
+4. Show before/after field diff and confirm every update, even for a single match.
+5. Send only changed fields.
+
+```js
+// MCP gap fallback when no typed update helper exists.
+codemode.request({
+  method: "POST",
+  path: "/crm.deal.update/",
+  body: { id: dealId, fields: { OPPORTUNITY: 9000000, ASSIGNED_BY_ID: 12 } }
+})
+```
+
+Skip this search rule for `upsertContact` and `upsertCompanyByTaxCode`; they dedup internally.
+
+## Custom Fields & Routing
+
+- `UF_CRM_*`: discover with `codemode.entityIds()` or `crm.{entity}.fields`.
+- `categoryId`: route deal to the correct pipeline.
+- `assignedById`: responsible user. Resolve user IDs before writing.
+- Do not echo full custom-field PII unless user explicitly asks.
+
+## Idempotency
+
+Omit `idempotencyKey`. **Verified 2026-05-15:** D1 table `idempotency_keys` missing; passing the key throws `SQLITE_ERROR` before write. Re-verify when MCP version changes. Escalation: MCP team.
 
 ---
 
 ## Verify Checklist (mandatory after every write op)
 
-- [ ] Contact: `PHONE[0].VALUE` starts with `+84` for VN numbers
-- [ ] Company: `RQ_VAT_ID` populated, address entity exists
-- [ ] Deal: `STAGE_ID` set, `OPPORTUNITY > 0`, payer linked
-- [ ] Lead: `SOURCE_ID` set, phone/email present
+- [ ] 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.
+- [ ] Lead: `SOURCE_ID` set, phone/email present, products set when user requested products.
+- [ ] Update: only intended fields changed.
 
 ---
 
 ## Known Pitfalls
 
 | Mistake | Symptom | Fix |
-|---------|---------|-----|
-| Used `bx-task` for CRM | Creates project task, not CRM record | Use `/bx:crm` |
+|---|---|---|
+| Used `bx:task` for CRM | Creates project task, not CRM record | Use `/bx:crm` |
 | `crm.contact.add` directly | No dedup, phone not normalized | `upsertContact` |
-| `crm.company.add` directly | Requisite missing RQ_VAT_ID + no address | `upsertCompanyByTaxCode` |
+| `crm.company.add` directly | Requisite missing tax fields + address | `upsertCompanyByTaxCode` |
 | Passed `idempotencyKey` | D1 table error at runtime | Omit the field |
-| Pre-formatted phone `+84977...` | Helper double-normalizes (idempotent, fine) | Pass raw anyway |
 | Skipped verify step | Bugs discovered sessions later | Always verify |

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

@@ -4,10 +4,16 @@ Covers: dealForecast, stuckInStage, overdueActivities, arReport, teamReport.
 
 ---
 
+## Timezone
+
+MCP may return UTC ISO timestamps. Convert display times to Asia/Saigon (UTC+7). Date-only summaries use the Asia/Saigon date.
+
+---
+
 ## Helper Selection
 
 | Report | Helper | Typical Frequency |
-|--------|--------|-------------------|
+|---|---|---|
 | Pipeline forecast month/quarter | `dealForecast` | Weekly |
 | Deals stuck too long in stage | `stuckInStage` | Weekly |
 | Overdue activities | `overdueActivities` | Daily |
@@ -19,61 +25,71 @@ Covers: dealForecast, stuckInStage, overdueActivities, arReport, teamReport.
 
 ## Output Template — dealForecast
 
-```
-| Month  | Predicted | Won | At Risk | # Deals |
-|--------|-----------|-----|---------|---------|
-| T5/26  | $X        | $Y  | $Z      | N       |
+```text
+| Month | Predicted | Won | At Risk | # Deals |
+|---|---:|---:|---:|---:|
+| T5/26 | $X | $Y | $Z | N |
 ```
 
-Red flags: deals in same stage > 30 days with no activity → highlight with 🔴.
+Red flags: deals in same stage > 30 days with no activity.
 
 ---
 
 ## Output Template — stuckInStage
 
-Group by pipeline stage → sort by days stuck DESC within each group.
+Group by pipeline stage. Sort by days stuck DESC within each group.
 
-**Top 5 per stage:**
-```
+```text
 Stage: [Stage Name]
-  1. [dealId] "[title]" — [owner] — [N] days — last activity: [date]
-  2. ...
+1. [dealId] "[title]" — [owner] — [N] days — last activity: [date]
 ```
 
 ---
 
 ## Output Template — overdueActivities
 
-```
+```text
 | Deal/Contact | Activity | Assigned | Due | Days Overdue |
-|-------------|----------|----------|-----|--------------|
-| ...         | ...      | ...      | ... | N            |
+|---|---|---|---|---:|
+| ... | ... | ... | ... | N |
 ```
 
-Sort by days overdue DESC. Group by assignee if > 10 items.
+Sort by days overdue DESC. Group by assignee if more than 10 items.
 
 ---
 
-## Output Template — arReport (Aging Buckets)
+## Output Template — arReport
 
+```text
+| Bucket | Amount | % of Total | # Invoices |
+|---|---:|---:|---:|
+| Current | $X | X% | N |
+| 1-30d | $X | X% | N |
+| 31-60d | $X | X% | N |
+| 61-90d | $X | X% | N |
+| 90d+ | $X | X% | N |
 ```
-| Bucket   | Amount | % of Total | # Invoices |
-|----------|--------|------------|------------|
-| Current  | $X     | X%         | N          |
-| 1–30d    | $X     | X%         | N          |
-| 31–60d   | $X     | X%         | N          |
-| 61–90d   | $X     | X%         | N          |
-| 90d+     | $X     | X%         | N          |  ← highlight if > 20%
+
+For 90d+ bucket: list each debtor below the table.
+
+---
+
+## Output Template — teamReport
+
+```text
+| Rep | # Deals | Total Value | Avg Response | Overdue |
+|---|---:|---:|---:|---:|
+| ... | N | $X | Nh | N |
 ```
 
-For 90d+ bucket: list each debtor individually below the table.
+Sort by Total Value DESC. Flag response time and overdue counts using the thresholds below.
 
 ---
 
 ## Interpretation Thresholds
 
-| Metric | Yellow ⚠️ | Red 🔴 | Action |
-|--------|----------|--------|--------|
+| Metric | Yellow | Red | Action |
+|---|---|---|---|
 | stuckInStage | > 14 days | > 30 days | Assign follow-up activity |
 | AR 90d+ bucket | > 10% total AR | > 20% total AR | Escalate to account manager |
 | teamReport response_time | > 12h | > 24h | Flag for coaching |
@@ -84,15 +100,30 @@ For 90d+ bucket: list each debtor individually below the table.
 ## Common Report Calls
 
 ```js
-// Weekly pipeline review
 dealForecast({ period: "month", includeAtRisk: true })
+stuckInStage({ minDays: 14, pipelineId: null })
+overdueActivities({ assignedTo: null })
+arReport({ groupByBucket: true, listDebtors90Plus: true })
+teamReport({ period: "month", includeResponseTime: true })
+```
+
+---
 
-// Stuck deals
-stuckInStage({ minDays: 14, pipelineId: null })  // null = all pipelines
+## Example Dialog — dealForecast
 
-// Daily overdue check
-overdueActivities({ assignedTo: null })  // null = all reps
+User: "review pipeline tuần này"
 
-// Monthly AR
-arReport({ groupByBucket: true, listDebtors90Plus: true })
+LLM behavior: call `dealForecast({ period: "month", includeAtRisk: true })`, convert dates to Asia/Saigon, then summarize risks.
+
+Sample output:
+```text
+Pipeline T5/26: predicted 1.2B VND, won 420M, at risk 180M across 4 deals.
+Red flag: 3 deals stuck >30 days with no recent activity.
+Next action: assign follow-up activities today for all red-flag deals.
 ```
+
+## Verify Checklist
+
+- [ ] Date/time displayed in Asia/Saigon.
+- [ ] Totals reconcile with helper output.
+- [ ] Red/yellow flags use the threshold table above.