logwork-cli 1.1.0 → 1.2.0

package/commands/setup.mjs

@@ -1,13 +1,15 @@
 import { constants as fsConstants, promises as fs } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { delimiter, dirname, join, relative, resolve } from 'node:path';
+import { delimiter, dirname, join, relative, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { redactText } from '../lib/auth-redaction.mjs';
 import { credentialStoreLabel } from '../lib/credential-store.mjs';
-import { helperHome } from '../lib/paths.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 {
+  MCP_NODE_PATH_NOTE,
   MCP_SERVER_NAME,
-  defaultMcpServerPath,
   formatCodexToml,
   stdioMcpServersConfig,
   vscodeMcpConfig
@@ -59,11 +61,12 @@ export async function installUserRuntime({
   sourceDir,
   targetDir,
   mkdirFn = fs.mkdir,
-  copyFn = copyDirectory,
+  copyFn = copyRuntimeFiles,
   cleanupFn = sanitizeRuntimeMetadata,
   installFn = installDependencies,
   linkFn = linkGlobalBinaries,
   authFn = maybeRunAuthLogin,
+  runtimeInfoFn = recordRuntimeInfo,
   reminderFn = refreshReminderSchedule,
   printFn = printMcpInstructions
 }) {
@@ -75,6 +78,7 @@ export async function installUserRuntime({
   await installFn(targetDir);
   const linkResult = await linkFn(targetDir);
   const authResult = await authFn(targetDir, options);
+  await runtimeInfoFn(targetDir);
   const reminderResult = await reminderFn(targetDir);
   await printFn(targetDir, authResult, linkResult, cleanupResult, reminderResult);
 
@@ -87,22 +91,83 @@ export async function installUserRuntime({
   };
 }
 
-// A reminder enabled by an older install still points at the old runtime.
-// Re-register it so the OS scheduler runs this runtime (and the legacy entry
-// is removed by installReminderScheduler).
-async function refreshReminderSchedule(targetDir) {
+// 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.
+export async function recordRuntimeInfo(targetDir, {
+  nodePath = process.execPath,
+  nodeVersion = process.version,
+  writeFn = writeRuntimeInfo,
+  readFileFn = fs.readFile
+} = {}) {
+  try {
+    const manifest = JSON.parse(await readFileFn(join(targetDir, 'package.json'), 'utf8'));
+    return await writeFn({
+      path: join(targetDir, RUNTIME_INFO_FILE_NAME),
+      nodePath,
+      nodeVersion,
+      version: manifest.version || null
+    });
+  } catch {
+    return null;
+  }
+}
+
+// A reminder enabled by an older install still points at the old runtime, or
+// at a Node that nvm or Homebrew removed. Re-register it so the OS scheduler
+// runs this runtime with the current node (and the legacy entry is removed by
+// installReminderScheduler).
+export async function refreshReminderSchedule(targetDir, {
+  nodePath = process.execPath,
+  loadConfig = loadReminderConfig,
+  install = installReminderScheduler
+} = {}) {
   try {
-    const config = await loadReminderConfig();
+    const config = await loadConfig();
     if (!config?.enabled) {
       return null;
     }
-    await installReminderScheduler(config, { home: targetDir });
-    return { ok: true };
+    await install(config, { home: targetDir, nodePath });
+    return { ok: true, nodePath };
   } catch (error) {
     return { ok: false, error: error.message };
   }
 }
 
+// Copies only what the npm package ships (package.json "files", plus the
+// manifest and lockfile). The target is also the state directory, so a git
+// checkout's .env files, tests, archives or a repo-scope .logwork.json must
+// never land there.
+export async function copyRuntimeFiles(sourceDir, targetDir) {
+  const manifest = JSON.parse(await fs.readFile(join(sourceDir, 'package.json'), 'utf8'));
+  const listed = Array.isArray(manifest.files) ? manifest.files : [];
+  const names = ['package.json', 'package-lock.json', 'npm-shrinkwrap.json', ...listed.map((item) => String(item).replace(/[\\/]+$/, ''))];
+  for (const name of [...new Set(names)]) {
+    const sourcePath = join(sourceDir, name);
+    let stat;
+    try {
+      stat = await fs.stat(sourcePath);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        // A lockfile from an earlier install that no longer matches this
+        // package.json would make `npm ci` fail; let npm install write a new one.
+        if (name === 'package-lock.json') {
+          await fs.rm(join(targetDir, name), { force: true });
+        }
+        continue;
+      }
+      throw error;
+    }
+    if (stat.isDirectory()) {
+      await fs.mkdir(join(targetDir, name), { recursive: true });
+      await copyDirectory(sourcePath, targetDir, sourceDir);
+    } else {
+      await fs.mkdir(dirname(join(targetDir, name)), { recursive: true });
+      await fs.copyFile(sourcePath, join(targetDir, name));
+    }
+  }
+}
+
 async function copyDirectory(sourceDir, targetDir, rootDir) {
   const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
@@ -139,7 +204,8 @@ function installDependencies(targetDir) {
 
 function runCommand(command, args, options = {}) {
   return new Promise((resolveValue, reject) => {
-    const child = spawn(command, args, options);
+    const invocation = command === 'npm' ? npmInvocation(args) : { command, args, shell: false };
+    const child = spawn(invocation.command, invocation.args, { ...options, shell: invocation.shell });
 
     child.on('error', reject);
     child.on('close', (code) => {
@@ -243,9 +309,73 @@ function isStaleSelfDependency(value) {
   return typeof value === 'string' && /^file:.*logwork-(helper|cli).*\.tgz$/i.test(value);
 }
 
+const LEGACY_GLOBAL_LINKS = [
+  'bin/logwork',
+  'bin/logwork-helper',
+  'bin/logwork-helper-install',
+  'bin/logwork-helper-manual',
+  'bin/logwork-helper-mcp',
+  'bin/logwork-helper-setup-user',
+  'lib/node_modules/logwork-helper'
+];
+
+// The old package was installed with `npm link` from ~/.logwork-helper. When
+// that folder is deleted first, its global links dangle: `npm rm -g` cannot
+// read the package any more and leaves bin/logwork behind, which then blocks
+// `npm install -g logwork-cli` and `npm link` with EEXIST. Remove only links
+// that point into a logwork-helper path that no longer exists.
+export async function removeDanglingLegacyLinks(globalPrefix, {
+  platform = process.platform,
+  lstatFn = fs.lstat,
+  statFn = fs.stat,
+  readlinkFn = fs.readlink,
+  unlinkFn = fs.unlink
+} = {}) {
+  const removed = [];
+  if (!globalPrefix || platform === 'win32') {
+    return removed;
+  }
+  for (const relativePath of LEGACY_GLOBAL_LINKS) {
+    const path = join(globalPrefix, relativePath);
+    try {
+      if (!(await lstatFn(path)).isSymbolicLink()) {
+        continue;
+      }
+      if (!/logwork-helper/.test(await readlinkFn(path))) {
+        continue;
+      }
+      try {
+        await statFn(path);
+        continue;
+      } catch {
+        // Dangling: the target is gone.
+      }
+      await unlinkFn(path);
+      removed.push(path);
+    } catch {
+      // Missing or unreadable: nothing to clean.
+    }
+  }
+  return removed;
+}
+
+function readNpmGlobalPrefix(cwd) {
+  return new Promise((resolveValue) => {
+    const invocation = npmInvocation(['prefix', '-g']);
+    const child = spawn(invocation.command, invocation.args, { cwd, shell: invocation.shell, stdio: ['ignore', 'pipe', 'ignore'] });
+    let stdout = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.on('error', () => resolveValue(''));
+    child.on('close', (code) => resolveValue(code === 0 ? stdout.trim() : ''));
+  });
+}
+
 export async function linkGlobalBinaries(targetDir, {
   runner = runCommand,
-  commandFinder = findCommandOnPath
+  commandFinder = findCommandOnPath,
+  prefixReader = readNpmGlobalPrefix,
+  legacyLinkCleaner = removeDanglingLegacyLinks
 } = {}) {
   // Best effort: drop the pre-rename global package so its `logwork` bin does
   // not block linking this one. A no-op when it is not installed.
@@ -253,6 +383,10 @@ export async function linkGlobalBinaries(targetDir, {
     cwd: targetDir,
     stdio: 'ignore'
   }).catch(() => {});
+  await Promise.resolve()
+    .then(() => prefixReader(targetDir))
+    .then((prefix) => legacyLinkCleaner(prefix))
+    .catch(() => []);
 
   try {
     await runner('npm', ['link'], {
@@ -403,9 +537,12 @@ export function formatSetupUserInstructions({
   linkResult = null,
   cleanupResult = null,
   reminderResult = null,
-  platform = process.platform
+  platform = process.platform,
+  nodePath = process.execPath
 } = {}) {
-  const entryPath = resolve(targetDir, 'bin', 'logwork.mjs');
+  const entryPath = platform === 'win32'
+    ? win32.resolve(targetDir, 'bin', 'logwork.mjs')
+    : resolve(targetDir, 'bin', 'logwork.mjs');
   const storeLabel = credentialStoreLabel({ platform });
   const sections = [
     `logwork-cli installed to ${targetDir}.`,
@@ -424,16 +561,17 @@ export function formatSetupUserInstructions({
     'Next steps',
     ...formatNextSteps(authResult),
     '',
-    `MCP config (server name "${MCP_SERVER_NAME}", runs: node ${entryPath} mcp)`,
+    `MCP config (server name "${MCP_SERVER_NAME}", runs: ${nodePath} ${entryPath} mcp)`,
+    MCP_NODE_PATH_NOTE,
     '',
     'Cursor / Antigravity / Claude Code (.mcp.json):',
-    JSON.stringify(stdioMcpServersConfig(entryPath), null, 2),
+    JSON.stringify(stdioMcpServersConfig(entryPath, { nodePath }), null, 2),
     '',
     'Codex config.toml:',
-    formatCodexToml(entryPath),
+    formatCodexToml(entryPath, { nodePath }),
     '',
     'GitHub Copilot / VS Code mcp.json:',
-    JSON.stringify(vscodeMcpConfig(entryPath), null, 2),
+    JSON.stringify(vscodeMcpConfig(entryPath, { nodePath }), null, 2),
     '',
     'AI agent skill (log work from your commits)',
     '- Claude Code / Codex: run `logwork skill install`.',

package/commands/tui.mjs

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

package/docs/advanced.md

@@ -27,7 +27,7 @@ Supported overrides:
 ```text
 LOGWORK_PROFILE            (LOGWORK_HELPER_PROFILE still accepted)
 LOGWORK_HOME               (local state directory; LOGWORK_HELPER_HOME still accepted)
-LOGWORK_DRY_RUN=1          (RO writes return the request body instead of calling the API)
+LOGWORK_DRY_RUN=1          (RO and Jira writes return the request instead of calling the API)
 LOGWORK_API_BASE
 LOGWORK_LOGIN_URL
 LOGWORK_JIRA_BASE_URL
@@ -222,6 +222,7 @@ Useful commands inside the session:
 /projects
 /projects 5234
 /map SCB 5234
+/map --repo . 5234
 /history
 /diagnostics
 ```
@@ -285,11 +286,20 @@ Inside `logwork`, use `/history`, `/history ro`, `/history jira`, or `/history b
 
 ## Dry Run
 
-`LOGWORK_DRY_RUN=1` makes Resource Optimiser writes return the request body instead of calling the API. Reads still hit the API.
+`LOGWORK_DRY_RUN=1` makes every Resource Optimiser and Jira write return the request (`{ dryRun: true, method, path, body }`) instead of calling the API. The request never contains the token or the `Authorization` header. Reads still hit the API: Jira issue lookup and the duplicate-worklog check still call Jira, and RO previews still read RO.
+
+What a dry run reports:
+
+- RO apply summaries start with `DRY RUN`; edit, resubmit and delete return `status: "dry_run"`.
+- Jira apply (`log_jira_work` with `confirm: true`, or the terminal UI `/apply`) returns `status: "dry_run"`, `dryRun: true`, one `dry_run` result per entry with its `request`, and a summary that starts with `DRY RUN (LOGWORK_DRY_RUN=1)`.
+- Apply history records a Jira dry run with status `dry_run` and `dryRun: true` entries. They are not counted as submitted.
+- The terminal UI status bar shows `DRY RUN`.
 
 ```bash
 LOGWORK_DRY_RUN=1 logwork quick -m "Dry run task"
 LOGWORK_DRY_RUN=1 logwork edit 304032 --desc "Dry run" --yes
+npm run dry-run                     # terminal UI, RO and Jira writes stubbed
+LOGWORK_DRY_RUN=1 logwork mcp       # MCP server, RO and Jira writes stubbed
 ```
 
 In Windows PowerShell:

package/docs/mcp-setup.md

@@ -4,11 +4,17 @@
 
 For the full RO/Jira/Both processing model, mapping, reconciliation, history, reminders and updates, see the [operations guide](operations-guide.md).
 
-Every client runs `node <home>/.logwork-cli/bin/logwork.mjs mcp` under the server name `logwork`.
+Every client runs `<absolute path to node> <home>/.logwork-cli/bin/logwork.mjs mcp` under the server name `logwork`.
 
-The config uses an absolute `node` entry path instead of the `logwork` command. GUI IDEs often start without the npm global bin directory on `PATH`, so the bare command may not be found.
+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.
 
-The examples use `/Users/<user>` as a macOS placeholder. On Windows, use the path printed by `logwork setup` or `/mcp`, usually `C:\\Users\\<user>\\.logwork-cli\\bin\\logwork.mjs` inside JSON or TOML strings.
+`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).
+
+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.
+
+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.
 
 ## Cursor / Google Antigravity
 
@@ -18,7 +24,7 @@ Cursor MCP settings, or `~/.gemini/antigravity/mcp_config.json`:
 {
   "mcpServers": {
     "logwork": {
-      "command": "node",
+      "command": "<absolute path to node>",
       "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
     }
   }
@@ -31,7 +37,7 @@ Cursor MCP settings, or `~/.gemini/antigravity/mcp_config.json`:
 
 ```toml
 [mcp_servers.logwork]
-command = "node"
+command = "<absolute path to node>"
 args = ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 120
@@ -46,7 +52,7 @@ Workspace `.vscode/mcp.json`, or your VS Code user MCP config:
   "servers": {
     "logwork": {
       "type": "stdio",
-      "command": "node",
+      "command": "<absolute path to node>",
       "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
     }
   }
@@ -56,13 +62,13 @@ Workspace `.vscode/mcp.json`, or your VS Code user MCP config:
 ## Claude Code
 
 ```bash
-claude mcp add --transport stdio logwork -- node "/Users/<user>/.logwork-cli/bin/logwork.mjs" mcp
+claude mcp add --transport stdio logwork -- "<absolute path to node>" "/Users/<user>/.logwork-cli/bin/logwork.mjs" mcp
 ```
 
 From Windows PowerShell:
 
 ```powershell
-claude mcp add --transport stdio logwork -- node 'C:\Users\<user>\.logwork-cli\bin\logwork.mjs' mcp
+claude mcp add --transport stdio 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`.
@@ -89,25 +95,25 @@ 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 and hours that fill the RO remaining booked time. Returns `draftText` for `log_work`. |
+| 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 | `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. |
 | Read | `reconcile` | read-only | Compare RO and Jira hours by day. Never writes. |
 | Read | `get_history` | read-only (local) | Local apply history. Contains no credentials. |
-| RO write | `log_work` | two-call write | Create new RO entries from a weekly block (worklog task + description). |
+| RO write | `log_work` | two-call write | Create new RO entries from a weekly block (worklog task + description). The preview flags possible duplicates of existing RO entries; apply refuses them without `allowDuplicates: true`. |
 | RO write | `edit_entry` | two-call, destructive | Change hours, worklog task, type of work or description of a submitted or approved entry. Apply replaces the entry. |
 | RO write | `resubmit_entry` | two-call write | Fix and resubmit a rejected entry (hours, type, description, note to PM). |
 | RO write | `delete_entry` | two-call, destructive | Delete a submitted or approved entry. |
 | Jira write | `log_jira_work` | two-call write | Create Jira worklogs. The description becomes the worklog comment. |
-| Config | `map_project` | local write, `confirm` | Map ticket prefixes or keywords to an RO project (`.logwork.json`). |
+| Config | `map_project` | local write, `confirm` | Map ticket prefixes, keywords or git repos (`repos`) to an RO project (`.logwork.json`). |
 | Config | `reminder` | `action`: status / enable / disable / test | Native OS reminder. Every action except `status` needs `confirm: true`. |
 | Config | `update` | `action`: check / install | npm self-update. `install` needs `confirm: true`. |
 | Auth | `login` | local | `target: "ro"` (default) opens or explains a terminal login. `target: "jira"` explains how to save a PAT. Never accepts credentials. |
 
 ### Tool Name Changes From logwork-helper
 
-| logwork-helper (before 0.3.0) | logwork-cli |
+| logwork-helper (0.2.x and earlier) | logwork-cli |
 |---|---|
 | `preview_logwork_batch`, `apply_logwork_batch` | `log_work` |
 | `query_logwork` | `get_logwork` |
@@ -189,9 +195,15 @@ Expected flow:
 
 1. `get_logwork` shows which days and projects still have booked hours to fill.
 2. `draft_from_commits` (with `repos` set to the workspace folders) groups your commits into draft lines with hours.
+   - 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`.
 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)` previews the entries, then `log_work(batchId, confirm: true)` applies them.
+5. `log_work(text, projectOverrides)` previews the entries, then `log_work(batchId, confirm: true)` applies them.
+   - Preview entry ids are `<date>-<NN>`, where NN counts entry lines through the whole text. The overrides match `draftText` as returned.
+   - If lines are added, removed or reordered, the assistant renumbers the overrides.
 
 
 
@@ -227,7 +239,9 @@ A suggestion is not an approved write. It still goes through the two-call write
 2. Call `list_projects`, then `list_tasks` with the `projectId`, to pick valid worklog task names.
 3. Call `log_work` with `text`.
 4. Show the summary and ask for approval. The summary shows each line as `project - worklog task | description`, plus an approval checklist with the total hours, date range and per-project breakdown.
-5. Call `log_work` with `batchId` and `confirm: true`. Add `allowUnbooked: true` only if the user agreed to log to a project that is not booked on that date.
+5. Call `log_work` with `batchId` and `confirm: true`.
+   - Add `allowUnbooked: true` only if the user agreed to log to a project that is not booked on that date.
+   - Add `allowDuplicates: true` only if the user confirmed that lines flagged as possible duplicates are new work (see below).
 
 The `batchId` changes whenever a description or `defaultWorklogTask` changes, so an approval always covers the exact text that will be written. If an entry is unresolved, re-preview with `projectOverrides` (preview entry id → `projectMemberId`), or save a mapping with `map_project`.
 
@@ -338,6 +352,13 @@ 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`.
+- 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.
+
 Mappings are stored in one of two places:
 - **User scope (default):** `~/.logwork-cli/.logwork.json`.
 - **Project scope:** `.logwork.json` in the current repo. A repo that still has `.logwork-helper.json` keeps using that file until a `.logwork.json` exists.
@@ -349,7 +370,8 @@ Mappings are stored in one of two places:
       "projectName": "2621A-SIT-HTML BUILDER-PRJ",
       "projectMemberId": 5234,
       "tickets": ["SCB"],
-      "keywords": ["question bank", "programme", "cluster"]
+      "keywords": ["question bank", "programme", "cluster"],
+      "repos": ["/Users/me/code/html-builder"]
     }
   ]
 }
@@ -366,3 +388,23 @@ Only allow this when the matched project is correct. Apply with:
 ```json
 { "batchId": "<from preview>", "confirm": true, "allowUnbooked": true }
 ```
+
+### Possible Duplicates
+
+Before showing a `log_work` preview, the server reads your RO entries for each date in the batch (`GET /logwork/day`).
+
+An entry is flagged `possibleDuplicate` in two cases:
+- **It matches an existing RO entry** on the same date: the same worklog task (by id, or by name when RO has no id), the same hours and the same description. The description compare ignores extra spaces and letter case.
+- **It repeats an earlier line** of the same batch.
+
+The summary shows a `WARNING possible duplicate` line for each one.
+
+Apply refuses the whole batch while duplicates remain, and nothing is written. The preview stays cached, so after the user confirms the lines are really new work, call again with the same `batchId`:
+
+```json
+{ "batchId": "<from preview>", "confirm": true, "allowDuplicates": true }
+```
+
+Usually the better fix is to drop the duplicated lines and preview again.
+
+If RO cannot be read for a date (other than a login problem), the preview is not blocked. Its summary notes that the duplicate check was skipped for that date. In the terminal UI, `/apply` asks a separate question before submitting possible duplicates; the default answer is no.

package/docs/operations-guide.md

@@ -19,6 +19,8 @@ npm install -g logwork-cli
 logwork 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:
 
 ```bash
@@ -47,7 +49,7 @@ Resource Optimiser credentials and Jira PATs are never accepted by MCP tools. Th
 | Delete RO entry | `logwork delete` | - | `delete_entry` | Apply call only |
 | Log Jira | - | `/logwork jira` | `log_jira_work` | Apply call only |
 | Log Both | - | `/logwork both` | `log_work` + `log_jira_work` separately | Apply calls only |
-| Project mapping | - | `/projects`, `/map` | `list_projects`, `map_project` | Local config only |
+| Project mapping | - | `/projects`, `/map`, `/map --repo` | `list_projects`, `map_project` | Local config only |
 | RO worklog task catalog | - | - | `list_tasks` | No |
 | Reconcile RO/Jira | `logwork reconcile` | `/reconcile` | `reconcile` | No |
 | Apply history | `logwork history` | `/history` | `get_history` | No |
@@ -186,6 +188,8 @@ MCP uses:
 
 Every entry must contain exactly one Jira issue key. RO is not written by this flow.
 
+In dry run (`LOGWORK_DRY_RUN=1`), the Jira apply still reads Jira for the duplicate check but sends no worklog. It returns `status: "dry_run"` with the request each entry would send, and the summary starts with `DRY RUN`. Apply history records it as `dry_run`, not as submitted.
+
 ### Both
 
 Use the combined terminal flow when the same date/tasks should be sent to both systems:
@@ -269,6 +273,8 @@ Submitted 2 entries, 3h total.
 
 If a valid membership is not booked for the selected date, preview prefixes the entry with `UNBOOKED`. Applying it requires a second decision through `allowUnbooked: true`. An unresolved project always blocks apply.
 
+Preview also reads the RO entries of each date. An entry with the same worklog task, hours and description as an existing entry (or an earlier line of the batch) gets a `WARNING possible duplicate` line. Applying it requires a separate decision: `allowDuplicates: true`, or a yes to the duplicate question in the terminal UI. Without it, nothing is written. If the day cannot be read, the preview notes that the duplicate check was skipped and does not block.
+
 ## Jira Processing Example
 
 For each entry, Jira preview:
@@ -431,6 +437,8 @@ Other operations:
 
 ```bash
 logwork reminder enable --time 18:00 --target ro
+logwork reminder enable --repo ~/code/app --repo ~/code/api
+logwork reminder enable --no-repos
 logwork reminder status
 logwork reminder test
 logwork reminder disable
@@ -445,9 +453,19 @@ 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 `node ~/.logwork-cli/bin/logwork.mjs reminder run --home ~/.logwork-cli`.
+- 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.
 - Enabling or disabling the reminder also removes a leftover `logwork-helper` schedule.
 
+Commit evidence:
+
+- `--repo <path>` (repeatable) saves git repos in `reminder.json` as absolute paths. MCP: `reminder` with `action: "enable"` and `repos`. `--repo` or `repos` replaces the saved list, `--no-repos` or `repos: []` clears it, and leaving them out keeps it.
+- Repos listed in a project mapping's `repos` field are added.
+- When RO hours are missing, the reminder reads your commits today in those repos (read-only, the same reader as `logwork commits`, without another RO query) and adds `Hôm nay: <n> commit trong <k> repo`. The action line then points to `logwork commits today`.
+- Run outside a git repo, `logwork commits today` falls back to the reminder repos.
+- With no repos, no commits today, or any error reading them (missing repo, git not on the scheduler's `PATH`, a 20-second timeout), the plain message is shown.
+- The notification stays a plain OS notification on both platforms (macOS `display notification`, a Windows toast). It has no buttons; open a terminal and run the command shown.
+
 Example Both notification:
 
 ```text
@@ -458,6 +476,19 @@ Jira: chưa có worklog hôm nay
 Mở Terminal và chạy: logwork
 ```
 
+With reminder repos and commits today:
+
+```text
+Logwork hôm nay chưa hoàn tất
+RO: 4/8h, còn thiếu 4h
+Jira: chưa có worklog hôm nay
+Hôm nay: 5 commit trong 2 repo
+
+Mở Terminal và chạy: logwork commits today (bản nháp từ commit)
+```
+
+`logwork reminder test` sends a sample in this format.
+
 The notification text is localized in Vietnamese. The OS schedule stores only fixed Node/script paths and reads credentials from the OS credential store when it runs.
 
 ## End-User Updates
@@ -535,6 +566,7 @@ The release doctor checks package version consistency, self-dependencies, clean/
 | Apply history | `.logwork-cli/apply-ledger.json` | No |
 | 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 |
 | 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.
@@ -549,7 +581,9 @@ Migration from `logwork-helper` happens on the first run, unless `LOGWORK_HOME`
 Run the cross-platform suite:
 
 ```bash
+npm run lint
 npm test
+npm run test:coverage   # same suite with coverage thresholds; CI runs it on macOS
 git diff --check
 npm pack --dry-run
 ```
@@ -582,6 +616,7 @@ 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 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).

package/docs/recipes.md

@@ -39,6 +39,27 @@ List the Resource Optimiser worklog tasks for my booked project today, then log
 
 The assistant uses `list_projects` and `list_tasks`, writes `+2 <task> | <description>`, and previews. If you write lines without `|`, the assistant can pass `defaultWorklogTask` (for example `Feature Development`) so each line becomes the description.
 
+## Log From Commits Into The Right Projects
+
+Tell logwork which RO project each repo belongs to, once:
+
+```text
+logwork
+/map --repo ~/code/portal 5234
+```
+
+or ask your assistant: `Map the repo /Users/me/code/portal to my Portal project` (it calls `list_projects`, then `map_project` with `repos` after you approve).
+
+Then `logwork commits yesterday` (or the assistant's `draft_from_commits`) puts that repo's commits on project 5234. The hours come from what is still free on that project: booked minus logged. If the project is already full, its lines get 0h and the summary says so. Repos without a mapping fall back to ticket/keyword mappings and that day's bookings, and are listed at the end so you can map them.
+
+The assistant passes the draft's `projectOverrides` to `log_work` with the same text, so each line is logged to the project the draft chose.
+
+## Handle A Possible Duplicate RO Entry
+
+If a `log_work` preview shows `WARNING possible duplicate`, RO already has an entry on that date with the same worklog task, hours and description, or the batch repeats a line. This often happens after an agent re-ran or a batch failed partway.
+
+Check `/query` (or `get_logwork`) first. If the work is already logged, drop the line and preview again. Only if it really is separate work, approve it explicitly: in the terminal UI answer yes to the duplicate question, or let the assistant confirm with `allowDuplicates: true`. Without that, apply writes nothing.
+
 ## Edit Existing Resource Optimiser Logwork
 
 Find the RO logwork ID with `logwork query this-week`, `/query this-week`, or by asking the assistant to call `get_logwork`. Then use Terminal:
@@ -214,6 +235,12 @@ RO-only reminder at 18:00:
 logwork reminder enable --time 18:00 --target ro
 ```
 
+Add commit evidence from your repos (shown when RO hours are missing):
+
+```bash
+logwork reminder enable --repo ~/code/app --repo ~/code/api
+```
+
 Send a sample notification and inspect scheduler status:
 
 ```bash

package/docs/security.md

@@ -111,7 +111,8 @@ The runtime and local state live in `~/.logwork-cli` (`%USERPROFILE%\.logwork-cl
 | `manual-drafts.json` | Terminal UI drafts. |
 | `apply-ledger.json` | Sanitized apply history. |
 | `update-state.json` | Update check cache: package name, latest SemVer, and check timestamp. Expires after 24 hours and contains no npm credentials. |
-| `reminder.json`, `reminder-state.json` | Reminder config: enabled state, local time, target and weekdays. Last-run state: sanitized timestamps and status summaries. |
+| `reminder.json`, `reminder-state.json` | Reminder config: enabled state, local time, target, weekdays and optional git repo paths for the commit summary. Last-run state: sanitized timestamps and status summaries. |
+| `runtime.json` | The Node path and version `logwork setup` ran with, its install time and the package version. |
 | `diagnostics/` | Sanitized diagnostics reports from `logwork doctor`. |
 
 The apply ledger stores the target, flow target, batch ID, timestamp, workspace path, entry metadata, and submitted/failed/blocked status. It does not store credentials, cookies, or raw API responses, and token-like error text is redacted before writing.
@@ -145,6 +146,7 @@ The macOS launch agent and Windows scheduled task contain only fixed Node and sc
 - `reminder` with `action: "status"` is read-only.
 - `enable`, `disable` and `test` require `confirm: true`. They never accept arbitrary scheduler commands, paths, JQL, or credentials.
 - The background reminder reads RO and Jira sessions from the OS credential store only when it runs. Notification and state text are sanitized and never include raw API responses.
+- With reminder repos, the background reminder runs read-only `git log` in those repos and shows only commit and repo counts. Commit subjects and paths are not put in the notification or the state file.
 
 **Login and diagnostics**
 - `login` never accepts credentials. It only opens or explains a terminal login.