shakers-cli-beta 0.13.0 → 0.14.0

package/README.md

@@ -379,7 +379,7 @@ scanned project** — the report can't slip into a commit by accident.
 Desktop) can drive the same features as tools. It exposes, among others:
 
 - **AI usage**: `ai_usage`, `ai_usage_result`.
-- **Auth**: `login`, `logout`, `social_signin_start`, `social_signin_poll`.
+- **Auth**: `social_signin_start`, `social_signin_poll`, `logout`.
 - **Sign-up** (from the talent's own AI, ticket 39540; copy from UX review
   39574): every talent-facing text is fixed, comes from the tools in the
   talent's language (es/en/it/pt, fixed by their first message) and the AI shows
@@ -413,17 +413,36 @@ Desktop) can drive the same features as tools. It exposes, among others:
   pick directly; otherwise it returns `question` and `options` and the AI offers
   them as buttons or a numbered list. The legal texts are always shown in the
   chat before any consent dialog.
+- **Asked before touching this computer**: `suggest_register_context` (look for
+  the CV), `read_cv` (read one CV file), `import_profile` with a CV file (send it)
+  and `add_project` (send the project folder's name, web address, dates and
+  client) each ask the talent themselves, naming exactly what they read or send,
+  the same way as the closed questions above. Without a dialog, the answer only
+  counts when it comes back for a question that tool asked for those exact
+  arguments; a yes the AI sets on its own is ignored and the question is asked
+  again. Nothing is read or sent before the yes.
 - **Profile / skills / agents**: `list_addable`, `add_skill`, `add_agent`,
   `add_project`, `get_profile`, `get_rate`, `get_languages`, `list_socials`,
   `list_experiences`, `list_portfolios`, `get_availability`.
 - **Marketplace**: `find_projects`, `show_project`, `save_project`,
   `unsave_project`, `list_invitations`, `list_applications`.
 - **Certifications**: `list_certifications`, `list_certifiable_dimensions`.
-- **Alma**: `ask`.
+- **Alma**: `alma_chat`, `alma_decision` (a change Alma proposes is applied only
+  after the talent says yes).
+
+Each tool has two audiences. Its `title` and `description` are what the talent
+reads in the client: plain words saying what it does, what it reads on the
+machine and what it sends to Shakers. `packaging/mcpb/manifest.json` declares the
+same tools with the same descriptions, and a test keeps them equal. How the AI
+must use a tool (order, verbatim texts, internal ids) travels in the
+description of its input schema.
 
 MCP tool names are **stable** (renaming would break existing client configs); the
 role tools above were added, not renamed. `register`, `register_preview` and
-`register_status` were removed with the sign-up redesign, not renamed.
+`register_status` were removed with the sign-up redesign, not renamed. `login`
+(it only pointed to `social_signin_start`) and `ask` (a copy of `alma_chat` that
+dropped Alma's confirmation requests) were removed to show the talent fewer
+tools; the `/ask` prompt now uses `alma_chat`.
 
 ## Try it
 
@@ -885,6 +904,12 @@ history directory is absent or unreadable.
   whether it's silently dropped or degraded on failure, is unaffected by
   consent either way. The local **usage** read (Claude Code history) is not
   even a network call — it never leaves the machine, consent or not.
+- **Registration funnel analytics.** `shakers register` and the MCP sign-up
+  send one event per registration step to the Hub, which relays them to
+  Amplitude. Only steps and categories travel (never an exact rate or free
+  text), with a random device id kept in
+  `~/.config/shakers/analytics-device.json` (permissions `600`). A failed
+  send never affects the registration.
 - The consent decision lives in `~/.config/shakers/consent.json`
   (permissions `600`).
 - An **unfinished interview** (agent certification, or the skill-code

package/bin/mcp.js

@@ -14,7 +14,6 @@ const { makeAvailabilityTools } = require('../src/mcp-availability-tools');
 const { makeCertificationsTools } = require('../src/mcp-certifications-tools');
 const { makeProfileTools } = require('../src/mcp-profile-tools');
 const { makeRateTools } = require('../src/mcp-rate-tools');
-const { makeAskTools } = require('../src/mcp-ask-tools');
 const { makeAlmaTools } = require('../src/mcp-alma-tools');
 const { makeLangTools } = require('../src/mcp-lang-tools');
 const { makeSocialsTools } = require('../src/mcp-socials-tools');
@@ -29,6 +28,7 @@ const { makeReportTools } = require('../src/mcp-report-tools');
 const { makePrompts } = require('../src/mcp-prompts');
 const { buildServerInstructions } = require('../src/mcp-instructions');
 const { ensureFreshSession } = require('../src/session-refresh');
+const { createFunnel } = require('../src/onboarding-funnel');
 
 let VERSION = '';
 try {
@@ -43,7 +43,7 @@ const HELP = `\n  shakers mcp — local MCP server (stdio)\n\n`
   + `  Usage: shakers mcp\n\n`
   + `  This command speaks JSON-RPC on stdio; it is meant to be launched by an\n`
   + `  MCP client, not run by hand.\n`
-  + `  Tools: ai_usage, ai_usage_result, login, logout, social_signin_start, social_signin_poll,\n`
+  + `  Tools: ai_usage, ai_usage_result, logout, social_signin_start, social_signin_poll,\n`
   + `         list_addable, add_skill, add_agent,\n`
   + `         add_project, signup_start, signup_email, signup_draft, signup_create_account,\n`
   + `         signup_status, update_existing_profile, import_profile, save_profile_details, open_web,\n`
@@ -57,7 +57,7 @@ const HELP = `\n  shakers mcp — local MCP server (stdio)\n\n`
   + `         save_project, unsave_project, list_invitations,\n`
   + `         list_applications, get_availability,\n`
   + `         list_certifications, get_profile, get_rate, get_languages,\n`
-  + `         list_socials, list_experiences, list_portfolios, ask.\n\n`;
+  + `         list_socials, list_experiences, list_portfolios, alma_chat, alma_decision.\n\n`;
 
 // The LOCAL (filesystem/machine) tools — the only ones the .mcpb bundle exposes; the
 // server-backed tools belong to the remote connector.
@@ -65,9 +65,9 @@ const LOCAL_ONLY_TOOL_NAMES = new Set(['ai_usage', 'ai_usage_result', 'read_cv',
 
 // `localOnly` builds the scan-only server for the Claude .mcpb bundle, reusing the SAME
 // tool registry (just filtered) — no duplicate registration.
-function buildServer({ localOnly = false } = {}) {
+function buildServer({ localOnly = false, funnel = createFunnel({ surface: 'mcp' }) } = {}) {
   const lang = detectFlowLang();
-  const allTools = [makeAiUsageTool(), makeAiUsageResultTool(), ...makeOnboardingTools(), ...makeRoleTools({ lang }), ...makeDeviceLoginTools(), ...makeSignupTools({ lang }), ...makeRegisterTools({ lang }), ...makeReportTools(), ...makeCertifyDimensionTools(), ...makeFindProjectsTools(), ...makeShowProjectTools(), ...makeSavedPositionsTools(), ...makeInvitationsTools(), ...makeApplicationsTools(), ...makeAvailabilityTools(), ...makeCertificationsTools(), ...makeProfileTools(), ...makeRateTools(), ...makeLangTools(), ...makeSocialsTools(), ...makePortfolioTools(), ...makeAskTools(), ...makeAlmaTools()];
+  const allTools = [makeAiUsageTool(), makeAiUsageResultTool(), ...makeOnboardingTools(), ...makeRoleTools({ lang, funnel }), ...makeDeviceLoginTools(), ...makeSignupTools({ lang, funnel }), ...makeRegisterTools({ lang, funnel }), ...makeReportTools(), ...makeCertifyDimensionTools(), ...makeFindProjectsTools(), ...makeShowProjectTools(), ...makeSavedPositionsTools(), ...makeInvitationsTools(), ...makeApplicationsTools(), ...makeAvailabilityTools(), ...makeCertificationsTools(), ...makeProfileTools(), ...makeRateTools(), ...makeLangTools(), ...makeSocialsTools(), ...makePortfolioTools(), ...makeAlmaTools()];
   const tools = localOnly ? allTools.filter((t) => LOCAL_ONLY_TOOL_NAMES.has(t.name)) : allTools;
   // Slash-command prompts, kept to the tools actually registered in this mode.
   const prompts = makePrompts(new Set(tools.map((t) => t.name)), lang);
@@ -79,9 +79,15 @@ function buildServer({ localOnly = false } = {}) {
     // Long-lived server: refresh the email session's hub JWT from the stored
     // cookie before each tool call so a stale (~15-min) JWT never reaches a tool.
     beforeCall: () => ensureFreshSession(process.env),
+    onInitialize: ({ clientInfo }) => funnel.setMcpClient(clientInfo.name),
   });
 }
 
+function prepareProcess(env = process.env) {
+  require('../src/config').sanitizeStaleBakedEndpoints(env);
+  require('../src/backend-request').setClientIdentity('mcp');
+}
+
 async function run(argv = process.argv.slice(2)) {
   // The installer's last step; not a command the Talent needs to know.
   if (argv[0] === 'install') {
@@ -93,7 +99,7 @@ async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  require('../src/config').sanitizeStaleBakedEndpoints(process.env);
+  prepareProcess();
 
   // `--local` = the scan-only server shipped in the Claude .mcpb bundle.
   const server = buildServer({ localOnly: argv.includes('--local') });
@@ -111,7 +117,7 @@ async function run(argv = process.argv.slice(2)) {
   });
 }
 
-module.exports = { run, buildServer, buildServerInstructions };
+module.exports = { run, buildServer, buildServerInstructions, prepareProcess };
 
 if (require.main === module) {
   run();

package/bin/register.js

@@ -20,6 +20,7 @@ const { typeOut } = require('../src/typewriter');
 const { withSpinner } = require('../src/terminal-progress');
 const { openPath } = require('../src/open-file');
 const { c: fmt } = require('../src/terminal-format');
+const { createFunnel } = require('../src/onboarding-funnel');
 const red = (s) => `${fmt.danger}${s}${fmt.reset}`;
 
 const VALID_LANGS = new Set(['es', 'en']);
@@ -285,7 +286,7 @@ function makeIo({ ask, lang, out, acceptDisclaimer, stdinIsTTY = false }) {
 
 async function run(
   argv = process.argv.slice(2),
-  { ask: injectedAsk = null, stdinIsTTY: ttyOverride = undefined, deps = null, out = null, openBrowser = undefined, input = undefined, output = undefined } = {},
+  { ask: injectedAsk = null, stdinIsTTY: ttyOverride = undefined, deps = null, out = null, openBrowser = undefined, input = undefined, output = undefined, funnel = undefined } = {},
 ) {
   const o = parseArgs(argv);
   const lang = o.lang || detectFlowLang();
@@ -316,7 +317,9 @@ async function run(
     const io = makeIo({ ask, lang, out: write, acceptDisclaimer: o.acceptDisclaimer, stdinIsTTY });
     // At a terminal the profile opens in the browser at the end; piped runs, tests and --no-open only print it.
     const openProfile = stdinIsTTY && !o.noOpen ? (openBrowser || openPath) : undefined;
-    const result = await runOnboarding(io, deps || makeDeps(), { method, openBrowser, onAuthUrl: io.onGoogleAuthUrl, openProfile });
+    // Injected deps (tests) bring their own funnel or none.
+    const registrationFunnel = funnel || (deps ? undefined : createFunnel({ surface: 'cli' }));
+    const result = await runOnboarding(io, deps || makeDeps(), { method, openBrowser, onAuthUrl: io.onGoogleAuthUrl, openProfile, funnel: registrationFunnel });
     if (!result.ok) {
       process.stderr.write(`\n  ${red(`register: ${result.reason}${result.step ? ` (${result.step})` : ''}`)}\n\n`);
       process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakers-cli-beta",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Shakers AI usage & skills evaluator: a local-first CLI (`shakers` binary) plus a local MCP server. Commands: ai-usage (scan + classify your AI-tool setup, T0-T7), certify (certify Skills from your code), share (branded LinkedIn card).",
   "type": "commonjs",
   "bin": {

package/src/backend-request.js

@@ -8,6 +8,14 @@ const crypto = require('crypto');
 
 const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 
+const CLIENT_IDENTITIES = ['cli', 'mcp'];
+let clientIdentity = 'cli';
+
+function setClientIdentity(identity) {
+  if (!CLIENT_IDENTITIES.includes(identity)) throw new Error(`unknown client identity: ${identity}`);
+  clientIdentity = identity;
+}
+
 // Extra request headers, sanitized (talents-ai-score, issue 038 — the agent certification interview needs `Authorization: Bearer <sessionToken>`).
 const UNSAFE_HEADER_VALUE_RE = /[\r\n\0]/;
 
@@ -39,13 +47,8 @@ function postJsonWithTimeout(url, body, timeoutMs, method = 'POST', idempotencyK
         method,
         headers: {
           Accept: 'application/json',
-          // Lets the backend (and Datadog) tell CLI/MCP traffic apart from the
-          // browser without touching auth — same value regardless of which
-          // bin/ entrypoint is running, since none of them plumb through here
-          // separately today. Set unconditionally so no caller can drop it via
-          // extraHeaders (sanitizeExtraHeaders runs after this, so it can only
-          // add headers, not remove this one).
-          'X-Shakers-Client': 'cli',
+          // Tells CLI and MCP traffic apart from the browser.
+          'X-Shakers-Client': clientIdentity,
           // Only declared when there IS a body — see the bodyless note above.
           ...(data ? { 'Content-Type': 'application/json', 'Content-Length': data.length } : {}),
           ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
@@ -125,7 +128,7 @@ function postMultipartWithTimeout(url, fields, timeoutMs, method = 'POST', extra
         headers: {
           Accept: 'application/json',
           // See postJsonWithTimeout's identical header for why.
-          'X-Shakers-Client': 'cli',
+          'X-Shakers-Client': clientIdentity,
           'Content-Type': `multipart/form-data; boundary=${boundary}`,
           'Content-Length': data.length,
           ...sanitizeExtraHeaders(extraHeaders),
@@ -184,4 +187,5 @@ module.exports = {
   postMultipartWithTimeout,
   extractSetCookie,
   requestBackend,
+  setClientIdentity,
 };

package/src/config.js

@@ -124,10 +124,17 @@ function resolveIngestEndpoint(env = process.env) {
 // Only the DEFAULT bases; per-endpoint SHAKERS_CLI_* env and config.json overrides
 // still win at each getter (env > config.json > baked profile).
 const ENV_PROFILES = {
+  prod: {
+    certsBase: 'https://api.certifications.shakersworks.com/api/v1',
+    hubBase: 'https://api.hub.shakersworks.com/api/v1',
+    profileUrl: 'https://app.shakersworks.com/login',
+    almaBase: 'https://app.shakersworks.com',
+  },
   staging: {
     certsBase: 'https://api.staging.certifications.shakersworks.com/api/v1',
     hubBase: 'https://api.hub.staging.shakersworks.com/api/v1',
     profileUrl: 'https://works.staging.shakersworks.com/login',
+    almaBase: 'https://works.staging.shakersworks.com',
   },
   dev: {
     certsBase: 'https://api.dev.certifications.shakersworks.com/api/v1',
@@ -142,8 +149,8 @@ const ENV_PROFILES = {
 };
 
 // Which flavor is baked: SHAKERS_CLI_ENV override wins, else derived from the
-// published package name (beta -> staging, private -> dev), else dev (safe default).
-const PACKAGE_NAME_ENV = { 'shakers-cli-beta': 'staging', '@shakers/shakers-cli': 'dev' };
+// published package name (public -> prod, beta -> staging, private -> dev), else dev (safe default).
+const PACKAGE_NAME_ENV = { 'shakers-cli': 'prod', 'shakers-cli-beta': 'staging', '@shakers/shakers-cli': 'dev' };
 const DEFAULT_ENV_PROFILE = 'dev';
 
 function bakedEnvProfileName() {
@@ -395,13 +402,13 @@ function getTalentMeProfileEndpoint(env = process.env) {
 }
 
 // Alma (the AI assistant) is a SEPARATE service — NOT derived from hubBase.
-// Default to the local/dev container; override with SHAKERS_CLI_ALMA_BASE.
+// SHAKERS_CLI_ALMA_BASE > the baked profile's almaBase > the local/dev container.
 const DEFAULT_ALMA_BASE = 'http://127.0.0.1:5030';
 
 function getAlmaBase(env = process.env) {
   const explicit = readEnv(env, 'ALMA_BASE');
   if (explicit && explicit.trim()) return explicit.trim().replace(/\/+$/, '');
-  return DEFAULT_ALMA_BASE;
+  return getEnvProfile(env).almaBase || DEFAULT_ALMA_BASE;
 }
 
 function getAlmaChatEndpoint(env = process.env) {
@@ -553,6 +560,10 @@ function getMyImportStatusEndpoint(env = process.env) {
   return deriveFromHub(env, 'works/talent/me/import-profile/status');
 }
 
+function getOnboardingEventsEndpoint(env = process.env) {
+  return deriveFromHub(env, 'works/talent/me/onboarding-events');
+}
+
 function getOneTimeTokenEndpoint(env = process.env) {
   return deriveFromHub(env, 'auth/one-time-token/generate');
 }
@@ -786,7 +797,7 @@ module.exports = {
   getMeAvailabilityEndpoint,
   getMeProfileEndpoint,
   getTalentMeProfileEndpoint,
-  // Alma assistant (`ask` command / `ask` MCP tool) — separate service.
+  // Alma assistant (`ask` command / `alma_chat` MCP tool) — separate service.
   getAlmaBase,
   getAlmaChatEndpoint,
   getAlmaDecisionEndpoint,
@@ -816,6 +827,7 @@ module.exports = {
   getImportProfileEndpoint,
   getMcpSignupEndpoint,
   getMyImportStatusEndpoint,
+  getOnboardingEventsEndpoint,
   getOneTimeTokenEndpoint,
   getOneTimeLoginUrl,
   getProfessionalDetailsEndpoint,

package/src/consent-flow.js

@@ -15,9 +15,10 @@ const MAX_ATTEMPTS = 5;
 const YES_RE = /^(y|yes|s|si|sí)$/i;
 const NO_RE = /^(n|no)$/i;
 
-async function askYesNo(ask, question, catalog) {
+async function askYesNo(ask, question, catalog, { defaultNo = false } = {}) {
   for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
     const raw = String(await ask(question)).trim();
+    if (defaultNo && raw === '') return false;
     if (YES_RE.test(raw)) return true;
     if (NO_RE.test(raw)) return false;
     process.stdout.write(`  ${catalog.consent.invalidAnswer}\n`);
@@ -62,7 +63,12 @@ async function runConsentPrompt({
 
   if (drainBeforeAsk && typeof ask.drain === 'function') ask.drain();
 
-  const accepted = await askYesNo(ask, c.persistQuestion, catalog);
+  if (loggedIn && sessionEmail && isValidEmail(sessionEmail)) {
+    process.stdout.write(`  ${c.savedUnderEmail(sessionEmail)}\n`);
+  }
+
+  // defaultNo: a blank Enter means "do not save" (legal requirement).
+  const accepted = await askYesNo(ask, c.persistQuestion, catalog, { defaultNo: true });
   if (accepted === null) {
     process.stdout.write(`  ${c.notObtained}\n\n`);
     return null;
@@ -92,13 +98,9 @@ async function runConsentPrompt({
     return null;
   }
 
-  if (profile === 'external') {
-    recordConsent('granted', email, { verified: false });
-    process.stdout.write(`  ${c.grantedSavedExternal(email)}\n\n`);
-    return 'granted';
-  }
+  process.stdout.write(`  ${c.savedUnderEmail(email)}\n`);
 
-  // Prove email ownership BEFORE persisting anything (ADR-006).
+  // Prove email ownership BEFORE persisting (ADR-006) — every profile, external included.
   const verification = await verifyEmail({ email, ask, catalog, env });
   if (verification && verification.verified) {
     recordConsent('granted', email, { verified: true });
@@ -106,8 +108,6 @@ async function runConsentPrompt({
     return 'granted';
   }
 
-  // Not verified: persist nothing, re-ask next run. runEmailVerification
-  // already printed the specific reason (cancelled / technical / exhausted).
   process.stdout.write(`  ${c.notObtained}\n\n`);
   return null;
 }

package/src/i18n.js

@@ -637,17 +637,17 @@ const catalogs = {
         + 'puede acarrear penalizaciones en tu cuenta de Shakers, incluida la '
         + 'posible suspensión. Consulta el README de este repositorio para '
         + 'más detalle.',
-      persistQuestion: '¿Guardar este informe en Shakers? (s/n):',
+      persistQuestion: '¿Guardar este informe en Shakers? [s/N]:',
       invalidAnswer: 'Respuesta no reconocida. Responde "s" (sí) o "n" (no).',
       emailPrompt: 'Introduce tu correo:',
-      emailPromptExternal: 'Déjanos tu email para que el equipo de Shakers pueda contactarte (no lo verificamos):',
+      emailPromptExternal: 'Déjanos tu email para que el equipo de Shakers pueda contactarte:',
+      savedUnderEmail: (email) => `El informe se guardará a nombre de: ${email}`,
       invalidEmail: 'Correo no válido, inténtalo de nuevo.',
       notObtained: 'No se ha podido registrar tu respuesta; se te volverá a preguntar la próxima vez.',
       // talents-ai-score, ADR-051: esta pregunta se pide ahora ANTES de cualquier llamada de IA/egress (agent-synthesis, agent-evaluation, personalización de roadmap), no después.
       noReportWithoutConsent: 'Sin tu consentimiento, este informe no incluirá síntesis, evaluación ni roadmap generados por IA esta vez (el resto del informe se muestra igual). Vuelve a ejecutar `usage` y acepta para incluirlos, o usa --consent-reset si quieres que se te pregunte de nuevo.',
       deniedSaved: 'Entendido, no se guardará nada. Puedes cambiar de opinión más adelante volviendo a ejecutar el comando.',
       grantedSaved: (email) => `Gracias. A partir de ahora este informe se guardará automáticamente en Shakers (correo: ${email}, máx. 1 vez por hora).`,
-      grantedSavedExternal: (email) => `Gracias. Hemos guardado tu email (${email}) para que el equipo de Shakers pueda contactarte — no lo hemos verificado.`,
       // talents-ai-score, issue 130: un talento logueado NUNCA ve el prompt de email (su cuenta ya prueba su identidad).
       noSessionEmail: 'No hay un correo asociado a tu sesión todavía, así que no se puede guardar el informe esta vez. Se te preguntará de nuevo la próxima ejecución.',
       skipAlreadyDecided: (decision, path) =>
@@ -2277,17 +2277,17 @@ const catalogs = {
         + 'yours or that you are not authorized to analyze— may result in penalties '
         + "on your Shakers account, up to and including suspension. See this "
         + "repository's README for more detail.",
-      persistQuestion: 'Save this report in Shakers? (y/n):',
+      persistQuestion: 'Save this report in Shakers? [y/N]:',
       invalidAnswer: 'Answer not recognized. Reply "y" (yes) or "n" (no).',
       emailPrompt: 'Enter your email:',
-      emailPromptExternal: "Leave us your email so the Shakers team can reach out (we don't verify it):",
+      emailPromptExternal: 'Leave us your email so the Shakers team can reach out:',
+      savedUnderEmail: (email) => `The report will be saved under: ${email}`,
       invalidEmail: 'Invalid email, try again.',
       notObtained: "Couldn't record your answer; you'll be asked again next time.",
       // talents-ai-score, ADR-051: this question is now asked BEFORE any AI/egress call (agent-synthesis, agent-evaluation, roadmap personalization), not after.
       noReportWithoutConsent: 'Without your consent, this report will not include AI-generated synthesis, evaluation, or roadmap this time (the rest of the report is shown as usual). Run `usage` again and accept to include them, or use --consent-reset if you want to be asked again.',
       deniedSaved: 'Understood, nothing will be saved. You can change your mind later by running the command again.',
       grantedSaved: (email) => `Thanks. From now on this report will be saved in Shakers automatically (email: ${email}, max. once per hour).`,
-      grantedSavedExternal: (email) => `Thanks. We've saved your email (${email}) so the Shakers team can reach out — we haven't verified it.`,
       // talents-ai-score, issue 130: a logged-in Talent is NEVER asked for an email (their account already proves identity).
       noSessionEmail: "There's no email on file for your session yet, so this report can't be saved this time. You'll be asked again next run.",
       skipAlreadyDecided: (decision, path) =>

package/src/mcp-ai-usage-result-tool.js

@@ -70,7 +70,7 @@ function makeAiUsageResultTool(deps = {}) {
   async function handler() {
     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.');
     }
     const endpoint = getUsageDiscoveredInventoryEndpoint();
     if (!endpoint) {
@@ -94,7 +94,9 @@ function makeAiUsageResultTool(deps = {}) {
 
   return {
     name: 'ai_usage_result',
-    description:
+    title: 'Results of your AI analysis',
+    description: 'Fetches from Shakers the description of each AI agent found in the analysis you approved. It reads nothing on this computer.',
+    guidance:
       "Retrieve the enriched Shakers classification for the talent's agents after ai_usage. Shakers classifies agents and writes their descriptions server-side (no client LLM), so this reads the result: per agent { name, tools, model, category, role, level, code, whatItDoes }. Session-keyed, no arguments. Server-side classification can take a few minutes, so this does a bounded internal poll (~90s max, never a long-held call): returns { status: 'ready', agents } once every agent has been classified, or { status: 'pending', agents } while Shakers is still processing (call it again to keep waiting — 'pending' is normal progress, not an error). Present agents to the talent by NAME and category/role only; the `code` field is an internal handle for add_agent, never show it. Requires an active session.",
     inputSchema: RESULT_INPUT_SCHEMA,
     handler,

package/src/mcp-ai-usage-tool.js

@@ -385,7 +385,9 @@ function makeAiUsageTool(deps = {}) {
 
   return {
     name: 'ai_usage',
-    description:
+    title: 'Analyse how you work with AI',
+    description: 'Asks you first and, only if you say yes, looks at which AI tools you use on this computer and the history of your code projects. With your yes it sends a summary with anonymised excerpts to your Shakers profile; your code and prompts never leave your computer.',
+    guidance:
       "Measure how a Shakers talent uses AI in their work: scans this machine and repository for AI-tool usage (subagents, MCP servers, sessions, git activity), scores their AI-maturity tier (T0-T7), and, with the talent's consent, submits the report to Shakers so their profile reflects it. Runs entirely on the talent's own machine. Before any scan, call it without consent: it asks the AI-usage question with both disclaimers in the same block (a dialog, or `say` to print word for word); only an explicit yes allows consent.granted:true, and skipping is consent.granted:false. In the sign-up it is the step right after the account exists and before the interview: on yes it runs and uploads in the background, never wait for it. Submission also requires an active, email-verified Shakers session (via `shakers login` / registration OTP): without a verified session the report stays on this machine and nothing is sent — check the `send` field for the outcome. Always fast and deterministic: it runs no LLM on the machine. Agent descriptions and catalog classification are produced by Shakers server-side. This waits briefly (~30s) and, if classification finishes, returns the enriched agents inline; otherwise it returns enrichment:'pending' (normal progress, not an error) and you should call `ai_usage_result` to get them. The `text` field is a ready-to-show plain-text 'My work with AI' report (Markdown, no ANSI) mirroring the CLI terminal — render it verbatim to the talent; the matrix grid is inside a fenced code block, keep it fenced so it stays aligned. Use the `display` block for structured access: show the tier (with the tierLegend explaining T0-T7) and the agent list by NAME and category/role. IDs and codes (agent `code`, skillId, catalogId) are internal handles for the add_* tools only — never show raw IDs or codes to the talent.",
     inputSchema: AI_USAGE_INPUT_SCHEMA,
     handler,

package/src/mcp-alma-tools.js

@@ -27,7 +27,7 @@ function makeAlmaTools(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 (alma is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (alma is session-gated).');
     }
     return session;
   };
@@ -75,13 +75,17 @@ function makeAlmaTools(deps = {}) {
   return [
     {
       name: 'alma_chat',
-      description: "Send a message to Alma, the Shakers AI assistant, and get her answer (about the talent's profile, rate, availability, skills, positions, applications). Continuity is automatic across turns (same session). When Alma proposes a profile change she returns `pendingConfirmation { text, irreversible }` — DO NOT auto-approve: show the talent `pendingConfirmation.text` (and warn when irreversible), ask them yes/no, then call `alma_decision` with their answer. `webLinks` are web-only navigation targets. Relay the answer as-is; never show internal Shakers ids/codes.",
+      title: 'Chat with Alma',
+      description: 'Sends your message to Alma, the Shakers assistant, and shows her answer. If she proposes a change to your profile, you are asked before it is made.',
+      guidance: "Send a message to Alma, the Shakers AI assistant, and get her answer (about the talent's profile, rate, availability, skills, positions, applications). Continuity is automatic across turns (same session). When Alma proposes a profile change she returns `pendingConfirmation { text, irreversible }` — DO NOT auto-approve: show the talent `pendingConfirmation.text` (and warn when irreversible), ask them yes/no, then call `alma_decision` with their answer. `webLinks` are web-only navigation targets. Relay the answer as-is; never show internal Shakers ids/codes.",
       inputSchema: ALMA_CHAT_SCHEMA,
       handler: almaChat,
     },
     {
       name: 'alma_decision',
-      description: "Relay the talent's decision on the pending Alma action from alma_chat: approved=true makes Alma perform the change, approved=false cancels it. Call this ONLY after the talent has explicitly answered yes/no to the pendingConfirmation — never decide on their behalf.",
+      title: "Confirm Alma's change",
+      description: 'Sends your yes or no to a profile change Alma proposed.',
+      guidance: "Relay the talent's decision on the pending Alma action from alma_chat: approved=true makes Alma perform the change, approved=false cancels it. Call this ONLY after the talent has explicitly answered yes/no to the pendingConfirmation — never decide on their behalf.",
       inputSchema: ALMA_DECISION_SCHEMA,
       handler: almaDecision,
     },

package/src/mcp-applications-tools.js

@@ -14,7 +14,7 @@ function makeApplicationsTools(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_applications is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (list_applications is session-gated).');
     }
     return session;
   };
@@ -29,7 +29,9 @@ function makeApplicationsTools(deps = {}) {
   return [
     {
       name: 'list_applications',
-      description: "List the positions the talent has applied to, with each candidature's status. Read-only. Requires an active session. Any positionId/projectId in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a project by its title/company.",
+      title: 'Your applications',
+      description: 'Shows the projects you applied to and how each application is going.',
+      guidance: "List the positions the talent has applied to, with each candidature's status. Read-only. Requires an active session. Any positionId/projectId in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a project by its title/company.",
       inputSchema: LIST_APPLICATIONS_SCHEMA,
       handler: listApplications,
     },

package/src/mcp-availability-tools.js

@@ -15,7 +15,7 @@ function makeAvailabilityTools(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_availability is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (get_availability is session-gated).');
     }
     return session;
   };
@@ -30,7 +30,9 @@ function makeAvailabilityTools(deps = {}) {
   return [
     {
       name: 'get_availability',
-      description: "View the talent's availability: open-to-work, monthly hours, work modes (a combinable array of REMOTE/HYBRID/IN_PERSON), and location. Read-only. Requires an active session. Any internal ids in the result (e.g. numeric city id) are handles for tools only — never show or mention them to the talent.",
+      title: 'Your availability',
+      description: 'Shows your availability on Shakers: whether you are open to work, hours per month, work mode and location.',
+      guidance: "View the talent's availability: open-to-work, monthly hours, work modes (a combinable array of REMOTE/HYBRID/IN_PERSON), and location. Read-only. Requires an active session. Any internal ids in the result (e.g. numeric city id) are handles for tools only — never show or mention them to the talent.",
       inputSchema: GET_AVAILABILITY_SCHEMA,
       handler: getAvailability,
     },

package/src/mcp-certifications-tools.js

@@ -14,7 +14,7 @@ function makeCertificationsTools(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_certifications is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (list_certifications is session-gated).');
     }
     return session;
   };
@@ -29,7 +29,9 @@ function makeCertificationsTools(deps = {}) {
   return [
     {
       name: 'list_certifications',
-      description: "List the talent's role dimensions with their certification state (CERTIFIED/UNCERTIFIED/EXPIRED), band and main role. Requires an active session. Any dimension/cluster ids in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a dimension by its name.",
+      title: 'Your certifications',
+      description: 'Shows which areas of your roles are certified on Shakers.',
+      guidance: "List the talent's role dimensions with their certification state (CERTIFIED/UNCERTIFIED/EXPIRED), band and main role. Requires an active session. Any dimension/cluster ids in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a dimension by its name.",
       inputSchema: LIST_CERTIFICATIONS_SCHEMA,
       handler: listCertifications,
     },

package/src/mcp-certify-dimension-tools.js

@@ -17,7 +17,7 @@ function makeCertifyDimensionTools(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 (certification is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (certification is session-gated).');
     }
     return session;
   };
@@ -51,7 +51,9 @@ function makeCertifyDimensionTools(deps = {}) {
   return [
     {
       name: 'list_certifiable_dimensions',
-      description: "List the dimensions the talent can certify right now: their main role's hub dimensions whose interview runs by text (terminal or spoken-case templates) and not already CERTIFIED (UNCERTIFIED/EXPIRED). Dimensions the talent cannot retake yet are NOT in `dimensions`; they come in `onCooldown` with the ISO date they free up, so tell the talent when they can retry instead of offering them. Requires an active session. The certification interview itself is done on the web; running `shakers certify` in the terminal hands the talent the web link to take it. The dimensionKey/clusterId in each item are INTERNAL handles for tools only — never show or mention them to the talent; refer to a dimension by its name.",
+      title: 'What you can certify',
+      description: 'Shows which areas of your main role you can certify now and when you can retry the others.',
+      guidance: "List the dimensions the talent can certify right now: their main role's hub dimensions whose interview runs by text (terminal or spoken-case templates) and not already CERTIFIED (UNCERTIFIED/EXPIRED). Dimensions the talent cannot retake yet are NOT in `dimensions`; they come in `onCooldown` with the ISO date they free up, so tell the talent when they can retry instead of offering them. Requires an active session. The certification interview itself is done on the web; running `shakers certify` in the terminal hands the talent the web link to take it. The dimensionKey/clusterId in each item are INTERNAL handles for tools only — never show or mention them to the talent; refer to a dimension by its name.",
       inputSchema: LIST_CERTIFIABLE_DIMENSIONS_SCHEMA,
       handler: listCertifiableDimensions,
     },

package/src/mcp-choice.js

@@ -66,4 +66,30 @@ async function askAfterTexts(ctx, { tool, texts, question, options, answer }) {
   };
 }
 
-module.exports = { askChoice, askAfterTexts, chatChoice, optionFor, queueNotice, takeNotices, SAY_MESSAGE };
+// Questions this process put to the talent in the chat, keyed by exactly what they would allow:
+// an answer counts only for a question the tool asked, so a flag the AI sets by itself never does.
+const pendingConsent = new Set();
+
+// The talent's yes or no before a tool reads this computer or sends data: { granted } or { reply } to return.
+async function askConsent(ctx, { tool, key, question, yes, no, answer }) {
+  const options = [yes, no];
+  const picked = pendingConsent.has(key) ? optionFor(answer, options) : null;
+  if (picked) {
+    pendingConsent.delete(key);
+    return { granted: picked === yes };
+  }
+  const asked = ctx && ctx.elicitation ? await askChoice(ctx, { question, options }) : { chat: chatChoice(question, options) };
+  if (asked.answer) return { granted: asked.answer === yes };
+  pendingConsent.add(key);
+  return {
+    reply: {
+      ok: false,
+      reason: 'consent-required',
+      ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
+      ...asked.chat,
+      message: `Nothing was read or sent. ${asked.chat.choiceMessage} Then call ${tool} again with the same arguments and answer set to the option they pick.`,
+    },
+  };
+}
+
+module.exports = { askConsent, askChoice, askAfterTexts, chatChoice, optionFor, queueNotice, takeNotices, SAY_MESSAGE };

package/src/mcp-device-login-tools.js

@@ -157,13 +157,17 @@ function makeDeviceLoginTools(deps = {}) {
   return [
     {
       name: 'social_signin_start',
-      description: "Begin sign-in (or registration) via the device flow — provider 'google' (default), 'linkedin' or 'email'. Email goes through the SAME web flow: the talent reuses their open Shakers session or signs in with their email on the page, never a password in the chat. Returns a verificationUrl and a userCode: show BOTH to the talent verbatim — they open the URL and enter the code in their own browser (they never type anything in the chat, and you never invent or fill the code). Pass mode 'register' to create the account if it is new. After showing them, call social_signin_poll. Returns { ok, status, provider, verificationUrl, userCode, pollIntervalSeconds, ... }.",
+      title: 'Sign in to Shakers',
+      description: 'Opens a Shakers page in your browser where you sign in with Google, LinkedIn or your email. Your password never goes through the chat.',
+      guidance: "Begin sign-in (or registration) via the device flow — provider 'google' (default), 'linkedin' or 'email'. Email goes through the SAME web flow: the talent reuses their open Shakers session or signs in with their email on the page, never a password in the chat. Returns a verificationUrl and a userCode: show BOTH to the talent verbatim — they open the URL and enter the code in their own browser (they never type anything in the chat, and you never invent or fill the code). Pass mode 'register' to create the account if it is new. After showing them, call social_signin_poll. Returns { ok, status, provider, verificationUrl, userCode, pollIntervalSeconds, ... }.",
       inputSchema: START_SCHEMA,
       handler: start,
     },
     {
       name: 'social_signin_poll',
-      description: "Check whether the talent has finished the social sign-in started by social_signin_start, and persist the session when they have. Call it after showing the code; if it returns status 'pending', wait pollIntervalSeconds and call it again — the 'pending' response repeats the verificationUrl and userCode so you can keep the clickable link in front of the talent. Returns status 'authorized' (session saved, with isNewUser + method), 'pending', 'denied', or 'expired'.",
+      title: 'Finish signing in',
+      description: 'Checks whether you finished signing in on that page and, if so, keeps you signed in on this computer.',
+      guidance: "Check whether the talent has finished the social sign-in started by social_signin_start, and persist the session when they have. Call it after showing the code; if it returns status 'pending', wait pollIntervalSeconds and call it again — the 'pending' response repeats the verificationUrl and userCode so you can keep the clickable link in front of the talent. Returns status 'authorized' (session saved, with isNewUser + method), 'pending', 'denied', or 'expired'.",
       inputSchema: POLL_SCHEMA,
       handler: poll,
     },

package/src/mcp-find-projects-tools.js

@@ -28,7 +28,7 @@ function makeFindProjectsTools(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 (find_projects is session-gated).');
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (find_projects is session-gated).');
     }
     return session;
   };
@@ -54,7 +54,9 @@ function makeFindProjectsTools(deps = {}) {
   return [
     {
       name: 'find_projects',
-      description: "List the Positions/Projects available to the talent right now (Shakers Find Positions), paginated and ordered by match desc. Each item carries its parent Project id/name, title, company, budget, work mode and match. Supports server-side pagination (page/limit) and filters (tab all|saved, attendance, country ISO2). `meta` carries {page,pageSize,total,totalPages}. Requires an active session. The positionId/projectId in each item are INTERNAL handles for calling other tools (e.g. show_project, save_project) — NEVER show or mention them to the talent; refer to a project by its title/company only.",
+      title: 'Find projects',
+      description: 'Shows the open Shakers projects that match you best.',
+      guidance: "List the Positions/Projects available to the talent right now (Shakers Find Positions), paginated and ordered by match desc. Each item carries its parent Project id/name, title, company, budget, work mode and match. Supports server-side pagination (page/limit) and filters (tab all|saved, attendance, country ISO2). `meta` carries {page,pageSize,total,totalPages}. Requires an active session. The positionId/projectId in each item are INTERNAL handles for calling other tools (e.g. show_project, save_project) — NEVER show or mention them to the talent; refer to a project by its title/company only.",
       inputSchema: FIND_PROJECTS_SCHEMA,
       handler: findProjects,
     },