todocko-mcp 3.10.2 → 3.10.3

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.
Files changed (2) hide show
  1. package/README.md +1336 -1169
  2. package/package.json +1 -1
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,584 @@ 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
+ # Add a task (without -p it uses the first project)
571
+ todo add "Fix the login"
572
+ todo add "Fix the login" -p TODO --priority high --scheduled today
670
573
 
671
- # Změna stavu (identifikace kódem úkolu)
574
+ # Change status (tasks are addressed by their code)
672
575
  todo done TODO-160 # status=done
673
576
  todo start TODO-160 # status=in_progress
674
577
  todo mv TODO-160 review # backlog|todo|in_progress|review|done|recurring
675
578
 
676
579
  # Worklog
677
- todo log TODO-160 1h30m "ladění OAuth"
678
- todo worklogs TODO-160 # tabulka worklogů
580
+ todo log TODO-160 1h30m "debugging OAuth"
581
+ todo worklogs TODO-160 # worklog table
679
582
 
680
- # Strojový výstup na všech příkazech
583
+ # Machine readable output on every command
681
584
  todo add "X" --json
682
585
  ```
683
586
 
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.
587
+ - **Sync:** after a mutation it waits about 3 s for the relay. Offline it prints
588
+ `⚠ uloženo lokálně` and exits 0, because the data is safe locally either way.
589
+ - **Exit codes:** `0` success, `1` user or business error (unknown code, bad
590
+ status or duration), `2` configuration (missing mnemonic).
591
+ - **Colors** only on a TTY and only when `NO_COLOR` is unset.
592
+ - **Note:** it runs as its own process against the same SQLite database as the
593
+ MCP server. A write that collides with the MCP server can rarely raise
594
+ `SQLITE_BUSY`; repeat the command when it does. Out of scope for v1:
595
+ `list`/`today`, editing descriptions, projects, tags, checklists and shared
596
+ projects.
717
597
 
718
- ### Rotace zapisovacího klíče sdílených projektů (TODO-268)
598
+ ## Security
719
599
 
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.
600
+ **Important:** Your backup phrase (mnemonic) is sensitive data!
723
601
 
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.
602
+ - Never share it directly in conversation with AI
603
+ - The MCP server never exposes the phrase through a tool: nothing in Todocko can read or print it
604
+ - That is not the same as the AI having no access to it. An agent that can run commands or
605
+ read files (Claude Code and the like) reads `~/.claude.json` or `~/.claude/settings.json`
606
+ like any other file. The configuration keeps the phrase away from MCP tools, not from a
607
+ shell. (TODO-441)
608
+ - Anyone with your phrase has full access to your data
728
609
 
729
- ### Komu klíč patří: nárok versus grant (TODO-440)
610
+ ### Argument and path checks (TODO-441)
730
611
 
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:
612
+ - Argument values are checked against the type the tool declares. `isBlocked: "false"`
613
+ used to be stored as `true` (a non-empty string is truthy); it is an error now.
614
+ - Date arguments (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`,
615
+ `startDate`, `endDate`, ...) must be `YYYY-MM-DD`; where the schema says datetime
616
+ (`completedAt`, `expiresAt`, activity-log `from`/`to`) an ISO datetime is accepted too.
617
+ `deadline: "zitra"` used to be stored verbatim with nothing reporting it.
618
+ - Attachments: paths are judged after symlinks are resolved, so a link inside the allowed
619
+ directory no longer leads out of it. Downloads now refuse dotfiles (as uploads already
620
+ did) and never replace an existing file unless `overwrite: true` is passed.
734
621
 
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í.
622
+ ### Shared project write key rotation (TODO-268)
738
623
 
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.
624
+ When the owner of a shared project removes a member, the app swaps the
625
+ project's write key on the relay. The key derived from `ownerSecret` stops
626
+ being valid and the relay refuses every write made with it.
743
627
 
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.
628
+ This server picks the new key up from the `projectRef.writeKey` column, which
629
+ reaches its database through the ordinary AppOwner sync. It checks at start and
630
+ then once a minute, so a rotation can leave about a minute in which writes to
631
+ that one project are refused and the rows wait locally. Reading is unaffected.
749
632
 
750
- ## Umístění dat
633
+ ## Data Location
751
634
 
752
- Databáze jsou uloženy v adresáři `~/.todocko/`:
635
+ Databases are stored in the `~/.todocko/` directory:
753
636
 
754
- | Platforma | Cesta |
755
- |-----------|-------|
637
+ | Platform | Path |
638
+ |----------|------|
756
639
  | Linux | `~/.todocko/` |
757
640
  | macOS | `~/.todocko/` |
758
641
  | Windows | `C:\Users\<user>\.todocko\` |
759
642
 
760
- Soubory:
761
- - `todocko.db` - vaše osobní data (úkoly, projekty)
762
- - `todocko-shared.db` - sdílené projekty
643
+ Files:
644
+ - `todocko.db` - your personal data (tasks, projects)
645
+ - `todocko-shared.db` - shared projects
763
646
 
764
- ## Změna konfigurace
647
+ ## Configuration Changes
765
648
 
766
649
  ### Claude Code (CLI)
767
650
 
768
- Po změně konfigurace v `~/.claude/settings.json` (např. změna mnemonicu) spusťte příkaz:
651
+ After changing configuration in `~/.claude/settings.json` (e.g., changing mnemonic), run the command:
769
652
  ```
770
653
  /mcp
771
654
  ```
772
- Tím se MCP server restartuje s novou konfigurací.
655
+ This will restart the MCP server with the new configuration.
773
656
 
774
- ### Přepnutí na jiný účet
657
+ ### Switching to a Different Account
775
658
 
776
- Při změně mnemonicu na **jiný Todocko účet** je potřeba smazat lokální databázi:
659
+ When changing the mnemonic to a **different Todocko account**, you need to delete the local database:
777
660
 
778
661
  ```bash
779
662
  # Linux/macOS
@@ -783,181 +666,314 @@ rm ~/.todocko/todocko.db
783
666
  del %USERPROFILE%\.todocko\todocko.db
784
667
  ```
785
668
 
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.
669
+ 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.
670
+
671
+ ## Troubleshooting
672
+
673
+ ### Server won't start
674
+ - Check that you have Node.js 24.20 or newer (Evolu v8 requires it)
675
+ - Check that you ran `npm run build`
676
+ - Check logs in Claude Desktop
677
+
678
+ ### Data not syncing
679
+ - Verify the backup phrase is correct (24 words)
680
+ - Check internet connection
681
+ - Wait a few seconds for synchronization
682
+ - Try deleting `~/.todocko/todocko.db` and restart
683
+
684
+ ### Tools not visible
685
+ - Restart Claude Desktop
686
+ - In Claude Code, use `/mcp` for reload
687
+ - Check the configuration file
688
+ - Check the path to dist/index.js
689
+
690
+ ### `project ... is a shared project` on a write
691
+ A shared project keeps its data in the **shared instance**, so the personal
692
+ tools (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) refuse a
693
+ write aimed at one and point at the `td_*_shared_*` counterpart.
694
+
695
+ Such a write used to be stored quietly in the personal instance beside the real
696
+ row, leaving the same task in two instances, free to drift: the app reads the
697
+ shared side and `td_list_tasks` reads the personal one, so the two disagreed
698
+ with nothing reporting it. (TODO-318)
699
+
700
+ **Deletes are still allowed** on a shared project, because otherwise old
701
+ personal copies could never be cleaned up. `td_search_tasks` with
702
+ `includeShared` shows both copies side by side and is the quickest way to spot
703
+ a split task.
704
+
705
+ ### `Todocko MCP už nad touto databází běží` (TODO-341)
706
+ A second instance over the same backup phrase refuses to start. The client
707
+ database runs with `journal_mode=delete` and a zero `busy_timeout`, so the
708
+ second process gets SQLITE_BUSY immediately, Evolu turns it into
709
+ `PanicAbortReason: database is locked`, and the **first** process loses its
710
+ dbWorker. Until TODO-341 a new window silently killed the one you were working
711
+ in.
712
+
713
+ The lock is `~/.todocko/todocko-<owner>.lock` next to the database. It holds the
714
+ owning pid; after a crash the next start detects it as stale
715
+ (`process.kill(pid, 0)`) and takes it over.
716
+
717
+ If you really need a second instance (the `todo` CLI next to the MCP, say), give
718
+ it its own database name:
719
+ ```bash
720
+ TODOCKO_INSTANCE=cli todo ...
721
+ ```
722
+ It gets `~/.todocko/todocko-cli-<owner>.db`, a separate local copy that
723
+ reconciles with the first one through the relay. Allowed characters are
724
+ `a-z0-9-`; anything else is dropped and an empty value means the default
725
+ database.
726
+
727
+ ### Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)
728
+
729
+ There are two causes, told apart by what the server says.
730
+
731
+ **1. A dead dbWorker after two processes raced (TODO-316).** Two MCP processes
732
+ creating the schema of the same database at the same time race each other. The
733
+ loser gets `SqliteError: table evolu_version already exists` and its dbWorker
734
+ stays dead for the life of the process. Typically on the first starts after an
735
+ MCP upgrade that adds a table.
736
+
737
+ Since TODO-316 the server detects this at startup and **refuses to start**:
738
+ every tool call returns `Evolu dbWorker never answered` immediately. Since
739
+ TODO-317 the reason the worker died is recorded too, in `workerDefects` from
740
+ `td_sync_status` and on stderr as `FATAL: Evolu dbWorker defect: ...`. It used to
741
+ look healthy while every query hung until the client gave up 1800s later. The
742
+ fix is a `/mcp` reconnect in Claude Code.
743
+
744
+ **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.
745
+
746
+ Typical symptoms: `td_sync_status` reports `ok` with `errorCount: 0`, but `td_get_task`, `td_list_*`, etc. all time out.
747
+
748
+ Fix – rebuild the native binding against the current Node:
749
+ ```bash
750
+ cd ~/.todocko-mcp # or wherever todocko-mcp is installed
751
+ cd node_modules/better-sqlite3
752
+ npx node-gyp rebuild --release
753
+ ```
754
+ Then `/mcp` reconnect in Claude Code.
755
+
756
+ 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.
757
+
758
+ ## Development
759
+
760
+ ```bash
761
+ # Install dependencies
762
+ npm install
763
+
764
+ # Build
765
+ npm run build
766
+
767
+ # Watch mode for development
768
+ npm run dev
769
+
770
+ # Tests
771
+ npm test
772
+
773
+ # Manual run
774
+ TODOCKO_MNEMONIC="your phrase" npm start
775
+ ```
776
+
777
+ ### Tests
787
778
 
788
- ## Troubleshooting
779
+ Vitest. **The suite runs in CI** (`ci.yml`, on pushes and
780
+ pull requests to `main`) since TODO-229. Before that CI only built, so nobody
781
+ learned that `helpers.test.ts` **does not even survive the import** on Node
782
+ 18/20: through `helpers.ts` it pulled in `../evolu.js`, whose module-level
783
+ initialization dies on `crypto.getRandomValues must be defined`.
789
784
 
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
785
+ That is why the functions with no Evolu dependency live in
786
+ **`src/tools/pure.ts`** and are tested from there. `helpers.ts` re-exports them,
787
+ so callers do not change. A helper that does not need Evolu belongs in
788
+ `pure.ts`, otherwise it cannot be tested without a running database.
794
789
 
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
790
+ The required version is **Node 24.20 or newer**: it is in `engines` and Evolu v8
791
+ does not run on anything older. `ci.yml` and `release.yml` both use it.
800
792
 
793
+ ### Releasing
801
794
 
802
- ### `status: relay-blocked` v `td_sync_status` (TODO-112)
795
+ ```bash
796
+ npm version patch # or minor / major
797
+ git push --follow-tags
798
+ ```
803
799
 
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ě.
800
+ The tag starts `release.yml`, which builds, runs the tests, checks that the tag
801
+ matches `package.json` and then **stages** the release on npm with a signed
802
+ provenance statement. It carries no npm credentials: the runner asks for a
803
+ short-lived one through trusted publishing (OIDC).
808
804
 
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
805
+ Staging is deliberate. A release does not reach anyone until it is approved on
806
+ npmjs.com under **Staged Packages**, or with `npm stage list todocko-mcp` and
807
+ `npm stage approve <stage-id>`. Approval needs 2FA, so a workflow run that
808
+ someone else managed to steer cannot put a version in front of users on its own.
814
809
 
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.
810
+ ---
819
811
 
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)
812
+ # Česky
824
813
 
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ý.
814
+ MCP (Model Context Protocol) server pro práci s daty [Todocko](https://app.todocko.cz) aplikace z AI asistentů.
828
815
 
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á.
816
+ ## Podpora
836
817
 
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.
818
+ - **Claude Desktop** - plná podpora
819
+ - **Claude Code (CLI)** - plná podpora (stejná konfigurace)
842
820
 
843
- Aktuální stav ukáže `td_sync_status` v poli `copy`.
821
+ ## Požadavky
844
822
 
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.
823
+ - **Node.js 24.20+** – Evolu v8 to má v `engines`, a není to formalita: v8 stojí
824
+ na `navigator.locks`, `MessageChannel`, `BroadcastChannel` a `WebSocket`, které
825
+ má Node nativně teprve od 24
826
+ - Todocko účet s daty synchronizovanými přes Evolu
848
827
 
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íž).
828
+ ## Evolu v8 (TODO-88)
856
829
 
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.
830
+ MCP běží na `@evolu/common` 8.27.0 a `@evolu/nodejs` 4.6.0. Upgrade z 8.22
831
+ (TODO-431) nevyžadoval změnu kódu; sync přes relay ověřen v obou směrech
832
+ proti verzi 8.22.
860
833
 
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í.
834
+ Upgrade na 8.27 (TODO-448) změnu kódu vyžadoval, a hlavně **mění formát
835
+ databáze na disku**:
868
836
 
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.
837
+ - `@evolu/nodejs` 4.4 vyměnilo better-sqlite3 za vlastní SQLite. Ten na rozdíl
838
+ od better-sqlite3 respektuje šifrovací klíč, který Evolu pro klientskou
839
+ databázi předává, takže soubor v `~/.todocko` je nově **šifrovaný**. Starou
840
+ databázi psanou better-sqlite3 nový driver neotevře, skončí na
841
+ `file is not a database` (SQLITE_NOTADB, ověřeno na kopii reálné databáze).
842
+ **Při upgradu je proto nutné lokální databáze smazat**; jsou jen keší dat
843
+ z relaye, takže se stáhnou znovu (ověřeno: čerstvá databáze se dosynchronizovala
844
+ na 17 MB). Co nebylo odsynchronizované, je pryč, takže před smazáním
845
+ zkontrolovat `td_sync_status`.
846
+ - Dopad na bezpečnost je naopak příjemný: lokální kopie všech úkolů už neleží na
847
+ disku v plaintextu. Druhá strana téže mince je, že do souboru nenahlédne ani
848
+ žádný vlastní nástroj, což odneslo `ensureMissingColumns`.
849
+ - Transportní URL je od 8.27 brandovaný `RelayUrl`, takže `TODOCKO_RELAY_URL` se
850
+ parsuje přes `RelayUrlFromString` a URL s query se odmítne; `createOwnerWebSocketTransport`
851
+ si `?ownerId=` připojuje sám.
852
+ - Platforma musí nově dodat `deleteDatabaseFiles` (maže soubor databáze i žurnál)
853
+ a `getDevicePersistence` i na hlavním vlákně, ne jen v shared workeru.
877
854
 
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.
855
+ Od Evolu 8.20.3 nese zápis do sdílené instance celého ownera,
856
+ `{ owner: sharedOwner }`, ne `{ ownerId }`. Zapomenuté `ownerId` Evolu ignoruje
857
+ a řádek zapíše pod jiného ownera, odkud se nenasynchronizuje. Hlídá to
858
+ `src/tools/sharedWrites.test.ts`. Databázi, jejíž worker spadl, Evolu nově
859
+ odmítne přes `evoluError`; `td_sync_status` ji ukáže v poli `evoluError`
860
+ a nástroje na ni nečekají do timeoutu, hned řeknou, že je potřeba reconnect.
861
+ (TODO-427)
885
862
 
886
- ### Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)
863
+ v7 dodával `createDbWorkerForPlatform`, což bylo vše, co headless klient v Node
864
+ potřeboval. v8 to zrušil: `@evolu/nodejs` v3 nabízí relay a pár primitiv, a
865
+ jedinou kompletní klientskou platformu má upstream pro web. `src/evoluPlatform.ts`
866
+ je protějšek pro Node, poskládaný ze stejných dílů.
887
867
 
888
- Příčiny jsou dvě, poznáte je podle toho, co server řekne.
868
+ Vyšel krátce, protože Node 24 má potřebná web API nativně. Oba workery běží
869
+ **in-process** přes `createWorker` / `createSharedWorker` – to jsou vlastní
870
+ fallbacky Evolu „pro platformy bez podpory workerů"; `worker_threads` by přinesly
871
+ izolaci, kterou jednoprocesový CLI nepotřebuje.
889
872
 
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.
873
+ Sedm věcí, na kterých se to dá snadno rozbít:
895
874
 
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.
875
+ - **Mutace má strop 640 000 bajtů** (od 8.12). Větší zápis vyhodí výjimku ještě
876
+ před uložením, takže se ani nenasynchronizuje. Přílohy se proto ukládají
877
+ binárně a po kusech po 480 KiB (`src/tools/attachmentChunks.ts`), stejně jako
878
+ v aplikaci; velikost kusu musí sedět s ní, jinak se příloha nahraná tady
879
+ otevře jinde useknutá. Čtení umí i starý tvar, base64 v `attachment.data`,
880
+ protože schéma je append-only.
881
+ - **Obsah nové přílohy leží ve vlastním shardu** (`src/attachmentShards.ts`,
882
+ TODO-450), ne pod AppOwnerem. Jednotlivou změnu v CRDT smazat nejde, jen
883
+ označit jako smazanou, takže owner je jediná jednotka skutečného smazání.
884
+ Cesta `attachment/<id>` se odvozuje z id přílohy, a tedy se nikam neukládá;
885
+ v řádku je jen značka `contentShard`. Odvození i pořadí při mazání, nejdřív
886
+ relay a pak lokálně, musí sedět s aplikací, jinak se obě poloviny rozejdou
887
+ tiše: příloha nahraná tady by se tam otevřela prázdná. Shard se registruje
888
+ jen na dobu nahrání nebo čtení, protože adresa transportu nese owner id
889
+ a trvale registrovaný shard by znamenal jeden WebSocket na každou přílohu.
890
+ - **Hlášení stavů dohledává jména k identifikátorům** (`src/statusReporting.ts`,
891
+ TODO-458). Pilulka v aplikaci ukazovala u volání, která dostanou jen id,
892
+ zkrácený identifikátor, což člověku neříká nic. Tabulky i sloupce, ze kterých
893
+ se jméno bere, jsou vyjmenované vedle seznamu povolených polí, ne odvozené
894
+ z názvu nástroje. Dohledání běží uvnitř téhož pošli a nečekej jako celé
895
+ hlášení a má vlastní strop, takže zaseknutý dotaz nedrží frontu; když se nic
896
+ nenajde, zůstane zkrácené id.
902
897
 
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
898
 
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.
899
+ - **`installPolyfills()` je povinné** a musí proběhnout dřív než cokoli
900
+ z `@evolu/common`. v8 volá `Map.prototype.getOrInsert(Computed)`, které nemá
901
+ žádný vydaný Node (ověřeno do 25.9.0). Bez toho to spadne na první zprávě.
902
+ - **Databáze patří jednomu mnemonicu.** v7 při neshodě volal `restoreAppOwner`,
903
+ který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala
904
+ data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu
905
+ **ohlásí a odmítne nastartovat** – smaž `~/.todocko/todocko.db` a nech ho
906
+ stáhnout data znovu.
907
+ - **`createNodeEvoluDeps()` musí být singleton na proces.** Shared worker drží
908
+ jediný `tabLeaderPortStore` a `initDbWorker` každého tenanta předpokládá, že
909
+ je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo
910
+ leadera neohlásil, a vytvoření sdílené instance spadne na
911
+ `initDbWorker: Expected value to be non-nullable`. Jeden worker obslouží obě
912
+ instance jako dva tenanty podle `appName`, stejně jako `@evolu/web` na jedné
913
+ stránce.
914
+ - **Mutace nevrací `Result`.** v7 vracel z `insert`/`update` `Result`, takže se
915
+ testovalo `result.ok` a čtlo `result.value.id`. v8 vrací přímo `{ id }` a při
916
+ neplatné změně vyhodí výjimku. Kontrola `!result.ok` proto uspěla vždy a
917
+ nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší,
918
+ protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to
919
+ `src/tools/pure.test.ts`.
920
+ - **Ownera filtrovat v SQL, ne až v JS.** Sdílená instance drží data všech
921
+ ownerů v jedné tabulce. `limit` provede SQLite dřív, než se v JS cokoli
922
+ filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a
923
+ filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26.
924
+ Stejná past číhá u `orderBy position desc limit 1` při výpočtu další pozice.
913
925
 
914
- ## Vývoj
926
+ ## Instalace
915
927
 
916
- ```bash
917
- # Instalace závislostí
918
- npm install
928
+ ### Z npm
919
929
 
920
- # Build
921
- npm run build
930
+ Není co klonovat ani sestavovat. Stačí Clauda nasměrovat na vydaný balíček,
931
+ který si při prvním spuštění sám stáhne:
922
932
 
923
- # Watch mode pro vývoj
924
- npm run dev
933
+ **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
925
934
 
926
- # Ruční spuštění
927
- TODOCKO_MNEMONIC="vaše fráze" npm start
935
+ ```json
936
+ {
937
+ "mcpServers": {
938
+ "todocko": {
939
+ "command": "npx",
940
+ "args": ["-y", "todocko-mcp"],
941
+ "env": {
942
+ "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
943
+ }
944
+ }
945
+ }
946
+ }
928
947
  ```
929
948
 
930
- ---
931
-
932
- # English
949
+ **Claude Code (CLI)** - tentýž blok přidejte do `~/.claude/settings.json`
950
+ a restartujte Clauda.
933
951
 
934
- MCP (Model Context Protocol) server for working with [Todocko](https://app.todocko.cz) app data from AI assistants.
935
-
936
- ## Support
937
-
938
- - **Claude Desktop** - full support
939
- - **Claude Code (CLI)** - full support (same configuration)
952
+ Místo `todocko-mcp` můžete napsat `todocko-mcp@<verze>` a držet si tak verzi pod
953
+ kontrolou. Pokud chcete mít v `PATH` i nástroj `todo` pro příkazovou řádku,
954
+ nainstalujte balíček globálně:
940
955
 
941
- ## Requirements
956
+ ```bash
957
+ npm install -g todocko-mcp
958
+ ```
942
959
 
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
960
+ Pozor, `TODOCKO_MNEMONIC` je privátní klíč ke všem vašim datům. Patří do
961
+ konfiguračního souboru a nikam jinam: nikdy na příkazovou řádku, nikdy do
962
+ historie shellu, nikdy do repozitáře. Viz [Bezpečnost](#bezpečnost).
947
963
 
948
- ## Installation
964
+ ### Ze zdrojových kódů
949
965
 
950
- ### 1. Download
966
+ #### 1. Stažení
951
967
 
952
- **Using git:**
968
+ **Pomocí git:**
953
969
  ```bash
954
970
  git clone https://github.com/brnt-cz/todocko-mcp.git
955
971
  cd todocko-mcp
956
972
  ```
957
973
 
958
- **Or download ZIP** from [Releases](https://github.com/brnt-cz/todocko-mcp/releases) and extract.
974
+ **Nebo stáhněte ZIP** z [Releases](https://github.com/brnt-cz/todocko-mcp/releases) a rozbalte.
959
975
 
960
- ### 2. Run the installer
976
+ #### 2. Spuštění instalátoru
961
977
 
962
978
  **Linux/macOS:**
963
979
  ```bash
@@ -970,546 +986,641 @@ chmod +x install.sh
970
986
  .\install.ps1
971
987
  ```
972
988
 
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
989
+ Instalátor:
990
+ 1. Nainstaluje závislosti a sestaví projekt
991
+ 2. Zeptá se, zda chcete nakonfigurovat Claude Desktop, Claude Code nebo obojí
992
+ 3. Vytvoří konfigurační soubor s placeholderem
993
+ 4. **Ručně doplňte** svou 24slovnou zálohovací frázi do konfiguračního souboru
994
+ 5. Restartujte Claude
979
995
 
980
- ### Manual installation
996
+ #### Manuální instalace
981
997
 
982
- 1. Install dependencies:
998
+ 1. Nainstalujte závislosti:
983
999
  ```bash
984
1000
  npm install
985
1001
  npm run build
986
1002
  ```
987
1003
 
988
- 2. Add to configuration:
1004
+ 2. Přidejte do konfigurace:
989
1005
 
990
- **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
1006
+ **Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
991
1007
 
992
1008
  ```json
993
1009
  {
994
1010
  "mcpServers": {
995
1011
  "todocko": {
996
1012
  "command": "node",
997
- "args": ["/path/to/mcp-server/dist/index.js"],
1013
+ "args": ["/cesta/k/mcp-server/dist/index.js"],
998
1014
  "env": {
999
- "TODOCKO_MNEMONIC": "your 24 word backup phrase"
1015
+ "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
1000
1016
  }
1001
1017
  }
1002
1018
  }
1003
1019
  }
1004
1020
  ```
1005
1021
 
1006
- **Claude Code (CLI)** - add to `~/.claude/settings.json`:
1022
+ **Claude Code (CLI)** - přidejte do `~/.claude/settings.json`:
1007
1023
 
1008
1024
  ```json
1009
1025
  {
1010
1026
  "mcpServers": {
1011
1027
  "todocko": {
1012
1028
  "command": "node",
1013
- "args": ["/path/to/mcp-server/dist/index.js"],
1029
+ "args": ["/cesta/k/mcp-server/dist/index.js"],
1014
1030
  "env": {
1015
- "TODOCKO_MNEMONIC": "your 24 word backup phrase"
1031
+ "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
1016
1032
  }
1017
1033
  }
1018
1034
  }
1019
1035
  }
1020
1036
  ```
1021
1037
 
1022
- 3. Restart Claude Desktop / Claude Code
1038
+ 3. Restartujte Claude Desktop / Claude Code
1023
1039
 
1024
- ## Available Tools (161)
1040
+ ## Dostupné nástroje (161)
1025
1041
 
1026
- ### Projects
1042
+ ### Projekty
1027
1043
 
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) |
1044
+ | Nástroj | Popis |
1045
+ |---------|-------|
1046
+ | `td_list_projects` | Seznam všech projektů |
1047
+ | `td_get_project` | Detail projektu podle ID nebo kódu |
1048
+ | `td_create_project` | Vytvoření nového projektu (kód jen `A-Z` a `0-9`, jako v appce) |
1049
+ | `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` |
1050
+ | `td_delete_project` | Smazání projektu (soft delete) |
1035
1051
 
1036
- ### Tasks
1052
+ ### Úkoly
1037
1053
 
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. |
1054
+ | Nástroj | Popis |
1055
+ |---------|-------|
1056
+ | `td_list_tasks` | Seznam úkolů s filtry (projekt, status, priorita, assignee) |
1057
+ | `td_get_task` | Detail úkolu podle ID nebo kódu (např. `PROJ-123`), včetně nastavení opakování |
1058
+ | `td_create_task` | Vytvoření nového úkolu (včetně recurrence, sprintNumber, parentTaskId) |
1059
+ | `td_update_task` | Aktualizace existujícího úkolu (včetně recurrence, sprintNumber, parentTaskId) |
1060
+ | `td_search_tasks` | Vyhledávání úkolů podle textu |
1061
+ | `td_bulk_update_tasks` | Hromadná aktualizace více úkolů (včetně sprintNumber) |
1062
+ | `td_bulk_delete_tasks` | Hromadné smazání více úkolů |
1063
+ | `td_delete_task` | Smazání jednoho úkolu (soft delete, kaskáda na worklogy a přílohy) |
1064
+ | `td_list_git_events` | Git aktivita pro úkol (commits, PR) z relay serveru |
1049
1065
 
1050
- ### Users
1066
+ ### Uživatelé
1051
1067
 
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) |
1068
+ | Nástroj | Popis |
1069
+ |---------|-------|
1070
+ | `td_list_users` | Seznam všech uživatelů |
1071
+ | `td_get_user` | Detail uživatele |
1072
+ | `td_create_user` | Vytvoření nového uživatele |
1073
+ | `td_update_user` | Aktualizace uživatele |
1074
+ | `td_delete_user` | Smazání uživatele (soft delete) |
1059
1075
 
1060
- ### Worklogs
1076
+ ### Worklogy
1061
1077
 
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) |
1078
+ | Nástroj | Popis |
1079
+ |---------|-------|
1080
+ | `td_list_worklogs` | Seznam worklogů pro úkol |
1081
+ | `td_add_worklog` | Přidání worklogu k úkolu |
1082
+ | `td_update_worklog` | Aktualizace worklogu |
1083
+ | `td_delete_worklog` | Smazání worklogu (soft delete) |
1068
1084
 
1069
- ### Attachments
1085
+ ### Přílohy
1070
1086
 
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 |
1087
+ | Nástroj | Popis |
1088
+ |---------|-------|
1089
+ | `td_upload_attachment` | Nahrání přílohy k úkolu (ze souboru nebo base64) |
1090
+ | `td_list_attachments` | Seznam příloh úkolu |
1091
+ | `td_download_attachment` | Stažení přílohy |
1092
+ | `td_delete_attachment` | Smazání přílohy |
1093
+ | `td_upload_note_attachment` | Nahrání přílohy k lokální poznámce projektu |
1094
+ | `td_list_note_attachments` | Seznam příloh lokální poznámky |
1095
+ | `td_download_note_attachment` | Stažení přílohy poznámky |
1096
+ | `td_delete_note_attachment` | Smazání přílohy poznámky |
1081
1097
 
1082
- ### Comments
1098
+ ### Komentáře
1083
1099
 
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) |
1100
+ | Nástroj | Popis |
1101
+ |---------|-------|
1102
+ | `td_list_task_comments` | Seznam komentářů k úkolu |
1103
+ | `td_create_task_comment` | Přidání komentáře k úkolu |
1104
+ | `td_update_task_comment` | Úprava komentáře |
1105
+ | `td_delete_task_comment` | Smazání komentáře (soft delete) |
1090
1106
 
1091
1107
  ### Checklist
1092
1108
 
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) |
1109
+ | Nástroj | Popis |
1110
+ |---------|-------|
1111
+ | `td_list_checklist_items` | Seznam položek checklistu úkolu |
1112
+ | `td_create_checklist_item` | Přidání položky checklistu |
1113
+ | `td_update_checklist_item` | Aktualizace položky (zaškrtnutí, pozice) |
1114
+ | `td_delete_checklist_item` | Smazání položky (soft delete) |
1099
1115
 
1100
- ### Mentions
1116
+ ### Zmínky (mentions)
1101
1117
 
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) |
1118
+ | Nástroj | Popis |
1119
+ |---------|-------|
1120
+ | `td_list_mentions` | Seznam zmínek uživatele |
1121
+ | `td_create_mention` | Vytvoření zmínky |
1122
+ | `td_mark_mention_read` | Označení zmínky jako přečtené |
1123
+ | `td_mark_all_mentions_read` | Označení všech zmínek jako přečtených |
1124
+ | `td_delete_mention` | Smazání zmínky (soft delete) |
1109
1125
 
1110
- ### Task Links
1126
+ ### Linky mezi úkoly
1111
1127
 
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) |
1128
+ | Nástroj | Popis |
1129
+ |---------|-------|
1130
+ | `td_list_app_settings` | Nastavení účtu, která se přenášejí mezi zařízeními |
1131
+ | `td_set_app_setting` | Nastavení jedné hodnoty na účtu |
1132
+ | `td_list_task_links` | Seznam linků úkolu |
1133
+ | `td_create_task_link` | Vytvoření linku mezi úkoly (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
1134
+ | `td_delete_task_link` | Smazání linku (soft delete) |
1119
1135
 
1120
- ### Tags
1136
+ ### Tagy
1121
1137
 
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 |
1138
+ | Nástroj | Popis |
1139
+ |---------|-------|
1140
+ | `td_list_tags` | Seznam štítků; vrací `projectId`, umí filtrovat podle projektu i na nezařazené |
1141
+ | `td_create_tag` | Vytvoření štítku – **předej `projectId`**, viz poznámku níž |
1142
+ | `td_update_tag` | Přejmenování, změna barvy, přiřazení projektu, nebo příznak výchozího štítku |
1143
+ | `td_delete_tag` | Smazání štítku (soft delete) |
1144
+ | `td_list_task_tags` | Seznam štítků přiřazených k úkolu |
1145
+ | `td_add_tag_to_task` | Přiřazení štítku k úkolu |
1146
+ | `td_remove_tag_from_task` | Odebrání štítku z úkolu |
1131
1147
 
1132
- Shared projects (TODO-235):
1148
+ Sdílené projekty (TODO-235):
1133
1149
 
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 |
1150
+ | Nástroj | Popis |
1151
+ |---------|-------|
1152
+ | `td_list_shared_tags` | Štítky ve sdíleném projektu |
1153
+ | `td_create_shared_tag` | Vytvoření štítku ve sdíleném projektu |
1154
+ | `td_update_shared_tag` | Přejmenování / změna barvy / příznak výchozího štítku |
1155
+ | `td_delete_shared_tag` | Smazání (soft delete) |
1156
+ | `td_add_shared_tag_to_task` | Přiřazení k úkolu ve sdíleném projektu |
1157
+ | `td_remove_shared_tag_from_task` | Odebrání z úkolu |
1142
1158
 
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`.
1159
+ > **Štítek bez projektu appka nikde nenabídne.** Od TODO-227 jsou štítky vázané
1160
+ > na projekt; `td_create_tag` bez `projectId` vyrobí **nezařazený** štítek, který
1161
+ > se v appce objeví jen v nastavení projektu v sekci „Nezařazené" s tlačítkem na
1162
+ > přiřazení. Odpověď nástroje na to upozorní. Dodatečně to spraví
1163
+ > `td_update_tag` s `projectId`.
1148
1164
  >
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.
1165
+ > **Limity free tarifu (TODO-243).** Tarifní limity patří do appky, ne sem.
1166
+ > `td_create_task` a `td_create_project` proto do odpovědi přilepí varování
1167
+ > s reálným počtem, když je owner na free tarifu a je nad limitem (1 projekt,
1168
+ > 50 **aktivních** úkolů). Jde o to, aby se to člověk dozvěděl při zakládání, ne až
1169
+ > zpětně v appce, a aby z textu bylo jasné, že o nic nepřišel. **Nic to neblokuje**
1170
+ > a při neznámém tarifu (nedostupný relay) radši mlčí – falešný poplach je horší
1171
+ > než žádný.
1156
1172
 
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.
1173
+ > **Výchozí štítky (TODO-239).** `isDefault` u `td_create_tag` / `td_update_tag`
1174
+ > (a sdílených variant) znamená, že štítek dostane **každý nově zakládaný úkol**
1175
+ > projektu. `td_create_task` i `td_create_shared_task` je přidávají samy a vrátí
1176
+ > je v `appliedTags` – appka je předzaškrtává v modalu, takže bez toho by výsledek
1177
+ > závisel na tom, odkud úkol vznikne. Existujících úkolů se to nedotkne.
1162
1178
  >
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.
1179
+ > Ve sdílených projektech se zapisuje do **jiné Evolu instance**, proto samostatná
1180
+ > sada nástrojů – `td_add_tag_to_task` na sdílený úkol nefunguje.
1165
1181
 
1166
- ### Task Templates
1182
+ ### Šablony úkolů
1167
1183
 
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) |
1184
+ | Nástroj | Popis |
1185
+ |---------|-------|
1186
+ | `td_list_task_templates` | Seznam šablon úkolů |
1187
+ | `td_create_task_template` | Vytvoření šablony (volitelně `checklistItems` a `tagIds`) |
1188
+ | `td_update_task_template` | Aktualizace šablony (`checklistItems`, `tagIds`; prázdné pole maže) |
1189
+ | `td_delete_task_template` | Smazání šablony (soft delete) |
1190
+
1191
+ ### Kanban sloupce
1192
+
1193
+ | Nástroj | Popis |
1194
+ |---------|-------|
1195
+ | `td_list_kanban_columns` | Seznam kanban sloupců |
1196
+ | `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) |
1197
+ | `td_update_kanban_column` | Aktualizace sloupce (`wipLimit: null` limit zruší) |
1198
+ | `td_delete_kanban_column` | Smazání sloupce (soft delete) |
1174
1199
 
1175
- ### Kanban Columns
1200
+ ### Uložená zobrazení
1176
1201
 
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) |
1202
+ | Nástroj | Popis |
1203
+ |---------|-------|
1204
+ | `td_list_saved_views` | Seznam uložených zobrazení |
1205
+ | `td_create_saved_view` | Vytvoření zobrazení |
1206
+ | `td_update_saved_view` | Aktualizace zobrazení |
1207
+ | `td_delete_saved_view` | Smazání zobrazení (soft delete) |
1183
1208
 
1184
- ### Saved Views
1209
+ ### Aktivita
1185
1210
 
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) |
1211
+ | Nástroj | Popis |
1212
+ |---------|-------|
1213
+ | `td_list_activity_log` | Seznam zápisů aktivity s filtry (úkol, aktor, akce, typ entity, datum od/do) – read-only |
1192
1214
 
1193
- ### Activity Log
1215
+ ### Poznámky k projektu
1194
1216
 
1195
- | Tool | Description |
1196
- |------|-------------|
1197
- | `td_list_activity_log` | List activity log entries with filters (task, actor, action, entityType, date from/to) — read-only |
1217
+ | Nástroj | Popis |
1218
+ |---------|-------|
1219
+ | `td_list_project_notes` | Seznam lokálních poznámek projektu (rejstřík: titulek a `contentLength`, obsah až na `includeContent`) |
1220
+ | `td_get_project_note` | Jedna lokální poznámka včetně obsahu |
1221
+ | `td_create_project_note` | Vytvoření lokální poznámky |
1222
+ | `td_update_project_note` | Aktualizace lokální poznámky |
1223
+ | `td_delete_project_note` | Smazání lokální poznámky (soft delete) |
1198
1224
 
1199
- ### Project Notes
1225
+ ### Dokumentace projektu
1200
1226
 
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) |
1227
+ Dokumenty jsou poznámky s `isDoc`, takže mohou být zanořené pod jiný dokument
1228
+ (`parentDocId`).
1208
1229
 
1209
- ### Deployment Stages
1230
+ | Nástroj | Popis |
1231
+ |---------|-------|
1232
+ | `td_list_project_docs` | Seznam dokumentů projektu (rejstřík: titulek, hierarchie a `contentLength`, obsah až na `includeContent`) |
1233
+ | `td_get_project_doc` | Jedna stránka dokumentace včetně obsahu |
1234
+ | `td_create_project_doc` | Vytvoření dokumentu |
1235
+ | `td_update_project_doc` | Aktualizace dokumentu |
1236
+ | `td_delete_project_doc` | Smazání dokumentu (soft delete) |
1210
1237
 
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. |
1238
+ ### Systémová oznámení (relay)
1217
1239
 
1218
- ### Repository Links
1240
+ Broadcast oznámení pro všechny uživatele. Zápis a výpis včetně expirovaných
1241
+ vyžaduje `TODOCKO_RELAY_ADMIN_KEY`; obráceným směrem jdou zprávy od uživatelů,
1242
+ viz níž.
1219
1243
 
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. |
1244
+ Bez `TODOCKO_RELAY_ADMIN_KEY` se `td_create_system_notification`
1245
+ a `td_delete_system_notification` klientovi vůbec nenabízejí (nemohly by nic
1246
+ jiného než vrátit 401) a u výpisu zmizí přepínač `admin`. Klíč se navíc nikdy
1247
+ neposílá přes nešifrované `http://` jinam než na localhost. (TODO-441)
1226
1248
 
1227
- ### Shared Projects
1249
+ | Nástroj | Popis |
1250
+ |---------|-------|
1251
+ | `td_list_system_notifications` | Seznam aktivních oznámení (s `admin: true` i expirovaná) |
1252
+ | `td_create_system_notification` | Vytvoření oznámení pro všechny uživatele |
1253
+ | `td_delete_system_notification` | Smazání oznámení |
1228
1254
 
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. |
1255
+ ### Deployment stages
1285
1256
 
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.
1257
+ | Nástroj | Popis |
1258
+ |---------|-------|
1259
+ | `td_list_deployment_stages` | Seznam deployment stages pro projekt |
1260
+ | `td_create_deployment_stage` | Vytvoření deployment stage |
1261
+ | `td_update_deployment_stage` | Aktualizace deployment stage |
1262
+ | `td_delete_deployment_stage` | Smazání deployment stage (soft delete) |
1316
1263
 
1317
- ### Project Documentation
1264
+ ### Repository linky
1318
1265
 
1319
- Documents are notes with `isDoc`, so they can nest under another document via `parentDocId`.
1266
+ | Nástroj | Popis |
1267
+ |---------|-------|
1268
+ | `td_list_repository_links` | Seznam repozitářových linků |
1269
+ | `td_create_repository_link` | Vytvoření repozitářového linku |
1270
+ | `td_update_repository_link` | Aktualizace repozitářového linku |
1271
+ | `td_delete_repository_link` | Smazání repozitářového linku |
1320
1272
 
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) |
1273
+ ### Sdílené projekty
1328
1274
 
1329
- ### System Notifications (relay)
1275
+ | Nástroj | Popis |
1276
+ |---------|-------|
1277
+ | `td_list_shared_projects` | Seznam sdílených projektů s vaším oprávněním (`ownerSecret` už nevrací) |
1278
+ | `td_list_shared_tasks` | Seznam úkolů ze sdíleného projektu |
1279
+ | `td_create_shared_task` | Vytvoření úkolu ve sdíleném projektu (auto-generovaný kód) |
1280
+ | `td_update_shared_task` | Aktualizace úkolu ve sdíleném projektu (všechna pole včetně recurrence, estimate, blocking) |
1281
+ | `td_delete_shared_task` | Smazání úkolu ve sdíleném projektu (soft delete, kaskáda na checklist) |
1282
+ | `td_update_shared_project` | Aktualizace sdíleného projektu: název, kód, barva, archivace, skrytí z filtrů, automatické schvalování členů |
1283
+ | `td_list_shared_worklogs` | Seznam worklogů úkolu ve sdíleném projektu |
1284
+ | `td_add_shared_worklog` | Přidání worklogu k úkolu ve sdíleném projektu |
1285
+ | `td_delete_shared_worklog` | Smazání worklogu ve sdíleném projektu |
1286
+ | `td_list_shared_checklist_items` | Seznam položek checklistu úkolu ve sdíleném projektu |
1287
+ | `td_create_shared_checklist_item` | Přidání položky checklistu ve sdíleném projektu |
1288
+ | `td_update_shared_checklist_item` | Aktualizace položky checklistu ve sdíleném projektu |
1289
+ | `td_delete_shared_checklist_item` | Smazání položky checklistu ve sdíleném projektu |
1290
+ | `td_list_shared_task_links` | Seznam vazeb úkolu ve sdíleném projektu |
1291
+ | `td_create_shared_task_link` | Vytvoření vazby mezi úkoly ve sdíleném projektu |
1292
+ | `td_delete_shared_task_link` | Smazání vazby ve sdíleném projektu (soft delete) |
1293
+ | `td_list_shared_task_comments` | Seznam komentářů úkolu ve sdíleném projektu |
1294
+ | `td_create_shared_task_comment` | Přidání komentáře k úkolu ve sdíleném projektu |
1295
+ | `td_update_shared_task_comment` | Aktualizace komentáře ve sdíleném projektu |
1296
+ | `td_delete_shared_task_comment` | Smazání komentáře ve sdíleném projektu |
1297
+ | `td_upload_shared_attachment` | Nahrání přílohy k úkolu ve sdíleném projektu |
1298
+ | `td_list_shared_attachments` | Seznam příloh úkolu ve sdíleném projektu |
1299
+ | `td_download_shared_attachment` | Stažení přílohy úkolu sdíleného projektu |
1300
+ | `td_delete_shared_attachment` | Smazání přílohy úkolu sdíleného projektu |
1301
+ | `td_list_shared_deployment_stages` | Seznam deployment stages pro sdílený projekt |
1302
+ | `td_create_shared_deployment_stage` | Vytvoření deployment stage ve sdíleném projektu |
1303
+ | `td_update_shared_deployment_stage` | Aktualizace deployment stage ve sdíleném projektu |
1304
+ | `td_delete_shared_deployment_stage` | Smazání deployment stage ve sdíleném projektu |
1305
+ | `td_list_shared_repository_links` | Seznam repozitářových linků sdíleného projektu |
1306
+ | `td_create_shared_repository_link` | Vytvoření repozitářového linku ve sdíleném projektu |
1307
+ | `td_update_shared_repository_link` | Aktualizace repozitářového linku ve sdíleném projektu |
1308
+ | `td_delete_shared_repository_link` | Smazání repozitářového linku ve sdíleném projektu |
1309
+ | `td_list_shared_project_notes` | Seznam poznámek sdíleného projektu (rejstřík, obsah až na `includeContent`) |
1310
+ | `td_get_shared_project_note` | Jedna poznámka sdíleného projektu včetně obsahu |
1311
+ | `td_create_shared_project_note` | Vytvoření poznámky ve sdíleném projektu |
1312
+ | `td_update_shared_project_note` | Aktualizace poznámky ve sdíleném projektu |
1313
+ | `td_delete_shared_project_note` | Smazání poznámky ve sdíleném projektu |
1314
+ | `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) |
1315
+ | `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 |
1316
+ | `td_upload_shared_note_attachment` | Nahrání přílohy k poznámce sdíleného projektu |
1317
+ | `td_list_shared_note_attachments` | Seznam příloh poznámky sdíleného projektu |
1318
+ | `td_download_shared_note_attachment` | Stažení přílohy poznámky sdíleného projektu |
1319
+ | `td_delete_shared_note_attachment` | Smazání přílohy poznámky sdíleného projektu |
1320
+ | `td_list_shared_project_docs` | Seznam dokumentů sdíleného projektu (rejstřík, obsah až na `includeContent`) |
1321
+ | `td_get_shared_project_doc` | Jedna stránka dokumentace sdíleného projektu včetně obsahu |
1322
+ | `td_create_shared_project_doc` | Vytvoření dokumentu ve sdíleném projektu |
1323
+ | `td_update_shared_project_doc` | Aktualizace dokumentu ve sdíleném projektu |
1324
+ | `td_delete_shared_project_doc` | Smazání dokumentu ve sdíleném projektu |
1325
+ | `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ářů) |
1326
+ | `td_list_shared_task_tags` | Tagy úkolu ve sdíleném projektu |
1327
+ | `td_bulk_update_shared_tasks` | Hromadná úprava úkolů ve sdíleném projektu |
1328
+ | `td_bulk_delete_shared_tasks` | Hromadné smazání úkolů ve sdíleném projektu (kaskáda na checklist a komentáře) |
1329
+ | `td_update_shared_worklog` | Úprava worklogu ve sdíleném projektu |
1330
+ | `td_list_shared_activity_log` | Aktivita ve sdíleném projektu (stejné filtry jako u osobní) |
1331
+
1332
+ > **Oprávnění, `ownerSecret` a historie ve sdílených projektech (TODO-434).**
1333
+ >
1334
+ > - **`ownerSecret` je nepovinný a nemá se posílat.** Každý sdílený nástroj si ho
1335
+ > najde ve vašem `projectRef` podle `sharedOwnerId` a `td_list_shared_projects`
1336
+ > ho už nevrací. Secret je klíč k celému projektu, takže dřív ležel v kontextu
1337
+ > modelu i v každém přepisu konverzace. Kdo ho pošle, tomu to dál funguje
1338
+ > (a kontroluje se proti `sharedOwnerId`).
1339
+ > - **Zápisy hlídají oprávnění stejně jako appka** (`src/permissions.ts`, port
1340
+ > appkového `permissions.ts`). Úkoly, worklogy, checklist, komentáře, přílohy,
1341
+ > vazby, přiřazení štítků, poznámky a dokumenty chtějí `write` nebo `admin`.
1342
+ > Nastavení projektu (`td_update_shared_project` včetně mazání a obnovy),
1343
+ > deployment stages, repozitářové linky, správa štítků a členové chtějí
1344
+ > vlastníka nebo `admin`. Bez `projectRef` se zápis odmítne, čtení jde dál.
1345
+ > Odmítnutí přijde jako chyba a nic se nezapíše.
1346
+ > - **Členy MCP spravuje jen napůl.** Appka po každé změně člena rotuje
1347
+ > zapisovací klíč nebo předá ten současný, jinak zablokovaný člen zapisuje dál.
1348
+ > MCP rotovat neumí, takže změny, po kterých člen nesmí zapisovat (block,
1349
+ > kick, zamítnutí, snížení na `read`), odmítne s odkazem na appku. Schválení,
1350
+ > odblokování a povýšení projdou, jen dokud projekt nemá rotovaný klíč.
1351
+ > - **Sdílené zápisy píšou historii** do sdílené instance, stejné záznamy jako
1352
+ > appka (úkol vytvořen/upraven po polích/smazán, worklog, checklist, komentář,
1353
+ > příloha, štítek, stage, repozitář, projekt, člen), s `actorId` vašeho účtu
1354
+ > a `source: "mcp"` v metadatech.
1355
+ > - **Mazání neexistujícího id** vrací chybu místo `success` a hromadné mazání ho
1356
+ > počítá mezi přeskočené. `td_update_shared_project` vybírá řádek projektu
1357
+ > stejně jako appka (nejstarší živý) a umí ho obnovit z koše.
1358
+ > - **Kód projektu** smí obsahovat jen `A-Z` a `0-9` a souběžná volání
1359
+ > `td_create_task` / `td_create_shared_task` do jednoho projektu už nedostanou
1360
+ > stejný kód.
1330
1361
 
1331
- Broadcast notices for every user. Writing, and listing expired ones, needs `TODOCKO_RELAY_ADMIN_KEY`.
1362
+ > **Stavy úkolů a validace argumentů (TODO-296, TODO-297).** Stav
1363
+ > `recurring` je plnohodnotný, appka ho používá pro opakované úkoly a MCP ho
1364
+ > teď nabízí ve všech devíti enumech. Zároveň se **kontrolují hodnoty enumů a
1365
+ > odmítají nedeklarované argumenty**. Dřív byly enumy jen dokumentace a
1366
+ > neznámý argument se tiše zahodil, což je přesně způsob, jak
1367
+ > `td_create_shared_checklist_item` přijal `isChecked`, vrátil `success`
1368
+ > a položku založil neodškrtnutou. Ten argument tam dnes je.
1369
+ >
1370
+ > Při té příležitosti se srovnal i `linkType`: MCP nabízelo `related`, kterému
1371
+ > appka nerozumí, a chyběly mu `explicit` a `mention`, které appka opravdu
1372
+ > zapisuje. Platné hodnoty jsou `blocks`, `explicit`, `mention`.
1332
1373
 
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)
1374
+ > **Rodič se ověřuje, argumenty jsou dorovnané (TODO-300, TODO-302).**
1375
+ > `td_create_task_comment` a `td_create_checklist_item` šly dřív založit na
1376
+ > **neexistující úkol**: řádek se zapsal proti ID, které nic nerozřeší, každý
1377
+ > výpis jde přes `taskId`, takže ho nikdo nikdy nepřečte, a tool vrátil
1378
+ > `success`. `td_add_worklog` to odmítal od TODO-90 M12, tyhle dva ne. Teď
1379
+ > odmítají obě strany, osobní i sdílená, a sdílená scopuje i podle ownera.
1380
+ >
1381
+ > Zároveň se dorovnalo devět argumentů, které sdílené tooly proti osobním
1382
+ > neměly. Nejcitelnější byl `td_update_shared_project`: uměl jen archivaci,
1383
+ > takže **sdílený projekt nešlo přejmenovat**.
1337
1384
 
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. |
1385
+ ### Zprávy od uživatelů (relay)
1343
1386
 
1344
- ### User Messages (relay)
1387
+ Zprávy, které uživatelé posílají z aplikace (hlášení vad, návrhy, vzkazy).
1388
+ Výpis a mazání umí jen **admin owner** a relay od TODO-90 H2 nevěří samotnému
1389
+ `ownerId` – požadavek se podepisuje Ed25519 klíčem odvozeným z nastaveného
1390
+ mnemoniku. Odesílání relay nechává nepřihlášené, stejně jako formulář v appce.
1345
1391
 
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.
1392
+ | Nástroj | Popis |
1393
+ |---------|-------|
1394
+ | `td_list_user_messages` | Výpis zpráv od uživatelů (jen admin owner) |
1395
+ | `td_submit_user_message` | Odeslání zprávy adminům (hlášení vady, návrh, vzkaz) |
1396
+ | `td_delete_user_message` | Smazání zprávy na relayi (jen admin owner, tvrdé smazání) |
1347
1397
 
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. |
1398
+ ### Analytika a přehledy
1353
1399
 
1354
- ### Analytics & Reports
1400
+ | Nástroj | Popis |
1401
+ |---------|-------|
1402
+ | `td_get_dashboard_summary` | Přehled: úkoly dnes, po termínu, odpracováno tento týden, nadcházející deadline |
1403
+ | `td_get_team_workload` | Vytížení týmu: odpracováno vs odhad vs kapacita per uživatel za období |
1404
+ | `td_list_recurring_tasks` | Seznam opakujících se úkolů s konfigurací opakování |
1405
+ | `td_list_overdue_tasks` | Úkoly po termínu (seřazené od nejstaršího) |
1355
1406
 
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) |
1407
+ > **Do v1.6.0 tyhle tři nástroje vracely vždy prázdno.** `td_list_recurring_tasks`,
1408
+ > `td_list_overdue_tasks` a `td_list_tasks_by_date_range` čtly `result.rows`,
1409
+ > zatímco `evolu.loadQuery` vrací pole samo – takže `count: 0` na jakýkoli vstup,
1410
+ > bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný
1411
+ > `queryRows`. Recurrence pole navíc vrací i `td_get_task`, takže nastavení
1412
+ > opakování jde přečíst tou nejpřímější cestou.
1413
+ | `td_list_tasks_by_date_range` | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí |
1414
+ | `td_analyze_dependencies` | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |
1362
1415
 
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 |
1416
+ > **Sdílené projekty se do analytiky počítají (TODO-112).** Do MCP IX čtlo všech
1417
+ > pět přehledů jen osobní instanci, takže úkol ve sdíleném projektu neviděl
1418
+ > dashboard, rozdělení vytížení, seznam opakujících se ani po termínu, ani dotaz
1419
+ > na rozmezí dat. U vytížení to nebylo jen chybějící číslo: počítá se
1420
+ > z odpracovaného času, takže vynechané sdílené minuty podhodnocovaly každého,
1421
+ > kdo ve sdíleném projektu pracuje. Každý nástroj bere `includeShared`
1422
+ > (výchozí `true`) a vrací `sharedIncluded`, ať je vidět, jestli se sdílená
1423
+ > polovina opravdu načetla. `td_analyze_dependencies` zůstává záměrně jen
1424
+ > osobní: appka sdílené `taskLink` řádky čte, ale žádné nezapisuje.
1425
+ >
1426
+ > `td_search_tasks` hledá ve sdílených projektech taky, se stejným přepínačem.
1371
1427
 
1372
- ### Diagnostics
1428
+ ### Diagnostika
1373
1429
 
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) |
1430
+ | Nástroj | Popis |
1431
+ |---------|-------|
1432
+ | `td_sync_status` | Stav synchronizace |
1433
+ | `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
1434
 
1379
- ## Usage Examples
1435
+ ## Příklady použití
1380
1436
 
1381
- ### List projects
1437
+ ### Seznam projektů
1382
1438
  ```
1383
- Show me all projects in Todocko
1439
+ Zobraz mi seznam všech projektů v Todocko
1384
1440
  ```
1385
1441
 
1386
- ### List tasks
1442
+ ### Seznam úkolů
1387
1443
  ```
1388
- What tasks do I have with status "todo"?
1389
- Show tasks for project TODO
1444
+ Jaké mám úkoly ve stavu "todo"?
1445
+ Zobraz úkoly projektu TODO
1390
1446
  ```
1391
1447
 
1392
- ### Task details
1448
+ ### Detail úkolu
1393
1449
  ```
1394
- What are the details of task TODO-15?
1450
+ Jaké jsou detaily úkolu TODO-15?
1395
1451
  ```
1396
1452
 
1397
- ### Create task
1453
+ ### Vytvoření úkolu
1398
1454
  ```
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
1455
+ Vytvoř nový úkol v projektu PROJ s názvem "Opravit bug v přihlášení" a prioritou high
1456
+ Vytvoř úkol s deadline na 2026-03-15 a scheduledDate na 2026-03-10
1401
1457
  ```
1402
1458
 
1403
- ### Update task
1459
+ ### Aktualizace úkolu
1404
1460
  ```
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
1461
+ Označ úkol PROJ-5 jako dokončený
1462
+ Přiřaď úkol TODO-10 uživateli s ID xyz
1463
+ Nastav scheduledDate úkolu TODO-10 na zítra
1408
1464
  ```
1409
1465
 
1410
- ### Log time
1466
+ ### Logování času
1411
1467
  ```
1412
- Log 2 hours of work on task TODO-15 with description "Feature implementation"
1468
+ Zaloguj 2 hodiny práce na úkol TODO-15 s popisem "Implementace feature"
1413
1469
  ```
1414
1470
 
1415
- ### Working with attachments
1471
+ ### Práce s přílohami
1416
1472
  ```
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
1473
+ Nahraj soubor /home/user/report.pdf jako přílohu k úkolu TODO-15
1474
+ Jaké přílohy má úkol TODO-15?
1475
+ Smaž přílohu s ID xyz
1420
1476
  ```
1421
1477
 
1422
- ### Shared projects
1478
+ ### Sdílené projekty
1423
1479
  ```
1424
- Show shared projects
1425
- What tasks are in the shared project?
1426
- Mark task as deployed to production
1480
+ Zobraz sdílené projekty
1481
+ Jaké úkoly jsou ve sdíleném projektu?
1482
+ Označ úkol jako nasazený na produkci
1427
1483
  ```
1428
1484
 
1429
1485
  ### Deployment stages
1430
1486
  ```
1431
- What deployment stages does the project have?
1432
- Create a new deployment stage "Staging" for the shared project
1487
+ Jaké deployment stages má projekt?
1488
+ Vytvoř novou deployment stage "Staging" pro sdílený projekt
1433
1489
  ```
1434
1490
 
1435
- ### Sub-tasks
1491
+ ### Sub-úkoly
1436
1492
  ```
1437
- Create a sub-task for task TODO-15 in project TODO
1438
- Detach task TODO-20 from its parent (parentTaskId: null)
1493
+ Vytvoř sub-úkol k úkolu TODO-15 v projektu TODO
1494
+ Odpoj úkol TODO-20 od rodičovského úkolu (parentTaskId: null)
1439
1495
  ```
1440
1496
 
1441
- ### Analytics & Reports
1497
+ ### Přehledy a analytika
1442
1498
  ```
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?
1499
+ Jaký mám dnes přehled? (dashboard summary)
1500
+ Jak je vytížený tým tento týden?
1501
+ Jaké úkoly jsou po termínu?
1502
+ Zobraz úkoly naplánované na příští týden
1503
+ Analyzuj závislosti v projektu TODO
1504
+ Jaké mám opakující se úkoly?
1449
1505
  ```
1450
1506
 
1451
- ## Security
1507
+ ## Linux CLI (`todo`) (TODO-160)
1452
1508
 
1453
- **Important:** Your backup phrase (mnemonic) is sensitive data!
1509
+ 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`.
1510
+
1511
+ 📖 **Podrobný návod: [CLI.md](CLI.md)**
1512
+
1513
+ ```bash
1514
+ # Přidání úkolu (bez -p použije první projekt)
1515
+ todo add "Opravit login"
1516
+ todo add "Opravit login" -p TODO --priority high --scheduled today
1517
+
1518
+ # Změna stavu (identifikace kódem úkolu)
1519
+ todo done TODO-160 # status=done
1520
+ todo start TODO-160 # status=in_progress
1521
+ todo mv TODO-160 review # backlog|todo|in_progress|review|done|recurring
1522
+
1523
+ # Worklog
1524
+ todo log TODO-160 1h30m "ladění OAuth"
1525
+ todo worklogs TODO-160 # tabulka worklogů
1526
+
1527
+ # Strojový výstup na všech příkazech
1528
+ todo add "X" --json
1529
+ ```
1530
+
1531
+ - **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`.
1532
+ - **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ě).
1533
+ - **Exit kódy:** `0` úspěch, `1` user/business chyba (neznámý kód, špatný stav/čas), `2` config (chybí mnemonic).
1534
+ - **Barvy** jen v TTY a při nenastaveném `NO_COLOR`.
1535
+ - **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.
1536
+
1537
+ ## Bezpečnost
1538
+
1539
+ **Důležité:** Vaše zálohovací fráze (mnemonic) je citlivý údaj!
1540
+
1541
+ - Nikdy ji nesdílejte v přímé konverzaci s AI
1542
+ - MCP server frázi nevystavuje přes žádný nástroj: nejde ji z Todočka přečíst ani vypsat
1543
+ - To ale neznamená, že k ní AI nemá přístup. Agent, který umí spouštět příkazy nebo číst
1544
+ soubory (Claude Code a podobní), si `~/.claude.json` nebo `~/.claude/settings.json`
1545
+ přečte stejně jako kterýkoli jiný soubor. Konfigurace chrání frázi před nástroji MCP,
1546
+ ne před shellem. (TODO-441)
1547
+ - Kdokoli s vaší frází má plný přístup k vašim datům
1548
+
1549
+ ### Kontrola argumentů a cest (TODO-441)
1550
+
1551
+ - Hodnoty argumentů se kontrolují proti typu, který nástroj deklaruje. `isBlocked: "false"`
1552
+ se dřív ukládalo jako `true` (neprázdný řetězec je pravdivý), teď je to chyba.
1553
+ - Datová pole (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`, `startDate`,
1554
+ `endDate`, …) musí být `YYYY-MM-DD`; kde schéma mluví o datetime (`completedAt`,
1555
+ `expiresAt`, `from`/`to` v activity logu), projde i ISO datetime. `deadline: "zítra"`
1556
+ se dřív uložilo doslova a nikdo se to nedozvěděl.
1557
+ - Přílohy: cesty se vyhodnocují až po rozpadnutí symlinků, takže odkaz uvnitř povoleného
1558
+ adresáře už nevede ven. Stahování nově odmítá tečkové soubory (stejně jako nahrávání)
1559
+ a nepřepíše existující soubor, dokud nepošleš `overwrite: true`.
1560
+
1561
+ ### WebSocket Origin (TODO-169)
1562
+
1563
+ 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.
1564
+
1565
+ ### Rotace zapisovacího klíče sdílených projektů (TODO-268)
1566
+
1567
+ Když vlastník sdíleného projektu někoho vyhodí, aplikace vymění zapisovací klíč
1568
+ projektu na relayi. Klíč odvozený z `ownerSecret` tím přestane platit a relay
1569
+ s ním odmítne každý zápis.
1454
1570
 
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
1571
+ MCP server si nový klíč načte ze sloupce `projectRef.writeKey`, který do jeho
1572
+ databáze přiteče běžným syncem AppOwnera. Kontrola běží při startu a pak každou
1573
+ minutu, takže po rotaci může být zhruba minuta, kdy zápisy do toho jednoho
1574
+ projektu relay odmítá a řádky čekají lokálně. Čtení rotace neovlivňuje.
1462
1575
 
1463
- ### Argument and path checks (TODO-441)
1576
+ ### Komu klíč patří: nárok versus grant (TODO-440)
1464
1577
 
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.
1578
+ `projectMember.permission` si zapisuje sám člen, takže o tom, kdo dostane
1579
+ zapisovací klíč, rozhodovat nemůže. Vlastník si vede vlastní záznam ve své
1580
+ osobní instanci, kam žádný člen nedosáhne:
1474
1581
 
1475
- ### Shared project write key rotation (TODO-268)
1582
+ - `shareInvite` na každý vygenerovaný odkaz, její id cestuje v tokenu,
1583
+ - `memberGrant` na každého člena, jehož oprávnění vlastník nastavil ručně,
1584
+ a ten pozvánku přebíjí.
1476
1585
 
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.
1586
+ Člen si id pozvánky neukládá, ten řádek čtou i ostatní členové a mohli by si ho
1587
+ opsat. Ukládá si do `projectMember.inviteProof` HMAC vlastní identity klíčovaný
1588
+ id pozvánky; vlastník, který id má, ho ověří, cizí člen si ho pro sebe nevyrobí.
1589
+ Skutečné oprávnění je to nižší z nároku a záznamu.
1480
1590
 
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.
1591
+ `td_list_shared_members` proto vlastníkovi vrací navíc `verifiedPermission`
1592
+ a `effectivePermission` a `td_update_shared_member` zapisuje `memberGrant`
1593
+ spolu se změnou nároku. Dokud to MCP neumělo, změnilo povýšení přes MCP jen
1594
+ nárok: člen zapisovací klíč nedostal a appka u něj začala hlásit, že si
1595
+ nárokuje víc, než má potvrzeno.
1485
1596
 
1486
- ## Data Location
1597
+ ## Umístění dat
1487
1598
 
1488
- Databases are stored in the `~/.todocko/` directory:
1599
+ Databáze jsou uloženy v adresáři `~/.todocko/`:
1489
1600
 
1490
- | Platform | Path |
1491
- |----------|------|
1601
+ | Platforma | Cesta |
1602
+ |-----------|-------|
1492
1603
  | Linux | `~/.todocko/` |
1493
1604
  | macOS | `~/.todocko/` |
1494
1605
  | Windows | `C:\Users\<user>\.todocko\` |
1495
1606
 
1496
- Files:
1497
- - `todocko.db` - your personal data (tasks, projects)
1498
- - `todocko-shared.db` - shared projects
1607
+ Soubory:
1608
+ - `todocko.db` - vaše osobní data (úkoly, projekty)
1609
+ - `todocko-shared.db` - sdílené projekty
1499
1610
 
1500
- ## Configuration Changes
1611
+ ## Změna konfigurace
1501
1612
 
1502
1613
  ### Claude Code (CLI)
1503
1614
 
1504
- After changing configuration in `~/.claude/settings.json` (e.g., changing mnemonic), run the command:
1615
+ Po změně konfigurace v `~/.claude/settings.json` (např. změna mnemonicu) spusťte příkaz:
1505
1616
  ```
1506
1617
  /mcp
1507
1618
  ```
1508
- This will restart the MCP server with the new configuration.
1619
+ Tím se MCP server restartuje s novou konfigurací.
1509
1620
 
1510
- ### Switching to a Different Account
1621
+ ### Přepnutí na jiný účet
1511
1622
 
1512
- When changing the mnemonic to a **different Todocko account**, you need to delete the local database:
1623
+ Při změně mnemonicu na **jiný Todocko účet** je potřeba smazat lokální databázi:
1513
1624
 
1514
1625
  ```bash
1515
1626
  # Linux/macOS
@@ -1519,126 +1630,182 @@ rm ~/.todocko/todocko.db
1519
1630
  del %USERPROFILE%\.todocko\todocko.db
1520
1631
  ```
1521
1632
 
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.
1633
+ 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
1634
 
1524
1635
  ## Troubleshooting
1525
1636
 
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
1637
+ ### Server se nespustí
1638
+ - Zkontrolujte, že máte Node.js 24.20+
1639
+ - Zkontrolujte, že jste spustili `npm run build`
1640
+ - Zkontrolujte logy v Claude Desktop
1530
1641
 
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
1642
+ ### Data se nesynchronizují
1643
+ - Ověřte, že je zálohovací fráze správná (24 slov)
1644
+ - Zkontrolujte internetové připojení
1645
+ - Počkejte pár sekund na synchronizaci
1646
+ - Zkuste smazat `~/.todocko/todocko.db` a restartovat
1536
1647
 
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
1648
 
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.
1649
+ ### `status: relay-blocked` v `td_sync_status` (TODO-112)
1547
1650
 
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)
1651
+ Relay odpovídá na HTTPS, ale WebSocket nepropustí. Mezi strojem a relayí tedy
1652
+ něco blokuje upgrade spojení, typicky proxy nebo firewall, ne vada relaye.
1653
+ Zápisy se drží lokálně a odejdou, jakmile socket projde. Od `no-relay` se to
1654
+ liší tím, že tam neodpovídá vůbec nic, což znamená spíš výpadek sítě.
1552
1655
 
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.
1656
+ ### Nástroje nejsou viditelné
1657
+ - Restartujte Claude Desktop
1658
+ - V Claude Code použijte `/mcp` pro reload
1659
+ - Zkontrolujte konfigurační soubor
1660
+ - Zkontrolujte cestu k dist/index.js
1661
+
1662
+ ### `project ... is a shared project` při zápisu
1663
+ Sdílený projekt má svá data ve **sdílené instanci**. Osobní nástroje
1664
+ (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) proto zápis do
1665
+ takového projektu odmítnou a pošlou tě na `td_*_shared_*` protějšek.
1666
+
1667
+ Dřív se zápis tiše uložil do osobní instance vedle skutečného řádku. Vznikly
1668
+ tím dvě kopie téhož úkolu v různých instancích, které se rozcházely: aplikace
1669
+ čte sdílenou stranu, MCP `td_list_tasks` osobní, takže každý ukazoval něco
1670
+ jiného a nic to nehlásilo. (TODO-318)
1671
+
1672
+ **Mazání zůstává povolené i pro sdílený projekt**, jinak by staré osobní kopie
1673
+ nešlo uklidit. `td_search_tasks` s `includeShared` ukáže obě kopie vedle sebe a
1674
+ je proto nejrychlejší způsob, jak zjistit, že je úkol rozdvojený.
1675
+
1676
+ ### Kód úkolu se teď přidělit nedá (TODO-373)
1677
+ `td_create_task` odvozuje kód z nejvyššího, který v téhle kopii vidí. Když část
1678
+ účtu ještě nedorazila, je maximum nižší než skutečné a vznikne kód, který na
1679
+ relayi už existuje. Stalo se to 2026-09-23: v 07:01 kopie neměla TODO-360 až
1680
+ 367 a server vyrobil TODO-353 a dál, v 09:33 už je nad stejným souborem měla
1681
+ a navázal správně na 368. Nic se nerozbilo jen proto, že 353 až 359 byla shodou
1682
+ okolností volná.
1683
+
1684
+ Před přidělením kódu se proto porovná počet zpráv: Evolu jich drží po jedné
1685
+ v `evolu_timestamp`, relay hlásí stejné číslo pro ownera. Naměřeno 81 130 na
1686
+ obou stranách. Když je kopie pozadu, zápis se odmítne a řekne, kolik zpráv
1687
+ chybí; až se sync dotáhne, projde. Když se relay zeptat nedá, zápis projde:
1688
+ odmítat i tam by z lokálně prvního nástroje udělalo nástroj závislý na síti.
1689
+
1690
+ Aktuální stav ukáže `td_sync_status` v poli `copy`.
1691
+
1692
+ **Sdílené projekty tenhle strážce nemají.** Jejich úkoly patří jinému ownerovi
1693
+ s vlastním počtem zpráv a zeptat se na něj chce jeho klíč, ne ten odvozený
1694
+ z mnemoniky. Měřit tam app ownera by vypadalo jako pokrytí a nebylo by.
1557
1695
 
1558
1696
  ### `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.
1697
+ Druhá instance nad stejnou zálohovací frází se odmítne nastartovat. Není to
1698
+ opatrnost navíc: klientská databáze jede v režimu `journal_mode=delete`
1699
+ s nulovým `busy_timeout`, takže druhý proces dostane SQLITE_BUSY okamžitě,
1700
+ Evolu z toho udělá `PanicAbortReason: database is locked` a **prvnímu** procesu
1701
+ umře dbWorker. Do TODO-341 tak nové okno tiše shodilo to, ve kterém jsi pracoval
1702
+ (projevilo se jako `status: worker-dead`, viz níž).
1565
1703
 
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.
1704
+ Zámek je soubor `~/.todocko/todocko-<owner>.lock` vedle databáze. Drží pid,
1705
+ který ho vzal; po pádu procesu se pozná jako neaktuální a další start si ho
1706
+ vezme.
1569
1707
 
1570
- If you really need a second instance (the `todo` CLI next to the MCP, say), give
1571
- it its own database name:
1708
+ Samotné `process.kill(pid, 0)` na to nestačí (TODO-372). **Zombie procesem ten
1709
+ test projde**: proces, který skončil, ale rodič ho nesklidil, je pořád
1710
+ v tabulce procesů a signál 0 na něm uspěje. Zámek pak vypadá jako věčně držený
1711
+ a žádná nová instance se nespustí. Stalo se to 2026-09-22, kdy byl držitel ve
1712
+ stavu `Z` a jeho rodič zastavený `claude` ve stavu `Tl`, takže neměl kdo
1713
+ sklízet. Na Linuxu se proto čte stav z `/proc/<pid>/stat` a `Z` se bere jako
1714
+ mrtvý. Kde `/proc` není, zůstává původní chování.
1715
+
1716
+ Když potřebuješ druhou instanci doopravdy (třeba CLI `todo` vedle MCP), spusť ji
1717
+ s vlastním jménem databáze:
1572
1718
  ```bash
1573
1719
  TODOCKO_INSTANCE=cli todo ...
1574
1720
  ```
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`)
1721
+ Dostane `~/.todocko/todocko-cli-<owner>.db`, tedy vlastní lokální kopii, která
1722
+ se s tou první srovná přes relay. Povolené znaky jsou `a-z0-9-`, zbytek se
1723
+ zahodí; prázdná hodnota znamená výchozí databázi.
1581
1724
 
1582
- There are two causes, told apart by what the server says.
1725
+ ### Worker umřel za běhu (`status: worker-dead`)
1726
+ Proces normálně naběhl a po nějaké době přestal odpovídat. `td_sync_status`
1727
+ vrátí `status: "worker-dead"` a v `workerDefects` je panika i s časem. Dotazy
1728
+ v tomhle stavu selžou **hned**, ne až po 15 s. Řešení je `/mcp` reconnect.
1729
+ Nejčastější příčina je druhý MCP proces nad stejnou databází; od TODO-341 se
1730
+ druhá instance nenastartuje, takže tuhle cestu k mrtvému workeru už nemá jak
1731
+ způsobit.
1583
1732
 
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.
1733
+ ### Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)
1589
1734
 
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.
1735
+ Příčiny jsou dvě, poznáte je podle toho, co server řekne.
1596
1736
 
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.
1737
+ **1. Mrtvý dbWorker po závodu dvou procesů (TODO-316).** Dva MCP procesy, které
1738
+ současně zakládají schéma téže databáze, se porvou. Poražený dostane
1739
+ `SqliteError: table evolu_version already exists` a jeho dbWorker zůstane
1740
+ mrtvý do konce života procesu. Typicky při prvních startech po upgradu MCP,
1741
+ který přidá tabulku.
1598
1742
 
1599
- Typical symptoms: `td_sync_status` reports `ok` with `errorCount: 0`, but `td_get_task`, `td_list_*`, etc. all time out.
1743
+ Od TODO-316 to server pozná při startu a **odmítne se nastartovat**: každé
1744
+ volání nástroje hned vrátí `Evolu dbWorker never answered`. Od TODO-317 se
1745
+ navíc zapíše i **proč** worker umřel, do `workerDefects` v `td_sync_status`
1746
+ a do stderr jako `FATAL: Evolu dbWorker defect: ...`. Dřív se tvářil
1747
+ zdravě a každý dotaz visel, dokud to klient po 1800 s nevzdal. Řešení je `/mcp`
1748
+ reconnect v Claude Code.
1600
1749
 
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.
1750
+ **2. Databáze, kterou nový driver neotevře.** Od TODO-448 je klientská databáze
1751
+ šifrovaná a starou, plaintextovou, nový driver odmítne: `file is not a database`.
1752
+ Symptom je stejný jako u všech vad dbWorkeru, tedy `Evolu dbWorker never answered`
1753
+ u každého volání. Řešení je smazat `~/.todocko/todocko*-<ownerId>.db` a nechat
1754
+ data stáhnout z relaye; předtím se ujistit přes `td_sync_status`, že nic nečeká
1755
+ na odeslání.
1608
1756
 
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.
1757
+ Dřív tu stával mismatch native bindingu better-sqlite3 (`ERR_DLOPEN_FAILED` po
1758
+ upgradu Node nebo přepnutí mezi nvm a brew). `@evolu/nodejs` 4.4 ho nahradilo
1759
+ předpřipraveným SQLite, takže se nic nekompiluje a tahle třída chyb zmizela.
1610
1760
 
1611
- ## Development
1761
+ ## Vývoj
1612
1762
 
1613
1763
  ```bash
1614
- # Install dependencies
1764
+ # Instalace závislostí
1615
1765
  npm install
1616
1766
 
1617
1767
  # Build
1618
1768
  npm run build
1619
1769
 
1620
- # Watch mode for development
1770
+ # Watch mode pro vývoj
1621
1771
  npm run dev
1622
1772
 
1623
- # Tests
1773
+ # Testy
1624
1774
  npm test
1625
1775
 
1626
- # Manual run
1627
- TODOCKO_MNEMONIC="your phrase" npm start
1776
+ # Ruční spuštění
1777
+ TODOCKO_MNEMONIC="vaše fráze" npm start
1628
1778
  ```
1629
1779
 
1630
1780
  ### Testy
1631
1781
 
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
1782
+ Vitest. **Sada běží v CI** (`ci.yml`, push i PR na `main`)
1783
+ od TODO-229 – do té doby CI spouštěla jen build, takže se nikdo nedozvěděl, že
1634
1784
  `helpers.test.ts` na Node 18/20 **ani neprojde importem**: přes `helpers.ts`
1635
1785
  tahal `../evolu.js`, jehož inicializace při načtení modulu spadne na
1636
1786
  `crypto.getRandomValues must be defined`.
1637
1787
 
1638
1788
  Proto jsou funkce bez závislosti na Evolu v **`src/tools/pure.ts`** a testují se
1639
1789
  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
1790
+ který Evolu nepotřebuje, patří do `pure.ts` – jinak ho nejde testovat bez
1641
1791
  nastartované databáze.
1642
1792
 
1643
- Závazná verze je **Node 24.20 nebo novější** — je v `engines` a Evolu v8 na
1793
+ Závazná verze je **Node 24.20 nebo novější** – je v `engines` a Evolu v8 na
1644
1794
  starším neběží. Na té jede `ci.yml` i `release.yml`.
1795
+
1796
+ ### Vydání
1797
+
1798
+ ```bash
1799
+ npm version patch # nebo minor / major
1800
+ git push --follow-tags
1801
+ ```
1802
+
1803
+ Tag spustí `release.yml`: sestaví, pustí testy, ověří, že tag souhlasí
1804
+ s `package.json`, a vydání na npm **zařadí do fronty** i s podepsanou
1805
+ provenance. Žádné přihlašovací údaje k npm v repozitáři nejsou, runner si o
1806
+ krátkodobé oprávnění řekne sám přes trusted publishing (OIDC).
1807
+
1808
+ Fronta je tam schválně. K nikomu se verze nedostane, dokud ji neschválíš na
1809
+ npmjs.com v **Staged Packages**, případně přes `npm stage list todocko-mcp`
1810
+ a `npm stage approve <stage-id>`. Schválení chce 2FA, takže ani ovládnutý běh
1811
+ workflow nedokáže poslat verzi uživatelům sám.