Add missing things from Steve

README.md

@@ -21,6 +21,10 @@ temporal-dev/
 │   │   ├── patterns.md         # Signals, queries, saga, child workflows
 │   │   ├── versioning.md       # Patching, workflow types, worker versioning
 │   │   ├── troubleshooting.md  # Decision trees, recovery procedures
+│   │   ├── error-reference.md  # Common error types, workflow status
+│   │   ├── interactive-workflows.md # Testing signals, updates, queries
+│   │   ├── tool-reference.md   # Script options, worker management
+│   │   ├── logs.md             # Log file locations, search patterns
 │   │   └── ai-integration.md   # AI/LLM integration concepts
 │   ├── python/                 # Python SDK references
 │   │   ├── python.md           # SDK overview, quick start

SKILL.md

@@ -155,6 +155,10 @@ Available scripts in `scripts/` for worker and workflow management:
 - **`references/core/patterns.md`** - Conceptual patterns (signals, queries, saga)
 - **`references/core/versioning.md`** - Versioning strategies and concepts
 - **`references/core/troubleshooting.md`** - Decision trees, recovery procedures
+- **`references/core/error-reference.md`** - Common error types, workflow status reference
+- **`references/core/interactive-workflows.md`** - Testing signals, updates, queries
+- **`references/core/tool-reference.md`** - Script options and worker management details
+- **`references/core/logs.md`** - Log file locations and search patterns
 - **`references/core/ai-integration.md`** - AI/LLM integration patterns
 
 ### Python References

references/core/error-reference.md

@@ -0,0 +1,24 @@
+# Common Error Types Reference
+
+| Error Type | Where to Find | What Happened | Recovery |
+|------------|---------------|---------------|----------|
+| **Non-determinism** | `WorkflowTaskFailed` in history | Replay doesn't match history | Analyze error first. **If accidental**: fix code to match history → restart worker. **If intentional v2 change**: terminate → start fresh workflow. |
+| **Workflow code bug** | `WorkflowTaskFailed` in history | Bug in workflow logic | Fix code → Restart worker → Workflow auto-resumes |
+| **Missing workflow** | Worker logs | Workflow not registered | Add to worker.py → Restart worker |
+| **Missing activity** | Worker logs | Activity not registered | Add to worker.py → Restart worker |
+| **Activity bug** | `ActivityTaskFailed` in history | Bug in activity code | Fix code → Restart worker → Auto-retries |
+| **Activity retries** | `ActivityTaskFailed` (count >2) | Repeated failures | Fix code → Restart worker → Auto-retries |
+| **Sandbox violation** | Worker logs | Bad imports in workflow | Fix workflow.py imports → Restart worker |
+| **Task queue mismatch** | Workflow never starts | Different queues in starter/worker | Align task queue names |
+| **Timeout** | Status = TIMED_OUT | Operation too slow | Increase timeout config |
+
+## Workflow Status Reference
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `RUNNING` | Workflow in progress | Wait, or check if stalled |
+| `COMPLETED` | Successfully finished | Get result, verify correctness |
+| `FAILED` | Error during execution | Analyze error |
+| `CANCELED` | Explicitly canceled | Review reason |
+| `TERMINATED` | Force-stopped | Review reason |
+| `TIMED_OUT` | Exceeded timeout | Increase timeout |

references/core/interactive-workflows.md

@@ -0,0 +1,53 @@
+# Interactive Workflows
+
+Interactive workflows pause and wait for external input (signals or updates).
+
+## Signals
+
+Fire-and-forget messages to a workflow.
+
+```bash
+# Send signal to workflow
+temporal workflow signal \
+  --workflow-id <id> \
+  --name "signal_name" \
+  --input '{"key": "value"}'
+
+# Or via interact script (if available)
+uv run interact --workflow-id <id> --signal-name "signal_name" --data '{"key": "value"}'
+```
+
+## Updates
+
+Request-response style interaction (returns a value).
+
+```bash
+# Send update to workflow
+temporal workflow update \
+  --workflow-id <id> \
+  --name "update_name" \
+  --input '{"approved": true}'
+```
+
+## Queries
+
+Read-only inspection of workflow state.
+
+```bash
+# Query workflow state (read-only)
+temporal workflow query \
+  --workflow-id <id> \
+  --name "get_status"
+```
+
+## Testing Interactive Workflows
+
+```bash
+./scripts/ensure-worker.sh
+uv run starter  # Get workflow_id
+./scripts/wait-for-workflow-status.sh --workflow-id $workflow_id --status RUNNING
+uv run interact --workflow-id $workflow_id --signal-name "approval" --data '{"approved": true}'
+./scripts/wait-for-workflow-status.sh --workflow-id $workflow_id --status COMPLETED
+./scripts/get-workflow-result.sh --workflow-id $workflow_id
+./scripts/kill-worker.sh  # CLEANUP
+```

references/core/logs.md

@@ -0,0 +1,23 @@
+# Log Files
+
+| Log | Location | Content |
+|-----|----------|---------|
+| Worker logs | `$CLAUDE_TEMPORAL_LOG_DIR/worker-{project}.log` | Worker output, activity logs, errors |
+
+Default log directory: `/tmp/claude-temporal-logs`
+
+## Useful Log Searches
+
+```bash
+# Find errors
+grep -i "error" $CLAUDE_TEMPORAL_LOG_DIR/worker-*.log
+
+# Check worker startup
+grep -i "started" $CLAUDE_TEMPORAL_LOG_DIR/worker-*.log
+
+# Find activity issues
+grep -i "activity" $CLAUDE_TEMPORAL_LOG_DIR/worker-*.log
+
+# Tail live logs
+tail -f $CLAUDE_TEMPORAL_LOG_DIR/worker-$(basename "$(pwd)").log
+```

references/core/tool-reference.md

@@ -0,0 +1,84 @@
+# Tool Reference
+
+## Lifecycle Scripts
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `ensure-server.sh` | Start dev server if not running | - |
+| `ensure-worker.sh` | Kill old workers, start fresh one | Uses `$TEMPORAL_WORKER_CMD` |
+| `kill-worker.sh` | Kill current project's worker | - |
+| `kill-all-workers.sh` | Kill all workers | `--include-server` |
+| `list-workers.sh` | List running workers | - |
+
+## Monitoring Scripts
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `list-recent-workflows.sh` | Show recent executions | `--minutes N` (default: 5) |
+| `find-stalled-workflows.sh` | Detect stalled workflows | `--query "..."` |
+| `monitor-worker-health.sh` | Check worker status | - |
+| `wait-for-workflow-status.sh` | Block until status | `--workflow-id`, `--status`, `--timeout` |
+
+## Debugging Scripts
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `analyze-workflow-error.sh` | Extract errors from history | `--workflow-id`, `--run-id` |
+| `get-workflow-result.sh` | Get workflow output | `--workflow-id`, `--raw` |
+| `bulk-cancel-workflows.sh` | Mass cancellation | `--pattern "..."` |
+
+## Worker Management Details
+
+### The Golden Rule
+
+**Ensure no old workers are running.** Stale workers with outdated code cause:
+- Non-determinism errors (history mismatch)
+- Executing old buggy code
+- Confusing behavior
+
+**Best practice**: Run only ONE worker instance with the latest code.
+
+### Starting Workers
+
+```bash
+# PREFERRED: Smart restart (kills old, starts fresh)
+./scripts/ensure-worker.sh
+```
+
+This command:
+1. Finds ALL existing workers for the project
+2. Kills them
+3. Starts a new worker with fresh code
+4. Waits for worker to be ready
+
+### Verifying Workers
+
+```bash
+# List all running workers
+./scripts/list-workers.sh
+
+# Check specific worker health
+./scripts/monitor-worker-health.sh
+
+# View worker logs
+tail -f $CLAUDE_TEMPORAL_LOG_DIR/worker-$(basename "$(pwd)").log
+```
+
+**What to look for in logs**:
+- `Worker started, listening on task queue: ...` → Worker is ready
+- `Worker process died during startup` → Startup failure, check logs for error
+
+### Cleanup (REQUIRED)
+
+**Always kill workers when done.** Don't leave workers running.
+
+```bash
+# Kill current project's worker
+./scripts/kill-worker.sh
+
+# Kill ALL workers (full cleanup)
+./scripts/kill-all-workers.sh
+
+# Kill all workers AND server
+./scripts/kill-all-workers.sh --include-server
+```