shakers-cli-beta 0.12.0 → 0.14.0

package/src/mcp-rate-tools.js

@@ -14,7 +14,7 @@ function makeRateTools(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 (get_rate is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (get_rate is session-gated).');
     }
     return session;
   };
@@ -29,7 +29,9 @@ function makeRateTools(deps = {}) {
   return [
     {
       name: 'get_rate',
-      description: "View the talent's rates as the web shows them: partTimePrice is the hourly rate (per hour) and fullTimePrice the annual target (per year); a variant not selected is not offered. Read-only. Requires an active session. Show only the human-facing amounts/currency; any internal ids in the result are handles for tools only — never show or mention them to the talent.",
+      title: 'Your rates',
+      description: 'Shows your hourly rate and your yearly target on Shakers.',
+      guidance: "View the talent's rates as the web shows them: partTimePrice is the hourly rate (per hour) and fullTimePrice the annual target (per year); a variant not selected is not offered. Read-only. Requires an active session. Show only the human-facing amounts/currency; any internal ids in the result are handles for tools only — never show or mention them to the talent.",
       inputSchema: GET_RATE_SCHEMA,
       handler: getRate,
     },

package/src/mcp-register-tools.js

@@ -1,7 +1,9 @@
 'use strict';
 
 const { TranscriptBuffer } = require('./interview-transcript');
-const { askChoice } = require('./mcp-choice');
+const path = require('path');
+const { askChoice, askConsent } = require('./mcp-choice');
+const { expandHome, tildify } = require('./env-paths');
 
 const ANSWER_MODES = ['drafted', 'own', 'full'];
 
@@ -62,7 +64,7 @@ function withTimeout(promise, ms) {
   return Promise.race([promise, expiry]).finally(() => clearTimeout(timer));
 }
 
-// No telemetry ships in this package: stderr reaches the MCP client's server log, with what is needed to size the gap.
+// Stays local (stderr, the MCP client's log); only the sign-up funnel is sent.
 function defaultReportLivekitFailure(kind, error) {
   const cause = error && error.cause && error.cause.message ? error.cause.message : (error && error.message) || '';
   process.stderr.write(`  [mcp] livekit-unavailable kind=${kind} os=${process.platform} arch=${process.arch} node=${process.version} cause=${JSON.stringify(cause.slice(0, 300))}\n`);
@@ -85,6 +87,8 @@ function makeRegisterTools(deps = {}) {
   const textLang = () => require('./signup-language').signupLanguage(lang);
   const copy = () => require('./signup-copy').signupCopy(textLang());
   const checkCompleted = deps.checkOnboardingCompleted || require('./onboarding-availability').checkOnboardingCompleted;
+  const funnel = deps.funnel || require('./onboarding-funnel').NOOP_FUNNEL;
+  const track = (record) => { record(); funnel.flush(); };
 
   // The LiveKit room is a live WebRTC connection that must survive between the
   // separate start/turn/complete JSON-RPC calls of this long-lived stdio server.
@@ -115,6 +119,7 @@ function makeRegisterTools(deps = {}) {
   }
 
   function interviewLater() {
+    track(() => funnel.completed('pre_interview', { interview_choice: 'skip' }));
     return { ok: false, reason: 'interview-later', message: 'The talent does the interview later on the web: skip it here and go on with the main role, then open_web.' };
   }
 
@@ -149,7 +154,7 @@ function makeRegisterTools(deps = {}) {
         reason: 'onboarding-already-completed',
         alreadyCompleted: true,
         message:
-          'You have already completed the onboarding interview. Re-running it is optional. If the talent explicitly wants to repeat it, call again with confirmRepeat:true.',
+          'The talent already completed the onboarding interview: skip it and say nothing about it to the talent, just go on with the next step. Only if the talent themselves asks to repeat it, call again with confirmRepeat:true.',
       };
     }
     if (!CHAT_INTERVIEW_LANGUAGES.has(textLang())) {
@@ -157,6 +162,7 @@ function makeRegisterTools(deps = {}) {
     }
     const acknowledged = args.disclaimerAcknowledged === true;
     if (!acknowledged) {
+      track(() => funnel.viewed('pre_interview'));
       const where = await askWhere(args, ctx);
       if (where.here === false) return interviewLater();
       if (where.chat) {
@@ -181,8 +187,10 @@ function makeRegisterTools(deps = {}) {
         message: `${answer.chat.choiceMessage} Then call onboarding_interview_start again with where:"here", disclaimerAcknowledged:true and answerMode: drafted for the first option, own for the second, full for the third.`,
       };
     }
+    track(() => funnel.completed('pre_interview', { interview_choice: 'start_now' }));
     const room = {};
     const opened = await withTimeout(openRoom(args, room), interviewTimeoutMs);
+    if (opened === TIMED_OUT || !opened.ok) track(() => funnel.errored('interview', opened === TIMED_OUT ? 'timeout' : opened.reason));
     if (opened === TIMED_OUT) {
       room.abandoned = true;
       if (room.client) room.client.disconnect().catch(() => {});
@@ -190,6 +198,7 @@ function makeRegisterTools(deps = {}) {
     }
     if (!opened.ok) return opened;
     interviewSessions.set(opened.interviewId, { client: opened.client, buffer: opened.buffer, connectAt: Date.now(), ended: opened.opening.ended === true });
+    track(() => funnel.viewed('interview', { interview_mode: 'text' }));
     return { ok: true, interviewId: opened.interviewId, answerMode: answer.mode, greeting: opened.opening.text, ended: opened.opening.ended === true };
   }
 
@@ -275,6 +284,7 @@ function makeRegisterTools(deps = {}) {
     const saved = await teardownInterview(args.interviewId, { persist: true });
     if (!saved.ok) return { ok: false, reason: saved.reason || 'complete-failed' };
     lastCompletedInterview = { interviewId: args.interviewId, completedAt: Date.now() };
+    track(() => funnel.completed('interview', { interview_mode: 'text' }));
     return { ok: true, state: 'taken', message: catalog.interviewComplete };
   }
 
@@ -311,8 +321,12 @@ function makeRegisterTools(deps = {}) {
     };
   }
 
-  // Content-free context the model may PROPOSE to the talent (never auto-write).
-  async function suggestContext(args = {}) {
+  // Content-free context the model may PROPOSE to the talent (never auto-write), searched only after the talent says yes.
+  async function suggestContext(args = {}, ctx = {}) {
+    const c = copy().consent;
+    const asked = await askConsent(ctx, { tool: 'suggest_register_context', key: 'suggest_register_context', question: c.cvSearch, 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 searched. Do not look for the CV on this computer; ask them to attach it in the chat.' };
     const read = deps.readRegisterContextSuggestions || require('./register-context').readRegisterContextSuggestions;
     const suggestions = read({ talentName: args.talentName });
     const found = suggestions.cvCandidates && suggestions.cvCandidates.length > 0;
@@ -321,16 +335,21 @@ function makeRegisterTools(deps = {}) {
       suggestions,
       note: 'Propose these to the talent to confirm; never write them without confirmation.',
       message: found
-        ? 'The talent already allowed the search: read_cv the first candidate now (the most likely), with talentConsent:true and talentName if you know it. nameMatch:null only means their name is unknown, never that the CV is not theirs. Move to the next candidate only if read_cv says mentionsTalent:false; say you did not find it only when none is left.'
+        ? 'Now call read_cv on the first candidate (the most likely), with talentName if you know it: read_cv asks the talent itself before reading it, so ask nothing in your own words. nameMatch:null only means their name is unknown, never that the CV is not theirs. Move to the next candidate only if read_cv says mentionsTalent:false; say you did not find it only when none is left.'
         : 'No CV was found on this machine: ask the talent to attach it.',
     };
   }
 
-  // Text of the CV the talent confirmed as theirs, read only with their permission.
-  async function readCv(args = {}) {
-    if (args.talentConsent !== true) return { ok: false, reason: 'consent-required', message: 'Ask the talent first whether this CV is theirs and whether you may read it; call again with talentConsent:true only after they say yes.' };
+  // Text of the CV file the talent allowed this tool to read, in its own question.
+  async function readCv(args = {}, ctx = {}) {
+    if (typeof args.path !== 'string' || !args.path.trim()) return { ok: false, reason: 'cv-not-found', message: 'Pass the path of the CV file.' };
+    const file = path.resolve(expandHome(args.path.trim()));
+    const c = copy().consent;
+    const asked = await askConsent(ctx, { tool: 'read_cv', key: `read_cv:${file}`, question: c.cvRead(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: the file was not read. Do not read it; ask them to attach their CV in the chat or tell you what it says.' };
     const read = deps.readCvText || require('./cv-text').readCvText;
-    const result = read(args.path, { talentName: args.talentName });
+    const result = read(file, { talentName: args.talentName });
     if (!result.ok) return { ...result, message: 'Could not read the CV text here. Ask the talent to attach the CV to the chat, or to tell you what it says.' };
     // Someone else's CV (a candidate they downloaded): never hand its contents over.
     if (result.mentionsTalent === false) return { ok: true, mentionsTalent: false, note: "This CV does not name the talent: it belongs to someone else. Do not use, quote or describe it; try the next candidate." };
@@ -340,27 +359,33 @@ function makeRegisterTools(deps = {}) {
   return [
     {
       name: 'suggest_register_context',
-      description: "SUGGESTIONS for the sign-up read on this machine (no network, no file contents): timezone, git name/email, the gh CLI GitHub login, and cvCandidates: PDF/DOC/DOCX files in Desktop, Documents, Downloads and iCloud Drive whose NAME looks like a CV or carries the talent's name, each with nameMatch (null when their name is unknown) and generic flags. A candidate is only a lead (people who hire keep other people's CVs): confirm it with read_cv. Pass talentName to sharpen the match. Use it when the talent said you may look for their CV on this machine.",
-      inputSchema: { type: 'object', properties: { talentName: { type: 'string', description: "The talent's full name as you know it (memory, chat); improves CV matching." } } },
+      title: 'Look for your CV on this computer',
+      description: 'Asks you first, then lists the names of PDF and Word files in your Desktop, Documents, Downloads and iCloud Drive folders that look like a CV and reads your time zone and the name, email and GitHub user saved by your coding tools. It does not open those files or send anything.',
+      guidance: "SUGGESTIONS for the sign-up read on this machine (no network, no file contents): timezone, git name/email, the gh CLI GitHub login, and cvCandidates: PDF/DOC/DOCX files in Desktop, Documents, Downloads and iCloud Drive whose NAME looks like a CV or carries the talent's name, each with nameMatch (null when their name is unknown) and generic flags. A candidate is only a lead (people who hire keep other people's CVs): confirm it with read_cv. Pass talentName to sharpen the match. The tool asks the talent first (a dialog when the client has one, otherwise it returns `say` to print word for word as your whole reply); nothing is searched until they answer yes. After a `say`, call it again with answer set to the option they pick. Never answer for them.",
+      inputSchema: { type: 'object', properties: { talentName: { type: 'string', description: "The talent's full name as you know it (memory, chat); improves CV matching." }, answer: { type: 'string', description: 'The option the talent picked when you printed the question this tool returned. Never set it yourself.' } } },
       handler: suggestContext,
     },
     {
       name: 'read_cv',
-      description: "Read the TEXT of a CV file (PDF, DOC, DOCX) on this machine, with the talent's permission (talentConsent:true) and talentName set. Returns { mentionsTalent, links: { linkedin, github, emails, phones }, text } for the talent's own CV; a CV that does not name them returns only mentionsTalent:false: it is someone else's, drop it, never describe it, try the next candidate. Nothing is uploaded by this tool: pass the confirmed path to signup_start (or import_profile) as cvPath, use the text for userQuery and the email, and links.linkedin as their LinkedIn URL.",
+      title: 'Read your CV',
+      description: 'Asks you first, then reads the text of the CV file you allow to prepare your profile draft. This step sends nothing to Shakers.',
+      guidance: "Read the TEXT of a CV file (PDF, DOC, DOCX) on this machine, with talentName set. The tool asks the talent first, 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 read until they answer yes. After a `say`, call it again with the same path and answer set to the option they pick. Never answer for them. Returns { mentionsTalent, links: { linkedin, github, emails, phones }, text } for the talent's own CV; a CV that does not name them returns only mentionsTalent:false: it is someone else's, drop it, never describe it, try the next candidate. Nothing is uploaded by this tool: pass the confirmed path to signup_start (or import_profile) as cvPath, use the text for userQuery and the email, and links.linkedin as their LinkedIn URL.",
       inputSchema: {
         type: 'object',
         properties: {
           path: { type: 'string', description: 'Path to the CV file, exactly as suggest_register_context gave it (the short ~/ form is fine) or absolute.' },
-          talentConsent: { type: 'boolean', description: 'true ONLY after the talent allowed you to search for and read their CV.' },
+          answer: { type: 'string', description: 'The option the talent picked when you printed the question this tool returned. Never set it yourself.' },
           talentName: { type: 'string', description: "The talent's full name as you know it; used to tell their CV from other people's." },
         },
-        required: ['path', 'talentConsent'],
+        required: ['path'],
       },
       handler: readCv,
     },
     {
       name: 'onboarding_interview_start',
-      description: "Start the onboarding interview, here in the chat. Offer it only when signup_status says onboardingInterview.completed is not true. Call it first without disclaimerAcknowledged: it asks 'here now or later on the web?' (in a dialog when the client has one, otherwise it returns `say` to print word for word; default here), then how they want to answer, with the two interview disclaimers in that same question. reason 'interview-later' means they chose the web: skip the interview. reason 'interview-on-web' (a sign-up language the chat interview does not speak) is the same: print relayVerbatim and skip it. If it returns reason 'interview-already-started' (begun elsewhere and not finished), call open_web so they continue on the web. It runs over LiveKit and the server agent conducts it; the client does not decide its branch. When it returns `say`, print it word for word as your whole reply (it holds the disclaimers and the question) and, once they answer, call with where:'here', disclaimerAcknowledged:true and answerMode. Returns { interviewId, answerMode, greeting, ended }: relay the greeting VERBATIM, then drive it with onboarding_interview_turn. ANSWER MODES. For drafted and full, first gather everything you know (memory, a search of past conversations if you have that tool, their CV, the ai_usage report, the sign-up data) and show ONE short sheet 'esto es lo que se de ti' (roles and projects with concrete facts, stack, languages, what they want next); let them correct it once; those corrections override your memory. Your answers are first person, one or two short sentences in their plain voice, built only from facts on the confirmed sheet: no embellishment, no adjectives, metrics or claims they did not give, no repeating a fact already said unless asked; for wishes, preferences or opinions give your best guess and say it is a guess. (1) drafted: show each question VERBATIM with your proposed answer and send it only after the talent approves or edits it; if the sheet does not cover a question, ask them briefly instead of guessing. Only if the talent explicitly asks you to answer everything yourself (for example 'hazla entera' or 'contéstalas tú todas'), answer the remaining questions without asking for each approval, as in full. (2) full (they chose it, or asked for it as above): answer every question yourself without per-answer approval, still showing each question and your answer, and when the interview ends tell them in one line that you answered those questions yourself. (3) own: you are a pure CONDUIT: show every question VERBATIM and pass back only their REAL, VERBATIM words. In every mode never reword, summarize or translate the questions. `interviewId` is internal: never show it. If it fails with next:'open_web', print relayVerbatim word for word and call open_web so they do the interview on the web.",
+      title: 'Start your onboarding interview',
+      description: 'Starts the short Shakers interview here in the chat, after asking you where and how you want to answer it. Your answers go to Shakers to get to know your profile.',
+      guidance: "Start the onboarding interview, here in the chat. Offer it only when signup_status says onboardingInterview.completed is not true. Call it first without disclaimerAcknowledged: it asks 'here now or later on the web?' (in a dialog when the client has one, otherwise it returns `say` to print word for word; default here), then how they want to answer, with the two interview disclaimers in that same question. reason 'interview-later' means they chose the web: skip the interview. reason 'interview-on-web' (a sign-up language the chat interview does not speak) is the same: print relayVerbatim and skip it. If it returns reason 'interview-already-started' (begun elsewhere and not finished), call open_web so they continue on the web. It runs over LiveKit and the server agent conducts it; the client does not decide its branch. When it returns `say`, print it word for word as your whole reply (it holds the disclaimers and the question) and, once they answer, call with where:'here', disclaimerAcknowledged:true and answerMode. Returns { interviewId, answerMode, greeting, ended }: relay the greeting VERBATIM, then drive it with onboarding_interview_turn. ANSWER MODES. For drafted and full, first gather everything you know (memory, a search of past conversations if you have that tool, their CV, the ai_usage report, the sign-up data) and show ONE short sheet 'esto es lo que se de ti' (roles and projects with concrete facts, stack, languages, what they want next); let them correct it once; those corrections override your memory. Your answers are first person, one or two short sentences in their plain voice, built only from facts on the confirmed sheet: no embellishment, no adjectives, metrics or claims they did not give, no repeating a fact already said unless asked; for wishes, preferences or opinions give your best guess and say it is a guess. (1) drafted: show each question VERBATIM with your proposed answer and send it only after the talent approves or edits it; if the sheet does not cover a question, ask them briefly instead of guessing. Only if the talent explicitly asks you to answer everything yourself (for example 'hazla entera' or 'contéstalas tú todas'), answer the remaining questions without asking for each approval, as in full. (2) full (they chose it, or asked for it as above): answer every question yourself without per-answer approval, still showing each question and your answer, and when the interview ends tell them in one line that you answered those questions yourself. (3) own: you are a pure CONDUIT: show every question VERBATIM and pass back only their REAL, VERBATIM words. In every mode never reword, summarize or translate the questions. `interviewId` is internal: never show it. If it fails with next:'open_web', print relayVerbatim word for word and call open_web so they do the interview on the web.",
       inputSchema: INTERVIEW_START_SCHEMA,
       handler: interviewStart,
       available: async () => {
@@ -373,25 +398,33 @@ function makeRegisterTools(deps = {}) {
     },
     {
       name: 'onboarding_interview_turn',
-      description: "Send the talent's answer to the current onboarding-interview question and get the next one. Follow the answerMode the talent chose at onboarding_interview_start. drafted: `message` is the answer the talent APPROVED or edited after seeing your proposal; never send one they have not confirmed, unless they explicitly asked you to answer the rest yourself ('hazla entera', 'contéstalas tú todas'): from then on, as in full, send your own answers without per-answer approval. full: send your own answer to each question, built only from what they confirmed, and when it ends tell them you answered those questions yourself. own: `message` is ONLY the talent's REAL, VERBATIM answer — never invent, infer or complete it. Outside full, if the talent has not answered or approved yet, do NOT call this, wait for them. Relay the returned `response` (the next question) to the talent VERBATIM — do not reword, summarize or translate it. Keep calling with their next `message` until `ended` is true, then call onboarding_interview_complete. Do NOT show or mention `interviewId` to the talent (internal handle). If it returns reason 'unknown-interview' (the server was restarted and the live room is gone), start again with onboarding_interview_start.",
+      title: 'Answer an interview question',
+      description: 'Sends the answer you gave or approved for the current interview question to Shakers and brings the next one.',
+      guidance: "Send the talent's answer to the current onboarding-interview question and get the next one. Follow the answerMode the talent chose at onboarding_interview_start. drafted: `message` is the answer the talent APPROVED or edited after seeing your proposal; never send one they have not confirmed, unless they explicitly asked you to answer the rest yourself ('hazla entera', 'contéstalas tú todas'): from then on, as in full, send your own answers without per-answer approval. full: send your own answer to each question, built only from what they confirmed, and when it ends tell them you answered those questions yourself. own: `message` is ONLY the talent's REAL, VERBATIM answer — never invent, infer or complete it. Outside full, if the talent has not answered or approved yet, do NOT call this, wait for them. Relay the returned `response` (the next question) to the talent VERBATIM — do not reword, summarize or translate it. Keep calling with their next `message` until `ended` is true, then call onboarding_interview_complete. Do NOT show or mention `interviewId` to the talent (internal handle). If it returns reason 'unknown-interview' (the server was restarted and the live room is gone), start again with onboarding_interview_start.",
       inputSchema: INTERVIEW_TURN_SCHEMA,
       handler: interviewTurn,
     },
     {
       name: 'onboarding_interview_complete',
-      description: "Close the onboarding interview once the turns report ended:true: the buffered transcript is saved and the live room is disconnected. `interviewId` is internal: never show it. Returns { state:'taken' }. If it returns reason 'unknown-interview' the room was already gone (server restart): nothing to complete. In the sign-up flow, go on to the main role (list_my_roles with waitSeconds, then set_main_role) and finish with open_web; do NOT call onboarding_finish there.",
+      title: 'Finish the interview',
+      description: 'Closes the interview and saves it on Shakers.',
+      guidance: "Close the onboarding interview once the turns report ended:true: the buffered transcript is saved and the live room is disconnected. `interviewId` is internal: never show it. Returns { state:'taken' }. If it returns reason 'unknown-interview' the room was already gone (server restart): nothing to complete. In the sign-up flow, go on to the main role (list_my_roles with waitSeconds, then set_main_role) and finish with open_web; do NOT call onboarding_finish there.",
       inputSchema: INTERVIEW_COMPLETE_SCHEMA,
       handler: interviewComplete,
     },
     {
       name: 'repeat_onboarding_interview',
-      description: "OVERWRITE-repeat the onboarding interview: resets the talent's completed onboarding interview IN PLACE; the previous evaluation is DISCARDED and CANNOT be recovered. Clearly warn the talent that this is irreversible and get their explicit go-ahead BEFORE calling this. On success run the interview again (onboarding_interview_start, onboarding_interview_turn until ended, onboarding_interview_complete), then onboarding_finish. Returns { interviewId, language } or reason 'onboarding-not-found' (no onboarding yet), 'http-401'/'http-403'.",
+      title: 'Repeat your onboarding interview',
+      description: 'Deletes your previous onboarding interview on Shakers so you can take it again. This cannot be undone.',
+      guidance: "OVERWRITE-repeat the onboarding interview: resets the talent's completed onboarding interview IN PLACE; the previous evaluation is DISCARDED and CANNOT be recovered. Clearly warn the talent that this is irreversible and get their explicit go-ahead BEFORE calling this. On success run the interview again (onboarding_interview_start, onboarding_interview_turn until ended, onboarding_interview_complete), then onboarding_finish. Returns { interviewId, language } or reason 'onboarding-not-found' (no onboarding yet), 'http-401'/'http-403'.",
       inputSchema: { type: 'object', properties: {} },
       handler: repeatOnboarding,
     },
     {
       name: 'onboarding_finish',
-      description: "Mark the onboarding as COMPLETED on Shakers. NOT part of the sign-up flow (signup_start): there, never call it. Use it only to close a repeat_onboarding_interview run. Idempotent. Returns { finalized, onboardingStatus, registrationLevel, completedProfilePercentage, profileUrl }.",
+      title: 'Complete your onboarding',
+      description: 'Marks your onboarding as completed on Shakers after you repeat the interview.',
+      guidance: "Mark the onboarding as COMPLETED on Shakers. NOT part of the sign-up flow (signup_start): there, never call it. Use it only to close a repeat_onboarding_interview run. Idempotent. Returns { finalized, onboardingStatus, registrationLevel, completedProfilePercentage, profileUrl }.",
       inputSchema: FINISH_SCHEMA,
       handler: onboardingFinish,
     },

package/src/mcp-report-tools.js

@@ -33,7 +33,7 @@ function makeReportTools(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;
   };
@@ -85,13 +85,17 @@ function makeReportTools(deps = {}) {
   return [
     {
       name: 'report',
-      description: "Two modes. stored:true returns the talent's ENTIRE stored server report (inventory + activity + AI-fluency level + prompting/interaction level) as plain text, read from certs WITHOUT re-running any scan — says so cleanly when none is stored (this stored view does NOT include the Setup×Usage matrix or the vision/how-I-work narratives). Otherwise builds the local report for this repo from local state: it returns the full human-readable report in `text` (Markdown mirroring the CLI terminal — Setup level and rank rationale, tools, MCP servers, agents, activity, plus the Setup×Usage matrix and vision/how-I-work when available) AND the HTML file path (no browser). Render `text` verbatim to the talent; keep the fenced blocks fenced so the tables stay aligned. Requires an active session. Any internal ids/codes are handles for tools only — never show or mention them to the talent.",
+      title: 'Show your AI report',
+      description: 'Shows your AI report, either the one saved on Shakers or one built from your last AI analysis on this computer, which it also saves there as a file.',
+      guidance: "Two modes. stored:true returns the talent's ENTIRE stored server report (inventory + activity + AI-fluency level + prompting/interaction level) as plain text, read from certs WITHOUT re-running any scan — says so cleanly when none is stored (this stored view does NOT include the Setup×Usage matrix or the vision/how-I-work narratives). Otherwise builds the local report for this repo from local state: it returns the full human-readable report in `text` (Markdown mirroring the CLI terminal — Setup level and rank rationale, tools, MCP servers, agents, activity, plus the Setup×Usage matrix and vision/how-I-work when available) AND the HTML file path (no browser). Render `text` verbatim to the talent; keep the fenced blocks fenced so the tables stay aligned. Requires an active session. Any internal ids/codes are handles for tools only — never show or mention them to the talent.",
       inputSchema: REPORT_SCHEMA,
       handler: report,
     },
     {
       name: 'share',
-      description: "Generate the Shakers-branded LinkedIn share card for this repo and return its file path. Does not open a browser. Requires an active session.",
+      title: 'Create your share card',
+      description: 'Creates on this computer a card with your AI report to share on LinkedIn. It sends nothing.',
+      guidance: "Generate the Shakers-branded LinkedIn share card for this repo and return its file path. Does not open a browser. Requires an active session.",
       inputSchema: SHARE_SCHEMA,
       handler: share,
     },

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;
   };
@@ -282,10 +283,18 @@ function makeRoleTools(deps = {}) {
     // This call's own list: another call may replace `offered` while the dialog is open.
     const options = shown.map((m) => m.role);
     offered = options;
-    const reasons = shown
-      .filter((m) => m.byRole.length || m.byStack.length)
-      .map((m) => [c.roleName(m.role.name), m.byRole.length ? c.catalogueReason.role(m.byRole.join(', ')) : null, m.byStack.length ? c.catalogueReason.stack(m.byStack.join(', ')) : null].filter(Boolean).join('\n'));
-    const asked = await askChoice(ctx, { texts: reasons.length ? [reasons.join('\n\n')] : [], question: c.mainRoleQuestion, options: [...options.map((r) => r.name), c.mainRoleNotListed] });
+    // Same block as the recommended roles: intro, the best match marked, its reason, its open projects, then what the main profile is.
+    const fits = shown.filter((m) => m.byRole.length || m.byStack.length);
+    const session = loadAuthSession();
+    const counts = fits.length ? await openCounts(session && session.hubAccessToken, fits.map((m) => m.role)) : [];
+    const blocks = fits.map((m, i) => [
+      i === 0 ? c.roleRecommended(m.role.name) : c.roleName(m.role.name),
+      m.byRole.length ? c.catalogueReason.role(m.byRole.join(', ')) : null,
+      m.byStack.length ? c.catalogueReason.stack(m.byStack.join(', ')) : null,
+      typeof counts[i] === 'number' && counts[i] > 0 ? c.openProjects(counts[i]) : null,
+    ].filter(Boolean).join('\n'));
+    const texts = [[...(blocks.length ? [c.rolesIntro, ...blocks] : []), c.rolesOutro].join('\n\n')];
+    const asked = await askChoice(ctx, { texts, question: c.mainRoleQuestion, options: [...options.map((r) => r.name), c.mainRoleNotListed] });
     if (asked.answer === c.mainRoleNotListed) return askOwnRole();
     const role = asked.answer && options.find((r) => r.name === asked.answer);
     if (role) {
@@ -293,7 +302,7 @@ function makeRoleTools(deps = {}) {
       return { role, add: true };
     }
     offered = options;
-    return { reply: roleChoice(asked.chat ? asked : { chat: chatChoice(c.mainRoleQuestion, [...options.map((r) => r.name), c.mainRoleNotListed]) }, options, `Pass catalogue:true too: it adds the role first. If they pick the last option, call set_main_role with catalogue:true and answer = that option.`) };
+    return { reply: roleChoice(asked.chat ? asked : { chat: chatChoice(c.mainRoleQuestion, [...options.map((r) => r.name), c.mainRoleNotListed], texts) }, options, `Pass catalogue:true too: it adds the role first. If they pick the last option, call set_main_role with catalogue:true and answer = that option.`) };
   }
 
   async function setMainRole(args = {}, ctx = {}) {
@@ -309,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') {
@@ -86,10 +86,14 @@ function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVe
     }
   }
 
-  // An `elicitation` capability without `form` but with `url` only opens links, so it cannot ask a closed question.
+  // The spec (2025-06-18) advertises elicitation support as a presence flag: `capabilities.elicitation: {}`.
+  // So any advertised elicitation can ask a closed question — except an explicit url-only object
+  // (`{ url }` without `{ form }`), which only opens links and falls back to the chat.
   function canElicitForm() {
     const e = clientCapabilities.elicitation;
-    return !!e && typeof e === 'object' && (e.form !== undefined || e.url === undefined);
+    if (!e) return false;
+    if (typeof e === 'object' && e.url !== undefined && e.form === undefined) return false;
+    return true;
   }
 
   // MCP elicitation/create: the client's { action, content }, or null when it has no dialog or the exchange failed.
@@ -103,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,
     };
   }
 
@@ -201,6 +208,12 @@ 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`);
           const text = typeof instructions === 'function' ? instructions({ elicitation: canElicitForm() }) : instructions;
           return resultResponse(id, {
             protocolVersion: requested || advertisedVersion,

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,
     },