docs: add pos HOW-TO guide set (index + 8 category guides)

2026-08-06 02:54:36 -04:00
parent 025971ca1e
commit 8bef0f8c6d
13 changed files with 844 additions and 0 deletions
@@ -0,0 +1,106 @@
+# How-To: `pos communication`
+
+Telegram messaging and alerts. Tools: `telegram`, `matrix`.
+
+| Tool | What it does |
+|------|--------------|
+| `pos communication telegram` | Send messages/files, manage config, webhook state, message logs |
+| `pos communication matrix` | Matrix/Synapse sender (extensible; not yet implemented) |
+
+`telegram` is the workhorse: it backs the whole **notify system** — health
+digests, backup alerts, firewall changes — and can be used directly.
+
+---
+
+## `pos communication telegram`
+
+### One-time setup
+
+```bash
+pos communication telegram config set TELEGRAM_BOT_TOKEN=123456:ABC...
+pos communication telegram config set TELEGRAM_CHAT_ID=987654321
+pos communication telegram config set TELEGRAM_DISABLE_WEBHOOK=true   # if used with webhooks
+pos communication telegram config
+# config lives in ~/.config/linux_post_install/telegram.env (chmod 600)
+```
+
+The bot token comes from @BotFather, the chat ID from @userinfobot (or by
+starting a chat and reading it). To set your display name once: message
+`/start` to your bot, then `pos communication telegram chat-id` prints it.
+
+### Send
+
+```bash
+pos communication telegram send "hello from my server"      # plain text
+pos communication telegram send --markdown "**bold** ok"    # parse as markdown
+pos communication telegram send --help                     # list all flags
+pos communication telegram file /path/to/report.pdf         # send a document
+pos communication telegram broadcast "restarting in 5min"   # to all known chat IDs
+```
+
+### State & logs
+
+```bash
+pos communication telegram getwebhookinfo        # current webhook + pending count
+pos communication telegram setwebhook https://... # point a webhook URL (or "")
+pos communication telegram deletemenu            # clear the bot menu
+pos communication telegram logs                  # recent send history (logs dir)
+pos communication telegram clear-logs            # wipe message logs
+```
+
+**Recipes:**
+- **Alert when a backup finishes** — automatic: `pos system backup` calls
+  `notify_send` (below) on success *and* failure.
+- **Warn before a service update:**
+  ```bash
+  pos communication telegram send "Maintenance: docker compose down in 2min"
+  ```
+- **On-call file drop:** `pos communication telegram file ~/log/nginx-error.log`
+
+**Troubleshooting:**
+- "Not configured (no token or chat id)" → run `config set` for both values.
+- Send succeeds but nothing arrives → the chat must have started the bot
+  (press `Start` / send `/start` once).
+- **Markdown silently empty** → Telegram uses its own MarkdownV2; unmatched
+  syntax makes the message vanish. Use `--markdown` only when the text is
+  Telegram-safe (the health digest output is).
+- **Webhook vs getUpdates:** if your bot has an active webhook, `send` may
+  still work (we disable the webhook automatically when it owns it) — but if
+  another process registered the webhook, polls fail; `deletemenu`/webhook
+  state shows ownership. See `getwebhookinfo`.
+
+---
+
+## The notify system (`notify_send`)
+
+Every tool that announces something sends through `lib/notify.sh` instead of
+hard-coding Telegram:
+
+```bash
+# ~/.config/linux_post_install/notify.env
+NOTIFY_PLATFORM=telegram        # default; comma-separated to fan out to all
+```
+
+- `notify_send "msg"` → delivers to every platform in `NOTIFY_PLATFORM`
+  (current senders: `telegram`).
+- **Silent-fail:** no platform configured → one WARN line, exit 0, never
+  breaks the calling tool.
+- New platform (e.g. Matrix): implement `bin/pos-communication-<p> send
+  <value> [--markdown]`, then list it in `NOTIFY_PLATFORM`. Details:
+  [DOC/DEV.md → Alerting](../DEV.md).
+
+---
+
+## `pos communication matrix`
+
+Sender contract exists (`send <value> [--markdown]`) and the dispatcher routes
+to it, but no implementation ships yet. When present, add `matrix` to
+`NOTIFY_PLATFORM` and configure it via `pos communication matrix config set …`.
+
+---
+
+## Related
+
+- Reference + config file details: [DOC/POS.md → communication](../POS.md)
+- Alerting contract: [DOC/DEV.md → Alerting](../DEV.md)
+- Health digest (uses `--send --markdown`): [system.md](system.md)