todocko-mcp 3.10.2 → 3.10.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,132 +1,72 @@
1
1
  # Todocko MCP Server
2
2
 
3
- > **English version below** / [Jump to English](#english)
3
+ > [Česká verze níže](#česky) / Czech version below
4
4
 
5
- MCP (Model Context Protocol) server pro práci s daty [Todocko](https://app.todocko.cz) aplikace z AI asistentů.
6
-
7
- ## Podpora
8
-
9
- - **Claude Desktop** - plná podpora
10
- - **Claude Code (CLI)** - plná podpora (stejná konfigurace)
5
+ MCP (Model Context Protocol) server for working with [Todocko](https://app.todocko.cz) app data from AI assistants.
11
6
 
12
- ## Požadavky
7
+ ## Support
13
8
 
14
- - **Node.js 24.20+** — Evolu v8 to má v `engines`, a není to formalita: v8 stojí
15
- na `navigator.locks`, `MessageChannel`, `BroadcastChannel` a `WebSocket`, které
16
- má Node nativně teprve od 24
17
- - Todocko účet s daty synchronizovanými přes Evolu
9
+ - **Claude Desktop** - full support
10
+ - **Claude Code (CLI)** - full support (same configuration)
18
11
 
19
- ## Evolu v8 (TODO-88)
12
+ ## Requirements
20
13
 
21
- MCP běží na `@evolu/common` 8.27.0 a `@evolu/nodejs` 4.6.0. Upgrade z 8.22
22
- (TODO-431) nevyžadoval změnu kódu; sync přes relay ověřen v obou směrech
23
- proti verzi 8.22.
14
+ - **Node.js 24.20+** – required by Evolu v8's `engines`, and not merely formally:
15
+ v8 relies on `navigator.locks`, `MessageChannel`, `BroadcastChannel` and
16
+ `WebSocket`, which Node only has natively from 24 on
17
+ - Todocko account with data synchronized via Evolu
24
18
 
25
- Upgrade na 8.27 (TODO-448) změnu kódu vyžadoval, a hlavně **mění formát
26
- databáze na disku**:
19
+ ## Installation
27
20
 
28
- - `@evolu/nodejs` 4.4 vyměnilo better-sqlite3 za vlastní SQLite. Ten na rozdíl
29
- od better-sqlite3 respektuje šifrovací klíč, který Evolu pro klientskou
30
- databázi předává, takže soubor v `~/.todocko` je nově **šifrovaný**. Starou
31
- databázi psanou better-sqlite3 nový driver neotevře, skončí na
32
- `file is not a database` (SQLITE_NOTADB, ověřeno na kopii reálné databáze).
33
- **Při upgradu je proto nutné lokální databáze smazat**; jsou jen keší dat
34
- z relaye, takže se stáhnou znovu (ověřeno: čerstvá databáze se dosynchronizovala
35
- na 17 MB). Co nebylo odsynchronizované, je pryč, takže před smazáním
36
- zkontrolovat `td_sync_status`.
37
- - Dopad na bezpečnost je naopak příjemný: lokální kopie všech úkolů už neleží na
38
- disku v plaintextu. Druhá strana téže mince je, že do souboru nenahlédne ani
39
- žádný vlastní nástroj, což odneslo `ensureMissingColumns`.
40
- - Transportní URL je od 8.27 brandovaný `RelayUrl`, takže `TODOCKO_RELAY_URL` se
41
- parsuje přes `RelayUrlFromString` a URL s query se odmítne; `createOwnerWebSocketTransport`
42
- si `?ownerId=` připojuje sám.
43
- - Platforma musí nově dodat `deleteDatabaseFiles` (maže soubor databáze i žurnál)
44
- a `getDevicePersistence` i na hlavním vlákně, ne jen v shared workeru.
21
+ ### From npm
45
22
 
46
- Od Evolu 8.20.3 nese zápis do sdílené instance celého ownera,
47
- `{ owner: sharedOwner }`, ne `{ ownerId }`. Zapomenuté `ownerId` Evolu ignoruje
48
- a řádek zapíše pod jiného ownera, odkud se nenasynchronizuje. Hlídá to
49
- `src/tools/sharedWrites.test.ts`. Databázi, jejíž worker spadl, Evolu nově
50
- odmítne přes `evoluError`; `td_sync_status` ji ukáže v poli `evoluError`
51
- a nástroje na ni nečekají do timeoutu, hned řeknou, že je potřeba reconnect.
52
- (TODO-427)
23
+ Nothing to clone and nothing to build. Point Claude at the published package
24
+ and it fetches it on first run:
53
25
 
54
- v7 dodával `createDbWorkerForPlatform`, což bylo vše, co headless klient v Node
55
- potřeboval. v8 to zrušil: `@evolu/nodejs` v3 nabízí relay a pár primitiv, a
56
- jedinou kompletní klientskou platformu má upstream pro web. `src/evoluPlatform.ts`
57
- je protějšek pro Node, poskládaný ze stejných dílů.
26
+ **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
58
27
 
59
- Vyšel krátce, protože Node 24 má potřebná web API nativně. Oba workery běží
60
- **in-process** přes `createWorker` / `createSharedWorker` — to jsou vlastní
61
- fallbacky Evolu „pro platformy bez podpory workerů"; `worker_threads` by přinesly
62
- izolaci, kterou jednoprocesový CLI nepotřebuje.
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "todocko": {
32
+ "command": "npx",
33
+ "args": ["-y", "todocko-mcp"],
34
+ "env": {
35
+ "TODOCKO_MNEMONIC": "your 24 word backup phrase"
36
+ }
37
+ }
38
+ }
39
+ }
40
+ ```
63
41
 
64
- Sedm věcí, na kterých se to dá snadno rozbít:
42
+ **Claude Code (CLI)** - add the same block to `~/.claude/settings.json`, then
43
+ restart Claude.
65
44
 
66
- - **Mutace má strop 640 000 bajtů** (od 8.12). Větší zápis vyhodí výjimku ještě
67
- před uložením, takže se ani nenasynchronizuje. Přílohy se proto ukládají
68
- binárně a po kusech po 480 KiB (`src/tools/attachmentChunks.ts`), stejně jako
69
- v aplikaci; velikost kusu musí sedět s ní, jinak se příloha nahraná tady
70
- otevře jinde useknutá. Čtení umí i starý tvar, base64 v `attachment.data`,
71
- protože schéma je append-only.
72
- - **Obsah nové přílohy leží ve vlastním shardu** (`src/attachmentShards.ts`,
73
- TODO-450), ne pod AppOwnerem. Jednotlivou změnu v CRDT smazat nejde, jen
74
- označit jako smazanou, takže owner je jediná jednotka skutečného smazání.
75
- Cesta `attachment/<id>` se odvozuje z id přílohy, a tedy se nikam neukládá;
76
- v řádku je jen značka `contentShard`. Odvození i pořadí při mazání, nejdřív
77
- relay a pak lokálně, musí sedět s aplikací, jinak se obě poloviny rozejdou
78
- tiše: příloha nahraná tady by se tam otevřela prázdná. Shard se registruje
79
- jen na dobu nahrání nebo čtení, protože adresa transportu nese owner id
80
- a trvale registrovaný shard by znamenal jeden WebSocket na každou přílohu.
81
- - **Hlášení stavů dohledává jména k identifikátorům** (`src/statusReporting.ts`,
82
- TODO-458). Pilulka v aplikaci ukazovala u volání, která dostanou jen id,
83
- zkrácený identifikátor, což člověku neříká nic. Tabulky i sloupce, ze kterých
84
- se jméno bere, jsou vyjmenované vedle seznamu povolených polí, ne odvozené
85
- z názvu nástroje. Dohledání běží uvnitř téhož pošli a nečekej jako celé
86
- hlášení a má vlastní strop, takže zaseknutý dotaz nedrží frontu; když se nic
87
- nenajde, zůstane zkrácené id.
45
+ Pin a version with `todocko-mcp@<version>` instead of `todocko-mcp` if you would
46
+ rather decide yourself when to move. To get the `todo` command line tool on your
47
+ `PATH` as well, install the package globally:
88
48
 
49
+ ```bash
50
+ npm install -g todocko-mcp
51
+ ```
89
52
 
90
- - **`installPolyfills()` je povinné** a musí proběhnout dřív než cokoli
91
- z `@evolu/common`. v8 volá `Map.prototype.getOrInsert(Computed)`, které nemá
92
- žádný vydaný Node (ověřeno do 25.9.0). Bez toho to spadne na první zprávě.
93
- - **Databáze patří jednomu mnemonicu.** v7 při neshodě volal `restoreAppOwner`,
94
- který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala
95
- data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu
96
- **ohlásí a odmítne nastartovat** — smaž `~/.todocko/todocko.db` a nech ho
97
- stáhnout data znovu.
98
- - **`createNodeEvoluDeps()` musí být singleton na proces.** Shared worker drží
99
- jediný `tabLeaderPortStore` a `initDbWorker` každého tenanta předpokládá, že
100
- je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo
101
- leadera neohlásil, a vytvoření sdílené instance spadne na
102
- `initDbWorker: Expected value to be non-nullable`. Jeden worker obslouží obě
103
- instance jako dva tenanty podle `appName`, stejně jako `@evolu/web` na jedné
104
- stránce.
105
- - **Mutace nevrací `Result`.** v7 vracel z `insert`/`update` `Result`, takže se
106
- testovalo `result.ok` a čtlo `result.value.id`. v8 vrací přímo `{ id }` a při
107
- neplatné změně vyhodí výjimku. Kontrola `!result.ok` proto uspěla vždy a
108
- nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší,
109
- protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to
110
- `src/tools/pure.test.ts`.
111
- - **Ownera filtrovat v SQL, ne až v JS.** Sdílená instance drží data všech
112
- ownerů v jedné tabulce. `limit` provede SQLite dřív, než se v JS cokoli
113
- filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a
114
- filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26.
115
- Stejná past číhá u `orderBy position desc limit 1` při výpočtu další pozice.
53
+ Note that `TODOCKO_MNEMONIC` is the private key to all of your data. Keep it in
54
+ the configuration file and nowhere else: never on a command line, never in a
55
+ shell history, never in a repository. See [Security](#security).
116
56
 
117
- ## Instalace
57
+ ### From source
118
58
 
119
- ### 1. Stažení
59
+ #### 1. Download
120
60
 
121
- **Pomocí git:**
61
+ **Using git:**
122
62
  ```bash
123
63
  git clone https://github.com/brnt-cz/todocko-mcp.git
124
64
  cd todocko-mcp
125
65
  ```
126
66
 
127
- **Nebo stáhněte ZIP** z [Releases](https://github.com/brnt-cz/todocko-mcp/releases) a rozbalte.
67
+ **Or download ZIP** from [Releases](https://github.com/brnt-cz/todocko-mcp/releases) and extract.
128
68
 
129
- ### 2. Spuštění instalátoru
69
+ #### 2. Run the installer
130
70
 
131
71
  **Linux/macOS:**
132
72
  ```bash
@@ -139,641 +79,596 @@ chmod +x install.sh
139
79
  .\install.ps1
140
80
  ```
141
81
 
142
- Instalátor:
143
- 1. Nainstaluje závislosti a sestaví projekt
144
- 2. Zeptá se, zda chcete nakonfigurovat Claude Desktop, Claude Code nebo obojí
145
- 3. Vytvoří konfigurační soubor s placeholderem
146
- 4. **Ručně doplňte** svou 24slovnou zálohovací frázi do konfiguračního souboru
147
- 5. Restartujte Claude
82
+ The installer will:
83
+ 1. Install dependencies and build the project
84
+ 2. Ask whether to configure Claude Desktop, Claude Code, or both
85
+ 3. Create a configuration file with a placeholder
86
+ 4. **Manually add** your 24-word backup phrase to the configuration file
87
+ 5. Restart Claude
148
88
 
149
- ### Manuální instalace
89
+ #### Manual installation
150
90
 
151
- 1. Nainstalujte závislosti:
91
+ 1. Install dependencies:
152
92
  ```bash
153
93
  npm install
154
94
  npm run build
155
95
  ```
156
96
 
157
- 2. Přidejte do konfigurace:
97
+ 2. Add to configuration:
158
98
 
159
- **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
99
+ **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
160
100
 
161
101
  ```json
162
102
  {
163
103
  "mcpServers": {
164
104
  "todocko": {
165
105
  "command": "node",
166
- "args": ["/cesta/k/mcp-server/dist/index.js"],
106
+ "args": ["/path/to/mcp-server/dist/index.js"],
167
107
  "env": {
168
- "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
108
+ "TODOCKO_MNEMONIC": "your 24 word backup phrase"
169
109
  }
170
110
  }
171
111
  }
172
112
  }
173
113
  ```
174
114
 
175
- **Claude Code (CLI)** - přidejte do `~/.claude/settings.json`:
115
+ **Claude Code (CLI)** - add to `~/.claude/settings.json`:
176
116
 
177
117
  ```json
178
118
  {
179
119
  "mcpServers": {
180
120
  "todocko": {
181
121
  "command": "node",
182
- "args": ["/cesta/k/mcp-server/dist/index.js"],
122
+ "args": ["/path/to/mcp-server/dist/index.js"],
183
123
  "env": {
184
- "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
124
+ "TODOCKO_MNEMONIC": "your 24 word backup phrase"
185
125
  }
186
126
  }
187
127
  }
188
128
  }
189
129
  ```
190
130
 
191
- 3. Restartujte Claude Desktop / Claude Code
192
-
193
- ## Dostupné nástroje (161)
131
+ 3. Restart Claude Desktop / Claude Code
194
132
 
195
- ### Projekty
133
+ ## Available Tools (161)
196
134
 
197
- | Nástroj | Popis |
198
- |---------|-------|
199
- | `td_list_projects` | Seznam všech projektů |
200
- | `td_get_project` | Detail projektu podle ID nebo kódu |
201
- | `td_create_project` | Vytvoření nového projektu (kód jen `A-Z` a `0-9`, jako v appce) |
202
- | `td_update_project` | Aktualizace projektu (name, code, color, isArchived, isHiddenFromFilters; kód jen `A-Z` a `0-9`). `autoApproveMembers` patří sdílenému projektu, tady se odmítne, viz `td_update_shared_project` |
203
- | `td_delete_project` | Smazání projektu (soft delete) |
135
+ ### Projects
204
136
 
205
- ### Úkoly
137
+ | Tool | Description |
138
+ |------|-------------|
139
+ | `td_list_projects` | List all projects |
140
+ | `td_get_project` | Get project details by ID or code |
141
+ | `td_create_project` | Create a new project (code: `A-Z` and `0-9` only, as in the app) |
142
+ | `td_update_project` | Update a project (name, code, color, isArchived, isHiddenFromFilters; code `A-Z` and `0-9` only). `autoApproveMembers` belongs to the shared project and is refused here, see `td_update_shared_project` |
143
+ | `td_delete_project` | Delete a project (soft delete) |
206
144
 
207
- | Nástroj | Popis |
208
- |---------|-------|
209
- | `td_list_tasks` | Seznam úkolů s filtry (projekt, status, priorita, assignee) |
210
- | `td_get_task` | Detail úkolu podle ID nebo kódu (např. `PROJ-123`), včetně nastavení opakování |
211
- | `td_create_task` | Vytvoření nového úkolu (včetně recurrence, sprintNumber, parentTaskId) |
212
- | `td_update_task` | Aktualizace existujícího úkolu (včetně recurrence, sprintNumber, parentTaskId) |
213
- | `td_search_tasks` | Vyhledávání úkolů podle textu |
214
- | `td_bulk_update_tasks` | Hromadná aktualizace více úkolů (včetně sprintNumber) |
215
- | `td_bulk_delete_tasks` | Hromadné smazání více úkolů |
216
- | `td_delete_task` | Smazání jednoho úkolu (soft delete, kaskáda na worklogy a přílohy) |
217
- | `td_list_git_events` | Git aktivita pro úkol (commits, PR) z relay serveru |
145
+ ### Tasks
218
146
 
219
- ### Uživatelé
147
+ | Tool | Description |
148
+ |------|-------------|
149
+ | `td_list_tasks` | List tasks with filters (project, status, priority, assignee) |
150
+ | `td_get_task` | Get task details by ID or code (e.g., `PROJ-123`), recurrence settings included |
151
+ | `td_create_task` | Create a new task (with recurrence, sprint, parentTaskId support) |
152
+ | `td_update_task` | Update an existing task (with recurrence, sprint, parentTaskId support) |
153
+ | `td_search_tasks` | Search tasks by text |
154
+ | `td_bulk_update_tasks` | Bulk update multiple tasks |
155
+ | `td_bulk_delete_tasks` | Bulk delete multiple tasks |
156
+ | `td_delete_task` | Soft-delete a single personal task (cascades to its worklogs and attachments). |
157
+ | `td_list_git_events` | List git events (push, PR opened/merged/closed) for a task by its code. |
220
158
 
221
- | Nástroj | Popis |
222
- |---------|-------|
223
- | `td_list_users` | Seznam všech uživatelů |
224
- | `td_get_user` | Detail uživatele |
225
- | `td_create_user` | Vytvoření nového uživatele |
226
- | `td_update_user` | Aktualizace uživatele |
227
- | `td_delete_user` | Smazání uživatele (soft delete) |
159
+ ### Users
228
160
 
229
- ### Worklogy
161
+ | Tool | Description |
162
+ |------|-------------|
163
+ | `td_list_users` | List all users |
164
+ | `td_get_user` | Get user details |
165
+ | `td_create_user` | Create a new user |
166
+ | `td_update_user` | Update a user |
167
+ | `td_delete_user` | Delete a user (soft delete) |
230
168
 
231
- | Nástroj | Popis |
232
- |---------|-------|
233
- | `td_list_worklogs` | Seznam worklogů pro úkol |
234
- | `td_add_worklog` | Přidání worklogu k úkolu |
235
- | `td_update_worklog` | Aktualizace worklogu |
236
- | `td_delete_worklog` | Smazání worklogu (soft delete) |
169
+ ### Worklogs
237
170
 
238
- ### Přílohy
171
+ | Tool | Description |
172
+ |------|-------------|
173
+ | `td_list_worklogs` | List worklogs for a task |
174
+ | `td_add_worklog` | Add a worklog to a task |
175
+ | `td_update_worklog` | Update a worklog |
176
+ | `td_delete_worklog` | Delete a worklog (soft delete) |
239
177
 
240
- | Nástroj | Popis |
241
- |---------|-------|
242
- | `td_upload_attachment` | Nahrání přílohy k úkolu (ze souboru nebo base64) |
243
- | `td_list_attachments` | Seznam příloh úkolu |
244
- | `td_download_attachment` | Stažení přílohy |
245
- | `td_delete_attachment` | Smazání přílohy |
246
- | `td_upload_note_attachment` | Nahrání přílohy k lokální poznámce projektu |
247
- | `td_list_note_attachments` | Seznam příloh lokální poznámky |
248
- | `td_download_note_attachment` | Stažení přílohy poznámky |
249
- | `td_delete_note_attachment` | Smazání přílohy poznámky |
178
+ ### Attachments
250
179
 
251
- ### Komentáře
180
+ | Tool | Description |
181
+ |------|-------------|
182
+ | `td_upload_attachment` | Upload an attachment to a task (from file or base64) |
183
+ | `td_list_attachments` | List attachments for a task |
184
+ | `td_download_attachment` | Download an attachment |
185
+ | `td_delete_attachment` | Delete an attachment |
186
+ | `td_upload_note_attachment` | Upload an attachment to a local project note |
187
+ | `td_list_note_attachments` | List attachments of a local note |
188
+ | `td_download_note_attachment` | Download a note attachment |
189
+ | `td_delete_note_attachment` | Delete a note attachment |
252
190
 
253
- | Nástroj | Popis |
254
- |---------|-------|
255
- | `td_list_task_comments` | Seznam komentářů k úkolu |
256
- | `td_create_task_comment` | Přidání komentáře k úkolu |
257
- | `td_update_task_comment` | Úprava komentáře |
258
- | `td_delete_task_comment` | Smazání komentáře (soft delete) |
191
+ ### Comments
192
+
193
+ | Tool | Description |
194
+ |------|-------------|
195
+ | `td_list_task_comments` | List comments for a task |
196
+ | `td_create_task_comment` | Add a comment to a task |
197
+ | `td_update_task_comment` | Update a comment |
198
+ | `td_delete_task_comment` | Delete a comment (soft delete) |
259
199
 
260
200
  ### Checklist
261
201
 
262
- | Nástroj | Popis |
263
- |---------|-------|
264
- | `td_list_checklist_items` | Seznam položek checklistu úkolu |
265
- | `td_create_checklist_item` | Přidání položky checklistu |
266
- | `td_update_checklist_item` | Aktualizace položky (zaškrtnutí, pozice) |
267
- | `td_delete_checklist_item` | Smazání položky (soft delete) |
202
+ | Tool | Description |
203
+ |------|-------------|
204
+ | `td_list_checklist_items` | List checklist items for a task |
205
+ | `td_create_checklist_item` | Add a checklist item |
206
+ | `td_update_checklist_item` | Update a checklist item (check, reposition) |
207
+ | `td_delete_checklist_item` | Delete a checklist item (soft delete) |
268
208
 
269
- ### Zmínky (mentions)
209
+ ### Mentions
270
210
 
271
- | Nástroj | Popis |
272
- |---------|-------|
273
- | `td_list_mentions` | Seznam zmínek uživatele |
274
- | `td_create_mention` | Vytvoření zmínky |
275
- | `td_mark_mention_read` | Označení zmínky jako přečtené |
276
- | `td_mark_all_mentions_read` | Označení všech zmínek jako přečtených |
277
- | `td_delete_mention` | Smazání zmínky (soft delete) |
211
+ | Tool | Description |
212
+ |------|-------------|
213
+ | `td_list_mentions` | List mentions for a user |
214
+ | `td_create_mention` | Create a mention |
215
+ | `td_mark_mention_read` | Mark a mention as read |
216
+ | `td_mark_all_mentions_read` | Mark all mentions as read |
217
+ | `td_delete_mention` | Delete a mention (soft delete) |
278
218
 
279
- ### Linky mezi úkoly
219
+ ### Task Links
280
220
 
281
- | Nástroj | Popis |
282
- |---------|-------|
283
- | `td_list_app_settings` | Nastavení účtu, která se přenášejí mezi zařízeními |
284
- | `td_set_app_setting` | Nastavení jedné hodnoty na účtu |
285
- | `td_list_task_links` | Seznam linků úkolu |
286
- | `td_create_task_link` | Vytvoření linku mezi úkoly (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
287
- | `td_delete_task_link` | Smazání linku (soft delete) |
221
+ | Tool | Description |
222
+ |------|-------------|
223
+ | `td_list_app_settings` | Account settings that follow the user across devices |
224
+ | `td_set_app_setting` | Set one account setting |
225
+ | `td_list_task_links` | List links for a task |
226
+ | `td_create_task_link` | Create a link between tasks (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
227
+ | `td_delete_task_link` | Delete a task link (soft delete) |
288
228
 
289
- ### Tagy
229
+ ### Tags
290
230
 
291
- | Nástroj | Popis |
292
- |---------|-------|
293
- | `td_list_tags` | Seznam štítků; vrací `projectId`, umí filtrovat podle projektu i na nezařazené |
294
- | `td_create_tag` | Vytvoření štítku — **předej `projectId`**, viz poznámku níž |
295
- | `td_update_tag` | Přejmenování, změna barvy, přiřazení projektu, nebo příznak výchozího štítku |
296
- | `td_delete_tag` | Smazání štítku (soft delete) |
297
- | `td_list_task_tags` | Seznam štítků přiřazených k úkolu |
298
- | `td_add_tag_to_task` | Přiřazení štítku k úkolu |
299
- | `td_remove_tag_from_task` | Odebrání štítku z úkolu |
231
+ | Tool | Description |
232
+ |------|-------------|
233
+ | `td_list_tags` | List tags; returns `projectId`, filters by project or unassigned |
234
+ | `td_create_tag` | Create a tag – **pass `projectId`**, see the note below |
235
+ | `td_update_tag` | Rename, recolour, assign to a project, or mark default |
236
+ | `td_delete_tag` | Delete a tag (soft delete) |
237
+ | `td_list_task_tags` | List tags assigned to a task |
238
+ | `td_add_tag_to_task` | Assign a tag to a task |
239
+ | `td_remove_tag_from_task` | Remove a tag from a task |
300
240
 
301
- Sdílené projekty (TODO-235):
241
+ Shared projects (TODO-235):
302
242
 
303
- | Nástroj | Popis |
304
- |---------|-------|
305
- | `td_list_shared_tags` | Štítky ve sdíleném projektu |
306
- | `td_create_shared_tag` | Vytvoření štítku ve sdíleném projektu |
307
- | `td_update_shared_tag` | Přejmenování / změna barvy / příznak výchozího štítku |
308
- | `td_delete_shared_tag` | Smazání (soft delete) |
309
- | `td_add_shared_tag_to_task` | Přiřazení k úkolu ve sdíleném projektu |
310
- | `td_remove_shared_tag_from_task` | Odebrání z úkolu |
243
+ | Tool | Description |
244
+ |------|-------------|
245
+ | `td_list_shared_tags` | Tags in a shared project |
246
+ | `td_create_shared_tag` | Create a tag in a shared project |
247
+ | `td_update_shared_tag` | Rename / recolour |
248
+ | `td_delete_shared_tag` | Delete (soft delete) |
249
+ | `td_add_shared_tag_to_task` | Assign to a task in a shared project |
250
+ | `td_remove_shared_tag_from_task` | Remove from a task |
311
251
 
312
- > **Štítek bez projektu appka nikde nenabídne.** Od TODO-227 jsou štítky vázané
313
- > na projekt; `td_create_tag` bez `projectId` vyrobí **nezařazený** štítek, který
314
- > se v appce objeví jen v nastavení projektu v sekci „Nezařazené" s tlačítkem na
315
- > přiřazení. Odpověď nástroje na to upozorní. Dodatečně to spraví
316
- > `td_update_tag` s `projectId`.
252
+ > **A tag without a project is never offered by the app.** Since TODO-227 tags
253
+ > belong to a project; `td_create_tag` without `projectId` makes an **unassigned**
254
+ > tag, which shows up only under "Nezařazené" in project settings with a button to
255
+ > adopt it. The tool response says so. Fix it afterwards with `td_update_tag` and
256
+ > a `projectId`.
317
257
  >
318
- > **Limity free tarifu (TODO-243).** Tarifní limity patří do appky, ne sem.
319
- > `td_create_task` a `td_create_project` proto do odpovědi přilepí varování
320
- > s reálným počtem, když je owner na free tarifu a je nad limitem (1 projekt,
321
- > 50 **aktivních** úkolů). Jde o to, aby se to člověk dozvěděl při zakládání, ne až
322
- > zpětně v appce, a aby z textu bylo jasné, že o nic nepřišel. **Nic to neblokuje**
323
- > a při neznámém tarifu (nedostupný relay) radši mlčí — falešný poplach je horší
324
- > než žádný.
258
+ > **Free-tier limits (TODO-243).** Tier caps belong to the app, not here.
259
+ > `td_create_task` and `td_create_project` append a warning with the real count
260
+ > when the owner is on the free tier and above its cap (1 project, 50 **active**
261
+ > tasks), so that it is learned at creation time rather than later in the app, and
262
+ > so that the text makes clear nothing was lost. **Nothing is blocked**, and with
263
+ > an unknown tier (unreachable relay) it stays silent – a false alarm is worse
264
+ > than none.
325
265
 
326
- > **Výchozí štítky (TODO-239).** `isDefault` u `td_create_tag` / `td_update_tag`
327
- > (a sdílených variant) znamená, že štítek dostane **každý nově zakládaný úkol**
328
- > projektu. `td_create_task` i `td_create_shared_task` je přidávají samy a vrátí
329
- > je v `appliedTags` — appka je předzaškrtává v modalu, takže bez toho by výsledek
330
- > závisel na tom, odkud úkol vznikne. Existujících úkolů se to nedotkne.
266
+ > **Default tags (TODO-239).** `isDefault` on `td_create_tag` / `td_update_tag`
267
+ > (and the shared variants) means every task newly created in the project gets the
268
+ > tag. Both `td_create_task` and `td_create_shared_task` apply them and report them
269
+ > back in `appliedTags` – the app pre-ticks them in its form, so without this the
270
+ > result would depend on where the task was created. Existing tasks are untouched.
331
271
  >
332
- > Ve sdílených projektech se zapisuje do **jiné Evolu instance**, proto samostatná
333
- > sada nástrojů — `td_add_tag_to_task` na sdílený úkol nefunguje.
334
-
335
- ### Šablony úkolů
336
-
337
- | Nástroj | Popis |
338
- |---------|-------|
339
- | `td_list_task_templates` | Seznam šablon úkolů |
340
- | `td_create_task_template` | Vytvoření šablony (volitelně `checklistItems` a `tagIds`) |
341
- | `td_update_task_template` | Aktualizace šablony (`checklistItems`, `tagIds`; prázdné pole maže) |
342
- | `td_delete_task_template` | Smazání šablony (soft delete) |
343
-
344
- ### Kanban sloupce
345
-
346
- | Nástroj | Popis |
347
- |---------|-------|
348
- | `td_list_kanban_columns` | Seznam kanban sloupců |
349
- | `td_create_kanban_column` | Vytvoření sloupce (volitelně `wipLimit`, max. úkolů na uživatele v In progress před varováním v hlavičce) |
350
- | `td_update_kanban_column` | Aktualizace sloupce (`wipLimit: null` limit zruší) |
351
- | `td_delete_kanban_column` | Smazání sloupce (soft delete) |
352
-
353
- ### Uložená zobrazení
354
-
355
- | Nástroj | Popis |
356
- |---------|-------|
357
- | `td_list_saved_views` | Seznam uložených zobrazení |
358
- | `td_create_saved_view` | Vytvoření zobrazení |
359
- | `td_update_saved_view` | Aktualizace zobrazení |
360
- | `td_delete_saved_view` | Smazání zobrazení (soft delete) |
361
-
362
- ### Aktivita
272
+ > Shared projects write to a **different Evolu instance**, hence the separate set
273
+ > – `td_add_tag_to_task` does not work on a shared task.
363
274
 
364
- | Nástroj | Popis |
365
- |---------|-------|
366
- | `td_list_activity_log` | Seznam zápisů aktivity s filtry (úkol, aktor, akce, typ entity, datum od/do) — read-only |
275
+ ### Task Templates
367
276
 
368
- ### Poznámky k projektu
277
+ | Tool | Description |
278
+ |------|-------------|
279
+ | `td_list_task_templates` | List task templates |
280
+ | `td_create_task_template` | Create a task template (optional `checklistItems` and `tagIds`) |
281
+ | `td_update_task_template` | Update a task template (`checklistItems`, `tagIds`; empty array clears) |
282
+ | `td_delete_task_template` | Delete a task template (soft delete) |
369
283
 
370
- | Nástroj | Popis |
371
- |---------|-------|
372
- | `td_list_project_notes` | Seznam lokálních poznámek projektu (rejstřík: titulek a `contentLength`, obsah až na `includeContent`) |
373
- | `td_get_project_note` | Jedna lokální poznámka včetně obsahu |
374
- | `td_create_project_note` | Vytvoření lokální poznámky |
375
- | `td_update_project_note` | Aktualizace lokální poznámky |
376
- | `td_delete_project_note` | Smazání lokální poznámky (soft delete) |
284
+ ### Kanban Columns
377
285
 
378
- ### Dokumentace projektu
286
+ | Tool | Description |
287
+ |------|-------------|
288
+ | `td_list_kanban_columns` | List kanban columns |
289
+ | `td_create_kanban_column` | Create a kanban column (optional `wipLimit`, max tasks per user in In progress before the header warns) |
290
+ | `td_update_kanban_column` | Update a kanban column (`wipLimit: null` clears the limit) |
291
+ | `td_delete_kanban_column` | Delete a kanban column (soft delete) |
379
292
 
380
- Dokumenty jsou poznámky s `isDoc`, takže mohou být zanořené pod jiný dokument
381
- (`parentDocId`).
293
+ ### Saved Views
382
294
 
383
- | Nástroj | Popis |
384
- |---------|-------|
385
- | `td_list_project_docs` | Seznam dokumentů projektu (rejstřík: titulek, hierarchie a `contentLength`, obsah až na `includeContent`) |
386
- | `td_get_project_doc` | Jedna stránka dokumentace včetně obsahu |
387
- | `td_create_project_doc` | Vytvoření dokumentu |
388
- | `td_update_project_doc` | Aktualizace dokumentu |
389
- | `td_delete_project_doc` | Smazání dokumentu (soft delete) |
295
+ | Tool | Description |
296
+ |------|-------------|
297
+ | `td_list_saved_views` | List saved views |
298
+ | `td_create_saved_view` | Create a saved view |
299
+ | `td_update_saved_view` | Update a saved view |
300
+ | `td_delete_saved_view` | Delete a saved view (soft delete) |
390
301
 
391
- ### Systémová oznámení (relay)
302
+ ### Activity Log
392
303
 
393
- Broadcast oznámení pro všechny uživatele. Zápis a výpis včetně expirovaných
394
- vyžaduje `TODOCKO_RELAY_ADMIN_KEY`; obráceným směrem jdou zprávy od uživatelů,
395
- viz níž.
304
+ | Tool | Description |
305
+ |------|-------------|
306
+ | `td_list_activity_log` | List activity log entries with filters (task, actor, action, entityType, date from/to) – read-only |
396
307
 
397
- Bez `TODOCKO_RELAY_ADMIN_KEY` se `td_create_system_notification`
398
- a `td_delete_system_notification` klientovi vůbec nenabízejí (nemohly by nic
399
- jiného než vrátit 401) a u výpisu zmizí přepínač `admin`. Klíč se navíc nikdy
400
- neposílá přes nešifrované `http://` jinam než na localhost. (TODO-441)
308
+ ### Project Notes
401
309
 
402
- | Nástroj | Popis |
403
- |---------|-------|
404
- | `td_list_system_notifications` | Seznam aktivních oznámení (s `admin: true` i expirovaná) |
405
- | `td_create_system_notification` | Vytvoření oznámení pro všechny uživatele |
406
- | `td_delete_system_notification` | Smazání oznámení |
310
+ | Tool | Description |
311
+ |------|-------------|
312
+ | `td_list_project_notes` | List local project notes (index: title and `contentLength`; content via `includeContent`) |
313
+ | `td_get_project_note` | Read one local project note, with its content |
314
+ | `td_create_project_note` | Create a local project note |
315
+ | `td_update_project_note` | Update a local project note |
316
+ | `td_delete_project_note` | Delete a local project note (soft delete) |
407
317
 
408
- ### Deployment stages
318
+ ### Deployment Stages
409
319
 
410
- | Nástroj | Popis |
411
- |---------|-------|
412
- | `td_list_deployment_stages` | Seznam deployment stages pro projekt |
413
- | `td_create_deployment_stage` | Vytvoření deployment stage |
414
- | `td_update_deployment_stage` | Aktualizace deployment stage |
415
- | `td_delete_deployment_stage` | Smazání deployment stage (soft delete) |
320
+ | Tool | Description |
321
+ |------|-------------|
322
+ | `td_list_deployment_stages` | List deployment stages for a project |
323
+ | `td_create_deployment_stage` | Create a deployment stage for a personal project. |
324
+ | `td_update_deployment_stage` | Update a deployment stage in a personal project. |
325
+ | `td_delete_deployment_stage` | Soft-delete a deployment stage in a personal project. |
416
326
 
417
- ### Repository linky
327
+ ### Repository Links
418
328
 
419
- | Nástroj | Popis |
420
- |---------|-------|
421
- | `td_list_repository_links` | Seznam repozitářových linků |
422
- | `td_create_repository_link` | Vytvoření repozitářového linku |
423
- | `td_update_repository_link` | Aktualizace repozitářového linku |
424
- | `td_delete_repository_link` | Smazání repozitářového linku |
329
+ | Tool | Description |
330
+ |------|-------------|
331
+ | `td_list_repository_links` | List repository links |
332
+ | `td_create_repository_link` | Create a repository link |
333
+ | `td_delete_repository_link` | Delete a repository link |
334
+ | `td_update_repository_link` | Update a repository link for a project. |
425
335
 
426
- ### Sdílené projekty
336
+ ### Shared Projects
427
337
 
428
- | Nástroj | Popis |
429
- |---------|-------|
430
- | `td_list_shared_projects` | Seznam sdílených projektů s vaším oprávněním (`ownerSecret` už nevrací) |
431
- | `td_list_shared_tasks` | Seznam úkolů ze sdíleného projektu |
432
- | `td_create_shared_task` | Vytvoření úkolu ve sdíleném projektu (auto-generovaný kód) |
433
- | `td_update_shared_task` | Aktualizace úkolu ve sdíleném projektu (všechna pole včetně recurrence, estimate, blocking) |
434
- | `td_delete_shared_task` | Smazání úkolu ve sdíleném projektu (soft delete, kaskáda na checklist) |
435
- | `td_update_shared_project` | Aktualizace sdíleného projektu: název, kód, barva, archivace, skrytí z filtrů, automatické schvalování členů |
436
- | `td_list_shared_worklogs` | Seznam worklogů úkolu ve sdíleném projektu |
437
- | `td_add_shared_worklog` | Přidání worklogu k úkolu ve sdíleném projektu |
438
- | `td_delete_shared_worklog` | Smazání worklogu ve sdíleném projektu |
439
- | `td_list_shared_checklist_items` | Seznam položek checklistu úkolu ve sdíleném projektu |
440
- | `td_create_shared_checklist_item` | Přidání položky checklistu ve sdíleném projektu |
441
- | `td_update_shared_checklist_item` | Aktualizace položky checklistu ve sdíleném projektu |
442
- | `td_delete_shared_checklist_item` | Smazání položky checklistu ve sdíleném projektu |
443
- | `td_list_shared_task_links` | Seznam vazeb úkolu ve sdíleném projektu |
444
- | `td_create_shared_task_link` | Vytvoření vazby mezi úkoly ve sdíleném projektu |
445
- | `td_delete_shared_task_link` | Smazání vazby ve sdíleném projektu (soft delete) |
446
- | `td_list_shared_task_comments` | Seznam komentářů úkolu ve sdíleném projektu |
447
- | `td_create_shared_task_comment` | Přidání komentáře k úkolu ve sdíleném projektu |
448
- | `td_update_shared_task_comment` | Aktualizace komentáře ve sdíleném projektu |
449
- | `td_delete_shared_task_comment` | Smazání komentáře ve sdíleném projektu |
450
- | `td_upload_shared_attachment` | Nahrání přílohy k úkolu ve sdíleném projektu |
451
- | `td_list_shared_attachments` | Seznam příloh úkolu ve sdíleném projektu |
452
- | `td_download_shared_attachment` | Stažení přílohy úkolu sdíleného projektu |
453
- | `td_delete_shared_attachment` | Smazání přílohy úkolu sdíleného projektu |
454
- | `td_list_shared_deployment_stages` | Seznam deployment stages pro sdílený projekt |
455
- | `td_create_shared_deployment_stage` | Vytvoření deployment stage ve sdíleném projektu |
456
- | `td_update_shared_deployment_stage` | Aktualizace deployment stage ve sdíleném projektu |
457
- | `td_delete_shared_deployment_stage` | Smazání deployment stage ve sdíleném projektu |
458
- | `td_list_shared_repository_links` | Seznam repozitářových linků sdíleného projektu |
459
- | `td_create_shared_repository_link` | Vytvoření repozitářového linku ve sdíleném projektu |
460
- | `td_update_shared_repository_link` | Aktualizace repozitářového linku ve sdíleném projektu |
461
- | `td_delete_shared_repository_link` | Smazání repozitářového linku ve sdíleném projektu |
462
- | `td_list_shared_project_notes` | Seznam poznámek sdíleného projektu (rejstřík, obsah až na `includeContent`) |
463
- | `td_get_shared_project_note` | Jedna poznámka sdíleného projektu včetně obsahu |
464
- | `td_create_shared_project_note` | Vytvoření poznámky ve sdíleném projektu |
465
- | `td_update_shared_project_note` | Aktualizace poznámky ve sdíleném projektu |
466
- | `td_delete_shared_project_note` | Smazání poznámky ve sdíleném projektu |
467
- | `td_list_shared_members` | Seznam členů sdíleného projektu (jméno, oprávnění, kicked/blocked stav, `isPending` = čeká na schválení). Vlastníkovi navíc `verifiedPermission` (co udělil) a `effectivePermission` (to nižší z obojího, rozhoduje o write key) |
468
- | `td_update_shared_member` | Jen admin. Změna oprávnění mezi `write` a `admin`, schválení čekajícího nebo odblokování (jen dokud projekt nemá rotovaný klíč); block, kick, zamítnutí a snížení na `read` odmítne, ty patří do appky. Oprávnění nastavené vlastníkem se zapíše i jako jeho `memberGrant`, což teprve rozdává write key; admin bez vlastnictví změní jen členův nárok |
469
- | `td_upload_shared_note_attachment` | Nahrání přílohy k poznámce sdíleného projektu |
470
- | `td_list_shared_note_attachments` | Seznam příloh poznámky sdíleného projektu |
471
- | `td_download_shared_note_attachment` | Stažení přílohy poznámky sdíleného projektu |
472
- | `td_delete_shared_note_attachment` | Smazání přílohy poznámky sdíleného projektu |
473
- | `td_list_shared_project_docs` | Seznam dokumentů sdíleného projektu (rejstřík, obsah až na `includeContent`) |
474
- | `td_get_shared_project_doc` | Jedna stránka dokumentace sdíleného projektu včetně obsahu |
475
- | `td_create_shared_project_doc` | Vytvoření dokumentu ve sdíleném projektu |
476
- | `td_update_shared_project_doc` | Aktualizace dokumentu ve sdíleném projektu |
477
- | `td_delete_shared_project_doc` | Smazání dokumentu ve sdíleném projektu |
478
- | `td_get_shared_task` | Detail jednoho úkolu ve sdíleném projektu (podle ID nebo kódu, s odpracovaným časem a počty checklistu a komentářů) |
479
- | `td_list_shared_task_tags` | Tagy úkolu ve sdíleném projektu |
480
- | `td_bulk_update_shared_tasks` | Hromadná úprava úkolů ve sdíleném projektu |
481
- | `td_bulk_delete_shared_tasks` | Hromadné smazání úkolů ve sdíleném projektu (kaskáda na checklist a komentáře) |
482
- | `td_update_shared_worklog` | Úprava worklogu ve sdíleném projektu |
483
- | `td_list_shared_activity_log` | Aktivita ve sdíleném projektu (stejné filtry jako u osobní) |
338
+ | Tool | Description |
339
+ |------|-------------|
340
+ | `td_list_shared_projects` | List shared projects with your permission (no longer returns `ownerSecret`) |
341
+ | `td_list_shared_tasks` | List tasks from a shared project |
342
+ | `td_update_shared_task` | Update a task in a shared project |
343
+ | `td_list_shared_deployment_stages` | List deployment stages for a shared project |
344
+ | `td_create_shared_deployment_stage` | Create a deployment stage in a shared project |
345
+ | `td_list_shared_repository_links` | List repository links for a shared project |
346
+ | `td_create_shared_repository_link` | Create a repository link in a shared project |
347
+ | `td_list_shared_project_notes` | List notes for a shared project (index; content via `includeContent`) |
348
+ | `td_get_shared_project_note` | Read one note from a shared project, with its content |
349
+ | `td_create_shared_project_note` | Create a note in a shared project |
350
+ | `td_update_shared_project_note` | Update a note in a shared project |
351
+ | `td_delete_shared_project_note` | Delete a note in a shared project |
352
+ | `td_list_shared_members` | List members of a shared project (name, permission, kicked/blocked state, `isPending` = waiting for approval). The owner also gets `verifiedPermission` (what they granted) and `effectivePermission` (the lower of the two, which decides the write key) |
353
+ | `td_update_shared_member` | Admin only. Change permission between `write` and `admin`, approve a pending join or unblock (only while the project has no rotated write key); refuses block, kick, reject and downgrade to `read`, which belong in the app. A permission set by the owner is also recorded as their `memberGrant`, which is what hands out the write key; an admin who does not own the project changes only the member's claim |
354
+ | `td_upload_shared_note_attachment` | Upload an attachment to a shared project note |
355
+ | `td_list_shared_note_attachments` | List attachments of a shared project note |
356
+ | `td_download_shared_note_attachment` | Download a shared note attachment |
357
+ | `td_delete_shared_note_attachment` | Delete a shared note attachment |
358
+ | `td_list_shared_project_docs` | List document pages from a shared project (index; content via `includeContent`) |
359
+ | `td_get_shared_project_doc` | Read one document page from a shared project, with its content |
360
+ | `td_create_shared_project_doc` | Create a document page in a shared project |
361
+ | `td_update_shared_project_doc` | Update a document page in a shared project |
362
+ | `td_delete_shared_project_doc` | Delete a document page in a shared project (soft delete) |
363
+ | `td_create_shared_task` | Create a task in a shared project. |
364
+ | `td_delete_shared_task` | Soft-delete a task in a shared project (cascades to its checklist items and comments). |
365
+ | `td_list_shared_worklogs` | List worklogs for a task in a shared project. |
366
+ | `td_add_shared_worklog` | Add a worklog to a task in a shared project. |
367
+ | `td_delete_shared_worklog` | Soft-delete a worklog in a shared project. |
368
+ | `td_list_shared_checklist_items` | List checklist items for a task in a shared project. |
369
+ | `td_create_shared_checklist_item` | Create a checklist item on a task in a shared project. |
370
+ | `td_update_shared_checklist_item` | Update a checklist item in a shared project (toggle done, rename, reorder). |
371
+ | `td_delete_shared_checklist_item` | Soft-delete a checklist item in a shared project. |
372
+ | `td_list_shared_task_links` | List dependency links for a task in a shared project. |
373
+ | `td_create_shared_task_link` | Create a dependency link between tasks in a shared project. |
374
+ | `td_delete_shared_task_link` | Delete a dependency link in a shared project (soft delete). |
375
+ | `td_list_shared_task_comments` | List comments for a task in a shared project. |
376
+ | `td_create_shared_task_comment` | Add a comment to a task in a shared project. |
377
+ | `td_update_shared_task_comment` | Update a comment in a shared project. |
378
+ | `td_delete_shared_task_comment` | Soft-delete a comment in a shared project. |
379
+ | `td_update_shared_repository_link` | Update a repository link in a shared project. |
380
+ | `td_delete_shared_repository_link` | Soft-delete a repository link in a shared project. |
381
+ | `td_update_shared_deployment_stage` | Update a deployment stage in a shared project. |
382
+ | `td_delete_shared_deployment_stage` | Soft-delete a deployment stage in a shared project. |
383
+ | `td_update_shared_project` | Update shared-project metadata (archive / hide from filters). |
384
+ | `td_upload_shared_attachment` | Upload a file attachment to a task in a shared project. |
385
+ | `td_list_shared_attachments` | List file attachments of a task in a shared project (metadata only, no data). |
386
+ | `td_download_shared_attachment` | Download a task attachment from a shared project. |
387
+ | `td_delete_shared_attachment` | Soft-delete a task attachment in a shared project. |
388
+ | `td_get_shared_task` | Get one task in a shared project by ID or code, with its worklog total, checklist and comment counts. |
389
+ | `td_list_shared_task_tags` | List the tags on a task in a shared project. |
390
+ | `td_bulk_update_shared_tasks` | Update several tasks in a shared project at once. |
391
+ | `td_bulk_delete_shared_tasks` | Soft-delete several tasks in a shared project at once, cascading their checklist items and comments. |
392
+ | `td_update_shared_worklog` | Update a worklog in a shared project. |
393
+ | `td_list_shared_activity_log` | List activity log entries for a shared project. |
484
394
 
485
- > **Oprávnění, `ownerSecret` a historie ve sdílených projektech (TODO-434).**
395
+ > **Permissions, `ownerSecret` and history in shared projects (TODO-434).**
486
396
  >
487
- > - **`ownerSecret` je nepovinný a nemá se posílat.** Každý sdílený nástroj si ho
488
- > najde ve vašem `projectRef` podle `sharedOwnerId` a `td_list_shared_projects`
489
- > ho už nevrací. Secret je klíč k celému projektu, takže dřív ležel v kontextu
490
- > modelu i v každém přepisu konverzace. Kdo ho pošle, tomu to dál funguje
491
- > (a kontroluje se proti `sharedOwnerId`).
492
- > - **Zápisy hlídají oprávnění stejně jako appka** (`src/permissions.ts`, port
493
- > appkového `permissions.ts`). Úkoly, worklogy, checklist, komentáře, přílohy,
494
- > vazby, přiřazení štítků, poznámky a dokumenty chtějí `write` nebo `admin`.
495
- > Nastavení projektu (`td_update_shared_project` včetně mazání a obnovy),
496
- > deployment stages, repozitářové linky, správa štítků a členové chtějí
497
- > vlastníka nebo `admin`. Bez `projectRef` se zápis odmítne, čtení jde dál.
498
- > Odmítnutí přijde jako chyba a nic se nezapíše.
499
- > - **Členy MCP spravuje jen napůl.** Appka po každé změně člena rotuje
500
- > zapisovací klíč nebo předá ten současný, jinak zablokovaný člen zapisuje dál.
501
- > MCP rotovat neumí, takže změny, po kterých člen nesmí zapisovat (block,
502
- > kick, zamítnutí, snížení na `read`), odmítne s odkazem na appku. Schválení,
503
- > odblokování a povýšení projdou, jen dokud projekt nemá rotovaný klíč.
504
- > - **Sdílené zápisy píšou historii** do sdílené instance, stejné záznamy jako
505
- > appka (úkol vytvořen/upraven po polích/smazán, worklog, checklist, komentář,
506
- > příloha, štítek, stage, repozitář, projekt, člen), s `actorId` vašeho účtu
507
- > a `source: "mcp"` v metadatech.
508
- > - **Mazání neexistujícího id** vrací chybu místo `success` a hromadné mazání ho
509
- > počítá mezi přeskočené. `td_update_shared_project` vybírá řádek projektu
510
- > stejně jako appka (nejstarší živý) a umí ho obnovit z koše.
511
- > - **Kód projektu** smí obsahovat jen `A-Z` a `0-9` a souběžná volání
512
- > `td_create_task` / `td_create_shared_task` do jednoho projektu už nedostanou
513
- > stejný kód.
397
+ > - **`ownerSecret` is optional; leave it out.** Every shared tool looks it up
398
+ > from your `projectRef` by `sharedOwnerId`, and `td_list_shared_projects` no
399
+ > longer returns it. The secret is the key to the whole project, so it used
400
+ > to sit in the model's context and every transcript. Passing it still works
401
+ > and is checked against `sharedOwnerId`.
402
+ > - **Writes are gated by permission, as in the app** (`src/permissions.ts`, a
403
+ > port of the app's `permissions.ts`). Tasks, worklogs, checklist items,
404
+ > comments, attachments, links, tag assignment, notes and documents need
405
+ > `write` or `admin`. Project settings (`td_update_shared_project`, delete and
406
+ > restore included), deployment stages, repository links, tag management and
407
+ > members need the owner or `admin`. Without a `projectRef` writes are
408
+ > refused, reads still work. A refusal is an error and nothing is written.
409
+ > - **Member management is partial.** After every member change the app rotates
410
+ > the write key or hands the current one over, otherwise a blocked member keeps
411
+ > writing. The MCP cannot rotate, so changes that leave the member unable to
412
+ > write (block, kick, reject, downgrade to `read`) are refused with a pointer
413
+ > to the app. Approving, unblocking and upgrading pass only while the project
414
+ > has no rotated write key.
415
+ > - **Shared writes record history** in the shared instance, the same entries
416
+ > the app writes (task created / updated per field / deleted, worklog,
417
+ > checklist, comment, attachment, tag, stage, repository link, project,
418
+ > member), with your account as `actorId` and `source: "mcp"` in metadata.
419
+ > - **Deleting an unknown id** is an error instead of `success`, and bulk delete
420
+ > counts it as skipped. `td_update_shared_project` picks the project row the
421
+ > way the app does (oldest live row) and can restore it from the Trash.
422
+ > - **Project codes** may contain only `A-Z` and `0-9`, and concurrent
423
+ > `td_create_task` / `td_create_shared_task` calls for one project no longer
424
+ > get the same code.
514
425
 
515
- > **Stavy úkolů a validace argumentů (TODO-296, TODO-297).** Stav
516
- > `recurring` je plnohodnotný, appka ho používá pro opakované úkoly a MCP ho
517
- > teď nabízí ve všech devíti enumech. Zároveň se **kontrolují hodnoty enumů a
518
- > odmítají nedeklarované argumenty**. Dřív byly enumy jen dokumentace a
519
- > neznámý argument se tiše zahodil, což je přesně způsob, jak
520
- > `td_create_shared_checklist_item` přijal `isChecked`, vrátil `success`
521
- > a položku založil neodškrtnutou. Ten argument tam dnes je.
522
- >
523
- > Při té příležitosti se srovnal i `linkType`: MCP nabízelo `related`, kterému
524
- > appka nerozumí, a chyběly mu `explicit` a `mention`, které appka opravdu
525
- > zapisuje. Platné hodnoty jsou `blocks`, `explicit`, `mention`.
426
+ ### Project Documentation
526
427
 
527
- > **Rodič se ověřuje, argumenty jsou dorovnané (TODO-300, TODO-302).**
528
- > `td_create_task_comment` a `td_create_checklist_item` šly dřív založit na
529
- > **neexistující úkol**: řádek se zapsal proti ID, které nic nerozřeší, každý
530
- > výpis jde přes `taskId`, takže ho nikdo nikdy nepřečte, a tool vrátil
531
- > `success`. `td_add_worklog` to odmítal od TODO-90 M12, tyhle dva ne. Teď
532
- > odmítají obě strany, osobní i sdílená, a sdílená scopuje i podle ownera.
533
- >
534
- > Zároveň se dorovnalo devět argumentů, které sdílené tooly proti osobním
535
- > neměly. Nejcitelnější byl `td_update_shared_project`: uměl jen archivaci,
536
- > takže **sdílený projekt nešlo přejmenovat**.
428
+ Documents are notes with `isDoc`, so they can nest under another document via `parentDocId`.
537
429
 
538
- ### Zprávy od uživatelů (relay)
430
+ | Tool | Description |
431
+ |------|-------------|
432
+ | `td_list_project_docs` | List local project document pages (index: title, hierarchy and `contentLength`; content via `includeContent`) |
433
+ | `td_get_project_doc` | Read one local project document page, with its content |
434
+ | `td_create_project_doc` | Create a local project document page |
435
+ | `td_update_project_doc` | Update a local project document page |
436
+ | `td_delete_project_doc` | Delete a local project document page (soft delete) |
539
437
 
540
- Zprávy, které uživatelé posílají z aplikace (hlášení vad, návrhy, vzkazy).
541
- Výpis a mazání umí jen **admin owner** a relay od TODO-90 H2 nevěří samotnému
542
- `ownerId` — požadavek se podepisuje Ed25519 klíčem odvozeným z nastaveného
543
- mnemoniku. Odesílání relay nechává nepřihlášené, stejně jako formulář v appce.
438
+ ### System Notifications (relay)
544
439
 
545
- | Nástroj | Popis |
546
- |---------|-------|
547
- | `td_list_user_messages` | Výpis zpráv od uživatelů (jen admin owner) |
548
- | `td_submit_user_message` | Odeslání zprávy adminům (hlášení vady, návrh, vzkaz) |
549
- | `td_delete_user_message` | Smazání zprávy na relayi (jen admin owner, tvrdé smazání) |
440
+ Broadcast notices for every user. Writing, and listing expired ones, needs `TODOCKO_RELAY_ADMIN_KEY`.
550
441
 
551
- ### Analytika a přehledy
442
+ Without `TODOCKO_RELAY_ADMIN_KEY`, `td_create_system_notification` and
443
+ `td_delete_system_notification` are not offered to the client at all (a 401 is
444
+ the only answer they could give) and the listing drops its `admin` flag. The key
445
+ is never sent over plain `http://` to anything but localhost. (TODO-441)
552
446
 
553
- | Nástroj | Popis |
554
- |---------|-------|
555
- | `td_get_dashboard_summary` | Přehled: úkoly dnes, po termínu, odpracováno tento týden, nadcházející deadline |
556
- | `td_get_team_workload` | Vytížení týmu: odpracováno vs odhad vs kapacita per uživatel za období |
557
- | `td_list_recurring_tasks` | Seznam opakujících se úkolů s konfigurací opakování |
558
- | `td_list_overdue_tasks` | Úkoly po termínu (seřazené od nejstaršího) |
447
+ | Tool | Description |
448
+ |------|-------------|
449
+ | `td_list_system_notifications` | List active system/broadcast notifications from the relay server. |
450
+ | `td_create_system_notification` | Create a broadcast notification visible to all Todocko users. |
451
+ | `td_delete_system_notification` | Delete a system notification by ID. |
559
452
 
560
- > **Do v1.6.0 tyhle tři nástroje vracely vždy prázdno.** `td_list_recurring_tasks`,
561
- > `td_list_overdue_tasks` a `td_list_tasks_by_date_range` čtly `result.rows`,
562
- > zatímco `evolu.loadQuery` vrací pole samo — takže `count: 0` na jakýkoli vstup,
563
- > bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný
564
- > `queryRows`. Recurrence pole navíc vrací i `td_get_task`, takže nastavení
565
- > opakování jde přečíst tou nejpřímější cestou.
566
- | `td_list_tasks_by_date_range` | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí |
567
- | `td_analyze_dependencies` | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |
453
+ ### User Messages (relay)
568
454
 
569
- > **Sdílené projekty se do analytiky počítají (TODO-112).** Do MCP IX čtlo všech
570
- > pět přehledů jen osobní instanci, takže úkol ve sdíleném projektu neviděl
571
- > dashboard, rozdělení vytížení, seznam opakujících se ani po termínu, ani dotaz
572
- > na rozmezí dat. U vytížení to nebylo jen chybějící číslo: počítá se
573
- > z odpracovaného času, takže vynechané sdílené minuty podhodnocovaly každého,
574
- > kdo ve sdíleném projektu pracuje. Každý nástroj bere `includeShared`
575
- > (výchozí `true`) a vrací `sharedIncluded`, ať je vidět, jestli se sdílená
576
- > polovina opravdu načetla. `td_analyze_dependencies` zůstává záměrně jen
577
- > osobní: appka sdílené `taskLink` řádky čte, ale žádné nezapisuje.
578
- >
579
- > `td_search_tasks` hledá ve sdílených projektech taky, se stejným přepínačem.
455
+ What users send from the app: bug reports, feature requests, notes. Listing and deleting are admin-owner only and the request is signed with the configured mnemonic; submitting needs no admin rights.
580
456
 
581
- ### Diagnostika
457
+ | Tool | Description |
458
+ |------|-------------|
459
+ | `td_list_user_messages` | List messages users have sent from the app (bug reports, feature requests, notes). |
460
+ | `td_submit_user_message` | Send a message to the Todocko admins (bug report, feature request or note), the same way the app's feedback form does. |
461
+ | `td_delete_user_message` | Delete one user message from the relay. |
582
462
 
583
- | Nástroj | Popis |
584
- |---------|-------|
585
- | `td_sync_status` | Stav synchronizace |
586
- | `td_force_sync` | Vynutí sync round-trip s relayem (užitečné, když chceš mít jistotu, že vidíš nejnovější data z jiného zařízení) |
463
+ ### Analytics & Reports
587
464
 
588
- ## Příklady použití
465
+ | Tool | Description |
466
+ |------|-------------|
467
+ | `td_get_dashboard_summary` | Overview: tasks today, overdue, this week's worklog, upcoming deadlines |
468
+ | `td_get_team_workload` | Team workload: logged vs estimate vs capacity per user for a period |
469
+ | `td_list_recurring_tasks` | List recurring tasks with recurrence configuration |
470
+ | `td_list_overdue_tasks` | Overdue tasks (sorted oldest first) |
589
471
 
590
- ### Seznam projektů
472
+ > **Before v1.6.0 these three tools always returned nothing.**
473
+ > `td_list_recurring_tasks`, `td_list_overdue_tasks` and
474
+ > `td_list_tasks_by_date_range` read `result.rows`, while `evolu.loadQuery`
475
+ > resolves to the array itself – so `count: 0` for every input, with no error to
476
+ > notice. Fixed in TODO-242 behind a shared `queryRows`. `td_get_task` now returns
477
+ > the recurrence settings too, so a schedule can be read the obvious way.
478
+ | `td_list_tasks_by_date_range` | Tasks filtered by scheduledDate or deadline within a date range |
479
+ | `td_analyze_dependencies` | Dependency analysis: blocked tasks, blocking chains, critical path |
480
+
481
+ ### Diagnostics
482
+
483
+ | Tool | Description |
484
+ |------|-------------|
485
+ | `td_sync_status` | Sync status |
486
+ | `td_force_sync` | Force a sync round-trip with the relay (useful when you want to make sure you're reading the latest data from another device) |
487
+
488
+ ## Usage Examples
489
+
490
+ ### List projects
591
491
  ```
592
- Zobraz mi seznam všech projektů v Todocko
492
+ Show me all projects in Todocko
593
493
  ```
594
494
 
595
- ### Seznam úkolů
495
+ ### List tasks
596
496
  ```
597
- Jaké mám úkoly ve stavu "todo"?
598
- Zobraz úkoly projektu TODO
497
+ What tasks do I have with status "todo"?
498
+ Show tasks for project TODO
599
499
  ```
600
500
 
601
- ### Detail úkolu
501
+ ### Task details
602
502
  ```
603
- Jaké jsou detaily úkolu TODO-15?
503
+ What are the details of task TODO-15?
604
504
  ```
605
505
 
606
- ### Vytvoření úkolu
506
+ ### Create task
607
507
  ```
608
- Vytvoř nový úkol v projektu PROJ s názvem "Opravit bug v přihlášení" a prioritou high
609
- Vytvoř úkol s deadline na 2026-03-15 a scheduledDate na 2026-03-10
508
+ Create a new task in project PROJ with title "Fix login bug" and priority high
509
+ Create a task with deadline 2026-03-15 and scheduledDate 2026-03-10
610
510
  ```
611
511
 
612
- ### Aktualizace úkolu
512
+ ### Update task
613
513
  ```
614
- Označ úkol PROJ-5 jako dokončený
615
- Přiřaď úkol TODO-10 uživateli s ID xyz
616
- Nastav scheduledDate úkolu TODO-10 na zítra
514
+ Mark task PROJ-5 as completed
515
+ Assign task TODO-10 to user with ID xyz
516
+ Set scheduledDate of task TODO-10 to tomorrow
617
517
  ```
618
518
 
619
- ### Logování času
519
+ ### Log time
620
520
  ```
621
- Zaloguj 2 hodiny práce na úkol TODO-15 s popisem "Implementace feature"
521
+ Log 2 hours of work on task TODO-15 with description "Feature implementation"
622
522
  ```
623
523
 
624
- ### Práce s přílohami
524
+ ### Working with attachments
625
525
  ```
626
- Nahraj soubor /home/user/report.pdf jako přílohu k úkolu TODO-15
627
- Jaké přílohy má úkol TODO-15?
628
- Smaž přílohu s ID xyz
526
+ Upload file /home/user/report.pdf as attachment to task TODO-15
527
+ What attachments does task TODO-15 have?
528
+ Delete attachment with ID xyz
629
529
  ```
630
530
 
631
- ### Sdílené projekty
531
+ ### Shared projects
632
532
  ```
633
- Zobraz sdílené projekty
634
- Jaké úkoly jsou ve sdíleném projektu?
635
- Označ úkol jako nasazený na produkci
533
+ Show shared projects
534
+ What tasks are in the shared project?
535
+ Mark task as deployed to production
636
536
  ```
637
537
 
638
538
  ### Deployment stages
639
539
  ```
640
- Jaké deployment stages má projekt?
641
- Vytvoř novou deployment stage "Staging" pro sdílený projekt
540
+ What deployment stages does the project have?
541
+ Create a new deployment stage "Staging" for the shared project
642
542
  ```
643
543
 
644
- ### Sub-úkoly
544
+ ### Sub-tasks
645
545
  ```
646
- Vytvoř sub-úkol k úkolu TODO-15 v projektu TODO
647
- Odpoj úkol TODO-20 od rodičovského úkolu (parentTaskId: null)
546
+ Create a sub-task for task TODO-15 in project TODO
547
+ Detach task TODO-20 from its parent (parentTaskId: null)
648
548
  ```
649
549
 
650
- ### Přehledy a analytika
550
+ ### Analytics & Reports
651
551
  ```
652
- Jaký mám dnes přehled? (dashboard summary)
653
- Jak je vytížený tým tento týden?
654
- Jaké úkoly jsou po termínu?
655
- Zobraz úkoly naplánované na příští týden
656
- Analyzuj závislosti v projektu TODO
657
- Jaké mám opakující se úkoly?
552
+ What's my dashboard summary for today?
553
+ How is the team's workload this week?
554
+ What tasks are overdue?
555
+ Show tasks scheduled for next week
556
+ Analyze dependencies in project TODO
557
+ What recurring tasks do I have?
658
558
  ```
659
559
 
660
- ## Linux CLI (`todo`) (TODO-160)
560
+ ## Command line (`todo`)
661
561
 
662
- Vedle MCP serveru je v balíčku i CLI `todo` pro rychlé osobní ovládání z terminálu — sdílí stejnou databázi i `TODOCKO_MNEMONIC` jako MCP. Po `npm link` (nebo globální instalaci) je dostupné jako `todo`.
562
+ The package also ships a `todo` command line tool for quick personal use from a
563
+ terminal. It shares the same database and the same `TODOCKO_MNEMONIC` as the MCP
564
+ server, and a global install (`npm install -g todocko-mcp`) puts it on your
565
+ `PATH`.
663
566
 
664
- 📖 **Podrobný návod: [CLI.md](CLI.md)**
567
+ 📖 **Full guide: [CLI.md](CLI.md)**
665
568
 
666
569
  ```bash
667
- # Přidání úkolu (bez -p použije první projekt)
668
- todo add "Opravit login"
669
- todo add "Opravit login" -p TODO --priority high --scheduled today
570
+ # What is on for today, and why each task is on the list
571
+ todo today
670
572
 
671
- # Změna stavu (identifikace kódem úkolu)
573
+ # List tasks (without --all it hides done and recurring ones)
574
+ todo list
575
+ todo list -p TODO --status review
576
+ todo list --no-shared # skip shared projects, which is faster
577
+
578
+ # Add a task (without -p it uses the first project)
579
+ todo add "Fix the login"
580
+ todo add "Fix the login" -p TODO --priority high --scheduled today
581
+
582
+ # Change status (tasks are addressed by their code)
672
583
  todo done TODO-160 # status=done
673
584
  todo start TODO-160 # status=in_progress
674
585
  todo mv TODO-160 review # backlog|todo|in_progress|review|done|recurring
675
586
 
676
587
  # Worklog
677
- todo log TODO-160 1h30m "ladění OAuth"
678
- todo worklogs TODO-160 # tabulka worklogů
588
+ todo log TODO-160 1h30m "debugging OAuth"
589
+ todo worklogs TODO-160 # worklog table
679
590
 
680
- # Strojový výstup na všech příkazech
591
+ # Machine readable output on every command
681
592
  todo add "X" --json
682
593
  ```
683
594
 
684
- - **Architektura:** `src/cli.ts` (commander) → mapuje argumenty na existující tool handlery (`handleToolCall`), žádná duplicitní business logika. Kód úkolu se překládá na ID přes `td_get_task`.
685
- - **Sync:** po mutaci čeká ~3 s na relay; když je offline, vypíše `⚠ uloženo lokálně` a skončí s kódem 0 (data jsou lokálně bezpečně).
686
- - **Exit kódy:** `0` úspěch, `1` user/business chyba (neznámý kód, špatný stav/čas), `2` config (chybí mnemonic).
687
- - **Barvy** jen v TTY a při nenastaveném `NO_COLOR`.
688
- - **Pozn.:** běží jako samostatný proces nad stejnou SQLite DB jako MCP; při souběžném zápisu s MCP může (vzácně) nastat `SQLITE_BUSY` — v takovém případě příkaz zopakuj. Mimo rozsah v1: `list`/`today`, editace popisu, projekty/tagy/checklist, sdílené projekty.
689
-
690
- ## Bezpečnost
691
-
692
- **Důležité:** Vaše zálohovací fráze (mnemonic) je citlivý údaj!
693
-
694
- - Nikdy ji nesdílejte v přímé konverzaci s AI
695
- - MCP server frázi nevystavuje přes žádný nástroj: nejde ji z Todočka přečíst ani vypsat
696
- - To ale neznamená, že k ní AI nemá přístup. Agent, který umí spouštět příkazy nebo číst
697
- soubory (Claude Code a podobní), si `~/.claude.json` nebo `~/.claude/settings.json`
698
- přečte stejně jako kterýkoli jiný soubor. Konfigurace chrání frázi před nástroji MCP,
699
- ne před shellem. (TODO-441)
700
- - Kdokoli s vaší frází má plný přístup k vašim datům
701
-
702
- ### Kontrola argumentů a cest (TODO-441)
703
-
704
- - Hodnoty argumentů se kontrolují proti typu, který nástroj deklaruje. `isBlocked: "false"`
705
- se dřív ukládalo jako `true` (neprázdný řetězec je pravdivý), teď je to chyba.
706
- - Datová pole (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`, `startDate`,
707
- `endDate`, …) musí být `YYYY-MM-DD`; kde schéma mluví o datetime (`completedAt`,
708
- `expiresAt`, `from`/`to` v activity logu), projde i ISO datetime. `deadline: "zítra"`
709
- se dřív uložilo doslova a nikdo se to nedozvěděl.
710
- - Přílohy: cesty se vyhodnocují až po rozpadnutí symlinků, takže odkaz uvnitř povoleného
711
- adresáře už nevede ven. Stahování nově odmítá tečkové soubory (stejně jako nahrávání)
712
- a nepřepíše existující soubor, dokud nepošleš `overwrite: true`.
713
-
714
- ### WebSocket Origin (TODO-169)
715
-
716
- MCP server při WebSocket připojení k relay posílá hlavičku `Origin: https://todocko-mcp`. Sdílený relay (`relay.todocko.cz`) má tuto hodnotu povolenou ve whitelistu Access Control. Pokud používáš vlastní relay, musíš ji přidat do `tiers.json.allowedDomains`, jinak relay odmítne připojení s `403 Forbidden` na WS upgrade.
595
+ - **Sync:** after a mutation it waits about 3 s for the relay. Offline it prints
596
+ `⚠ uloženo lokálně` and exits 0, because the data is safe locally either way.
597
+ - **Exit codes:** `0` success, `1` user or business error (unknown code, bad
598
+ status or duration), `2` configuration (missing mnemonic).
599
+ - **Colors** only on a TTY and only when `NO_COLOR` is unset.
600
+ - **Reading covers shared projects too.** `todo list` and `todo today` merge
601
+ the personal instance with every joined shared project; a listing built on
602
+ the personal one alone would quietly omit part of the work. Skip it with
603
+ `--no-shared` when speed matters more.
604
+ - **Note:** it runs as its own process against the same SQLite database as the
605
+ MCP server. A write that collides with the MCP server can rarely raise
606
+ `SQLITE_BUSY`; repeat the command when it does. Out of scope: editing
607
+ descriptions, projects, tags, checklists, comments and attachments, plus any
608
+ writing to shared projects. Parity with the 161 MCP tools is not planned.
717
609
 
718
- ### Rotace zapisovacího klíče sdílených projektů (TODO-268)
610
+ ## Security
719
611
 
720
- Když vlastník sdíleného projektu někoho vyhodí, aplikace vymění zapisovací klíč
721
- projektu na relayi. Klíč odvozený z `ownerSecret` tím přestane platit a relay
722
- s ním odmítne každý zápis.
612
+ **Important:** Your backup phrase (mnemonic) is sensitive data!
723
613
 
724
- MCP server si nový klíč načte ze sloupce `projectRef.writeKey`, který do jeho
725
- databáze přiteče běžným syncem AppOwnera. Kontrola běží při startu a pak každou
726
- minutu, takže po rotaci může být zhruba minuta, kdy zápisy do toho jednoho
727
- projektu relay odmítá a řádky čekají lokálně. Čtení rotace neovlivňuje.
614
+ - Never share it directly in conversation with AI
615
+ - The MCP server never exposes the phrase through a tool: nothing in Todocko can read or print it
616
+ - That is not the same as the AI having no access to it. An agent that can run commands or
617
+ read files (Claude Code and the like) reads `~/.claude.json` or `~/.claude/settings.json`
618
+ like any other file. The configuration keeps the phrase away from MCP tools, not from a
619
+ shell. (TODO-441)
620
+ - Anyone with your phrase has full access to your data
728
621
 
729
- ### Komu klíč patří: nárok versus grant (TODO-440)
622
+ ### Argument and path checks (TODO-441)
730
623
 
731
- `projectMember.permission` si zapisuje sám člen, takže o tom, kdo dostane
732
- zapisovací klíč, rozhodovat nemůže. Vlastník si vede vlastní záznam ve své
733
- osobní instanci, kam žádný člen nedosáhne:
624
+ - Argument values are checked against the type the tool declares. `isBlocked: "false"`
625
+ used to be stored as `true` (a non-empty string is truthy); it is an error now.
626
+ - Date arguments (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`,
627
+ `startDate`, `endDate`, ...) must be `YYYY-MM-DD`; where the schema says datetime
628
+ (`completedAt`, `expiresAt`, activity-log `from`/`to`) an ISO datetime is accepted too.
629
+ `deadline: "zitra"` used to be stored verbatim with nothing reporting it.
630
+ - Attachments: paths are judged after symlinks are resolved, so a link inside the allowed
631
+ directory no longer leads out of it. Downloads now refuse dotfiles (as uploads already
632
+ did) and never replace an existing file unless `overwrite: true` is passed.
734
633
 
735
- - `shareInvite` na každý vygenerovaný odkaz, její id cestuje v tokenu,
736
- - `memberGrant` na každého člena, jehož oprávnění vlastník nastavil ručně,
737
- a ten pozvánku přebíjí.
634
+ ### Shared project write key rotation (TODO-268)
738
635
 
739
- Člen si id pozvánky neukládá, ten řádek čtou i ostatní členové a mohli by si ho
740
- opsat. Ukládá si do `projectMember.inviteProof` HMAC vlastní identity klíčovaný
741
- id pozvánky; vlastník, který id má, ho ověří, cizí člen si ho pro sebe nevyrobí.
742
- Skutečné oprávnění je to nižší z nároku a záznamu.
636
+ When the owner of a shared project removes a member, the app swaps the
637
+ project's write key on the relay. The key derived from `ownerSecret` stops
638
+ being valid and the relay refuses every write made with it.
743
639
 
744
- `td_list_shared_members` proto vlastníkovi vrací navíc `verifiedPermission`
745
- a `effectivePermission` a `td_update_shared_member` zapisuje `memberGrant`
746
- spolu se změnou nároku. Dokud to MCP neumělo, změnilo povýšení přes MCP jen
747
- nárok: člen zapisovací klíč nedostal a appka u něj začala hlásit, že si
748
- nárokuje víc, než má potvrzeno.
640
+ This server picks the new key up from the `projectRef.writeKey` column, which
641
+ reaches its database through the ordinary AppOwner sync. It checks at start and
642
+ then once a minute, so a rotation can leave about a minute in which writes to
643
+ that one project are refused and the rows wait locally. Reading is unaffected.
749
644
 
750
- ## Umístění dat
645
+ ## Data Location
751
646
 
752
- Databáze jsou uloženy v adresáři `~/.todocko/`:
647
+ Databases are stored in the `~/.todocko/` directory:
753
648
 
754
- | Platforma | Cesta |
755
- |-----------|-------|
649
+ | Platform | Path |
650
+ |----------|------|
756
651
  | Linux | `~/.todocko/` |
757
652
  | macOS | `~/.todocko/` |
758
653
  | Windows | `C:\Users\<user>\.todocko\` |
759
654
 
760
- Soubory:
761
- - `todocko.db` - vaše osobní data (úkoly, projekty)
762
- - `todocko-shared.db` - sdílené projekty
655
+ Files:
656
+ - `todocko.db` - your personal data (tasks, projects)
657
+ - `todocko-shared.db` - shared projects
763
658
 
764
- ## Změna konfigurace
659
+ ## Configuration Changes
765
660
 
766
661
  ### Claude Code (CLI)
767
662
 
768
- Po změně konfigurace v `~/.claude/settings.json` (např. změna mnemonicu) spusťte příkaz:
663
+ After changing configuration in `~/.claude/settings.json` (e.g., changing mnemonic), run the command:
769
664
  ```
770
665
  /mcp
771
666
  ```
772
- Tím se MCP server restartuje s novou konfigurací.
667
+ This will restart the MCP server with the new configuration.
773
668
 
774
- ### Přepnutí na jiný účet
669
+ ### Switching to a Different Account
775
670
 
776
- Při změně mnemonicu na **jiný Todocko účet** je potřeba smazat lokální databázi:
671
+ When changing the mnemonic to a **different Todocko account**, you need to delete the local database:
777
672
 
778
673
  ```bash
779
674
  # Linux/macOS
@@ -783,181 +678,314 @@ rm ~/.todocko/todocko.db
783
678
  del %USERPROFILE%\.todocko\todocko.db
784
679
  ```
785
680
 
786
- Databáze obsahuje ID vlastníka z předchozího mnemonicu. Po smazání se při dalším spuštění vytvoří nová databáze a stáhnou se data nového účtu.
681
+ The database contains the owner ID from the previous mnemonic. After deletion, a new database will be created on the next startup and data from the new account will be downloaded.
682
+
683
+ ## Troubleshooting
684
+
685
+ ### Server won't start
686
+ - Check that you have Node.js 24.20 or newer (Evolu v8 requires it)
687
+ - Check that you ran `npm run build`
688
+ - Check logs in Claude Desktop
689
+
690
+ ### Data not syncing
691
+ - Verify the backup phrase is correct (24 words)
692
+ - Check internet connection
693
+ - Wait a few seconds for synchronization
694
+ - Try deleting `~/.todocko/todocko.db` and restart
695
+
696
+ ### Tools not visible
697
+ - Restart Claude Desktop
698
+ - In Claude Code, use `/mcp` for reload
699
+ - Check the configuration file
700
+ - Check the path to dist/index.js
701
+
702
+ ### `project ... is a shared project` on a write
703
+ A shared project keeps its data in the **shared instance**, so the personal
704
+ tools (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) refuse a
705
+ write aimed at one and point at the `td_*_shared_*` counterpart.
706
+
707
+ Such a write used to be stored quietly in the personal instance beside the real
708
+ row, leaving the same task in two instances, free to drift: the app reads the
709
+ shared side and `td_list_tasks` reads the personal one, so the two disagreed
710
+ with nothing reporting it. (TODO-318)
711
+
712
+ **Deletes are still allowed** on a shared project, because otherwise old
713
+ personal copies could never be cleaned up. `td_search_tasks` with
714
+ `includeShared` shows both copies side by side and is the quickest way to spot
715
+ a split task.
716
+
717
+ ### `Todocko MCP už nad touto databází běží` (TODO-341)
718
+ A second instance over the same backup phrase refuses to start. The client
719
+ database runs with `journal_mode=delete` and a zero `busy_timeout`, so the
720
+ second process gets SQLITE_BUSY immediately, Evolu turns it into
721
+ `PanicAbortReason: database is locked`, and the **first** process loses its
722
+ dbWorker. Until TODO-341 a new window silently killed the one you were working
723
+ in.
724
+
725
+ The lock is `~/.todocko/todocko-<owner>.lock` next to the database. It holds the
726
+ owning pid; after a crash the next start detects it as stale
727
+ (`process.kill(pid, 0)`) and takes it over.
728
+
729
+ If you really need a second instance (the `todo` CLI next to the MCP, say), give
730
+ it its own database name:
731
+ ```bash
732
+ TODOCKO_INSTANCE=cli todo ...
733
+ ```
734
+ It gets `~/.todocko/todocko-cli-<owner>.db`, a separate local copy that
735
+ reconciles with the first one through the relay. Allowed characters are
736
+ `a-z0-9-`; anything else is dropped and an empty value means the default
737
+ database.
738
+
739
+ ### Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)
740
+
741
+ There are two causes, told apart by what the server says.
742
+
743
+ **1. A dead dbWorker after two processes raced (TODO-316).** Two MCP processes
744
+ creating the schema of the same database at the same time race each other. The
745
+ loser gets `SqliteError: table evolu_version already exists` and its dbWorker
746
+ stays dead for the life of the process. Typically on the first starts after an
747
+ MCP upgrade that adds a table.
748
+
749
+ Since TODO-316 the server detects this at startup and **refuses to start**:
750
+ every tool call returns `Evolu dbWorker never answered` immediately. Since
751
+ TODO-317 the reason the worker died is recorded too, in `workerDefects` from
752
+ `td_sync_status` and on stderr as `FATAL: Evolu dbWorker defect: ...`. It used to
753
+ look healthy while every query hung until the client gave up 1800s later. The
754
+ fix is a `/mcp` reconnect in Claude Code.
755
+
756
+ **2. A mismatched native binding.** The `better-sqlite3` native binding was compiled against a different Node.js ABI than the one running the MCP server. `new Database()` fails with `ERR_DLOPEN_FAILED`, the Evolu dbWorker init never completes, and every `loadQuery` hangs forever. Mutations (insert/update) report success but are silently lost.
757
+
758
+ Typical symptoms: `td_sync_status` reports `ok` with `errorCount: 0`, but `td_get_task`, `td_list_*`, etc. all time out.
759
+
760
+ Fix – rebuild the native binding against the current Node:
761
+ ```bash
762
+ cd ~/.todocko-mcp # or wherever todocko-mcp is installed
763
+ cd node_modules/better-sqlite3
764
+ npx node-gyp rebuild --release
765
+ ```
766
+ Then `/mcp` reconnect in Claude Code.
767
+
768
+ This mismatch typically appears after upgrading Node.js (e.g. v22 → v25) or switching between nvm and linuxbrew/brew Node, because the installer builds the binding against the `node` from `PATH`, but `claude` may later spawn the MCP with a different node binary.
769
+
770
+ ## Development
771
+
772
+ ```bash
773
+ # Install dependencies
774
+ npm install
775
+
776
+ # Build
777
+ npm run build
778
+
779
+ # Watch mode for development
780
+ npm run dev
781
+
782
+ # Tests
783
+ npm test
784
+
785
+ # Manual run
786
+ TODOCKO_MNEMONIC="your phrase" npm start
787
+ ```
788
+
789
+ ### Tests
787
790
 
788
- ## Troubleshooting
791
+ Vitest. **The suite runs in CI** (`ci.yml`, on pushes and
792
+ pull requests to `main`) since TODO-229. Before that CI only built, so nobody
793
+ learned that `helpers.test.ts` **does not even survive the import** on Node
794
+ 18/20: through `helpers.ts` it pulled in `../evolu.js`, whose module-level
795
+ initialization dies on `crypto.getRandomValues must be defined`.
789
796
 
790
- ### Server se nespustí
791
- - Zkontrolujte, že máte Node.js 24.20+
792
- - Zkontrolujte, že jste spustili `npm run build`
793
- - Zkontrolujte logy v Claude Desktop
797
+ That is why the functions with no Evolu dependency live in
798
+ **`src/tools/pure.ts`** and are tested from there. `helpers.ts` re-exports them,
799
+ so callers do not change. A helper that does not need Evolu belongs in
800
+ `pure.ts`, otherwise it cannot be tested without a running database.
794
801
 
795
- ### Data se nesynchronizují
796
- - Ověřte, že je zálohovací fráze správná (24 slov)
797
- - Zkontrolujte internetové připojení
798
- - Počkejte pár sekund na synchronizaci
799
- - Zkuste smazat `~/.todocko/todocko.db` a restartovat
802
+ The required version is **Node 24.20 or newer**: it is in `engines` and Evolu v8
803
+ does not run on anything older. `ci.yml` and `release.yml` both use it.
800
804
 
805
+ ### Releasing
801
806
 
802
- ### `status: relay-blocked` v `td_sync_status` (TODO-112)
807
+ ```bash
808
+ npm version patch # or minor / major
809
+ git push --follow-tags
810
+ ```
803
811
 
804
- Relay odpovídá na HTTPS, ale WebSocket nepropustí. Mezi strojem a relayí tedy
805
- něco blokuje upgrade spojení, typicky proxy nebo firewall, ne vada relaye.
806
- Zápisy se drží lokálně a odejdou, jakmile socket projde. Od `no-relay` se to
807
- liší tím, že tam neodpovídá vůbec nic, což znamená spíš výpadek sítě.
812
+ The tag starts `release.yml`, which builds, runs the tests, checks that the tag
813
+ matches `package.json` and then **stages** the release on npm with a signed
814
+ provenance statement. It carries no npm credentials: the runner asks for a
815
+ short-lived one through trusted publishing (OIDC).
808
816
 
809
- ### Nástroje nejsou viditelné
810
- - Restartujte Claude Desktop
811
- - V Claude Code použijte `/mcp` pro reload
812
- - Zkontrolujte konfigurační soubor
813
- - Zkontrolujte cestu k dist/index.js
817
+ Staging is deliberate. A release does not reach anyone until it is approved on
818
+ npmjs.com under **Staged Packages**, or with `npm stage list todocko-mcp` and
819
+ `npm stage approve <stage-id>`. Approval needs 2FA, so a workflow run that
820
+ someone else managed to steer cannot put a version in front of users on its own.
814
821
 
815
- ### `project ... is a shared project` při zápisu
816
- Sdílený projekt má svá data ve **sdílené instanci**. Osobní nástroje
817
- (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) proto zápis do
818
- takového projektu odmítnou a pošlou tě na `td_*_shared_*` protějšek.
822
+ ---
819
823
 
820
- Dřív se zápis tiše uložil do osobní instance vedle skutečného řádku. Vznikly
821
- tím dvě kopie téhož úkolu v různých instancích, které se rozcházely: aplikace
822
- čte sdílenou stranu, MCP `td_list_tasks` osobní, takže každý ukazoval něco
823
- jiného a nic to nehlásilo. (TODO-318)
824
+ # Česky
824
825
 
825
- **Mazání zůstává povolené i pro sdílený projekt**, jinak by staré osobní kopie
826
- nešlo uklidit. `td_search_tasks` s `includeShared` ukáže obě kopie vedle sebe a
827
- je proto nejrychlejší způsob, jak zjistit, že je úkol rozdvojený.
826
+ MCP (Model Context Protocol) server pro práci s daty [Todocko](https://app.todocko.cz) aplikace z AI asistentů.
828
827
 
829
- ### Kód úkolu se teď přidělit nedá (TODO-373)
830
- `td_create_task` odvozuje kód z nejvyššího, který v téhle kopii vidí. Když část
831
- účtu ještě nedorazila, je maximum nižší než skutečné a vznikne kód, který na
832
- relayi už existuje. Stalo se to 2026-09-23: v 07:01 kopie neměla TODO-360 až
833
- 367 a server vyrobil TODO-353 a dál, v 09:33 už je nad stejným souborem měla
834
- a navázal správně na 368. Nic se nerozbilo jen proto, že 353 až 359 byla shodou
835
- okolností volná.
828
+ ## Podpora
836
829
 
837
- Před přidělením kódu se proto porovná počet zpráv: Evolu jich drží po jedné
838
- v `evolu_timestamp`, relay hlásí stejné číslo pro ownera. Naměřeno 81 130 na
839
- obou stranách. Když je kopie pozadu, zápis se odmítne a řekne, kolik zpráv
840
- chybí; až se sync dotáhne, projde. Když se relay zeptat nedá, zápis projde:
841
- odmítat i tam by z lokálně prvního nástroje udělalo nástroj závislý na síti.
830
+ - **Claude Desktop** - plná podpora
831
+ - **Claude Code (CLI)** - plná podpora (stejná konfigurace)
842
832
 
843
- Aktuální stav ukáže `td_sync_status` v poli `copy`.
833
+ ## Požadavky
844
834
 
845
- **Sdílené projekty tenhle strážce nemají.** Jejich úkoly patří jinému ownerovi
846
- s vlastním počtem zpráv a zeptat se na něj chce jeho klíč, ne ten odvozený
847
- z mnemoniky. Měřit tam app ownera by vypadalo jako pokrytí a nebylo by.
835
+ - **Node.js 24.20+** – Evolu v8 to má v `engines`, a není to formalita: v8 stojí
836
+ na `navigator.locks`, `MessageChannel`, `BroadcastChannel` a `WebSocket`, které
837
+ má Node nativně teprve od 24
838
+ - Todocko účet s daty synchronizovanými přes Evolu
848
839
 
849
- ### `Todocko MCP už nad touto databází běží` (TODO-341)
850
- Druhá instance nad stejnou zálohovací frází se odmítne nastartovat. Není to
851
- opatrnost navíc: klientská databáze jede v režimu `journal_mode=delete`
852
- s nulovým `busy_timeout`, takže druhý proces dostane SQLITE_BUSY okamžitě,
853
- Evolu z toho udělá `PanicAbortReason: database is locked` a **prvnímu** procesu
854
- umře dbWorker. Do TODO-341 tak nové okno tiše shodilo to, ve kterém jsi pracoval
855
- (projevilo se jako `status: worker-dead`, viz níž).
840
+ ## Evolu v8 (TODO-88)
856
841
 
857
- Zámek je soubor `~/.todocko/todocko-<owner>.lock` vedle databáze. Drží pid,
858
- který ho vzal; po pádu procesu se pozná jako neaktuální a další start si ho
859
- vezme.
842
+ MCP běží na `@evolu/common` 8.27.0 a `@evolu/nodejs` 4.6.0. Upgrade z 8.22
843
+ (TODO-431) nevyžadoval změnu kódu; sync přes relay ověřen v obou směrech
844
+ proti verzi 8.22.
860
845
 
861
- Samotné `process.kill(pid, 0)` na to nestačí (TODO-372). **Zombie procesem ten
862
- test projde**: proces, který skončil, ale rodič ho nesklidil, je pořád
863
- v tabulce procesů a signál 0 na něm uspěje. Zámek pak vypadá jako věčně držený
864
- a žádná nová instance se nespustí. Stalo se to 2026-09-22, kdy byl držitel ve
865
- stavu `Z` a jeho rodič zastavený `claude` ve stavu `Tl`, takže neměl kdo
866
- sklízet. Na Linuxu se proto čte stav z `/proc/<pid>/stat` a `Z` se bere jako
867
- mrtvý. Kde `/proc` není, zůstává původní chování.
846
+ Upgrade na 8.27 (TODO-448) změnu kódu vyžadoval, a hlavně **mění formát
847
+ databáze na disku**:
868
848
 
869
- Když potřebuješ druhou instanci doopravdy (třeba CLI `todo` vedle MCP), spusť ji
870
- s vlastním jménem databáze:
871
- ```bash
872
- TODOCKO_INSTANCE=cli todo ...
873
- ```
874
- Dostane `~/.todocko/todocko-cli-<owner>.db`, tedy vlastní lokální kopii, která
875
- se s tou první srovná přes relay. Povolené znaky jsou `a-z0-9-`, zbytek se
876
- zahodí; prázdná hodnota znamená výchozí databázi.
849
+ - `@evolu/nodejs` 4.4 vyměnilo better-sqlite3 za vlastní SQLite. Ten na rozdíl
850
+ od better-sqlite3 respektuje šifrovací klíč, který Evolu pro klientskou
851
+ databázi předává, takže soubor v `~/.todocko` je nově **šifrovaný**. Starou
852
+ databázi psanou better-sqlite3 nový driver neotevře, skončí na
853
+ `file is not a database` (SQLITE_NOTADB, ověřeno na kopii reálné databáze).
854
+ **Při upgradu je proto nutné lokální databáze smazat**; jsou jen keší dat
855
+ z relaye, takže se stáhnou znovu (ověřeno: čerstvá databáze se dosynchronizovala
856
+ na 17 MB). Co nebylo odsynchronizované, je pryč, takže před smazáním
857
+ zkontrolovat `td_sync_status`.
858
+ - Dopad na bezpečnost je naopak příjemný: lokální kopie všech úkolů už neleží na
859
+ disku v plaintextu. Druhá strana téže mince je, že do souboru nenahlédne ani
860
+ žádný vlastní nástroj, což odneslo `ensureMissingColumns`.
861
+ - Transportní URL je od 8.27 brandovaný `RelayUrl`, takže `TODOCKO_RELAY_URL` se
862
+ parsuje přes `RelayUrlFromString` a URL s query se odmítne; `createOwnerWebSocketTransport`
863
+ si `?ownerId=` připojuje sám.
864
+ - Platforma musí nově dodat `deleteDatabaseFiles` (maže soubor databáze i žurnál)
865
+ a `getDevicePersistence` i na hlavním vlákně, ne jen v shared workeru.
877
866
 
878
- ### Worker umřel za běhu (`status: worker-dead`)
879
- Proces normálně naběhl a po nějaké době přestal odpovídat. `td_sync_status`
880
- vrátí `status: "worker-dead"` a v `workerDefects` je panika i s časem. Dotazy
881
- v tomhle stavu selžou **hned**, ne až po 15 s. Řešení je `/mcp` reconnect.
882
- Nejčastější příčina je druhý MCP proces nad stejnou databází; od TODO-341 se
883
- druhá instance nenastartuje, takže tuhle cestu k mrtvému workeru už nemá jak
884
- způsobit.
867
+ Od Evolu 8.20.3 nese zápis do sdílené instance celého ownera,
868
+ `{ owner: sharedOwner }`, ne `{ ownerId }`. Zapomenuté `ownerId` Evolu ignoruje
869
+ a řádek zapíše pod jiného ownera, odkud se nenasynchronizuje. Hlídá to
870
+ `src/tools/sharedWrites.test.ts`. Databázi, jejíž worker spadl, Evolu nově
871
+ odmítne přes `evoluError`; `td_sync_status` ji ukáže v poli `evoluError`
872
+ a nástroje na ni nečekají do timeoutu, hned řeknou, že je potřeba reconnect.
873
+ (TODO-427)
885
874
 
886
- ### Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)
875
+ v7 dodával `createDbWorkerForPlatform`, což bylo vše, co headless klient v Node
876
+ potřeboval. v8 to zrušil: `@evolu/nodejs` v3 nabízí relay a pár primitiv, a
877
+ jedinou kompletní klientskou platformu má upstream pro web. `src/evoluPlatform.ts`
878
+ je protějšek pro Node, poskládaný ze stejných dílů.
887
879
 
888
- Příčiny jsou dvě, poznáte je podle toho, co server řekne.
880
+ Vyšel krátce, protože Node 24 má potřebná web API nativně. Oba workery běží
881
+ **in-process** přes `createWorker` / `createSharedWorker` – to jsou vlastní
882
+ fallbacky Evolu „pro platformy bez podpory workerů"; `worker_threads` by přinesly
883
+ izolaci, kterou jednoprocesový CLI nepotřebuje.
889
884
 
890
- **1. Mrtvý dbWorker po závodu dvou procesů (TODO-316).** Dva MCP procesy, které
891
- současně zakládají schéma téže databáze, se porvou. Poražený dostane
892
- `SqliteError: table evolu_version already exists` a jeho dbWorker zůstane
893
- mrtvý do konce života procesu. Typicky při prvních startech po upgradu MCP,
894
- který přidá tabulku.
885
+ Sedm věcí, na kterých se to dá snadno rozbít:
895
886
 
896
- Od TODO-316 to server pozná při startu a **odmítne se nastartovat**: každé
897
- volání nástroje hned vrátí `Evolu dbWorker never answered`. Od TODO-317 se
898
- navíc zapíše i **proč** worker umřel, do `workerDefects` v `td_sync_status`
899
- a do stderr jako `FATAL: Evolu dbWorker defect: ...`. Dřív se tvářil
900
- zdravě a každý dotaz visel, dokud to klient po 1800 s nevzdal. Řešení je `/mcp`
901
- reconnect v Claude Code.
887
+ - **Mutace má strop 640 000 bajtů** (od 8.12). Větší zápis vyhodí výjimku ještě
888
+ před uložením, takže se ani nenasynchronizuje. Přílohy se proto ukládají
889
+ binárně a po kusech po 480 KiB (`src/tools/attachmentChunks.ts`), stejně jako
890
+ v aplikaci; velikost kusu musí sedět s ní, jinak se příloha nahraná tady
891
+ otevře jinde useknutá. Čtení umí i starý tvar, base64 v `attachment.data`,
892
+ protože schéma je append-only.
893
+ - **Obsah nové přílohy leží ve vlastním shardu** (`src/attachmentShards.ts`,
894
+ TODO-450), ne pod AppOwnerem. Jednotlivou změnu v CRDT smazat nejde, jen
895
+ označit jako smazanou, takže owner je jediná jednotka skutečného smazání.
896
+ Cesta `attachment/<id>` se odvozuje z id přílohy, a tedy se nikam neukládá;
897
+ v řádku je jen značka `contentShard`. Odvození i pořadí při mazání, nejdřív
898
+ relay a pak lokálně, musí sedět s aplikací, jinak se obě poloviny rozejdou
899
+ tiše: příloha nahraná tady by se tam otevřela prázdná. Shard se registruje
900
+ jen na dobu nahrání nebo čtení, protože adresa transportu nese owner id
901
+ a trvale registrovaný shard by znamenal jeden WebSocket na každou přílohu.
902
+ - **Hlášení stavů dohledává jména k identifikátorům** (`src/statusReporting.ts`,
903
+ TODO-458). Pilulka v aplikaci ukazovala u volání, která dostanou jen id,
904
+ zkrácený identifikátor, což člověku neříká nic. Tabulky i sloupce, ze kterých
905
+ se jméno bere, jsou vyjmenované vedle seznamu povolených polí, ne odvozené
906
+ z názvu nástroje. Dohledání běží uvnitř téhož pošli a nečekej jako celé
907
+ hlášení a má vlastní strop, takže zaseknutý dotaz nedrží frontu; když se nic
908
+ nenajde, zůstane zkrácené id.
902
909
 
903
- **2. Databáze, kterou nový driver neotevře.** Od TODO-448 je klientská databáze
904
- šifrovaná a starou, plaintextovou, nový driver odmítne: `file is not a database`.
905
- Symptom je stejný jako u všech vad dbWorkeru, tedy `Evolu dbWorker never answered`
906
- u každého volání. Řešení je smazat `~/.todocko/todocko*-<ownerId>.db` a nechat
907
- data stáhnout z relaye; předtím se ujistit přes `td_sync_status`, že nic nečeká
908
- na odeslání.
909
910
 
910
- Dřív tu stával mismatch native bindingu better-sqlite3 (`ERR_DLOPEN_FAILED` po
911
- upgradu Node nebo přepnutí mezi nvm a brew). `@evolu/nodejs` 4.4 ho nahradilo
912
- předpřipraveným SQLite, takže se nic nekompiluje a tahle třída chyb zmizela.
911
+ - **`installPolyfills()` je povinné** a musí proběhnout dřív než cokoli
912
+ z `@evolu/common`. v8 volá `Map.prototype.getOrInsert(Computed)`, které nemá
913
+ žádný vydaný Node (ověřeno do 25.9.0). Bez toho to spadne na první zprávě.
914
+ - **Databáze patří jednomu mnemonicu.** v7 při neshodě volal `restoreAppOwner`,
915
+ který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala
916
+ data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu
917
+ **ohlásí a odmítne nastartovat** – smaž `~/.todocko/todocko.db` a nech ho
918
+ stáhnout data znovu.
919
+ - **`createNodeEvoluDeps()` musí být singleton na proces.** Shared worker drží
920
+ jediný `tabLeaderPortStore` a `initDbWorker` každého tenanta předpokládá, že
921
+ je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo
922
+ leadera neohlásil, a vytvoření sdílené instance spadne na
923
+ `initDbWorker: Expected value to be non-nullable`. Jeden worker obslouží obě
924
+ instance jako dva tenanty podle `appName`, stejně jako `@evolu/web` na jedné
925
+ stránce.
926
+ - **Mutace nevrací `Result`.** v7 vracel z `insert`/`update` `Result`, takže se
927
+ testovalo `result.ok` a čtlo `result.value.id`. v8 vrací přímo `{ id }` a při
928
+ neplatné změně vyhodí výjimku. Kontrola `!result.ok` proto uspěla vždy a
929
+ nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší,
930
+ protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to
931
+ `src/tools/pure.test.ts`.
932
+ - **Ownera filtrovat v SQL, ne až v JS.** Sdílená instance drží data všech
933
+ ownerů v jedné tabulce. `limit` provede SQLite dřív, než se v JS cokoli
934
+ filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a
935
+ filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26.
936
+ Stejná past číhá u `orderBy position desc limit 1` při výpočtu další pozice.
913
937
 
914
- ## Vývoj
938
+ ## Instalace
915
939
 
916
- ```bash
917
- # Instalace závislostí
918
- npm install
940
+ ### Z npm
919
941
 
920
- # Build
921
- npm run build
942
+ Není co klonovat ani sestavovat. Stačí Clauda nasměrovat na vydaný balíček,
943
+ který si při prvním spuštění sám stáhne:
922
944
 
923
- # Watch mode pro vývoj
924
- npm run dev
945
+ **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
925
946
 
926
- # Ruční spuštění
927
- TODOCKO_MNEMONIC="vaše fráze" npm start
947
+ ```json
948
+ {
949
+ "mcpServers": {
950
+ "todocko": {
951
+ "command": "npx",
952
+ "args": ["-y", "todocko-mcp"],
953
+ "env": {
954
+ "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
955
+ }
956
+ }
957
+ }
958
+ }
928
959
  ```
929
960
 
930
- ---
931
-
932
- # English
933
-
934
- MCP (Model Context Protocol) server for working with [Todocko](https://app.todocko.cz) app data from AI assistants.
935
-
936
- ## Support
961
+ **Claude Code (CLI)** - tentýž blok přidejte do `~/.claude/settings.json`
962
+ a restartujte Clauda.
937
963
 
938
- - **Claude Desktop** - full support
939
- - **Claude Code (CLI)** - full support (same configuration)
964
+ Místo `todocko-mcp` můžete napsat `todocko-mcp@<verze>` a držet si tak verzi pod
965
+ kontrolou. Pokud chcete mít v `PATH` i nástroj `todo` pro příkazovou řádku,
966
+ nainstalujte balíček globálně:
940
967
 
941
- ## Requirements
968
+ ```bash
969
+ npm install -g todocko-mcp
970
+ ```
942
971
 
943
- - **Node.js 24.20+** — required by Evolu v8's `engines`, and not merely formally:
944
- v8 relies on `navigator.locks`, `MessageChannel`, `BroadcastChannel` and
945
- `WebSocket`, which Node only has natively from 24 on
946
- - Todocko account with data synchronized via Evolu
972
+ Pozor, `TODOCKO_MNEMONIC` je privátní klíč ke všem vašim datům. Patří do
973
+ konfiguračního souboru a nikam jinam: nikdy na příkazovou řádku, nikdy do
974
+ historie shellu, nikdy do repozitáře. Viz [Bezpečnost](#bezpečnost).
947
975
 
948
- ## Installation
976
+ ### Ze zdrojových kódů
949
977
 
950
- ### 1. Download
978
+ #### 1. Stažení
951
979
 
952
- **Using git:**
980
+ **Pomocí git:**
953
981
  ```bash
954
982
  git clone https://github.com/brnt-cz/todocko-mcp.git
955
983
  cd todocko-mcp
956
984
  ```
957
985
 
958
- **Or download ZIP** from [Releases](https://github.com/brnt-cz/todocko-mcp/releases) and extract.
986
+ **Nebo stáhněte ZIP** z [Releases](https://github.com/brnt-cz/todocko-mcp/releases) a rozbalte.
959
987
 
960
- ### 2. Run the installer
988
+ #### 2. Spuštění instalátoru
961
989
 
962
990
  **Linux/macOS:**
963
991
  ```bash
@@ -970,546 +998,650 @@ chmod +x install.sh
970
998
  .\install.ps1
971
999
  ```
972
1000
 
973
- The installer will:
974
- 1. Install dependencies and build the project
975
- 2. Ask whether to configure Claude Desktop, Claude Code, or both
976
- 3. Create a configuration file with a placeholder
977
- 4. **Manually add** your 24-word backup phrase to the configuration file
978
- 5. Restart Claude
1001
+ Instalátor:
1002
+ 1. Nainstaluje závislosti a sestaví projekt
1003
+ 2. Zeptá se, zda chcete nakonfigurovat Claude Desktop, Claude Code nebo obojí
1004
+ 3. Vytvoří konfigurační soubor s placeholderem
1005
+ 4. **Ručně doplňte** svou 24slovnou zálohovací frázi do konfiguračního souboru
1006
+ 5. Restartujte Claude
979
1007
 
980
- ### Manual installation
1008
+ #### Manuální instalace
981
1009
 
982
- 1. Install dependencies:
1010
+ 1. Nainstalujte závislosti:
983
1011
  ```bash
984
1012
  npm install
985
1013
  npm run build
986
1014
  ```
987
1015
 
988
- 2. Add to configuration:
1016
+ 2. Přidejte do konfigurace:
989
1017
 
990
- **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
1018
+ **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
991
1019
 
992
1020
  ```json
993
1021
  {
994
1022
  "mcpServers": {
995
1023
  "todocko": {
996
1024
  "command": "node",
997
- "args": ["/path/to/mcp-server/dist/index.js"],
1025
+ "args": ["/cesta/k/mcp-server/dist/index.js"],
998
1026
  "env": {
999
- "TODOCKO_MNEMONIC": "your 24 word backup phrase"
1027
+ "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
1000
1028
  }
1001
1029
  }
1002
1030
  }
1003
1031
  }
1004
1032
  ```
1005
1033
 
1006
- **Claude Code (CLI)** - add to `~/.claude/settings.json`:
1034
+ **Claude Code (CLI)** - přidejte do `~/.claude/settings.json`:
1007
1035
 
1008
1036
  ```json
1009
1037
  {
1010
1038
  "mcpServers": {
1011
1039
  "todocko": {
1012
1040
  "command": "node",
1013
- "args": ["/path/to/mcp-server/dist/index.js"],
1041
+ "args": ["/cesta/k/mcp-server/dist/index.js"],
1014
1042
  "env": {
1015
- "TODOCKO_MNEMONIC": "your 24 word backup phrase"
1043
+ "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
1016
1044
  }
1017
1045
  }
1018
1046
  }
1019
1047
  }
1020
1048
  ```
1021
1049
 
1022
- 3. Restart Claude Desktop / Claude Code
1050
+ 3. Restartujte Claude Desktop / Claude Code
1023
1051
 
1024
- ## Available Tools (161)
1052
+ ## Dostupné nástroje (161)
1025
1053
 
1026
- ### Projects
1054
+ ### Projekty
1027
1055
 
1028
- | Tool | Description |
1029
- |------|-------------|
1030
- | `td_list_projects` | List all projects |
1031
- | `td_get_project` | Get project details by ID or code |
1032
- | `td_create_project` | Create a new project (code: `A-Z` and `0-9` only, as in the app) |
1033
- | `td_update_project` | Update a project (name, code, color, isArchived, isHiddenFromFilters; code `A-Z` and `0-9` only). `autoApproveMembers` belongs to the shared project and is refused here, see `td_update_shared_project` |
1034
- | `td_delete_project` | Delete a project (soft delete) |
1056
+ | Nástroj | Popis |
1057
+ |---------|-------|
1058
+ | `td_list_projects` | Seznam všech projektů |
1059
+ | `td_get_project` | Detail projektu podle ID nebo kódu |
1060
+ | `td_create_project` | Vytvoření nového projektu (kód jen `A-Z` a `0-9`, jako v appce) |
1061
+ | `td_update_project` | Aktualizace projektu (name, code, color, isArchived, isHiddenFromFilters; kód jen `A-Z` a `0-9`). `autoApproveMembers` patří sdílenému projektu, tady se odmítne, viz `td_update_shared_project` |
1062
+ | `td_delete_project` | Smazání projektu (soft delete) |
1035
1063
 
1036
- ### Tasks
1064
+ ### Úkoly
1037
1065
 
1038
- | Tool | Description |
1039
- |------|-------------|
1040
- | `td_list_tasks` | List tasks with filters (project, status, priority, assignee) |
1041
- | `td_get_task` | Get task details by ID or code (e.g., `PROJ-123`), recurrence settings included |
1042
- | `td_create_task` | Create a new task (with recurrence, sprint, parentTaskId support) |
1043
- | `td_update_task` | Update an existing task (with recurrence, sprint, parentTaskId support) |
1044
- | `td_search_tasks` | Search tasks by text |
1045
- | `td_bulk_update_tasks` | Bulk update multiple tasks |
1046
- | `td_bulk_delete_tasks` | Bulk delete multiple tasks |
1047
- | `td_delete_task` | Soft-delete a single personal task (cascades to its worklogs and attachments). |
1048
- | `td_list_git_events` | List git events (push, PR opened/merged/closed) for a task by its code. |
1066
+ | Nástroj | Popis |
1067
+ |---------|-------|
1068
+ | `td_list_tasks` | Seznam úkolů s filtry (projekt, status, priorita, assignee) |
1069
+ | `td_get_task` | Detail úkolu podle ID nebo kódu (např. `PROJ-123`), včetně nastavení opakování |
1070
+ | `td_create_task` | Vytvoření nového úkolu (včetně recurrence, sprintNumber, parentTaskId) |
1071
+ | `td_update_task` | Aktualizace existujícího úkolu (včetně recurrence, sprintNumber, parentTaskId) |
1072
+ | `td_search_tasks` | Vyhledávání úkolů podle textu |
1073
+ | `td_bulk_update_tasks` | Hromadná aktualizace více úkolů (včetně sprintNumber) |
1074
+ | `td_bulk_delete_tasks` | Hromadné smazání více úkolů |
1075
+ | `td_delete_task` | Smazání jednoho úkolu (soft delete, kaskáda na worklogy a přílohy) |
1076
+ | `td_list_git_events` | Git aktivita pro úkol (commits, PR) z relay serveru |
1049
1077
 
1050
- ### Users
1078
+ ### Uživatelé
1051
1079
 
1052
- | Tool | Description |
1053
- |------|-------------|
1054
- | `td_list_users` | List all users |
1055
- | `td_get_user` | Get user details |
1056
- | `td_create_user` | Create a new user |
1057
- | `td_update_user` | Update a user |
1058
- | `td_delete_user` | Delete a user (soft delete) |
1080
+ | Nástroj | Popis |
1081
+ |---------|-------|
1082
+ | `td_list_users` | Seznam všech uživatelů |
1083
+ | `td_get_user` | Detail uživatele |
1084
+ | `td_create_user` | Vytvoření nového uživatele |
1085
+ | `td_update_user` | Aktualizace uživatele |
1086
+ | `td_delete_user` | Smazání uživatele (soft delete) |
1059
1087
 
1060
- ### Worklogs
1088
+ ### Worklogy
1061
1089
 
1062
- | Tool | Description |
1063
- |------|-------------|
1064
- | `td_list_worklogs` | List worklogs for a task |
1065
- | `td_add_worklog` | Add a worklog to a task |
1066
- | `td_update_worklog` | Update a worklog |
1067
- | `td_delete_worklog` | Delete a worklog (soft delete) |
1090
+ | Nástroj | Popis |
1091
+ |---------|-------|
1092
+ | `td_list_worklogs` | Seznam worklogů pro úkol |
1093
+ | `td_add_worklog` | Přidání worklogu k úkolu |
1094
+ | `td_update_worklog` | Aktualizace worklogu |
1095
+ | `td_delete_worklog` | Smazání worklogu (soft delete) |
1068
1096
 
1069
- ### Attachments
1097
+ ### Přílohy
1070
1098
 
1071
- | Tool | Description |
1072
- |------|-------------|
1073
- | `td_upload_attachment` | Upload an attachment to a task (from file or base64) |
1074
- | `td_list_attachments` | List attachments for a task |
1075
- | `td_download_attachment` | Download an attachment |
1076
- | `td_delete_attachment` | Delete an attachment |
1077
- | `td_upload_note_attachment` | Upload an attachment to a local project note |
1078
- | `td_list_note_attachments` | List attachments of a local note |
1079
- | `td_download_note_attachment` | Download a note attachment |
1080
- | `td_delete_note_attachment` | Delete a note attachment |
1099
+ | Nástroj | Popis |
1100
+ |---------|-------|
1101
+ | `td_upload_attachment` | Nahrání přílohy k úkolu (ze souboru nebo base64) |
1102
+ | `td_list_attachments` | Seznam příloh úkolu |
1103
+ | `td_download_attachment` | Stažení přílohy |
1104
+ | `td_delete_attachment` | Smazání přílohy |
1105
+ | `td_upload_note_attachment` | Nahrání přílohy k lokální poznámce projektu |
1106
+ | `td_list_note_attachments` | Seznam příloh lokální poznámky |
1107
+ | `td_download_note_attachment` | Stažení přílohy poznámky |
1108
+ | `td_delete_note_attachment` | Smazání přílohy poznámky |
1081
1109
 
1082
- ### Comments
1110
+ ### Komentáře
1083
1111
 
1084
- | Tool | Description |
1085
- |------|-------------|
1086
- | `td_list_task_comments` | List comments for a task |
1087
- | `td_create_task_comment` | Add a comment to a task |
1088
- | `td_update_task_comment` | Update a comment |
1089
- | `td_delete_task_comment` | Delete a comment (soft delete) |
1112
+ | Nástroj | Popis |
1113
+ |---------|-------|
1114
+ | `td_list_task_comments` | Seznam komentářů k úkolu |
1115
+ | `td_create_task_comment` | Přidání komentáře k úkolu |
1116
+ | `td_update_task_comment` | Úprava komentáře |
1117
+ | `td_delete_task_comment` | Smazání komentáře (soft delete) |
1090
1118
 
1091
1119
  ### Checklist
1092
1120
 
1093
- | Tool | Description |
1094
- |------|-------------|
1095
- | `td_list_checklist_items` | List checklist items for a task |
1096
- | `td_create_checklist_item` | Add a checklist item |
1097
- | `td_update_checklist_item` | Update a checklist item (check, reposition) |
1098
- | `td_delete_checklist_item` | Delete a checklist item (soft delete) |
1121
+ | Nástroj | Popis |
1122
+ |---------|-------|
1123
+ | `td_list_checklist_items` | Seznam položek checklistu úkolu |
1124
+ | `td_create_checklist_item` | Přidání položky checklistu |
1125
+ | `td_update_checklist_item` | Aktualizace položky (zaškrtnutí, pozice) |
1126
+ | `td_delete_checklist_item` | Smazání položky (soft delete) |
1099
1127
 
1100
- ### Mentions
1128
+ ### Zmínky (mentions)
1101
1129
 
1102
- | Tool | Description |
1103
- |------|-------------|
1104
- | `td_list_mentions` | List mentions for a user |
1105
- | `td_create_mention` | Create a mention |
1106
- | `td_mark_mention_read` | Mark a mention as read |
1107
- | `td_mark_all_mentions_read` | Mark all mentions as read |
1108
- | `td_delete_mention` | Delete a mention (soft delete) |
1130
+ | Nástroj | Popis |
1131
+ |---------|-------|
1132
+ | `td_list_mentions` | Seznam zmínek uživatele |
1133
+ | `td_create_mention` | Vytvoření zmínky |
1134
+ | `td_mark_mention_read` | Označení zmínky jako přečtené |
1135
+ | `td_mark_all_mentions_read` | Označení všech zmínek jako přečtených |
1136
+ | `td_delete_mention` | Smazání zmínky (soft delete) |
1109
1137
 
1110
- ### Task Links
1138
+ ### Linky mezi úkoly
1111
1139
 
1112
- | Tool | Description |
1113
- |------|-------------|
1114
- | `td_list_app_settings` | Account settings that follow the user across devices |
1115
- | `td_set_app_setting` | Set one account setting |
1116
- | `td_list_task_links` | List links for a task |
1117
- | `td_create_task_link` | Create a link between tasks (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
1118
- | `td_delete_task_link` | Delete a task link (soft delete) |
1140
+ | Nástroj | Popis |
1141
+ |---------|-------|
1142
+ | `td_list_app_settings` | Nastavení účtu, která se přenášejí mezi zařízeními |
1143
+ | `td_set_app_setting` | Nastavení jedné hodnoty na účtu |
1144
+ | `td_list_task_links` | Seznam linků úkolu |
1145
+ | `td_create_task_link` | Vytvoření linku mezi úkoly (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
1146
+ | `td_delete_task_link` | Smazání linku (soft delete) |
1119
1147
 
1120
- ### Tags
1148
+ ### Tagy
1121
1149
 
1122
- | Tool | Description |
1123
- |------|-------------|
1124
- | `td_list_tags` | List tags; returns `projectId`, filters by project or unassigned |
1125
- | `td_create_tag` | Create a tag — **pass `projectId`**, see the note below |
1126
- | `td_update_tag` | Rename, recolour, assign to a project, or mark default |
1127
- | `td_delete_tag` | Delete a tag (soft delete) |
1128
- | `td_list_task_tags` | List tags assigned to a task |
1129
- | `td_add_tag_to_task` | Assign a tag to a task |
1130
- | `td_remove_tag_from_task` | Remove a tag from a task |
1150
+ | Nástroj | Popis |
1151
+ |---------|-------|
1152
+ | `td_list_tags` | Seznam štítků; vrací `projectId`, umí filtrovat podle projektu i na nezařazené |
1153
+ | `td_create_tag` | Vytvoření štítku – **předej `projectId`**, viz poznámku níž |
1154
+ | `td_update_tag` | Přejmenování, změna barvy, přiřazení projektu, nebo příznak výchozího štítku |
1155
+ | `td_delete_tag` | Smazání štítku (soft delete) |
1156
+ | `td_list_task_tags` | Seznam štítků přiřazených k úkolu |
1157
+ | `td_add_tag_to_task` | Přiřazení štítku k úkolu |
1158
+ | `td_remove_tag_from_task` | Odebrání štítku z úkolu |
1131
1159
 
1132
- Shared projects (TODO-235):
1160
+ Sdílené projekty (TODO-235):
1133
1161
 
1134
- | Tool | Description |
1135
- |------|-------------|
1136
- | `td_list_shared_tags` | Tags in a shared project |
1137
- | `td_create_shared_tag` | Create a tag in a shared project |
1138
- | `td_update_shared_tag` | Rename / recolour |
1139
- | `td_delete_shared_tag` | Delete (soft delete) |
1140
- | `td_add_shared_tag_to_task` | Assign to a task in a shared project |
1141
- | `td_remove_shared_tag_from_task` | Remove from a task |
1162
+ | Nástroj | Popis |
1163
+ |---------|-------|
1164
+ | `td_list_shared_tags` | Štítky ve sdíleném projektu |
1165
+ | `td_create_shared_tag` | Vytvoření štítku ve sdíleném projektu |
1166
+ | `td_update_shared_tag` | Přejmenování / změna barvy / příznak výchozího štítku |
1167
+ | `td_delete_shared_tag` | Smazání (soft delete) |
1168
+ | `td_add_shared_tag_to_task` | Přiřazení k úkolu ve sdíleném projektu |
1169
+ | `td_remove_shared_tag_from_task` | Odebrání z úkolu |
1142
1170
 
1143
- > **A tag without a project is never offered by the app.** Since TODO-227 tags
1144
- > belong to a project; `td_create_tag` without `projectId` makes an **unassigned**
1145
- > tag, which shows up only under "Nezařazené" in project settings with a button to
1146
- > adopt it. The tool response says so. Fix it afterwards with `td_update_tag` and
1147
- > a `projectId`.
1171
+ > **Štítek bez projektu appka nikde nenabídne.** Od TODO-227 jsou štítky vázané
1172
+ > na projekt; `td_create_tag` bez `projectId` vyrobí **nezařazený** štítek, který
1173
+ > se v appce objeví jen v nastavení projektu v sekci „Nezařazené" s tlačítkem na
1174
+ > přiřazení. Odpověď nástroje na to upozorní. Dodatečně to spraví
1175
+ > `td_update_tag` s `projectId`.
1148
1176
  >
1149
- > **Free-tier limits (TODO-243).** Tier caps belong to the app, not here.
1150
- > `td_create_task` and `td_create_project` append a warning with the real count
1151
- > when the owner is on the free tier and above its cap (1 project, 50 **active**
1152
- > tasks), so that it is learned at creation time rather than later in the app, and
1153
- > so that the text makes clear nothing was lost. **Nothing is blocked**, and with
1154
- > an unknown tier (unreachable relay) it stays silent — a false alarm is worse
1155
- > than none.
1177
+ > **Limity free tarifu (TODO-243).** Tarifní limity patří do appky, ne sem.
1178
+ > `td_create_task` a `td_create_project` proto do odpovědi přilepí varování
1179
+ > s reálným počtem, když je owner na free tarifu a je nad limitem (1 projekt,
1180
+ > 50 **aktivních** úkolů). Jde o to, aby se to člověk dozvěděl při zakládání, ne až
1181
+ > zpětně v appce, a aby z textu bylo jasné, že o nic nepřišel. **Nic to neblokuje**
1182
+ > a při neznámém tarifu (nedostupný relay) radši mlčí – falešný poplach je horší
1183
+ > než žádný.
1156
1184
 
1157
- > **Default tags (TODO-239).** `isDefault` on `td_create_tag` / `td_update_tag`
1158
- > (and the shared variants) means every task newly created in the project gets the
1159
- > tag. Both `td_create_task` and `td_create_shared_task` apply them and report them
1160
- > back in `appliedTags` — the app pre-ticks them in its form, so without this the
1161
- > result would depend on where the task was created. Existing tasks are untouched.
1185
+ > **Výchozí štítky (TODO-239).** `isDefault` u `td_create_tag` / `td_update_tag`
1186
+ > (a sdílených variant) znamená, že štítek dostane **každý nově zakládaný úkol**
1187
+ > projektu. `td_create_task` i `td_create_shared_task` je přidávají samy a vrátí
1188
+ > je v `appliedTags` – appka je předzaškrtává v modalu, takže bez toho by výsledek
1189
+ > závisel na tom, odkud úkol vznikne. Existujících úkolů se to nedotkne.
1162
1190
  >
1163
- > Shared projects write to a **different Evolu instance**, hence the separate set
1164
- > — `td_add_tag_to_task` does not work on a shared task.
1191
+ > Ve sdílených projektech se zapisuje do **jiné Evolu instance**, proto samostatná
1192
+ > sada nástrojů – `td_add_tag_to_task` na sdílený úkol nefunguje.
1165
1193
 
1166
- ### Task Templates
1194
+ ### Šablony úkolů
1167
1195
 
1168
- | Tool | Description |
1169
- |------|-------------|
1170
- | `td_list_task_templates` | List task templates |
1171
- | `td_create_task_template` | Create a task template (optional `checklistItems` and `tagIds`) |
1172
- | `td_update_task_template` | Update a task template (`checklistItems`, `tagIds`; empty array clears) |
1173
- | `td_delete_task_template` | Delete a task template (soft delete) |
1196
+ | Nástroj | Popis |
1197
+ |---------|-------|
1198
+ | `td_list_task_templates` | Seznam šablon úkolů |
1199
+ | `td_create_task_template` | Vytvoření šablony (volitelně `checklistItems` a `tagIds`) |
1200
+ | `td_update_task_template` | Aktualizace šablony (`checklistItems`, `tagIds`; prázdné pole maže) |
1201
+ | `td_delete_task_template` | Smazání šablony (soft delete) |
1202
+
1203
+ ### Kanban sloupce
1204
+
1205
+ | Nástroj | Popis |
1206
+ |---------|-------|
1207
+ | `td_list_kanban_columns` | Seznam kanban sloupců |
1208
+ | `td_create_kanban_column` | Vytvoření sloupce (volitelně `wipLimit`, max. úkolů na uživatele v In progress před varováním v hlavičce) |
1209
+ | `td_update_kanban_column` | Aktualizace sloupce (`wipLimit: null` limit zruší) |
1210
+ | `td_delete_kanban_column` | Smazání sloupce (soft delete) |
1174
1211
 
1175
- ### Kanban Columns
1212
+ ### Uložená zobrazení
1176
1213
 
1177
- | Tool | Description |
1178
- |------|-------------|
1179
- | `td_list_kanban_columns` | List kanban columns |
1180
- | `td_create_kanban_column` | Create a kanban column (optional `wipLimit`, max tasks per user in In progress before the header warns) |
1181
- | `td_update_kanban_column` | Update a kanban column (`wipLimit: null` clears the limit) |
1182
- | `td_delete_kanban_column` | Delete a kanban column (soft delete) |
1214
+ | Nástroj | Popis |
1215
+ |---------|-------|
1216
+ | `td_list_saved_views` | Seznam uložených zobrazení |
1217
+ | `td_create_saved_view` | Vytvoření zobrazení |
1218
+ | `td_update_saved_view` | Aktualizace zobrazení |
1219
+ | `td_delete_saved_view` | Smazání zobrazení (soft delete) |
1183
1220
 
1184
- ### Saved Views
1221
+ ### Aktivita
1185
1222
 
1186
- | Tool | Description |
1187
- |------|-------------|
1188
- | `td_list_saved_views` | List saved views |
1189
- | `td_create_saved_view` | Create a saved view |
1190
- | `td_update_saved_view` | Update a saved view |
1191
- | `td_delete_saved_view` | Delete a saved view (soft delete) |
1223
+ | Nástroj | Popis |
1224
+ |---------|-------|
1225
+ | `td_list_activity_log` | Seznam zápisů aktivity s filtry (úkol, aktor, akce, typ entity, datum od/do) – read-only |
1192
1226
 
1193
- ### Activity Log
1227
+ ### Poznámky k projektu
1194
1228
 
1195
- | Tool | Description |
1196
- |------|-------------|
1197
- | `td_list_activity_log` | List activity log entries with filters (task, actor, action, entityType, date from/to) — read-only |
1229
+ | Nástroj | Popis |
1230
+ |---------|-------|
1231
+ | `td_list_project_notes` | Seznam lokálních poznámek projektu (rejstřík: titulek a `contentLength`, obsah až na `includeContent`) |
1232
+ | `td_get_project_note` | Jedna lokální poznámka včetně obsahu |
1233
+ | `td_create_project_note` | Vytvoření lokální poznámky |
1234
+ | `td_update_project_note` | Aktualizace lokální poznámky |
1235
+ | `td_delete_project_note` | Smazání lokální poznámky (soft delete) |
1198
1236
 
1199
- ### Project Notes
1237
+ ### Dokumentace projektu
1200
1238
 
1201
- | Tool | Description |
1202
- |------|-------------|
1203
- | `td_list_project_notes` | List local project notes (index: title and `contentLength`; content via `includeContent`) |
1204
- | `td_get_project_note` | Read one local project note, with its content |
1205
- | `td_create_project_note` | Create a local project note |
1206
- | `td_update_project_note` | Update a local project note |
1207
- | `td_delete_project_note` | Delete a local project note (soft delete) |
1239
+ Dokumenty jsou poznámky s `isDoc`, takže mohou být zanořené pod jiný dokument
1240
+ (`parentDocId`).
1208
1241
 
1209
- ### Deployment Stages
1242
+ | Nástroj | Popis |
1243
+ |---------|-------|
1244
+ | `td_list_project_docs` | Seznam dokumentů projektu (rejstřík: titulek, hierarchie a `contentLength`, obsah až na `includeContent`) |
1245
+ | `td_get_project_doc` | Jedna stránka dokumentace včetně obsahu |
1246
+ | `td_create_project_doc` | Vytvoření dokumentu |
1247
+ | `td_update_project_doc` | Aktualizace dokumentu |
1248
+ | `td_delete_project_doc` | Smazání dokumentu (soft delete) |
1210
1249
 
1211
- | Tool | Description |
1212
- |------|-------------|
1213
- | `td_list_deployment_stages` | List deployment stages for a project |
1214
- | `td_create_deployment_stage` | Create a deployment stage for a personal project. |
1215
- | `td_update_deployment_stage` | Update a deployment stage in a personal project. |
1216
- | `td_delete_deployment_stage` | Soft-delete a deployment stage in a personal project. |
1250
+ ### Systémová oznámení (relay)
1217
1251
 
1218
- ### Repository Links
1252
+ Broadcast oznámení pro všechny uživatele. Zápis a výpis včetně expirovaných
1253
+ vyžaduje `TODOCKO_RELAY_ADMIN_KEY`; obráceným směrem jdou zprávy od uživatelů,
1254
+ viz níž.
1219
1255
 
1220
- | Tool | Description |
1221
- |------|-------------|
1222
- | `td_list_repository_links` | List repository links |
1223
- | `td_create_repository_link` | Create a repository link |
1224
- | `td_delete_repository_link` | Delete a repository link |
1225
- | `td_update_repository_link` | Update a repository link for a project. |
1256
+ Bez `TODOCKO_RELAY_ADMIN_KEY` se `td_create_system_notification`
1257
+ a `td_delete_system_notification` klientovi vůbec nenabízejí (nemohly by nic
1258
+ jiného než vrátit 401) a u výpisu zmizí přepínač `admin`. Klíč se navíc nikdy
1259
+ neposílá přes nešifrované `http://` jinam než na localhost. (TODO-441)
1226
1260
 
1227
- ### Shared Projects
1261
+ | Nástroj | Popis |
1262
+ |---------|-------|
1263
+ | `td_list_system_notifications` | Seznam aktivních oznámení (s `admin: true` i expirovaná) |
1264
+ | `td_create_system_notification` | Vytvoření oznámení pro všechny uživatele |
1265
+ | `td_delete_system_notification` | Smazání oznámení |
1228
1266
 
1229
- | Tool | Description |
1230
- |------|-------------|
1231
- | `td_list_shared_projects` | List shared projects with your permission (no longer returns `ownerSecret`) |
1232
- | `td_list_shared_tasks` | List tasks from a shared project |
1233
- | `td_update_shared_task` | Update a task in a shared project |
1234
- | `td_list_shared_deployment_stages` | List deployment stages for a shared project |
1235
- | `td_create_shared_deployment_stage` | Create a deployment stage in a shared project |
1236
- | `td_list_shared_repository_links` | List repository links for a shared project |
1237
- | `td_create_shared_repository_link` | Create a repository link in a shared project |
1238
- | `td_list_shared_project_notes` | List notes for a shared project (index; content via `includeContent`) |
1239
- | `td_get_shared_project_note` | Read one note from a shared project, with its content |
1240
- | `td_create_shared_project_note` | Create a note in a shared project |
1241
- | `td_update_shared_project_note` | Update a note in a shared project |
1242
- | `td_delete_shared_project_note` | Delete a note in a shared project |
1243
- | `td_list_shared_members` | List members of a shared project (name, permission, kicked/blocked state, `isPending` = waiting for approval). The owner also gets `verifiedPermission` (what they granted) and `effectivePermission` (the lower of the two, which decides the write key) |
1244
- | `td_update_shared_member` | Admin only. Change permission between `write` and `admin`, approve a pending join or unblock (only while the project has no rotated write key); refuses block, kick, reject and downgrade to `read`, which belong in the app. A permission set by the owner is also recorded as their `memberGrant`, which is what hands out the write key; an admin who does not own the project changes only the member's claim |
1245
- | `td_upload_shared_note_attachment` | Upload an attachment to a shared project note |
1246
- | `td_list_shared_note_attachments` | List attachments of a shared project note |
1247
- | `td_download_shared_note_attachment` | Download a shared note attachment |
1248
- | `td_delete_shared_note_attachment` | Delete a shared note attachment |
1249
- | `td_list_shared_project_docs` | List document pages from a shared project (index; content via `includeContent`) |
1250
- | `td_get_shared_project_doc` | Read one document page from a shared project, with its content |
1251
- | `td_create_shared_project_doc` | Create a document page in a shared project |
1252
- | `td_update_shared_project_doc` | Update a document page in a shared project |
1253
- | `td_delete_shared_project_doc` | Delete a document page in a shared project (soft delete) |
1254
- | `td_create_shared_task` | Create a task in a shared project. |
1255
- | `td_delete_shared_task` | Soft-delete a task in a shared project (cascades to its checklist items and comments). |
1256
- | `td_list_shared_worklogs` | List worklogs for a task in a shared project. |
1257
- | `td_add_shared_worklog` | Add a worklog to a task in a shared project. |
1258
- | `td_delete_shared_worklog` | Soft-delete a worklog in a shared project. |
1259
- | `td_list_shared_checklist_items` | List checklist items for a task in a shared project. |
1260
- | `td_create_shared_checklist_item` | Create a checklist item on a task in a shared project. |
1261
- | `td_update_shared_checklist_item` | Update a checklist item in a shared project (toggle done, rename, reorder). |
1262
- | `td_delete_shared_checklist_item` | Soft-delete a checklist item in a shared project. |
1263
- | `td_list_shared_task_links` | List dependency links for a task in a shared project. |
1264
- | `td_create_shared_task_link` | Create a dependency link between tasks in a shared project. |
1265
- | `td_delete_shared_task_link` | Delete a dependency link in a shared project (soft delete). |
1266
- | `td_list_shared_task_comments` | List comments for a task in a shared project. |
1267
- | `td_create_shared_task_comment` | Add a comment to a task in a shared project. |
1268
- | `td_update_shared_task_comment` | Update a comment in a shared project. |
1269
- | `td_delete_shared_task_comment` | Soft-delete a comment in a shared project. |
1270
- | `td_update_shared_repository_link` | Update a repository link in a shared project. |
1271
- | `td_delete_shared_repository_link` | Soft-delete a repository link in a shared project. |
1272
- | `td_update_shared_deployment_stage` | Update a deployment stage in a shared project. |
1273
- | `td_delete_shared_deployment_stage` | Soft-delete a deployment stage in a shared project. |
1274
- | `td_update_shared_project` | Update shared-project metadata (archive / hide from filters). |
1275
- | `td_upload_shared_attachment` | Upload a file attachment to a task in a shared project. |
1276
- | `td_list_shared_attachments` | List file attachments of a task in a shared project (metadata only, no data). |
1277
- | `td_download_shared_attachment` | Download a task attachment from a shared project. |
1278
- | `td_delete_shared_attachment` | Soft-delete a task attachment in a shared project. |
1279
- | `td_get_shared_task` | Get one task in a shared project by ID or code, with its worklog total, checklist and comment counts. |
1280
- | `td_list_shared_task_tags` | List the tags on a task in a shared project. |
1281
- | `td_bulk_update_shared_tasks` | Update several tasks in a shared project at once. |
1282
- | `td_bulk_delete_shared_tasks` | Soft-delete several tasks in a shared project at once, cascading their checklist items and comments. |
1283
- | `td_update_shared_worklog` | Update a worklog in a shared project. |
1284
- | `td_list_shared_activity_log` | List activity log entries for a shared project. |
1267
+ ### Deployment stages
1285
1268
 
1286
- > **Permissions, `ownerSecret` and history in shared projects (TODO-434).**
1287
- >
1288
- > - **`ownerSecret` is optional; leave it out.** Every shared tool looks it up
1289
- > from your `projectRef` by `sharedOwnerId`, and `td_list_shared_projects` no
1290
- > longer returns it. The secret is the key to the whole project, so it used
1291
- > to sit in the model's context and every transcript. Passing it still works
1292
- > and is checked against `sharedOwnerId`.
1293
- > - **Writes are gated by permission, as in the app** (`src/permissions.ts`, a
1294
- > port of the app's `permissions.ts`). Tasks, worklogs, checklist items,
1295
- > comments, attachments, links, tag assignment, notes and documents need
1296
- > `write` or `admin`. Project settings (`td_update_shared_project`, delete and
1297
- > restore included), deployment stages, repository links, tag management and
1298
- > members need the owner or `admin`. Without a `projectRef` writes are
1299
- > refused, reads still work. A refusal is an error and nothing is written.
1300
- > - **Member management is partial.** After every member change the app rotates
1301
- > the write key or hands the current one over, otherwise a blocked member keeps
1302
- > writing. The MCP cannot rotate, so changes that leave the member unable to
1303
- > write (block, kick, reject, downgrade to `read`) are refused with a pointer
1304
- > to the app. Approving, unblocking and upgrading pass only while the project
1305
- > has no rotated write key.
1306
- > - **Shared writes record history** in the shared instance, the same entries
1307
- > the app writes (task created / updated per field / deleted, worklog,
1308
- > checklist, comment, attachment, tag, stage, repository link, project,
1309
- > member), with your account as `actorId` and `source: "mcp"` in metadata.
1310
- > - **Deleting an unknown id** is an error instead of `success`, and bulk delete
1311
- > counts it as skipped. `td_update_shared_project` picks the project row the
1312
- > way the app does (oldest live row) and can restore it from the Trash.
1313
- > - **Project codes** may contain only `A-Z` and `0-9`, and concurrent
1314
- > `td_create_task` / `td_create_shared_task` calls for one project no longer
1315
- > get the same code.
1269
+ | Nástroj | Popis |
1270
+ |---------|-------|
1271
+ | `td_list_deployment_stages` | Seznam deployment stages pro projekt |
1272
+ | `td_create_deployment_stage` | Vytvoření deployment stage |
1273
+ | `td_update_deployment_stage` | Aktualizace deployment stage |
1274
+ | `td_delete_deployment_stage` | Smazání deployment stage (soft delete) |
1316
1275
 
1317
- ### Project Documentation
1276
+ ### Repository linky
1318
1277
 
1319
- Documents are notes with `isDoc`, so they can nest under another document via `parentDocId`.
1278
+ | Nástroj | Popis |
1279
+ |---------|-------|
1280
+ | `td_list_repository_links` | Seznam repozitářových linků |
1281
+ | `td_create_repository_link` | Vytvoření repozitářového linku |
1282
+ | `td_update_repository_link` | Aktualizace repozitářového linku |
1283
+ | `td_delete_repository_link` | Smazání repozitářového linku |
1320
1284
 
1321
- | Tool | Description |
1322
- |------|-------------|
1323
- | `td_list_project_docs` | List local project document pages (index: title, hierarchy and `contentLength`; content via `includeContent`) |
1324
- | `td_get_project_doc` | Read one local project document page, with its content |
1325
- | `td_create_project_doc` | Create a local project document page |
1326
- | `td_update_project_doc` | Update a local project document page |
1327
- | `td_delete_project_doc` | Delete a local project document page (soft delete) |
1285
+ ### Sdílené projekty
1328
1286
 
1329
- ### System Notifications (relay)
1287
+ | Nástroj | Popis |
1288
+ |---------|-------|
1289
+ | `td_list_shared_projects` | Seznam sdílených projektů s vaším oprávněním (`ownerSecret` už nevrací) |
1290
+ | `td_list_shared_tasks` | Seznam úkolů ze sdíleného projektu |
1291
+ | `td_create_shared_task` | Vytvoření úkolu ve sdíleném projektu (auto-generovaný kód) |
1292
+ | `td_update_shared_task` | Aktualizace úkolu ve sdíleném projektu (všechna pole včetně recurrence, estimate, blocking) |
1293
+ | `td_delete_shared_task` | Smazání úkolu ve sdíleném projektu (soft delete, kaskáda na checklist) |
1294
+ | `td_update_shared_project` | Aktualizace sdíleného projektu: název, kód, barva, archivace, skrytí z filtrů, automatické schvalování členů |
1295
+ | `td_list_shared_worklogs` | Seznam worklogů úkolu ve sdíleném projektu |
1296
+ | `td_add_shared_worklog` | Přidání worklogu k úkolu ve sdíleném projektu |
1297
+ | `td_delete_shared_worklog` | Smazání worklogu ve sdíleném projektu |
1298
+ | `td_list_shared_checklist_items` | Seznam položek checklistu úkolu ve sdíleném projektu |
1299
+ | `td_create_shared_checklist_item` | Přidání položky checklistu ve sdíleném projektu |
1300
+ | `td_update_shared_checklist_item` | Aktualizace položky checklistu ve sdíleném projektu |
1301
+ | `td_delete_shared_checklist_item` | Smazání položky checklistu ve sdíleném projektu |
1302
+ | `td_list_shared_task_links` | Seznam vazeb úkolu ve sdíleném projektu |
1303
+ | `td_create_shared_task_link` | Vytvoření vazby mezi úkoly ve sdíleném projektu |
1304
+ | `td_delete_shared_task_link` | Smazání vazby ve sdíleném projektu (soft delete) |
1305
+ | `td_list_shared_task_comments` | Seznam komentářů úkolu ve sdíleném projektu |
1306
+ | `td_create_shared_task_comment` | Přidání komentáře k úkolu ve sdíleném projektu |
1307
+ | `td_update_shared_task_comment` | Aktualizace komentáře ve sdíleném projektu |
1308
+ | `td_delete_shared_task_comment` | Smazání komentáře ve sdíleném projektu |
1309
+ | `td_upload_shared_attachment` | Nahrání přílohy k úkolu ve sdíleném projektu |
1310
+ | `td_list_shared_attachments` | Seznam příloh úkolu ve sdíleném projektu |
1311
+ | `td_download_shared_attachment` | Stažení přílohy úkolu sdíleného projektu |
1312
+ | `td_delete_shared_attachment` | Smazání přílohy úkolu sdíleného projektu |
1313
+ | `td_list_shared_deployment_stages` | Seznam deployment stages pro sdílený projekt |
1314
+ | `td_create_shared_deployment_stage` | Vytvoření deployment stage ve sdíleném projektu |
1315
+ | `td_update_shared_deployment_stage` | Aktualizace deployment stage ve sdíleném projektu |
1316
+ | `td_delete_shared_deployment_stage` | Smazání deployment stage ve sdíleném projektu |
1317
+ | `td_list_shared_repository_links` | Seznam repozitářových linků sdíleného projektu |
1318
+ | `td_create_shared_repository_link` | Vytvoření repozitářového linku ve sdíleném projektu |
1319
+ | `td_update_shared_repository_link` | Aktualizace repozitářového linku ve sdíleném projektu |
1320
+ | `td_delete_shared_repository_link` | Smazání repozitářového linku ve sdíleném projektu |
1321
+ | `td_list_shared_project_notes` | Seznam poznámek sdíleného projektu (rejstřík, obsah až na `includeContent`) |
1322
+ | `td_get_shared_project_note` | Jedna poznámka sdíleného projektu včetně obsahu |
1323
+ | `td_create_shared_project_note` | Vytvoření poznámky ve sdíleném projektu |
1324
+ | `td_update_shared_project_note` | Aktualizace poznámky ve sdíleném projektu |
1325
+ | `td_delete_shared_project_note` | Smazání poznámky ve sdíleném projektu |
1326
+ | `td_list_shared_members` | Seznam členů sdíleného projektu (jméno, oprávnění, kicked/blocked stav, `isPending` = čeká na schválení). Vlastníkovi navíc `verifiedPermission` (co udělil) a `effectivePermission` (to nižší z obojího, rozhoduje o write key) |
1327
+ | `td_update_shared_member` | Jen admin. Změna oprávnění mezi `write` a `admin`, schválení čekajícího nebo odblokování (jen dokud projekt nemá rotovaný klíč); block, kick, zamítnutí a snížení na `read` odmítne, ty patří do appky. Oprávnění nastavené vlastníkem se zapíše i jako jeho `memberGrant`, což teprve rozdává write key; admin bez vlastnictví změní jen členův nárok |
1328
+ | `td_upload_shared_note_attachment` | Nahrání přílohy k poznámce sdíleného projektu |
1329
+ | `td_list_shared_note_attachments` | Seznam příloh poznámky sdíleného projektu |
1330
+ | `td_download_shared_note_attachment` | Stažení přílohy poznámky sdíleného projektu |
1331
+ | `td_delete_shared_note_attachment` | Smazání přílohy poznámky sdíleného projektu |
1332
+ | `td_list_shared_project_docs` | Seznam dokumentů sdíleného projektu (rejstřík, obsah až na `includeContent`) |
1333
+ | `td_get_shared_project_doc` | Jedna stránka dokumentace sdíleného projektu včetně obsahu |
1334
+ | `td_create_shared_project_doc` | Vytvoření dokumentu ve sdíleném projektu |
1335
+ | `td_update_shared_project_doc` | Aktualizace dokumentu ve sdíleném projektu |
1336
+ | `td_delete_shared_project_doc` | Smazání dokumentu ve sdíleném projektu |
1337
+ | `td_get_shared_task` | Detail jednoho úkolu ve sdíleném projektu (podle ID nebo kódu, s odpracovaným časem a počty checklistu a komentářů) |
1338
+ | `td_list_shared_task_tags` | Tagy úkolu ve sdíleném projektu |
1339
+ | `td_bulk_update_shared_tasks` | Hromadná úprava úkolů ve sdíleném projektu |
1340
+ | `td_bulk_delete_shared_tasks` | Hromadné smazání úkolů ve sdíleném projektu (kaskáda na checklist a komentáře) |
1341
+ | `td_update_shared_worklog` | Úprava worklogu ve sdíleném projektu |
1342
+ | `td_list_shared_activity_log` | Aktivita ve sdíleném projektu (stejné filtry jako u osobní) |
1343
+
1344
+ > **Oprávnění, `ownerSecret` a historie ve sdílených projektech (TODO-434).**
1345
+ >
1346
+ > - **`ownerSecret` je nepovinný a nemá se posílat.** Každý sdílený nástroj si ho
1347
+ > najde ve vašem `projectRef` podle `sharedOwnerId` a `td_list_shared_projects`
1348
+ > ho už nevrací. Secret je klíč k celému projektu, takže dřív ležel v kontextu
1349
+ > modelu i v každém přepisu konverzace. Kdo ho pošle, tomu to dál funguje
1350
+ > (a kontroluje se proti `sharedOwnerId`).
1351
+ > - **Zápisy hlídají oprávnění stejně jako appka** (`src/permissions.ts`, port
1352
+ > appkového `permissions.ts`). Úkoly, worklogy, checklist, komentáře, přílohy,
1353
+ > vazby, přiřazení štítků, poznámky a dokumenty chtějí `write` nebo `admin`.
1354
+ > Nastavení projektu (`td_update_shared_project` včetně mazání a obnovy),
1355
+ > deployment stages, repozitářové linky, správa štítků a členové chtějí
1356
+ > vlastníka nebo `admin`. Bez `projectRef` se zápis odmítne, čtení jde dál.
1357
+ > Odmítnutí přijde jako chyba a nic se nezapíše.
1358
+ > - **Členy MCP spravuje jen napůl.** Appka po každé změně člena rotuje
1359
+ > zapisovací klíč nebo předá ten současný, jinak zablokovaný člen zapisuje dál.
1360
+ > MCP rotovat neumí, takže změny, po kterých člen nesmí zapisovat (block,
1361
+ > kick, zamítnutí, snížení na `read`), odmítne s odkazem na appku. Schválení,
1362
+ > odblokování a povýšení projdou, jen dokud projekt nemá rotovaný klíč.
1363
+ > - **Sdílené zápisy píšou historii** do sdílené instance, stejné záznamy jako
1364
+ > appka (úkol vytvořen/upraven po polích/smazán, worklog, checklist, komentář,
1365
+ > příloha, štítek, stage, repozitář, projekt, člen), s `actorId` vašeho účtu
1366
+ > a `source: "mcp"` v metadatech.
1367
+ > - **Mazání neexistujícího id** vrací chybu místo `success` a hromadné mazání ho
1368
+ > počítá mezi přeskočené. `td_update_shared_project` vybírá řádek projektu
1369
+ > stejně jako appka (nejstarší živý) a umí ho obnovit z koše.
1370
+ > - **Kód projektu** smí obsahovat jen `A-Z` a `0-9` a souběžná volání
1371
+ > `td_create_task` / `td_create_shared_task` do jednoho projektu už nedostanou
1372
+ > stejný kód.
1330
1373
 
1331
- Broadcast notices for every user. Writing, and listing expired ones, needs `TODOCKO_RELAY_ADMIN_KEY`.
1374
+ > **Stavy úkolů a validace argumentů (TODO-296, TODO-297).** Stav
1375
+ > `recurring` je plnohodnotný, appka ho používá pro opakované úkoly a MCP ho
1376
+ > teď nabízí ve všech devíti enumech. Zároveň se **kontrolují hodnoty enumů a
1377
+ > odmítají nedeklarované argumenty**. Dřív byly enumy jen dokumentace a
1378
+ > neznámý argument se tiše zahodil, což je přesně způsob, jak
1379
+ > `td_create_shared_checklist_item` přijal `isChecked`, vrátil `success`
1380
+ > a položku založil neodškrtnutou. Ten argument tam dnes je.
1381
+ >
1382
+ > Při té příležitosti se srovnal i `linkType`: MCP nabízelo `related`, kterému
1383
+ > appka nerozumí, a chyběly mu `explicit` a `mention`, které appka opravdu
1384
+ > zapisuje. Platné hodnoty jsou `blocks`, `explicit`, `mention`.
1332
1385
 
1333
- Without `TODOCKO_RELAY_ADMIN_KEY`, `td_create_system_notification` and
1334
- `td_delete_system_notification` are not offered to the client at all (a 401 is
1335
- the only answer they could give) and the listing drops its `admin` flag. The key
1336
- is never sent over plain `http://` to anything but localhost. (TODO-441)
1386
+ > **Rodič se ověřuje, argumenty jsou dorovnané (TODO-300, TODO-302).**
1387
+ > `td_create_task_comment` a `td_create_checklist_item` šly dřív založit na
1388
+ > **neexistující úkol**: řádek se zapsal proti ID, které nic nerozřeší, každý
1389
+ > výpis jde přes `taskId`, takže ho nikdo nikdy nepřečte, a tool vrátil
1390
+ > `success`. `td_add_worklog` to odmítal od TODO-90 M12, tyhle dva ne. Teď
1391
+ > odmítají obě strany, osobní i sdílená, a sdílená scopuje i podle ownera.
1392
+ >
1393
+ > Zároveň se dorovnalo devět argumentů, které sdílené tooly proti osobním
1394
+ > neměly. Nejcitelnější byl `td_update_shared_project`: uměl jen archivaci,
1395
+ > takže **sdílený projekt nešlo přejmenovat**.
1337
1396
 
1338
- | Tool | Description |
1339
- |------|-------------|
1340
- | `td_list_system_notifications` | List active system/broadcast notifications from the relay server. |
1341
- | `td_create_system_notification` | Create a broadcast notification visible to all Todocko users. |
1342
- | `td_delete_system_notification` | Delete a system notification by ID. |
1397
+ ### Zprávy od uživatelů (relay)
1343
1398
 
1344
- ### User Messages (relay)
1399
+ Zprávy, které uživatelé posílají z aplikace (hlášení vad, návrhy, vzkazy).
1400
+ Výpis a mazání umí jen **admin owner** a relay od TODO-90 H2 nevěří samotnému
1401
+ `ownerId` – požadavek se podepisuje Ed25519 klíčem odvozeným z nastaveného
1402
+ mnemoniku. Odesílání relay nechává nepřihlášené, stejně jako formulář v appce.
1345
1403
 
1346
- What users send from the app: bug reports, feature requests, notes. Listing and deleting are admin-owner only and the request is signed with the configured mnemonic; submitting needs no admin rights.
1404
+ | Nástroj | Popis |
1405
+ |---------|-------|
1406
+ | `td_list_user_messages` | Výpis zpráv od uživatelů (jen admin owner) |
1407
+ | `td_submit_user_message` | Odeslání zprávy adminům (hlášení vady, návrh, vzkaz) |
1408
+ | `td_delete_user_message` | Smazání zprávy na relayi (jen admin owner, tvrdé smazání) |
1347
1409
 
1348
- | Tool | Description |
1349
- |------|-------------|
1350
- | `td_list_user_messages` | List messages users have sent from the app (bug reports, feature requests, notes). |
1351
- | `td_submit_user_message` | Send a message to the Todocko admins (bug report, feature request or note), the same way the app's feedback form does. |
1352
- | `td_delete_user_message` | Delete one user message from the relay. |
1410
+ ### Analytika a přehledy
1353
1411
 
1354
- ### Analytics & Reports
1412
+ | Nástroj | Popis |
1413
+ |---------|-------|
1414
+ | `td_get_dashboard_summary` | Přehled: úkoly dnes, po termínu, odpracováno tento týden, nadcházející deadline |
1415
+ | `td_get_team_workload` | Vytížení týmu: odpracováno vs odhad vs kapacita per uživatel za období |
1416
+ | `td_list_recurring_tasks` | Seznam opakujících se úkolů s konfigurací opakování |
1417
+ | `td_list_overdue_tasks` | Úkoly po termínu (seřazené od nejstaršího) |
1355
1418
 
1356
- | Tool | Description |
1357
- |------|-------------|
1358
- | `td_get_dashboard_summary` | Overview: tasks today, overdue, this week's worklog, upcoming deadlines |
1359
- | `td_get_team_workload` | Team workload: logged vs estimate vs capacity per user for a period |
1360
- | `td_list_recurring_tasks` | List recurring tasks with recurrence configuration |
1361
- | `td_list_overdue_tasks` | Overdue tasks (sorted oldest first) |
1419
+ > **Do v1.6.0 tyhle tři nástroje vracely vždy prázdno.** `td_list_recurring_tasks`,
1420
+ > `td_list_overdue_tasks` a `td_list_tasks_by_date_range` čtly `result.rows`,
1421
+ > zatímco `evolu.loadQuery` vrací pole samo – takže `count: 0` na jakýkoli vstup,
1422
+ > bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný
1423
+ > `queryRows`. Recurrence pole navíc vrací i `td_get_task`, takže nastavení
1424
+ > opakování jde přečíst tou nejpřímější cestou.
1425
+ | `td_list_tasks_by_date_range` | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí |
1426
+ | `td_analyze_dependencies` | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |
1362
1427
 
1363
- > **Before v1.6.0 these three tools always returned nothing.**
1364
- > `td_list_recurring_tasks`, `td_list_overdue_tasks` and
1365
- > `td_list_tasks_by_date_range` read `result.rows`, while `evolu.loadQuery`
1366
- > resolves to the array itself — so `count: 0` for every input, with no error to
1367
- > notice. Fixed in TODO-242 behind a shared `queryRows`. `td_get_task` now returns
1368
- > the recurrence settings too, so a schedule can be read the obvious way.
1369
- | `td_list_tasks_by_date_range` | Tasks filtered by scheduledDate or deadline within a date range |
1370
- | `td_analyze_dependencies` | Dependency analysis: blocked tasks, blocking chains, critical path |
1428
+ > **Sdílené projekty se do analytiky počítají (TODO-112).** Do MCP IX čtlo všech
1429
+ > pět přehledů jen osobní instanci, takže úkol ve sdíleném projektu neviděl
1430
+ > dashboard, rozdělení vytížení, seznam opakujících se ani po termínu, ani dotaz
1431
+ > na rozmezí dat. U vytížení to nebylo jen chybějící číslo: počítá se
1432
+ > z odpracovaného času, takže vynechané sdílené minuty podhodnocovaly každého,
1433
+ > kdo ve sdíleném projektu pracuje. Každý nástroj bere `includeShared`
1434
+ > (výchozí `true`) a vrací `sharedIncluded`, ať je vidět, jestli se sdílená
1435
+ > polovina opravdu načetla. `td_analyze_dependencies` zůstává záměrně jen
1436
+ > osobní: appka sdílené `taskLink` řádky čte, ale žádné nezapisuje.
1437
+ >
1438
+ > `td_search_tasks` hledá ve sdílených projektech taky, se stejným přepínačem.
1371
1439
 
1372
- ### Diagnostics
1440
+ ### Diagnostika
1373
1441
 
1374
- | Tool | Description |
1375
- |------|-------------|
1376
- | `td_sync_status` | Sync status |
1377
- | `td_force_sync` | Force a sync round-trip with the relay (useful when you want to make sure you're reading the latest data from another device) |
1442
+ | Nástroj | Popis |
1443
+ |---------|-------|
1444
+ | `td_sync_status` | Stav synchronizace |
1445
+ | `td_force_sync` | Vynutí sync round-trip s relayem (užitečné, když chceš mít jistotu, že vidíš nejnovější data z jiného zařízení) |
1378
1446
 
1379
- ## Usage Examples
1447
+ ## Příklady použití
1380
1448
 
1381
- ### List projects
1449
+ ### Seznam projektů
1382
1450
  ```
1383
- Show me all projects in Todocko
1451
+ Zobraz mi seznam všech projektů v Todocko
1384
1452
  ```
1385
1453
 
1386
- ### List tasks
1454
+ ### Seznam úkolů
1387
1455
  ```
1388
- What tasks do I have with status "todo"?
1389
- Show tasks for project TODO
1456
+ Jaké mám úkoly ve stavu "todo"?
1457
+ Zobraz úkoly projektu TODO
1390
1458
  ```
1391
1459
 
1392
- ### Task details
1460
+ ### Detail úkolu
1393
1461
  ```
1394
- What are the details of task TODO-15?
1462
+ Jaké jsou detaily úkolu TODO-15?
1395
1463
  ```
1396
1464
 
1397
- ### Create task
1465
+ ### Vytvoření úkolu
1398
1466
  ```
1399
- Create a new task in project PROJ with title "Fix login bug" and priority high
1400
- Create a task with deadline 2026-03-15 and scheduledDate 2026-03-10
1467
+ Vytvoř nový úkol v projektu PROJ s názvem "Opravit bug v přihlášení" a prioritou high
1468
+ Vytvoř úkol s deadline na 2026-03-15 a scheduledDate na 2026-03-10
1401
1469
  ```
1402
1470
 
1403
- ### Update task
1471
+ ### Aktualizace úkolu
1404
1472
  ```
1405
- Mark task PROJ-5 as completed
1406
- Assign task TODO-10 to user with ID xyz
1407
- Set scheduledDate of task TODO-10 to tomorrow
1473
+ Označ úkol PROJ-5 jako dokončený
1474
+ Přiřaď úkol TODO-10 uživateli s ID xyz
1475
+ Nastav scheduledDate úkolu TODO-10 na zítra
1408
1476
  ```
1409
1477
 
1410
- ### Log time
1478
+ ### Logování času
1411
1479
  ```
1412
- Log 2 hours of work on task TODO-15 with description "Feature implementation"
1480
+ Zaloguj 2 hodiny práce na úkol TODO-15 s popisem "Implementace feature"
1413
1481
  ```
1414
1482
 
1415
- ### Working with attachments
1483
+ ### Práce s přílohami
1416
1484
  ```
1417
- Upload file /home/user/report.pdf as attachment to task TODO-15
1418
- What attachments does task TODO-15 have?
1419
- Delete attachment with ID xyz
1485
+ Nahraj soubor /home/user/report.pdf jako přílohu k úkolu TODO-15
1486
+ Jaké přílohy má úkol TODO-15?
1487
+ Smaž přílohu s ID xyz
1420
1488
  ```
1421
1489
 
1422
- ### Shared projects
1490
+ ### Sdílené projekty
1423
1491
  ```
1424
- Show shared projects
1425
- What tasks are in the shared project?
1426
- Mark task as deployed to production
1492
+ Zobraz sdílené projekty
1493
+ Jaké úkoly jsou ve sdíleném projektu?
1494
+ Označ úkol jako nasazený na produkci
1427
1495
  ```
1428
1496
 
1429
1497
  ### Deployment stages
1430
1498
  ```
1431
- What deployment stages does the project have?
1432
- Create a new deployment stage "Staging" for the shared project
1499
+ Jaké deployment stages má projekt?
1500
+ Vytvoř novou deployment stage "Staging" pro sdílený projekt
1433
1501
  ```
1434
1502
 
1435
- ### Sub-tasks
1503
+ ### Sub-úkoly
1436
1504
  ```
1437
- Create a sub-task for task TODO-15 in project TODO
1438
- Detach task TODO-20 from its parent (parentTaskId: null)
1505
+ Vytvoř sub-úkol k úkolu TODO-15 v projektu TODO
1506
+ Odpoj úkol TODO-20 od rodičovského úkolu (parentTaskId: null)
1439
1507
  ```
1440
1508
 
1441
- ### Analytics & Reports
1509
+ ### Přehledy a analytika
1442
1510
  ```
1443
- What's my dashboard summary for today?
1444
- How is the team's workload this week?
1445
- What tasks are overdue?
1446
- Show tasks scheduled for next week
1447
- Analyze dependencies in project TODO
1448
- What recurring tasks do I have?
1511
+ Jaký mám dnes přehled? (dashboard summary)
1512
+ Jak je vytížený tým tento týden?
1513
+ Jaké úkoly jsou po termínu?
1514
+ Zobraz úkoly naplánované na příští týden
1515
+ Analyzuj závislosti v projektu TODO
1516
+ Jaké mám opakující se úkoly?
1449
1517
  ```
1450
1518
 
1451
- ## Security
1519
+ ## Linux CLI (`todo`) (TODO-160)
1452
1520
 
1453
- **Important:** Your backup phrase (mnemonic) is sensitive data!
1521
+ Vedle MCP serveru je v balíčku i CLI `todo` pro rychlé osobní ovládání z terminálu – sdílí stejnou databázi i `TODOCKO_MNEMONIC` jako MCP. Po `npm link` (nebo globální instalaci) je dostupné jako `todo`.
1522
+
1523
+ 📖 **Podrobný návod: [CLI.md](CLI.md)**
1524
+
1525
+ ```bash
1526
+ # Co je na dnešek, a u každého úkolu proč tam je
1527
+ todo today
1528
+
1529
+ # Výpis úkolů (bez --all skryje hotové a opakované)
1530
+ todo list
1531
+ todo list -p TODO --status review
1532
+ todo list --no-shared # vynechat sdílené projekty, je to rychlejší
1533
+
1534
+ # Přidání úkolu (bez -p použije první projekt)
1535
+ todo add "Opravit login"
1536
+ todo add "Opravit login" -p TODO --priority high --scheduled today
1537
+
1538
+ # Změna stavu (identifikace kódem úkolu)
1539
+ todo done TODO-160 # status=done
1540
+ todo start TODO-160 # status=in_progress
1541
+ todo mv TODO-160 review # backlog|todo|in_progress|review|done|recurring
1542
+
1543
+ # Worklog
1544
+ todo log TODO-160 1h30m "ladění OAuth"
1545
+ todo worklogs TODO-160 # tabulka worklogů
1546
+
1547
+ # Strojový výstup na všech příkazech
1548
+ todo add "X" --json
1549
+ ```
1550
+
1551
+ - **Architektura:** `src/cli.ts` (commander) → mapuje argumenty na existující tool handlery (`handleToolCall`), žádná duplicitní business logika. Kód úkolu se překládá na ID přes `td_get_task`.
1552
+ - **Sync:** po mutaci čeká ~3 s na relay; když je offline, vypíše `⚠ uloženo lokálně` a skončí s kódem 0 (data jsou lokálně bezpečně).
1553
+ - **Exit kódy:** `0` úspěch, `1` user/business chyba (neznámý kód, špatný stav/čas), `2` config (chybí mnemonic).
1554
+ - **Barvy** jen v TTY a při nenastaveném `NO_COLOR`.
1555
+ - **Čtení pokrývá i sdílené projekty.** `todo list` a `todo today` spojují osobní instanci se všemi připojenými sdílenými projekty; výpis postavený jen na osobní by tiše zamlčel část práce. Volbou `--no-shared` to jde vynechat, když víc záleží na rychlosti.
1556
+ - **Pozn.:** běží jako samostatný proces nad stejnou SQLite DB jako MCP; při souběžném zápisu s MCP může (vzácně) nastat `SQLITE_BUSY` – v takovém případě příkaz zopakuj. Mimo rozsah: editace popisu, projekty, štítky, checklist, komentáře a přílohy, a jakýkoliv zápis do sdílených projektů. Parita se 161 nástroji MCP se nechystá.
1557
+
1558
+ ## Bezpečnost
1559
+
1560
+ **Důležité:** Vaše zálohovací fráze (mnemonic) je citlivý údaj!
1561
+
1562
+ - Nikdy ji nesdílejte v přímé konverzaci s AI
1563
+ - MCP server frázi nevystavuje přes žádný nástroj: nejde ji z Todočka přečíst ani vypsat
1564
+ - To ale neznamená, že k ní AI nemá přístup. Agent, který umí spouštět příkazy nebo číst
1565
+ soubory (Claude Code a podobní), si `~/.claude.json` nebo `~/.claude/settings.json`
1566
+ přečte stejně jako kterýkoli jiný soubor. Konfigurace chrání frázi před nástroji MCP,
1567
+ ne před shellem. (TODO-441)
1568
+ - Kdokoli s vaší frází má plný přístup k vašim datům
1569
+
1570
+ ### Kontrola argumentů a cest (TODO-441)
1571
+
1572
+ - Hodnoty argumentů se kontrolují proti typu, který nástroj deklaruje. `isBlocked: "false"`
1573
+ se dřív ukládalo jako `true` (neprázdný řetězec je pravdivý), teď je to chyba.
1574
+ - Datová pole (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`, `startDate`,
1575
+ `endDate`, …) musí být `YYYY-MM-DD`; kde schéma mluví o datetime (`completedAt`,
1576
+ `expiresAt`, `from`/`to` v activity logu), projde i ISO datetime. `deadline: "zítra"`
1577
+ se dřív uložilo doslova a nikdo se to nedozvěděl.
1578
+ - Přílohy: cesty se vyhodnocují až po rozpadnutí symlinků, takže odkaz uvnitř povoleného
1579
+ adresáře už nevede ven. Stahování nově odmítá tečkové soubory (stejně jako nahrávání)
1580
+ a nepřepíše existující soubor, dokud nepošleš `overwrite: true`.
1581
+
1582
+ ### WebSocket Origin (TODO-169)
1583
+
1584
+ MCP server při WebSocket připojení k relay posílá hlavičku `Origin: https://todocko-mcp`. Sdílený relay (`relay.todocko.cz`) má tuto hodnotu povolenou ve whitelistu Access Control. Pokud používáš vlastní relay, musíš ji přidat do `tiers.json.allowedDomains`, jinak relay odmítne připojení s `403 Forbidden` na WS upgrade.
1585
+
1586
+ ### Rotace zapisovacího klíče sdílených projektů (TODO-268)
1587
+
1588
+ Když vlastník sdíleného projektu někoho vyhodí, aplikace vymění zapisovací klíč
1589
+ projektu na relayi. Klíč odvozený z `ownerSecret` tím přestane platit a relay
1590
+ s ním odmítne každý zápis.
1454
1591
 
1455
- - Never share it directly in conversation with AI
1456
- - The MCP server never exposes the phrase through a tool: nothing in Todocko can read or print it
1457
- - That is not the same as the AI having no access to it. An agent that can run commands or
1458
- read files (Claude Code and the like) reads `~/.claude.json` or `~/.claude/settings.json`
1459
- like any other file. The configuration keeps the phrase away from MCP tools, not from a
1460
- shell. (TODO-441)
1461
- - Anyone with your phrase has full access to your data
1592
+ MCP server si nový klíč načte ze sloupce `projectRef.writeKey`, který do jeho
1593
+ databáze přiteče běžným syncem AppOwnera. Kontrola běží při startu a pak každou
1594
+ minutu, takže po rotaci může být zhruba minuta, kdy zápisy do toho jednoho
1595
+ projektu relay odmítá a řádky čekají lokálně. Čtení rotace neovlivňuje.
1462
1596
 
1463
- ### Argument and path checks (TODO-441)
1597
+ ### Komu klíč patří: nárok versus grant (TODO-440)
1464
1598
 
1465
- - Argument values are checked against the type the tool declares. `isBlocked: "false"`
1466
- used to be stored as `true` (a non-empty string is truthy); it is an error now.
1467
- - Date arguments (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`,
1468
- `startDate`, `endDate`, ...) must be `YYYY-MM-DD`; where the schema says datetime
1469
- (`completedAt`, `expiresAt`, activity-log `from`/`to`) an ISO datetime is accepted too.
1470
- `deadline: "zitra"` used to be stored verbatim with nothing reporting it.
1471
- - Attachments: paths are judged after symlinks are resolved, so a link inside the allowed
1472
- directory no longer leads out of it. Downloads now refuse dotfiles (as uploads already
1473
- did) and never replace an existing file unless `overwrite: true` is passed.
1599
+ `projectMember.permission` si zapisuje sám člen, takže o tom, kdo dostane
1600
+ zapisovací klíč, rozhodovat nemůže. Vlastník si vede vlastní záznam ve své
1601
+ osobní instanci, kam žádný člen nedosáhne:
1474
1602
 
1475
- ### Shared project write key rotation (TODO-268)
1603
+ - `shareInvite` na každý vygenerovaný odkaz, její id cestuje v tokenu,
1604
+ - `memberGrant` na každého člena, jehož oprávnění vlastník nastavil ručně,
1605
+ a ten pozvánku přebíjí.
1476
1606
 
1477
- When the owner of a shared project removes a member, the app swaps the
1478
- project's write key on the relay. The key derived from `ownerSecret` stops
1479
- being valid and the relay refuses every write made with it.
1607
+ Člen si id pozvánky neukládá, ten řádek čtou i ostatní členové a mohli by si ho
1608
+ opsat. Ukládá si do `projectMember.inviteProof` HMAC vlastní identity klíčovaný
1609
+ id pozvánky; vlastník, který id má, ho ověří, cizí člen si ho pro sebe nevyrobí.
1610
+ Skutečné oprávnění je to nižší z nároku a záznamu.
1480
1611
 
1481
- This server picks the new key up from the `projectRef.writeKey` column, which
1482
- reaches its database through the ordinary AppOwner sync. It checks at start and
1483
- then once a minute, so a rotation can leave about a minute in which writes to
1484
- that one project are refused and the rows wait locally. Reading is unaffected.
1612
+ `td_list_shared_members` proto vlastníkovi vrací navíc `verifiedPermission`
1613
+ a `effectivePermission` a `td_update_shared_member` zapisuje `memberGrant`
1614
+ spolu se změnou nároku. Dokud to MCP neumělo, změnilo povýšení přes MCP jen
1615
+ nárok: člen zapisovací klíč nedostal a appka u něj začala hlásit, že si
1616
+ nárokuje víc, než má potvrzeno.
1485
1617
 
1486
- ## Data Location
1618
+ ## Umístění dat
1487
1619
 
1488
- Databases are stored in the `~/.todocko/` directory:
1620
+ Databáze jsou uloženy v adresáři `~/.todocko/`:
1489
1621
 
1490
- | Platform | Path |
1491
- |----------|------|
1622
+ | Platforma | Cesta |
1623
+ |-----------|-------|
1492
1624
  | Linux | `~/.todocko/` |
1493
1625
  | macOS | `~/.todocko/` |
1494
1626
  | Windows | `C:\Users\<user>\.todocko\` |
1495
1627
 
1496
- Files:
1497
- - `todocko.db` - your personal data (tasks, projects)
1498
- - `todocko-shared.db` - shared projects
1628
+ Soubory:
1629
+ - `todocko.db` - vaše osobní data (úkoly, projekty)
1630
+ - `todocko-shared.db` - sdílené projekty
1499
1631
 
1500
- ## Configuration Changes
1632
+ ## Změna konfigurace
1501
1633
 
1502
1634
  ### Claude Code (CLI)
1503
1635
 
1504
- After changing configuration in `~/.claude/settings.json` (e.g., changing mnemonic), run the command:
1636
+ Po změně konfigurace v `~/.claude/settings.json` (např. změna mnemonicu) spusťte příkaz:
1505
1637
  ```
1506
1638
  /mcp
1507
1639
  ```
1508
- This will restart the MCP server with the new configuration.
1640
+ Tím se MCP server restartuje s novou konfigurací.
1509
1641
 
1510
- ### Switching to a Different Account
1642
+ ### Přepnutí na jiný účet
1511
1643
 
1512
- When changing the mnemonic to a **different Todocko account**, you need to delete the local database:
1644
+ Při změně mnemonicu na **jiný Todocko účet** je potřeba smazat lokální databázi:
1513
1645
 
1514
1646
  ```bash
1515
1647
  # Linux/macOS
@@ -1519,126 +1651,182 @@ rm ~/.todocko/todocko.db
1519
1651
  del %USERPROFILE%\.todocko\todocko.db
1520
1652
  ```
1521
1653
 
1522
- The database contains the owner ID from the previous mnemonic. After deletion, a new database will be created on the next startup and data from the new account will be downloaded.
1654
+ Databáze obsahuje ID vlastníka z předchozího mnemonicu. Po smazání se při dalším spuštění vytvoří nová databáze a stáhnou se data nového účtu.
1523
1655
 
1524
1656
  ## Troubleshooting
1525
1657
 
1526
- ### Server won't start
1527
- - Check that you have Node.js 24.20 or newer (Evolu v8 requires it)
1528
- - Check that you ran `npm run build`
1529
- - Check logs in Claude Desktop
1658
+ ### Server se nespustí
1659
+ - Zkontrolujte, že máte Node.js 24.20+
1660
+ - Zkontrolujte, že jste spustili `npm run build`
1661
+ - Zkontrolujte logy v Claude Desktop
1530
1662
 
1531
- ### Data not syncing
1532
- - Verify the backup phrase is correct (24 words)
1533
- - Check internet connection
1534
- - Wait a few seconds for synchronization
1535
- - Try deleting `~/.todocko/todocko.db` and restart
1663
+ ### Data se nesynchronizují
1664
+ - Ověřte, že je zálohovací fráze správná (24 slov)
1665
+ - Zkontrolujte internetové připojení
1666
+ - Počkejte pár sekund na synchronizaci
1667
+ - Zkuste smazat `~/.todocko/todocko.db` a restartovat
1536
1668
 
1537
- ### Tools not visible
1538
- - Restart Claude Desktop
1539
- - In Claude Code, use `/mcp` for reload
1540
- - Check the configuration file
1541
- - Check the path to dist/index.js
1542
1669
 
1543
- ### `project ... is a shared project` on a write
1544
- A shared project keeps its data in the **shared instance**, so the personal
1545
- tools (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) refuse a
1546
- write aimed at one and point at the `td_*_shared_*` counterpart.
1670
+ ### `status: relay-blocked` v `td_sync_status` (TODO-112)
1547
1671
 
1548
- Such a write used to be stored quietly in the personal instance beside the real
1549
- row, leaving the same task in two instances, free to drift: the app reads the
1550
- shared side and `td_list_tasks` reads the personal one, so the two disagreed
1551
- with nothing reporting it. (TODO-318)
1672
+ Relay odpovídá na HTTPS, ale WebSocket nepropustí. Mezi strojem a relayí tedy
1673
+ něco blokuje upgrade spojení, typicky proxy nebo firewall, ne vada relaye.
1674
+ Zápisy se drží lokálně a odejdou, jakmile socket projde. Od `no-relay` se to
1675
+ liší tím, že tam neodpovídá vůbec nic, což znamená spíš výpadek sítě.
1552
1676
 
1553
- **Deletes are still allowed** on a shared project, because otherwise old
1554
- personal copies could never be cleaned up. `td_search_tasks` with
1555
- `includeShared` shows both copies side by side and is the quickest way to spot
1556
- a split task.
1677
+ ### Nástroje nejsou viditelné
1678
+ - Restartujte Claude Desktop
1679
+ - V Claude Code použijte `/mcp` pro reload
1680
+ - Zkontrolujte konfigurační soubor
1681
+ - Zkontrolujte cestu k dist/index.js
1682
+
1683
+ ### `project ... is a shared project` při zápisu
1684
+ Sdílený projekt má svá data ve **sdílené instanci**. Osobní nástroje
1685
+ (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) proto zápis do
1686
+ takového projektu odmítnou a pošlou tě na `td_*_shared_*` protějšek.
1687
+
1688
+ Dřív se zápis tiše uložil do osobní instance vedle skutečného řádku. Vznikly
1689
+ tím dvě kopie téhož úkolu v různých instancích, které se rozcházely: aplikace
1690
+ čte sdílenou stranu, MCP `td_list_tasks` osobní, takže každý ukazoval něco
1691
+ jiného a nic to nehlásilo. (TODO-318)
1692
+
1693
+ **Mazání zůstává povolené i pro sdílený projekt**, jinak by staré osobní kopie
1694
+ nešlo uklidit. `td_search_tasks` s `includeShared` ukáže obě kopie vedle sebe a
1695
+ je proto nejrychlejší způsob, jak zjistit, že je úkol rozdvojený.
1696
+
1697
+ ### Kód úkolu se teď přidělit nedá (TODO-373)
1698
+ `td_create_task` odvozuje kód z nejvyššího, který v téhle kopii vidí. Když část
1699
+ účtu ještě nedorazila, je maximum nižší než skutečné a vznikne kód, který na
1700
+ relayi už existuje. Stalo se to 2026-09-23: v 07:01 kopie neměla TODO-360 až
1701
+ 367 a server vyrobil TODO-353 a dál, v 09:33 už je nad stejným souborem měla
1702
+ a navázal správně na 368. Nic se nerozbilo jen proto, že 353 až 359 byla shodou
1703
+ okolností volná.
1704
+
1705
+ Před přidělením kódu se proto porovná počet zpráv: Evolu jich drží po jedné
1706
+ v `evolu_timestamp`, relay hlásí stejné číslo pro ownera. Naměřeno 81 130 na
1707
+ obou stranách. Když je kopie pozadu, zápis se odmítne a řekne, kolik zpráv
1708
+ chybí; až se sync dotáhne, projde. Když se relay zeptat nedá, zápis projde:
1709
+ odmítat i tam by z lokálně prvního nástroje udělalo nástroj závislý na síti.
1710
+
1711
+ Aktuální stav ukáže `td_sync_status` v poli `copy`.
1712
+
1713
+ **Sdílené projekty tenhle strážce nemají.** Jejich úkoly patří jinému ownerovi
1714
+ s vlastním počtem zpráv a zeptat se na něj chce jeho klíč, ne ten odvozený
1715
+ z mnemoniky. Měřit tam app ownera by vypadalo jako pokrytí a nebylo by.
1557
1716
 
1558
1717
  ### `Todocko MCP už nad touto databází běží` (TODO-341)
1559
- A second instance over the same backup phrase refuses to start. The client
1560
- database runs with `journal_mode=delete` and a zero `busy_timeout`, so the
1561
- second process gets SQLITE_BUSY immediately, Evolu turns it into
1562
- `PanicAbortReason: database is locked`, and the **first** process loses its
1563
- dbWorker. Until TODO-341 a new window silently killed the one you were working
1564
- in.
1718
+ Druhá instance nad stejnou zálohovací frází se odmítne nastartovat. Není to
1719
+ opatrnost navíc: klientská databáze jede v režimu `journal_mode=delete`
1720
+ s nulovým `busy_timeout`, takže druhý proces dostane SQLITE_BUSY okamžitě,
1721
+ Evolu z toho udělá `PanicAbortReason: database is locked` a **prvnímu** procesu
1722
+ umře dbWorker. Do TODO-341 tak nové okno tiše shodilo to, ve kterém jsi pracoval
1723
+ (projevilo se jako `status: worker-dead`, viz níž).
1565
1724
 
1566
- The lock is `~/.todocko/todocko-<owner>.lock` next to the database. It holds the
1567
- owning pid; after a crash the next start detects it as stale
1568
- (`process.kill(pid, 0)`) and takes it over.
1725
+ Zámek je soubor `~/.todocko/todocko-<owner>.lock` vedle databáze. Drží pid,
1726
+ který ho vzal; po pádu procesu se pozná jako neaktuální a další start si ho
1727
+ vezme.
1569
1728
 
1570
- If you really need a second instance (the `todo` CLI next to the MCP, say), give
1571
- it its own database name:
1729
+ Samotné `process.kill(pid, 0)` na to nestačí (TODO-372). **Zombie procesem ten
1730
+ test projde**: proces, který skončil, ale rodič ho nesklidil, je pořád
1731
+ v tabulce procesů a signál 0 na něm uspěje. Zámek pak vypadá jako věčně držený
1732
+ a žádná nová instance se nespustí. Stalo se to 2026-09-22, kdy byl držitel ve
1733
+ stavu `Z` a jeho rodič zastavený `claude` ve stavu `Tl`, takže neměl kdo
1734
+ sklízet. Na Linuxu se proto čte stav z `/proc/<pid>/stat` a `Z` se bere jako
1735
+ mrtvý. Kde `/proc` není, zůstává původní chování.
1736
+
1737
+ Když potřebuješ druhou instanci doopravdy (třeba CLI `todo` vedle MCP), spusť ji
1738
+ s vlastním jménem databáze:
1572
1739
  ```bash
1573
1740
  TODOCKO_INSTANCE=cli todo ...
1574
1741
  ```
1575
- It gets `~/.todocko/todocko-cli-<owner>.db`, a separate local copy that
1576
- reconciles with the first one through the relay. Allowed characters are
1577
- `a-z0-9-`; anything else is dropped and an empty value means the default
1578
- database.
1579
-
1580
- ### Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)
1742
+ Dostane `~/.todocko/todocko-cli-<owner>.db`, tedy vlastní lokální kopii, která
1743
+ se s tou první srovná přes relay. Povolené znaky jsou `a-z0-9-`, zbytek se
1744
+ zahodí; prázdná hodnota znamená výchozí databázi.
1581
1745
 
1582
- There are two causes, told apart by what the server says.
1746
+ ### Worker umřel za běhu (`status: worker-dead`)
1747
+ Proces normálně naběhl a po nějaké době přestal odpovídat. `td_sync_status`
1748
+ vrátí `status: "worker-dead"` a v `workerDefects` je panika i s časem. Dotazy
1749
+ v tomhle stavu selžou **hned**, ne až po 15 s. Řešení je `/mcp` reconnect.
1750
+ Nejčastější příčina je druhý MCP proces nad stejnou databází; od TODO-341 se
1751
+ druhá instance nenastartuje, takže tuhle cestu k mrtvému workeru už nemá jak
1752
+ způsobit.
1583
1753
 
1584
- **1. A dead dbWorker after two processes raced (TODO-316).** Two MCP processes
1585
- creating the schema of the same database at the same time race each other. The
1586
- loser gets `SqliteError: table evolu_version already exists` and its dbWorker
1587
- stays dead for the life of the process. Typically on the first starts after an
1588
- MCP upgrade that adds a table.
1754
+ ### Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)
1589
1755
 
1590
- Since TODO-316 the server detects this at startup and **refuses to start**:
1591
- every tool call returns `Evolu dbWorker never answered` immediately. Since
1592
- TODO-317 the reason the worker died is recorded too, in `workerDefects` from
1593
- `td_sync_status` and on stderr as `FATAL: Evolu dbWorker defect: ...`. It used to
1594
- look healthy while every query hung until the client gave up 1800s later. The
1595
- fix is a `/mcp` reconnect in Claude Code.
1756
+ Příčiny jsou dvě, poznáte je podle toho, co server řekne.
1596
1757
 
1597
- **2. A mismatched native binding.** The `better-sqlite3` native binding was compiled against a different Node.js ABI than the one running the MCP server. `new Database()` fails with `ERR_DLOPEN_FAILED`, the Evolu dbWorker init never completes, and every `loadQuery` hangs forever. Mutations (insert/update) report success but are silently lost.
1758
+ **1. Mrtvý dbWorker po závodu dvou procesů (TODO-316).** Dva MCP procesy, které
1759
+ současně zakládají schéma téže databáze, se porvou. Poražený dostane
1760
+ `SqliteError: table evolu_version already exists` a jeho dbWorker zůstane
1761
+ mrtvý do konce života procesu. Typicky při prvních startech po upgradu MCP,
1762
+ který přidá tabulku.
1598
1763
 
1599
- Typical symptoms: `td_sync_status` reports `ok` with `errorCount: 0`, but `td_get_task`, `td_list_*`, etc. all time out.
1764
+ Od TODO-316 to server pozná při startu a **odmítne se nastartovat**: každé
1765
+ volání nástroje hned vrátí `Evolu dbWorker never answered`. Od TODO-317 se
1766
+ navíc zapíše i **proč** worker umřel, do `workerDefects` v `td_sync_status`
1767
+ a do stderr jako `FATAL: Evolu dbWorker defect: ...`. Dřív se tvářil
1768
+ zdravě a každý dotaz visel, dokud to klient po 1800 s nevzdal. Řešení je `/mcp`
1769
+ reconnect v Claude Code.
1600
1770
 
1601
- Fix — rebuild the native binding against the current Node:
1602
- ```bash
1603
- cd ~/.todocko-mcp # or wherever todocko-mcp is installed
1604
- cd node_modules/better-sqlite3
1605
- npx node-gyp rebuild --release
1606
- ```
1607
- Then `/mcp` reconnect in Claude Code.
1771
+ **2. Databáze, kterou nový driver neotevře.** Od TODO-448 je klientská databáze
1772
+ šifrovaná a starou, plaintextovou, nový driver odmítne: `file is not a database`.
1773
+ Symptom je stejný jako u všech vad dbWorkeru, tedy `Evolu dbWorker never answered`
1774
+ u každého volání. Řešení je smazat `~/.todocko/todocko*-<ownerId>.db` a nechat
1775
+ data stáhnout z relaye; předtím se ujistit přes `td_sync_status`, že nic nečeká
1776
+ na odeslání.
1608
1777
 
1609
- This mismatch typically appears after upgrading Node.js (e.g. v22 → v25) or switching between nvm and linuxbrew/brew Node, because the installer builds the binding against the `node` from `PATH`, but `claude` may later spawn the MCP with a different node binary.
1778
+ Dřív tu stával mismatch native bindingu better-sqlite3 (`ERR_DLOPEN_FAILED` po
1779
+ upgradu Node nebo přepnutí mezi nvm a brew). `@evolu/nodejs` 4.4 ho nahradilo
1780
+ předpřipraveným SQLite, takže se nic nekompiluje a tahle třída chyb zmizela.
1610
1781
 
1611
- ## Development
1782
+ ## Vývoj
1612
1783
 
1613
1784
  ```bash
1614
- # Install dependencies
1785
+ # Instalace závislostí
1615
1786
  npm install
1616
1787
 
1617
1788
  # Build
1618
1789
  npm run build
1619
1790
 
1620
- # Watch mode for development
1791
+ # Watch mode pro vývoj
1621
1792
  npm run dev
1622
1793
 
1623
- # Tests
1794
+ # Testy
1624
1795
  npm test
1625
1796
 
1626
- # Manual run
1627
- TODOCKO_MNEMONIC="your phrase" npm start
1797
+ # Ruční spuštění
1798
+ TODOCKO_MNEMONIC="vaše fráze" npm start
1628
1799
  ```
1629
1800
 
1630
1801
  ### Testy
1631
1802
 
1632
- Vitest, 164 testů ve dvanácti souborech. **Běží v CI** (`ci.yml`, push i PR na `main`)
1633
- od TODO-229 — do té doby CI spouštěla jen build, takže se nikdo nedozvěděl, že
1803
+ Vitest. **Sada běží v CI** (`ci.yml`, push i PR na `main`)
1804
+ od TODO-229 – do té doby CI spouštěla jen build, takže se nikdo nedozvěděl, že
1634
1805
  `helpers.test.ts` na Node 18/20 **ani neprojde importem**: přes `helpers.ts`
1635
1806
  tahal `../evolu.js`, jehož inicializace při načtení modulu spadne na
1636
1807
  `crypto.getRandomValues must be defined`.
1637
1808
 
1638
1809
  Proto jsou funkce bez závislosti na Evolu v **`src/tools/pure.ts`** a testují se
1639
1810
  odtud. `helpers.ts` je re-exportuje, takže volající se nemění. Když píšeš helper,
1640
- který Evolu nepotřebuje, patří do `pure.ts` — jinak ho nejde testovat bez
1811
+ který Evolu nepotřebuje, patří do `pure.ts` – jinak ho nejde testovat bez
1641
1812
  nastartované databáze.
1642
1813
 
1643
- Závazná verze je **Node 24.20 nebo novější** — je v `engines` a Evolu v8 na
1814
+ Závazná verze je **Node 24.20 nebo novější** – je v `engines` a Evolu v8 na
1644
1815
  starším neběží. Na té jede `ci.yml` i `release.yml`.
1816
+
1817
+ ### Vydání
1818
+
1819
+ ```bash
1820
+ npm version patch # nebo minor / major
1821
+ git push --follow-tags
1822
+ ```
1823
+
1824
+ Tag spustí `release.yml`: sestaví, pustí testy, ověří, že tag souhlasí
1825
+ s `package.json`, a vydání na npm **zařadí do fronty** i s podepsanou
1826
+ provenance. Žádné přihlašovací údaje k npm v repozitáři nejsou, runner si o
1827
+ krátkodobé oprávnění řekne sám přes trusted publishing (OIDC).
1828
+
1829
+ Fronta je tam schválně. K nikomu se verze nedostane, dokud ji neschválíš na
1830
+ npmjs.com v **Staged Packages**, případně přes `npm stage list todocko-mcp`
1831
+ a `npm stage approve <stage-id>`. Schválení chce 2FA, takže ani ovládnutý běh
1832
+ workflow nedokáže poslat verzi uživatelům sám.