Move sample script into examples and refresh docs

README.md

@@ -158,6 +158,47 @@ print(f"Start Time: {result['metrics']['start_time']}")
 print(f"Exit Code: {result['exit_code']}")
 print(f"Success: {result['metrics']['success']}")
 ```
+
+## ⏱️ Task Scheduling & Automation
+
+Python Script Runner ships with a lightweight scheduler to automate recurring or event-driven jobs without standing up extra infrastructure. The scheduler includes:
+
+- **Automation & recurrence**: Define hourly, daily, weekly, or custom interval schedules (`every_5min`, `every_30min`) or supply a cron expression for more complex windows.
+- **Dependency-aware execution**: Chain tasks together so downstream jobs only start after upstream tasks complete successfully.
+- **Error handling & visibility**: Execution results are captured in-memory with status, error messages, and next-run timestamps for quick troubleshooting.
+- **Event triggers**: Bind tasks to custom events (for example, `on_script_failure`) and trigger them manually via the CLI.
+
+Basic usage:
+
+```python
+from runner import TaskScheduler
+
+scheduler = TaskScheduler()
+
+# Schedule a daily report and a dependent distribution step
+scheduler.add_scheduled_task("generate_report", "reports/daily.py", schedule="daily")
+scheduler.add_scheduled_task(
+    "distribute_report",
+    "reports/distribute.py",
+    dependencies=["generate_report"],
+)
+
+# Run any tasks that are due (e.g., inside a cron shell)
+for result in scheduler.run_due_tasks():
+    print(result)
+```
+
+You can also interact via the CLI:
+
+```bash
+python -m runner \
+  --add-scheduled-task nightly_cleanup \
+  --script scripts/cleanup.py \
+  --schedule daily \
+  --list-scheduled-tasks
+```
+
+The scheduler respects dependency ordering automatically; if a prerequisite task fails, dependent tasks are skipped until the next eligible run.
 **Benefit**: SQLite database provides immutable audit trail for SOC2/HIPAA compliance. Every execution logged with full context.
 
 ---
@@ -186,6 +227,8 @@ python -m runner script.py --slack-webhook "YOUR_WEBHOOK_URL"
 python-script-runner myscript.py
 ```
 
+> Need a quick smoke test? Run the bundled sample script with `python -m runner examples/sample_script.py` to see the default metrics output without creating your own file first.
+
 ### 📊 Default Output - Comprehensive Metrics Report
 
 Every run automatically displays a detailed metrics report with:

dashboard/backend/test_app.py

@@ -57,7 +57,7 @@ def test_database():
     cursor.execute("""INSERT INTO executions 
         (script_path, script_args, start_time, end_time, execution_time_seconds, exit_code, success, stdout_lines, stderr_lines, created_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""", 
-        ('test_script.py', '', now, now, 1.5, 0, True, 10, 0, now))
+        ('sample_script.py', '', now, now, 1.5, 0, True, 10, 0, now))
     exec_id = cursor.lastrowid
 
     cursor.execute("""INSERT INTO metrics (execution_id, metric_name, metric_value)

docs/installation.md

@@ -57,7 +57,7 @@ docker run --rm psr myscript.py
 ```bash
 python runner.py --version
 python runner.py --help
-python runner.py test_script.py
+python runner.py examples/sample_script.py
 ```
 
 ## Troubleshooting

examples/sample_script.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+"""Simple sample script for Python Script Runner demonstration."""
+
+print("Python Script Runner - Sample Script")
+print("✅ Sample completed successfully")

release.sh

@@ -728,7 +728,7 @@ cmd_validate() {
     # Check Python compilation
     print_step "Checking code quality..."
     local compile_output
-    if compile_output=$(python3 -m py_compile runner.py test_script.py 2>&1); then
+    if compile_output=$(python3 -m py_compile runner.py examples/sample_script.py 2>&1); then
         print_success "Compilation successful"
     else
         print_error "Python compilation failed:"