logwork-cli 1.2.0 → 1.3.0

package/commands/setup.mjs

@@ -1,21 +1,26 @@
 import { constants as fsConstants, promises as fs } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { delimiter, dirname, join, relative, resolve, win32 } from 'node:path';
+import { delimiter, dirname, join, relative, resolve } from 'node:path';
 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 { 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,
+  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.
@@ -28,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());
@@ -44,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({
@@ -67,7 +76,9 @@ export async function installUserRuntime({
   linkFn = linkGlobalBinaries,
   authFn = maybeRunAuthLogin,
   runtimeInfoFn = recordRuntimeInfo,
+  launcherFn = writeRuntimeLauncher,
   reminderFn = refreshReminderSchedule,
+  mcpInstallFn = installMcpClients,
   printFn = printMcpInstructions
 }) {
   await mkdirFn(targetDir, { recursive: true });
@@ -79,21 +90,61 @@ export async function installUserRuntime({
   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
   };
 }
 
-// Records the node that ran setup (the one the printed MCP configs and the
-// reminder use), so doctor and reminder status can spot a removed or switched
-// Node later. Best effort: a failed write must not fail the install.
+// 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 {
+    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,
@@ -117,6 +168,7 @@ export async function recordRuntimeInfo(targetDir, {
 // 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,
@@ -437,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') {
@@ -447,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 }) {
@@ -521,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
   }));
 }
 
@@ -537,13 +600,14 @@ export function formatSetupUserInstructions({
   linkResult = null,
   cleanupResult = null,
   reminderResult = null,
+  mcpResult = null,
   platform = process.platform,
-  nodePath = process.execPath
+  nodePath = process.execPath,
+  env = process.env,
+  launch = mcpResult?.launch || resolveLaunchCommand({ platform, home: targetDir, execPath: nodePath, env })
 } = {}) {
-  const entryPath = platform === 'win32'
-    ? win32.resolve(targetDir, 'bin', 'logwork.mjs')
-    : resolve(targetDir, 'bin', 'logwork.mjs');
   const storeLabel = credentialStoreLabel({ platform });
+  const mcp = formatMcpSection({ mcpResult, launch, platform });
   const sections = [
     `logwork-cli installed to ${targetDir}.`,
     '',
@@ -559,28 +623,18 @@ export function formatSetupUserInstructions({
     formatTerminalCommandInstructions(linkResult),
     '',
     'Next steps',
-    ...formatNextSteps(authResult),
-    '',
-    `MCP config (server name "${MCP_SERVER_NAME}", runs: ${nodePath} ${entryPath} mcp)`,
-    MCP_NODE_PATH_NOTE,
+    ...formatNextSteps(authResult, mcp.manual),
     '',
-    'Cursor / Antigravity / Claude Code (.mcp.json):',
-    JSON.stringify(stdioMcpServersConfig(entryPath, { nodePath }), null, 2),
-    '',
-    'Codex config.toml:',
-    formatCodexToml(entryPath, { nodePath }),
-    '',
-    'GitHub Copilot / VS Code mcp.json:',
-    JSON.stringify(vscodeMcpConfig(entryPath, { nodePath }), 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.',
@@ -591,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';
@@ -601,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) {
@@ -609,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/docs/advanced.md

@@ -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,7 +222,8 @@ Useful commands inside the session:
 /projects
 /projects 5234
 /map SCB 5234
-/map --repo . 5234
+/map --repo
+/map --repo ~/code/fcs GKE Fair Chem
 /history
 /diagnostics
 ```
@@ -272,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.

package/docs/mcp-setup.md

@@ -1,81 +1,130 @@
 # MCP Setup
 
-`logwork setup` prints copy-ready configs that use your real path. You can also open the terminal UI with `logwork` and type `/mcp`, or `/mcp <client>` for a single client.
+Run `logwork setup` and answer yes for each client. That is the whole setup: you do not edit MCP JSON or TOML yourself, and you do not need to know where Node is installed.
 
 For the full RO/Jira/Both processing model, mapping, reconciliation, history, reminders and updates, see the [operations guide](operations-guide.md).
 
-Every client runs `<absolute path to node> <home>/.logwork-cli/bin/logwork.mjs mcp` under the server name `logwork`.
+## Automatic Setup
 
-Both paths are absolute:
-- The entry is `bin/logwork.mjs` instead of the `logwork` command, because GUI IDEs often start without the npm global bin directory on `PATH`.
-- The `command` is the absolute path of your Node binary instead of a bare `node`. Cursor or VS Code started from the Dock, Finder or Start menu usually does not get the `PATH` that nvm (or another version manager) sets up in your shell, so `node` is not found and the server never starts.
+`logwork setup` (and `logwork mcp install` at any time later) looks for these clients and adds or updates the `logwork` server in each one it finds. A client counts as found only when its config directory or CLI exists; setup never creates config for a client you do not have.
 
-`logwork setup` and `/mcp` print both paths for the Node that ran them (`process.execPath`). To find it yourself, run `which node` (macOS) or `(Get-Command node).Source` (PowerShell).
+| Client | Detected by | What is changed |
+|---|---|---|
+| Claude Code | `claude` on `PATH`, or `~/.claude.json` | `claude mcp remove --scope user logwork`, then `claude mcp add --scope user logwork -- <command> <args>`. Without the CLI: the top-level `mcpServers` in `~/.claude.json`. |
+| Cursor | `~/.cursor` | `mcpServers.logwork` in `~/.cursor/mcp.json` |
+| Codex | `~/.codex` | the `[mcp_servers.logwork]` table in `~/.codex/config.toml` |
+| VS Code (user) | `~/Library/Application Support/Code/User` (macOS), `%APPDATA%\Code\User` (Windows) | `servers.logwork` (`"type": "stdio"`) in `mcp.json` there |
+| Google Antigravity | `~/.gemini/antigravity` | `mcpServers.logwork` in `~/.gemini/antigravity/mcp_config.json` |
+
+How files are edited:
+- Each file is read, parsed and merged. Only the `logwork` entry changes; other servers and settings stay as they are. Extra fields you added to the `logwork` entry (such as `env`) are kept, except in Codex, where the whole `[mcp_servers.logwork]` table (with sub-tables such as `[mcp_servers.logwork.env]`) is replaced.
+- An old `logwork-helper` entry is removed. In Claude Code, a stale project-scope (`--scope local`) `logwork` entry is removed too, because it would hide the user-scope one.
+- Before the first change, the file is copied to `<file>.logwork-backup-<YYYYMMDDHHmmss>` next to it. Then the new file is written atomically. A symlinked config is written through the link.
+- When the entry is already current, nothing is written and no backup is made.
+- When a file does not parse cleanly (JSON with comments or trailing commas, TOML with an unusual layout such as an inline `mcp_servers` table), it is not touched. The result says "could not update automatically" and shows the snippet to paste.
+
+Commands:
+
+```bash
+logwork mcp status                     # per client: current, stale (and why), missing, leftover logwork-helper
+logwork mcp install                    # asks once per client that needs a change (default: yes)
+logwork mcp install --client cursor    # only some clients (repeatable: claude, cursor, codex, vscode, antigravity)
+logwork mcp install --dry-run          # show the planned changes, write nothing
+logwork mcp install --yes              # no questions
+logwork setup --yes                    # setup, updating every detected client without asking
+logwork setup --no-mcp-install         # setup without touching MCP configs
+```
+
+When setup does not run in a terminal (for example from `logwork update`), it only prints what `logwork mcp install` would change.
+
+`logwork doctor` includes the same per-client check.
+
+## What The Configs Run
+
+Every client runs one command under the server name `logwork`. The command never names a Node version, so `nvm install`, `brew upgrade node` or a new Node installer do not break it:
+
+- **macOS:** `~/.logwork-cli/bin/logwork-launch mcp`. `logwork setup` writes this small `sh` script. It starts `~/.logwork-cli/bin/logwork.mjs` with the first Node 22+ it finds, in this order:
+  1. the Node that ran `logwork setup`;
+  2. `node` on `PATH`;
+  3. the newest nvm Node (`$NVM_DIR` or `~/.nvm`);
+  4. Volta (`~/.volta/bin/node`) and the fnm default;
+  5. `/opt/homebrew/bin/node`, `/usr/local/bin/node`.
+
+  If none is found, it prints one line ("install Node.js 22 or newer, or run `logwork setup` again") and exits with code 127.
+- **Windows:** `<node.exe> %USERPROFILE%\.logwork-cli\bin\logwork.mjs mcp`. GUI clients would need `cmd /c` to run a `.cmd` launcher, so the config uses a stable `node.exe` instead:
+  - when Node runs from an nvm-windows version folder and `NVM_SYMLINK` is set, `%NVM_SYMLINK%\node.exe`, which follows `nvm use`;
+  - otherwise the Node that ran setup, usually `C:\Program Files\nodejs\node.exe`, which an installer upgrade keeps.
+
+  With any other Node location (Scoop, a portable zip), re-run `logwork setup` after moving or upgrading Node.
+
+The paths are absolute because GUI IDEs (started from the Dock, Finder or Start menu) often do not get your shell's `PATH`, so a bare `node` or `logwork` would not be found.
+
+## Manual Setup (Fallback)
 
-If Node is upgraded or moved (`nvm uninstall`, `brew upgrade node`, a new installer), the old path stops working. Re-run `logwork setup` and paste the new config. `logwork doctor` warns when the Node recorded by setup no longer exists.
+Use this only for a client that `logwork setup` does not support, or one whose file it could not update. `logwork setup` prints the snippet for each client it could not update. You can also open the terminal UI with `logwork` and type `/mcp`, or `/mcp <client>` for a single client; both print your real paths.
 
-The examples use `/Users/<user>` and `<absolute path to node>` as placeholders. With nvm on macOS the Node path looks like `/Users/<user>/.nvm/versions/node/v24.x.y/bin/node`; with Homebrew, `/opt/homebrew/bin/node`. On Windows, use the paths printed by `logwork setup` or `/mcp`, for example `C:\\Program Files\\nodejs\\node.exe` and `C:\\Users\\<user>\\.logwork-cli\\bin\\logwork.mjs` inside JSON or TOML strings.
+The examples use `/Users/<user>` as a placeholder. On Windows, use the paths printed by `logwork setup` or `/mcp`, for example `"command": "C:\\Program Files\\nodejs\\node.exe"` and `"args": ["C:\\Users\\<user>\\.logwork-cli\\bin\\logwork.mjs", "mcp"]` inside JSON or TOML strings.
 
-## Cursor / Google Antigravity
+### Cursor / Google Antigravity
 
-Cursor MCP settings, or `~/.gemini/antigravity/mcp_config.json`:
+`~/.cursor/mcp.json`, or `~/.gemini/antigravity/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
     "logwork": {
-      "command": "<absolute path to node>",
-      "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+      "command": "/Users/<user>/.logwork-cli/bin/logwork-launch",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-## Codex
+### Codex
 
 `~/.codex/config.toml`, or project `.codex/config.toml`:
 
 ```toml
 [mcp_servers.logwork]
-command = "<absolute path to node>"
-args = ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+command = "/Users/<user>/.logwork-cli/bin/logwork-launch"
+args = ["mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 ```
 
-## GitHub Copilot / VS Code
+### GitHub Copilot / VS Code
 
-Workspace `.vscode/mcp.json`, or your VS Code user MCP config:
+Workspace `.vscode/mcp.json`, or your VS Code user `mcp.json`:
 
 ```json
 {
   "servers": {
     "logwork": {
       "type": "stdio",
-      "command": "<absolute path to node>",
-      "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+      "command": "/Users/<user>/.logwork-cli/bin/logwork-launch",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-## Claude Code
+### Claude Code
 
 ```bash
-claude mcp add --transport stdio logwork -- "<absolute path to node>" "/Users/<user>/.logwork-cli/bin/logwork.mjs" mcp
+claude mcp add --transport stdio --scope user logwork -- ~/.logwork-cli/bin/logwork-launch mcp
 ```
 
 From Windows PowerShell:
 
 ```powershell
-claude mcp add --transport stdio logwork -- 'C:\Program Files\nodejs\node.exe' 'C:\Users\<user>\.logwork-cli\bin\logwork.mjs' mcp
+claude mcp add --transport stdio --scope user logwork -- 'C:\Program Files\nodejs\node.exe' 'C:\Users\<user>\.logwork-cli\bin\logwork.mjs' mcp
 ```
 
 Or add the Cursor JSON above to the project `.mcp.json`.
 
-Templates are also in [examples/mcp](../examples/mcp/).
+Templates (macOS form) are also in [examples/mcp](../examples/mcp/); on Windows, use the paths printed by `/mcp`.
 
-If you used `logwork-helper` before, delete its old MCP entry. It points at `~/.logwork-helper/mcp-server.mjs`, which is the old runtime.
+If you used `logwork-helper` before and edit configs by hand, delete its old MCP entry. It points at `~/.logwork-helper/mcp-server.mjs`, which is the old runtime.
 
 ## Exposed Tools
 
@@ -95,7 +144,7 @@ Previews expire after 1 hour. They are also lost when the server restarts.
 | Group | Tool | Kind | Purpose |
 |---|---|---|---|
 | Read | `get_logwork` | read-only | Booked vs logged RO hours by day and project, with entries (`logworkId`, worklog task, description, status). |
-| Read | `draft_from_commits` | read-only | Your git commits (all branches, your author) for a period in the given `repos`, grouped per day into draft lines with a suggested worklog task, an RO project (repo mapping, else ticket/keyword mappings and bookings) and hours that fill each project's remaining booked time. Returns `draftText` and `projectOverrides` for `log_work`, and `unmappedRepos`. |
+| Read | `draft_from_commits` | read-only | Your git commits (all branches, your author) for a period in the given `repos`, grouped per day into draft lines with a suggested worklog task, an RO project (repo mapping, else ticket/keyword mappings and bookings) and hours that fill each project's remaining booked time. Returns `draftText` and `projectOverrides` for `log_work`, `unmappedRepos`, and `repoSuggestions` (likely project per unmapped repo, with reasons) plus `projectCandidates`. |
 | Read | `list_projects` | read-only | RO memberships (`projectMemberId`, `projectId`, `projectName`) and local mappings. |
 | Read | `list_tasks` | read-only | RO worklog task catalog for one `projectId`: id, name, type of work, and when to use each task. |
 | Read | `get_jira_issue` | read-only | Jira issue key, summary and status. |
@@ -198,7 +247,10 @@ Expected flow:
    - Each line gets a project. A `map_project` mapping whose `repos` holds the repo comes first; then ticket/keyword mappings and that day's booked projects.
    - Each project's remaining hours are split across its own lines and never exceeded. Lines without a project share the room of booked projects that no line claimed.
    - It returns `draftText`, plus `projectOverrides` (preview entry id → `projectMemberId`) for each line with a project.
-   - It also returns `unmappedRepos`. For those, the assistant asks which project the repo belongs to and offers `map_project` with `repos`.
+   - It also returns `unmappedRepos` (repo paths whose lines got no project), `repoSuggestions` and `projectCandidates`:
+     - `repoSuggestions` maps each unmapped repo to up to 5 projects, best first: `{ projectName, projectMemberId, projectId, score, reasons }`. The evidence is a ticket from the repo's commits that you logged to the project in the last 30 days, the repo folder or git remote name matching the project name (its acronym in parentheses or its initials), and the only project booked on the repo's commit days. `reasons` are readable, for example `ticket FCS-12 was logged to this project on 2026-11-03` or `repo name matches FCS`.
+     - `projectCandidates` lists every member project (booked ones first).
+     - The assistant asks one short question per repo by project name ("Is fcs-web part of GKE Fair Chem System (FCS)?"). On a yes it calls `map_project` with `projectName` (or the suggestion's `projectMemberId`), `repos` and `confirm: true`, then runs `draft_from_commits` again.
 3. `list_tasks` confirms the worklog task names for each project.
 4. The assistant rewrites vague descriptions, shows you the block and waits for approval.
 5. `log_work(text, projectOverrides)` previews the entries, then `log_work(batchId, confirm: true)` applies them.
@@ -353,11 +405,11 @@ The two applies are intentionally not atomic. `log_work` never writes Jira, and
 You do not need to create the mapping file by hand. When a preview cannot resolve a ticket like `SCB-213`, the assistant calls `list_projects`. After you approve, it calls `map_project` with `tickets`, an optional `keywords`, and `confirm: true`.
 
 For commit drafts, a mapping can also list git repos.
-- When `draft_from_commits` reports `unmappedRepos`, the assistant can call `map_project` with `repos` (absolute paths) and `confirm: true`.
+- When `draft_from_commits` reports `unmappedRepos`, the assistant confirms the top `repoSuggestions` entry with you by name, then calls `map_project` with `projectName`, `repos` (absolute paths) and `confirm: true`.
 - At least one ticket prefix or repo is required.
 - A subfolder is stored as the root of its repo.
 - Paths are compared without trailing separators, and case-insensitively on Windows.
-- In the terminal UI, `/map --repo [path] <projectMemberId>` does the same. The path defaults to the current folder.
+- In a terminal, `logwork commits` asks for each unmapped repo with a picker (likely project first). In the terminal UI, `/map --repo [path]` opens the same picker and `/map --repo [path] <project name>` maps by name. The path defaults to the current folder.
 
 Mappings are stored in one of two places:
 - **User scope (default):** `~/.logwork-cli/.logwork.json`.

package/docs/operations-guide.md

@@ -19,6 +19,8 @@ npm install -g logwork-cli
 logwork setup
 ```
 
+`logwork setup` also writes the launcher (`~/.logwork-cli/bin/logwork-launch` on macOS) 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. Options: `--yes` (no questions), `--no-mcp-install` (do not touch MCP configs). Check or redo it later with `logwork mcp status` and `logwork mcp install`; see [MCP setup](mcp-setup.md#automatic-setup).
+
 Upgrading from `logwork-helper`: run `npm uninstall -g logwork-helper` first. Both packages provide a `logwork` command, and npm refuses to overwrite it (`EEXIST`). If `~/.logwork-helper` was already deleted, the uninstall leaves broken links behind; remove them with `P="$(npm prefix -g)"; rm -f "$P/bin/logwork" "$P"/bin/logwork-helper* "$P/lib/node_modules/logwork-helper"`, or run `npx logwork-cli@latest setup`, which removes them.
 
 Authenticate each target from Terminal:
@@ -348,6 +350,14 @@ RO project mapping can use:
 - Task keywords, for example `maintenance mode`.
 - Explicit project selection during preview.
 - Jira project key/name metadata in the terminal Both flow to rank RO memberships.
+- Git repo roots (`repos`), for commit drafts.
+
+A repo with no mapping is mapped once, in place, without ids:
+- `logwork commits` in an interactive terminal asks `Which RO project does <repo> belong to?` with the likely project preselected, saves the choice and redoes the draft (`--no-prompt` turns this off).
+- In the terminal UI, `/map --repo [path]` opens the same picker; `/map --repo [path] <project name>` maps by name (case-insensitive, then a unique part of the name; an ambiguous name opens the picker).
+- MCP: `draft_from_commits` returns `repoSuggestions` per unmapped repo; the assistant confirms the top one by name and calls `map_project` with `projectName` and `repos`.
+
+The likely project comes from ticket keys in the repo's commits that you logged to a project in the last 30 days, then the repo folder or git remote name against the project name (acronym in parentheses, initials, shared words), then the only project booked on the repo's commit days.
 
 Example MCP sequence:
 
@@ -453,8 +463,10 @@ Behavior:
 - Missing auth produces an actionable notification without exposing API details.
 - macOS uses a user `launchd` agent (`sg.vinova.logwork-cli.reminder`).
 - Windows uses an interactive user Task Scheduler task (`Logwork Reminder`).
-- The scheduler runs `<absolute node path> ~/.logwork-cli/bin/logwork.mjs reminder run --home ~/.logwork-cli`, using the Node that ran `reminder enable` or `logwork setup`.
-- If that Node is removed or replaced (`nvm uninstall`, `brew upgrade node`), the schedule still looks installed but cannot run. `logwork reminder status` and `logwork doctor` warn about it; run `logwork reminder enable` or `logwork setup` to re-register it with the current Node.
+- The scheduler runs the same command as the MCP configs with `reminder run --home ~/.logwork-cli`:
+  - macOS: `~/.logwork-cli/bin/logwork-launch`, which finds a Node 22+ itself, so a Node upgrade does not break the reminder;
+  - Windows: a stable `node.exe` (the nvm-windows symlink, or `C:\Program Files\nodejs\node.exe`) plus `~/.logwork-cli/bin/logwork.mjs`.
+- `logwork reminder status` and `logwork doctor` warn when the scheduled command is missing, when the launcher finds no usable Node, and when a schedule from an older version still runs a raw Node path. Run `logwork setup` (or `logwork reminder enable`) to re-register it.
 - Enabling or disabling the reminder also removes a leftover `logwork-helper` schedule.
 
 Commit evidence:
@@ -567,6 +579,8 @@ The release doctor checks package version consistency, self-dependencies, clean/
 | Update cache | `.logwork-cli/update-state.json` | No |
 | Reminder config/state | `.logwork-cli/reminder.json`, `.logwork-cli/reminder-state.json` | No |
 | Runtime Node record | `.logwork-cli/runtime.json` (Node path and version from `logwork setup`) | No |
+| Launcher (macOS) | `.logwork-cli/bin/logwork-launch`, written by `logwork setup` | No |
+| MCP config backups | `<client config>.logwork-backup-<timestamp>`, next to each edited client config | No |
 | RO/Jira sessions | OS credential store, service `logwork-cli` | Yes |
 
 The helper home is `~/.logwork-cli` on macOS and `%USERPROFILE%\.logwork-cli` on Windows. `LOGWORK_HOME` overrides it; the older `LOGWORK_HELPER_HOME` is still honored.
@@ -616,7 +630,8 @@ Recommended end-user checks after installation:
 - Partial Both result: inspect `/history both`, then preview only the missing target.
 - npm `E401`: refresh npm login with `npm login --registry=https://registry.npmjs.org/`.
 - Reminder config/scheduler mismatch: rerun `reminder enable` or `reminder disable`.
-- Reminder or MCP Node path gone after a Node upgrade: run `logwork setup` (refreshes `runtime.json`, the reminder and the printed MCP configs), then paste the new MCP config.
+- MCP client or reminder does not start after a Node change: run `logwork doctor` or `logwork mcp status`. `logwork setup` rewrites the launcher, re-registers the reminder and updates the MCP configs it can edit; paste the printed snippet only for a client it reports as "could not update automatically".
+- `logwork mcp install` reports "could not update automatically": the file has comments, trailing commas or an unusual TOML layout. Paste the printed snippet by hand, or remove the comments and run it again.
 - MCP after update: restart or reload the MCP connection.
 
 For client configuration details, see [MCP setup](mcp-setup.md). For security boundaries and stored-data details, see [Security and auth](security.md). For copy-ready task recipes, see [Quick recipes](recipes.md).