Merge pull request #229 from MervinPraison/claude/issue-227-20260422-1640

docs: document PRAISONAI_RUN_SYNC_TIMEOUT and shutdown() API (fixes #227)

Author: MervinPraison

docs/cli/env.mdx

@@ -33,6 +33,19 @@ praisonai env show
 praisonai env check
 ```
 
+## Related Environment Variables
+
+PraisonAI supports several environment variables for configuration and security:
+
+| Variable | Purpose |
+|----------|---------|
+| `PRAISONAI_ALLOW_LOCAL_TOOLS` | Enable local tools.py file loading |
+| `PRAISONAI_ALLOW_JOB_WORKFLOWS` | Enable job workflow execution |
+| `PRAISONAI_BROWSER_ALLOW_REMOTE` | Enable remote browser access |
+| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) |
+
+For complete details and security implications, see [Security Environment Variables](/docs/features/security-environment-variables).
+
 ## See Also
 
 - [Config](/docs/cli/config) - Configuration management

docs/features/gateway.mdx

@@ -337,6 +337,21 @@ session_config = SessionConfig(
 
 ---
 
+## Graceful Shutdown
+
+Long-running servers can stop the wrapper's background async loop explicitly:
+
+```python
+from praisonai._async_bridge import shutdown
+
+# On SIGTERM / server stop
+shutdown()
+```
+
+`shutdown()` is also registered via `atexit`, so it runs automatically on interpreter exit. Call it manually when you need deterministic cleanup (flushing telemetry exporters, closing async HTTP/DB clients) before the process exits.
+
+---
+
 ## CLI Commands
 
 ```bash

docs/features/security-environment-variables.mdx

@@ -104,6 +104,8 @@ unset PRAISONAI_ALLOW_LOCAL_TOOLS
 - Agent API calls
 - Real-time UI interactions
 
+As of recent PraisonAI versions, the `PRAISONAI_ALLOW_LOCAL_TOOLS` gate is enforced consistently across the CLI (`praisonai run`), YAML workflows, and Python (`AgentsGenerator`) entry points. Previously it was only enforced on one path.
+
 **Usage Example**:
 ```python
 from praisonaiagents import Agent
@@ -185,6 +187,22 @@ server = BrowserServer(host="0.0.0.0", port=8080)
 server.start()
 ```
 
+### PRAISONAI_RUN_SYNC_TIMEOUT
+
+Default maximum seconds the wrapper's sync-to-async bridge will wait for a coroutine to complete.
+
+**Default:** `300` (5 minutes)
+
+```bash
+# Tighten for latency-sensitive servers
+export PRAISONAI_RUN_SYNC_TIMEOUT=30
+
+# Loosen for long-running batch jobs
+export PRAISONAI_RUN_SYNC_TIMEOUT=3600
+```
+
+Applies to every `praisonai` CLI entry and wrapper-based server (gateway, a2u, mcp_server, scheduler). The SDK (`praisonaiagents`) uses a separate bridge — see [Async Bridge](/docs/features/async-bridge).
+
 ---
 
 ## Common Patterns
@@ -196,6 +214,7 @@ server.start()
 export PRAISONAI_ALLOW_LOCAL_TOOLS=true
 export PRAISONAI_ALLOW_JOB_WORKFLOWS=true  
 export PRAISONAI_BROWSER_ALLOW_REMOTE=true
+export PRAISONAI_RUN_SYNC_TIMEOUT=30
 
 # Add to ~/.bashrc or ~/.zshrc for persistence
 echo 'export PRAISONAI_ALLOW_LOCAL_TOOLS=true' >> ~/.bashrc
@@ -208,13 +227,15 @@ echo 'export PRAISONAI_ALLOW_LOCAL_TOOLS=true' >> ~/.bashrc
 unset PRAISONAI_ALLOW_LOCAL_TOOLS
 unset PRAISONAI_ALLOW_JOB_WORKFLOWS
 unset PRAISONAI_BROWSER_ALLOW_REMOTE
+export PRAISONAI_RUN_SYNC_TIMEOUT=300
 
 # Or use systemd service with secure environment
 # /etc/systemd/system/praisonai.service
 [Service]
 Environment="PRAISONAI_ALLOW_LOCAL_TOOLS=false"
 Environment="PRAISONAI_ALLOW_JOB_WORKFLOWS=false"
 Environment="PRAISONAI_BROWSER_ALLOW_REMOTE=false"
+Environment="PRAISONAI_RUN_SYNC_TIMEOUT=300"
 ```
 </Tab>
 
@@ -258,6 +279,7 @@ Check if you use any of these features:
 export PRAISONAI_ALLOW_LOCAL_TOOLS=true      # If you use tools.py
 export PRAISONAI_ALLOW_JOB_WORKFLOWS=true    # If you use job workflows
 export PRAISONAI_BROWSER_ALLOW_REMOTE=true   # If you bind browser to 0.0.0.0
+export PRAISONAI_RUN_SYNC_TIMEOUT=300        # Adjust timeout as needed
 ```
 </Step>