{#each filtered() as iconName}
diff --git a/plans/phase-10-telegram-commands.md b/plans/phase-10-telegram-commands.md
index 8eb6f16..8ae05cf 100644
--- a/plans/phase-10-telegram-commands.md
+++ b/plans/phase-10-telegram-commands.md
@@ -14,61 +14,127 @@ Define and implement Telegram bot commands that users can invoke directly from c
## Proposed Commands
### Informational
+
- `/status` — Show tracker status (active trackers, last event, server health)
- `/albums` — List tracked albums with asset counts
- `/events [N]` — Show last N events (default 5)
### On-Demand Notifications
+
- `/summary` — Trigger periodic summary now
-- `/latest [album]` — Show latest assets from an album (or all)
+- `/latest [album] [N]` — Show latest assets from an album (or all)
- `/memory` — Trigger "On This Day" memory notification now
-- `/random [album]` — Send random photo(s) from an album
+- `/random [album] [N]` — Send random photo(s) from an album
### Asset Browsing
**IMPORTANT**: All asset commands MUST only search within albums that are tracked by the tracker(s) associated with the bot's target. Never expose assets from untracked albums.
-- `/search ` — Semantic/smart search via Immich CLIP ("dog on beach", "birthday party")
-- `/find ` — Text search by filename, description
-- `/person ` — Find photos with a specific person
-- `/place ` — Find photos by city/country/location
-- `/favorites [album]` — Show favorite assets
+- `/search [N]` — Semantic/smart search via Immich CLIP ("dog on beach", "birthday party")
+- `/find [N]` — Text search by filename, description
+- `/ocr [N]` — Search by text visible in photos/videos (OCR)
+- `/person [N]` — Find photos with a specific person
+- `/place [N]` — Find photos by city/country/location
+- `/favorites [album] [N]` — Show favorite assets
- `/people` — List detected people across albums
+All browsing commands accept optional `[N]` count limit (default configurable per bot, max: 20).
+
### Management
+
- `/help` — Show available commands with descriptions
---
+## Configuration (per bot)
+
+### Command Settings
+
+- **Enabled commands**: checkboxes per command (enable/disable individually)
+- **Default result count**: 1-20 (default: 5) — used when `[N]` is omitted
+- **Response mode**: `media` (send photos) or `text` (send links) — default per bot, overridable per command with inline suffix like `/search sunset --text`
+- **Rate limiting**: configurable cooldown per command category per chat (e.g. 30s for search, 10s for info). 0 = no limit.
+- **Bot locale**: EN/RU — used for command descriptions registered with Telegram and response messages
+
+---
+
## Tasks
### 1. Command registry model `[ ]`
-- New entity or config: list of enabled commands per bot
-- Admin can enable/disable individual commands per bot
-- Default set of commands enabled on bot registration
-### 2. Auto-register commands with Telegram `[ ]`
+- Add `commands_config` JSON field to TelegramBot model:
+ ```json
+ {
+ "enabled": ["status", "albums", "events", "search", "find", "help", ...],
+ "default_count": 5,
+ "response_mode": "media",
+ "rate_limits": {"search": 30, "find": 30, "ocr": 30, "default": 10},
+ "locale": "en"
+ }
+ ```
+- Default config set on bot registration
+
+### 2. Command descriptions & localization `[ ]`
+
+- Store command descriptions in both EN and RU:
+ ```
+ status: "Show tracker status" / "Показать статус трекеров"
+ albums: "List tracked albums" / "Список отслеживаемых альбомов"
+ events: "Show recent events" / "Показать последние события"
+ summary: "Send album summary now" / "Отправить сводку альбомов"
+ latest: "Show latest photos" / "Показать последние фото"
+ memory: "On This Day memories" / "Воспоминания за этот день"
+ random: "Send random photo" / "Отправить случайное фото"
+ search: "Smart search (AI)" / "Умный поиск (AI)"
+ find: "Search by text" / "Поиск по тексту"
+ ocr: "Search text in photos" / "Поиск текста на фото"
+ person: "Find photos of person" / "Найти фото человека"
+ place: "Find photos by location" / "Найти фото по месту"
+ favorites: "Show favorites" / "Показать избранное"
+ people: "List detected people" / "Список людей"
+ help: "Show available commands" / "Показать доступные команды"
+ ```
+- Bot response messages also localized based on bot locale setting
+- Descriptions editable per bot in the UI (override defaults)
+
+### 3. Auto-register commands with Telegram `[ ]`
+
- Call `setMyCommands` API when commands config changes
- Call on bot creation and on config update
-- Store command descriptions in i18n (EN/RU based on bot locale setting)
+- Use bot locale to select which descriptions to register
+- Telegram supports `setMyCommands` with `language_code` parameter — register both EN and RU descriptions simultaneously
### 3. Webhook command handler `[ ]`
+
- Extend existing webhook handler to route `/command` messages
-- Parse command + arguments
+- Parse command + arguments + optional count `[N]`
+- Check if command is enabled for this bot
+- Check rate limit per chat per command
- Execute corresponding logic (reuse existing services)
-- Return formatted response
+- Return response in configured mode (media or text)
### 4. Implement each command `[ ]`
+
- `/status`, `/albums`, `/events` — read from DB
-- `/summary`, `/memory`, `/latest`, `/random` — call watcher/notifier services
-- `/search`, `/favorites`, `/people` — call Immich API via core client
-- `/trackers`, `/targets` — read from DB, optional inline keyboard for toggle
-- `/help` — auto-generated from enabled commands
+- `/summary`, `/memory` — call watcher/notifier services
+- `/latest`, `/random` — fetch from Immich via core client, scoped to tracked albums
+- `/search` — call Immich `POST /api/search/smart` (CLIP), scoped to tracked albums
+- `/find` — call Immich `POST /api/search/metadata`, scoped to tracked albums
+- `/ocr` — call Immich `POST /api/search/smart` with OCR context, scoped to tracked albums
+- `/person` — filter tracked album assets by person name
+- `/place` — filter tracked album assets by city/country
+- `/favorites` — filter tracked album assets by is_favorite
+- `/people` — aggregate people from all tracked album assets
+- `/help` — auto-generated from enabled commands with descriptions
### 5. Frontend: command config per bot `[ ]`
+
- On telegram-bots page, expandable "Commands" section per bot
- Checkboxes to enable/disable each command
-- Bot locale selector (for command descriptions language)
+- Default count slider (1-20)
+- Response mode toggle (media/text)
+- Rate limit inputs per category
+- Bot locale selector (EN/RU)
- "Sync Commands" button (calls setMyCommands)
---
@@ -76,6 +142,9 @@ Define and implement Telegram bot commands that users can invoke directly from c
## Acceptance Criteria
- [ ] Commands registered with Telegram and visible in bot menu
-- [ ] Each command returns a useful response
+- [ ] Each command returns a useful response (media or text based on config)
- [ ] Commands auto-sync when config changes
- [ ] Admin can enable/disable commands per bot via UI
+- [ ] Rate limiting works per chat per command
+- [ ] All asset commands scoped to tracked albums only
+- [ ] Count limit configurable per bot with per-command override