feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

docs/TELEGRAM-NOTIFICATIONS.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Shared setup for Telegram notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`, both for completion and for pauses that need user attention.
+Shared setup for Telegram notifications used by reviewer-driven skills such as
+`create-plan`, `implement-plan`, and `do-task`, both for completion and for
+pauses that need user attention.
 
 ## Requirements
 
@@ -12,17 +14,23 @@ Shared setup for Telegram notifications used by reviewer-driven skills such as `
   - Codex: `~/.codex/skills/reviewer-runtime/notify-telegram.sh`
   - Claude Code: `~/.claude/skills/reviewer-runtime/notify-telegram.sh`
   - OpenCode: `~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh`
-  - Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh` or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
+  - Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh`
+    or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
+  - Pi: `.pi/skills/reviewer-runtime/pi/notify-telegram.sh`
+    or `~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh`
 
 ## Install
 
-The helper ships from `skills/reviewer-runtime/` together with `run-review.sh`.
+The helpers ship from `skills/reviewer-runtime/` (non-Pi) and
+`skills/reviewer-runtime/pi/` (Pi) together with `run-review.sh`.
 
 ### Codex
 
 ```bash
 mkdir -p ~/.codex/skills/reviewer-runtime
-cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/
+cp skills/reviewer-runtime/run-review.sh \
+   skills/reviewer-runtime/notify-telegram.sh \
+   ~/.codex/skills/reviewer-runtime/
 chmod +x ~/.codex/skills/reviewer-runtime/*.sh
 ```
 
@@ -30,7 +38,9 @@ chmod +x ~/.codex/skills/reviewer-runtime/*.sh
 
 ```bash
 mkdir -p ~/.claude/skills/reviewer-runtime
-cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/
+cp skills/reviewer-runtime/run-review.sh \
+   skills/reviewer-runtime/notify-telegram.sh \
+   ~/.claude/skills/reviewer-runtime/
 chmod +x ~/.claude/skills/reviewer-runtime/*.sh
 ```
 
@@ -38,7 +48,9 @@ chmod +x ~/.claude/skills/reviewer-runtime/*.sh
 
 ```bash
 mkdir -p ~/.config/opencode/skills/reviewer-runtime
-cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/
+cp skills/reviewer-runtime/run-review.sh \
+   skills/reviewer-runtime/notify-telegram.sh \
+   ~/.config/opencode/skills/reviewer-runtime/
 chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh
 ```
 
@@ -48,7 +60,9 @@ Repo-local install:
 
 ```bash
 mkdir -p .cursor/skills/reviewer-runtime
-cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/
+cp skills/reviewer-runtime/run-review.sh \
+   skills/reviewer-runtime/notify-telegram.sh \
+   .cursor/skills/reviewer-runtime/
 chmod +x .cursor/skills/reviewer-runtime/*.sh
 ```
 
@@ -56,22 +70,57 @@ Global install:
 
 ```bash
 mkdir -p ~/.cursor/skills/reviewer-runtime
-cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.cursor/skills/reviewer-runtime/
+cp skills/reviewer-runtime/run-review.sh \
+   skills/reviewer-runtime/notify-telegram.sh \
+   ~/.cursor/skills/reviewer-runtime/
 chmod +x ~/.cursor/skills/reviewer-runtime/*.sh
 ```
 
+### Pi
+
+Pi uses a separate set of helpers from `skills/reviewer-runtime/pi/` that are
+optimized for the Pi agent environment. See
+[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) for full details.
+
+Global install:
+
+```bash
+mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
+cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
+chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh
+```
+
+Repo-local install:
+
+```bash
+mkdir -p .pi/skills/reviewer-runtime/pi
+cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
+chmod +x .pi/skills/reviewer-runtime/pi/*.sh
+```
+
 ## Verify Installation
 
+### Verify: Non-Pi agents
+
 ```bash
 test -x ~/.codex/skills/reviewer-runtime/notify-telegram.sh || true
 test -x ~/.claude/skills/reviewer-runtime/notify-telegram.sh || true
 test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh || true
-test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
+test -x .cursor/skills/reviewer-runtime/notify-telegram.sh \
+  || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
+```
+
+### Verify: Pi
+
+```bash
+test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh \
+  || test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh || true
 ```
 
 ## Configure Telegram
 
-Export the required variables before running a skill that sends Telegram notifications:
+Export the required variables before running a skill that sends Telegram
+notifications:
 
 ```bash
 export TELEGRAM_BOT_TOKEN="<bot-token>"
@@ -86,7 +135,7 @@ export TELEGRAM_API_BASE_URL="https://api.telegram.org"
 
 ## Test the Helper
 
-Example:
+Non-Pi agents example:
 
 ```bash
 TELEGRAM_BOT_TOKEN="<bot-token>" \
@@ -94,9 +143,19 @@ TELEGRAM_CHAT_ID="<chat-id>" \
 skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"
 ```
 
+Pi example:
+
+```bash
+TELEGRAM_BOT_TOKEN="<bot-token>" \
+TELEGRAM_CHAT_ID="<chat-id>" \
+skills/reviewer-runtime/pi/notify-telegram.sh --message "Pi Telegram test"
+```
+
 ## Rules
 
 - Telegram is the only supported notification path for these skills.
 - Notification failures are non-blocking, but they must be surfaced to the user.
-- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
-- Skills should report when Telegram is not configured instead of silently pretending a notification was sent.
+- Before stopping for any user interaction, approval, or manual decision, send a
+  Telegram summary first if configured.
+- Skills should report when Telegram is not configured instead of silently
+  pretending a notification was sent.