create-claude-cabinet 0.29.13 → 0.30.0

package/lib/cli.js

@@ -592,6 +592,22 @@ const MODULES = {
     ],
     postInstall: 'site-audit-setup',
   },
+  handoff: {
+    name: 'Handoff (secure credential collection)',
+    description: 'Skill-based credential handoff for consulting engagements. Encrypted credential capture via OS dialog, pluggable transport (email/MCP/file), bidirectional messaging. Six skills across consultant and client sides.',
+    mandatory: false,
+    default: false,
+    lean: false,
+    templates: [
+      'skills/handoff',
+      'skills/handoff-progress',
+      'skills/handoff-ask',
+      'skills/handoff-create',
+      'skills/handoff-add',
+      'skills/handoff-status',
+      'handoff',
+    ],
+  },
 };
 
 /** Recursively collect all relative file paths under a directory. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.29.13",
+  "version": "0.30.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/handoff/capture-and-encrypt.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+//
+// Single-subprocess credential capture + encryption.
+// Plaintext never exits this process, never enters Claude's context or Anthropic's API.
+// stdout: serialized encrypted envelope (base64) only.
+//
+import { readFile } from 'node:fs/promises';
+import { captureSecureInput, detectPlatform, DialogCancelledError, DialogUnavailableError } from './secure-input.mjs';
+import { encryptCredential, serializeEnvelope } from './handoff-crypto.mjs';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+const prompt = getArg('--prompt');
+const publicKeyPath = getArg('--public-key');
+const testMode = args.includes('--test');
+
+if (!testMode && (!prompt || !publicKeyPath)) {
+  console.error('Usage: node capture-and-encrypt.mjs --prompt <text> --public-key <path>');
+  console.error('       node capture-and-encrypt.mjs --test');
+  process.exit(1);
+}
+
+try {
+  if (testMode) {
+    const { generateKeypair, decryptCredential, deserializeEnvelope } = await import('./handoff-crypto.mjs');
+    const plaintext = 'test-credential-value';
+    const { publicKey, privateKey } = await generateKeypair();
+    const envelope = await encryptCredential(plaintext, publicKey);
+    const serialized = serializeEnvelope(envelope);
+    const recovered = deserializeEnvelope(serialized);
+    const decrypted = await decryptCredential(recovered, privateKey);
+
+    if (decrypted !== plaintext) {
+      console.error(JSON.stringify({ error: 'test_failed', detail: 'Roundtrip mismatch' }));
+      process.exit(4);
+    }
+    console.log(JSON.stringify({
+      ok: true,
+      platform: detectPlatform(),
+      envelope_id: envelope.envelope_id,
+    }));
+    process.exit(0);
+  }
+
+  const publicKeyJWK = JSON.parse(await readFile(publicKeyPath, 'utf-8'));
+  const plaintext = await captureSecureInput(prompt);
+  const envelope = await encryptCredential(plaintext, publicKeyJWK);
+  // Plaintext is now only in local `plaintext` var — GC will collect it.
+  // Only the encrypted envelope reaches stdout.
+  process.stdout.write(serializeEnvelope(envelope));
+} catch (err) {
+  if (err instanceof DialogCancelledError) {
+    console.error(JSON.stringify({ error: 'cancelled' }));
+    process.exit(2);
+  }
+  if (err instanceof DialogUnavailableError) {
+    console.error(JSON.stringify({ error: 'no_dialog', platform: err.platform }));
+    process.exit(3);
+  }
+  console.error(JSON.stringify({ error: 'encrypt_failed', detail: err.message }));
+  process.exit(4);
+}

package/templates/handoff/decrypt-credential.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+//
+// Decrypt a credential envelope using the consultant's passphrase-protected private key.
+// Passphrase captured via secure OS dialog — never enters Claude's context.
+// stdout: decrypted plaintext (displayed once by the skill, not stored).
+//
+import { readFile } from 'node:fs/promises';
+import { captureSecureInput, DialogCancelledError, DialogUnavailableError } from './secure-input.mjs';
+import { decryptCredential, decryptPrivateKey, deserializeEnvelope } from './handoff-crypto.mjs';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+const envelopeInput = getArg('--envelope');
+const privateKeyPath = getArg('--private-key') || './keys/consultant.priv.jwk.enc';
+const testMode = args.includes('--test');
+
+if (!testMode && !envelopeInput) {
+  console.error('Usage: node decrypt-credential.mjs --envelope <base64> [--private-key <path>]');
+  console.error('       node decrypt-credential.mjs --test');
+  process.exit(1);
+}
+
+try {
+  if (testMode) {
+    const { generateKeypair, encryptCredential, encryptPrivateKey, serializeEnvelope } = await import('./handoff-crypto.mjs');
+    const testPassphrase = 'test-pass-123';
+    const testPlaintext = 'test-secret-value';
+
+    const { publicKey, privateKey } = await generateKeypair();
+    const encrypted = await encryptPrivateKey(privateKey, testPassphrase);
+    const envelope = await encryptCredential(testPlaintext, publicKey);
+    const serialized = serializeEnvelope(envelope);
+
+    const recovered = decryptPrivateKey(encrypted, testPassphrase);
+    const decrypted = await decryptCredential(deserializeEnvelope(serialized), await recovered);
+
+    console.log(JSON.stringify({
+      ok: decrypted === testPlaintext,
+      detail: decrypted === testPlaintext ? 'Roundtrip passed' : 'Mismatch',
+    }));
+    process.exit(decrypted === testPlaintext ? 0 : 4);
+  }
+
+  const encryptedKey = JSON.parse(await readFile(privateKeyPath, 'utf-8'));
+  const envelope = deserializeEnvelope(envelopeInput);
+
+  const passphrase = await captureSecureInput('Enter your private key passphrase');
+  const privateKeyJWK = await decryptPrivateKey(encryptedKey, passphrase);
+  const plaintext = await decryptCredential(envelope, privateKeyJWK);
+
+  process.stdout.write(plaintext);
+} catch (err) {
+  if (err instanceof DialogCancelledError) {
+    console.error(JSON.stringify({ error: 'cancelled' }));
+    process.exit(2);
+  }
+  if (err instanceof DialogUnavailableError) {
+    console.error(JSON.stringify({ error: 'no_dialog', platform: err.platform }));
+    process.exit(3);
+  }
+  if (err.message?.includes('decrypt') || err.message?.includes('OperationError')) {
+    console.error(JSON.stringify({ error: 'wrong_passphrase' }));
+    process.exit(5);
+  }
+  console.error(JSON.stringify({ error: 'decrypt_failed', detail: err.message }));
+  process.exit(4);
+}

package/templates/handoff/example-checklist.yaml

@@ -0,0 +1,81 @@
+# Example handoff checklist — customize for your engagement.
+# See schema.md for the full format reference.
+
+meta:
+  title: "Project Go-Live Credentials"
+  consultant: "Your Name"
+  public_key: "./keys/consultant.pub.jwk"
+
+transport:
+  type: email
+  consultant: "consultant@example.com"
+  client: "client@example.com"
+
+sections:
+  - key: hosting
+    title: "Hosting Setup"
+    items:
+      - key: hosting_provider
+        prompt: "Which hosting provider are you using?"
+        kind: decide
+        options: [Railway, Vercel, Fly.io, Other]
+
+      - key: railway_token
+        prompt: "Your Railway API token"
+        kind: credential
+        help: "Find this at railway.app → Account Settings → Tokens"
+        visibility:
+          depends_on: hosting_provider
+          value_in: [Railway]
+
+      - key: vercel_token
+        prompt: "Your Vercel access token"
+        kind: credential
+        help: "Find this at vercel.com → Settings → Tokens"
+        visibility:
+          depends_on: hosting_provider
+          value_in: [Vercel]
+
+  - key: email_service
+    title: "Email Service"
+    items:
+      - key: email_provider
+        prompt: "Which email service are you using?"
+        kind: decide
+        options: [Postmark, SendGrid, Resend, None]
+
+      - key: postmark_token
+        prompt: "Your Postmark server API token"
+        kind: credential
+        help: "Find this in your Postmark server → API Tokens tab"
+        visibility:
+          depends_on: email_provider
+          value_in: [Postmark]
+
+      - key: sendgrid_key
+        prompt: "Your SendGrid API key"
+        kind: credential
+        visibility:
+          depends_on: email_provider
+          value_in: [SendGrid]
+
+      - key: resend_key
+        prompt: "Your Resend API key"
+        kind: credential
+        help: "Find this at resend.com → API Keys"
+        visibility:
+          depends_on: email_provider
+          value_in: [Resend]
+
+  - key: domain
+    title: "Domain & DNS"
+    items:
+      - key: domain_name
+        prompt: "What domain will this project use?"
+        kind: provide
+        help: "e.g., example.com or app.example.com"
+
+      - key: dns_access
+        prompt: "Do you have access to your domain's DNS settings?"
+        kind: confirm
+        help: "We'll need to add records for the hosting provider and email service."

package/templates/handoff/generate-keys.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { generateKeypair, encryptPrivateKey } from './handoff-crypto.mjs';
+import { captureSecureInput } from './secure-input.mjs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+const outdir = getArg('--outdir') || './keys';
+const testPassphrase = getArg('--test-passphrase');
+
+let passphrase;
+if (testPassphrase) {
+  passphrase = testPassphrase;
+} else {
+  console.error('A passphrase dialog will appear — enter a passphrase to protect your private key.');
+  console.error('You will need this passphrase to decrypt credentials via /handoff-status.');
+  passphrase = await captureSecureInput('Create a passphrase for your private key');
+}
+
+const { publicKey, privateKey } = await generateKeypair();
+const encrypted = await encryptPrivateKey(privateKey, passphrase);
+
+await mkdir(resolve(outdir), { recursive: true });
+await writeFile(resolve(outdir, 'consultant.pub.jwk'), JSON.stringify(publicKey, null, 2));
+await writeFile(resolve(outdir, 'consultant.priv.jwk.enc'), JSON.stringify(encrypted, null, 2));
+
+console.log(`Keys written to ${outdir}/`);
+console.log('  consultant.pub.jwk      — share with client (ships with plugin)');
+console.log('  consultant.priv.jwk.enc — keep private (encrypted with your passphrase)');

package/templates/handoff/handoff-checklist.mjs

@@ -0,0 +1,172 @@
+import { readFile, writeFile, rename } from 'node:fs/promises';
+
+const VALID_KINDS = ['decide', 'provide', 'confirm', 'credential'];
+const VALID_TRANSPORT_TYPES = ['email', 'mcp', 'file'];
+
+export function validateChecklist(checklist) {
+  const errors = [];
+
+  if (!checklist.meta) errors.push('Missing "meta" section');
+  else {
+    if (!checklist.meta.title) errors.push('meta.title is required');
+    if (!checklist.meta.public_key) errors.push('meta.public_key is required');
+  }
+
+  if (!checklist.transport) {
+    errors.push('Missing "transport" section');
+  } else if (!VALID_TRANSPORT_TYPES.includes(checklist.transport.type)) {
+    errors.push(`transport.type must be one of: ${VALID_TRANSPORT_TYPES.join(', ')}`);
+  }
+
+  if (!Array.isArray(checklist.sections)) {
+    errors.push('Missing or invalid "sections" array');
+    return { valid: false, errors };
+  }
+
+  // First pass: collect all keys for cross-section dependency validation
+  const allKeys = new Set();
+  for (const section of checklist.sections) {
+    for (const item of (section.items || [])) {
+      if (item.key) allKeys.add(item.key);
+    }
+  }
+
+  const seenKeys = new Set();
+  for (const section of checklist.sections) {
+    if (!section.key) errors.push('Section missing "key"');
+    if (!section.title) errors.push(`Section ${section.key || '?'} missing "title"`);
+    if (!Array.isArray(section.items)) {
+      errors.push(`Section ${section.key || '?'} missing "items" array`);
+      continue;
+    }
+    for (const item of section.items) {
+      if (!item.key) { errors.push('Item missing "key"'); continue; }
+      if (!item.prompt) errors.push(`Item ${item.key} missing "prompt"`);
+      if (!VALID_KINDS.includes(item.kind)) {
+        errors.push(`Item ${item.key}: kind must be one of: ${VALID_KINDS.join(', ')}`);
+      }
+      if (seenKeys.has(item.key)) errors.push(`Duplicate item key: ${item.key}`);
+      seenKeys.add(item.key);
+
+      if (item.visibility) {
+        if (!item.visibility.depends_on) errors.push(`Item ${item.key}: visibility.depends_on is required`);
+        if (!Array.isArray(item.visibility.value_in)) errors.push(`Item ${item.key}: visibility.value_in must be an array`);
+        if (item.visibility.depends_on && !allKeys.has(item.visibility.depends_on)) {
+          errors.push(`Item ${item.key}: depends_on "${item.visibility.depends_on}" references non-existent key`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function getAllItems(checklist) {
+  return (checklist.sections || []).flatMap(s => s.items || []);
+}
+
+export function detectCycles(checklist) {
+  const items = getAllItems(checklist);
+  const keySet = new Set(items.map(i => i.key));
+  const graph = new Map();
+  const inDegree = new Map();
+
+  for (const item of items) {
+    graph.set(item.key, []);
+    inDegree.set(item.key, 0);
+  }
+
+  for (const item of items) {
+    const parent = item.visibility?.depends_on;
+    if (parent && keySet.has(parent)) {
+      graph.get(parent).push(item.key);
+      inDegree.set(item.key, inDegree.get(item.key) + 1);
+    }
+  }
+
+  const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([k]) => k);
+  let processed = 0;
+
+  while (queue.length > 0) {
+    const key = queue.shift();
+    processed++;
+    for (const child of graph.get(key) || []) {
+      const nd = inDegree.get(child) - 1;
+      inDegree.set(child, nd);
+      if (nd === 0) queue.push(child);
+    }
+  }
+
+  const hasCycle = processed < items.length;
+  const cycleKeys = hasCycle
+    ? [...inDegree.entries()].filter(([, d]) => d > 0).map(([k]) => k)
+    : [];
+
+  return { hasCycle, cycleKeys };
+}
+
+export function computeVisibility(checklist, answers) {
+  const items = getAllItems(checklist);
+  const visible = new Set();
+
+  for (const item of items) {
+    if (!item.visibility) visible.add(item.key);
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const item of items) {
+      if (visible.has(item.key) || !item.visibility) continue;
+      const parentKey = item.visibility.depends_on;
+      if (!visible.has(parentKey)) continue;
+      const parentAnswer = answers[parentKey]?.value;
+      if (parentAnswer && item.visibility.value_in.includes(parentAnswer)) {
+        visible.add(item.key);
+        changed = true;
+      }
+    }
+  }
+
+  return visible;
+}
+
+export async function loadState(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export function createState(checklistPath) {
+  return {
+    checklist: checklistPath,
+    started_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    answers: {},
+  };
+}
+
+export async function saveState(path, state) {
+  state.updated_at = new Date().toISOString();
+  const tmp = path + '.tmp';
+  await writeFile(tmp, JSON.stringify(state, null, 2));
+  await rename(tmp, path);
+}
+
+export function recordAnswer(state, key, value) {
+  state.answers[key] = { value, answered_at: new Date().toISOString() };
+}
+
+export function recordCredentialSent(state, key, envelopeId) {
+  state.answers[key] = { status: 'sent', envelope_id: envelopeId, sent_at: new Date().toISOString() };
+}
+
+export function getProgress(checklist, state) {
+  const answers = state?.answers || {};
+  const visible = computeVisibility(checklist, answers);
+  const completed = [...visible].filter(key => answers[key]).length;
+  return { total: visible.size, completed, remaining: visible.size - completed };
+}

package/templates/handoff/handoff-crypto.mjs

@@ -0,0 +1,102 @@
+import { webcrypto } from 'node:crypto';
+
+const { subtle } = webcrypto;
+
+const RSA_ALGO = {
+  name: 'RSA-OAEP',
+  modulusLength: 2048,
+  publicExponent: new Uint8Array([1, 0, 1]),
+  hash: 'SHA-256',
+};
+
+const AES_ALGO = { name: 'AES-GCM', length: 256 };
+const PBKDF2_ITERATIONS = 600_000;
+
+export async function generateKeypair() {
+  const pair = await subtle.generateKey(RSA_ALGO, true, ['wrapKey', 'unwrapKey']);
+  return {
+    publicKey: await subtle.exportKey('jwk', pair.publicKey),
+    privateKey: await subtle.exportKey('jwk', pair.privateKey),
+  };
+}
+
+export async function encryptCredential(plaintext, publicKeyJWK) {
+  const publicKey = await subtle.importKey('jwk', publicKeyJWK, RSA_ALGO, false, ['wrapKey']);
+  const aesKey = await subtle.generateKey(AES_ALGO, true, ['encrypt']);
+  const iv = webcrypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, new TextEncoder().encode(plaintext));
+  const wrappedKey = await subtle.wrapKey('raw', aesKey, publicKey, RSA_ALGO);
+  const idBytes = webcrypto.getRandomValues(new Uint8Array(6));
+  const envelope_id = 'env_' + [...idBytes].map(b => b.toString(16).padStart(2, '0')).join('');
+
+  return {
+    envelope_id,
+    ciphertext: Buffer.from(ciphertext).toString('base64'),
+    iv: Buffer.from(iv).toString('base64'),
+    wrappedKey: Buffer.from(wrappedKey).toString('base64'),
+  };
+}
+
+export async function decryptCredential(envelope, privateKeyJWK) {
+  const privateKey = await subtle.importKey('jwk', privateKeyJWK, RSA_ALGO, false, ['unwrapKey']);
+  const aesKey = await subtle.unwrapKey(
+    'raw',
+    Buffer.from(envelope.wrappedKey, 'base64'),
+    privateKey,
+    RSA_ALGO,
+    AES_ALGO,
+    false,
+    ['decrypt'],
+  );
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv: Buffer.from(envelope.iv, 'base64') },
+    aesKey,
+    Buffer.from(envelope.ciphertext, 'base64'),
+  );
+  return new TextDecoder().decode(decrypted);
+}
+
+export function serializeEnvelope(envelope) {
+  return Buffer.from(JSON.stringify(envelope)).toString('base64');
+}
+
+export function deserializeEnvelope(base64) {
+  return JSON.parse(Buffer.from(base64, 'base64').toString('utf-8'));
+}
+
+export async function encryptPrivateKey(privateKeyJWK, passphrase) {
+  const salt = webcrypto.getRandomValues(new Uint8Array(16));
+  const iv = webcrypto.getRandomValues(new Uint8Array(12));
+  const keyMaterial = await subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, ['deriveKey']);
+  const derived = await subtle.deriveKey(
+    { name: 'PBKDF2', salt, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
+    keyMaterial,
+    AES_ALGO,
+    false,
+    ['encrypt'],
+  );
+  const ciphertext = await subtle.encrypt({ name: 'AES-GCM', iv }, derived, new TextEncoder().encode(JSON.stringify(privateKeyJWK)));
+
+  return {
+    salt: Buffer.from(salt).toString('base64'),
+    iv: Buffer.from(iv).toString('base64'),
+    ciphertext: Buffer.from(ciphertext).toString('base64'),
+  };
+}
+
+export async function decryptPrivateKey(encrypted, passphrase) {
+  const keyMaterial = await subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, ['deriveKey']);
+  const derived = await subtle.deriveKey(
+    { name: 'PBKDF2', salt: Buffer.from(encrypted.salt, 'base64'), iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
+    keyMaterial,
+    AES_ALGO,
+    false,
+    ['decrypt'],
+  );
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv: Buffer.from(encrypted.iv, 'base64') },
+    derived,
+    Buffer.from(encrypted.ciphertext, 'base64'),
+  );
+  return JSON.parse(new TextDecoder().decode(decrypted));
+}

package/templates/handoff/handoff-transport.mjs

@@ -0,0 +1,105 @@
+import { writeFile, readFile, readdir, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const EMAIL_MCP_SIGNATURES = [
+  { provider: 'gmail', toolPattern: /gmail/i },
+  { provider: 'outlook', toolPattern: /outlook|microsoft/i },
+];
+
+export function detectEmailProvider(availableTools) {
+  if (!availableTools?.length) return null;
+  for (const sig of EMAIL_MCP_SIGNATURES) {
+    if (availableTools.some(t => sig.toolPattern.test(t))) return sig.provider;
+  }
+  return null;
+}
+
+export function buildEmailInstruction(envelope, transportConfig, provider, recipient) {
+  const envelopeId = typeof envelope === 'object' ? envelope.envelope_id : transportConfig.envelope_id;
+  const serialized = typeof envelope === 'string'
+    ? envelope
+    : Buffer.from(JSON.stringify(envelope)).toString('base64');
+
+  return {
+    type: 'email',
+    provider,
+    to: recipient,
+    subject: `[Handoff] ${envelopeId || 'delivery'}`,
+    body: serialized,
+  };
+}
+
+export function buildMcpInstruction(envelope, transportConfig) {
+  const serialized = typeof envelope === 'string'
+    ? envelope
+    : Buffer.from(JSON.stringify(envelope)).toString('base64');
+
+  return {
+    type: 'mcp',
+    tool: transportConfig.tool_name,
+    params: {
+      [transportConfig.payload_param || 'payload']: serialized,
+      ...(transportConfig.extra_params || {}),
+    },
+  };
+}
+
+export async function sendViaFile(envelope, config) {
+  const outdir = config?.outdir || './handoff-out';
+  await mkdir(outdir, { recursive: true });
+
+  const id = envelope.envelope_id || `env_${Date.now().toString(36)}`;
+  const filepath = join(outdir, `${id}.enc`);
+  const serialized = typeof envelope === 'string'
+    ? envelope
+    : Buffer.from(JSON.stringify(envelope)).toString('base64');
+
+  await writeFile(filepath, serialized);
+  return { type: 'file', delivered: true, ref: id, path: filepath };
+}
+
+export async function readFromFile(envelopeId, config) {
+  const outdir = config?.outdir || './handoff-out';
+  return readFile(join(outdir, `${envelopeId}.enc`), 'utf-8');
+}
+
+export async function listFiles(config) {
+  const outdir = config?.outdir || './handoff-out';
+  try {
+    const files = await readdir(outdir);
+    return files.filter(f => f.endsWith('.enc')).map(f => f.replace('.enc', ''));
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+export async function send(envelope, transportConfig, context) {
+  const type = transportConfig.type || 'file';
+
+  switch (type) {
+    case 'email': {
+      const provider = context?.emailProvider || detectEmailProvider(context?.availableTools);
+      if (!provider) {
+        process.stderr.write(
+          'Warning: No email MCP connected — falling back to file transport.\n' +
+          'Transfer files manually or connect an email MCP server.\n',
+        );
+        return { ...(await sendViaFile(envelope, transportConfig)), fallback: true };
+      }
+      const recipient = context?.side === 'consultant'
+        ? transportConfig.client
+        : transportConfig.consultant;
+      return buildEmailInstruction(envelope, transportConfig, provider, recipient);
+    }
+
+    case 'mcp':
+      return buildMcpInstruction(envelope, transportConfig);
+
+    case 'file':
+      return sendViaFile(envelope, transportConfig);
+
+    default:
+      throw new Error(`Unknown transport type: ${type}`);
+  }
+}