Update docs for API/CLI changes in 1.0 (#421)

* Update some API basics for the 0.23/1.0 API change

docs/cli/tg-show-processor-state.md

@@ -0,0 +1,196 @@
+# tg-show-processor-state
+
+## Synopsis
+
+```
+tg-show-processor-state [OPTIONS]
+```
+
+## Description
+
+The `tg-show-processor-state` command displays the current state of TrustGraph processors by querying the metrics endpoint. It retrieves processor information from the Prometheus metrics API and displays active processors with visual status indicators.
+
+This command is useful for:
+- Monitoring processor health and availability
+- Verifying that processors are running correctly
+- Troubleshooting processor connectivity issues
+- Getting a quick overview of active TrustGraph components
+
+## Options
+
+- `-m, --metrics-url URL`
+  - Metrics endpoint URL to query for processor information
+  - Default: `http://localhost:8088/api/metrics`
+  - Should point to a Prometheus-compatible metrics endpoint
+
+- `-h, --help`
+  - Show help message and exit
+
+## Examples
+
+### Basic Usage
+
+Display processor states using the default metrics URL:
+```bash
+tg-show-processor-state
+```
+
+### Custom Metrics URL
+
+Query processor states from a different metrics endpoint:
+```bash
+tg-show-processor-state -m http://metrics.example.com:8088/api/metrics
+```
+
+### Remote Monitoring
+
+Monitor processors on a remote TrustGraph instance:
+```bash
+tg-show-processor-state --metrics-url http://10.0.1.100:8088/api/metrics
+```
+
+## Output Format
+
+The command displays processor information in a table format:
+```
+  processor_name                 💚
+  another_processor              💚
+  third_processor                💚
+```
+
+Each line shows:
+- Processor name (left-aligned, 30 characters wide)
+- Status indicator (💚 for active processors)
+
+## Advanced Usage
+
+### Monitoring Script
+
+Create a monitoring script to periodically check processor states:
+```bash
+#!/bin/bash
+while true; do
+    echo "=== Processor State Check ===" 
+    date
+    tg-show-processor-state
+    echo
+    sleep 30
+done
+```
+
+### Health Check Integration
+
+Use in health check scripts:
+```bash
+#!/bin/bash
+output=$(tg-show-processor-state 2>&1)
+if [ $? -eq 0 ]; then
+    echo "Processors are running"
+    echo "$output"
+else
+    echo "Error checking processor state: $output"
+    exit 1
+fi
+```
+
+### Multiple Environment Monitoring
+
+Monitor processors across different environments:
+```bash
+#!/bin/bash
+for env in dev staging prod; do
+    echo "=== $env Environment ==="
+    tg-show-processor-state -m "http://${env}-metrics:8088/api/metrics"
+    echo
+done
+```
+
+## Error Handling
+
+The command handles various error conditions:
+
+- **Connection errors**: If the metrics endpoint is unavailable
+- **Invalid JSON**: If the metrics response is malformed
+- **Missing data**: If the expected processor_info metric is not found
+- **HTTP errors**: If the metrics endpoint returns an error status
+
+Common error scenarios:
+```bash
+# Metrics endpoint not available
+tg-show-processor-state -m http://invalid-host:8088/api/metrics
+# Output: Exception: [Connection error details]
+
+# Invalid URL format
+tg-show-processor-state -m "not-a-url"
+# Output: Exception: [URL parsing error]
+```
+
+## Integration with Other Commands
+
+### With Flow Monitoring
+
+Combine with flow state monitoring:
+```bash
+echo "=== Processor States ==="
+tg-show-processor-state
+echo
+echo "=== Flow States ==="
+tg-show-flow-state
+```
+
+### With Configuration Display
+
+Check processors and current configuration:
+```bash
+echo "=== Active Processors ==="
+tg-show-processor-state
+echo
+echo "=== Current Configuration ==="
+tg-show-config
+```
+
+## Best Practices
+
+1. **Regular Monitoring**: Include in regular health check routines
+2. **Error Handling**: Always check command exit status in scripts
+3. **Logging**: Capture output for historical analysis
+4. **Alerting**: Set up alerts based on processor availability
+5. **Documentation**: Keep track of expected processors for each environment
+
+## Troubleshooting
+
+### No Processors Shown
+
+If no processors are displayed:
+1. Verify the metrics endpoint is accessible
+2. Check that TrustGraph processors are running
+3. Ensure processors are properly configured to export metrics
+4. Verify the metrics URL is correct
+
+### Connection Issues
+
+For connection problems:
+1. Test network connectivity to the metrics endpoint
+2. Verify the metrics service is running
+3. Check firewall rules and network policies
+4. Ensure the correct port is being used
+
+### Metrics Format Issues
+
+If the command fails with JSON parsing errors:
+1. Verify the metrics endpoint returns Prometheus-compatible data
+2. Check that the `processor_info` metric exists
+3. Ensure the metrics service is properly configured
+
+## Related Commands
+
+- [`tg-show-flow-state`](tg-show-flow-state.md) - Display flow processor states
+- [`tg-show-config`](tg-show-config.md) - Show TrustGraph configuration
+- [`tg-show-token-costs`](tg-show-token-costs.md) - Display token usage costs
+- [`tg-show-library-processing`](tg-show-library-processing.md) - Show library processing status
+
+## See Also
+
+- TrustGraph Processor Documentation
+- Prometheus Metrics Configuration
+- TrustGraph Monitoring Guide