@kanvas/openclaw-plugin 0.1.9 → 0.1.11

package/README.md

@@ -2,21 +2,23 @@
 
 OpenClaw plugin that connects AI agents to [Kanvas](https://kanvas.dev) — your company's nervous system. Kanvas is the operational engine that connects all your data, tools, and workflows. For AI agents, it's what lets them actually run your business — not just talk about it.
 
-This plugin gives agents direct access to CRM, inventory, orders, and messaging so they can search leads, create contacts, check stock, track orders, store structured data, and send emails — all through 41 tools with auto-login and built-in system prompt context.
+This plugin gives agents direct access to CRM, inventory, orders, and messaging — 53 tools with auto-login, built-in system prompt context, and domain-specific skills.
 
 ## Quick Start
 
 ### 1. Install the plugin
 
 ```bash
-# From local directory (development)
-openclaw plugins install /path/to/kanvas-openclaw-plugin --link
+openclaw plugins install @kanvas/openclaw-plugin
+```
+
+### 2. Update to latest version
 
-# From npm (once published)
-openclaw plugins install kanvas-openclaw-plugin
+```bash
+openclaw plugins update kanvas
 ```
 
-### 2. Configure credentials
+### 3. Configure credentials
 
 In your OpenClaw config file:
 
@@ -42,43 +44,71 @@ In your OpenClaw config file:
 
 The API URL is preconfigured. The plugin authenticates automatically on the first tool call using the Kanvas login mutation.
 
-### 3. Set up the agent's system prompt
+## Skills
+
+The plugin ships with domain-specific **skills** — operational playbooks that teach the agent best practices for each use case. Skills are auto-loaded when the kanvas plugin is configured.
+
+### Included Skills
+
+| Skill | Description |
+|-------|-------------|
+| `kanvas-crm` | CRM operations — lead management, pipelines, email templates, follow-ups, file attachments, contact updates, participant relationships, email logging, and context isolation rules |
+
+Skills live in `skills/<skill-name>/SKILL.md` and follow the [OpenClaw skills format](https://docs.openclaw.ai/tools/skills). They inject operational guidance into the agent's context automatically.
+
+## Agent Setup Guides
+
+The `agent-setup/` directory contains step-by-step runbooks for deploying specific agent types. These are **human-facing documentation** — not auto-loaded by the agent.
+
+| Guide | Description |
+|-------|-------------|
+| [Sales Agent](agent-setup/sales.md) | Full setup protocol for an autonomous sales/deal architect agent — persona config, CRM customization, pipeline stages, daily heartbeat, email integration, and anti-pollution rules |
+
+### Agent types you can build with this plugin
+
+**Sales / Deal Architect**
+Autonomous lead generation, cold outreach, pipeline management, follow-up scheduling, and daily reporting. See [agent-setup/sales.md](agent-setup/sales.md) for the full setup protocol.
+
+**Operations Agent**
+Inventory monitoring, order tracking, stock alerts, and cross-domain reporting.
+
+**Customer Success Agent**
+Post-sale follow-ups, onboarding workflows, satisfaction tracking via CRM notes and events.
+
+**Data Entry / Admin Agent**
+Bulk lead import, contact enrichment, file attachments, and CRM hygiene.
 
-The plugin injects tool documentation into the agent's context automatically. But the agent's **base system prompt** (configured in OpenClaw) should tell it to use Kanvas. Here's a sample:
+Each agent type uses the same plugin and tools — the difference is the system prompt, skills, and heartbeat configuration.
+
+### Setting up the agent's system prompt
+
+The plugin injects tool documentation automatically. But the agent's **base system prompt** (configured in OpenClaw) should define its role. Example for a sales agent:
 
 ```
 You are a sales and operations agent for [Company Name]. You manage leads,
-inventory, and orders using Kanvas.
+inventory, and orders using the CRM.
 
 Your responsibilities:
 - Register and manage leads in the CRM pipeline
-- Look up products, stock levels, and pricing
-- Check and track orders
-- Add notes and messages to leads
-- Send emails to customers and prospects
+- Send outreach emails and follow up with prospects
+- Log all activity as CRM notes and messages
+- Schedule follow-ups as calendar events (never in local memory)
+- Send daily pipeline summaries to the team
 
 When users ask you to do any of these things, use the kanvas_* tools to act
 on it directly. Don't just describe what you would do — actually do it.
-
-Before creating a lead, always check kanvas_list_pipelines to get valid
-pipeline stage IDs, and kanvas_list_lead_sources for source IDs.
-
-When you don't have enough information to complete an action (e.g. missing
-a required field), ask the user for the missing details before proceeding.
 ```
 
-Customize this for your business — add your company name, specific workflows, and any domain-specific instructions.
-
 ## Tools Reference
 
-### CRM (22 tools)
+### CRM (29 tools)
 
 | Tool | Description |
 |------|-------------|
 | `kanvas_search_leads` | Search leads by keyword |
 | `kanvas_get_lead` | Full lead detail (pipeline, owner, participants, files, events) |
 | `kanvas_create_lead` | Create a new lead |
-| `kanvas_update_lead` | Update lead fields |
+| `kanvas_update_lead` | Update lead fields (auto-fetches branch_id/people_id) |
 | `kanvas_change_lead_owner` | Reassign lead owner |
 | `kanvas_change_lead_receiver` | Reassign lead receiver |
 | `kanvas_add_lead_participant` | Add a person to a lead |
@@ -93,6 +123,18 @@ Customize this for your business — add your company name, specific workflows,
 | `kanvas_add_lead_note_by_lead_id` | Add note by lead ID (auto-resolves channel) |
 | `kanvas_list_lead_messages` | List messages in a lead channel |
 | `kanvas_get_lead_primary_channel_slug` | Get the main channel slug for a lead |
+| `kanvas_attach_file_to_lead_by_url` | Attach file from a public URL |
+| `kanvas_upload_file_to_lead` | Upload file (base64, file path, or URL) |
+| `kanvas_upload_file_to_message` | Upload file to a message |
+| `kanvas_search_people` | Search contacts by name, email, or phone |
+| `kanvas_update_people` | Update contact info (phone, email, address, tags) |
+| `kanvas_list_contact_types` | List contact types (email, phone, etc.) |
+| `kanvas_list_people_relationships` | List relationship types |
+| `kanvas_create_people_relationship` | Create a relationship type |
+| `kanvas_update_people_relationship` | Update a relationship type |
+| `kanvas_delete_people_relationship` | Delete a relationship type |
+| `kanvas_create_follow_up` | Schedule a follow-up event linked to a lead |
+| `kanvas_list_events` | List scheduled events/follow-ups |
 | `kanvas_list_pipelines` | List pipelines and stages |
 | `kanvas_list_lead_statuses` | List lead statuses |
 | `kanvas_list_lead_sources` | List lead sources |
@@ -188,6 +230,21 @@ KANVAS_PASSWORD=yourpassword \
   npx ts-node --esm scripts/smoke-test.ts
 ```
 
+## Releasing
+
+```bash
+npm version patch   # bumps 0.1.x → 0.1.x+1 and creates a git commit + tag
+git push && git push --tags
+```
+
+GitHub Actions builds and publishes to npm automatically on any `v*` tag.
+
+Then on the agent machine:
+
+```bash
+openclaw plugins update kanvas
+```
+
 ## License
 
-Private — see package.json.
+MIT

package/agent-setup/sales.md

@@ -0,0 +1,200 @@
+# Deal Architect / Sales Agent Setup Protocol
+
+This document outlines the standard operating procedure (SOP) for configuring a new autonomous sales agent (Deal Architect) within the Kanvas ecosystem using Kanvas Plugin v0.1.8+.
+
+---
+
+## Phase 1: Core Persona & Rules Configuration
+
+### 1. Hidden Reasoning
+Instruct the agent to never expose its internal thinking process to the end-user or clients.
+
+### 2. White-labeling
+Instruct the agent to refer to the "Kanvas" system generically as:
+- "your database"
+- "the CRM"
+
+When communicating with clients or external parties.
+
+---
+
+## Phase 2: Plugin & Technical Integration
+
+### 1. Kanvas Credentials
+Verify the configuration includes:
+- `xKanvasApp`
+- `xKanvasLocation`
+- Agent `email`
+- Agent `password`
+- `xKanvasKey` (App Key)
+
+### 2. Email Template Setup
+
+- Identify or create a branded HTML email template (e.g., `incube-template`)
+
+#### Blade Syntax Fix
+
+Ensure the backend Laravel Blade template renders the message body using unescaped syntax:
+
+```php
+{!! $message !!}
+```
+
+This allows the agent to send:
+- Bold text  
+- Links  
+- Line breaks  
+- Full HTML formatting  
+
+---
+
+## Phase 3: Team Onboarding & Data Gathering
+
+### 1. Draft Welcome Email
+
+The agent drafts an onboarding email to the core team requesting:
+
+- **Working Email Credentials**  
+  Ensure backend email syncing is active
+
+- **Ideal Customer Profile (ICP)**  
+  Target audience descriptions
+
+- **Priority Reference Projects**  
+  3–5 strongest past projects for tailored pitches
+
+### 2. Communication Channel
+
+Provide the team with a direct link to the agent’s:
+- Telegram bot  
+- Slack bot  
+
+---
+
+## Phase 4: CRM Customization (Native Tools)
+
+### 1. Pipeline Stages
+
+Use Kanvas dashboard (or API) to map the pipeline:
+
+Prospecting → Needs Analysis → Proposal / Pitch Sent → In Negotiation → Contract Sent → Closed Won
+
+### 2. Categorization
+
+Use:
+
+- `kanvas_create_lead_type`
+- `kanvas_create_lead_source`
+
+To match:
+- ICP  
+- Acquisition strategy  
+
+### 3. Relationships
+
+Use:
+
+`kanvas_create_people_relationship`
+
+To ensure standard relationships exist before adding participants:
+
+- Client  
+- Architect  
+- Decision Maker  
+
+---
+
+## Phase 5: Automated Reporting (Mandatory)
+
+Every autonomous sales agent must send an automated morning summary.
+
+### 1. Daily Heartbeat
+
+Configure:
+
+`HEARTBEAT.md`
+
+To trigger a daily task (e.g., 07:00–08:00 UTC).
+
+### 2. Cron Logic
+
+- Check `MEMORY.md` to avoid duplicate emails
+- Query CRM for:
+
+`message_verb: "agent_email_log"`
+
+- Review past emails to prevent repetition
+- Draft summary of:
+  - Leads
+  - Emails
+  - Pipeline updates
+  - Scheduled follow-ups
+- Send via:
+
+`kanvas_send_anonymous_email`
+
+- Use branded template
+- Send to team distribution list
+- Log email as CRM message:
+
+`message_verb: "agent_email_log"`
+
+- Update:
+
+`MEMORY.md`
+
+With the current date
+
+---
+
+## Phase 6: Anti-Pollution & Context Isolation
+
+Sales agents must strictly avoid cross-polluting client data.
+
+### 1. Isolated Contexts
+Treat every interaction as a discrete transaction.
+
+### 2. CRM is the Source of Truth
+
+Always query Kanvas before replying:
+
+- `kanvas_get_lead`
+- `kanvas_list_lead_messages`
+
+### 3. Stateless Prompting (Sub-Agents)
+
+For complex pitches:
+
+- Spawn isolated sub-agent sessions  
+- Use only that specific lead’s data  
+
+---
+
+## Phase 7: Two-Way Email Integration (CRM-Managed)
+
+Agents must NEVER handle raw IMAP/SMTP credentials.
+
+### 1. Outbound
+
+Handled via CRM routing.
+
+### 2. Inbound (CRM Webhooks)
+
+- CRM monitors inbox
+- When a prospect replies:
+  - Message is logged in Lead’s message channel
+  - Agent is notified to respond
+
+---
+
+## Final Notes
+
+- Keep all communication consistent with CRM data
+- Avoid duplicate outreach
+- Maintain strict context isolation between leads
+- Always prioritize clarity, relevance, and forward movement in conversations
+
+---
+
+**Owner:** Kanvas Sales Agent System  
+**Version:** v0.1.8+

package/dist/index.js

@@ -67,7 +67,28 @@ export default {
     description: "Connects agents to Kanvas — your company's nervous system for CRM, inventory, orders, and messaging.",
     configSchema: { type: "object" },
     register(api) {
-        const config = resolveConfig(api.pluginConfig);
+        // Guard: resolve config and log a warning instead of throwing if
+        // credentials are missing. This prevents the gateway from entering
+        // an infinite retry loop when the plugin is installed but not yet
+        // configured, or when the gateway re-invokes register() multiple times.
+        let config;
+        try {
+            config = resolveConfig(api.pluginConfig);
+        }
+        catch (err) {
+            api.logger.info(`Kanvas plugin skipped: ${err.message}. Run "openclaw kanvas setup" to configure.`);
+            // Still register the CLI so the user can run setup even without config
+            api.registerCli((ctx) => {
+                ctx.program
+                    .command("setup")
+                    .description("Interactive setup — configure Kanvas credentials and test the connection")
+                    .action(async () => {
+                    const { runSetup } = await import("./cli/setup.js");
+                    await runSetup();
+                });
+            }, { commands: ["setup"] });
+            return;
+        }
         const client = new KanvasClient(config);
         const ensureAuth = createAuthGuard(client, config, api.logger);
         const crm = new CrmService(client);

package/openclaw.plugin.json

@@ -50,6 +50,7 @@
       }
     }
   },
+  "skills": ["skills"],
   "uiHints": {
     "apiUrl": { "label": "API URL", "placeholder": "https://graphapi.kanvas.dev/graphql" },
     "xKanvasApp": { "label": "App ID", "placeholder": "your-app-key" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanvas/openclaw-plugin",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Connects agents to Kanvas — your company's nervous system for CRM, inventory, orders, and messaging.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,8 @@
   },
   "files": [
     "dist/",
+    "skills/",
+    "agent-setup/",
     "openclaw.plugin.json",
     "README.md"
   ],

package/skills/kanvas-crm/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: kanvas-crm
+description: Use when interacting with the Kanvas CRM to manage leads, pipelines, send template emails, create follow-ups, upload files, and log sales activity.
+metadata: {"openclaw":{"requires":{"config":["plugins.entries.kanvas"]}}}
+---
+
+# Kanvas CRM Skill
+
+This skill provides operational guidance and technical best practices for using the Kanvas CRM plugin effectively.
+
+## Core Features & Usage Patterns
+
+### 1. HTML Email Templates (Laravel Blade)
+When sending emails via `kanvas_send_anonymous_email` using Kanvas notification templates, the backend uses Laravel Blade.
+- **The Issue:** Blade escapes HTML tags by default (`{{ $message }}`), causing `<br>` and `<strong>` to render as raw text.
+- **The Fix:** Ensure the backend template uses unescaped syntax (`{!! $message !!}`). Pass raw HTML in your message payloads to render properly formatted emails.
+
+### 2. Updating Lead Pipelines
+Use the native `kanvas_update_lead` tool.
+- Pass `id` and `input: { pipeline_stage_id: XYZ }`.
+- The plugin auto-fetches required fields (`branch_id`, `people_id`) behind the scenes as of v0.1.8+. No custom GraphQL scripts are necessary.
+
+### 3. Updating Contacts (People)
+Use the native `kanvas_update_people` tool.
+- You can seamlessly append phone numbers, emails, and custom fields to a Contact profile.
+- Pass the contacts array with the correct `contacts_types_id` (e.g., 1 for Email, 2 for Phone). Call `kanvas_list_contact_types` first if you are unsure of the IDs.
+
+### 4. File Attachments
+Use the native tools:
+- `kanvas_attach_file_to_lead_by_url`: Supply a public URL to download a PDF or image straight to the Lead profile.
+- `kanvas_upload_file_to_lead` / `kanvas_upload_file_to_message`: If passing base64 or a local file path.
+
+### 5. Follow-ups and Task Management
+Use the native `kanvas_create_follow_up` tool.
+- **Why:** Do not use local text files (`MEMORY.md`) to manage the sales pipeline reminders. If you schedule a follow-up, the human team needs to be able to see it natively inside the Kanvas dashboard.
+- **Usage:** Create a calendar event, pass the `lead_id`, `date`, `start_time`, and `end_time`. Use `kanvas_list_events` during your morning sweep to execute them.
+
+### 6. Participant API & Relationship Creation
+When using `kanvas_add_lead_participant`, the CRM requires a `relationship_id`.
+- **Pre-requisite:** Before attaching a person to a lead, ensure a relationship type exists (like "Architect", "Client", or "Consultant").
+- **Tool:** Use `kanvas_create_people_relationship` to dynamically create the relationship if it's missing, get its ID, and then call `kanvas_add_lead_participant`.
+
+### 7. Anti-Pollution & Context Isolation
+When handling multiple outbound conversations, strictly avoid mixing up client details.
+- **The CRM is the Single Source of Truth:** Before drafting a reply or follow-up, the agent must query Kanvas for the specific Lead ID (`kanvas_get_lead`), read the Lead Profile, and fetch the Message Channel history (`kanvas_list_lead_messages`). Build the response *strictly* based on this retrieved data.
+- **Stateless Prompting (Sub-Agents):** For complex negotiations or drafting highly technical pitches, spawn an isolated sub-agent session. Feed the sub-agent *only* the data for that specific lead and the required reference projects, retrieve the drafted text, and terminate the sub-agent to ensure zero cross-contamination.
+
+### 8. Email Logging & Deduplication
+To avoid sending the same update or repeating the same information to clients and the team:
+- **Logging:** EVERY outbound email sent (e.g., via `kanvas_send_anonymous_email` or custom scripts) MUST be immediately logged into Kanvas using a direct GraphQL `CreateMessage` mutation with the `message_verb: "agent_email_log"`.
+- **Payload Structure:** The `message` JSON payload must include the exact `subject`, `date`, `recipients` (array of emails), and `body` (the full HTML/text sent).
+- **Reviewing:** Before drafting a daily report or a follow-up pitch, query the CRM for messages with the `message_verb: "agent_email_log"` to review past logs and ensure you do not repeat topics that were covered in previous emails.
+
+### 9. Lead Generation & Injection (The Sourcing Loop)
+When sourcing targets automatically (via Apollo API or Web Search):
+- **Quota:** Source exactly 5 distinct companies/projects per run (10 per day: morning and after-lunch sweeps).
+- **Deduplication:** Always query Kanvas (`kanvas_search_leads`) by the prospect's email or company name *before* creating a new lead to prevent duplicate entries and spamming.
+- **Injection:** Create the Lead using `kanvas_create_lead` in the "Prospecting" stage with the correct ICP Lead Type and Source.
+- **Documentation:** Draft the initial cold email pitch and attach it as a note to the Lead profile so the leadership team can review it natively before sending.
+- **Reporting:** When sending the daily Approval Report email, you MUST include the strategic rationale (the "Why") directly in the email body, and link the company name directly to its CRM dashboard page using this exact URL format:
+  `https://kanvas.domain/projects/{app-uuid}/leads/{leaduuid}`
+
+### 10. Structured Pitch Notes (JSON)
+When attaching a drafted cold email or pitch to a Lead profile for human review, DO NOT pass it as a raw string.
+- **Requirement:** The UI parses pitches better when passed as a structured JSON object.
+- **Format:** When calling `kanvas_add_lead_note_by_lead_id`, pass the `message` payload as a structured object containing ONLY `title` and `body` fields.
+- **Title Formatting:** The title must be a clean, professional string in Norwegian (e.g., `Utkast til e-post: [Selskap]`). Never include debugging or array tags in the title.
+- **Body Formatting Rule:** Do NOT use explicit `\n\n` strings or JSON arrays in the `body`. Use the HTML `<br><br>` format for a single, continuous `body` string so that Kanvas frontend renders the JSON payloads with clean line breaks instead of visible newline escape characters.
+
+### 11. Apollo Integration & Contact Enrichment
+When using Apollo API to source leads, always extract the following fields and map them to Kanvas:
+- **Email:** Use `kanvas_list_contact_types` to find the ID (usually 1) and map to `contacts: [{ value: email, contacts_types_id: 1 }]`.
+- **LinkedIn Profile (Optional):** If the contact has a `linkedin_url`, extract it and map to `contacts: [{ value: linkedin_url, contacts_types_id: 5 }]`. Do not fail or block the lead creation if the LinkedIn profile is missing.
+- **Phone Numbers:** Apollo requires a webhook to reveal direct phone numbers. Until this is built into Kanvas, phone numbers cannot be automatically extracted via the synchronous API.
+
+### 12. White-Labeling & Value Communication
+When communicating with the leadership team, founders, or human architects, NEVER mention the specific technical backend tools (e.g., Apollo, Kanvas, OpenClaw, GraphQL).
+- **The Value Proposition:** Human teams only care about the *results*: qualified meetings booked, deals moved to the next stage, and a healthy sales pipeline. They do not care about the APIs used to get there.
+- **Reporting Rule:** In daily summaries and rationale notes, use generic business terminology. Instead of "Sourced via Apollo API," say "Identified via market intelligence." Instead of "Injected into Kanvas," say "Added to the CRM pipeline."
+- **Internal Tagging:** If you need to track the origin of a lead for analytics, use native CRM tags or the `LeadSource` field silently in the backend payload. Do not expose the data provider in the public-facing text notes or emails.q