shakers-cli-beta 0.12.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.12.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/authorship-mismatch.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Display-only authorship-transparency check (talents-ai-score).
+//
+// Warns the talent when their commits in the selected repos are authored under
+// an email that is not their Shakers account email, so their own work would be
+// attributed to nobody. This is a WARNING surface ONLY: it reads each repo's
+// CONFIGURED commit identity (`git config user.email`) and compares counts the
+// attribution path already produced — it NEVER feeds attribution/scoring.
+// git-activity.js owns `authoredCommitCount`; nothing here changes any count.
+
+const { execFileSync } = require('child_process');
+
+// The repo's locally configured commit identity. A plain config read, NOT the
+// authorship log parse — it only names who new commits here would be attributed to.
+function readConfiguredEmail(root) {
+  try {
+    const out = execFileSync('git', ['-C', root, 'config', '--get', 'user.email'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const value = String(out || '').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+function normalize(email) {
+  return String(email || '').trim().toLowerCase();
+}
+
+// Returns { accountEmail, emails: [configured emails that differ from the account] }
+// when the talent's own commits are plausibly going unattributed, else null.
+//
+// Conservative on purpose (a false warning erodes trust more than a missed one):
+// it fires only when the account email is known, the selection HAS commits, NONE
+// are attributed to the account, and at least one repo is configured under a
+// different email we can name.
+function detectAuthorshipMismatch(toplevels, accountEmail, gitActivity, { readEmail = readConfiguredEmail } = {}) {
+  const account = normalize(accountEmail);
+  if (!account) return null;
+  if (!gitActivity) return null;
+  const commits = gitActivity.commitCount || 0;
+  const authored = gitActivity.authoredCommitCount || 0;
+  if (commits === 0 || authored > 0) return null;
+
+  const emails = [];
+  const seen = new Set();
+  for (const root of Array.isArray(toplevels) ? toplevels : []) {
+    const configured = readEmail(root);
+    const key = normalize(configured);
+    if (!key || key === account || seen.has(key)) continue;
+    seen.add(key);
+    emails.push(String(configured).trim());
+  }
+  if (emails.length === 0) return null;
+  return { accountEmail: String(accountEmail).trim(), emails };
+}
+
+module.exports = { detectAuthorshipMismatch, readConfiguredEmail };

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');
 }
@@ -621,10 +632,18 @@ function getTranslationsEndpoint(env = process.env) {
   return deriveFromHub(env, 'translations');
 }
 
+// The signed-in user as hub sees it (GET only): read back the phone after saving it.
+function getUserMeEndpoint(env = process.env) {
+  const explicit = readEnv(env, 'USER_ME_ENDPOINT');
+  if (explicit && explicit.trim()) return explicit.trim();
+  return deriveFromHub(env, 'works/users/me');
+}
+
+// Talent base fields (PATCH name, phone...). works/users/me is GET only.
 function getTalentMeEndpoint(env = process.env) {
   const explicit = readEnv(env, 'TALENT_ME_ENDPOINT');
   if (explicit && explicit.trim()) return explicit.trim();
-  return deriveFromHub(env, 'works/users/me');
+  return deriveFromHub(env, 'works/talent/me');
 }
 
 function getOnboardingInterviewsEndpoint(env = process.env) {
@@ -778,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,
@@ -808,6 +827,7 @@ module.exports = {
   getImportProfileEndpoint,
   getMcpSignupEndpoint,
   getMyImportStatusEndpoint,
+  getOnboardingEventsEndpoint,
   getOneTimeTokenEndpoint,
   getOneTimeLoginUrl,
   getProfessionalDetailsEndpoint,
@@ -819,6 +839,7 @@ module.exports = {
   getMePortfoliosEndpoint,
   getTranslationsEndpoint,
   getTalentMeEndpoint,
+  getUserMeEndpoint,
   getOnboardingInterviewsEndpoint,
   getCompleteOnboardingEndpoint,
   getOnboardingRestartEndpoint,

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

@@ -355,8 +355,10 @@ const catalogs = {
         subagents: (n) => `${n} ${n === 1 ? 'run' : 'runs'} de subagente`,
         hours: (h) => `${h} h activas (gap idle > 25 min = pausa)`,
         commits: (authored, total) => `${authored}/${total} commits tuyos`,
-        lines: (added, deleted) => `+${added}/-${deleted} líneas`,
-        velocity: (v) => `${v} commits/día`,
+        lines: (added, deleted) => `+${added}/-${deleted} líneas (del repo)`,
+        velocity: (v) => `${v} commits/día (del repo)`,
+        authorshipMismatch: (emails, account) =>
+          `Tus commits en ${emails.length === 1 ? 'este repo' : 'estos repos'} están a nombre de ${emails.join(', ')}, que no es tu email de Shakers (${account}). Puede que tu trabajo no se te atribuya: configura git con tu email de Shakers (git config user.email "${account}") para que cuente.`,
         workStreams: (streams, multiDay, maxSpan) =>
           `${streams} ${streams === 1 ? 'workstream' : 'workstreams'} (${multiDay} multi-día, máx ${maxSpan}d)`,
         tractionLabel: 'Actividad reciente',
@@ -531,7 +533,7 @@ const catalogs = {
         error: 'No se pudo generar el informe.',
       },
       frameworkIntroUsage:
-        'Esto mide tu fluidez con IA en dos ejes: Setup (madurez de tu tooling, T0–T7, determinista) y Usage (cómo lo usas, evaluado en entrevista + código). Te sitúa en el mapa 3×3 (Explorer → AI Native). Completarlo posiciona tu perfil agéntico para los proyectos que valoran cómo trabajas con IA.',
+        'Esto mide tu fluidez con IA en dos ejes: Setup (madurez de tu tooling, T0–T7, determinista) y Usage (cómo lo usas, evaluado en entrevista + código). Te sitúa en el mapa 3×3 (Explorer → AI Native). Completarlo posiciona tu perfil agéntico para los proyectos que valoran cómo trabajas con IA. Por defecto leo el uso de IA de todo este equipo y asumo que es tuyo (un equipo = tú).',
       // Terminal progress feedback (talents-ai-score): stderr-only status
       // during the two slow phases (see src/terminal-progress.js).
       scanningLabel: 'Escaneando entorno y detectores…',
@@ -635,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) =>
@@ -2001,8 +2003,10 @@ const catalogs = {
         subagents: (n) => `${n} subagent ${n === 1 ? 'run' : 'runs'}`,
         hours: (h) => `${h} active h (idle gap > 25 min = pause)`,
         commits: (authored, total) => `${authored}/${total} commits by you`,
-        lines: (added, deleted) => `+${added}/-${deleted} lines`,
-        velocity: (v) => `${v} commits/day`,
+        lines: (added, deleted) => `+${added}/-${deleted} lines (repo-wide)`,
+        velocity: (v) => `${v} commits/day (repo-wide)`,
+        authorshipMismatch: (emails, account) =>
+          `Your commits in ${emails.length === 1 ? 'this repo' : 'these repos'} are under ${emails.join(', ')}, which is not your Shakers email (${account}). Your work may not be attributed to you: set git to your Shakers email (git config user.email "${account}") so it counts.`,
         workStreams: (streams, multiDay, maxSpan) =>
           `${streams} ${streams === 1 ? 'workstream' : 'workstreams'} (${multiDay} multi-day, max ${maxSpan}d)`,
         tractionLabel: 'Traction',
@@ -2173,7 +2177,7 @@ const catalogs = {
         error: 'Could not generate the report.',
       },
       frameworkIntroUsage:
-        'This measures your AI fluency across two axes: Setup (your tooling\'s maturity, T0–T7, deterministic) and Usage (how you use it, assessed via interview + code). It places you on the 3×3 map (Explorer → AI Native). Completing it positions your agentic profile for projects that value how you work with AI.',
+        'This measures your AI fluency across two axes: Setup (your tooling\'s maturity, T0–T7, deterministic) and Usage (how you use it, assessed via interview + code). It places you on the 3×3 map (Explorer → AI Native). Completing it positions your agentic profile for projects that value how you work with AI. By default it reads the AI usage across this whole machine and assumes it is yours (one machine = you).',
       scanningLabel: 'Scanning environment and detectors…',
       // Loader for the per-selected-repo aggregation phase (git + sessions + steering/decisions + evidence + agent org chart).
       aggregatingLabel: 'Aggregating signals across the selected repos…',
@@ -2273,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,
     },