feat: productize pi-knock for reliable remote notifications

.github/workflows/ci.yml

@@ -18,3 +18,5 @@ jobs:
           node-version: "22.19.0"
       - run: npm ci --ignore-scripts --no-audit --no-fund
       - run: npm run check
+      - name: Verify npm package contents
+        run: npm pack --dry-run

.github/workflows/release.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Check
         run: npm run check
 
+      - name: Verify npm package contents
+        run: npm pack --dry-run
+
       - name: Read package version
         id: version
         run: node -e "console.log('version=' + require('./package.json').version)" >> "$GITHUB_OUTPUT"

.gitignore

@@ -4,3 +4,4 @@ coverage/
 *.log
 .env
 pi-knock.local.json
+.test-dist/

CHANGELOG.md

@@ -6,6 +6,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+### Added
+
+- Automatic notification delivery retries for transient failures.
+- `/knock doctor` diagnostics with last-delivery status and attempt count.
+- Notification privacy mode to hide prompt text from lock-screen notifications, with `project-only` as the safe default.
+- Session names in notification titles when Pi sessions are named.
+- Provider, notifier, and lifecycle test coverage.
+- npm package-content verification in CI and release workflows.
+
+### Changed
+
+- Duplicate `agent_settled` events are ignored once a run has already settled.
+- Notification setup now includes a dedicated preferences screen.
+- Documentation files and the Chinese README are included in the npm package.
+
+
 ## [0.2.1] - 2026-10-03
 
 ### Changed

CONTRIBUTING.md

@@ -36,6 +36,10 @@ Behavior changes should include tests. In particular, lifecycle changes must pre
 
 Notification delivery failures must never break the agent run.
 
+Lifecycle changes should be covered in `test/lifecycle.test.ts`. Provider request changes belong in `test/channels.test.ts`, and retry behavior belongs in `test/notifier.test.ts`.
+
+Before releasing, `npm pack --dry-run` must show the README files and `docs/` content expected by links in the package documentation.
+
 ## Pull requests
 
 Keep changes focused. Update CHANGELOG.md for user-visible changes and avoid committing credentials, provider tokens, private webhook URLs, or local pi-knock configuration.

README.md

@@ -2,88 +2,68 @@
 
 English | [简体中文](./README.zh-CN.md)
 
-**Notifications for Pi when a task finishes, fails, or needs your input.**
+**Leave the terminal. Pi will knock when it needs you.**
 
-pi-knock is a lightweight Pi extension that sends notifications to **Pushover**, **ntfy**, or a **webhook**, so you do not need to keep watching the terminal while Pi works.
-
-## Features
-
-- ✅ Notify when a conversation finishes
-- ❓ Notify when Pi is waiting for input or confirmation
-- ❌ Notify when a task fails
-- ⏹️ Optional notification for aborted runs
-- 📱 Pushover, ntfy, and generic webhooks
-- ⌚ Apple Watch via iPhone notification mirroring
-- 🔗 Optional session URL for Pi-Web
-- 🔐 Separate config and credential storage
-
-## Install
-
-Recommended:
+pi-knock sends remote notifications when a Pi task **finishes, fails, or needs your input**. Use Pushover for iPhone / Apple Watch, ntfy for hosted or self-hosted push, or a webhook for your own automation.
 
 ```bash
 pi install npm:@asigers/pi-knock
 ```
 
-Or install directly from GitHub:
+## Why pi-knock
 
-```bash
-pi install git:github.com/Asigers/pi-knock
-```
-
-Then restart Pi or run:
-
-```text
-/reload
-```
-
-Requires **Pi 0.87+**.
+- **Actually waits for completion** — completion alerts are sent at `agent_settled`, after Pi has finished automatic retries and queued work.
+- **Works away from your desk** — notifications can reach your phone or watch instead of only the local terminal.
+- **Reliable delivery** — transient failures are retried automatically.
+- **Lock-screen safe by default** — prompt text is hidden unless you opt in.
+- **Session-aware** — named Pi sessions appear in notification titles.
+- **No push server required** — pi-knock sends directly to your configured provider.
 
 ## Quick start
 
-Run:
+After installation, restart Pi or run `/reload`, then:
 
 ```text
 /knock setup
 ```
 
-Choose a provider and enter the required settings. pi-knock sends a test notification after setup.
-
-Useful commands:
+Choose a provider and enter the required settings. pi-knock immediately sends a test notification.
 
 | Command | Description |
 | --- | --- |
-| `/knock setup` | Configure a notification provider |
+| `/knock setup` | Configure providers and notification preferences |
 | `/knock status` | Show current configuration |
-| `/knock test` | Send a test notification |
+| `/knock test` | Send a live test notification |
+| `/knock doctor` | Show provider and last-delivery diagnostics |
+
+Requires **Pi 0.87+**.
 
 ## Providers
 
 | Provider | Best for |
 | --- | --- |
 | **Pushover** | iPhone / Apple Watch |
-| **ntfy** | Simple self-hosted or hosted push |
-| **Webhook** | Custom integrations |
-
-For Apple Watch, install Pushover on your iPhone and enable notification mirroring in the Watch app.
+| **ntfy** | Hosted or self-hosted push |
+| **Webhook** | Custom integrations and automation |
 
-New to Pushover? See the [Pushover setup guide (简体中文)](./docs/pushover-setup.zh-CN.md) for account registration, app installation, User Key, and Application API Token setup.
+New to Pushover? See the [Pushover setup guide (简体中文)](./docs/pushover-setup.zh-CN.md).
 
 ## Notification behavior
 
-By default:
+Default behavior:
 
 | Event | Notify |
 | --- | --- |
 | Conversation completed | Yes |
 | Input / confirmation required | Yes |
 | Conversation failed | Yes |
 | Conversation aborted | No |
-| `/knock test` | Immediately |
 
-Completion notifications are sent after Pi reaches `agent_settled`, so retries, queued work, or other automatic continuation do not cause premature “finished” alerts.
+Notifications use the project name and, when available, the Pi session name. By default prompt text is **not** included on the lock screen.
 
-A completion notification contains the project name, the original prompt in compact form, and elapsed time.
+To change this, run `/knock setup` and choose **Notification preferences**.
+
+Delivery uses up to three attempts for transient network errors and retryable provider responses such as HTTP 429 / 5xx. Permanent 4xx errors fail immediately. Use `/knock doctor` to inspect the most recent delivery result.
 
 ## Configuration
 
@@ -101,60 +81,55 @@ Example:
 {
   "projectName": "",
   "openUrl": "",
+  "contentMode": "project-only",
   "notify": {
     "completed": true,
     "error": true,
     "aborted": false,
     "input": true
   },
-  "ntfy": {
-    "enabled": false,
-    "server": "https://ntfy.sh",
-    "topic": ""
-  },
   "pushover": {
     "enabled": true
-  },
-  "webhook": {
-    "enabled": false,
-    "url": ""
   }
 }
 ```
 
-See [`pi-knock.example.json`](./pi-knock.example.json) and [`config.schema.json`](./config.schema.json) for the full configuration.
+See [`pi-knock.example.json`](./pi-knock.example.json) and [`config.schema.json`](./config.schema.json) for the complete configuration.
 
-Environment variables are also supported, which is useful for Pi-Web, containers, CI, and secret managers.
+Environment variables are supported for Pi-Web, containers, CI, and external secret managers.
 
-> Credentials entered through Pi's standard input are visible while typing. Run `/knock setup` only in a private terminal or session.
+> Pi's standard input is not masked. Run `/knock setup` only in a private terminal or session when entering credentials.
 
-## Update / remove
+## Install from GitHub
+
+Latest `main`:
 
 ```bash
-pi update --extensions
+pi install git:github.com/Asigers/pi-knock
 ```
 
-Remove the npm package:
+Update installed extensions:
 
 ```bash
-pi remove npm:@asigers/pi-knock
+pi update --extensions
 ```
 
-Remove the Git package:
+Remove:
 
 ```bash
-pi remove git:github.com/Asigers/pi-knock
+pi remove npm:@asigers/pi-knock
 ```
 
 ## Development
 
 ```bash
 npm ci --ignore-scripts
 npm run check
+npm pack --dry-run
 pi -ne -e ./src/index.ts
 ```
 
-Using `-ne` prevents another installed copy of pi-knock from being loaded during local testing.
+Using `-ne` prevents another installed copy of pi-knock from loading during local testing.
 
 ## More