feat(sag-notify): genericize for sharing, add language presets and sag install reference

- Remove personal/environment-specific info: no absolute home paths, no ~/.secret default, no real project names, no account-bound (professional) voice id
- Default config is now generic + English; key resolved from ELEVENLABS_API_KEY env (optional user key_file)
- Add multi-language presets (languages.<lang>); language setting selects preset, templates.* overrides win, en fallback. Ship en + vi
- Add references/sag-cli.md: install (brew steipete/tap/sag), auth, env vars, models, voices
- lib.sh sag_template() resolves template by precedence; sag_resolve_key no longer assumes ~/.secret
- Update skill, README, and setup/config/test commands to be generic and language-aware
- Add 'No Personal / Environment-Specific Information' rule to repo CLAUDE.md
- Bump plugin to 1.1.0

Co-Authored-By: duyetbot <duyetbot@users.noreply.github.com>

Author: duyet

CLAUDE.md

@@ -53,6 +53,30 @@ plugin-name/
 
 When changing plugin metadata, keep Claude and Codex manifests in sync and run `bash scripts/validate-plugins.sh`.
 
+## No Personal / Environment-Specific Information
+
+Plugins in this repo are **published and shared**. Never bake personal or
+machine-specific information into any plugin file (manifests, hooks, scripts,
+skills, commands, configs, docs, examples).
+
+**Never hardcode:**
+- Absolute home paths (`/Users/<you>/…`) — use `$HOME`, `~`, `${CLAUDE_PLUGIN_ROOT}`, or `$PWD`.
+- Personal secret-file conventions (e.g. `~/.secret`) — read secrets from documented env vars; allow an optional, user-set key-file path.
+- Real project, client, host, or repo names — use neutral placeholders (`demo-project`, `/path/to/project`).
+- Account-bound resources (private/professional voice IDs, API keys, tokens, account ids, emails).
+
+**Defaults must be generic.** Ship neutral, English-first defaults that work for
+any user. Put personal preferences (language, voice, key location, custom
+wording) in the user's own config under `~/.config/<plugin>/` — outside the repo,
+never committed.
+
+Author/owner metadata (`author`, marketplace `owner`) is allowed — that is
+legitimate attribution, not environment-specific leakage. Shipping additional
+**language presets** (e.g. a `vi` template set) is a feature, not personal info.
+
+Before committing a plugin, scan for leaks:
+`grep -rniE "/Users/|~/\.secret|<your-name>|<real-project-names>" <plugin>/`
+
 ## Commit Convention
 
 Use semantic commits with plugin scope:

sag-notify/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sag-notify",
-  "version": "1.0.0",
-  "description": "Spoken voice notifications via sag (ElevenLabs TTS). Speaks a short alert when Claude needs you, and a per-turn summary when work finishes — naming the project. Auto-injected hooks; configurable voice, language, and message templates.",
+  "version": "1.1.0",
+  "description": "Spoken voice notifications via sag (ElevenLabs TTS). Speaks a short alert when Claude needs you, and a per-turn summary when work finishes — naming the project. Auto-injected hooks; configurable voice, multi-language presets, and message templates.",
   "author": {
     "name": "duyet"
   }

sag-notify/README.md

@@ -1,36 +1,49 @@
 # sag-notify
 
-Spoken voice notifications for Claude Code via [`sag`](https://github.com/) (ElevenLabs TTS).
+Spoken voice notifications for Claude Code via [`sag`](https://github.com/steipete/sag) (ElevenLabs TTS).
 
 - **Needs you** → when Claude waits for permission/input, it speaks a short alert naming the project.
 - **Turn done** → when Claude finishes substantive work, it speaks a one-line summary you author.
 
 Both are driven by **auto-injected hooks** — once the plugin is enabled, every session gets them, no per-session setup.
 
+## Requirements
+
+The `sag` CLI must be installed and authenticated. Install with `brew install steipete/tap/sag` and set `ELEVENLABS_API_KEY`. Full guide: [skills/sag-voice/references/sag-cli.md](skills/sag-voice/references/sag-cli.md).
+
 ## How it works
 
 | Event | Hook | Behavior |
 |-------|------|----------|
-| `Notification` | `hooks/notify.sh` | Speaks `templates.notification` with the project name. The harness message is English, so it's replaced by your (Vietnamese by default) template. |
-| `Stop` | `hooks/summary.sh` | Reads the body Claude wrote to `summary_file`, speaks it via `templates.summary`, deletes the file. **Silent when no file exists**, so trivial turns are quiet. |
+| `Notification` | `hooks/notify.sh` | Speaks the notification template, naming the project, in the configured language. (The harness message is English, so it is replaced by the template.) |
+| `Stop` | `hooks/summary.sh` | Reads the body Claude wrote to `summary_file`, speaks it via the summary template, deletes the file. **Silent when no file exists**, so trivial turns are quiet. |
 
-To make Claude speak a summary, it writes a short body to `~/.claude/.sag-summary` during a substantive turn. The hook adds the `Đây là Claude, project <name>.` prefix.
+To make Claude speak a summary, it writes a short body to `~/.claude/.sag-summary` during a substantive turn. The hook adds the `This is <name>, reporting from project <name>:` framing automatically.
 
 ## Setup
 
-1. Enable the plugin (it ships `hooks/hooks.json`).
-2. Run `/sag-notify:setup` — checks `sag`/`jq`, resolves the API key, picks a voice, writes config, and tests audio.
-3. Or just rely on defaults: Brian voice, Vietnamese, key from `~/.secret`.
+1. Install + authenticate `sag` (see Requirements).
+2. Enable the plugin (it ships `hooks/hooks.json`).
+3. Run `/sag-notify:setup` — checks `sag`/`jq`, resolves the API key, picks a voice, writes config, and tests audio.
+4. Or just rely on defaults: Brian voice, English templates, key from the `ELEVENLABS_API_KEY` environment variable.
 
-`ELEVENLABS_API_KEY` must be resolvable — from the env or the configured `key_file` (default `~/.secret`).
+`ELEVENLABS_API_KEY` must be resolvable — from the environment, or from an optional key file you point `key_file` at in your user config.
 
 ## Configuration
 
-User config at `~/.config/sag-notify/config.json` overrides [`config.default.json`](config.default.json). See the **sag-voice** skill or run `/sag-notify:config`. Key settings: `enabled`, `events.{notification,summary}`, `voice_id`, `model_id`, `self_name`, `language`, `key_file`, `summary_file`, `error_log`, `max_chars`, `templates.{notification,summary}`.
+User config at `~/.config/sag-notify/config.json` overrides [`config.default.json`](config.default.json). See the **sag-voice** skill or run `/sag-notify:config`. Key settings: `enabled`, `events.{notification,summary}`, `voice_id`, `model_id`, `self_name`, `language`, `key_file`, `summary_file`, `error_log`, `max_chars`, `templates.{notification,summary}`, `languages.<lang>.{notification,summary}`.
+
+### Languages
+
+Set `language` to pick a built-in preset. `en` and `vi` ship by default; add more under `languages.<lang>` (placeholders `{name}`, `{project}`, `{body}`). Resolution: explicit `templates.<kind>` override → `languages.<language>.<kind>` → `languages.en.<kind>`.
+
+```bash
+jq '.language = "vi"' ~/.config/sag-notify/config.json > /tmp/c && mv /tmp/c ~/.config/sag-notify/config.json
+```
 
 ### Voice tiers (important)
 
-`premade` voices work on the **free** ElevenLabs tier. `professional`/library voices (e.g. the native Vietnamese "Minh Trung" `FTYCiQT21H9XQvhRu0ch`) return **402 Payment Required** unless you upgrade. Default is **Brian** (`nPczCjzI2devNBz1zQrb`, premade) speaking Vietnamese via the multilingual `eleven_flash_v2_5` model.
+`premade` voices work on the **free** ElevenLabs tier. `professional`/library voices return **402 Payment Required** unless you upgrade your plan. The default is **Brian** (`nPczCjzI2devNBz1zQrb`, premade); `eleven_flash_v2_5` is multilingual so a premade voice can speak any language (with an accent). Run `sag voices` to list what your key can use.
 
 ## Commands
 

sag-notify/commands/config.md

@@ -15,16 +15,18 @@ jq '<filter>' ~/.config/sag-notify/config.json > /tmp/sag-cfg.json && mv /tmp/sa
 ```
 
 Common changes:
+- **Language**: `.language = "vi"` (built-in: `en`, `vi`). Add a new one: `.languages.fr = {"notification":"…{name}…{project}…","summary":"…{name}…{project}…{body}…"}`.
 - **Voice**: `.voice_id = "<ID>"` (run `sag voices`; premade = free, professional = paid/402).
+- **Custom wording** (overrides the language preset): `.templates.notification = "…"` / `.templates.summary = "…"`. Set to `""` to fall back to the language preset.
 - **Disable a sound**: `.events.notification = false` or `.events.summary = false`.
 - **Turn everything off**: `.enabled = false`.
-- **Language → English**: set both templates, e.g. `.templates.notification = "This is {name}, project {project} needs your input."` and `.templates.summary = "This is {name} on project {project}. {body}"`.
 - **Name**: `.self_name = "..."`.
 - **Length cap**: `.max_chars = 200`.
+- **Key file**: `.key_file = "~/path/to/keyfile"` (sourced if `ELEVENLABS_API_KEY` is unset).
 
 After changing the voice or templates, verify in the FOREGROUND (hooks background the call):
 ```
-! source ~/.secret 2>/dev/null; sag speak --model-id "$(jq -r .model_id ~/.config/sag-notify/config.json)" --voice-id "$(jq -r .voice_id ~/.config/sag-notify/config.json)" "$(jq -r .templates.summary ~/.config/sag-notify/config.json | sed 's/{name}/Claude/;s/{project}/test/;s/{body}/kiểm tra/')" 2>&1 | grep -iE "failed|402" || echo OK
+! V=$(jq -r .voice_id ~/.config/sag-notify/config.json); M=$(jq -r .model_id ~/.config/sag-notify/config.json); sag speak --model-id "$M" --voice-id "$V" "test" 2>&1 | grep -iE "failed|402" || echo OK
 ```
 
 Always validate the result: `jq . ~/.config/sag-notify/config.json`.

sag-notify/commands/setup.md

@@ -6,23 +6,24 @@ One-time setup for spoken voice notifications via `sag` (ElevenLabs TTS).
 
 Walk the user through setup, doing the work for them where possible:
 
-1. **Check `sag` and `jq`** are installed: `command -v sag jq`. If `sag` is missing, tell the user to install it (it's the ElevenLabs TTS CLI) and stop.
+1. **Check `sag` and `jq`** are installed: `command -v sag jq`. If `sag` is missing, point them at the install guide [skills/sag-voice/references/sag-cli.md](../skills/sag-voice/references/sag-cli.md) (`brew install steipete/tap/sag`) and stop.
 
-2. **Resolve the API key.** Check `ELEVENLABS_API_KEY` in the env and in the key file (`~/.secret` by default). If absent, instruct the user to add it themselves (do NOT ask them to paste the secret in chat):
+2. **Resolve the API key.** Check `ELEVENLABS_API_KEY` in the environment. If absent, instruct the user to add it themselves (do NOT ask them to paste the secret in chat). Recommend their shell env file so non-interactive hook shells inherit it:
    ```
-   ! echo "export ELEVENLABS_API_KEY='your-key'" >> ~/.secret
+   ! echo "export ELEVENLABS_API_KEY='your-key'" >> ~/.zshenv
    ```
+   Or, if they keep secrets in a separate file, set `key_file` in their user config to that path.
 
-3. **Pick a voice.** Run `sag voices` and show the `premade` voices (free tier). Use AskUserQuestion to let them choose, or default to Brian (`nPczCjzI2devNBz1zQrb`). Warn that `professional`/library voices need a paid plan (402 error).
+3. **Choose a language.** Ask which built-in preset (`en`, `vi`, or another they want added). Set `language` in the user config; add a `languages.<lang>` entry if it's a new one.
 
-4. **Choose language + templates.** Default is Vietnamese (`Đây là {name}, project {project} …`). Offer English as an alternative.
+4. **Pick a voice.** Run `sag voices` and show the `premade` voices (free tier). Use AskUserQuestion to let them choose, or default to Brian (`nPczCjzI2devNBz1zQrb`). Warn that `professional`/library voices need a paid plan (402 error).
 
 5. **Write user config** to `~/.config/sag-notify/config.json` (create the dir). Start from the plugin's `config.default.json` and apply their choices with `jq`.
 
 6. **Verify audio in the FOREGROUND** (the hooks background the call, so exit codes lie):
    ```
-   ! source ~/.secret 2>/dev/null; sag speak --model-id eleven_flash_v2_5 --voice-id <ID> "Đây là Claude. Thiết lập hoàn tất." 2>&1 | grep -iE "failed|402|payment" || echo OK
+   ! sag speak --model-id eleven_flash_v2_5 --voice-id <ID> "<a short test line in their language>" 2>&1 | grep -iE "failed|402|payment" || echo OK
    ```
-   Empty/`OK` = success. A 402 means the voice needs a paid plan — go back to step 3.
+   Empty/`OK` = success. A 402 means the voice needs a paid plan — go back to step 4.
 
 7. Confirm the hooks are active and explain that summaries only speak when Claude writes a body to the configured `summary_file`.

sag-notify/commands/test.md

@@ -11,14 +11,14 @@ Run both hook paths the same way Claude Code would, then check the error log.
    ! CFG=~/.config/sag-notify/config.json; [ -f "$CFG" ] || CFG="${CLAUDE_PLUGIN_ROOT}/config.default.json"; jq . "$CFG"
    ```
 
-2. **Notification path** — fire the hook with a fake cwd so it names a project:
+2. **Notification path** — fire the hook with a sample cwd so it names a project:
    ```
-   ! echo '{"cwd":"/Users/duet/project/anyrouter"}' | "${CLAUDE_PLUGIN_ROOT}/hooks/notify.sh"; echo exit=$?
+   ! echo '{"cwd":"/path/to/demo-project"}' | "${CLAUDE_PLUGIN_ROOT}/hooks/notify.sh"; echo exit=$?
    ```
 
-3. **Summary path** — prime a body, then fire the Stop hook:
+3. **Summary path** — prime a body, then fire the Stop hook (use the configured language for the body):
    ```
-   ! printf 'đây là một bài kiểm tra âm thanh.' > ~/.claude/.sag-summary; echo '{"cwd":"/Users/duet/project/clickhouse-monitor"}' | "${CLAUDE_PLUGIN_ROOT}/hooks/summary.sh"; echo exit=$?
+   ! printf 'this is an audio test.' > ~/.claude/.sag-summary; echo '{"cwd":"/path/to/demo-project"}' | "${CLAUDE_PLUGIN_ROOT}/hooks/summary.sh"; echo exit=$?
    ```
 
 4. **Check for silent failures** (the hooks background the call, so a clean exit ≠ sound):

sag-notify/config.default.json

@@ -7,13 +7,23 @@
   "voice_id": "nPczCjzI2devNBz1zQrb",
   "model_id": "eleven_flash_v2_5",
   "self_name": "Claude",
-  "language": "vi",
-  "key_file": "~/.secret",
+  "language": "en",
+  "key_file": "",
   "summary_file": "~/.claude/.sag-summary",
   "error_log": "~/.claude/.sag-error.log",
   "max_chars": 280,
   "templates": {
-    "notification": "Đây là {name}. Mình đang làm ở project {project}, cần bạn xem qua một chút.",
-    "summary": "Đây là {name}, báo cáo từ project {project}: {body}"
+    "notification": "",
+    "summary": ""
+  },
+  "languages": {
+    "en": {
+      "notification": "This is {name}. I'm working on project {project} and could use your input.",
+      "summary": "This is {name}, reporting from project {project}: {body}"
+    },
+    "vi": {
+      "notification": "Đây là {name}. Mình đang làm ở project {project}, cần bạn xem qua một chút.",
+      "summary": "Đây là {name}, báo cáo từ project {project}: {body}"
+    }
   }
 }

sag-notify/hooks/lib.sh

@@ -27,11 +27,12 @@ cfg() {
   printf '%s' "${2:-}"
 }
 
-# Ensure ELEVENLABS_API_KEY is available, sourcing the configured key file if needed.
+# Ensure ELEVENLABS_API_KEY is available. Prefer the environment; optionally source
+# a user-configured key file (config `key_file`). No key file is assumed by default.
 sag_resolve_key() {
   [ -n "${ELEVENLABS_API_KEY:-}" ] && return 0
-  local kf; kf=$(sag_expand "$(cfg '.key_file' "$HOME/.secret")")
-  [ -f "$kf" ] && . "$kf" 2>/dev/null || true
+  local kf; kf=$(sag_expand "$(cfg '.key_file' '')")
+  [ -n "$kf" ] && [ -f "$kf" ] && . "$kf" 2>/dev/null || true
   [ -n "${ELEVENLABS_API_KEY:-}" ]
 }
 
@@ -40,6 +41,20 @@ sag_project() {
   local p; p=$(basename "$1"); printf '%s' "${p//[-_]/ }"
 }
 
+# sag_template <notification|summary> — resolve the message template.
+# Precedence: explicit `templates.<kind>` override → `languages.<language>.<kind>`
+# preset → `languages.en.<kind>` fallback. Lets users pick a language (vi, en, …)
+# via the `language` setting, or fully override with their own `templates`.
+sag_template() {
+  local kind="$1" lang t
+  t=$(cfg ".templates.$kind" '')
+  [ -n "$t" ] && { printf '%s' "$t"; return; }
+  lang=$(cfg '.language' 'en')
+  t=$(cfg ".languages.${lang}.${kind}" '')
+  [ -n "$t" ] && { printf '%s' "$t"; return; }
+  cfg ".languages.en.${kind}" ''
+}
+
 # sag_speak <text> — fire-and-forget TTS; errors go to the configured log, never /dev/null.
 sag_speak() {
   local voice model log

sag-notify/hooks/notify.sh

@@ -19,7 +19,7 @@ cwd=$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)
 
 name=$(cfg '.self_name' 'Claude')
 project=$(sag_project "$cwd")
-tmpl=$(cfg '.templates.notification' 'Đây là {name}, project {project} cần bạn xem qua.')
+tmpl=$(sag_template notification)
 
 sag_speak "$(sag_render "$tmpl" "$name" "$project")"
 exit 0

sag-notify/hooks/summary.sh

@@ -28,7 +28,7 @@ maxlen=$(cfg '.max_chars' '280')
 body=${body:0:$maxlen}
 name=$(cfg '.self_name' 'Claude')
 project=$(sag_project "$cwd")
-tmpl=$(cfg '.templates.summary' 'Đây là {name}, project {project}. {body}')
+tmpl=$(sag_template summary)
 
 sag_speak "$(sag_render "$tmpl" "$name" "$project" "$body")"
 exit 0