shakers-cli-beta 0.8.0-beta.2 → 0.8.0-beta.3

package/bin/mcp.js

@@ -42,7 +42,7 @@ const HELP = `\n  shakers mcp — local MCP server (stdio)\n\n`
   + `  MCP client, not run by hand.\n`
   + `  Tools: ai_usage, ai_usage_result, login, logout, social_signin_start, social_signin_poll,\n`
   + `         list_addable, add_skill, add_agent,\n`
-  + `         add_project, register, register_status, onboarding_interview_start,\n`
+  + `         add_project, suggest_register_context, read_cv, register_preview, register, register_status, onboarding_interview_start,\n`
   + `         onboarding_interview_turn, onboarding_interview_complete,\n`
   + `         repeat_onboarding_interview, onboarding_finish,\n`
   + `         list_available_roles, add_role, list_my_roles, set_main_role,\n`

package/package.json

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

package/src/backend-request.js

@@ -105,6 +105,14 @@ function postMultipartWithTimeout(url, fields, timeoutMs, method = 'POST', extra
     const chunks = [];
     for (const [name, value] of Object.entries(fields || {})) {
       if (value === undefined || value === null) continue;
+      // A file part: { filename, contentType, data: Buffer }.
+      if (typeof value === 'object' && Buffer.isBuffer(value.data)) {
+        const filename = String(value.filename || 'file').replace(/["\r\n\0]/g, '');
+        const contentType = String(value.contentType || 'application/octet-stream').replace(UNSAFE_HEADER_VALUE_RE, '');
+        chunks.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"; filename="${filename}"\r\nContent-Type: ${contentType}\r\n\r\n`));
+        chunks.push(value.data, Buffer.from('\r\n'));
+        continue;
+      }
       const clean = String(value).replace(UNSAFE_HEADER_VALUE_RE, '');
       chunks.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${clean}\r\n`));
     }

package/src/cv-text.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Plain text out of the talent's CV PDF, so the AI can pre-fill from what the CV
+// says. Zero-dependency on purpose (install.sh copies the CLI without npm
+// install): macOS reads it with the system PDFKit through JXA, elsewhere with
+// poppler's pdftotext when it is installed. With neither, the caller asks the
+// talent to attach the CV to the chat instead.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { expandHome } = require('./env-paths');
+
+const MAX_BYTES = 10 * 1024 * 1024;
+const MAX_CHARS = 20000;
+
+const JXA_PDF_TEXT = 'function run(argv){ObjC.import("PDFKit");'
+  + 'const d=$.PDFDocument.alloc.initWithURL($.NSURL.fileURLWithPath(argv[0]));'
+  + 'return d.isNil()?"":d.string.js}';
+
+function run(cmd, args, exec) {
+  return String(exec(cmd, args, { encoding: 'utf8', timeout: 20000, maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }) || '');
+}
+
+function extractors(platform) {
+  const list = [];
+  if (platform === 'darwin') list.push({ name: 'pdfkit', cmd: 'osascript', args: (file) => ['-l', 'JavaScript', '-e', JXA_PDF_TEXT, file] });
+  list.push({ name: 'pdftotext', cmd: 'pdftotext', args: (file) => ['-layout', '-q', file, '-'] });
+  return list;
+}
+
+function readCvText(input, { platform = process.platform, exec = execFileSync, env = process.env } = {}) {
+  const file = expandHome(input, env);
+  if (typeof file !== 'string' || !path.isAbsolute(file) || !/\.pdf$/i.test(file)) return { ok: false, reason: 'not-a-pdf-path' };
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    return { ok: false, reason: 'not-found' };
+  }
+  if (!stat.isFile()) return { ok: false, reason: 'not-found' };
+  if (stat.size > MAX_BYTES) return { ok: false, reason: 'too-large' };
+
+  for (const extractor of extractors(platform)) {
+    let text;
+    try {
+      text = run(extractor.cmd, extractor.args(file), exec).trim();
+    } catch {
+      continue;
+    }
+    if (!text) continue;
+    return { ok: true, extractor: extractor.name, truncated: text.length > MAX_CHARS, text: text.slice(0, MAX_CHARS) };
+  }
+  return { ok: false, reason: 'no-text-extracted' };
+}
+
+module.exports = { readCvText, MAX_CHARS };

package/src/env-paths.js

@@ -13,4 +13,18 @@ function getHomeDir(env = process.env) {
   return readEnv(env, 'HOME_DIR') || os.homedir();
 }
 
-module.exports = { getHomeDir, readEnv };
+// `~/Documents/cv.pdf` -> absolute, so a model can pass the short form it was shown.
+function expandHome(file, env = process.env) {
+  if (typeof file !== 'string') return file;
+  if (file === '~') return getHomeDir(env);
+  if (file.startsWith('~/')) return require('path').join(getHomeDir(env), file.slice(2));
+  return file;
+}
+
+// The short `~/...` form of a path under home, for showing (and copying) without typos.
+function tildify(file, env = process.env) {
+  const home = getHomeDir(env);
+  return typeof file === 'string' && file.startsWith(`${home}/`) ? `~/${file.slice(home.length + 1)}` : file;
+}
+
+module.exports = { getHomeDir, readEnv, expandHome, tildify };

package/src/mcp-register-tools.js

@@ -81,14 +81,22 @@ function buildSchemas(lang) {
     required: ['name', 'lastName', 'email', 'freelanceType', 'profile', 'workSituation', 'pricing'],
   };
 
-  return { ACCOUNT_FIELDS, WORK_SITUATION_SCHEMA, LANGUAGES_SCHEMA, AVAILABILITY_SCHEMA, REGISTER_SCHEMA };
+  // Same shape as REGISTER_SCHEMA but NOTHING is required: the preview accepts a
+  // partial, pre-filled payload and reports what is still missing.
+  const PREVIEW_SCHEMA = {
+    type: 'object',
+    description: 'A partial, pre-filled register payload to REVIEW before writing. Every field is optional — fill only what the talent has said or what is verifiable from context, omit the rest. Returns what WOULD be written, what is still missing to ask, and any invalid values. Writes nothing.',
+    properties: { ...REGISTER_SCHEMA.properties },
+  };
+
+  return { ACCOUNT_FIELDS, WORK_SITUATION_SCHEMA, LANGUAGES_SCHEMA, AVAILABILITY_SCHEMA, REGISTER_SCHEMA, PREVIEW_SCHEMA };
 }
 
 // The register tool's own long description, per language: the batched
 // collection guide with friendly labels inline for every choice field.
 function buildRegisterDescription(lang) {
   const L = getCatalog(lang).onboarding;
-  return "The talent registers THEMSELVES on Shakers (self-service; no prior session needed). Your job is to relay the non-secret profile details the talent gives you in the chat as arguments. Credentials never touch the chat or any tool argument: the tool opens a sign-up window on the talent's own machine (127.0.0.1) where they either Continue with Google (no password at all) or type an email and password directly into that local window.\n\nCOLLECT THE DETAILS IN A FEW GROUPED BATCHES, not one field at a time, and for every CHOICE field PRESENT THE VALID OPTIONS so the talent just picks one. For every choice field SHOW THE TALENT THE FRIENDLY LABEL, never the raw code (e.g. show 'Nativo', not 'NATIVE'), and pass the code as the value. Suggested batches:\n1. Identity — name, lastName, email (optional: preferredLanguage, newsletterConsent).\n2. Profile — `profile.linkedinUrl` (required source; optional GitHub/website/CV path).\n3. Work — freelanceType (offer: "
+  return "The talent registers THEMSELVES on Shakers (self-service; no prior session needed). Your job is to relay the non-secret profile details the talent gives you in the chat as arguments. Credentials never touch the chat or any tool argument: the tool opens a sign-up window on the talent's own machine (127.0.0.1) where they either Continue with Google (no password at all) or type an email and password directly into that local window.\n\nSAVE THE TALENT TYPING: first call suggest_register_context (timezone, local git identity, GitHub login, CV files) and PROPOSE those values for them to confirm; then call register_preview with the partial payload to get a review (what would be written, what is still missing) and show the talent a short summary to confirm or correct BEFORE calling register. Pre-fill EVERY field you can reasonably infer from what you know about the talent (your memory of past conversations, the chat, context) — including `pricing` and `workSituation.changeMotivators`. PRICING: whenever you know anything about their role, seniority, stack or location, ALWAYS propose a concrete per-project amount yourself (full-time and/or part-time, in their currency), labelled as your estimate — do not hand the question back to the talent; only ask for it when you know nothing at all about their work. MOTIVATORS: pick the one that best matches what they have told you. What you know about the person outranks suggest_register_context: if the git identity does not match the person you know, ignore it. For each inferred value briefly say where it comes from. Ask ONLY for what you genuinely have no basis for. Use suggest_register_context's githubUrl and cvCandidates to propose profile.githubUrl and profile.cvPath (cvCandidates often include OTHER people's CVs, e.g. candidates they downloaded: propose a CV ONLY if its file name matches the talent's name — nameMatch:true or a name you know — and never one named after someone else; if none matches but there is a generic:true one like cv.pdf, ASK the talent whether it is theirs and whether you may read it and send it with the registration; otherwise ask for the path). Once the talent confirms a CV and allows it, ALWAYS call read_cv BEFORE register_preview and use its text to pre-fill or correct the other fields (languages and levels, experience, location); if the CV adds or changes any value, show the talent just those changes and get their OK before calling register; pass paths exactly as given, the short ~/ form is fine. For optional fields you have no basis for (phone, website, newsletter), do not ask one by one: add a single closing line offering them (e.g. '¿Quieres añadir teléfono o web?'). The goal is that the talent only has to answer 'sí' or correct a value. Never write without the talent's confirmation of the summary. All of this is self-declared profile data.\n\nCOLLECT THE DETAILS IN A FEW GROUPED BATCHES, not one field at a time, and for every CHOICE field PRESENT THE VALID OPTIONS so the talent just picks one. For every choice field SHOW THE TALENT THE FRIENDLY LABEL, never the raw code (e.g. show 'Nativo', not 'NATIVE'), and pass the code as the value. Suggested batches:\n1. Identity — name, lastName, email (optional: preferredLanguage, newsletterConsent).\n2. Profile — `profile.linkedinUrl` (required source; optional GitHub/website/CV path).\n3. Work — freelanceType (offer: "
     + labelledOptions(FREELANCE_TYPES, L.freelanceTypeLabels)
     + ") and `workSituation` (offer situation: "
     + labelledOptions(WORK_SITUATIONS, L.workSituationLabels)
@@ -121,7 +129,7 @@ const PROFILE_SCHEMA = {
   type: 'object',
   properties: {
     linkedinUrl: { type: 'string', description: "The talent's LinkedIn URL. Required — it is the mandatory profile source." },
-    cvPath: { type: 'string', description: 'Absolute path to a CV PDF on the machine (optional).' },
+    cvPath: { type: 'string', description: 'Path to the CV (PDF/DOC/DOCX, max 10 MB) on this machine, absolute or ~/... (optional). Only a CV the talent confirmed is theirs. The FILE is uploaded to Shakers with the profile import.' },
     githubUrl: { type: 'string', description: 'GitHub URL (optional).' },
     websiteUrl: { type: 'string', description: 'Personal website URL (optional).' },
   },
@@ -143,7 +151,7 @@ const PRICING_SCHEMA = {
 
 // Default (English) static exports for callers/tests that read the module-level
 // schemas directly. The live tools rebuild these per session language.
-const { ACCOUNT_FIELDS, WORK_SITUATION_SCHEMA, LANGUAGES_SCHEMA, AVAILABILITY_SCHEMA, REGISTER_SCHEMA } = buildSchemas('en');
+const { ACCOUNT_FIELDS, WORK_SITUATION_SCHEMA, LANGUAGES_SCHEMA, AVAILABILITY_SCHEMA, REGISTER_SCHEMA, PREVIEW_SCHEMA } = buildSchemas('en');
 
 const STATUS_SCHEMA = {
   type: 'object',
@@ -172,7 +180,7 @@ const INTERVIEW_TURN_SCHEMA = {
   type: 'object',
   properties: {
     interviewId: { type: 'string', description: 'Internal handle for this interview — for calling the interview tools ONLY; never shown or mentioned to the talent.' },
-    message: { type: 'string', description: "The talent's REAL, VERBATIM answer to the current question. NEVER invent, infer, complete, translate, or answer on the talent's behalf. If the talent has not answered yet, do NOT call this — wait for their actual words." },
+    message: { type: 'string', description: "The talent's answer to the current question: in conduit mode their REAL, VERBATIM words; in AI-drafted mode (only if the talent opted in) the answer they APPROVED after seeing your draft, with their edits. Never a value they have not seen and confirmed. If they have not answered or approved yet, do NOT call this." },
   },
   required: ['interviewId', 'message'],
 };
@@ -446,6 +454,26 @@ function makeRegisterTools(deps = {}) {
     };
   }
 
+  // PURE preview: reuses the write-path validators, touches no network, no session.
+  async function registerPreview(args = {}) {
+    return flow.buildRegisterPreview(args || {});
+  }
+
+  // Content-free context the model may PROPOSE to the talent (never auto-write).
+  async function suggestContext() {
+    const read = deps.readRegisterContextSuggestions || require('./register-context').readRegisterContextSuggestions;
+    return { ok: true, suggestions: read({}), note: 'Propose these to the talent to confirm; never write them without confirmation.' };
+  }
+
+  // Text of the CV the talent confirmed as theirs, read only with their permission.
+  async function readCv(args = {}) {
+    if (args.talentConsent !== true) return { ok: false, reason: 'consent-required', message: 'Ask the talent first whether this CV is theirs and whether you may read it; call again with talentConsent:true only after they say yes.' };
+    const read = deps.readCvText || require('./cv-text').readCvText;
+    const result = read(args.path);
+    if (!result.ok) return { ...result, message: 'Could not read the CV text here. Ask the talent to attach the CV to the chat, or to tell you what it says.' };
+    return result;
+  }
+
   return [
     {
       name: 'register',
@@ -453,6 +481,31 @@ function makeRegisterTools(deps = {}) {
       inputSchema: schemas.REGISTER_SCHEMA,
       handler: register,
     },
+    {
+      name: 'register_preview',
+      description: "REVIEW a (partial) register payload BEFORE writing — the preferred way to register with the least typing. Fill every field you can reasonably infer, then call this. It writes NOTHING; it returns { wouldWrite: the normalized data per hub endpoint, missingFields: what is still needed (required:true) or just suggested (required:false) to ASK the talent, warnings: any value that is invalid, mustConfirm }. Show the talent a short human summary of wouldWrite and the missing items, let them confirm or correct, then call `register` with the final payload. Pre-fill every field you can reasonably infer (memory, chat, context), including pricing and changeMotivators; omit only what you have no basis for. The talent confirms the whole summary once; fields in `mustConfirm` just need to be visible in that summary, not asked separately. All register data is self-declared profile data.",
+      inputSchema: schemas.PREVIEW_SCHEMA,
+      handler: registerPreview,
+    },
+    {
+      name: 'suggest_register_context',
+      description: "Get local SUGGESTIONS to speed up registration: the environment timezone, the local git identity (user.name / user.email), the GitHub login the gh CLI is signed in with (githubUser/githubUrl), and cvCandidates — PDF files in Desktop/Documents/Downloads whose NAME looks like a CV (names only, never read), each with nameMatch (file name contains the git name). Only propose a CV that is clearly the talent's own; never propose one named after someone else. A generic:true name (cv.pdf, curriculum_2024.pdf) may be theirs: ask 'is this CV yours? may I read it and send it with your registration?'. These are PROPOSALS only — present them to the talent to confirm (e.g. 'I see your timezone is Europe/Madrid and your git email is X — use these?') and never write any of them without the talent's confirmation. No session needed. Use it before register_preview to pre-fill availability.timezone, name/email, profile.githubUrl and profile.cvPath.",
+      inputSchema: { type: 'object', properties: {} },
+      handler: suggestContext,
+    },
+    {
+      name: 'read_cv',
+      description: "Read the TEXT of the talent's CV PDF so you can pre-fill the register and the onboarding from what it says (experience, projects, stack, languages, education). Only for a CV the talent has CONFIRMED is theirs, and only after they gave you PERMISSION to read it — set talentConsent:true only then. Typical path: one of suggest_register_context's cvCandidates. Local only: the file is read on this machine and its text comes back to you; nothing is uploaded by this tool (the CV is sent to Shakers only if the talent also confirms it as profile.cvPath in register). Returns { ok, text, truncated } or { ok:false, reason } — on failure ask the talent to attach the CV to the chat.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Path to the PDF the talent confirmed as their CV, exactly as suggest_register_context gave it (the short ~/ form is fine) or absolute.' },
+          talentConsent: { type: 'boolean', description: 'true ONLY after the talent explicitly agreed that this is their CV and that you may read it.' },
+        },
+        required: ['path', 'talentConsent'],
+      },
+      handler: readCv,
+    },
     {
       name: 'register_status',
       description: 'Check the state of the background profile import started by register. Pass the importJobId (an internal handle — never shown to the talent). Returns { state } (e.g. running | done | failed).',
@@ -461,7 +514,7 @@ function makeRegisterTools(deps = {}) {
     },
     {
       name: 'onboarding_interview_start',
-      description: "Start the onboarding interview (step 5, optional). Runs over LiveKit: the server joins a live room and the agent conducts it, transparently resolving the branch (role/dedication only when AI-usage evidence exists, otherwise the AI-usage blocks too) — the client does NOT decide the branch. You MUST first show the talent BOTH interview disclaimers separately (from register's disclaimers.interview) and only then call with disclaimerAcknowledged:true. Returns { interviewId, greeting, ended }: relay the greeting to the talent VERBATIM, then drive the interview with onboarding_interview_turn. INTERVIEW RULE — you are a pure CONDUIT, never a participant: show every interview question to the talent VERBATIM (do not reword, clarify, summarize, translate, or add your own hints/examples/answers), and only ever pass the talent's REAL, VERBATIM words back. Do NOT opine, guide, correct, interpret, or answer for the talent at any point. `interviewId` is an internal handle for the interview tools only — never show or mention it to the talent. If it returns reason 'livekit-not-installed', relay the `message` (it tells the talent how to install the optional @livekit/rtc-node package). If the talent declines the interview, do not call this — instead run the final main-role step (list_my_roles + set_main_role) and offer them their profile URL from register. If the talent has ALREADY completed onboarding this refuses with an already-completed notice unless confirmRepeat:true; note a completed onboarding interview cannot actually be restarted (it returns reason 'interview-already-started') — in that case just run set_main_role.",
+      description: "Start the onboarding interview (step 5, optional). Runs over LiveKit: the server joins a live room and the agent conducts it, transparently resolving the branch (role/dedication only when AI-usage evidence exists, otherwise the AI-usage blocks too) — the client does NOT decide the branch. You MUST first show the talent BOTH interview disclaimers separately (from register's disclaimers.interview) and only then call with disclaimerAcknowledged:true. Returns { interviewId, greeting, ended }: relay the greeting to the talent VERBATIM, then drive the interview with onboarding_interview_turn. ANSWER MODE — before calling this, ASK the talent once: do they want you to draft their answers from what you already know about them (your memory of past conversations, the chat, the register data), so they only confirm, correct or add their opinion? (1) If they say YES (AI-drafted mode): FIRST gather everything you can know about them — your memory, a search of your past conversations with them if you have such a tool, their CV (read_cv, with their permission, if not read yet), their AI-usage report and the register data — and show ONE short sheet 'esto es lo que sé de ti' (roles and projects with the concrete facts, stack, languages, what they want next). Let them correct it once; those corrections override your memory for every later answer. Then for every interview question show the question VERBATIM and your proposed answer in the first person: one or two short sentences in their plain voice, built only from facts on the confirmed sheet — no embellishment, no adjectives, metrics or claims they did not give, no repeating a fact already said unless asked. If the sheet does not cover the question, do not guess a fact: ask them briefly. Ask them to confirm, edit or add their view. Send ONLY the version they approve — their edits and opinions included — never a draft they have not seen. For questions about wishes, preferences or opinions, give your best guess but make clear it is a guess. (2) If they say NO: you are a pure CONDUIT — show every question VERBATIM and pass only the talent's REAL, VERBATIM words back; do not opine, guide or answer for them. In both modes never reword, summarize or translate the interview's questions. `interviewId` is an internal handle for the interview tools only — never show or mention it to the talent. If it returns reason 'livekit-not-installed', relay the `message` (it tells the talent how to install the optional @livekit/rtc-node package). If the talent declines the interview, do not call this — instead run the final main-role step (list_my_roles + set_main_role) and offer them their profile URL from register. If the talent has ALREADY completed onboarding this refuses with an already-completed notice unless confirmRepeat:true; note a completed onboarding interview cannot actually be restarted (it returns reason 'interview-already-started') — in that case just run set_main_role.",
       inputSchema: INTERVIEW_START_SCHEMA,
       handler: interviewStart,
       available: async () => {
@@ -474,7 +527,7 @@ function makeRegisterTools(deps = {}) {
     },
     {
       name: 'onboarding_interview_turn',
-      description: "Send the talent's answer to the current onboarding-interview question and get the next one. You are a pure CONDUIT: pass ONLY the talent's REAL, VERBATIM answer in `message` — NEVER invent, infer, complete, or answer on their behalf; if they have not answered, do NOT call this, wait for them. Relay the returned `response` (the next question) to the talent VERBATIM — do not reword, clarify, summarize, translate, or add hints/examples/opinions of your own. Keep calling with their next `message` until `ended` is true, then call onboarding_interview_complete. Do NOT show or mention `interviewId` to the talent (internal handle). If it returns reason 'unknown-interview' (the server was restarted and the live room is gone), start again with onboarding_interview_start.",
+      description: "Send the talent's answer to the current onboarding-interview question and get the next one. Follow the ANSWER MODE the talent chose at onboarding_interview_start. AI-drafted mode: `message` is the answer the talent APPROVED after seeing your draft (with their edits/opinion); never send a draft they have not confirmed. Conduit mode: `message` is ONLY the talent's REAL, VERBATIM answer — never invent, infer or complete it. In both modes, if the talent has not answered or approved yet, do NOT call this, wait for them. Relay the returned `response` (the next question) to the talent VERBATIM — do not reword, summarize or translate it. Keep calling with their next `message` until `ended` is true, then call onboarding_interview_complete. Do NOT show or mention `interviewId` to the talent (internal handle). If it returns reason 'unknown-interview' (the server was restarted and the live room is gone), start again with onboarding_interview_start.",
       inputSchema: INTERVIEW_TURN_SCHEMA,
       handler: interviewTurn,
     },
@@ -503,6 +556,7 @@ module.exports = {
   makeRegisterTools,
   ACCOUNT_FIELDS,
   REGISTER_SCHEMA,
+  PREVIEW_SCHEMA,
   STATUS_SCHEMA,
   INTERVIEW_START_SCHEMA,
   INTERVIEW_TURN_SCHEMA,

package/src/onboarding-client.js

@@ -1,8 +1,11 @@
 'use strict';
 
-const { postJsonWithTimeout } = require('./backend-request');
+const fs = require('fs');
+const path = require('path');
+const { postJsonWithTimeout, postMultipartWithTimeout } = require('./backend-request');
 const { WORKS_CODE_TO_REASON } = require('./skills-client');
 const { toLowerLang, toUpperLang } = require('./lang-codes');
+const { expandHome } = require('./env-paths');
 
 const DEFAULT_TIMEOUT_MS = 20000;
 const IMPORT_KICKOFF_TIMEOUT_MS = 90000;
@@ -48,6 +51,28 @@ function buildImportSources({ linkedinUrl, cvPath, githubUrl, websiteUrl, langua
   return sources;
 }
 
+// The CV formats and size hub accepts on import-profile.
+const CV_CONTENT_TYPES = {
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+};
+const CV_MAX_BYTES = 10 * 1024 * 1024;
+
+function readCvUpload(input) {
+  const cvPath = expandHome(input);
+  const contentType = CV_CONTENT_TYPES[path.extname(cvPath).toLowerCase()];
+  if (!contentType) return { ok: false, reason: 'cv-bad-format' };
+  let data;
+  try {
+    data = fs.readFileSync(cvPath);
+  } catch {
+    return { ok: false, reason: 'cv-not-found' };
+  }
+  if (data.length > CV_MAX_BYTES) return { ok: false, reason: 'cv-too-large' };
+  return { ok: true, file: { filename: path.basename(cvPath), contentType, data } };
+}
+
 async function requestImportProfile(
   { linkedinUrl, cvPath, githubUrl, websiteUrl, language, accessToken, hubAccessToken } = {},
   { endpoint, timeoutMs = IMPORT_KICKOFF_TIMEOUT_MS } = {},
@@ -59,7 +84,16 @@ async function requestImportProfile(
   const body = buildImportSources({ linkedinUrl, cvPath, githubUrl, websiteUrl, language });
   let res;
   try {
-    res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'POST', null, hubHeaders({ hubAccessToken }));
+    if (body.cvPath) {
+      // Hub reads the CV as an uploaded `cv` file (multipart), never as a local
+      // path: a path on the talent's machine means nothing to the server.
+      const cv = readCvUpload(body.cvPath);
+      if (!cv.ok) return cv;
+      const { cvPath: _localPath, ...fields } = body;
+      res = await postMultipartWithTimeout(endpoint, { ...fields, cv: cv.file }, timeoutMs, 'POST', hubHeaders({ hubAccessToken }));
+    } else {
+      res = await postJsonWithTimeout(endpoint, body, timeoutMs, 'POST', null, hubHeaders({ hubAccessToken }));
+    }
   } catch (e) {
     return { ok: false, reason: (e && e.kind) || 'network-error' };
   }

package/src/onboarding-flow.js

@@ -241,6 +241,120 @@ function validateAvailability(input = {}) {
   return { ok: true, availability: body };
 }
 
+// Fields the talent must ALWAYS confirm explicitly — never inferred/invented by
+// the model (a wrong price or motivation is worse than a gap).
+const MUST_CONFIRM_FIELDS = ['pricing', 'workSituation.changeMotivators'];
+
+// PURE preview of a (possibly partial) register payload: what WOULD be written,
+// what is still missing, and what is invalid — reusing the same validators the
+// write path uses. Touches no network and needs no session, so the model can show
+// the talent a review before the single `register` write.
+function buildRegisterPreview(args = {}) {
+  const wouldWrite = [];
+  const missingFields = [];
+  const warnings = [];
+  const addMissing = (field, required) => missingFields.push({ field, required });
+
+  // --- account (always written at registration; password never in the payload) ---
+  const account = {
+    name: args.name,
+    lastName: args.lastName,
+    email: args.email,
+    freelanceType: args.freelanceType,
+  };
+  if (!isNonEmptyString(account.name)) addMissing('name', true);
+  if (!isNonEmptyString(account.lastName)) addMissing('lastName', true);
+  if (!isNonEmptyString(account.email)) addMissing('email', true);
+  const ftype = normalizeFreelanceType(account.freelanceType);
+  if (!ftype) {
+    if (isNonEmptyString(account.freelanceType)) warnings.push({ field: 'freelanceType', reason: 'bad-freelance-type' });
+    else addMissing('freelanceType', true);
+  }
+  wouldWrite.push({
+    section: 'account',
+    endpoint: 'hub: auth/sign-up/email + works/auth/complete-registration',
+    data: {
+      name: isNonEmptyString(account.name) ? account.name : null,
+      lastName: isNonEmptyString(account.lastName) ? account.lastName : null,
+      email: isNonEmptyString(account.email) ? account.email : null,
+      freelanceType: ftype || null,
+      preferredLanguage: isNonEmptyString(args.preferredLanguage) ? args.preferredLanguage : null,
+      newsletterConsent: args.newsletterConsent === true,
+    },
+    note: 'password is never part of this payload — the talent types it in the local sign-up window',
+  });
+
+  // --- profile import (linkedinUrl is the required source) ---
+  const profile = args.profile && typeof args.profile === 'object' ? args.profile : {};
+  if (!isNonEmptyString(profile.linkedinUrl)) addMissing('profile.linkedinUrl', true);
+  else {
+    const pdata = { linkedinUrl: profile.linkedinUrl };
+    for (const k of ['githubUrl', 'websiteUrl', 'cvPath']) if (isNonEmptyString(profile[k])) pdata[k] = profile[k];
+    wouldWrite.push({ section: 'profile', endpoint: 'hub: works/me/import-profile', data: pdata });
+  }
+
+  // --- work situation (situation required) ---
+  const ws = args.workSituation && typeof args.workSituation === 'object' ? args.workSituation : {};
+  if (!isNonEmptyString(ws.situation)) addMissing('workSituation.situation', true);
+  else {
+    const vws = validateWorkSituation(ws);
+    if (!vws.ok) warnings.push({ field: 'workSituation', reason: vws.reason });
+    else wouldWrite.push({ section: 'workSituation', endpoint: 'hub: works/me/professional-details', data: vws.professionalDetails });
+  }
+
+  // --- pricing (at least one variant; ALWAYS confirm) ---
+  const pricing = args.pricing && typeof args.pricing === 'object' ? args.pricing : {};
+  const pricingEmpty = pricing.fullTimeSelected !== true && pricing.partTimeSelected !== true
+    && pricing.fullTimeAmount == null && pricing.partTimeAmount == null;
+  if (pricingEmpty) addMissing('pricing', true);
+  else {
+    const vp = validatePricing(pricing);
+    if (!vp.ok) warnings.push({ field: 'pricing', reason: vp.reason });
+    else wouldWrite.push({ section: 'pricing', endpoint: 'hub: works/talents/me/work-details/pricing-rate', data: vp.pricing });
+  }
+
+  // --- availability (optional; suggest the sub-fields the talent did not give) ---
+  if (args.availability && typeof args.availability === 'object') {
+    const va = validateAvailability(args.availability);
+    if (!va.ok) warnings.push({ field: 'availability', reason: va.reason });
+    else {
+      wouldWrite.push({ section: 'availability', endpoint: 'hub: works/talents/me/work-details/availability', data: va.availability });
+      for (const k of ['available', 'monthlyHours', 'workModes', 'country', 'timezone']) {
+        if (!(k in va.availability)) addMissing(`availability.${k}`, false);
+      }
+    }
+  } else {
+    addMissing('availability', false);
+  }
+
+  // --- languages (optional; ids resolve at write-time, so the preview shows codes) ---
+  if (Array.isArray(args.languages) && args.languages.length > 0) {
+    const vl = validateLanguageRows(args.languages);
+    if (!vl.ok) warnings.push({ field: 'languages', reason: vl.reason });
+    else wouldWrite.push({ section: 'languages', endpoint: 'hub: works/talents/me/work-details/languages', data: vl.rows, note: 'language codes resolve to ids at write time' });
+  } else {
+    addMissing('languages', false);
+  }
+
+  // --- phone (optional) ---
+  if (args.phone && typeof args.phone === 'object') {
+    const vph = validatePhone(args.phone);
+    if (!vph.ok) warnings.push({ field: 'phone', reason: vph.reason });
+    else wouldWrite.push({ section: 'phone', endpoint: 'hub: works/me', data: { telephoneCode: vph.telephoneCode, telephoneNumber: vph.telephoneNumber } });
+  } else {
+    addMissing('phone', false);
+  }
+
+  return {
+    ok: true,
+    provenance: 'self-declared',
+    wouldWrite,
+    missingFields,
+    warnings,
+    mustConfirm: MUST_CONFIRM_FIELDS,
+  };
+}
+
 function makeDeps(overrides = {}) {
   const config = require('./config');
   const client = require('./onboarding-client');
@@ -1052,6 +1166,8 @@ module.exports = {
   buildPricingUpsert,
   isAcceptablePassword,
   validateRegisterFields,
+  buildRegisterPreview,
+  MUST_CONFIRM_FIELDS,
   deriveCurrentEmploymentStatus,
   showsFreelanceOpinion,
   deriveFreelanceIntent,

package/src/register-context.js

@@ -0,0 +1,128 @@
+'use strict';
+
+// Local context SUGGESTIONS for the register flow: the environment timezone, the
+// local git identity, the GitHub login and CV candidates. These are proposals the
+// model offers the talent to confirm — they are NEVER auto-written. No file
+// content, no commit scanning, no network, no session: CV candidates are file
+// NAMES only. This is deliberately NOT the authorship/evidence path.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { getHomeDir, tildify } = require('./env-paths');
+
+// Where a talent keeps a CV, and how deep we look under each folder.
+const CV_DIRS = ['Desktop', 'Documents', 'Downloads', 'Escritorio', 'Documentos', 'Descargas'];
+const CV_MAX_DEPTH = 2;
+const CV_MAX_RESULTS = 5;
+const CV_NAME = /(^|[^a-z])(cv|curriculum|curr[ií]culum|resume|r[ée]sum[ée])([^a-z]|$)/i;
+
+function detectTimezone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || null;
+  } catch {
+    return null;
+  }
+}
+
+function gitConfig(key, cwd) {
+  try {
+    const out = execFileSync('git', ['config', '--get', key], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      cwd: cwd || process.cwd(),
+    });
+    const value = String(out || '').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+// The login the GitHub CLI is signed in with, read from its local hosts file
+// (no network), else the conventional `github.user` git key.
+function detectGithubUser(home, cwd) {
+  try {
+    const hosts = fs.readFileSync(path.join(home, '.config', 'gh', 'hosts.yml'), 'utf8');
+    const block = hosts.split(/^github\.com:\s*$/m)[1];
+    const match = block && block.match(/^\s+user:\s*(\S+)\s*$/m);
+    if (match) return match[1];
+  } catch {
+    // no gh CLI config
+  }
+  return gitConfig('github.user', cwd);
+}
+
+const fold = (text) => String(text || '').normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
+
+// Whether a file name carries a token of the person's name. People who hire keep
+// other people's CVs in Downloads; only a name match makes a candidate theirs.
+function matchesName(fileName, personName) {
+  const tokens = fold(personName).split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
+  const file = fold(fileName);
+  return tokens.some((t) => file.includes(t));
+}
+
+// Words that say nothing about whose CV it is: `cv.pdf`, `Curriculum_2024_ES.pdf`,
+// `resume-final-v2.pdf`. Such a file may be the talent's own, so it is worth asking.
+const GENERIC_WORDS = /\b(cv|curriculum|curriculo|resume|vitae|mi|my|el|the|de|of|final|actualizado|updated|nuevo|new|latest|es|en|esp|eng|spanish|english|espanol|ingles|v\d+|copia|copy)\b/g;
+
+function isGenericCvName(fileName) {
+  const rest = fold(fileName.replace(/\.pdf$/i, '')).replace(/[^a-z0-9]+/g, ' ').replace(GENERIC_WORDS, ' ').replace(/\d+/g, ' ');
+  return rest.trim().length === 0;
+}
+
+// PDFs whose NAME looks like a CV: name matches first, then generic names, then
+// newest. Never opens a file.
+function findCvCandidates(home, personName) {
+  const found = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (depth < CV_MAX_DEPTH) walk(full, depth + 1);
+      } else if (entry.isFile() && /\.pdf$/i.test(entry.name) && CV_NAME.test(entry.name.replace(/\.pdf$/i, ''))) {
+        try {
+          found.push({
+            path: full,
+            nameMatch: matchesName(entry.name, personName),
+            generic: isGenericCvName(entry.name),
+            mtimeMs: fs.statSync(full).mtimeMs,
+          });
+        } catch {
+          // vanished between readdir and stat
+        }
+      }
+    }
+  };
+  for (const name of CV_DIRS) walk(path.join(home, name), 1);
+  return found
+    .sort((a, b) => Number(b.nameMatch) - Number(a.nameMatch) || Number(b.generic) - Number(a.generic) || b.mtimeMs - a.mtimeMs)
+    .slice(0, CV_MAX_RESULTS)
+    .map(({ path: cvPath, nameMatch, generic }) => ({ path: tildify(cvPath, { SHAKERS_CLI_HOME_DIR: home }), nameMatch, generic }));
+}
+
+// Returns the signals found, each clearly a SUGGESTION to confirm.
+function readRegisterContextSuggestions({ cwd, env = process.env } = {}) {
+  const home = getHomeDir(env);
+  const githubUser = detectGithubUser(home, cwd);
+  const gitName = gitConfig('user.name', cwd);
+  return {
+    timezone: detectTimezone(),
+    gitName,
+    gitEmail: gitConfig('user.email', cwd),
+    githubUser,
+    githubUrl: githubUser ? `https://github.com/${githubUser}` : null,
+    cvCandidates: findCvCandidates(home, gitName),
+  };
+}
+
+module.exports = { readRegisterContextSuggestions, detectTimezone, findCvCandidates, detectGithubUser, isGenericCvName };