shakers-cli 0.16.0 → 0.18.0

package/README.md

@@ -64,14 +64,29 @@ Run `shakers` with no command to see every command.
 ## Privacy
 
 - The `ai-usage` scan runs on your machine and its report is shown there first.
-- Saving it to Shakers is opt-in. You are asked once, after you see the report. Change
-  your decision any time with `shakers ai-usage --consent-status`, `--consent-revoke` or
-  `--consent-email`.
-- What is saved is derived data (counts, categories, tier, detected technologies), never
-  file contents, paths, environment variables or credentials.
+- Saving it to Shakers is opt-in. Every time, before anything is uploaded, you see what
+  would be sent and what Shakers does with it, and it is uploaded only if you say yes. You
+  can leave out agents and text excerpts there. `--consent-revoke` stops future uploads
+  from this computer; it does not delete what was already uploaded. To ask for that, write
+  to talent@shakersworks.com.
+- What is sent is mostly derived data (counts, categories, tier, detected technologies,
+  sessions, active days, commits and lines changed). Literal text travels too, and the review
+  shows how much: up to 40 fragments of your messages to AI assistants and 20 commands they
+  ran (200 characters at most each), and the definition (up to 2,000 characters) and short
+  description of each of your AI agents, all after removing anything that looks like a
+  secret, a path or an email. The fragments come from the conversations in the repositories
+  analysed, or from every conversation on this computer when you analyse the whole machine
+  (registration always does). Never your code, your full conversations, the names of your
+  repositories, environment variables or credentials.
+- An AI model from an external provider (OpenAI, Google or Anthropic) analyses that text
+  automatically for Shakers to compute your evaluation, and then it is discarded. Only the result is stored: levels, scores, counts and the names
+  of your tools and agents.
+- Do not run it on a machine or with conversations that hold information you are not
+  allowed to share: client, employer or third-party data. Secret removal is automatic and
+  best effort; names or business details you wrote can remain in the fragments.
 - Certification sends secret-scrubbed samples of your code and your interview answers to
   Shakers to assess them.
-- Read the full policy at <https://shakersworks.com/legal/mcp-privacy>.
+- Read the full policy at <https://www.shakersworks.com/en/politica-de-privacidad>.
 
 ## License
 

package/bin/ai-usage.js

@@ -4,7 +4,9 @@
 const { detectReportLang, getCatalog } = require('../src/i18n');
 const { parseArgs } = require('../src/cli-args');
 const { handleOneShotCommand } = require('../src/usage-oneshot-commands');
+const { createLazyStdinAsk } = require('../src/stdin-ask');
 const { computeUsage } = require('../src/usage-scan');
+const { hasAccountTrace } = require('../src/account-trace');
 const {
   resolveRepoScope,
   machineWideToplevels,
@@ -32,18 +34,35 @@ async function run(argv = process.argv.slice(2), { ask: injectedAsk = null, bypa
   // One-shot commands (consent/endpoint config): act immediately, do NOT scan.
   if (await handleOneShotCommand({ opts, catalog, injectedAsk })) return;
 
-  const { report, maturity, root, gate } = await computeUsage({
-    opts,
-    catalog,
-    lang,
-    inRegistration,
-    prepareIdentity: prepareIdentityAndUsage,
-    resolveConsent: (args) => resolveAiConsent({ ...args, injectedAsk }),
-    resolveScope: (args) => resolveRepoScope({ ...args, injectedAsk }),
-  });
-
-  // 7. Render (or emit --json), persist, optional --build-next-level, auto-share.
-  await renderAndFinalize({ report, maturity, lang, opts, root, gate, catalog, bypassThrottle });
+  if (opts.roadmap && hasAccountTrace()) {
+    process.stdout.write(`\n  ${catalog.cli.roadmapNotForAccounts}\n\n`);
+    return;
+  }
+
+  const ask = injectedAsk || createLazyStdinAsk();
+  try {
+    const { report, maturity, root, gate, repos } = await computeUsage({
+      opts,
+      catalog,
+      lang,
+      inRegistration,
+      prepareIdentity: prepareIdentityAndUsage,
+      resolveConsent: (args) => resolveAiConsent({ ...args, injectedAsk: ask }),
+      resolveScope: async (args) => {
+        if (injectedAsk) return resolveRepoScope({ ...args, injectedAsk });
+        ask.suspend();
+        try {
+          return await resolveRepoScope(args);
+        } finally {
+          ask.resume();
+        }
+      },
+    });
+
+    await renderAndFinalize({ report, maturity, lang, opts, root, gate, catalog, bypassThrottle, repos, injectedAsk: ask });
+  } finally {
+    if (!injectedAsk) ask.close();
+  }
 }
 
 module.exports = { run, resolveRepoScope, machineWideToplevels, promptScope };

package/bin/command-audit-worker.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+
+const { ensureFreshSession } = require('../src/session-refresh');
+const { emitCommandAudit, PAYLOAD_VAR } = require('../src/command-audit');
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(process.env[PAYLOAD_VAR]);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload.command !== 'string') return;
+  await ensureFreshSession(process.env).catch(() => null);
+  await emitCommandAudit({ command: payload.command, argv: payload.args ? [payload.args] : [], env: process.env, id: typeof payload.id === 'string' ? payload.id : null });
+}
+
+main();

package/bin/login.js

@@ -5,7 +5,7 @@
 
 const { detectReportLang, getCatalog } = require('../src/i18n');
 const { getAuthTokenEndpoint, getDeviceAuthorizeEndpoint, getDeviceTokenEndpoint, getCompleteRegistrationEndpoint } = require('../src/config');
-const { runDeviceLogin, appendProviderParam, deviceSessionRecord } = require('../src/device-login');
+const { runDeviceLogin, withDeviceParams, deviceSessionRecord } = require('../src/device-login');
 const { buildRegistrationContext } = require('../src/signup-client');
 const { openPath } = require('../src/open-file');
 const { endSession } = require('../src/session-refresh');
@@ -100,14 +100,10 @@ function persistAndReport(result, c, email = null, output = process.stdout) {
     }
   }
   try {
-    // `cookie`/`cookieExpiresAt` are present for the email (better-auth) flow and
-    // absent for Google (auth-works JWT) — saveAuthSession picks the right model.
     saveAuthSession({
       accessToken: result.accessToken,
       expiresAt: result.expiresAt,
       accessTokenExpiresAt: result.expiresAt,
-      cookie: result.cookie || null,
-      cookieExpiresAt: result.cookieExpiresAt || null,
       sessionToken: result.sessionToken || null,
       sessionExpiresAt: result.sessionExpiresAt || null,
       email,
@@ -120,7 +116,7 @@ function persistAndReport(result, c, email = null, output = process.stdout) {
   }
   output.write(`\n  ${c.success}\n`);
   if (result.expiresAt) output.write(`  ${c.expiresAt(result.expiresAt)}\n`);
-  output.write('\n');
+  output.write(`\n  ${c.deviceGranted}\n\n`);
   return true;
 }
 
@@ -157,8 +153,8 @@ async function runDeviceFlow(provider, c, { openBrowser = openPath, sleep = unde
     {
       ...(sleep ? { sleep } : {}),
       onPrompt: ({ verificationUriComplete, userCode }) => {
-        const url = appendProviderParam(verificationUriComplete, provider);
-        output.write(`\n  ${c.deviceVisit}\n  ${url}\n\n  ${c.deviceCodeLabel(userCode)}\n\n  ${c.deviceWaiting}\n`);
+        const url = withDeviceParams(verificationUriComplete, { provider, mode: 'login', surface: 'cli' });
+        output.write(`\n  ${c.deviceTrust}\n\n  ${c.deviceVisit}\n  ${url}\n\n  ${c.deviceCodeLabel(userCode)}\n\n  ${c.deviceWaiting}\n`);
         if (provider === 'email') output.write(`  ${c.deviceApproveHint}\n`);
         try { openBrowser(url); } catch { /* the printed URL covers it */ }
       },

package/bin/mcp.js

@@ -2,7 +2,7 @@
 'use strict';
 
 const { createMcpServer } = require('../src/mcp-server');
-const { makeAiUsageTool } = require('../src/mcp-ai-usage-tool');
+const { makeAiUsageTools } = require('../src/mcp-ai-usage-tool');
 const { makeAiUsageResultTool } = require('../src/mcp-ai-usage-result-tool');
 const { makeCertifyDimensionTools } = require('../src/mcp-certify-dimension-tools');
 const { makeFindProjectsTools } = require('../src/mcp-find-projects-tools');
@@ -23,13 +23,20 @@ const { makeRoleTools } = require('../src/mcp-role-tools');
 const { makeDeviceLoginTools } = require('../src/mcp-device-login-tools');
 const { makeRegisterTools } = require('../src/mcp-register-tools');
 const { makeSignupTools } = require('../src/mcp-signup-tools');
+const { makeSignupTool, outsideSignup, narratedTool, narrationLanguage, ABSORBED_TOOLS } = require('../src/mcp-signup-flow');
 const { detectFlowLang } = require('../src/i18n');
 const { makeReportTools } = require('../src/mcp-report-tools');
 const { makePrompts } = require('../src/mcp-prompts');
 const { buildServerInstructions } = require('../src/mcp-instructions');
+const { mcpNarration } = require('../src/trust-narration');
 const { ensureFreshSession } = require('../src/session-refresh');
+const { emitCommandAudit } = require('../src/command-audit');
 const { createFunnel } = require('../src/onboarding-funnel');
 
+function narrateTool(lang) {
+  return (name, { failed = false, args } = {}) => mcpNarration(narratedTool(name, args), narrationLanguage(name, args, lang), { failed });
+}
+
 let VERSION = '';
 try {
   VERSION = require('../package.json').version || '';
@@ -43,32 +50,32 @@ 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, 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`
-  + `         open_linkedin_profile,\n`
-  + `         suggest_register_context, read_cv, onboarding_interview_start,\n`
-  + `         onboarding_interview_turn, onboarding_interview_complete,\n`
-  + `         repeat_onboarding_interview, onboarding_finish,\n`
-  + `         list_available_roles, add_role, list_my_roles, set_main_role,\n`
-  + `         report, share,\n`
-  + `         list_certifiable_dimensions, find_projects, show_project,\n`
-  + `         save_project, unsave_project, list_invitations,\n`
-  + `         list_applications, get_availability,\n`
+  + `  Tools: signup (the whole sign-up, step by step), ai_usage, ai_usage_upload,\n`
+  + `         ai_usage_result, logout, social_signin_start, social_signin_poll,\n`
+  + `         list_addable, add_skill, add_agent, add_project, open_web,\n`
+  + `         onboarding_interview_start, onboarding_interview_turn,\n`
+  + `         onboarding_interview_complete, repeat_onboarding_interview,\n`
+  + `         onboarding_finish, list_available_roles, add_role, list_my_roles,\n`
+  + `         set_main_role, report, share, list_certifiable_dimensions,\n`
+  + `         find_projects, show_project, save_project, unsave_project,\n`
+  + `         list_invitations, list_applications, get_availability,\n`
   + `         list_certifications, get_profile, get_rate, get_languages,\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.
-const LOCAL_ONLY_TOOL_NAMES = new Set(['ai_usage', 'ai_usage_result', 'read_cv', 'suggest_register_context']);
+const LOCAL_ONLY_TOOL_NAMES = new Set(['ai_usage', 'ai_usage_upload', 'ai_usage_result', 'read_cv', 'suggest_register_context']);
 
 // `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, funnel = createFunnel({ surface: 'mcp' }), makeInterviewClient = null } = {}) {
   const lang = detectFlowLang();
-  const allTools = [makeAiUsageTool(), makeAiUsageResultTool(), ...makeOnboardingTools(), ...makeRoleTools({ lang, funnel }), ...makeDeviceLoginTools(), ...makeSignupTools({ lang, funnel }), ...makeRegisterTools({ lang, funnel, flowDeps: { makeInterviewClient } }), ...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;
+  const aiUsage = makeAiUsageTools();
+  const allTools = [aiUsage.usage, aiUsage.upload, makeAiUsageResultTool(), ...makeOnboardingTools(), ...makeRoleTools({ lang, funnel }), ...makeDeviceLoginTools({ lang, funnel }), ...makeSignupTools({ lang, funnel }), ...makeRegisterTools({ lang, funnel, flowDeps: { makeInterviewClient } }), ...makeReportTools(), ...makeCertifyDimensionTools(), ...makeFindProjectsTools(), ...makeShowProjectTools(), ...makeSavedPositionsTools(), ...makeInvitationsTools(), ...makeApplicationsTools(), ...makeAvailabilityTools(), ...makeCertificationsTools(), ...makeProfileTools(), ...makeRateTools(), ...makeLangTools(), ...makeSocialsTools(), ...makePortfolioTools(), ...makeAlmaTools()];
+  // The sign-up runs through one tool (`signup`), so Claude Desktop asks the talent once instead of once per step.
+  const tools = localOnly
+    ? allTools.filter((t) => LOCAL_ONLY_TOOL_NAMES.has(t.name))
+    : [makeSignupTool(allTools), ...allTools.filter((t) => !ABSORBED_TOOLS.has(t.name)).map(outsideSignup)];
   // Slash-command prompts, kept to the tools actually registered in this mode.
   const prompts = makePrompts(new Set(tools.map((t) => t.name)), lang);
   return createMcpServer({
@@ -76,10 +83,14 @@ function buildServer({ localOnly = false, funnel = createFunnel({ surface: 'mcp'
     prompts,
     serverInfo: { name: localOnly ? 'Shakers (local scan)' : 'Shakers', version: VERSION || '0.0.0' },
     instructions: localOnly ? null : (client) => buildServerInstructions(client),
-    // 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),
-    afterCall: () => { funnel.flush(); },
+    afterCall: (name) => {
+      funnel.flush();
+      ensureFreshSession(process.env)
+        .catch(() => null)
+        .then(() => emitCommandAudit({ command: `mcp:${name}`, env: process.env }));
+    },
+    narrate: narrateTool(lang),
     onInitialize: ({ clientInfo }) => funnel.setMcpClient(clientInfo.name),
   });
 }
@@ -121,7 +132,7 @@ async function run(argv = process.argv.slice(2), { makeInterviewClient = null }
   await funnel.settle();
 }
 
-module.exports = { run, buildServer, buildServerInstructions, prepareProcess };
+module.exports = { run, buildServer, buildServerInstructions, prepareProcess, narrateTool };
 
 if (require.main === module) {
   run();

package/bin/register.js

@@ -2,9 +2,7 @@
 'use strict';
 
 const { detectFlowLang, getCatalog } = require('../src/i18n');
-const { loadAuthSession, sessionStatus } = require('../src/auth-session-store');
 const { createStdinAsk } = require('../src/stdin-ask');
-const { run: runLogin } = require('./login');
 const { run: runAiUsage } = require('./ai-usage');
 const {
   runOnboarding, makeDeps, CURRENCIES, MONTHLY_HOURS, normalizeAmount,
@@ -20,6 +18,7 @@ const { BRAND_ANSI } = require('../src/brand-ansi');
 const { typeOut } = require('../src/typewriter');
 const { withSpinner } = require('../src/terminal-progress');
 const { openPath } = require('../src/open-file');
+const { termsText, legalCopy } = require('../src/signup-copy');
 const { c: fmt } = require('../src/terminal-format');
 const { createFunnel } = require('../src/onboarding-funnel');
 const red = (s) => `${fmt.danger}${s}${fmt.reset}`;
@@ -122,9 +121,10 @@ function makeIo({ ask, lang, out, acceptDisclaimer, stdinIsTTY = false }) {
       }
       return { fullTimeSelected: true, fullTimeAmount, fullTimeCurrency, partTimeSelected, partTimeAmount, partTimeCurrency };
     },
-    askAvailability: async (c) => {
+    askAvailability: async (c, { onLocation = () => {} } = {}) => {
       const available = isYes(await ask(`  ${c.availableAsk} `));
       const monthlyHours = await promptSelect({ ask, stdinIsTTY, out: selectOut, items: MONTHLY_HOURS, header: `  ${c.monthlyHoursAsk}` });
+      onLocation();
       const workModes = await promptMultiSelect({
         ask,
         stdinIsTTY,
@@ -150,26 +150,11 @@ function makeIo({ ask, lang, out, acceptDisclaimer, stdinIsTTY = false }) {
       const telephoneNumber = (await ask(`  ${c.phoneNumberAsk} `)).trim();
       return { available, monthlyHours, workModes, country, subdivision, timezone, longFullTimeProjects, telephoneCode, telephoneNumber };
     },
-    askSignUp: async (c) => {
-      const name = (await ask(`  ${c.askName} `)).trim();
-      const lastName = (await ask(`  ${c.askLastName} `)).trim();
-      const email = (await ask(`  ${c.askEmail} `)).trim();
-      const askSecret = (prompt) => (typeof ask.secret === 'function' ? ask.secret(`  ${prompt} `) : ask(`  ${prompt} `).then((v) => v.trim()));
-      let password;
-      for (;;) {
-        password = await askSecret(c.askPassword);
-        const again = await askSecret(c.askPasswordConfirm);
-        if (password === again) break;
-        writeErr(c.passwordMismatch);
-      }
-      const newsletterConsent = isYes(await ask(`  ${c.askNewsletter} `));
-      // freelanceType is NOT asked here anymore: it is derived from the work
-      // situation (asked once, after the sources) and sent via professional-details.
-      return { name, lastName, email, password, newsletterConsent };
-    },
-    askGoogleSignUp: async () => {
-      // Nothing to ask: Google supplies name/email; freelanceType is derived later.
-      return {};
+    askTerms: async (c) => {
+      out(`\n  ${termsText(lang, (label, url) => `${label} (${url})`)}\n`);
+      if (!isYes(await ask(`  ${c.termsAsk} `))) return { accepted: false };
+      const newsletterConsent = isYes(await ask(`  ${c.newsletterAsk(legalCopy(lang).newsletter)} `));
+      return { accepted: true, newsletterConsent };
     },
     askWorkSituation: async (c) => {
       const situation = await promptSelect({
@@ -241,13 +226,9 @@ function makeIo({ ask, lang, out, acceptDisclaimer, stdinIsTTY = false }) {
       }
       return rows;
     },
-    onGoogleAuthUrl: (url, userCode) => {
+    onAuthUrl: (url, userCode) => {
       const g = getCatalog(lang).login;
-      out(`\n  ${g.deviceVisit}\n  ${url}\n\n  ${g.deviceCodeLabel(userCode)}\n\n  ${g.deviceWaiting}\n`);
-    },
-    login: async () => {
-      await runLogin(['--lang', lang], { ask });
-      return sessionStatus(loadAuthSession()) === 'active';
+      out(`\n  ${g.deviceTrust}\n\n  ${g.deviceVisit}\n  ${url}\n\n  ${g.deviceCodeLabel(userCode)}\n\n  ${g.deviceWaiting}\n`);
     },
     // Registration always measures the whole machine (--all-repos).
     runUsage: async () => { await runAiUsage(['--lang', lang, '--all-repos'], { ask, bypassThrottle: true, inRegistration: true }); },
@@ -331,7 +312,8 @@ 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({ makeInterviewClient: createInterviewClient }), { method, openBrowser, onAuthUrl: io.onGoogleAuthUrl, openProfile, funnel: registrationFunnel });
+    const openAuth = openBrowser || (deps || o.noOpen ? undefined : openPath);
+    const result = await runOnboarding(io, deps || makeDeps({ makeInterviewClient: createInterviewClient }), { method, openBrowser: openAuth, onAuthUrl: io.onAuthUrl, openProfile, funnel: registrationFunnel });
     if (!result.ok) {
       process.stderr.write(`\n  ${red(`register: ${result.reason}${result.step ? ` (${result.step})` : ''}`)}\n\n`);
       process.exitCode = 1;

package/bin/shakers-cli.js

@@ -37,9 +37,10 @@ const { run: runOnboarding } = require('./onboarding');
 const { run: runConfig } = require('./config');
 const { run: runUpdate } = require('./update');
 const { checkOnboardingCompleted } = require('../src/onboarding-availability');
-const { emitCommandAudit } = require('../src/command-audit');
+const { startCommandAudit } = require('../src/command-audit');
 const { readPackageInfo } = require('../src/update-flow');
 const { isSuppressed, maybeNotify, triggerBackgroundCheck } = require('../src/update-notifier');
+const { cliNarration, changedNothing } = require('../src/trust-narration');
 
 let VERSION = '';
 try {
@@ -92,10 +93,11 @@ const HANDLERS = {
   login: runLogin,
   logout: runLogout,
   superadmin: runSuperadmin,
-  mcp: () => require('../src/mcp-install').runMcpInstall(),
+  mcp: (args) => require('../src/mcp-install').runMcpInstall({ args }),
+  skill: (args) => require('../src/skill-install').runSkillInstall({ args }),
 };
 
-const SESSION_EXEMPT = new Set(['ai-usage', 'register', 'config', 'login', 'logout', 'superadmin', 'mcp', 'share', 'alma', 'update']);
+const SESSION_EXEMPT = new Set(['ai-usage', 'register', 'config', 'login', 'logout', 'superadmin', 'mcp', 'skill', 'share', 'alma', 'update']);
 
 // Command FAMILIES — a navigation layer over the flat commands (which all stay
 // valid as aliases). `shakers <family> <sub>` resolves to the flat handler; every
@@ -178,7 +180,8 @@ function usageText(lang, { hideOnboarding = false } = {}) {
       + `  Público (sin sesión):\n`
       + `    ai-usage     Escanea este proyecto + tu máquina y puntúa tu setup de IA\n`
       + `    register     Registro completo: perfil, precio, uso de IA y entrevista\n`
-      + `    mcp          Servidor MCP local (stdio) para apps de IA de escritorio\n\n`
+      + `    mcp          Servidor MCP local (stdio) para apps de IA de escritorio\n`
+      + `    skill install Instala la skill shakers-cli en Claude Code y Codex\n\n`
       + `  Requieren sesión (ejecuta antes: shakers login):\n`
       + onboardingLine
       + `    certify      Certifica una dimensión de tu rol (entrevista por LiveKit)\n`
@@ -222,7 +225,8 @@ function usageText(lang, { hideOnboarding = false } = {}) {
     + `  Public (no session):\n`
     + `    ai-usage     Scan this project + machine and score your AI setup\n`
     + `    register     Full registration: profile, pricing, AI usage and interview\n`
-    + `    mcp          Local MCP server (stdio) for desktop AI apps\n\n`
+    + `    mcp          Local MCP server (stdio) for desktop AI apps\n`
+    + `    skill install Install the shakers-cli skill into Claude Code and Codex\n\n`
     + `  Require a session (run \`shakers login\` first):\n`
     + onboardingLine
     + `    certify      Certify a dimension of your role (LiveKit interview)\n`
@@ -287,15 +291,13 @@ async function main() {
 
   migrateLegacyConfigDir(process.env);
   sanitizeStaleBakedEndpoints(process.env);
-  // Mint a fresh hub JWT from the stored cookie once per command (email sessions only; a no-op for Google/legacy or when no session exists).
   try { await ensureFreshSession(process.env); } catch { /* never blocks a command */ }
 
   const token = argv.find((a) => !a.startsWith('-'));
 
-  // Single dispatch choke-point: audit EXACTLY once before branching, fire-and-forget (never awaited). MCP tool calls run in-process and never reach here.
   const auditCommand =
     !token || token.toLowerCase() === 'help' ? 'help' : token.toLowerCase();
-  emitCommandAudit({ command: auditCommand, argv, env: process.env });
+  startCommandAudit({ command: auditCommand, argv, env: process.env });
 
   // Non-blocking update notice: reads a cached version synchronously, registry check runs in a detached worker; stderr-only, suppressed for --json/non-TTY/CI/update/opt-out.
   if (!isSuppressed({ argv, command: auditCommand, env: process.env })) {
@@ -346,7 +348,10 @@ async function main() {
     await remindAccountForAiUsage(lang, args);
   }
 
-  await handler(args);
+  const narration = wantsHelp || args.includes('--json') ? { before: null, after: null } : cliNarration(command, args, lang);
+  if (narration.before) process.stderr.write(`\n  ${narration.before}\n`);
+  const outcome = await handler(args);
+  if (narration.after && !process.exitCode && !changedNothing(outcome)) process.stderr.write(`\n  ${narration.after}\n\n`);
 }
 
-module.exports = { main };
+module.exports = { main, HANDLERS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakers-cli",
-  "version": "0.16.0",
+  "version": "0.18.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/account-marker.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { getConfigDir } = require('./config-dir');
+
+const MARKER_FILE_NAME = 'account-marker.json';
+const MARKER_FILE_VERSION = 1;
+
+function accountMarkerPath(env = process.env) {
+  return path.join(getConfigDir(env), MARKER_FILE_NAME);
+}
+
+function hasAccountMarker(env = process.env, { fs: fsImpl = fs } = {}) {
+  return fsImpl.existsSync(accountMarkerPath(env));
+}
+
+function recordAccountMarker(kind, env = process.env, { fs: fsImpl = fs } = {}) {
+  if (hasAccountMarker(env, { fs: fsImpl })) return;
+  const target = accountMarkerPath(env);
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.${MARKER_FILE_NAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  const payload = `${JSON.stringify({ version: MARKER_FILE_VERSION, kind, at: new Date().toISOString() }, null, 2)}\n`;
+  try {
+    fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const fd = fsImpl.openSync(tmp, 'wx', 0o600);
+    try {
+      fsImpl.writeFileSync(fd, payload);
+      try { fsImpl.fsyncSync(fd); } catch {}
+    } finally {
+      fsImpl.closeSync(fd);
+    }
+    fsImpl.renameSync(tmp, target);
+  } catch {
+    try { fsImpl.unlinkSync(tmp); } catch {}
+  }
+}
+
+module.exports = { hasAccountMarker, recordAccountMarker };

package/src/account-trace.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { hasAuthSessionFile } = require('./auth-session-store');
+const { loadConsentState } = require('./share-consent-state');
+const { loadConfigFile } = require('./config');
+const { hasAccountMarker, recordAccountMarker } = require('./account-marker');
+
+function hasCurrentTrace(env) {
+  const consent = loadConsentState(env);
+  return hasAuthSessionFile(env)
+    || !!(consent && consent.lastSentAt)
+    || require('./report-store').hasRecordedUpload(env)
+    || !!loadConfigFile(env).superadminSession;
+}
+
+function hasAccountTrace(env = process.env) {
+  if (hasAccountMarker(env)) return true;
+  if (!hasCurrentTrace(env)) return false;
+  recordAccountMarker('existing-trace', env);
+  return true;
+}
+
+module.exports = { hasAccountTrace };

package/src/agents-client.js

@@ -54,6 +54,7 @@ async function requestListAgents({ accessToken, hubAccessToken } = {}, { endpoin
     .map((entry) => ({
       name: entry && typeof entry.name === 'string' ? entry.name : null,
       id: entry && (typeof entry.id === 'string' || typeof entry.id === 'number') ? String(entry.id) : null,
+      source: entry && typeof entry.source === 'string' ? entry.source : null,
     }))
     .filter((a) => a.name !== null);
   return { ok: true, agents };

package/src/ai-usage-review.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const path = require('path');
+const { derivePayload } = require('./share-payload');
+const { classify } = require('./maturity');
+const { reviewCopy } = require('./signup-copy');
+const { sanitizeRenderText } = require('./sanitize-network-text');
+
+function repoName(repo) {
+  return path.basename(String(repo)) || String(repo);
+}
+
+function uploadFacts({ report, maturity, repos = [] }) {
+  const payload = derivePayload(report, maturity);
+  const sessions = payload.sessions || {};
+  const conversationExcerpts =
+    (payload.steering ? payload.steering.redactedSteeringExcerpts.length : 0)
+    + (payload.decisions ? payload.decisions.redactedDecisionExcerpts.length : 0);
+  const commandExcerpts = Array.isArray(sessions.redactedCommandSample) ? sessions.redactedCommandSample.length : 0;
+  return {
+    tools: (report.tools || []).filter((t) => t && t.detected).map((t) => t.name || t.id),
+    technologies: payload.technologies.filter((t) => typeof t === 'string'),
+    sessionCount: sessions.sessionCount || 0,
+    activeDaysPerWeek: typeof sessions.activeDaysPerWeek === 'number' ? sessions.activeDaysPerWeek : null,
+    commitCount: payload.gitActivity ? payload.gitActivity.commitCount : 0,
+    repos: repos.map(repoName),
+    agents: payload.agents.map((a) => a.name),
+    agentDefinitions: payload.agents.filter((a) => a.definition).length,
+    agentSummaries: payload.agentSynthesis.filter((a) => a.whatItDoes || a.symbolicName).length,
+    conversationExcerpts,
+    commandExcerpts,
+  };
+}
+
+function keepNamed(list, excluded) {
+  return Array.isArray(list) ? list.filter((x) => !(x && excluded.has(x.name))) : list;
+}
+
+function withoutExcluded(report, { agents = [], excerpts = true } = {}) {
+  const excluded = new Set(agents);
+  const next = structuredClone(report);
+  if (excluded.size > 0) {
+    next.agents = keepNamed(next.agents, excluded)
+      .map((a) => (a && excluded.has(a.parent) ? { ...a, parent: null } : a));
+    next.agentDefinitions = keepNamed(next.agentDefinitions, excluded);
+    next.agentDescriptions = keepNamed(next.agentDescriptions, excluded);
+    if (next.agentEvaluation) next.agentEvaluation.evaluations = keepNamed(next.agentEvaluation.evaluations, excluded);
+    if (next.agentSynthesis) next.agentSynthesis.agents = keepNamed(next.agentSynthesis.agents, excluded);
+    if (next.detectionEvidence) next.detectionEvidence.agents = keepNamed(next.detectionEvidence.agents, excluded);
+    if (next.agentUsage && next.agentUsage.byAgent) {
+      for (const name of excluded) delete next.agentUsage.byAgent[name];
+    }
+    if (next.agentCounts) next.agentCounts.agents = Array.isArray(next.agents) ? next.agents.length : 0;
+  }
+  if (!excerpts) {
+    if (next.steering) next.steering.redactedSteeringExcerpts = [];
+    if (next.decisions) next.decisions.redactedDecisionExcerpts = [];
+    if (next.sessions) next.sessions.redactedCommandSample = [];
+  }
+  return { report: next, maturity: classify(next) };
+}
+
+function joined(list) {
+  return list.join(', ');
+}
+
+function summaryText(lang, facts, { sent = false } = {}) {
+  const c = reviewCopy(lang);
+  return [
+    sent ? c.sentTitle : c.title,
+    facts.tools.length ? c.tools(joined(facts.tools)) : null,
+    facts.technologies.length ? c.technologies(joined(facts.technologies)) : null,
+    c.activity(facts.sessionCount, facts.activeDaysPerWeek),
+    facts.repos.length ? c.repos(joined(facts.repos), facts.commitCount) : null,
+    facts.agents.length ? c.agents(joined(facts.agents), facts.agentDefinitions, facts.agentSummaries) : null,
+    facts.conversationExcerpts + facts.commandExcerpts > 0 ? c.excerpts(facts.conversationExcerpts, facts.commandExcerpts) : c.noExcerpts,
+    c.notSent,
+  ].filter(Boolean).map((line, i) => (i === 0 ? line : `- ${line}`)).join('\n');
+}
+
+function explanationText(lang) {
+  const c = reviewCopy(lang);
+  return [c.explanationTitle, ...c.explanation, c.afterwards].join('\n\n');
+}
+
+// `explained`: the talent already read what the two axes mean and how to disagree (the review in the sign-up), so they are not repeated.
+function resultText(lang, preview, { explained = false } = {}) {
+  const c = reviewCopy(lang);
+  const after = explained ? [] : [c.afterwards];
+  if (!preview) return [c.resultPending, ...after].join('\n\n');
+  const m = preview.matrix || {};
+  const lines = [
+    c.resultTitle,
+    m.setupLevel ? c.setupLevel(c.levels[m.setupLevel] || m.setupLevel) : null,
+    preview.setup && preview.setup.explanation,
+    m.usageLevel ? c.usageLevel(c.levels[m.usageLevel] || m.usageLevel) : null,
+    preview.usage && preview.usage.explanation,
+    m.cell ? c.cell(m.cell) : null,
+  ].filter(Boolean).map(sanitizeRenderText);
+  return [lines.join('\n'), ...(explained ? [] : [c.explanation[0]]), ...after].join('\n\n');
+}
+
+module.exports = { uploadFacts, withoutExcluded, repoName, summaryText, explanationText, resultText };