@vruum/skills 0.6.36 → 0.6.37

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Skills for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/README.md

@@ -63,6 +63,14 @@ Download and upload via **Settings → Customize → Plugins → "+"**.
 npx @vruum/skills install --target /path/to/skills/dir
 ```
 
+## Coexisting with operator skills
+
+The public and operator skill bundles can coexist in the same harness. For
+overlapping skill names, a valid operator-owned installation takes precedence.
+Public installs and uninstalls preserve the operator bundle's links and update
+checker. If an operator link becomes stale, the next public install restores
+the public skill instead of leaving a broken link.
+
 ## Skills
 
 <!-- generated:skills-begin -->

package/install.js

@@ -37,6 +37,7 @@ const VRUUM_ROOT = path.join(os.homedir(), '.vruum');
 const VRUUM_SKILLS = path.join(VRUUM_ROOT, 'skills');
 const VRUUM_AGENTS = path.join(VRUUM_ROOT, 'agents');
 const VRUUM_BIN = path.join(VRUUM_ROOT, 'bin');
+const VRUUM_OPERATOR_ROOT = path.join(VRUUM_ROOT, 'skills-operator');
 const VRUUM_VERSION_FILE = path.join(VRUUM_ROOT, 'VERSION');
 const PKG_BIN = path.join(PACKAGE_ROOT, 'bin');
 
@@ -154,7 +155,7 @@ function syncVruumRoot({ dryRun }) {
       `would sync ${PKG_SKILLS} -> ${VRUUM_SKILLS} (with auto-update prelude)`,
     ];
     if (fs.existsSync(PKG_AGENTS)) rows.push(`would sync ${PKG_AGENTS} -> ${VRUUM_AGENTS}`);
-    if (fs.existsSync(PKG_BIN)) rows.push(`would sync ${PKG_BIN} -> ${VRUUM_BIN}`);
+    if (fs.existsSync(PKG_BIN)) rows.push(`would merge ${PKG_BIN} -> ${VRUUM_BIN}`);
     rows.push(`would write ${VRUUM_VERSION_FILE} = ${VERSION}`);
     return rows;
   }
@@ -174,14 +175,18 @@ function syncVruumRoot({ dryRun }) {
     rows.push(`synced ${VRUUM_AGENTS}`);
   }
 
-  // Bin scripts — update-check needs to land at a stable path and be exec.
+  // Bin scripts share ~/.vruum/bin with the operator installer. Copy only this
+  // package's files; replacing the directory would delete the operator update
+  // checker and make that bundle permanently stale.
   if (fs.existsSync(PKG_BIN)) {
-    fs.rmSync(VRUUM_BIN, { recursive: true, force: true });
-    fs.cpSync(PKG_BIN, VRUUM_BIN, { recursive: true });
-    for (const entry of fs.readdirSync(VRUUM_BIN)) {
-      fs.chmodSync(path.join(VRUUM_BIN, entry), 0o755);
+    fs.mkdirSync(VRUUM_BIN, { recursive: true });
+    for (const entry of fs.readdirSync(PKG_BIN)) {
+      const src = path.join(PKG_BIN, entry);
+      const dst = path.join(VRUUM_BIN, entry);
+      fs.cpSync(src, dst, { recursive: true, force: true });
+      fs.chmodSync(dst, 0o755);
     }
-    rows.push(`synced ${VRUUM_BIN}`);
+    rows.push(`merged ${PKG_BIN} -> ${VRUUM_BIN}`);
   }
 
   // VERSION file — read by vruum-skills-update-check as the local version.
@@ -205,6 +210,25 @@ function isOurLink(dst, linkTarget) {
   return resolved === VRUUM_SKILLS || resolved.startsWith(VRUUM_SKILLS + path.sep);
 }
 
+// Operator skills are a strict superset with multi-company scoping. When both
+// installers are present, operator links win for overlapping names regardless
+// of install order. Public-only names still link normally.
+function isOperatorLink(dst, linkTarget) {
+  const resolved = path.isAbsolute(linkTarget)
+    ? path.resolve(linkTarget)
+    : path.resolve(path.dirname(dst), linkTarget);
+  return resolved === VRUUM_OPERATOR_ROOT
+    || resolved.startsWith(VRUUM_OPERATOR_ROOT + path.sep);
+}
+
+function hasSkillFile(dir) {
+  try {
+    return fs.statSync(path.join(dir, 'SKILL.md')).isFile();
+  } catch {
+    return false;
+  }
+}
+
 // Prune pass — after relinking current skills, remove links for skills no
 // longer in the package (renamed or deleted), but ONLY symlinks this installer
 // owns (target under ~/.vruum/skills/). Non-symlinks (real user dirs/files) and
@@ -276,6 +300,22 @@ function linkSkill({ name, srcAbs, target, dryRun }) {
   if (existing?.kind === 'symlink' && existing.target === srcAbs) {
     return { name, target, action: 'already-linked' };
   }
+  const resolvedExistingTarget = existing?.kind === 'symlink'
+    ? (path.isAbsolute(existing.target)
+      ? path.resolve(existing.target)
+      : path.resolve(path.dirname(dst), existing.target))
+    : null;
+  const operatorSkillIsUsable = resolvedExistingTarget
+    && isOperatorLink(dst, existing.target)
+    && hasSkillFile(resolvedExistingTarget);
+  if (operatorSkillIsUsable) {
+    return {
+      name,
+      target,
+      action: 'operator-kept',
+      reason: 'operator bundle takes precedence for overlapping skills',
+    };
+  }
   if (existing && existing.kind !== 'symlink') {
     return {
       name,
@@ -441,7 +481,7 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
   // Only clean up our own subdirectories — ~/.vruum/ is a shared state dir
   // (e.g. the .agents/ vruum-update-check keeps config.yaml + snooze state
   // there, and both installers share that config).
-  for (const dir of [VRUUM_SKILLS, VRUUM_AGENTS, VRUUM_BIN]) {
+  for (const dir of [VRUUM_SKILLS, VRUUM_AGENTS]) {
     if (!fs.existsSync(dir)) continue;
     if (dryRun) {
       console.log(`${prefix}would remove ${dir}`);
@@ -450,6 +490,23 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
       console.log(`${prefix}removed ${dir}`);
     }
   }
+  // Remove only binaries shipped by the public package. The operator update
+  // checker in the same directory belongs to the operator installer.
+  if (fs.existsSync(PKG_BIN) && fs.existsSync(VRUUM_BIN)) {
+    for (const entry of fs.readdirSync(PKG_BIN)) {
+      const dst = path.join(VRUUM_BIN, entry);
+      if (!fs.existsSync(dst)) continue;
+      if (dryRun) {
+        console.log(`${prefix}would remove ${dst}`);
+      } else {
+        fs.rmSync(dst, { recursive: true, force: true });
+        console.log(`${prefix}removed ${dst}`);
+      }
+    }
+    if (!dryRun && fs.readdirSync(VRUUM_BIN).length === 0) {
+      fs.rmdirSync(VRUUM_BIN);
+    }
+  }
   if (fs.existsSync(VRUUM_VERSION_FILE)) {
     if (dryRun) {
       console.log(`${prefix}would remove ${VRUUM_VERSION_FILE}`);
@@ -543,6 +600,7 @@ module.exports = {
   listAvailableSkills,
   linkSkill,
   isOurLink,
+  isOperatorLink,
   pruneStaleLinks,
   pruneLegacyCodexLinks,
   commandInstall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -42,5 +42,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "9271a000625e137db6e7f5bb1daf4663ec97de8f38eac6839f05db100f864021"
+  "contentHash": "9562cd3662884c9fb44cb61950299f9569a13ce38dc64101dc196b36e26d1c43"
 }

package/skills/campaign-builder/SKILL.md

@@ -36,8 +36,9 @@ Iterate with the seller until the cohort is right ("too broad — only the US on
 
 If the criteria names organizations/accounts and the preview has fewer people than needed, do not create an empty campaign or pretend the accounts are contacts. Hand off the missing-account cohort to `/pipeline-fill` discovery before Step 3:
 
-- Build `source_policy` using `.agents/skills/pipeline-fill/contracts/source-policy.schema.json`.
+- Build `source_policy` using `pipeline-fill/contracts/source-policy.schema.json` from the installed skills bundle.
 - Preserve every explicit provider instruction. Example: "use Clay, no Sales Nav or CSV" becomes `selected_source: "clay"`, `source_mode: "preferred"`, `prohibited_sources: ["sales_nav", "linkedin", "csv"]`, and an ordered `allowed_fallbacks` list.
+- CSV and Sales Nav remain fully supported sources when the seller explicitly selects them. Source prohibitions are scoped to this run only; never turn one seller's preference into a global capability restriction or silently substitute a prohibited source.
 - Use the schema defaults unless the seller overrides them: company waves 10, person waves 5, and two retries for transient failures. `source_mode: "exclusive"` requires `allowed_fallbacks: []`.
 - Pass the named organizations and campaign criteria as the discovery ICP brief.
 - Set pipeline-fill `mode: "save"` explicitly. This persists approved people so their IDs can return here, but cannot enroll them or start outreach.
@@ -62,12 +63,28 @@ For large cohorts, assign in bounded batches and report requested vs updated cou
 Show the seller a launch summary before anything sends:
 - Campaign name, source of messaging (cloned from X / fresh)
 - Cohort size and criteria
-- Channels and cadence (from the campaign config)
+- Channels, cadence, and maximum touches (from the campaign config). Enrollment schedules the first action immediately; spacing between later touches must already be represented in the campaign cadence.
 
-Then ask explicitly: "Launch outreach to these N people?" Only after a clear yes, call `manage_outreach` action=start id=[person uuids] (native bulk; payload optional {max_touches, allowed_channels, start_immediately}).
+Then ask explicitly: "Launch outreach to these N people?" Only after a clear yes, call `manage_outreach` action=start id=[person uuids] (native bulk; payload optional `{max_touches, allowed_channels}`). Do not pass `start_immediately`; the MCP intentionally ignores it.
 
 If the seller wants a dry run, stop after Step 4 — the campaign exists with members and nothing sends until plans start.
 
+### Existing Gmail scheduling
+
+If Gmail already contains scheduled or sent campaign emails, reconcile them before approving, drafting, or starting replacement email touches:
+
+1. Call `fetch` with `type=settings subtype=channel_status`. Select the intended sender mailbox from `channels.email.accounts[]` and use its public `id` as `account_id`; never invent or ask the seller for an internal provider id.
+2. Call `manage_messages` action=`reconcile_external_email`, id=<campaign uuid>, payload=`{account_id, action: "preview", after?, before?}`.
+3. Show exact matched, ambiguous, and unmatched counts. A preview is read-only.
+4. When the seller asked to synchronize—or explicitly approves the preview—apply that exact snapshot with payload=`{account_id, action: "apply", preview_id}`. Applying creates/finalizes Vruum reservations; it never sends or resends email.
+5. Pull payload=`{account_id, action: "exceptions"}` for the exception-first rescue queue. Never guess a recipient or silently release a reservation.
+
+Provider-scheduled rows are protected from duplicate dispatch and excluded from actionable review. Surface `externally_scheduled_count` when verifying the campaign.
+
+### Repairing already-created plans
+
+If the seller changes maximum touches or allowed channels after plans exist, update the cohort through `manage_outreach` action=`update`, id=[plan uuids], payload=`{max_touches?, allowed_channels?}`. This preserves each plan's active/paused state. Report per-plan success, error, and not-attempted counts; never patch outreach-plan rows directly in the database.
+
 ## Notes
 
 - Junk-safe personalization: contacts with garbage first names (single letters, org names) automatically get the no-name greeting variant — you don't need to filter them out of the cohort for that reason.

package/skills/outreach-triage/SKILL.md

@@ -28,9 +28,16 @@ For small queues (5 or fewer) or when subagents can't access MCP, review directl
 
 ### Step 1: Get the lay of the land
 
-Call `fetch` with type=stats and subtype=outreach to see the pending queue shape. The response carries `needs_draft_count` (unauthored touches awaiting authoring) alongside `draft_count` (authored, awaiting approval) — surface both so the authoring backlog is visible up front. Present a quick summary:
+Call `fetch` with type=stats and subtype=outreach to see the pending queue shape, then call `get_outreach_review` with `content_length=preview, limit=1` for authoritative review-state counts. Surface:
 
-"You have N to author (needs_draft, W of them WARM accepted-connection follow-ups), X reply responses, Y pending T1s, Z T2+ follow-ups. [Any critical alerts.] Want me to run full triage or focus on a specific category?"
+- `needs_draft_count`: unauthored touches awaiting authoring
+- `draft_count`: authored touches awaiting approval
+- `approved_pending_send_count`: approved Vruum sends waiting on cadence/cooldown
+- `externally_scheduled_count`: Gmail/provider-scheduled rows protected by an external-send reservation
+
+Externally scheduled rows are intentionally excluded from actionable items. Never re-draft, approve, or manually resend them. Present a quick summary:
+
+"You have N to author (W WARM accepted-connection follow-ups), D drafts to review, A approved sends waiting on cadence, and E externally scheduled in Gmail. [Any critical alerts.] Want me to run full triage or focus on a specific category?"
 
 **Warm follow-ups outrank everything except replies.** The stats payload carries `needs_draft_warm_count`: unauthored `linkedin_message` touches to people who ACCEPTED the connection request. These are the highest-EV rows in the queue — a person who said yes to the invite is waiting on a first real message. When non-zero, lead the summary with it and default the triage order to: inbound replies → warm follow-ups → everything else.
 
@@ -38,6 +45,19 @@ Keep it short. The user knows their queue — they just need the numbers to deci
 
 **needs_draft items EXPIRE.** A nightly backend sweep (03:20 UTC) rejects any `needs_draft` row older than 14 days from creation — intended garbage collection, not an operator action. An expired touch is not lost forever (the plan reschedules and mints a fresh row about a week later), but the authoring work is deferred a cycle and the queue silently shrinks. The tools tell you: the stats payload carries `needs_draft_expiring_soon_count` (rows within 3 days of the sweep — surface it in the summary when non-zero), and each needs_draft item carries `expires_at` (its sweep deadline). Consequence for triage: author oldest-first, and if the queue is too big to clear in one session, clear the items closest to `expires_at` rather than sampling the freshest.
 
+### Gmail/Vruum reconciliation lane
+
+When the seller asks to audit or synchronize Gmail scheduling, do this before normal triage:
+
+1. Call `fetch` with `type=settings subtype=channel_status`. Select the intended sender mailbox from `channels.email.accounts[]` and use its public `id` as `account_id`; never invent or ask the seller for an internal provider id.
+2. Call `manage_messages` action=`reconcile_external_email`, id=<campaign uuid>, payload=`{account_id, action: "preview", after?, before?}`.
+3. Present matched, ambiguous, and unmatched counts. Preview is provider-read-only and mutation-free.
+4. If synchronization was requested or the seller approves the preview, call the same action with payload=`{account_id, action: "apply", preview_id}`. Apply only the exact preview; it creates/finalizes reservations without sending or resending anything.
+5. Call payload=`{account_id, action: "exceptions"}` and lead with blocked, ambiguous, unmatched, failed, or unverified contacts.
+6. Re-read `get_outreach_review` and verify `externally_scheduled_count` plus the actionable queue. A Gmail-scheduled row must never remain actionable.
+
+Manual Gmail edits require a fresh preview. Use guarded `hold`, `release`, or `mark_cancelled` only with the reservation id, a reason, and affirmative cancellation evidence or explicit human instruction. Reauthorization must preserve the provider identity and existing reservation; never create a replacement touch merely because the connector was refreshed.
+
 ### Step 2: Build the dispatch list and categorize
 
 Once the user says go (or picks a focus area), pull the lightweight message queue via `search` with type=messages, `fields=compact` and limit=100 — make THREE cheap calls: `warm_only=true, status=needs_draft, sort_by=expiring` (the WARM authoring lane — LinkedIn follow-ups to accepted connections, nearest deadline first), `status=needs_draft` (the full authoring lane; warm rows appear here too — dedupe by message_id, warm lane wins), and `status=draft` (the review lane). `fields=compact` returns message_id, person_name, category, sequence_number, channel, status, match_score, touches_completed, campaign_id, first_content_touch, and channel_rewrite_reason WITHOUT message content — very cheap on tokens. Tag each item with its status so dispatch routes it to the right mode: `needs_draft` → authoring, `draft` → review. (Omitting the status filter returns the default actionable set — needs_draft + draft + approved — but pull the two lanes explicitly so already-approved messages awaiting send don't enter triage.)
@@ -202,4 +222,5 @@ After outreach messages are processed, ask if the user wants to review the engag
 - **User wants to review a specific person:** pull that person's conversation with `fetch` (type=conversation) and review directly. No batch workflow.
 - **Subagent can't reach MCP tools:** fall back to inline review.
 - **Homogeneous T1 pattern:** if the first T1 batch all had the identical issue, fix the remaining in bulk with a single `manage_messages` call passing an id array (same action applied to every id, max 50 per call). Confirm first.
+- **Campaign plan settings drifted:** repair `max_touches` or `allowed_channels` through `manage_outreach` action=`update` with plan-id arrays. This preserves execution state; never update plan rows directly.
 

package/skills/pipeline-fill/SKILL.md

@@ -90,6 +90,8 @@ ETA estimates: ~2s for batch Step 3 dedup + ~30s/wave Phase A + ~60s/wave Phase
 
 > Sourcing {campaign_name} via discovery (ICP-based, long-tail). Reply `sales-nav`, `yc`, `csv`, or `picker` to switch.
 
+CSV and Sales Nav are fully supported when selected. `source_policy` is a per-run routing contract: an explicit "use CSV" or "use Sales Nav" selects that capability; an explicit "no CSV" or "no Sales Nav" prohibits it only for this run. Never persist a seller's personal source preference as a tenant-wide capability restriction.
+
 Why discovery is the default: keyword/Sales-Nav sources keep returning the same marquee names, which collide with already-enrolled prospects as a campaign matures — the Step 3 dedup then throws most of the batch away. Discovery anchors on the campaign's own ICP and reaches the long tail, deduping *before* research instead of after. Only render the full picker below when the operator asks to choose (`picker`), names a non-discovery source, or the discovery handler can't proceed.
 
 Per selected campaign, when the operator wants to choose the source explicitly, prompt:

package/skills/vruum-guide/SKILL.md

@@ -33,6 +33,7 @@ Build "your revenue engine today" from live reads — never from memory or assum
 - `search` type=people limit=1 filters={research_status: "all"} → total contacts (read the total, not the rows)
 - `search` type=deals limit=5 → deal pipeline existence
 - `fetch` type=stats subtype=outreach → sends, replies, meetings
+- `get_outreach_review` content_length=preview limit=1 → actionable, approved-pending-send, and externally scheduled counts
 - `search` type=content → whether an organic content motion is active
 
 Present a compact snapshot (5-8 lines, their numbers), positioned on the revenue-motion map (Step 2). If the company record or knowledge base shows a referral source ("referred by X"), acknowledge it and skip intake questions that referral context already answers.
@@ -64,6 +65,7 @@ Important boundaries: outreach/reply/content/comment prose is authored in the ha
 | Signal | Recommendation |
 |---|---|
 | Contacts sitting unenrolled | enroll into a campaign (`/campaign-builder` or `manage_campaign` action=members) |
+| Gmail/provider-scheduled rows or reconciliation exceptions | `/outreach-triage` Gmail/Vruum reconciliation lane; never recreate the email |
 | Outreach queue has pending drafts | `/outreach-triage` |
 | Engagement queue non-empty | `/engagement-triage` |
 | Replies without follow-up | `/diagnose-reply` on the interesting ones, then respond |