fix: Suppress script output in JSON mode for clean parsing

Resolves Issue #28 (Issue 1) by making --json output parseable with jq
and other JSON tools.

Problem:
- Script stdout/stderr mixed with JSON output
- Broke jq parsing: `./bin/xdebug-profile --json -- php script.php | jq`
- Prevented piping to other JSON processing tools
- Common error: "parse error: Invalid numeric literal"

Solution:
- In JSON mode, redirect script output to /dev/null
- Keep exit code for error detection
- Use passthru() for human mode (show script output)
- Use exec() for JSON mode (suppress script output)

Benefits:
- ✅ Clean JSON output for jq: `... | jq '.["🎯 bottleneck_functions"]'`
- ✅ MCP-compatible: pure JSON response
- ✅ Tool-friendly: easy to integrate with other tools
- ✅ Backward compatible: human mode unchanged

Changes:
- bin/xdebug-profile: Conditional output suppression in JSON mode
- docs/TROUBLESHOOTING.md: Added JSON parsing issue and solution
- Updated --help text with clear behavior explanation
- Added jq usage example to help text

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: koriym

bin/xdebug-profile

@@ -28,7 +28,7 @@ function showHelp(string $scriptName): void
     echo "  ✅ Comprehensive metrics: CPU time, memory, function calls, I/O operations\n";
     echo "\n";
     echo "CORE OPTIONS:\n";
-    echo "  --json                      AI-optimized JSON output with comprehensive metrics\n";
+    echo "  --json                      AI-optimized JSON output (suppresses script output for clean parsing)\n";
     echo "  --claude                    Auto-analyze profile data with Claude AI\n";
     echo "  --context=TEXT             Add contextual description for AI analysis\n";
     echo "  --include-vendor=PATTERNS  Include vendor packages in performance analysis\n";
@@ -51,6 +51,9 @@ function showHelp(string $scriptName): void
     echo "  # 5. Test suite performance optimization\n";
     echo "  $scriptName --context=\"PHPUnit test suite performance\" -- php vendor/bin/phpunit\n";
     echo "\n";
+    echo "  # 6. JSON output for tooling (clean parsing with jq)\n";
+    echo "  $scriptName --json -- php script.php | jq '.\"🎯 bottleneck_functions\"'\n";
+    echo "\n";
     echo "PERFORMANCE ANALYSIS CAPABILITIES:\n";
     echo "  🚀 Function Timing: Identify slowest functions with microsecond precision\n";
     echo "  💾 Memory Analysis: Track memory usage patterns and identify leaks\n";
@@ -60,7 +63,8 @@ function showHelp(string $scriptName): void
     echo "\n";
     echo "OUTPUT FORMATS:\n";
     echo "  Default: Human-readable with proper time/memory units and KCachegrind suggestions\n";
-    echo "  --json: AI-optimized JSON with emoji keys and comprehensive performance metrics\n";
+    echo "  --json: Pure JSON output (script stdout/stderr suppressed for clean parsing with jq)\n";
+    echo "          AI-optimized with emoji keys and comprehensive performance metrics\n";
     echo "  Schema: https://koriym.github.io/xdebug-mcp/schemas/xdebug-profile.json\n";
     echo "  Benefits: AI can rank bottlenecks, suggest optimizations, compare before/after\n";
     echo "\n";
@@ -158,9 +162,16 @@ if ($xdebugFlag !== '') {
 $allArgs = array_merge($xdebugOptions, [$targetFile], $phpArgs);
 $cmd = 'php ' . implode(' ', array_map('escapeshellarg', $allArgs));
 
-// Execute with passthru to show output
+// Execute command
 $exitCode = 0;
-passthru($cmd, $exitCode);
+if ($jsonOutput) {
+    // JSON mode: suppress script output for clean JSON parsing
+    $cmd .= ' > /dev/null 2>&1';
+    exec($cmd, $output, $exitCode);
+} else {
+    // Human-readable mode: show script output
+    passthru($cmd, $exitCode);
+}
 
 // Generate profile analysis
 try {

docs/TROUBLESHOOTING.md

@@ -215,11 +215,24 @@ rm /tmp/trace.*.xt /tmp/cachegrind.out.*
 
 **Issue**: Output not in expected format or missing data
 
+**Common Problem - Script Output Mixing with JSON**:
+```bash
+# ❌ Before v0.x.x: Script output breaks jq parsing
+./bin/xdebug-profile --json -- php script.php | jq '.'
+# parse error: Invalid numeric literal at line 1, column 8
+
+# ✅ Now: Clean JSON output (script stdout/stderr automatically suppressed)
+./bin/xdebug-profile --json -- php script.php | jq '.["🎯 bottleneck_functions"]'
+```
+
 **Format Solutions**:
 ```bash
 # Ensure JSON output for AI processing
 ./bin/xdebug-profile --json -- php script.php
 
+# Pipe to jq for filtering
+./bin/xdebug-profile --json -- php script.php | jq '.["⏱️ execution_time_ms"]'
+
 # Verify schema compliance
 ./bin/validate-profile-json profile-output.json