shakers-cli-beta 0.13.0 → 0.14.0

package/src/mcp-role-tools.js

@@ -109,12 +109,13 @@ function makeRoleTools(deps = {}) {
     countOpenPositions = (opts) => require('./find-projects-client').countOpenPositions({}, opts),
     sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
     now = () => Date.now(),
+    funnel = require('./onboarding-funnel').NOOP_FUNNEL,
   } = deps;
 
   const requireSession = () => {
     const session = loadAuthSession();
     if (sessionStatus(session) !== 'active') {
-      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first.');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first.');
     }
     return session;
   };
@@ -317,37 +318,51 @@ function makeRoleTools(deps = {}) {
         const added = await addRole({ clusterId: picked.role.clusterId });
         if (!added.ok) return added;
       }
-      const set = await setMainRole({ clusterId: picked.role.clusterId });
+      const set = await applyMainRole(session, picked.role.clusterId, { suggestion: !picked.add });
       return set.ok ? { ...set, name: picked.role.name } : set;
     }
-    const res = await requestSetMainRole({ clusterId: args.clusterId, hubAccessToken: session.hubAccessToken }, { endpoint: getSetMainRoleEndpoint() });
+    return applyMainRole(session, args.clusterId, { suggestion: args.catalogue === true ? false : undefined });
+  }
+
+  async function applyMainRole(session, clusterId, { suggestion } = {}) {
+    const res = await requestSetMainRole({ clusterId, hubAccessToken: session.hubAccessToken }, { endpoint: getSetMainRoleEndpoint() });
     if (res.ok === false && res.reason === 'http-400') return { ok: false, reason: res.reason, message: 'The talent does not hold that role yet: call add_role with it, then set_main_role again.' };
     if (!res.ok) return { ok: false, reason: res.reason };
-    return { ok: true, clusterId: args.clusterId };
+    funnel.completed('supercluster', { supercluster: clusterId, was_suggestion_accepted: suggestion });
+    funnel.flush();
+    return { ok: true, clusterId };
   }
 
   return [
     {
       name: 'list_available_roles',
-      description: "List the roles the talent can add to their profile (the cluster catalog minus roles they already hold). Each row has clusterId (internal handle), name, category and an optional proposalKind (why it is suggested). Present roles to the talent by NAME; never show clusterId. Requires an active session.",
+      title: 'Roles you can add',
+      description: 'Shows the Shakers roles you can add to your profile.',
+      guidance: "List the roles the talent can add to their profile (the cluster catalog minus roles they already hold). Each row has clusterId (internal handle), name, category and an optional proposalKind (why it is suggested). Present roles to the talent by NAME; never show clusterId. Requires an active session.",
       inputSchema: EMPTY_SCHEMA,
       handler: listAvailableRoles,
     },
     {
       name: 'add_role',
-      description: "Add a role to the talent's profile (a GROWTH role) by clusterId from list_available_roles. Requires an active session. Returns { clusterId, alreadyAssigned? }.",
+      title: 'Add a role',
+      description: 'Adds the role you pick to your Shakers profile.',
+      guidance: "Add a role to the talent's profile (a GROWTH role) by clusterId from list_available_roles. Requires an active session. Returns { clusterId, alreadyAssigned? }.",
       inputSchema: CLUSTER_SCHEMA,
       handler: addRole,
     },
     {
       name: 'list_my_roles',
-      description: "List the roles the talent already holds, plus mainClusterId (their current main role) and `recommended`: the roles the onboarding interview and the CV import suggest, interview first. Use it before set_main_role. In the sign-up pass waitSeconds (20): it waits for the interview evaluation to recommend roles and says when to call again (`pending`) or to fall back to list_available_roles. Follow `message`. clusterId is an internal handle — refer to roles by name to the talent. Requires an active session.",
+      title: 'Your roles',
+      description: 'Shows your roles on Shakers and the ones suggested by your interview and your CV.',
+      guidance: "List the roles the talent already holds, plus mainClusterId (their current main role) and `recommended`: the roles the onboarding interview and the CV import suggest, interview first. Use it before set_main_role. In the sign-up pass waitSeconds (20): it waits for the interview evaluation to recommend roles and says when to call again (`pending`) or to fall back to list_available_roles. Follow `message`. clusterId is an internal handle — refer to roles by name to the talent. Requires an active session.",
       inputSchema: LIST_MY_ROLES_SCHEMA,
       handler: listMyRoles,
     },
     {
       name: 'set_main_role',
-      description: "Set the talent's MAIN role. In the sign-up it is the last step before open_web: after onboarding_interview_complete (or when the talent skipped the interview) and once list_my_roles is no longer pending, call it without clusterId: it asks the talent which of the recommended roles is their main one, with the catalogue as the last option (or straight from the catalogue when nothing is recommended), in a dialog when the client has one; otherwise it returns `say` to print word for word and the roles, to call it again with the clusterId they pick. Then it sets that role (adding a catalogue role first). Also usable standalone with clusterId to change the main role later; catalogue:true adds a catalogue role first. Requires an active session.",
+      title: 'Choose your main role',
+      description: 'Asks you which role is your main one and saves it on your Shakers profile.',
+      guidance: "Set the talent's MAIN role. In the sign-up it is the last step before open_web: after onboarding_interview_complete (or when the talent skipped the interview) and once list_my_roles is no longer pending, call it without clusterId: it asks the talent which of the recommended roles is their main one, with the catalogue as the last option (or straight from the catalogue when nothing is recommended), in a dialog when the client has one; otherwise it returns `say` to print word for word and the roles, to call it again with the clusterId they pick. Then it sets that role (adding a catalogue role first). Also usable standalone with clusterId to change the main role later; catalogue:true adds a catalogue role first. Requires an active session.",
       inputSchema: SET_MAIN_ROLE_SCHEMA,
       handler: setMainRole,
     },

package/src/mcp-saved-positions-tools.js

@@ -19,7 +19,7 @@ function makeSavedPositionsTools(deps = {}) {
   const requireLoginSession = () => {
     const session = loadAuthSession();
     if (sessionStatus(session) !== 'active') {
-      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first (this tool is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (this tool is session-gated).');
     }
     return session;
   };
@@ -36,13 +36,17 @@ function makeSavedPositionsTools(deps = {}) {
   return [
     {
       name: 'save_project',
-      description: 'Bookmark a project/Position for the talent (Find Positions "Saved"). Idempotent — saving twice is a no-op. Requires an active session and the position id. The position id is an INTERNAL handle for calling tools — never show or mention it to the talent.',
+      title: 'Save a project',
+      description: 'Saves a project to your list on Shakers.',
+      guidance: 'Bookmark a project/Position for the talent (Find Positions "Saved"). Idempotent — saving twice is a no-op. Requires an active session and the position id. The position id is an INTERNAL handle for calling tools — never show or mention it to the talent.',
       inputSchema: ID_SCHEMA,
       handler: toggle(savePosition),
     },
     {
       name: 'unsave_project',
-      description: 'Remove a project/Position bookmark for the talent. Idempotent — un-saving something not saved is not an error. Requires an active session and the position id. The position id is an INTERNAL handle for calling tools — never show or mention it to the talent.',
+      title: 'Remove a saved project',
+      description: 'Removes a project from your saved list on Shakers.',
+      guidance: 'Remove a project/Position bookmark for the talent. Idempotent — un-saving something not saved is not an error. Requires an active session and the position id. The position id is an INTERNAL handle for calling tools — never show or mention it to the talent.',
       inputSchema: ID_SCHEMA,
       handler: toggle(unsavePosition),
     },

package/src/mcp-server.js

@@ -34,7 +34,7 @@ function errorResponse(id, code, message, data) {
   return { jsonrpc: JSONRPC, id: id === undefined ? null : id, error };
 }
 
-function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVersion, beforeCall = null, instructions = null, elicitationTimeoutMs = ELICITATION_TIMEOUT_MS } = {}) {
+function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVersion, beforeCall = null, onInitialize = null, instructions = null, elicitationTimeoutMs = ELICITATION_TIMEOUT_MS } = {}) {
   const registry = new Map();
   for (const t of tools) {
     if (!t || !t.name || typeof t.handler !== 'function') {
@@ -107,11 +107,14 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
     }
   }
 
+  // `description` and `title` are what the talent reads in the client; `guidance` is how the model must use the tool, so it rides in the schema.
   function shapeTool(t) {
+    const schema = t.inputSchema || { type: 'object' };
     return {
       name: t.name,
+      ...(t.title ? { title: t.title } : {}),
       description: t.description || '',
-      inputSchema: t.inputSchema || { type: 'object' },
+      inputSchema: t.guidance ? { ...schema, description: [t.guidance, schema.description].filter(Boolean).join(' ') } : schema,
     };
   }
 
@@ -205,6 +208,9 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
         case 'initialize': {
           const requested = msg.params && msg.params.protocolVersion;
           clientCapabilities = (msg.params && msg.params.capabilities) || {};
+          if (typeof onInitialize === 'function') {
+            try { onInitialize({ clientInfo: (msg.params && msg.params.clientInfo) || {} }); } catch { /* never breaks the handshake */ }
+          }
           // One line per connection on stderr (never stdout: it carries JSON-RPC), so the host's
           // declared elicitation shape and the resulting decision are visible in the MCP log.
           process.stderr.write(`  [mcp] initialize elicitation=${JSON.stringify(clientCapabilities.elicitation)} -> elicit=${canElicitForm()}\n`);

package/src/mcp-show-project-tools.js

@@ -20,7 +20,7 @@ function makeShowProjectTools(deps = {}) {
   const requireLoginSession = () => {
     const session = loadAuthSession();
     if (sessionStatus(session) !== 'active') {
-      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first (show_project is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (show_project is session-gated).');
     }
     return session;
   };
@@ -37,7 +37,9 @@ function makeShowProjectTools(deps = {}) {
   return [
     {
       name: 'show_project',
-      description: "Get the full detail of one Position/Project available to the talent (Shakers Find Positions detail): title, parent project, company, budget, work mode, required skills/languages, description, goals, FAQs, and the talent's saved/applied/canApply state. Requires an active session and the position id. The `id` (and any positionId/projectId in the result) is an INTERNAL handle for calling tools — NEVER show or mention it to the talent; refer to the project by its title/company.",
+      title: 'See a project',
+      description: 'Shows the full details of one Shakers project.',
+      guidance: "Get the full detail of one Position/Project available to the talent (Shakers Find Positions detail): title, parent project, company, budget, work mode, required skills/languages, description, goals, FAQs, and the talent's saved/applied/canApply state. Requires an active session and the position id. The `id` (and any positionId/projectId in the result) is an INTERNAL handle for calling tools — NEVER show or mention it to the talent; refer to the project by its title/company.",
       inputSchema: SHOW_PROJECT_SCHEMA,
       handler: showProject,
     },

package/src/mcp-signup-tools.js

@@ -6,9 +6,12 @@ const {
 } = require('./onboarding-flow');
 const { signupCopy, legalCopy, renderDraft, amount } = require('./signup-copy');
 const { fixSignupLanguage, signupLanguage } = require('./signup-language');
+const path = require('path');
 const { readLocalCv } = require('./cv-file');
 const { emailFromHubToken } = require('./auth-session-store');
-const { askAfterTexts, optionFor, queueNotice, takeNotices } = require('./mcp-choice');
+const { askAfterTexts, askConsent, optionFor, queueNotice, takeNotices } = require('./mcp-choice');
+const { expandHome, tildify } = require('./env-paths');
+const { NOOP_FUNNEL, weeklyHours, rateTypes, workSituationValue } = require('./onboarding-funnel');
 
 // MCP sign-up (ticket 39540): hub imports into an UNREGISTERED profile that the local window claims with a code kept only in memory.
 
@@ -173,6 +176,15 @@ const EMAIL_SCHEMA = {
 
 // In the order the data notice names them.
 const DRAFT_SOURCES = ['linkedin', 'cv'];
+const DRAFT_FIELDS = ['name', 'role', 'city', 'country', 'situation', 'participation', 'yearsOfExperience', 'stack', 'languages', 'workMode', 'monthlyHours', 'hourlyRate', 'annualRate'];
+// Draft fields per funnel step, for was_edited.
+const STEP_DRAFT_FIELDS = {
+  work_situation: ['situation', 'participation'],
+  availability: ['monthlyHours', 'workMode'],
+  rates: ['hourlyRate', 'annualRate'],
+  languages: ['languages'],
+  location: ['country', 'city'],
+};
 
 const DRAFT_SCHEMA = {
   type: 'object',
@@ -181,6 +193,9 @@ const DRAFT_SCHEMA = {
     name: { type: 'string', description: 'Full name.' },
     role: { type: 'string', description: 'Role, e.g. "Data Engineer".' },
     city: { type: 'string' },
+    country: { type: 'string', description: 'ISO-2 country code (ES, US, GB): the same country save_profile_details will write.' },
+    situation: { type: 'string', enum: WORK_SITUATIONS, description: 'Current work situation, the same code save_profile_details will write.' },
+    participation: { type: 'string', enum: EMPLOYMENT_PARTICIPATIONS, description: 'Only when situation is EMPLOYED.' },
     yearsOfExperience: { type: 'number' },
     stack: { type: 'string', description: 'Main technologies, comma separated, at most five.' },
     languages: { type: 'string', description: 'Languages and level, e.g. "Español nativo, inglés C1".' },
@@ -230,6 +245,7 @@ const IMPORT_SCHEMA = {
     websiteUrl: { type: 'string' },
     userQuery: { type: 'string', description: 'Everything you know about the talent, as free text.' },
     language: { type: 'string', enum: [...IMPORT_LANGUAGES] },
+    answer: { type: 'string', description: 'The option the talent picked when you printed the question this tool returned about the CV file. Never set it yourself.' },
   },
 };
 
@@ -288,6 +304,7 @@ function makeSignupTools(deps = {}) {
     fetchPricingRate = (opts) => require('./rate-client').fetchPricingRate({}, opts),
     fetchAvailability = (opts) => require('./availability-client').fetchAvailability({}, opts),
     fetchLanguages = (opts) => require('./profile-client').fetchLanguages({}, opts),
+    funnel = NOOP_FUNNEL,
     fetchTelephone = (opts) => require('./profile-client').fetchTelephone({}, opts),
     openBrowser = require('./open-file').openPath,
     sleep = defaultSleep,
@@ -301,6 +318,7 @@ function makeSignupTools(deps = {}) {
     sessionToken: null,
     email: null,
     draft: null,
+    firstDraft: null,
     draftConfirmed: false,
     keepProfile: false,
     // Fields the update question already told the talent they keep.
@@ -313,11 +331,18 @@ function makeSignupTools(deps = {}) {
     failedSources: new Set(),
     cvPath: null,
     wake: null,
+    importStartedAt: null,
+    importReported: new Set(),
   };
   currentSignup = state;
 
   function setAccount(next) {
+    const before = state.account.state;
     state.account = next;
+    if ((next.state === 'created' || next.state === 'existing') && before !== next.state) {
+      funnel.completed('account_creation', { auth_method: next.via, is_returning_account: next.state === 'existing' });
+      funnel.identified();
+    }
     if (state.wake) state.wake();
   }
 
@@ -432,7 +457,12 @@ function makeSignupTools(deps = {}) {
     }
     if (!nonEmpty(args.answer)) {
       fixSignupLanguage(args.language);
+      funnel.begin();
+      funnel.viewed('start');
       state.draft = null;
+      state.firstDraft = null;
+      state.importStartedAt = null;
+      state.importReported = new Set();
       state.draftConfirmed = false;
       state.email = null;
       state.failedSources.clear();
@@ -447,13 +477,14 @@ function makeSignupTools(deps = {}) {
     // A CV path in the first message already answers the CV question: that CV is read, and the welcome
     // rides on the next question block, because models skip a relay that comes before another tool call.
     if (!nonEmpty(args.answer) && state.cvPath) {
+      funnel.completed('start');
       queueNotice(c.welcome(nonEmpty(args.firstName)));
       return {
         ok: true,
         step: 'cv-given',
         cvPath: state.cvPath,
         language: lang(),
-        message: `Never explain to the talent what you are doing or what the CV holds: every text they read in this step comes from the tools, the welcome included. Now read_cv cvPath with talentConsent:true, asking nothing about the CV. ${linkedin}`,
+        message: `Never explain to the talent what you are doing or what the CV holds: every text they read in this step comes from the tools, the welcome included. Now call read_cv with cvPath: it asks the talent itself before reading the file, so ask nothing about the CV in your own words. ${linkedin}`,
       };
     }
     const asked = await askAfterTexts(ctx, {
@@ -464,6 +495,7 @@ function makeSignupTools(deps = {}) {
       answer: args.answer,
     });
     if (asked.reply) return { ...asked.reply, language: lang() };
+    funnel.completed('start');
     // A CV path the talent gave wins over both answers: searching could read another candidate.
     const cvPath = state.cvPath;
     if (cvPath) {
@@ -471,7 +503,7 @@ function makeSignupTools(deps = {}) {
         ok: true,
         step: 'cv-given',
         cvPath,
-        message: `The talent already gave their CV: read_cv it now with talentConsent:true, saying nothing about attaching it. ${linkedin}`,
+        message: `The talent already gave their CV: call read_cv with cvPath now (it asks the talent itself before reading the file), saying nothing about attaching it. ${linkedin}`,
       };
     }
     if (asked.answer === c.cvSearch) {
@@ -479,7 +511,7 @@ function makeSignupTools(deps = {}) {
         ok: true,
         step: 'cv-search',
         cvNotFound: c.cvNotFound,
-        message: `The talent allowed you to look for their CV: call suggest_register_context, then read_cv on its first candidate without asking again, even when nameMatch is null (their name is just unknown). Only if there is no candidate, or every one comes back mentionsTalent:false, show \`cvNotFound\` word for word and wait for the file. ${linkedin}`,
+        message: `The talent chose to look for their CV on this computer: call suggest_register_context, then read_cv on its first candidate, even when nameMatch is null (their name is just unknown). Each of them asks the talent itself before searching or reading, so ask nothing in your own words. Only if there is no candidate, or every one comes back mentionsTalent:false, show \`cvNotFound\` word for word and wait for the file. ${linkedin}`,
       };
     }
     return {
@@ -525,9 +557,10 @@ function makeSignupTools(deps = {}) {
     const pricing = pricingFromRates(args);
     if (!pricing.ok) return pricing;
     const draft = {};
-    for (const key of ['name', 'role', 'city', 'yearsOfExperience', 'stack', 'languages', 'workMode', 'monthlyHours', 'hourlyRate', 'annualRate']) {
+    for (const key of DRAFT_FIELDS) {
       if (args[key] !== undefined && args[key] !== null && args[key] !== '') draft[key] = args[key];
     }
+    if (typeof draft.country === 'string') draft.country = draft.country.trim().toUpperCase();
     if (!draft.name || !draft.role) return { ok: false, reason: 'draft-incomplete', message: 'The draft needs at least name and role: read the CV first.' };
     if (draft.hourlyRate === undefined || draft.annualRate === undefined) {
       return { ok: false, reason: 'draft-rates-required', message: 'The draft needs both rates: if the talent gave them, send them with ratesFromTalent:true; otherwise estimate hourlyRate (€/h) and annualRate (€/year) from role, seniority, stack and location, and send them without it. Then call signup_draft again.' };
@@ -538,6 +571,7 @@ function makeSignupTools(deps = {}) {
     if (!sources.length && !optionFor(args.answer, [c.draftOk, c.draftChange])) {
       return { ok: false, reason: 'draft-sources-required', message: "The draft needs sources: 'cv' if you read their CV, 'linkedin' only if you have their LinkedIn URL. Then call signup_draft again." };
     }
+    if (!state.firstDraft) state.firstDraft = draft;
     const asked = await askAfterTexts(ctx, {
       tool: 'signup_draft',
       texts: [renderDraft(lang(), draft), legalCopy(lang()).signupNotice(sources), knownAccount() ? c.windowNoticeSignIn : c.windowNotice],
@@ -617,7 +651,16 @@ function makeSignupTools(deps = {}) {
     state.sources = sources;
     state.reported = { account: 'waiting', import: 'none' };
     const reused = state.account.state === 'waiting';
-    if (!reused) await openWindow(identity);
+    if (!state.importStartedAt) {
+      const attempted = DRAFT_SOURCES.filter((source) => (source === 'cv' ? !!cv : !!sources.linkedinUrl));
+      state.importStartedAt = Object.fromEntries(attempted.map((source) => [source, now()]));
+      for (const source of attempted) funnel.track('source_import_started', 'import_sources', { source_type: source });
+      funnel.completed('import_sources', { sources_attempted: attempted });
+    }
+    if (!reused) {
+      funnel.viewed('account_creation');
+      await openWindow(identity);
+    }
     return {
       ok: true,
       status: 'window-open',
@@ -628,13 +671,35 @@ function makeSignupTools(deps = {}) {
     };
   }
 
+  function trackImportOutcome(imp) {
+    if (!state.importStartedAt) return;
+    let tracked = false;
+    for (const [source, startedAt] of Object.entries(state.importStartedAt)) {
+      if (state.importReported.has(source)) continue;
+      const outcome = imp.sources && imp.sources[source] ? imp.sources[source].state : (imp.state === 'failed' ? 'failed' : null);
+      if (outcome !== 'done' && outcome !== 'failed') continue;
+      state.importReported.add(source);
+      const code = imp.sources && imp.sources[source] && imp.sources[source].code ? imp.sources[source].code : imp.code;
+      funnel.track(outcome === 'done' ? 'source_import_completed' : 'source_import_failed', 'import_sources', {
+        source_type: source,
+        duration_ms: Math.max(0, now() - startedAt),
+        ...(outcome === 'failed' && code ? { failure_reason: code } : {}),
+      });
+      tracked = true;
+    }
+    if (tracked) funnel.flush();
+  }
+
   async function readImport() {
     // An account that already existed got no import from this sign-up: its last import is not news.
     if (state.account.state === 'existing') return { state: 'none' };
     const session = resolved.loadAuthSession();
     if (resolved.sessionStatus(session) !== 'active' || !session || !session.hubAccessToken) return { state: 'none' };
     const res = await requestMyImportStatus({ hubAccessToken: session.hubAccessToken }, { endpoint: getMyImportStatusEndpoint() });
-    return res.ok ? { state: res.state, sources: res.sources, ...(res.code ? { code: res.code } : {}) } : { state: 'unknown', reason: res.reason };
+    if (!res.ok) return { state: 'unknown', reason: res.reason };
+    const imp = { state: res.state, sources: res.sources, ...(res.code ? { code: res.code } : {}) };
+    trackImportOutcome(imp);
+    return imp;
   }
 
   function nextSteps(account) {
@@ -644,7 +709,7 @@ function makeSignupTools(deps = {}) {
       return `This talent already had an account and signed in. Call update_existing_profile: it shows what would change and asks whether to update, and its text tells the talent about the account, so say nothing about it yourself. ${aiUsage} ${interview}`;
     }
     const unclaimed = account.claimed === false ? ' This account did not take over the imported profile: call import_profile with the same LinkedIn/CV first.' : '';
-    return `The account exists.${unclaimed} Now, without asking: save_profile_details with the confirmed draft (situation, motivation, both rates, availability and location, languages). ${aiUsage} ${interview}`;
+    return `The account exists.${unclaimed} Now, without asking: save_profile_details with the confirmed draft (situation, motivation, both rates, availability and location with its country, languages). ${aiUsage} ${interview}`;
   }
 
   // A source that did not import gets its fixed line once, on the next question block.
@@ -697,6 +762,19 @@ function makeSignupTools(deps = {}) {
     return out;
   }
 
+  // The tool: a CV file from this computer is sent only after the talent says yes to that file.
+  async function importProfileAsked(args = {}, ctx = {}) {
+    if (nonEmpty(args.cvPath)) {
+      const file = path.resolve(expandHome(nonEmpty(args.cvPath)));
+      const c = copy().consent;
+      const asked = await askConsent(ctx, { tool: 'import_profile', key: `import_profile:${file}`, question: c.cvSend(tildify(file)), yes: c.yes, no: c.no, answer: args.answer });
+      if (asked.reply) return asked.reply;
+      if (!asked.granted) return { ok: false, reason: 'consent-declined', message: 'The talent said no: nothing was sent. Do not send that file; call import_profile again without cvPath if the other sources still need importing.' };
+      return importProfile({ ...args, cvPath: file });
+    }
+    return importProfile(args);
+  }
+
   async function importProfile(args = {}) {
     if (nonEmpty(args.linkedinUrl) && !isLinkedinProfileUrl(nonEmpty(args.linkedinUrl))) return { ok: false, reason: 'invalid-linkedin-url', message: INVALID_LINKEDIN_MESSAGE };
     const res = await flow.startProfileImport(resolved, {
@@ -710,7 +788,7 @@ function makeSignupTools(deps = {}) {
     });
     if (!res.ok) {
       if (res.reason === 'no-session') {
-        return { ok: false, reason: isSignupPending() ? 'signup-pending' : 'no-session', message: isSignupPending() ? 'The account does not exist yet: wait for signup_status to report it.' : 'The talent is not signed in: use login first.' };
+        return { ok: false, reason: isSignupPending() ? 'signup-pending' : 'no-session', message: isSignupPending() ? 'The account does not exist yet: wait for signup_status to report it.' : 'The talent is not signed in: sign them in with social_signin_start first.' };
       }
       return { ok: false, reason: res.reason };
     }
@@ -869,6 +947,40 @@ function makeSignupTools(deps = {}) {
     return c.ratesSaved(shown, !(state.draft && state.draft.ratesFromTalent));
   }
 
+  function wasEdited(step) {
+    if (!state.firstDraft || !state.draft) return undefined;
+    return STEP_DRAFT_FIELDS[step].some((key) => String(state.firstDraft[key] ?? '') !== String(state.draft[key] ?? ''));
+  }
+
+  function trackSavedSteps(details, results) {
+    const saved = (section) => results[section] && results[section].ok === true;
+    const step = (name, props) => funnel.completed(name, { ...props, is_prefilled: true, was_edited: wasEdited(name) });
+    if (saved('workSituation')) {
+      step('work_situation', { work_situation: workSituationValue(String(details.workSituation.situation || '').trim().toUpperCase()) });
+    }
+    if (saved('availability')) {
+      const a = details.availability;
+      step('availability', { availability_hours_per_week: weeklyHours(a.monthlyHours) });
+      const country = typeof a.country === 'string' && /^[A-Za-z]{2}$/.test(a.country.trim()) ? a.country.trim().toUpperCase() : null;
+      const proposed = state.firstDraft && state.firstDraft.country;
+      const modes = Array.isArray(a.workModes) ? a.workModes.map((m) => String(m).toUpperCase()) : [];
+      step('location', {
+        location_country: country ? country.toLowerCase() : undefined,
+        location_method: country && proposed === country ? 'prefilled' : 'manual',
+        is_remote_only: modes.length ? modes.every((m) => m === 'REMOTE') : undefined,
+      });
+    }
+    if (saved('pricing')) {
+      const types = rateTypes(pricingFromRates(details.pricing).input);
+      funnel.completed('rates', { rate_types_selected: types, rate_type: types[0], rate_currency: 'EUR', is_prefilled: !(state.draft && state.draft.ratesFromTalent), was_edited: wasEdited('rates') });
+    }
+    if (saved('languages')) {
+      const codes = details.languages.map((row) => String(row.language || '').trim().toLowerCase()).filter(Boolean);
+      step('languages', { languages_count: codes.length, languages: codes });
+    }
+    funnel.flush();
+  }
+
   async function saveProfileDetails(args = {}) {
     const { saved } = copy();
     const existing = state.account.state === 'existing';
@@ -902,6 +1014,7 @@ function makeSignupTools(deps = {}) {
         results.phone = again.ok ? { ok: true } : { ok: false, reason: again.reason };
       }
     }
+    trackSavedSteps(details, results);
     const confirmations = sections.filter(([name]) => results[name] && results[name].ok).map(([, , , text]) => text);
     const ok = Object.values(results).every((r) => r.ok);
     const report = keptReport(kept);
@@ -974,61 +1087,81 @@ function makeSignupTools(deps = {}) {
   return [
     {
       name: 'signup_start',
-      description: "FIRST call when the talent asks to sign up or register on Shakers, before you write anything: pass `language` = the language of their message. It returns the welcome to show word for word and its one question (send me your CV, or shall I look for it on this computer?). Then follow its message: CV, LinkedIn, signup_email, signup_draft, signup_create_account, signup_status. Every text it and the next sign-up tools return in `say` or relayVerbatim is printed word for word, in that language.",
+      title: 'Start your Shakers sign-up',
+      description: 'Starts your sign-up here in the chat and asks whether you send your CV or want it looked for on this computer.',
+      guidance: "FIRST call when the talent asks to sign up or register on Shakers, before you write anything: pass `language` = the language of their message. It returns the welcome to show word for word and its one question (send me your CV, or shall I look for it on this computer?). Then follow its message: CV, LinkedIn, signup_email, signup_draft, signup_create_account, signup_status. Every text it and the next sign-up tools return in `say` or relayVerbatim is printed word for word, in that language.",
       inputSchema: WELCOME_SCHEMA,
       handler: signupStart,
     },
     {
       name: 'signup_email',
-      description: 'Sign-up step after the CV and LinkedIn: asks which email to create the account with (the one they read most). Pass the best email you know, or none. Never comment on the email yourself.',
+      title: 'Choose your account email',
+      description: 'Asks which email your Shakers account will use.',
+      guidance: 'Sign-up step after the CV and LinkedIn: asks which email to create the account with (the one they read most). Pass the best email you know, or none. Never comment on the email yourself.',
       inputSchema: EMAIL_SCHEMA,
       handler: signupEmail,
     },
     {
       name: 'signup_draft',
-      description: 'Sign-up step before the account: shows the talent the profile draft you prepared from their CV, LinkedIn and what you know, with the data notice and how the account window works, and asks them to confirm it. The window to create the account opens only after they confirm.',
+      title: 'Review your profile draft',
+      description: 'Shows the profile draft prepared from your CV and LinkedIn, explains how your data is used and asks you to confirm it. Your account is not created until you confirm.',
+      guidance: 'Sign-up step before the account: shows the talent the profile draft you prepared from their CV, LinkedIn and what you know, with the data notice and how the account window works, and asks them to confirm it. The window to create the account opens only after they confirm.',
       inputSchema: DRAFT_SCHEMA,
       handler: signupDraft,
     },
     {
       name: 'signup_create_account',
-      description: "After the talent confirmed the draft: starts the profile import on Shakers and, a few seconds later, opens a window in the talent's browser where they create the account with Google or a password, or sign in if they already have one. No password ever goes through the chat. Returns next: signup_status.",
+      title: 'Create your account',
+      description: 'Once you confirm the draft, sends your CV, LinkedIn and draft to Shakers and opens a browser window where you create your account with Google or a password. Your password never goes through the chat.',
+      guidance: "After the talent confirmed the draft: starts the profile import on Shakers and, a few seconds later, opens a window in the talent's browser where they create the account with Google or a password, or sign in if they already have one. No password ever goes through the chat. Returns next: signup_status.",
       inputSchema: CREATE_SCHEMA,
       handler: signupCreateAccount,
     },
     {
       name: 'signup_status',
-      description: "State of the sign-up: account (waiting | created | existing | failed) and, once it exists, the profile import per source (linkedin, cv: running | done | failed). Pass waitSeconds (up to 25) to wait for a change. Follow `message`: it gives the remaining steps. Never show internal codes to the talent.",
+      title: 'Sign-up progress',
+      description: 'Shows whether your account is ready and how the import of your profile is going.',
+      guidance: "State of the sign-up: account (waiting | created | existing | failed) and, once it exists, the profile import per source (linkedin, cv: running | done | failed). Pass waitSeconds (up to 25) to wait for a change. Follow `message`: it gives the remaining steps. Never show internal codes to the talent.",
       inputSchema: STATUS_SCHEMA,
       handler: signupStatus,
     },
     {
       name: 'update_existing_profile',
-      description: 'When signup_status says the talent already had an account: shows what the confirmed draft would fill in the empty fields of their profile and the value each field they already had keeps, and asks whether to update it; on yes it imports their LinkedIn/CV filling only what is empty.',
+      title: 'Update your existing profile',
+      description: 'If you already had an account, shows what your draft would add to the empty fields of your profile and asks before changing anything. It never overwrites what you already filled in.',
+      guidance: 'When signup_status says the talent already had an account: shows what the confirmed draft would fill in the empty fields of their profile and the value each field they already had keeps, and asks whether to update it; on yes it imports their LinkedIn/CV filling only what is empty.',
       inputSchema: UPDATE_EXISTING_SCHEMA,
       handler: updateExistingProfile,
     },
     {
       name: 'import_profile',
-      description: "Import LinkedIn, CV, GitHub or website into the SIGNED-IN talent's profile, filling only what is empty: existing texts and languages are kept, lists are added without duplicates. Use it when the sign-up import failed for a source, or for a non-PDF CV. Takes up to ~90 s.",
+      title: 'Import into your profile',
+      description: 'Sends your LinkedIn, GitHub or website to Shakers to fill the empty parts of your profile, and a CV file from this computer only after asking you first. What you already wrote is kept.',
+      guidance: "Import LinkedIn, CV, GitHub or website into the SIGNED-IN talent's profile, filling only what is empty: existing texts and languages are kept, lists are added without duplicates. Use it when the sign-up import failed for a source, or for a non-PDF CV. With cvPath the tool first asks the talent, naming the file (a dialog when the client has one, otherwise it returns `say` to print word for word as your whole reply); nothing is sent until they answer yes. After a `say`, call it again with the same arguments and answer set to the option they pick. Never answer for them. Takes up to ~90 s.",
       inputSchema: IMPORT_SCHEMA,
-      handler: importProfile,
+      handler: importProfileAsked,
     },
     {
       name: 'save_profile_details',
-      description: "After the account exists, write the confirmed draft — work situation and motivation, hourly rate and annual target, availability and location, languages, phone — WITHOUT asking again: they can edit every field on the web. Each section is saved on its own; returns per-section results. On an account that already existed it only fills what the profile leaves empty, never overwrites a value the talent set.",
+      title: 'Save your profile details',
+      description: 'Saves the details you confirmed in your draft (work situation, rates, availability, location, languages and phone) to your Shakers profile. On an existing account it only fills empty fields.',
+      guidance: "After the account exists, write the confirmed draft — work situation and motivation, hourly rate and annual target, availability and location, languages, phone — WITHOUT asking again: they can edit every field on the web. Each section is saved on its own; returns per-section results. On an account that already existed it only fills what the profile leaves empty, never overwrites a value the talent set.",
       inputSchema: buildDetailsSchema(deps.lang || 'en'),
       handler: saveProfileDetails,
     },
     {
       name: 'open_web',
-      description: "Open Shakers in the talent's browser already signed in (one-time link, valid 2 minutes, single use). Use it at the end of the sign-up, or when the onboarding interview has to be done on the web. Returns { opened, loggedIn }, plus `link` only when the browser was not opened.",
+      title: 'Open Shakers in your browser',
+      description: 'Opens Shakers in your browser, already signed in.',
+      guidance: "Open Shakers in the talent's browser already signed in (one-time link, valid 2 minutes, single use). Use it at the end of the sign-up, or when the onboarding interview has to be done on the web. Returns { opened, loggedIn }, plus `link` only when the browser was not opened.",
       inputSchema: { type: 'object', properties: { open: { type: 'boolean', description: 'false returns a fresh link without opening the browser: only when the talent says the browser did not open.' } } },
       handler: openWeb,
     },
     {
       name: 'open_linkedin_profile',
-      description: "Open the talent's own LinkedIn profile in their browser (linkedin.com/in/me redirects to it) so they copy the address bar. Use it ONLY when the talent says they do not know where to find their LinkedIn URL, and only after showing them, word for word, the `linkedinOpening` text signup_start returned.",
+      title: 'Open your LinkedIn profile',
+      description: 'Opens your own LinkedIn profile in your browser so you can copy its address.',
+      guidance: "Open the talent's own LinkedIn profile in their browser (linkedin.com/in/me redirects to it) so they copy the address bar. Use it ONLY when the talent says they do not know where to find their LinkedIn URL, and only after showing them, word for word, the `linkedinOpening` text signup_start returned.",
       inputSchema: { type: 'object', properties: {} },
       handler: openLinkedinProfile,
     },

package/src/mcp-socials-tools.js

@@ -14,7 +14,7 @@ function makeSocialsTools(deps = {}) {
   const requireLoginSession = () => {
     const session = loadAuthSession();
     if (sessionStatus(session) !== 'active') {
-      throw new Error('no active Shakers session — call the login tool (or run `shakers login`) first (list_socials is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (list_socials is session-gated).');
     }
     return session;
   };
@@ -29,7 +29,9 @@ function makeSocialsTools(deps = {}) {
   return [
     {
       name: 'list_socials',
-      description: "View the talent's social links (linkedin/github/website/twitter/instagram/facebook/dribbble/behance — null when unset). Read-only. Requires an active session.",
+      title: 'Your social links',
+      description: 'Shows the social and web links on your Shakers profile.',
+      guidance: "View the talent's social links (linkedin/github/website/twitter/instagram/facebook/dribbble/behance — null when unset). Read-only. Requires an active session.",
       inputSchema: LIST_SOCIALS_SCHEMA,
       handler: listSocials,
     },