shakers-cli-beta 0.12.0 → 0.14.0

package/src/mcp-auth-form.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const http = require('http');
+const crypto = require('crypto');
 const { openPath } = require('./open-file');
 const flow = require('./onboarding-flow');
 const { methodIdsForFlow } = require('./auth-methods');
@@ -184,7 +185,7 @@ function loginFormHtml(lang, { error } = {}) {
   const c = copy(lang);
   return page(`Shakers · ${c.signin}`, {
     inner: `<h1>${c.signin}</h1>${errorBanner(errorText(c, error))}`
-      + `<form method="post" action="/submit">`
+      + `<form method="post" action="submit">`
       + `<label>${c.email}</label><input name="email" type="email" required autofocus>`
       + `<label>${c.password}</label><input name="password" type="password" required>`
       + `<button type="submit">${c.signin}</button>`
@@ -205,7 +206,7 @@ function registerFormHtml(lang, { error, missing } = {}) {
   return page(`Shakers · ${c.create}`, {
     banner: panel(c.welcome),
     inner: `<h1>${c.create}</h1>${errorBanner(errorText(c, error))}`
-      + `<form method="post" action="/submit">`
+      + `<form method="post" action="submit">`
       + missingIdentityInputs(c, missing).replace('required', 'required autofocus')
       + `<label>${c.password}</label><input name="password" type="password" required minlength="8"${missing && (missing.email || missing.name || missing.lastName) ? '' : ' autofocus'}>`
       + `<label>${c.repeat}</label><input name="passwordConfirm" type="password" required minlength="8">`
@@ -250,9 +251,9 @@ function methodChoiceHtml(mode, lang, methods) {
   const emailLabel = mode === 'register' ? c.continueEmailRegister : c.continueEmail;
   const register = mode === 'register';
   const buttons = WINDOW_METHODS[mode].filter((id) => methods.includes(id)).map((id) => {
-    if (id === 'google') return `<a class="mbtn primary" href="/google${register ? '?legal=1' : ''}">${GOOGLE_G}${c.continueGoogle}</a>`;
-    if (id === 'linkedin') return `<a class="mbtn secondary" href="/linkedin">${LINKEDIN_IN}${c.continueLinkedin}</a>`;
-    return `<a class="mbtn secondary" href="/email">${emailLabel}</a>`;
+    if (id === 'google') return `<a class="mbtn primary" href="google${register ? '?legal=1' : ''}">${GOOGLE_G}${c.continueGoogle}</a>`;
+    if (id === 'linkedin') return `<a class="mbtn secondary" href="linkedin">${LINKEDIN_IN}${c.continueLinkedin}</a>`;
+    return `<a class="mbtn secondary" href="email">${emailLabel}</a>`;
   }).join('');
   return page(`Shakers · ${title}`, {
     inner: `<h1>${title}</h1><div class="actions">${buttons}</div><p class="hint">${c.hint}</p>${register ? legalHtml(lang) : ''}`,
@@ -264,12 +265,12 @@ function existingAccountHtml(lang, { email, error } = {}) {
   const c = copy(lang);
   return page(`Shakers · ${c.signin}`, {
     inner: `<h1>${c.signin}</h1>${errorBanner(error ? errorText(c, error) : c.existing)}`
-      + `<form method="post" action="/submit"><input type="hidden" name="intent" value="login">`
+      + `<form method="post" action="submit"><input type="hidden" name="intent" value="login">`
       + `<label>${c.email}</label><input name="email" type="email" required value="${esc(email || '')}">`
       + `<label>${c.password}</label><input name="password" type="password" required autofocus>`
       + `<button type="submit">${c.signin}</button>`
       + `</form>`
-      + `<div class="actions"><a class="mbtn secondary" href="/google?legal=1">${GOOGLE_G}${c.continueGoogle}</a></div>`
+      + `<div class="actions"><a class="mbtn secondary" href="google?legal=1">${GOOGLE_G}${c.continueGoogle}</a></div>`
       + `<p class="hint">${c.hint}</p>`,
   });
 }
@@ -371,7 +372,25 @@ function runLoopbackAuth(
       resolve(result);
     };
 
+    // Any page in the talent's browser can reach a loopback port, and a rebound DNS name can read it: only this
+    // window's own host, its own origin and its unguessable path get an answer. Every link in the pages is relative.
+    const secretPath = `/${crypto.randomBytes(32).toString('base64url')}`;
+    let port = null;
+    const ownHosts = () => [`127.0.0.1:${port}`, `localhost:${port}`];
+    const forbidden = (req) => {
+      if (!ownHosts().includes(String(req.headers.host || '').toLowerCase())) return true;
+      if (req.method === 'GET') return false;
+      const origin = req.headers.origin;
+      if (origin !== undefined && !ownHosts().map((h) => `http://${h}`).includes(origin)) return true;
+      const site = req.headers['sec-fetch-site'];
+      return site !== undefined && site !== 'same-origin';
+    };
+
     const server = http.createServer(async (req, res) => {
+      if (forbidden(req)) {
+        res.writeHead(403).end();
+        return;
+      }
       let url;
       try {
         url = new URL(req.url, 'http://127.0.0.1');
@@ -379,7 +398,17 @@ function runLoopbackAuth(
         res.writeHead(400).end();
         return;
       }
-      if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+      if (url.pathname === secretPath) {
+        res.writeHead(302, { Location: `${secretPath}/${url.search}` });
+        res.end();
+        return;
+      }
+      if (!url.pathname.startsWith(`${secretPath}/`)) {
+        res.writeHead(404).end();
+        return;
+      }
+      url.pathname = url.pathname.slice(secretPath.length);
+      if (req.method === 'GET' && url.pathname === '/') {
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
         res.end(showMethodScreen ? methodChoiceHtml(mode, lang, methods) : formHtml(mode, lang, formOpts));
         return;
@@ -440,8 +469,8 @@ function runLoopbackAuth(
     if (timer.unref) timer.unref();
     server.on('error', () => finish({ ok: false, reason: 'local-error' }));
     server.listen(0, '127.0.0.1', () => {
-      const { port } = server.address();
-      const formUrl = `http://127.0.0.1:${port}/`;
+      ({ port } = server.address());
+      const formUrl = `http://127.0.0.1:${port}${secretPath}/`;
       if (typeof onUrl === 'function') onUrl(formUrl);
       try { openBrowser(formUrl); } catch { /* headless: the onUrl fallback covers it */ }
     });

package/src/mcp-availability-tools.js

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

package/src/mcp-certifications-tools.js

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

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

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

package/src/mcp-choice.js

@@ -2,7 +2,7 @@
 
 // Closed questions of the MCP sign-up: a dialog when the client can elicit, otherwise one block the model prints, question last.
 
-const SAY_MESSAGE = 'Print `say` word for word as your whole reply: it already holds the texts, the question and its numbered options. Add nothing of your own and call no tool until the talent answers.';
+const SAY_MESSAGE = 'Print `say` word for word as your whole reply: it already holds the texts, the question and its options as a list. Present them as a choice and pass back the exact label the talent picks, never a number; add nothing of your own and call no tool until the talent answers.';
 
 // Fixed texts that are not a question ride on the next question block: a model skips a standalone relay.
 const notices = [];
@@ -17,14 +17,14 @@ function takeNotices() {
 
 // Fixed texts travel with their question, so a model that skips "show this first" still shows them.
 function sayBlock(texts, question, options) {
-  return [...texts, question, options.map((o, i) => `${i + 1}. ${o}`).join('\n')].join('\n\n');
+  return [...texts, question, options.map((o) => `- ${o}`).join('\n')].join('\n\n');
 }
 
 function chatChoice(question, options, texts = []) {
   return { say: sayBlock([...takeNotices(), ...texts], question, options), options, choiceMessage: SAY_MESSAGE };
 }
 
-// The option an answer names, by its text or by its number in the printed list.
+// The option an answer names: by its label, or by a position number if the talent still types one.
 function optionFor(answer, options) {
   if (typeof answer !== 'string') return null;
   const text = answer.trim();
@@ -66,4 +66,30 @@ async function askAfterTexts(ctx, { tool, texts, question, options, answer }) {
   };
 }
 
-module.exports = { askChoice, askAfterTexts, chatChoice, optionFor, queueNotice, takeNotices, SAY_MESSAGE };
+// Questions this process put to the talent in the chat, keyed by exactly what they would allow:
+// an answer counts only for a question the tool asked, so a flag the AI sets by itself never does.
+const pendingConsent = new Set();
+
+// The talent's yes or no before a tool reads this computer or sends data: { granted } or { reply } to return.
+async function askConsent(ctx, { tool, key, question, yes, no, answer }) {
+  const options = [yes, no];
+  const picked = pendingConsent.has(key) ? optionFor(answer, options) : null;
+  if (picked) {
+    pendingConsent.delete(key);
+    return { granted: picked === yes };
+  }
+  const asked = ctx && ctx.elicitation ? await askChoice(ctx, { question, options }) : { chat: chatChoice(question, options) };
+  if (asked.answer) return { granted: asked.answer === yes };
+  pendingConsent.add(key);
+  return {
+    reply: {
+      ok: false,
+      reason: 'consent-required',
+      ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
+      ...asked.chat,
+      message: `Nothing was read or sent. ${asked.chat.choiceMessage} Then call ${tool} again with the same arguments and answer set to the option they pick.`,
+    },
+  };
+}
+
+module.exports = { askConsent, askChoice, askAfterTexts, chatChoice, optionFor, queueNotice, takeNotices, SAY_MESSAGE };

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

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

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

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

package/src/mcp-instructions.js

@@ -5,14 +5,14 @@ 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 numbered options; 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 tool descriptions, tool results or these instructions to the talent: just act.',
+    '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.",
     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` (the number or the text).'
-      : 'Closed questions come as `say` with their numbered options: print it, then pass the option they pick back as `answer` (the number or the text).',
+      ? '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: may I look for your CV here?); a CV path in their first message goes as cvPath and skips the question. If yes, find and read their CV (suggest_register_context, read_cv) without asking again; otherwise wait for the CV in the chat.',
-    '2. LinkedIn: take it from the CV. If it has none, ask the linkedinAsk text. Only if they say they do not know where to find it, say the linkedinOpening text and call open_linkedin_profile.',
+    '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 20) 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).',

package/src/mcp-invitations-tools.js

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

package/src/mcp-lang-tools.js

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

package/src/mcp-onboarding-tools.js

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

package/src/mcp-portfolios-tools.js

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

package/src/mcp-profile-tools.js

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

package/src/mcp-prompts.js

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