logwork-cli 1.1.1 → 1.3.0

package/commands/quick.mjs

@@ -10,41 +10,56 @@ import {
 import * as ui from '../lib/ui.mjs';
 import { todayLocalDateISO } from '../lib/util.mjs';
 
+const QUICK_API = { addLogtime, fetchWorklogTasksForProject, getTodayTimesheetProjects };
+
 // `logwork quick [-m "what you did"]`: log one Resource Optimiser entry for
 // today with guided prompts (project -> worklog task -> description -> hours).
-export async function run(argv = []) {
+// The second argument of run and the options of runQuickLog are test seams;
+// the CLI uses the defaults.
+export async function run(argv = [], {
+  quickLog = runQuickLog,
+  quickUi = ui,
+  showIntro = intro,
+  print = console.log
+} = {}) {
   const { message, help } = parseQuickArgs(argv);
   if (help) {
-    console.log(formatQuickHelp());
+    print(formatQuickHelp());
     return 0;
   }
 
   try {
-    intro('Logwork quick');
-    const result = await runQuickLog({ message });
-    ui.showSuccess(result.dryRun
+    showIntro('Logwork quick');
+    const result = await quickLog({ message });
+    quickUi.showSuccess(result.dryRun
       ? 'DRY RUN: payload generated; no API write performed.'
       : 'Logwork submitted.');
     return 0;
   } catch (error) {
-    ui.showError(error);
+    quickUi.showError(error);
     return 1;
   }
 }
 
-export async function runQuickLog({ message = '' } = {}) {
-  const localDateISO = todayLocalDateISO();
-  let session = await openSession();
+export async function runQuickLog({
+  message = '',
+  quickUi = ui,
+  openSession: open = openSession,
+  api = QUICK_API,
+  today = todayLocalDateISO
+} = {}) {
+  const localDateISO = today();
+  let session = await open();
 
   let projects;
   try {
-    projects = await loadBookedProjects(session, localDateISO);
+    projects = await loadBookedProjects(session, localDateISO, api);
   } catch (error) {
     if (!isUnauthorized(error)) {
       throw error;
     }
-    session = await openSession({ forceLogin: true });
-    projects = await loadBookedProjects(session, localDateISO);
+    session = await open({ forceLogin: true });
+    projects = await loadBookedProjects(session, localDateISO, api);
   }
 
   const daySummaries = projects.map((project) => ({
@@ -52,8 +67,8 @@ export async function runQuickLog({ message = '' } = {}) {
     totalHours: project.loggedHours,
     ok: true
   }));
-  const project = await ui.chooseProject(projects, daySummaries);
-  const tasks = (await fetchWorklogTasksForProject(session.token, project.projectId)).map((task) => ({
+  const project = await quickUi.chooseProject(projects, daySummaries);
+  const tasks = (await api.fetchWorklogTasksForProject(session.token, project.projectId)).map((task) => ({
     taskId: task.id,
     name: task.name,
     typeOfWork: task.typeOfWork || 'other',
@@ -63,11 +78,11 @@ export async function runQuickLog({ message = '' } = {}) {
   if (!tasks.length) {
     throw new Error(`No worklog tasks are available for ${project.projectName}.`);
   }
-  const task = await ui.chooseTask(tasks);
-  const description = await ui.chooseMessageSource(message);
-  const hours = await ui.askHours(CONFIG.defaultHours);
+  const task = await quickUi.chooseTask(tasks);
+  const description = await quickUi.chooseMessageSource(message);
+  const hours = await quickUi.askHours(CONFIG.defaultHours);
 
-  await ui.confirmSubmit({
+  await quickUi.confirmSubmit({
     projectName: project.projectName,
     hours,
     taskName: task.name,
@@ -88,13 +103,13 @@ export async function runQuickLog({ message = '' } = {}) {
   };
 
   try {
-    return await addLogtime(session.token, entry);
+    return await api.addLogtime(session.token, entry);
   } catch (error) {
     if (!isUnauthorized(error)) {
       throw error;
     }
-    session = await openSession({ forceLogin: true });
-    return addLogtime(session.token, entry);
+    session = await open({ forceLogin: true });
+    return api.addLogtime(session.token, entry);
   }
 }
 
@@ -150,8 +165,8 @@ async function openSession({ forceLogin = false } = {}) {
   return { token, userId: getUserIdFromJwt(token) };
 }
 
-async function loadBookedProjects(session, localDateISO) {
-  const projects = await getTodayTimesheetProjects(session.token, session.userId, localDateISO);
+async function loadBookedProjects(session, localDateISO, api) {
+  const projects = await api.getTodayTimesheetProjects(session.token, session.userId, localDateISO);
   if (!projects.length) {
     throw new Error(`You have no booked project on ${localDateISO}.`);
   }

package/commands/reminder.mjs

@@ -1,5 +1,6 @@
 import { confirm, isCancel } from '@clack/prompts';
 import {
+  normalizeReminderRepos,
   normalizeReminderTime,
   REMINDER_TARGETS
 } from '../lib/reminder-config.mjs';
@@ -27,6 +28,7 @@ export function parseReminderArgs(args = []) {
     yes: false,
     json: false,
     home: undefined,
+    repos: undefined,
     help: false
   };
   for (let index = 0; index < rest.length; index += 1) {
@@ -44,6 +46,27 @@ export function parseReminderArgs(args = []) {
       index += 1;
       continue;
     }
+    if (arg === '--repo' || arg.startsWith('--repo=')) {
+      const value = arg === '--repo' ? rest[index + 1] : arg.slice('--repo='.length);
+      if (!value || (arg === '--repo' && value.startsWith('--'))) {
+        throw new Error('--repo requires a path.');
+      }
+      if (options.repos === null) {
+        throw new Error('--repo cannot be combined with --no-repos.');
+      }
+      options.repos = [...(options.repos || []), value];
+      if (arg === '--repo') {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === '--no-repos') {
+      if (options.repos?.length) {
+        throw new Error('--repo cannot be combined with --no-repos.');
+      }
+      options.repos = null;
+      continue;
+    }
     if (arg === '--yes' || arg === '-y') {
       options.yes = true;
       continue;
@@ -61,6 +84,16 @@ export function parseReminderArgs(args = []) {
   if (command !== 'enable' && options.time) {
     throw new Error('--time is only valid with reminder enable.');
   }
+  if (command !== 'enable' && options.repos !== undefined) {
+    throw new Error('--repo and --no-repos are only valid with reminder enable.');
+  }
+  if (Array.isArray(options.repos)) {
+    // Resolve against the directory the command runs in; the scheduled run
+    // starts in the helper home.
+    options.repos = normalizeReminderRepos(options.repos);
+  } else if (options.repos === null) {
+    options.repos = [];
+  }
   if (command !== 'run' && options.home) {
     throw new Error('--home is reserved for the OS reminder runner.');
   }
@@ -131,6 +164,7 @@ export async function runReminderCli(args = [], {
     result = await enable({
       time: options.time,
       target: options.target,
+      ...(options.repos !== undefined ? { repos: options.repos } : {}),
       confirm: true
     });
   } else if (options.command === 'disable') {
@@ -147,12 +181,17 @@ export async function runReminderCli(args = [], {
 
 export function formatReminderHelp() {
   return `Usage:
-  logwork reminder enable [--time HH:mm] [--target ro|jira|both] [--yes]
+  logwork reminder enable [--time HH:mm] [--target ro|jira|both]
+                          [--repo <path>]... [--no-repos] [--yes]
   logwork reminder status [--json]
   logwork reminder test [--target ro|jira|both] [--yes]
   logwork reminder disable [--yes]
 
-The reminder runs Monday-Friday at 17:00 by default. It uses launchd on macOS and Task Scheduler on Windows. RO compares logged and booked hours; Jira checks whether the current user has a worklog today.`;
+The reminder runs Monday-Friday at 17:00 by default. It uses launchd on macOS and Task Scheduler on Windows. RO compares logged and booked hours; Jira checks whether the current user has a worklog today.
+
+--repo (repeatable) sets the git repos whose commits today are counted when RO hours are missing, for example "Hôm nay: 5 commit trong 2 repo", and points to \`logwork commits today\` for a draft. Repos listed on project mappings are also used. --repo replaces the saved list; --no-repos clears it; without either the saved list is kept.
+
+The schedule stores the absolute path of the Node that ran \`reminder enable\`. After upgrading or removing that Node (nvm, Homebrew), run \`logwork reminder enable\` or \`logwork setup\` again; \`logwork reminder status\` warns when the path is gone.`;
 }
 
 async function requireInteractiveConfirmation({ isTTY, promptConfirm, message }) {

package/commands/setup.mjs

@@ -5,16 +5,22 @@ import { fileURLToPath } from 'node:url';
 import { redactText } from '../lib/auth-redaction.mjs';
 import { credentialStoreLabel } from '../lib/credential-store.mjs';
 import { npmInvocation } from '../lib/npm-command.mjs';
-import { helperHome } from '../lib/paths.mjs';
+import { writeRuntimeInfo } from '../lib/node-runtime.mjs';
+import { RUNTIME_INFO_FILE_NAME, helperHome } from '../lib/paths.mjs';
+import { mcpArgs, resolveLaunchCommand, writeLauncher } from '../lib/launcher.mjs';
 import {
+  MCP_LAUNCHER_NOTE,
+  MCP_NODE_PATH_NOTE,
   MCP_SERVER_NAME,
-  defaultMcpServerPath,
+  formatClaudeMcpAddCommand,
   formatCodexToml,
   stdioMcpServersConfig,
   vscodeMcpConfig
 } from '../lib/manual-mcp.mjs';
+import { createMcpInstallContext, describeMcpPlan, planMcpInstall } from '../lib/mcp-install.mjs';
 import { loadReminderConfig } from '../lib/reminder-config.mjs';
 import { installReminderScheduler } from '../lib/reminder-scheduler.mjs';
+import { formatMcpInstallResults, isInteractiveTerminal, runMcpInstall } from './mcp.mjs';
 
 // Package name before the rename. Its global install provides a `logwork` bin
 // that would block `npm link` of logwork-cli, so setup removes it first.
@@ -27,8 +33,9 @@ const EXCLUDED_DIRS = new Set([
 ]);
 
 // `logwork setup`: copy this package into ~/.logwork-cli, install its
-// dependencies, link the `logwork` command, refresh a migrated reminder, and
-// print the MCP configs.
+// dependencies, link the `logwork` command, write the launcher, refresh a
+// migrated reminder, and add or update the `logwork` entry in the MCP clients
+// found on this machine.
 export async function run(argv = []) {
   if (argv.includes('--help') || argv.includes('-h')) {
     console.log(formatSetupHelp());
@@ -43,16 +50,19 @@ export async function run(argv = []) {
 
 export function formatSetupHelp() {
   return `Usage:
-  logwork setup [--login|--no-login]
+  logwork setup [--yes] [--no-mcp-install] [--login|--no-login]
 
-Installs the runtime to ~/.logwork-cli, links the \`logwork\` command, and prints
-MCP configs for Cursor, Antigravity, Claude Code, Codex and VS Code.
-Settings, mappings and the login session from an older logwork-helper install
-are carried over automatically.
+Installs the runtime to ~/.logwork-cli, links the \`logwork\` command, and adds
+the "logwork" MCP server to the clients it finds (Claude Code, Cursor, Codex,
+VS Code, Google Antigravity), asking once per client. Each edited config is
+backed up first. Settings, mappings and the login session from an older
+logwork-helper install are carried over automatically.
 
 Options:
-  --login     Log in to Resource Optimiser after installing
-  --no-login  Do not ask to log in`;
+  --yes, -y         Update every detected MCP client without asking
+  --no-mcp-install  Do not touch MCP client configs
+  --login           Log in to Resource Optimiser after installing
+  --no-login        Do not ask to log in`;
 }
 
 export async function installUserRuntime({
@@ -65,7 +75,10 @@ export async function installUserRuntime({
   installFn = installDependencies,
   linkFn = linkGlobalBinaries,
   authFn = maybeRunAuthLogin,
+  runtimeInfoFn = recordRuntimeInfo,
+  launcherFn = writeRuntimeLauncher,
   reminderFn = refreshReminderSchedule,
+  mcpInstallFn = installMcpClients,
   printFn = printMcpInstructions
 }) {
   await mkdirFn(targetDir, { recursive: true });
@@ -76,29 +89,98 @@ export async function installUserRuntime({
   await installFn(targetDir);
   const linkResult = await linkFn(targetDir);
   const authResult = await authFn(targetDir, options);
+  await runtimeInfoFn(targetDir);
+  await launcherFn(targetDir);
   const reminderResult = await reminderFn(targetDir);
-  await printFn(targetDir, authResult, linkResult, cleanupResult, reminderResult);
+  const mcpResult = await mcpInstallFn(targetDir, options);
+  await printFn(targetDir, authResult, linkResult, cleanupResult, reminderResult, mcpResult);
 
   return {
     targetDir,
     authResult,
     linkResult,
     cleanupResult,
-    reminderResult
+    reminderResult,
+    mcpResult
   };
 }
 
-// A reminder enabled by an older install still points at the old runtime.
-// Re-register it so the OS scheduler runs this runtime (and the legacy entry
-// is removed by installReminderScheduler).
-async function refreshReminderSchedule(targetDir) {
+// macOS/Linux: <home>/bin/logwork-launch, which MCP configs and the reminder
+// run. It must exist before the reminder is re-registered.
+export async function writeRuntimeLauncher(targetDir, {
+  nodePath = process.execPath,
+  platform = process.platform,
+  writeFn = writeLauncher
+} = {}) {
+  return writeFn({ home: targetDir, nodePath, platform });
+}
+
+// Adds or updates the `logwork` entry in the detected MCP clients:
+// - --no-mcp-install: skipped;
+// - --yes: every detected client, without asking;
+// - a terminal: one yes/no per client that needs a change;
+// - otherwise (npm exec from `logwork update`, CI): only the plan.
+export async function installMcpClients(targetDir, options = {}, {
+  interactive = isInteractiveTerminal(),
+  ctx = createMcpInstallContext({ home: targetDir }),
+  install = runMcpInstall,
+  plan = planMcpInstall
+} = {}) {
+  if (options.mcpInstall === false) {
+    return { mode: 'skipped', launch: ctx.launch };
+  }
   try {
-    const config = await loadReminderConfig();
+    if (options.yes || interactive) {
+      const result = await install({ ctx, yes: Boolean(options.yes), interactive });
+      return { mode: 'installed', launch: ctx.launch, results: result.results };
+    }
+    const plans = await plan(ctx);
+    return { mode: 'planned', launch: ctx.launch, plans, lines: plans.flatMap((item) => describeMcpPlan(item, ctx)) };
+  } catch (error) {
+    return { mode: 'error', launch: ctx.launch, error: error.message };
+  }
+}
+
+// Records the node that ran setup. The macOS/Linux launcher tries it first;
+// on Windows the MCP configs and the reminder run it (or the nvm-windows
+// symlink). doctor and reminder status compare it with the current Node.
+// Best effort: a failed write must not fail the install.
+export async function recordRuntimeInfo(targetDir, {
+  nodePath = process.execPath,
+  nodeVersion = process.version,
+  writeFn = writeRuntimeInfo,
+  readFileFn = fs.readFile
+} = {}) {
+  try {
+    const manifest = JSON.parse(await readFileFn(join(targetDir, 'package.json'), 'utf8'));
+    return await writeFn({
+      path: join(targetDir, RUNTIME_INFO_FILE_NAME),
+      nodePath,
+      nodeVersion,
+      version: manifest.version || null
+    });
+  } catch {
+    return null;
+  }
+}
+
+// A reminder enabled by an older install still points at the old runtime, or
+// at a Node that nvm or Homebrew removed. Re-register it so the OS scheduler
+// runs this runtime with the current node (and the legacy entry is removed by
+// installReminderScheduler).
+// The schedule runs the launcher (macOS) or a stable node.exe (Windows).
+export async function refreshReminderSchedule(targetDir, {
+  nodePath = process.execPath,
+  loadConfig = loadReminderConfig,
+  install = installReminderScheduler
+} = {}) {
+  try {
+    const config = await loadConfig();
     if (!config?.enabled) {
       return null;
     }
-    await installReminderScheduler(config, { home: targetDir });
-    return { ok: true };
+    await install(config, { home: targetDir, nodePath });
+    return { ok: true, nodePath };
   } catch (error) {
     return { ok: false, error: error.message };
   }
@@ -407,6 +489,8 @@ export async function findCommandOnPath(commandName, {
 
 export function parseSetupUserArgs(args = []) {
   let loginMode = 'prompt';
+  let yes = false;
+  let mcpInstall = true;
 
   for (const arg of args) {
     if (arg === '--login') {
@@ -417,10 +501,18 @@ export function parseSetupUserArgs(args = []) {
       loginMode = 'skip';
       continue;
     }
+    if (arg === '--yes' || arg === '-y') {
+      yes = true;
+      continue;
+    }
+    if (arg === '--no-mcp-install') {
+      mcpInstall = false;
+      continue;
+    }
     throw new Error(`Unknown setup option: ${arg}`);
   }
 
-  return { loginMode };
+  return { loginMode, yes, mcpInstall };
 }
 
 async function maybeRunAuthLogin(targetDir, { loginMode }) {
@@ -491,13 +583,14 @@ function runAuthLogin(targetDir) {
   });
 }
 
-function printMcpInstructions(targetDir, authResult = null, linkResult = null, cleanupResult = null, reminderResult = null) {
+function printMcpInstructions(targetDir, authResult = null, linkResult = null, cleanupResult = null, reminderResult = null, mcpResult = null) {
   console.log(formatSetupUserInstructions({
     targetDir,
     authResult,
     linkResult,
     cleanupResult,
-    reminderResult
+    reminderResult,
+    mcpResult
   }));
 }
 
@@ -507,10 +600,14 @@ export function formatSetupUserInstructions({
   linkResult = null,
   cleanupResult = null,
   reminderResult = null,
-  platform = process.platform
+  mcpResult = null,
+  platform = process.platform,
+  nodePath = process.execPath,
+  env = process.env,
+  launch = mcpResult?.launch || resolveLaunchCommand({ platform, home: targetDir, execPath: nodePath, env })
 } = {}) {
-  const entryPath = resolve(targetDir, 'bin', 'logwork.mjs');
   const storeLabel = credentialStoreLabel({ platform });
+  const mcp = formatMcpSection({ mcpResult, launch, platform });
   const sections = [
     `logwork-cli installed to ${targetDir}.`,
     '',
@@ -526,27 +623,18 @@ export function formatSetupUserInstructions({
     formatTerminalCommandInstructions(linkResult),
     '',
     'Next steps',
-    ...formatNextSteps(authResult),
+    ...formatNextSteps(authResult, mcp.manual),
     '',
-    `MCP config (server name "${MCP_SERVER_NAME}", runs: node ${entryPath} mcp)`,
-    '',
-    'Cursor / Antigravity / Claude Code (.mcp.json):',
-    JSON.stringify(stdioMcpServersConfig(entryPath), null, 2),
-    '',
-    'Codex config.toml:',
-    formatCodexToml(entryPath),
-    '',
-    'GitHub Copilot / VS Code mcp.json:',
-    JSON.stringify(vscodeMcpConfig(entryPath), null, 2),
+    ...mcp.lines,
     '',
     'AI agent skill (log work from your commits)',
     '- Claude Code / Codex: run `logwork skill install`.',
     '- Other MCP clients: use the MCP prompt "log_from_commits".',
     '',
     'Verify',
-    '- Restart or reload your IDE MCP tools after pasting config.',
+    '- Restart or reload your IDE MCP tools after a config change.',
     '- In the IDE, ask: Check my logwork for this week.',
-    '- An old "logwork-helper" MCP entry can be deleted; it points at the old runtime.',
+    '- `logwork mcp status` shows which clients have a current "logwork" entry.',
     '',
     'Safety',
     '- Do not paste passwords, 2FA codes, Bearer tokens, cookies, or raw curl auth logs into AI chat.',
@@ -557,6 +645,70 @@ export function formatSetupUserInstructions({
   return sections.join('\n');
 }
 
+// The MCP part of the setup summary. `manual` is true when the user still has
+// to paste a config somewhere.
+function formatMcpSection({ mcpResult, launch, platform }) {
+  const header = `MCP server "${MCP_SERVER_NAME}" runs: ${[launch.command, ...mcpArgs(launch)].join(' ')}`;
+  if (mcpResult?.mode === 'installed' && mcpResult.results?.length) {
+    const failed = mcpResult.results.some((result) => result.status === 'failed');
+    return {
+      manual: failed,
+      lines: [header, 'MCP clients', ...formatMcpInstallResults(mcpResult.results)]
+    };
+  }
+  if (mcpResult?.mode === 'planned') {
+    const pending = (mcpResult.plans || []).some((plan) => plan.action === 'add' || plan.action === 'update');
+    if (mcpResult.plans?.length) {
+      return {
+        manual: false,
+        lines: [
+          header,
+          'MCP clients (not changed: this is not an interactive terminal)',
+          ...(mcpResult.lines || []),
+          ...(pending ? ['To apply: run `logwork mcp install` (asks per client) or `logwork mcp install --yes`.'] : [])
+        ]
+      };
+    }
+  }
+  if (mcpResult?.mode === 'skipped') {
+    return {
+      manual: false,
+      lines: [header, 'MCP clients: not changed (--no-mcp-install). Run `logwork mcp install` to add or update them, or `logwork mcp status` to check.']
+    };
+  }
+  // No client found, an error, or an older caller: print every snippet.
+  const lines = [header];
+  if (mcpResult?.mode === 'error') {
+    lines.push(`MCP clients: could not update automatically (${redactText(mcpResult.error || 'unknown error')}).`);
+  } else if (mcpResult) {
+    lines.push('MCP clients: none found (Claude Code, Cursor, Codex, VS Code, Google Antigravity).');
+  }
+  lines.push(...formatManualMcpSnippets(launch, { platform }));
+  return { manual: true, lines };
+}
+
+export function formatManualMcpSnippets(launch, { platform = process.platform } = {}) {
+  const note = launch.stable ? (launch.kind === 'launcher' ? MCP_LAUNCHER_NOTE : '') : MCP_NODE_PATH_NOTE;
+  return [
+    'Manual MCP config (paste into your client):',
+    ...(note ? [note] : []),
+    '',
+    'Cursor / Antigravity / Claude Code (.mcp.json):',
+    JSON.stringify(stdioMcpServersConfig(launch), null, 2),
+    '',
+    'Claude Code CLI:',
+    formatClaudeMcpAddCommand(launch, { platform }),
+    '',
+    'Codex config.toml:',
+    formatCodexToml(launch),
+    '',
+    'GitHub Copilot / VS Code mcp.json:',
+    JSON.stringify(vscodeMcpConfig(launch), null, 2),
+    '',
+    'An old "logwork-helper" MCP entry can be deleted; it points at the old runtime.'
+  ];
+}
+
 function formatAuthStatus(authResult) {
   if (authResult?.ok) {
     return 'completed';
@@ -567,7 +719,7 @@ function formatAuthStatus(authResult) {
   return 'not run';
 }
 
-function formatNextSteps(authResult) {
+function formatNextSteps(authResult, manualMcp = true) {
   const steps = [];
   let index = 1;
   if (!authResult?.ok) {
@@ -575,9 +727,12 @@ function formatNextSteps(authResult) {
     steps.push('   logwork login');
     index += 1;
   }
-  steps.push(`${index}. Paste one MCP config below into your IDE.`);
-  steps.push(`${index + 1}. Restart or reload your IDE MCP tools.`);
-  steps.push(`${index + 2}. Verify with: Check my logwork for this week.`);
+  if (manualMcp) {
+    steps.push(`${index}. Paste the MCP config below into your IDE (or run \`logwork mcp install\`).`);
+    index += 1;
+  }
+  steps.push(`${index}. Restart or reload your IDE MCP tools.`);
+  steps.push(`${index + 1}. Verify with: Check my logwork for this week.`);
   return steps;
 }
 

package/commands/tui.mjs

@@ -43,6 +43,7 @@ Common commands inside the UI:
   /reconcile this-week      Compare RO and Jira
   /projects                 List RO projects
   /map SCB 5234             Map a ticket prefix to a project
+  /map --repo . 5234        Map this git repo to a project (commit drafts)
   /mcp                      Show MCP config for an IDE
   /history                  Local apply history
 

package/docs/advanced.md

@@ -27,7 +27,7 @@ Supported overrides:
 ```text
 LOGWORK_PROFILE            (LOGWORK_HELPER_PROFILE still accepted)
 LOGWORK_HOME               (local state directory; LOGWORK_HELPER_HOME still accepted)
-LOGWORK_DRY_RUN=1          (RO writes return the request body instead of calling the API)
+LOGWORK_DRY_RUN=1          (RO and Jira writes return the request instead of calling the API)
 LOGWORK_API_BASE
 LOGWORK_LOGIN_URL
 LOGWORK_JIRA_BASE_URL
@@ -78,9 +78,9 @@ To install and start auth immediately:
 logwork setup --login
 ```
 
-Use `--no-login` when installing in scripts or CI.
+Use `--no-login` when installing in scripts or CI. Add `--no-mcp-install` to leave MCP client configs alone, or `--yes` to update every detected client without asking. Without a terminal and without `--yes`, setup only prints what `logwork mcp install` would change.
 
-`logwork setup` copies the package into `~/.logwork-cli`, runs `npm ci --omit=dev` there, removes a globally installed `logwork-helper` package (its `logwork` bin would block linking), runs `npm link`, re-registers an enabled reminder, and prints MCP configs.
+`logwork setup` copies the package into `~/.logwork-cli`, runs `npm ci --omit=dev` there, removes a globally installed `logwork-helper` package (its `logwork` bin would block linking), runs `npm link`, writes `runtime.json` and the launcher (`bin/logwork-launch`, macOS), re-registers an enabled reminder, and adds or updates the `logwork` entry in the detected MCP clients ([details](mcp-setup.md#automatic-setup)). It prints the manual snippets only for clients it could not update, or when it found none.
 
 ## Update
 
@@ -91,7 +91,7 @@ logwork update install           # interactive confirmation
 logwork update install --version 0.3.1 --yes
 ```
 
-The installer accepts only the version currently published under npm's `latest` tag. It runs `npm exec --package=logwork-cli@<version> -- logwork setup --no-login` with a fixed argument list. Then it verifies the copied `package.json` version in `~/.logwork-cli`.
+The installer accepts only the version currently published under npm's `latest` tag. It runs `npm exec --package=logwork-cli@<version> -- logwork setup --no-login` with a fixed argument list. Then it verifies the copied `package.json` version in `~/.logwork-cli`. That setup runs without a terminal, so it does not edit MCP configs; they keep working because they point at the launcher (macOS) or a stable `node.exe` (Windows). `logwork mcp status` shows whether anything needs `logwork mcp install`.
 
 Project mappings, drafts, apply history, update cache, and OS credential-store records are preserved.
 
@@ -222,6 +222,8 @@ Useful commands inside the session:
 /projects
 /projects 5234
 /map SCB 5234
+/map --repo
+/map --repo ~/code/fcs GKE Fair Chem
 /history
 /diagnostics
 ```
@@ -271,8 +273,8 @@ Inside `logwork`, use `/history`, `/history ro`, `/history jira`, or `/history b
 
 ## Troubleshooting
 
-- **IDE does not show tools:** restart or reload the MCP client. Check that the config runs `node ~/.logwork-cli/bin/logwork.mjs mcp` (on Windows, `%USERPROFILE%\.logwork-cli\bin\logwork.mjs`) and that the server name is `logwork`.
-- **Tools show old names such as `preview_logwork_batch`:** the IDE is still connected to the old `logwork-helper` entry. Replace that entry with the config printed by `logwork setup`; the [tool name table](mcp-setup.md#tool-name-changes-from-logwork-helper) lists the renames.
+- **IDE does not show tools:** run `logwork mcp status`. If the client's entry is missing or stale, run `logwork mcp install`, then restart or reload the MCP client. The entry should run `~/.logwork-cli/bin/logwork-launch mcp` (on Windows, `node.exe %USERPROFILE%\.logwork-cli\bin\logwork.mjs mcp`) under the server name `logwork`. `logwork doctor` also checks that the launcher finds a usable Node.
+- **Tools show old names such as `preview_logwork_batch`:** the IDE is still connected to the old `logwork-helper` entry. `logwork mcp install` removes it; the [tool name table](mcp-setup.md#tool-name-changes-from-logwork-helper) lists the renames.
 - **`logwork: command not found` after `logwork setup`:** open a new terminal first. If it still fails, run `npm install -g logwork-cli`, or make sure your npm global bin directory is on `PATH`.
 - **`npm link` fails with `EEXIST` on `logwork`:** an old global `logwork-helper` package still owns the bin. Run `npm rm -g logwork-helper`, then `logwork setup` again.
 - **Not authenticated to Resource Optimiser:** run `logwork login`, or ask the assistant to call `login`. Enter secrets only in the terminal.
@@ -285,11 +287,20 @@ Inside `logwork`, use `/history`, `/history ro`, `/history jira`, or `/history b
 
 ## Dry Run
 
-`LOGWORK_DRY_RUN=1` makes Resource Optimiser writes return the request body instead of calling the API. Reads still hit the API.
+`LOGWORK_DRY_RUN=1` makes every Resource Optimiser and Jira write return the request (`{ dryRun: true, method, path, body }`) instead of calling the API. The request never contains the token or the `Authorization` header. Reads still hit the API: Jira issue lookup and the duplicate-worklog check still call Jira, and RO previews still read RO.
+
+What a dry run reports:
+
+- RO apply summaries start with `DRY RUN`; edit, resubmit and delete return `status: "dry_run"`.
+- Jira apply (`log_jira_work` with `confirm: true`, or the terminal UI `/apply`) returns `status: "dry_run"`, `dryRun: true`, one `dry_run` result per entry with its `request`, and a summary that starts with `DRY RUN (LOGWORK_DRY_RUN=1)`.
+- Apply history records a Jira dry run with status `dry_run` and `dryRun: true` entries. They are not counted as submitted.
+- The terminal UI status bar shows `DRY RUN`.
 
 ```bash
 LOGWORK_DRY_RUN=1 logwork quick -m "Dry run task"
 LOGWORK_DRY_RUN=1 logwork edit 304032 --desc "Dry run" --yes
+npm run dry-run                     # terminal UI, RO and Jira writes stubbed
+LOGWORK_DRY_RUN=1 logwork mcp       # MCP server, RO and Jira writes stubbed
 ```
 
 In Windows PowerShell: