logwork-cli 1.1.1 → 1.3.0

package/README.md

@@ -26,7 +26,7 @@ logwork setup
 - installs the runtime to `~/.logwork-cli` (`%USERPROFILE%\.logwork-cli` on Windows),
 - links the `logwork` command,
 - offers to log in,
-- prints copy-ready MCP configs that use your real local path.
+- adds the `logwork` MCP server to the AI clients it finds (Claude Code, Cursor, Codex, VS Code, Google Antigravity). It asks once per client; answer yes. See [Set Up MCP](#set-up-mcp).
 
 ## Upgrading from logwork-helper
 
@@ -57,7 +57,7 @@ Most of the move is automatic:
 
 Two things you need to do yourself:
 
-- **IDE config:** replace the old `logwork-helper` MCP entry with the new `logwork` entry printed by `logwork setup` or `/mcp`.
+- **IDE config:** `logwork setup` replaces the old `logwork-helper` entry with the new `logwork` entry in the clients it can edit. For any other client, use the config printed by `logwork setup` or `/mcp`.
 - **MCP tool names:** the tool names changed. See the [old → new tool name table](docs/mcp-setup.md#tool-name-changes-from-logwork-helper).
 
 ## Log In
@@ -77,7 +77,7 @@ Sessions are stored in macOS Keychain or Windows Credential Manager. The default
 ```text
 logwork                 Open the terminal UI
 logwork query [period]  Booked vs logged hours with entry ids (today, yesterday, this-week, last-week, this-month, last-month)
-logwork commits [period] Draft logwork lines from your git commits (--repo, --author)
+logwork commits [period] Draft logwork lines from your git commits (--repo, --author, --no-prompt)
 logwork quick [-m text] Log one entry for today with guided prompts
 logwork edit <id> ...   Change an existing RO entry (replaces it)
 logwork delete <id>     Delete a submitted or approved RO entry
@@ -85,7 +85,9 @@ logwork reconcile       Compare RO and Jira hours by day (read-only)
 logwork history         Local apply history
 logwork login|logout|status [ro|jira]
 logwork skill install   Install the AI agent skill (Claude Code, Codex)
-logwork setup           Install the runtime and print MCP configs
+logwork setup           Install the runtime and add logwork to your MCP clients
+logwork mcp install     Add or update the logwork entry in your MCP clients
+logwork mcp status      Check each MCP client's logwork entry
 logwork mcp             Run the MCP stdio server (used by IDE configs)
 logwork reminder ...    Weekday logwork reminder
 logwork update ...      Check for or install a new version
@@ -120,12 +122,20 @@ How the draft is built:
   | `chore` | Other Activities |
 
   Conventional prefixes are used first, then keywords in the subject.
-- **Hours:** each day's RO remaining time (booked − logged, per project) is split across the groups in 0.5h steps, weighted by commits and lines changed. Days without a booking get 0h. Without RO access, a weekday counts as 8h.
+- **Project:** a project mapping whose `repos` list holds the repo wins. Otherwise ticket and keyword mappings and the day's booked projects pick it, the same way `log_work` does.
+- **Repos with no project:** you are asked once, in place. In an interactive terminal, `logwork commits` shows `Which RO project does <repo> belong to?` with your member projects. The likely project is preselected, with the reason as a hint:
+  - a ticket key from the repo's commits that you logged to that project in the last 30 days;
+  - the repo folder or git remote name matching the project name, its acronym in parentheses (`fcs-web` → `GKE Fair Chem System (FCS)`) or its initials;
+  - the only project booked on the repo's commit days.
 
-Nothing is written. Paste the draft into `/logwork`, or let your AI agent use it.
+  Your choice is saved as a repo mapping (user scope) and the draft is redone. Choose `Skip for now` to be asked again next time. `--no-prompt`, `--json` or a non-interactive terminal never ask; the summary then names the likely project per repo.
+- **Hours:** each project's RO remaining time (booked − logged) is split across that project's groups in 0.5h steps, weighted by commits and lines changed, and never exceeds it. A project with no room left gets 0h. Groups without a project share the room of booked projects that no group claimed. Days without a booking get 0h. Without RO access, a weekday counts as 8h, split across all groups.
+
+Nothing is written to RO or Jira. Paste the draft into `/logwork`, or let your AI agent use it.
 
 For agents:
-- **MCP tool `draft_from_commits`** returns the same draft as `draftText`.
+- **MCP tool `draft_from_commits`** returns the same draft as `draftText`, plus `projectOverrides` (preview entry id → `projectMemberId`) for every line with a project. The agent passes both to `log_work` unchanged. In the terminal UI, pasted lines are resolved again from mappings and bookings.
+- For `unmappedRepos` it also returns `repoSuggestions` (ranked projects with reasons per repo) and `projectCandidates`. The agent asks you one short question per repo by project name ("Is fcs-web part of GKE Fair Chem System (FCS)?"), then saves the answer with `map_project` and drafts again. You never type an id.
 - **MCP prompt `log_from_commits`** gives an agent the full procedure:
   1. find gaps with `get_logwork`;
   2. draft from commits;
@@ -184,28 +194,33 @@ The default tasks shared by all projects are:
 
 ## Set Up MCP
 
-`logwork setup` prints the configs. You can also open the terminal UI with `logwork` and type `/mcp` (or `/mcp cursor`, `/mcp antigravity`, `/mcp copilot`, `/mcp claude-code`, `/mcp codex`).
+Run `logwork setup` and answer yes for each client. It finds the clients you have and adds or updates the `logwork` server in each:
 
-Every client runs the same thing, `node ~/.logwork-cli/bin/logwork.mjs mcp`, under the server name `logwork`:
+| Client | What setup changes |
+|---|---|
+| Claude Code | `claude mcp add --scope user logwork ...` (or `~/.claude.json` when the `claude` CLI is not on `PATH`) |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex | `~/.codex/config.toml` |
+| VS Code | user `mcp.json` (`~/Library/Application Support/Code/User` on macOS, `%APPDATA%\Code\User` on Windows) |
+| Google Antigravity | `~/.gemini/antigravity/mcp_config.json` |
 
-```json
-{
-  "mcpServers": {
-    "logwork": {
-      "command": "node",
-      "args": ["/Users/you/.logwork-cli/bin/logwork.mjs", "mcp"]
-    }
-  }
-}
-```
-
-For Claude Code, run:
+It touches only the `logwork` entry, removes an old `logwork-helper` entry, and backs up each file first (`<file>.logwork-backup-<timestamp>`). A file it cannot parse safely (JSON with comments, unusual TOML) is left alone, and setup prints the snippet to paste instead.
 
 ```bash
-claude mcp add --transport stdio logwork -- node ~/.logwork-cli/bin/logwork.mjs mcp
+logwork mcp status            # which clients have a current logwork entry
+logwork mcp install           # add or update them later (asks per client)
+logwork mcp install --dry-run # show the changes without writing
+logwork setup --yes           # update every detected client without asking
+logwork setup --no-mcp-install
 ```
 
-Restart or reload the IDE's MCP tools after saving.
+The configs never name a Node version, so Node upgrades need no config change:
+- **macOS:** clients run `~/.logwork-cli/bin/logwork-launch mcp`. This small script, written by `logwork setup`, starts logwork with the first Node 22+ it finds: the Node that ran setup, `node` on `PATH`, the newest nvm Node, Volta or fnm, then Homebrew.
+- **Windows:** clients run `node.exe %USERPROFILE%\.logwork-cli\bin\logwork.mjs mcp` with a stable `node.exe`: the nvm-windows symlink (`%NVM_SYMLINK%\node.exe`) or `C:\Program Files\nodejs\node.exe`.
+
+For a client setup does not know, open the terminal UI with `logwork` and type `/mcp` (or `/mcp cursor`, `/mcp antigravity`, `/mcp copilot`, `/mcp claude-code`, `/mcp codex`) for a copy-ready config. [docs/mcp-setup.md](docs/mcp-setup.md) has the manual snippets.
+
+Restart or reload the IDE's MCP tools after a change.
 
 The server exposes 16 tools and one prompt (`log_from_commits`). It also sends `instructions` covering the approval rules, the line format and the recommended call order. Every write is **two calls to the same tool**:
 1. Call the tool without `confirm`. It returns a preview with a `batchId` or `previewId` and a summary.
@@ -289,7 +304,7 @@ In the terminal UI, `/logwork` opens a target picker. `/logwork ro` writes Resou
 - `/query this-week`
 - `/reconcile`
 - `/projects`
-- `/map SCB 5234`
+- `/map --repo` (this git repo, for commit drafts: opens a project picker with the likely project first), `/map --repo ~/code/fcs GKE Fair` (by name), or `/map SCB 5234` (ticket prefix)
 - `/history`
 - `/diagnostics`
 
@@ -298,6 +313,7 @@ In the terminal UI, `/logwork` opens a target picker. `/logwork ro` writes Resou
 ```bash
 logwork reminder enable                 # 17:00 Monday-Friday, RO and Jira
 logwork reminder enable --time 18:00 --target ro
+logwork reminder enable --repo ~/code/app --repo ~/code/api   # add commit evidence
 logwork reminder test
 logwork reminder status
 logwork reminder disable
@@ -305,7 +321,19 @@ logwork reminder disable
 
 For Resource Optimiser, the reminder compares today's logged and booked hours. For Jira, it checks whether you have any worklog today. Complete days stay silent.
 
-macOS uses a user `launchd` agent (`sg.vinova.logwork-cli.reminder`) and Windows uses Task Scheduler (`Logwork Reminder`). Neither schedule stores credentials.
+With `--repo` (repeatable; `--no-repos` clears the list), a reminder about missing RO hours also counts your commits today in those repos and points you to a draft:
+
+```text
+Logwork hôm nay chưa hoàn tất
+RO: 4/8h, còn thiếu 4h
+Hôm nay: 5 commit trong 2 repo
+
+Mở Terminal và chạy: logwork commits today (bản nháp từ commit)
+```
+
+Repos listed on project mappings are used too. Run outside a git repo, `logwork commits today` falls back to these repos. If reading commits fails, the reminder shows the plain message.
+
+macOS uses a user `launchd` agent (`sg.vinova.logwork-cli.reminder`) and Windows uses Task Scheduler (`Logwork Reminder`). Neither schedule stores credentials. On macOS the schedule runs the `logwork-launch` launcher, so Node upgrades do not break it. On Windows it runs a stable `node.exe`. A schedule from an older version that still runs a raw Node path is flagged by `logwork reminder status`; run `logwork setup` to re-register it.
 
 ## Reconcile RO And Jira
 

package/RELEASE.md

@@ -55,6 +55,7 @@ This checks version consistency, git cleanliness, npm auth, npm latest version,
 
 The gate must pass all of the following:
 
+- `npm run lint`
 - `npm test`
 - `npm audit --omit=dev --audit-level=moderate`
 - `npm pack --dry-run`
@@ -63,8 +64,9 @@ The gate must pass all of the following:
 ## Manual Verification
 
 - Install from the packed tarball in a temporary directory.
-- Run `logwork setup --no-login`.
-- Confirm the printed MCP config uses server name `logwork` and `node ~/.logwork-cli/bin/logwork.mjs mcp`.
+- Run `logwork setup --no-login` with a temporary `HOME` and `LOGWORK_HOME`, so no real MCP client config is touched.
+- Confirm `~/.logwork-cli/bin/logwork-launch` exists and is executable (macOS), and that `logwork-launch --version` prints the package version.
+- Confirm `logwork mcp install --dry-run` lists the detected clients with server name `logwork` and command `~/.logwork-cli/bin/logwork-launch mcp` (Windows: `node.exe ...\bin\logwork.mjs mcp`), and that `logwork mcp status` reports them.
 - Run `logwork --help` and `logwork --version`.
 - Run `logwork update check --force` against the published npm version.
 - Run `logwork mcp` through an MCP client smoke test and confirm it lists the 16 tools (`get_logwork`, `draft_from_commits`, `list_projects`, `list_tasks`, `log_work`, `edit_entry`, `resubmit_entry`, `delete_entry`, `log_jira_work`, `get_jira_issue`, `reconcile`, `get_history`, `map_project`, `login`, `reminder`, `update`).

package/bin/logwork.mjs

@@ -20,8 +20,8 @@ export const COMMANDS = [
   { name: 'logout', usage: 'logout [ro|jira]', summary: 'Remove the stored RO (default) or Jira session', load: () => import('../commands/auth.mjs'), fn: 'runLogout' },
   { name: 'status', usage: 'status', summary: 'Show RO and Jira login status', load: () => import('../commands/auth.mjs'), fn: 'runStatus' },
   { name: 'skill', usage: 'skill [print|install] [--target claude|codex|all]', summary: 'Print or install the AI agent skill for logging from commits', load: () => import('../commands/skill.mjs'), fn: 'run' },
-  { name: 'setup', usage: 'setup [--login|--no-login]', summary: 'Install the runtime and print MCP configs', load: () => import('../commands/setup.mjs'), fn: 'run' },
-  { name: 'mcp', usage: 'mcp', summary: 'Run the MCP stdio server (used by IDE configs)', load: () => import('../lib/mcp-server.mjs'), fn: 'startMcpServer' },
+  { name: 'setup', usage: 'setup [--yes] [--no-mcp-install] [--login|--no-login]', summary: 'Install the runtime and add logwork to your MCP clients', load: () => import('../commands/setup.mjs'), fn: 'run' },
+  { name: 'mcp', usage: 'mcp [install|status]', summary: 'Run the MCP stdio server; install or check IDE configs', load: () => import('../commands/mcp.mjs'), fn: 'run' },
   { name: 'reminder', usage: 'reminder enable|disable|status|test', summary: 'Manage the weekday logwork reminder', load: () => import('../commands/reminder.mjs'), fn: 'runReminderCli' },
   { name: 'update', usage: 'update [check|install]', summary: 'Check for or install a new version', load: () => import('../commands/update.mjs'), fn: 'runUpdateCli' },
   { name: 'doctor', usage: 'doctor', summary: 'Write a sanitized diagnostics report', load: () => import('../commands/doctor.mjs'), fn: 'run' },

package/commands/commits.mjs

@@ -1,10 +1,18 @@
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { draftLogworkFromCommits } from '../lib/commit-workflow.mjs';
+import { upsertProjectMapping } from '../lib/project-mapping-workflow.mjs';
 import { normalizeReconciliationPeriod } from '../lib/reconciliation-workflow.mjs';
+import { loadReminderConfig } from '../lib/reminder-config.mjs';
+import { collectReminderRepos } from '../lib/reminder-workflow.mjs';
+import { chooseRepoProject } from '../lib/ui.mjs';
 
-// `logwork commits [period] [--repo path]... [--author x] [--no-bookings] [--json]`:
-// turn your git commits into a logwork draft. Read-only.
+// `logwork commits [period] [--repo path]... [--author x] [--no-bookings] [--no-prompt] [--json]`:
+// turn your git commits into a logwork draft. Never writes to RO or Jira; in an
+// interactive terminal it asks once per unmapped repo which project it belongs
+// to and saves the answer as a local repo mapping.
 export function parseCommitsArgs(args = []) {
-  const options = { period: 'today', repos: [], author: undefined, useBookings: true, json: false, help: false };
+  const options = { period: 'today', repos: [], author: undefined, useBookings: true, json: false, prompt: true, help: false };
   const positional = [];
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -14,6 +22,8 @@ export function parseCommitsArgs(args = []) {
       options.json = true;
     } else if (arg === '--no-bookings') {
       options.useBookings = false;
+    } else if (arg === '--no-prompt') {
+      options.prompt = false;
     } else if (arg === '--repo' || arg === '--author') {
       const value = args[index + 1];
       if (!value || value.startsWith('--')) {
@@ -44,29 +54,125 @@ export function parseCommitsArgs(args = []) {
   return options;
 }
 
-export async function run(args = [], { draft = draftLogworkFromCommits, print = console.log } = {}) {
+export async function run(args = [], {
+  draft = draftLogworkFromCommits,
+  print = console.log,
+  cwd = process.cwd(),
+  reminderRepos = loadReminderRepos,
+  isInteractive = defaultIsInteractive,
+  chooseProject = chooseRepoProject,
+  saveMapping = upsertProjectMapping
+} = {}) {
   const options = parseCommitsArgs(args);
   if (options.help) {
     print(formatCommitsHelp());
     return 0;
   }
-  const result = await draft({
+  // The reminder tells the user to run `logwork commits today` from a fresh
+  // terminal, which starts outside any repo. There, fall back to the
+  // reminder's repos instead of reporting no commits.
+  let repos = options.repos;
+  let fallbackNote = '';
+  if (!repos.length && !isInsideGitWorkTree(cwd)) {
+    const fallback = await reminderRepos().catch(() => []);
+    if (fallback.length) {
+      repos = fallback;
+      fallbackNote = `Not in a git repo; using the reminder repos: ${fallback.join(', ')}`;
+    }
+  }
+  const draftOptions = {
     period: options.period,
-    repos: options.repos,
+    repos,
     author: options.author,
     useBookings: options.useBookings
-  });
-  print(options.json ? JSON.stringify(result, null, 2) : result.summary);
+  };
+  const result = await draft(draftOptions);
+  if (options.json) {
+    print(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  print(fallbackNote ? `${fallbackNote}\n\n${result.summary}` : result.summary);
+
+  if (!options.prompt || !isInteractive() || !result.unmappedRepos?.length) {
+    return 0;
+  }
+  const mapped = await askRepoProjects(result, { chooseProject, saveMapping, print, cwd });
+  if (mapped) {
+    const updated = await draft(draftOptions);
+    print(`\nUpdated draft:\n\n${updated.summary}`);
+  }
   return 0;
 }
 
+// One select prompt per unmapped repo (once per run); a chosen project is
+// saved as a user-scope repo mapping. Returns how many repos were mapped.
+export async function askRepoProjects(result, { chooseProject = chooseRepoProject, saveMapping = upsertProjectMapping, print = console.log, cwd = process.cwd() } = {}) {
+  const candidates = result.projectCandidates || [];
+  if (!candidates.length) {
+    return 0;
+  }
+  let mapped = 0;
+  for (const repo of result.unmappedRepos) {
+    const repoName = basename(repo) || repo;
+    const project = await chooseProject({
+      repoName,
+      suggestions: result.repoSuggestions?.[repo] || [],
+      candidates
+    });
+    if (!project) {
+      print(`Skipped ${repoName}; it will be asked again next time.`);
+      continue;
+    }
+    try {
+      await saveMapping({
+        repos: [repo],
+        ...(project.projectMemberId !== undefined ? { projectMemberId: project.projectMemberId } : { projectName: project.projectName }),
+        scope: 'user',
+        confirm: true,
+        cwd
+      });
+      print(`Mapped ${repoName} to ${project.projectName}. Later drafts use it automatically.`);
+      mapped += 1;
+    } catch (error) {
+      print(`Could not map ${repoName}: ${error.message}`);
+    }
+  }
+  return mapped;
+}
+
+function defaultIsInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+// True when dir or a parent holds .git (a directory, or a file for worktrees
+// and submodules). No git process is started.
+export function isInsideGitWorkTree(dir, { exists = existsSync } = {}) {
+  let current = resolve(dir);
+  for (;;) {
+    if (exists(join(current, '.git'))) {
+      return true;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return false;
+    }
+    current = parent;
+  }
+}
+
+async function loadReminderRepos() {
+  return collectReminderRepos({ config: await loadReminderConfig() });
+}
+
 export function formatCommitsHelp() {
   return `Usage:
   logwork commits [today|yesterday|this-week|last-week|this-month|last-month]
-                  [--repo <path>]... [--author <email>] [--no-bookings] [--json]
+                  [--repo <path>]... [--author <email>] [--no-bookings]
+                  [--no-prompt] [--json]
 
 Reads your commits (all branches, your git user.email) from each repo (default:
-the current directory) and drafts logwork lines:
+the current directory; outside a git repo, the repos set with
+\`logwork reminder enable --repo\`) and drafts logwork lines:
   +<hours> <worklog task> | <description>
 
 - Commits are grouped per day by repo, ticket key and kind of work.
@@ -74,9 +180,18 @@ the current directory) and drafts logwork lines:
   fix -> Bug Fix, refactor/perf/review -> Code Review & Refactoring,
   test -> Testing Activities, ci/build/release -> Deployment & Release,
   docs/design -> Requirements & Design, chore -> Other Activities.
-- Hours split the day's RO remaining time (booked - logged) by how much work
-  each group holds. With --no-bookings or without login, a weekday is 8h.
+- Each group gets an RO project: a mapping whose repos holds the repo, else
+  ticket/keyword mappings and that day's bookings.
+- For a repo with no project, an interactive terminal asks once: "Which RO
+  project does <repo> belong to?", with the likely project preselected (ticket
+  history, repo/remote name, single booked project). The answer is saved as a
+  repo mapping and the draft is redone. Skip it to be asked again next time;
+  --no-prompt (or --json, or a non-interactive terminal) never asks.
+- Each project's RO remaining time (booked - logged) is split across its
+  groups by how much work each holds; groups without a project share the room
+  of booked projects no group claimed. With --no-bookings or without login, a
+  weekday is 8h split across all groups.
 
-Nothing is written. Review the draft, then paste it into /logwork or give it
+Nothing is written to RO or Jira. Review the draft, then paste it into /logwork or give it
 to your AI agent (log_work).`;
 }

package/commands/history.mjs

@@ -56,7 +56,3 @@ function printHistoryHelp(print = console.log) {
 
 Shows the local apply result ledger. Target both means entries applied from a combined Both flow.`);
 }
-
-async function main() {
-  await runHistoryCommand(process.argv.slice(2));
-}

package/commands/mcp.mjs

@@ -0,0 +1,266 @@
+// `logwork mcp`: with no arguments, the MCP stdio server that every IDE config
+// runs. Nothing may be written to stdout before the server starts, because
+// stdout is the protocol channel. `install`, `status` and `--help` are
+// dispatched first. The modules imported here never write to stdout.
+import { constants as fsConstants, promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { writeLauncher } from '../lib/launcher.mjs';
+import { helperHome } from '../lib/paths.mjs';
+import {
+  MCP_INSTALL_CLIENT_KEYS,
+  applyMcpClientPlan,
+  createMcpInstallContext,
+  describeMcpPlan,
+  inspectMcpClients,
+  normalizeMcpInstallClient,
+  planMcpInstall
+} from '../lib/mcp-install.mjs';
+
+export async function run(argv = []) {
+  if (!argv.length) {
+    const { startMcpServer } = await import('../lib/mcp-server.mjs');
+    return startMcpServer();
+  }
+  const [sub, ...rest] = argv;
+  if (sub === '--help' || sub === '-h' || sub === 'help') {
+    console.log(formatMcpHelp());
+    return 0;
+  }
+  if (sub === 'install') {
+    if (rest.includes('--help') || rest.includes('-h')) {
+      console.log(formatMcpHelp());
+      return 0;
+    }
+    return runMcpInstallCli(parseMcpInstallArgs(rest));
+  }
+  if (sub === 'status') {
+    if (rest.includes('--help') || rest.includes('-h')) {
+      console.log(formatMcpHelp());
+      return 0;
+    }
+    if (rest.length) {
+      throw new Error(`Unknown mcp status option: ${rest[0]}`);
+    }
+    return runMcpStatusCli();
+  }
+  throw new Error(`Unknown mcp command: ${sub}. Run \`logwork mcp --help\`.`);
+}
+
+export function formatMcpHelp() {
+  return `Usage:
+  logwork mcp                 Run the MCP stdio server (what IDE configs run)
+  logwork mcp install [--client claude|cursor|codex|vscode|antigravity]... [--yes] [--dry-run]
+  logwork mcp status
+
+install  Adds or updates the "logwork" server in the MCP clients found on this
+         machine (Claude Code, Cursor, Codex, VS Code, Google Antigravity).
+         Asks once per client unless --yes. Each edited file is backed up next
+         to itself first (<file>.logwork-backup-<timestamp>). An old
+         "logwork-helper" entry is removed.
+status   Shows each client and whether its "logwork" entry is current, stale
+         or missing.
+
+Options:
+  --client <name>  Only this client (repeatable)
+  --yes, -y        Update every selected client without asking
+  --dry-run        Show the planned changes without writing anything`;
+}
+
+export function parseMcpInstallArgs(args = []) {
+  const options = { clients: [], yes: false, dryRun: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--yes' || arg === '-y') {
+      options.yes = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--client' || arg.startsWith('--client=')) {
+      const value = arg === '--client' ? args[++index] : arg.slice('--client='.length);
+      const key = normalizeMcpInstallClient(value);
+      if (!key) {
+        throw new Error(`Unknown MCP client: ${value || '(missing)'}. Use claude, cursor, codex, vscode or antigravity.`);
+      }
+      if (!options.clients.includes(key)) {
+        options.clients.push(key);
+      }
+    } else {
+      throw new Error(`Unknown mcp install option: ${arg}`);
+    }
+  }
+  return options;
+}
+
+async function runMcpInstallCli(options) {
+  const ctx = createMcpInstallContext();
+  const warning = await prepareRuntimeLauncher(helperHome(), { dryRun: options.dryRun });
+  if (warning) {
+    console.error(warning);
+  }
+  const result = await runMcpInstall({ ...options, ctx, interactive: isInteractiveTerminal() });
+  console.log(result.output);
+  return result.results.some((item) => item.status === 'failed') ? 1 : 0;
+}
+
+async function runMcpStatusCli() {
+  const result = await runMcpStatus({ ctx: createMcpInstallContext() });
+  console.log(result.output);
+  return 0;
+}
+
+// The configs point at <home>/bin/logwork-launch (macOS/Linux), which
+// `logwork setup` writes. Write it here too, so `logwork mcp install` works
+// without a fresh setup. Returns a warning when the runtime itself is missing.
+export async function prepareRuntimeLauncher(home, {
+  dryRun = false,
+  platform = process.platform,
+  access = fs.access,
+  write = writeLauncher
+} = {}) {
+  const entry = join(home, 'bin', 'logwork.mjs');
+  try {
+    await access(entry, fsConstants.F_OK);
+  } catch {
+    return `Warning: the logwork runtime is missing at ${entry}. Run \`logwork setup\` so the configured command can start.`;
+  }
+  if (!dryRun && platform !== 'win32') {
+    await write({ home, platform });
+  }
+  return '';
+}
+
+export function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+async function clackConfirm(message) {
+  const { confirm, isCancel } = await import('@clack/prompts');
+  const answer = await confirm({ message, initialValue: true });
+  return !isCancel(answer) && Boolean(answer);
+}
+
+// Plans, asks (unless --yes), applies and formats. Returns
+// { plans, results, output, pending } where pending lists the clients that
+// still need a change when nothing was applied (dry run or not interactive).
+export async function runMcpInstall({
+  ctx,
+  clients = [],
+  yes = false,
+  dryRun = false,
+  interactive = false,
+  confirmFn = clackConfirm
+} = {}) {
+  const explicit = clients.length > 0;
+  const plans = await planMcpInstall(ctx, {
+    clients: explicit ? clients : MCP_INSTALL_CLIENT_KEYS,
+    explicit
+  });
+  const header = `MCP server "logwork" runs: ${formatCommandLine(ctx)}`;
+  const pending = plans.filter((plan) => plan.action === 'add' || plan.action === 'update');
+
+  if (!plans.length) {
+    return {
+      plans,
+      results: [],
+      pending,
+      output: [header, 'No MCP clients found (Claude Code, Cursor, Codex, VS Code, Google Antigravity). Use `/mcp` in the terminal UI for copy-ready configs.'].join('\n')
+    };
+  }
+
+  if (dryRun || (!yes && !interactive)) {
+    const lines = [header, dryRun ? 'Dry run: nothing was written.' : 'Not an interactive terminal: nothing was written.'];
+    for (const plan of plans) {
+      lines.push(...describeMcpPlan(plan, ctx));
+    }
+    if (pending.length && !dryRun) {
+      lines.push('Run `logwork mcp install --yes` to apply these changes.');
+    }
+    return { plans, results: [], pending, output: lines.join('\n') };
+  }
+
+  const results = [];
+  for (const plan of plans) {
+    if ((plan.action === 'add' || plan.action === 'update') && !yes) {
+      const verb = plan.action === 'add' ? 'Add' : 'Update';
+      const where = plan.kind === 'claude' && plan.cliPath ? 'with the claude CLI' : plan.file;
+      const accepted = await confirmFn(`${verb} the logwork MCP server in ${plan.label} (${where})?`);
+      if (!accepted) {
+        results.push({ key: plan.key, label: plan.label, file: plan.file, status: 'skipped' });
+        continue;
+      }
+    }
+    results.push(await applyMcpClientPlan(plan, ctx));
+  }
+  return { plans, results, pending, output: [header, ...formatMcpInstallResults(results)].join('\n') };
+}
+
+export function formatMcpInstallResults(results) {
+  const lines = [];
+  for (const result of results) {
+    switch (result.status) {
+      case 'added':
+      case 'updated':
+        lines.push(`- ${result.label}: ${result.status}${result.via ? ` (${result.via})` : ` (${result.file})`}${result.backup ? `; backup ${result.backup}` : ''}`);
+        break;
+      case 'up_to_date':
+        lines.push(`- ${result.label}: already up to date`);
+        break;
+      case 'skipped':
+        lines.push(`- ${result.label}: skipped`);
+        break;
+      case 'not_detected':
+        lines.push(`- ${result.label}: not detected; skipped`);
+        break;
+      default:
+        lines.push(`- ${result.label}: could not update automatically (${result.reason || 'unknown error'}). Add this manually${result.file ? ` to ${result.file}` : ''}:`);
+        lines.push(...String(result.snippet || '').split('\n').map((line) => `    ${line}`));
+    }
+  }
+  if (results.some((result) => result.status === 'added' || result.status === 'updated')) {
+    lines.push('Restart or reload the updated clients to pick up the change.');
+  }
+  return lines;
+}
+
+export async function runMcpStatus({ ctx } = {}) {
+  const clients = await inspectMcpClients(ctx);
+  const lines = [`MCP server "logwork" should run: ${formatCommandLine(ctx)}`];
+  const commandExists = await ctx.fs.access(ctx.launch.command).then(() => true, () => false);
+  if (!commandExists) {
+    lines.push(`Warning: ${ctx.launch.command} is missing, so these entries cannot start. Run \`logwork setup\`.`);
+  }
+  for (const client of clients) {
+    lines.push(...formatClientStatus(client));
+  }
+  const needsWork = clients.some((client) => client.detected && (client.status !== 'current' || client.legacy || (client.localScopes || []).length));
+  if (!clients.some((client) => client.detected)) {
+    lines.push('No MCP clients found. Use `/mcp` in the terminal UI for copy-ready configs.');
+  } else if (needsWork) {
+    lines.push('Run `logwork mcp install` to fix the entries above.');
+  }
+  return { clients, output: lines.join('\n') };
+}
+
+function formatClientStatus(client) {
+  if (!client.detected) {
+    return [`- ${client.label}: not detected`];
+  }
+  const where = client.kind === 'claude' && client.cliPath ? `${client.file}; claude CLI found` : client.file;
+  const state = {
+    current: 'current',
+    missing: 'missing',
+    stale: `stale: ${client.reason}`,
+    unreadable: `unreadable: ${client.reason}`
+  }[client.status] || client.status;
+  const lines = [`- ${client.label} (${where}): ${state}`];
+  if (client.legacy) {
+    lines.push('    leftover "logwork-helper" entry (old runtime)');
+  }
+  for (const stray of client.localScopes || []) {
+    lines.push(`    local-scope "${stray.name}" entry for ${stray.project}: ${stray.reason || 'stale'}`);
+  }
+  return lines;
+}
+
+function formatCommandLine(ctx) {
+  return [ctx.launch.command, ...ctx.launch.argsPrefix, 'mcp'].join(' ');
+}