logwork-cli 1.1.1 → 1.2.0

package/README.md

@@ -120,12 +120,13 @@ 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 (`/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.
+- **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.
 
 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.
 - **MCP prompt `log_from_commits`** gives an agent the full procedure:
   1. find gaps with `get_logwork`;
   2. draft from commits;
@@ -186,13 +187,13 @@ The default tasks shared by all projects are:
 
 `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`).
 
-Every client runs the same thing, `node ~/.logwork-cli/bin/logwork.mjs mcp`, under the server name `logwork`:
+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`:
 
 ```json
 {
   "mcpServers": {
     "logwork": {
-      "command": "node",
+      "command": "/Users/you/.nvm/versions/node/v24.1.0/bin/node",
       "args": ["/Users/you/.logwork-cli/bin/logwork.mjs", "mcp"]
     }
   }
@@ -202,9 +203,11 @@ Every client runs the same thing, `node ~/.logwork-cli/bin/logwork.mjs mcp`, und
 For Claude Code, run:
 
 ```bash
-claude mcp add --transport stdio logwork -- node ~/.logwork-cli/bin/logwork.mjs mcp
+claude mcp add --transport stdio logwork -- "$(which node)" ~/.logwork-cli/bin/logwork.mjs mcp
 ```
 
+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.
+
 Restart or reload the IDE's MCP tools after saving.
 
 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**:
@@ -289,7 +292,7 @@ In the terminal UI, `/logwork` opens a target picker. `/logwork ro` writes Resou
 - `/query this-week`
 - `/reconcile`
 - `/projects`
-- `/map SCB 5234`
+- `/map SCB 5234` (ticket prefix) or `/map --repo . 5234` (this git repo, for commit drafts)
 - `/history`
 - `/diagnostics`
 
@@ -298,6 +301,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 +309,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. 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.
 
 ## 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`

package/commands/commits.mjs

@@ -1,5 +1,9 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { draftLogworkFromCommits } from '../lib/commit-workflow.mjs';
 import { normalizeReconciliationPeriod } from '../lib/reconciliation-workflow.mjs';
+import { loadReminderConfig } from '../lib/reminder-config.mjs';
+import { collectReminderRepos } from '../lib/reminder-workflow.mjs';
 
 // `logwork commits [period] [--repo path]... [--author x] [--no-bookings] [--json]`:
 // turn your git commits into a logwork draft. Read-only.
@@ -44,29 +48,71 @@ 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
+} = {}) {
   const options = parseCommitsArgs(args);
   if (options.help) {
     print(formatCommitsHelp());
     return 0;
   }
+  // 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 result = await draft({
     period: options.period,
-    repos: options.repos,
+    repos,
     author: options.author,
     useBookings: options.useBookings
   });
-  print(options.json ? JSON.stringify(result, null, 2) : result.summary);
+  if (options.json) {
+    print(JSON.stringify(result, null, 2));
+  } else {
+    print(fallbackNote ? `${fallbackNote}\n\n${result.summary}` : result.summary);
+  }
   return 0;
 }
 
+// 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]
 
 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,8 +120,13 @@ 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 (/map
+  --repo in the terminal UI, or map_project), else ticket/keyword mappings and
+  that day's bookings.
+- 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
 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/quick.mjs

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

package/commands/reminder.mjs

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

package/commands/setup.mjs

@@ -1,14 +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 { npmInvocation } from '../lib/npm-command.mjs';
-import { helperHome } from '../lib/paths.mjs';
+import { writeRuntimeInfo } from '../lib/node-runtime.mjs';
+import { RUNTIME_INFO_FILE_NAME, helperHome } from '../lib/paths.mjs';
 import {
+  MCP_NODE_PATH_NOTE,
   MCP_SERVER_NAME,
-  defaultMcpServerPath,
   formatCodexToml,
   stdioMcpServersConfig,
   vscodeMcpConfig
@@ -65,6 +66,7 @@ export async function installUserRuntime({
   installFn = installDependencies,
   linkFn = linkGlobalBinaries,
   authFn = maybeRunAuthLogin,
+  runtimeInfoFn = recordRuntimeInfo,
   reminderFn = refreshReminderSchedule,
   printFn = printMcpInstructions
 }) {
@@ -76,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);
 
@@ -88,17 +91,44 @@ 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 };
   }
@@ -507,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}.`,
@@ -528,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: