v1.3.3

CoderLuii · CoderLuii · commit f50689561a9d · 2026-06-15T14:39:23.000-04:00
Context: Issue #38 reported Telegram notifications failing after following the documented NOTIFY_TELEGRAM example. Apprise 1.11.0 accepts tgram:// and rejects tg://, so the fix needs corrected docs plus runtime compatibility for existing compose files. What changed: Updated Telegram examples to tgram://, normalized legacy tg:// values before Apprise receives them, added dry-run/debug diagnostics with redacted output, covered notification parsing with unittest, and disabled Docker metadata's automatic latest tag so slim builds cannot publish latest. Verification: Ran python -m py_compile scripts/notify.py tests/test_notify.py; python -m unittest discover -s tests -p "test_*.py"; verified Apprise 1.11.0 rejects tg:// and accepts tgram://; validated compose configs; built and smoke-tested slim/full images with dry-run notification diagnostics; parsed docker-publish.yml with js-yaml; verified v1.3.2 workflow attempt 2 succeeded and Docker Hub tags point to expected full/slim digests. Release: v1.3.3 fixes issue #38 and hardens Docker release tagging. Constraint: Existing users may already have NOTIFY_TELEGRAM=tg://... in compose files Rejected: Docs-only fix | existing containers would still fail after following the old value Confidence: high Scope-risk: moderate Directive: Keep tgram:// as the documented Telegram scheme; do not remove legacy tg:// normalization without a migration window Tested: py_compile; unittest; Apprise 1.11.0 URL acceptance; compose config; local slim/full Docker builds; slim/full dry-run smoke; workflow YAML parse; v1.3.2 release workflow/tag verification Not-tested: v1.3.3 GitHub release workflow before tag push Related: #38
diff --git a/.dockerignore b/.dockerignore
@@ -19,6 +19,7 @@ workspace/
 .omc/
 evidence/
 .evidence/
+tests/
 
 # Environment and credentials
 .env
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
@@ -70,6 +70,8 @@ jobs:
           images: |
             ${{ env.DOCKERHUB_IMAGE }}
             ${{ env.GHCR_IMAGE }}
+          flavor: |
+            latest=false
           tags: |
             type=raw,value=latest,enable=${{ matrix.variant == 'full' }}
             type=raw,value=slim,enable=${{ matrix.variant == 'slim' }}
diff --git a/README.md b/README.md
@@ -398,7 +398,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -955,10 +955,17 @@ Walk away from your computer and know when a task is done. Claude Code hooks, ra
 1. Add one or more `NOTIFY_*` variables to your compose `environment`:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. Inside the container: `touch ~/.claude/notify-on`
 
+Telegram uses Apprise's `tgram://` scheme. Legacy Telegram values are still accepted, but new setups should use `tgram://`.
+
+Test the setup without sending a message:
+```bash
+docker compose exec holyclaude /usr/local/bin/notify.py test --dry-run --debug
+```
+
 See [configuration docs](docs/configuration.md#notifications-apprise) for all supported variables and URL formats.
 
 **To disable:** `rm ~/.claude/notify-on`
diff --git a/config/claude-memory-full.md b/config/claude-memory-full.md
@@ -141,6 +141,8 @@ Optional push notifications via [Apprise](https://github.com/caronc/apprise) —
 1. Set one or more `NOTIFY_*` environment variables (e.g. `NOTIFY_DISCORD`, `NOTIFY_TELEGRAM`, `NOTIFY_PUSHOVER`)
 2. Create the flag file: `touch ~/.claude/notify-on`
 
+Telegram uses `NOTIFY_TELEGRAM=tgram://bot_token/chat_id`. Check setup without sending: `/usr/local/bin/notify.py test --dry-run --debug`.
+
 **To disable:** `rm ~/.claude/notify-on`
 
 **Events:**
diff --git a/config/claude-memory-slim.md b/config/claude-memory-slim.md
@@ -172,6 +172,8 @@ Optional push notifications via [Apprise](https://github.com/caronc/apprise) —
 1. Set one or more `NOTIFY_*` environment variables (e.g. `NOTIFY_DISCORD`, `NOTIFY_TELEGRAM`, `NOTIFY_PUSHOVER`)
 2. Create the flag file: `touch ~/.claude/notify-on`
 
+Telegram uses `NOTIFY_TELEGRAM=tgram://bot_token/chat_id`. Check setup without sending: `/usr/local/bin/notify.py test --dry-run --debug`.
+
 **To disable:** `rm ~/.claude/notify-on`
 
 ## Workspace
diff --git a/docker-compose.full.yaml b/docker-compose.full.yaml
@@ -48,7 +48,7 @@ services:
 
       # --- Notifications (uncomment services you want) ---
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -4,6 +4,13 @@ All notable changes to HolyClaude will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.3.3] - 06/15/2026
+
+### Fixed
+- Corrected Telegram notification examples to use Apprise's `tgram://bot_token/chat_id` scheme and kept legacy `tg://` values working at runtime.
+- Added a dry-run notification diagnostic so users can check `notify-on`, `NOTIFY_*` variables, and Apprise URL acceptance without sending a message.
+- Kept Docker release metadata from auto-adding `latest` to slim builds, so `latest` stays tied to the full image.
+
 ## [1.3.2] - 06/15/2026
 
 ### Changed
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -68,7 +68,7 @@ Claude Code hooks, raw CLI hooks for Codex and Gemini CLI, and CloudCLI Codex ch
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `NOTIFY_DISCORD` | *(unset)* | Discord webhook — `discord://webhook_id/webhook_token` |
-| `NOTIFY_TELEGRAM` | *(unset)* | Telegram bot — `tg://bot_token/chat_id` |
+| `NOTIFY_TELEGRAM` | *(unset)* | Telegram bot — `tgram://bot_token/chat_id` |
 | `NOTIFY_PUSHOVER` | *(unset)* | Pushover — `pover://user_key@app_token` |
 | `NOTIFY_SLACK` | *(unset)* | Slack webhook — `slack://token_a/token_b/token_c` |
 | `NOTIFY_EMAIL` | *(unset)* | Email (SMTP) — `mailto://user:pass@gmail.com?to=you@gmail.com` |
@@ -77,6 +77,13 @@ Claude Code hooks, raw CLI hooks for Codex and Gemini CLI, and CloudCLI Codex ch
 
 Notifications also require the flag file `~/.claude/notify-on` to exist inside the container. Create it with `touch ~/.claude/notify-on`.
 
+Telegram uses Apprise's `tgram://` scheme. Legacy Telegram values are normalized for compatibility, but new setups should use `tgram://`.
+
+Validate notification setup without sending a message:
+```bash
+docker compose exec holyclaude /usr/local/bin/notify.py test --dry-run --debug
+```
+
 **Migrating from Pushover (v1.0.0):** Replace `PUSHOVER_APP_TOKEN` and `PUSHOVER_USER_KEY` with a single variable: `NOTIFY_PUSHOVER=pover://user_key@app_token`
 
 ### AI Provider API Keys
diff --git a/docs/dockerhub-description.md b/docs/dockerhub-description.md
@@ -83,7 +83,7 @@ Credentials stored locally in your bind-mounted `./data/claude` directory. We do
 | `PGID` | Container user GID | `1000` |
 | `CHOKIDAR_USEPOLLING` | Enable polling for NAS/SMB mounts | unset |
 | `NOTIFY_DISCORD` | Discord webhook URL for notifications | unset |
-| `NOTIFY_TELEGRAM` | Telegram bot URL for notifications | unset |
+| `NOTIFY_TELEGRAM` | Telegram bot URL (`tgram://bot_token/chat_id`) | unset |
 | `NOTIFY_PUSHOVER` | Pushover URL for notifications | unset |
 | `NOTIFY_SLACK` | Slack webhook URL for notifications | unset |
 | `NOTIFY_URLS` | Catch-all Apprise notification URLs | unset |
diff --git a/docs/translations/README.de.md b/docs/translations/README.de.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ Geh von deinem Computer weg und erfahre, wenn Claude fertig ist. Verwendet [Appr
 1. Füge eine oder mehrere `NOTIFY_*`-Variablen zur compose `environment` hinzu:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. Im Container: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.es.md b/docs/translations/README.es.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -906,7 +906,7 @@ Alejate de tu computadora y enterate cuando Claude haya terminado. Usa [Apprise]
 1. Agrega una o mas variables `NOTIFY_*` al `environment` de tu compose:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. Dentro del contenedor: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.fr.md b/docs/translations/README.fr.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ Même avec tout ça, la surface de risque est énorme. Utilisez Tailscale ou Clo
 1. Ajoutez une ou plusieurs variables `NOTIFY_*` à l'`environment` de votre compose :
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. À l'intérieur du conteneur : `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.hi.md b/docs/translations/README.hi.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ Password एक speed bump है, दरवाज़ा नहीं। HolyCla
 1. अपने compose `environment` में एक या अधिक `NOTIFY_*` variables जोड़ें:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. Container के अंदर: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.it.md b/docs/translations/README.it.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ Allontanati dal computer e sappi quando Claude ha finito. Usa [Apprise](https://
 1. Aggiungi una o più variabili `NOTIFY_*` all'`environment` del tuo compose:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. All'interno del container: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.ja.md b/docs/translations/README.ja.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ HolyClaude は CloudCLI をポート `3001` にバインドする。デフォル
 1. compose の `environment` に `NOTIFY_*` 変数を一つ以上追加:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. コンテナ内で: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.ko.md b/docs/translations/README.ko.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ HolyClaude는 CloudCLI를 포트 `3001`에 바인딩합니다. 기본적으로 
 1. compose `environment`에 `NOTIFY_*` 변수를 하나 이상 추가하세요:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. 컨테이너 내부에서: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.pt.md b/docs/translations/README.pt.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ Saia do computador e saiba quando Claude terminar. Usa [Apprise](https://github.
 1. Adicione uma ou mais variáveis `NOTIFY_*` ao `environment` do seu compose:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. Dentro do container: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.ru.md b/docs/translations/README.ru.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ HolyClaude привязывает CloudCLI к порту `3001`. По умолч
 1. Добавьте одну или несколько переменных `NOTIFY_*` в раздел `environment` вашего compose:
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. Внутри контейнера: `touch ~/.claude/notify-on`
 
diff --git a/docs/translations/README.zh.md b/docs/translations/README.zh.md
@@ -397,7 +397,7 @@ services:
       # inside the container: touch ~/.claude/notify-on
       #
       # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+      # - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
       # - NOTIFY_PUSHOVER=pover://user_key@app_token
       # - NOTIFY_SLACK=slack://token_a/token_b/token_c
       # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
@@ -907,7 +907,7 @@ HolyClaude 将 CloudCLI 绑定到端口 `3001`。默认情况下这只是本地
 1. 在 compose 的 `environment` 中添加一个或多个 `NOTIFY_*` 变量：
    ```yaml
    - NOTIFY_DISCORD=discord://webhook_id/webhook_token
-   - NOTIFY_TELEGRAM=tg://bot_token/chat_id
+   - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
    ```
 2. 在容器内执行：`touch ~/.claude/notify-on`
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -55,9 +55,32 @@ Note: Polling uses more CPU than inotify. Only enable when needed.
 
 ---
 
-### Permission denied errors
-
-**Symptom:** Can't write files, `git` operations fail, npm install fails.
+### Telegram notifications do not arrive
+
+**Symptom:** `notify-on` exists and `NOTIFY_TELEGRAM` is set, but no Telegram message arrives.
+
+**Cause:** Telegram uses Apprise's `tgram://` URL scheme. Older HolyClaude docs showed a shorter Telegram scheme that Apprise rejects.
+
+**Fix:** Use the current Telegram format:
+```yaml
+environment:
+  - NOTIFY_TELEGRAM=tgram://bot_token/chat_id
+```
+
+Legacy Telegram values are normalized for compatibility, but `tgram://` is the supported format for new setups.
+
+Check the setup without sending a message:
+```bash
+docker compose exec holyclaude /usr/local/bin/notify.py test --dry-run --debug
+```
+
+If the dry run passes but Telegram still does not receive the real test, run the same command without `--dry-run`, then check the bot token, chat ID, and container network access.
+
+---
+
+### Permission denied errors
+
+**Symptom:** Can't write files, `git` operations fail, npm install fails.
 
 **Cause:** Usually one of these:
 
diff --git a/scripts/notify.py b/scripts/notify.py
diff --git a/tests/test_notify.py b/tests/test_notify.py
