[{"id":"basic-file-edit","title":"Safe file edit with pre-change snapshot","description":"The canonical Rail usage pattern: declare scope, snapshot, check scope, make change, close.","steps":[{"step":1,"tool":"declare_task","call":{"task_id":"edit-config-001","description":"Update database connection string in config","allowed_paths":["/config/database.json"],"ttl_seconds":1800},"note":"Opens a session; returns session_id"},{"step":2,"tool":"take_snapshot","call":{"session_id":"{{session_id}}","path":"/config/database.json","content":"{{current_file_content}}"},"note":"Immutable R2 snapshot before any edit"},{"step":3,"tool":"check_scope","call":{"session_id":"{{session_id}}","path":"/config/database.json","action":"write"},"note":"Must return allowed:true before proceeding"},{"step":4,"description":"Make the actual file change","note":"Only execute after check_scope returns allowed:true"},{"step":5,"tool":"close_session","call":{"session_id":"{{session_id}}","outcome":"success"}}]},{"id":"deferred-approval","title":"Human-in-the-loop approval for sensitive operations","description":"Use defer mode to pause agent execution and require human sign-off before a high-risk action.","steps":[{"step":1,"tool":"declare_task","call":{"task_id":"drop-table-approval","description":"Drop legacy analytics table after human approval","allowed_paths":["/db/migrations/**"],"ttl_seconds":86400}},{"step":2,"tool":"check_scope","call":{"session_id":"{{session_id}}","path":"/db/migrations/drop_analytics.sql","action":"execute"},"note":"Rail detects high-risk pattern, auto-defers, returns allowed:false with defer_id"},{"step":3,"description":"Agent pauses and notifies operator (webhook fires approval_requested event)"},{"step":4,"tool":"list_pending_approvals","call":{},"note":"Operator calls this to see what needs review"},{"step":5,"tool":"approve_action","call":{"approval_id":"{{approval_id}}","decision":"approve","reason":"Confirmed with DBA team — table is safe to drop"}},{"step":6,"description":"Agent resumes execution with approved action"}]},{"id":"webhook-monitoring","title":"Real-time scope violation alerts","description":"Register a webhook to get notified when an agent attempts an out-of-scope action.","steps":[{"step":1,"tool":"register_webhook","call":{"url":"https://your-system.example.com/rail-events","events":["scope_violation","approval_requested","session_closed"],"secret":"{{your_hmac_secret}}"},"note":"All events carry X-Rail-Signature for verification"},{"step":2,"description":"Your endpoint verifies the HMAC-SHA256 signature and logs or alerts","note":"Signature = HMAC-SHA256(secret, request_body)"}]},{"id":"rollback","title":"Restore a file from snapshot after failed change","description":"If a change causes an error, restore the pre-change snapshot.","steps":[{"step":1,"tool":"list_snapshots","call":{"session_id":"{{session_id}}"},"note":"Find the snapshot_id for the file to restore"},{"step":2,"tool":"restore_snapshot","call":{"session_id":"{{session_id}}","snapshot_id":"{{snapshot_id}}"},"note":"Returns full file content — write it back to disk"},{"step":3,"tool":"close_session","call":{"session_id":"{{session_id}}","outcome":"failure"}}]},{"id":"route-inventory-diff","title":"Capture route inventory and detect deployment diffs","description":"Record all public routes before deploy, then compare the post-deploy inventory and abort if the route surface shrinks.","steps":[{"step":1,"tool":"capture_route_inventory","call":{"session_id":"{{session_id}}","worker_name":"rail-aiops","environment":"production","routes":[{"method":"GET","path":"/"},{"method":"GET","path":"/health"},{"method":"POST","path":"/mcp"}]},"note":"Stores a pre-deploy checksum and route_count for rollback guards"},{"step":2,"description":"Deploy only the targeted content changes"},{"step":3,"tool":"list_route_inventories","call":{"worker_name":"rail-aiops","environment":"production","limit":2},"note":"Compare the latest checksum and route_count against the pre-deploy baseline"},{"step":4,"description":"If any routes were removed, immediately roll back to the previous deployment"}]},{"id":"session-health-monitoring","title":"Session health monitoring with context-drift detection","description":"Continuously inspect agent behavior for drift, call bursts, path-distance spikes, and safety-fingerprint mismatches.","steps":[{"step":1,"tool":"declare_task","call":{"task_id":"monitor-session-health","description":"Watch a long-running deployment session for drift","allowed_paths":["/home/user/sprint5a_deploy/rail-aiops/**"]}},{"step":2,"tool":"get_session_health","call":{"session_id":"{{session_id}}","include_recent_calls":true,"include_path_stats":true},"note":"Returns context_drift, call_frequency, path_distance, safety_fingerprint, and blast_radius data"},{"step":3,"description":"Escalate to human review if status is warning or critical before the agent continues"}]}]