logwork-cli 1.2.0 → 1.3.1

package/LICENSE

@@ -1,11 +1,21 @@
-Proprietary License
+MIT License
 
-Copyright (c) 2026 Truc Tran and contributors.
-All rights reserved.
+Copyright (c) 2026 malcohelper and contributors
 
-This project is proprietary and is not open source. Use, copying,
-modification, distribution, publication, sublicensing, or sale of this
-software or its documentation is permitted only with prior written permission
-from the copyright holder or under a separate written agreement.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-No license is granted by implication, estoppel, or otherwise.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,13 +122,20 @@ How the draft is built:
   | `chore` | Other Activities |
 
   Conventional prefixes are used first, then keywords in the subject.
-- **Project:** a project mapping whose `repos` list holds the repo wins (`/map --repo . 5234` in the terminal UI, or the MCP tool `map_project` with `repos`). Otherwise ticket and keyword mappings and the day's booked projects pick it, the same way `log_work` does. Repos with no project are listed so you can map them.
+- **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.
+
+  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. Paste the draft into `/logwork`, or let your AI agent use it.
+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`, 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;
@@ -162,53 +171,35 @@ The default tasks shared by all projects are:
 | 183 | Testing Activities | create |
 | 111 | Other Activities | other |
 
-## API Notes
-
-- Read bookings: `GET /member-logtime/timesheet`
-- Read worklog tasks: `GET /logwork/tasks?project_id=<id>` and `GET /logwork/tasks/defaults?project_id=<id>`
-- Write an entry: `POST /logwork/entries`
-- Delete an entry: `DELETE /logwork/entries/:id`
-- Resubmit a rejected entry: `PATCH /logwork/entries/:id/resubmit`
-
-```json
-{
-  "worklog_task_id": 71,
-  "type_of_work": "create",
-  "effort_hours": 2,
-  "logdate": "2026-06-01",
-  "project_id": 720,
-  "description": "Implement maintenance mode management and status UI (SCB-213)"
-}
-```
-
-`project_id` is sent only when the worklog task is a shared default task.
-
 ## 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`. The printed configs use the absolute path of your Node binary, because IDEs started from the Dock or Finder often do not see nvm's `node` on `PATH`:
+| 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": "/Users/you/.nvm/versions/node/v24.1.0/bin/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 -- "$(which 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
 ```
 
-If you upgrade or remove that Node (`nvm uninstall`, `brew upgrade node`), re-run `logwork setup` and paste the new config. `logwork doctor` warns when the recorded Node path is gone.
+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 saving.
+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.
@@ -241,11 +232,11 @@ Options:
 
 The long forms `--task-name` and `--description` also work. Project and date are always preserved.
 
-Resource Optimiser has no staff API for editing an entry; the edit endpoint is PM-only. So apply **replaces** the entry:
+Resource Optimiser only lets project managers edit an entry. So apply **replaces** the entry:
 
 1. It re-reads the entry and stops if the entry changed after the preview.
-2. It creates the corrected entry with `POST /logwork/entries`.
-3. It deletes the original with `DELETE /logwork/entries/:id`.
+2. It creates the corrected entry.
+3. It deletes the original.
 4. It verifies the new entry.
 
 If the create fails, the original is untouched. If the delete fails, the new entry is deleted again, so nothing changes.
@@ -292,7 +283,7 @@ In the terminal UI, `/logwork` opens a target picker. `/logwork ro` writes Resou
 - `/query this-week`
 - `/reconcile`
 - `/projects`
-- `/map SCB 5234` (ticket prefix) or `/map --repo . 5234` (this git repo, for commit drafts)
+- `/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`
 
@@ -321,7 +312,7 @@ 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. The schedule stores the absolute Node path; after upgrading or removing that Node, run `logwork reminder enable` (or `logwork setup`) again. `logwork reminder status` warns when that path no longer exists.
+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
 
@@ -354,4 +345,4 @@ Updating keeps OS credentials, project mappings, drafts and apply history. Recon
 
 ## License
 
-This project is proprietary and not open source. See [LICENSE](LICENSE).
+[MIT](LICENSE) © 2026 malcohelper and contributors.

package/RELEASE.md

@@ -64,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,14 +1,18 @@
 import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+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];
@@ -18,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('--')) {
@@ -52,7 +58,10 @@ export async function run(args = [], {
   draft = draftLogworkFromCommits,
   print = console.log,
   cwd = process.cwd(),
-  reminderRepos = loadReminderRepos
+  reminderRepos = loadReminderRepos,
+  isInteractive = defaultIsInteractive,
+  chooseProject = chooseRepoProject,
+  saveMapping = upsertProjectMapping
 } = {}) {
   const options = parseCommitsArgs(args);
   if (options.help) {
@@ -71,20 +80,70 @@ export async function run(args = [], {
       fallbackNote = `Not in a git repo; using the reminder repos: ${fallback.join(', ')}`;
     }
   }
-  const result = await draft({
+  const draftOptions = {
     period: options.period,
     repos,
     author: options.author,
     useBookings: options.useBookings
-  });
+  };
+  const result = await draft(draftOptions);
   if (options.json) {
     print(JSON.stringify(result, null, 2));
-  } else {
-    print(fallbackNote ? `${fallbackNote}\n\n${result.summary}` : result.summary);
+    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 } = {}) {
@@ -108,7 +167,8 @@ async function loadReminderRepos() {
 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; outside a git repo, the repos set with
@@ -120,14 +180,18 @@ the current directory; outside a git repo, the repos set with
   fix -> Bug Fix, refactor/perf/review -> Code Review & Refactoring,
   test -> Testing Activities, ci/build/release -> Deployment & Release,
   docs/design -> Requirements & Design, chore -> Other Activities.
-- Each group gets an RO project: a mapping whose repos holds the repo (/map
-  --repo in the terminal UI, or map_project), else ticket/keyword mappings and
-  that day's bookings.
+- 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/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(' ');
+}