@empirical-gauzza/cli 1.0.37 → 1.0.38

package/lib/memoryResolve.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// Resolving "which memory did the user mean" from a --match query, shared by every memory
+// subcommand that accepts --match. It lives in its own module so attachmentCommands.js can use
+// it without a require cycle back through memoryCommands.js; memoryCommands.js re-exports the
+// three names so existing importers and tests are unaffected.
+
+const { warn } = require('./ui');
+const { httpJson } = require('./http');
+const { parseOption } = require('./env');
+const { buildApiAuthHeaders } = require('./auth');
+
+async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters) {
+  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
+  const body = { query: match, topK: 5 };
+  if (filters && Object.keys(filters).length) body.filters = filters;
+  let response;
+  try {
+    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    return { found: false, reason: 'error', message: error.message };
+  }
+
+  const results = (response && response.data && Array.isArray(response.data.results))
+    ? response.data.results
+    : (Array.isArray(response) ? response : []);
+
+  if (!results.length) {
+    return { found: false, reason: 'no_results' };
+  }
+
+  const scored = results.map((r) => ({
+    id: r.id,
+    summary: r.summary,
+    score: r.rankScore != null ? r.rankScore : (r.similarityScore != null ? r.similarityScore : 0)
+  }));
+
+  scored.sort((a, b) => b.score - a.score);
+
+  // A caller-supplied filter (e.g. --tags) that narrows the server-side result set to exactly
+  // one memory is already a stronger disambiguation signal than the semantic score - trust it
+  // outright rather than falling through to the score check below. This matters because Atlas
+  // vector search has a real async indexing lag: a memory created moments ago can come back
+  // with score 0 (unindexed, not "not this one") even when a tag filter already proves it is
+  // the only candidate. Fixes a real bug found 2026-08-25 where delete --match failed on a
+  // memory `query` found instantly, because delete had no way to trust a filtered, unambiguous
+  // result over a stale/zero semantic score.
+  if (filters && Object.keys(filters).length && results.length === 1) {
+    const only = scored[0];
+    return { found: true, memory: { id: only.id, summary: only.summary, score: only.score } };
+  }
+
+  const top = scored[0];
+  const second = scored[1];
+
+  if (top.score < minScore) {
+    return { found: false, reason: 'low_score', candidates: scored.slice(0, 3) };
+  }
+
+  if (second && (top.score - second.score) <= 0.05) {
+    return { found: false, reason: 'ambiguous', candidates: scored.slice(0, 3) };
+  }
+
+  return { found: true, memory: { id: top.id, summary: top.summary, score: top.score } };
+}
+
+// --match resolution depends on Atlas vector search, which has a real async indexing lag:
+// a memory created moments ago can be invisible to $vectorSearch even though it is already
+// findable by tag. Letting --match commands pass --tags narrows the candidate pool directly
+// instead of hoping semantic ranking surfaces the right one - the fix for a real bug found
+// 2026-08-25 where delete --match returned unrelated score-0 candidates for a memory that
+// `query` found instantly. Deliberately --tags (plural) only, not --category: `delete` already
+// uses singular --tag/--category to mean "bulk delete everything in this category", so adding
+// --category here would silently reroute a --match delete into a bulk delete instead of
+// narrowing it - --tags never collides with that bulk-mode gate.
+function parseMatchFilters(args) {
+  const tagsRaw = parseOption(args, '--tags', '');
+  const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+  const filters = {};
+  if (tags.length) filters.tags = tags;
+  return filters;
+}
+
+function printMemoryResolveError(result) {
+  if (result.reason === 'no_results') {
+    warn(JSON.stringify({ error: true, code: 'no_results', message: 'No memories matched the query.' }));
+  } else if (result.reason === 'low_score') {
+    warn(JSON.stringify({
+      error: true,
+      code: 'low_score',
+      message: 'Top result score was below --min-score threshold.',
+      candidates: result.candidates
+    }));
+  } else if (result.reason === 'ambiguous') {
+    warn(JSON.stringify({
+      error: true,
+      code: 'ambiguous',
+      message: 'Multiple memories matched with similar scores. Use --memory-id to target one directly.',
+      candidates: result.candidates
+    }));
+  } else if (result.reason === 'error') {
+    warn(JSON.stringify({ error: true, code: 'query_error', message: result.message }));
+  } else {
+    warn(JSON.stringify({ error: true, code: 'resolve_failed', message: 'Could not resolve memory.' }));
+  }
+}
+
+module.exports = {
+  resolveMemoryByQuery,
+  parseMatchFilters,
+  printMemoryResolveError
+};

package/lib/setupCommands.js

@@ -55,9 +55,20 @@ function recoveryHints(error, sessionId, step = '') {
   switch (error && error.code) {
     case 'GUIDED_SETUP_VOICE_NOT_WAITING':
     case 'GUIDED_SETUP_VOICE_STALE':
+    case 'GUIDED_SETUP_WORKSPACE_NOT_WAITING':
       return [`See the current question and its key with: ${resume}`];
     case 'GUIDED_SETUP_VOICE_BUSY':
+    case 'GUIDED_SETUP_WORKSPACE_BUSY':
       return [`Wait a moment, then pick it up with: ${resume}`];
+    // The workspace interview's own refusals. The server's message already carries the price of a new
+    // interview (it is the effective one), so these lines name no number. An abandoned interview is
+    // not refunded, which is said before the person is pointed at starting again.
+    case 'GUIDED_SETUP_WORKSPACE_SESSION_LIMIT':
+      return [`If a draft was already shown, you can read it with ${resume} and confirm it; the limit can be reached before there is one. Starting a new interview is charged again, and stopping this one with empirical setup abandon ${sid} does not return what it cost.`];
+    case 'GUIDED_SETUP_WORKSPACE_GENERATION_FAILED':
+      return [`Your answers are saved. Run ${resume} to see where the setup is, then answer again.`];
+    case 'GUIDED_SETUP_WORKSPACE_UNAVAILABLE':
+      return ['Nothing was started or charged. Run the command again in a few minutes.'];
     case 'EMPIRICAL_TOKENS_ATTEMPT_CLOSED':
       return ['This attempt is already closed, so it cannot be continued. Start a new one with: empirical setup run <setupId>'];
     case 'EMPIRICAL_TOKEN_KEY_OWNER_MISMATCH':
@@ -120,7 +131,23 @@ function refundLine(error) {
   return null;
 }
 
+// The server words its errors for every client, and one clause tells an AGENT to call a tool. At a terminal the
+// same step is a command, so that clause (and only that clause) becomes the real command.
+function cliConfirmWording(text, sessionId) {
+  return String(text === undefined || text === null ? '' : text).replace(
+    /\b([Cc])all confirm_guided_setup with this session's sessionId and the draftHash shown with the draft/g,
+    (_m, c) => `${c === 'C' ? 'Run' : 'run'} empirical setup confirm ${sessionId || '<sessionId>'} <draftHash>`
+  );
+}
+function forTerminal(error, sessionId) {
+  if (!error) return error;
+  if (typeof error.message === 'string') error.message = cliConfirmWording(error.message, sessionId);
+  if (typeof error.serverMessage === 'string') error.serverMessage = cliConfirmWording(error.serverMessage, sessionId);
+  return error;
+}
+
 function failWith(error, pathSuffix, body) {
+  forTerminal(error, sessionIdFromPath(pathSuffix));
   printApiError(error);
   for (const line of recoveryHints(error, sessionIdFromPath(pathSuffix), stepOf(pathSuffix, body))) warn(line);
   const refund = refundLine(error);
@@ -219,7 +246,9 @@ function formatQuestionLines(question, progress = {}) {
     // records whatever is typed, so the end-early hint belongs to the follow-up loop alone.
     if (p.meterLine && question.kind === 'text' && /^g\d+$/.test(key) && !question.focus) lines.push(loopHint(question, p));
   }
-  if (question.kind === 'pick_and_edit') lines.push('Reply with the numbers that fit, like 2,5, and optionally a | and your own changes.');
+  // The workspace interview words its own examples (built from the options on offer, and in the 'add Name'
+  // form its parser reads); this Writing Voice line would show "2,5" for a list that may have two options.
+  if (question.kind === 'pick_and_edit' && !isWorkspaceQuestion(question)) lines.push('Reply with the numbers that fit, like 2,5, and optionally a | and your own changes.');
   if (question.kind === 'pick_one') lines.push('Reply with one number.');
   if (question.kind === 'yes_no') lines.push('Reply yes or no.');
   if (staleTopic) {
@@ -238,7 +267,46 @@ function workspacePlace(name) {
   return /\bworkspace$/i.test(n) ? n : `${n} workspace`;
 }
 
+// A workspace draft is a list of plain sentences (no hub or rules), the people to be invited, and
+// anything that stops it being confirmed. The Writing Voice branch below would print "Hub: undefined".
+function isWorkspaceDraft(question) {
+  return Boolean(question && question.draft && Array.isArray(question.draft.lines));
+}
+
+function formatWorkspaceDraftLines(question) {
+  const t = sanitizeForTerminal;
+  const confirm = question.confirm || {};
+  const lines = [];
+  for (const l of [...question.draft.lines, ...(Array.isArray(question.draft.statusSummary) ? question.draft.statusSummary : [])]) lines.push(`- ${t(l)}`);
+  if (Array.isArray(confirm.invites)) {
+    lines.push(confirm.invites.length
+      ? `Invites: ${confirm.invites.map((i) => `${t(i.email)} (${t(i.role)})`).join(', ')}`
+      : 'Invites: nobody yet.');
+  }
+  if (confirm.inviteNote) lines.push(t(confirm.inviteNote));
+  if (confirm.canConfirm === false) {
+    lines.push('This draft cannot be confirmed as it is:');
+    for (const b of Array.isArray(confirm.blockers) ? confirm.blockers : []) lines.push(`- ${t(b)}`);
+    lines.push('Type a change to fix it. Nothing has been created or changed.');
+  } else if (question.prompt) {
+    // The server's own review wording: what the person can do next (next, confirm, a change, a rename).
+    lines.push(workspaceReviewPrompt(question.prompt));
+  }
+  return lines;
+}
+
+// The server words the review for every client, and its one tool-call clause (how an AGENT confirms) means
+// nothing at a terminal, where the person types the word that is asked for below. Everything else is the
+// server's own text, unchanged, so every example in it works as typed.
+function workspaceReviewPrompt(prompt) {
+  return sanitizeForTerminal(prompt)
+    .replace(/\s*\(call confirm_guided_setup[^)]*\)/, '')
+    .replace(/To (?:create the workspace|save these changes), call confirm_guided_setup[^.]*\.\s*/, '')
+    .trim();
+}
+
 function formatDraftLines(question, progress = {}) {
+  if (isWorkspaceDraft(question)) return formatWorkspaceDraftLines(question);
   const t = sanitizeForTerminal;
   const draft = question.draft || {};
   const confirm = question.confirm || {};
@@ -302,6 +370,10 @@ function printCurrentQuestion(result) {
   }
   printDraft(question, result.progress);
   const confirm = question.confirm || {};
+  if (isWorkspaceDraft(question) && confirm.canConfirm === false) {
+    warn(`Ask for a change with: empirical setup answer ${sid} ${key} <the change you want>`);
+    return;
+  }
   if (confirm.stale) {
     warn(`Rebuild it with: empirical setup answer ${sid} ${key} rebuild`);
   } else if (confirm.draftHash) {
@@ -378,6 +450,14 @@ async function offerVoicePluginInstall({ prompter, env = process.env, install =
 // offer: { prompter } when a person at a terminal ran the interview; absent for scripted runs.
 async function reportConfirmed(result, offer) {
   if (result && result.message) log(sanitizeForTerminal(result.message));
+  // A confirmed workspace interview has no install job: it names the workspace and what to do next.
+  if (result && result.workspaceId && !(result && result.installId)) {
+    const id = sanitizeForTerminal(result.workspaceId);
+    log(`Workspace id: ${id}`);
+    log(`Switch to it with: ${WORKSPACE_USE_LINE(id)}`);
+    log(`Change its shape later with: ${WORKSPACE_SHAPE_LINE(id)}`);
+    return;
+  }
   const installId = result && result.installId;
   if (!installId) return;
   const status = await fetchInstallStatus(installId);
@@ -419,11 +499,26 @@ async function reportConfirmed(result, offer) {
 // Spec 7.3: a priced setup returns a cost preview first. Acceptance is sent only from the explicit
 // --accept-cost flag; a first call without it stops at the cost and starts nothing. A person at a
 // terminal is asked instead, and a non-interactive run stops.
-async function startWithCost(setupId, { acceptCost, prompter }) {
-  const first = await callApi('POST', '/start', acceptCost ? { setupId, acceptEmpiricalTokenCost: true } : { setupId });
+//
+// start carries any extra start fields. For the workspace interview that is targetWorkspaceId, the one
+// explicit way to ask for a re-shape (no field means a new workspace). Its start is also where a setup
+// that is switched off for the person answers 404, which is explained instead of left as a bare error.
+async function startWithCost(setupId, { acceptCost, prompter, start = {} }) {
+  const first = await startCall({ setupId, ...start, ...(acceptCost ? { acceptEmpiricalTokenCost: true } : {}) });
   if (!isCostPreview(first)) return reportTokensUsed(first);
   await confirmCostOrExit(first, { prompter, warn, sanitize: sanitizeForTerminal });
-  return reportTokensUsed(await callApi('POST', '/start', { setupId, acceptEmpiricalTokenCost: true }));
+  return reportTokensUsed(await startCall({ setupId, ...start, acceptEmpiricalTokenCost: true }));
+}
+
+async function startCall(body) {
+  const { data, error } = await tryApi('POST', '/start', body);
+  if (!error) return data;
+  if (body.setupId === WORKSPACE_SETUP_ID && error.statusCode === 404) {
+    printApiError(error);
+    warn('The workspace interview is not switched on for your account, so nothing was started or charged.');
+    process.exit(1);
+  }
+  return failWith(error, '/start', body);
 }
 
 // After a paid start, say what it cost, but only when the response carries the amount. stderr, so
@@ -434,20 +529,35 @@ function reportTokensUsed(result) {
   return result;
 }
 
-async function runNonInteractive(setupId, answersFilePath, acceptCost) {
+async function runNonInteractive(setupId, answersFilePath, acceptCost, start) {
   const raw = fs.readFileSync(path.resolve(answersFilePath), 'utf8');
   const answersByQuestionKey = JSON.parse(raw);
 
-  let current = await startWithCost(setupId, { acceptCost, prompter: null });
+  let current = await startWithCost(setupId, { acceptCost, prompter: null, start });
+  hintAbandon(current);
   let confirmed = false;
+  const reviewTurns = {};
 
   while (current.question && current.status !== 'completed' && current.status !== 'finished_early') {
     const question = current.question;
     const questionKey = question.questionKey;
+    if (question.kind === 'confirm' && isFirstWorkspaceReview(question) && Object.prototype.hasOwnProperty.call(answersByQuestionKey, questionKey) && answersByQuestionKey[questionKey] !== 'confirm') {
+      // The first review of a workspace: the file's value is the answer, so a script can reach the invites.
+      // A list is taken in order (a rename, then next); a single string is sent once.
+      const wanted = answersByQuestionKey[questionKey];
+      const queue = Array.isArray(wanted) ? wanted : [wanted];
+      const turn = (reviewTurns[questionKey] = (reviewTurns[questionKey] || 0) + 1) - 1;
+      if (turn < queue.length) {
+        current = await callApi('POST', `/${current.sessionId}/continue`, answerBody(question, queue[turn]));
+        continue;
+      }
+    }
     if (question.kind === 'confirm') {
       // Confirming is its own step: only an explicit "confirm" for q5_confirm installs, never a stale draft.
       const stale = Boolean(question.confirm && question.confirm.stale);
-      if (answersByQuestionKey[questionKey] === 'confirm' && !stale) {
+      // A workspace draft with blockers has no hash to confirm; the file's "confirm" is not sent for it.
+      const confirmable = !(question.confirm && question.confirm.canConfirm === false);
+      if (answersByQuestionKey[questionKey] === 'confirm' && !stale && confirmable) {
         current = await callApi('POST', `/${current.sessionId}/confirm`, { draftHash: question.confirm.draftHash });
         confirmed = true;
       } else if (stale) {
@@ -517,34 +627,44 @@ async function sendInteractiveAnswer(current, answer) {
   if (!error) return data;
   if (error.statusCode !== 400 && error.statusCode !== 409) failWith(error, pathSuffix, body);
   if (error.code === 'GUIDED_SETUP_CONFIRM_REQUIRED') warn('To install this draft, type yes.');
-  else warn(sanitizeForTerminal(error.serverMessage || error.message));
+  else warn(sanitizeForTerminal(cliConfirmWording(error.serverMessage || error.message, current.sessionId)));
   return callApi('POST', pathSuffix, {});
 }
 
-async function runInteractive(setupId, acceptCost) {
+async function runInteractive(setupId, acceptCost, start) {
   const prompter = createPrompter(process.stderr);
   let abortMessage = null;
   let finalResult = null;
   let confirmed = false;
   try {
-    let current = await startWithCost(setupId, { acceptCost, prompter });
+    let current = await startWithCost(setupId, { acceptCost, prompter, start });
     if (!current) return;
+    hintAbandon(current);
     let emptyReplies = 0;
     while (current.question && current.status !== 'completed' && current.status !== 'finished_early') {
       const question = current.question;
       if (question.kind === 'confirm') {
         printDraft(question, current.progress);
-        const reply = (await prompter.askText('Install this? (type yes to install, or type a change you want)')).trim();
+        const reply = (await prompter.askText(confirmPromptFor(question))).trim();
         if (!reply) {
           const sessionId = current.sessionId;
           abortMessage = () => printNothingInstalled(sessionId, question.confirm && question.confirm.draftHash);
           break;
         }
-        if (/^(y|yes)$/i.test(reply)) {
+        const firstReview = isFirstWorkspaceReview(question);
+        if (firstReview && /^(y|yes)$/i.test(reply)) {
+          warn('Yes is not one of the choices here. Type next to choose who to invite, or confirm to finish without inviting anyone.');
+          continue;
+        }
+        if (firstReview ? /^confirm$/i.test(reply) : /^(y|yes|confirm)$/i.test(reply)) {
           if (question.confirm && question.confirm.stale) {
             warn('This draft is out of date. Type rebuild to write a new one first.');
             continue;
           }
+          if (isWorkspaceDraft(question) && (question.confirm.canConfirm === false || !question.confirm.draftHash)) {
+            warn('This draft cannot be confirmed as it is. Type a change to fix what is listed above.');
+            continue;
+          }
           current = await callApi('POST', `/${current.sessionId}/confirm`, { draftHash: question.confirm.draftHash });
           confirmed = true;
           break;
@@ -589,6 +709,50 @@ async function runInteractive(setupId, acceptCost) {
   printJson(finalResult);
 }
 
+const WORKSPACE_SETUP_ID = 'setup_workspace';
+// The commands printed after a workspace is made, built from the real id so they work as typed.
+const WORKSPACE_USE_LINE = (id) => `empirical workspace use ${id}`;
+const WORKSPACE_SHAPE_LINE = (id) => `empirical workspace shape --workspace-id ${id}`;
+
+// The question at the review step. The workspace interview creates or changes a workspace, not an install.
+// The first review (questionKey draft) is BEFORE the invitations, so a bare yes is not a choice there: the
+// person picks next (to choose who to invite) or confirm (finish with nobody invited). The final review
+// (after the invitations) is the one a yes confirms.
+function isFirstWorkspaceReview(question) {
+  return isWorkspaceDraft(question) && question.questionKey === 'draft';
+}
+function confirmPromptFor(question) {
+  if (!isWorkspaceDraft(question)) return 'Install this? (type yes to install, or type a change you want)';
+  const reshape = question.confirm && question.confirm.mode === 'reshape';
+  if (question.confirm && question.confirm.canConfirm === false) return 'What next? (type a change you want)';
+  if (isFirstWorkspaceReview(question)) return `What next? (type next to choose who to invite, confirm to ${reshape ? 'save these changes' : 'create the workspace'} without inviting anyone, or type a change you want)`;
+  return `${reshape ? 'Apply this to the workspace?' : 'Create this workspace?'} (type yes to confirm, or type a change you want)`;
+}
+
+// Printed once after a workspace interview starts. An abandoned interview is NOT refunded, and the
+// line says so, so nobody stops one expecting their Empirical Tokens back.
+function hintAbandon(result) {
+  if (!result || !result.sessionId || !result.question) return;
+  if (!isWorkspaceQuestion(result.question)) return;
+  const sid = sanitizeForTerminal(result.sessionId);
+  warn(`If you want to stop this interview, run: empirical setup abandon ${sid} (what it cost is not returned).`);
+}
+
+// Workspace questions are the only ones with these keys; the Writing Voice engine has none of them.
+function isWorkspaceQuestion(question) {
+  const key = String((question && question.questionKey) || '');
+  return key === 'purpose' || key === 'types' || key === 'nesting' || key === 'policy' || key === 'invites'
+    || key === 'draft' || /^(statuses|fields):/.test(key);
+}
+
+// The workspace interview from the workspace commands. targetWorkspaceId present means re-shape that
+// workspace, absent means create a new one; nothing else decides it.
+async function runWorkspaceInterview({ targetWorkspaceId, answersFile = '', acceptCost = false } = {}) {
+  const start = targetWorkspaceId ? { targetWorkspaceId } : {};
+  if (answersFile) return runNonInteractive(WORKSPACE_SETUP_ID, answersFile, acceptCost, start);
+  return runInteractive(WORKSPACE_SETUP_ID, acceptCost, start);
+}
+
 async function runRun(args) {
   const setupId = args[0] && !args[0].startsWith('--') ? args[0] : '';
   if (!setupId) {
@@ -627,6 +791,18 @@ async function runFinish(args) {
   printJson(result);
 }
 
+async function runAbandon(args) {
+  const [sessionId] = args;
+  if (!sessionId) {
+    warn('Usage: empirical setup abandon <sessionId>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/abandon`, {});
+  log(result && result.status === 'abandoned'
+    ? 'The interview was stopped. Nothing was created or changed, and what it cost was not returned.'
+    : 'That interview was already finished or stopped. Nothing was changed, and no Empirical Tokens were returned.');
+}
+
 async function runResume(args) {
   const [sessionId] = args;
   if (!sessionId) {
@@ -656,11 +832,12 @@ async function runSetupCommand(args) {
   if (sub === 'finish') return runFinish(rest);
   if (sub === 'resume') return runResume(rest);
   if (sub === 'confirm') return runConfirm(rest);
-  warn('Usage: empirical setup <list|run|answer|finish|resume|confirm> ...');
+  if (sub === 'abandon') return runAbandon(rest);
+  warn('Usage: empirical setup <list|run|answer|finish|resume|confirm|abandon> ...');
   process.exit(1);
 }
 
 module.exports = {
-  refundLine, runSetupCommand, formatQuestionLines, formatDraftLines, sanitizeForTerminal,
+  refundLine, cliConfirmWording, runSetupCommand, runWorkspaceInterview, WORKSPACE_SETUP_ID, recoveryHints, formatQuestionLines, formatDraftLines, sanitizeForTerminal,
   offerVoicePluginInstall, VOICE_PLUGIN_COMMANDS, VOICE_STANDING_INSTRUCTION
 };

package/lib/workspaceCommands.js

@@ -1,12 +1,14 @@
 'use strict';
 
-const { log, ask, uiSuccess } = require('./ui');
+const { log, warn, ask, askYesNo, uiSuccess } = require('./ui');
 const { httpJson } = require('./http');
 const { getEnv, parseFlag, parseOption } = require('./env');
 const { ensureHeadlessToken, resolveAccessToken, buildApiAuthHeaders } = require('./auth');
 const { readStoredOAuthClient } = require('./oauthClient');
 const { deriveBaseUrlFromMcpUrl } = require('./constants');
 const { withCliAnalyticsContext } = require('./memoryCommands');
+const { runWorkspaceInterview, sanitizeForTerminal } = require('./setupCommands');
+const { isInteractiveTerminal } = require('./empiricalTokensFormat');
 const {
   writeSelectedWorkspace,
   clearSelectedWorkspace,
@@ -18,9 +20,38 @@ const {
   WORKSPACE_ENV_VAR
 } = require('./workspaceContext');
 
+const WORKSPACE_CREATE_INTERVIEW_USAGE = 'Usage: empirical workspace create --interview [--answers <file.json>] [--accept-cost]. The interview asks what the workspace is for, so it takes no name.';
+const WORKSPACE_SHAPE_USAGE = 'Usage: empirical workspace shape [--workspace-id <id>] [--answers <file.json>] [--accept-cost]. Pass --workspace-id, or at a terminal bind this directory to the workspace first with `empirical workspace use <id>` and the command will ask you to confirm it.';
+const WORKSPACE_SHAPE_EXPLICIT_ID = 'A re-shape is charged, so a script (--answers or --accept-cost) or a run with no terminal must name the workspace itself. Pass --workspace-id <id>; the workspace this directory is bound to is not used here.';
+
+// Which workspace `workspace shape` re-shapes. An explicit --workspace-id is used as given. The ambient
+// binding (env, project or global) is a convenience for a person at a terminal ONLY: it is shown by NAME
+// and source and needs a yes that names the workspace, and it is never used by a script or with
+// --accept-cost, so a stale binding cannot aim a paid re-shape at the wrong workspace unseen.
+// Everything said here goes to stderr (warn), so a scripted run keeps stdout for its result.
+async function resolveShapeTarget({ requested, local, answersFile, acceptCost, interactive, fetchName, askYesNo: confirm, say = warn }) {
+  if (requested) {
+    say(`Re-shaping workspace ${sanitizeForTerminal(requested)}.`);
+    return requested;
+  }
+  if (!local || !local.workspaceId) throw new Error(WORKSPACE_SHAPE_USAGE);
+  if (answersFile || acceptCost || !interactive) throw new Error(WORKSPACE_SHAPE_EXPLICIT_ID);
+  let name = '';
+  try { name = String((await fetchName(local.workspaceId)) || ''); } catch (_error) { name = ''; }
+  // The name can come from an AI-generated purpose, and everything below reaches the terminal: sanitised.
+  name = sanitizeForTerminal(name || String(local.label || ''));
+  const id = sanitizeForTerminal(local.workspaceId);
+  const source = sanitizeForTerminal(describeSelectionSource(local).trim().replace(/^\(|\)$/g, '')) || 'a local binding';
+  const shown = name ? `"${name}" (${id})` : id;
+  say(`No --workspace-id was given. This directory is bound to ${shown}: ${source}.`);
+  const yes = await confirm(`Re-shape ${name ? `"${name}"` : `workspace ${id}`}? This starts an interview that is charged.`, false, process.stderr);
+  if (!yes) throw new Error('Nothing was started. Pass --workspace-id <id> to name the workspace.');
+  return local.workspaceId;
+}
+
 function isWorkspaceCommand(args) {
   if (args[0] !== 'workspace') return false;
-  if (['list', 'current', 'select', 'use', 'unbind', 'create', 'delete'].includes(args[1])) return true;
+  if (['list', 'current', 'select', 'use', 'unbind', 'create', 'delete', 'shape'].includes(args[1])) return true;
   return args[1] === 'invite' && ['create', 'list', 'revoke'].includes(args[2]);
 }
 
@@ -40,7 +71,7 @@ function workspaceOptions(payload) {
 }
 
 function positionalArgs(args, startIndex) {
-  const valueOptions = new Set(['--description', '--role', '--expires-in-days', '--max-uses']);
+  const valueOptions = new Set(['--description', '--role', '--expires-in-days', '--max-uses', '--answers', '--workspace-id']);
   const positional = [];
   for (let index = startIndex; index < args.length; index += 1) {
     if (valueOptions.has(args[index])) {
@@ -276,9 +307,41 @@ async function runWorkspaceCommand(args) {
         return;
       }
 
+      if (action === 'shape') {
+        // Re-shapes a team workspace you manage through the interview. resolveShapeTarget decides which: an
+        // explicit --workspace-id, or (at a terminal only, after a named yes) the bound workspace.
+        const requested = parseOption(args, '--workspace-id', '').trim();
+        const answersFile = parseOption(args, '--answers', '');
+        const acceptCost = parseFlag(args, '--accept-cost');
+        const targetWorkspaceId = await resolveShapeTarget({
+          requested,
+          local: requested ? null : resolveLocalWorkspaceSelection(),
+          answersFile,
+          acceptCost,
+          interactive: isInteractiveTerminal(),
+          fetchName: async (id) => {
+            const payload = await httpJson(teamBrainsUrl, 'GET', null, authHeaders);
+            const hit = getTeamBrains(payload).find((b) => b.workspaceId === id);
+            return hit ? hit.name : '';
+          },
+          askYesNo
+        });
+        return runWorkspaceInterview({ targetWorkspaceId, answersFile, acceptCost });
+      }
+
+      if (action === 'create' && parseFlag(args, '--interview')) {
+        // Creating through the interview takes no name (it asks what the workspace is for), and it never
+        // re-shapes: with no --workspace-id it always makes a new workspace.
+        if (positionalArgs(args, 2).length || parseOption(args, '--workspace-id', '')) throw new Error(WORKSPACE_CREATE_INTERVIEW_USAGE);
+        return runWorkspaceInterview({
+          answersFile: parseOption(args, '--answers', ''),
+          acceptCost: parseFlag(args, '--accept-cost')
+        });
+      }
+
       if (action === 'create') {
         const name = positionalArgs(args, 2).join(' ').trim();
-        if (!name) throw new Error('Usage: empirical workspace create <name> [--description <text>]');
+        if (!name) throw new Error('Usage: empirical workspace create <name> [--description <text>]  or  empirical workspace create --interview');
         const description = parseOption(args, '--description', '');
         const created = await httpJson(
           teamBrainsUrl,
@@ -394,5 +457,9 @@ module.exports = {
   isWorkspaceCommand,
   getWorkspaceCommandAuth,
   resolveWorkspaceTarget,
-  runWorkspaceCommand
+  runWorkspaceCommand,
+  WORKSPACE_CREATE_INTERVIEW_USAGE,
+  WORKSPACE_SHAPE_USAGE,
+  WORKSPACE_SHAPE_EXPLICIT_ID,
+  resolveShapeTarget
 };