logwork-cli 1.1.1 → 1.3.0

package/docs/mcp-setup.md

@@ -1,75 +1,130 @@
 # MCP Setup
 
-`logwork setup` prints copy-ready configs that use your real path. You can also open the terminal UI with `logwork` and type `/mcp`, or `/mcp <client>` for a single client.
+Run `logwork setup` and answer yes for each client. That is the whole setup: you do not edit MCP JSON or TOML yourself, and you do not need to know where Node is installed.
 
 For the full RO/Jira/Both processing model, mapping, reconciliation, history, reminders and updates, see the [operations guide](operations-guide.md).
 
-Every client runs `node <home>/.logwork-cli/bin/logwork.mjs mcp` under the server name `logwork`.
+## Automatic Setup
 
-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.
+`logwork setup` (and `logwork mcp install` at any time later) looks for these clients and adds or updates the `logwork` server in each one it finds. A client counts as found only when its config directory or CLI exists; setup never creates config for a client you do not have.
 
-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.
+| Client | Detected by | What is changed |
+|---|---|---|
+| Claude Code | `claude` on `PATH`, or `~/.claude.json` | `claude mcp remove --scope user logwork`, then `claude mcp add --scope user logwork -- <command> <args>`. Without the CLI: the top-level `mcpServers` in `~/.claude.json`. |
+| Cursor | `~/.cursor` | `mcpServers.logwork` in `~/.cursor/mcp.json` |
+| Codex | `~/.codex` | the `[mcp_servers.logwork]` table in `~/.codex/config.toml` |
+| VS Code (user) | `~/Library/Application Support/Code/User` (macOS), `%APPDATA%\Code\User` (Windows) | `servers.logwork` (`"type": "stdio"`) in `mcp.json` there |
+| Google Antigravity | `~/.gemini/antigravity` | `mcpServers.logwork` in `~/.gemini/antigravity/mcp_config.json` |
+
+How files are edited:
+- Each file is read, parsed and merged. Only the `logwork` entry changes; other servers and settings stay as they are. Extra fields you added to the `logwork` entry (such as `env`) are kept, except in Codex, where the whole `[mcp_servers.logwork]` table (with sub-tables such as `[mcp_servers.logwork.env]`) is replaced.
+- An old `logwork-helper` entry is removed. In Claude Code, a stale project-scope (`--scope local`) `logwork` entry is removed too, because it would hide the user-scope one.
+- Before the first change, the file is copied to `<file>.logwork-backup-<YYYYMMDDHHmmss>` next to it. Then the new file is written atomically. A symlinked config is written through the link.
+- When the entry is already current, nothing is written and no backup is made.
+- When a file does not parse cleanly (JSON with comments or trailing commas, TOML with an unusual layout such as an inline `mcp_servers` table), it is not touched. The result says "could not update automatically" and shows the snippet to paste.
+
+Commands:
+
+```bash
+logwork mcp status                     # per client: current, stale (and why), missing, leftover logwork-helper
+logwork mcp install                    # asks once per client that needs a change (default: yes)
+logwork mcp install --client cursor    # only some clients (repeatable: claude, cursor, codex, vscode, antigravity)
+logwork mcp install --dry-run          # show the planned changes, write nothing
+logwork mcp install --yes              # no questions
+logwork setup --yes                    # setup, updating every detected client without asking
+logwork setup --no-mcp-install         # setup without touching MCP configs
+```
+
+When setup does not run in a terminal (for example from `logwork update`), it only prints what `logwork mcp install` would change.
+
+`logwork doctor` includes the same per-client check.
+
+## What The Configs Run
+
+Every client runs one command under the server name `logwork`. The command never names a Node version, so `nvm install`, `brew upgrade node` or a new Node installer do not break it:
+
+- **macOS:** `~/.logwork-cli/bin/logwork-launch mcp`. `logwork setup` writes this small `sh` script. It starts `~/.logwork-cli/bin/logwork.mjs` with the first Node 22+ it finds, in this order:
+  1. the Node that ran `logwork setup`;
+  2. `node` on `PATH`;
+  3. the newest nvm Node (`$NVM_DIR` or `~/.nvm`);
+  4. Volta (`~/.volta/bin/node`) and the fnm default;
+  5. `/opt/homebrew/bin/node`, `/usr/local/bin/node`.
+
+  If none is found, it prints one line ("install Node.js 22 or newer, or run `logwork setup` again") and exits with code 127.
+- **Windows:** `<node.exe> %USERPROFILE%\.logwork-cli\bin\logwork.mjs mcp`. GUI clients would need `cmd /c` to run a `.cmd` launcher, so the config uses a stable `node.exe` instead:
+  - when Node runs from an nvm-windows version folder and `NVM_SYMLINK` is set, `%NVM_SYMLINK%\node.exe`, which follows `nvm use`;
+  - otherwise the Node that ran setup, usually `C:\Program Files\nodejs\node.exe`, which an installer upgrade keeps.
+
+  With any other Node location (Scoop, a portable zip), re-run `logwork setup` after moving or upgrading Node.
+
+The paths are absolute because GUI IDEs (started from the Dock, Finder or Start menu) often do not get your shell's `PATH`, so a bare `node` or `logwork` would not be found.
 
-## Cursor / Google Antigravity
+## Manual Setup (Fallback)
 
-Cursor MCP settings, or `~/.gemini/antigravity/mcp_config.json`:
+Use this only for a client that `logwork setup` does not support, or one whose file it could not update. `logwork setup` prints the snippet for each client it could not update. You can also open the terminal UI with `logwork` and type `/mcp`, or `/mcp <client>` for a single client; both print your real paths.
+
+The examples use `/Users/<user>` as a placeholder. On Windows, use the paths printed by `logwork setup` or `/mcp`, for example `"command": "C:\\Program Files\\nodejs\\node.exe"` and `"args": ["C:\\Users\\<user>\\.logwork-cli\\bin\\logwork.mjs", "mcp"]` inside JSON or TOML strings.
+
+### Cursor / Google Antigravity
+
+`~/.cursor/mcp.json`, or `~/.gemini/antigravity/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
     "logwork": {
-      "command": "node",
-      "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+      "command": "/Users/<user>/.logwork-cli/bin/logwork-launch",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-## Codex
+### Codex
 
 `~/.codex/config.toml`, or project `.codex/config.toml`:
 
 ```toml
 [mcp_servers.logwork]
-command = "node"
-args = ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+command = "/Users/<user>/.logwork-cli/bin/logwork-launch"
+args = ["mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 ```
 
-## GitHub Copilot / VS Code
+### GitHub Copilot / VS Code
 
-Workspace `.vscode/mcp.json`, or your VS Code user MCP config:
+Workspace `.vscode/mcp.json`, or your VS Code user `mcp.json`:
 
 ```json
 {
   "servers": {
     "logwork": {
       "type": "stdio",
-      "command": "node",
-      "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+      "command": "/Users/<user>/.logwork-cli/bin/logwork-launch",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-## Claude Code
+### Claude Code
 
 ```bash
-claude mcp add --transport stdio logwork -- node "/Users/<user>/.logwork-cli/bin/logwork.mjs" mcp
+claude mcp add --transport stdio --scope user logwork -- ~/.logwork-cli/bin/logwork-launch mcp
 ```
 
 From Windows PowerShell:
 
 ```powershell
-claude mcp add --transport stdio logwork -- node 'C:\Users\<user>\.logwork-cli\bin\logwork.mjs' mcp
+claude mcp add --transport stdio --scope user logwork -- 'C:\Program Files\nodejs\node.exe' 'C:\Users\<user>\.logwork-cli\bin\logwork.mjs' mcp
 ```
 
 Or add the Cursor JSON above to the project `.mcp.json`.
 
-Templates are also in [examples/mcp](../examples/mcp/).
+Templates (macOS form) are also in [examples/mcp](../examples/mcp/); on Windows, use the paths printed by `/mcp`.
 
-If you used `logwork-helper` before, delete its old MCP entry. It points at `~/.logwork-helper/mcp-server.mjs`, which is the old runtime.
+If you used `logwork-helper` before and edit configs by hand, delete its old MCP entry. It points at `~/.logwork-helper/mcp-server.mjs`, which is the old runtime.
 
 ## Exposed Tools
 
@@ -89,18 +144,18 @@ 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`, `unmappedRepos`, and `repoSuggestions` (likely project per unmapped repo, with reasons) plus `projectCandidates`. |
 | Read | `list_projects` | read-only | RO memberships (`projectMemberId`, `projectId`, `projectName`) and local mappings. |
 | Read | `list_tasks` | read-only | RO worklog task catalog for one `projectId`: id, name, type of work, and when to use each task. |
 | Read | `get_jira_issue` | read-only | Jira issue key, summary and status. |
 | 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. |
@@ -189,9 +244,18 @@ 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` (repo paths whose lines got no project), `repoSuggestions` and `projectCandidates`:
+     - `repoSuggestions` maps each unmapped repo to up to 5 projects, best first: `{ projectName, projectMemberId, projectId, score, reasons }`. The evidence is a ticket from the repo's commits that you logged to the project in the last 30 days, the repo folder or git remote name matching the project name (its acronym in parentheses or its initials), and the only project booked on the repo's commit days. `reasons` are readable, for example `ticket FCS-12 was logged to this project on 2026-11-03` or `repo name matches FCS`.
+     - `projectCandidates` lists every member project (booked ones first).
+     - The assistant asks one short question per repo by project name ("Is fcs-web part of GKE Fair Chem System (FCS)?"). On a yes it calls `map_project` with `projectName` (or the suggestion's `projectMemberId`), `repos` and `confirm: true`, then runs `draft_from_commits` again.
 3. `list_tasks` confirms the worklog task names for each project.
 4. The assistant rewrites vague descriptions, shows you the block and waits for approval.
-5. `log_work(text)` 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 +291,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 +404,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 confirms the top `repoSuggestions` entry with you by name, then calls `map_project` with `projectName`, `repos` (absolute paths) and `confirm: true`.
+- At least one ticket prefix or repo is required.
+- A subfolder is stored as the root of its repo.
+- Paths are compared without trailing separators, and case-insensitively on Windows.
+- In a terminal, `logwork commits` asks for each unmapped repo with a picker (likely project first). In the terminal UI, `/map --repo [path]` opens the same picker and `/map --repo [path] <project name>` maps by name. The path defaults to the current folder.
+
 Mappings are stored in one of two places:
 - **User scope (default):** `~/.logwork-cli/.logwork.json`.
 - **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 +422,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 +440,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
 ```
 
+`logwork setup` also writes the launcher (`~/.logwork-cli/bin/logwork-launch` on macOS) and adds the `logwork` MCP server to the clients it finds (Claude Code, Cursor, Codex, VS Code, Google Antigravity), asking once per client. Each edited config is backed up first. Options: `--yes` (no questions), `--no-mcp-install` (do not touch MCP configs). Check or redo it later with `logwork mcp status` and `logwork mcp install`; see [MCP setup](mcp-setup.md#automatic-setup).
+
 Upgrading from `logwork-helper`: run `npm uninstall -g logwork-helper` first. Both packages provide a `logwork` command, and npm refuses to overwrite it (`EEXIST`). If `~/.logwork-helper` was already deleted, the uninstall leaves broken links behind; remove them with `P="$(npm prefix -g)"; rm -f "$P/bin/logwork" "$P"/bin/logwork-helper* "$P/lib/node_modules/logwork-helper"`, or run `npx logwork-cli@latest setup`, which removes them.
 
 Authenticate each target from Terminal:
@@ -49,7 +51,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 |
@@ -188,6 +190,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:
@@ -271,6 +275,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:
@@ -344,6 +350,14 @@ RO project mapping can use:
 - Task keywords, for example `maintenance mode`.
 - Explicit project selection during preview.
 - Jira project key/name metadata in the terminal Both flow to rank RO memberships.
+- Git repo roots (`repos`), for commit drafts.
+
+A repo with no mapping is mapped once, in place, without ids:
+- `logwork commits` in an interactive terminal asks `Which RO project does <repo> belong to?` with the likely project preselected, saves the choice and redoes the draft (`--no-prompt` turns this off).
+- In the terminal UI, `/map --repo [path]` opens the same picker; `/map --repo [path] <project name>` maps by name (case-insensitive, then a unique part of the name; an ambiguous name opens the picker).
+- MCP: `draft_from_commits` returns `repoSuggestions` per unmapped repo; the assistant confirms the top one by name and calls `map_project` with `projectName` and `repos`.
+
+The likely project comes from ticket keys in the repo's commits that you logged to a project in the last 30 days, then the repo folder or git remote name against the project name (acronym in parentheses, initials, shared words), then the only project booked on the repo's commit days.
 
 Example MCP sequence:
 
@@ -433,6 +447,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
@@ -447,9 +463,21 @@ 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 the same command as the MCP configs with `reminder run --home ~/.logwork-cli`:
+  - macOS: `~/.logwork-cli/bin/logwork-launch`, which finds a Node 22+ itself, so a Node upgrade does not break the reminder;
+  - Windows: a stable `node.exe` (the nvm-windows symlink, or `C:\Program Files\nodejs\node.exe`) plus `~/.logwork-cli/bin/logwork.mjs`.
+- `logwork reminder status` and `logwork doctor` warn when the scheduled command is missing, when the launcher finds no usable Node, and when a schedule from an older version still runs a raw Node path. Run `logwork setup` (or `logwork reminder enable`) to re-register it.
 - Enabling or disabling the reminder also removes a leftover `logwork-helper` schedule.
 
+Commit evidence:
+
+- `--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
@@ -460,6 +488,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
@@ -537,6 +578,9 @@ 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 |
+| Launcher (macOS) | `.logwork-cli/bin/logwork-launch`, written by `logwork setup` | No |
+| MCP config backups | `<client config>.logwork-backup-<timestamp>`, next to each edited client config | No |
 | RO/Jira sessions | OS credential store, service `logwork-cli` | Yes |
 
 The helper home is `~/.logwork-cli` on macOS and `%USERPROFILE%\.logwork-cli` on Windows. `LOGWORK_HOME` overrides it; the older `LOGWORK_HELPER_HOME` is still honored.
@@ -551,7 +595,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
 ```
@@ -584,6 +630,8 @@ Recommended end-user checks after installation:
 - Partial Both result: inspect `/history both`, then preview only the missing target.
 - npm `E401`: refresh npm login with `npm login --registry=https://registry.npmjs.org/`.
 - Reminder config/scheduler mismatch: rerun `reminder enable` or `reminder disable`.
+- MCP client or reminder does not start after a Node change: run `logwork doctor` or `logwork mcp status`. `logwork setup` rewrites the launcher, re-registers the reminder and updates the MCP configs it can edit; paste the printed snippet only for a client it reports as "could not update automatically".
+- `logwork mcp install` reports "could not update automatically": the file has comments, trailing commas or an unusual TOML layout. Paste the printed snippet by hand, or remove the comments and run it again.
 - MCP after update: restart or reload the MCP connection.
 
 For client configuration details, see [MCP setup](mcp-setup.md). For security boundaries and stored-data details, see [Security and auth](security.md). For copy-ready task recipes, see [Quick recipes](recipes.md).

package/docs/recipes.md

@@ -39,6 +39,40 @@ 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
+
+Each repo needs its RO project once. Just run the draft:
+
+```bash
+logwork commits yesterday
+```
+
+For a repo with no project yet, it asks in place:
+
+```text
+Which RO project does portal-web belong to?
+› Customer Portal · ticket CP-12 was logged to this project on 2026-11-03
+  GKE Fair Chem System (FCS)
+  Managed Hosting
+  Skip for now
+```
+
+The likely project is preselected. Press Enter to save it as a repo mapping; the draft is then redone with that repo's lines on the project. `Skip for now` asks again next time; `--no-prompt` never asks.
+
+Other ways to map a repo, all without ids:
+- Terminal UI: `/map --repo` (this folder) or `/map --repo ~/code/portal` opens the same picker; `/map --repo ~/code/portal Customer Portal` maps by name (a unique part of the name is enough).
+- Assistant: `draft_from_commits` returns `repoSuggestions`, so the assistant asks "Is portal-web part of Customer Portal?" and calls `map_project` with `projectName` and `repos` after you say yes.
+
+Mapped repos put their commits on that project. 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.
+
+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 +248,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,12 +111,32 @@ 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. |
+| `bin/logwork-launch` (macOS) | The launcher MCP configs and the reminder run. A `sh` script with the runtime path and the recorded Node path, nothing else. |
 | `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.
 
-The macOS launch agent and Windows scheduled task contain only fixed Node and script paths (`bin/logwork.mjs reminder run`). They never contain RO tokens, Jira PATs, passwords, or API responses.
+The macOS launch agent runs `bin/logwork-launch reminder run`, and the Windows scheduled task runs a fixed `node.exe` with `bin/logwork.mjs reminder run`. They never contain RO tokens, Jira PATs, passwords, or API responses.
+
+## MCP Client Configs
+
+`logwork setup` and `logwork mcp install` edit the MCP config of the clients they find, after asking (or with `--yes`):
+
+| Client | File or command |
+| --- | --- |
+| Claude Code | `claude mcp remove` / `claude mcp add --scope user` (or `~/.claude.json` without the CLI) |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex | `~/.codex/config.toml` |
+| VS Code | user `mcp.json` (`~/Library/Application Support/Code/User`, `%APPDATA%\Code\User`) |
+| Google Antigravity | `~/.gemini/antigravity/mcp_config.json` |
+
+- Only the `logwork` server entry is written, plus removal of an old `logwork-helper` entry (and, in Claude Code, a stale project-scope `logwork` entry). Other servers and settings are kept.
+- The entry holds only `command` and `args` (the launcher or `node.exe`, the runtime path and `mcp`). No token, PAT, password, cookie or email is ever written to an MCP config.
+- Before changing a file, it is copied to `<file>.logwork-backup-<YYYYMMDDHHmmss>` in the same folder, with the same permissions as the original. The new file is written atomically. Backups are never deleted automatically; remove them when you no longer need them. A backup can contain other servers' settings (for example API keys in their `env`), exactly as the original file does.
+- A file that does not parse cleanly (comments, trailing commas, unusual TOML) is never written; the snippet is printed instead.
+- `logwork mcp install --dry-run` and `logwork mcp status` only read.
 
 ## Safety Model
 
@@ -145,6 +165,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.

package/examples/mcp/antigravity.mcp_config.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "logwork": {
-      "command": "node",
-      "args": ["<home>/.logwork-cli/bin/logwork.mjs", "mcp"]
+      "command": "<home>/.logwork-cli/bin/logwork-launch",
+      "args": ["mcp"]
     }
   }
 }

package/examples/mcp/codex.config.toml

@@ -1,5 +1,5 @@
 [mcp_servers.logwork]
-command = "node"
-args = ["<home>/.logwork-cli/bin/logwork.mjs", "mcp"]
+command = "<home>/.logwork-cli/bin/logwork-launch"
+args = ["mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 120

package/examples/mcp/copilot.mcp.json

@@ -2,8 +2,8 @@
   "servers": {
     "logwork": {
       "type": "stdio",
-      "command": "node",
-      "args": ["<home>/.logwork-cli/bin/logwork.mjs", "mcp"]
+      "command": "<home>/.logwork-cli/bin/logwork-launch",
+      "args": ["mcp"]
     }
   }
 }