docs: update SKILL.md for v0.2.0 — new tools, cancel guard note

skills/odoo/SKILL.md

@@ -5,16 +5,19 @@ description: >
   involving: products, product catalog, stock levels, inventory; knowledge base
   articles; contacts, customers, vendors; sales orders, quotes; CRM leads and
   opportunities; projects and tasks; helpdesk tickets; purchase orders;
-  employees and departments. Triggers on: "in Odoo", "our products", "the
+  employees and departments; bulk record updates; archiving records; counting
+  records; cancelling quotations. Triggers on: "in Odoo", "our products", "the
   knowledge base", "find a contact", "sales order", "opportunity", "project
   tasks", "helpdesk ticket", "purchase order", "stock", "inventory",
   "employee", "what stage is", "create a task", "update the ticket",
-  "set icon", "article icon", "emoji icon".
+  "cancel quotation", "cancel quote", "archive", "mark lost", "bulk update",
+  "how many records", "count of", "stage id for", "resolve stage",
+  "search with filters", "filter by", "lost reasons".
 ---
 
 # Odoo MPM Skill
 
-You have direct access to MPM's Odoo V19 instance at mpmedia.odoo.com via the `odoo-mpm` MCP server.
+You have direct access to MPM's Odoo instance at mpmedia.odoo.com via the `odoo-mpm` MCP server.
 
 ## First-Time Setup (required once per Mac)
 
@@ -58,20 +61,21 @@ One-time setup to store your personal API key in the macOS Keychain. Use `clear_
 Search the product catalog, retrieve product details including pricing and descriptions, and check stock levels across warehouse locations.
 
 ### Knowledge (`search_knowledge_articles`, `get_knowledge_article`, `create_knowledge_article`, `update_knowledge_article`)
-Read, search, create, and update internal Knowledge base articles. Body content is HTML.
+Read, search, create, and update internal Knowledge base articles. Body content is HTML. All three tools support an `icon` field — pass a Unicode emoji (e.g. `⚙️`, `🔌`, `🖥️`) to set the article's icon in the KB tree. Browse icons at https://emojipedia.org.
 
-**Icon support:** Both `create_knowledge_article` and `update_knowledge_article` accept an optional `icon` parameter — a single Unicode emoji string (e.g. `"⚙️"`, `"🔌"`, `"🖥️"`) that sets the article's icon in the KB tree view. `get_knowledge_article` returns the current icon. Omitting or passing an empty string leaves the existing icon unchanged.
+### Knowledge Templates (`search_knowledge_templates`, `get_knowledge_template`, `list_knowledge_template_categories`)
-
+Browse built-in Odoo Knowledge article templates by name or category. Use `get_knowledge_template` to retrieve the full template body for use as a starting point when creating articles.
-To browse and select emojis, use: **[Emojipedia](https://emojipedia.org)** — search by keyword, copy the emoji character, and pass it directly to the tool.
 
 ### Contacts (`search_contacts`, `get_contact`, `create_contact`)
 Search customers, vendors, and individuals. Use `is_company=true` to filter to companies.
 
-### Sales (`search_sales_orders`, `get_sales_order`, `create_sales_order`)
+### Sales (`search_sales_orders`, `get_sales_order`, `create_sales_order`, `cancel_sale_orders`, `cancel_and_archive_quotations`)
 Look up quotes and sales orders by name (e.g. S00901) or customer. `get_sales_order` includes line items.
 
-### CRM (`search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages`)
+**Important:** `cancel_sale_orders` and `cancel_and_archive_quotations` ONLY operate on orders in **Quotation (draft)** or **Quotation Sent (sent)** state. Both tools will refuse and raise an error if any provided IDs are in any other state (confirmed Sale Order, Locked, Cancelled, etc.). This is an intentional safety constraint — confirmed orders cannot be cancelled via Claude.
-Manage opportunities in the sales pipeline. Use `list_crm_stages` to get valid stage IDs before updating.
+
+### CRM (`search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages`, `mark_crm_lead_lost`, `list_crm_lost_reasons`)
+Manage opportunities in the sales pipeline. Use `list_crm_stages` to get valid stage IDs before updating. Use `list_crm_lost_reasons` then `mark_crm_lead_lost` to record a loss with a reason.
 
 ### Project (`list_projects`, `get_project`, `search_tasks`, `get_task`, `create_task`, `update_task`, `list_task_stages`)
 Browse projects, search and update tasks. Use `list_task_stages` with a project_id to get valid stage IDs.
@@ -88,16 +92,26 @@ Check current stock levels and recent stock movements by product.
 ### Employees (`search_employees`, `get_employee`, `list_departments`)
 Look up employee information and department structure.
 
-### Utilities (`odoo_search`, `odoo_get_record`)
+### Utilities — Generic (`odoo_search`, `odoo_get_record`, `odoo_search_read`, `get_record_count`, `bulk_update_records`, `archive_records`, `get_stage_ids`, `call_odoo_method`)
-Generic tools for any Odoo model — useful for looking up stage IDs, categories, or any other reference data.
+Advanced tools for any Odoo model:
+- `odoo_search_read` — preferred for efficient queries: search with domain + return only specified fields. Use this instead of `odoo_search` + `odoo_get_record` to avoid token bloat.
+- `get_record_count` — count records matching a domain without fetching data. Use before bulk operations.
+- `bulk_update_records` — set one or more field values on a list of record IDs in a single API call. Works for stage changes, custom Studio fields (`x_studio_*`), status flags, etc.
+- `archive_records` — soft-delete records by setting `active=False`. For `sale.order`, cancel first with `cancel_sale_orders`.
+- `get_stage_ids` — resolve stage names to IDs with case-insensitive exact matching. Supports `crm.stage`, `project.task.type`, and `helpdesk.stage`.
+- `call_odoo_method` — escape hatch for any model method not covered by other tools (workflow transitions, report actions, custom methods). Use sparingly.
+- `odoo_search` / `odoo_get_record` — legacy generic lookup tools; prefer `odoo_search_read` for new usage.
 
 ---
 
 ## Workflow Guidelines
 
 - When looking up items by number (e.g. "S00901", "P00195"), use `search_sales_orders` or `search_purchase_orders` with that as the query.
-- Before updating a task or ticket stage, call `list_task_stages` or `odoo_search('helpdesk.stage', 'name', ...)` to confirm valid stage IDs.
+- Before updating a task or ticket stage, call `list_task_stages` or `get_stage_ids('helpdesk.stage', ['Stage Name'])` to confirm valid stage IDs.
+- Use `get_stage_ids` instead of `odoo_search` for stage lookups — it handles case-insensitive matching correctly.
 - Knowledge article bodies are stored as HTML — when creating or updating articles, use basic HTML formatting.
-- When setting KB article icons, prompt the user for the emoji or suggest one based on context. Reference: https://emojipedia.org
 - IDs returned from search tools can be passed directly to `get_*` tools for full details.
 - When the user asks about "our products" without specifying, use `search_products` with no query and limit=20 to show a broad overview.
+- Use `odoo_search_read` for any query where you only need specific fields — it is more efficient than `odoo_get_record` and avoids large responses.
+- Before calling `cancel_sale_orders` or `cancel_and_archive_quotations`, use `search_sales_orders` to verify the orders are in `draft` or `sent` state. Both tools will refuse if any order is in another state.
+- Before calling `mark_crm_lead_lost`, call `list_crm_lost_reasons` to show the user available reasons so they can choose one by name.