Merge pull request #23 from eSlider/release-please--branches--main--components--go-onlyoffice

chore(main): release 0.10.0

.env.example

@@ -11,7 +11,7 @@ ONLYOFFICE_PASS=
 # ONLYOFFICE_NAME=
 # ONLYOFFICE_PASSWORD=
 #
-# produktor.io operator aliases (CLI-only):
+# Optional CLI-only aliases:
 # OO_URL=
 # OO_USER=
 # OO_PASS=

.github/workflows/release-please.yml

@@ -9,6 +9,7 @@ permissions:
   contents: write
   pull-requests: write
   issues: write
+  actions: write
 
 jobs:
   release-please:
@@ -23,6 +24,18 @@ jobs:
           manifest-file: .release-please-manifest.json
           token: ${{ secrets.RELEASE_PLEASE_TOKEN != '' && secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
 
+      # Tags/releases created with GITHUB_TOKEN do not trigger other workflows
+      # (push:tags on Release.yml never fires). Dispatch GoReleaser explicitly.
+      - name: Trigger GoReleaser
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.release.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          echo "Dispatching Release workflow for $TAG"
+          gh workflow run release.yml --repo "${{ github.repository }}" -f "tag=${TAG}"
+
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}

.github/workflows/release.yml

@@ -18,10 +18,28 @@ jobs:
     name: GoReleaser
     runs-on: ubuntu-latest
     steps:
+      # Always clone default branch first. workflow_dispatch often races with
+      # release-please creating the tag; fetching refs/tags/X before it exists
+      # fails checkout. Retry fetch, then check out the tag.
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.ref }}
+
+      - name: Checkout release tag
+        env:
+          TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+        run: |
+          set -euo pipefail
+          echo "Releasing tag: $TAG"
+          for i in 1 2 3 4 5 6; do
+            if git fetch --force origin "refs/tags/${TAG}:refs/tags/${TAG}"; then
+              break
+            fi
+            echo "tag $TAG not visible yet (attempt $i); sleeping…"
+            sleep 10
+          done
+          git rev-parse "refs/tags/${TAG}"
+          git checkout --force "refs/tags/${TAG}"
 
       - name: Set up Go
         uses: actions/setup-go@v5

.github/workflows/test.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches: [main]
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.0"
+  ".": "0.10.0"
 }

AGENTS.md

@@ -9,17 +9,17 @@ Canonical Go client for OnlyOffice Workspace (Projects + Calendar + CRM) and the
   - `request.go` — `Request`, `Query`, `Time`, `Token`, `MetaResponse`, `Permissions`.
   - `auth.go` — `Authenticate`, `AuthenticateContext`, `InvalidateToken`, `Auth`, token lifecycle.
   - `http.go` — transport + DRY response decoders (`ResponseArray`/`ResponseObject`/`postFormObject`/`putFormObject`/`deleteObject`).
-  - `projects.go`, `tasks.go`, `users.go`, `calendar.go`, `crm.go`, `files.go`, `mails.go` — typed / untyped domain methods. **`files.go`** — CRM opportunity upload plus **project/task Documents** (`GetProjectFiles`, `UploadProjectFile`, `GetTaskFiles`, `AttachFilesToTask`, `UploadTaskFile`, `DetachTaskFile`, `GetFile`, `RenameFile`, `DeleteFiles`, `DownloadFile`). **`mails.go`** — OnlyOffice Workspace Mail addon (`ListMailAccounts`, `ListMailFolders`, `ListMailMessages`, `GetMailMessage`, `RemoveMailMessages`).
+  - `projects.go`, `tasks.go`, `users.go`, `calendar.go`, `crm.go`, `files.go`, `mails.go`, `invoices.go` — typed / untyped domain methods. **`files.go`** — CRM opportunity upload plus **project/task Documents**. **`mails.go`** — OnlyOffice Workspace Mail. **`invoices.go`** — CRM invoices, PDF regen/cleanup, status. Association rules: [`docs/crm-associations.md`](docs/crm-associations.md).
   - Pure stdlib + `google/go-querystring`; no UI, no dotenv.
 - **CLI — `cmd/oo/` as `package main`.** Cobra wrapper that loads `.env` via `godotenv` at startup. **Subject-based command tree** mirroring [`tea`](https://gitea.com/gitea/tea):
   - `main.go` — entry point (docstring lists the command tree).
   - `common.go` — `rootCmd`, `newOO`, `printTable`/`printObject`, `--output table|json` flag.
-  - `calendar.go`, `projects.go`, `projects_files.go`, `tasks.go`, `tasks_files.go`, `users.go`, `contacts.go`, `opportunities.go`, `cases.go`, `crm_tasks.go`, `apps.go` — one file per subject (or per subject facet), each registers in `init()`.
+  - `calendar.go`, `projects.go`, `projects_files.go`, `tasks.go`, `tasks_files.go`, `users.go`, `contacts.go`, `opportunities.go`, `cases.go`, `crm_tasks.go`, `mails.go`, `invoices.go` — one file per subject (or per subject facet), each registers in `init()`.
   - CLI-only deps (`spf13/cobra`, `joho/godotenv`) stay out of the library.
 - **TUI — `cmd/office/` as `package main`.** Bubble Tea three-pane browser (module tree, selectable list, markdown preview). Reuses `cmd/internal/bootstrap` for env/auth and the root `onlyoffice` library for all API calls. UI logic in `cmd/office/ui/`; preview/formatting in `cmd/office/preview/`; list loaders in `cmd/office/fetch/`.
   - **List table (`DataTable`)** — `cmd/office/ui/table*.go`. Column layout policies live in `cmd/office/model/table_layout.go` (`TableFlexLayoutFor`); cell rendering uses the bubbles/table inline pattern in `table_render.go` (`renderTableCell`, `padANSIWidth`). See `.cursor/skills/office-tui-table/SKILL.md` before changing center-pane tables.
 - **Shared bootstrap — `cmd/internal/bootstrap/`.** `LoadEnv()` + `NewClient(ctx)` extracted from `oo`; both binaries import it.
-- **Applications sync — `cmd/oo/applications/`.** README→CRM bridge, CV-specific; kept under `cmd/oo/` so it's clear it's internal to the binary, not a library feature.
+- **Personal ops tooling** (disk inventory, dossier→CRM sync, SearXNG) lives in private [`eSlider/oo-workspace`](https://git.produktor.io/eSlider/oo-workspace) (`oow`), not in this public tree.
 
 ## Rules
 

CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+* **docs:** CRM association graph and OO quirks (`docs/crm-associations.md`)
+* **crm:** `ForceRegenerateInvoicePDF`, `SetInvoiceStatus`, `PurgeStaleInvoicePDFs`, contact/opportunity file list helpers
+* **oo:** `invoices pdf`, `pdf-cleanup`, `status`; create `--consignee`; draft-invoice force-regens PDF
+
+### Fixed
+
+* Document that invoice→deal must be set at create (`update --opportunity` often HTTP 400)
+
+## [0.10.0](https://github.com/eSlider/go-onlyoffice/compare/v0.9.0...v0.10.0) (2026-08-13)
+
+
+### Features
+
+* **crm:** add invoices CLI and opportunity update ([19a7e9c](https://github.com/eSlider/go-onlyoffice/commit/19a7e9cbf8f7bd335c4e4cfd4d3b8a84a350cc41))
+* **crm:** allow updating invoice terms via oo ([31c556d](https://github.com/eSlider/go-onlyoffice/commit/31c556d34cedd65d6957441f448520af9a7e380b))
+* **crm:** invoice update notes and PO fields ([d81e7de](https://github.com/eSlider/go-onlyoffice/commit/d81e7de9114a29439142efba67f205653f562730))
+* **crm:** invoices CLI and opportunity update ([f958309](https://github.com/eSlider/go-onlyoffice/commit/f95830961d3aecba65f3cb074d33c9c98f6c6cf2))
+* **mail:** draft, attach, and draft-invoice CLI ([73b1050](https://github.com/eSlider/go-onlyoffice/commit/73b1050a83e9e49dcf99d8a966a84746376d7dd9))
+
+
+### Bug Fixes
+
+* **crm:** JSON person update and oo persons update CLI ([42c31d4](https://github.com/eSlider/go-onlyoffice/commit/42c31d4b485bfab6903aeed0dd6fb2c43f61b4f2))
+* **crm:** link invoices to opportunities ([3201a58](https://github.com/eSlider/go-onlyoffice/commit/3201a58df75bceb7d41034970cf384a9169163ed))
+* **mail:** German spacing for invoice draft template ([7f35b0e](https://github.com/eSlider/go-onlyoffice/commit/7f35b0e91075d871f87de95b6c84b2353e02f9cf))
+
+
+### Documentation
+
+* **crm:** capture association graph and invoice/mail quirks ([490426c](https://github.com/eSlider/go-onlyoffice/commit/490426c2779160f1a9b168f6ccae9dd8dccf89e9))
+* **crm:** clarify mail API send vs signature for chat links ([6b5a82b](https://github.com/eSlider/go-onlyoffice/commit/6b5a82bef831341aee16b0b0ea1fe6db2c24567d))
+* **crm:** Team vs Contacts and persons update note ([11aa23f](https://github.com/eSlider/go-onlyoffice/commit/11aa23f1a17471bad2bd95fddb769a94afbcf97a))
+
+## [0.9.0](https://github.com/eSlider/go-onlyoffice/compare/v0.8.3...v0.9.0) (2026-07-26)
+
+
+### Features
+
+* **catalog:** mbox header scan, company legal-suffix match, apply order ([8b29be2](https://github.com/eSlider/go-onlyoffice/commit/8b29be2d9bb71154d473f780ad247c5c440c6021))
+* **catalog:** scan Thunderbird address books and Gloda contacts ([502b373](https://github.com/eSlider/go-onlyoffice/commit/502b373e3726ded8b9c50e061ff30aea83205a34))
+* **oo:** catalog scan/match/apply for CRM clients and contacts ([547f063](https://github.com/eSlider/go-onlyoffice/commit/547f063f7fe922fe784358093a89730f9aaf0683))
+* **oo:** catalog scan/match/apply for CRM clients and contacts ([c32e4dd](https://github.com/eSlider/go-onlyoffice/commit/c32e4dd6116f0b8df67e93c5b589a417dfee59aa))
+* **projects:** CRM contacts + git author linking ([457c589](https://github.com/eSlider/go-onlyoffice/commit/457c589abdc2c9fe8edd42b4b7445581976cc5a2))
+* **projects:** link CRM companies and git authors to projects ([5a8735e](https://github.com/eSlider/go-onlyoffice/commit/5a8735e2898cf53e330e183250cf3c5d3c84da55))
+
+
+### Bug Fixes
+
+* **catalog:** oo_projects field + safer match ([8d5ca67](https://github.com/eSlider/go-onlyoffice/commit/8d5ca67d64da83c70d8ae293f4c7c23f9f9f59d3))
+* **catalog:** preserve oo_id on match; add oo_projects field ([d873cb7](https://github.com/eSlider/go-onlyoffice/commit/d873cb748adf4458369d8a2167abd8da987737c5))
+* **crm:** clean person names; canonical project titles ([b9591f5](https://github.com/eSlider/go-onlyoffice/commit/b9591f5fc3efc13b78dbe932ff32c2f2905e18fc))
+* **crm:** person names + CC | Company | Title projects ([6305135](https://github.com/eSlider/go-onlyoffice/commit/6305135bd799efe42dbb900a694e82aeae9f9e58))
+
+## [0.8.3](https://github.com/eSlider/go-onlyoffice/compare/v0.8.2...v0.8.3) (2026-07-23)
+
+
+### Bug Fixes
+
+* **ci:** dispatch GoReleaser after release-please; allow Tests dispatch ([#13](https://github.com/eSlider/go-onlyoffice/issues/13)) ([bf2fa63](https://github.com/eSlider/go-onlyoffice/commit/bf2fa637aaf0419ba5af40b25b64f9ebe24116e8))
+
+## [0.8.2](https://github.com/eSlider/go-onlyoffice/compare/v0.8.1...v0.8.2) (2026-07-23)
+
+
+### Bug Fixes
+
+* **ci:** retry tag fetch in Release workflow ([#11](https://github.com/eSlider/go-onlyoffice/issues/11)) ([31b4aa0](https://github.com/eSlider/go-onlyoffice/commit/31b4aa0d90393e6d93513284e453b7da7e92c62d))
+
+## [0.8.1](https://github.com/eSlider/go-onlyoffice/compare/v0.8.0...v0.8.1) (2026-07-23)
+
+
+### Bug Fixes
+
+* **oo:** assign owner and deadline on task create ([#9](https://github.com/eSlider/go-onlyoffice/issues/9)) ([f608207](https://github.com/eSlider/go-onlyoffice/commit/f60820734924284d6c40b46c79380a24573432f3))
+
 ## [0.8.0](https://github.com/eSlider/go-onlyoffice/compare/v0.7.0...v0.8.0) (2026-07-23)
 
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Example Author
+Copyright (c) 2026 Andriy Oblivantsev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -533,7 +533,7 @@ deals, total, _ := client.ListOpportunities(ctx, 50, 0)
 company, _ := client.FindCompany(ctx, "ACME")
 
 // Subtasks (form-encoded)
-client.AddSubtask(ctx, "4242", "Prepare CV")
+client.AddSubtask(ctx, "4242", "Prepare notes")
 ```
 
 ### oo (bundled CLI)
@@ -552,14 +552,13 @@ oo calendar events --start 2026-04-24 --end 2026-05-01
 oo projects list
 oo projects get 33
 oo tasks list --all --verbose
-oo tasks subtask add 4242 "Prepare CV"
+oo tasks subtask add 4242 "Prepare notes"
 oo persons create --first Jane --last Doe --email jane@example.com
 oo companies create --name "Acme GmbH" --website https://acme.com
 oo opportunities list
 oo opportunities stages
 oo cases list
 oo crm-tasks categories
-oo applications sync --path ./applications/2026 --apply
 ```
 
 ### office (TUI)
@@ -613,7 +612,7 @@ oo projects files download 12345 --to ./copy.md
 oo projects files rename 12345 notes-v2.md
 oo projects files delete 12345
 oo tasks files list 208
-oo tasks files upload 208 ./cv.pdf
+oo tasks files upload 208 ./notes.pdf
 oo tasks files detach 208 12345
 ```
 
@@ -623,33 +622,28 @@ oo tasks files detach 208 12345
 | `projects` | `list`, `get`, `milestones`, `create`, `update`, `delete`, **`files`** (`list`, `upload`, `download`, `rename`, `delete`) |
 | `tasks` | `list`, `get`, `create`, `update`, `delete`, `subtask add`, **`files`** (`list`, `upload`, `detach`) |
 | `users` | `list`, `self` (alias: `oo whoami`) |
-| `contacts` | `list`, `get`, `delete`, `info-add` |
+| `contacts` | `list`, `get`, `delete`, `info-add`, `merge`, `dedupe-info` |
-| `persons` | `list` (filtered), `create`, `delete` |
-| `companies` | `list` (filtered), `create`, `delete` |
-| `contacts` | `list`, `get`, `delete`, `info-add`, `dedupe-info` |
 | `persons` | `list`, `create`, `delete`, `dedupe` |
 | `companies` | `list`, `create`, `delete`, `dedupe`, `dedupe-persons` |
 | `opportunities` | `list`, `get`, `create`, `delete`, `stages`, `member-add`, `dedupe`, `dedupe-members`, `fix-titles` |
+| `invoices` | `list`, `get`, `create`, `update`, `pdf`, `pdf-cleanup`, `status`, `delete`, `items …` |
 | `crm` | `cleanup` |
-| `mails` | `accounts`, `folders`, `list`, `get`, `delete` |
+| `mails` | `accounts`, `folders`, `list`, `get`, `draft`, `attach`, `draft-invoice`, `delete` |
 | `cases` | `list`, `create`, `delete`, `member-add` |
 | `crm-tasks` | `list`, `create`, `delete`, `categories` |
-| `applications` | `sync` |
 
 The CLI reads only `.env` from the current working directory (godotenv is a
 CLI-only concern — the library itself never loads dotfiles).
 
-Canonical `ONLYOFFICE_*` variables win over aliases. For produktor.io operator
+Canonical `ONLYOFFICE_*` variables win over aliases. Optional CLI-only aliases:
-files, `OO_URL` / `OO_USER` / `OO_PASS` are accepted as CLI-only aliases for
+`OO_URL` / `OO_USER` / `OO_PASS` → `ONLYOFFICE_URL` / `ONLYOFFICE_USER` / `ONLYOFFICE_PASS`.
-`ONLYOFFICE_URL` / `ONLYOFFICE_USER` / `ONLYOFFICE_PASS`.
 
 Run `oo --help` or `oo <subject> --help` for the full command reference.
 
 > **0.5.0 migration note:** the command tree was flattened per-subject. Old
-> flat names (`oo cal-events`, `oo task-list`, `oo crm-contacts`,
+> flat names (`oo cal-events`, `oo task-list`, `oo crm-contacts`, …) were
-> `oo applications-sync`, …) were replaced by subject-based equivalents
+> replaced by subject-based equivalents (`oo calendar events`, `oo tasks list`,
-> (`oo calendar events`, `oo tasks list`, `oo contacts list`,
+> `oo contacts list`). Flags on leaf commands are unchanged.
-> `oo applications sync`). Flags on leaf commands are unchanged.
 
 ## oo CLI use cases
 
@@ -671,7 +665,7 @@ Every list command accepts `-o table` (default) or `-o json` for scripting.
 ### CRM cleanup after imports or sync drift
 
 **Problem:** Duplicate companies (`Acme` / `ACME GmbH`), persons created twice,
-the same email on a contact three times, deals titled ` @ contoso`, or the same
+the same email on a contact three times, deals titled ` @ Acme`, or the same
 HR contact linked to a deal twice.
 
 **One-shot fix** — runs every dedupe pass in order:
@@ -710,13 +704,39 @@ oo contacts dedupe-info
 # Two deals with the same title
 oo opportunities dedupe
 
-# Same contact attached twice to one deal (common after applications sync)
+# Same contact attached twice to one deal
 oo opportunities dedupe-members
 
-# Titles like " @ contoso" or extra whitespace
+# Titles like " @ Acme" or extra whitespace
 oo opportunities fix-titles
 ```
 
+Merge two known company ids (keeps `INTO`):
+
+```bash
+oo contacts merge FROM_ID INTO_ID
+```
+
+Company ↔ person ↔ deal ↔ project ↔ invoice ↔ mail rules and OO quirks:
+[docs/crm-associations.md](docs/crm-associations.md).
+
+### Invoices (`oo invoices`)
+
+**Problem:** Bill a client deal as Draft, regenerate PDF, prune duplicate PDF
+attachments, prepare OnlyOffice Mail — without inventing a second bill-to company.
+
+```bash
+# Always pass --opportunity at create (update --opportunity often HTTP 400)
+oo invoices create --number INV-2026-01 --contact COMPANY_ID --item ITEM_ID \
+  --price 300 --opportunity DEAL_ID --language de-DE \
+  --line-description "…" --terms $'…' --description $'…' --po "Deal #DEAL_ID"
+
+oo invoices pdf INVOICE_ID --force
+oo invoices pdf-cleanup INVOICE_ID
+oo invoices status INVOICE_ID --status draft
+oo mails draft-invoice --invoice INVOICE_ID --to billing@example.com
+```
+
 **Deal grouping flag** — when the same role at the same company created
 separate deals (`Engineer @ Acme` vs `Engineer`):
 
@@ -728,45 +748,11 @@ oo crm cleanup --ignore-company-suffix
 **Inspect before/after:**
 
 ```bash
-oo opportunities list --count 200 | grep -i contoso
+oo opportunities list --count 200
-oo contacts get 857 -o json
+oo contacts get CONTACT_ID -o json
 oo crm cleanup -o json
 ```
 
-### Job applications → CRM (`applications sync`)
-
-**Problem:** You keep CVs in a folder tree (`applications/2026/Acme/README.md`)
-and want companies, persons, deals, and history notes in OnlyOffice without
-re-typing.
-
-**Dry-run first** (default — prints what would happen, writes nothing):
-
-```bash
-oo applications sync --path ./applications/2026 --verbose
-```
-
-**Apply** when the preview looks right:
-
-```bash
-oo applications sync --path ./applications/2026 --apply --verbose
-```
-
-Each dossier `README.md` is parsed for company, role, email, phone, LinkedIn, etc.
-Discovery walks `--path` and **skips** junk trees (`node_modules`, `tools`, `.venv`,
-`pdfs`, …). Only folders that look like CV application slugs (`source-NNN-…`, or
-long hyphenated dossiers) are synced — not npm package READMEs.
-
-The sync creates or finds contacts, opens a deal, adds members, and appends a
-history note. Re-running is safe: duplicate members and duplicate deal titles
-are skipped when already present.
-
-**After a large sync**, run CRM cleanup to collapse duplicates introduced by
-repeated runs or manual edits:
-
-```bash
-oo applications sync --path ./applications/2026 --apply
-oo crm cleanup -o json
-```
 
 ### Workspace mail (`oo mails`)
 
@@ -799,8 +785,21 @@ oo mails get 5664 -o json | jq '{subject, from, to, date}'
 # Remove one or more messages (server moves to trash or deletes per Mail rules)
 oo mails delete 5664
 oo mails delete 5664 5663 5661
+
+# Create / update a draft (HTML body field is API "body"; plain text is wrapped)
+oo mails draft --to client@example.com --subject "Rechnung INV-2026-01" \
+  --body "Guten Tag,\n\nanbei die Rechnung.\n\nMit freundlichen Grüßen"
+
+# Attach an OnlyOffice Files document (e.g. invoice PDF file id) to a draft
+oo mails attach 7301 --file-id 12345
+
+# Regenerate invoice PDF (force) + draft + attach (does not send)
+oo mails draft-invoice --invoice 16 --to info@example.com
 ```
 
+Matrix / chat URLs in signatures: use plain text
+`chat: https://matrix.to/#/@user:server` — HTML `<a href="…#…">` truncates at `#`.
+
 **Table output** splits the `from` header into `fromName` and `fromAddress`
 (e.g. `Bitfinex` + `no-reply@bitfinex.com`). **JSON output** returns the raw
 API payload.
@@ -840,8 +839,8 @@ oo calendar events --start 2026-06-24 --end 2026-07-01
 # Schedule interview block
 oo calendar add "Technical interview" 2026-06-26T10:00:00Z 2026-06-26T11:00:00Z
 
-# Attach CV to a hiring task
+# Attach a file to a task
-oo tasks files upload 208 ./cv.pdf
+oo tasks files upload 208 ./notes.pdf
 oo projects files list 33
 ```
 
@@ -849,7 +848,7 @@ oo projects files list 33
 
 | When | Command |
 |------|---------|
-| After `applications sync --apply` | `oo crm cleanup` |
+| After bulk CRM imports | `oo crm cleanup` |
 | After bulk CSV import into CRM | `oo crm cleanup` |
 | Weekly inbox triage | `oo mails list --folder inbox --limit 100` |
 | Before exec reporting | `oo opportunities list` + `oo projects list` |
@@ -863,9 +862,9 @@ oo projects files list 33
 | `ONLYOFFICE_PASS` (or `ONLYOFFICE_PASSWORD`) | Password |
 | `ONLYOFFICE_CALENDAR_ID` | Default calendar id used when omitted (default `1`) |
 | `ONLYOFFICE_PROJECT_ID` | Default project id used when omitted (default `33`) |
-| `OO_URL`, `OO_USER`, `OO_PASS` | CLI-only produktor.io aliases mapped to `ONLYOFFICE_URL`, `ONLYOFFICE_USER`, `ONLYOFFICE_PASS` |
+| `OO_URL`, `OO_USER`, `OO_PASS` | Optional CLI-only aliases for `ONLYOFFICE_*` |
 
-Mail, CRM cleanup, and applications sync are documented in [oo CLI use cases](#oo-cli-use-cases) above.
+Mail and CRM cleanup are documented in [oo CLI use cases](#oo-cli-use-cases) above. Personal disk inventory / dossier sync lives in the private `oo-workspace` (`oow`) tooling.
 
 ### CI / releases
 

client_test.go

@@ -139,6 +139,23 @@ func TestIntegrationProjectAndTaskLifecycle(t *testing.T) {
 
 	start := Time(time.Now().AddDate(0, 0, -2))
 	deadline := Time(time.Now().AddDate(0, 0, 2))
+	ms, err := c.CreateMilestone(NewMilestoneRequest{
+		ProjectID: *project.ID,
+		Title:     "integration milestone",
+		Deadline:  deadline,
+	})
+	if err != nil {
+		t.Fatalf("CreateMilestone: %v", err)
+	}
+	if ms == nil || ms.ID == nil {
+		t.Fatal("created milestone without id")
+	}
+	t.Cleanup(func() {
+		if err := c.DeleteMilestone(*ms.ID); err != nil {
+			t.Logf("cleanup DeleteMilestone: %v", err)
+		}
+	})
+
 	task, err := c.CreateProjectTask(NewProjectTaskRequest{
 		ProjectId:   *project.ID,
 		Title:       "integration parent task",
@@ -146,6 +163,7 @@ func TestIntegrationProjectAndTaskLifecycle(t *testing.T) {
 		StartDate:   start,
 		Deadline:    deadline,
 		Priority:    int(TaskPriorityNormal),
+		MilestoneId: int(*ms.ID),
 	})
 	if err != nil {
 		t.Fatalf("CreateProjectTask: %v", err)

cmd/office/model/columns.go

@@ -171,10 +171,15 @@ func CellText(it Item, key string) string {
 		if it.Raw == nil {
 			return ""
 		}
-		if rel := FormatRelativeDeadline(it.Raw["deadline"]); rel != "" {
+		// CRM tasks use camelCase deadLine; project tasks use deadline.
+		rawDL := it.Raw["deadline"]
+		if rawDL == nil || formatAny(rawDL) == "" {
+			rawDL = it.Raw["deadLine"]
+		}
+		if rel := FormatRelativeDeadline(rawDL); rel != "" {
 			return rel
 		}
-		return formatAny(it.Raw["deadline"])
+		return formatAny(rawDL)
 	case "responsible":
 		if it.Kind == KindTask || it.Kind == KindCRMTask {
 			return TaskResponsibleLabel(it.Raw)

cmd/office/model/task_display.go

@@ -169,6 +169,9 @@ func personName(v any) string {
 		return ""
 	}
 	if name := strRaw(m, "displayName"); name != "" {
+		if strings.EqualFold(name, "Profile has been removed") {
+			return ""
+		}
 		return name
 	}
 	first := strRaw(m, "firstName")

cmd/oo/cli_test.go

@@ -11,7 +11,7 @@ func TestRootRegistersSubjects(t *testing.T) {
 	want := []string{
 		"calendar", "projects", "tasks", "users", "whoami",
 		"contacts", "persons", "companies",
-		"opportunities", "cases", "crm-tasks", "applications", "crm", "mails",
+		"opportunities", "cases", "crm-tasks", "crm", "mails", "invoices",
 	}
 	got := make(map[string]bool, len(rootCmd.Commands()))
 	for _, c := range rootCmd.Commands() {
@@ -38,7 +38,7 @@ func TestRootHelpListsSubjects(t *testing.T) {
 		t.Fatal(err)
 	}
 	help := out.String()
-	for _, snippet := range []string{"calendar", "projects", "tasks", "users", "opportunities"} {
+	for _, snippet := range []string{"calendar", "projects", "tasks", "users", "opportunities", "invoices"} {
 		if !strings.Contains(help, snippet) {
 			t.Fatalf("help missing %q", snippet)
 		}
@@ -53,6 +53,13 @@ func TestProjectsAlias(t *testing.T) {
 	if cmd.Name() != "projects" {
 		t.Fatalf("prj alias resolved to %q", cmd.Name())
 	}
+	ms, _, err := rootCmd.Find([]string{"projects", "milestone-create"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ms.Name() != "milestone-create" {
+		t.Fatalf("milestone-create resolved to %q", ms.Name())
+	}
 }
 
 func TestNewOOReturnsErrorWithoutCredentials(t *testing.T) {

cmd/oo/common.go

@@ -20,7 +20,7 @@ var outputFormat = "table"
 var rootCmd = &cobra.Command{
 	Use:           "oo",
 	Short:         "OnlyOffice Workspace CLI — subject-based command tree",
-	Long:          "oo is a thin CLI over github.com/eslider/go-onlyoffice.\nCommands are grouped by OnlyOffice subject (calendar, projects, tasks, users, persons, companies, opportunities, cases, crm-tasks, applications).",
+	Long:          "oo is a thin CLI over github.com/eslider/go-onlyoffice.\nCommands are grouped by OnlyOffice subject (calendar, projects, tasks, users, persons, companies, opportunities, cases, crm-tasks, mails, invoices).",
 	Version:       version,
 	SilenceUsage:  true,
 	SilenceErrors: false,

cmd/oo/contacts.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"strconv"
+	"strings"
 
 	onlyoffice "github.com/eslider/go-onlyoffice"
 	"github.com/spf13/cobra"
@@ -39,12 +40,20 @@ func init() {
 	contactsCmd.AddCommand(contactsListCmd(nil))
 	contactsCmd.AddCommand(contactsGetCmd())
 	contactsCmd.AddCommand(contactsDeleteCmd())
+	contactsCmd.AddCommand(contactsMergeCmd())
 	contactsCmd.AddCommand(contactsInfoAddCmd())
 	contactsCmd.AddCommand(contactsDedupeInfoCmd())
+	contactsCmd.AddCommand(contactsTagsCmd())
+	contactsCmd.AddCommand(contactsTagCreateCmd())
+	contactsCmd.AddCommand(contactsTagAddCmd())
+	contactsCmd.AddCommand(contactsTagRemoveCmd())
+	contactsCmd.AddCommand(contactsByTagCmd())
 
 	only := true
 	personsCmd.AddCommand(contactsListCmd(&only)) // persons only
 	personsCmd.AddCommand(personsCreateCmd())
+	personsCmd.AddCommand(personsUpdateCmd())
+	personsCmd.AddCommand(personsFixNamesCmd())
 	personsCmd.AddCommand(contactsDeleteCmd())
 	personsCmd.AddCommand(personsDedupeCmd())
 
@@ -146,6 +155,26 @@ func contactsDeleteCmd() *cobra.Command {
 	}
 }
 
+func contactsMergeCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "merge FROM_ID INTO_ID",
+		Short: "Merge FROM contact into INTO (FROM is removed)",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.MergeContacts(cmd.Context(), args[1], args[0])
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+}
+
 func contactsInfoAddCmd() *cobra.Command {
 	var infoType, value, category string
 	var isPrimary bool
@@ -177,7 +206,7 @@ func contactsInfoAddCmd() *cobra.Command {
 }
 
 func personsCreateCmd() *cobra.Command {
-	var first, last, email, linkedin string
+	var first, last, email, linkedin, phone string
 	var companyID int
 	var jobTitle, about string
 	cmd := &cobra.Command{
@@ -200,6 +229,9 @@ func personsCreateCmd() *cobra.Command {
 			if email != "" {
 				_, _ = c.AddContactInfo(cmd.Context(), pid, "Email", email, "Work", true)
 			}
+			if phone != "" {
+				_, _ = c.AddContactInfo(cmd.Context(), pid, "Phone", phone, "Work", true)
+			}
 			if linkedin != "" {
 				_, _ = c.AddContactInfo(cmd.Context(), pid, "LinkedIn", linkedin, "Work", false)
 			}
@@ -213,12 +245,169 @@ func personsCreateCmd() *cobra.Command {
 	cmd.Flags().StringVar(&jobTitle, "job-title", "", "")
 	cmd.Flags().StringVar(&about, "about", "", "about / bio")
 	cmd.Flags().StringVar(&email, "email", "", "primary email (adds ContactInfo)")
+	cmd.Flags().StringVar(&phone, "phone", "", "primary phone (adds ContactInfo)")
 	cmd.Flags().StringVar(&linkedin, "linkedin", "", "linkedin url (adds ContactInfo)")
 	return cmd
 }
 
+func personsUpdateCmd() *cobra.Command {
+	var first, last string
+	var companyID int
+	var jobTitle, about string
+	cmd := &cobra.Command{
+		Use:   "update PERSON_ID",
+		Short: "Update a person (name, company, job title, about)",
+		Long: `Updates CRM person fields via PUT /crm/contact/person/{id}.
+
+--company-id 0 leaves the employer association unchanged.
+Omit --first/--last to keep current names (fetched first).`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pid := args[0]
+			cur, err := c.GetContact(cmd.Context(), pid)
+			if err != nil {
+				return err
+			}
+			if first == "" {
+				if v, ok := cur["firstName"].(string); ok {
+					first = v
+				}
+			}
+			if last == "" {
+				if v, ok := cur["lastName"].(string); ok {
+					last = v
+				}
+			}
+			if first == "" || last == "" {
+				return fmt.Errorf("first and last name required (pass --first/--last or ensure contact has them)")
+			}
+			out, err := c.UpdatePerson(cmd.Context(), pid, first, last, companyID, jobTitle, about)
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&first, "first", "", "first name (default: current)")
+	cmd.Flags().StringVar(&last, "last", "", "last name (default: current)")
+	cmd.Flags().IntVar(&companyID, "company-id", 0, "employer company id (0 = leave unchanged)")
+	cmd.Flags().StringVar(&jobTitle, "job-title", "", "job title")
+	cmd.Flags().StringVar(&about, "about", "", "about / bio")
+	return cmd
+}
+
+func personsFixNamesCmd() *cobra.Command {
+	var companyID int
+	var dryRun bool
+	var orgHint string
+	cmd := &cobra.Command{
+		Use:   "fix-names",
+		Short: "Strip company annotations from last names; keep companyId link",
+		Long: `Repairs CRM persons whose lastName embeds a company ("Doe (Acme)")
+or whose firstName is an email. Company belongs on companyId, not in the name.
+
+With --company-id, only persons linked to that company are scanned.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			ctx := cmd.Context()
+			var list []map[string]any
+			if companyID > 0 {
+				list, err = c.ListCompanyPersons(ctx, strconv.Itoa(companyID))
+			} else {
+				all, err2 := c.ListAllContacts(ctx)
+				err = err2
+				for _, row := range all {
+					if isCo, _ := row["isCompany"].(bool); !isCo {
+						list = append(list, row)
+					}
+				}
+			}
+			if err != nil {
+				return err
+			}
+			fixed, skipped := 0, 0
+			for _, p := range list {
+				id := fmt.Sprint(p["id"])
+				// List payloads often omit contactInfos; refresh when name looks like email.
+				fn := strings.TrimSpace(fmt.Sprint(p["firstName"]))
+				if strings.Contains(fn, "@") || fn == "" {
+					if full, gerr := c.GetContact(ctx, id); gerr == nil && full != nil {
+						p = full
+					}
+				}
+				fn = strings.TrimSpace(fmt.Sprint(p["firstName"]))
+				ln := strings.TrimSpace(fmt.Sprint(p["lastName"]))
+				dn := strings.TrimSpace(fmt.Sprint(p["displayName"]))
+				org := orgHint
+				if org == "" {
+					if co, ok := p["company"].(map[string]any); ok {
+						org = strings.TrimSpace(fmt.Sprint(co["displayName"]))
+					}
+				}
+				emails := contactEmailsFromMap(p)
+				for _, row := range onlyoffice.ContactInfoRows(p) {
+					if onlyoffice.NormalizeContactInfoType(fmt.Sprint(row["infoType"])) == "email" {
+						if data := strings.TrimSpace(fmt.Sprint(row["data"])); data != "" {
+							emails = append(emails, data)
+						}
+					}
+				}
+				cf, cl := onlyoffice.CleanPersonNames(fn, ln, dn, org, emails)
+				needName := cf != fn || cl != ln
+				linkID := companyID
+				if linkID == 0 {
+					if co, ok := p["company"].(map[string]any); ok {
+						linkID = int(flexIDFloat(co["id"]))
+					}
+				}
+				if !needName {
+					skipped++
+					continue
+				}
+				row := map[string]any{
+					"id": id, "from": fn + " / " + ln, "to": cf + " / " + cl, "companyId": linkID,
+				}
+				if dryRun {
+					printObject(row)
+					fixed++
+					continue
+				}
+				if _, err := c.UpdatePerson(ctx, id, cf, cl, linkID, "", ""); err != nil {
+					return fmt.Errorf("update %s: %w", id, err)
+				}
+				printObject(row)
+				fixed++
+			}
+			printObject(map[string]any{"fixed": fixed, "skipped": skipped, "dry_run": dryRun})
+			return nil
+		},
+	}
+	cmd.Flags().IntVar(&companyID, "company-id", 0, "limit to persons of this company")
+	cmd.Flags().StringVar(&orgHint, "org", "", "org name hint for stripping suffixes")
+	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "print planned renames only")
+	return cmd
+}
+
+func contactEmailsFromMap(p map[string]any) []string {
+	var out []string
+	for _, k := range []string{"email", "primaryEmail"} {
+		if v := strings.TrimSpace(fmt.Sprint(p[k])); v != "" && v != "<nil>" {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
 func companiesCreateCmd() *cobra.Command {
-	var name, email, website string
+	var name, email, website, phone, about, street, city, state, zip, country string
 	cmd := &cobra.Command{
 		Use:     "create",
 		Aliases: []string{"add"},
@@ -236,12 +425,34 @@ func companiesCreateCmd() *cobra.Command {
 				return err
 			}
 			cid := strconv.Itoa(int(flexIDFloat(out["id"])))
+			if about != "" || street != "" {
+				aboutText := about
+				if street != "" {
+					addr := strings.TrimSpace(strings.Join([]string{street, zip, city, state, country}, ", "))
+					if aboutText != "" {
+						aboutText = aboutText + "\n" + addr
+					} else {
+						aboutText = "Billing address: " + addr
+					}
+				}
+				if updated, err := c.UpdateCompany(cmd.Context(), cid, name, aboutText); err == nil {
+					out = updated
+				}
+			}
 			if email != "" {
 				_, _ = c.AddContactInfo(cmd.Context(), cid, "Email", email, "Work", true)
 			}
 			if website != "" {
 				_, _ = c.AddContactInfo(cmd.Context(), cid, "Website", website, "Work", false)
 			}
+			if phone != "" {
+				_, _ = c.AddContactInfo(cmd.Context(), cid, "Phone", phone, "Work", true)
+			}
+			if street != "" {
+				if _, err := c.AddContactAddress(cmd.Context(), cid, street, city, state, zip, country, "Billing", true); err != nil {
+					fmt.Fprintf(cmd.ErrOrStderr(), "warning: address API failed (stored in about): %v\n", err)
+				}
+			}
 			printObject(out)
 			return nil
 		},
@@ -249,6 +460,13 @@ func companiesCreateCmd() *cobra.Command {
 	cmd.Flags().StringVar(&name, "name", "", "company name")
 	cmd.Flags().StringVar(&email, "email", "", "primary email (adds ContactInfo)")
 	cmd.Flags().StringVar(&website, "website", "", "website url (adds ContactInfo)")
+	cmd.Flags().StringVar(&phone, "phone", "", "primary phone (adds ContactInfo)")
+	cmd.Flags().StringVar(&about, "about", "", "about / notes")
+	cmd.Flags().StringVar(&street, "street", "", "billing street")
+	cmd.Flags().StringVar(&city, "city", "", "billing city")
+	cmd.Flags().StringVar(&state, "state", "", "billing state")
+	cmd.Flags().StringVar(&zip, "zip", "", "billing zip")
+	cmd.Flags().StringVar(&country, "country", "", "billing country")
 	return cmd
 }
 
@@ -311,3 +529,106 @@ func contactsDedupeInfoCmd() *cobra.Command {
 		}),
 	}
 }
+
+func contactsTagsCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "tags",
+		Short: "List CRM contact tags",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			list, err := c.ListContactTags(cmd.Context())
+			if err != nil {
+				return err
+			}
+			printTable([]string{"title", "relativeItemsCount"}, list)
+			return nil
+		},
+	}
+}
+
+func contactsTagCreateCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "tag-create TAG",
+		Short: "Create a CRM contact tag",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			if err := c.CreateContactTag(cmd.Context(), args[0]); err != nil {
+				return err
+			}
+			fmt.Println(args[0])
+			return nil
+		},
+	}
+}
+
+func contactsTagAddCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "tag-add CONTACT_ID TAG",
+		Short: "Attach a tag to a contact",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			if err := c.AddContactTag(cmd.Context(), args[0], args[1]); err != nil {
+				return err
+			}
+			fmt.Printf("%s ← %s\n", args[0], args[1])
+			return nil
+		},
+	}
+}
+
+func contactsTagRemoveCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "tag-remove CONTACT_ID TAG",
+		Short: "Remove a tag from a contact",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			if err := c.RemoveContactTag(cmd.Context(), args[0], args[1]); err != nil {
+				return err
+			}
+			fmt.Printf("%s ✕ %s\n", args[0], args[1])
+			return nil
+		},
+	}
+}
+
+func contactsByTagCmd() *cobra.Command {
+	var count, offset int
+	cmd := &cobra.Command{
+		Use:   "by-tag TAG",
+		Short: "List contacts with a given CRM tag (ignore-list = tag ignore)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			list, total, err := c.ListContactsByTag(cmd.Context(), args[0], count, offset)
+			if err != nil {
+				return err
+			}
+			if outputFormat == "table" {
+				fmt.Printf("tag=%s total: %d (shown: %d)\n", args[0], total, len(list))
+			}
+			printTable([]string{"id", "displayName", "isCompany", "title", "about"}, list)
+			return nil
+		},
+	}
+	cmd.Flags().IntVar(&count, "count", 50, "")
+	cmd.Flags().IntVar(&offset, "offset", 0, "")
+	return cmd
+}

cmd/oo/crm_tasks.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"strconv"
+	"strings"
 
 	"github.com/spf13/cobra"
 )
@@ -17,6 +18,7 @@ func init() {
 	rootCmd.AddCommand(crmTasksCmd)
 	crmTasksCmd.AddCommand(crmTasksListCmd())
 	crmTasksCmd.AddCommand(crmTasksCreateCmd())
+	crmTasksCmd.AddCommand(crmTasksReassignSelfCmd())
 	crmTasksCmd.AddCommand(crmTasksDeleteCmd())
 	crmTasksCmd.AddCommand(crmTasksCategoriesCmd())
 }
@@ -38,7 +40,7 @@ func crmTasksListCmd() *cobra.Command {
 			if outputFormat == "table" {
 				fmt.Printf("total: %d (shown: %d)\n", total, len(list))
 			}
-			printTable([]string{"id", "title", "deadline", "isClosed", "categoryID"}, list)
+			printTable([]string{"id", "title", "deadLine", "isClosed", "categoryID"}, list)
 			return nil
 		},
 	}
@@ -53,7 +55,7 @@ func crmTasksCreateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "create TITLE",
 		Aliases: []string{"add"},
-		Short:   "Create a CRM task",
+		Short:   "Create a CRM task (assigns self + deadline default now+14d)",
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := newOO(cmd)
@@ -68,7 +70,7 @@ func crmTasksCreateCmd() *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().StringVar(&deadline, "deadline", "", "deadline (YYYY-MM-DD or ISO8601)")
+	cmd.Flags().StringVar(&deadline, "deadline", "", "deadline (YYYY-MM-DD or ISO8601); default now+14d")
 	cmd.Flags().IntVar(&categoryID, "category", 0, "category id (see `oo crm-tasks categories`)")
 	cmd.Flags().IntVar(&contactID, "contact", 0, "contact id")
 	cmd.Flags().StringVar(&entityType, "entity-type", "", "opportunity|case|contact")
@@ -77,6 +79,104 @@ func crmTasksCreateCmd() *cobra.Command {
 	return cmd
 }
 
+func crmTaskNeedsOwner(t map[string]any) (need bool, name string) {
+	resp, _ := t["responsible"].(map[string]any)
+	rid, _ := resp["id"].(string)
+	name, _ = resp["displayName"].(string)
+	need = rid == "" || strings.EqualFold(name, "Profile has been removed")
+	return need, name
+}
+
+func crmTaskCategoryID(t map[string]any) int {
+	cat, ok := t["category"].(map[string]any)
+	if !ok {
+		return 0
+	}
+	switch v := cat["id"].(type) {
+	case float64:
+		return int(v)
+	case int:
+		return v
+	default:
+		return 0
+	}
+}
+
+func crmTasksReassignSelfCmd() *cobra.Command {
+	var apply bool
+	var count, max int
+	cmd := &cobra.Command{
+		Use:   "reassign-self",
+		Short: "Reassign CRM tasks with missing/removed owner to the authenticated user",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			uid, err := c.SelfUserID(cmd.Context())
+			if err != nil {
+				return err
+			}
+
+			type item struct {
+				id, title, deadline, ownerName string
+				categoryID                     int
+			}
+			var todos []item
+			scanned := 0
+			for start := 0; ; start += count {
+				list, total, err := c.ListCRMTasks(cmd.Context(), count, start)
+				if err != nil {
+					return err
+				}
+				for _, t := range list {
+					scanned++
+					need, name := crmTaskNeedsOwner(t)
+					if !need {
+						continue
+					}
+					title, _ := t["title"].(string)
+					dl, _ := t["deadLine"].(string)
+					todos = append(todos, item{
+						id: fmt.Sprint(t["id"]), title: title, deadline: dl,
+						ownerName: name, categoryID: crmTaskCategoryID(t),
+					})
+					if max > 0 && len(todos) >= max {
+						break
+					}
+				}
+				if (max > 0 && len(todos) >= max) || start+count >= total || len(list) == 0 {
+					break
+				}
+			}
+
+			fixed := 0
+			for _, t := range todos {
+				fmt.Printf("  task %s %q owner=%q → %s\n", t.id, t.title, t.ownerName, uid)
+				if !apply {
+					fixed++
+					continue
+				}
+				if _, err := c.UpdateCRMTask(cmd.Context(), t.id, t.title, t.deadline, t.categoryID, uid); err != nil {
+					return fmt.Errorf("update %s: %w", t.id, err)
+				}
+				fixed++
+			}
+
+			mode := "DRY-RUN"
+			if apply {
+				mode = "APPLIED"
+			}
+			fmt.Printf("%s: scanned=%d reassigned=%d (self=%s)\n", mode, scanned, fixed, uid)
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&apply, "apply", false, "write changes (default dry-run)")
+	cmd.Flags().IntVar(&count, "count", 100, "page size")
+	cmd.Flags().IntVar(&max, "max", 0, "stop after N candidates (0 = all)")
+	return cmd
+}
+
 func crmTasksDeleteCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:     "delete TASK_ID [TASK_ID...]",

cmd/oo/invoices.go

@@ -0,0 +1,441 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	onlyoffice "github.com/eslider/go-onlyoffice"
+	"github.com/spf13/cobra"
+)
+
+var invoicesCmd = &cobra.Command{
+	Use:     "invoices",
+	Aliases: []string{"invoice"},
+	Short:   "CRM invoices (billing)",
+}
+
+func init() {
+	rootCmd.AddCommand(invoicesCmd)
+	invoicesCmd.AddCommand(invoiceListCmd())
+	invoicesCmd.AddCommand(invoiceGetCmd())
+	invoicesCmd.AddCommand(invoiceCreateCmd())
+	invoicesCmd.AddCommand(invoiceUpdateCmd())
+	invoicesCmd.AddCommand(invoicePDFCmd())
+	invoicesCmd.AddCommand(invoicePDFCleanupCmd())
+	invoicesCmd.AddCommand(invoiceStatusCmd())
+	invoicesCmd.AddCommand(invoiceDeleteCmd())
+	invoicesCmd.AddCommand(invoiceItemsCmd())
+}
+
+func invoiceListCmd() *cobra.Command {
+	var count, offset int
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List CRM invoices",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			list, total, err := c.ListInvoices(cmd.Context(), count, offset)
+			if err != nil {
+				return err
+			}
+			rows := make([]map[string]any, 0, len(list))
+			for _, inv := range list {
+				rows = append(rows, onlyoffice.FlattenInvoiceRow(inv))
+			}
+			if outputFormat == "table" {
+				fmt.Printf("total: %d (shown: %d)\n", total, len(rows))
+			}
+			printTable([]string{"id", "number", "cost", "statusTitle", "contactName", "issueDate", "dueDate"}, rows)
+			return nil
+		},
+	}
+	cmd.Flags().IntVar(&count, "count", 50, "")
+	cmd.Flags().IntVar(&offset, "offset", 0, "")
+	return cmd
+}
+
+func invoiceGetCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "get INVOICE_ID",
+		Short: "Show an invoice by id (incl. lines)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.GetInvoice(cmd.Context(), args[0])
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+}
+
+func invoiceCreateCmd() *cobra.Command {
+	var (
+		number, issueDate, dueDate, language, currency, terms, description, po string
+		contactID, consigneeID, itemID, opportunityID                          int64
+		price, qty                                                             float64
+		lineDesc                                                               string
+	)
+	cmd := &cobra.Command{
+		Use:   "create",
+		Short: "Create a draft invoice with one line",
+		Long: `Create a CRM invoice (Draft) with a single line.
+
+Always pass --opportunity when a deal exists (entity link at create). Updating
+--opportunity later often fails with HTTP 400 — see docs/crm-associations.md.
+
+Example:
+  oo invoices create --number INV-2026-01 --contact CONTACT_ID --item ITEM_ID \
+    --price 300 --opportunity OPPORTUNITY_ID --line-description "Service package" \
+    --terms "…payment terms…"
+`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if number == "" || contactID == 0 || itemID == 0 {
+				return fmt.Errorf("--number, --contact and --item are required")
+			}
+			if issueDate == "" {
+				issueDate = time.Now().Format("2006-01-02") + "T00:00:00.0000000+01:00"
+			} else if !strings.Contains(issueDate, "T") {
+				issueDate = issueDate + "T00:00:00.0000000+01:00"
+			}
+			if dueDate == "" {
+				dueDate = time.Now().Add(14 * 24 * time.Hour).Format("2006-01-02") + "T00:00:00.0000000+01:00"
+			} else if !strings.Contains(dueDate, "T") {
+				dueDate = dueDate + "T00:00:00.0000000+01:00"
+			}
+			if qty == 0 {
+				qty = 1
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.CreateInvoice(cmd.Context(), onlyoffice.CreateInvoiceParams{
+				Number:              number,
+				IssueDate:           issueDate,
+				DueDate:             dueDate,
+				ContactID:           contactID,
+				ConsigneeID:         consigneeID,
+				EntityID:            opportunityID,
+				EntityType:          0, // Opportunity
+				Language:            language,
+				Currency:            currency,
+				ExchangeRate:        1,
+				PurchaseOrderNumber: po,
+				Terms:               terms,
+				Description:         description,
+				Lines: []onlyoffice.InvoiceLine{{
+					InvoiceItemID: itemID,
+					Description:   lineDesc,
+					Quantity:      qty,
+					Price:         price,
+					SortOrder:     0,
+				}},
+			})
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&number, "number", "", "invoice number (e.g. INV-2026-01)")
+	cmd.Flags().Int64Var(&contactID, "contact", 0, "bill-to company contact id (canonical company, not a PDF-only clone)")
+	cmd.Flags().Int64Var(&consigneeID, "consignee", 0, "optional Empfänger person/contact id")
+	cmd.Flags().Int64Var(&opportunityID, "opportunity", 0, "link to CRM opportunity/deal id (set at create)")
+	cmd.Flags().Int64Var(&itemID, "item", 0, "catalog invoice item id")
+	cmd.Flags().Float64Var(&price, "price", 0, "line price")
+	cmd.Flags().Float64Var(&qty, "qty", 1, "line quantity")
+	cmd.Flags().StringVar(&lineDesc, "line-description", "", "line description override")
+	cmd.Flags().StringVar(&issueDate, "issue-date", "", "YYYY-MM-DD (default today)")
+	cmd.Flags().StringVar(&dueDate, "due-date", "", "YYYY-MM-DD (default +14d)")
+	cmd.Flags().StringVar(&language, "language", "de-DE", "invoice language")
+	cmd.Flags().StringVar(&currency, "currency", "EUR", "currency abbreviation")
+	cmd.Flags().StringVar(&terms, "terms", "", "payment terms / footer")
+	cmd.Flags().StringVar(&description, "description", "", "invoice description")
+	cmd.Flags().StringVar(&po, "po", "", "purchase order number")
+	return cmd
+}
+
+func invoiceUpdateCmd() *cobra.Command {
+	var opportunityID int64
+	var description, po, terms string
+	cmd := &cobra.Command{
+		Use:   "update INVOICE_ID",
+		Short: "Update invoice (notes, PO, terms; opportunity link unreliable)",
+		Long: `Update Draft invoice fields.
+
+--opportunity often returns HTTP 400 on existing invoices. Prefer
+oo invoices create … --opportunity, or delete+recreate. See docs/crm-associations.md.
+`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if opportunityID == 0 && !cmd.Flags().Changed("description") && !cmd.Flags().Changed("po") && !cmd.Flags().Changed("terms") {
+				return fmt.Errorf("set --opportunity and/or --description and/or --po and/or --terms")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.UpdateInvoice(cmd.Context(), args[0], onlyoffice.UpdateInvoiceParams{
+				EntityID:         opportunityID,
+				EntityType:       0,
+				Description:      description,
+				DescriptionSet:   cmd.Flags().Changed("description"),
+				PurchaseOrder:    po,
+				PurchaseOrderSet: cmd.Flags().Changed("po"),
+				Terms:            terms,
+				TermsSet:         cmd.Flags().Changed("terms"),
+			})
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().Int64Var(&opportunityID, "opportunity", 0, "CRM opportunity/deal id (may 400 — prefer create)")
+	cmd.Flags().StringVar(&description, "description", "", "invoice notes (Notizen); use \\n for line breaks")
+	cmd.Flags().StringVar(&po, "po", "", "purchase order number")
+	cmd.Flags().StringVar(&terms, "terms", "", "payment terms / footer (Bedingungen)")
+	return cmd
+}
+
+func invoicePDFCmd() *cobra.Command {
+	var force bool
+	cmd := &cobra.Command{
+		Use:   "pdf INVOICE_ID",
+		Short: "Return / regenerate invoice PDF file metadata",
+		Long: `GET /api/2.0/crm/invoice/{id}/pdf.
+
+With --force, touches the Draft to clear cached fileID first (layout changes).
+`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			var out map[string]any
+			if force {
+				out, err = c.ForceRegenerateInvoicePDF(cmd.Context(), args[0])
+			} else {
+				out, err = c.InvoicePDFFile(cmd.Context(), args[0])
+			}
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&force, "force", false, "clear PDF cache then regenerate")
+	return cmd
+}
+
+func invoicePDFCleanupCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "pdf-cleanup INVOICE_ID",
+		Short: "Delete older P-*.pdf copies on company/deal; keep invoice.fileID",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			deleted, err := c.PurgeStaleInvoicePDFs(cmd.Context(), args[0])
+			if err != nil {
+				return err
+			}
+			if outputFormat == "json" {
+				printObject(map[string]any{"deleted": deleted})
+				return nil
+			}
+			fmt.Printf("deleted %d stale PDF file(s): %v\n", len(deleted), deleted)
+			return nil
+		},
+	}
+}
+
+func invoiceStatusCmd() *cobra.Command {
+	var status string
+	cmd := &cobra.Command{
+		Use:   "status INVOICE_ID [INVOICE_ID...]",
+		Short: "Set invoice status (draft|billed|rejected|paid)",
+		Long: `PUT /api/2.0/crm/invoice/status/{id}.
+
+Billed invoices are not content-editable. Billed→Draft often does not work —
+recreate as Draft instead (docs/crm-associations.md).
+`,
+		Args: cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			statusID, err := parseInvoiceStatus(status)
+			if err != nil {
+				return err
+			}
+			ids := make([]int64, 0, len(args))
+			for _, a := range args {
+				var id int64
+				if _, err := fmt.Sscan(a, &id); err != nil || id <= 0 {
+					return fmt.Errorf("invalid invoice id %q", a)
+				}
+				ids = append(ids, id)
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.SetInvoiceStatus(cmd.Context(), statusID, ids...)
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&status, "status", "draft", "draft|billed|rejected|paid or numeric id")
+	return cmd
+}
+
+func parseInvoiceStatus(s string) (int, error) {
+	s = strings.TrimSpace(strings.ToLower(s))
+	switch s {
+	case "", "draft", "1":
+		return onlyoffice.InvoiceStatusDraft, nil
+	case "billed", "2":
+		return onlyoffice.InvoiceStatusBilled, nil
+	case "rejected", "3":
+		return onlyoffice.InvoiceStatusRejected, nil
+	case "paid", "4":
+		return onlyoffice.InvoiceStatusPaid, nil
+	default:
+		var n int
+		if _, err := fmt.Sscan(s, &n); err != nil || n <= 0 {
+			return 0, fmt.Errorf("unknown status %q (draft|billed|rejected|paid)", s)
+		}
+		return n, nil
+	}
+}
+
+func invoiceDeleteCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "delete INVOICE_ID [INVOICE_ID...]",
+		Short: "Delete one or more invoices",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			for _, id := range args {
+				if _, err := c.DeleteInvoice(cmd.Context(), id); err != nil {
+					return err
+				}
+				fmt.Println("deleted", id)
+			}
+			return nil
+		},
+	}
+}
+
+func invoiceItemsCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "items",
+		Aliases: []string{"item"},
+		Short:   "Invoice catalog items",
+	}
+	cmd.AddCommand(invoiceItemsListCmd())
+	cmd.AddCommand(invoiceItemsCreateCmd())
+	cmd.AddCommand(invoiceItemsDeleteCmd())
+	return cmd
+}
+
+func invoiceItemsListCmd() *cobra.Command {
+	var count, offset int
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List catalog invoice items",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			list, total, err := c.ListInvoiceItems(cmd.Context(), count, offset)
+			if err != nil {
+				return err
+			}
+			if outputFormat == "table" {
+				fmt.Printf("total: %d (shown: %d)\n", total, len(list))
+				for _, row := range list {
+					if cur, ok := row["currency"].(map[string]any); ok {
+						row["currency"] = cur["abbreviation"]
+					}
+				}
+			}
+			printTable([]string{"id", "title", "price", "currency", "description"}, list)
+			return nil
+		},
+	}
+	cmd.Flags().IntVar(&count, "count", 50, "")
+	cmd.Flags().IntVar(&offset, "offset", 0, "")
+	return cmd
+}
+
+func invoiceItemsCreateCmd() *cobra.Command {
+	var title, description, currency string
+	var price float64
+	cmd := &cobra.Command{
+		Use:   "create",
+		Short: "Create a catalog invoice item",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if title == "" {
+				return fmt.Errorf("--title is required")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.CreateInvoiceItem(cmd.Context(), title, description, price, currency)
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&title, "title", "", "item title")
+	cmd.Flags().StringVar(&description, "description", "", "item description")
+	cmd.Flags().Float64Var(&price, "price", 0, "unit price")
+	cmd.Flags().StringVar(&currency, "currency", "EUR", "currency")
+	return cmd
+}
+
+func invoiceItemsDeleteCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "delete ITEM_ID [ITEM_ID...]",
+		Short: "Delete catalog invoice items",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			for _, id := range args {
+				if _, err := c.DeleteInvoiceItem(cmd.Context(), id); err != nil {
+					return err
+				}
+				fmt.Println("deleted", id)
+			}
+			return nil
+		},
+	}
+}

cmd/oo/mails.go

@@ -1,6 +1,8 @@
 package main
 
 import (
+	"fmt"
+	"os"
 	"strconv"
 	"strings"
 
@@ -11,7 +13,7 @@ import (
 var mailsCmd = &cobra.Command{
 	Use:     "mails",
 	Aliases: []string{"mail"},
-	Short:   "OnlyOffice Workspace mail — list, read, delete",
+	Short:   "OnlyOffice Workspace mail — list, read, draft, delete",
 }
 
 func init() {
@@ -20,6 +22,9 @@ func init() {
 	mailsCmd.AddCommand(mailsFoldersCmd())
 	mailsCmd.AddCommand(mailsListCmd())
 	mailsCmd.AddCommand(mailsGetCmd())
+	mailsCmd.AddCommand(mailsDraftCmd())
+	mailsCmd.AddCommand(mailsAttachCmd())
+	mailsCmd.AddCommand(mailsDraftInvoiceCmd())
 	mailsCmd.AddCommand(mailsDeleteCmd())
 }
 
@@ -126,6 +131,172 @@ func mailsGetCmd() *cobra.Command {
 	}
 }
 
+func mailsDraftCmd() *cobra.Command {
+	var from, to, cc, bcc, subject, body, html string
+	var id int64
+	cmd := &cobra.Command{
+		Use:   "draft",
+		Short: "Create or update a mail draft (OnlyOffice Mail)",
+		Long: `Save a draft in /addons/mail (PUT /api/2.0/mail/drafts/save).
+
+  oo mails draft --to a@b.com --subject "…" --body "<p>…</p>"
+  oo mails draft --id 123 --to a@b.com --subject "…" --html "<p>…</p>"
+`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if to == "" {
+				return fmt.Errorf("--to is required")
+			}
+			htmlBody := body
+			if html != "" {
+				htmlBody = html
+			}
+			if htmlBody == "" {
+				return fmt.Errorf("--body or --html is required")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.SaveMailDraft(cmd.Context(), onlyoffice.SaveMailDraftParams{
+				ID:      id,
+				From:    from,
+				To:      to,
+				Cc:      cc,
+				Bcc:     bcc,
+				Subject: subject,
+				Body:    onlyoffice.PlainTextToMailHTML(htmlBody),
+			})
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().Int64Var(&id, "id", 0, "existing draft id (0 = create)")
+	cmd.Flags().StringVar(&from, "from", "", "from address (default: first enabled mailbox)")
+	cmd.Flags().StringVar(&to, "to", "", "recipient (required)")
+	cmd.Flags().StringVar(&cc, "cc", "", "cc")
+	cmd.Flags().StringVar(&bcc, "bcc", "", "bcc")
+	cmd.Flags().StringVar(&subject, "subject", "", "subject")
+	cmd.Flags().StringVar(&body, "body", "", "plain text or HTML body")
+	cmd.Flags().StringVar(&html, "html", "", "HTML body (alias of --body when set)")
+	return cmd
+}
+
+func mailsAttachCmd() *cobra.Command {
+	var fileID int64
+	cmd := &cobra.Command{
+		Use:   "attach MESSAGE_ID",
+		Short: "Attach an OnlyOffice Files document to a draft/message",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if fileID <= 0 {
+				return fmt.Errorf("--file-id is required")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.AttachMailDocument(cmd.Context(), args[0], fileID)
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().Int64Var(&fileID, "file-id", 0, "OnlyOffice file id (e.g. invoice PDF)")
+	return cmd
+}
+
+func mailsDraftInvoiceCmd() *cobra.Command {
+	var to, from, subject, body string
+	var invoiceID int
+	cmd := &cobra.Command{
+		Use:   "draft-invoice",
+		Short: "Create a mail draft with regenerated invoice PDF attached",
+		Long: `Regenerate the CRM invoice PDF, save an OnlyOffice Mail draft, and attach the PDF.
+
+Does not send. Open /addons/mail/#drafts to review.
+
+  oo mails draft-invoice --invoice 16 --to info@example.com
+`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if invoiceID <= 0 || to == "" {
+				return fmt.Errorf("--invoice and --to are required")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pdf, err := c.ForceRegenerateInvoicePDF(cmd.Context(), strconv.Itoa(invoiceID))
+			if err != nil {
+				return err
+			}
+			fileID := onlyoffice.Int64FromMap(pdf, "id")
+			if fileID <= 0 {
+				return fmt.Errorf("invoice PDF has no file id: %+v", pdf)
+			}
+			inv, err := c.GetInvoice(cmd.Context(), strconv.Itoa(invoiceID))
+			if err != nil {
+				return err
+			}
+			number := strings.TrimSpace(fmt.Sprint(inv["number"]))
+			cost := formatInvoiceCostEUR(inv["cost"])
+			if subject == "" {
+				subject = fmt.Sprintf("Invoice %s (%s EUR)", number, cost)
+			}
+			if body == "" {
+				body = fmt.Sprintf(`Hello,
+
+please find attached invoice %s for %s EUR.
+
+Payment terms: see invoice notes.
+
+Best regards`, number, cost)
+			}
+			draft, err := c.SaveMailDraft(cmd.Context(), onlyoffice.SaveMailDraftParams{
+				From:    from,
+				To:      to,
+				Subject: subject,
+				Body:    onlyoffice.MailHTMLWithBlankParagraphs(onlyoffice.PlainTextToMailHTML(body)),
+			})
+			if err != nil {
+				return err
+			}
+			mid := fmt.Sprint(draft["id"])
+			att, err := c.AttachMailDocument(cmd.Context(), mid, fileID)
+			if err != nil {
+				return fmt.Errorf("draft %s created but attach failed: %w", mid, err)
+			}
+			if outputFormat == "json" {
+				printObject(map[string]any{"draft": draft, "attachment": att, "pdfFileId": fileID})
+				return nil
+			}
+			fmt.Printf("draft %s  to=%s  subject=%q  pdfFileId=%d\n", mid, to, subject, fileID)
+			fmt.Printf("open: %s/addons/mail/#drafts\n", strings.TrimRight(os.Getenv("ONLYOFFICE_URL"), "/"))
+			return nil
+		},
+	}
+	cmd.Flags().IntVar(&invoiceID, "invoice", 0, "CRM invoice id")
+	cmd.Flags().StringVar(&to, "to", "", "recipient")
+	cmd.Flags().StringVar(&from, "from", "", "from address (default mailbox)")
+	cmd.Flags().StringVar(&subject, "subject", "", "override subject")
+	cmd.Flags().StringVar(&body, "body", "", "override plain-text body")
+	return cmd
+}
+
+func formatInvoiceCostEUR(v any) string {
+	s := strings.TrimSpace(fmt.Sprint(v))
+	s = strings.TrimSuffix(s, ".00")
+	s = strings.TrimSuffix(s, ".0")
+	if s == "" || s == "<nil>" {
+		return "?"
+	}
+	return s
+}
+
 func mailsDeleteCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:     "delete ID [ID...]",

cmd/oo/main.go

@@ -6,15 +6,17 @@
 //	oo projects      list | get | milestones | create | update | delete | files (list|upload|download|rename|delete)
 //	oo tasks         list | get | create | update | delete | subtask add | files (list|upload|detach)
 //	oo users         list | self            (alias: oo whoami)
-//	oo contacts      list | get | delete | info-add | dedupe-info
+//	oo contacts      list | get | delete | info-add | merge | dedupe-info
 //	oo persons       list | create | delete | dedupe
 //	oo companies     list | create | delete | dedupe | dedupe-persons
 //	oo opportunities list | get | create | delete | stages | member-add | dedupe | dedupe-members | fix-titles
 //	oo cases         list | create | delete | member-add
 //	oo crm-tasks     list | create | delete | categories
 //	oo crm           cleanup
-//	oo mails         accounts | folders | list | get | delete
+//	oo mails         accounts | folders | list | get | draft | attach | draft-invoice | delete
-//	oo applications  sync
+//	oo invoices      list | get | create | update | pdf | pdf-cleanup | status | delete | items …
+//
+// CRM association rules: docs/crm-associations.md
 //
 // Every list supports `--output/-o json|table` (table is the default).
 //

cmd/oo/opportunities.go

@@ -19,6 +19,7 @@ func init() {
 	opportunitiesCmd.AddCommand(oppListCmd())
 	opportunitiesCmd.AddCommand(oppGetCmd())
 	opportunitiesCmd.AddCommand(oppCreateCmd())
+	opportunitiesCmd.AddCommand(oppUpdateCmd())
 	opportunitiesCmd.AddCommand(oppDeleteCmd())
 	opportunitiesCmd.AddCommand(oppStagesCmd())
 	opportunitiesCmd.AddCommand(oppMemberAddCmd())
@@ -118,6 +119,40 @@ func oppCreateCmd() *cobra.Command {
 	return cmd
 }
 
+func oppUpdateCmd() *cobra.Command {
+	var title, desc string
+	var stage int64
+	var bid float64
+	cmd := &cobra.Command{
+		Use:   "update OPPORTUNITY_ID",
+		Short: "Update opportunity title, description, stage, or bid",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			out, err := c.UpdateOpportunity(cmd.Context(), args[0], onlyoffice.UpdateOpportunityParams{
+				Title:       title,
+				Description: desc,
+				StageID:     stage,
+				BidValue:    bid,
+				BidValueSet: cmd.Flags().Changed("bid"),
+			})
+			if err != nil {
+				return err
+			}
+			printObject(out)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&title, "title", "", "new title")
+	cmd.Flags().StringVar(&desc, "description", "", "new description")
+	cmd.Flags().Int64Var(&stage, "stage", 0, "pipeline stage id")
+	cmd.Flags().Float64Var(&bid, "bid", 0, "bid value")
+	return cmd
+}
+
 func oppDeleteCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:     "delete OPPORTUNITY_ID [OPPORTUNITY_ID...]",

cmd/oo/projects.go

@@ -2,7 +2,11 @@ package main
 
 import (
 	"fmt"
+	"os"
+	"os/exec"
 	"strconv"
+	"strings"
+	"time"
 
 	onlyoffice "github.com/eslider/go-onlyoffice"
 	"github.com/spf13/cobra"
@@ -19,9 +23,11 @@ func init() {
 	projectsCmd.AddCommand(prjListCmd())
 	projectsCmd.AddCommand(prjGetCmd())
 	projectsCmd.AddCommand(prjMilestonesCmd())
+	projectsCmd.AddCommand(prjMilestoneCreateCmd())
 	projectsCmd.AddCommand(prjCreateCmd())
 	projectsCmd.AddCommand(prjUpdateCmd())
 	projectsCmd.AddCommand(prjDeleteCmd())
+	projectsCmd.AddCommand(prjContactsCmd())
 }
 
 func prjListCmd() *cobra.Command {
@@ -114,19 +120,80 @@ func prjMilestonesCmd() *cobra.Command {
 	}
 }
 
-func prjCreateCmd() *cobra.Command {
+func prjMilestoneCreateCmd() *cobra.Command {
-	var desc, resp string
+	var deadline, desc string
+	var key bool
 	cmd := &cobra.Command{
-		Use:   "create TITLE",
+		Use:   "milestone-create PROJECT_ID TITLE",
-		Short: "Create a new project",
+		Short: "Create a project milestone (Gantt row)",
-		Args:  cobra.ExactArgs(1),
+		Args:  cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := newOO(cmd)
 			if err != nil {
 				return err
 			}
+			pid, err := strconv.Atoi(args[0])
+			if err != nil {
+				return fmt.Errorf("project id must be integer: %w", err)
+			}
+			if deadline == "" {
+				return fmt.Errorf("--deadline YYYY-MM-DD is required")
+			}
+			day, err := time.Parse("2006-01-02", deadline)
+			if err != nil {
+				return fmt.Errorf("deadline: %w", err)
+			}
+			ms, err := c.CreateMilestone(onlyoffice.NewMilestoneRequest{
+				ProjectID:   pid,
+				Title:       args[1],
+				Deadline:    onlyoffice.Time(day),
+				Description: desc,
+				IsKey:       key,
+			})
+			if err != nil {
+				return err
+			}
+			printObject(map[string]any{
+				"id":    derefInt64(ms.ID),
+				"title": derefString(ms.Title),
+			})
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&deadline, "deadline", "", "deadline YYYY-MM-DD")
+	cmd.Flags().StringVar(&desc, "description", "", "description")
+	cmd.Flags().BoolVar(&key, "key", false, "mark as key milestone")
+	return cmd
+}
+
+func prjCreateCmd() *cobra.Command {
+	var desc, resp string
+	var country, company string
+	cmd := &cobra.Command{
+		Use:   "create TITLE",
+		Short: "Create a new project",
+		Long: `Create a project. Prefer canonical titles:
+
+  CC | Company | Title
+
+Examples:
+  oo projects create "Mapbender" --country DE --company "Stadt Mainz"
+  oo projects create "DE | Acme | Geo Engineer"
+
+When --country and --company are set, TITLE is only the third segment and the
+full title is composed as "CC | Company | Title".`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			title := args[0]
+			if country != "" || company != "" {
+				title = onlyoffice.FormatProjectTitle(country, company, args[0])
+			}
 			p, err := c.CreateProject(onlyoffice.NewProjectRequest{
-				Title:         args[0],
+				Title:         title,
 				Description:   desc,
 				ResponsibleID: resp,
 			})
@@ -142,6 +209,8 @@ func prjCreateCmd() *cobra.Command {
 	}
 	cmd.Flags().StringVar(&desc, "description", "", "project description")
 	cmd.Flags().StringVar(&resp, "responsible", "", "responsible user id (default: self)")
+	cmd.Flags().StringVar(&country, "country", "", "country/region code (DE, TF, UA, …)")
+	cmd.Flags().StringVar(&company, "company", "", "CRM company / engagement org name")
 	return cmd
 }
 
@@ -160,6 +229,25 @@ func prjUpdateCmd() *cobra.Command {
 			if err != nil {
 				return fmt.Errorf("project id must be integer: %w", err)
 			}
+			// OO update requires responsibleId; reuse current when not passed.
+			if resp == "" {
+				cur, gerr := c.GetProjectByID(cmd.Context(), args[0])
+				if gerr != nil {
+					return gerr
+				}
+				if r, ok := cur["responsible"].(map[string]any); ok {
+					resp = fmt.Sprint(r["id"])
+				}
+				if resp == "" || resp == "<nil>" {
+					resp = strings.TrimSpace(fmt.Sprint(cur["responsibleId"]))
+				}
+				if title == "" {
+					title = strings.TrimSpace(fmt.Sprint(cur["title"]))
+				}
+				if desc == "" {
+					desc = strings.TrimSpace(fmt.Sprint(cur["description"]))
+				}
+			}
 			p, err := c.UpdateProject(onlyoffice.ProjectUpdateRequest{
 				ID:            id,
 				Title:         title,
@@ -173,6 +261,11 @@ func prjUpdateCmd() *cobra.Command {
 				"id":    derefInt(p.ID),
 				"title": p.String(),
 			})
+			// Confirm via GET — some OO builds return an empty body on PUT.
+			got, gerr := c.GetProjectByID(cmd.Context(), args[0])
+			if gerr == nil && got != nil {
+				printObject(map[string]any{"confirmed_title": got["title"], "confirmed_id": got["id"]})
+			}
 			return nil
 		},
 	}
@@ -216,6 +309,314 @@ func derefString(p *string) string {
 	return *p
 }
 
+func prjContactsCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "contacts",
+		Short: "CRM contacts linked to a project (companies + persons)",
+		Long: `OnlyOffice Projects have two participant layers:
+  - Team (portal users) — ProjectTeam.aspx
+  - Contacts (CRM companies/persons) — linked via this API
+
+Link employers/clients and people who worked on the engagement (e.g. git authors).`,
+	}
+	cmd.AddCommand(prjContactsListCmd())
+	cmd.AddCommand(prjContactsAddCmd())
+	cmd.AddCommand(prjContactsRemoveCmd())
+	cmd.AddCommand(prjContactsLinkGitCmd())
+	cmd.AddCommand(prjContactsLinkAuthorsCmd())
+	return cmd
+}
+
+func prjContactsListCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "list PROJECT_ID",
+		Short: "List CRM contacts linked to the project",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pid, err := strconv.Atoi(args[0])
+			if err != nil {
+				return fmt.Errorf("project id: %w", err)
+			}
+			list, err := c.ListProjectContacts(cmd.Context(), pid)
+			if err != nil {
+				return err
+			}
+			rows := make([]map[string]any, 0, len(list))
+			for _, row := range list {
+				rows = append(rows, map[string]any{
+					"id":        row["id"],
+					"name":      row["displayName"],
+					"company":   row["isCompany"],
+					"companyOf": row["companyName"],
+				})
+			}
+			printTable([]string{"id", "name", "company", "companyOf"}, rows)
+			return nil
+		},
+	}
+}
+
+func prjContactsAddCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "add PROJECT_ID CONTACT_ID [CONTACT_ID...]",
+		Short: "Link CRM contact(s) to the project",
+		Args:  cobra.MinimumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pid, err := strconv.Atoi(args[0])
+			if err != nil {
+				return fmt.Errorf("project id: %w", err)
+			}
+			for _, raw := range args[1:] {
+				cid, err := strconv.Atoi(raw)
+				if err != nil {
+					return fmt.Errorf("contact id %q: %w", raw, err)
+				}
+				if _, err := c.AddProjectContact(cmd.Context(), pid, cid); err != nil {
+					return fmt.Errorf("add %d: %w", cid, err)
+				}
+				printObject(map[string]any{"project_id": pid, "contact_id": cid, "linked": true})
+			}
+			return nil
+		},
+	}
+}
+
+func prjContactsRemoveCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "remove PROJECT_ID CONTACT_ID [CONTACT_ID...]",
+		Short: "Unlink CRM contact(s) from the project",
+		Args:  cobra.MinimumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pid, err := strconv.Atoi(args[0])
+			if err != nil {
+				return fmt.Errorf("project id: %w", err)
+			}
+			for _, raw := range args[1:] {
+				cid, err := strconv.Atoi(raw)
+				if err != nil {
+					return fmt.Errorf("contact id %q: %w", raw, err)
+				}
+				if err := c.RemoveProjectContact(cmd.Context(), pid, cid); err != nil {
+					return fmt.Errorf("remove %d: %w", cid, err)
+				}
+				printObject(map[string]any{"project_id": pid, "contact_id": cid, "unlinked": true})
+			}
+			return nil
+		},
+	}
+}
+
+func prjContactsLinkGitCmd() *cobra.Command {
+	var gitRoot string
+	var minCommits int
+	var dryRun bool
+	var companyIDs []int
+	cmd := &cobra.Command{
+		Use:   "link-git PROJECT_ID",
+		Short: "Link CRM persons matched from git shortlog (+ optional companies)",
+		Long: `Runs git shortlog -sne --all in --git-root, matches author emails to CRM
+persons (FindPersonByEmail), and links found contacts to the project.
+Does not create new persons — create/link them in CRM first.
+
+Also links --company-id contacts (employer and/or client company).`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if gitRoot == "" && len(companyIDs) == 0 {
+				return fmt.Errorf("need --git-root and/or --company-id")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pid, err := strconv.Atoi(args[0])
+			if err != nil {
+				return fmt.Errorf("project id: %w", err)
+			}
+			var authors []gitAuthor
+			if gitRoot != "" {
+				authors, err = gitShortlogAuthors(gitRoot, minCommits)
+				if err != nil {
+					return err
+				}
+			}
+			return linkProjectPeople(cmd, c, pid, authors, companyIDs, dryRun)
+		},
+	}
+	cmd.Flags().StringVar(&gitRoot, "git-root", "", "local git repository path")
+	cmd.Flags().IntVar(&minCommits, "min-commits", 3, "ignore authors below this commit count")
+	cmd.Flags().IntSliceVar(&companyIDs, "company-id", nil, "CRM company contact ids to link")
+	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "print planned links only")
+	return cmd
+}
+
+func prjContactsLinkAuthorsCmd() *cobra.Command {
+	var authorsFile string
+	var minCommits int
+	var dryRun bool
+	var companyIDs []int
+	cmd := &cobra.Command{
+		Use:   "link-authors PROJECT_ID",
+		Short: "Link CRM persons from a git shortlog file (+ companies)",
+		Long: `Same as link-git, but reads authors from a file produced by:
+
+  git shortlog -sne --all > authors.txt
+
+Then: oo projects contacts link-authors 59 --from authors.txt --company-id COMPANY_ID`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if authorsFile == "" && len(companyIDs) == 0 {
+				return fmt.Errorf("need --from and/or --company-id")
+			}
+			c, err := newOO(cmd)
+			if err != nil {
+				return err
+			}
+			pid, err := strconv.Atoi(args[0])
+			if err != nil {
+				return fmt.Errorf("project id: %w", err)
+			}
+			var authors []gitAuthor
+			if authorsFile != "" {
+				b, err := os.ReadFile(authorsFile)
+				if err != nil {
+					return err
+				}
+				authors = parseShortlog(string(b), minCommits)
+			}
+			return linkProjectPeople(cmd, c, pid, authors, companyIDs, dryRun)
+		},
+	}
+	cmd.Flags().StringVar(&authorsFile, "from", "", "path to git shortlog -sne output")
+	cmd.Flags().IntVar(&minCommits, "min-commits", 3, "ignore authors below this commit count")
+	cmd.Flags().IntSliceVar(&companyIDs, "company-id", nil, "CRM company contact ids to link")
+	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "print planned links only")
+	return cmd
+}
+
+func linkProjectPeople(cmd *cobra.Command, c *onlyoffice.Client, pid int, authors []gitAuthor, companyIDs []int, dryRun bool) error {
+	ctx := cmd.Context()
+	existing, err := c.ListProjectContacts(ctx, pid)
+	if err != nil {
+		return err
+	}
+	have := map[int]struct{}{}
+	for _, row := range existing {
+		have[int(flexIDFloat(row["id"]))] = struct{}{}
+	}
+	linked, skipped := 0, 0
+	for _, cid := range companyIDs {
+		if _, ok := have[cid]; ok {
+			skipped++
+			continue
+		}
+		if dryRun {
+			printObject(map[string]any{"would_link_company": cid})
+			linked++
+			continue
+		}
+		if _, err := c.AddProjectContact(ctx, pid, cid); err != nil {
+			return fmt.Errorf("company %d: %w", cid, err)
+		}
+		have[cid] = struct{}{}
+		linked++
+		printObject(map[string]any{"linked_company": cid})
+	}
+	for _, a := range authors {
+		p, err := c.FindPersonByEmail(ctx, a.Email)
+		if err != nil {
+			return err
+		}
+		if p == nil {
+			printObject(map[string]any{
+				"skipped_email": a.Email, "name": a.Name, "commits": a.Commits, "reason": "no_crm_person",
+			})
+			skipped++
+			continue
+		}
+		cid := int(flexIDFloat(p["id"]))
+		if _, ok := have[cid]; ok {
+			skipped++
+			continue
+		}
+		if dryRun {
+			printObject(map[string]any{"would_link_person": cid, "email": a.Email, "commits": a.Commits})
+			linked++
+			continue
+		}
+		if _, err := c.AddProjectContact(ctx, pid, cid); err != nil {
+			return fmt.Errorf("person %d (%s): %w", cid, a.Email, err)
+		}
+		have[cid] = struct{}{}
+		linked++
+		printObject(map[string]any{"linked_person": cid, "email": a.Email, "commits": a.Commits})
+	}
+	printObject(map[string]any{"project_id": pid, "linked": linked, "skipped": skipped, "dry_run": dryRun})
+	return nil
+}
+
+func parseShortlog(text string, minCommits int) []gitAuthor {
+	var authors []gitAuthor
+	seen := map[string]struct{}{}
+	for _, line := range strings.Split(text, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		parts := strings.SplitN(line, "\t", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		n, _ := strconv.Atoi(strings.TrimSpace(parts[0]))
+		if n < minCommits {
+			continue
+		}
+		rest := parts[1]
+		lt := strings.LastIndex(rest, "<")
+		gt := strings.LastIndex(rest, ">")
+		if lt < 0 || gt <= lt {
+			continue
+		}
+		email := strings.ToLower(strings.TrimSpace(rest[lt+1 : gt]))
+		name := strings.TrimSpace(rest[:lt])
+		if email == "" {
+			continue
+		}
+		if _, ok := seen[email]; ok {
+			continue
+		}
+		seen[email] = struct{}{}
+		authors = append(authors, gitAuthor{Commits: n, Name: name, Email: email})
+	}
+	return authors
+}
+
+type gitAuthor struct {
+	Commits int
+	Name    string
+	Email   string
+}
+
+func gitShortlogAuthors(root string, minCommits int) ([]gitAuthor, error) {
+	cmd := exec.Command("git", "-C", root, "shortlog", "-sne", "--all")
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("git shortlog in %s: %w", root, err)
+	}
+	return parseShortlog(string(out), minCommits), nil
+}
+
 func derefInt(p *int) int {
 	if p == nil {
 		return 0

cmd/oo/tasks.go

@@ -2,7 +2,11 @@ package main
 
 import (
 	"fmt"
+	"os"
+	"strconv"
+	"time"
 
+	onlyoffice "github.com/eslider/go-onlyoffice"
 	"github.com/spf13/cobra"
 )
 
@@ -82,11 +86,12 @@ func taskGetCmd() *cobra.Command {
 }
 
 func taskCreateCmd() *cobra.Command {
-	var project, desc, deadline, prio string
+	var project, desc, deadline, start, prio string
+	var milestone int64
 	cmd := &cobra.Command{
 		Use:     "create TITLE",
 		Aliases: []string{"add"},
-		Short:   "Create a project task",
+		Short:   "Create a project task (Gantt bar when --start/--deadline/--milestone set)",
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := newOO(cmd)
@@ -100,6 +105,51 @@ func taskCreateCmd() *cobra.Command {
 			case "low":
 				p = -1
 			}
+			if start != "" || milestone != 0 {
+				pid, err := strconv.Atoi(project)
+				if err != nil && project != "" {
+					return fmt.Errorf("project id: %w", err)
+				}
+				if project == "" {
+					pid, err = strconv.Atoi(os.Getenv("OO_PROJECT_ID"))
+					if err != nil {
+						return fmt.Errorf("--project or OO_PROJECT_ID required")
+					}
+				}
+				req := onlyoffice.NewProjectTaskRequest{
+					ProjectId:   pid,
+					Title:       args[0],
+					Description: desc,
+					Priority:    p,
+					MilestoneId: int(milestone),
+				}
+				if deadline == "" {
+					deadline = time.Now().Add(14 * 24 * time.Hour).Format("2006-01-02")
+				}
+				d, err := time.Parse("2006-01-02", deadline)
+				if err != nil {
+					return fmt.Errorf("deadline: %w", err)
+				}
+				req.Deadline = onlyoffice.Time(d)
+				if start != "" {
+					s, err := time.Parse("2006-01-02", start)
+					if err != nil {
+						return fmt.Errorf("start: %w", err)
+					}
+					req.StartDate = onlyoffice.Time(s)
+				} else {
+					req.StartDate = onlyoffice.Time(time.Now())
+				}
+				task, err := c.CreateProjectTask(req)
+				if err != nil {
+					return err
+				}
+				printObject(map[string]any{
+					"id":    derefInt(task.ID),
+					"title": derefString(task.Title),
+				})
+				return nil
+			}
 			out, err := c.AddTask(cmd.Context(), project, args[0], desc, p, deadline)
 			if err != nil {
 				return err
@@ -110,7 +160,9 @@ func taskCreateCmd() *cobra.Command {
 	}
 	cmd.Flags().StringVarP(&project, "project", "p", "", "project id (default $OO_PROJECT_ID)")
 	cmd.Flags().StringVar(&desc, "description", "", "description")
-	cmd.Flags().StringVar(&deadline, "deadline", "", "deadline YYYY-MM-DD")
+	cmd.Flags().StringVar(&deadline, "deadline", "", "deadline YYYY-MM-DD (default now+14d)")
+	cmd.Flags().StringVar(&start, "start", "", "start YYYY-MM-DD (uses CreateProjectTask / Gantt)")
+	cmd.Flags().Int64Var(&milestone, "milestone", 0, "milestone id (Gantt row)")
 	cmd.Flags().StringVar(&prio, "priority", "normal", "high|normal|low")
 	return cmd
 }

crm.go

@@ -2,7 +2,7 @@ package onlyoffice
 
 // Minimal CRM helpers: contacts, opportunities, cases, tasks, and history notes.
 // These expose untyped maps for flexibility — they are primarily consumed by
-// cmd/oo and the applications-sync workflow.
+// cmd/oo and CRM sync tooling.
 
 import (
 	"context"
@@ -11,6 +11,7 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"time"
 )
 
 // ListContacts returns a page of CRM contacts and the total count.
@@ -45,9 +46,12 @@ func (c *Client) GetContact(ctx context.Context, contactID string) (map[string]a
 }
 
 // FindCompany searches for a company contact with an exact (case-insensitive)
-// displayName match. Returns nil when not found.
+// displayName match after slogan/legal-suffix normalization. Returns nil when not found.
 func (c *Client) FindCompany(ctx context.Context, name string) (map[string]any, error) {
 	needle := CompanyGroupingKey(name)
+	if needle == "" {
+		return nil, nil
+	}
 	const page = 50
 	for start := 0; ; start += page {
 		items, total, err := c.ListContacts(ctx, page, start, name)
@@ -66,6 +70,19 @@ func (c *Client) FindCompany(ctx context.Context, name string) (map[string]any,
 			break
 		}
 	}
+	// Search filter may miss longer legal names; fall back to a full company scan.
+	all, err := c.ListAllContacts(ctx)
+	if err != nil {
+		return nil, err
+	}
+	for _, co := range all {
+		if !isCompany(co) {
+			continue
+		}
+		if CompanyGroupingKey(fmt.Sprint(co["displayName"])) == needle {
+			return co, nil
+		}
+	}
 	return nil, nil
 }
 
@@ -95,6 +112,52 @@ func (c *Client) FindPerson(ctx context.Context, first, last string) (map[string
 	return nil, nil
 }
 
+// FindPersonByEmail finds a person whose primary or contact-info email matches
+// (case-insensitive). Companies are skipped. Returns nil when not found.
+func (c *Client) FindPersonByEmail(ctx context.Context, email string) (map[string]any, error) {
+	needle := strings.ToLower(strings.TrimSpace(email))
+	if needle == "" {
+		return nil, nil
+	}
+	all, err := c.ListAllContacts(ctx)
+	if err != nil {
+		return nil, err
+	}
+	for _, p := range all {
+		if isCompany(p) {
+			continue
+		}
+		for _, em := range contactEmailValues(p) {
+			if strings.ToLower(strings.TrimSpace(em)) == needle {
+				return p, nil
+			}
+		}
+	}
+	return nil, nil
+}
+
+func contactEmailValues(p map[string]any) []string {
+	var out []string
+	for _, key := range []string{"email", "primaryEmail"} {
+		if v := strings.TrimSpace(fmt.Sprint(p[key])); v != "" && v != "<nil>" {
+			out = append(out, v)
+		}
+	}
+	for _, row := range ContactInfoRows(p) {
+		if NormalizeContactInfoType(fmt.Sprint(row["infoType"])) != "email" {
+			continue
+		}
+		data := strings.TrimSpace(fmt.Sprint(row["data"]))
+		if data == "" || data == "<nil>" {
+			data = strings.TrimSpace(fmt.Sprint(row["value"]))
+		}
+		if data != "" {
+			out = append(out, data)
+		}
+	}
+	return out
+}
+
 func isCompany(m map[string]any) bool {
 	v, ok := m["isCompany"].(bool)
 	return ok && v
@@ -124,6 +187,44 @@ func (c *Client) CreatePerson(ctx context.Context, first, last string, companyID
 	return c.postFormObject(ctx, "/api/2.0/crm/contact/person.json", fields)
 }
 
+// UpdatePerson updates first/last name and optional company link on a person.
+// companyID == 0 leaves the company association unchanged (re-sends current
+// company id when present). OnlyOffice ignores companyId/about on form-encoded
+// PUT and may unlink the company when companyId is omitted — use JSON body.
+func (c *Client) UpdatePerson(ctx context.Context, personID, first, last string, companyID int, jobTitle, about string) (map[string]any, error) {
+	body := map[string]any{
+		"firstName": first,
+		"lastName":  last,
+	}
+	if companyID != 0 {
+		body["companyId"] = companyID
+	} else {
+		// Preserve existing employer: omitted companyId unlinks on this API.
+		if cur, err := c.GetContact(ctx, personID); err == nil {
+			if co, ok := cur["company"].(map[string]any); ok {
+				if id := flexInt(co["id"]); id != 0 {
+					body["companyId"] = id
+				}
+			}
+		}
+	}
+	if jobTitle != "" {
+		body["jobTitle"] = jobTitle
+	}
+	if about != "" {
+		body["about"] = about
+	}
+	out, err := c.putJSONObject(ctx, fmt.Sprintf("/api/2.0/crm/contact/person/%s.json", url.PathEscape(personID)), body)
+	if err != nil {
+		return out, err
+	}
+	// PUT response body is often stale; re-fetch for authoritative fields.
+	if fresh, gerr := c.GetContact(ctx, personID); gerr == nil && fresh != nil {
+		out = fresh
+	}
+	return out, nil
+}
+
 // AddContactInfo attaches an email/website/phone/etc. to a contact.
 func (c *Client) AddContactInfo(ctx context.Context, contactID, infoType, dataValue, category string, isPrimary bool) (map[string]any, error) {
 	if category == "" {
@@ -142,6 +243,69 @@ func (c *Client) DeleteContact(ctx context.Context, contactID string) (map[strin
 	return c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/contact/%s.json", url.PathEscape(contactID)))
 }
 
+// ListContactTags returns all CRM contact tags (title + relativeItemsCount).
+func (c *Client) ListContactTags(ctx context.Context) ([]map[string]any, error) {
+	return c.ResponseArray(ctx, "/api/2.0/crm/contact/tag.json")
+}
+
+// CreateContactTag creates a contact tag by name. Idempotent: "already exists" is OK.
+func (c *Client) CreateContactTag(ctx context.Context, tagName string) error {
+	fields := url.Values{}
+	fields.Set("tagName", tagName)
+	_, err := c.postFormObject(ctx, "/api/2.0/crm/contact/tag.json", fields)
+	if err != nil && strings.Contains(err.Error(), "already exists") {
+		return nil
+	}
+	return err
+}
+
+// AddContactTag attaches tagName to a contact.
+func (c *Client) AddContactTag(ctx context.Context, contactID, tagName string) error {
+	fields := url.Values{}
+	fields.Set("tagName", tagName)
+	_, err := c.postFormObject(ctx, fmt.Sprintf("/api/2.0/crm/contact/%s/tag.json", url.PathEscape(contactID)), fields)
+	return err
+}
+
+// RemoveContactTag removes tagName from a contact.
+func (c *Client) RemoveContactTag(ctx context.Context, contactID, tagName string) error {
+	fields := url.Values{}
+	fields.Set("tagName", tagName)
+	raw, err := c.deleteForm(ctx, fmt.Sprintf("/api/2.0/crm/contact/%s/tag.json", url.PathEscape(contactID)), fields)
+	if err != nil {
+		return err
+	}
+	_, err = unmarshalResponseObject(raw)
+	return err
+}
+
+// ListContactsByTag returns contacts filtered by a single CRM tag name.
+func (c *Client) ListContactsByTag(ctx context.Context, tagName string, count, startIndex int) ([]map[string]any, int, error) {
+	if count <= 0 {
+		count = 50
+	}
+	q := url.Values{}
+	q.Set("count", strconv.Itoa(count))
+	q.Set("startIndex", strconv.Itoa(startIndex))
+	q.Set("tags", tagName)
+	raw, err := c.getJSON(ctx, "/api/2.0/crm/contact/filter.json?"+q.Encode())
+	if err != nil {
+		return nil, 0, err
+	}
+	var env struct {
+		Response []map[string]any `json:"response"`
+		Total    int              `json:"total"`
+	}
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, 0, err
+	}
+	total := env.Total
+	if total == 0 && len(env.Response) > 0 {
+		total = len(env.Response)
+	}
+	return env.Response, total, nil
+}
+
 // ListAllContacts paginates through every CRM contact.
 func (c *Client) ListAllContacts(ctx context.Context) ([]map[string]any, error) {
 	const page = 100
@@ -491,11 +655,25 @@ func (c *Client) ListCRMTasks(ctx context.Context, count, startIndex int) ([]map
 }
 
 // CreateCRMTask creates a CRM task (reminder) attached to an entity.
+// Empty deadline defaults to now+14d (API requires a deadline). Empty
+// responsibleID falls back to the authenticated user — without this the
+// portal assigns a stub "Profile has been removed" owner.
 func (c *Client) CreateCRMTask(ctx context.Context, title, deadline string, categoryID, contactID int, entityType string, entityID int, description string) (map[string]any, error) {
+	if deadline == "" {
+		deadline = time.Now().Add(14 * 24 * time.Hour).Format("2006-01-02T15:04:05")
+	}
+	if categoryID == 0 {
+		categoryID = 2 // Opportunity (default CRM task category)
+	}
+	uid, err := c.SelfUserID(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("CreateCRMTask: resolve self: %w", err)
+	}
 	fields := url.Values{}
 	fields.Set("title", title)
 	fields.Set("deadline", deadline)
 	fields.Set("categoryId", strconv.Itoa(categoryID))
+	fields.Set("responsibleId", uid)
 	if contactID != 0 {
 		fields.Set("contactId", strconv.Itoa(contactID))
 	}
@@ -511,6 +689,29 @@ func (c *Client) CreateCRMTask(ctx context.Context, title, deadline string, cate
 	return c.postFormObject(ctx, "/api/2.0/crm/task.json", fields)
 }
 
+// UpdateCRMTask updates title, deadline, category, and responsible on a CRM task.
+// Empty responsibleID falls back to SelfUserID; empty deadline is left unchanged
+// by the API only if omitted — callers should pass deadLine when known.
+func (c *Client) UpdateCRMTask(ctx context.Context, id, title, deadline string, categoryID int, responsibleID string) (map[string]any, error) {
+	if responsibleID == "" {
+		uid, err := c.SelfUserID(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("UpdateCRMTask: resolve self: %w", err)
+		}
+		responsibleID = uid
+	}
+	fields := url.Values{}
+	fields.Set("title", title)
+	fields.Set("responsibleId", responsibleID)
+	if deadline != "" {
+		fields.Set("deadline", deadline)
+	}
+	if categoryID != 0 {
+		fields.Set("categoryId", strconv.Itoa(categoryID))
+	}
+	return c.putFormObject(ctx, fmt.Sprintf("/api/2.0/crm/task/%s.json", url.PathEscape(id)), fields)
+}
+
 // DeleteCRMTask removes a CRM task by id.
 func (c *Client) DeleteCRMTask(ctx context.Context, id string) (map[string]any, error) {
 	return c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/task/%s.json", url.PathEscape(id)))

crm_dedupe_plan.go

@@ -227,6 +227,11 @@ func GroupCompanyPersons(persons []map[string]any) map[int64]map[string][]map[st
 			continue
 		}
 		cid := flexInt(row["companyId"])
+		if cid == 0 {
+			if co, ok := row["company"].(map[string]any); ok {
+				cid = flexInt(co["id"])
+			}
+		}
 		if cid == 0 {
 			continue
 		}

crm_names.go

@@ -0,0 +1,172 @@
+package onlyoffice
+
+import (
+	"regexp"
+	"strings"
+	"unicode"
+)
+
+var (
+	parenSuffixRE  = regexp.MustCompile(`(?i)\s*[\(\[\{][^)\]\}]*[\)\]\}]\s*$`)
+	dashCompanyRE  = regexp.MustCompile(`(?i)\s+[-–—]\s+[A-Za-z0-9].*$`)
+	emailLocalRE   = regexp.MustCompile(`(?i)^[a-z0-9._%+\-]+@[a-z0-9.\-]+\.[a-z]{2,}$`)
+	nonNameTokenRE = regexp.MustCompile(`[^a-zA-ZÀ-öø-ÿĀ-ž0-9'’.\-]+`)
+)
+
+// CleanPersonNames strips company annotations from display names and fills
+// first/last from email local-part when the source used an address as the name.
+// Company affiliation belongs on CRM companyId — never in LastName.
+func CleanPersonNames(first, last, display, org string, emails []string) (cleanFirst, cleanLast string) {
+	first = strings.TrimSpace(first)
+	last = strings.TrimSpace(last)
+	display = strings.TrimSpace(display)
+	org = strings.TrimSpace(org)
+
+	if looksLikeEmail(first) {
+		ef, el := GuessNameFromEmail(first)
+		first, last = ef, el
+	}
+	if looksLikeEmail(display) && first == "" && last == "" {
+		display = ""
+	}
+
+	if first == "" && last == "" && display != "" {
+		first, last = SplitDisplayName(display)
+	}
+
+	first = stripCompanyAnnotation(first, org)
+	last = stripCompanyAnnotation(last, org)
+
+	last = stripCompanyAnnotation(last, org)
+	if i := strings.IndexAny(first, "(["); i > 0 {
+		first = strings.TrimSpace(first[:i])
+	}
+	if org != "" && personLastIsOrg(last, org) {
+		last = ""
+	}
+
+	if (first == "" || looksLikeEmail(first)) && len(emails) > 0 {
+		ef, el := GuessNameFromEmail(emails[0])
+		if first == "" || looksLikeEmail(first) {
+			first = ef
+		}
+		if last == "" || last == "-" {
+			last = el
+		}
+	}
+
+	first = strings.TrimSpace(first)
+	last = strings.TrimSpace(last)
+	if last == "" {
+		last = "-"
+	}
+	return first, last
+}
+
+func stripCompanyAnnotation(s, org string) string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return ""
+	}
+	s = parenSuffixRE.ReplaceAllString(s, "")
+	s = strings.TrimSpace(s)
+	s = dashCompanyRE.ReplaceAllString(s, "")
+	s = strings.TrimSpace(s)
+	if org != "" {
+		for _, sep := range []string{" - ", " – ", " — ", " / "} {
+			if i := strings.LastIndex(strings.ToLower(s), strings.ToLower(sep+org)); i >= 0 {
+				s = strings.TrimSpace(s[:i])
+			}
+		}
+		suf := " (" + org + ")"
+		if strings.HasSuffix(strings.ToLower(s), strings.ToLower(suf)) {
+			s = strings.TrimSpace(s[:len(s)-len(suf)])
+		}
+	}
+	return strings.TrimSpace(s)
+}
+
+func personLastIsOrg(last, org string) bool {
+	last = NormalizePersonNameKey(last)
+	org = NormalizePersonNameKey(org)
+	if last == "" || org == "" {
+		return false
+	}
+	if last == org {
+		return true
+	}
+	return strings.HasPrefix(org, last+" ") || strings.HasPrefix(org, last+",")
+}
+
+func looksLikeEmail(s string) bool {
+	return emailLocalRE.MatchString(strings.TrimSpace(s))
+}
+
+// GuessNameFromEmail turns local@domain into Title-Case first/last when the
+// local part looks like first.last / first_last / first-last.
+func GuessNameFromEmail(email string) (first, last string) {
+	email = NormalizeContactEmail(email)
+	local, _, ok := strings.Cut(email, "@")
+	if !ok || local == "" {
+		return "", ""
+	}
+	local = strings.Split(local, "+")[0]
+	parts := strings.FieldsFunc(local, func(r rune) bool {
+		return r == '.' || r == '_' || r == '-'
+	})
+	if len(parts) == 0 {
+		return titleNameToken(local), ""
+	}
+	if len(parts) == 1 {
+		return titleNameToken(parts[0]), ""
+	}
+	return titleNameToken(parts[0]), titleNameToken(strings.Join(parts[1:], " "))
+}
+
+func titleNameToken(s string) string {
+	s = nonNameTokenRE.ReplaceAllString(s, " ")
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return ""
+	}
+	runes := []rune(strings.ToLower(s))
+	runes[0] = unicode.ToTitle(runes[0])
+	return string(runes)
+}
+
+// FormatProjectTitle builds "CC | Company | Title" (spaces around |).
+// Country should be a short code (DE, TF, UA, …). Empty segments are dropped.
+func FormatProjectTitle(country, company, title string) string {
+	parts := make([]string, 0, 3)
+	for _, p := range []string{country, company, title} {
+		p = strings.TrimSpace(p)
+		p = strings.ReplaceAll(p, "|", "/")
+		if p != "" {
+			parts = append(parts, p)
+		}
+	}
+	return strings.Join(parts, " | ")
+}
+
+// NormalizeContactEmail lowercases and trims.
+func NormalizeContactEmail(s string) string {
+	return strings.ToLower(strings.TrimSpace(s))
+}
+
+// NormalizePersonNameKey collapses whitespace and lowercases for matching.
+func NormalizePersonNameKey(s string) string {
+	fields := strings.Fields(strings.ToLower(strings.TrimSpace(s)))
+	return strings.Join(fields, " ")
+}
+
+// SplitDisplayName splits "First Last …" into first/last (last = remainder).
+func SplitDisplayName(name string) (first, last string) {
+	parts := strings.Fields(strings.TrimSpace(name))
+	if len(parts) == 0 {
+		return "", ""
+	}
+	if len(parts) == 1 {
+		return parts[0], ""
+	}
+	return parts[0], strings.Join(parts[1:], " ")
+}

crm_names_test.go

@@ -0,0 +1,39 @@
+package onlyoffice
+
+import "testing"
+
+func TestCleanPersonNames_stripsCompanyParen(t *testing.T) {
+	f, l := CleanPersonNames("Jane", "Doe (Acme)", "Jane Doe (Acme)", "Acme", nil)
+	if f != "Jane" || l != "Doe" {
+		t.Fatalf("got %q %q", f, l)
+	}
+}
+
+func TestCleanPersonNames_stripsDashCompany(t *testing.T) {
+	f, l := CleanPersonNames("Jane", "Doe - Acme", "", "Acme", nil)
+	if f != "Jane" || l != "Doe" {
+		t.Fatalf("got %q %q", f, l)
+	}
+}
+
+func TestCleanPersonNames_fromEmail(t *testing.T) {
+	f, l := CleanPersonNames("jane.doe@example.com", "-", "", "Acme",
+		[]string{"jane.doe@example.com"})
+	if f != "Jane" || l != "Doe" {
+		t.Fatalf("got %q %q", f, l)
+	}
+}
+
+func TestCleanPersonNames_lastIsCompany(t *testing.T) {
+	f, l := CleanPersonNames("Jane", "Acme", "", "Acme GmbH & Co. KG", nil)
+	if f != "Jane" || l != "-" {
+		t.Fatalf("got %q %q", f, l)
+	}
+}
+
+func TestFormatProjectTitle(t *testing.T) {
+	got := FormatProjectTitle("DE", "Acme", "Map App")
+	if got != "DE | Acme | Map App" {
+		t.Fatalf("got %q", got)
+	}
+}

crm_normalize.go

@@ -10,6 +10,9 @@ var multiSpace = regexp.MustCompile(`\s+`)
 // sloganSeparators split a company name from a trailing tagline/slogan.
 var sloganSeparators = []string{" — ", " – ", " - ", "—", "–"}
 
+// companyLegalSuffix matches trailing legal-form tokens (GmbH, & Co. KG, …).
+var companyLegalSuffix = regexp.MustCompile(`(?i)[\s,]*(&\s*co\.?\s*kg\.?|co\.?\s*kg\.?|gmbh|ag|ltd\.?|llc\.?|inc\.?|plc\.?|s\.?l\.?|sarl|b\.?v\.?)\s*$`)
+
 // StripSloganSuffix returns the part before an em/en dash tagline, e.g.
 // "Affirm — Fraud Engineering" → "Affirm".
 func StripSloganSuffix(s string) string {
@@ -22,9 +25,23 @@ func StripSloganSuffix(s string) string {
 	return s
 }
 
-// CompanyGroupingKey normalizes a company name for dedupe (ignores slogans).
+// StripCompanyLegalSuffix removes trailing GmbH / & Co. KG / Ltd / … tokens.
+func StripCompanyLegalSuffix(s string) string {
+	s = strings.TrimSpace(s)
+	s = strings.TrimRight(s, ",; ")
+	for {
+		next := companyLegalSuffix.ReplaceAllString(s, "")
+		next = strings.TrimRight(strings.TrimSpace(next), ",; ")
+		if next == s || next == "" {
+			return s
+		}
+		s = next
+	}
+}
+
+// CompanyGroupingKey normalizes a company name for dedupe (ignores slogans and legal suffixes).
 func CompanyGroupingKey(s string) string {
-	return NormalizeCompanyName(StripSloganSuffix(s))
+	return NormalizeCompanyName(StripCompanyLegalSuffix(StripSloganSuffix(s)))
 }
 
 // NormalizeCompanyName lowercases and collapses whitespace for grouping.
@@ -52,7 +69,7 @@ func StripCompanySuffix(title string) string {
 }
 
 // FixDealTitle strips a leading @, normalizes separator spacing, and collapses
-// empty-position titles like " @ contoso" to "contoso".
+// empty-position titles like " @ Acme" to "Acme".
 func FixDealTitle(s string) string {
 	s = strings.TrimSpace(s)
 	for strings.HasPrefix(s, "@") {
@@ -75,8 +92,53 @@ func FixDealTitle(s string) string {
 }
 
 // ContactInfoKey groups contact info rows by type and normalized value.
+// ContactInfoKey builds a dedupe key for a contact-info row.
 func ContactInfoKey(infoType, value string) string {
-	return strings.ToLower(strings.TrimSpace(infoType)) + "|" + strings.ToLower(strings.TrimSpace(value))
+	return NormalizeContactInfoType(infoType) + "|" + strings.ToLower(strings.TrimSpace(value))
+}
+
+// NormalizeContactInfoType maps OO numeric infoType codes and string labels to
+// a canonical lowercase label (email, phone, …).
+func NormalizeContactInfoType(infoType string) string {
+	t := strings.ToLower(strings.TrimSpace(infoType))
+	switch t {
+	case "1", "email":
+		return "email"
+	case "2", "phone":
+		return "phone"
+	case "3", "website":
+		return "website"
+	case "4", "skype":
+		return "skype"
+	case "5", "twitter":
+		return "twitter"
+	case "6", "linkedin":
+		return "linkedin"
+	case "7", "facebook":
+		return "facebook"
+	case "8", "address":
+		return "address"
+	case "9", "livejournal":
+		return "livejournal"
+	case "10", "myspace":
+		return "myspace"
+	case "11", "gmail":
+		return "gmail"
+	case "12", "blogger":
+		return "blogger"
+	case "13", "yahoo":
+		return "yahoo"
+	case "14", "msn":
+		return "msn"
+	case "15", "icq":
+		return "icq"
+	case "16", "jabber":
+		return "jabber"
+	case "17", "aim":
+		return "aim"
+	default:
+		return t
+	}
 }
 
 // MemberDisplayKey normalizes a member displayName for duplicate detection.

crm_normalize_test.go

@@ -65,6 +65,10 @@ func TestCompanyGroupingKey(t *testing.T) {
 	if a != b {
 		t.Fatalf("%q != %q", a, b)
 	}
+	if CompanyGroupingKey("Acme") != CompanyGroupingKey("Acme GmbH & Co. KG,") {
+		t.Fatalf("legal suffix should not change grouping key: %q vs %q",
+			CompanyGroupingKey("Acme"), CompanyGroupingKey("Acme GmbH & Co. KG,"))
+	}
 }
 
 func TestOpportunityTitlesMatchSlogan(t *testing.T) {

docs/crm-associations.md

@@ -0,0 +1,124 @@
+# CRM associations (company ↔ person ↔ deal ↔ project ↔ invoice ↔ mail)
+
+Operational rules for the `oo` CLI and this library. Business SSOT remains
+OnlyOffice Workspace CRM + Projects.
+
+## Canonical graph
+
+One **legal company** owns the relationship. Do not invent a second “bill-to”
+company just for PDF layout.
+
+```text
+Company
+├── Person (buyer contact)          oo persons create --company-id
+├── Opportunity / Deal              oo opportunities … ; member-add company + person
+├── Project (hub)                   oo projects … ; contacts add company + person
+│     └── Epic + subtasks
+└── Invoice (Draft → …)             oo invoices create --contact COMPANY --opportunity DEAL
+      └── PDF file                  oo invoices pdf ID
+            └── Mail draft          oo mails draft-invoice --invoice ID --to …
+```
+
+| Layer | CLI | Must link |
+|-------|-----|-----------|
+| Company | `oo companies create` | website, email, phone, **one** Billing address |
+| Person | `oo persons create --company-id` / `oo persons update ID` | job title; never encode employer in `lastName`; **update uses JSON** (form PUT ignores `companyId`/`about`) |
+| Deal | `oo opportunities create` + `member-add` | company **and** person as members |
+| Project | `oo projects create` + `contacts add` | same company + person |
+| Invoice | `oo invoices create --contact COMPANY --opportunity DEAL` | `entityId` at **create** |
+| Mail | `oo mails draft-invoice` | attach current PDF; **do not send** until confirmed |
+
+UI checks (same company card):
+
+- `#contacts` → person  
+- `#deals` → opportunity  
+- `#projects` → hub project  
+- `#invoices` on the **deal** → invoice (needs `entity`)  
+- `#files` → preferably **one** current invoice PDF
+
+**Project Team ≠ Project Contacts.** Team = portal users. CRM people/companies
+show under the project **Contacts** tab (`oo projects contacts list`).
+
+## Hard rules
+
+1. **One company per legal entity.** Duplicate “bill-to” contacts empty Deals /
+   Projects / Contacts tabs and break merge. Prefer
+   `oo contacts merge FROM INTO` (keeps `INTO`) or `oo companies dedupe`.
+2. **Link invoice → deal at create.**  
+   `POST /crm/invoice` with `entityId` + `entityType: 0` (Opportunity).  
+   `oo invoices update … --opportunity` often returns **400**
+   (“Value does not fall within the expected range”). If the link is missing,
+   delete the Draft and recreate with `--opportunity`.
+3. **Bill To = company id**, not a throwaway contact. Person stays under the
+   company (`companyId`). Optional `consigneeId` for Empfänger when the portal
+   template prints it.
+4. **Stay Draft until mail is ready.** Billed (`status id=2`) is **not editable**
+   via content PUT. Going Billed → Draft via `…/crm/invoice/status/1` usually
+   **does not work** — delete + recreate Draft instead.
+5. **Do not regenerate PDF in a loop** without cleanup. Each
+   `GET …/crm/invoice/{id}/pdf` attaches a new file to the company (and often
+   the deal). Keep `invoice.fileID`; delete older PDFs with
+   `oo invoices pdf-cleanup ID` / Documents `fileops/delete`.
+
+## Invoice PDF quirks
+
+| Symptom | Workaround |
+|---------|------------|
+| Cached / stale PDF | Touch invoice (Draft PUT that clears `fileID`), then `GET …/pdf` — `oo invoices pdf ID --force` |
+| Billing address missing on **new** PDFs | Temporary multiline `companyName` (`Line1\nLine2\n…`) on the **canonical** company → force PDF → restore clean name. Cached `fileID` keeps the multiline Bill To. |
+| Separate bill-to company for newlines | **Forbidden** — merge back to the real company |
+| Invoice **number** won’t change on PUT | Delete Draft and recreate with the desired number |
+| Notizen / Bedingungen spacing | Leading `\n` and blank lines only — no HTML (tags print literally) |
+| Issuer street lines | Organisation profile address (`street` with `\n`), not only terms |
+
+Status ids commonly used: `1` Draft, `2` Billed, `3` Rejected, `4` Paid.
+
+## Mail quirks
+
+| Symptom | Workaround |
+|---------|------------|
+| Signature / body doubles chat URL | Put chat in **one** place only. UI drafts: signature. API send: body (API **does not** append signature). |
+| Signature / body cuts URL at `#` | Plain text URLs — avoid `<a href="…#…">` (or encode `#` as `%23` in href) |
+| German letter spacing | Blank `<p>&nbsp;</p>` between blocks (`MailHTMLWithBlankParagraphs`) |
+| Send | `PUT /api/2.0/mail/messages/send.json` with `id/from/to/subject/body`; omit empty `cc`/`bcc`. Never auto-send; draft only until the human confirms |
+
+Prefer OnlyOffice Mail (`/addons/mail/#drafts`) for invoice delivery until confirmed.
+
+## Project / task quirks
+
+- Hub title: `CC | Company` (e.g. `DE | Acme GmbH`).
+- Streams = epics/tasks under the hub, not a third title segment (unless the
+  project itself is a named delivery stream).
+- Closing a **subtask**:  
+  `PUT /api/2.0/project/task/{epicId}/{subtaskId}/status` with `status=2`.  
+  `oo tasks update SUBTASK -s closed` returns **404** for subtasks.
+- After deleting a CRM contact, `GET /project/contact/{deletedId}` may still
+  return projects (ghost). Official project contact list should only show live
+  ids; unlink may 400 if the contact is gone.
+
+## Merge / cleanup cheat sheet
+
+```bash
+# Keep the preferred company (INTO), drop the duplicate (FROM)
+oo contacts merge FROM_ID INTO_ID
+
+# Or by normalized name (careful — whole CRM)
+oo companies dedupe
+
+# Invoice ↔ deal must exist at create
+oo invoices create --number P-YYYY-NN --contact COMPANY_ID --item ITEM_ID \
+  --price 300 --opportunity DEAL_ID --language de-DE …
+
+# Fresh PDF + prune older PDFs on company/deal
+oo invoices pdf INVOICE_ID --force
+oo invoices pdf-cleanup INVOICE_ID
+
+# Mail draft (no send)
+oo mails draft-invoice --invoice INVOICE_ID --to billing@example.com
+```
+
+## Related
+
+- README § invoices / mail / CRM cleanup  
+- Personal workspace tooling (disk inventory, dossier sync): private
+  `git.produktor.io/eSlider/oo-workspace` (`oow` CLI)

go.mod

@@ -39,8 +39,8 @@ require (
 	github.com/yuin/goldmark v1.8.2 // indirect
 	github.com/yuin/goldmark-emoji v1.0.3 // indirect
 	golang.org/x/net v0.55.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
-	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
 	golang.org/x/term v0.43.0 // indirect
 	golang.org/x/text v0.37.0 // indirect
 )

go.sum

@@ -89,11 +89,11 @@ github.com/yuin/goldmark-emoji v1.0.3/go.mod h1:tTkZEbwu5wkPmgTcitqddVxY9osFZiav
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
 golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
-golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
 golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=

http.go

@@ -181,6 +181,11 @@ func (c *Client) putForm(ctx context.Context, path string, fields url.Values) (j
 	return c.formRequest(ctx, http.MethodPut, path, fields)
 }
 
+// deleteForm issues an authenticated DELETE with application/x-www-form-urlencoded body.
+func (c *Client) deleteForm(ctx context.Context, path string, fields url.Values) (json.RawMessage, error) {
+	return c.formRequest(ctx, http.MethodDelete, path, fields)
+}
+
 func (c *Client) formRequest(ctx context.Context, method, path string, fields url.Values) (json.RawMessage, error) {
 	auth, err := c.authHeader()
 	if err != nil {
@@ -244,6 +249,58 @@ func (c *Client) putJSONObject(ctx context.Context, path string, body any) (map[
 	return unmarshalResponseObject(raw)
 }
 
+// postJSONObject issues an authenticated POST with JSON body and decodes response.
+func (c *Client) postJSONObject(ctx context.Context, path string, body any) (map[string]any, error) {
+	raw, err := c.postJSON(ctx, path, body)
+	if err != nil {
+		return nil, err
+	}
+	return unmarshalResponseObject(raw)
+}
+
+// postJSON issues an authenticated POST with application/json body.
+func (c *Client) postJSON(ctx context.Context, path string, body any) (json.RawMessage, error) {
+	auth, err := c.authHeader()
+	if err != nil {
+		return nil, err
+	}
+	var rdr io.Reader
+	switch b := body.(type) {
+	case nil:
+		rdr = strings.NewReader("{}")
+	case []byte:
+		rdr = bytes.NewReader(b)
+	case string:
+		rdr = strings.NewReader(b)
+	default:
+		buf, err := json.Marshal(b)
+		if err != nil {
+			return nil, err
+		}
+		rdr = bytes.NewReader(buf)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL()+path, rdr)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", auth)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("POST JSON %s: %d %s", path, resp.StatusCode, truncate(string(raw), 400))
+	}
+	return raw, nil
+}
+
 // putJSON issues an authenticated PUT with application/json body.
 func (c *Client) putJSON(ctx context.Context, path string, body any) (json.RawMessage, error) {
 	auth, err := c.authHeader()

invoices.go

@@ -0,0 +1,545 @@
+package onlyoffice
+
+// CRM Invoices and invoice catalog items (billing).
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"strconv"
+	"strings"
+)
+
+// InvoiceLine is one line on a create-invoice request.
+type InvoiceLine struct {
+	InvoiceItemID int64   `json:"invoiceItemID"`
+	InvoiceTax1ID int64   `json:"invoiceTax1ID"`
+	InvoiceTax2ID int64   `json:"invoiceTax2ID"`
+	Description   string  `json:"description"`
+	Quantity      float64 `json:"quantity"`
+	Price         float64 `json:"price"`
+	Discount      float64 `json:"discount"`
+	SortOrder     int     `json:"sortOrder"`
+}
+
+// CreateInvoiceParams holds fields for POST /api/2.0/crm/invoice.
+type CreateInvoiceParams struct {
+	Number              string
+	IssueDate           string // ISO-8601
+	DueDate             string // ISO-8601
+	ContactID           int64
+	ConsigneeID         int64 // 0 = omit
+	EntityID            int64 // 0 = omit; link to opportunity/case
+	EntityType          int   // OnlyOffice EntityType; 0 = Opportunity
+	Language            string
+	Currency            string
+	ExchangeRate        float64
+	PurchaseOrderNumber string
+	Terms               string
+	Description         string
+	TemplateType        int
+	Lines               []InvoiceLine
+}
+
+// ListInvoices returns a page of CRM invoices and the total count.
+func (c *Client) ListInvoices(ctx context.Context, count, startIndex int) ([]map[string]any, int, error) {
+	q := url.Values{}
+	q.Set("count", strconv.Itoa(count))
+	q.Set("startIndex", strconv.Itoa(startIndex))
+	raw, err := c.getJSON(ctx, "/api/2.0/crm/invoice/filter.json?"+q.Encode())
+	if err != nil {
+		return nil, 0, err
+	}
+	var env struct {
+		Response []map[string]any `json:"response"`
+		Total    int              `json:"total"`
+	}
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, 0, err
+	}
+	total := env.Total
+	if total == 0 && len(env.Response) > 0 {
+		total = len(env.Response)
+	}
+	return env.Response, total, nil
+}
+
+// GetInvoice returns a single invoice by id (includes invoiceLines).
+func (c *Client) GetInvoice(ctx context.Context, id string) (map[string]any, error) {
+	return c.ResponseObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s.json", url.PathEscape(id)))
+}
+
+// CreateInvoice creates a draft invoice with the given lines.
+func (c *Client) CreateInvoice(ctx context.Context, p CreateInvoiceParams) (map[string]any, error) {
+	if p.ContactID == 0 {
+		return nil, fmt.Errorf("contactId is required")
+	}
+	if p.Number == "" {
+		return nil, fmt.Errorf("number is required")
+	}
+	if len(p.Lines) == 0 {
+		return nil, fmt.Errorf("at least one invoice line is required")
+	}
+	if p.Language == "" {
+		p.Language = "de-DE"
+	}
+	if p.Currency == "" {
+		p.Currency = "EUR"
+	}
+	if p.ExchangeRate == 0 {
+		p.ExchangeRate = 1
+	}
+	body := map[string]any{
+		"number":              p.Number,
+		"issueDate":           p.IssueDate,
+		"dueDate":             p.DueDate,
+		"contactId":           p.ContactID,
+		"language":            p.Language,
+		"currency":            p.Currency,
+		"exchangeRate":        p.ExchangeRate,
+		"purchaseOrderNumber": p.PurchaseOrderNumber,
+		"terms":               p.Terms,
+		"description":         p.Description,
+		"templateType":        p.TemplateType,
+		"invoiceLines":        p.Lines,
+	}
+	if p.ConsigneeID != 0 {
+		body["consigneeId"] = p.ConsigneeID
+	}
+	if p.EntityID != 0 {
+		body["entityId"] = p.EntityID
+		body["entityType"] = p.EntityType // 0 = Opportunity on this portal
+	}
+	return c.postJSONObject(ctx, "/api/2.0/crm/invoice", body)
+}
+
+// UpdateInvoiceParams are fields for PUT /api/2.0/crm/invoice/{id}.
+// Loads the current invoice and merges non-zero / set fields.
+type UpdateInvoiceParams struct {
+	EntityID         int64 // link to opportunity; 0 = leave unchanged
+	EntityType       int
+	ContactID        int64  // 0 = leave unchanged
+	Description      string // invoice notes; empty + DescriptionSet=false keeps existing
+	DescriptionSet   bool
+	PurchaseOrder    string
+	PurchaseOrderSet bool
+	Terms            string
+	TermsSet         bool
+}
+
+// UpdateInvoice PUTs a full invoice body (OnlyOffice requires complete payload).
+//
+// Linking an opportunity via EntityID on an existing invoice often returns HTTP 400
+// on this portal — prefer CreateInvoice with EntityID set. See docs/crm-associations.md.
+func (c *Client) UpdateInvoice(ctx context.Context, id string, p UpdateInvoiceParams) (map[string]any, error) {
+	inv, err := c.GetInvoice(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	contactID := int64(0)
+	if m, ok := inv["contact"].(map[string]any); ok {
+		contactID = flexInt(m["id"])
+	}
+	if p.ContactID != 0 {
+		contactID = p.ContactID
+	}
+	cur := "EUR"
+	if m, ok := inv["currency"].(map[string]any); ok {
+		if a := stringField(m, "abbreviation"); a != "" {
+			cur = a
+		}
+	}
+	statusID := 1
+	if m, ok := inv["status"].(map[string]any); ok {
+		statusID = int(flexInt(m["id"]))
+	}
+	var lines []map[string]any
+	switch raw := inv["invoiceLines"].(type) {
+	case []any:
+		for _, row := range raw {
+			m, ok := row.(map[string]any)
+			if !ok {
+				continue
+			}
+			lines = append(lines, map[string]any{
+				"id":            flexInt(m["id"]),
+				"invoiceItemID": flexInt(m["invoiceItemID"]),
+				"invoiceTax1ID": flexInt(m["invoiceTax1ID"]),
+				"invoiceTax2ID": flexInt(m["invoiceTax2ID"]),
+				"description":   stringField(m, "description"),
+				"quantity":      floatField(m, "quantity"),
+				"price":         floatField(m, "price"),
+				"discount":      floatField(m, "discount"),
+				"sortOrder":     int(flexInt(m["sortOrder"])),
+			})
+		}
+	case []map[string]any:
+		for _, m := range raw {
+			lines = append(lines, map[string]any{
+				"id":            flexInt(m["id"]),
+				"invoiceItemID": flexInt(m["invoiceItemID"]),
+				"invoiceTax1ID": flexInt(m["invoiceTax1ID"]),
+				"invoiceTax2ID": flexInt(m["invoiceTax2ID"]),
+				"description":   stringField(m, "description"),
+				"quantity":      floatField(m, "quantity"),
+				"price":         floatField(m, "price"),
+				"discount":      floatField(m, "discount"),
+				"sortOrder":     int(flexInt(m["sortOrder"])),
+			})
+		}
+	}
+	body := map[string]any{
+		"id":                  flexInt(inv["id"]),
+		"number":              stringField(inv, "number"),
+		"issueDate":           stringField(inv, "issueDate"),
+		"dueDate":             stringField(inv, "dueDate"),
+		"contactId":           contactID,
+		"language":            stringField(inv, "language"),
+		"currency":            cur,
+		"exchangeRate":        floatField(inv, "exchangeRate"),
+		"purchaseOrderNumber": stringField(inv, "purchaseOrderNumber"),
+		"terms":               stringField(inv, "terms"),
+		"description":         stringField(inv, "description"),
+		"templateType":        int(flexInt(inv["templateType"])),
+		"status":              statusID,
+		"invoiceLines":        lines,
+	}
+	if p.DescriptionSet {
+		body["description"] = p.Description
+	}
+	if p.PurchaseOrderSet {
+		body["purchaseOrderNumber"] = p.PurchaseOrder
+	}
+	if p.TermsSet {
+		body["terms"] = p.Terms
+	}
+	if p.EntityID != 0 {
+		body["entityId"] = p.EntityID
+		body["entityType"] = p.EntityType
+	} else if ent, ok := inv["entity"].(map[string]any); ok && ent != nil {
+		body["entityId"] = flexInt(ent["entityId"])
+		// API returns entityType as string ("opportunity"); create/update want int.
+		switch v := ent["entityType"].(type) {
+		case float64:
+			body["entityType"] = int(v)
+		case int:
+			body["entityType"] = v
+		case string:
+			if strings.EqualFold(v, "opportunity") {
+				body["entityType"] = 0
+			}
+		}
+	}
+	return c.putJSONObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s", url.PathEscape(id)), body)
+}
+
+// DeleteInvoice removes an invoice by id.
+func (c *Client) DeleteInvoice(ctx context.Context, id string) (map[string]any, error) {
+	return c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s.json", url.PathEscape(id)))
+}
+
+// Invoice status ids used by OnlyOffice CRM.
+const (
+	InvoiceStatusDraft    = 1
+	InvoiceStatusBilled   = 2
+	InvoiceStatusRejected = 3
+	InvoiceStatusPaid     = 4
+)
+
+// SetInvoiceStatus sets CRM invoice status for one or more invoice ids
+// (PUT /api/2.0/crm/invoice/status/{statusId} with invoiceids).
+// Note: Billed→Draft often does not stick; recreate Draft instead (see docs/crm-associations.md).
+func (c *Client) SetInvoiceStatus(ctx context.Context, statusID int, invoiceIDs ...int64) (map[string]any, error) {
+	if statusID <= 0 {
+		return nil, fmt.Errorf("status id is required")
+	}
+	if len(invoiceIDs) == 0 {
+		return nil, fmt.Errorf("at least one invoice id is required")
+	}
+	ids := make([]string, 0, len(invoiceIDs))
+	for _, id := range invoiceIDs {
+		ids = append(ids, strconv.FormatInt(id, 10))
+	}
+	fields := url.Values{}
+	fields.Set("invoiceids", strings.Join(ids, ","))
+	return c.putFormObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/status/%d", statusID), fields)
+}
+
+// InvoicePDFFile returns invoice PDF file metadata (id, title, viewUrl).
+// Without force, OnlyOffice may return a cached fileID with stale layout.
+func (c *Client) InvoicePDFFile(ctx context.Context, invoiceID string) (map[string]any, error) {
+	id := strings.TrimSpace(invoiceID)
+	if id == "" {
+		return nil, fmt.Errorf("InvoicePDFFile: invoice id is required")
+	}
+	return c.ResponseObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s/pdf", url.PathEscape(id)))
+}
+
+// ForceRegenerateInvoicePDF clears the cached PDF (Draft touch) then requests a new file.
+// No-op touch when the invoice is not editable (e.g. Billed) — falls back to GET /pdf.
+func (c *Client) ForceRegenerateInvoicePDF(ctx context.Context, invoiceID string) (map[string]any, error) {
+	id := strings.TrimSpace(invoiceID)
+	if id == "" {
+		return nil, fmt.Errorf("ForceRegenerateInvoicePDF: invoice id is required")
+	}
+	inv, err := c.GetInvoice(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	canEdit := true
+	if v, ok := inv["canEdit"].(bool); ok {
+		canEdit = v
+	}
+	if canEdit {
+		desc := stringField(inv, "description")
+		// Append/remove a trailing space so PUT clears fileID without visible change.
+		touch := desc + " "
+		if strings.HasSuffix(desc, " ") {
+			touch = strings.TrimSuffix(desc, " ")
+		}
+		if _, err := c.UpdateInvoice(ctx, id, UpdateInvoiceParams{
+			Description:    touch,
+			DescriptionSet: true,
+		}); err != nil {
+			return nil, fmt.Errorf("ForceRegenerateInvoicePDF: clear cache: %w", err)
+		}
+	}
+	return c.InvoicePDFFile(ctx, id)
+}
+
+// ListCRMContactFiles lists Documents attached on a CRM contact card (#files).
+func (c *Client) ListCRMContactFiles(ctx context.Context, contactID string) ([]map[string]any, error) {
+	return c.ResponseArray(ctx, fmt.Sprintf("/api/2.0/crm/contact/%s/files.json", url.PathEscape(contactID)))
+}
+
+// ListOpportunityFiles lists Documents attached on a CRM opportunity.
+func (c *Client) ListOpportunityFiles(ctx context.Context, opportunityID string) ([]map[string]any, error) {
+	return c.ResponseArray(ctx, fmt.Sprintf("/api/2.0/crm/opportunity/%s/files.json", url.PathEscape(opportunityID)))
+}
+
+// PurgeStaleInvoicePDFs deletes older P-*.pdf copies on the invoice contact (and linked
+// opportunity) while keeping the invoice's current fileID. Returns deleted file ids.
+func (c *Client) PurgeStaleInvoicePDFs(ctx context.Context, invoiceID string) ([]int, error) {
+	inv, err := c.GetInvoice(ctx, invoiceID)
+	if err != nil {
+		return nil, err
+	}
+	keep := flexInt(inv["fileID"])
+	number := strings.TrimSpace(stringField(inv, "number"))
+	base := number
+	for strings.HasSuffix(base, "b") || strings.HasSuffix(base, "B") {
+		base = base[:len(base)-1]
+	}
+	if base == "" {
+		base = "P-"
+	}
+
+	seen := map[int]struct{}{}
+	var candidates []int
+	addFiles := func(files []map[string]any) {
+		for _, f := range files {
+			title := stringField(f, "title")
+			id := int(flexInt(f["id"]))
+			if id == 0 || id == int(keep) {
+				continue
+			}
+			if !strings.HasPrefix(title, "P-") {
+				continue
+			}
+			if !strings.HasPrefix(title, base) {
+				continue
+			}
+			if _, ok := seen[id]; ok {
+				continue
+			}
+			seen[id] = struct{}{}
+			candidates = append(candidates, id)
+		}
+	}
+
+	if m, ok := inv["contact"].(map[string]any); ok {
+		cid := strconv.FormatInt(flexInt(m["id"]), 10)
+		if cid != "0" {
+			files, err := c.ListCRMContactFiles(ctx, cid)
+			if err != nil {
+				return nil, err
+			}
+			addFiles(files)
+		}
+	}
+	if ent, ok := inv["entity"].(map[string]any); ok && ent != nil {
+		if strings.EqualFold(fmt.Sprint(ent["entityType"]), "opportunity") || flexInt(ent["entityType"]) == 0 {
+			oid := strconv.FormatInt(flexInt(ent["entityId"]), 10)
+			if oid != "0" {
+				files, err := c.ListOpportunityFiles(ctx, oid)
+				if err != nil {
+					return nil, err
+				}
+				addFiles(files)
+			}
+		}
+	}
+
+	if len(candidates) == 0 {
+		return nil, nil
+	}
+	if err := c.DeleteFiles(ctx, candidates); err != nil {
+		return nil, err
+	}
+	// CRM may still list deleted files briefly; also try CRM unlink.
+	for _, fid := range candidates {
+		_, _ = c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/files/%d.json", fid))
+	}
+	return candidates, nil
+}
+
+// ListInvoiceItems returns catalog invoice items.
+func (c *Client) ListInvoiceItems(ctx context.Context, count, startIndex int) ([]map[string]any, int, error) {
+	q := url.Values{}
+	q.Set("count", strconv.Itoa(count))
+	q.Set("startIndex", strconv.Itoa(startIndex))
+	raw, err := c.getJSON(ctx, "/api/2.0/crm/invoiceitem/filter.json?"+q.Encode())
+	if err != nil {
+		return nil, 0, err
+	}
+	var env struct {
+		Response []map[string]any `json:"response"`
+		Total    int              `json:"total"`
+	}
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, 0, err
+	}
+	total := env.Total
+	if total == 0 && len(env.Response) > 0 {
+		total = len(env.Response)
+	}
+	return env.Response, total, nil
+}
+
+// CreateInvoiceItem creates a reusable catalog line item.
+func (c *Client) CreateInvoiceItem(ctx context.Context, title, description string, price float64, currency string) (map[string]any, error) {
+	if title == "" {
+		return nil, fmt.Errorf("title is required")
+	}
+	if currency == "" {
+		currency = "EUR"
+	}
+	fields := url.Values{}
+	fields.Set("title", title)
+	fields.Set("description", description)
+	fields.Set("price", strconv.FormatFloat(price, 'f', 2, 64))
+	fields.Set("currency", currency)
+	fields.Set("stockKeepingUnit", "")
+	fields.Set("trackInventory", "false")
+	fields.Set("quantity", "0")
+	fields.Set("invoiceTax1ID", "0")
+	fields.Set("invoiceTax2ID", "0")
+	return c.postFormObject(ctx, "/api/2.0/crm/invoiceitem", fields)
+}
+
+// DeleteInvoiceItem removes a catalog invoice item.
+func (c *Client) DeleteInvoiceItem(ctx context.Context, id string) (map[string]any, error) {
+	return c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/invoiceitem/%s.json", url.PathEscape(id)))
+}
+
+// AddContactAddress attaches a postal address to a contact.
+// category: Home|Postal|Office|Billing|Other|Work (or numeric string).
+func (c *Client) AddContactAddress(ctx context.Context, contactID, street, city, state, zip, country, category string, isPrimary bool) (map[string]any, error) {
+	if category == "" {
+		category = "Billing"
+	}
+	fields := url.Values{}
+	fields.Set("street", street)
+	fields.Set("city", city)
+	fields.Set("state", state)
+	fields.Set("zip", zip)
+	fields.Set("country", country)
+	fields.Set("category", category)
+	fields.Set("isPrimary", strconv.FormatBool(isPrimary))
+	return c.postFormObject(ctx, fmt.Sprintf("/api/2.0/crm/contact/%s/address", url.PathEscape(contactID)), fields)
+}
+
+// UpdateCompany updates company name and optional about text.
+func (c *Client) UpdateCompany(ctx context.Context, companyID, name, about string) (map[string]any, error) {
+	fields := url.Values{}
+	fields.Set("companyName", name)
+	if about != "" {
+		fields.Set("about", about)
+	}
+	return c.putFormObject(ctx, fmt.Sprintf("/api/2.0/crm/contact/company/%s.json", url.PathEscape(companyID)), fields)
+}
+
+// UpdateOpportunityParams are optional fields for UpdateOpportunity.
+// Zero/empty values mean "keep existing" except BidValueSet.
+type UpdateOpportunityParams struct {
+	Title       string
+	Description string
+	StageID     int64
+	BidValue    float64
+	BidValueSet bool
+}
+
+// UpdateOpportunity loads a deal and PUTs updated fields.
+func (c *Client) UpdateOpportunity(ctx context.Context, id string, p UpdateOpportunityParams) (map[string]any, error) {
+	opp, err := c.GetOpportunity(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	title := p.Title
+	if title == "" {
+		title = stringField(opp, "title")
+	}
+	body := opportunityUpdateBody(opp, title)
+	if p.Description != "" {
+		body["description"] = p.Description
+	}
+	if p.StageID != 0 {
+		body["stageid"] = p.StageID
+	}
+	if p.BidValueSet {
+		body["bidValue"] = p.BidValue
+	}
+	return c.putJSONObject(ctx, fmt.Sprintf("/api/2.0/crm/opportunity/%s.json", url.PathEscape(id)), body)
+}
+
+// InvoiceContactName extracts displayName from nested contact on an invoice row.
+func InvoiceContactName(inv map[string]any) string {
+	if m, ok := inv["contact"].(map[string]any); ok {
+		return stringField(m, "displayName")
+	}
+	return ""
+}
+
+// InvoiceStatusTitle extracts status.title from an invoice row.
+func InvoiceStatusTitle(inv map[string]any) string {
+	if m, ok := inv["status"].(map[string]any); ok {
+		return stringField(m, "title")
+	}
+	return ""
+}
+
+// FlattenInvoiceRow copies nested fields for table output.
+func FlattenInvoiceRow(inv map[string]any) map[string]any {
+	out := map[string]any{}
+	for k, v := range inv {
+		out[k] = v
+	}
+	out["contactName"] = InvoiceContactName(inv)
+	out["statusTitle"] = InvoiceStatusTitle(inv)
+	if cur, ok := inv["currency"].(map[string]any); ok {
+		out["currency"] = stringField(cur, "abbreviation")
+	}
+	return out
+}
+
+// FindInvoiceItemByTitle returns the first catalog item with an exact title match.
+func FindInvoiceItemByTitle(items []map[string]any, title string) map[string]any {
+	want := strings.TrimSpace(title)
+	for _, it := range items {
+		if strings.TrimSpace(stringField(it, "title")) == want {
+			return it
+		}
+	}
+	return nil
+}

mails.go

@@ -5,6 +5,7 @@ package onlyoffice
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"net/mail"
 	"net/url"
@@ -96,11 +97,157 @@ func (c *Client) GetMailMessage(ctx context.Context, messageID string) (map[stri
 }
 
 // RemoveMailMessages deletes messages by id (PUT /api/2.0/mail/messages/remove).
+// The API response "response" field may be a number or object; success is HTTP 2xx.
 func (c *Client) RemoveMailMessages(ctx context.Context, ids ...int) (map[string]any, error) {
 	if len(ids) == 0 {
 		return nil, fmt.Errorf("RemoveMailMessages: at least one id is required")
 	}
-	return c.putJSONObject(ctx, "/api/2.0/mail/messages/remove", map[string]any{"ids": ids})
+	raw, err := c.putJSON(ctx, "/api/2.0/mail/messages/remove", map[string]any{"ids": ids})
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]any{"ok": true, "ids": ids}
+	if resp, err := responseField(raw, "response"); err == nil {
+		var n json.Number
+		if json.Unmarshal(resp, &n) == nil {
+			out["response"] = n.String()
+		} else {
+			var m map[string]any
+			if json.Unmarshal(resp, &m) == nil {
+				out["response"] = m
+			} else {
+				out["response"] = string(resp)
+			}
+		}
+	}
+	return out, nil
+}
+
+// SaveMailDraftParams creates or updates a draft via PUT /api/2.0/mail/drafts/save.
+// Id 0 creates a new draft. Body is HTML; the API field name is "body" (not htmlBody).
+type SaveMailDraftParams struct {
+	ID      int64  // 0 = create
+	From    string // mailbox address, e.g. eslider@gmail.com
+	To      string // comma-separated or single address
+	Cc      string
+	Bcc     string
+	Subject string
+	Body    string // HTML
+}
+
+// SaveMailDraft saves a draft message. Returns the saved message map (incl. id).
+func (c *Client) SaveMailDraft(ctx context.Context, p SaveMailDraftParams) (map[string]any, error) {
+	if strings.TrimSpace(p.To) == "" {
+		return nil, fmt.Errorf("SaveMailDraft: to is required")
+	}
+	if strings.TrimSpace(p.From) == "" {
+		from, err := c.defaultMailFrom(ctx)
+		if err != nil {
+			return nil, err
+		}
+		p.From = from
+	}
+	body := map[string]any{
+		"id":      p.ID,
+		"from":    p.From,
+		"to":      p.To,
+		"cc":      p.Cc,
+		"bcc":     p.Bcc,
+		"subject": p.Subject,
+		"body":    p.Body,
+	}
+	return c.putJSONObject(ctx, "/api/2.0/mail/drafts/save", body)
+}
+
+func (c *Client) defaultMailFrom(ctx context.Context) (string, error) {
+	accounts, err := c.ListMailAccounts(ctx)
+	if err != nil {
+		return "", err
+	}
+	var fallback string
+	for _, a := range accounts {
+		email := strings.TrimSpace(stringFromMap(a, "email"))
+		if email == "" || email == "<nil>" {
+			continue
+		}
+		if boolField(a, "enabled") || boolField(a, "isDefault") {
+			return email, nil
+		}
+		if fallback == "" {
+			fallback = email
+		}
+	}
+	if fallback == "" {
+		return "", fmt.Errorf("SaveMailDraft: from is required (no mailbox on account)")
+	}
+	return fallback, nil
+}
+
+// AttachMailDocument attaches an OnlyOffice Files document to a mail message/draft.
+// fileID is the Documents/CRM file id (e.g. from InvoicePDFFile).
+func (c *Client) AttachMailDocument(ctx context.Context, messageID string, fileID int64) (map[string]any, error) {
+	id := strings.TrimSpace(messageID)
+	if id == "" {
+		return nil, fmt.Errorf("AttachMailDocument: message id is required")
+	}
+	if fileID <= 0 {
+		return nil, fmt.Errorf("AttachMailDocument: file id is required")
+	}
+	fields := url.Values{}
+	fields.Set("fileId", strconv.FormatInt(fileID, 10))
+	return c.postFormObject(ctx, fmt.Sprintf("/api/2.0/mail/messages/%s/document", url.PathEscape(id)), fields)
+}
+
+// PlainTextToMailHTML turns plain text into simple HTML paragraphs for drafts.
+// If s already looks like HTML, it is returned unchanged.
+func PlainTextToMailHTML(s string) string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return ""
+	}
+	if strings.Contains(s, "<") && strings.Contains(s, ">") {
+		return s
+	}
+	parts := strings.Split(s, "\n\n")
+	var b strings.Builder
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		if p == "" {
+			continue
+		}
+		b.WriteString("<p>")
+		b.WriteString(strings.ReplaceAll(p, "\n", "<br/>"))
+		b.WriteString("</p>\n")
+	}
+	return b.String()
+}
+
+// MailHTMLWithBlankParagraphs inserts empty paragraphs between blocks
+// (German Geschäftsbrief-style vertical spacing in OnlyOffice Mail).
+func MailHTMLWithBlankParagraphs(html string) string {
+	html = strings.TrimSpace(html)
+	if html == "" {
+		return ""
+	}
+	return strings.ReplaceAll(html, "</p>\n<p>", "</p>\n<p>&nbsp;</p>\n<p>")
+}
+
+// Int64FromMap coerces OnlyOffice numeric id fields (float64/int/string) to int64.
+func Int64FromMap(m map[string]any, key string) int64 {
+	switch v := m[key].(type) {
+	case float64:
+		return int64(v)
+	case int64:
+		return v
+	case int:
+		return int64(v)
+	case string:
+		n, _ := strconv.ParseInt(strings.TrimSpace(v), 10, 64)
+		return n
+	default:
+		n, _ := strconv.ParseInt(fmt.Sprint(m[key]), 10, 64)
+		return n
+	}
 }
 
 // ResolveMailFolder maps a CLI folder name or numeric string to a folder id.

mails_test.go

@@ -1,6 +1,9 @@
 package onlyoffice
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestResolveMailFolder(t *testing.T) {
 	tests := []struct {
@@ -70,3 +73,27 @@ func TestMailMessagesAsTableRows(t *testing.T) {
 		t.Fatalf("got %+v", rows[0])
 	}
 }
+
+func TestPlainTextToMailHTML(t *testing.T) {
+	got := PlainTextToMailHTML("Hello\n\nWorld\nline2")
+	if !strings.Contains(got, "<p>Hello</p>") || !strings.Contains(got, "World<br/>line2") {
+		t.Fatalf("got %q", got)
+	}
+	html := "<p>Already</p>"
+	if PlainTextToMailHTML(html) != html {
+		t.Fatalf("html passthrough failed")
+	}
+	spaced := MailHTMLWithBlankParagraphs("<p>A</p>\n<p>B</p>")
+	if spaced != "<p>A</p>\n<p>&nbsp;</p>\n<p>B</p>" {
+		t.Fatalf("spaced: %q", spaced)
+	}
+}
+
+func TestInt64FromMap(t *testing.T) {
+	if Int64FromMap(map[string]any{"id": float64(99)}, "id") != 99 {
+		t.Fatal("float64")
+	}
+	if Int64FromMap(map[string]any{"id": "42"}, "id") != 42 {
+		t.Fatal("string")
+	}
+}

project_contacts.go

@@ -0,0 +1,35 @@
+package onlyoffice
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strconv"
+)
+
+// ListProjectContacts returns CRM persons/companies linked to a project.
+// GET /api/2.0/crm/contact/project/{projectid}
+func (c *Client) ListProjectContacts(ctx context.Context, projectID int) ([]map[string]any, error) {
+	return c.ResponseArray(ctx, fmt.Sprintf("/api/2.0/crm/contact/project/%d", projectID))
+}
+
+// AddProjectContact links a CRM contact (person or company) to a project.
+// POST /api/2.0/project/{projectid}/contact  form: contactId=
+func (c *Client) AddProjectContact(ctx context.Context, projectID, contactID int) (map[string]any, error) {
+	fields := url.Values{}
+	fields.Set("contactId", strconv.Itoa(contactID))
+	return c.postFormObject(ctx, fmt.Sprintf("/api/2.0/project/%d/contact", projectID), fields)
+}
+
+// RemoveProjectContact unlinks a CRM contact from a project.
+// DELETE /api/2.0/project/{projectid}/contact?contactId=
+func (c *Client) RemoveProjectContact(ctx context.Context, projectID, contactID int) error {
+	_, err := c.deleteReq(ctx, fmt.Sprintf("/api/2.0/project/%d/contact?contactId=%d", projectID, contactID))
+	return err
+}
+
+// GetProjectTeam returns portal users on the project team.
+// GET /api/2.0/project/{projectid}/team
+func (c *Client) GetProjectTeam(ctx context.Context, projectID int) ([]map[string]any, error) {
+	return c.ResponseArray(ctx, fmt.Sprintf("/api/2.0/project/%d/team", projectID))
+}

projects.go

@@ -134,6 +134,51 @@ func (c *Client) GetProjectByID(ctx context.Context, projectID string) (map[stri
 	return c.ResponseObject(ctx, fmt.Sprintf("/api/2.0/project/%s.json", url.PathEscape(projectID)))
 }
 
+// NewMilestoneRequest is the payload for CreateMilestone.
+type NewMilestoneRequest struct {
+	ProjectID   int    `json:"-"`
+	Title       string `json:"title"`
+	Deadline    Time   `json:"deadline"`
+	Description string `json:"description,omitempty"`
+	IsKey       bool   `json:"isKey"`
+	IsNotify    bool   `json:"isNotify"`
+	Responsible string `json:"responsible,omitempty"`
+}
+
+// CreateMilestone creates a project milestone (Gantt row).
+// POST /api/2.0/project/{id}/milestone
+func (c *Client) CreateMilestone(req NewMilestoneRequest) (*Milestone, error) {
+	if req.Responsible == "" {
+		uid, err := c.SelfUserID(context.Background())
+		if err != nil {
+			return nil, fmt.Errorf("CreateMilestone: self: %w", err)
+		}
+		req.Responsible = uid
+	}
+	ms := new(Milestone)
+	err := c.Query(Request{
+		Uri:    fmt.Sprintf("/api/2.0/project/%d/milestone", req.ProjectID),
+		Method: "POST",
+		Body:   req,
+	}, &struct {
+		MetaResponse `json:",inline"`
+		Response     *Milestone `json:"response"`
+	}{Response: ms})
+	return ms, err
+}
+
+// DeleteMilestone removes a milestone by id.
+// DELETE /api/2.0/project/milestone/{id}
+func (c *Client) DeleteMilestone(id int64) error {
+	return c.Query(Request{
+		Uri:    fmt.Sprintf("/api/2.0/project/milestone/%d", id),
+		Method: "DELETE",
+	}, &struct {
+		MetaResponse `json:",inline"`
+		Response     *Milestone `json:"response"`
+	}{})
+}
+
 // GetProjectMilestones returns milestones for the given project.
 // https://api1.onlyoffice.com/portals/method/project/post/api/2.0/project/%7bid%7d/milestone
 func (c *Client) GetProjectMilestones(project *Project) ([]*Milestone, error) {
@@ -193,16 +238,26 @@ func (c *Client) DeleteProject(id int) (*Project, error) {
 }
 
 // UpdateProject updates project fields.
+// OnlyOffice requires responsibleId on PUT; callers should set ResponsibleID
+// (the CLI fills it from the current project when omitted).
 func (c *Client) UpdateProject(req ProjectUpdateRequest) (*Project, error) {
-	p := &Project{}
+	p := new(Project)
-	return p, c.Query(Request{
+	body := map[string]any{
+		"title":         req.Title,
+		"description":   req.Description,
+		"responsibleId": req.ResponsibleID,
+	}
+	err := c.Query(Request{
 		Uri:    fmt.Sprintf("/api/2.0/project/%d.json", req.ID),
 		Method: "PUT",
-		Body:   req,
+		Body:   body,
-	},
+	}, &struct {
-		&struct {
+		Response *Project `json:"response"`
-			Response *Project `json:"response"`
+	}{Response: p})
-		}{p})
+	if err != nil {
+		return p, err
+	}
+	return p, nil
 }
 
 // UpdateProjectStatus sets project lifecycle status (open, paused, closed).

tasks.go

@@ -233,17 +233,26 @@ func (c *Client) GetTaskByID(ctx context.Context, taskID string) (map[string]any
 // AddTask creates a task via the form-encoded endpoint (no milestone/start).
 // Prefer the typed CreateProjectTask for new code; AddTask is kept for
 // parity with the Python reference tooling.
+//
+// Always assigns the authenticated user as responsible (form field
+// "responsibles"). Empty deadline defaults to today+14 days.
 func (c *Client) AddTask(ctx context.Context, projectID, title, description string, priority int, deadline string) (map[string]any, error) {
 	if projectID == "" {
 		projectID = c.defaults.ProjectID
 	}
+	if deadline == "" {
+		deadline = time.Now().Add(14 * 24 * time.Hour).Format("2006-01-02")
+	}
+	uid, err := c.SelfUserID(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("AddTask: resolve self: %w", err)
+	}
 	fields := url.Values{}
 	fields.Set("title", title)
 	fields.Set("description", description)
 	fields.Set("priority", strconv.Itoa(priority))
-	if deadline != "" {
+	fields.Set("deadline", deadline)
-		fields.Set("deadline", deadline)
+	fields.Set("responsibles", uid)
-	}
 	return c.postFormObject(ctx, fmt.Sprintf("/api/2.0/project/%s/task.json", url.PathEscape(projectID)), fields)
 }