Simplify documentation and add repository development skill

docs/WEBHOOKS.md

@@ -1,5 +1,14 @@
 # Message webhooks
 
+Use this guide to connect a message listener to your HTTP consumer. Start with direct HTTPS if you already have a webhook endpoint; the local receiver is optional. The listener observes messages surfaced in the Desktop app, rather than subscribing to WhatsApp's server history.
+
+## Choose a delivery mode
+
+| Mode | What runs locally | Use it for |
+| --- | --- | --- |
+| Direct HTTPS | Listener/relay in WhatsApp; optional brief scheduled Python checks | Your existing webhook service or Node-RED |
+| Loopback HTTP | Listener/relay plus a running Python receiver | Local testing and durable SQLite capture |
+
 ## Execution and restart behavior
 
 `webhook install` is a one-shot command. JavaScript subscribes to message collection events inside WhatsApp and queues decoded records. A resident native helper posts them directly to an HTTPS endpoint or to a loopback HTTP receiver. Direct HTTPS needs no local server and no continuously running Python process. No CDP or UI automation is used. WhatsApp's CSP blocks direct JavaScript HTTP requests to localhost, so delivery uses native WinHTTP without weakening CSP.
@@ -10,8 +19,17 @@ A WhatsApp process restart destroys injected code. For direct HTTPS, optional `-
 
 For direct HTTPS, supply a 32–128 character printable ASCII token through the named environment variable using your secret manager, then run:
 
+If you are setting it manually, this PowerShell prompt hides the input and avoids placing the token in the command text:
+
+```powershell
+$env:WHATSAPP_INJECTOR_WEBHOOK_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host 'Webhook token' -AsSecureString)).Password
+```
+
+Install the listener:
+
 ```powershell
 python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --token-env WHATSAPP_INJECTOR_WEBHOOK_TOKEN --self-only --auto-restore --config listener.json
+Remove-Item Env:\WHATSAPP_INJECTOR_WEBHOOK_TOKEN
 ```
 
 The endpoint must authenticate `X-Webhook-Token` and accept the batch schema below. Certificate validation is enabled; credentials in URLs, query strings, fragments and redirects are rejected. Remove `--self-only` only when you intend to forward events from other chats. `webhook auto-restore --config listener.json` registers/enables restoration separately; `webhook ensure --config listener.json` performs one check. `webhook watch --config listener.json` is an optional continuously running alternative.
@@ -60,6 +78,40 @@ The loopback endpoint is `POST /whatsapp-webhook` on `127.0.0.1`; direct HTTPS u
 
 HTTP 2xx means the batch was accepted. The built-in receiver commits before acknowledgement and deduplicates message IDs. Failed HTTP delivery leaves queued records available for retry. Consumer side effects such as AI jobs should also deduplicate IDs. There is no exactly-once guarantee.
 
+### Example batch
+
+This is synthetic data. Message IDs are opaque strings; use `event_id` for deduplication rather than parsing its format.
+
+```json
+{
+  "listener_id": "91b17841-2106-4e73-97db-c38be6e9b269",
+  "seqs": [1],
+  "events": [{
+    "seq": 1,
+    "event_id": "synthetic-message-1",
+    "type": "message",
+    "message": {
+      "id": "synthetic-message-1",
+      "chat_id": "synthetic-chat",
+      "timestamp": 1700000000,
+      "from_me": true,
+      "message_type": "chat",
+      "body": "Hello",
+      "caption": null,
+      "text_truncated": false,
+      "body_length": 5,
+      "caption_length": 0
+    }
+  }]
+}
+```
+
+`timestamp` is Unix seconds; sequence numbers identify queue entries within the current listener installation. Body/caption may be null. Text lengths count JavaScript UTF-16 code units. Batches contain up to 16 events and are additionally bounded by serialized size.
+
+Your endpoint should authenticate `X-Webhook-Token`, validate the batch, deduplicate IDs, persist or enqueue accepted work, and only then return HTTP 2xx. No response-body schema is required by the relay. Use a non-2xx status when a retry is needed. TLS certificates must validate, and redirects are not followed.
+
+For a summarizer, pass newly accepted message events to your own processing queue. This repository supplies delivery, not an AI provider, prompt, response policy or automatic message sender.
+
 ## Bounds and limitations
 
 - This listens to the app's loaded message collection, not a server-side subscription. Messages not surfaced there can be missed.