dealdesk-plugin 0.0.0-stage → 0.1.0

package/scripts/zip-archive.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const zlib = require('zlib');
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) {
+      c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i += 1) {
+    c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function dosDateTime(date) {
+  const time =
+    (date.getUTCHours() << 11) |
+    (date.getUTCMinutes() << 5) |
+    Math.floor(date.getUTCSeconds() / 2);
+  const day =
+    ((date.getUTCFullYear() - 1980) << 9) |
+    ((date.getUTCMonth() + 1) << 5) |
+    date.getUTCDate();
+  return { time, day };
+}
+
+function createZip(files, date = new Date()) {
+  const { time, day } = dosDateTime(date);
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+
+  for (const file of files) {
+    if (!file.name || /\\|\.\.|^\/|^\s|\s$/.test(file.name)) {
+      throw new Error(`Unsafe zip path: ${file.name}`);
+    }
+    const name = Buffer.from(file.name, 'utf8');
+    const data = Buffer.isBuffer(file.data) ? file.data : Buffer.from(file.data);
+    const compressed = zlib.deflateRawSync(data);
+    const crc = crc32(data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0, 6);
+    local.writeUInt16LE(8, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(day, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(compressed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0, 8);
+    central.writeUInt16LE(8, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(day, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(compressed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(0, 38);
+    central.writeUInt32LE(offset, 42);
+
+    locals.push(Buffer.concat([local, name, compressed]));
+    centrals.push(Buffer.concat([central, name]));
+    offset += local.length + name.length + compressed.length;
+  }
+
+  const centralDir = Buffer.concat(centrals);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(files.length, 8);
+  eocd.writeUInt16LE(files.length, 10);
+  eocd.writeUInt32LE(centralDir.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...locals, centralDir, eocd]);
+}
+
+function readZip(buffer) {
+  let eocd = -1;
+  const start = Math.max(0, buffer.length - 22 - 0xffff);
+  for (let i = buffer.length - 22; i >= start; i -= 1) {
+    if (buffer.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0) throw new Error('ZIP is missing an end-of-central-directory record');
+
+  const count = buffer.readUInt16LE(eocd + 10);
+  let ptr = buffer.readUInt32LE(eocd + 16);
+  const entries = [];
+  for (let n = 0; n < count; n += 1) {
+    if (buffer.readUInt32LE(ptr) !== 0x02014b50) {
+      throw new Error('ZIP central directory is truncated');
+    }
+    const method = buffer.readUInt16LE(ptr + 10);
+    const compressedSize = buffer.readUInt32LE(ptr + 20);
+    const nameLen = buffer.readUInt16LE(ptr + 28);
+    const extraLen = buffer.readUInt16LE(ptr + 30);
+    const commentLen = buffer.readUInt16LE(ptr + 32);
+    const localOffset = buffer.readUInt32LE(ptr + 42);
+    const name = buffer.toString('utf8', ptr + 46, ptr + 46 + nameLen);
+    const localNameLen = buffer.readUInt16LE(localOffset + 26);
+    const localExtraLen = buffer.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + localNameLen + localExtraLen;
+    const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
+    const data = method === 0 ? Buffer.from(compressed) : zlib.inflateRawSync(compressed);
+    entries.push({ name, data });
+    ptr += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+module.exports = { createZip, readZip };

package/skills/README.md

@@ -0,0 +1,30 @@
+# DealDesk skills
+
+These notes describe common workflows the DealDesk MCP connector supports. Hosts load each workflow from `skills/<name>/SKILL.md`. Slash commands in `commands/` start the same workflows. Your AI host may also load live skill descriptions from the agenthouse DealDesk server (`dealdesk.list_skills`).
+
+## Guidelines
+
+- Prefer update and soft-close over delete. Delete is not offered through MCP.
+- Prefer the export skill for analysis instead of paging through large lists endlessly.
+- For portfolio publish, always review the preview and confirm before publishing.
+- Skill-gated tools need `dealdesk.discover` with the matching domain first. The server remembers that unlock for the API key or OAuth user.
+- **Notes vs email:** use `dealdesk.add_card_note` for internal notes. Log inbound/outbound email with `dealdesk.log_email` (status-update touchpoint). Never store emails as card notes.
+
+## Shipped skills
+
+| Skill | Slash command | Purpose |
+| --- | --- | --- |
+| [dealdesk-help](./dealdesk-help/SKILL.md) | `/dealdesk-help` | Overview of capabilities; agent calls `list_skills` / `discover` |
+| [dealdesk-create-card](./dealdesk-create-card/SKILL.md) | `/dealdesk-create-card` | Create or update a desk card |
+| [dealdesk-log-card-activity](./dealdesk-log-card-activity/SKILL.md) | `/dealdesk-log-card-activity` | Notes, comments, tasks, and email touchpoints |
+| [dealdesk-craft-quote](./dealdesk-craft-quote/SKILL.md) | `/dealdesk-craft-quote` | Craft or refine a classic quote |
+| [dealdesk-quote-from-portfolio](./dealdesk-quote-from-portfolio/SKILL.md) | `/dealdesk-quote-from-portfolio` | Evaluate and create a quote from the published portfolio |
+| [dealdesk-evaluate-configuration](./dealdesk-evaluate-configuration/SKILL.md) | `/dealdesk-evaluate-configuration` | Side-effect free CPQ evaluation |
+| [dealdesk-directory-activity](./dealdesk-directory-activity/SKILL.md) | `/dealdesk-directory-activity` | Company/contact notes and commercial summary |
+| [dealdesk-find-or-create-customer](./dealdesk-find-or-create-customer/SKILL.md) | `/dealdesk-find-or-create-customer` | Directory company/contact lookup and create |
+| [dealdesk-share-quote](./dealdesk-share-quote/SKILL.md) | `/dealdesk-share-quote` | Quote status and customer share links (classic + rich) |
+| [dealdesk-manage-cases](./dealdesk-manage-cases/SKILL.md) | — | Local DealDesk cases |
+| [dealdesk-manage-orders](./dealdesk-manage-orders/SKILL.md) | — | Orders (discover `orders`) |
+| [dealdesk-portfolio-browse](./dealdesk-portfolio-browse/SKILL.md) | — | Portfolio articles/revisions (discover `portfolio`) |
+| [dealdesk-export-analysis](./dealdesk-export-analysis/SKILL.md) | `/dealdesk-export-analysis` | Bounded Deal Intelligence export |
+| [dealdesk-publish-portfolio](./dealdesk-publish-portfolio/SKILL.md) | `/dealdesk-publish-portfolio` | Preview then confirm portfolio publish |

package/skills/dealdesk-craft-quote/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: dealdesk-craft-quote
+description: Guide the user to craft an excellent classic DealDesk quote. Use when they want a new classic quote draft, to clone a past quote, or to refine line items — not only portfolio-evaluated pricing.
+---
+
+# Craft an excellent classic quote
+
+Tools: `dealdesk.list_companies`, `dealdesk.get_company`, `dealdesk.create_company`, `dealdesk.list_contacts`, `dealdesk.get_contact`, `dealdesk.create_contact`, `dealdesk.list_quotes`, `dealdesk.get_quote`, `dealdesk.get_quote_summary`, `dealdesk.create_quote`, `dealdesk.clone_quote`, `dealdesk.replace_quote_items`, `dealdesk.patch_quote`, `dealdesk.portfolio_summary`, `dealdesk.portfolio_evaluate`, `dealdesk.discover`, `dealdesk.list_portfolio_articles`, `dealdesk.get_portfolio_article`, `dealdesk.create_quote_from_configuration`, `dealdesk.update_quote_from_configuration`, `dealdesk.create_quote_share`, `dealdesk.render_quote_pdf`
+
+## Conversation (classic-first)
+
+1. Confirm **company** and **contact** (search/create in the Customer Directory).
+2. Ask what the quote is **about** (title / intent).
+3. Always ask: scan past quotes and suggest a clone, copy a quote they like, or **create fresh**?
+4. Consult the **published portfolio** for recommended articles; confirm what belongs in the quote.
+5. Ask whether positions should be in **groups**, and propose how to separate them (family, category, or custom). Confirm single vs multi selection, included vs optional, and `quantityEditable` where useful.
+6. Create with `create_quote` or `clone_quote`. Refine with `replace_quote_items` (add/edit/remove positions, regroup).
+7. Use CPQ `create_quote_from_configuration` / `update_quote_from_configuration` only when the user wants portfolio-evaluated pricing. Pass `quoteLayout` for presentation.
+8. Offer share link / PDF when ready. Never delete through MCP.
+
+Do not invent prices for CPQ lines client-side. Classic/open positions may carry explicit `unitPrice`.

package/skills/dealdesk-create-card/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: dealdesk-create-card
+description: Create or update a DealDesk desk card (title, stage, description, owner, priority, company/contact, deal estimates, quote value override). Use when the user wants a new card, a stage/owner change, estimates, or directory links. Never delete a card.
+---
+
+# Create or update a desk card
+
+Tools: `dealdesk.create_card`, `dealdesk.patch_card`, `dealdesk.get_card`, `dealdesk.list_cards`, `dealdesk.list_desk_stages`, `dealdesk.list_desk_users`, `dealdesk.list_card_activity`
+
+Create a card or update title, stage, description, owner, priority, Customer Directory links, deal estimates, and quote deal-value override. Soft-close by setting stage `closed` rather than deleting.
+
+Use `description` for the main card body. Use `deskDescription` for a local desk-only description. Use `dealdesk.add_card_note` only for structured notes, not as a substitute for the card description.
+
+## Stages (discrete column ids)
+
+`stage` is a **board column id**, not a UI label. Call `dealdesk.list_desk_stages` and use a returned `columnId`. Never slugify a German/English label into a stage string (e.g. do **not** send `anfrage-in-bearbeitung`). That creates a ghost column and the card vanishes from the board.
+
+Default board (when the project has not customized columns):
+
+| columnId | EN | DE |
+| --- | --- | --- |
+| `request` | Open request | Offene Anfrage |
+| `request-in-progress` | Request in progress | Anfrage in Bearbeitung |
+| `quote-preparation` | Quote in preparation | Angebot in Bearbeitung |
+| `quote-sent` | Quote sent | Angebot gesendet |
+| `quote-accepted` | Quote accepted | Angebot angenommen |
+| `order-processing` | Order processing | Auftrag in Vorbereitung |
+| `order-completed` | Order completed | Auftrag abgeschlossen |
+| `closed` | Closed | Geschlossen |
+
+Tenants may add column ids — only use ids from `list_desk_stages`.
+
+## Owner and priority
+
+Resolve assignees with `dealdesk.list_desk_users`, then set `ownerUserId` on create/patch. Pass `null` on `patch_card` to clear. Filter with `list_cards` + `ownerUserId`. `priority` is free text (default `normal`).
+
+## Deal value, period, and win chance
+
+Set on the card with `create_card` / `patch_card`:
+
+- `estimatedValue`, `estimatedValueCurrency`, `estimatedValuePeriod` (`one_time` | `month` | `year`), `probabilityPercent`
+
+Use `year` for per-year / ARR. Do not invent synonyms (`annual`, `yearly`, `monthly`).
+
+When the card has a linked local case, the server updates that case (UI parity) and returns `caseId` when present. Do **not** call `create_case` just to set estimates — that creates a second desk item.
+
+## Quote deal-value override
+
+On an unaccepted quote card, `dealValueOverride` + `dealValueOverrideNet` replace quote net on the board/overview (same as the UI). Ignored after accept, decline, or when an order exists. Clear with `dealValueOverrideNet=null`.
+
+## Company / contact
+
+`patch_card` with `companyId` / `contactId` (or `null` to clear). Clearing company also clears contact. Company/contact changes also sync a linked local case and quote customer link.
+
+## History
+
+`dealdesk.list_card_activity` returns stage/owner/account/note/quote/order/share milestones (not the comment/email timeline — that is status updates).
+
+Do **not** use notes to log customer email. Use `dealdesk-log-card-activity` (`dealdesk.log_email`).

package/skills/dealdesk-directory-activity/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: dealdesk-directory-activity
+description: Read commercial summaries and add or patch notes on a DealDesk company or contact. Use for pipeline context on a customer, not for email logs.
+---
+
+# Directory notes and commercial summary
+
+Tools: `dealdesk.get_company`, `dealdesk.get_company_commercial_summary`, `dealdesk.add_company_note`, `dealdesk.patch_company_note`, `dealdesk.get_contact`, `dealdesk.get_contact_commercial_summary`, `dealdesk.add_contact_note`, `dealdesk.patch_contact_note`
+
+1. Resolve the company or contact with `get_company` / `get_contact` when needed.
+2. Read `get_company_commercial_summary` or `get_contact_commercial_summary` before advising on pipeline.
+3. Add or patch structured notes with title and body (`add_*_note` / `patch_*_note`).
+
+Never store email logs as directory notes. Never delete notes through MCP. For desk-card email, use `dealdesk.log_email` instead.

package/skills/dealdesk-evaluate-configuration/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: dealdesk-evaluate-configuration
+description: Run a side-effect free DealDesk CPQ evaluation against the portfolio. Use when the user wants totals, blockers, or a rule trace without creating a quote.
+---
+
+# Evaluate a configuration
+
+Tools: `dealdesk.portfolio_evaluate`
+
+Run a side-effect free CPQ evaluation against the Portfolio. Use this before creating a quote when you need blockers, totals, or a rule trace without persisting a quote.

package/skills/dealdesk-export-analysis/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: dealdesk-export-analysis
+description: Export DealDesk data for offline analysis with the bounded Deal Intelligence export. Use instead of paging through large card or quote lists.
+---
+
+# Export for analysis
+
+Tools: `dealdesk.export_intelligence`
+
+Use `dealdesk.export_intelligence` for a bounded workbook. The result contains `filename` and `relativePath` under `applications/dealdesk/exports`. It does not return a server filesystem path or the file bytes. Do not page `list_cards` or `list_quotes` to build a workbook by hand.
+

package/skills/dealdesk-find-or-create-customer/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: dealdesk-find-or-create-customer
+description: Search the DealDesk customer directory and create a company or contact only when no match exists. Use for company or contact lookup.
+---
+
+# Find or create a company / contact
+
+Tools: `dealdesk.list_companies`, `dealdesk.get_company`, `dealdesk.create_company`, `dealdesk.patch_company`, `dealdesk.list_contacts`, `dealdesk.get_contact`, `dealdesk.create_contact`, `dealdesk.patch_contact`
+
+Search the customer directory first. Create only when no suitable match exists. Update with `dealdesk.patch_company` / `dealdesk.patch_contact` using `expectedRevision` from get.
+
+Companies: send `legalName` or `name` (maps to `legalName`). `externalId` is optional and auto-generated as `local-company-<uuid>` when omitted.
+
+Contacts: send `displayName` or `name` (or first/last name). `externalId` is optional and auto-generated as `local-contact-<uuid>` when omitted.

package/skills/dealdesk-help/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: dealdesk-help
+description: Explain DealDesk capabilities, slash commands, and hard limits. Use when the user asks for help or what they can do with the plugin. Call dealdesk.list_skills before answering when MCP is available.
+---
+
+# DealDesk help
+
+Help the user use DealDesk. Prefer live discovery over memory.
+
+## First steps
+
+1. Call `dealdesk.list_projects` and tell the user which `authorizedProjectIds` the token covers. Do not assume the singular `projectId` when more than one id is listed.
+2. Call `dealdesk.list_skills` and summarize the returned skills in plain language.
+3. If important tools are missing from the current tool list, call `dealdesk.discover` (omit `domain` for the domain list, or pass a domain such as `desk`, `quotes`, `portfolio`, `directory`, `export`, or `portfolio-authoring`).
+4. Then answer with the command map below and the live skill list.
+
+If MCP is not connected yet, still explain the command map and say which auth path to use.
+
+## Slash commands
+
+| Command | What it does |
+| --- | --- |
+| `/dealdesk-help` | This overview |
+| `/dealdesk-create-card` | Create or update a desk card (including company/contact link) |
+| `/dealdesk-log-card-activity` | Log inbound or outbound email on a card timeline |
+| `/dealdesk-craft-quote` | Craft or refine a classic quote (clone or fresh draft) |
+| `/dealdesk-quote-from-portfolio` | Evaluate a configuration and create a quote from the portfolio |
+| `/dealdesk-evaluate-configuration` | Evaluate a configuration without creating a quote |
+| `/dealdesk-directory-activity` | Company/contact commercial summary and notes |
+| `/dealdesk-find-or-create-customer` | Find or create a company or contact |
+| `/dealdesk-share-quote` | Quote status and customer share links (classic + rich) |
+| `/dealdesk-export-analysis` | Bounded Deal Intelligence export |
+| `/dealdesk-publish-portfolio` | Preview then confirm portfolio publish |
+
+Hosts may prefix commands with the plugin name (for example `/dealdesk:dealdesk-help`).
+
+## Status updates and email
+
+- Email: use `dealdesk.log_email` (or `/dealdesk-log-card-activity`). Never put email in `add_card_note`.
+- Other timeline work: use `dealdesk.create_status_update` for `comment`, `task`, and touchpoints (`phone_call`, `meeting`, `email_incoming`, `email_outgoing`, `misc`).
+- Read the timeline with `dealdesk.list_status_updates`. Update with `dealdesk.patch_status_update`.
+- Structured desk notes: `dealdesk.add_card_note` / `dealdesk.patch_card_note`.
+
+## Quotes and shares
+
+- Status and acceptance: `dealdesk.get_quote` (also returns existing shares).
+- Line items without enrichment: `dealdesk.get_quote_summary`.
+- Customer links: `create_quote_share` → `classicUrl` (standard) and `experienceUrl` (rich experience). Soft-close with `patch_quote_share` `isOpen=false`.
+
+## Hard limits
+
+- Delete is not available through MCP. Soft-close cards by changing stage; soft-close shares with `isOpen=false`.
+- Portfolio publish needs preview, then `portfolio_publish` with `confirm=true`.
+- Do not invent prices. Prefer portfolio evaluation and published revision ids.
+- Prefer `/dealdesk-export-analysis` over paging through large lists forever.
+- Skill-gated tools need `dealdesk.discover` with the matching domain first (for example `orders`, `portfolio`, `portfolio-authoring`).
+- Remind the user that DealDesk tool results may disclose customer data to the AI host and other tools in the conversation, and that they remain responsible for that data.
+
+## Auth
+
+- Sign-in is OAuth. The user signs in on the agenthouse page, chooses one or more projects, and grants DealDesk access. When several projects are authorized, pass `projectId` on scoped tools.
+- Remote URL: `https://api.agenthouse.org/mcp/dealdesk` (ChatGPT, Claude, Codex, Cursor).
+- The Cursor plugin and the local connector open that same page. An API key is only for automation that cannot open a browser (`AGENTHOUSE_API_KEY`, and `AGENTHOUSE_PROJECT_ID` when the account has more than one project).

package/skills/dealdesk-log-card-activity/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: dealdesk-log-card-activity
+description: Add internal notes or log email and other status updates on a DealDesk card timeline. Use for inbound or outbound email, comments, tasks, calls, and meetings. Never store email as a card note.
+---
+
+# Add notes and log email / status updates on a card
+
+Tools: `dealdesk.get_card`, `dealdesk.add_card_note`, `dealdesk.patch_card_note`, `dealdesk.list_status_updates`, `dealdesk.create_status_update`, `dealdesk.patch_status_update`, `dealdesk.log_email`
+
+## Notes
+
+Use `dealdesk.add_card_note` for internal structured notes (title + body) on a desk card. Edit with `dealdesk.patch_card_note`. Delete is not available through MCP.
+
+## Email (required path)
+
+Log inbound or outbound email with `dealdesk.log_email`:
+
+- `direction`: `incoming` or `outgoing`
+- `from` / `to` / `subject` / `text`
+- `cardId` of the desk card
+
+This creates a status-update **touchpoint** (`email_incoming` / `email_outgoing`) on the card timeline — the same surface the DealDesk UI uses. The server persists structured `from` and `to` fields (and a compatible `participants` string `from → to`). Prefer `dealdesk.log_email` over a generic touchpoint so those fields are set correctly.
+
+**Never** put email logs into `add_card_note`.
+
+## Other status updates
+
+Use `dealdesk.create_status_update` for:
+
+- `type: comment` — timeline comment (`body` required)
+- `type: task` — task (`title` required; optional due date / assignee)
+- `type: touchpoint` — `phone_call`, `meeting`, `email_incoming`, `email_outgoing`, or `misc` (for email, prefer `dealdesk.log_email` so `from` / `to` are persisted)
+
+List existing timeline entries with `dealdesk.list_status_updates` (`entityType: desk-card` + `cardId` / `entityId`).
+
+Update an existing entry with `dealdesk.patch_status_update` (comment body, task status/fields, or touchpoint fields including `from` / `to`). Prefer listing first for `statusUpdateId` and `updatedAt`.

package/skills/dealdesk-manage-cases/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: dealdesk-manage-cases
+description: List, create, and update DealDesk cases. Use for local sales/request cases. Not Salesforce Opportunity search. Do not use create_case to set estimates on an existing desk card — use patch_card instead.
+---
+
+# Manage DealDesk cases
+
+Tools: `dealdesk.list_cases`, `dealdesk.get_case`, `dealdesk.create_case`, `dealdesk.patch_case`, `dealdesk.list_desk_stages`, `dealdesk.list_desk_users`
+
+Create or update local DealDesk cases (title, stage, description, company/contact/quote links, estimates, ownerUserId). Resolve stages with `dealdesk.list_desk_stages` and owners with `dealdesk.list_desk_users`. Soft-close via stage when appropriate. Do not call disconnected Salesforce Opportunity search endpoints.
+
+## Stages (discrete column ids)
+
+Same board column ids as desk cards. Call `dealdesk.list_desk_stages` and pass a returned `columnId`. Never slugify UI labels into stage strings.
+
+## Estimates on cases
+
+`create_case` / `patch_case` accept:
+
+- `estimatedValue`
+- `estimatedValueCurrency` (ISO 4217, e.g. `EUR`)
+- `estimatedValuePeriod` — `one_time` | `month` | `year` (labels the amount; does not convert it)
+- `probabilityPercent` (0–100)
+
+These round-trip on get/list. Use `year` for per-year / ARR. Do not invent synonyms (`annual`, `yearly`, `monthly`).
+
+## Desk cards vs cases
+
+Creating a case also creates a desk card. If the opportunity already appears as a desk card, set value/chance/period with `dealdesk.patch_card` on that card. Do **not** use `create_case` as a substitute for updating a card’s estimates — that duplicates the opportunity on the desk.

package/skills/dealdesk-manage-orders/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: dealdesk-manage-orders
+description: Work with DealDesk orders. Discover domain orders first, then list/get/create from quote/patch. Never delete orders through MCP.
+---
+
+# Manage orders
+
+Tools: `dealdesk.discover`, `dealdesk.list_orders`, `dealdesk.get_order`, `dealdesk.create_order_from_quote`, `dealdesk.patch_order`
+
+1. Call `dealdesk.discover` with domain `orders` if order tools are not listed.
+2. Create from a quote with `create_order_from_quote`.
+3. Patch metadata only. Delete is not available through MCP.

package/skills/dealdesk-portfolio-browse/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: dealdesk-portfolio-browse
+description: Browse portfolio articles and revisions. Discover domain portfolio first.
+---
+
+# Browse portfolio
+
+Tools: `dealdesk.discover`, `dealdesk.portfolio_summary`, `dealdesk.list_portfolio_articles`, `dealdesk.get_portfolio_article`, `dealdesk.list_portfolio_revisions`, `dealdesk.portfolio_evaluate`
+
+1. Call `dealdesk.discover` with domain `portfolio`.
+2. List or get articles; list revisions when comparing published content.
+3. Evaluate configurations with `portfolio_evaluate` (side-effect free).

package/skills/dealdesk-publish-portfolio/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: dealdesk-publish-portfolio
+description: Preview a DealDesk portfolio publish and confirm only when blockers are clear. Use when the user asks to publish the portfolio. Never publish without confirm=true.
+---
+
+# Publish portfolio (preview + confirm)
+
+Tools: `dealdesk.discover`, `dealdesk.initialize_portfolio_draft`, `dealdesk.portfolio_publish_preview`, `dealdesk.portfolio_publish`
+
+1. Unlock portfolio-authoring tools with `dealdesk.discover` and domain `portfolio-authoring` if needed.
+2. Call `initialize_portfolio_draft` only when no draft exists.
+3. Call `portfolio_publish_preview` and review blockers.
+4. Call `portfolio_publish` only with `confirm=true` when blockers are clear.
+
+
+Never publish without the explicit confirm flag. Confirm must work from a plain tools/call (no widget required).

package/skills/dealdesk-quote-from-portfolio/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: dealdesk-quote-from-portfolio
+description: Evaluate a configuration and create a DealDesk quote from the published portfolio. Use when the user wants a quote, not a price invented in chat.
+---
+
+# Quote from published portfolio
+
+Tools: `dealdesk.portfolio_summary`, `dealdesk.portfolio_evaluate`, `dealdesk.create_quote_from_configuration`, `dealdesk.update_quote_from_configuration`
+
+1. Optionally call `portfolio_summary` to confirm a published revision exists.
+2. Call `portfolio_evaluate` with the configuration (side-effect free).
+3. Call `create_quote_from_configuration` or `update_quote_from_configuration` with the published `portfolioRevisionId`, `priceBookRevisionId`, and the same configuration.
+
+Do not invent prices client-side. Prefer the published revision ids returned by the API.
+

package/skills/dealdesk-share-quote/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: dealdesk-share-quote
+description: Inspect DealDesk quote status and create or update customer share links. Use when the user asks for a quote link, share URL, rich experience link, or quote acceptance status.
+---
+
+# Quote status and share links
+
+Tools: `dealdesk.list_quotes`, `dealdesk.get_quote`, `dealdesk.get_quote_summary`, `dealdesk.list_quote_shares`, `dealdesk.create_quote_share`, `dealdesk.patch_quote_share`
+
+1. Resolve the quote with `list_quotes` / `get_quote`.
+2. `get_quote` returns `status`, `acceptanceSummary`, `analytics`, and current `shares`.
+3. Create a link with `create_quote_share`. Use:
+   - `classicUrl` / `classicPath` for the standard customer share
+   - `experienceUrl` / `experiencePath` for the rich experience Desk
+4. Soft-close a link with `patch_quote_share` and `isOpen=false`. Do not delete shares through MCP.
+5. Prefer `get_quote_summary` when you need stored line items without enrichment.