logwork-cli 0.0.0-stage → 1.0.0

package/docs/advanced.md

@@ -0,0 +1,334 @@
+# Advanced Usage
+
+This file keeps technical details out of the main README. Most users only need `npm install -g logwork-cli`, `logwork setup`, `logwork login`, and `/mcp`.
+
+For one consolidated reference covering all newly integrated CLI and MCP workflows, see the [integrated operations guide](operations-guide.md).
+
+## Environment Configuration
+
+Defaults target the current Resource Optimiser / Vinova profile. For non-default deployments, configure the runtime with environment variables instead of editing source:
+
+```bash
+LOGWORK_PROFILE=vinova
+LOGWORK_API_BASE=https://api.resourceoptimiser.com/api/v1
+LOGWORK_LOGIN_URL=https://app.resourceoptimiser.com/vinova
+LOGWORK_JIRA_BASE_URL=https://jira-vnv.vinova.sg
+LOGWORK_JIRA_STARTED_TIME=09:00
+LOGWORK_TIMEZONE=Asia/Ho_Chi_Minh
+LOGWORK_KEYCLOAK_AUTH_URL=https://keycloak.vinova.sg/auth/realms/resource/protocol/openid-connect/auth
+LOGWORK_KEYCLOAK_TOKEN_URL=https://keycloak.vinova.sg/auth/realms/resource/protocol/openid-connect/token
+LOGWORK_KEYCLOAK_REDIRECT_URI=https://app.resourceoptimiser.com/vinova/check-login
+```
+
+In Windows PowerShell, set the same values with `$env:NAME = "value"` before running `logwork`.
+
+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_API_BASE
+LOGWORK_LOGIN_URL
+LOGWORK_JIRA_BASE_URL
+LOGWORK_JIRA_STARTED_TIME
+LOGWORK_TIMEZONE
+LOGWORK_TOKEN_KEY
+LOGWORK_ALLOWED_SAFARI_HOSTS
+LOGWORK_KEYCLOAK_AUTH_URL
+LOGWORK_KEYCLOAK_TOKEN_URL
+LOGWORK_KEYCLOAK_CLIENT_ID
+LOGWORK_KEYCLOAK_REDIRECT_URI
+LOGWORK_KEYCLOAK_SCOPE
+LOGWORK_KEYCLOAK_RESPONSE_MODE
+LOGWORK_KEYCLOAK_RESPONSE_TYPE
+LOGWORK_HTTP_TIMEOUT_MS
+LOGWORK_HTTP_READ_RETRIES
+LOGWORK_HTTP_RETRY_DELAY_MS
+LOGWORK_DAY_LOG_CONCURRENCY
+```
+
+URL and numeric overrides are validated on startup. Invalid values fail fast so the helper does not log work against an unintended endpoint.
+
+## Install Alternatives
+
+The recommended install path is:
+
+```bash
+npm install -g logwork-cli
+logwork setup --no-login
+```
+
+One-off setup without a prior global install:
+
+```bash
+npx -y logwork-cli setup --no-login
+```
+
+Yarn global install:
+
+```bash
+yarn global add logwork-cli
+logwork setup --no-login
+```
+
+To install and start auth immediately:
+
+```bash
+logwork setup --login
+```
+
+Use `--no-login` when installing in scripts or CI.
+
+`logwork setup` copies the package into `~/.logwork-cli`, runs `npm ci --omit=dev` there, removes a globally installed `logwork-helper` package (its `logwork` bin would block linking), runs `npm link`, re-registers an enabled reminder, and prints MCP configs.
+
+## Update
+
+```bash
+logwork update check             # uses a 24-hour cache
+logwork update check --force     # query npm now
+logwork update install           # interactive confirmation
+logwork update install --version 0.3.1 --yes
+```
+
+The installer accepts only the version currently published under npm's `latest` tag. It runs `npm exec --package=logwork-cli@<version> -- logwork setup --no-login` with a fixed argument list. Then it verifies the copied `package.json` version in `~/.logwork-cli`.
+
+Project mappings, drafts, apply history, update cache, and OS credential-store records are preserved.
+
+The `logwork` terminal UI performs a cached check at startup and shows a one-line notice when an update exists. Registry failures are ignored in this startup path, so offline use still works.
+
+MCP exposes the same update through the `update` tool:
+- `action: "check"` is read-only.
+- `action: "install"` requires `confirm: true`. It does not accept a registry or an arbitrary command, and it re-checks npm immediately before installing.
+
+Reconnect or reload the IDE MCP server after updating.
+
+Manual recovery path:
+
+```bash
+npm install -g logwork-cli@latest
+logwork setup --no-login
+```
+
+## Native Logwork Reminder
+
+Enable the default weekday reminder:
+
+```bash
+logwork reminder enable
+```
+
+Defaults:
+
+- Local OS time `17:00`.
+- Monday-Friday.
+- Target `both`.
+- At most one notification per day.
+- No notification when all enabled checks are complete.
+
+Customize the time or target:
+
+```bash
+logwork reminder enable --time 18:00 --target ro
+logwork reminder enable --time 17:45 --target jira
+```
+
+Inspect, test, or remove the reminder:
+
+```bash
+logwork reminder status
+logwork reminder test
+logwork reminder disable
+```
+
+How the reminder is scheduled:
+- **macOS:** it writes `~/Library/LaunchAgents/sg.vinova.logwork-cli.reminder.plist` and loads it with `launchctl`.
+- **Windows:** it creates the interactive user task `Logwork Reminder` with `schtasks.exe`.
+
+Both schedulers run `node ~/.logwork-cli/bin/logwork.mjs reminder run --home ~/.logwork-cli`. That command reads credentials from macOS Keychain or Windows Credential Manager when it runs. Enabling or disabling the reminder also removes the old `logwork-helper` schedule (`sg.vinova.logwork-helper.reminder` / `Logwork Helper Reminder`) if one is still present.
+
+Resource Optimiser is incomplete when today's logged hours are lower than booked hours. A day with no RO bookings and no RO logs is treated as not expected. Jira is incomplete when JQL finds no issue with a worklog by `currentUser()` on today's date. Auth or check failures produce an actionable notification without including the underlying API response.
+
+The `test` command sends a sample notification immediately and does not query or write RO/Jira. On macOS, allow notifications when prompted. On Windows, ensure app notifications are enabled for PowerShell because the lightweight WinRT toast is delivered through the built-in PowerShell host.
+
+## Reconcile Resource Optimiser And Jira
+
+Use the same preset periods as `/query`:
+
+```bash
+logwork reconcile today
+logwork reconcile this-week
+logwork reconcile last-week --json
+```
+
+The command queries RO task details and Jira worklogs authored by the authenticated Jira user. Jira issues are discovered with an exclusive date-range JQL query, then each issue's worklogs are filtered again by author and started date. The result includes booked, RO, and Jira hours by day; total and issue-level differences; missing task-detail diagnostics; and high-confidence correction suggestions.
+
+A suggestion is high confidence only when an RO entry contains exactly one issue key such as `SCB-213`. Jira-to-RO suggestions still require project resolution. Reconciliation is read-only and never calls either apply workflow.
+
+Inside the terminal UI, `/reconcile` opens a period picker. Direct commands are also available:
+
+```text
+/reconcile today
+/reconcile yesterday
+/reconcile this-week
+/reconcile last-week
+/reconcile this-month
+/reconcile last-month
+```
+
+MCP exposes the same workflow as `reconcile`. To correct a mismatch, preview it with `log_work`, `edit_entry` or `log_jira_work`, inspect the preview, and apply each target separately after approval.
+
+## Terminal UI
+
+If you want to log work directly from Terminal without an MCP client, use the React + Ink manual session:
+
+```bash
+logwork
+```
+
+Prompt preview:
+
+```text
+Logwork
+cwd: /path/to/repo
+
+logwork > /
+> /help        Show this help
+  /auth        Authenticate Resource Optimiser or show Jira login command
+  /status      Show Resource Optimiser and Jira auth status
+  /diagnostics Write a sanitized report
+  /query       Query logwork by preset period
+  /logwork     Create Resource Optimiser, Jira, or combined logwork
+  /mcp         Show copy-ready MCP setup
+```
+
+Useful commands inside the session:
+
+```text
+/query today
+/query yesterday
+/query this-week
+/query last-week
+/query this-month
+/query last-month
+/reconcile
+/reconcile this-week
+/logwork
+/logwork ro
+/logwork jira
+/logwork both
+/edit-logwork 304032 --task Bug Fix --desc Fix date picker (SAP-42)
+/mcp
+/projects
+/projects 5234
+/map SCB 5234
+/history
+/diagnostics
+```
+
+`/logwork` opens a target picker for Resource Optimiser, Jira, or Both. `/logwork ro` starts the Resource Optimiser wizard: pick a day in the current week, pick a Resource Optimiser project, then enter one task per line as `+<hours> <worklog task> | <description>`. The worklog task must be a Resource Optimiser catalog task for that project; the description is stored on the RO entry:
+
+```text
++2 Feature Development | check ui/ux
++1.5 Feature Development | polish reset password state
+```
+
+`/logwork jira` starts the Jira worklog wizard: pick a day, then enter tasks with exactly one Jira issue key:
+
+```text
++2 Feature Development | check ui/ux (SCB-213)
++1.5 Feature Development | polish reset password state (SCB-214)
+```
+
+`/logwork both` uses one date/task draft, builds separate Resource Optimiser and Jira previews, then asks for separate approvals when applying.
+
+Inside `/logwork`, press Enter on an empty input to apply the ready preview. Use `/remove` to open a multi-select task remover, `/edit` to replace a task, `/save` to persist a local draft, or `Esc` to cancel with confirmation.
+
+While the `task >` prompt is active, type `/` to see task-only actions:
+
+```text
+/save        Save this draft locally
+/drafts      Resume or delete saved drafts
+/diagnostics Write a sanitized support report
+/remove      Select tasks to delete
+/edit        Select one task and replace it
+/clear       Clear current task list
+/back        Return to project picker
+/cancel      Discard this logwork session
+```
+
+Resource Optimiser drafts saved with `/save` are stored locally at `~/.logwork-cli/manual-drafts.json` on macOS or `%USERPROFILE%\.logwork-cli\manual-drafts.json` on Windows. Drafts never contain tokens, passwords, or OTPs.
+
+Successful, partial, failed, and blocked apply outcomes are recorded in `~/.logwork-cli/apply-ledger.json`. The ledger contains only sanitized batch, entry, project, issue, status, and timestamp metadata. Read it with:
+
+```bash
+logwork history
+logwork history --target jira --limit 10
+logwork history --target both
+```
+
+Inside `logwork`, use `/history`, `/history ro`, `/history jira`, or `/history both`. The `both` filter means records created while using the combined Both flow.
+
+## Troubleshooting
+
+- **IDE does not show tools:** restart or reload the MCP client. Check that the config runs `node ~/.logwork-cli/bin/logwork.mjs mcp` (on Windows, `%USERPROFILE%\.logwork-cli\bin\logwork.mjs`) and that the server name is `logwork`.
+- **Tools show old names such as `preview_logwork_batch`:** the IDE is still connected to the old `logwork-helper` entry. Replace that entry with the config printed by `logwork setup`; the [tool name table](mcp-setup.md#tool-name-changes-from-logwork-helper) lists the renames.
+- **`logwork: command not found` after `logwork setup`:** open a new terminal first. If it still fails, run `npm install -g logwork-cli`, or make sure your npm global bin directory is on `PATH`.
+- **`npm link` fails with `EEXIST` on `logwork`:** an old global `logwork-helper` package still owns the bin. Run `npm rm -g logwork-helper`, then `logwork setup` again.
+- **Not authenticated to Resource Optimiser:** run `logwork login`, or ask the assistant to call `login`. Enter secrets only in the terminal.
+- **Not authenticated to Jira:** run `logwork login jira`, or ask the assistant to call `login` with `target: "jira"`. Paste the Jira PAT only in the terminal.
+- **Auth error after 2FA:** retry `logwork login`. If it still fails, run `logwork doctor` and send only the generated sanitized report.
+- **Jira worklog preview is blocked:** every Jira entry must include exactly one issue key, such as `SCB-213`. Duplicate Jira worklogs block the apply and cannot be overridden.
+- **Apply says no cached preview:** previews expire after 1 hour and are lost when the MCP server restarts. Preview again.
+- **No project matched:** ask the assistant to call `list_projects`, choose the correct project, then call `map_project`.
+- **Never paste Bearer tokens, cookies, passwords, OTPs, or raw curl auth logs:** auth is handled locally, and the MCP config should only contain `command` and `args`.
+
+## Dry Run
+
+`LOGWORK_DRY_RUN=1` makes Resource Optimiser writes return the request body instead of calling the API. Reads still hit the API.
+
+```bash
+LOGWORK_DRY_RUN=1 logwork quick -m "Dry run task"
+LOGWORK_DRY_RUN=1 logwork edit 304032 --desc "Dry run" --yes
+```
+
+In Windows PowerShell:
+
+```powershell
+$env:LOGWORK_DRY_RUN = "1"; logwork quick -m "Dry run task"
+```
+
+## Release Checks
+
+Before publishing or tagging a release, run:
+
+```bash
+logwork release doctor --full
+npm run release:check
+```
+
+The release doctor checks version consistency, git state, npm/GitHub auth, npm latest, tag/release state, local tarball artifacts, tests, audit, package dry run, and whitespace checks. See [RELEASE.md](../RELEASE.md) for the full checklist and manual verification steps.
+
+## GitHub About Metadata
+
+Suggested repository description:
+
+```text
+Log work to Resource Optimiser and Jira from the terminal, an MCP server for AI IDEs, and a terminal UI.
+```
+
+Suggested topics:
+
+```text
+resource-optimiser
+logwork
+mcp-server
+nodejs
+macos
+windows
+keycloak
+codex
+cursor
+vscode
+claude-code
+```

package/docs/mcp-setup.md

@@ -0,0 +1,347 @@
+# 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.
+
+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`.
+
+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.
+
+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.
+
+## Cursor / Google Antigravity
+
+Cursor MCP settings, or `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "logwork": {
+      "command": "node",
+      "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+    }
+  }
+}
+```
+
+## Codex
+
+`~/.codex/config.toml`, or project `.codex/config.toml`:
+
+```toml
+[mcp_servers.logwork]
+command = "node"
+args = ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+## GitHub Copilot / VS Code
+
+Workspace `.vscode/mcp.json`, or your VS Code user MCP config:
+
+```json
+{
+  "servers": {
+    "logwork": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/Users/<user>/.logwork-cli/bin/logwork.mjs", "mcp"]
+    }
+  }
+}
+```
+
+## Claude Code
+
+```bash
+claude mcp add --transport stdio logwork -- 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
+```
+
+Or add the Cursor JSON above to the project `.mcp.json`.
+
+Templates are also in [examples/mcp](../examples/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.
+
+## Exposed Tools
+
+After editing the config, restart or reload the IDE. The server exposes 15 tools. Each one has a title, a description, a described input schema, and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so IDEs and agents can tell read-only tools from writes.
+
+The server also sends MCP `instructions` that explain the approval rules, the line format and the recommended call order. Most clients pass these to the model automatically.
+
+**Writes are two calls to the same tool:**
+
+1. Call the tool **without `confirm`**. It returns a preview: a `batchId` (for `log_work` and `log_jira_work`) or a `previewId` (for the entry tools), plus a `summary`. Show the summary to the user.
+2. After explicit approval, call the same tool **again with only that id and `confirm: true`**.
+
+The apply call writes the cached, approved preview as-is. If the apply call also carries content fields (such as `text`, `hours` or `description`), it is rejected rather than silently ignored. To change values, preview again.
+
+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 | `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 | `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 | `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 |
+|---|---|
+| `preview_logwork_batch`, `apply_logwork_batch` | `log_work` |
+| `query_logwork` | `get_logwork` |
+| `list_logwork_projects` | `list_projects` |
+| `list_worklog_tasks` | `list_tasks` |
+| `preview_ro_logwork_edit`, `apply_ro_logwork_edit` | `edit_entry` |
+| `preview_ro_logwork_resubmit`, `apply_ro_logwork_resubmit` | `resubmit_entry` |
+| `preview_ro_logwork_delete`, `apply_ro_logwork_delete`, `delete_ro_logwork_entry` | `delete_entry` |
+| `preview_jira_worklog_batch`, `apply_jira_worklog_batch` | `log_jira_work` |
+| `reconcile_logwork` | `reconcile` |
+| `query_apply_history` | `get_history` |
+| `upsert_project_mapping` | `map_project` |
+| `start_auth_login`, `start_jira_auth` | `login` (`target: "ro"` or `"jira"`) |
+| `get_logwork_reminder`, `configure_logwork_reminder`, `test_logwork_reminder` | `reminder` (`action`) |
+| `check_for_updates`, `apply_update` | `update` (`action`) |
+
+The structured `batch` / `preview` echo parameters of the old apply tools are gone. Apply calls use only the id.
+
+## Logwork Line Format
+
+`log_work` and `log_jira_work` take the same text:
+
+```text
+Monday, 01 Jun 2026
++2 Feature Development | Implement maintenance mode management and status UI (SCB-213)
++1 Code Review & Refactoring | Review system page PR (SCB-227)
+Tuesday, 02 Jun 2026
++2.5 Bug Fix | Password reset validation and UI improvements (SCB-228)
+```
+
+- **Day heading:** `<Weekday>, <DD> <Mon> <YYYY>`.
+- **Entry:** `+<hours> <worklog task> | <description>`.
+  - `<worklog task>` is a Resource Optimiser worklog task name from `list_tasks` (case-insensitive exact match), or `#<id>`.
+  - `<description>` is free text. Resource Optimiser stores it as the entry `description`, and Jira uses it as the worklog comment. Only the first `|` splits the line; any later `|` stays in the description.
+- **Lines without `|`** are still accepted:
+  - If the whole text is a catalog task name, the entry is written without a description and the preview shows a warning.
+  - Otherwise, pass `defaultWorklogTask` (for example `"Other Activities"`) to the `log_work` preview call, and the text becomes the description. Without it, the entry is unresolved with reason `worklog_task_required` and the preview lists `availableTaskNames`.
+- **Jira lines** need exactly one issue key, such as `SCB-213`.
+
+If a tool says auth is required, the assistant calls `login`, or you can run `logwork login` yourself. For Jira, the assistant calls `login` with `target: "jira"`, or you run `logwork login jira`.
+
+The Jira prompt accepts a Personal Access Token in the terminal only. Neither login accepts credentials through MCP.
+
+Do not paste passwords, 2FA codes, Bearer tokens, cookies, or raw auth logs into AI chat.
+
+## Verify Setup
+
+Use these prompts after your IDE sees the `logwork` server:
+
+```text
+Check my logwork for this week.
+```
+
+```text
+Which Resource Optimiser project should this repo log work to?
+```
+
+```text
+Log 2 hours today for SCB-213 "maintenance mode UI" as Feature Development, with a clear description. Preview first and wait for my approval.
+```
+
+```text
+Set up the SCB ticket mapping to project 2621A-SIT-HTML BUILDER-PRJ.
+```
+
+## Common MCP Workflows
+
+### Query Logwork
+
+Ask your assistant:
+
+```text
+List the days and projects I logged work for this week, including entry details.
+```
+
+The assistant calls `get_logwork`. Supported periods are `today`, `yesterday`, `this_week`, `last_week`, `this_month` and `last_month`. This is read-only.
+
+### Reconcile Resource Optimiser And Jira
+
+```text
+Compare my Resource Optimiser and Jira worklogs for this week. Show daily differences and do not write anything.
+```
+
+The assistant calls `reconcile` with `period: "this_week"`. Custom dates are intentionally not exposed.
+
+The result includes:
+- daily booked, RO and Jira totals;
+- issue-level differences;
+- entries that cannot be verified because they do not contain exactly one Jira key;
+- high-confidence correction suggestions.
+
+A suggestion is not an approved write. It still goes through the two-call write of `log_work`, `edit_entry` or `log_jira_work`.
+
+### Log Work To Resource Optimiser
+
+1. Optional: call `get_logwork` to see booked and logged hours.
+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.
+
+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`.
+
+Each preview entry contains:
+- `taskName`: the resolved RO worklog task;
+- `worklogTaskId`;
+- `description`;
+- `descriptionMissing`;
+- `taskResolution.reason`.
+
+| `taskResolution.reason` / entry `reason` | Meaning | Fix |
+|---|---|---|
+| `worklog_task_match` | Task resolved from the text before `\|` (or the whole line). | None. |
+| `default_worklog_task` | The line had no `\|`, so `defaultWorklogTask` was used and the line became the description. | None. |
+| `worklog_task_required` | The line had no `\|` and is not a catalog task. | Add `<task> \|`, or pass `defaultWorklogTask`. See `availableTaskNames`. |
+| `task_not_found` | The task before `\|` is not in the catalog. | Use a name from `suggestedTaskNames` or `availableTaskNames`. |
+| `task_lookup_failed` | The catalog request failed. | Retry, or check auth. |
+
+Apply sends `POST /logwork/entries` with `worklog_task_id`, `effort_hours`, `logdate`, `type_of_work` and `description`, plus `project_id` when the task is a shared default. New entries are approved immediately. `log_work` never writes Jira.
+
+### Edit, Resubmit, Or Delete An Existing RO Entry
+
+Get the `logworkId` from `get_logwork` first.
+
+```text
+RO logwork 304032 should be a Bug Fix with description "Fix date picker timezone (SAP-42)". Keep hours, project, and date. Show me the diff and ask before applying.
+```
+
+1. Call `edit_entry` with `logworkId: 304032`, `taskName: "Bug Fix"` and `description: "Fix date picker timezone (SAP-42)"`.
+2. Show the original and updated fields. Project and date are shown as unchanged.
+3. Ask for explicit approval.
+4. Call `edit_entry` with the returned `previewId` and `confirm: true`.
+
+The optional changes are:
+- `hours`
+- `taskName`: a catalog name from `list_tasks`, or `#<id>`.
+- `description`
+- `typeOfWork`
+
+Pass at least one. Omitted fields keep their current value. The exception is `typeOfWork`: if it is omitted and the task changes, it follows the new task's catalog type.
+
+RO has no staff edit endpoint. `PATCH /logwork/pm/entries/:id/edit-approve` exists but is PM-only. So apply **replaces** the entry:
+
+1. It re-reads the entry and blocks if the entry changed after the preview.
+2. It creates the corrected entry with `POST /logwork/entries`.
+3. It deletes the original with `DELETE /logwork/entries/:id`.
+4. It verifies the new entry.
+
+If the create fails, the original is untouched. If the delete fails, the new entry is rolled back.
+
+Deleting needs no approval, and the new entry is approved immediately, so the edit takes effect at once. Because the entry id changes, the result returns both `originalLogworkId` and `newLogworkId`.
+
+Which tool to use:
+
+| Entry | Tool |
+|---|---|
+| Rejected, needs fixing | `resubmit_entry`: change hours, type of work, description, or add a note to the PM. |
+| No longer needed | `delete_entry`: works only on submitted or approved entries. |
+| On a locked day, created by Jira, or owned by another user | Edit is blocked. |
+
+`edit_entry` and `delete_entry` carry `destructiveHint: true`.
+
+### Log Work To Jira
+
+Jira worklogs are separate from Resource Optimiser logwork. Log in first with `logwork login jira`.
+
+Each line must include exactly one Jira issue key. The RO worklog task before `|` is ignored by Jira. A line without `|` uses the whole text as the comment.
+
+1. Call `log_jira_work` with `text`.
+2. Show the summary and ask for approval. The summary includes the ready, duplicate, missing-ticket, multi-ticket and lookup-failed counts; the issue summary and status; and the final `started` and comment values.
+3. Call `log_jira_work` with `batchId` and `confirm: true`.
+
+Duplicates block apply, and there is no override option. A worklog counts as a duplicate when it has the same short marker (`#lh:<hash>`), or the same issue, date, duration and normalized comment. Legacy `[logwork-helper:...]` markers in older comments are still recognized.
+
+Each worklog is written with these values:
+
+```text
+started: 09:00 Asia/Ho_Chi_Minh on the entry date
+timeSpentSeconds: hours * 3600
+comment: description (text after "|", or the whole line) plus short marker, for example #lh:8f3a91c0
+adjustEstimate: leave
+```
+
+Override `started` with `LOGWORK_JIRA_STARTED_TIME=HH:mm` and the timezone with `LOGWORK_TIMEZONE=<IANA timezone>`.
+
+### Both
+
+For the same text, run both previews: `log_work` and `log_jira_work`. Show both summaries, then apply each one with its own approval.
+
+The two applies are intentionally not atomic. `log_work` never writes Jira, and `log_jira_work` never writes Resource Optimiser.
+
+### History, Updates, Reminder
+
+- **History:** `get_history` reads the sanitized local ledger. The `both` filter returns records created by the combined Both flow.
+- **Updates:**
+  1. Call `update` with `action: "check"` (read-only) and show the target version.
+  2. After approval, call `update` with `action: "install"`, `version` and `confirm: true`.
+  3. Reconnect MCP afterwards.
+
+  Install re-checks npm, accepts only npm latest, and never accepts a registry, package or shell command.
+- **Reminder:**
+  - `reminder` with `action: "status"` is read-only.
+  - `enable` (with optional `time` and `target`), `disable` and `test` need `confirm: true` after approval.
+  - macOS uses launchd and Windows uses Task Scheduler.
+  - Reminder tools never accept credentials, scheduler commands or executable paths.
+
+### Project Mapping
+
+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`.
+
+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.
+
+```json
+{
+  "projectMappings": [
+    {
+      "projectName": "2621A-SIT-HTML BUILDER-PRJ",
+      "projectMemberId": 5234,
+      "tickets": ["SCB"],
+      "keywords": ["question bank", "programme", "cluster"]
+    }
+  ]
+}
+```
+
+This file stores matching hints only. It never stores tokens.
+
+### Allow Unbooked Logging
+
+Sometimes a line matches one of your project memberships, but that project is not booked for the date. The preview then marks the entry `UNBOOKED`.
+
+Only allow this when the matched project is correct. Apply with:
+
+```json
+{ "batchId": "<from preview>", "confirm": true, "allowUnbooked": true }
+```