docs: Owner-DM inline-button pairing approval for Telegram/Discord/Slack bots

docs.json

@@ -288,6 +288,7 @@
                       "docs/features/bot-commands",
                       "docs/features/bot-gateway",
                       "docs/features/bot-routing",
+                      "docs/features/bot-unknown-user-pairing",
                       "docs/features/botos",
                       "docs/features/push-notifications"
                     ]

docs/best-practices/bot-security.mdx

@@ -212,56 +212,67 @@ channels:
 WhatsApp has the **strongest security defaults** and serves as the reference implementation for other channels.
 </Tip>
 
-## Gateway Pairing
+## Owner-DM Pairing
 
-<Warning>
-**Note:** The pairing system described below represents planned functionality. Current SDK implementation may differ. Verify against actual SDK documentation.
-</Warning>
+The pairing system is now shipped and enables owner-approval for unknown users with inline Approve/Deny buttons sent directly to your DM.
 
-For production deployments, use **gateway pairing** to authorize channels dynamically:
+For production deployments, use **owner-DM pairing** to authorize unknown users dynamically:
 
-### 1. Set Gateway Secret
+### 1. Set Callback Secret
 
 ```bash
-export PRAISONAI_GATEWAY_SECRET="your-secure-secret-key"
+export PRAISONAI_CALLBACK_SECRET="$(openssl rand -hex 32)"
 ```
 
 <Warning>
-Without `PRAISONAI_GATEWAY_SECRET`, pairing codes will **not persist across restarts**. Set this in production.
+Without `PRAISONAI_CALLBACK_SECRET`, inline-button callbacks will **not work across restarts**. Set this in production.
 </Warning>
 
-### 2. Generate Pairing Code
+### 2. Configure Unknown User Policy
 
 ```python
-# Note: This API is conceptual - verify implementation
-from praisonaiagents.gateway.pairing import PairingStore
+from praisonaiagents import Agent
+from praisonaiagents.bots import BotConfig
 
-store = PairingStore()
-code = store.generate_code(channel_type="telegram")
-print(f"Pairing code: {code}")  # 8-character hex code
+config = BotConfig(
+    token="your-bot-token",
+    unknown_user_policy="pair",     # Enable owner-approval workflow
+    owner_user_id="123456789",      # Your platform user ID
+)
+
+agent = Agent(
+    name="Support Bot",
+    instructions="Help users with their questions",
+)
 ```
 
-### 3. Verify in Channel
+### 3. Owner Approval Workflow
+
+When an unknown user messages your bot:
 
-Send the code to your bot in the target channel:
+1. Bot generates a pairing code
+2. **Owner receives DM with inline Approve/Deny buttons**
+3. Owner clicks Approve → User is permanently approved
+4. Owner clicks Deny → Request is rejected
 
+**CLI Fallback:** If `owner_user_id` is not set, the bot replies:
 ```
-/pair abc12345
+Your pairing code: abc12345. Ask the owner to run: praisonai pairing approve telegram abc12345
 ```
 
-The bot will verify the HMAC signature and authorize the channel.
+### 4. Manual Approval (CLI)
 
-### 4. Check Status
+Owners can approve pairing requests manually:
 
-```python
-# Check if channel is paired  
-# Note: Verify this API exists in current SDK
-paired = store.is_paired("@username", "telegram")
-print(f"Channel paired: {paired}")
-
-# List all paired channels  
-for channel in store.list_paired():
-    print(f"{channel.channel_type}: {channel.channel_id}")
+```bash
+# Approve a specific pairing code
+praisonai pairing approve telegram abc12345
+
+# Approve for Discord
+praisonai pairing approve discord def67890
+
+# Approve for Slack
+praisonai pairing approve slack ghi13579
 ```
 
 ## Doctor Security Check
@@ -311,8 +322,10 @@ Remediation: Consider allowlists for DM security and 'mention_only' group policy
 
   <Accordion title="✅ Gateway Pairing Active" icon="link">
     - [ ] `PRAISONAI_GATEWAY_SECRET` set
-    - [ ] Pairing codes generated and shared securely
-    - [ ] All production channels paired and verified
+    - [ ] `PRAISONAI_CALLBACK_SECRET` set (for inline buttons)
+    - [ ] `unknown_user_policy` configured (`deny`/`pair`/`allow`)
+    - [ ] `owner_user_id` set for inline approvals
+    - [ ] Pairing workflow tested and verified
     - [ ] Revocation process documented
   </Accordion>