diff --git a/docs/ORCHESTRATION_SCENARIOS.md b/docs/ORCHESTRATION_SCENARIOS.md
new file mode 100644
index 0000000..78d8bfd
--- /dev/null
+++ b/docs/ORCHESTRATION_SCENARIOS.md
@@ -0,0 +1,679 @@
+# Orchestration Scenarios and Tool Flows
+
+This document outlines example scenarios of varying complexity to illustrate the desired orchestration patterns between Tatlock (Butler/Coordinator), expert agents (The Librarian, etc.), and the user.
+
+## Architecture Overview
+
+```
+User Request
+     ↓
+[Steward] → Analyzes request, has visibility into ALL capabilities
+           → Makes routing decision: which experts needed
+           → Passes simplified instruction to Tatlock (not raw tool schemas)
+     ↓
+[Tatlock/Butler] → Coordinator, receives "use Librarian for wiki creation"
+                 → Calls expert agents as tools
+                 → Synthesizes responses into butler-voice answer
+     ↓
+[Expert Agents] → The Librarian, Home Automation, Memory, etc.
+                → Each has their own specialized tools
+                → Return structured results to Tatlock
+     ↓
+[External APIs] → library-desk, home-assistant, user-db, etc.
+```
+
+**Key Principles**:
+
+1. **Steward sees everything** - Has access to all capability descriptions to make informed routing decisions
+2. **Simplified passthrough** - Tatlock receives "delegate to Librarian for research" not 16 tool schemas
+3. **Expert agents are tools** - Tatlock calls `librarian_agent(task)`, not `hybrid_search()` directly
+4. **Each expert owns their tools** - Librarian has wiki tools, Home Automation has device tools
+5. **Results flow up** - Tatlock synthesizes all expert responses into coherent butler answer
+
+---
+
+## Scenario 1: Weather Check (Multi-Step with Memory Lookup)
+
+**User**: "What's the weather like?"
+
+### Complexity Analysis
+
+This seemingly simple request requires:
+1. **Location determination** - Where does the user want weather for?
+2. **Memory/database lookup** - Retrieve user's home location or current location
+3. **Weather data fetch** - Search for weather at determined location
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: memory (user context), tatlock_core (web search)
+   → Complexity: moderate
+   → Note: Location must be determined before weather lookup
+
+2. Tatlock Execution - Step 1
+   <think>User asked about weather but didn't specify location.
+   Checking user profile for home location...</think>
+   → Calls: memory_agent(task: "get user home location")
+   → Memory queries user database
+   → Returns: "User home location: Amsterdam, Netherlands"
+
+3. Tatlock Execution - Step 2
+   <think>User is based in Amsterdam. Fetching current weather...</think>
+   → Calls: search_web("current weather Amsterdam Netherlands")
+   → Receives: "Amsterdam: 12°C, light rain, humidity 78%"
+
+4. Response
+   "Currently 12°C with light rain in Amsterdam, sir. You might want
+   to grab an umbrella if you're heading out."
+```
+
+### Intra-System Prompts
+
+**Steward → Tatlock Note**:
+```
+Weather query - location not specified.
+1. First: Query memory for user's location (home or current)
+2. Then: Search weather for that location
+Capabilities: memory, tatlock_core
+Complexity: moderate
+```
+
+**Tatlock → Memory Agent**:
+```
+Task: Retrieve user's location for weather query.
+Context: User asked about weather without specifying location.
+Action required: Return user's home location or current known location.
+
+Reference (user's original request): "What's the weather like?"
+```
+
+**Memory Agent → Tatlock Response**:
+```
+User location retrieved:
+- Home location: Amsterdam, Netherlands
+- Last known location: Amsterdam (home)
+- Location confidence: high
+- Source: user profile settings
+```
+
+### Alternative Flow: Location Ambiguity
+
+If user has multiple locations or is traveling:
+
+```
+Memory Agent → Tatlock Response:
+  User has multiple locations:
+  - Home: Amsterdam, Netherlands
+  - Office: Rotterdam, Netherlands
+  - Currently traveling: Unknown
+
+  Recommendation: Ask user to clarify or use home location as default.
+```
+
+Tatlock could then either:
+- Ask user: "Shall I check the weather in Amsterdam, sir, or elsewhere?"
+- Default to home: Use Amsterdam and mention the assumption
+
+---
+
+## Scenario 2: Adjust Temperature Based on Weather (Conditional Multi-Expert)
+
+**User**: "Check the weather and if it's cold, turn up the heating"
+
+### Complexity Analysis
+
+This requires:
+1. **Location lookup** - Where to check weather (implicit: user's home)
+2. **Weather fetch** - Get current outdoor temperature
+3. **Conditional evaluation** - Is it "cold"? (requires threshold judgment)
+4. **Home automation** - Adjust heating if condition met
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: memory, tatlock_core, home_automation
+   → Complexity: moderate
+   → Note: Conditional logic - heating only if cold
+   → Sequence: location → weather → evaluate → (maybe) heating
+
+2. Tatlock Execution - Step 1
+   <think>Need to check weather at user's location first...</think>
+   → Calls: memory_agent(task: "get user home location")
+   → Returns: "Amsterdam, Netherlands"
+
+3. Tatlock Execution - Step 2
+   <think>Fetching weather for Amsterdam...</think>
+   → Calls: search_web("current weather Amsterdam Netherlands")
+   → Receives: "Current temperature: 8°C, cloudy, wind 15km/h"
+
+4. Tatlock Evaluation
+   <think>Temperature is 8°C - that's cold by most standards.
+   User requested heating adjustment if cold. Will proceed...</think>
+
+5. Tatlock Execution - Step 3
+   <think>Delegating heating adjustment to Home Automation...</think>
+   → Calls: home_automation_agent(task)
+   → Home Automation executes: set_thermostat(temperature=21)
+   → Receives: "Thermostat set to 21°C"
+
+6. Response
+   "It's rather brisk outside at 8°C, sir. I've taken the liberty of raising
+   the heating to a comfortable 21°C. The house should warm up shortly."
+```
+
+### Intra-System Prompts
+
+**Steward → Tatlock Note**:
+```
+Conditional weather-to-heating request.
+1. Get user location from memory
+2. Check weather at location
+3. IF cold (suggest: below 15°C): delegate to home_automation to increase heating
+4. IF not cold: inform user, no action needed
+Capabilities: memory, tatlock_core, home_automation
+Complexity: moderate (conditional)
+```
+
+**Tatlock → Home Automation Agent**:
+```
+Task: Increase heating due to cold weather conditions.
+Context: Current outdoor temperature is 8°C in Amsterdam. User requested
+heating adjustment if cold - condition is met.
+Action required: Set thermostat to comfortable temperature (recommend 21°C).
+
+Reference (user's original request): "Check the weather and if it's cold, turn up the heating"
+```
+
+**Home Automation → Tatlock Response**:
+```
+Action completed: Thermostat adjusted
+- Previous setting: 18°C
+- New setting: 21°C
+- Zone: All zones (whole house)
+- Estimated time to reach target: 15 minutes
+- Note: Eco mode disabled temporarily for faster heating
+```
+
+### Alternative Flow: Not Cold
+
+```
+Weather returns: "Current temperature: 18°C, partly sunny"
+
+Tatlock Evaluation:
+<think>18°C isn't cold - no heating adjustment needed.
+Will inform user that conditions don't warrant heating...</think>
+
+Response:
+"It's a pleasant 18°C outside, sir - not particularly cold.
+I don't believe the heating requires adjustment, but do let
+me know if you'd like it warmer regardless."
+```
+
+---
+
+## Scenario 3: Adjust Lights Based on Time (Conditional Logic)
+
+**User**: "Set the lights appropriately for the time of day"
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: tatlock_core (datetime), home_automation
+   → Complexity: moderate
+
+2. Tatlock Execution - Step 1
+   <think>Checking current time to determine appropriate lighting...</think>
+   → Calls: get_current_datetime()
+   → Receives: "2024-12-11 21:45"
+
+3. Tatlock Evaluation
+   <think>It's evening (21:45). Will set warm, dimmed lighting for wind-down time...</think>
+
+4. Tatlock Execution - Step 2
+   → Calls: home_automation_agent(task)
+   → Home Automation executes: set_scene("evening_relaxation")
+   → Receives: "Scene 'evening_relaxation' activated - warm white 40%"
+
+5. Response
+   "It's quarter to ten in the evening, sir. I've set the lights to a warm,
+   subdued glow - ideal for winding down. Shall I also draw the curtains?"
+```
+
+### Intra-System Prompts
+
+**Tatlock → Home Automation Agent**:
+```
+Task: Set lighting appropriate for current time of day.
+Context: Current time is 21:45 (evening). User wants lights adjusted automatically.
+Action required: Activate appropriate lighting scene for evening/night.
+
+Reference (user's original request): "Set the lights appropriately for the time of day"
+```
+
+---
+
+## Scenario 4: Create a Reminder (Simple Expert Delegation)
+
+**User**: "Remind me to call the dentist tomorrow at 2pm"
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: personal_assistant (reminders)
+   → Complexity: simple
+
+2. Tatlock Execution
+   <think>Creating reminder for tomorrow afternoon...</think>
+   → Calls: personal_assistant_agent(task)
+   → PA executes: create_reminder(title, datetime, notification_time)
+   → Receives: "Reminder created: ID 847"
+
+3. Response
+   "Very good, sir. I've set a reminder to call the dentist for tomorrow at
+   2 o'clock in the afternoon. I'll notify you 15 minutes beforehand."
+```
+
+### Intra-System Prompts
+
+**Tatlock → Personal Assistant Agent**:
+```
+Task: Create a reminder for the user.
+Details:
+- Subject: Call the dentist
+- When: Tomorrow at 14:00
+- Notification: 15 minutes before (default)
+
+Reference (user's original request): "Remind me to call the dentist tomorrow at 2pm"
+```
+
+---
+
+## Scenario 5: Schedule Recurring Automation (Complex, Multi-Expert)
+
+**User**: "Schedule the lights to turn on at 09:00 every weekend day"
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: home_automation (scheduling)
+   → Complexity: moderate
+   → Note: Recurring schedule, weekend-only
+
+2. Tatlock Execution
+   <think>Setting up recurring weekend morning lighting schedule...</think>
+   → Calls: home_automation_agent(task)
+   → HA executes: create_schedule(trigger, days, action)
+   → Receives: "Schedule created: ID wake_light_weekend"
+
+3. Response
+   "The weekend wake-up lighting is now scheduled, sir. Every Saturday and
+   Sunday at 9 o'clock sharp, the lights will illuminate. Would you prefer
+   a gradual sunrise simulation, or an immediate full brightness?"
+```
+
+### Intra-System Prompts
+
+**Tatlock → Home Automation Agent**:
+```
+Task: Create a recurring lighting schedule.
+Details:
+- Action: Turn on lights
+- Time: 09:00
+- Days: Saturday, Sunday (weekends only)
+- Recurrence: Weekly
+
+Reference (user's original request): "Schedule the lights to turn on at 09:00 every weekend day"
+```
+
+---
+
+## Scenario 6: Create Wiki Page About Topic (Expert with Research)
+
+**User**: "Create a wiki page about CI/CD"
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: librarian
+   → Complexity: complex
+   → Specific action: smart_create (research-backed page creation)
+
+2. Tatlock Execution
+   <think>Delegating to The Librarian for research and wiki page creation...</think>
+   → Calls: librarian_agent(task)
+
+3. Librarian Internal Flow
+   → hybrid_search("CI/CD continuous integration deployment")
+   → Synthesizes content from wiki, graph, and web sources
+   → create_wiki_page(title, path, content, tags)
+   → Returns summary to Tatlock
+
+4. Tatlock Receives
+   "Page created: CI/CD
+    Path: /technology/cicd
+    Sources used: 12 (3 wiki, 4 graph, 5 web)
+    Forward links: 8, Backward links: 3"
+
+5. Response
+   "The wiki page on CI/CD has been created, sir. The Librarian has compiled
+   information from 12 sources, including our existing documentation on DevOps
+   practices. The page is now available at /technology/cicd and has been
+   cross-linked with related topics like Jenkins, GitHub Actions, and Docker."
+```
+
+### Intra-System Prompts
+
+**Tatlock → Librarian Agent**:
+```
+Task: Create a comprehensive wiki page about CI/CD.
+Context: User wants a new wiki page created. Use research capabilities to
+gather information and create a well-sourced page.
+
+Action required:
+1. Research the topic using hybrid search (wiki, knowledge graph, web)
+2. Create wiki page with synthesized content
+3. Apply appropriate tags (suggest: technology, devops, automation)
+4. Report back with page details and research summary
+
+Reference (user's original request): "Create a wiki page about CI/CD"
+```
+
+**Librarian → Tatlock Response**:
+```
+Task completed: Wiki page created
+
+Page Details:
+- Title: CI/CD (Continuous Integration/Continuous Deployment)
+- Path: /technology/cicd
+- Tags: technology, devops, automation, software-development
+
+Research Summary:
+- Wiki sources: 3 pages (DevOps Overview, Jenkins Setup, GitHub Actions Guide)
+- Knowledge graph entities: 4 (linked to Docker, Kubernetes, Git, Testing)
+- Web sources: 5 articles (current best practices, 2024 trends)
+- Total sources synthesized: 12
+
+Knowledge Graph Updates:
+- Forward links created: 8 (to existing related pages)
+- Backward links created: 3 (updated existing pages to reference new page)
+
+Content includes sections on:
+- Definition and core concepts
+- CI vs CD distinction
+- Popular tools comparison
+- Best practices
+- Integration with our documented infrastructure
+```
+
+---
+
+## Scenario 7: Update Stock Wiki with Evaluation Tracker (Complex, Multi-Tool Expert)
+
+**User**: "Update the GOOG stock wiki page with a rolling evaluation tracker"
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: librarian
+   → Complexity: complex
+   → Specific action: search existing page, fetch current data, update page
+
+2. Tatlock Execution
+   <think>This requires finding the existing page, fetching current stock data,
+   and updating with a new evaluation section. Delegating to The Librarian...</think>
+   → Calls: librarian_agent(task)
+
+3. Librarian Internal Flow - Step 1
+   <think>First, locating the existing GOOG wiki page...</think>
+   → search_wiki("GOOG stock Alphabet")
+   → Receives: Page ID 234, path /investments/stocks/goog
+
+4. Librarian Internal Flow - Step 2
+   <think>Fetching current page content to preserve existing information...</think>
+   → get_wiki_page(234)
+   → Receives: Current page content
+
+5. Librarian Internal Flow - Step 3
+   <think>Researching current stock data and evaluation metrics...</think>
+   → hybrid_search("GOOG Alphabet stock price evaluation 2024")
+   → Receives: Current price, P/E ratio, analyst ratings, etc.
+
+6. Librarian Internal Flow - Step 4
+   <think>Updating page with new rolling evaluation section...</think>
+   → update_wiki_page(234, content=updated_content)
+   → Receives: Update confirmation
+
+7. Tatlock Receives
+   "Page updated: GOOG Stock Analysis
+    Added section: Rolling Evaluation Tracker
+    Data points added: Price history, P/E trend, Analyst consensus
+    Last updated: 2024-12-11"
+
+8. Response
+   "The GOOG stock page has been updated, sir. I've added a rolling evaluation
+   tracker with current metrics: the stock is trading at $178.32 with a P/E
+   of 24.8, and analyst consensus remains 'Buy'. The tracker includes a
+   90-day price trend and quarterly earnings history. Shall I set up
+   automatic weekly updates?"
+```
+
+### Intra-System Prompts
+
+**Tatlock → Librarian Agent**:
+```
+Task: Update the GOOG (Alphabet) stock wiki page with a rolling evaluation tracker.
+Context: User wants to add ongoing stock evaluation tracking to an existing page.
+
+Actions required:
+1. Find the existing GOOG stock wiki page
+2. Read current page content (preserve existing information)
+3. Research current stock data and evaluation metrics
+4. Update the page with a new "Rolling Evaluation Tracker" section including:
+   - Current price and change
+   - Key ratios (P/E, P/B, etc.)
+   - Analyst consensus
+   - Price trend (30/60/90 day)
+   - Recent earnings summary
+5. Report back with update summary
+
+Reference (user's original request): "Update the GOOG stock wiki page with a rolling evaluation tracker"
+```
+
+**Librarian → Tatlock Response**:
+```
+Task completed: Wiki page updated
+
+Page Details:
+- Title: GOOG - Alphabet Inc. Stock Analysis
+- Path: /investments/stocks/goog
+- Page ID: 234
+
+Update Summary:
+- New section added: "Rolling Evaluation Tracker"
+- Existing content: Preserved (company overview, investment thesis)
+
+Evaluation Data Added:
+- Current Price: $178.32 (+1.2% today)
+- P/E Ratio: 24.8 (vs sector avg 28.3)
+- P/B Ratio: 6.2
+- 52-Week Range: $120.21 - $191.75
+- Analyst Consensus: Buy (24 buy, 8 hold, 2 sell)
+- Price Trend: +15.3% (90-day)
+- Last Earnings: Q3 2024 - Beat estimates by 8%
+
+Sources:
+- Web: 4 financial data sources
+- Existing wiki: Investment strategy context
+
+Suggested follow-up: Set up automated weekly data refresh?
+```
+
+---
+
+## Scenario 8: Complex Multi-Expert Coordination
+
+**User**: "Check if there's anything about the new project deadline in my notes,
+if so create a reminder, and if the deadline is this week, also update the
+project wiki page with a status note"
+
+### Flow
+
+```
+1. Steward Analysis
+   → Capabilities needed: librarian, personal_assistant
+   → Complexity: complex
+   → Note: Conditional multi-step, requires information passing between experts
+
+2. Tatlock Execution - Step 1
+   <think>First, searching for project deadline information in the wiki...</think>
+   → Calls: librarian_agent(search_task)
+   → Librarian: hybrid_search("new project deadline")
+   → Returns: "Project Alpha deadline: December 15, 2024 (this Friday)"
+
+3. Tatlock Evaluation
+   <think>Found deadline: December 15. That's this week (Friday).
+   Need to: 1) Create reminder, 2) Update project wiki page...</think>
+
+4. Tatlock Execution - Step 2 (parallel if possible)
+   <think>Creating reminder and updating wiki status...</think>
+
+   → Calls: personal_assistant_agent(reminder_task)
+   → PA: create_reminder("Project Alpha deadline", "2024-12-15 09:00")
+   → Returns: "Reminder created for Dec 15 at 9am"
+
+   → Calls: librarian_agent(update_task)
+   → Librarian: search_wiki → get_wiki_page → update_wiki_page
+   → Returns: "Project Alpha page updated with deadline status note"
+
+5. Response
+   "I've found the deadline in your notes, sir - Project Alpha is due this
+   Friday, December 15th. I've set a reminder for 9 o'clock that morning,
+   and I've updated the project wiki page with a status note indicating
+   the imminent deadline. Is there anything else you need to prepare?"
+```
+
+### Intra-System Prompts
+
+**Tatlock → Librarian Agent (Search)**:
+```
+Task: Search for information about a new project deadline.
+Context: User wants to find deadline information from their notes/wiki.
+
+Action required:
+1. Search wiki and knowledge base for project deadline information
+2. Return: Project name, deadline date, and any relevant context
+
+Reference (user's original request): "Check if there's anything about the new project deadline in my notes..."
+```
+
+**Tatlock → Personal Assistant Agent**:
+```
+Task: Create a reminder for a project deadline.
+Details:
+- Subject: Project Alpha deadline
+- When: December 15, 2024 at 09:00
+- Priority: High (deadline is this week)
+- Notification: Morning of the deadline
+
+Reference: Creating reminder based on deadline found in user's notes.
+```
+
+**Tatlock → Librarian Agent (Update)**:
+```
+Task: Update the Project Alpha wiki page with a deadline status note.
+Context: Project deadline is December 15, 2024 (this Friday). User requested
+a status update since the deadline is this week.
+
+Action required:
+1. Find the Project Alpha wiki page
+2. Add a status note/banner indicating the imminent deadline
+3. Optionally update any status fields
+
+Reference: Part of user's request to track and highlight near-term deadlines.
+```
+
+---
+
+## Response Pattern Guidelines
+
+### Tatlock's Think Updates (Streaming to User)
+
+During multi-step operations, Tatlock should emit `<think>` updates to keep the user informed:
+
+```
+<think>Analyzing your request...</think>
+<think>Searching for deadline information in the wiki...</think>
+<think>Found the deadline - December 15th. Creating reminder...</think>
+<think>Updating the project page with status note...</think>
+<think>All tasks complete. Composing response...</think>
+```
+
+### Tatlock's Final Response Pattern
+
+1. **Acknowledge** - Confirm understanding of the request
+2. **Summarize actions** - What was done, by whom (implicitly)
+3. **Key details** - Important information the user should know
+4. **Proactive offer** - Suggest related actions or follow-ups
+5. **Butler voice** - Formal but warm, with personality
+
+### Expert Agent Response Pattern
+
+1. **Task status** - Completed/Partial/Failed
+2. **Action summary** - What was done
+3. **Key data** - Information Tatlock needs to synthesize
+4. **Metadata** - IDs, counts, timestamps for reference
+5. **Suggestions** - Optional follow-up actions
+
+---
+
+## Error Handling Scenarios
+
+### Expert Agent Failure
+
+```
+Tatlock → Librarian: "Create wiki page about quantum computing"
+Librarian → Tatlock: "Error: library-desk API unavailable (connection timeout)"
+
+Tatlock Response:
+"I'm afraid The Librarian is having some difficulty reaching the wiki
+service at the moment, sir. I can attempt a basic web search on quantum
+computing if you'd like, or we can try the wiki operation again in a
+few minutes."
+```
+
+### Partial Completion
+
+```
+User: "Create a reminder and add it to my calendar"
+
+Tatlock → PA: Create reminder
+PA → Tatlock: "Reminder created successfully"
+
+Tatlock → Calendar: Add to calendar
+Calendar → Tatlock: "Error: Calendar sync not configured"
+
+Tatlock Response:
+"I've created the reminder, sir, but I wasn't able to add it to your
+calendar - it appears the calendar integration needs to be configured.
+The reminder will still alert you at the scheduled time. Shall I help
+set up the calendar connection?"
+```
+
+---
+
+## Summary: Key Design Principles
+
+1. **Tatlock is the orchestrator** - Never exposes raw tool complexity to users
+2. **Expert agents are tools** - Tatlock calls them, they return structured responses
+3. **Context flows down** - Each expert gets only what they need to complete their task
+4. **Results flow up** - Tatlock synthesizes all responses into coherent butler-voice answer
+5. **Think updates maintain engagement** - User sees progress during complex operations
+6. **Errors are handled gracefully** - Tatlock explains and offers alternatives
+7. **Proactive suggestions** - Tatlock anticipates follow-up needs