shakers-cli 0.16.0 → 0.18.0

package/src/mcp-install.js

@@ -10,9 +10,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { buildServerInstructions } = require('./mcp-instructions');
 
-const SERVER_NAME = 'shakers';
-// The name the first published setup guide used.
-const LEGACY_SERVER_NAME = 'shakers-ai-usage';
+const { SERVER_NAME, LEGACY_SERVER_NAME } = require('./mcp-server-name');
 const FORWARDED_ENV = [
   'SHAKERS_PROFILE',
   'SHAKERS_CLI_CERTS_BASE',
@@ -38,11 +36,57 @@ function stableNodePath(env, execPath) {
   return execPath;
 }
 
-function serverEntry({ nodePath, cliPath, env }) {
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+
+function realpathOr(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+function insideNpxCache(file, { env, platform, homedir }) {
+  const p = pathFor(platform);
+  const defaultCache = platform === 'win32'
+    ? p.join(env.LOCALAPPDATA || p.join(homedir, 'AppData', 'Local'), 'npm-cache')
+    : p.join(homedir, '.npm');
+  return [env.npm_config_cache, defaultCache].filter(Boolean).flatMap((dir) => [dir, realpathOr(dir)]).some((dir) => {
+    const rel = p.relative(p.join(dir, '_npx'), file);
+    return rel !== '' && !rel.startsWith('..') && !p.isAbsolute(rel);
+  });
+}
+
+function withoutNpxBins(value, where) {
+  const p = pathFor(where.platform);
+  return value.split(p.delimiter).filter((dir) => {
+    const parts = p.normalize(dir).split(p.sep);
+    const [last, parent] = [parts[parts.length - 1], parts[parts.length - 2]];
+    return !(last === 'node-gyp-bin' || (last === '.bin' && parent === 'node_modules') || insideNpxCache(dir, where));
+  }).join(p.delimiter);
+}
+
+function npxNextTo(nodePath) {
+  const candidate = path.join(path.dirname(nodePath), 'npx');
+  try {
+    fs.accessSync(candidate, fs.constants.X_OK);
+    return candidate;
+  } catch {
+    return 'npx';
+  }
+}
+
+function serverEntry({ nodePath, cliPath, env, platform = process.platform, homedir = os.homedir(), packageName }) {
+  const where = { env, platform, homedir };
+  const viaNpx = insideNpxCache(cliPath, where);
   const entryEnv = {};
-  if (env.PATH) entryEnv.PATH = env.PATH;
+  const pathValue = env.PATH && viaNpx ? withoutNpxBins(env.PATH, where) : env.PATH;
+  if (pathValue) entryEnv.PATH = pathValue;
   for (const key of FORWARDED_ENV) if (env[key]) entryEnv[key] = env[key];
-  return { command: nodePath, args: [cliPath, 'mcp'], env: entryEnv };
+  if (!viaNpx) return { command: nodePath, args: [cliPath, 'mcp'], env: entryEnv };
+  const npxArgs = ['-y', packageName, 'mcp'];
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'npx', ...npxArgs], env: entryEnv };
+  return { command: npxNextTo(nodePath), args: npxArgs, env: entryEnv };
 }
 
 function claudeDesktopConfigPath({ platform, homedir, env }) {
@@ -51,11 +95,11 @@ function claudeDesktopConfigPath({ platform, homedir, env }) {
   return path.join(homedir, '.config', 'Claude', 'claude_desktop_config.json');
 }
 
-function writeJsonAtomic(file, value, mode) {
+function writeFileAtomic(file, text, mode) {
   const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
   const fd = fs.openSync(tmp, 'wx', mode);
   try {
-    fs.writeSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    fs.writeSync(fd, text);
     fs.fsyncSync(fd);
   } catch (e) {
     fs.closeSync(fd);
@@ -78,14 +122,14 @@ function installIntoJsonConfig(file, entry, key = 'mcpServers') {
     try {
       config = raw.trim() ? JSON.parse(raw) : {};
     } catch {
-      return { status: 'invalid-json' };
+      return { status: 'invalid-config' };
     }
-    if (!config || typeof config !== 'object' || Array.isArray(config)) return { status: 'invalid-json' };
+    if (!config || typeof config !== 'object' || Array.isArray(config)) return { status: 'invalid-config' };
     mode = fs.statSync(file).mode & 0o777;
   }
   const current = config[key];
   if (current !== undefined && (!current || typeof current !== 'object' || Array.isArray(current))) {
-    return { status: 'invalid-json' };
+    return { status: 'invalid-config' };
   }
   const servers = current || {};
   const legacy = Object.prototype.hasOwnProperty.call(servers, LEGACY_SERVER_NAME);
@@ -94,19 +138,156 @@ function installIntoJsonConfig(file, entry, key = 'mcpServers') {
   const next = { ...config, [key]: { ...servers, [SERVER_NAME]: entry } };
   delete next[key][LEGACY_SERVER_NAME];
   if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
-  writeJsonAtomic(file, next, mode);
+  writeFileAtomic(file, `${JSON.stringify(next, null, 2)}\n`, mode);
   return { status: 'configured', removedLegacy: legacy };
 }
 
+const TOML_ESCAPES = { '"': '\\"', '\\': '\\\\', '\b': '\\b', '\t': '\\t', '\n': '\\n', '\f': '\\f', '\r': '\\r' };
+const tomlString = (s) => `"${String(s).replace(/["\\\u0000-\u001f\u007f]/g, (ch) => TOML_ESCAPES[ch] || `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`)}"`;
+const tomlKey = (k) => (/^[A-Za-z0-9_-]+$/.test(k) ? k : tomlString(k));
+
+function tomlServerBlock(entry, eol = '\n') {
+  const env = Object.entries(entry.env || {});
+  return [
+    `[mcp_servers.${SERVER_NAME}]`,
+    `command = ${tomlString(entry.command)}`,
+    `args = [${entry.args.map(tomlString).join(', ')}]`,
+    ...(env.length ? [`env = { ${env.map(([k, v]) => `${tomlKey(k)} = ${tomlString(v)}`).join(', ')} }`] : []),
+    'startup_timeout_sec = 30',
+    '',
+  ].join(eol);
+}
+
+function parseTomlKeyPath(text) {
+  const keys = [];
+  let rest = text.trim();
+  while (rest) {
+    const m = rest.match(/^(?:([A-Za-z0-9_-]+)|"((?:[^"\\]|\\.)*)"|'([^']*)')\s*/);
+    if (!m) return null;
+    keys.push(m[1] ?? (m[2] !== undefined ? JSON.parse(`"${m[2]}"`) : m[3]));
+    rest = rest.slice(m[0].length);
+    if (!rest) break;
+    if (rest[0] !== '.') return null;
+    rest = rest.slice(1).trimStart();
+    if (!rest) return null;
+  }
+  return keys.length ? keys : null;
+}
+
+function scanTomlValue(line, state) {
+  let i = 0;
+  while (i < line.length) {
+    if (state.multiline) {
+      const end = line.indexOf(state.multiline, i);
+      if (end === -1) return;
+      i = end + 3;
+      state.multiline = null;
+      continue;
+    }
+    const ch = line[i];
+    if (ch === '#') return;
+    if (line.startsWith('"""', i) || line.startsWith("'''", i)) {
+      state.multiline = line.slice(i, i + 3);
+      i += 3;
+    } else if (ch === '"' || ch === "'") {
+      i += 1;
+      while (i < line.length && line[i] !== ch) i += ch === '"' && line[i] === '\\' ? 2 : 1;
+      i += 1;
+    } else {
+      if (ch === '[' || ch === '{') state.depth += 1;
+      if (ch === ']' || ch === '}') state.depth -= 1;
+      i += 1;
+    }
+  }
+}
+
+const OUR_TOML_NAMES = [SERVER_NAME, LEGACY_SERVER_NAME];
+const isOurs = (keys) => keys.length >= 2 && keys[0] === 'mcp_servers' && OUR_TOML_NAMES.includes(keys[1]);
+
+function removeTomlServers(text) {
+  const lines = text.match(/[^\n]*\n|[^\n]+$/g) || [];
+  const state = { multiline: null, depth: 0 };
+  const kept = [];
+  let table = [];
+  let ours = false;
+  let tail = [];
+  let removedLegacy = false;
+  const flushTail = () => {
+    const firstComment = tail.findIndex((l) => l.trim().startsWith('#'));
+    if (firstComment !== -1) kept.push(...tail.slice(firstComment));
+    tail = [];
+  };
+  for (const line of lines) {
+    const bare = line.replace(/\r?\n$/, '');
+    const trimmed = bare.trim();
+    if (!state.multiline && state.depth === 0 && trimmed.startsWith('[')) {
+      const header = trimmed.match(/^(\[\[?)\s*(.*?)\s*(\]\]?)\s*(#.*)?$/);
+      const keys = header && header[1].length === header[3].length ? parseTomlKeyPath(header[2]) : null;
+      if (!keys) return null;
+      if (header[1] === '[[' && keys[0] === 'mcp_servers' && (keys.length === 1 || isOurs(keys))) return null;
+      if (isOurs(keys)) {
+        if (keys[1] === LEGACY_SERVER_NAME) removedLegacy = true;
+        ours = true;
+        tail = [];
+        continue;
+      }
+      if (ours) flushTail();
+      ours = false;
+      table = keys;
+      kept.push(line);
+      continue;
+    }
+    if (!state.multiline && state.depth === 0 && trimmed && !trimmed.startsWith('#')) {
+      const eq = bare.match(/^\s*((?:[A-Za-z0-9_.\s-]|"(?:[^"\\]|\\.)*"|'[^']*')+?)\s*=/);
+      const keys = eq && parseTomlKeyPath(eq[1]);
+      if (!keys) return null;
+      const full = [...table, ...keys];
+      if (!ours && full[0] === 'mcp_servers' && (full.length === 1 || OUR_TOML_NAMES.includes(full[1]))) return null;
+      scanTomlValue(bare.slice(eq[0].length), state);
+    } else if (state.multiline || state.depth > 0) {
+      scanTomlValue(bare, state);
+    }
+    if (!ours) kept.push(line);
+    else if (!trimmed || trimmed.startsWith('#')) tail.push(line);
+    else tail = [];
+  }
+  if (state.multiline || state.depth !== 0) return null;
+  if (ours) flushTail();
+  return { text: kept.join(''), removedLegacy };
+}
+
+function installIntoTomlConfig(file, entry) {
+  if (!fs.existsSync(path.dirname(file))) return { status: 'not-found' };
+  const exists = fs.existsSync(file);
+  const raw = exists ? fs.readFileSync(file, 'utf8') : '';
+  const removed = removeTomlServers(raw);
+  if (!removed) return { status: 'invalid-config' };
+  const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+  let base = removed.text;
+  if (base && !base.endsWith('\n')) base += eol;
+  if (base && !/\r?\n\r?\n$/.test(base)) base += eol;
+  const next = base + tomlServerBlock(entry, eol);
+  if (next === raw) return { status: 'unchanged' };
+  const mode = exists ? fs.statSync(file).mode & 0o777 : 0o600;
+  if (exists) fs.copyFileSync(file, `${file}.bak`);
+  writeFileAtomic(file, next, mode);
+  return { status: 'configured', removedLegacy: removed.removedLegacy };
+}
+
+function shellQuote(arg, platform) {
+  if (platform === 'win32') return /^[A-Za-z0-9_\-./=@\\:]+$/.test(arg) ? arg : `"${arg}"`;
+  return /^[A-Za-z0-9_\-./=@%+,]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+function claudeCodeAddArgs(entry) {
+  const envFlags = Object.entries(entry.env).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
+  // Name before `-e`: it swallows every value up to `--`.
+  return ['mcp', 'add', SERVER_NAME, '--scope', 'user', ...envFlags, '--', entry.command, ...entry.args];
+}
+
 function installIntoClaudeCode(entry, { spawn }) {
   spawn('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME], { encoding: 'utf8' });
-  const envFlags = Object.entries(entry.env).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
-  const added = spawn(
-    'claude',
-    // Name first: `-e` takes every value up to `--`, so a name after it is read as one more variable.
-    ['mcp', 'add', SERVER_NAME, '--scope', 'user', ...envFlags, '--', entry.command, ...entry.args],
-    { encoding: 'utf8' },
-  );
+  const added = spawn('claude', claudeCodeAddArgs(entry), { encoding: 'utf8' });
   if (added.error || added.status !== 0) return { status: 'failed' };
   return { status: 'configured' };
 }
@@ -123,7 +304,7 @@ function codexSkill() {
     '',
     '# Shakers',
     '',
-    'Every Shakers action is a tool of the `shakers` MCP server. They are deferred: they are not in your tool list, but `exec` has them as `tools.mcp__shakers__<name>` and lists them in `ALL_TOOLS` (filter by `name.startsWith(\'mcp__shakers__\')`). Never say you have no Shakers tools without checking `ALL_TOOLS`. The tool names below are those `<name>`s: to sign the talent up, call `tools.mcp__shakers__signup_start` first.',
+    'Every Shakers action is a tool of the `shakers` MCP server. They are deferred: they are not in your tool list, but `exec` has them as `tools.mcp__shakers__<name>` and lists them in `ALL_TOOLS` (filter by `name.startsWith(\'mcp__shakers__\')`). Never say you have no Shakers tools without checking `ALL_TOOLS`. The tool names below are those `<name>`s: to sign the talent up, call `tools.mcp__shakers__signup` with step "start" first, and every later sign-up step through it.',
     '',
     '## Server instructions',
     '',
@@ -133,18 +314,23 @@ function codexSkill() {
 }
 
 function installCodexSkill({ env, homedir }) {
-  const dir = path.join(env.CODEX_HOME || path.join(homedir, '.codex'), 'skills', SERVER_NAME);
+  const dir = path.join(codexHomeDir({ env, homedir }), 'skills', SERVER_NAME);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(dir, 'SKILL.md'), codexSkill());
+  writeFileAtomic(path.join(dir, 'SKILL.md'), codexSkill(), 0o600);
 }
 
-function installIntoCodex(entry, { spawn, env, homedir }) {
-  spawn('codex', ['mcp', 'remove', SERVER_NAME], { encoding: 'utf8' });
-  const envFlags = Object.entries(entry.env).flatMap(([k, v]) => ['--env', `${k}=${v}`]);
-  const added = spawn('codex', ['mcp', 'add', SERVER_NAME, ...envFlags, '--', entry.command, ...entry.args], { encoding: 'utf8' });
-  if (added.error || added.status !== 0) return { status: 'failed' };
-  installCodexSkill({ env, homedir });
-  return { status: 'configured' };
+const codexHomeDir = ({ env, homedir }) => env.CODEX_HOME || path.join(homedir, '.codex');
+
+function chatgptAppInstalled({ platform, homedir }) {
+  return platform === 'darwin' && fs.existsSync(path.join(homedir, 'Library', 'Application Support', 'com.openai.chat'));
+}
+
+function installIntoCodex(entry, { env, homedir }) {
+  const dir = codexHomeDir({ env, homedir });
+  fs.mkdirSync(dir, { recursive: true });
+  const result = installIntoTomlConfig(path.join(dir, 'config.toml'), entry);
+  if (result.status === 'configured' || result.status === 'unchanged') installCodexSkill({ env, homedir });
+  return result;
 }
 
 function vscodeUserDir({ platform, homedir, env }) {
@@ -153,11 +339,17 @@ function vscodeUserDir({ platform, homedir, env }) {
   return path.join(homedir, '.config', 'Code', 'User');
 }
 
+function cliOnPath(spawn, bin) {
+  const probe = spawn(bin, ['--version'], { encoding: 'utf8' });
+  return !probe.error && probe.status === 0;
+}
+
+function codexDetected({ env, platform, homedir, spawn }) {
+  return fs.existsSync(codexHomeDir({ env, homedir })) || cliOnPath(spawn, 'codex') || chatgptAppInstalled({ platform, homedir });
+}
+
 function clientTable({ env, platform, homedir, spawn }) {
-  const hasCli = (bin) => {
-    const probe = spawn(bin, ['--version'], { encoding: 'utf8' });
-    return !probe.error && probe.status === 0;
-  };
+  const hasCli = (bin) => cliOnPath(spawn, bin);
   const jsonClient = (client, file, key, shape = (entry) => entry) => ({
     client,
     found: () => fs.existsSync(path.dirname(file)),
@@ -165,10 +357,20 @@ function clientTable({ env, platform, homedir, spawn }) {
   });
   return [
     jsonClient('claudeDesktop', claudeDesktopConfigPath({ platform, homedir, env })),
-    { client: 'claudeCode', found: () => hasCli('claude'), install: (entry) => installIntoClaudeCode(entry, { spawn }) },
+    {
+      client: 'claudeCode',
+      found: () => hasCli('claude') || fs.existsSync(path.join(homedir, '.claude.json')),
+      install: (entry) => (hasCli('claude')
+        ? installIntoClaudeCode(entry, { spawn })
+        : { status: 'manual', command: ['claude', ...claudeCodeAddArgs(entry)].map((a) => shellQuote(a, platform)).join(' ') }),
+    },
     jsonClient('cursor', path.join(homedir, '.cursor', 'mcp.json')),
     jsonClient('geminiCli', path.join(homedir, '.gemini', 'settings.json')),
-    { client: 'codex', found: () => hasCli('codex'), install: (entry) => installIntoCodex(entry, { spawn, env, homedir }) },
+    {
+      client: 'codex',
+      found: () => codexDetected({ env, platform, homedir, spawn }),
+      install: (entry) => installIntoCodex(entry, { env, homedir }),
+    },
     // VS Code keys servers under "servers" and wants the transport spelled out.
     jsonClient('vscode', path.join(vscodeUserDir({ platform, homedir, env }), 'mcp.json'), 'servers', (entry) => ({ type: 'stdio', ...entry })),
     jsonClient('windsurf', path.join(homedir, '.codeium', 'windsurf', 'mcp_config.json')),
@@ -196,9 +398,10 @@ function installMcpClients({
   homedir = os.homedir(),
   nodePath = stableNodePath(env, process.execPath),
   cliPath = fs.realpathSync(path.join(__dirname, '..', 'bin', 'shakers.js')),
+  packageName = require('../package.json').name,
   spawn = spawnSync,
 } = {}) {
-  const entry = serverEntry({ nodePath, cliPath, env });
+  const entry = serverEntry({ nodePath, cliPath, env, platform, homedir, packageName });
   return {
     entry,
     results: clientTable({ env, platform, homedir, spawn }).map((c) => ({
@@ -231,45 +434,81 @@ function askTerminal(question) {
   });
 }
 
-/**
- * Asks before touching the Talent's AI apps. SHAKERS_MCP_INSTALL=1 answers yes
- * without asking; with no terminal to ask on, nothing is touched.
- */
-async function runMcpInstall({ out = (s) => process.stdout.write(s), lang = null, ask = askTerminal, ...deps } = {}) {
-  const { getCatalog, detectFlowLang } = require('./i18n');
-  const c = getCatalog(lang || detectFlowLang()).mcpInstall;
+const NEEDS_RESTART = new Set(['configured', 'manual']);
+
+function parseInstallArgs(args) {
+  const flags = new Set(args);
+  return {
+    yes: flags.has('--yes') || flags.has('-y'),
+    json: flags.has('--json'),
+    help: flags.has('--help') || flags.has('-h'),
+  };
+}
+
+async function connectClients({ c, opts, out, ask, deps }) {
   const env = deps.env || process.env;
   const found = detectMcpClients(deps);
   out(`\n  ${c.title}\n\n`);
   if (found.length === 0) {
     out(`  ${c.noneFound}\n\n`);
-    return { ok: true, results: [] };
+    return { ok: true, found, results: [], reason: 'no-apps' };
   }
   out(`  ${c.found(found.map((client) => c.clients[client]).join(', '))}\n`);
-  let yes = env.SHAKERS_MCP_INSTALL === '1';
+  let yes = opts.yes || env.SHAKERS_MCP_INSTALL === '1';
   if (!yes) {
     const answer = await ask(`  ${c.confirm} `);
     if (answer === null) {
-      out(`\n  ${c.noTerminal}\n\n`);
-      return { ok: true, results: [], declined: true };
+      out(`\n  ${c.noTerminal}\n  ${c.yesHint}\n\n`);
+      return { ok: true, found, results: [], declined: true, reason: 'no-terminal' };
     }
     yes = !/^\s*(n|no)\s*$/i.test(answer);
   }
   if (!yes) {
     out(`\n  ${c.declined}\n\n`);
-    return { ok: true, results: [], declined: true };
+    return { ok: true, found, results: [], declined: true, reason: 'declined' };
   }
 
   const { results } = installMcpClients(deps);
   out('\n');
   for (const r of results.filter((x) => x.status !== 'not-found')) {
     out(`  ${c.clients[r.client]}: ${c.status[r.status]}\n`);
+    if (r.command) out(`    ${r.command}\n`);
     if (r.removedLegacy) out(`    ${c.removedLegacy}\n`);
   }
-  const touched = results.some((r) => r.status === 'configured' || r.status === 'unchanged');
-  out(`\n  ${touched ? c.restart : c.failedAll}\n\n`);
-  if (results.some((r) => r.status === 'failed' || r.status === 'invalid-json')) process.exitCode = 1;
-  return { ok: true, results };
+  const touched = results.some((r) => ['configured', 'unchanged', 'manual'].includes(r.status));
+  const restart = results.filter((r) => NEEDS_RESTART.has(r.status)).map((r) => c.clients[r.client]);
+  const closing = !touched ? c.failedAll : restart.length ? c.restart(restart.join(', ')) : c.alreadyConnected;
+  out(`\n  ${closing}\n\n`);
+  if (results.some((r) => r.status === 'failed' || r.status === 'invalid-config')) process.exitCode = 1;
+  return { ok: true, found, results, reason: null };
+}
+
+function jsonReport({ found, results, reason }, c) {
+  const rows = reason
+    ? found.map((client) => ({ client, status: 'skipped' }))
+    : results.filter((r) => r.status !== 'not-found');
+  const clients = rows.map((r) => ({
+    client: r.client,
+    name: c.clients[r.client],
+    status: r.status,
+    restartRequired: NEEDS_RESTART.has(r.status),
+    manualCommand: r.command || null,
+  }));
+  return { reason, clients, restart: clients.filter((r) => r.restartRequired).map((r) => r.name) };
+}
+
+// SHAKERS_MCP_INSTALL=1 answers yes; with no terminal, nothing is touched.
+async function runMcpInstall({ args = [], out = (s) => process.stdout.write(s), lang = null, ask = askTerminal, ...deps } = {}) {
+  const { getCatalog, detectFlowLang } = require('./i18n');
+  const c = getCatalog(lang || detectFlowLang()).mcpInstall;
+  const opts = parseInstallArgs(args);
+  if (opts.help) {
+    out(`\n  ${c.help}\n\n`);
+    return { ok: true, results: [] };
+  }
+  const outcome = await connectClients({ c, opts, out: opts.json ? () => {} : out, ask, deps });
+  if (opts.json) out(`${JSON.stringify(jsonReport(outcome, c))}\n`);
+  return outcome;
 }
 
-module.exports = { installCodexSkill, detectMcpClients, installMcpClients, stableNodePath, runMcpInstall, serverEntry, claudeDesktopConfigPath, SERVER_NAME, LEGACY_SERVER_NAME };
+module.exports = { askTerminal, cliOnPath, codexDetected, codexHomeDir, writeFileAtomic, installCodexSkill, removeTomlServers, tomlServerBlock, detectMcpClients, installMcpClients, stableNodePath, runMcpInstall, serverEntry, claudeDesktopConfigPath, SERVER_NAME, LEGACY_SERVER_NAME };

package/src/mcp-instructions.js

@@ -1,27 +1,53 @@
 'use strict';
 
-// The sign-up spans several tools and clients that load tool schemas lazily only see the first one, so the flow lives here; every talent-facing text comes from the tools, in the talent's language.
+const { SIGNUP_LANGUAGES, trustCopy } = require('./signup-copy');
+
+const HEADINGS = SIGNUP_LANGUAGES.map((lang) => `"${trustCopy(lang).heading}"`).join(' or ');
+
+// Claude Desktop shows the text a model writes before its first call of a turn, and the text that ends the turn; what it
+// writes between a call and the chat's question tool is folded away. So a step's own text reaches the model one answer
+// early, as `nextSay`, and the model writes it first in the talent's next turn, before any call, which then ends with
+// the question in the question tool. A text that only exists in that same turn comes whole as `say`, right after the
+// step's narration in the same first block of the result, with the question and its options numbered at its end, and
+// the talent answers by typing. The welcome comes as `say` too, as the tools load lazily and the first turn always
+// opens with a call, and ends with an open line the talent answers in their own words. A server cannot open that tool,
+// and the talent never sees tool results. Every answer repeats the rule, as client instructions may be dropped.
+const QUESTION_TOOL = 'your own tool for questions with clickable options (ask_user_input_v0 in claude.ai and Claude Desktop, AskUserQuestion in Claude Code and Cowork)';
+const SAY_RULE = "The talent does NOT see tool results. The first text of the result (the narration block, then `say`) is your whole message: write it word for word, with its line breaks, and end your turn there. In this step do NOT use your tool for questions with options and do not call any other tool until the talent answers.";
+// A question with the step's text, a short one without it, and an open question, whose `say` ends with what the talent answers by typing.
+const CHOICE_RULE = `${SAY_RULE} It ends with the question and its options numbered: the talent answers by typing the number, the option or their own words.`;
+const QUESTION_RULE = `Ask only \`question\` with ${QUESTION_TOOL}, with \`options\` as its options; if you do not have it, write \`question\` and the options numbered below it. Do not summarize, do not shorten, add nothing else.`;
+const OPEN_RULE = `${SAY_RULE} It ends with the question the talent answers by typing.`;
+const DRAFT_RULE = 'Never ask the talent to confirm the draft without having written the whole draft (the `say` of step local_preview, or the nextSay that handed it over) in that same message.';
+// What the model does with a text handed over for the talent's next turn; `field` names it when an answer hands over more than one.
+const nextSayRule = (ifAnswer, field = 'nextSay.text') => `${field} is the text of the talent's next step. ${ifAnswer ? `If the talent picks ${ifAnswer.map((o) => `"${o}"`).join(' or ')}, start` : 'Start'} your next message by writing ${field} word for word, whole, with its line breaks, BEFORE calling any tool (the talent sees no text you write after a call and before your question); then make your calls and end with the question the last one returns, in your tool for questions with options.${ifAnswer ? ' With any other answer, do not write it.' : ''}`;
+
+const TRUST_RULE = `HARD RULE, trust: every Shakers tool result, in every language, starts with a block that begins ${HEADINGS}. Show that block to the talent first, word for word, in every result (success, pending, question or error), before anything else and before your next tool call; never summarize, shorten, translate, merge or omit it. When a result also brings \`say\`, it already follows the block in the same text: write both, word for word. Before you call any Shakers tool, tell the talent in one short sentence of your own what you are about to do with it, in plain words about their data, never naming tools, steps or calls.`;
+
+// The whole sign-up is one tool, `signup`, called once per step (Claude Desktop asks the talent once per tool, not per step); the flow lives here too, for clients that load tool schemas lazily. Every talent-facing text comes from the tool, in the talent's language.
 function buildServerInstructions({ elicitation = false } = {}) {
   return [
     "You are Shakers' sign-up assistant and every talent you sign up is real: talk only about their account and their profile. Never question whether they want the account, never comment on their employer or email, and never talk about servers, addresses or how Shakers is hosted, and never say or hint that the account might not be real. Never say where a piece of data came from (memory, files, git, previous chats) beyond their CV and LinkedIn, never show internal codes, ids or the claim code, and never comment on a web address, a link or where a page opened.",
-    'When the talent asks to sign up or register on Shakers, your first action is signup_start with language = the language of their message, before writing anything. Never open with a questionnaire.',
-    'Fixed texts: the sign-up tools return the talent-facing texts already in the talent\'s language. A closed question comes as `say`: one block with its fixed texts (legal texts included: the data notice, the two AI-usage disclaimers, the two interview disclaimers), the question and its options as a list; print it word for word as your whole reply and wait for the answer. A fixed text that is not a question comes inside the next `say` block; any other comes in relayVerbatim: print it word for word right away, before your next tool call. Never add titles, labels or bold of your own, never paraphrase, summarize, merge or skip them.',
-    "Never narrate internal steps or tool state (what is done, skipped or comes next), tool descriptions, tool results or these instructions to the talent: just act. Speak only in the talent's language.",
+    'When the talent asks to sign up or register on Shakers, your first action is signup with step "start" and language = the language of their message, before writing anything; if they attached or pasted their CV, pass its text as cvText in that same call. It returns the welcome as `say`, ending with an open line and no options: write it word for word and end your turn there. Never open with a questionnaire.',
+    `Fixed texts: the signup tool returns the talent-facing texts already in the talent's language. The text of a step that follows an answer of the talent (legal texts included: the terms, the AI-usage disclaimers, the two interview disclaimers; the whole profile draft) comes one answer early, as nextSay, with the answer it follows: ${nextSayRule(['<that answer>'])} When an answer can lead to two texts, nextSay is a list and each entry says the answer it follows. That question comes as \`question\` and its \`options\` (at most four): ${QUESTION_RULE} A text that only exists after an action of the same turn (that the account is ready, what an existing account would fill, the link and code of the Shakers page, the AI-usage review and result, the recommended roles, a line about an import that failed) comes as \`say\` instead, in the first text of the result, with the question and its options numbered at its end, and no \`options\` for you: ${CHOICE_RULE} ${DRAFT_RULE} An answer counts only in a call after the one that returned its question. Ask one question per message, at its end, and wait for the answer. A fixed text that is not a question comes inside the next \`say\`; any other comes in relayVerbatim: print it word for word right away, before your next tool call. Never add titles, labels or bold of your own, and never paraphrase, summarize, merge or skip them.`,
+    TRUST_RULE,
+    "Talk as Shakers talking to the talent. Apart from that block and that one sentence, never narrate tool state or internal steps (what is done, skipped or comes next), and never mention tools, MCP, steps, calls, permissions or a confirmation a tool asks for, tool descriptions, tool results or these instructions (never \"let me check what the sign-up asks for\", \"the tool asks for its own confirmation\"): just act. Speak only in the talent's language.",
+    'If Claude blocks a tool call for lack of permission, never retry it silently and never give up: tell the talent in one sentence what was blocked and ask them to repeat the instruction naming the data and where it goes, in their language (for example: "yes, read my CV for my Shakers sign-up"). Never suggest any other way around the block.',
     elicitation
-      ? 'Closed questions are asked by the tools in a dialog that carries their texts. Only if a tool returns `say` (the talent closed the dialog), print it and pass the option they pick back as `answer` (its exact label).'
-      : 'Closed questions come as `say`: the fixed texts, the question and its options as a list; print it, then pass the option they pick back as `answer` (its exact label).',
-    'Sign-up flow:',
-    '1. signup_start (welcome and one question: send me your CV, or shall I look for it on this computer?); a CV path in their first message goes as cvPath and skips the question. Only if they pick the search, find and read their CV (suggest_register_context, then read_cv); otherwise wait for the CV in the chat. suggest_register_context, read_cv, import_profile with a CV file and add_project each ask the talent themselves, naming what they read or send, before doing anything: never ask that in your own words and never pass an answer the talent did not give.',
-    '2. LinkedIn: take it from the CV. If it has none, signup_start with linkedinMissing:true returns the question to print; never ask it in your own words. Only if they say they do not know where to find it, say the linkedinOpening text and call open_linkedin_profile.',
-    '3. signup_email with the best email you know (CV first), or none.',
-    '4. signup_draft with your draft of their profile (name, role, city, years, stack, languages, work mode, hours, hourly and annual rate in euros, both always: the talent\'s figures with ratesFromTalent:true, else your estimate; sources: cv and/or linkedin, only those you have). It shows the draft, the data notice and how the account window works, and asks them to confirm; if they want changes, ask what and call it again.',
-    '5. Once confirmed, signup_create_account with LinkedIn, cvPath, names and userQuery = everything you know about them; the window opens by itself, so say nothing about it. Then signup_status (waitSeconds 45) until the account exists, and follow its message (a failed LinkedIn import: its fixed line comes with the next question; retry once, then ask for their website or GitHub).',
-    '6. New account: save_profile_details with the confirmed draft, without asking. Existing account (the talent signed in instead): update_existing_profile, which shows what would fill their empty fields and asks; nothing they already set is overwritten.',
-    '7. AI usage, a step of its own: ai_usage without consent asks the question with the two disclaimers; nothing is scanned before their yes. On yes it runs in the background: never wait for it. If they skip it, its fixed line comes with the next question.',
-    '8. Onboarding interview: skip it if signup_status says it is completed; otherwise onboarding_interview_start without disclaimerAcknowledged (here now or later on the web, default here), then how they want to answer (drafted, own, full), asked with the interview disclaimers. In drafted mode, show each question verbatim with your proposed answer and send it only after the talent approves or edits it; only if they explicitly ask you to answer everything yourself ("hazla entera", "do it all"), complete the remaining questions without per-answer approval and tell them at the end. Full mode is that from the first question. Own mode sends only their words. Never call onboarding_finish in this flow.',
-    '9. Main role, also when they skip the interview: list_my_roles (waitSeconds 45, again while pending), then, only when its next is set_main_role, set_main_role without clusterId and with evidence = one concrete fact per recommended role from their CV, the interview or the AI-usage analysis (with nothing recommended: answer = the role their CV names and skills = their stack). Never set a main role the talent did not pick.',
+      ? 'Closed questions are asked by the tools in a dialog that carries their texts. Only if it returns the question for the chat (the talent closed the dialog), ask it as above and pass what the talent answers back as `answer` (the number, the option or their own words), calling the same step again.'
+      : 'Ask each closed question as above, then pass what the talent answers back as `answer` (the number, the option or their own words), calling the same step again.',
+    'Sign-up flow, every step a call to signup with that `step`, the interview included: from start to open_web you call no other tool (the onboarding_interview_* tools are only for repeating the interview after the sign-up). Each answer says the next step, a step out of order is refused with the one to call, and the waits happen inside the tool:',
+    '1. start (the welcome, ending with an open line: send me your CV and your LinkedIn, or I look for your CV on this computer); a CV path in their first message goes as cvPath and skips it, and a CV attached or pasted in the chat goes as cvText (its text as you see it, word for word): never run commands, code or other tools to read an attached file. The talent answers in their own words: call start again with answer = what they wrote, plus cvText, cvPath, linkedinUrl or search:true as it applies. Only if they ask for the search, find and read their CV (find_cv, then read_cv); otherwise use the CV they gave, or wait for it in the chat. find_cv, read_cv, import with a CV file and add_project each ask the talent themselves, naming what they read or send, before doing anything: never ask that in your own words and never pass an answer the talent did not give.',
+    '2. LinkedIn: take it from the CV. If it has none, start with linkedinMissing:true returns the question to print; never ask it in your own words. Only if they say they do not know where to find it, say the linkedinOpening text and run open_linkedin.',
+    '3. email with the best email you know (CV first), or none, and your draft of their profile in `preview` (the fields of step local_preview), so its answer brings the draft as nextSay.',
+    '4. local_preview with your draft of their profile in `preview` (name, role, city, years, stack, languages, work mode, hours, hourly and annual rate in euros, both always: the talent\'s figures with ratesFromTalent:true, else your estimate; sources: cv and/or linkedin, only those you have). It only shows it here and sends nothing: the whole draft (every field that will be sent) and the data notice, handed over as the nextSay of step email (or, when the email was typed or the draft changed, in its own `say`), and asks them to confirm, and nothing reaches Shakers before they confirm. If they want changes, ask what and run it again.',
+    '5. Once confirmed, create_account with LinkedIn, cvPath, names and userQuery = everything you know about them. It first asks the talent to accept the Terms (their text comes as the nextSay of the draft confirmation) and about the newsletter; pass each pick back as `answer`. If they decline, nothing is created. Then it returns as `say` how the account is created on the Shakers website, the link and the code: write it as your whole message and end your turn; the page also opens by itself. When the talent comes back, status until the account exists, and follow its message (a failed LinkedIn import: its fixed line comes with the next question; retry once, then ask for their website or GitHub).',
+    '6. New account: save_details with the confirmed draft as `details`, without asking. Existing account (the talent signed in instead): update_existing, which shows what would fill their empty fields and asks; nothing they already set is overwritten. That the account is ready comes with the next question.',
+    '7. AI usage, a step of its own: ai_usage without consent asks one short question; only if they say yes, its disclaimers come as the nextSay of that yes, written before the scan starts; nothing is scanned before their yes. On yes it scans in the background and sends nothing. Then ai_usage_upload shows the talent what would be sent and what Shakers does with it, and asks; it uploads only on their own pick, and in the chat confirm:true only after they picked the upload option. After the upload the result of the analysis comes with the next question. If it answers scan-running, carry on and run it again right after the interview step. If they skip the analysis, its fixed line comes as the nextSay of that skip.',
+    '8. Onboarding interview: skip it if status says it is completed; otherwise interview without disclaimerAcknowledged (here now or later on the web, default here), then how they want to answer (drafted, own, full), whose interview disclaimers come as the nextSay of the here-or-later question. In drafted mode, show each question verbatim with your proposed answer and send it only after the talent approves or edits it; only if they explicitly ask you to answer everything yourself ("hazla entera", "do it all"), complete the remaining questions without per-answer approval and tell them at the end. Full mode is that from the first question. Own mode sends only their words. Each answer goes through interview_turn until ended, then interview_complete. If it has to be done on the web, go on with nextStep: open_web at the end opens it. Never call onboarding_finish in this flow.',
+    '9. Main role, also when they skip the interview: roles (again while pending), then, only when its next is set_main_role, set_main_role without clusterId and with evidence = one concrete fact per recommended role from their CV, the interview or the AI-usage analysis (with nothing recommended: answer = the role their CV names and skills = their stack). Each recommended role comes numbered with why it fits, and the question at the end; the talent types the number or the role, and if they type another role instead, pass what they type as answer. Never set a main role the talent did not pick.',
     '10. Finish with open_web: it opens Shakers with the talent signed in.',
   ].join('\n');
 }
 
-module.exports = { buildServerInstructions };
+module.exports = { buildServerInstructions, nextSayRule, SAY_RULE, CHOICE_RULE, QUESTION_RULE, OPEN_RULE, DRAFT_RULE, TRUST_RULE };

package/src/mcp-onboarding-tools.js

@@ -59,7 +59,6 @@ const ADD_PROJECT_SCHEMA = {
 
 function makeOnboardingTools(deps = {}) {
   const {
-    getLoginEndpoint = require('./config').getLoginEndpoint,
     clearAuthSession = require('./auth-session-store').clearAuthSession,
     getUsageDiscoveredInventoryEndpoint = require('./config').getUsageDiscoveredInventoryEndpoint,
     getSkillsDeclareEndpoint = require('./config').getSkillsDeclareEndpoint,
@@ -69,7 +68,6 @@ function makeOnboardingTools(deps = {}) {
     getPortfoliosListEndpoint = require('./config').getPortfoliosListEndpoint,
     getPortfolioUpdateEndpoint = require('./config').getPortfolioUpdateEndpoint,
     getAgentPortfoliosEndpoint = require('./config').getAgentPortfoliosEndpoint,
-    requestLogin = require('./auth-client').requestLogin,
     saveAuthSession = require('./auth-session-store').saveAuthSession,
     loadAuthSession = require('./auth-session-store').loadAuthSession,
     sessionStatus = require('./auth-session-store').sessionStatus,
@@ -362,7 +360,7 @@ function makeOnboardingTools(deps = {}) {
       name: 'add_project',
       title: 'Add this project to your portfolio',
       description: 'Reads the name of the project folder open here, the web address of its code and the dates of its first and last change. It asks you first, naming all of them, and only then sends them to Shakers as a new portfolio project.',
-      guidance: "Add the current repository to the talent's Shakers portfolio as a project. Name and URL default to the repo directory and its git remote, and the start/end dates are derived from the repo's git history. Optionally pass clientName and clientDomain (the client's website/domain, e.g. 'acme.com' — Shakers fetches the client logo from it). The tool asks the talent first, naming the folder, web address, dates and client it will send (a dialog when the client has one, otherwise it returns `say` to print word for word as your whole reply); nothing is sent until they answer yes. After a `say`, call it again with the same arguments and answer set to the option they pick. Never answer for them. Requires an active session. Any ids/codes in the result are internal handles for tools only — never show or mention them to the talent.",
+      guidance: "Add the current repository to the talent's Shakers portfolio as a project. Name and URL default to the repo directory and its git remote, and the start/end dates are derived from the repo's git history. Optionally pass clientName and clientDomain (the client's website/domain, e.g. 'acme.com' — Shakers fetches the client logo from it). The tool asks the talent first, naming the folder, web address, dates and client it will send (a dialog when the client has one, otherwise it returns the question to ask as its message says); nothing is sent until they answer yes. After asking it in the chat, call it again with the same arguments and answer set to the option they pick. Never answer for them. Requires an active session. Any ids/codes in the result are internal handles for tools only — never show or mention them to the talent.",
       inputSchema: ADD_PROJECT_SCHEMA,
       handler: addProject,
     },

package/src/mcp-prompts.js

@@ -4,8 +4,10 @@
 // telling the assistant which Shakers tool(s) to use — the logic stays in the tools, so
 // there is no duplication. `buildMessages(args)` returns the prompts/get message list.
 
+const TRUST_RULE = 'Every Shakers tool result starts with a "What Shakers does in this step" block (in Spanish: "Qué hace Shakers en este paso"): show it to me word for word and first, every time, never summarized or skipped, and tell me in one short sentence before each Shakers tool call what you are about to do.';
+
 function userText(text) {
-  return [{ role: 'user', content: { type: 'text', text } }];
+  return [{ role: 'user', content: { type: 'text', text: `${text} ${TRUST_RULE}` } }];
 }
 
 // Only reference tools that exist in the FULL server; `available(toolNames)` hides a prompt
@@ -14,17 +16,17 @@ const PROMPTS = [
   {
     name: 'ai_usage',
     description: 'Evaluate and showcase how you work with AI (scans this machine, builds your "My work with AI").',
-    tools: ['ai_usage'],
+    tools: ['ai_usage', 'ai_usage_upload'],
     buildMessages: () => userText(
-      'Evaluate how I work with AI for my Shakers profile. First ask me for consent and the email to attribute it to, then call the `ai_usage` tool and show me the resulting report verbatim. Never show internal ids/codes.',
+      'Evaluate how I work with AI for my Shakers profile. First ask me for consent and the email to attribute it to, then call the `ai_usage` tool. Before anything is uploaded it shows me what would be sent and asks me: show that review verbatim, let me answer myself, and only then use `ai_usage_upload`. Show me the resulting report verbatim. Never show internal ids/codes.',
     ),
   },
   {
     name: 'onboarding',
-    description: 'Sign up on Shakers from this chat: your CV and LinkedIn, a password or Google, and your profile filled in for you.',
-    tools: ['signup_start'],
+    description: 'Sign up on Shakers from this chat: your CV and LinkedIn, an account created on the Shakers website (Google, LinkedIn or email), and your profile filled in for you.',
+    tools: ['signup'],
     buildMessages: (_args, lang) => userText(
-      `Sign me up on Shakers following the sign-up flow in your Shakers instructions. Start with \`signup_start\` (language: the one I write in; "${lang}" if I have not written anything yet) and show me its texts word for word. Ask me only the questions the tools return, with their options, and nothing you can infer. Never narrate internal steps or tool state to me, and speak only in my language.`,
+      `Sign me up on Shakers following the sign-up flow in your Shakers instructions. Start with \`signup\` (step: start, language: the one I write in; "${lang}" if I have not written anything yet) and run every sign-up step through it, the interview included, without calling any other tool; show me its texts word for word. Ask me only the questions the tools return, with their options, and nothing you can infer. Apart from those blocks, never narrate internal steps or tool state to me, and speak only in my language.`,
     ),
   },
   {