Initial commit with translated description

references/usage.md

@@ -0,0 +1,202 @@
+# Task Status Usage Guide
+
+## Quick Examples
+
+### Manual Status Updates (Single Messages)
+```bash
+# Progress update
+python send_status.py "Fetching data..." "progress" "fetch"
+
+# Success update
+python send_status.py "Done! 150 records processed" "success" "process"
+
+# Error update
+python send_status.py "Failed to connect to API" "error" "api_call"
+
+# Warning update
+python send_status.py "Continuing despite timeout" "warning" "timeout"
+```
+
+### Automated Periodic Monitoring (Every 5 seconds)
+```bash
+# Start monitoring a long task
+python monitor_task.py start "video_processing" "progress"
+
+# Monitor runs in background, sending "Still working..." updates every 5 seconds
+
+# Stop monitoring with final status
+python monitor_task.py stop "video_processing" "success" "Processing complete!"
+
+# Or with an error
+python monitor_task.py stop "video_processing" "error" "Failed: Corrupt file"
+```
+
+### Python Script
+```python
+from send_status import send_status
+
+def process_data():
+    send_status("Reading files...", "progress", "read")
+    # ... work
+    send_status("Processing complete", "success", "process")
+```
+
+### Shell Script
+```bash
+#!/bin/bash
+python send_status.py "Starting backup..." "progress" "backup"
+# ... backup command
+python send_status.py "Backup complete" "success" "backup"
+```
+
+## Status Types
+
+| Type | Emoji | ASCII | When to Use |
+|------|-------|-------|-------------|
+| progress | 🔄 | -> | Ongoing work, "still working on it" |
+| success | ✅ | OK | Task completed successfully |
+| error | ❌ | ! | Task failed, cannot continue |
+| warning | ⚠️ | ? | Issue but continuing |
+
+## When to Use Each Method
+
+### Use Manual Updates When:
+- Task is short (under 30 seconds)
+- You want control over when updates are sent
+- Task has discrete, meaningful milestones
+
+### Use Periodic Monitoring When:
+- Task is long-running (over 1 minute)
+- You want consistent "heartbeat" updates every 5 seconds
+- Task has long periods of quiet work
+- You want to reassure user that work is ongoing
+
+## Periodic Monitoring Details
+
+### Starting a Monitor
+```bash
+python monitor_task.py start "<task_name>" "<status_type>" [--interval <seconds>]
+```
+
+- Sends "Still working..." updates every 5 seconds by default
+- Runs in background until stopped
+- Can customize interval with `--interval`
+
+### Viewing Active Monitors
+```bash
+python monitor_task.py status
+```
+
+### Cancelling All Monitors (Without Final Status)
+```bash
+python monitor_task.py cancel_all
+```
+
+## Best Practices
+
+1. **Keep messages short** - Under 140 characters
+2. **Be specific** - Include step names for clarity
+3. **Update periodically** - Every ~4 seconds for long tasks (or use monitoring)
+4. **Use details** - Add extra context when needed
+5. **End with status** - Always send final success/error
+
+## Common Patterns
+
+### Multi-step Task (Manual)
+```bash
+python send_status.py "Step 1/5: Validating input" "progress" "step1"
+# ... step 1
+python send_status.py "Step 2/5: Processing data" "progress" "step2"
+# ... step 2
+# ... etc
+python send_status.py "All steps complete" "success" "final"
+```
+
+### Long-Running Task (Automatic Monitoring)
+```bash
+# Start monitor before starting the task
+python monitor_task.py start "data_migration" "progress"
+
+# Run the actual task (can take minutes/hours)
+# Monitor sends "Still working..." updates every 5 seconds
+
+# When task finishes, stop monitor with final status
+python monitor_task.py stop "data_migration" "success" "Migration complete: 5000 records"
+```
+
+### With Details
+```bash
+python send_status.py "Uploading..." "progress" "upload" --details "File: report.pdf (2.4MB)"
+```
+
+### Error Recovery
+```bash
+python send_status.py "Connection failed, retrying..." "warning" "retry"
+# ... retry logic
+if success:
+    python send_status.py "Retry successful" "success" "retry"
+else:
+    python send_status.py "Retry failed, giving up" "error" "retry"
+```
+
+### Long Task with Manual Control
+```bash
+# Start monitor
+python monitor_task.py start "processing" "progress"
+
+# ... do work ...
+
+# Check status periodically
+python monitor_task.py status
+
+# When done, stop monitor
+python monitor_task.py stop "processing" "success" "Finished!"
+```
+
+## Integration
+
+### Import send_status for Python Scripts
+```python
+from send_status import send_status
+
+msg = send_status("Working...", "progress", "work")
+print(f"Logged: {msg}")  # Output: "-> [work] Working..."
+```
+
+### Use in Shell Scripts
+```bash
+#!/bin/bash
+send_status() {
+    python send_status.py "$1" "$2" "$3"
+}
+
+send_status "Starting process" "progress" "main"
+# ... process
+send_status "Done" "success" "main"
+```
+
+### Automation with Clawdbot Cron
+For scheduled tasks that need periodic status updates, use Clawdbot's cron feature.
+
+## Monitoring Use Cases
+
+### File Processing
+```bash
+python monitor_task.py start "file_proc" "progress"
+# Process 1000 files (takes 10 minutes)
+python monitor_task.py stop "file_proc" "success" "Processed 1000 files"
+```
+
+### Data Sync
+```bash
+python monitor_task.py start "sync" "progress" --interval 10
+# Sync databases (takes 5 minutes)
+python monitor_task.py stop "sync" "success" "Sync complete"
+```
+
+### API Calls
+```bash
+python monitor_task.py start "api_call" "progress"
+# Make 1000 API requests
+python monitor_task.py stop "api_call" "success" "All 1000 requests successful"
+```