@iflow-ai/iflow-cli 0.2.12-beta.3 → 0.2.12-beta.5

package/README.md

@@ -168,6 +168,61 @@ Here is a settings demo file:
 }
 ```
 
+## 🐛 Crash Debugging
+
+If you encounter runtime crashes, you can enable crash diagnostics to collect detailed information for debugging:
+
+### Enable Crash Diagnostics
+
+```bash
+# Enable crash debugging mode
+DEBUG=true iflow
+
+# Or with additional Node.js debugging flags
+DEBUG=true node --trace-warnings --trace-uncaught node_modules/.bin/iflow
+```
+
+### System Configuration for Core Dumps
+
+**macOS:**
+```bash
+# Enable core dumps
+ulimit -c unlimited
+sudo sysctl -w kern.coredump=1
+```
+
+**Linux:**
+```bash
+# Configure core dump pattern and enable unlimited core dumps
+echo 'core.%p.%t' | sudo tee /proc/sys/kernel/core_pattern
+ulimit -c unlimited
+```
+
+### Crash Information Collection
+
+When `DEBUG=true` is enabled, the system will:
+
+1. **Generate crash files** - Create `crash-[timestamp]-[pid].json` files containing:
+   - Complete error stack trace
+   - Memory usage information
+   - Process information (PID, uptime, Node.js version)
+   - Environment variables
+   - Platform and architecture details
+
+2. **Create core dumps** - Generate system core dumps for advanced debugging
+
+3. **Monitor warnings** - Log Node.js warnings and unhandled promise rejections
+
+### Analyzing Crash Files
+
+The generated crash files contain structured JSON data that can help identify:
+- The exact error that caused the crash
+- Memory usage patterns before the crash
+- System environment and configuration
+- Call stack at the time of crash
+
+Share these files when reporting crash issues for faster debugging assistance.
+
 ## GitHub Actions
 
 You can also use iFlow CLI in your GitHub Actions workflows with the community-maintained action: [iflow-cli-action](https://github.com/vibe-ideas/iflow-cli-action)