shakers-cli-beta 0.13.0 → 0.14.0

package/src/mcp-instructions.js

@@ -11,7 +11,7 @@ function buildServerInstructions({ elicitation = false } = {}) {
       ? 'Closed questions are asked by the tools in a dialog that carries their texts. Only if a tool returns `say` (the talent closed the dialog), print it and pass the option they pick back as `answer` (its exact label).'
       : 'Closed questions come as `say`: the fixed texts, the question and its options as a list; print it, then pass the option they pick back as `answer` (its exact label).',
     'Sign-up flow:',
-    '1. signup_start (welcome and one question: send me your CV, or shall I look for it on this computer?); a CV path in their first message goes as cvPath and skips the question. Only if they pick the search, find and read their CV (suggest_register_context, read_cv) without asking again; otherwise wait for the CV in the chat.',
+    '1. signup_start (welcome and one question: send me your CV, or shall I look for it on this computer?); a CV path in their first message goes as cvPath and skips the question. Only if they pick the search, find and read their CV (suggest_register_context, then read_cv); otherwise wait for the CV in the chat. suggest_register_context, read_cv, import_profile with a CV file and add_project each ask the talent themselves, naming what they read or send, before doing anything: never ask that in your own words and never pass an answer the talent did not give.',
     '2. LinkedIn: take it from the CV. If it has none, signup_start with linkedinMissing:true returns the question to print; never ask it in your own words. Only if they say they do not know where to find it, say the linkedinOpening text and call open_linkedin_profile.',
     '3. signup_email with the best email you know (CV first), or none.',
     '4. signup_draft with your draft of their profile (name, role, city, years, stack, languages, work mode, hours, hourly and annual rate in euros, both always: the talent\'s figures with ratesFromTalent:true, else your estimate; sources: cv and/or linkedin, only those you have). It shows the draft, the data notice and how the account window works, and asks them to confirm; if they want changes, ask what and call it again.',

package/src/mcp-invitations-tools.js

@@ -14,7 +14,7 @@ function makeInvitationsTools(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_invitations is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (list_invitations is session-gated).');
     }
     return session;
   };
@@ -29,7 +29,9 @@ function makeInvitationsTools(deps = {}) {
   return [
     {
       name: 'list_invitations',
-      description: "List the talent's unread position invitations (projects that invited them). Requires an active session. Any projectId/chatId in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a project by its name.",
+      title: 'Your invitations',
+      description: 'Shows the projects that invited you and that you have not read yet.',
+      guidance: "List the talent's unread position invitations (projects that invited them). Requires an active session. Any projectId/chatId in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a project by its name.",
       inputSchema: LIST_INVITATIONS_SCHEMA,
       handler: listInvitations,
     },

package/src/mcp-lang-tools.js

@@ -14,7 +14,7 @@ function makeLangTools(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_languages is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (get_languages is session-gated).');
     }
     return session;
   };
@@ -29,7 +29,9 @@ function makeLangTools(deps = {}) {
   return [
     {
       name: 'get_languages',
-      description: "View the talent's languages and proficiency levels (NATIVE/ADVANCED/INTERMEDIATE/INTERMEDIATE_WRITTEN). Read-only. Requires an active session. Any language ids in the result are internal handles for tools only — never show or mention them to the talent; refer to a language by its name.",
+      title: 'Your languages',
+      description: 'Shows the languages and levels on your Shakers profile.',
+      guidance: "View the talent's languages and proficiency levels (NATIVE/ADVANCED/INTERMEDIATE/INTERMEDIATE_WRITTEN). Read-only. Requires an active session. Any language ids in the result are internal handles for tools only — never show or mention them to the talent; refer to a language by its name.",
       inputSchema: GET_LANGUAGES_SCHEMA,
       handler: getLanguages,
     },

package/src/mcp-onboarding-tools.js

@@ -1,13 +1,8 @@
 'use strict';
 
 const path = require('path');
-
-const LOGIN_SCHEMA = {
-  type: 'object',
-  properties: {
-    method: { type: 'string', enum: ['email', 'google', 'linkedin'], description: "Optional auth method. None of them sign in here: this tool points you to social_signin_start/social_signin_poll (the device flow) with that provider. 'email' reuses the talent's open Shakers web session or signs them in on the page (never a password in the chat); 'google'/'linkedin' open that social sign-in. Omit it to default to email (the page still offers Google and LinkedIn)." },
-  },
-};
+const { askConsent } = require('./mcp-choice');
+const { tildify } = require('./env-paths');
 
 const LOGOUT_SCHEMA = { type: 'object', properties: {} };
 
@@ -58,6 +53,7 @@ const ADD_PROJECT_SCHEMA = {
     clientName: { type: 'string', description: 'Client name (optional, e.g. for freelance work).' },
     clientDomain: { type: 'string', description: "Client website or domain (optional, e.g. 'acme.com' or a full URL — normalized to a bare domain). Hub generates the client logo from it." },
     skillIds: { type: 'array', items: { type: 'integer' } },
+    answer: { type: 'string', description: 'The option the talent picked when you printed the question this tool returned. Never set it yourself.' },
   },
 };
 
@@ -89,6 +85,7 @@ function makeOnboardingTools(deps = {}) {
     requestUpdatePortfolioSkills = require('./portfolio-client').requestUpdatePortfolioSkills,
     getRemoteUrl = require('./portfolio-git-info').getRemoteUrl,
     getCommitDateRange = require('./portfolio-git-info').getCommitDateRange,
+    consentCopy = () => require('./signup-copy').signupCopy(require('./signup-language').signupLanguage(require('./i18n').detectFlowLang())).consent,
     normalizeDomain = require('./start-add-portfolio').normalizeDomain,
     isValidEmail = require('./share').isValidEmail,
     normalizeEmail = require('./share').normalizeEmail,
@@ -97,7 +94,7 @@ function makeOnboardingTools(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;
   };
@@ -117,25 +114,6 @@ function makeOnboardingTools(deps = {}) {
     return endpoint;
   };
 
-  // Every method runs through the device flow (start/poll tools); a blocking form
-  // can't surface the code, and email now reuses the web session there instead of
-  // prompting for a password. The start/poll pair persists the session.
-  const socialSigninPointer = (mode, provider = 'email') => ({
-    ok: false,
-    reason: 'use-device-flow',
-    next: 'social_signin_start',
-    mode,
-    provider,
-    message: `For ${provider}, call social_signin_start (provider "${provider}", mode "${mode}") to get a URL and code to show the talent, then social_signin_poll.`,
-  });
-
-  // Email, Google and LinkedIn all hand off to social_signin_start/poll. Email
-  // defaults when no method is given; the /cli-login page still offers the others.
-  async function login(args = {}) {
-    const provider = args.method === 'google' || args.method === 'linkedin' ? args.method : 'email';
-    return socialSigninPointer('login', provider);
-  }
-
   async function logout() {
     const wasLoggedIn = loadAuthSession() !== null;
     try { clearAuthSession(); } catch { /* idempotent — nothing to clear */ }
@@ -299,10 +277,11 @@ function makeOnboardingTools(deps = {}) {
     return { ...base, portfolios, related, relateFailures };
   }
 
-  async function addProject(args = {}) {
+  // Sends the project only after the talent says yes to exactly what goes: name, web address, dates, client.
+  async function addProject(args = {}, ctx = {}) {
     const session = requireSession();
     const endpoint = requireEndpoint(getPortfoliosDeclareEndpoint, 'portfolios-declare');
-    const root = typeof args.root === 'string' && args.root ? args.root : process.cwd();
+    const root = path.resolve(typeof args.root === 'string' && args.root ? args.root : process.cwd());
     const name = typeof args.name === 'string' && args.name ? args.name : path.basename(root);
     const type = args.type === 'EXPERIENCE' ? 'EXPERIENCE' : 'PORTFOLIO';
     let url = typeof args.url === 'string' && args.url ? args.url : null;
@@ -312,14 +291,29 @@ function makeOnboardingTools(deps = {}) {
     let startDate;
     let endDate;
     try { ({ startDate, endDate } = getCommitDateRange(root)); } catch { startDate = null; endDate = null; }
+    const clientName = typeof args.clientName === 'string' && args.clientName ? args.clientName : null;
+    const clientDomain = normalizeDomain(args.clientDomain) || null;
+    const description = typeof args.description === 'string' && args.description ? args.description : null;
+    const sent = { name, type, url, startDate, endDate, clientName, clientDomain, description };
+    const c = consentCopy();
+    const asked = await askConsent(ctx, {
+      tool: 'add_project',
+      key: `add_project:${root}:${JSON.stringify(sent)}`,
+      question: c.project({ folder: tildify(root), name, url, startDate, endDate, client: [clientName, clientDomain].filter(Boolean).join(', '), description }),
+      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 add the project.' };
     const result = await requestDeclarePortfolio(
       {
         name,
         type,
-        description: typeof args.description === 'string' ? args.description : undefined,
+        description: description || undefined,
         url: url || undefined,
-        clientName: typeof args.clientName === 'string' && args.clientName ? args.clientName : undefined,
-        clientDomain: normalizeDomain(args.clientDomain) || undefined,
+        clientName: clientName || undefined,
+        clientDomain: clientDomain || undefined,
         startDate: startDate || undefined,
         endDate: endDate || undefined,
         skillIds: Array.isArray(args.skillIds) ? args.skillIds : undefined,
@@ -332,39 +326,43 @@ function makeOnboardingTools(deps = {}) {
   }
 
   return [
-    {
-      name: 'login',
-      description: "Start signing the talent in to Shakers so the add_* and certify tools can run. This tool does not sign in itself: it points you to social_signin_start + social_signin_poll (the device flow), which open the Shakers web page and persist the session. Email (the default) reuses the talent's open web session or signs them in on the page — never a password in the chat; 'google'/'linkedin' open that social sign-in. Returns a { ok: false, reason: 'use-device-flow', next, provider } pointer; call social_signin_start next.",
-      inputSchema: LOGIN_SCHEMA,
-      handler: login,
-    },
     {
       name: 'logout',
-      description: "Sign the talent out of Shakers by clearing the persisted session. Idempotent — returns { ok: true, wasLoggedIn } whether or not a session existed.",
+      title: 'Sign out of Shakers',
+      description: 'Signs you out by deleting the Shakers sign-in saved on this computer.',
+      guidance: "Sign the talent out of Shakers by clearing the persisted session. Idempotent — returns { ok: true, wasLoggedIn } whether or not a session existed.",
       inputSchema: LOGOUT_SCHEMA,
       handler: logout,
     },
     {
       name: 'list_addable',
-      description: "List the skills and AI agents that Shakers discovered from the talent's submitted ai_usage report and that can be added to their Shakers profile. Use it to offer choices before add_skill / add_agent. Present skills and agents to the talent by NAME only; skillId, agent code and catalogId are internal handles for the add_* tools — never show raw IDs or codes. Requires an active session.",
+      title: 'Skills and agents you can add',
+      description: 'Shows the skills and AI agents found in the AI analysis you sent to Shakers, so you can pick which ones go on your profile.',
+      guidance: "List the skills and AI agents that Shakers discovered from the talent's submitted ai_usage report and that can be added to their Shakers profile. Use it to offer choices before add_skill / add_agent. Present skills and agents to the talent by NAME only; skillId, agent code and catalogId are internal handles for the add_* tools — never show raw IDs or codes. Requires an active session.",
       inputSchema: LIST_ADDABLE_SCHEMA,
       handler: listAddable,
     },
     {
       name: 'add_skill',
-      description: "Add a discovered skill to the talent's Shakers profile by skillId (taken from list_addable). skillId is an internal handle — refer to the skill by its name when talking to the talent, never show the id. Optionally pass relatedPortfolioIds to relate it to one or more of the talent's portfolio experiences (matches the web's 'Relate to an experience' step) — the response always includes `portfolios` (id/name/type) so you can ask the talent which one(s) on a later call. If the talent has no portfolios yet, the skill is still added, unrelated. Requires an active session.",
+      title: 'Add a skill to your profile',
+      description: 'Adds the skill you pick to your Shakers profile.',
+      guidance: "Add a discovered skill to the talent's Shakers profile by skillId (taken from list_addable). skillId is an internal handle — refer to the skill by its name when talking to the talent, never show the id. Optionally pass relatedPortfolioIds to relate it to one or more of the talent's portfolio experiences (matches the web's 'Relate to an experience' step) — the response always includes `portfolios` (id/name/type) so you can ask the talent which one(s) on a later call. If the talent has no portfolios yet, the skill is still added, unrelated. Requires an active session.",
       inputSchema: ADD_SKILL_SCHEMA,
       handler: addSkill,
     },
     {
       name: 'add_agent',
-      description: "Add a discovered AI agent to the talent's Shakers profile by name (from list_addable). Optionally pass whatItDoes and humanDecides (what the talent does around the agent — supervision/validation). Optionally pass relatedPortfolios ({ portfolioId }) to relate it to the talent's experiences (matches the web's 'Relate to an experience' step) — the response always includes `portfolios` (id/name/type) so you can ask which one(s) on a later call. If the talent has no experiences yet, the agent is still added, unrelated. Requires an active session.",
+      title: 'Add an AI agent to your profile',
+      description: 'Adds the AI agent you pick, with the description you agree on, to your Shakers profile.',
+      guidance: "Add a discovered AI agent to the talent's Shakers profile by name (from list_addable). Optionally pass whatItDoes and humanDecides (what the talent does around the agent — supervision/validation). Optionally pass relatedPortfolios ({ portfolioId }) to relate it to the talent's experiences (matches the web's 'Relate to an experience' step) — the response always includes `portfolios` (id/name/type) so you can ask which one(s) on a later call. If the talent has no experiences yet, the agent is still added, unrelated. Requires an active session.",
       inputSchema: ADD_AGENT_SCHEMA,
       handler: addAgent,
     },
     {
       name: 'add_project',
-      description: "Add the current repository to the talent's Shakers portfolio as a project. Name and URL default to the repo directory and its git remote, and the start/end dates are derived from the repo's git history. Optionally pass clientName and clientDomain (the client's website/domain, e.g. 'acme.com' — Shakers fetches the client logo from it). Requires an active session. Any ids/codes in the result are internal handles for tools only — never show or mention them to the talent.",
+      title: 'Add this project to your portfolio',
+      description: 'Reads the name of the project folder open here, the web address of its code and the dates of its first and last change. It asks you first, naming all of them, and only then sends them to Shakers as a new portfolio project.',
+      guidance: "Add the current repository to the talent's Shakers portfolio as a project. Name and URL default to the repo directory and its git remote, and the start/end dates are derived from the repo's git history. Optionally pass clientName and clientDomain (the client's website/domain, e.g. 'acme.com' — Shakers fetches the client logo from it). The tool asks the talent first, naming the folder, web address, dates and client it will send (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. Requires an active session. Any ids/codes in the result are internal handles for tools only — never show or mention them to the talent.",
       inputSchema: ADD_PROJECT_SCHEMA,
       handler: addProject,
     },
@@ -373,7 +371,6 @@ function makeOnboardingTools(deps = {}) {
 
 module.exports = {
   makeOnboardingTools,
-  LOGIN_SCHEMA,
   LOGOUT_SCHEMA,
   LIST_ADDABLE_SCHEMA,
   ADD_SKILL_SCHEMA,

package/src/mcp-portfolios-tools.js

@@ -15,7 +15,7 @@ function makePortfolioTools(deps = {}) {
   const requireLoginSession = (tool) => {
     const session = loadAuthSession();
     if (sessionStatus(session) !== 'active') {
-      throw new Error(`no active Shakers session — call the login tool (or run \`shakers login\`) first (${tool} is session-gated).`);
+      throw new Error(`no active Shakers session — sign in with social_signin_start (or run \`shakers login\`) first (${tool} is session-gated).`);
     }
     return session;
   };
@@ -30,13 +30,17 @@ function makePortfolioTools(deps = {}) {
   return [
     {
       name: 'list_experiences',
-      description: "List the talent's work experiences (company, role/title, dates, location, skills). Read-only. Requires an active session. Any ids in the result are internal handles for tools only — never show or mention them to the talent.",
+      title: 'Your work experience',
+      description: 'Shows the work experience on your Shakers profile.',
+      guidance: "List the talent's work experiences (company, role/title, dates, location, skills). Read-only. Requires an active session. Any ids in the result are internal handles for tools only — never show or mention them to the talent.",
       inputSchema: SCHEMA,
       handler: lister('experiences', 'list_experiences'),
     },
     {
       name: 'list_portfolios',
-      description: "List the talent's portfolio showcase pieces (name, dates, location, skills, link). Read-only. Requires an active session. Any ids in the result are internal handles for tools only — never show or mention them to the talent.",
+      title: 'Your portfolio',
+      description: 'Shows the portfolio projects on your Shakers profile.',
+      guidance: "List the talent's portfolio showcase pieces (name, dates, location, skills, link). Read-only. Requires an active session. Any ids in the result are internal handles for tools only — never show or mention them to the talent.",
       inputSchema: SCHEMA,
       handler: lister('portfolios', 'list_portfolios'),
     },

package/src/mcp-profile-tools.js

@@ -17,7 +17,7 @@ function makeProfileTools(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_profile is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (get_profile is session-gated).');
     }
     return session;
   };
@@ -33,7 +33,9 @@ function makeProfileTools(deps = {}) {
   return [
     {
       name: 'get_profile',
-      description: "Get the talent's summary: main role, per-project rate, and the 'My work with AI' read model (setup/usage tier+level, 3x3 cell, vision, how-I-work). Requires an active session. Present it in human terms; any internal ids/codes in the result are handles for tools only — never show or mention them to the talent.",
+      title: 'Your Shakers profile',
+      description: 'Shows your main role, your rate and your "My work with AI" summary on Shakers.',
+      guidance: "Get the talent's summary: main role, per-project rate, and the 'My work with AI' read model (setup/usage tier+level, 3x3 cell, vision, how-I-work). Requires an active session. Present it in human terms; any internal ids/codes in the result are handles for tools only — never show or mention them to the talent.",
       inputSchema: GET_PROFILE_SCHEMA,
       handler: getProfile,
     },

package/src/mcp-prompts.js

@@ -46,10 +46,10 @@ const PROMPTS = [
   {
     name: 'ask',
     description: 'Ask Alma, the Shakers AI assistant, a question.',
-    tools: ['ask'],
+    tools: ['alma_chat'],
     arguments: [{ name: 'message', description: 'What to ask Alma.', required: false }],
     buildMessages: (args = {}) => userText(
-      `Ask Alma (the Shakers assistant) and relay her answer as-is. My question: ${typeof args.message === 'string' && args.message ? args.message : '(ask me what I want to know first)'}`,
+      `Ask Alma (the Shakers assistant) with \`alma_chat\` and relay her answer as-is. My question: ${typeof args.message === 'string' && args.message ? args.message : '(ask me what I want to know first)'}`,
     ),
   },
   {

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.' };
   }
 
@@ -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,
     },