fix: wire notifications into gateway + README polish

Wire the NotificationDispatcher all the way through at startup so
configured channels actually fire at runtime. Previously the dispatcher
existed but nothing instantiated it.

Changes:

- gateway/server.py
  * Instantiate `self.notifier = NotificationDispatcher(config)` during
    GatewayServer.__init__, log enabled channels or the
    setup_communications hint when none are configured.
  * Attach the EventBroadcaster to WebChatChannel via set_broadcaster()
    so web-chat notifications flow into /api/v1/events/stream.

- README.md
  * Remove dead links to ROADMAP.md, RUNBOOK.md, and blockchain/docs/
    components.md (all deleted earlier).
  * Replace the stale "50+ services" blurb with an accurate "221
    capabilities across 21 categories" section that documents the
    capability catalog and shows the /api/v1/capabilities endpoints.
  * Add setup_communications.py guidance + health-check curl to Quick
    Start.

- .env.example
  * Expand notifications section with every supported env var:
    Telegram, Discord, Slack, SMTP, Twilio SMS/WhatsApp, APNs, generic
    webhook.

Author: Neo

.env.example

@@ -19,15 +19,41 @@
 # BASE_RPC_URL=https://sepolia.base.org
 
 # ── Notifications ──
+# Set any subset. Run `python setup_communications.py` for guided setup.
+# Telegram
 # TELEGRAM_BOT_TOKEN=
-# OWNER_TELEGRAM_ID=          # Your Telegram user ID — used by the bridge approval gate
+# OWNER_TELEGRAM_ID=           # Your Telegram chat ID
+# Discord
+# DISCORD_WEBHOOK_URL=
+# Slack
+# SLACK_WEBHOOK_URL=
+# Email (SMTP)
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=
+# SMTP_FROM=
+# SMTP_TO=
+# SMS / WhatsApp (Twilio)
+# TWILIO_ACCOUNT_SID=
+# TWILIO_AUTH_TOKEN=
+# TWILIO_FROM_NUMBER=
+# TWILIO_TO_NUMBER=
+# TWILIO_WHATSAPP_FROM=        # e.g. +14155238886 (Twilio sandbox)
+# TWILIO_WHATSAPP_TO=
+# iOS push (APNs) — for the MTRX iOS app
+# APNS_KEY_ID=
+# APNS_TEAM_ID=
+# APNS_BUNDLE_ID=com.opnmatrx.mtrx
+# Generic webhook
+# NOTIFY_WEBHOOK_URL=
+# NOTIFY_WEBHOOK_BEARER=
 
 # ── Social media ──
 # TWITTER_API_KEY=
 # TWITTER_API_SECRET=
 # TWITTER_ACCESS_TOKEN=
 # TWITTER_ACCESS_SECRET=
-# DISCORD_WEBHOOK_URL=
 # DISCORD_ANNOUNCEMENTS_WEBHOOK=
 
 # ── Protocol Integrations ────────────────────────────────────

README.md

@@ -83,10 +83,20 @@ The interactive setup walks you through everything — model provider, blockchai
 After setup:
 
 ```bash
-python -m gateway.server
+python -m gateway.server                  # starts on port 18790 (or $PORT)
+curl http://localhost:18790/health        # {"status": "ok", ...}
 ```
 
-Or use the install script:
+Need to add a notification channel later (Telegram, Discord, Slack, SMS,
+Email, WhatsApp, iOS push, webhook)?
+
+```bash
+python setup_communications.py            # interactive menu
+python setup_communications.py telegram   # jump to one channel
+python setup_communications.py --list     # show enabled channels
+```
+
+Or use the one-liner install script:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/ItsDardanRexhepi/0pnMatrx/main/install.sh | bash
@@ -132,8 +142,9 @@ What works today, no chain required:
 
 What activates the moment a chain is configured: actual contract
 deployment, on-chain attestations, paymaster gas sponsorship, and the
-NeoSafe ETH transfer. See `ROADMAP.md` → "Blockchain Activation" for the
-checklist.
+NeoSafe ETH transfer. Populate `blockchain.*` in `openmatrix.config.json`
+and run `python -m contracts.deploy` to flip any "not_deployed" response
+into live on-chain behavior.
 
 ---
 
@@ -149,15 +160,32 @@ Every decision made by every agent on 0pnMatrx passes through the Unified Rexhep
 
 ---
 
-## Blockchain Infrastructure
+## Web3 Capability Surface
+
+**221 capabilities across 21 categories** — smart contracts, DeFi,
+DeFi advanced (perps, options, synthetics, orderbook), NFTs, NFT
+finance (lending, fractionalization, ERC-6551), identity (DID, KYC),
+governance (DAOs, veTokens, quadratic voting, RetroPGF), social
+(Lens, Farcaster, Push, creator coins), creator platforms (Sound.xyz,
+Mirror, Paragraph), payments (streaming, escrow, channels), cross-chain
+(CCIP, Hyperlane, Wormhole, Stargate, Axelar), staking & restaking
+(EigenLayer, Symbiotic, Karak, Lido, Rocket Pool), privacy & ZK,
+oracles (Chainlink, Pyth, RedStone, API3, Keepers), storage (IPFS,
+Arweave, Filecoin, Ceramic, OrbitDB), compute & DePIN (Akash, Gensyn,
+Render), real-world assets, markets (prediction, auction), gaming,
+and security (MPC, social recovery, session keys).
+
+Every capability is catalogued in `runtime/capabilities/catalog.py`.
+Browse them at runtime:
+
+```bash
+curl http://localhost:18790/api/v1/capabilities            # list all
+curl http://localhost:18790/api/v1/capabilities/categories # 21 buckets
+```
 
-50+ blockchain services run natively on Base (Ethereum L2) and
-return a well-formed `{"status": "not_deployed", ...}` envelope
-whenever a chain is not configured, so every flow is safe to exercise
-offline. All transaction fees are covered by the platform paymaster
-once deployed — users never pay gas. See
-`blockchain/docs/components.md` and `ROADMAP.md` for the activation
-checklist.
+All transactions are sponsored by the platform paymaster — users never
+pay gas. Capabilities return `{"status": "not_deployed", ...}` until
+contracts are deployed, keeping every flow safe to exercise offline.
 
 ---
 
@@ -295,8 +323,7 @@ kubectl apply -f k8s/
 ./scripts/build-contracts.sh
 ```
 
-See `docs/RUNBOOK.md` for the full on-call playbook and
-`docs/api-reference.md` for the complete HTTP / WebSocket surface.
+See `docs/api-reference.md` for the complete HTTP / WebSocket surface.
 
 ---
 

gateway/server.py

@@ -284,6 +284,28 @@ def __init__(self, config: dict):
         self.badge_manager = None
         self.certification_manager = None
 
+        # ── Notifications (unified 9-channel dispatcher) ────────────
+        # Available channels: telegram, discord, slack, email, sms,
+        # whatsapp, web_chat, ios_push, webhook. Configure with
+        # `python setup_communications.py`. Every channel is optional;
+        # the dispatcher is always instantiated so callers can rely on
+        # it without guarding imports.
+        try:
+            from runtime.notifications import NotificationDispatcher
+            self.notifier = NotificationDispatcher(config)
+            enabled = self.notifier.list_enabled_channels()
+            if enabled:
+                logger.info("Notifications ready: %s", ", ".join(enabled))
+            else:
+                logger.info(
+                    "Notifications: no channels configured. "
+                    "Run `python setup_communications.py` to add Telegram, "
+                    "Discord, Slack, SMS, Email, WhatsApp, iOS push, or webhooks."
+                )
+        except Exception as exc:
+            logger.warning("NotificationDispatcher init failed: %s", exc)
+            self.notifier = None
+
         # Rate limiting — three buckets:
         #   - ``rate_limiter_auth``   : API-key bearer auth (operator tokens)
         #   - ``rate_limiter_wallet`` : per-SIWE-address, keyed by wallet
@@ -1492,6 +1514,13 @@ def create_app(self) -> web.Application:
             # service dispatchers, metrics) can push live events into
             # /api/v1/events/stream.
             self.event_broadcaster = service_routes.broadcaster
+            # Connect the WebChatChannel so /api/v1/events/stream
+            # receives notifications broadcast by the NotificationDispatcher.
+            try:
+                from runtime.notifications.web_chat import WebChatChannel
+                WebChatChannel.set_broadcaster(self.event_broadcaster)
+            except Exception as _exc:
+                logger.debug("Web chat broadcaster not wired: %s", _exc)
             logger.info("Service routes registered successfully.")
         except Exception as e:
             logger.warning("Service routes registration skipped: %s", e)