feat: allow multiple questions

docs: rename and expand contributing guidelines

README.md

@@ -111,7 +111,7 @@ This sets up:
 - **LLM provider** - Interactive default model configuration
 - All required Python dependencies with `uv`
 
-- At last, it will initiate the open hive interface in your browser
+- Finally, it will open the Hive interface in your browser
 
 > **Tip:** To reopen the dashboard later, run `hive open` from the project directory.
 
@@ -125,18 +125,18 @@ Type the agent you want to build in the home input box
 
 ### Use Template Agents
 
-Click "Try a sample agent" and check the templates. You can run a templates directly or choose to build your version on top of the existing template.
+Click "Try a sample agent" and check the templates. You can run a template directly or choose to build your version on top of the existing template.
 
 ### Run Agents
 
-Now you can run an agent by selectiing the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.
+Now you can run an agent by selecting the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.
 
 <img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/71c38206-2ad5-49aa-bde8-6698d0bc55f5" />
 
 ## Features
 
 - **Browser-Use** - Control the browser on your computer to achieve hard tasks
-- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agent compelteing the jobs for you
+- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agents completing the jobs for you
 - **[Goal-Driven Generation](docs/key_concepts/goals_outcome.md)** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them
 - **[Adaptiveness](docs/key_concepts/evolution.md)** - Framework captures failures, calibrates according to the objectives, and evolves the agent graph
 - **[Dynamic Node Connections](docs/key_concepts/graph.md)** - No predefined edges; connection code is generated by any capable LLM based on your goals

SECURITY.md

@@ -39,8 +39,8 @@ We consider security research conducted in accordance with this policy to be:
 ## Security Best Practices for Users
 
 1. **Keep Updated**: Always run the latest version
-2. **Secure Configuration**: Review `config.yaml` settings, especially in production
-3. **Environment Variables**: Never commit `.env` files or `config.yaml` with secrets
+2. **Secure Configuration**: Review your `~/.hive/configuration.json`, `.mcp.json`, and environment variable settings, especially in production
+3. **Environment Variables**: Never commit `.env` files or any configuration files that contain secrets
 4. **Network Security**: Use HTTPS in production, configure firewalls appropriately
 5. **Database Security**: Use strong passwords, limit network access
 

core/demos/event_loop_wss_demo.py

@@ -601,7 +601,7 @@ async def handle_ws(websocket):
         )
         node = EventLoopNode(
             event_bus=bus,
-            config=LoopConfig(max_iterations=10_000, max_history_tokens=32_000),
+            config=LoopConfig(max_iterations=10_000, max_context_tokens=32_000),
             conversation_store=STORE,
             tool_executor=tool_executor,
         )

core/demos/github_outreach_demo.py

@@ -1769,7 +1769,7 @@ async def _run_pipeline(websocket, initial_message: str):
             config=LoopConfig(
                 max_iterations=30,
                 max_tool_calls_per_turn=30,
-                max_history_tokens=64000,
+                max_context_tokens=64000,
                 max_tool_result_chars=8_000,
                 spillover_dir=str(_DATA_DIR),
             ),

core/demos/handoff_demo.py

@@ -752,7 +752,7 @@ async def _run_pipeline(websocket, topic: str):
         config=LoopConfig(
             max_iterations=20,
             max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
+            max_context_tokens=32_000,
         ),
         conversation_store=store_a,
         tool_executor=tool_executor,
@@ -850,7 +850,7 @@ async def _run_pipeline(websocket, topic: str):
         config=LoopConfig(
             max_iterations=10,
             max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
+            max_context_tokens=32_000,
         ),
         conversation_store=store_b,
     )

core/demos/org_demo.py

@@ -1258,7 +1258,7 @@ async def _run_org_pipeline(websocket, topic: str):
             config=LoopConfig(
                 max_iterations=30,
                 max_tool_calls_per_turn=30,
-                max_history_tokens=32_000,
+                max_context_tokens=32_000,
             ),
             conversation_store=store,
             tool_executor=executor,

core/framework/agents/credential_tester/__main__.py

@@ -10,13 +10,14 @@ from .agent import CredentialTesterAgent
 
 
 def setup_logging(verbose=False, debug=False):
+    from framework.observability import configure_logging
+
     if debug:
-        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+        configure_logging(level="DEBUG")
     elif verbose:
-        level, fmt = logging.INFO, "%(message)s"
+        configure_logging(level="INFO")
     else:
-        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
-    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+        configure_logging(level="WARNING")
 
 
 def pick_account(agent: CredentialTesterAgent) -> dict | None:

core/framework/agents/credential_tester/agent.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from framework.config import get_max_context_tokens
 from framework.graph import Goal, NodeSpec, SuccessCriterion
 from framework.graph.checkpoint_config import CheckpointConfig
 from framework.graph.edge import GraphSpec
@@ -455,7 +456,6 @@ identity_prompt = (
 loop_config = {
     "max_iterations": 50,
     "max_tool_calls_per_turn": 30,
-    "max_history_tokens": 32000,
 }
 
 # ---------------------------------------------------------------------------
@@ -541,7 +541,7 @@ class CredentialTesterAgent:
             loop_config={
                 "max_iterations": 50,
                 "max_tool_calls_per_turn": 30,
-                "max_history_tokens": 32000,
+                "max_context_tokens": get_max_context_tokens(),
             },
             conversation_mode="continuous",
             identity_prompt=(

core/framework/agents/discovery.py

@@ -79,7 +79,7 @@ def _extract_agent_stats(agent_path: Path) -> tuple[int, int, list[str]]:
     if agent_json.exists():
         try:
             data = json.loads(agent_json.read_text(encoding="utf-8"))
-            json_nodes = data.get("nodes", [])
+            json_nodes = data.get("graph", {}).get("nodes", []) or data.get("nodes", [])
             if node_count == 0:
                 node_count = len(json_nodes)
             tools: set[str] = set()

core/framework/agents/queen/agent.py

@@ -35,6 +35,5 @@ queen_graph = GraphSpec(
     loop_config={
         "max_iterations": 999_999,
         "max_tool_calls_per_turn": 30,
-        "max_history_tokens": 32000,
     },
 )

core/framework/agents/queen/nodes/__init__.py

@@ -77,6 +77,10 @@ _QUEEN_PLANNING_TOOLS = [
     "list_agent_sessions",
     "list_agent_checkpoints",
     "get_agent_checkpoint",
+    # Draft graph (visual-only, no code) — new planning workflow
+    "save_agent_draft",
+    "confirm_and_build",
+    # Scaffold + transition to building (requires confirm_and_build first)
     "initialize_and_build_agent",
     # Load existing agent (after user confirms)
     "load_built_agent",
@@ -87,6 +91,7 @@ _QUEEN_BUILDING_TOOLS = _SHARED_TOOLS + [
     "load_built_agent",
     "list_credentials",
     "replan_agent",
+    "save_agent_draft",  # Re-draft during building → auto-dissolves + updates flowchart
     "write_to_diary",  # Episodic memory — available in all phases
 ]
 
@@ -185,18 +190,21 @@ docs. Always run list_agent_tools() to see what actually exists.
 
 # Tool Discovery (MANDATORY before designing)
 
-Before designing any agent, run list_agent_tools() with NO arguments \
-to see ALL available tools (names + descriptions, grouped by category). \
-ONLY use tools from this list in your node definitions. \
+Before designing any agent, discover tools progressively — start compact, drill into \
+what you need. ONLY use tools from this list in your node definitions. \
 NEVER guess or fabricate tool names from memory.
 
-  list_agent_tools()  # ALWAYS call this first (simple mode)
-  list_agent_tools(group="google", output_schema="full")  # drill into a provider
+  list_agent_tools()                                                      # Step 1: provider summary (counts + credential status)
+  list_agent_tools(group="google", output_schema="summary")               # Step 2: service breakdown within a provider
+  list_agent_tools(group="google", service="gmail")                       # Step 3: tool names for one service
+  list_agent_tools(group="google", service="gmail", output_schema="full") # Step 4: full detail for specific tools
 
-NEVER skip the first call. Always start with the full list \
-so you know what providers and tools exist before drilling in. \
-Simple mode truncates long descriptions — use group + "full" to \
-get the complete description and input_schema for the tools you need.
+Step 1 is MANDATORY. Returns provider names, tool counts, credential availability — very compact. \
+Step 2 breaks a provider into services (e.g. google → gmail/calendar/sheets/drive). Only do this \
+for providers that are relevant to the task. \
+Step 3 gets tool names for a specific service — no descriptions, minimal tokens. \
+Step 4 only for services you plan to actually use. \
+Use credentials="available" at any step to filter to tools whose credentials are already configured.
 
 # Discovery & Design Workflow
 
@@ -299,9 +307,31 @@ Present a short **Framework Fit Assessment**:
 - **Gaps/Deal-breakers**: Only list genuinely missing capabilities after checking \
 both list_agent_tools() and built-in features like GCU
 
-## 3: Design Graph and Propose
+### Credential Check (MANDATORY)
 
-Act like an experienced AI solution architect Design the agent architecture:
+The summary from list_agent_tools() includes `credentials_required` and \
+`credentials_available` per provider. **Before designing the graph**, check \
+which providers the design will need and whether credentials are available.
+
+For each provider whose tools you plan to use and where \
+`credentials_available` is false:
+- Tell the user which credential is missing and what it's needed for
+- Ask if they have access to set it up (e.g., API key, OAuth, service account)
+- If they don't have access, adjust the design to work without that provider \
+or suggest alternatives
+
+**Do NOT proceed to the design step with tools that require unavailable \
+credentials without the user acknowledging it.** Finding out at runtime that \
+credentials are missing wastes everyone's time. Surface this early.
+
+Example:
+> "The design needs Google Sheets tools, but the `google` credential isn't \
+configured yet. Do you have a Google service account or OAuth credentials \
+you can set up? If not, I can use CSV file output instead."
+
+## 3: Design Graph and Create Draft
+
+Act like an experienced AI solution architect. Design the agent architecture:
 - Goal: id, name, description, 3-5 success criteria, 2-4 constraints
 - Nodes: **3-6 nodes** (HARD RULE: never fewer than 3, never more than 6). \
 2 nodes is ALWAYS wrong — it means you under-decomposed the task. \
@@ -333,9 +363,140 @@ Read reference agents before designing:
   read_file("exports/deep_research_agent/agent.py")
   read_file("exports/deep_research_agent/nodes/__init__.py")
 
-Present the design to the user. Lead with a large ASCII graph inside \
-a code block so it renders in monospace. Make it visually prominent — \
-use box-drawing characters and clear flow arrows:
+**IMPORTANT: Call save_agent_draft() early and often.** \
+The flowchart is a live collaboration artifact, not a final deliverable. \
+Call save_agent_draft() as soon as you have a rough shape — even before \
+all details are finalized. Then **update it interactively** as the \
+conversation progresses:
+
+- After the user gives feedback ("add a validation step", "split that node") \
+→ immediately call save_agent_draft() with the updated graph so they see \
+the change reflected in the visualizer.
+- After you refine your understanding of requirements → update the draft.
+- When the user asks "what about X?" and it changes the design → update.
+- Don't wait until everything is perfect — iterate visually with the user.
+
+The flowchart is the shared canvas. Every structural change should be \
+visible to the user immediately. The draft captures business logic \
+(node purposes, data flow, tools) without requiring executable code. \
+Include in each node: id, name, description, planned tools, \
+input/output keys, and success criteria as high-level hints.
+
+Each node is auto-classified into an ISO 5807 flowchart symbol type \
+with a unique color. You can override auto-detection by setting \
+`flowchart_type` explicitly on a node. Common types:
+
+**Core symbols:**
+- **start** (green, stadium): Entry point / trigger
+- **terminal** (red, stadium): End of flow
+- **process** (blue, rectangle): Standard processing step
+- **decision** (amber, diamond): Conditional branching
+- **io** (purple, parallelogram): External data input/output
+- **document** (blue-grey, wavy rect): Report or document generation
+- **subprocess** (teal, subroutine): Delegated sub-agent / predefined process
+- **preparation** (brown, hexagon): Setup / initialization step
+- **manual_operation** (pink, trapezoid): Human-in-the-loop / manual review
+- **delay** (orange, D-shape): Wait / throttle / cooldown
+- **display** (cyan): Present results to user
+
+**Data storage:**
+- **database** (light green, cylinder): Database or data store
+- **stored_data** (lime): Generic persistent data
+- **internal_storage** (amber): In-memory / cache
+
+**Flow operations:**
+- **merge** (indigo, inv. triangle): Combine multiple inputs
+- **extract** (indigo, triangle): Split or filter data
+- **connector** (grey, circle): On-page link
+- **offpage_connector** (dark grey, pentagon): Cross-page link
+
+**Domain-specific:**
+- **browser** (dark indigo, hexagon): GCU browser automation
+- **subagent** (dark teal, subroutine): Planning-only sub-agent delegation \
+(dissolved into parent's sub_agents at build time)
+
+Auto-detection works well for most cases: first node → start, nodes with \
+no outgoing edges → terminal, nodes with multiple conditional outgoing \
+edges → decision, GCU nodes → browser, nodes mentioning "database" → \
+database, nodes mentioning "report/document" → document, etc. Set \
+flowchart_type explicitly only when auto-detection would be wrong. \
+Note: `subagent` is never auto-detected — you must set it explicitly.
+
+## Decision Nodes — Planning-Only Conditional Branching
+
+Decision nodes (amber diamonds) are **planning-only** visual elements. They \
+let you show explicit conditional logic in the flowchart so the user can see \
+and approve branching behavior. At `confirm_and_build()`, decision nodes are \
+automatically **dissolved** into the runtime graph:
+
+- The decision clause is merged into the predecessor node's `success_criteria`
+- The yes/no edges are rewired as the predecessor's `on_success`/`on_failure` edges
+- The original flowchart (with decision diamonds) is preserved for display
+
+**When to use decision nodes:**
+- When a workflow has a meaningful condition that determines the next step \
+(e.g., "Did we find enough results?", "Is the data valid?", "Amount > $100?")
+- When the branching logic is important for the user to understand and approve
+- When different outcomes lead to genuinely different processing paths
+
+**How to create a decision node:**
+- Set `flowchart_type: "decision"` on the node
+- Set `decision_clause` to the condition text (e.g., "Data passes validation?")
+- Add two outgoing edges with `label: "Yes"` and `label: "No"` pointing \
+to the respective target nodes
+
+**Good flowcharts display conditions explicitly.** During planning, the user \
+sees the full flowchart with decision diamonds. This is different from the \
+building/running phase where conditions are embedded inside node criteria. \
+The flowchart is the user-facing contract — make branching logic visible.
+
+Example with a decision node:
+```
+gather → [Valid data?] →Yes→ transform → deliver
+                       →No→  notify_user
+```
+In the draft: the `[Valid data?]` node has `flowchart_type: "decision"`, \
+`decision_clause: "Data passes validation checks?"`, with labeled yes/no edges.
+
+## Sub-Agent Nodes — Planning-Only Delegation
+
+Sub-agent nodes (dark teal subroutines) are **planning-only** visual elements \
+that show which nodes delegate to sub-agents. At `confirm_and_build()`, \
+sub-agent nodes are **dissolved** into their parent node:
+
+- The sub-agent node's ID is added to the predecessor's `sub_agents` list
+- The sub-agent node and its connecting edge are removed
+- At runtime, the parent node can invoke the sub-agent via `delegate_to_sub_agent`
+
+**Rules for sub-agent nodes (INCLUDING GCU nodes):**
+- Set `flowchart_type: "subagent"` explicitly (never auto-detected)
+- Connect from the managing parent node to the sub-agent node
+- Sub-agent nodes must be **leaf nodes** — NO outgoing edges to other nodes
+- The sub-agent node's ID must match a real node ID in the runtime graph \
+(the node it represents will be invokable as a sub-agent)
+
+**CRITICAL: GCU nodes (`node_type: "gcu"`) are ALWAYS sub-agents.** \
+They MUST NOT appear in the linear flow. NEVER chain GCU nodes \
+sequentially (A → gcu1 → gcu2 → B is WRONG). Instead, attach them \
+as leaves to the parent that orchestrates them:
+```
+WRONG:  intake → gcu_find_prospect → gcu_scan_mutuals → check_results
+RIGHT:  intake (sub_agents: [gcu_find, gcu_scan]) → check_results
+```
+The parent node delegates to its GCU sub-agents and collects results. \
+The main flow continues from the parent, not from the GCU node.
+
+**How to show delegation in the flowchart:**
+```
+research → (deep_searcher)   ← subagent node, leaf
+research → [Enough results?] ← decision node
+```
+After dissolution: `research` node gets `sub_agents: ["deep_searcher"]` \
+and `success_criteria: "Enough results?"`.
+
+After calling save_agent_draft(), also present an ASCII graph in your message \
+alongside a brief summary of each node's purpose. The user sees both the \
+interactive visualizer AND your textual explanation.
 
 ```
 ┌─────────────────────────┐
@@ -371,18 +532,25 @@ When building the agent, design the entry node's `input_keys` to \
 match what the queen will provide at run time. Worker nodes should \
 use `escalate` for blockers.
 
-Follow the graph with a brief summary of each node's purpose. \
-Get user approval before implementing.
+## 4: Get User Confirmation (MANDATORY GATE)
 
-## 4: Get User Confirmation by ask_user
+**This is a hard boundary between planning and building.** \
+You MUST get explicit user approval before ANY code is generated.
 
-**WAIT for user response.** You MUST get explicit user approval before \
-calling `initialize_and_build_agent`.
-- If **Proceed**: Move to implementing (call `initialize_and_build_agent`)
-- If **Adjust scope**: Discuss what to change, update your notes, re-assess if needed
-- If **More questions**: Answer them honestly, then ask again
-- If **Reconsider**: Discuss alternatives. If they decide to proceed anyway, \
-that's their informed choice
+1. Call ask_user() with options like \
+["Approve and build", "Adjust the design", "I have questions"]
+2. **WAIT for user response.** Do NOT proceed without it.
+3. Handle the response:
+   - If **Approve / Proceed**: Call confirm_and_build(), then \
+   initialize_and_build_agent(agent_name, nodes)
+   - If **Adjust scope**: Discuss changes, update the draft with \
+   save_agent_draft() again, and re-ask
+   - If **More questions**: Answer them honestly, then ask again
+   - If **Reconsider**: Discuss alternatives. If they decide to proceed, \
+   that's their informed choice
+
+**NEVER call initialize_and_build_agent without first calling \
+confirm_and_build().** The system will block the transition if you try.
 """
 
 _building_knowledge = """\
@@ -410,11 +578,10 @@ hashline=True for anchors in results
 - undo_changes(path?) — restore from git snapshot
 
 ## Meta-Agent
-- list_agent_tools(server_config_path?, output_schema?, group?) — discover \
-available tools grouped by category. output_schema: "simple" (default, \
-descriptions truncated to ~200 chars) or "full" (complete descriptions + \
-input_schema). group: "all" (default) or a provider like "google". \
-Call FIRST before designing.
+- list_agent_tools(group?, service?, output_schema?, credentials?) — discover tools \
+progressively: no args=provider summary; group+output_schema="summary"=service breakdown; \
+group+service=tool names; group+service+output_schema="full"=full details. \
+credentials="available" filters to configured tools. Call FIRST before designing.
 - validate_agent_package(agent_name) — run ALL validation checks in one call \
 (class validation, runner load, tool validation, tests). Call after building.
 - list_agents() — list all agent packages in exports/ with session counts
@@ -440,7 +607,9 @@ When a user says "my agent is failing" or "debug this agent":
 
 ## 5. Implement
 
-**Please make sure you have propose the design to the user before implementing**
+**You should only reach this step after the user has approved the draft design \
+in the planning phase. The draft metadata will pre-populate descriptions, \
+goals, success criteria, and node metadata in the generated files.**
 
 Call `initialize_and_build_agent(agent_name, nodes)` to generate all package \
 files. The agent_name must be snake_case (e.g., "my_agent"). Pass node names \
@@ -551,24 +720,44 @@ but no write/edit tools.
 - run_command(command, cwd?, timeout?) — Read-only commands only (grep, ls, git log). \
 Never use this to write files, run scripts, or modify the filesystem — transition \
 to BUILDING phase for that.
-- list_agent_tools(server_config_path?, output_schema?, group?) \
-— Discover available tools for design
+- list_agent_tools(server_config_path?, output_schema?, group?, credentials?) \
+— Discover available tools for design (summary → names → full)
 - list_agents() — See existing agent packages for reference
 - list_agent_sessions(agent_name, status?, limit?) — Inspect past runs of an agent
 - list_agent_checkpoints(agent_name, session_id) — View execution history
 - get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — Load a checkpoint
-- initialize_and_build_agent(agent_name?, nodes?) — With agent_name: scaffold a \
-new agent and transition to BUILDING phase. Without agent_name: transition to \
-BUILDING to fix the currently loaded agent (requires a loaded worker).
+
+## Draft Graph Workflow (new agents)
+- save_agent_draft(agent_name, goal, nodes, edges?, terminal_nodes?, ...) — \
+Create an ISO 5807 color-coded flowchart draft. No code is generated. Each \
+node is auto-classified into a standard flowchart symbol (process, decision, \
+document, database, subprocess, etc.) with unique shapes and colors. Set \
+flowchart_type on a node to override. Nodes need only an id. \
+Use decision nodes (flowchart_type: "decision", with decision_clause and \
+labeled yes/no edges) to make conditional branching explicit. \
+Use subagent nodes (flowchart_type: "subagent") as leaf nodes connected \
+to a parent to show sub-agent delegation visually.
+- confirm_and_build() — Record user confirmation of the draft. Dissolves \
+planning-only nodes (decision → predecessor criteria; subagent → predecessor \
+sub_agents list). Call this ONLY after the user explicitly approves via ask_user.
+- initialize_and_build_agent(agent_name?, nodes?) — Scaffold the agent package \
+and transition to BUILDING phase. For new agents, this REQUIRES \
+save_agent_draft() + confirm_and_build() first. The draft metadata is used to \
+pre-populate the generated files. Without agent_name: transition to BUILDING \
+to fix the currently loaded agent (no draft required).
+
+## Loading existing agents
 - load_built_agent(agent_path) — Load an existing agent and switch to STAGING \
 phase. Only use this when the user explicitly asks to work with an existing agent \
 (e.g. "load my_agent", "run the research agent"). Confirm with the user first.
 
-Focus on understanding requirements and proposing an agent architecture \
-with ASCII graph art. Use ask_user to get user approval, then call \
-initialize_and_build_agent to begin building. If the user wants to work with \
-an existing agent instead, use load_built_agent after confirming. \
-If you are diagnosing an existing agent, call initialize_and_build_agent() \
+## Workflow summary
+1. Understand requirements → discover tools → design graph
+2. Call save_agent_draft() to create visual draft → present to user
+3. Call ask_user() to get explicit approval
+4. Call confirm_and_build() to record approval
+5. Call initialize_and_build_agent() to scaffold and start building
+For diagnosis of existing agents, call initialize_and_build_agent() \
 (no args) after agreeing on a fix plan with the user.
 """
 
@@ -583,6 +772,14 @@ list_agents, list_agent_sessions, \
 list_agent_checkpoints, get_agent_checkpoint
 - load_built_agent(agent_path) — Load the agent and switch to STAGING phase
 - list_credentials(credential_id?) — List authorized credentials
+- save_agent_draft(...) — **Re-draft the flowchart during building.** When \
+called during building, planning-only nodes (decision, subagent) are \
+dissolved automatically — no re-confirmation needed. The user sees the \
+updated flowchart immediately. Use this when you make structural changes \
+(add/remove nodes, change edges) so the flowchart stays in sync.
+- replan_agent() — Switch back to PLANNING phase. The previous draft is \
+restored (with decision/subagent nodes intact) so you can edit it. Use \
+when the user requests a major redesign that needs their approval.
 
 When you finish building an agent, call load_built_agent(path) to stage it.
 """
@@ -627,28 +824,44 @@ To just stop without modifying, call stop_worker().
 _queen_behavior_always = """
 # Behavior
 
-## CRITICAL RULE — ask_user tool
+## CRITICAL RULE — ask_user / ask_user_multiple
 
 Every response that ends with a question, a prompt, or expects user \
-input MUST finish with a call to ask_user(prompt, options). \
+input MUST finish with a call to ask_user or ask_user_multiple. \
 The system CANNOT detect that you are waiting for \
-input unless you call ask_user. You MUST call ask_user as the LAST \
+input unless you call one of these tools. You MUST call it as the LAST \
 action in your response.
 
 NEVER end a response with a question in text without calling ask_user. \
 NEVER rely on the user seeing your text and replying — call ask_user.
 
+**When you have 2+ questions**, use ask_user_multiple instead of ask_user. \
+This renders all questions at once so the user answers in one interaction \
+instead of going back and forth. ALWAYS prefer ask_user_multiple when \
+you need to clarify multiple things. \
+**IMPORTANT: When using ask_user_multiple, do NOT repeat the questions \
+in your text response.** The widget renders the questions with options — \
+duplicating them in text wastes the user's time and delays the widget \
+appearing. Keep your text to a brief context/intro sentence only.
+
 Always provide 2-4 short options that cover the most likely answers. \
 The user can always type a custom response.
 
-Examples:
+Examples (single question):
 - ask_user("What do you need?",
   ["Build a new agent", "Run the loaded worker", "Help with code"])
-- ask_user("Which pattern?",
-  ["Simple 3-node", "Rich with feedback", "Custom"])
 - ask_user("Ready to proceed?",
   ["Yes, go ahead", "Let me change something"])
 
+Example (multiple questions — ALWAYS use ask_user_multiple):
+- ask_user_multiple(questions=[
+    {"id": "goal", "prompt": "What should this agent do?"},
+    {"id": "tools", "prompt": "Which integrations?",
+     "options": ["Slack", "Gmail", "Google Sheets"]},
+    {"id": "schedule", "prompt": "How often should it run?",
+     "options": ["On demand", "Every hour", "Daily"]}
+  ])
+
 ## Greeting
 
 When the user greets you, respond concisely (under 10 lines) with worker \
@@ -690,9 +903,26 @@ You are in planning mode. Your job is to:
 3. Discover available tools with list_agent_tools()
 4. Assess framework fit and gaps
 5. Consider multiple approaches and their trade-offs
-6. Design the agent graph and present it as ASCII art
-7. Use ask_user to get explicit user approval and clarify the approach
-8. Call initialize_and_build_agent(agent_name, nodes) to scaffold and start building
+6. Design the agent graph — call save_agent_draft() **as soon as you have a \
+rough shape**, even before finalizing all details
+7. **Iterate on the draft interactively** — every time the user gives feedback \
+that changes the structure, call save_agent_draft() again so they see the \
+update in real-time. The flowchart is a live collaboration tool.
+8. When the design is stable, use ask_user to get explicit approval
+9. Call confirm_and_build() after the user approves
+10. Call initialize_and_build_agent(agent_name, nodes) to scaffold and start building
+
+**The flowchart is your shared whiteboard.** Don't describe changes in text \
+and then ask "should I update the draft?" — just update it. If the user says \
+"add a validation step," immediately call save_agent_draft() with the new \
+node added. If they say "remove that," update and re-draft. The user should \
+see every structural change reflected in the visualizer as you discuss it.
+
+**CRITICAL: Planning → Building boundary.** You MUST get explicit user \
+confirmation before moving to building. The sequence is:
+  save_agent_draft() → iterate with user → ask_user() → confirm_and_build() → \
+  initialize_and_build_agent()
+Skipping any of these steps will be blocked by the system.
 
 Remember: DO NOT write or edit any files yet. This is a read-only exploration \
 and planning phase. You have read-only tools but no write/edit tools in this \
@@ -745,6 +975,21 @@ run_agent_with_input(task) (if in staging) or load then run (if in building)
 subtasks to justify delegation.
 - Building, modifying, or configuring agents is ALWAYS your job. Never \
 delegate agent construction to the worker, even as a "research" subtask.
+
+## Keeping the flowchart in sync during building
+
+When you make structural changes to the agent (add/remove/rename nodes, \
+change edges, modify sub-agent assignments), call save_agent_draft() to \
+update the flowchart. During building, this auto-dissolves planning-only \
+nodes without needing user re-confirmation. The user sees the updated \
+flowchart immediately.
+
+- **Minor changes** (add a node, rename, adjust edges): call \
+save_agent_draft() with the updated graph and keep building.
+- **Major redesign** (user requests fundamental restructuring): call \
+replan_agent() to go back to planning. The previous draft is restored \
+so you can edit it with the user rather than starting from scratch. \
+After they approve, confirm_and_build() → continue building.
 """
 
 # -- STAGING phase behavior --
@@ -931,8 +1176,10 @@ _queen_tools_docs = (
     + "\n\n### RUNNING phase (worker is executing)\n"
     + _queen_tools_running.strip()
     + "\n\n### Phase transitions\n"
-    "- initialize_and_build_agent(agent_name?, nodes?) → with name: scaffolds package; "
-    "without name: switches to BUILDING for existing agent\n"
+    "- save_agent_draft(...) → creates visual-only draft graph (stays in PLANNING)\n"
+    "- confirm_and_build() → records user approval of draft (stays in PLANNING)\n"
+    "- initialize_and_build_agent(agent_name?, nodes?) → scaffolds package + switches to "
+    "BUILDING (requires draft + confirmation for new agents)\n"
     "- replan_agent() → switches back to PLANNING phase (only when user explicitly requests)\n"
     "- load_built_agent(path) → switches to STAGING phase\n"
     "- run_agent_with_input(task) → starts worker, switches to RUNNING phase\n"

core/framework/agents/queen/reference/file_templates.md

@@ -180,7 +180,7 @@ terminal_nodes = []  # Forever-alive
 # Module-level vars read by AgentRunner.load()
 conversation_mode = "continuous"
 identity_prompt = "You are a helpful agent."
-loop_config = {"max_iterations": 100, "max_tool_calls_per_turn": 20, "max_history_tokens": 32000}
+loop_config = {"max_iterations": 100, "max_tool_calls_per_turn": 20, "max_context_tokens": 32000}
 
 
 class MyAgent:

core/framework/agents/queen/reference/framework_guide.md

@@ -226,7 +226,7 @@ Only three valid keys:
 loop_config = {
     "max_iterations": 100,          # Max LLM turns per node visit
     "max_tool_calls_per_turn": 20,  # Max tool calls per LLM response
-    "max_history_tokens": 32000,    # Triggers conversation compaction
+    "max_context_tokens": 32000,    # Triggers conversation compaction
 }
 ```
 **INVALID keys** (do NOT use): `"strategy"`, `"mode"`, `"timeout"`,

core/framework/config.py

@@ -56,6 +56,14 @@ def get_max_tokens() -> int:
     return get_hive_config().get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)
 
 
+DEFAULT_MAX_CONTEXT_TOKENS = 32_000
+
+
+def get_max_context_tokens() -> int:
+    """Return the configured max_context_tokens, falling back to DEFAULT_MAX_CONTEXT_TOKENS."""
+    return get_hive_config().get("llm", {}).get("max_context_tokens", DEFAULT_MAX_CONTEXT_TOKENS)
+
+
 def get_api_key() -> str | None:
     """Return the API key, supporting env var, Claude Code subscription, Codex, and ZAI Code.
 
@@ -178,6 +186,7 @@ class RuntimeConfig:
     model: str = field(default_factory=get_preferred_model)
     temperature: float = 0.7
     max_tokens: int = field(default_factory=get_max_tokens)
+    max_context_tokens: int = field(default_factory=get_max_context_tokens)
     api_key: str | None = field(default_factory=get_api_key)
     api_base: str | None = field(default_factory=get_api_base)
     extra_kwargs: dict[str, Any] = field(default_factory=get_llm_extra_kwargs)

core/framework/credentials/key_storage.py

@@ -149,8 +149,14 @@ def delete_aden_api_key() -> None:
 
         storage = EncryptedFileStorage()
         storage.delete(ADEN_CREDENTIAL_ID)
+    except (FileNotFoundError, PermissionError) as e:
+        logger.debug("Could not delete %s from encrypted store: %s", ADEN_CREDENTIAL_ID, e)
     except Exception:
-        logger.debug("Could not delete %s from encrypted store", ADEN_CREDENTIAL_ID)
+        logger.warning(
+            "Unexpected error deleting %s from encrypted store",
+            ADEN_CREDENTIAL_ID,
+            exc_info=True,
+        )
 
     os.environ.pop(ADEN_ENV_VAR, None)
 
@@ -167,8 +173,10 @@ def _read_credential_key_file() -> str | None:
             value = CREDENTIAL_KEY_PATH.read_text(encoding="utf-8").strip()
             if value:
                 return value
+    except (FileNotFoundError, PermissionError) as e:
+        logger.debug("Could not read %s: %s", CREDENTIAL_KEY_PATH, e)
     except Exception:
-        logger.debug("Could not read %s", CREDENTIAL_KEY_PATH)
+        logger.warning("Unexpected error reading %s", CREDENTIAL_KEY_PATH, exc_info=True)
     return None
 
 
@@ -196,6 +204,12 @@ def _read_aden_from_encrypted_store() -> str | None:
         cred = storage.load(ADEN_CREDENTIAL_ID)
         if cred:
             return cred.get_key("api_key")
+    except (FileNotFoundError, PermissionError, KeyError) as e:
+        logger.debug("Could not load %s from encrypted store: %s", ADEN_CREDENTIAL_ID, e)
     except Exception:
-        logger.debug("Could not load %s from encrypted store", ADEN_CREDENTIAL_ID)
+        logger.warning(
+            "Unexpected error loading %s from encrypted store",
+            ADEN_CREDENTIAL_ID,
+            exc_info=True,
+        )
     return None

core/framework/graph/conversation.py

@@ -307,13 +307,13 @@ class NodeConversation:
     def __init__(
         self,
         system_prompt: str = "",
-        max_history_tokens: int = 32000,
+        max_context_tokens: int = 32000,
         compaction_threshold: float = 0.8,
         output_keys: list[str] | None = None,
         store: ConversationStore | None = None,
     ) -> None:
         self._system_prompt = system_prompt
-        self._max_history_tokens = max_history_tokens
+        self._max_context_tokens = max_context_tokens
         self._compaction_threshold = compaction_threshold
         self._output_keys = output_keys
         self._store = store
@@ -525,16 +525,16 @@ class NodeConversation:
         self._last_api_input_tokens = actual_input_tokens
 
     def usage_ratio(self) -> float:
-        """Current token usage as a fraction of *max_history_tokens*.
+        """Current token usage as a fraction of *max_context_tokens*.
 
-        Returns 0.0 when ``max_history_tokens`` is zero (unlimited).
+        Returns 0.0 when ``max_context_tokens`` is zero (unlimited).
         """
-        if self._max_history_tokens <= 0:
+        if self._max_context_tokens <= 0:
             return 0.0
-        return self.estimate_tokens() / self._max_history_tokens
+        return self.estimate_tokens() / self._max_context_tokens
 
     def needs_compaction(self) -> bool:
-        return self.estimate_tokens() >= self._max_history_tokens * self._compaction_threshold
+        return self.estimate_tokens() >= self._max_context_tokens * self._compaction_threshold
 
     # --- Output-key extraction ---------------------------------------------
 
@@ -1029,7 +1029,7 @@ class NodeConversation:
         await self._store.write_meta(
             {
                 "system_prompt": self._system_prompt,
-                "max_history_tokens": self._max_history_tokens,
+                "max_context_tokens": self._max_context_tokens,
                 "compaction_threshold": self._compaction_threshold,
                 "output_keys": self._output_keys,
             }
@@ -1062,7 +1062,7 @@ class NodeConversation:
 
         conv = cls(
             system_prompt=meta.get("system_prompt", ""),
-            max_history_tokens=meta.get("max_history_tokens", 32000),
+            max_context_tokens=meta.get("max_context_tokens", 32000),
             compaction_threshold=meta.get("compaction_threshold", 0.8),
             output_keys=meta.get("output_keys"),
             store=store,

core/framework/graph/conversation_judge.py

@@ -37,7 +37,7 @@ async def evaluate_phase_completion(
     phase_description: str,
     success_criteria: str,
     accumulator_state: dict[str, Any],
-    max_history_tokens: int = 8_196,
+    max_context_tokens: int = 8_196,
 ) -> PhaseVerdict:
     """Level 2 judge: read the conversation and evaluate quality.
 
@@ -50,7 +50,7 @@ async def evaluate_phase_completion(
         phase_description: Description of the phase
         success_criteria: Natural-language criteria for phase completion
         accumulator_state: Current output key values
-        max_history_tokens: Main conversation token budget (judge gets 20%)
+        max_context_tokens: Main conversation token budget (judge gets 20%)
 
     Returns:
         PhaseVerdict with action and optional feedback
@@ -89,7 +89,7 @@ FEEDBACK: (reason if RETRY, empty if ACCEPT)"""
         response = await llm.acomplete(
             messages=[{"role": "user", "content": user_prompt}],
             system=system_prompt,
-            max_tokens=max(1024, max_history_tokens // 5),
+            max_tokens=max(1024, max_context_tokens // 5),
             max_retries=1,
         )
         if not response.content or not response.content.strip():

core/framework/graph/event_loop_node.py

@@ -170,7 +170,7 @@ class LoopConfig:
     judge_every_n_turns: int = 1
     stall_detection_threshold: int = 3
     stall_similarity_threshold: float = 0.85
-    max_history_tokens: int = 32_000
+    max_context_tokens: int = 32_000
     store_prefix: str = ""
 
     # Overflow margin for max_tool_calls_per_turn.  Tool calls are only
@@ -512,7 +512,7 @@ class EventLoopNode(NodeProtocol):
 
                 conversation = NodeConversation(
                     system_prompt=system_prompt,
-                    max_history_tokens=self._config.max_history_tokens,
+                    max_context_tokens=self._config.max_context_tokens,
                     output_keys=ctx.node_spec.output_keys or None,
                     store=self._conversation_store,
                 )
@@ -549,6 +549,8 @@ class EventLoopNode(NodeProtocol):
             tools.append(set_output_tool)
         if ctx.node_spec.client_facing and not ctx.event_triggered:
             tools.append(self._build_ask_user_tool())
+            if stream_id == "queen":
+                tools.append(self._build_ask_user_multiple_tool())
         # Workers/subagents can escalate blockers to the queen.
         if stream_id not in ("queen", "judge"):
             tools.append(self._build_escalate_tool())
@@ -635,6 +637,7 @@ class EventLoopNode(NodeProtocol):
                 _synthetic_names = {
                     "set_output",
                     "ask_user",
+                    "ask_user_multiple",
                     "escalate",
                     "delegate_to_sub_agent",
                     "report_to_parent",
@@ -712,6 +715,7 @@ class EventLoopNode(NodeProtocol):
                         model=turn_tokens.get("model", ""),
                         input_tokens=turn_tokens.get("input", 0),
                         output_tokens=turn_tokens.get("output", 0),
+                        cached_tokens=turn_tokens.get("cached", 0),
                         execution_id=execution_id,
                         iteration=iteration,
                     )
@@ -1058,7 +1062,9 @@ class EventLoopNode(NodeProtocol):
             mcp_tool_calls = [
                 tc
                 for tc in logged_tool_calls
-                if tc.get("tool_name") not in ("set_output", "ask_user", "escalate")
+                if tc.get("tool_name") not in (
+                    "set_output", "ask_user", "ask_user_multiple", "escalate",
+                )
             ]
             if mcp_tool_calls:
                 fps = self._fingerprint_tool_calls(mcp_tool_calls)
@@ -1252,8 +1258,12 @@ class EventLoopNode(NodeProtocol):
                     iteration,
                     _cf_auto,
                 )
+                # Check for multi-question batch from ask_user_multiple
+                multi_qs = getattr(self, "_pending_multi_questions", None)
+                self._pending_multi_questions = None
                 got_input = await self._await_user_input(
-                    ctx, prompt=_cf_prompt, options=ask_user_options
+                    ctx, prompt=_cf_prompt, options=ask_user_options,
+                    questions=multi_qs,
                 )
                 logger.info("[%s] iter=%d: unblocked, got_input=%s", node_id, iteration, got_input)
                 if not got_input:
@@ -1736,6 +1746,7 @@ class EventLoopNode(NodeProtocol):
         prompt: str = "",
         *,
         options: list[str] | None = None,
+        questions: list[dict] | None = None,
         emit_client_request: bool = True,
     ) -> bool:
         """Block until user input arrives or shutdown is signaled.
@@ -1750,6 +1761,8 @@ class EventLoopNode(NodeProtocol):
             options: Optional predefined choices for the user (from ask_user).
                 Passed through to the CLIENT_INPUT_REQUESTED event so the
                 frontend can render a QuestionWidget with buttons.
+            questions: Optional list of question dicts for ask_user_multiple.
+                Each dict has id, prompt, and optional options.
             emit_client_request: When False, wait silently without publishing
                 CLIENT_INPUT_REQUESTED. Used for worker waits where input is
                 expected from the queen via inject_worker_message().
@@ -1774,6 +1787,7 @@ class EventLoopNode(NodeProtocol):
                 prompt=prompt,
                 execution_id=ctx.execution_id or "",
                 options=options,
+                questions=questions,
             )
 
         self._awaiting_input = True
@@ -1833,7 +1847,7 @@ class EventLoopNode(NodeProtocol):
         stream_id = ctx.stream_id or ctx.node_id
         node_id = ctx.node_id
         execution_id = ctx.execution_id or ""
-        token_counts: dict[str, int] = {"input": 0, "output": 0}
+        token_counts: dict[str, int] = {"input": 0, "output": 0, "cached": 0}
         tool_call_count = 0
         final_text = ""
         final_system_prompt = conversation.system_prompt
@@ -1914,6 +1928,7 @@ class EventLoopNode(NodeProtocol):
                     elif isinstance(event, FinishEvent):
                         token_counts["input"] += event.input_tokens
                         token_counts["output"] += event.output_tokens
+                        token_counts["cached"] += event.cached_tokens
                         token_counts["stop_reason"] = event.stop_reason
                         token_counts["model"] = event.model
 
@@ -2142,6 +2157,59 @@ class EventLoopNode(NodeProtocol):
                     )
                     results_by_id[tc.tool_use_id] = result
 
+                elif tc.tool_name == "ask_user_multiple":
+                    # --- Framework-level ask_user_multiple ---
+                    user_input_requested = True
+                    raw_questions = tc.tool_input.get("questions", [])
+                    if not isinstance(raw_questions, list) or len(raw_questions) < 2:
+                        result = ToolResult(
+                            tool_use_id=tc.tool_use_id,
+                            content=(
+                                "ERROR: questions must be an array of at "
+                                "least 2 question objects. Use ask_user "
+                                "for single questions."
+                            ),
+                            is_error=True,
+                        )
+                        results_by_id[tc.tool_use_id] = result
+                        user_input_requested = False
+                        continue
+
+                    # Normalize each question entry
+                    questions: list[dict] = []
+                    for i, q in enumerate(raw_questions):
+                        if not isinstance(q, dict):
+                            continue
+                        qid = str(q.get("id", f"q{i+1}"))
+                        prompt = str(q.get("prompt", ""))
+                        opts = q.get("options", None)
+                        if isinstance(opts, list):
+                            opts = [str(o) for o in opts if o]
+                            if len(opts) < 2:
+                                opts = None
+                        else:
+                            opts = None
+                        questions.append({
+                            "id": qid,
+                            "prompt": prompt,
+                            **({"options": opts} if opts else {}),
+                        })
+
+                    # Store as multi-question prompt/options for
+                    # the event emission path
+                    ask_user_prompt = ""
+                    ask_user_options = None
+                    # Pass the full questions list via a special
+                    # key that the event emitter picks up
+                    self._pending_multi_questions = questions
+
+                    result = ToolResult(
+                        tool_use_id=tc.tool_use_id,
+                        content="Waiting for user input...",
+                        is_error=False,
+                    )
+                    results_by_id[tc.tool_use_id] = result
+
                 elif tc.tool_name == "escalate":
                     # --- Framework-level escalate handling ---
                     reason = str(tc.tool_input.get("reason", "")).strip()
@@ -2388,6 +2456,7 @@ class EventLoopNode(NodeProtocol):
                 if tc.tool_name not in (
                     "set_output",
                     "ask_user",
+                    "ask_user_multiple",
                     "escalate",
                     "delegate_to_sub_agent",
                     "report_to_parent",
@@ -2457,7 +2526,7 @@ class EventLoopNode(NodeProtocol):
                 # next turn.  The char-based token estimator underestimates
                 # actual API tokens, so the standard compaction check in the
                 # outer loop may not trigger in time.
-                protect = max(2000, self._config.max_history_tokens // 12)
+                protect = max(2000, self._config.max_context_tokens // 12)
                 pruned = await conversation.prune_old_tool_results(
                     protect_tokens=protect,
                     min_prune_tokens=max(1000, protect // 3),
@@ -2466,7 +2535,7 @@ class EventLoopNode(NodeProtocol):
                     logger.info(
                         "Post-limit pruning: cleared %d old tool results (budget: %d)",
                         pruned,
-                        self._config.max_history_tokens,
+                        self._config.max_context_tokens,
                     )
                 # Limit hit — return from this turn so the judge can
                 # evaluate instead of looping back for another stream.
@@ -2487,7 +2556,7 @@ class EventLoopNode(NodeProtocol):
 
             # --- Mid-turn pruning: prevent context blowup within a single turn ---
             if conversation.usage_ratio() >= 0.6:
-                protect = max(2000, self._config.max_history_tokens // 12)
+                protect = max(2000, self._config.max_context_tokens // 12)
                 pruned = await conversation.prune_old_tool_results(
                     protect_tokens=protect,
                     min_prune_tokens=max(1000, protect // 3),
@@ -2580,6 +2649,73 @@ class EventLoopNode(NodeProtocol):
             },
         )
 
+    def _build_ask_user_multiple_tool(self) -> Tool:
+        """Build the synthetic ask_user_multiple tool for batched questions.
+
+        Queen-only tool that presents multiple questions at once so the user
+        can answer them all in a single interaction rather than one at a time.
+        """
+        return Tool(
+            name="ask_user_multiple",
+            description=(
+                "Ask the user multiple questions at once. Use this instead of "
+                "ask_user when you have 2 or more questions to ask in the same "
+                "turn — it lets the user answer everything in one go rather than "
+                "going back and forth. Each question can have its own predefined "
+                "options (2-3 choices) or be free-form. The UI renders all "
+                "questions together with a single Submit button. "
+                "ALWAYS prefer this over ask_user when you have multiple things "
+                "to clarify. "
+                "IMPORTANT: Do NOT repeat the questions in your text response — "
+                "the widget renders them. Keep your text to a brief intro only. "
+                'Example: {"questions": ['
+                '  {"id": "scope", "prompt": "What scope?", "options": ["Full", "Partial"]},'
+                '  {"id": "format", "prompt": "Output format?", "options": ["PDF", "CSV", "JSON"]},'
+                '  {"id": "details", "prompt": "Any special requirements?"}'
+                "]}"
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "questions": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "type": "string",
+                                    "description": (
+                                        "Short identifier for this question "
+                                        "(used in the response)."
+                                    ),
+                                },
+                                "prompt": {
+                                    "type": "string",
+                                    "description": "The question text shown to the user.",
+                                },
+                                "options": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": (
+                                        "2-3 predefined choices. The UI appends an "
+                                        "'Other' free-text input automatically. "
+                                        "Omit only when the user must type a free-form answer."
+                                    ),
+                                    "minItems": 2,
+                                    "maxItems": 3,
+                                },
+                            },
+                            "required": ["id", "prompt"],
+                        },
+                        "minItems": 2,
+                        "maxItems": 8,
+                        "description": "List of questions to present to the user.",
+                    },
+                },
+                "required": ["questions"],
+            },
+        )
+
     def _build_set_output_tool(self, output_keys: list[str] | None) -> Tool | None:
         """Build the synthetic set_output tool for explicit output declaration."""
         if not output_keys:
@@ -2914,7 +3050,7 @@ class EventLoopNode(NodeProtocol):
                 phase_description=ctx.node_spec.description,
                 success_criteria=ctx.node_spec.success_criteria,
                 accumulator_state=accumulator.to_dict(),
-                max_history_tokens=self._config.max_history_tokens,
+                max_context_tokens=self._config.max_context_tokens,
             )
             if verdict.action != "ACCEPT":
                 return JudgeVerdict(
@@ -3354,7 +3490,7 @@ class EventLoopNode(NodeProtocol):
         phase_grad = getattr(ctx, "continuous_mode", False)
 
         # --- Step 1: Prune old tool results (free, no LLM) ---
-        protect = max(2000, self._config.max_history_tokens // 12)
+        protect = max(2000, self._config.max_context_tokens // 12)
         pruned = await conversation.prune_old_tool_results(
             protect_tokens=protect,
             min_prune_tokens=max(1000, protect // 3),
@@ -3460,7 +3596,7 @@ class EventLoopNode(NodeProtocol):
                 accumulator,
                 formatted,
             )
-            summary_budget = max(1024, self._config.max_history_tokens // 2)
+            summary_budget = max(1024, self._config.max_context_tokens // 2)
             try:
                 response = await ctx.llm.acomplete(
                     messages=[{"role": "user", "content": prompt}],
@@ -3563,7 +3699,7 @@ class EventLoopNode(NodeProtocol):
         elif spec.output_keys:
             ctx_lines.append(f"OUTPUTS STILL NEEDED: {', '.join(spec.output_keys)}")
 
-        target_tokens = self._config.max_history_tokens // 2
+        target_tokens = self._config.max_context_tokens // 2
         target_chars = target_tokens * 4
         node_ctx = "\n".join(ctx_lines)
 
@@ -4031,6 +4167,7 @@ class EventLoopNode(NodeProtocol):
         model: str,
         input_tokens: int,
         output_tokens: int,
+        cached_tokens: int = 0,
         execution_id: str = "",
         iteration: int | None = None,
     ) -> None:
@@ -4042,6 +4179,7 @@ class EventLoopNode(NodeProtocol):
                 model=model,
                 input_tokens=input_tokens,
                 output_tokens=output_tokens,
+                cached_tokens=cached_tokens,
                 execution_id=execution_id,
                 iteration=iteration,
             )
@@ -4442,7 +4580,7 @@ class EventLoopNode(NodeProtocol):
                 max_iterations=max_iter,  # Tighter budget
                 max_tool_calls_per_turn=self._config.max_tool_calls_per_turn,
                 tool_call_overflow_margin=self._config.tool_call_overflow_margin,
-                max_history_tokens=self._config.max_history_tokens,
+                max_context_tokens=self._config.max_context_tokens,
                 stall_detection_threshold=self._config.stall_detection_threshold,
                 max_tool_result_chars=self._config.max_tool_result_chars,
                 spillover_dir=subagent_spillover,

core/framework/graph/executor.py

@@ -330,7 +330,7 @@ class GraphExecutor:
                 _depth,
             )
         else:
-            max_tokens = getattr(conversation, "_max_history_tokens", 32000)
+            max_tokens = getattr(conversation, "_max_context_tokens", 32000)
             target_tokens = max_tokens // 2
             target_chars = target_tokens * 4
 
@@ -1872,7 +1872,7 @@ class GraphExecutor:
                     max_tool_calls_per_turn=lc.get("max_tool_calls_per_turn", 30),
                     tool_call_overflow_margin=lc.get("tool_call_overflow_margin", 0.5),
                     stall_detection_threshold=lc.get("stall_detection_threshold", 3),
-                    max_history_tokens=lc.get("max_history_tokens", 32000),
+                    max_context_tokens=lc.get("max_context_tokens", 32000),
                     max_tool_result_chars=lc.get("max_tool_result_chars", 30_000),
                     spillover_dir=spillover,
                     hooks=lc.get("hooks", {}),

core/framework/llm/litellm.py

@@ -118,6 +118,15 @@ RATE_LIMIT_MAX_RETRIES = 10
 RATE_LIMIT_BACKOFF_BASE = 2  # seconds
 RATE_LIMIT_MAX_DELAY = 120  # seconds - cap to prevent absurd waits
 MINIMAX_API_BASE = "https://api.minimax.io/v1"
+
+# Providers that accept cache_control on message content blocks.
+# Anthropic: native ephemeral caching. MiniMax & Z-AI/GLM: pass-through to their APIs.
+# (OpenAI caches automatically server-side; Groq/Gemini/etc. strip the header.)
+_CACHE_CONTROL_PREFIXES = ("anthropic/", "claude-", "minimax/", "minimax-", "MiniMax-", "zai-glm", "glm-")
+
+
+def _model_supports_cache_control(model: str) -> bool:
+    return any(model.startswith(p) for p in _CACHE_CONTROL_PREFIXES)
 # Kimi For Coding uses an Anthropic-compatible endpoint (no /v1 suffix).
 # Claude Code integration uses this format; the /v1 OpenAI-compatible endpoint
 # enforces a coding-agent whitelist that blocks unknown User-Agents.
@@ -707,7 +716,10 @@ class LiteLLMProvider(LLMProvider):
 
         full_messages: list[dict[str, Any]] = []
         if system:
-            full_messages.append({"role": "system", "content": system})
+            sys_msg: dict[str, Any] = {"role": "system", "content": system}
+            if _model_supports_cache_control(self.model):
+                sys_msg["cache_control"] = {"type": "ephemeral"}
+            full_messages.append(sys_msg)
         full_messages.extend(messages)
 
         if json_mode:
@@ -878,7 +890,10 @@ class LiteLLMProvider(LLMProvider):
 
         full_messages: list[dict[str, Any]] = []
         if system:
-            full_messages.append({"role": "system", "content": system})
+            sys_msg: dict[str, Any] = {"role": "system", "content": system}
+            if _model_supports_cache_control(self.model):
+                sys_msg["cache_control"] = {"type": "ephemeral"}
+            full_messages.append(sys_msg)
         full_messages.extend(messages)
 
         # Codex Responses API requires an `instructions` field (system prompt).
@@ -943,9 +958,26 @@ class LiteLLMProvider(LLMProvider):
                 response = await litellm.acompletion(**kwargs)  # type: ignore[union-attr]
 
                 async for chunk in response:
-                    choice = chunk.choices[0] if chunk.choices else None
-                    if not choice:
+                    # Capture usage from the trailing usage-only chunk that
+                    # stream_options={"include_usage": True} sends with empty choices.
+                    if not chunk.choices:
+                        usage = getattr(chunk, "usage", None)
+                        if usage:
+                            input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+                            output_tokens = getattr(usage, "completion_tokens", 0) or 0
+                            logger.debug(
+                                "[tokens] trailing usage chunk: input=%d output=%d model=%s",
+                                input_tokens,
+                                output_tokens,
+                                self.model,
+                            )
+                        else:
+                            logger.debug(
+                                "[tokens] empty-choices chunk with no usage (model=%s)",
+                                self.model,
+                            )
                         continue
+                    choice = chunk.choices[0]
 
                     delta = choice.delta
 
@@ -1018,19 +1050,90 @@ class LiteLLMProvider(LLMProvider):
                             tail_events.append(TextEndEvent(full_text=accumulated_text))
 
                         usage = getattr(chunk, "usage", None)
+                        logger.debug(
+                            "[tokens] finish-chunk raw usage: %r (type=%s)",
+                            usage,
+                            type(usage).__name__,
+                        )
+                        cached_tokens = 0
                         if usage:
                             input_tokens = getattr(usage, "prompt_tokens", 0) or 0
                             output_tokens = getattr(usage, "completion_tokens", 0) or 0
+                            _details = getattr(usage, "prompt_tokens_details", None)
+                            cached_tokens = (
+                                getattr(_details, "cached_tokens", 0) or 0
+                                if _details is not None
+                                else getattr(usage, "cache_read_input_tokens", 0) or 0
+                            )
+                            logger.debug(
+                                "[tokens] finish-chunk usage: input=%d output=%d cached=%d model=%s",
+                                input_tokens,
+                                output_tokens,
+                                cached_tokens,
+                                self.model,
+                            )
 
+                        logger.debug(
+                            "[tokens] finish event: input=%d output=%d cached=%d stop=%s model=%s",
+                            input_tokens,
+                            output_tokens,
+                            cached_tokens,
+                            choice.finish_reason,
+                            self.model,
+                        )
                         tail_events.append(
                             FinishEvent(
                                 stop_reason=choice.finish_reason,
                                 input_tokens=input_tokens,
                                 output_tokens=output_tokens,
+                                cached_tokens=cached_tokens,
                                 model=self.model,
                             )
                         )
 
+                # Fallback: LiteLLM strips usage from yielded chunks before
+                # returning them to us, but appends the original chunk (with
+                # usage intact) to response.chunks first.  Use LiteLLM's own
+                # calculate_total_usage() on that accumulated list.
+                if input_tokens == 0 and output_tokens == 0:
+                    try:
+                        from litellm.litellm_core_utils.streaming_handler import (
+                            calculate_total_usage,
+                        )
+
+                        _chunks = getattr(response, "chunks", None)
+                        if _chunks:
+                            _usage = calculate_total_usage(chunks=_chunks)
+                            input_tokens = _usage.prompt_tokens or 0
+                            output_tokens = _usage.completion_tokens or 0
+                            _details = getattr(_usage, "prompt_tokens_details", None)
+                            cached_tokens = (
+                                getattr(_details, "cached_tokens", 0) or 0
+                                if _details is not None
+                                else getattr(_usage, "cache_read_input_tokens", 0) or 0
+                            )
+                            logger.debug(
+                                "[tokens] post-loop chunks fallback:"
+                                " input=%d output=%d cached=%d model=%s",
+                                input_tokens,
+                                output_tokens,
+                                cached_tokens,
+                                self.model,
+                            )
+                            # Patch the FinishEvent already queued with 0 tokens
+                            for _i, _ev in enumerate(tail_events):
+                                if isinstance(_ev, FinishEvent) and _ev.input_tokens == 0:
+                                    tail_events[_i] = FinishEvent(
+                                        stop_reason=_ev.stop_reason,
+                                        input_tokens=input_tokens,
+                                        output_tokens=output_tokens,
+                                        cached_tokens=cached_tokens,
+                                        model=_ev.model,
+                                    )
+                                    break
+                    except Exception as _e:
+                        logger.debug("[tokens] chunks fallback failed: %s", _e)
+
                 # Check whether the stream produced any real content.
                 # (If text deltas were yielded above, has_content is True
                 # and we skip the retry path — nothing was yielded in vain.)

core/framework/llm/stream_events.py

@@ -71,6 +71,7 @@ class FinishEvent:
     stop_reason: str = ""
     input_tokens: int = 0
     output_tokens: int = 0
+    cached_tokens: int = 0
     model: str = ""
 
 

core/framework/monitoring/judge.py

@@ -253,6 +253,6 @@ judge_graph = GraphSpec(
     loop_config={
         "max_iterations": 10,  # One check shouldn't take many turns
         "max_tool_calls_per_turn": 3,  # get_summary + optionally emit_ticket
-        "max_history_tokens": 16000,  # Compact — judge only needs recent context
+        "max_context_tokens": 16000,  # Compact — judge only needs recent context
     },
 )

core/framework/observability/logging.py

@@ -148,8 +148,9 @@ class HumanReadableFormatter(logging.Formatter):
         if record_event is not None:
             event = f" [{record_event}]"
 
-        # Format message: [LEVEL] [trace context] message
-        return f"{color}[{level}]{reset} {context_prefix}{record.getMessage()}{event}"
+        timestamp = self.formatTime(record, "%Y-%m-%d %H:%M:%S")
+        # Format message: TIMESTAMP [LEVEL] [trace context] message
+        return f"{timestamp} {color}[{level}]{reset} {context_prefix}{record.getMessage()}{event}"
 
 
 def configure_logging(

core/framework/runner/cli.py

@@ -243,6 +243,12 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
         action="store_true",
         help="Open dashboard in browser after server starts",
     )
+    serve_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Enable INFO log level"
+    )
+    serve_parser.add_argument(
+        "--debug", action="store_true", help="Enable DEBUG log level"
+    )
     serve_parser.set_defaults(func=cmd_serve)
 
     # open command (serve + auto-open browser)
@@ -280,6 +286,12 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
         default=None,
         help="LLM model for preloaded agents",
     )
+    open_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Enable INFO log level"
+    )
+    open_parser.add_argument(
+        "--debug", action="store_true", help="Enable DEBUG log level"
+    )
     open_parser.set_defaults(func=cmd_open)
 
 
@@ -380,13 +392,15 @@ def cmd_run(args: argparse.Namespace) -> int:
     from framework.credentials.models import CredentialError
     from framework.runner import AgentRunner
 
+    from framework.observability import configure_logging
+
     # Set logging level (quiet by default for cleaner output)
     if args.quiet:
-        logging.basicConfig(level=logging.ERROR, format="%(message)s")
+        configure_logging(level="ERROR")
     elif getattr(args, "verbose", False):
-        logging.basicConfig(level=logging.INFO, format="%(message)s")
+        configure_logging(level="INFO")
     else:
-        logging.basicConfig(level=logging.WARNING, format="%(message)s")
+        configure_logging(level="WARNING")
 
     # Load input context
     context = {}
@@ -742,6 +756,17 @@ def cmd_dispatch(args: argparse.Namespace) -> int:
     if args.agents:
         # Use specific agents
         for agent_name in args.agents:
+            # Guard against full paths: if the name contains path separators
+            # (e.g. "exports/my_agent"), it will be doubled with agents_dir
+            agent_name_path = Path(agent_name)
+            if len(agent_name_path.parts) > 1:
+                print(
+                    f"Error: --agents expects agent names, not paths. "
+                    f"Use: --agents {agent_name_path.name} "
+                    f"instead of --agents {agent_name}",
+                    file=sys.stderr,
+                )
+                return 1
             agent_path = agents_dir / agent_name
             if not _is_valid_agent_dir(agent_path):
                 print(f"Agent not found: {agent_path}", file=sys.stderr)
@@ -912,11 +937,9 @@ def cmd_shell(args: argparse.Namespace) -> int:
     from framework.credentials.models import CredentialError
     from framework.runner import AgentRunner
 
-    # Configure logging to show runtime visibility
-    logging.basicConfig(
-        level=logging.INFO,
-        format="%(message)s",  # Simple format for clean output
-    )
+    from framework.observability import configure_logging
+
+    configure_logging(level="INFO")
 
     agents_dir = Path(args.agents_dir)
 
@@ -1622,10 +1645,12 @@ def cmd_serve(args: argparse.Namespace) -> int:
 
     from framework.server.app import create_app
 
-    logging.basicConfig(
-        level=logging.INFO,
-        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-    )
+    from framework.observability import configure_logging
+
+    if getattr(args, "debug", False):
+        configure_logging(level="DEBUG")
+    else:
+        configure_logging(level="INFO")
 
     model = getattr(args, "model", None)
     app = create_app(model=model)

core/framework/runner/runner.py

@@ -9,7 +9,7 @@ from datetime import UTC
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from framework.config import get_hive_config, get_preferred_model
+from framework.config import get_hive_config, get_max_context_tokens, get_preferred_model
 from framework.credentials.validation import (
     ensure_credential_key_env as _ensure_credential_key_env,
 )
@@ -926,10 +926,31 @@ class AgentRunner:
 
             if agent_config and hasattr(agent_config, "max_tokens"):
                 max_tokens = agent_config.max_tokens
+                logger.info(
+                    "Agent default_config overrides max_tokens: %d (configuration.json value ignored)",
+                    max_tokens,
+                )
             else:
                 hive_config = get_hive_config()
                 max_tokens = hive_config.get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)
 
+            # Resolve max_context_tokens with priority:
+            #   1. agent loop_config["max_context_tokens"] (explicit, wins silently)
+            #   2. agent default_config.max_context_tokens (logged)
+            #   3. configuration.json llm.max_context_tokens
+            #   4. hardcoded default (32_000)
+            agent_loop_config: dict = dict(getattr(agent_module, "loop_config", {}))
+            if "max_context_tokens" not in agent_loop_config:
+                if agent_config and hasattr(agent_config, "max_context_tokens"):
+                    agent_loop_config["max_context_tokens"] = agent_config.max_context_tokens
+                    logger.info(
+                        "Agent default_config overrides max_context_tokens: %d"
+                        " (configuration.json value ignored)",
+                        agent_config.max_context_tokens,
+                    )
+                else:
+                    agent_loop_config["max_context_tokens"] = get_max_context_tokens()
+
             # Read intro_message from agent metadata (shown on TUI load)
             agent_metadata = getattr(agent_module, "metadata", None)
             intro_message = ""
@@ -949,7 +970,7 @@ class AgentRunner:
                 "nodes": nodes,
                 "edges": edges,
                 "max_tokens": max_tokens,
-                "loop_config": getattr(agent_module, "loop_config", {}),
+                "loop_config": agent_loop_config,
             }
             # Only pass optional fields if explicitly defined by the agent module
             conversation_mode = getattr(agent_module, "conversation_mode", None)

core/framework/runtime/event_bus.py

@@ -137,6 +137,12 @@ class EventType(StrEnum):
     WORKER_LOADED = "worker_loaded"
     CREDENTIALS_REQUIRED = "credentials_required"
 
+    # Draft graph (planning phase — lightweight graph preview)
+    DRAFT_GRAPH_UPDATED = "draft_graph_updated"
+
+    # Flowchart map updated (after reconciliation with runtime graph)
+    FLOWCHART_MAP_UPDATED = "flowchart_map_updated"
+
     # Queen phase changes (building <-> staging <-> running)
     QUEEN_PHASE_CHANGED = "queen_phase_changed"
 
@@ -616,6 +622,7 @@ class EventBus:
         model: str,
         input_tokens: int,
         output_tokens: int,
+        cached_tokens: int = 0,
         execution_id: str | None = None,
         iteration: int | None = None,
     ) -> None:
@@ -625,6 +632,7 @@ class EventBus:
             "model": model,
             "input_tokens": input_tokens,
             "output_tokens": output_tokens,
+            "cached_tokens": cached_tokens,
         }
         if iteration is not None:
             data["iteration"] = iteration
@@ -722,16 +730,23 @@ class EventBus:
         prompt: str = "",
         execution_id: str | None = None,
         options: list[str] | None = None,
+        questions: list[dict] | None = None,
     ) -> None:
         """Emit client input requested event (client_facing=True nodes).
 
         Args:
             options: Optional predefined choices for the user (1-3 items).
-                     The frontend appends an "Other" free-text option automatically.
+                     The frontend appends an "Other" free-text option
+                     automatically.
+            questions: Optional list of question dicts for multi-question
+                       batches (from ask_user_multiple). Each dict has id,
+                       prompt, and optional options.
         """
         data: dict[str, Any] = {"prompt": prompt}
         if options:
             data["options"] = options
+        if questions:
+            data["questions"] = questions
         await self.publish(
             AgentEvent(
                 type=EventType.CLIENT_INPUT_REQUESTED,

core/framework/server/routes_events.py

@@ -40,6 +40,7 @@ DEFAULT_EVENT_TYPES = [
     EventType.CREDENTIALS_REQUIRED,
     EventType.SUBAGENT_REPORT,
     EventType.QUEEN_PHASE_CHANGED,
+    EventType.DRAFT_GRAPH_UPDATED,
 ]
 
 # Keepalive interval in seconds

core/framework/server/routes_graphs.py

@@ -234,8 +234,69 @@ async def handle_node_tools(request: web.Request) -> web.Response:
     return web.json_response({"tools": tools_out})
 
 
+async def handle_draft_graph(request: web.Request) -> web.Response:
+    """Return the current draft graph from planning phase (if any)."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    phase_state = getattr(session, "phase_state", None)
+    if phase_state is None or phase_state.draft_graph is None:
+        return web.json_response({"draft": None})
+
+    return web.json_response({"draft": phase_state.draft_graph})
+
+
+async def handle_flowchart_map(request: web.Request) -> web.Response:
+    """Return the flowchart→runtime node mapping and the original (pre-dissolution) draft.
+
+    Available after confirm_and_build() dissolves decision nodes, or loaded
+    from the agent's flowchart.json file, or synthesized from the runtime graph.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    phase_state = getattr(session, "phase_state", None)
+
+    # Fast path: already in memory
+    if phase_state is not None and phase_state.original_draft_graph is not None:
+        return web.json_response({
+            "map": phase_state.flowchart_map,
+            "original_draft": phase_state.original_draft_graph,
+        })
+
+    # Try loading from flowchart.json in the agent folder
+    worker_path = getattr(session, "worker_path", None)
+    if worker_path is not None:
+        from pathlib import Path
+
+        target = Path(worker_path) / "flowchart.json"
+        if target.is_file():
+            try:
+                data = json.loads(target.read_text(encoding="utf-8"))
+                original_draft = data.get("original_draft")
+                fmap = data.get("flowchart_map")
+                # Cache in phase_state for future requests
+                if phase_state is not None and original_draft:
+                    phase_state.original_draft_graph = original_draft
+                    phase_state.flowchart_map = fmap
+                return web.json_response({
+                    "map": fmap,
+                    "original_draft": original_draft,
+                })
+            except Exception:
+                logger.warning("Failed to read flowchart.json from %s", worker_path)
+
+    return web.json_response({"map": None, "original_draft": None})
+
+
 def register_routes(app: web.Application) -> None:
     """Register graph/node inspection routes."""
+    # Draft graph (planning phase — visual only, no loaded worker required)
+    app.router.add_get("/api/sessions/{session_id}/draft-graph", handle_draft_graph)
+    # Flowchart map (post-dissolution — maps runtime nodes to original draft nodes)
+    app.router.add_get("/api/sessions/{session_id}/flowchart-map", handle_flowchart_map)
     # Session-primary routes
     app.router.add_get("/api/sessions/{session_id}/graphs/{graph_id}/nodes", handle_list_nodes)
     app.router.add_get(

core/frontend/src/api/graphs.ts

@@ -1,5 +1,5 @@
 import { api } from "./client";
-import type { GraphTopology, NodeDetail, NodeCriteria, ToolInfo } from "./types";
+import type { GraphTopology, NodeDetail, NodeCriteria, ToolInfo, DraftGraph, FlowchartMap } from "./types";
 
 export const graphsApi = {
   nodes: (sessionId: string, graphId: string, workerSessionId?: string) =>
@@ -26,4 +26,14 @@ export const graphsApi = {
     api.get<{ tools: ToolInfo[] }>(
       `/sessions/${sessionId}/graphs/${graphId}/nodes/${nodeId}/tools`,
     ),
+
+  draftGraph: (sessionId: string) =>
+    api.get<{ draft: DraftGraph | null }>(
+      `/sessions/${sessionId}/draft-graph`,
+    ),
+
+  flowchartMap: (sessionId: string) =>
+    api.get<FlowchartMap>(
+      `/sessions/${sessionId}/flowchart-map`,
+    ),
 };

core/frontend/src/api/types.ts

@@ -191,6 +191,56 @@ export interface GraphTopology {
   entry_points?: EntryPoint[];
 }
 
+// --- Draft graph types (planning phase) ---
+
+export interface DraftNode {
+  id: string;
+  name: string;
+  description: string;
+  node_type: string;
+  tools: string[];
+  input_keys: string[];
+  output_keys: string[];
+  success_criteria: string;
+  sub_agents: string[];
+  /** For decision nodes: the yes/no question evaluated during dissolution. */
+  decision_clause?: string;
+  flowchart_type: string;
+  flowchart_shape: string;
+  flowchart_color: string;
+}
+
+export interface DraftEdge {
+  id: string;
+  source: string;
+  target: string;
+  condition: string;
+  description: string;
+  /** Short label shown on the flowchart edge (e.g. "Yes", "No"). */
+  label?: string;
+}
+
+export interface DraftGraph {
+  agent_name: string;
+  goal: string;
+  description: string;
+  success_criteria: string[];
+  constraints: string[];
+  nodes: DraftNode[];
+  edges: DraftEdge[];
+  entry_node: string;
+  terminal_nodes: string[];
+  flowchart_legend: Record<string, { shape: string; color: string }>;
+}
+
+/** Mapping from runtime graph nodes → original flowchart draft nodes. */
+export interface FlowchartMap {
+  /** runtime_node_id → list of original draft node IDs it absorbed. */
+  map: Record<string, string[]> | null;
+  /** Original draft graph preserved before planning-node dissolution (decision + subagent). */
+  original_draft: DraftGraph | null;
+}
+
 export interface NodeCriteria {
   node_id: string;
   success_criteria: string | null;
@@ -276,7 +326,9 @@ export type EventTypeName =
   | "worker_loaded"
   | "credentials_required"
   | "queen_phase_changed"
-  | "subagent_report";
+  | "subagent_report"
+  | "draft_graph_updated"
+  | "flowchart_map_updated";
 
 export interface AgentEvent {
   type: EventTypeName;

core/frontend/src/components/ChatPanel.tsx

@@ -2,6 +2,7 @@ import { memo, useState, useRef, useEffect } from "react";
 import { Send, Square, Crown, Cpu, Check, Loader2 } from "lucide-react";
 import MarkdownContent from "@/components/MarkdownContent";
 import QuestionWidget from "@/components/QuestionWidget";
+import MultiQuestionWidget from "@/components/MultiQuestionWidget";
 
 export interface ChatMessage {
   id: string;
@@ -34,8 +35,12 @@ interface ChatPanelProps {
   pendingQuestion?: string | null;
   /** Options for the pending question */
   pendingOptions?: string[] | null;
+  /** Multiple questions from ask_user_multiple */
+  pendingQuestions?: { id: string; prompt: string; options?: string[] }[] | null;
   /** Called when user submits an answer to the pending question */
   onQuestionSubmit?: (answer: string, isOther: boolean) => void;
+  /** Called when user submits answers to multiple questions */
+  onMultiQuestionSubmit?: (answers: Record<string, string>) => void;
   /** Called when user dismisses the pending question without answering */
   onQuestionDismiss?: () => void;
   /** Queen operating phase — shown as a tag on queen messages */
@@ -222,7 +227,7 @@ const MessageBubble = memo(function MessageBubble({ msg, queenPhase }: { msg: Ch
   );
 }, (prev, next) => prev.msg.id === next.msg.id && prev.msg.content === next.msg.content && prev.queenPhase === next.queenPhase);
 
-export default function ChatPanel({ messages, onSend, isWaiting, isWorkerWaiting, isBusy, activeThread, disabled, onCancel, pendingQuestion, pendingOptions, onQuestionSubmit, onQuestionDismiss, queenPhase }: ChatPanelProps) {
+export default function ChatPanel({ messages, onSend, isWaiting, isWorkerWaiting, isBusy, activeThread, disabled, onCancel, pendingQuestion, pendingOptions, pendingQuestions, onQuestionSubmit, onMultiQuestionSubmit, onQuestionDismiss, queenPhase }: ChatPanelProps) {
   const [input, setInput] = useState("");
   const [readMap, setReadMap] = useState<Record<string, number>>({});
   const bottomRef = useRef<HTMLDivElement>(null);
@@ -332,7 +337,13 @@ export default function ChatPanel({ messages, onSend, isWaiting, isWorkerWaiting
       </div>
 
       {/* Input area — question widget replaces textarea when a question is pending */}
-      {pendingQuestion && pendingOptions && onQuestionSubmit ? (
+      {pendingQuestions && pendingQuestions.length >= 2 && onMultiQuestionSubmit ? (
+        <MultiQuestionWidget
+          questions={pendingQuestions}
+          onSubmit={onMultiQuestionSubmit}
+          onDismiss={onQuestionDismiss}
+        />
+      ) : pendingQuestion && pendingOptions && onQuestionSubmit ? (
         <QuestionWidget
           question={pendingQuestion}
           options={pendingOptions}

core/frontend/src/components/DraftGraph.tsx

@@ -0,0 +1,848 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { DraftGraph as DraftGraphData, DraftNode } from "@/api/types";
+import type { GraphNode } from "./AgentGraph";
+
+type DraftNodeStatus = "pending" | "running" | "complete" | "error";
+
+interface DraftGraphProps {
+  draft: DraftGraphData;
+  onNodeClick?: (node: DraftNode) => void;
+  /** Runtime node ID → list of original draft node IDs (post-dissolution mapping). */
+  flowchartMap?: Record<string, string[]>;
+  /** Current runtime graph nodes with live status (for overlay during execution). */
+  runtimeNodes?: GraphNode[];
+  /** Called when a draft node is clicked in overlay mode — receives the runtime node ID. */
+  onRuntimeNodeClick?: (runtimeNodeId: string) => void;
+}
+
+// Layout constants — tuned for a ~500px panel (484px after px-2 padding)
+const NODE_H = 52;
+const GAP_Y = 48;
+const TOP_Y = 28;
+const MARGIN_X = 16;
+const GAP_X = 16;
+
+function truncateLabel(label: string, availablePx: number, fontSize: number): string {
+  const avgCharW = fontSize * 0.58;
+  const maxChars = Math.floor(availablePx / avgCharW);
+  if (label.length <= maxChars) return label;
+  return label.slice(0, Math.max(maxChars - 1, 1)) + "\u2026";
+}
+
+/**
+ * Render an ISO 5807 flowchart shape as an SVG element.
+ */
+function FlowchartShape({
+  shape,
+  x,
+  y,
+  w,
+  h,
+  color,
+  selected,
+}: {
+  shape: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  color: string;
+  selected: boolean;
+}) {
+  const fill = selected ? `${color}28` : `${color}18`;
+  const stroke = selected ? color : `${color}80`;
+  const common = { fill, stroke, strokeWidth: 1.2 };
+
+  switch (shape) {
+    case "stadium":
+      return <rect x={x} y={y} width={w} height={h} rx={h / 2} {...common} />;
+
+    case "rectangle":
+      return <rect x={x} y={y} width={w} height={h} rx={4} {...common} />;
+
+    case "rounded_rect":
+      return <rect x={x} y={y} width={w} height={h} rx={12} {...common} />;
+
+    case "diamond": {
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      // Keep diamond within bounding box
+      return (
+        <polygon
+          points={`${cx},${y} ${x + w},${cy} ${cx},${y + h} ${x},${cy}`}
+          {...common}
+        />
+      );
+    }
+
+    case "parallelogram": {
+      const skew = 12;
+      return (
+        <polygon
+          points={`${x + skew},${y} ${x + w},${y} ${x + w - skew},${y + h} ${x},${y + h}`}
+          {...common}
+        />
+      );
+    }
+
+    case "document": {
+      const d = `M ${x} ${y + 4} Q ${x} ${y}, ${x + 8} ${y} L ${x + w - 8} ${y} Q ${x + w} ${y}, ${x + w} ${y + 4} L ${x + w} ${y + h - 8} C ${x + w * 0.75} ${y + h + 2}, ${x + w * 0.25} ${y + h - 10}, ${x} ${y + h - 4} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "multi_document": {
+      const off = 3;
+      const d = `M ${x} ${y + 4 + off} Q ${x} ${y + off}, ${x + 8} ${y + off} L ${x + w - 8 - off} ${y + off} Q ${x + w - off} ${y + off}, ${x + w - off} ${y + 4 + off} L ${x + w - off} ${y + h - 8} C ${x + (w - off) * 0.75} ${y + h + 2}, ${x + (w - off) * 0.25} ${y + h - 10}, ${x} ${y + h - 4} Z`;
+      return (
+        <g>
+          <rect x={x + off * 2} y={y} width={w - off * 2} height={h - off} rx={4} fill={fill} stroke={stroke} strokeWidth={1.2} opacity={0.4} />
+          <rect x={x + off} y={y + off / 2} width={w - off} height={h - off} rx={4} fill={fill} stroke={stroke} strokeWidth={1.2} opacity={0.6} />
+          <path d={d} {...common} />
+        </g>
+      );
+    }
+
+    case "subroutine": {
+      const inset = 7;
+      return (
+        <g>
+          <rect x={x} y={y} width={w} height={h} rx={4} {...common} />
+          <line x1={x + inset} y1={y} x2={x + inset} y2={y + h} stroke={stroke} strokeWidth={1.2} />
+          <line x1={x + w - inset} y1={y} x2={x + w - inset} y2={y + h} stroke={stroke} strokeWidth={1.2} />
+        </g>
+      );
+    }
+
+    case "hexagon": {
+      const inset = 14;
+      return (
+        <polygon
+          points={`${x + inset},${y} ${x + w - inset},${y} ${x + w},${y + h / 2} ${x + w - inset},${y + h} ${x + inset},${y + h} ${x},${y + h / 2}`}
+          {...common}
+        />
+      );
+    }
+
+    case "manual_input":
+      return (
+        <polygon
+          points={`${x},${y + 10} ${x + w},${y} ${x + w},${y + h} ${x},${y + h}`}
+          {...common}
+        />
+      );
+
+    case "trapezoid": {
+      const inset = 12;
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w - inset},${y + h} ${x + inset},${y + h}`}
+          {...common}
+        />
+      );
+    }
+
+    case "delay": {
+      const d = `M ${x} ${y + 4} Q ${x} ${y}, ${x + 4} ${y} L ${x + w * 0.65} ${y} A ${w * 0.35} ${h / 2} 0 0 1 ${x + w * 0.65} ${y + h} L ${x + 4} ${y + h} Q ${x} ${y + h}, ${x} ${y + h - 4} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "display": {
+      const d = `M ${x + 16} ${y} L ${x + w * 0.65} ${y} A ${w * 0.35} ${h / 2} 0 0 1 ${x + w * 0.65} ${y + h} L ${x + 16} ${y + h} L ${x} ${y + h / 2} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "cylinder": {
+      const ry = 7;
+      return (
+        <g>
+          <path
+            d={`M ${x} ${y + ry} L ${x} ${y + h - ry} A ${w / 2} ${ry} 0 0 0 ${x + w} ${y + h - ry} L ${x + w} ${y + ry}`}
+            {...common}
+          />
+          <ellipse cx={x + w / 2} cy={y + ry} rx={w / 2} ry={ry} {...common} />
+          <ellipse cx={x + w / 2} cy={y + h - ry} rx={w / 2} ry={ry} fill={fill} stroke={stroke} strokeWidth={1.2} />
+        </g>
+      );
+    }
+
+    case "stored_data": {
+      const d = `M ${x + 14} ${y} L ${x + w} ${y} A 10 ${h / 2} 0 0 0 ${x + w} ${y + h} L ${x + 14} ${y + h} A 10 ${h / 2} 0 0 1 ${x + 14} ${y} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "internal_storage":
+      return (
+        <g>
+          <rect x={x} y={y} width={w} height={h} rx={4} {...common} />
+          <line x1={x + 10} y1={y} x2={x + 10} y2={y + h} stroke={stroke} strokeWidth={0.8} opacity={0.5} />
+          <line x1={x} y1={y + 10} x2={x + w} y2={y + 10} stroke={stroke} strokeWidth={0.8} opacity={0.5} />
+        </g>
+      );
+
+    case "circle": {
+      const r = Math.min(w, h) / 2 - 2;
+      return <circle cx={x + w / 2} cy={y + h / 2} r={r} {...common} />;
+    }
+
+    case "pentagon":
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w},${y + h * 0.6} ${x + w / 2},${y + h} ${x},${y + h * 0.6}`}
+          {...common}
+        />
+      );
+
+    case "triangle_inv":
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w / 2},${y + h}`}
+          {...common}
+        />
+      );
+
+    case "triangle":
+      return (
+        <polygon
+          points={`${x + w / 2},${y} ${x + w},${y + h} ${x},${y + h}`}
+          {...common}
+        />
+      );
+
+    case "hourglass":
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w / 2},${y + h / 2} ${x + w},${y + h} ${x},${y + h} ${x + w / 2},${y + h / 2}`}
+          {...common}
+        />
+      );
+
+    case "circle_cross": {
+      const r = Math.min(w, h) / 2 - 2;
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      return (
+        <g>
+          <circle cx={cx} cy={cy} r={r} {...common} />
+          <line x1={cx - r * 0.7} y1={cy - r * 0.7} x2={cx + r * 0.7} y2={cy + r * 0.7} stroke={stroke} strokeWidth={1} />
+          <line x1={cx + r * 0.7} y1={cy - r * 0.7} x2={cx - r * 0.7} y2={cy + r * 0.7} stroke={stroke} strokeWidth={1} />
+        </g>
+      );
+    }
+
+    case "circle_bar": {
+      const r = Math.min(w, h) / 2 - 2;
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      return (
+        <g>
+          <circle cx={cx} cy={cy} r={r} {...common} />
+          <line x1={cx} y1={cy - r} x2={cx} y2={cy + r} stroke={stroke} strokeWidth={1} />
+          <line x1={cx - r} y1={cy} x2={cx + r} y2={cy} stroke={stroke} strokeWidth={1} />
+        </g>
+      );
+    }
+
+    case "flag": {
+      const d = `M ${x} ${y} L ${x + w} ${y} L ${x + w - 8} ${y + h / 2} L ${x + w} ${y + h} L ${x} ${y + h} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    default:
+      return <rect x={x} y={y} width={w} height={h} rx={8} {...common} />;
+  }
+}
+
+/** HTML tooltip positioned over the graph container */
+function Tooltip({ node, style }: { node: DraftNode; style: React.CSSProperties }) {
+  const lines: string[] = [];
+  if (node.description) lines.push(node.description);
+  if (node.tools.length > 0) lines.push(`Tools: ${node.tools.join(", ")}`);
+  if (node.success_criteria) lines.push(`Criteria: ${node.success_criteria}`);
+  if (lines.length === 0) return null;
+
+  return (
+    <div
+      className="absolute z-20 pointer-events-none px-2.5 py-2 rounded-md border border-border/40 bg-popover/95 backdrop-blur-sm shadow-lg max-w-[260px]"
+      style={style}
+    >
+      {lines.map((line, i) => (
+        <p key={i} className="text-[10px] text-muted-foreground leading-[1.4] mb-0.5 last:mb-0">
+          {line}
+        </p>
+      ))}
+    </div>
+  );
+}
+
+export default function DraftGraph({ draft, onNodeClick, flowchartMap, runtimeNodes, onRuntimeNodeClick }: DraftGraphProps) {
+  const [hoveredNode, setHoveredNode] = useState<string | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [containerW, setContainerW] = useState(484);
+
+  // Measure actual container width so layout fills it exactly
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver((entries) => {
+      const w = entries[0]?.contentRect.width;
+      if (w && w > 0) setContainerW(w);
+    });
+    ro.observe(el);
+    // Capture initial width
+    setContainerW(el.clientWidth || 484);
+    return () => ro.disconnect();
+  }, []);
+
+  // Invert flowchartMap: draftNodeId → runtimeNodeId
+  const draftToRuntime = useMemo<Record<string, string>>(() => {
+    if (!flowchartMap) return {};
+    const map: Record<string, string> = {};
+    for (const [runtimeId, draftIds] of Object.entries(flowchartMap)) {
+      for (const did of draftIds) {
+        map[did] = runtimeId;
+      }
+    }
+    return map;
+  }, [flowchartMap]);
+
+  // Compute draft node statuses from runtime overlay
+  const nodeStatuses = useMemo<Record<string, DraftNodeStatus>>(() => {
+    if (!runtimeNodes?.length || !Object.keys(draftToRuntime).length) return {};
+    // Build runtime status lookup
+    const runtimeStatus: Record<string, DraftNodeStatus> = {};
+    for (const rn of runtimeNodes) {
+      const s = rn.status;
+      runtimeStatus[rn.id] =
+        s === "running" || s === "looping" ? "running"
+        : s === "complete" ? "complete"
+        : s === "error" ? "error"
+        : "pending";
+    }
+    // Map to draft nodes
+    const result: Record<string, DraftNodeStatus> = {};
+    for (const [draftId, runtimeId] of Object.entries(draftToRuntime)) {
+      result[draftId] = runtimeStatus[runtimeId] ?? "pending";
+    }
+    return result;
+  }, [draftToRuntime, runtimeNodes]);
+
+  const hasStatusOverlay = Object.keys(nodeStatuses).length > 0;
+
+  const { nodes, edges } = draft;
+
+  const idxMap = useMemo(
+    () => Object.fromEntries(nodes.map((n, i) => [n.id, i])),
+    [nodes],
+  );
+
+  const forwardEdges = useMemo(() => {
+    const fwd: { fromIdx: number; toIdx: number; fanCount: number; fanIndex: number; label?: string }[] = [];
+    const grouped = new Map<number, { toIdx: number; label?: string }[]>();
+    for (const e of edges) {
+      const fromIdx = idxMap[e.source];
+      const toIdx = idxMap[e.target];
+      if (fromIdx === undefined || toIdx === undefined) continue;
+      if (toIdx <= fromIdx) continue;
+      const list = grouped.get(fromIdx) || [];
+      list.push({ toIdx, label: e.label || (e.condition !== "on_success" && e.condition !== "always" ? e.condition : e.description || undefined) });
+      grouped.set(fromIdx, list);
+    }
+    for (const [fromIdx, targets] of grouped) {
+      targets.forEach((t, fi) => {
+        fwd.push({ fromIdx, toIdx: t.toIdx, fanCount: targets.length, fanIndex: fi, label: t.label });
+      });
+    }
+    return fwd;
+  }, [edges, idxMap]);
+
+  const backEdges = useMemo(() => {
+    const back: { fromIdx: number; toIdx: number }[] = [];
+    for (const e of edges) {
+      const fromIdx = idxMap[e.source];
+      const toIdx = idxMap[e.target];
+      if (fromIdx === undefined || toIdx === undefined) continue;
+      if (toIdx <= fromIdx) back.push({ fromIdx, toIdx });
+    }
+    return back;
+  }, [edges, idxMap]);
+
+  // Layer-based layout with parent-aware column placement
+  const layout = useMemo(() => {
+    if (nodes.length === 0) {
+      return { layers: [] as number[], nodeW: 200, firstColX: MARGIN_X, nodeXPositions: [] as number[] };
+    }
+
+    // Build parent and children maps
+    const parents = new Map<number, number[]>();
+    const children = new Map<number, number[]>();
+    nodes.forEach((_, i) => { parents.set(i, []); children.set(i, []); });
+    forwardEdges.forEach((e) => {
+      parents.get(e.toIdx)!.push(e.fromIdx);
+      children.get(e.fromIdx)!.push(e.toIdx);
+    });
+
+    // Assign layers (longest path from root)
+    const layers = new Array(nodes.length).fill(0);
+    for (let i = 0; i < nodes.length; i++) {
+      const pars = parents.get(i) || [];
+      if (pars.length > 0) {
+        layers[i] = Math.max(...pars.map((p) => layers[p])) + 1;
+      }
+    }
+
+    const layerGroups = new Map<number, number[]>();
+    layers.forEach((l, i) => {
+      const group = layerGroups.get(l) || [];
+      group.push(i);
+      layerGroups.set(l, group);
+    });
+
+    let maxCols = 1;
+    layerGroups.forEach((group) => {
+      maxCols = Math.max(maxCols, group.length);
+    });
+
+    // Compute node width
+    const backEdgeMargin = backEdges.length > 0 ? 30 + backEdges.length * 14 : 8;
+    const totalMargin = MARGIN_X * 2 + backEdgeMargin;
+    const availW = containerW - totalMargin;
+    const nodeW = Math.min(360, Math.floor((availW - (maxCols - 1) * GAP_X) / maxCols));
+
+    // Parent-aware column placement using fractional positions.
+    // Instead of snapping to a fixed grid, nodes inherit positions from parents
+    // and fan-out children spread around the parent's position.
+    const colPos = new Array(nodes.length).fill(0); // fractional column positions
+    const maxLayer = Math.max(...layers);
+
+    // Process layers top-down
+    for (let layer = 0; layer <= maxLayer; layer++) {
+      const group = layerGroups.get(layer) || [];
+      if (layer === 0) {
+        // Root layer: spread evenly across available columns
+        if (group.length === 1) {
+          colPos[group[0]] = (maxCols - 1) / 2;
+        } else {
+          const offset = (maxCols - group.length) / 2;
+          group.forEach((nodeIdx, i) => { colPos[nodeIdx] = offset + i; });
+        }
+        continue;
+      }
+
+      // For each node, compute ideal position from parents
+      const ideals: { idx: number; pos: number }[] = [];
+      for (const nodeIdx of group) {
+        const pars = parents.get(nodeIdx) || [];
+        if (pars.length === 0) {
+          ideals.push({ idx: nodeIdx, pos: (maxCols - 1) / 2 });
+          continue;
+        }
+        // Average parent column — weighted center
+        const avgCol = pars.reduce((s, p) => s + colPos[p], 0) / pars.length;
+
+        // If this node is one of multiple children of a parent, offset from center
+        // Find the parent with the most children to determine fan-out
+        let bestOffset = 0;
+        for (const p of pars) {
+          const siblings = (children.get(p) || []).filter(c => layers[c] === layer);
+          if (siblings.length > 1) {
+            const sibIdx = siblings.indexOf(nodeIdx);
+            if (sibIdx >= 0) {
+              bestOffset = sibIdx - (siblings.length - 1) / 2;
+              // Scale so siblings don't exceed available columns
+              bestOffset *= Math.min(1, (maxCols - 1) / Math.max(siblings.length - 1, 1));
+            }
+          }
+        }
+        ideals.push({ idx: nodeIdx, pos: avgCol + bestOffset });
+      }
+
+      // Sort by ideal position, then assign while preventing overlaps
+      ideals.sort((a, b) => a.pos - b.pos);
+
+      // Ensure minimum spacing of 1 column between nodes in the same layer
+      const assigned: number[] = [];
+      for (const item of ideals) {
+        let pos = item.pos;
+        // Clamp to valid range
+        pos = Math.max(0, Math.min(maxCols - 1, pos));
+        // Push right if overlapping previous
+        if (assigned.length > 0) {
+          const prev = assigned[assigned.length - 1];
+          if (pos < prev + 1) pos = prev + 1;
+        }
+        assigned.push(pos);
+        colPos[item.idx] = pos;
+      }
+
+      // If we pushed nodes too far right, shift the whole group left
+      const maxPos = assigned[assigned.length - 1];
+      if (maxPos > maxCols - 1) {
+        const shift = maxPos - (maxCols - 1);
+        for (const item of ideals) {
+          colPos[item.idx] = Math.max(0, colPos[item.idx] - shift);
+        }
+      }
+    }
+
+    // Convert fractional column positions to pixel X positions
+    const colSpacing = nodeW + GAP_X;
+    const usedMin = Math.min(...colPos);
+    const usedMax = Math.max(...colPos);
+    const usedSpan = usedMax - usedMin || 1;
+    const totalNodesW = usedSpan * colSpacing;
+    const firstColX = MARGIN_X + (availW - totalNodesW) / 2;
+
+    const nodeXPositions = colPos.map((c: number) => firstColX + (c - usedMin) * colSpacing);
+
+    return { layers, nodeW, firstColX, nodeXPositions };
+  }, [nodes, forwardEdges, backEdges.length, containerW]);
+
+  if (nodes.length === 0) {
+    return (
+      <div className="flex flex-col h-full">
+        <div className="px-4 pt-4 pb-2">
+          <p className="text-[11px] text-muted-foreground font-medium uppercase tracking-wider">
+            Draft
+          </p>
+        </div>
+        <div className="flex-1 flex items-center justify-center px-4">
+          <p className="text-xs text-muted-foreground/60 text-center italic">
+            No draft graph yet.
+            <br />
+            Describe your workflow to get started.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const { layers, nodeW, nodeXPositions } = layout;
+
+  const nodePos = (i: number) => ({
+    x: nodeXPositions[i],
+    y: TOP_Y + layers[i] * (NODE_H + GAP_Y),
+  });
+
+  const maxLayer = Math.max(...layers);
+  const svgHeight = TOP_Y + (maxLayer + 1) * NODE_H + maxLayer * GAP_Y + 16;
+
+  // Compute group areas for multi-node runtime groups
+  const groupAreas = useMemo(() => {
+    if (!flowchartMap || !runtimeNodes?.length) return [];
+    const groups: { runtimeId: string; label: string; draftIds: string[] }[] = [];
+    for (const [runtimeId, draftIds] of Object.entries(flowchartMap)) {
+      if (draftIds.length < 2) continue;
+      const rn = runtimeNodes.find(n => n.id === runtimeId);
+      groups.push({ runtimeId, label: rn?.label ?? runtimeId, draftIds });
+    }
+    return groups;
+  }, [flowchartMap, runtimeNodes]);
+
+  // Legend
+  const usedTypes = (() => {
+    const seen = new Map<string, { shape: string; color: string }>();
+    for (const n of nodes) {
+      if (!seen.has(n.flowchart_type)) {
+        seen.set(n.flowchart_type, { shape: n.flowchart_shape, color: n.flowchart_color });
+      }
+    }
+    return [...seen.entries()];
+  })();
+  const legendH = usedTypes.length * 18 + 20;
+  const totalH = svgHeight + legendH;
+
+  // Find hovered node for tooltip positioning
+  const hoveredNodeData = hoveredNode ? nodes.find(n => n.id === hoveredNode) : null;
+  const hoveredIdx = hoveredNode ? idxMap[hoveredNode] : -1;
+  const hoveredPos = hoveredIdx >= 0 ? nodePos(hoveredIdx) : null;
+
+  const renderEdge = (edge: typeof forwardEdges[number], i: number) => {
+    const from = nodePos(edge.fromIdx);
+    const to = nodePos(edge.toIdx);
+    const fromCenterX = from.x + nodeW / 2;
+    const toCenterX = to.x + nodeW / 2;
+    const y1 = from.y + NODE_H;
+    const y2 = to.y;
+
+    let startX = fromCenterX;
+    if (edge.fanCount > 1) {
+      const spread = nodeW * 0.4;
+      const step = edge.fanCount > 1 ? spread / (edge.fanCount - 1) : 0;
+      startX = fromCenterX - spread / 2 + edge.fanIndex * step;
+    }
+
+    const midY = (y1 + y2) / 2;
+    const d = `M ${startX} ${y1} C ${startX} ${midY}, ${toCenterX} ${midY}, ${toCenterX} ${y2}`;
+
+    return (
+      <g key={`fwd-${i}`}>
+        <path d={d} fill="none" stroke="hsl(220,10%,30%)" strokeWidth={1.2} />
+        <polygon
+          points={`${toCenterX - 3},${y2 - 5} ${toCenterX + 3},${y2 - 5} ${toCenterX},${y2 - 1}`}
+          fill="hsl(220,10%,35%)"
+        />
+        {edge.label && (
+          <text
+            x={(startX + toCenterX) / 2}
+            y={midY - 3}
+            fill="hsl(220,10%,45%)"
+            fontSize={9}
+            fontStyle="italic"
+            textAnchor="middle"
+          >
+            {truncateLabel(edge.label, 80, 9)}
+          </text>
+        )}
+      </g>
+    );
+  };
+
+  const renderBackEdge = (edge: typeof backEdges[number], i: number) => {
+    const from = nodePos(edge.fromIdx);
+    const to = nodePos(edge.toIdx);
+    const rightX = Math.max(from.x, to.x) + nodeW;
+    const rightOffset = 20 + i * 14;
+    const startX = from.x + nodeW;
+    const startY = from.y + NODE_H / 2;
+    const endX = to.x + nodeW;
+    const endY = to.y + NODE_H / 2;
+    const curveX = rightX + rightOffset;
+    const r = 10;
+
+    const path = `M ${startX} ${startY} C ${startX + r} ${startY}, ${curveX} ${startY}, ${curveX} ${startY - r} L ${curveX} ${endY + r} C ${curveX} ${endY}, ${endX + r} ${endY}, ${endX + 5} ${endY}`;
+
+    return (
+      <g key={`back-${i}`}>
+        <path d={path} fill="none" stroke="hsl(220,10%,25%)" strokeWidth={1.2} strokeDasharray="4 3" />
+        <polygon
+          points={`${endX + 5},${endY - 2.5} ${endX + 5},${endY + 2.5} ${endX},${endY}`}
+          fill="hsl(220,10%,30%)"
+        />
+      </g>
+    );
+  };
+
+  const STATUS_COLORS: Record<DraftNodeStatus, string> = {
+    running: "#F59E0B",  // amber
+    complete: "#22C55E", // green
+    error: "#EF4444",    // red
+    pending: "",         // no overlay
+  };
+
+  const renderNode = (node: DraftNode, i: number) => {
+    const pos = nodePos(i);
+    const isHovered = hoveredNode === node.id;
+    const status = nodeStatuses[node.id] as DraftNodeStatus | undefined;
+    const statusColor = status ? STATUS_COLORS[status] : "";
+    const fontSize = 13;
+    const labelAvailW = nodeW - 28;
+    const displayLabel = truncateLabel(node.name, labelAvailW, fontSize);
+    const descAvailW = nodeW - 24;
+    const descLabel = node.description
+      ? truncateLabel(node.description, descAvailW, 9.5)
+      : node.flowchart_type.replace(/_/g, " ");
+    const textX = pos.x + nodeW / 2;
+    const textY = pos.y + NODE_H / 2;
+
+    return (
+      <g
+        key={node.id}
+        onClick={() => {
+          if (hasStatusOverlay && onRuntimeNodeClick) {
+            const runtimeId = draftToRuntime[node.id];
+            if (runtimeId) onRuntimeNodeClick(runtimeId);
+          } else {
+            onNodeClick?.(node);
+          }
+        }}
+        onMouseEnter={() => setHoveredNode(node.id)}
+        onMouseLeave={() => setHoveredNode(null)}
+        style={{ cursor: "pointer" }}
+      >
+        <title>{`${node.name}\n${node.flowchart_type}`}</title>
+
+        {/* Status glow ring (runtime overlay) */}
+        {hasStatusOverlay && statusColor && (
+          <rect
+            x={pos.x - 3}
+            y={pos.y - 3}
+            width={nodeW + 6}
+            height={NODE_H + 6}
+            rx={8}
+            fill="none"
+            stroke={statusColor}
+            strokeWidth={2}
+            opacity={status === "running" ? 0.8 : 0.6}
+          >
+            {status === "running" && (
+              <animate attributeName="opacity" values="0.4;0.9;0.4" dur="1.5s" repeatCount="indefinite" />
+            )}
+          </rect>
+        )}
+
+        <FlowchartShape
+          shape={node.flowchart_shape}
+          x={pos.x}
+          y={pos.y}
+          w={nodeW}
+          h={NODE_H}
+          color={node.flowchart_color}
+          selected={isHovered}
+        />
+
+        <text
+          x={textX}
+          y={textY - 5}
+          fill={isHovered ? "hsl(0,0%,92%)" : "hsl(0,0%,78%)"}
+          fontSize={fontSize}
+          fontWeight={500}
+          textAnchor="middle"
+          dominantBaseline="middle"
+        >
+          {displayLabel}
+        </text>
+
+        <text
+          x={textX}
+          y={textY + 11}
+          fill="hsl(220,10%,50%)"
+          fontSize={9.5}
+          textAnchor="middle"
+          dominantBaseline="middle"
+        >
+          {descLabel}
+        </text>
+
+        {/* Status dot indicator */}
+        {hasStatusOverlay && statusColor && (
+          <circle
+            cx={pos.x + nodeW - 6}
+            cy={pos.y + 6}
+            r={4}
+            fill={statusColor}
+          >
+            {status === "running" && (
+              <animate attributeName="r" values="3;5;3" dur="1s" repeatCount="indefinite" />
+            )}
+          </circle>
+        )}
+      </g>
+    );
+  };
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Header */}
+      <div className="px-4 pt-3 pb-1.5 flex items-center gap-2">
+        <p className="text-[11px] text-muted-foreground font-medium uppercase tracking-wider">
+          {hasStatusOverlay ? "Flowchart" : "Draft"}
+        </p>
+        <span className={`text-[9px] font-mono font-medium rounded px-1 py-0.5 leading-none border ${hasStatusOverlay ? "text-emerald-500/60 border-emerald-500/20" : "text-amber-500/60 border-amber-500/20"}`}>
+          {hasStatusOverlay ? "live" : "planning"}
+        </span>
+      </div>
+
+      {/* Agent name + goal */}
+      <div className="px-4 pb-2.5 border-b border-border/20">
+        <p className="text-[11px] font-medium text-foreground/80 truncate">
+          {draft.agent_name}
+        </p>
+        {draft.goal && (
+          <p className="text-[10px] text-muted-foreground/60 mt-0.5 line-clamp-2 leading-snug">
+            {draft.goal}
+          </p>
+        )}
+      </div>
+
+      {/* Graph */}
+      <div ref={containerRef} className="flex-1 overflow-y-auto overflow-x-hidden px-2 pb-2 relative">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${containerW} ${totalH}`}
+          preserveAspectRatio="xMidYMin meet"
+          className="select-none"
+          style={{ fontFamily: "'Inter', system-ui, sans-serif" }}
+        >
+          {/* Group areas — dashed boxes behind multi-node runtime groups */}
+          {groupAreas.map((group) => {
+            const memberIndices = group.draftIds
+              .map(id => idxMap[id])
+              .filter((idx): idx is number => idx !== undefined);
+            if (memberIndices.length < 2) return null;
+            const positions = memberIndices.map(i => nodePos(i));
+            const pad = 10;
+            const minX = Math.min(...positions.map(p => p.x)) - pad;
+            const minY = Math.min(...positions.map(p => p.y)) - pad - 14; // extra space for label
+            const maxX = Math.max(...positions.map(p => p.x + nodeW)) + pad;
+            const maxY = Math.max(...positions.map(p => p.y + NODE_H)) + pad;
+            return (
+              <g key={`group-${group.runtimeId}`}>
+                <rect
+                  x={minX}
+                  y={minY}
+                  width={maxX - minX}
+                  height={maxY - minY}
+                  rx={8}
+                  fill="hsl(220,15%,18%)"
+                  fillOpacity={0.35}
+                  stroke="hsl(220,10%,40%)"
+                  strokeWidth={1}
+                  strokeDasharray="5 3"
+                />
+                <text
+                  x={minX + 8}
+                  y={minY + 11}
+                  fill="hsl(220,10%,50%)"
+                  fontSize={9}
+                  fontWeight={500}
+                >
+                  {truncateLabel(group.label, maxX - minX - 16, 9)}
+                </text>
+              </g>
+            );
+          })}
+
+          {forwardEdges.map((e, i) => renderEdge(e, i))}
+          {backEdges.map((e, i) => renderBackEdge(e, i))}
+          {nodes.map((n, i) => renderNode(n, i))}
+
+          {/* Legend */}
+          <g transform={`translate(${MARGIN_X}, ${svgHeight + 4})`}>
+            <text fill="hsl(220,10%,40%)" fontSize={9} fontWeight={600} y={4}>
+              LEGEND
+            </text>
+            {usedTypes.map(([type, meta], i) => (
+              <g key={type} transform={`translate(0, ${14 + i * 18})`}>
+                <FlowchartShape
+                  shape={meta.shape}
+                  x={0}
+                  y={0}
+                  w={16}
+                  h={12}
+                  color={meta.color}
+                  selected={false}
+                />
+                <text x={22} y={9} fill="hsl(220,10%,55%)" fontSize={9.5}>
+                  {type.replace(/_/g, " ")}
+                </text>
+              </g>
+            ))}
+          </g>
+        </svg>
+
+        {/* HTML tooltip — rendered outside SVG so it's not clipped */}
+        {hoveredNodeData && hoveredPos && (
+          <Tooltip
+            node={hoveredNodeData}
+            style={{
+              left: 8,
+              right: 8,
+              // Position below the hovered node, scaled to container width
+              top: `calc(${((hoveredPos.y + NODE_H + 4) / totalH) * 100}%)`,
+            }}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

core/frontend/src/components/MultiQuestionWidget.tsx

@@ -0,0 +1,215 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+import { Send, MessageCircleQuestion, X } from "lucide-react";
+
+export interface QuestionItem {
+  id: string;
+  prompt: string;
+  options?: string[];
+}
+
+export interface MultiQuestionWidgetProps {
+  questions: QuestionItem[];
+  onSubmit: (answers: Record<string, string>) => void;
+  onDismiss?: () => void;
+}
+
+export default function MultiQuestionWidget({ questions, onSubmit, onDismiss }: MultiQuestionWidgetProps) {
+  // Per-question state: selected index (null = nothing, options.length = "Other")
+  const [selections, setSelections] = useState<(number | null)[]>(
+    () => questions.map(() => null),
+  );
+  const [customTexts, setCustomTexts] = useState<string[]>(
+    () => questions.map(() => ""),
+  );
+  const [submitted, setSubmitted] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Scroll the first unanswered question into view when it changes
+  useEffect(() => {
+    containerRef.current?.scrollTo({ top: 0, behavior: "smooth" });
+  }, []);
+
+  const canSubmit = questions.every((q, i) => {
+    const sel = selections[i];
+    if (sel === null) return false;
+    const isOther = q.options ? sel === q.options.length : true;
+    if (isOther && !customTexts[i].trim()) return false;
+    return true;
+  });
+
+  const handleSubmit = useCallback(() => {
+    if (!canSubmit || submitted) return;
+    setSubmitted(true);
+    const answers: Record<string, string> = {};
+    for (let i = 0; i < questions.length; i++) {
+      const q = questions[i];
+      const sel = selections[i]!;
+      const isOther = q.options ? sel === q.options.length : true;
+      answers[q.id] = isOther ? customTexts[i].trim() : q.options![sel];
+    }
+    onSubmit(answers);
+  }, [canSubmit, submitted, questions, selections, customTexts, onSubmit]);
+
+  // Enter to submit (only when not focused on a text input)
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (submitted) return;
+      const target = e.target as HTMLElement;
+      const inInput = target.tagName === "INPUT" || target.tagName === "TEXTAREA";
+      if (e.key === "Enter" && !e.shiftKey && !inInput) {
+        e.preventDefault();
+        handleSubmit();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [handleSubmit, submitted]);
+
+  if (submitted) return null;
+
+  const answeredCount = selections.filter((s) => s !== null).length;
+
+  return (
+    <div className="p-4">
+      <div className="bg-card border border-border rounded-xl shadow-sm overflow-hidden">
+        {/* Header */}
+        <div className="px-5 pt-4 pb-2 flex items-center gap-3">
+          <div className="w-7 h-7 rounded-lg bg-primary/10 border border-primary/20 flex items-center justify-center flex-shrink-0">
+            <MessageCircleQuestion className="w-3.5 h-3.5 text-primary" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium text-foreground">
+              {questions.length} questions
+            </p>
+            <p className="text-[11px] text-muted-foreground">
+              {answeredCount}/{questions.length} answered
+            </p>
+          </div>
+          {onDismiss && (
+            <button
+              onClick={onDismiss}
+              className="p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/60 transition-colors flex-shrink-0"
+            >
+              <X className="w-4 h-4" />
+            </button>
+          )}
+        </div>
+
+        {/* Questions */}
+        <div
+          ref={containerRef}
+          className="px-5 pb-3 space-y-4 max-h-[400px] overflow-y-auto"
+        >
+          {questions.map((q, qi) => {
+            const sel = selections[qi];
+            const hasOptions = q.options && q.options.length >= 2;
+            const otherIndex = hasOptions ? q.options!.length : 0;
+            const isOtherSelected = sel === otherIndex;
+
+            return (
+              <div key={q.id} className="space-y-1.5">
+                <p className="text-sm font-medium text-foreground">
+                  <span className="text-xs text-muted-foreground mr-1.5">
+                    {qi + 1}.
+                  </span>
+                  {q.prompt}
+                </p>
+
+                {hasOptions ? (
+                  <>
+                    {q.options!.map((opt, oi) => (
+                      <button
+                        key={oi}
+                        onClick={() => {
+                          setSelections((prev) => {
+                            const next = [...prev];
+                            next[qi] = oi;
+                            return next;
+                          });
+                        }}
+                        className={`w-full text-left px-4 py-2 rounded-lg border text-sm transition-colors ${
+                          sel === oi
+                            ? "border-primary bg-primary/10 text-foreground"
+                            : "border-border/60 bg-muted/20 text-foreground hover:border-primary/40 hover:bg-muted/40"
+                        }`}
+                      >
+                        {opt}
+                      </button>
+                    ))}
+                    <input
+                      type="text"
+                      value={customTexts[qi]}
+                      onFocus={() => {
+                        setSelections((prev) => {
+                          const next = [...prev];
+                          next[qi] = otherIndex;
+                          return next;
+                        });
+                      }}
+                      onChange={(e) => {
+                        setSelections((prev) => {
+                          const next = [...prev];
+                          next[qi] = otherIndex;
+                          return next;
+                        });
+                        setCustomTexts((prev) => {
+                          const next = [...prev];
+                          next[qi] = e.target.value;
+                          return next;
+                        });
+                      }}
+                      placeholder="Type a custom response..."
+                      className={`w-full px-4 py-2 rounded-lg border border-dashed text-sm transition-colors bg-transparent placeholder:text-muted-foreground focus:outline-none ${
+                        isOtherSelected
+                          ? "border-primary bg-primary/10 text-foreground"
+                          : "border-border text-muted-foreground hover:border-primary/40"
+                      }`}
+                    />
+                  </>
+                ) : (
+                  <input
+                    type="text"
+                    value={customTexts[qi]}
+                    onFocus={() => {
+                      setSelections((prev) => {
+                        const next = [...prev];
+                        next[qi] = 0;
+                        return next;
+                      });
+                    }}
+                    onChange={(e) => {
+                      setSelections((prev) => {
+                        const next = [...prev];
+                        next[qi] = 0;
+                        return next;
+                      });
+                      setCustomTexts((prev) => {
+                        const next = [...prev];
+                        next[qi] = e.target.value;
+                        return next;
+                      });
+                    }}
+                    placeholder="Type your answer..."
+                    className="w-full px-4 py-2 rounded-lg border text-sm transition-colors bg-transparent placeholder:text-muted-foreground focus:outline-none border-border text-foreground hover:border-primary/40 focus:border-primary"
+                  />
+                )}
+              </div>
+            );
+          })}
+        </div>
+
+        {/* Submit */}
+        <div className="px-5 pb-4">
+          <button
+            onClick={handleSubmit}
+            disabled={!canSubmit}
+            className="w-full flex items-center justify-center gap-2 py-2.5 rounded-lg text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90 disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+          >
+            <Send className="w-3.5 h-3.5" />
+            Submit All
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

core/frontend/src/pages/workspace.tsx

@@ -3,6 +3,7 @@ import ReactDOM from "react-dom";
 import { useSearchParams, useNavigate } from "react-router-dom";
 import { Plus, KeyRound, Sparkles, Layers, ChevronLeft, Bot, Loader2, WifiOff, X } from "lucide-react";
 import AgentGraph, { type GraphNode, type NodeStatus } from "@/components/AgentGraph";
+import DraftGraph from "@/components/DraftGraph";
 import ChatPanel, { type ChatMessage } from "@/components/ChatPanel";
 import TopBar from "@/components/TopBar";
 import { TAB_STORAGE_KEY, loadPersistedTabs, savePersistedTabs, type PersistedTabState } from "@/lib/tab-persistence";
@@ -13,7 +14,7 @@ import { executionApi } from "@/api/execution";
 import { graphsApi } from "@/api/graphs";
 import { sessionsApi } from "@/api/sessions";
 import { useMultiSSE } from "@/hooks/use-sse";
-import type { LiveSession, AgentEvent, DiscoverEntry, Message, NodeSpec } from "@/api/types";
+import type { LiveSession, AgentEvent, DiscoverEntry, Message, NodeSpec, DraftGraph as DraftGraphData } from "@/api/types";
 import { backendMessageToChatMessage, sseEventToChatMessage, formatAgentDisplayName } from "@/lib/chat-helpers";
 import { topologyToGraphNodes } from "@/lib/graph-converter";
 import { ApiError } from "@/api/client";
@@ -257,6 +258,12 @@ interface AgentBackendState {
   queenBuilding: boolean;
   /** Queen operating phase — "planning" (design), "building" (coding), "staging" (loaded), or "running" (executing) */
   queenPhase: "planning" | "building" | "staging" | "running";
+  /** Draft graph from planning phase (before code generation) */
+  draftGraph: DraftGraphData | null;
+  /** Original draft (pre-dissolution) for flowchart display during runtime */
+  originalDraft: DraftGraphData | null;
+  /** Runtime node ID → list of original draft node IDs it absorbed */
+  flowchartMap: Record<string, string[]> | null;
   workerRunState: "idle" | "deploying" | "running";
   currentExecutionId: string | null;
   nodeLogs: Record<string, string[]>;
@@ -270,10 +277,14 @@ interface AgentBackendState {
   workerIsTyping: boolean;
   llmSnapshots: Record<string, string>;
   activeToolCalls: Record<string, { name: string; done: boolean; streamId: string }>;
+  /** Agent folder path — set after scaffolding, used for credential queries */
+  agentPath: string | null;
   /** Structured question text from ask_user with options */
   pendingQuestion: string | null;
   /** Predefined choices from ask_user (1-3 items); UI appends "Other" */
   pendingOptions: string[] | null;
+  /** Multiple questions from ask_user_multiple */
+  pendingQuestions: { id: string; prompt: string; options?: string[] }[] | null;
   /** Whether the pending question came from queen or worker */
   pendingQuestionSource: "queen" | "worker" | null;
 }
@@ -292,6 +303,10 @@ function defaultAgentState(): AgentBackendState {
     workerInputMessageId: null,
     queenBuilding: false,
     queenPhase: "planning",
+    draftGraph: null,
+    originalDraft: null,
+    flowchartMap: null,
+    agentPath: null,
     workerRunState: "idle",
     currentExecutionId: null,
     nodeLogs: {},
@@ -305,6 +320,7 @@ function defaultAgentState(): AgentBackendState {
     activeToolCalls: {},
     pendingQuestion: null,
     pendingOptions: null,
+    pendingQuestions: null,
     pendingQuestionSource: null,
   };
 }
@@ -1056,6 +1072,39 @@ export default function Workspace() {
     }
   }, [agentStates, fetchGraphForAgent]);
 
+  // --- Fetch draft graph when a session is in planning phase ---
+  // Covers initial load, tab switches, reconnects, and cold restores.
+  const fetchedDraftSessionsRef = useRef<Set<string>>(new Set());
+  const fetchedFlowchartMapSessionsRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    for (const [agentType, state] of Object.entries(agentStates)) {
+      if (!state.sessionId || !state.ready) continue;
+
+      if (state.queenPhase === "planning") {
+        // Fetch draft graph for planning phase
+        if (state.draftGraph) continue;
+        if (fetchedDraftSessionsRef.current.has(state.sessionId)) continue;
+        fetchedDraftSessionsRef.current.add(state.sessionId);
+        graphsApi.draftGraph(state.sessionId).then(({ draft }) => {
+          if (draft) updateAgentState(agentType, { draftGraph: draft });
+        }).catch(() => {});
+      } else {
+        // Fetch flowchart map for non-planning phases (staging, running, building)
+        if (state.originalDraft) continue; // already have it
+        if (fetchedFlowchartMapSessionsRef.current.has(state.sessionId)) continue;
+        fetchedFlowchartMapSessionsRef.current.add(state.sessionId);
+        graphsApi.flowchartMap(state.sessionId).then(({ map, original_draft }) => {
+          if (original_draft) {
+            updateAgentState(agentType, {
+              flowchartMap: map,
+              originalDraft: original_draft,
+            });
+          }
+        }).catch(() => {});
+      }
+    }
+  }, [agentStates, updateAgentState]);
+
   // Poll entry points every second for agents with timers to keep
   // next_fire_in countdowns fresh without re-fetching the full topology.
   useEffect(() => {
@@ -1310,6 +1359,7 @@ export default function Workspace() {
               activeToolCalls: {},
               pendingQuestion: null,
               pendingOptions: null,
+              pendingQuestions: null,
               pendingQuestionSource: null,
             });
             markAllNodesAs(agentType, ["running", "looping", "complete", "error"], "pending");
@@ -1339,6 +1389,7 @@ export default function Workspace() {
               llmSnapshots: {},
               pendingQuestion: null,
               pendingOptions: null,
+              pendingQuestions: null,
               pendingQuestionSource: null,
             });
             markAllNodesAs(agentType, ["running", "looping"], "complete");
@@ -1388,9 +1439,13 @@ export default function Workspace() {
             console.log('[CLIENT_INPUT_REQ] stream_id:', streamId, 'isQueen:', isQueen, 'node_id:', event.node_id, 'prompt:', (event.data?.prompt as string)?.slice(0, 80), 'agentType:', agentType);
             const rawOptions = event.data?.options;
             const options = Array.isArray(rawOptions) ? (rawOptions as string[]) : null;
+            const rawQuestions = event.data?.questions;
+            const questions = Array.isArray(rawQuestions)
+              ? (rawQuestions as { id: string; prompt: string; options?: string[] }[])
+              : null;
             if (isQueen) {
               const prompt = (event.data?.prompt as string) || "";
-              const isAutoBlock = !prompt && !options;
+              const isAutoBlock = !prompt && !options && !questions;
               // Queen auto-block (empty prompt, no options) should not
               // overwrite a pending worker question — the worker's
               // QuestionWidget must stay visible.  Use the updater form
@@ -1421,6 +1476,7 @@ export default function Workspace() {
                     queenBuilding: false,
                     pendingQuestion: prompt || null,
                     pendingOptions: options,
+                    pendingQuestions: questions,
                     pendingQuestionSource: "queen",
                   }
                 };
@@ -1460,14 +1516,14 @@ export default function Workspace() {
             }
           }
           if (event.type === "execution_paused") {
-            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
             if (!isQueen) {
               updateAgentState(agentType, { workerRunState: "idle", currentExecutionId: null });
               markAllNodesAs(agentType, ["running", "looping"], "pending");
             }
           }
           if (event.type === "execution_failed") {
-            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
             if (!isQueen) {
               updateAgentState(agentType, { workerRunState: "idle", currentExecutionId: null });
               if (event.node_id) {
@@ -1500,9 +1556,9 @@ export default function Workspace() {
         case "node_loop_iteration":
           turnCounterRef.current[turnKey] = currentTurn + 1;
           if (isQueen) {
-            updateAgentState(agentType, { isStreaming: false, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isStreaming: false, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
           } else {
-            updateAgentState(agentType, { isStreaming: false, workerIsTyping: true, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isStreaming: false, workerIsTyping: true, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
           }
           if (!isQueen && event.node_id) {
             const pendingText = agentStates[agentType]?.llmSnapshots[event.node_id];
@@ -1788,6 +1844,7 @@ export default function Workspace() {
 
         case "queen_phase_changed": {
           const rawPhase = event.data?.phase as string;
+          const eventAgentPath = (event.data?.agent_path as string) || null;
           const newPhase: "planning" | "building" | "staging" | "running" =
             rawPhase === "running" ? "running"
             : rawPhase === "staging" ? "staging"
@@ -1798,7 +1855,51 @@ export default function Workspace() {
             queenBuilding: newPhase === "building",
             // Sync workerRunState so the RunButton reflects the phase
             workerRunState: newPhase === "running" ? "running" : "idle",
+            // Clear draft graph once we leave planning; also clear dedup refs
+            // so re-entering planning or re-fetching flowchart map works
+            ...(newPhase !== "planning" ? { draftGraph: null } : { originalDraft: null, flowchartMap: null }),
+            // Store agent path for credential queries
+            ...(eventAgentPath ? { agentPath: eventAgentPath } : {}),
           });
+          {
+            const sid = agentStates[agentType]?.sessionId;
+            if (sid) {
+              if (newPhase !== "planning") {
+                fetchedDraftSessionsRef.current.delete(sid);
+                fetchedFlowchartMapSessionsRef.current.delete(sid);
+                // Fetch the flowchart map (original draft + dissolution mapping)
+                graphsApi.flowchartMap(sid).then(({ map, original_draft }) => {
+                  updateAgentState(agentType, {
+                    flowchartMap: map,
+                    originalDraft: original_draft,
+                  });
+                }).catch(() => {});
+              } else {
+                fetchedDraftSessionsRef.current.delete(sid);
+                fetchedFlowchartMapSessionsRef.current.delete(sid);
+              }
+            }
+          }
+          break;
+        }
+
+        case "draft_graph_updated": {
+          // The draft dict is published directly as event.data (not nested under a key)
+          const draft = event.data as unknown as DraftGraphData | undefined;
+          if (draft?.nodes) {
+            updateAgentState(agentType, { draftGraph: draft });
+          }
+          break;
+        }
+
+        case "flowchart_map_updated": {
+          const mapData = event.data as { map?: Record<string, string[]>; original_draft?: DraftGraphData } | undefined;
+          if (mapData) {
+            updateAgentState(agentType, {
+              flowchartMap: mapData.map ?? null,
+              originalDraft: mapData.original_draft ?? null,
+            });
+          }
           break;
         }
 
@@ -1929,7 +2030,7 @@ export default function Workspace() {
             s.id === activeSession.id ? { ...s, messages: [...s.messages, userMsg] } : s
           ),
         }));
-        updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+        updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
         executionApi.workerInput(state.sessionId, text).catch((err: unknown) => {
           const errMsg = err instanceof Error ? err.message : String(err);
           const errorChatMsg: ChatMessage = {
@@ -1951,7 +2052,7 @@ export default function Workspace() {
 
     // If queen has a pending question widget, dismiss it when user types directly
     if (agentStates[activeWorker]?.pendingQuestionSource === "queen") {
-      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
     }
 
     const userMsg: ChatMessage = {
@@ -2018,7 +2119,7 @@ export default function Workspace() {
     }));
 
     // Clear awaiting state optimistically
-    updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+    updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
 
     executionApi.workerInput(state.sessionId, text).catch((err: unknown) => {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -2046,7 +2147,7 @@ export default function Workspace() {
 
     if (isOther) {
       // "Other" free-text → route through queen for evaluation
-      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
       if (question && opts && state?.sessionId && state?.ready) {
         const formatted = `[Worker asked: "${question}" | Options: ${opts.join(", ")}]\nUser answered: "${answer}"`;
         const userMsg: ChatMessage = {
@@ -2092,10 +2193,23 @@ export default function Workspace() {
   // --- handleQueenQuestionAnswer: submit queen's own question answer via /chat ---
   // The queen asked the question herself, so she already has context — just send the raw answer.
   const handleQueenQuestionAnswer = useCallback((answer: string, _isOther: boolean) => {
-    updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+    updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
     handleSend(answer, activeWorker);
   }, [activeWorker, handleSend, updateAgentState]);
 
+  // --- handleMultiQuestionAnswer: submit answers to ask_user_multiple ---
+  const handleMultiQuestionAnswer = useCallback((answers: Record<string, string>) => {
+    updateAgentState(activeWorker, {
+      pendingQuestion: null, pendingOptions: null,
+      pendingQuestions: null, pendingQuestionSource: null,
+    });
+    // Format as structured text the LLM can parse
+    const lines = Object.entries(answers).map(
+      ([id, answer]) => `[${id}]: ${answer}`,
+    );
+    handleSend(lines.join("\n"), activeWorker);
+  }, [activeWorker, handleSend, updateAgentState]);
+
   // --- handleQuestionDismiss: user closed the question widget without answering ---
   // Injects a dismiss signal so the blocked node can continue.
   const handleQuestionDismiss = useCallback(() => {
@@ -2108,6 +2222,7 @@ export default function Workspace() {
     updateAgentState(activeWorker, {
       pendingQuestion: null,
       pendingOptions: null,
+      pendingQuestions: null,
       pendingQuestionSource: null,
       awaitingInput: false,
     });
@@ -2371,18 +2486,32 @@ export default function Workspace() {
       <div className="flex flex-1 min-h-0">
 
         {/* ── Pipeline graph + chat ──────────────────────────────────── */}
-        <div className="w-[300px] min-w-[240px] bg-card/30 flex flex-col border-r border-border/30">
+        <div className={`${(activeAgentState?.queenPhase === "planning" && activeAgentState?.draftGraph) || activeAgentState?.originalDraft ? "w-[500px] min-w-[400px]" : "w-[300px] min-w-[240px]"} bg-card/30 flex flex-col border-r border-border/30 transition-[width] duration-200`}>
           <div className="flex-1 min-h-0">
-            <AgentGraph
-              nodes={currentGraph.nodes}
-              title={currentGraph.title}
-              onNodeClick={(node) => setSelectedNode(prev => prev?.id === node.id ? null : node)}
-              onRun={handleRun}
-              onPause={handlePause}
-              runState={activeAgentState?.workerRunState ?? "idle"}
-              building={activeAgentState?.queenBuilding ?? false}
-              queenPhase={activeAgentState?.queenPhase ?? "building"}
-            />
+            {activeAgentState?.queenPhase === "planning" && activeAgentState.draftGraph ? (
+              <DraftGraph draft={activeAgentState.draftGraph} />
+            ) : activeAgentState?.originalDraft ? (
+              <DraftGraph
+                draft={activeAgentState.originalDraft}
+                flowchartMap={activeAgentState.flowchartMap ?? undefined}
+                runtimeNodes={currentGraph.nodes}
+                onRuntimeNodeClick={(runtimeNodeId) => {
+                  const node = currentGraph.nodes.find(n => n.id === runtimeNodeId);
+                  if (node) setSelectedNode(prev => prev?.id === node.id ? null : node);
+                }}
+              />
+            ) : (
+              <AgentGraph
+                nodes={currentGraph.nodes}
+                title={currentGraph.title}
+                onNodeClick={(node) => setSelectedNode(prev => prev?.id === node.id ? null : node)}
+                onRun={handleRun}
+                onPause={handlePause}
+                runState={activeAgentState?.workerRunState ?? "idle"}
+                building={activeAgentState?.queenBuilding ?? false}
+                queenPhase={activeAgentState?.queenPhase ?? "building"}
+              />
+            )}
           </div>
         </div>
         <div className="flex-1 min-w-0 flex">
@@ -2454,11 +2583,13 @@ export default function Workspace() {
                 queenPhase={activeAgentState?.queenPhase ?? "building"}
                 pendingQuestion={activeAgentState?.awaitingInput ? activeAgentState.pendingQuestion : null}
                 pendingOptions={activeAgentState?.awaitingInput ? activeAgentState.pendingOptions : null}
+                pendingQuestions={activeAgentState?.awaitingInput ? activeAgentState.pendingQuestions : null}
                 onQuestionSubmit={
                   activeAgentState?.pendingQuestionSource === "queen"
                     ? handleQueenQuestionAnswer
                     : handleWorkerQuestionAnswer
                 }
+                onMultiQuestionSubmit={handleMultiQuestionAnswer}
                 onQuestionDismiss={handleQuestionDismiss}
               />
             )}
@@ -2546,7 +2677,7 @@ export default function Workspace() {
       <CredentialsModal
         agentType={activeWorker}
         agentLabel={activeWorkerLabel}
-        agentPath={credentialAgentPath || (!activeWorker.startsWith("new-agent") ? activeWorker : undefined)}
+        agentPath={credentialAgentPath || activeAgentState?.agentPath || (!activeWorker.startsWith("new-agent") ? activeWorker : undefined)}
         open={credentialsOpen}
         onClose={() => { setCredentialsOpen(false); setCredentialAgentPath(null); setDismissedBanner(null); }}
         credentials={activeSession?.credentials || []}

core/tests/test_event_loop_integration.py

@@ -572,7 +572,7 @@ async def test_event_loop_conversation_compaction():
     judge = CountingJudge(retry_count=3)
     node = EventLoopNode(
         judge=judge,
-        config=LoopConfig(max_iterations=10, max_history_tokens=200),
+        config=LoopConfig(max_iterations=10, max_context_tokens=200),
     )
     result = await node.execute(ctx)
 

core/tests/test_node_conversation.py

@@ -204,8 +204,8 @@ class TestNodeConversation:
 
     @pytest.mark.asyncio
     async def test_usage_ratio(self):
-        """usage_ratio returns estimate / max_history_tokens."""
-        conv = NodeConversation(max_history_tokens=1000)
+        """usage_ratio returns estimate / max_context_tokens."""
+        conv = NodeConversation(max_context_tokens=1000)
         await conv.add_user_message("a" * 400)
         assert conv.usage_ratio() == pytest.approx(0.1)  # 100/1000
 
@@ -214,15 +214,15 @@ class TestNodeConversation:
 
     @pytest.mark.asyncio
     async def test_usage_ratio_zero_budget(self):
-        """usage_ratio returns 0 when max_history_tokens is 0 (unlimited)."""
-        conv = NodeConversation(max_history_tokens=0)
+        """usage_ratio returns 0 when max_context_tokens is 0 (unlimited)."""
+        conv = NodeConversation(max_context_tokens=0)
         await conv.add_user_message("a" * 400)
         assert conv.usage_ratio() == 0.0
 
     @pytest.mark.asyncio
     async def test_needs_compaction_with_actual_tokens(self):
         """needs_compaction uses actual API token count when available."""
-        conv = NodeConversation(max_history_tokens=1000, compaction_threshold=0.8)
+        conv = NodeConversation(max_context_tokens=1000, compaction_threshold=0.8)
         await conv.add_user_message("a" * 100)  # chars/4 = 25, well under 800
 
         assert conv.needs_compaction() is False
@@ -233,7 +233,7 @@ class TestNodeConversation:
 
     @pytest.mark.asyncio
     async def test_needs_compaction(self):
-        conv = NodeConversation(max_history_tokens=100, compaction_threshold=0.8)
+        conv = NodeConversation(max_context_tokens=100, compaction_threshold=0.8)
         await conv.add_user_message("x" * 320)
         assert conv.needs_compaction() is True
 
@@ -457,7 +457,7 @@ class TestPersistence:
         store = MockConversationStore()
         assert await NodeConversation.restore(store) is None
 
-        conv = NodeConversation(system_prompt="hello", max_history_tokens=500, store=store)
+        conv = NodeConversation(system_prompt="hello", max_context_tokens=500, store=store)
         await conv.add_user_message("u1")
         await conv.add_assistant_message("a1")
 
@@ -643,7 +643,7 @@ class TestConversationIntegration:
         store = FileConversationStore(base)
         conv = NodeConversation(
             system_prompt="You are a helpful travel agent.",
-            max_history_tokens=16000,
+            max_context_tokens=16000,
             store=store,
         )
 
@@ -1314,7 +1314,7 @@ class TestLlmCompact:
         """Create a minimal EventLoopNode for testing."""
         from framework.graph.event_loop_node import EventLoopNode, LoopConfig
 
-        config = LoopConfig(max_history_tokens=32000)
+        config = LoopConfig(max_context_tokens=32000)
         node = EventLoopNode.__new__(EventLoopNode)
         node._config = config
         node._event_bus = None

docs/configuration.md

@@ -172,7 +172,7 @@ Add to `.vscode/settings.json`:
 ## Security Best Practices
 
 1. **Never commit API keys** - Use environment variables or `.env` files
-2. **`.env` is git-ignored** - Copy `.env.example` to `.env` at the project root and fill in your values
+2. **If you use a local `.env` file, keep it private** - This repository does not include a root `.env.example`; use your own local `.env` file or shell environment variables for secrets
 3. **Use real provider keys in non-production environments** - validate configuration with low-risk inputs before production rollout
 4. **Credential isolation** - Each tool validates its own credentials at runtime
 

docs/draft-flowchart-schema.md

@@ -0,0 +1,597 @@
+# Draft Flowchart System — Complete Reference
+
+The draft flowchart system bridges user-facing workflow design (planning phase) and the runtime agent graph (execution phase). During planning, the queen agent creates an ISO 5807 flowchart that the user reviews. On approval, decision nodes are dissolved into runtime-compatible structures, and the original flowchart is preserved for live status overlay during execution.
+
+---
+
+## Architecture Overview
+
+```
+Planning Phase                    Build Gate                     Runtime Phase
+─────────────────────────────────────────────────────────────────────────────
+
+Queen LLM                      confirm_and_build()              Graph Executor
+    │                                │                               │
+    ▼                                ▼                               ▼
+save_agent_draft()        ┌──────────────────────┐          Node execution
+    │                     │ dissolve_decision_nodes│          with status
+    ▼                     │                        │               │
+DraftGraph (SSE) ────►    │  Decision diamonds     │               ▼
+    │                     │  merged into           │          Flowchart Map
+    ▼                     │  predecessor criteria   │          inverts to
+Frontend renders          │                        │          overlay status
+ISO 5807 flowchart        │  Original draft        │          on original
+with diamond              │  preserved             │          flowchart
+decisions                 │                        │
+                          └──────────────────────┘
+```
+
+**Key files:**
+- Backend: `core/framework/tools/queen_lifecycle_tools.py` — draft creation, classification, dissolution
+- Backend: `core/framework/server/routes_graphs.py` — REST endpoints
+- Frontend: `core/frontend/src/components/DraftGraph.tsx` — SVG flowchart renderer
+- Frontend: `core/frontend/src/api/types.ts` — TypeScript interfaces
+- Frontend: `core/frontend/src/pages/workspace.tsx` — state management and conditional rendering
+
+---
+
+## 1. JSON Schemas
+
+### Tool: `save_agent_draft` — Input Schema
+
+```json
+{
+  "type": "object",
+  "required": ["agent_name", "goal", "nodes"],
+  "properties": {
+    "agent_name": {
+      "type": "string",
+      "description": "Snake_case name for the agent (e.g. 'lead_router_agent')"
+    },
+    "goal": {
+      "type": "string",
+      "description": "High-level goal description for the agent"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of what the agent does"
+    },
+    "nodes": {
+      "type": "array",
+      "description": "Graph nodes. Only 'id' is required; all other fields are optional hints.",
+      "items": { "$ref": "#/$defs/DraftNode" }
+    },
+    "edges": {
+      "type": "array",
+      "description": "Connections between nodes. Auto-generated as linear if omitted.",
+      "items": { "$ref": "#/$defs/DraftEdge" }
+    },
+    "terminal_nodes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Node IDs that are terminal (end) nodes. Auto-detected from edges if omitted."
+    },
+    "success_criteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Agent-level success criteria"
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Agent-level constraints"
+    }
+  }
+}
+```
+
+### Node Schema (`DraftNode`)
+
+```json
+{
+  "type": "object",
+  "required": ["id"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Kebab-case node identifier (e.g. 'enrich-lead')"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable display name. Defaults to id if omitted."
+    },
+    "description": {
+      "type": "string",
+      "description": "What this node does (business logic). Used for auto-classification."
+    },
+    "node_type": {
+      "type": "string",
+      "enum": ["event_loop", "gcu"],
+      "default": "event_loop",
+      "description": "Runtime node type. 'gcu' maps to browser automation."
+    },
+    "flowchart_type": {
+      "type": "string",
+      "enum": [
+        "start", "terminal", "process", "decision",
+        "io", "document", "multi_document",
+        "subprocess", "preparation",
+        "manual_input", "manual_operation",
+        "delay", "display",
+        "database", "stored_data", "internal_storage",
+        "connector", "offpage_connector",
+        "merge", "extract", "sort", "collate",
+        "summing_junction", "or",
+        "browser", "comment", "alternate_process"
+      ],
+      "description": "ISO 5807 flowchart symbol. Auto-detected if omitted."
+    },
+    "tools": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Planned tool names (hints for scaffolder, not validated)"
+    },
+    "input_keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Expected input memory keys"
+    },
+    "output_keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Expected output memory keys"
+    },
+    "success_criteria": {
+      "type": "string",
+      "description": "What success looks like for this node"
+    },
+    "decision_clause": {
+      "type": "string",
+      "description": "For decision nodes only: the yes/no question to evaluate (e.g. 'Is amount > $100?'). During dissolution, this becomes the predecessor node's success_criteria."
+    }
+  }
+}
+```
+
+### Edge Schema (`DraftEdge`)
+
+```json
+{
+  "type": "object",
+  "required": ["source", "target"],
+  "properties": {
+    "source": {
+      "type": "string",
+      "description": "Source node ID"
+    },
+    "target": {
+      "type": "string",
+      "description": "Target node ID"
+    },
+    "condition": {
+      "type": "string",
+      "enum": ["always", "on_success", "on_failure", "conditional", "llm_decide"],
+      "default": "on_success",
+      "description": "Edge traversal condition"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of when this edge is taken"
+    },
+    "label": {
+      "type": "string",
+      "description": "Short label shown on the flowchart edge (e.g. 'Yes', 'No', 'Retry')"
+    }
+  }
+}
+```
+
+### Output: Enriched Draft Graph Object
+
+After `save_agent_draft` processes the input, it stores and emits an enriched draft with auto-classified flowchart metadata. This is the structure sent via the `draft_graph_updated` SSE event and returned by `GET /api/sessions/{id}/draft-graph`.
+
+```json
+{
+  "agent_name": "lead_router_agent",
+  "goal": "Enrich and route incoming leads",
+  "description": "Automated lead enrichment and routing agent",
+  "success_criteria": ["Lead score calculated", "Correct tier assigned"],
+  "constraints": ["Apollo enrichment required before routing"],
+  "entry_node": "intake",
+  "terminal_nodes": ["route"],
+  "nodes": [
+    {
+      "id": "intake",
+      "name": "Intake",
+      "description": "Fetch contact from HubSpot",
+      "node_type": "event_loop",
+      "tools": ["hubspot_get_contact"],
+      "input_keys": ["contact_id"],
+      "output_keys": ["contact_data", "domain"],
+      "success_criteria": "Contact data retrieved",
+      "decision_clause": "",
+      "sub_agents": [],
+      "flowchart_type": "start",
+      "flowchart_shape": "stadium",
+      "flowchart_color": "#4CAF50"
+    },
+    {
+      "id": "check-tier",
+      "name": "Check Tier",
+      "description": "",
+      "node_type": "event_loop",
+      "decision_clause": "Is lead score > 80?",
+      "flowchart_type": "decision",
+      "flowchart_shape": "diamond",
+      "flowchart_color": "#FF9800"
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge-0",
+      "source": "intake",
+      "target": "check-tier",
+      "condition": "on_success",
+      "description": "",
+      "label": ""
+    },
+    {
+      "id": "edge-1",
+      "source": "check-tier",
+      "target": "enrich",
+      "condition": "on_success",
+      "description": "",
+      "label": "Yes"
+    },
+    {
+      "id": "edge-2",
+      "source": "check-tier",
+      "target": "route",
+      "condition": "on_failure",
+      "description": "",
+      "label": "No"
+    }
+  ],
+  "flowchart_legend": {
+    "start":    { "shape": "stadium",    "color": "#4CAF50" },
+    "terminal": { "shape": "stadium",    "color": "#F44336" },
+    "process":  { "shape": "rectangle",  "color": "#2196F3" },
+    "decision": { "shape": "diamond",    "color": "#FF9800" }
+  }
+}
+```
+
+**Enriched fields** (added by backend to every node during classification):
+
+| Field | Type | Description |
+|---|---|---|
+| `flowchart_type` | `string` | The resolved ISO 5807 symbol type |
+| `flowchart_shape` | `string` | SVG shape identifier for the frontend renderer |
+| `flowchart_color` | `string` | Hex color code for the symbol |
+
+### Flowchart Map Object
+
+Returned by `GET /api/sessions/{id}/flowchart-map` after `confirm_and_build()` dissolves decision nodes:
+
+```json
+{
+  "map": {
+    "intake": ["intake", "check-tier"],
+    "enrich": ["enrich"],
+    "route": ["route"]
+  },
+  "original_draft": { "...original draft graph before dissolution..." }
+}
+```
+
+- `map`: Keys are runtime node IDs, values are lists of original draft node IDs that the runtime node absorbed.
+- `original_draft`: The complete draft graph as it existed before dissolution, preserved for flowchart display.
+- Both fields are `null` if no dissolution has occurred yet.
+
+---
+
+## 2. ISO 5807 Flowchart Types
+
+### Core Symbols
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `start` | stadium | `#4CAF50` green | `<rect rx={h/2}>` | Entry point / start terminator |
+| `terminal` | stadium | `#F44336` red | `<rect rx={h/2}>` | End point / stop terminator |
+| `process` | rectangle | `#2196F3` blue | `<rect rx={4}>` | General processing step |
+| `decision` | diamond | `#FF9800` amber | `<polygon>` 4-point | Branching / conditional logic |
+| `io` | parallelogram | `#9C27B0` purple | `<polygon>` skewed | Data input or output |
+| `document` | document | `#607D8B` blue-grey | `<path>` wavy bottom | Single document output |
+| `multi_document` | multi_document | `#78909C` blue-grey | stacked `<rect>` + `<path>` | Multiple documents |
+| `subprocess` | subroutine | `#009688` teal | `<rect>` + inner `<line>` | Predefined process / sub-agent |
+| `preparation` | hexagon | `#795548` brown | `<polygon>` 6-point | Setup / initialization step |
+| `manual_input` | manual_input | `#E91E63` pink | `<polygon>` sloped top | Manual data entry |
+| `manual_operation` | trapezoid | `#AD1457` dark pink | `<polygon>` tapered bottom | Human-in-the-loop / approval |
+| `delay` | delay | `#FF5722` deep orange | `<path>` D-shape | Wait / pause / cooldown |
+| `display` | display | `#00BCD4` cyan | `<path>` pointed left | Display / render output |
+
+### Data Storage Symbols
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `database` | cylinder | `#8BC34A` light green | `<path>` + `<ellipse>` top/bottom | Database / direct access storage |
+| `stored_data` | stored_data | `#CDDC39` lime | `<path>` curved left | Generic data store |
+| `internal_storage` | internal_storage | `#FFC107` amber | `<rect>` + internal `<line>` grid | Internal memory / cache |
+
+### Connectors
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `connector` | circle | `#9E9E9E` grey | `<circle>` | On-page connector |
+| `offpage_connector` | pentagon | `#757575` dark grey | `<polygon>` 5-point | Off-page connector |
+
+### Flow Operations
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `merge` | triangle_inv | `#3F51B5` indigo | `<polygon>` inverted | Merge multiple flows |
+| `extract` | triangle | `#5C6BC0` indigo light | `<polygon>` upward | Extract / split flow |
+| `sort` | hourglass | `#7986CB` indigo lighter | `<polygon>` X-shape | Sort operation |
+| `collate` | hourglass_inv | `#9FA8DA` indigo lightest | `<polygon>` X-shape inv | Collate operation |
+| `summing_junction` | circle_cross | `#F06292` pink light | `<circle>` + cross `<line>` | Summing junction |
+| `or` | circle_bar | `#CE93D8` purple light | `<circle>` + plus `<line>` | Logical OR |
+
+### Domain-Specific (Hive)
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `browser` | hexagon | `#1A237E` dark indigo | `<polygon>` 6-point | Browser automation (GCU node) |
+| `comment` | flag | `#BDBDBD` light grey | `<path>` notched right | Annotation / comment |
+| `alternate_process` | rounded_rect | `#42A5F5` light blue | `<rect rx={12}>` | Alternate process variant |
+
+---
+
+## 3. Auto-Classification Priority
+
+When `flowchart_type` is omitted from a node, the backend classifies it automatically using this priority (function `_classify_flowchart_node` in `queen_lifecycle_tools.py`):
+
+1. **Explicit override** — if `flowchart_type` is set and valid, use it
+2. **Node type** — `gcu` nodes become `browser`
+3. **Position** — first node becomes `start`
+4. **Terminal detection** — nodes in `terminal_nodes` (or with no outgoing edges) become `terminal`
+5. **Branching structure** — nodes with 2+ outgoing edges with different conditions become `decision`
+6. **Sub-agents** — nodes with `sub_agents` become `subprocess`
+7. **Tool heuristics** — tool names match known patterns:
+   - DB tools (`query_database`, `sql_query`, `read_table`, etc.) → `database`
+   - Doc tools (`generate_report`, `create_document`, etc.) → `document`
+   - I/O tools (`send_email`, `post_to_slack`, `fetch_url`, etc.) → `io`
+   - Display tools (`serve_file_to_user`, `display_results`) → `display`
+8. **Description keyword heuristics**:
+   - `"manual"`, `"approval"`, `"human review"` → `manual_operation`
+   - `"setup"`, `"prepare"`, `"configure"` → `preparation`
+   - `"wait"`, `"delay"`, `"pause"` → `delay`
+   - `"merge"`, `"combine"`, `"aggregate"` → `merge`
+   - `"display"`, `"show"`, `"render"` → `display`
+   - `"database"`, `"data store"`, `"persist"` → `database`
+   - `"report"`, `"document"`, `"summary"` → `document`
+   - `"deliver"`, `"send"`, `"notify"` → `io`
+9. **Default** — `process` (blue rectangle)
+
+---
+
+## 4. Decision Node Dissolution
+
+When `confirm_and_build()` is called, decision nodes (flowchart diamonds) are dissolved into runtime-compatible structures by `_dissolve_decision_nodes()`. Decision nodes are a **planning-only** concept — they don't exist in the runtime graph.
+
+### Algorithm
+
+```
+For each decision node D (in topological order):
+  1. Find predecessors P via incoming edges
+  2. Find yes-target and no-target via outgoing edges
+     - Yes: edge with label "Yes"/"True"/"Pass" or condition "on_success"
+     - No:  edge with label "No"/"False"/"Fail" or condition "on_failure"
+     - Fallback: first outgoing = yes, second = no
+  3. Get decision clause: D.decision_clause || D.description || D.name
+  4. For each predecessor P:
+     - Append clause to P.success_criteria
+     - Remove edge P → D
+     - Add edge P → yes_target (on_success)
+     - Add edge P → no_target (on_failure)
+  5. Remove D and all its edges from the graph
+  6. Record absorption: flowchart_map[P.id] = [P.id, D.id]
+```
+
+### Edge Cases
+
+| Case | Behavior |
+|---|---|
+| **Decision at start** (no predecessor) | Converted to a process node with `success_criteria` = clause; outgoing edges rewired to `on_success`/`on_failure` |
+| **Chained decisions** (A → D1 → D2 → B) | Processed in order. D1 dissolves into A. D2's predecessor is now A, so D2 also dissolves into A. Map: `A → [A, D1, D2]` |
+| **Multiple predecessors** | Each predecessor gets its own copy of the yes/no edges |
+| **Existing success_criteria on predecessor** | Appended with `"; then evaluate: <clause>"` |
+| **Decision with >2 outgoing edges** | First classified yes/no pair is used; remaining edges are preserved |
+
+### Example
+
+**Input (planning flowchart):**
+```
+[Fetch Billing Data] → <Amount > $100?> → Yes → [Generate PDF Receipt]
+                                         → No  → [Draft Email Receipt]
+```
+
+**Output (runtime graph):**
+```
+[Fetch Billing Data] → on_success → [Generate PDF Receipt]
+                     → on_failure → [Draft Email Receipt]
+  success_criteria: "Amount > $100?"
+```
+
+**Flowchart map:**
+```json
+{
+  "fetch-billing-data": ["fetch-billing-data", "amount-gt-100"],
+  "generate-pdf-receipt": ["generate-pdf-receipt"],
+  "draft-email-receipt": ["draft-email-receipt"]
+}
+```
+
+The runtime Level 2 judge evaluates the decision clause against the node's conversation. `NodeResult.success = true` routes via `on_success` (yes), `false` routes via `on_failure` (no).
+
+---
+
+## 5. Frontend Rendering
+
+### Component: `DraftGraph.tsx`
+
+An SVG-based flowchart renderer that operates in two modes:
+
+1. **Planning mode** — renders the draft graph with ISO 5807 shapes during the planning phase
+2. **Runtime overlay mode** — renders the original (pre-dissolution) draft with live execution status when `flowchartMap` and `runtimeNodes` props are provided
+
+#### Props
+
+```typescript
+interface DraftGraphProps {
+  draft: DraftGraphData;                          // The draft graph to render
+  onNodeClick?: (node: DraftNode) => void;        // Node click handler
+  flowchartMap?: Record<string, string[]>;         // Runtime → draft node mapping
+  runtimeNodes?: GraphNode[];                      // Live runtime graph nodes with status
+}
+```
+
+#### Layout Engine
+
+The layout algorithm arranges nodes in layers based on graph topology:
+
+1. **Layer assignment**: Each node's layer = max(parent layers) + 1. Root nodes are layer 0.
+2. **Column assignment**: Within each layer, nodes are sorted by parent column average and centered.
+3. **Node sizing**: `nodeW = min(360, availableWidth / maxColumns)` — nodes fill available space up to 360px.
+4. **Container measurement**: A `ResizeObserver` measures the actual container width so SVG viewBox coordinates match CSS pixels 1:1.
+
+```
+Constants:
+  NODE_H   = 52px    (node height)
+  GAP_Y    = 48px    (vertical gap between layers)
+  GAP_X    = 16px    (horizontal gap between columns)
+  MARGIN_X = 16px    (left/right margin)
+  TOP_Y    = 28px    (top padding)
+```
+
+#### Shape Rendering
+
+The `FlowchartShape` component renders each ISO 5807 shape as SVG primitives. Each shape receives:
+- `x, y, w, h` — bounding box in SVG units
+- `color` — the hex color from the flowchart type
+- `selected` — hover state (increases fill opacity from 18% to 28%, brightens stroke)
+
+All shapes use `strokeWidth={1.2}` to prevent overflow on hover.
+
+#### Edge Rendering
+
+**Forward edges** (source layer < target layer):
+- Rendered as cubic bezier curves from source bottom-center to target top-center
+- Fan-out: when a node has multiple outgoing edges, start points spread across 40% of node width
+- Labels shown at the midpoint (from `edge.label`, or condition/description fallback)
+
+**Back edges** (source layer >= target layer):
+- Rendered as dashed arcs that loop right of the graph
+- Each back edge gets a unique offset to prevent overlap
+
+#### Node Labels
+
+Each node displays two lines of text:
+- **Primary**: Node name (font size 13, truncated to fit `nodeW - 28px`)
+- **Secondary**: Node description or flowchart type (font size 9.5, truncated to fit `nodeW - 24px`)
+
+Truncation uses `avgCharWidth = fontSize * 0.58` to estimate available characters.
+
+#### Tooltip
+
+An HTML overlay (not SVG) positioned below hovered nodes, showing:
+- Node description
+- Tools list (`Tools: tool_a, tool_b`)
+- Success criteria (`Criteria: ...`)
+
+#### Legend
+
+A dynamic legend at the bottom of the SVG listing all flowchart types used in the current draft, with their shape and color.
+
+### Runtime Status Overlay
+
+When `flowchartMap` and `runtimeNodes` are provided, the component computes per-node statuses:
+
+1. **Invert the map**: `flowchartMap` maps `runtime_id → [draft_ids]`; inversion gives `draft_id → runtime_id`
+2. **Map runtime status**: For each runtime node, classify status as `running` (amber), `complete` (green), `error` (red), or `pending` (no overlay)
+3. **Render overlays**:
+   - **Glow ring**: A pulsing amber `<rect>` around running nodes, solid green/red for complete/error
+   - **Status dot**: A small `<circle>` in the top-right corner with animated radius for running nodes
+4. **Header**: Changes from "Draft / planning" to "Flowchart / live"
+
+```typescript
+// Status color mapping
+const STATUS_COLORS = {
+  running:  "#F59E0B",  // amber — pulsing glow
+  complete: "#22C55E",  // green — solid ring
+  error:    "#EF4444",  // red   — solid ring
+  pending:  "",         // no overlay
+};
+```
+
+### Workspace Integration (`workspace.tsx`)
+
+The workspace conditionally renders `DraftGraph` in three scenarios:
+
+| Condition | Renders | Panel Width |
+|---|---|---|
+| `queenPhase === "planning"` and `draftGraph` exists | `<DraftGraph draft={draftGraph} />` | 500px |
+| `originalDraft` exists (post-planning) | `<DraftGraph draft={originalDraft} flowchartMap={...} runtimeNodes={...} />` | 500px |
+| Neither | `<AgentGraph ... />` (runtime pipeline view) | 300px |
+
+**State management:**
+- `draftGraph`: Set by `draft_graph_updated` SSE event during planning; cleared on phase change
+- `originalDraft` + `flowchartMap`: Fetched from `GET /api/sessions/{id}/flowchart-map` when phase transitions away from planning
+
+---
+
+## 6. Events & API
+
+### SSE Event: `draft_graph_updated`
+
+Emitted when `save_agent_draft` completes. The full draft graph object is the event `data` payload.
+
+```
+event: message
+data: {"type": "draft_graph_updated", "stream_id": "queen", "data": { ...draft graph object... }, ...}
+```
+
+### REST Endpoints
+
+**`GET /api/sessions/{session_id}/draft-graph`**
+
+Returns the current draft graph from planning phase.
+```json
+{"draft": <DraftGraph object>}
+// or
+{"draft": null}
+```
+
+**`GET /api/sessions/{session_id}/flowchart-map`**
+
+Returns the flowchart-to-runtime mapping and original draft (available after `confirm_and_build()`).
+```json
+{
+  "map": { "runtime-node-id": ["draft-node-a", "draft-node-b"], ... },
+  "original_draft": { ...original DraftGraph before dissolution... }
+}
+// or
+{"map": null, "original_draft": null}
+```
+
+---
+
+## 7. Phase Gate
+
+The draft graph is part of a two-step gate controlling the planning → building transition:
+
+1. **`save_agent_draft()`** — creates the draft, classifies nodes, emits `draft_graph_updated`
+2. User reviews the rendered flowchart (with decision diamonds, edge labels, color-coded shapes)
+3. **`confirm_and_build()`** — dissolves decision nodes, preserves original draft, builds flowchart map, sets `build_confirmed = true`
+4. **`initialize_and_build_agent()`** — checks `build_confirmed` before proceeding; passes the dissolved (decision-free) draft to the scaffolder for pre-population
+
+The scaffolder never sees decision nodes — it receives a clean graph with only runtime-compatible node types where branching is expressed through `success_criteria` + `on_success`/`on_failure` edges.

examples/recipes/README.md

@@ -1,54 +0,0 @@
-# Recipes
-
-A recipe describes an agent's design — the goal, nodes, prompts, edge logic, and tools — without providing runnable code. Think of it as a blueprint: it tells you *how* to build the agent, but you do the building.
-
-## What's in a recipe
-
-Each recipe is a markdown file (or folder with a markdown file) containing:
-
-- **Goal**: What the agent accomplishes, including success criteria and constraints
-- **Nodes**: Each step in the workflow, with the system prompt, node type, and input/output keys
-- **Edges**: How nodes connect, including conditions and routing logic
-- **Tools**: What external tools or MCP servers the agent needs
-- **Usage notes**: Tips, gotchas, and suggested variations
-
-## How to use a recipe
-
-1. Read through the recipe to understand the design
-2. Create a new agent using the standard export structure (see [templates/](../templates/) for a scaffold)
-3. Translate the recipe's goal, nodes, and edges into code
-4. Wire in the tools described
-5. Test and iterate
-
-## Available recipes
-
-### Sales & Marketing
-| Recipe | Description |
-|--------|-------------|
-| [social_media_management](social_media_management/) | Schedule posts, reply to comments, monitor trends |
-| [newsletter_production](newsletter_production/) | Transform voice memos and ideas into polished emails |
-| [news_jacking](news_jacking/) | Personalized outreach triggered by real-time company news |
-| [ad_campaign_monitoring](ad_campaign_monitoring/) | Monitor and analyze advertising campaign performance |
-| [crm_update](crm_update/) | Ensure every lead has follow-up dates and status |
-
-### Customer Success
-| Recipe | Description |
-|--------|-------------|
-| [inquiry_triaging](inquiry_triaging/) | Sort tire kickers from hot leads |
-| [onboarding_assistance](onboarding_assistance/) | Guide new clients through setup and welcome kits |
-
-### Operations Automation
-| Recipe | Description |
-|--------|-------------|
-| [inbox_management](inbox_management/) | Clear spam and surface emails that need your brain |
-| [invoicing_collections](invoicing_collections/) | Send invoices and chase overdue payments |
-| [data_keeper](data_keeper/) | Pull data from multiple sources into unified reports |
-| [calendar_coordination](calendar_coordination/) | Protect Deep Work time and book travel |
-
-### Technical & Product Maintenance
-| Recipe | Description |
-|--------|-------------|
-| [quality_assurance](quality_assurance/) | Test features and links before they go live |
-| [documentation](documentation/) | Turn messy processes into clean SOPs |
-| [support_troubleshooting](support_troubleshooting/) | Handle Level 1 tech support |
-| [issue_triaging](issue_triaging/) | Categorize and route bug reports by severity |

examples/recipes/ad_campaign_monitoring/README.md

@@ -1,36 +0,0 @@
-# Recipe: Ad Campaign Monitoring
-
-Checking daily spends on Meta/Google ads and flagging if the Cost Per Acquisition (CPA) spikes.
-
-## Why
-
-Ad platforms are designed to spend your money. Without daily oversight, a $50/day campaign can quietly become a $500 disaster. This agent watches your campaigns like a hawk, catching anomalies before they drain your budget and surfacing optimization opportunities you'd otherwise miss.
-
-## What
-
-- Monitor daily spend across all active campaigns
-- Track CPA, ROAS, CTR, and conversion metrics
-- Compare performance against historical benchmarks
-- Identify underperforming ads and audiences
-- Generate daily/weekly performance summaries
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Meta Ads API | Facebook/Instagram campaign data |
-| Google Ads API | Search/Display/YouTube campaign data |
-| Google Analytics 4 | Conversion tracking and attribution |
-| Google Sheets | Performance dashboards and reporting |
-| Slack | Alerts and daily summaries |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| CPA spikes >30% above target | Alert with breakdown by ad set and pause recommendation |
-| Daily budget exhausted before noon | Immediate alert — possible click fraud or viral ad |
-| ROAS drops below profitability threshold | Pause campaign and notify with optimization suggestions |
-| Ad rejected by platform | Alert with rejection reason and suggested fix |
-| Competitor running aggressive campaign | Flag if detected through auction insights |
-| Budget pacing off by >20% | Alert with projected monthly spend |

examples/recipes/calendar_coordination/README.md

@@ -1,37 +0,0 @@
-# Recipe: Travel & Calendar Coordination
-
-Protecting your "Deep Work" time from getting fragmented by random 15-minute meetings.
-
-## Why
-
-Your calendar is a battlefield. Everyone wants a slice of your time, and without protection, your days become a patchwork of 30-minute meetings with no room for actual work. This agent defends your schedule — booking travel, consolidating meetings, and protecting the focus time you need to think.
-
-## What
-
-- Block and protect "Deep Work" time slots
-- Batch similar meetings together to reduce context switching
-- Book travel (flights, hotels, ground transport)
-- Handle meeting requests and rescheduling
-- Prep briefing docs before important meetings
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Google Calendar / Outlook | Calendar management |
-| Calendly / Cal.com | External scheduling |
-| TripIt / Google Flights / Kayak | Travel booking |
-| Expensify / Ramp | Travel expense tracking |
-| Notion / Google Docs | Meeting prep documents |
-| Slack | Schedule alerts and confirmations |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Someone tries to book over Deep Work time | Decline and offer alternatives, alert you if they push back |
-| VIP requests meeting during protected time | Flag for your decision — worth the exception? |
-| Flight cancelled or significantly delayed | Immediate alert with rebooking options |
-| Double-booking conflict | Alert with suggested resolution |
-| Meeting with no agenda 24h before | Prompt organizer for agenda, flag if none provided |
-| Travel cost exceeds budget threshold | Queue for approval before booking |

examples/recipes/crm_update/README.md

@@ -1,35 +0,0 @@
-# Recipe: CRM Update
-
-Ensuring every lead has a follow-up date and a status update.
-
-## Why
-
-A messy CRM is a leaky pipeline. Leads without follow-up dates get forgotten. Deals without status updates go stale. This agent keeps your CRM clean and actionable — so when you open it, you see exactly what needs your attention today.
-
-## What
-
-- Audit leads missing follow-up dates or status updates
-- Flag stale deals that haven't been touched in X days
-- Merge duplicate contacts and companies
-- Enrich records with missing data (email, phone, company info)
-- Generate daily "pipeline hygiene" reports
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| HubSpot / Salesforce / Pipedrive | CRM management |
-| Clearbit / Apollo / ZoomInfo | Data enrichment |
-| Google Sheets | Hygiene reports and audits |
-| Slack | Daily pipeline summary and action items |
-| Zapier / Make | Cross-platform data sync |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| High-value deal stale >14 days | Alert with deal history and suggested re-engagement |
-| Duplicate detected for active deal | Flag before merging — might be intentional |
-| Lead data conflicts with enrichment | Queue for human verification |
-| Pipeline value drops significantly week-over-week | Alert with analysis of what changed |
-| Follow-up overdue for >5 leads | Daily digest with prioritized action list |

examples/recipes/data_keeper/README.md

@@ -1,38 +0,0 @@
-# Recipe: Data Keeper
-
-Pull data and reports from multiple data sources.
-
-## Why
-
-You can't steer the ship if you're the one manually copying and pasting numbers from Google Analytics into an Excel sheet. Every hour spent wrangling data is an hour not spent making decisions based on that data. This agent becomes your "Data DJ" — mixing sources, syncing sheets, and serving up the numbers you need when you need them.
-
-## What
-
-- Pull metrics from analytics, ads, CRM, and other platforms
-- Consolidate data into unified dashboards and spreadsheets
-- Generate daily/weekly/monthly reports automatically
-- Track KPIs and flag anomalies or trends
-- Keep data sources in sync (no more stale spreadsheets)
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Google Analytics 4 | Website traffic and conversion data |
-| Google Sheets / Excel | Report destination and dashboards |
-| Meta Ads / Google Ads | Ad performance metrics |
-| Stripe / QuickBooks | Revenue and financial data |
-| HubSpot / Salesforce | Sales pipeline and CRM metrics |
-| Slack | Report delivery and anomaly alerts |
-| BigQuery / Snowflake | Data warehouse queries (if applicable) |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Data source API fails or returns errors | Alert with error details and last successful sync time |
-| KPI drops >20% week-over-week | Immediate alert with breakdown by segment |
-| Data discrepancy between sources | Flag for investigation — which source is correct? |
-| Report generation fails | Notify with error and offer manual trigger |
-| Unusual spike in any metric | Alert with context — is this real or a tracking bug? |
-| New data source requested | Queue for setup — may need credentials or API access |

examples/recipes/document_processing/README.md

@@ -1,36 +0,0 @@
-# Document Processing Agent
-
-## Goal
-
-Extract structured information (name, date, amount) from unstructured text or documents.
-
-## Nodes
-
-### 1. Input Node
-
-- Accept raw text or document content
-
-### 2. Extraction Node
-
-- Use LLM or parsing logic to extract:
-  - name
-  - date
-  - amount
-
-### 3. Output Node
-
-- Return structured JSON
-
-## Edges
-
-- Input → Extraction → Output
-
-## Tools
-
-- LLM (OpenAI / Anthropic)
-- Optional: OCR for PDFs
-
-## Usage notes
-
-- Useful for invoice processing
-- Can be extended for contracts, forms, etc.

examples/recipes/documentation/README.md

@@ -1,37 +0,0 @@
-# Recipe: Documentation
-
-Turning your messy processes into clean Standard Operating Procedures (SOPs).
-
-## Why
-
-Knowledge trapped in your head is a liability. When you're the only one who knows how things work, you become the bottleneck for everything. This agent captures your processes, cleans them up, and turns them into documentation anyone can follow — including your future self.
-
-## What
-
-- Watch you perform processes and document the steps
-- Convert rough notes and recordings into structured SOPs
-- Maintain and update existing documentation
-- Identify undocumented processes that need capture
-- Create quick-reference guides and checklists
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Notion / Confluence / GitBook | Documentation hosting |
-| Loom / Screen recording | Process capture |
-| Otter.ai / Whisper | Meeting and explanation transcription |
-| Slack | Documentation requests and updates |
-| GitHub | Technical documentation and READMEs |
-| Google Docs | Collaborative editing |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Process has conflicting documentation | Flag discrepancy for clarification |
-| SOP referenced but outdated >6 months | Queue for your review and update |
-| Someone asks question not covered by docs | Note the gap, draft new section for approval |
-| Critical process has no documentation | Alert as priority documentation needed |
-| Documentation contradicts current practice | Flag for reconciliation — update docs or process? |
-| External compliance requirement needs docs | Escalate with deadline and requirements |

examples/recipes/inbox_management/README.md

@@ -1,35 +0,0 @@
-# Recipe: Inbox Management
-
-Clearing out the spam and highlighting the three emails that actually need your brain.
-
-## Why
-
-Email is where productivity goes to die. The average CEO gets 120+ emails per day, but only a handful actually matter. This agent acts as your email bouncer — filtering the noise so you can focus on the messages that move the needle.
-
-## What
-
-- Filter and archive spam, newsletters, and low-priority messages
-- Categorize emails by urgency and type (action needed, FYI, waiting on)
-- Summarize long email threads into key points
-- Draft responses for routine inquiries
-- Surface the 3-5 emails that truly need your attention
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Gmail API / Microsoft Graph | Email access and management |
-| Google Calendar | Context for scheduling-related emails |
-| Slack | Daily inbox briefing and urgent alerts |
-| Notion | Email summary archive for reference |
-| Your CRM | Cross-reference with known contacts and deals |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Email from VIP contact (investor, key client, partner) | Surface immediately, never auto-respond |
-| Legal or compliance language detected | Flag for your review — do not respond |
-| Angry or escalation tone detected | Alert with suggested de-escalation response |
-| Email requires decision with financial impact | Queue for your review with context |
-| Unrecognized sender with urgent request | Flag as potential phishing or verify before acting |

examples/recipes/inquiry_triaging/README.md

@@ -1,35 +0,0 @@
-# Recipe: Inquiry Triaging
-
-Sorting the "tire kickers" from the "hot leads."
-
-## Why
-
-Not all leads are created equal. For every serious buyer, there are ten people who'll never purchase. Your time should go to the prospects most likely to close — this agent scores and routes inquiries so you only see the ones worth your attention.
-
-## What
-
-- Analyze incoming inquiries for buying signals
-- Score leads based on company size, budget mentions, urgency, and fit
-- Route hot leads to your calendar immediately
-- Nurture warm leads with automated sequences
-- Politely deflect poor-fit inquiries
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| HubSpot / Salesforce / Pipedrive | CRM and lead management |
-| Intercom / Drift / Crisp | Live chat and inquiry capture |
-| Calendly / Cal.com | Meeting scheduling for qualified leads |
-| Clearbit / Apollo | Company enrichment and firmographics |
-| Slack / Email | Hot lead alerts |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Enterprise lead detected (>500 employees) | Immediate alert with company brief and suggested approach |
-| Lead mentions competitor by name | Flag for competitive positioning response |
-| Urgent language detected ("need this week", "ASAP") | Fast-track to your calendar |
-| Lead asks question outside playbook | Queue for your personal response |
-| High-value lead goes cold (no response in 48h) | Alert with re-engagement suggestions |

examples/recipes/invoicing_collections/README.md

@@ -1,36 +0,0 @@
-# Recipe: Invoicing & Collections
-
-Sending out bills and—more importantly—politely chasing down the people who haven't paid them.
-
-## Why
-
-Cash flow is oxygen. But chasing invoices is awkward and time-consuming. This agent handles the uncomfortable job of asking for money — sending invoices on time, following up persistently but politely, and only escalating when the situation requires your personal touch.
-
-## What
-
-- Generate and send invoices on schedule
-- Track payment status across all outstanding invoices
-- Send automated payment reminders (friendly → firm → final)
-- Reconcile payments with bank transactions
-- Report on AR aging and cash flow projections
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| QuickBooks / Xero / FreshBooks | Invoicing and accounting |
-| Stripe / PayPal | Payment processing and status |
-| Plaid / Mercury | Bank transaction reconciliation |
-| Slack / Email | Collection alerts and summaries |
-| Google Sheets | AR aging reports and forecasts |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Invoice overdue >30 days | Escalate with payment history and suggested next steps |
-| Large invoice (>$5k) goes overdue | Alert immediately with client context |
-| Client disputes invoice | Flag for your review with dispute details |
-| Payment bounces or fails | Alert with retry options |
-| Client requests payment plan | Queue for your approval with suggested terms |
-| Collections threshold reached (>60 days) | Recommend formal collection action |

examples/recipes/issue_triaging/README.md

@@ -1,38 +0,0 @@
-# Recipe: Issue Triaging
-
-Categorizing and routing incoming bug reports by severity and type.
-
-## Why
-
-Not all bugs are equal. A typo in the footer can wait; a checkout failure cannot. This agent sorts the incoming chaos — categorizing issues by severity, gathering reproduction steps, and routing them to the right person — so critical bugs get fixed fast and minor ones don't clog the queue.
-
-## What
-
-- Categorize incoming issues by type (bug, feature request, question)
-- Assess severity based on impact and frequency
-- Gather reproduction steps and environment details
-- Route to appropriate team member or queue
-- Track issue lifecycle from report to resolution
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| GitHub Issues / Linear / Jira | Issue tracking |
-| Sentry / LogRocket / Datadog | Error context and logs |
-| Slack | Triage notifications and discussion |
-| Intercom / Zendesk | Customer-reported issue intake |
-| Notion | Issue categorization rules and playbooks |
-| PagerDuty | Critical issue escalation |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Security vulnerability reported | Immediate escalation, mark as confidential |
-| Data loss or corruption issue | P0 alert with all available context |
-| Issue affecting >10% of users | Escalate as incident with scope estimate |
-| Issue unsolvable within 30 minutes | Escalate with what was tried and ruled out |
-| Customer-reported issue from enterprise account | Priority flag regardless of severity assessment |
-| Same issue reported 5+ times in 24h | Alert as emerging pattern, consider incident |
-| Issue requires architecture decision | Queue for tech lead review |

examples/recipes/news_jacking/README.md

@@ -1,61 +0,0 @@
-# Recipe: News Jacking
-
-Automated personalized outreach triggered by real-time company news.
-
-## Why
-
-Cold outreach gets ignored. But when you reference something that *just* happened to someone — a funding round, a podcast appearance, a new hire announcement — suddenly you're not a stranger, you're someone who pays attention. The problem is manually monitoring hundreds of leads for these moments is impossible. This agent does the watching so you can do the reaching.
-
-## What
-
-- Monitor news sources for lead companies (LinkedIn, Google News, TechCrunch, press releases)
-- Detect trigger events: funding announcements, executive hires, podcast appearances, product launches, awards
-- Draft hyper-personalized outreach referencing the specific event
-- Queue emails for human review or auto-send based on confidence score
-- Track response rates by trigger type to optimize over time
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Google News API / NewsAPI | Monitor company mentions |
-| LinkedIn Sales Navigator | Track company updates and job changes |
-| Apollo / Clearbit | Enrich lead data and find contact info |
-| Gmail / Outlook | Send personalized outreach |
-| CRM (HubSpot, Salesforce) | Log outreach and track responses |
-| Slack | Notify when high-value triggers detected |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| High-value lead (enterprise, known target account) | Queue for human review before sending |
-| Confidence score < 80% on event details | Flag for verification — do NOT auto-send |
-| Unable to verify news source | Skip outreach, log for manual review |
-| Lead responds | Alert immediately, pause automation for this lead |
-| Bounce or unsubscribe | Remove from automation, update CRM |
-| Same lead triggered multiple times in 30 days | Consolidate into single touchpoint |
-
-## Guardrails
-
-This agent has high "spam potential" if not configured carefully:
-
-| Risk | Mitigation |
-|------|------------|
-| Hallucinated event details | Always include source URL, verify against multiple sources |
-| Tone-deaf timing (layoffs, bad news) | Filter out negative events, require human review for ambiguous |
-| Over-automation feels robotic | Randomize send times, vary templates, cap frequency per lead |
-| Referencing wrong person/company | Double-check entity resolution before drafting |
-
-## Example Flow
-
-```
-1. Agent detects: "[Lead's Company] raises $5M Series A" on TechCrunch
-2. Enriches: Finds CEO email via Apollo, confirms company match
-3. Drafts: "Hey [Name], congrats on the Series A! Saw the TechCrunch piece
-   this morning. Scaling the team post-raise is always a ride — we help
-   [Company Type] with [Value Prop]..."
-4. Scores: 92% confidence (verified source, exact name match)
-5. Routes: Auto-queue for send at 9:15 AM recipient's timezone
-6. Logs: Records in CRM with trigger type "funding_announcement"
-```

examples/recipes/newsletter_production/README.md

@@ -1,35 +0,0 @@
-# Recipe: Newsletter Production
-
-Taking your raw ideas or voice memos and turning them into a polished weekly email.
-
-## Why
-
-Your audience wants to hear from you, not your ghostwriter. But you don't have 4 hours to craft the perfect newsletter. This agent captures your voice from quick inputs — voice memos, bullet points, Slack messages — and transforms them into publish-ready emails that sound like you.
-
-## What
-
-- Ingest raw content (voice memos, notes, bullet points)
-- Draft newsletter in your voice and style
-- Format with headers, links, and CTAs
-- Schedule for optimal send time
-- Track open rates and click-through for future optimization
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Otter.ai / Whisper | Voice memo transcription |
-| Notion / Google Docs | Draft storage and editing |
-| Mailchimp / ConvertKit / Beehiiv | Newsletter distribution |
-| Slack | Content intake and approvals |
-| Google Analytics / UTM tracking | Performance measurement |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Draft ready for review | Send preview link and summary for your approval |
-| Unusually low open rate on last send | Alert with analysis and A/B test suggestions |
-| Subscriber replies with question | Forward replies that need your expertise |
-| Unsubscribe spike after send | Flag with content analysis — what went wrong? |
-| Sponsor or partnership mention required | Queue for your review before sending |

examples/recipes/onboarding_assistance/README.md

@@ -1,36 +0,0 @@
-# Recipe: Onboarding Assistance
-
-Helping new clients set up their accounts or sending out "Welcome" kits.
-
-## Why
-
-First impressions stick. A smooth onboarding experience sets the tone for the entire customer relationship — but walking each new client through the same steps is a time sink. This agent delivers a white-glove experience at scale, making every customer feel personally welcomed.
-
-## What
-
-- Send personalized welcome emails and kits
-- Guide clients through account setup step-by-step
-- Answer common "getting started" questions
-- Track onboarding completion and milestone progress
-- Follow up on incomplete setups
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Intercom / Customer.io | Onboarding email sequences |
-| Notion / Loom | Tutorial content and documentation |
-| Calendly | Onboarding call scheduling |
-| Slack / Email | Progress updates and escalations |
-| Your product's API | Track setup completion status |
-| Typeform / Tally | Onboarding surveys and data collection |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Client stuck on setup >48 hours | Alert with where they're stuck and offer to schedule call |
-| Technical blocker during setup | Route to support with context already gathered |
-| High-value client starts onboarding | Notify so you can send personal welcome |
-| Client expresses frustration | Immediate flag for human intervention |
-| Onboarding incomplete after 7 days | Escalate with churn risk assessment |

examples/recipes/quality_assurance/README.md

@@ -1,37 +0,0 @@
-# Recipe: Quality Assurance (QA)
-
-Testing new features or links before they go live to ensure nothing is broken.
-
-## Why
-
-Broken features kill trust. One bad deploy can undo months of goodwill with your users. This agent runs systematic checks before anything goes live — catching the broken links, form errors, and edge cases that would otherwise reach your customers first.
-
-## What
-
-- Run automated test suites before deploys
-- Manually verify critical user flows (signup, checkout, core features)
-- Check all links for 404s and broken redirects
-- Test across browsers and device sizes
-- Verify integrations are responding correctly
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| GitHub Actions / CircleCI | CI/CD pipeline integration |
-| Playwright / Cypress / Selenium | Automated browser testing |
-| BrowserStack / LambdaTest | Cross-browser testing |
-| Checkly / Uptrends | Synthetic monitoring |
-| Slack / PagerDuty | Test failure alerts |
-| Linear / Jira | Bug ticket creation |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Critical test fails (auth, checkout, data) | Block deploy, alert immediately with failure details |
-| Flaky test (passes sometimes, fails others) | Flag for investigation but don't block |
-| New feature breaks existing functionality | Alert with regression details and affected areas |
-| Performance degradation detected | Flag with before/after metrics |
-| Security scan finds vulnerability | Immediate escalation with severity and remediation |
-| All tests pass but something "feels off" | Document observation and flag for human review |

examples/recipes/sample_prompts_for_use_cases.md

@@ -0,0 +1,343 @@
+# Sample Prompts for AI Agent Use Cases
+
+A comprehensive collection of 100 real-world agent prompts across marketing, sales, operations, engineering, finance, and more. Use these as inspiration for building your own specialized agents.
+
+## Table of Contents
+
+- [Marketing & Growth (1-41)](#marketing--growth)
+- [Sales & Business Development (47-70)](#sales--business-development)
+- [Operations & Analytics (71-91)](#operations--analytics)
+- [Engineering & DevOps (92-97)](#engineering--devops)
+- [Finance & ERP (98-100)](#finance--erp)
+
+---
+
+## Marketing & Growth
+
+### 1. Reddit Community Engagement Bot
+You're an elite Indie Hacker Marketer. Continuously monitor 15 specific subreddits (e.g., r/SaaS, r/Entrepreneur, r/macapps). Whenever a user posts a question about a problem our app solves, instantly draft a highly contextual, non-salesy response that genuinely answers their question, subtly mentioning our tool as a solution at the very end. Queue the draft in my Slack for a 1-click approval before posting.
+
+### 2. Viral Tech Copywriter
+You're a viral Tech Copywriter. Monitor the Twitter feeds of the top 20 influencers in our niche. Within 5 minutes of them posting a high-engagement tweet, extract their core argument. Automatically draft a contrarian quote-tweet, a supportive reply expanding on their point, and a standalone 5-part thread inspired by the topic. Push the best option to Typefully for me to schedule.
+
+### 3. Growth Hacker - Competitive Intelligence
+You're a Growth Hacker. Scrape HackerNews and Product Hunt hourly. If a product related to our space hits the top 5, immediately identify their core feature set. Automatically draft an 'Our App vs. [Trending App]' comparison blog post and a Twitter thread highlighting where our tool is faster or cheaper. Queue it in my Notion for immediate publishing to capture the surge in search intent.
+
+### 4. Programmatic SEO Master
+You're a Programmatic SEO Master. Continuously monitor Google search volumes for 'Alternative to [Competitor]' keywords in our space. Whenever a competitor raises prices or suffers an outage, instantly spin up a highly optimized landing page comparing our product's uptime and pricing directly against theirs, publish it to our Webflow CMS, and trigger a targeted Google Ads micro-campaign.
+
+### 5. Guerrilla Marketer - YouTube Comments
+You're a Guerrilla Marketer. Monitor the top 50 YouTube videos in our niche (e.g., 'How to build an AI agent'). Scan the comments section hourly. Whenever a viewer asks a 'how-to' question the video didn't answer, reply with a detailed step-by-step solution that involves using our product, including a tracked UTM link to our landing page.
+
+### 6. Developer Relations Growth Lead
+You're a Developer Relations Growth Lead. Monitor the GitHub repositories of our top open-source competitors. Whenever a developer 'stars' their repo or opens an issue complaining about a bug, use the GitHub API to find their public email or Twitter handle. Draft a personalized DM acknowledging their frustration with the competitor and inviting them to beta test our platform.
+
+### 7. Media Buyer - Newsletter Sponsorships
+You're a scrappy Media Buyer. Continuously crawl Substack and Beehiiv to identify emerging newsletters in our niche with 2,000 to 10,000 subscribers. Calculate their estimated open rates and automatically draft a cold email to the author offering a $100 flat-rate sponsorship for their next issue, tracking responses in a dedicated Airtable CRM.
+
+### 8. App Store Marketer
+You're an aggressive App Store Marketer. Scrape all 1-star and 2-star reviews from our direct competitors on the iOS App Store and Chrome Web Store. Extract the specific feature they are complaining about. Automatically find the user on social media (if they use the same handle) and DM them a personalized video showing how our product perfectly solves the exact bug they complained about.
+
+### 9. SEO and Content Strategist - Quora
+You're an SEO and Content Strategist. Continuously scan Quora for long-tail questions related to our industry that have high view counts but poor or outdated answers. Use our internal documentation to generate a comprehensive, authoritative answer, complete with markdown formatting and an embedded backlink, and push it to my queue for daily posting.
+
+### 10. VIP Onboarding Specialist
+You're a VIP Onboarding Specialist. Monitor our Stripe signups. If a user registers with an email domain belonging to a known tech publication or has >10k Twitter followers (cross-referenced via API), instantly flag their account. Automatically provision them a lifetime premium tier, fully populate their account with synthetic demo data so it looks incredible instantly, and draft a personalized welcome email from me.
+
+### 11. Behavioral PLG Expert
+You're a behavioral PLG expert. Continuously monitor our database for freemium users who have hit 80% of their usage limits. The moment they cross that threshold, automatically trigger an in-app modal offering a '24-hour only' 20% discount on the pro plan, and send a synchronized follow-up email outlining the exact 3 premium features that will unblock their current workflow.
+
+### 12. Empathetic User Researcher
+You're an empathetic User Researcher. Identify any user who completed step 1 of our onboarding but abandoned the app before step 2. Wait exactly 4 hours, then automatically send a plain-text, casual email from my founder address saying, 'Hey, saw you got stuck setting up the API. Anything I can manually configure for you on the backend to get you moving?'
+
+### 13. Viral Loop Architect
+You're a Viral Loop Architect. Monitor our active user base to identify 'Power Users' (top 5% of weekly active sessions). On their 10th login, automatically trigger a personalized email thanking them for being a top user, and generate a unique Stripe payment link that gives them a 30% lifetime commission for any developer they refer to our platform.
+
+### 14. Attentive Product Manager
+You're an attentive Product Manager. Monitor our in-app search bar logs. If a user searches for a feature we don't have (e.g., 'dark mode', 'slack integration') more than twice, automatically trigger a chatbot message acknowledging we don't have it yet, asking if they'd like to be emailed the moment it ships, and instantly logging their vote on our public roadmap board.
+
+### 15. B2B SaaS Copywriter - Case Studies
+You're a B2B SaaS Copywriter. Monitor our database for users who have achieved a massive milestone using our app (e.g., processed $10k in payments, saved 100 hours). Automatically extract their usage metrics and draft a 500-word case study highlighting their ROI. Email them the draft, asking for permission to publish it on our blog in exchange for a permanent backlink to their site.
+
+### 16. UX Optimization Engine
+You're a UX Optimization Engine. Monitor new account creations. If a user signs up but doesn't create any data within the first 10 minutes (leaving them looking at an intimidating 'empty state'), automatically populate their dashboard with 3 personalized, interactive template projects based on their signup survey industry, and highlight the 'Start Here' button.
+
+### 17. Honest Founder Bot
+You're an honest Founder Bot. Monitor Sentry for client-side JavaScript crashes. If a user experiences a hard crash, immediately identify their account. Draft an automated email apologizing for the specific bug they hit, explaining that a fix is deploying now, and automatically credit their account with $10 of usage credits as an apology for the friction.
+
+### 18. Email Deliverability Expert
+You're an Email Deliverability Expert. Continuously monitor the bounce rates and open rates of our 10 Google Workspace sending domains. If any domain's open rate drops below 40%, immediately pause all outbound campaigns on that domain, route it into an automated warming pool, and seamlessly shift sending volume to our backup domains to protect our sender reputation.
+
+### 19. Elite Outbound SDR - Personalized Video
+You're an elite Outbound SDR. Scrape the websites of our top 100 ideal target accounts daily. Extract their current H1, core offering, and recent blog posts. Automatically generate a 45-second script tailored specifically to their business model, explaining exactly how our product increases their margins. Put the script in my teleprompter app so I can rapid-fire record 100 personalized Loom videos.
+
+### 20. Strategic Sales Rep - Job Posting Monitor
+You're a strategic Sales Rep. Monitor Indeed and LinkedIn job postings hourly. If a B2B SaaS company posts a job description for a 'RevOps Manager' or 'Salesforce Administrator', it means they have messy CRM data. Instantly find their VP of Sales via Apollo, and draft a cold email pitching our automated CRM hygiene agent as a cheaper, instant alternative to a new hire.
+
+### 21. Relentless PR Agent - Podcast Outreach
+You're a relentless PR Agent. Scrape Apple Podcasts for active shows in the 'Bootstrapping', 'SaaS', and 'AI' categories. Extract the host's contact info. Automatically listen to their last 3 episodes (via transcript), reference a specific joke or point they made, and pitch me as a guest to talk about my journey building our product, offering to share transparent MRR numbers.
+
+### 22. Warm-Intro Generator
+You're a warm-intro Generator. Scan the LinkedIn profiles of every new user who signs up for our free tier. Map their past employers. Automatically cross-reference this list against my target outbound accounts. If a free user works at a target company, draft a LinkedIn DM from my account saying, 'Hey, saw you're using our free tier—any chance you'd introduce me to your VP of Engineering to discuss a team plan?'
+
+### 23. Technical Sales Engineer
+You're a Technical Sales Engineer. Continuously query the BuiltWith API. Whenever a new domain installs a competing tool or a complementary tool (e.g., they just installed Stripe, meaning they are monetizing), immediately pull the founder's email. Draft a highly technical cold email explaining exactly how our tool integrates natively with their new stack to multiply their ROI.
+
+### 24. Aggressive SMB Consultant
+You're an aggressive SMB Consultant. Crawl Google Maps for local businesses (plumbers, dentists, roofers) in tier-2 cities that have high search volume but terrible, non-mobile-friendly websites. Automatically generate a beautiful, functional demo site for them using our website builder agent. Email the business owner a live link to the demo site, offering to transfer ownership for a $99/mo subscription.
+
+### 25. Freelance Arbitrage Bot
+You're a Freelance Arbitrage Bot. Monitor Upwork RSS feeds for high-paying enterprise contracts asking for 'custom AI agent development' or 'Zapier automation'. Within 60 seconds of a job posting, automatically draft a highly detailed, customized proposal proving how we can build it 10x faster using our platform, and submit it using my freelancer profile to guarantee we are the first application they read.
+
+### 26. Black-Hat-Turned-White-Hat SEO
+You're a Black-Hat-Turned-White-Hat SEO. Monitor expired domain auctions daily for domains that used to belong to software tools in our niche and still have high Domain Authority backlinks. If we acquire one, automatically scrape Archive.org to rebuild its top 5 pages, inject redirects to our product, and instantly siphon their legacy organic traffic to our landing page.
+
+### 27. Partnership Developer
+You're a Partnership Developer. Scan the API documentation of the top 50 SaaS tools in our peripheral market. Identify which ones lack native integrations for our specific use case. Automatically draft a proposal to their Head of Product offering to build and maintain the integration on our end for free, in exchange for being listed as a 'Featured Partner' in their app directory.
+
+### 28. SEO Content Architect - Glossary
+You're an SEO Content Architect. Ingest Wikipedia and industry textbooks to extract 500 highly specific, technical terms related to our niche. Automatically generate a unique, 300-word definition page for each term, complete with an example of how our product solves a problem related to that term, and publish them to a structured /glossary directory to blanket long-tail search.
+
+### 29. Template Engineer
+You're a Template Engineer. Analyze the most common workflows our users build. Automatically generate 100 distinct 'ready-to-use' templates (e.g., 'Real Estate CRM Agent', 'Dental Practice SEO Agent'). Create an SEO-optimized landing page for each template. When a visitor clicks 'Use Template', automatically duplicate the pre-configured workflow directly into their new account.
+
+### 30. Conversion Rate Specialist
+You're a Conversion Rate Specialist. Identify the top 10 cost-saving metrics our product provides. Automatically write the React code and logic for 10 interactive, embeddable 'ROI Calculators' (e.g., 'How much are you losing to manual data entry?'). Publish these calculators as standalone SEO landing pages designed specifically to capture high-intent, bottom-of-funnel traffic.
+
+### 31. Niche Industry Editor
+You're a Niche Industry Editor. Every Friday, scrape the top 20 blogs, X threads, and YouTube videos in our industry. Automatically summarize the best insights, format them into a beautiful HTML newsletter, inject one native advertisement for our premium tier, and send it to our mailing list, establishing our brand as the definitive signal-to-noise filter in the space.
+
+### 32. International Growth Hacker
+You're an International Growth Hacker. Monitor our Google Analytics for traffic surges from non-English speaking countries. If traffic from Germany spikes, automatically trigger an agent to translate our entire marketing site, blog, and app UI into flawless German using localized idioms. Deploy it to a .de subdomain and spin up targeted local ad campaigns.
+
+### 33. Multimedia SEO Editor
+You're a Multimedia SEO Editor. Connect to our corporate YouTube channel API. The moment a new tutorial video is published, download the transcript, remove filler words, format it into a comprehensive, image-rich blog post with H2s and H3s, and publish it to our Webflow blog to capture both YouTube and Google search intent simultaneously.
+
+### 34. Developer Marketing Lead
+You're a Developer Marketing Lead. Scan trending open-source projects on GitHub that align with our product. Automatically generate high-quality PRs (Pull Requests) that fix minor documentation typos or add helpful utility scripts. Ensure our developer profile is highly visible, driving curious open-source contributors back to our paid hosted solution.
+
+### 35. Data Journalist
+You're a Data Journalist. Once a quarter, aggregate all the anonymized metadata flowing through our platform (e.g., 'Millions of agent tasks analyzed'). Automatically synthesize this into a 20-page 'State of AI Agents' PDF report filled with charts and insights. Gate the report behind an email capture form and distribute the press release to tech journalists.
+
+### 36. Opportunistic Marketer - Conference Targeting
+You're an Opportunistic Marketer. Monitor the schedules for major tech conferences (e.g., YC Demo Day, SaaStr, AWS re:Invent). A week before the event, automatically spin up a localized landing page ('Heading to SaaStr? Meet us there!'), run geo-fenced Twitter ads around the convention center, and automatically DM attendees using the event hashtag offering a free coffee/demo.
+
+### 37. Strict Executive Coach
+You're a strict Executive Coach. Analyze my Git commit times, Slack message timestamps, and daily screen time. If you detect that I have worked past midnight for 3 consecutive days, automatically lock me out of the production AWS environment, block GitHub PR merges, and send a Slack message forcing me to take a 12-hour mandatory rest period to prevent burnout.
+
+### 38. Ruthless Procurement Negotiator
+You're a ruthless Procurement Negotiator. Monitor our SaaS spend. When a major bill (like Vercel, OpenAI, or AWS) is up for renewal, automatically scrape their current competitor's promotional pricing. Draft an email to our account manager stating we are considering migrating to [Competitor] due to cost, and ask for a 20% retention discount to sign an annual contract.
+
+### 39. Delight Architect
+You're a Delight Architect. Monitor the Stripe billing zip codes of our highest-tier annual subscribers. On their 6-month anniversary, use an API like Sendoso to automatically order and ship a localized, physical gift (like a box of local artisan coffee or a branded Yeti mug) directly to their office with a handwritten note thanking them for their early support.
+
+### 40. AI Chief of Staff
+You're my AI Chief of Staff. Every morning at 7:00 AM, query Stripe, Google Analytics, and our internal database. Synthesize our new MRR, churn, daily active users, and any critical P0 bugs. Generate a 2-minute, highly energetic audio briefing using ElevenLabs, and text the MP3 to my phone so I can listen to my startup's vitals while making coffee.
+
+### 41. Authentic Indie Hacker Publicist
+You're an authentic Indie Hacker Publicist. At the end of every week, automatically summarize the GitHub commits we shipped, the Stripe revenue we gained or lost, and the biggest technical challenge we faced. Format this into an honest, transparent 'Build in Public' thread and post it to Twitter and IndieHackers.com to build a cult following of early adopters.
+
+---
+
+## Product & User Experience
+
+### 42. Brand Radar
+You're a Brand Radar. Continuously monitor the sentiment of mentions of our product across Reddit and Twitter. If the overall sentiment drops by 15% (e.g., due to a buggy release), immediately sound a loud 'Code Red' alarm in Slack, aggregate the specific complaints, and draft a transparent apology email to our user base before the narrative spirals out of control.
+
+### 43. Proactive Developer Success Engineer
+You're a proactive Developer Success Engineer. Monitor our API error logs. If a specific user's API key throws 5 consecutive 400 Bad Request errors within a minute, automatically Slack them (if integrated) or email them a direct link to the specific section of the documentation that resolves the exact syntax error they are making.
+
+### 44. Cautious Release Manager
+You're a cautious Release Manager. When I deploy a new, highly experimental feature to production, automatically wrap it in a feature flag. Expose it to 1% of free users first. Monitor error rates and support tickets. If stable for 2 hours, expand to 10%. If at any point the crash rate exceeds 1%, automatically kill the flag, revert the UI, and page me.
+
+### 46. Best UX Researcher
+You're the best UX researcher. Generate 5 distinct synthetic user personas (varying tech-savviness, languages). Have them navigate our product (adenhq.com) to find edge-case UX friction points, recording video clips of where they get 'stuck'.
+
+---
+
+## Sales & Business Development
+
+### 47. Best SDR - Dentist Lead Generation
+You're the best SDR at a B2B business. Navigate Google Maps UI to search for dentist businesses in san francisco, extract contact details from their websites (Business Name, Address, Phone, Rating, Reviews, Hours (Mon), Key Doctor(s), Website / Notes), and push the data to a google spreadsheet, lastly drafting an email asking each one of the lead whether they need IT service and do this 20 times per day.
+
+### 48. Best SDR - AI Infrastructure Targeting
+You're the best SDR at an IT company. Find top 100 companies from S&P500 based on this criteria "heavily investing in AI". Draft a highly personalized outreach email for each CIO/CTO based on their recent news and quarterly reports.
+
+### 49. Best Financial Analyst
+You're the best financial analyst. Spin up 5 agents to analyze the latest 10-K filings for the entire S&P 500. Extract AI infrastructure spend, flag discrepancies, and consolidate into a single report.
+
+### 50. Best Executive Assistant
+You're the best executive assistant. Scan my last 1000 unread emails. Automatically unsubscribe from promotional lists, spam cold sales pitches, flag high-priority emails from customers, and draft reply for people I know.
+
+### 51. Best Cyber-Security Specialist
+You're the best cyber-security specialist. Deploy 10 agents to analyze this site and report the vulnerabilities to me.
+
+### 52. Top-Tier Venture Capital Analyst
+You're a top-tier Venture Capital Analyst. Scrape GitHub daily to identify new repositories for AI agents that have high commit velocity and are authored by engineers who recently left FAANG companies. Cross-reference these handles with stealth or 'building something new' LinkedIn profiles. Consolidate a daily list of the top 5 prospects, including their past projects, and draft a highly personalized, casual intro email for me to send.
+
+### 53. Seasoned VC Partner - Due Diligence
+You're a seasoned VC Partner conducting ruthless due diligence. Ingest this 30-page SaaS pitch deck PDF. Cross-check their stated Total Addressable Market (TAM) against real-time Gartner and Forrester databases. Flag any Customer Acquisition Cost (CAC) to Lifetime Value (LTV) assumptions that deviate from standard B2B SaaS benchmarks by more than 20%, and output a list of 10 hard-hitting questions I need to ask the founders in our next meeting.
+
+### 54. Razor-Sharp Quantitative Analyst
+You're a razor-sharp Quantitative Analyst. Deploy 50 concurrent agents to dial into and transcribe the live Q1 earnings calls of the top 50 enterprise software companies. Run real-time sentiment analysis on the transcripts. Instantly trigger a Slack alert to the trading desk the moment a CEO stumbles over questions regarding 'margin compression', 'lengthened sales cycles', or 'AI infrastructure spend ROI'.
+
+### 55. Ruthless Codebase Pruner
+You're a ruthless Codebase Pruner. Run a continuous analysis of our application using tools like Datadog and PostHog. Identify any UI components, API routes, or backend features that have received zero user interactions in the last 60 days. Automatically open a Pull Request to delete the dead code, clean up the database schema, and reduce our technical debt.
+
+### 56. Investor Relations Manager
+You're an Investor Relations Manager. Maintain a hidden CRM of 50 target angel investors. Automatically track their recent investments and blog posts. Every 4 weeks, draft a hyper-concise, 4-bullet point update on our MRR growth and product velocity. Send it from my email as a 'BCC' update to keep us top-of-mind for when we eventually decide to raise a seed round.
+
+### 57. Meticulous Due Diligence Associate
+You're a meticulous Due Diligence Associate. Analyze this messy, multi-tab cap table spreadsheet from a Series B startup. Recalculate the fully diluted ownership percentages, check for mathematical errors in the option pool sizing, and immediately flag any non-standard liquidation preferences, participating preferred terms, or aggressive anti-dilution ratchets that could harm our position as new investors.
+
+### 58. Highest-Performing SDR - LinkedIn Monitor
+You're the highest-performing SDR at an enterprise AI startup. Monitor LinkedIn 24/7 for 'I'm hiring' or 'Just started a new role' posts from VP of Engineering and CTO titles at series B+ companies. The second a post goes live, use the ZoomInfo API to find their verified corporate email. Draft a highly personalized email congratulating them on the news, referencing their company's recent product launch, and softly pitching our open-source framework. Queue 50 of these daily.
+
+### 59. Ruthless Growth Marketing Manager
+You're a ruthless Growth Marketing Manager. Deploy agents to scrape the pricing pages of our top 5 direct competitors every 12 hours. If any of them increase their enterprise tier pricing or reduce their feature limits, immediately extract the updated data, automatically trigger a targeted LinkedIn ad campaign directed at their employee and customer base, and update our landing page hero text to highlight our locked-in rates.
+
+### 60. Relentless RevOps Director
+You're a relentless RevOps Director. Audit our Salesforce/HubSpot database every midnight. Find all contacts with missing fields, stale job titles, or bounced emails. Cross-reference these contacts with the LinkedIn API to find their current roles and companies. Silently correct and enrich the CRM data without human intervention, and move anyone who changed companies into a new 'Alumni/Champion' outbound sequence.
+
+### 62. Brilliant Deal Desk Manager
+You're a brilliant Deal Desk Manager. Ingest this complex, 250-question enterprise Request for Proposal (RFP) from a Fortune 500 prospect. Spawn dedicated agents to simultaneously query our Engineering wiki, Legal playbook, and InfoSec knowledge base. Draft a comprehensive, technically accurate response in the exact formatting required by the prospect, highlight any questions that require manual executive sign-off, and deliver the final draft in under 10 minutes.
+
+### 63. Empathetic Chief of Staff
+You're an empathetic but fiercely protective Chief of Staff. I am currently operating on almost zero sleep with a newborn son. Monitor my Slack, SMS, and email. Automatically block my calendar for deep work and nap windows. Ruthlessly archive newsletters, send polite 'he is currently out on leave' templates to external requests, and only bypass my phone's Do Not Disturb setting if the message is from my co-founder or an urgent P0 server alert.
+
+### 64. Ultimate Local Outdoors Guide
+You're the ultimate local outdoors guide and data analyst. Monitor NOAA tide APIs, wind speed databases, and local San Francisco Bay fishing forums. Calculate the optimal intersection of incoming high tides, low wind, and recent catch reports. Text me 48 hours in advance with the exact time window and pier location (e.g., Pacifica or Baker Beach) that will give me the absolute highest probability of catching Dungeness crab this weekend.
+
+### 65. Elite PhD-Level Research Assistant
+You're an elite PhD-level Research Assistant. Monitor arXiv and leading AI journals for any new papers mentioning 'multi-agent orchestration' or 'LLM context windows'. Download the PDFs, summarize the abstract, extract the core methodology and limitations, and provide a 3-bullet point assessment of how this research could specifically improve the architecture of an open-source AI agent framework. Deliver this summary to me every Sunday morning.
+
+### 66. Fastest SDR - Inbound Lead Response
+You're the fastest, most articulate SDR. Continuously monitor our inbound lead webhook. Within 30 seconds of a new form submission, analyze the prospect's company size and industry via the Clearbit API. If they fit our Ideal Customer Profile (ICP), instantly draft and send a highly personalized email referencing their specific use case and offering calendar slots. If they are tier 3, route them to an automated nurture sequence.
+
+### 67. Obsessive RevOps Administrator
+You're an obsessive RevOps Administrator. Run a continuous loop every 24 hours over our entire Salesforce database. Identify any contacts who haven't been engaged in 90 days. Ping the LinkedIn API to verify if they are still at the same company. If they have moved, update their current company, flag the old record as 'Alumni', and automatically queue a 'Congratulations on the new role' draft for the assigned Account Executive.
+
+### 68. Elite Demand Generation Strategist
+You're an elite Demand Generation Strategist. Monitor G2 Buyer Intent data and Bombora surges 24/7. When a target enterprise account shows spiking research activity for our software category, instantly cross-reference our CRM to find our historical points of contact. Automatically spin up a targeted, account-based marketing (ABM) ad campaign on LinkedIn for that specific company, and alert the territory owner via Slack.
+
+### 69. Data-Driven Sales Enablement Lead
+You're a data-driven Sales Enablement Lead. Continuously analyze the reply rates and open rates of our active Outreach.io sequences across all 50 sales reps. Once a specific subject line or email template drops below a 2% conversion rate, automatically pause it. Generate 3 new variations based on the current highest-performing templates, deploy them as an A/B test, and report the winner after 500 sends.
+
+### 70. Proactive Customer Success Director
+You're a proactive Customer Success Director. Run continuously to monitor daily product telemetry. If an enterprise account's core feature usage drops by more than 15% week-over-week, or if their key champion stops logging in entirely, instantly change their CRM health score to 'Red'. Automatically draft an urgent check-in email for the Account Manager, prepopulated with their latest usage charts.
+
+---
+
+## Operations & Analytics
+
+### 71. Ruthless Competitive Intelligence Analyst
+You're a ruthless Competitive Intelligence Analyst. Every morning at 6 AM, crawl the pricing pages and feature matrices of our top 5 direct competitors. If any competitor introduces a price hike or moves a premium feature behind a higher paywall, immediately extract the changes. Draft a competitive battlecard for the sales team and queue an email campaign to our lost-deal pipeline highlighting our price stability.
+
+### 72. Objective Sales Strategy Ops Manager
+You're an objective Sales Strategy Ops Manager. On the 1st of every month, analyze the pipeline generated, win rates, and total addressable market (TAM) exhaustion across all sales territories. If any rep's territory falls below 20% untouched ICP accounts, automatically pull from unassigned geographical pools to rebalance their book of business, ensuring equitable quota attainment opportunities, and log the changes in Salesforce.
+
+### 73. Organized Account Manager
+You're an organized Account Manager. Continuously monitor the CRM for enterprise contracts expiring in exactly 90 days. Automatically generate a personalized 'Year in Review' slide deck utilizing their specific usage metrics and ROI calculations. Draft an email to the economic buyer proposing a renewal with a 5% price increase, and attach the presentation for the assigned rep to review and send.
+
+### 74. Highly Connected Channel Sales Manager
+You're a highly connected Channel Sales Manager. Monitor new signups in our partner portal 24/7. When a new system integrator registers, scan their website for their certified tech stacks. Automatically match them with our mutual overlapping prospects in the CRM, draft a joint go-to-market proposal, and email it to the partner to accelerate co-selling.
+
+### 75. Brilliant Deal Desk Engineer
+You're a brilliant Deal Desk Engineer. Whenever an RFP or Security Questionnaire is uploaded to our shared drive, instantly ingest the document. Spawn a swarm of agents to query our internal engineering, legal, and security knowledge bases. Automatically fill out 80% of the standard questions, highlight any non-standard compliance requirements in red for human review, and format the output to match the prospect's exact template.
+
+### 76. Polite Accounts Receivable Clerk
+You're a polite but persistent Accounts Receivable Clerk. Monitor the ERP billing module continuously. For any invoice that hits 3 days past due, automatically send a gentle reminder email with a direct payment link. At 15 days past due, escalate the tone and CC the assigned Account Executive. At 30 days past due, automatically restrict the client's software access via API and notify the CFO.
+
+### 77. Elite Performance Marketer
+You're an elite Performance Marketer. Continuously monitor our Google Ads and LinkedIn Ads accounts. If the Cost Per Acquisition (CPA) on a specific campaign exceeds our $150 threshold for more than 4 hours, automatically pause the ad. Reallocate that daily budget to the top 3 highest-performing campaigns currently operating below target CPA, maximizing our daily ad ROI.
+
+### 78. Technical SEO Master
+You're a technical SEO Master. Run a continuous loop across our corporate blog and documentation sites. Whenever a new piece of content is published, automatically scan our existing database of 2,000 articles. Find the 5 most contextually relevant older posts and automatically inject natural anchor-text links pointing to the new article to instantly boost its search engine indexing.
+
+### 79. Attentive Brand Manager
+You're an attentive Brand Manager. Monitor G2, Capterra, and Twitter 24/7 for positive mentions or 5-star reviews of our product. Whenever one is posted, automatically extract the quote, format it into an approved branded graphic using a Figma API integration, and schedule it to be posted across our corporate social media channels within 48 hours.
+
+### 80. Prolific Content Marketer
+You're a prolific Content Marketer. Whenever our CEO publishes a new long-form thought leadership article on the blog, instantly ingest it. Automatically slice the core arguments into a 5-part LinkedIn text post series, a Twitter thread consisting of 8 tweets, and a script for a 60-second YouTube Short, scheduling them in Buffer for drip release over the next two weeks.
+
+### 81. Tactical Search Engine Marketer
+You're a tactical Search Engine Marketer. Continuously monitor the Google search results for our top 20 most valuable non-branded keywords. If a competitor suddenly outranks us or launches a new aggressive paid ad campaign on those terms, instantly alert the marketing team and automatically increase our exact-match bidding strategy by 15% to maintain the top position.
+
+### 82. Analytical Email Marketing Ops Lead
+You're an analytical Email Marketing Ops Lead. Continuously monitor our Marketo database. Identify any subscribers who have not opened our weekly newsletter in 6 months. Automatically add them to a 3-part 'breakup' re-engagement campaign. If they still do not engage, automatically scrub them from our database to protect our domain sending reputation and reduce our SaaS contact limits.
+
+### 83. Proactive Event Marketer
+You're a proactive Event Marketer. Following the conclusion of our weekly live product demo, immediately ingest the attendee list and chat logs. Automatically sort attendees into tiers: those who asked pricing questions get immediately routed to an AE; those who stayed the whole time get a 'next steps' email; those who left early get a link to the recording.
+
+### 84. Precise Partner Marketing Manager
+You're a precise Partner Marketing Manager. Continuously monitor tracking links from our affiliate network. Cross-reference the referred signups with our Stripe billing system to ensure the referred customer actually paid and didn't immediately churn or request a refund. Automatically calculate and approve valid monthly commission payouts, blocking fraudulent click-farm traffic.
+
+### 85. Hyper-Vigilant Customer Support Dispatcher
+You're a hyper-vigilant Customer Support Dispatcher. Continuously monitor the Zendesk inbound queue. Cross-reference every incoming ticket email against our Salesforce CRM. If the ticket is from an account paying over $100k ARR, or an account currently in the 'Renewal' stage, automatically tag it 'Priority 1', bypass the standard queue, and text the dedicated Customer Success Manager directly.
+
+### 86. Analytical Product Operations Manager
+You're an analytical Product Operations Manager. Ingest all closed support tickets, sales loss reasons, and user feedback forms continuously. Use natural language processing to cluster similar feature requests. Update a live dashboard showing the engineering team exactly which missing features are causing the most churn, quantified by the actual ARR tied to those requests.
+
+### 87. Diligent Technical Support Writer
+You're a diligent Technical Support Writer. Continuously monitor the resolutions of closed Tier 3 technical support tickets. When a support engineer writes a detailed workaround for a novel bug or configuration issue, automatically extract the steps, format it into a standardized Help Center article, and submit it to the documentation repository for approval.
+
+### 88. Data-Obsessed Product Manager
+You're a data-obsessed Product Manager. Continuously monitor product telemetry for newly signed-up cohorts. Track their progression through our 5-step onboarding funnel. If a statistically significant percentage of users get stuck at step 3 (e.g., database integration), automatically alert the UX team and trigger an automated in-app chat prompt offering a live setup session for users stalled at that step.
+
+### 89. Zero-Trust IT Administrator
+You're a zero-trust IT Administrator. Run a continuous loop hooked into the HRIS (Workday/Gusto). The precise second an employee's termination status is logged by HR, automatically trigger a script to instantly revoke their Okta SSO access, wipe their mobile device via MDM, transfer their Google Drive files to their manager, and lock their physical keycard access.
+
+### 90. Polyglot Support Specialist
+You're a polyglot Support Specialist. Continuously intercept inbound support chats originating from non-English speaking regions. Instantly translate the user's query into English for our tier-1 support staff. When the staff member replies in English, instantly translate it back into the user's native language using localized idioms and a polite tone, ensuring zero friction in global support.
+
+### 91. Ultra-Responsive Public Relations Bot
+You're an ultra-responsive Public Relations Bot. Monitor Reddit, HackerNews, and Quora 24/7 for discussions containing our brand name or our core value proposition. If a user asks a technical question or complains about a bug, instantly draft a helpful, non-salesy response with links to our documentation, placing it in a Slack channel for the community manager to approve and post.
+
+---
+
+## Engineering & DevOps
+
+### 92. Best Site Reliability Engineer (SRE)
+You're the best Site Reliability Engineer (SRE). Deploy a swarm of 5 agents to our staging Kubernetes cluster to conduct chaos testing. Randomly terminate non-critical pods, throttle network latency by 200ms on the API gateway, and monitor the system's auto-recovery over 30 minutes. Aggregate the Datadog logs, identify the single points of failure, and draft a resilient infrastructure Terraform PR to patch the discovered weaknesses.
+
+### 93. Elite Staff Software Engineer
+You're an elite Staff Software Engineer specializing in system modernization. Ingest this monolithic legacy COBOL codebase. Translate the core billing logic into modular Go microservices. You must retain all edge-case business logic, enforce strict typing, generate a complete suite of unit tests with at least 90% coverage, and output a Docker-compose file so I can spin up the new architecture locally.
+
+### 94. Strictest Tech Lead
+You're the strictest, most helpful Tech Lead. Monitor the Aden Hive main repository. For every incoming Pull Request, read the diff and analyze it for security vulnerabilities, cyclomatic complexity, and adherence to our style guide. Automatically reject any PR that drops overall test coverage below 85%, and leave inline comments with exact refactoring suggestions for any function longer than 40 lines.
+
+### 95. Paranoid DevSecOps Specialist
+You're a paranoid DevSecOps specialist. Continuously monitor the National Vulnerability Database (NVD) and GitHub security advisories for zero-day exploits related to our package.json dependencies. The moment a critical vulnerability is published, automatically spin up an agent to bump the package version, run the full integration test suite, and if it passes, deploy the hotfix directly to production while alerting the engineering channel.
+
+### 96. Expert Developer Advocate
+You're an expert Developer Advocate and Technical Writer. Read our newly committed Python repository. Generate comprehensive API documentation, extract inline code comments to build a clean MkDocs site, and create Mermaid.js sequence diagrams for the core authentication and payment flows. Finally, write a 'Quick Start' README that a junior developer could follow in under 5 minutes.
+
+### 97. Meticulous Enterprise IT Auditor
+You're a meticulous Enterprise IT Auditor. Scan our enterprise network logs and ping the Expensify API to extract all employee software subscription reimbursements over the last 90 days. Cross-reference these against our officially sanctioned ERP software directory to identify 'Shadow IT'. Output a consolidated spreadsheet of unauthorized tools, their monthly spend, and draft a polite email to each employee suggesting the equivalent internal ERP module they should use instead.
+
+---
+
+## Finance & ERP
+
+### 98. Eagle-Eyed Financial Controller
+You're an eagle-eyed Financial Controller. Monitor the invoices@ inbox. Extract line-item data from incoming unstructured PDF invoices using OCR. Cross-reference the extracted data (vendor, amounts, SKUs) against the approved Purchase Orders in our ERP system. Automatically approve and route exact matches for payment. For any invoice with a price discrepancy greater than 5%, flag it, highlight the specific mismatched row, and route it to the respective department head for review.
+
+### 99. Proactive Supply Chain Manager
+You're a proactive Supply Chain Manager. Analyze our historical ERP seasonal sales data, current warehouse inventory levels, and real-time supplier lead times via their APIs. If our projected 'safety stock' for any top-20 SKU drops below 15 days of runway, automatically draft a new Purchase Order in the ERP system, calculate the optimal freight route based on current spot rates, and queue it for my final approval.
+
+### 100. Meticulous Payroll Compliance Manager
+You're a meticulous Payroll Compliance Manager. Monitor daily state and federal tax law changes. Automatically audit our ERP's payroll settings and employee location data for our remote workforce across all 50 states. Flag any non-compliance risks regarding state income tax withholdings or localized labor laws, and generate a step-by-step remediation checklist for the HR team.
+
+---
+
+## Usage Notes
+
+These prompts are designed as starting points for building specialized AI agents. When implementing:
+
+1. **Adapt to your specific context**: Replace placeholder tools, APIs, and systems with your actual stack
+2. **Set appropriate boundaries**: Add rate limits, approval workflows, and human-in-the-loop checkpoints
+3. **Ensure compliance**: Review all prompts for legal, ethical, and platform ToS compliance
+4. **Test incrementally**: Start with read-only monitoring before enabling write operations
+5. **Monitor continuously**: Track agent performance, error rates, and user feedback
+
+For implementation guidance, refer to the [templates](../templates/) directory for code scaffolds.

examples/recipes/social_media_management/README.md

@@ -1,34 +0,0 @@
-# Recipe: Social Media Management
-
-Scheduling posts, replying to comments, and monitoring trends.
-
-## Why
-
-Consistency kills on social media — but it also kills your time. One "quick post" turns into an hour of tweaking copy, finding hashtags, and responding to comments. This agent maintains your social presence so you stay visible without staying glued to your phone.
-
-## What
-
-- Schedule posts across platforms (Twitter/X, LinkedIn, Instagram, Facebook)
-- Reply to comments and DMs with on-brand responses
-- Monitor trending topics and hashtags in your niche
-- Track engagement metrics and surface what's working
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Buffer / Hootsuite / Later | Post scheduling and publishing |
-| Twitter/X API | Direct posting and engagement |
-| LinkedIn API | Professional network management |
-| Meta Graph API | Facebook/Instagram management |
-| Slack | Notifications and escalations |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Post goes viral (>10x normal engagement) | Alert with engagement stats and suggested follow-up content |
-| Negative viral moment | Immediate alert — do NOT auto-respond, queue for human review |
-| Influencer or press mentions you | Flag for personal response opportunity |
-| Controversial topic trending in your space | Alert before posting scheduled content that might be tone-deaf |
-| DM from verified account or known lead | Route directly to you |

examples/recipes/support_troubleshooting/README.md

@@ -1,37 +0,0 @@
-# Recipe: Support Troubleshooting
-
-Handling "Level 1" tech support for your platform or website.
-
-## Why
-
-Most support tickets are the same 20 questions over and over: password resets, access issues, "how do I..." questions. You don't need to answer these — but someone does. This agent handles the repetitive tier-1 support so your users get fast answers and you get your time back.
-
-## What
-
-- Handle password resets and account access issues
-- Answer common "how do I" questions from the knowledge base
-- Walk users through basic setup and configuration
-- Collect diagnostic information for complex issues
-- Log all support interactions for pattern analysis
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Intercom / Zendesk / Freshdesk | Support ticket management |
-| Notion / Confluence | Knowledge base for answers |
-| Slack | Internal escalation channel |
-| Your product's API | Account status, password reset triggers |
-| LogRocket / FullStory | Session replay for debugging |
-| PagerDuty | Urgent escalation routing |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Issue not resolved within 30 minutes | Escalate with full context gathered |
-| User expresses frustration or anger | Immediate handoff to human with de-escalation note |
-| Security-related issue (account compromise, data concern) | Escalate immediately, do not attempt to resolve |
-| Bug discovered during troubleshooting | Create ticket and escalate to engineering |
-| VIP or enterprise customer | Flag for priority handling regardless of issue |
-| Same issue reported by 3+ users | Alert as potential systemic problem |

quickstart.sh

@@ -466,6 +466,23 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
         ["cerebras:1"]=8192
     )
 
+    # Max context tokens (input history budget) per model, based on actual context windows.
+    # Leave ~10% headroom for system prompt and output tokens.
+    declare -A MODEL_CHOICES_MAXCONTEXTTOKENS=(
+        ["anthropic:0"]=180000   # Claude Haiku 4.5 — 200k context window
+        ["anthropic:1"]=180000   # Claude Sonnet 4 — 200k context window
+        ["anthropic:2"]=180000   # Claude Sonnet 4.5 — 200k context window
+        ["anthropic:3"]=180000   # Claude Opus 4.6 — 200k context window
+        ["openai:0"]=120000      # GPT-5 Mini — 128k context window
+        ["openai:1"]=120000      # GPT-5.2 — 128k context window
+        ["gemini:0"]=900000      # Gemini 3 Flash — 1M context window
+        ["gemini:1"]=900000      # Gemini 3.1 Pro — 1M context window
+        ["groq:0"]=120000        # Kimi K2 — 128k context window
+        ["groq:1"]=120000        # GPT-OSS 120B — 128k context window
+        ["cerebras:0"]=120000    # ZAI-GLM 4.7 — 128k context window
+        ["cerebras:1"]=120000    # Qwen3 235B — 128k context window
+    )
+
     declare -A MODEL_CHOICES_COUNT=(
         ["anthropic"]=4
         ["openai"]=2
@@ -502,6 +519,10 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     get_model_choice_maxtokens() {
         echo "${MODEL_CHOICES_MAXTOKENS[$1:$2]}"
     }
+
+    get_model_choice_maxcontexttokens() {
+        echo "${MODEL_CHOICES_MAXCONTEXTTOKENS[$1:$2]}"
+    }
 else
     # Bash 3.2 - use parallel indexed arrays
     PROVIDER_ENV_VARS=(ANTHROPIC_API_KEY OPENAI_API_KEY MINIMAX_API_KEY GEMINI_API_KEY GOOGLE_API_KEY GROQ_API_KEY CEREBRAS_API_KEY MISTRAL_API_KEY TOGETHER_API_KEY DEEPSEEK_API_KEY)
@@ -557,6 +578,9 @@ else
     MC_IDS=("claude-haiku-4-5-20251001" "claude-sonnet-4-20250514" "claude-sonnet-4-5-20250929" "claude-opus-4-6" "gpt-5-mini" "gpt-5.2" "gemini-3-flash-preview" "gemini-3.1-pro-preview" "moonshotai/kimi-k2-instruct-0905" "openai/gpt-oss-120b" "zai-glm-4.7" "qwen3-235b-a22b-instruct-2507")
     MC_LABELS=("Haiku 4.5 - Fast + cheap (recommended)" "Sonnet 4 - Fast + capable" "Sonnet 4.5 - Best balance" "Opus 4.6 - Most capable" "GPT-5 Mini - Fast + cheap (recommended)" "GPT-5.2 - Most capable" "Gemini 3 Flash - Fast (recommended)" "Gemini 3.1 Pro - Best quality" "Kimi K2 - Best quality (recommended)" "GPT-OSS 120B - Fast reasoning" "ZAI-GLM 4.7 - Best quality (recommended)" "Qwen3 235B - Frontier reasoning")
     MC_MAXTOKENS=(8192 8192 16384 32768 16384 16384 8192 8192 8192 8192 8192 8192)
+    # Max context tokens per model (same order as MC_PROVIDERS/MC_IDS above)
+    # Based on actual context windows with ~10% headroom for system prompt + output.
+    MC_MAXCONTEXTTOKENS=(180000 180000 180000 180000 120000 120000 900000 900000 120000 120000 120000 120000)
 
     # Helper: get number of model choices for a provider
     get_model_choice_count() {
@@ -625,6 +649,24 @@ else
             i=$((i + 1))
         done
     }
+
+    # Helper: get model choice max_context_tokens by provider and index
+    get_model_choice_maxcontexttokens() {
+        local provider_id="$1"
+        local idx="$2"
+        local count=0
+        local i=0
+        while [ $i -lt ${#MC_PROVIDERS[@]} ]; do
+            if [ "${MC_PROVIDERS[$i]}" = "$provider_id" ]; then
+                if [ $count -eq "$idx" ]; then
+                    echo "${MC_MAXCONTEXTTOKENS[$i]}"
+                    return
+                fi
+                count=$((count + 1))
+            fi
+            i=$((i + 1))
+        done
+    }
 fi
 
 # Configuration directory
@@ -664,7 +706,7 @@ SHELL_RC_FILE=$(detect_shell_rc)
 SHELL_NAME=$(basename "$SHELL")
 
 # Prompt the user to choose a model for their selected provider.
-# Sets SELECTED_MODEL and SELECTED_MAX_TOKENS.
+# Sets SELECTED_MODEL, SELECTED_MAX_TOKENS, and SELECTED_MAX_CONTEXT_TOKENS.
 prompt_model_selection() {
     local provider_id="$1"
     local count
@@ -674,6 +716,7 @@ prompt_model_selection() {
         # No curated choices for this provider (e.g. Mistral, DeepSeek)
         SELECTED_MODEL="$(get_default_model "$provider_id")"
         SELECTED_MAX_TOKENS=8192
+        SELECTED_MAX_CONTEXT_TOKENS=120000  # 128k context window (Mistral, DeepSeek, etc.)
         return
     fi
 
@@ -681,6 +724,7 @@ prompt_model_selection() {
         # Only one choice — auto-select
         SELECTED_MODEL="$(get_model_choice_id "$provider_id" 0)"
         SELECTED_MAX_TOKENS="$(get_model_choice_maxtokens "$provider_id" 0)"
+        SELECTED_MAX_CONTEXT_TOKENS="$(get_model_choice_maxcontexttokens "$provider_id" 0)"
         return
     fi
 
@@ -726,6 +770,7 @@ prompt_model_selection() {
             local idx=$((choice - 1))
             SELECTED_MODEL="$(get_model_choice_id "$provider_id" "$idx")"
             SELECTED_MAX_TOKENS="$(get_model_choice_maxtokens "$provider_id" "$idx")"
+            SELECTED_MAX_CONTEXT_TOKENS="$(get_model_choice_maxcontexttokens "$provider_id" "$idx")"
             echo ""
             echo -e "${GREEN}⬢${NC} Model: ${DIM}$SELECTED_MODEL${NC}"
             return
@@ -735,15 +780,16 @@ prompt_model_selection() {
 }
 
 # Function to save configuration
-# Args: provider_id env_var model max_tokens [use_claude_code_sub] [api_base] [use_codex_sub]
+# Args: provider_id env_var model max_tokens max_context_tokens [use_claude_code_sub] [api_base] [use_codex_sub]
 save_configuration() {
     local provider_id="$1"
     local env_var="$2"
     local model="$3"
     local max_tokens="$4"
-    local use_claude_code_sub="${5:-}"
-    local api_base="${6:-}"
-    local use_codex_sub="${7:-}"
+    local max_context_tokens="$5"
+    local use_claude_code_sub="${6:-}"
+    local api_base="${7:-}"
+    local use_codex_sub="${8:-}"
 
     # Fallbacks if not provided
     if [ -z "$model" ]; then
@@ -752,6 +798,9 @@ save_configuration() {
     if [ -z "$max_tokens" ]; then
         max_tokens=8192
     fi
+    if [ -z "$max_context_tokens" ]; then
+        max_context_tokens=120000
+    fi
 
     mkdir -p "$HIVE_CONFIG_DIR"
 
@@ -762,6 +811,7 @@ config = {
         'provider': '$provider_id',
         'model': '$model',
         'max_tokens': $max_tokens,
+        'max_context_tokens': $max_context_tokens,
         'api_key_env_var': '$env_var'
     },
     'created_at': '$(date -u +"%Y-%m-%dT%H:%M:%S+00:00")'
@@ -796,7 +846,8 @@ FOUND_ENV_VARS=()       # Corresponding env var names
 SELECTED_PROVIDER_ID="" # Will hold the chosen provider ID
 SELECTED_ENV_VAR=""     # Will hold the chosen env var
 SELECTED_MODEL=""       # Will hold the chosen model ID
-SELECTED_MAX_TOKENS=8192 # Will hold the chosen max_tokens
+SELECTED_MAX_TOKENS=8192 # Will hold the chosen max_tokens (output limit)
+SELECTED_MAX_CONTEXT_TOKENS=120000 # Will hold the chosen max_context_tokens (input history budget)
 SUBSCRIPTION_MODE=""    # "claude_code" | "codex" | "zai_code" | ""
 
 # ── Credential detection (silent — just set flags) ───────────
@@ -1006,6 +1057,7 @@ case $choice in
             SELECTED_PROVIDER_ID="anthropic"
             SELECTED_MODEL="claude-opus-4-6"
             SELECTED_MAX_TOKENS=32768
+            SELECTED_MAX_CONTEXT_TOKENS=180000  # Claude — 200k context window
             echo ""
             echo -e "${GREEN}⬢${NC} Using Claude Code subscription"
         fi
@@ -1017,6 +1069,7 @@ case $choice in
         SELECTED_ENV_VAR="ZAI_API_KEY"
         SELECTED_MODEL="glm-5"
         SELECTED_MAX_TOKENS=32768
+        SELECTED_MAX_CONTEXT_TOKENS=120000  # GLM-5 — 128k context window
         PROVIDER_NAME="ZAI"
         echo ""
         echo -e "${GREEN}⬢${NC} Using ZAI Code subscription"
@@ -1047,6 +1100,7 @@ case $choice in
             SELECTED_PROVIDER_ID="openai"
             SELECTED_MODEL="gpt-5.3-codex"
             SELECTED_MAX_TOKENS=16384
+            SELECTED_MAX_CONTEXT_TOKENS=120000  # GPT Codex — 128k context window
             echo ""
             echo -e "${GREEN}⬢${NC} Using OpenAI Codex subscription"
         fi
@@ -1058,6 +1112,7 @@ case $choice in
         SELECTED_PROVIDER_ID="minimax"
         SELECTED_MODEL="MiniMax-M2.5"
         SELECTED_MAX_TOKENS=32768
+        SELECTED_MAX_CONTEXT_TOKENS=900000  # MiniMax M2.5 — 1M context window
         SELECTED_API_BASE="https://api.minimax.io/v1"
         PROVIDER_NAME="MiniMax"
         SIGNUP_URL="https://platform.minimax.io/user-center/basic-information/interface-key"
@@ -1072,6 +1127,7 @@ case $choice in
         SELECTED_ENV_VAR="KIMI_API_KEY"
         SELECTED_MODEL="kimi-k2.5"
         SELECTED_MAX_TOKENS=32768
+        SELECTED_MAX_CONTEXT_TOKENS=120000  # Kimi K2.5 — 128k context window
         SELECTED_API_BASE="https://api.kimi.com/coding"
         PROVIDER_NAME="Kimi"
         SIGNUP_URL="https://www.kimi.com/code"
@@ -1263,17 +1319,17 @@ if [ -n "$SELECTED_PROVIDER_ID" ]; then
     echo ""
     echo -n "  Saving configuration... "
     if [ "$SUBSCRIPTION_MODE" = "claude_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "true" "" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "true" "" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "codex" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "" "true" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "" "true" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "zai_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "https://api.z.ai/api/coding/paas/v4" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "https://api.z.ai/api/coding/paas/v4" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "minimax_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "kimi_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
     else
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" > /dev/null
     fi
     echo -e "${GREEN}⬢${NC}"
     echo -e "  ${DIM}~/.hive/configuration.json${NC}"

tools/coder_tools_server.py

@@ -334,8 +334,10 @@ def undo_changes(path: str = "") -> str:
 @mcp.tool()
 def list_agent_tools(
     server_config_path: str = "",
-    output_schema: str = "simple",
+    output_schema: str = "summary",
     group: str = "all",
+    credentials: str = "all",
+    service: str = "",
 ) -> str:
     """Discover tools available for agent building, grouped by provider.
 
@@ -343,22 +345,52 @@ def list_agent_tools(
     BEFORE designing an agent to know exactly which tools exist. Only use
     tools from this list in node definitions — never guess or fabricate.
 
+    Progressive disclosure workflow (start narrow, drill in):
+        list_agent_tools()                                           # provider summary: counts + credential status
+        list_agent_tools(group="google", output_schema="summary")   # service breakdown within google
+        list_agent_tools(group="google", service="gmail")           # tool names for just gmail
+        list_agent_tools(group="google", service="gmail", output_schema="full")  # full detail
+
     Args:
         server_config_path: Path to mcp_servers.json. Default: tools/mcp_servers.json
             (the standard hive-tools server). Can also point to an agent's config
             to see what tools that specific agent has access to.
-        output_schema: "simple" (default) returns name and description per tool.
-            "full" also includes server and input_schema.
+        output_schema: Controls verbosity of the response.
+            "summary" (default) — provider list with tool counts + credential status. Very compact.
+                When group is specified, shows service-level breakdown within that provider.
+            "names" — tool names only (no descriptions), grouped by provider.
+            "simple" — names + truncated descriptions.
+            "full" — names + descriptions + server + input_schema.
         group: "all" (default) returns all providers. A provider like "google"
             returns only that provider's tools. Legacy prefix filters (e.g. "gmail")
             are still supported.
+        credentials: Filter by credential availability.
+            "all" (default) — show every tool regardless of credential status.
+            "available" — only tools whose credentials are already configured.
+            "unavailable" — only tools that still need credential setup.
+        service: Filter to a specific service within a provider (e.g. service="gmail"
+            when group="google"). Matches tools whose name starts with "<service>_".
 
     Returns:
         JSON with tools grouped by provider.
     """
-    if output_schema not in ("simple", "full"):
+    if output_schema not in ("summary", "names", "simple", "full"):
         return json.dumps(
-            {"error": f"Invalid output_schema: {output_schema!r}. Use 'simple' or 'full'."}
+            {
+                "error": (
+                    f"Invalid output_schema: {output_schema!r}. "
+                    "Use 'summary', 'names', 'simple', or 'full'."
+                )
+            }
+        )
+    if credentials not in ("all", "available", "unavailable"):
+        return json.dumps(
+            {
+                "error": (
+                    f"Invalid credentials: {credentials!r}. "
+                    "Use 'all', 'available', or 'unavailable'."
+                )
+            }
         )
 
     # Resolve config path
@@ -472,6 +504,33 @@ def list_agent_tools(
 
     tool_provider_auth, tool_providers = _build_provider_metadata()
 
+    def _get_available_credential_names() -> set[str]:
+        """Return set of credential spec keys whose env_var is set in the environment."""
+        try:
+            from framework.credentials.validation import ensure_credential_key_env
+
+            ensure_credential_key_env()
+        except Exception:
+            pass
+        try:
+            from aden_tools.credentials import CREDENTIAL_SPECS
+        except ImportError:
+            return set()
+        return {
+            cred_name
+            for cred_name, spec in CREDENTIAL_SPECS.items()
+            if spec.env_var and os.environ.get(spec.env_var)
+        }
+
+    def _tool_credentials_available(tool_name: str, available_creds: set[str]) -> bool:
+        """True if all credentials required by tool_name are available (or tool needs none)."""
+        required = set()
+        for provider_creds in tool_provider_auth.get(tool_name, {}).values():
+            required.update(provider_creds.keys())
+        if not required:
+            return True  # no credentials needed
+        return required.issubset(available_creds)
+
     def _group_by_provider(tools: list[dict]) -> dict[str, dict]:
         """Group tools by provider, including auth metadata and providerless tools."""
         groups: dict[str, dict] = {}
@@ -481,16 +540,20 @@ def list_agent_tools(
             if not providers:
                 providers = ["no_provider"]
 
-            desc = t["description"]
-            if output_schema == "simple" and desc and len(desc) > 200:
-                desc = desc[:200].rsplit(" ", 1)[0] + "..."
-            tool_payload = {
-                "name": t["name"],
-                "description": desc,
-            }
-            if output_schema == "full":
-                tool_payload["server"] = t["server"]
-                tool_payload["input_schema"] = t["input_schema"]
+            if output_schema == "names":
+                # Store just the name string — will be collapsed to flat list below
+                tool_payload: dict | str = t["name"]
+            else:
+                desc = t["description"]
+                if output_schema == "simple" and desc and len(desc) > 200:
+                    desc = desc[:200].rsplit(" ", 1)[0] + "..."
+                tool_payload = {
+                    "name": t["name"],
+                    "description": desc,
+                }
+                if output_schema == "full":
+                    tool_payload["server"] = t["server"]
+                    tool_payload["input_schema"] = t["input_schema"]
 
             for provider in providers:
                 bucket = groups.setdefault(
@@ -502,17 +565,48 @@ def list_agent_tools(
                 )
                 bucket["tools"].append(tool_payload)
 
-                provider_auth = tool_provider_auth.get(t["name"], {}).get(provider, {})
-                for cred_name, auth in provider_auth.items():
-                    bucket["authorization"][cred_name] = auth
+                # Only accumulate full auth metadata for simple/full schemas.
+                # summary/names use compact representations.
+                if output_schema not in ("summary", "names"):
+                    provider_auth = tool_provider_auth.get(t["name"], {}).get(provider, {})
+                    for cred_name, auth in provider_auth.items():
+                        bucket["authorization"][cred_name] = auth
 
-        for _provider, bucket in groups.items():
-            bucket["tools"] = sorted(bucket["tools"], key=lambda x: x["name"])
-            bucket["authorization"] = dict(sorted(bucket["authorization"].items()))
+        for provider, bucket in groups.items():
+            if output_schema == "names":
+                # Collapse to compact structure: flat sorted name list + credential keys only
+                tool_names = sorted(set(bucket["tools"]))
+                cred_keys: set[str] = set()
+                for tn in tool_names:
+                    for prov_creds in tool_provider_auth.get(tn, {}).values():
+                        cred_keys.update(prov_creds.keys())
+                groups[provider] = {
+                    "tool_count": len(tool_names),
+                    "credentials_required": sorted(cred_keys),
+                    "tool_names": tool_names,
+                }
+            else:
+                bucket["tools"] = sorted(bucket["tools"], key=lambda x: x["name"])
+                bucket["authorization"] = dict(sorted(bucket["authorization"].items()))
 
         return dict(sorted(groups.items()))
 
-    provider_groups = _group_by_provider(all_tools)
+    # Compute credential availability once (used for filtering and summary)
+    available_creds: set[str] = (
+        _get_available_credential_names() if credentials != "all" or output_schema == "summary"
+        else set()
+    )
+
+    # Apply credentials filter before grouping (filter tool list)
+    filtered_tools = all_tools
+    if credentials != "all":
+        filtered_tools = [
+            t
+            for t in all_tools
+            if (credentials == "available") == _tool_credentials_available(t["name"], available_creds)
+        ]
+
+    provider_groups = _group_by_provider(filtered_tools)
 
     # Filter to a specific provider (preferred) or legacy prefix (fallback)
     if group != "all":
@@ -520,20 +614,104 @@ def list_agent_tools(
             provider_groups = {group: provider_groups[group]}
         else:
             prefixed_tools = []
-            for t in all_tools:
+            for t in filtered_tools:
                 parts = t["name"].split("_", 1)
                 prefix = parts[0] if len(parts) > 1 else "general"
                 if prefix == group:
                     prefixed_tools.append(t)
             provider_groups = _group_by_provider(prefixed_tools)
 
-    all_names = sorted({t["name"] for p in provider_groups.values() for t in p["tools"]})
-    result: dict = {
-        "total": len(all_names),
-        "tools_by_provider": provider_groups,
-        "tools_by_category": provider_groups,  # backward-compat alias
-        "all_tool_names": all_names,
-    }
+    # Apply service filter (tool name prefix within a provider, e.g. service="gmail")
+    if service:
+        service_prefix = service.rstrip("_") + "_"
+        service_filtered: list[dict] = []
+        for t in filtered_tools:
+            # Only include tools from the already-filtered provider set
+            tool_name = t["name"]
+            in_provider = any(tool_name in p.get("tool_names", [tool_entry.get("name") for tool_entry in p.get("tools", [])]) for p in provider_groups.values())
+            if in_provider and tool_name.startswith(service_prefix):
+                service_filtered.append(t)
+        provider_groups = _group_by_provider(service_filtered)
+
+    def _infer_service(tool_name: str) -> str:
+        """Infer service name from tool name prefix (e.g. 'gmail' from 'gmail_send_message')."""
+        return tool_name.split("_", 1)[0]
+
+    # Summary mode: compact overview with counts + credential status
+    if output_schema == "summary":
+        if group == "all":
+            # Provider-level summary (default first call)
+            full_groups = _group_by_provider(all_tools) if credentials != "all" else provider_groups
+            summary_providers: dict = {}
+            for prov, bucket in full_groups.items():
+                cred_names = bucket.get("credentials_required", sorted(bucket.get("authorization", {}).keys()))
+                creds_ok = all(c in available_creds for c in cred_names) if cred_names else True
+                summary_providers[prov] = {
+                    "tool_count": len(bucket.get("tool_names", bucket.get("tools", []))),
+                    "credentials_required": cred_names,
+                    "credentials_available": creds_ok,
+                }
+            result: dict = {
+                "total_tools": sum(v["tool_count"] for v in summary_providers.values()),
+                "providers": summary_providers,
+                "hint": (
+                    "Use list_agent_tools(group='<provider>', output_schema='summary') for service breakdown, "
+                    "list_agent_tools(group='<provider>', service='<service>') for tool names. "
+                    "Filter by credentials='available' to see only ready-to-use tools."
+                ),
+            }
+        else:
+            # Service-level breakdown within a specific provider
+            # Re-build from all filtered tools for this provider (ignore service filter for summary)
+            provider_tool_names: list[str] = []
+            for bucket in provider_groups.values():
+                provider_tool_names.extend(
+                    bucket.get("tool_names", [e.get("name") for e in bucket.get("tools", [])])
+                )
+
+            services: dict = {}
+            for tn in sorted(set(provider_tool_names)):
+                svc = _infer_service(tn)
+                if svc not in services:
+                    svc_creds: set[str] = set()
+                    for prov_creds in tool_provider_auth.get(tn, {}).values():
+                        svc_creds.update(prov_creds.keys())
+                    services[svc] = {"tool_count": 0, "credentials_required": sorted(svc_creds)}
+                services[svc]["tool_count"] += 1
+                # Accumulate credentials for other tools in this service
+                for prov_creds in tool_provider_auth.get(tn, {}).values():
+                    existing = set(services[svc]["credentials_required"])
+                    existing.update(prov_creds.keys())
+                    services[svc]["credentials_required"] = sorted(existing)
+
+            result = {
+                "provider": group,
+                "total_tools": len(provider_tool_names),
+                "services": services,
+                "hint": (
+                    f"Use list_agent_tools(group='{group}', service='<service>') "
+                    "for tool names within a service."
+                ),
+            }
+        if errors:
+            result["errors"] = errors
+        return json.dumps(result, indent=2, default=str)
+
+    if output_schema == "names":
+        # Compact result: no duplication, no all_tool_names list
+        total = sum(p["tool_count"] for p in provider_groups.values())
+        result = {
+            "total": total,
+            "tools_by_provider": provider_groups,
+        }
+    else:
+        all_names = sorted({t["name"] for p in provider_groups.values() for t in p["tools"]})
+        result = {
+            "total": len(all_names),
+            "tools_by_provider": provider_groups,
+            "tools_by_category": provider_groups,  # backward-compat alias
+            "all_tool_names": all_names,
+        }
     if errors:
         result["errors"] = errors
 
@@ -1483,7 +1661,11 @@ def _node_var_name(node_id: str) -> str:
 
 
 @mcp.tool()
-def initialize_and_build_agent(agent_name: str, nodes: str | None = None) -> str:
+def initialize_and_build_agent(
+    agent_name: str,
+    nodes: str | None = None,
+    _draft: dict | None = None,
+) -> str:
     """Scaffold a new agent package with placeholder files.
 
     Creates exports/{agent_name}/ with all files needed for a runnable agent:
@@ -1500,6 +1682,8 @@ def initialize_and_build_agent(agent_name: str, nodes: str | None = None) -> str
         nodes: Comma-separated node names (snake_case or kebab-case).
                If omitted, a single 'start' node is created.
                Example: 'intake,process,review'
+        _draft: Internal. Draft graph metadata from planning phase, used to
+                pre-populate descriptions, goals, and node metadata.
 
     Returns:
         JSON with files written and next steps.
@@ -1519,6 +1703,15 @@ def initialize_and_build_agent(agent_name: str, nodes: str | None = None) -> str
 
     node_list = [n.strip() for n in nodes.split(",") if n.strip()] if nodes else ["start"]
 
+    # Build draft node lookup for pre-populating metadata from planning phase
+    _draft_nodes: dict[str, dict] = {}
+    if _draft and _draft.get("nodes"):
+        for dn in _draft["nodes"]:
+            _draft_nodes[dn.get("id", "")] = dn
+
+    # Extract top-level draft metadata early so it's available for all templates
+    _draft_desc = (_draft.get("description") or "") if _draft else ""
+
     class_name = _snake_to_camel(agent_name)
     human_name = agent_name.replace("_", " ").title()
     entry_node = node_list[0]
@@ -1583,7 +1776,7 @@ default_config = RuntimeConfig()
 class AgentMetadata:
     name: str = "{human_name}"
     version: str = "1.0.0"
-    description: str = "TODO: Add agent description."
+    description: str = "{_draft_desc or 'TODO: Add agent description.'}"
     intro_message: str = "TODO: Add intro message."
 
 
@@ -1598,22 +1791,33 @@ metadata = AgentMetadata()
         var = _node_var_name(node_id)
         node_var_names.append(var)
         is_first = node_id == entry_node
+
+        # Use draft metadata to pre-populate if available
+        dn = _draft_nodes.get(node_id, {})
+        node_name = dn.get("name") or node_id.replace("_", " ").replace("-", " ").title()
+        node_desc = dn.get("description") or "TODO: Describe what this node does."
+        node_type = dn.get("node_type") or "event_loop"
+        node_tools = dn.get("tools") or []
+        node_input_keys = dn.get("input_keys") or []
+        node_output_keys = dn.get("output_keys") or []
+        node_sc = dn.get("success_criteria") or "TODO: Define success criteria."
+
         node_specs.append(f'''\
 {var} = NodeSpec(
     id="{node_id}",
-    name="{node_id.replace("_", " ").replace("-", " ").title()}",
-    description="TODO: Describe what this node does.",
-    node_type="event_loop",
+    name="{node_name}",
+    description="{node_desc}",
+    node_type="{node_type}",
     client_facing={is_first},
     max_node_visits=0,
-    input_keys=[],
-    output_keys=[],
+    input_keys={node_input_keys!r},
+    output_keys={node_output_keys!r},
     nullable_output_keys=[],
-    success_criteria="TODO: Define success criteria.",
+    success_criteria="{node_sc}",
     system_prompt="""\\
 TODO: Add system prompt for this node.
 """,
-    tools=[],
+    tools={node_tools!r},
 )''')
 
     nodes_init = f'''\
@@ -1631,10 +1835,29 @@ __all__ = {node_var_names!r}
     node_imports = ", ".join(node_var_names)
     nodes_list = ", ".join(node_var_names)
 
+    # Use draft edges if available, otherwise generate linear edges
+    _draft_edges = _draft.get("edges", []) if _draft else []
     edge_defs = []
-    for i in range(len(node_list) - 1):
-        src, tgt = node_list[i], node_list[i + 1]
-        edge_defs.append(f"""\
+    if _draft_edges:
+        for de in _draft_edges:
+            eid = de.get("id", f"{de.get('source', '')}-to-{de.get('target', '')}")
+            src = de.get("source", "")
+            tgt = de.get("target", "")
+            cond = de.get("condition", "on_success").upper()
+            desc = de.get("description", "")
+            desc_line = f'\n        description="{desc}",' if desc else ""
+            edge_defs.append(f"""\
+    EdgeSpec(
+        id="{eid}",
+        source="{src}",
+        target="{tgt}",
+        condition=EdgeCondition.{cond},{desc_line}
+        priority=1,
+    ),""")
+    else:
+        for i in range(len(node_list) - 1):
+            src, tgt = node_list[i], node_list[i + 1]
+            edge_defs.append(f"""\
     EdgeSpec(
         id="{src}-to-{tgt}",
         source="{src}",
@@ -1644,6 +1867,55 @@ __all__ = {node_var_names!r}
     ),""")
     edges_str = "\n".join(edge_defs) if edge_defs else "    # TODO: Add edges"
 
+    # Pre-populate goal from draft metadata
+    _draft_goal = (_draft.get("goal") or "TODO: Describe the agent's goal.") if _draft else "TODO: Describe the agent's goal."
+    _draft_sc = (_draft.get("success_criteria") or []) if _draft else []
+    _draft_constraints = (_draft.get("constraints") or []) if _draft else []
+
+    # Build success criteria entries
+    if _draft_sc:
+        sc_entries = "\n".join(
+            f'''\
+        SuccessCriterion(
+            id="sc-{i+1}",
+            description="{sc}",
+            metric="TODO",
+            target="TODO",
+            weight=1.0,
+        ),'''
+            for i, sc in enumerate(_draft_sc)
+        )
+    else:
+        sc_entries = '''\
+        SuccessCriterion(
+            id="sc-1",
+            description="TODO: Define success criterion.",
+            metric="TODO",
+            target="TODO",
+            weight=1.0,
+        ),'''
+
+    # Build constraint entries
+    if _draft_constraints:
+        constraint_entries = "\n".join(
+            f'''\
+        Constraint(
+            id="c-{i+1}",
+            description="{c}",
+            constraint_type="hard",
+            category="functional",
+        ),'''
+            for i, c in enumerate(_draft_constraints)
+        )
+    else:
+        constraint_entries = '''\
+        Constraint(
+            id="c-1",
+            description="TODO: Define constraint.",
+            constraint_type="hard",
+            category="functional",
+        ),'''
+
     _write(
         "agent.py",
         f'''\
@@ -1667,23 +1939,12 @@ from .nodes import {node_imports}
 goal = Goal(
     id="{agent_name}-goal",
     name="{human_name}",
-    description="TODO: Describe the agent's goal.",
+    description="{_draft_goal}",
     success_criteria=[
-        SuccessCriterion(
-            id="sc-1",
-            description="TODO: Define success criterion.",
-            metric="TODO",
-            target="TODO",
-            weight=1.0,
-        ),
+{sc_entries}
     ],
     constraints=[
-        Constraint(
-            id="c-1",
-            description="TODO: Define constraint.",
-            constraint_type="hard",
-            category="functional",
-        ),
+{constraint_entries}
     ],
 )
 

tools/src/aden_tools/_win32_atomic.py

@@ -0,0 +1,108 @@
+"""Windows atomic file replacement with DACL preservation.
+
+Uses ReplaceFileW for atomic replacement, then SetFileSecurityW to
+restore the exact original DACL.  ReplaceFileW merges ACEs from the
+temp file, which can duplicate inherited entries.  SetFileSecurityW
+restores the security descriptor as-is without re-evaluating
+inheritance (unlike SetNamedSecurityInfoW).
+
+On non-NTFS volumes (e.g. FAT32), DACL snapshot/restore is skipped
+gracefully and only the atomic replacement is performed.
+"""
+
+import ctypes
+import ctypes.wintypes
+
+_DACL_SECURITY_INFORMATION = 0x00000004
+_REPLACEFILE_IGNORE_MERGE_ERRORS = 0x00000002
+
+_advapi32 = None
+_kernel32 = None
+
+if hasattr(ctypes, "windll"):
+    _advapi32 = ctypes.windll.advapi32
+    _kernel32 = ctypes.windll.kernel32
+
+    _advapi32.GetFileSecurityW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpFileName
+        ctypes.wintypes.DWORD,  # RequestedInformation
+        ctypes.c_void_p,  # pSecurityDescriptor
+        ctypes.wintypes.DWORD,  # nLength
+        ctypes.POINTER(ctypes.wintypes.DWORD),  # lpnLengthNeeded
+    ]
+    _advapi32.GetFileSecurityW.restype = ctypes.wintypes.BOOL
+
+    _advapi32.SetFileSecurityW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpFileName
+        ctypes.wintypes.DWORD,  # SecurityInformation
+        ctypes.c_void_p,  # pSecurityDescriptor
+    ]
+    _advapi32.SetFileSecurityW.restype = ctypes.wintypes.BOOL
+
+    _kernel32.ReplaceFileW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpReplacedFileName
+        ctypes.wintypes.LPCWSTR,  # lpReplacementFileName
+        ctypes.wintypes.LPCWSTR,  # lpBackupFileName
+        ctypes.wintypes.DWORD,  # dwReplaceFlags
+        ctypes.c_void_p,  # lpExclude (reserved)
+        ctypes.c_void_p,  # lpReserved
+    ]
+    _kernel32.ReplaceFileW.restype = ctypes.wintypes.BOOL
+
+
+def snapshot_dacl(path: str) -> ctypes.Array | None:
+    """Save a file's DACL as raw bytes.  Returns None on non-NTFS."""
+    if _advapi32 is None:
+        return None
+
+    needed = ctypes.wintypes.DWORD()
+    _advapi32.GetFileSecurityW(
+        path,
+        _DACL_SECURITY_INFORMATION,
+        None,
+        0,
+        ctypes.byref(needed),
+    )
+    if needed.value == 0:
+        return None
+    sd_buf = ctypes.create_string_buffer(needed.value)
+    if not _advapi32.GetFileSecurityW(
+        path,
+        _DACL_SECURITY_INFORMATION,
+        sd_buf,
+        needed.value,
+        ctypes.byref(needed),
+    ):
+        return None
+    return sd_buf
+
+
+def atomic_replace(target: str, replacement: str) -> None:
+    """Atomically replace *target* with *replacement*, preserving the DACL.
+
+    Uses ReplaceFileW for the atomic swap, then restores the original
+    DACL via SetFileSecurityW (best-effort).
+    """
+    if _kernel32 is None or _advapi32 is None:
+        raise OSError("atomic_replace is only available on Windows")
+
+    sd_buf = snapshot_dacl(target)
+
+    if not _kernel32.ReplaceFileW(
+        target,
+        replacement,
+        None,
+        _REPLACEFILE_IGNORE_MERGE_ERRORS,
+        None,
+        None,
+    ):
+        raise ctypes.WinError()
+
+    # Best-effort: content is already saved, don't fail the whole edit
+    # over a DACL restore failure.
+    if sd_buf is not None:
+        _advapi32.SetFileSecurityW(
+            target,
+            _DACL_SECURITY_INFORMATION,
+            sd_buf,
+        )

tools/src/aden_tools/credentials/__init__.py

@@ -40,7 +40,6 @@ Credential categories:
 - discord.py: Discord bot credentials
 - github.py: GitHub API credentials
 - google_analytics.py: Google Analytics 4 Data API credentials
-- google_docs.py: Google Docs API credentials
 - google_maps.py: Google Maps Platform credentials
 - hubspot.py: HubSpot CRM credentials
 - intercom.py: Intercom customer messaging credentials
@@ -81,7 +80,6 @@ from .gcp_vision import GCP_VISION_CREDENTIALS
 from .github import GITHUB_CREDENTIALS
 from .gitlab import GITLAB_CREDENTIALS
 from .google_analytics import GOOGLE_ANALYTICS_CREDENTIALS
-from .google_docs import GOOGLE_DOCS_CREDENTIALS
 from .google_maps import GOOGLE_MAPS_CREDENTIALS
 from .google_search_console import GOOGLE_SEARCH_CONSOLE_CREDENTIALS
 from .greenhouse import GREENHOUSE_CREDENTIALS
@@ -171,7 +169,6 @@ CREDENTIAL_SPECS = {
     **GREENHOUSE_CREDENTIALS,
     **GITLAB_CREDENTIALS,
     **GOOGLE_ANALYTICS_CREDENTIALS,
-    **GOOGLE_DOCS_CREDENTIALS,
     **GOOGLE_MAPS_CREDENTIALS,
     **GOOGLE_SEARCH_CONSOLE_CREDENTIALS,
     **HUBSPOT_CREDENTIALS,
@@ -264,7 +261,6 @@ __all__ = [
     "GREENHOUSE_CREDENTIALS",
     "GITLAB_CREDENTIALS",
     "GOOGLE_ANALYTICS_CREDENTIALS",
-    "GOOGLE_DOCS_CREDENTIALS",
     "GOOGLE_MAPS_CREDENTIALS",
     "GOOGLE_SEARCH_CONSOLE_CREDENTIALS",
     "HUBSPOT_CREDENTIALS",

tools/src/aden_tools/credentials/email.py

@@ -69,12 +69,26 @@ EMAIL_CREDENTIALS = {
             "google_sheets_batch_clear_values",
             "google_sheets_add_sheet",
             "google_sheets_delete_sheet",
+            # Google Docs tools
+            "google_docs_create_document",
+            "google_docs_get_document",
+            "google_docs_insert_text",
+            "google_docs_replace_all_text",
+            "google_docs_insert_image",
+            "google_docs_format_text",
+            "google_docs_batch_update",
+            "google_docs_create_list",
+            "google_docs_add_comment",
+            "google_docs_list_comments",
+            "google_docs_export_content",
         ],
         node_types=[],
         required=True,
         startup_required=False,
         help_url="https://hive.adenhq.com",
-        description="Google OAuth2 access token (via Aden) - used for Gmail, Calendar, and Sheets",
+        description=(
+            "Google OAuth2 access token (via Aden) - used for Gmail, Calendar, Sheets, and Docs"
+        ),
         aden_supported=True,
         aden_provider_name="google",
         direct_api_key_supported=False,

tools/src/aden_tools/credentials/google_docs.py

@@ -1,51 +0,0 @@
-"""
-Google Docs tool credentials.
-
-Contains credentials for Google Docs API integration.
-"""
-
-from .base import CredentialSpec
-
-GOOGLE_DOCS_CREDENTIALS = {
-    "google_docs": CredentialSpec(
-        env_var="GOOGLE_DOCS_ACCESS_TOKEN",
-        tools=[
-            "google_docs_create_document",
-            "google_docs_get_document",
-            "google_docs_insert_text",
-            "google_docs_replace_all_text",
-            "google_docs_insert_image",
-            "google_docs_format_text",
-            "google_docs_batch_update",
-            "google_docs_create_list",
-            "google_docs_add_comment",
-            "google_docs_list_comments",
-            "google_docs_export_content",
-        ],
-        required=True,
-        startup_required=False,
-        help_url="https://console.cloud.google.com/apis/credentials",
-        description="Google Docs OAuth2 access token",
-        # Auth method support
-        aden_supported=True,
-        aden_provider_name="google",
-        direct_api_key_supported=True,
-        api_key_instructions="""To get a Google Docs access token:
-1. Go to Google Cloud Console: https://console.cloud.google.com/
-2. Create a new project or select an existing one
-3. Enable the Google Docs API and Google Drive API
-4. Go to APIs & Services > Credentials
-5. Create OAuth 2.0 credentials (Web application or Desktop app)
-6. Use the OAuth 2.0 Playground or your app to get an access token
-7. Required scopes:
-   - https://www.googleapis.com/auth/documents
-   - https://www.googleapis.com/auth/drive.file
-   - https://www.googleapis.com/auth/drive (for export/comments)""",
-        # Health check configuration
-        health_check_endpoint="https://docs.googleapis.com/v1/documents/1",
-        health_check_method="GET",
-        # Credential store mapping
-        credential_id="google_docs",
-        credential_key="access_token",
-    ),
-}

tools/src/aden_tools/credentials/health_check.py

@@ -1068,16 +1068,6 @@ class ExaSearchHealthChecker(BaseHttpHealthChecker):
         return {"query": "test", "numResults": 1}
 
 
-class GoogleDocsHealthChecker(OAuthBearerHealthChecker):
-    """Health checker for Google Docs OAuth tokens."""
-
-    def __init__(self):
-        super().__init__(
-            endpoint="https://docs.googleapis.com/v1/documents/1",
-            service_name="Google Docs",
-        )
-
-
 class CalcomHealthChecker(BaseHttpHealthChecker):
     """Health checker for Cal.com API key."""
 
@@ -1334,7 +1324,6 @@ HEALTH_CHECKERS: dict[str, CredentialHealthChecker] = {
     "github": GitHubHealthChecker(),
     "gitlab_token": GitLabHealthChecker(),
     "google": GoogleHealthChecker(),
-    "google_docs": GoogleDocsHealthChecker(),
     "google_maps": GoogleMapsHealthChecker(),
     "google_search": GoogleSearchHealthChecker(),
     "google_search_console": GoogleSearchConsoleHealthChecker(),

tools/src/aden_tools/file_ops.py

@@ -23,6 +23,7 @@ import json
 import os
 import re
 import subprocess
+import sys
 import tempfile
 from collections.abc import Callable
 from pathlib import Path
@@ -965,16 +966,25 @@ def register_file_tools(
         try:
             if before_write:
                 before_write()
-            original_mode = os.stat(resolved).st_mode
             fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(resolved))
             fd_open = True
             try:
-                if hasattr(os, "fchmod"):
-                    os.fchmod(fd, original_mode)
+                match sys.platform:
+                    case "win32":
+                        pass  # ACL preservation handled by atomic_replace below
+                    case _:
+                        original_mode = os.stat(resolved).st_mode
+                        os.fchmod(fd, original_mode)
                 with os.fdopen(fd, "w", encoding=encoding, newline="") as f:
                     fd_open = False
                     f.write(joined)
-                os.replace(tmp_path, resolved)
+                match sys.platform:
+                    case "win32":
+                        from aden_tools._win32_atomic import atomic_replace
+
+                        atomic_replace(resolved, tmp_path)
+                    case _:
+                        os.replace(tmp_path, resolved)
             except BaseException:
                 if fd_open:
                     os.close(fd)

tools/src/aden_tools/tools/file_system_toolkits/hashline_edit/hashline_edit.py

@@ -2,6 +2,7 @@ import contextlib
 import json
 import os
 import re
+import sys
 import tempfile
 
 from mcp.server.fastmcp import FastMCP
@@ -380,16 +381,25 @@ def register_tools(mcp: FastMCP) -> None:
 
         # 9. Atomic write (write-to-tmp + os.replace)
         try:
-            original_mode = os.stat(secure_path).st_mode
             fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(secure_path))
             fd_open = True
             try:
-                if hasattr(os, "fchmod"):
-                    os.fchmod(fd, original_mode)
+                match sys.platform:
+                    case "win32":
+                        pass  # ACL preservation handled by atomic_replace below
+                    case _:
+                        original_mode = os.stat(secure_path).st_mode
+                        os.fchmod(fd, original_mode)
                 with os.fdopen(fd, "w", encoding=encoding, newline="") as f:
                     fd_open = False
                     f.write(joined)
-                os.replace(tmp_path, secure_path)
+                match sys.platform:
+                    case "win32":
+                        from aden_tools._win32_atomic import atomic_replace
+
+                        atomic_replace(secure_path, tmp_path)
+                    case _:
+                        os.replace(tmp_path, secure_path)
             except BaseException:
                 if fd_open:
                     os.close(fd)

tools/src/aden_tools/tools/google_docs_tool/README.md

@@ -26,14 +26,13 @@ Create and manage Google Docs documents via the Google Docs API v1.
 6. Set the environment variable:
 
 ```bash
-export GOOGLE_DOCS_ACCESS_TOKEN="your-access-token"
+export GOOGLE_ACCESS_TOKEN="your-access-token"
 ```
 
 ### Required OAuth Scopes
 
-- `https://www.googleapis.com/auth/documents` - Full access to Google Docs
-- `https://www.googleapis.com/auth/drive.file` - Access to files created/opened by the app
-- `https://www.googleapis.com/auth/drive` - Required for document export and comment functionality
+- `https://www.googleapis.com/auth/documents` - Google Docs API (create, read, edit documents)
+- `https://www.googleapis.com/auth/drive.file` - Google Drive API (export, comments)
 
 ## Available Tools
 
@@ -144,4 +143,4 @@ All tools return a dict. On error, the dict contains an `"error"` key with a des
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `GOOGLE_DOCS_ACCESS_TOKEN` | Yes | OAuth2 access token |
+| `GOOGLE_ACCESS_TOKEN` | Yes | OAuth2 access token (shared with Gmail, Calendar, Sheets) |

tools/src/aden_tools/tools/google_docs_tool/google_docs_tool.py

@@ -3,7 +3,7 @@ Google Docs Tool - Create and manage Google Docs documents via Google Docs API v
 
 Supports:
 - OAuth2 tokens via the credential store
-- Direct access token (GOOGLE_DOCS_ACCESS_TOKEN)
+- Direct access token (GOOGLE_ACCESS_TOKEN)
 
 API Reference: https://developers.google.com/docs/api/reference/rest
 
@@ -18,7 +18,6 @@ import base64
 import json
 import os
 import re
-import time
 from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
@@ -30,8 +29,6 @@ if TYPE_CHECKING:
 
 GOOGLE_DOCS_API_BASE = "https://docs.googleapis.com/v1"
 GOOGLE_DRIVE_API_BASE = "https://www.googleapis.com/drive/v3"
-GOOGLE_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token"
-
 # Allowed URL schemes for image insertion
 ALLOWED_IMAGE_SCHEMES = {"https", "http"}
 # Regex pattern for valid URLs
@@ -99,105 +96,6 @@ def _get_document_end_index(doc: dict[str, Any]) -> int:
     return 1
 
 
-def _create_service_account_token(service_account_json: str) -> str | None:
-    """Create an access token from a service account JSON using JWT.
-
-    This implements the OAuth 2.0 service account flow:
-    1. Create a signed JWT
-    2. Exchange it for an access token
-
-    Args:
-        service_account_json: The service account JSON string
-
-    Returns:
-        Access token string, or None if token creation failed
-    """
-    try:
-        sa_data = json.loads(service_account_json)
-    except json.JSONDecodeError:
-        return None
-
-    # Check if this is actually a service account
-    if sa_data.get("type") != "service_account":
-        # Not a service account, check for direct access token
-        return sa_data.get("access_token")
-
-    # Required fields for service account
-    private_key = sa_data.get("private_key")
-    client_email = sa_data.get("client_email")
-    token_uri = sa_data.get("token_uri", GOOGLE_OAUTH_TOKEN_URL)
-
-    if not private_key or not client_email:
-        return None
-
-    # Create JWT header and claims
-    now = int(time.time())
-    header = {"alg": "RS256", "typ": "JWT"}
-    claims = {
-        "iss": client_email,
-        "sub": client_email,
-        "aud": token_uri,
-        "iat": now,
-        "exp": now + 3600,  # 1 hour expiry
-        "scope": (
-            "https://www.googleapis.com/auth/documents "
-            "https://www.googleapis.com/auth/drive.file "
-            "https://www.googleapis.com/auth/drive"
-        ),
-    }
-
-    try:
-        # Try using cryptography library for RSA signing
-        from cryptography.hazmat.backends import default_backend
-        from cryptography.hazmat.primitives import hashes, serialization
-        from cryptography.hazmat.primitives.asymmetric import padding
-
-        # Encode header and claims
-        def _b64url_encode(data: bytes) -> str:
-            return base64.urlsafe_b64encode(data).rstrip(b"=").decode("utf-8")
-
-        header_b64 = _b64url_encode(json.dumps(header).encode())
-        claims_b64 = _b64url_encode(json.dumps(claims).encode())
-        signing_input = f"{header_b64}.{claims_b64}"
-
-        # Load private key and sign
-        private_key_obj = serialization.load_pem_private_key(
-            private_key.encode(), password=None, backend=default_backend()
-        )
-        signature = private_key_obj.sign(
-            signing_input.encode(),
-            padding.PKCS1v15(),
-            hashes.SHA256(),
-        )
-        signature_b64 = _b64url_encode(signature)
-
-        jwt_token = f"{signing_input}.{signature_b64}"
-
-        # Exchange JWT for access token
-        response = httpx.post(
-            token_uri,
-            data={
-                "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
-                "assertion": jwt_token,
-            },
-            timeout=30.0,
-        )
-
-        if response.status_code == 200:
-            token_data = response.json()
-            return token_data.get("access_token")
-
-        return None
-
-    except ImportError:
-        # cryptography not available, cannot sign JWT
-        # Fall back to checking for pre-exchanged token
-        return sa_data.get("access_token")
-    except Exception:
-        # Any signing/exchange error
-        return None
-
-
 class _GoogleDocsClient:
     """Internal client wrapping Google Docs API v1 calls."""
 
@@ -486,25 +384,16 @@ def register_tools(
         if credentials is not None:
             if account:
                 return credentials.get_by_alias(
-                    "google_docs",
+                    "google",
                     account,
                 )
-            token = credentials.get("google_docs")
+            token = credentials.get("google")
             if token is not None and not isinstance(token, str):
                 raise TypeError(
-                    f"Expected string from credentials.get('google_docs'), "
-                    f"got {type(token).__name__}"
+                    f"Expected string from credentials.get('google'), got {type(token).__name__}"
                 )
             return token
-        # Try environment variables - direct access token first
-        token = os.getenv("GOOGLE_DOCS_ACCESS_TOKEN")
-        if token:
-            return token
-        # Try service account JSON with proper JWT token exchange
-        service_account = os.getenv("GOOGLE_SERVICE_ACCOUNT_JSON")
-        if service_account:
-            return _create_service_account_token(service_account)
-        return None
+        return os.getenv("GOOGLE_ACCESS_TOKEN")
 
     def _get_client(account: str = "") -> _GoogleDocsClient | dict[str, str]:
         """Get a Google Docs client, or return an error dict if no credentials."""
@@ -513,9 +402,8 @@ def register_tools(
             return {
                 "error": "Google Docs credentials not configured",
                 "help": (
-                    "Set GOOGLE_DOCS_ACCESS_TOKEN environment variable "
-                    "or configure via credential store. "
-                    "Get credentials at: https://console.cloud.google.com/apis/credentials"
+                    "Set GOOGLE_ACCESS_TOKEN environment variable "
+                    "or configure 'google' via credential store"
                 ),
             }
         return _GoogleDocsClient(token)

tools/src/aden_tools/tools/google_docs_tool/tests/test_google_docs_tool.py

@@ -49,16 +49,6 @@ class TestGoogleDocsCreateDocument:
             assert "not configured" in result["error"]
             assert "help" in result
 
-    def test_service_account_json_without_access_token_is_not_used(self, mcp):
-        """Test that service account JSON alone is not treated as an access token."""
-        with patch.dict(
-            "os.environ", {"GOOGLE_SERVICE_ACCOUNT_JSON": '{"type":"service_account"}'}
-        ):
-            tool_fn = get_tool_fn(mcp, "google_docs_create_document")
-            result = tool_fn(title="Test Document")
-            assert "error" in result
-            assert "not configured" in result["error"]
-
     @patch("httpx.post")
     def test_create_document_success(self, mock_post, mcp_with_credentials):
         """Test successful document creation."""
@@ -444,34 +434,6 @@ class TestReplaceAllTextValidation:
         assert "empty" in result["error"].lower()
 
 
-class TestServiceAccountTokenExchange:
-    """Tests for service account JWT token exchange."""
-
-    @patch("httpx.post")
-    @patch.dict(
-        "os.environ",
-        {"GOOGLE_SERVICE_ACCOUNT_JSON": '{"access_token": "pre-exchanged-token"}'},
-    )
-    def test_fallback_to_pre_exchanged_token(self, mock_post):
-        """Test that pre-exchanged tokens in JSON are used as fallback."""
-        server = FastMCP("test")
-        register_tools(server)
-
-        mock_response = MagicMock()
-        mock_response.status_code = 200
-        mock_response.json.return_value = {
-            "documentId": "doc123",
-            "title": "Test",
-        }
-        mock_post.return_value = mock_response
-
-        tool_fn = get_tool_fn(server, "google_docs_create_document")
-        result = tool_fn(title="Test")
-
-        # Should use the pre-exchanged token and make the API call
-        assert "error" not in result or "not configured" not in result.get("error", "")
-
-
 class TestGoogleDocsListComments:
     """Tests for google_docs_list_comments tool."""
 

tools/tests/test_health_checks.py

@@ -73,7 +73,6 @@ class TestHealthCheckerRegistry:
             "github",
             "gitlab_token",
             "google",
-            "google_docs",
             "google_maps",
             "google_search",
             "google_search_console",

tools/tests/tools/test_dns_security_scanner.py

@@ -0,0 +1,306 @@
+"""Tests for DNS Security Scanner tool."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.dns_security_scanner import register_tools
+
+
+@pytest.fixture
+def dns_tools(mcp: FastMCP):
+    """Register DNS security tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def scan_fn(dns_tools):
+    return dns_tools["dns_security_scan"]
+
+
+# ---------------------------------------------------------------------------
+# Input Validation & Cleaning
+# ---------------------------------------------------------------------------
+
+
+class TestInputValidation:
+    """Test domain input cleaning and validation."""
+
+    def test_strips_https_prefix(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                import dns.resolver
+
+                mock = MagicMock()
+                mock.resolve.side_effect = dns.resolver.NXDOMAIN()
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("https://example.com")
+                assert result["domain"] == "example.com"
+
+    def test_strips_http_prefix(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                import dns.resolver
+
+                mock = MagicMock()
+                mock.resolve.side_effect = dns.resolver.NXDOMAIN()
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("http://example.com")
+                assert result["domain"] == "example.com"
+
+    def test_strips_trailing_slash(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                import dns.resolver
+
+                mock = MagicMock()
+                mock.resolve.side_effect = dns.resolver.NXDOMAIN()
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com/")
+                assert result["domain"] == "example.com"
+
+    def test_strips_path(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                import dns.resolver
+
+                mock = MagicMock()
+                mock.resolve.side_effect = dns.resolver.NXDOMAIN()
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com/path/to/page")
+                assert result["domain"] == "example.com"
+
+    def test_strips_port(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                import dns.resolver
+
+                mock = MagicMock()
+                mock.resolve.side_effect = dns.resolver.NXDOMAIN()
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com:8080")
+                assert result["domain"] == "example.com"
+
+
+# ---------------------------------------------------------------------------
+# DNS Library Availability
+# ---------------------------------------------------------------------------
+
+
+class TestDnsAvailability:
+    """Test behavior when dnspython is not installed."""
+
+    def test_dns_not_available(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", False
+        ):
+            result = scan_fn("example.com")
+            assert "error" in result
+            assert "dnspython" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# SPF Record Checks
+# ---------------------------------------------------------------------------
+
+
+class TestSpfChecks:
+    """Test SPF record detection and policy analysis."""
+
+    def test_spf_hardfail_detected(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                mock = MagicMock()
+                mock_rdata = MagicMock()
+                mock_rdata.to_text.return_value = '"v=spf1 include:_spf.google.com -all"'
+                mock.resolve.return_value = [mock_rdata]
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com")
+                assert result["spf"]["present"] is True
+                assert result["spf"]["policy"] == "hardfail"
+                assert result["grade_input"]["spf_strict"] is True
+
+    def test_spf_softfail_detected(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                mock = MagicMock()
+                mock_rdata = MagicMock()
+                mock_rdata.to_text.return_value = '"v=spf1 include:_spf.google.com ~all"'
+                mock.resolve.return_value = [mock_rdata]
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com")
+                assert result["spf"]["present"] is True
+                assert result["spf"]["policy"] == "softfail"
+                assert result["grade_input"]["spf_strict"] is False
+
+    def test_spf_pass_all_dangerous(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                mock = MagicMock()
+                mock_rdata = MagicMock()
+                mock_rdata.to_text.return_value = '"v=spf1 +all"'
+                mock.resolve.return_value = [mock_rdata]
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com")
+                assert result["spf"]["policy"] == "pass_all"
+                assert len(result["spf"]["issues"]) > 0
+
+
+# ---------------------------------------------------------------------------
+# DMARC Record Checks
+# ---------------------------------------------------------------------------
+
+
+class TestDmarcChecks:
+    """Test DMARC record detection and policy analysis."""
+
+    def test_dmarc_reject_policy(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                mock = MagicMock()
+
+                def mock_resolve(domain, record_type):
+                    import dns.resolver
+
+                    if record_type == "TXT" and "_dmarc" in domain:
+                        rdata = MagicMock()
+                        rdata.to_text.return_value = '"v=DMARC1; p=reject"'
+                        return [rdata]
+                    raise dns.resolver.NXDOMAIN()
+
+                mock.resolve = mock_resolve
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com")
+                assert result["dmarc"]["present"] is True
+                assert result["dmarc"]["policy"] == "reject"
+                assert result["grade_input"]["dmarc_enforcing"] is True
+
+    def test_dmarc_none_policy(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                mock = MagicMock()
+
+                def mock_resolve(domain, record_type):
+                    if record_type == "TXT" and "_dmarc" in domain:
+                        rdata = MagicMock()
+                        rdata.to_text.return_value = '"v=DMARC1; p=none"'
+                        return [rdata]
+                    import dns.resolver
+
+                    raise dns.resolver.NXDOMAIN()
+
+                mock.resolve = mock_resolve
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com")
+                assert result["dmarc"]["policy"] == "none"
+                assert result["grade_input"]["dmarc_enforcing"] is False
+
+
+# ---------------------------------------------------------------------------
+# Grade Input
+# ---------------------------------------------------------------------------
+
+
+class TestGradeInput:
+    """Test grade_input dict is properly constructed."""
+
+    def test_grade_input_keys_present(self, scan_fn):
+        with patch(
+            "aden_tools.tools.dns_security_scanner.dns_security_scanner._DNS_AVAILABLE", True
+        ):
+            with patch(
+                "aden_tools.tools.dns_security_scanner.dns_security_scanner.dns.resolver.Resolver"
+            ) as MockResolver:
+                mock = MagicMock()
+                import dns.resolver
+
+                mock.resolve.side_effect = dns.resolver.NXDOMAIN()
+                mock.timeout = 10
+                mock.lifetime = 10
+                MockResolver.return_value = mock
+
+                result = scan_fn("example.com")
+                assert "grade_input" in result
+                grade = result["grade_input"]
+                assert "spf_present" in grade
+                assert "spf_strict" in grade
+                assert "dmarc_present" in grade
+                assert "dmarc_enforcing" in grade
+                assert "dkim_found" in grade
+                assert "dnssec_enabled" in grade
+                assert "zone_transfer_blocked" in grade

tools/tests/tools/test_file_ops_hashline.py

@@ -3,6 +3,7 @@
 import json
 import os
 import sys
+from unittest.mock import patch
 
 import pytest
 from fastmcp import FastMCP
@@ -401,6 +402,95 @@ class TestHashlineEditAtomicWrite:
         hashline_edit(path="f.txt", edits=edits)
         assert os.stat(f).st_mode & 0o777 == 0o755
 
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only ACL test")
+    def test_acl_preserved_after_edit_windows(self, tools, tmp_path):
+        """Atomic replace preserves the target file's DACL on Windows."""
+        import ctypes
+
+        advapi32 = ctypes.windll.advapi32
+        kernel32 = ctypes.windll.kernel32
+        SE_FILE_OBJECT = 1
+        DACL_SECURITY_INFORMATION = 0x00000004
+
+        advapi32.GetNamedSecurityInfoW.argtypes = [
+            ctypes.wintypes.LPCWSTR,  # pObjectName
+            ctypes.c_uint,  # ObjectType (SE_OBJECT_TYPE enum)
+            ctypes.wintypes.DWORD,  # SecurityInfo
+            ctypes.c_void_p,  # ppsidOwner
+            ctypes.c_void_p,  # ppsidGroup
+            ctypes.c_void_p,  # ppDacl
+            ctypes.c_void_p,  # ppSacl
+            ctypes.c_void_p,  # ppSecurityDescriptor
+        ]
+        advapi32.GetNamedSecurityInfoW.restype = ctypes.wintypes.DWORD
+
+        advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW.argtypes = [
+            ctypes.c_void_p,  # SecurityDescriptor
+            ctypes.wintypes.DWORD,  # RequestedStringSDRevision
+            ctypes.wintypes.DWORD,  # SecurityInformation
+            ctypes.c_void_p,  # StringSecurityDescriptor (out)
+            ctypes.c_void_p,  # StringSecurityDescriptorLen (out, optional)
+        ]
+        advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW.restype = ctypes.wintypes.BOOL
+
+        kernel32.LocalFree.argtypes = [ctypes.c_void_p]
+        kernel32.LocalFree.restype = ctypes.c_void_p
+
+        hashline_edit = tools[0]["hashline_edit"]
+        f = tmp_path / "f.txt"
+        f.write_text("aaa\nbbb\n")
+
+        def _read_dacl_sddl(path):
+            sd = ctypes.c_void_p()
+            dacl = ctypes.c_void_p()
+            rc = advapi32.GetNamedSecurityInfoW(
+                str(path),
+                SE_FILE_OBJECT,
+                DACL_SECURITY_INFORMATION,
+                None,
+                None,
+                ctypes.byref(dacl),
+                None,
+                ctypes.byref(sd),
+            )
+            assert rc == 0, f"GetNamedSecurityInfoW failed: {rc}"
+            sddl = ctypes.c_wchar_p()
+            assert advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW(
+                sd,
+                1,
+                DACL_SECURITY_INFORMATION,
+                ctypes.byref(sddl),
+                None,
+            )
+            value = sddl.value
+            kernel32.LocalFree(sddl)
+            kernel32.LocalFree(sd)
+            return value
+
+        acl_before = _read_dacl_sddl(f)
+
+        edits = json.dumps([{"op": "set_line", "anchor": _anchor(1, "aaa"), "content": "AAA"}])
+        hashline_edit(path="f.txt", edits=edits)
+
+        acl_after = _read_dacl_sddl(f)
+
+        assert acl_before == acl_after, f"ACL changed after edit: {acl_before} -> {acl_after}"
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only ACL test")
+    def test_edit_succeeds_when_dacl_unavailable_windows(self, tools, tmp_path):
+        """Edit still works on volumes without ACL support (e.g. FAT32)."""
+        from aden_tools import _win32_atomic
+
+        hashline_edit = tools[0]["hashline_edit"]
+        f = tmp_path / "f.txt"
+        f.write_text("aaa\nbbb\n")
+
+        with patch.object(_win32_atomic, "snapshot_dacl", return_value=None):
+            edits = json.dumps([{"op": "set_line", "anchor": _anchor(1, "aaa"), "content": "AAA"}])
+            hashline_edit(path="f.txt", edits=edits)
+
+        assert f.read_text().splitlines()[0].endswith("AAA")
+
     def test_preserves_trailing_newline(self, tools, tmp_path):
         """Files with trailing newline keep it after edit."""
         hashline_edit = tools[0]["hashline_edit"]

tools/tests/tools/test_google_docs_tool.py

@@ -0,0 +1,599 @@
+"""Tests for Google Docs tool with FastMCP.
+
+Covers:
+- Credential handling (credential store, env var, service account, missing)
+- _GoogleDocsClient methods (create, get, insert, replace, image, format, list, batch, export)
+- HTTP error handling (401, 403, 404, 429, 500, timeout)
+- All MCP tool functions via register_tools
+- Input validation (image URI, JSON parsing, list types, format types)
+- Helper functions (_validate_image_uri, _get_document_end_index)
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.google_docs_tool.google_docs_tool import (
+    GOOGLE_DOCS_API_BASE,
+    _get_document_end_index,
+    _GoogleDocsClient,
+    _validate_image_uri,
+    register_tools,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def mcp():
+    """Create a FastMCP instance for testing."""
+    return FastMCP("test-server")
+
+
+@pytest.fixture
+def client():
+    """Create a _GoogleDocsClient with a test token."""
+    return _GoogleDocsClient("test-token")
+
+
+def _register(mcp, credentials=None):
+    """Helper to register tools and return the tool lookup dict."""
+    register_tools(mcp, credentials=credentials)
+    return mcp._tool_manager._tools
+
+
+def _tool_fn(mcp, name, credentials=None):
+    """Register tools and return a single tool function by name."""
+    tools = _register(mcp, credentials)
+    return tools[name].fn
+
+
+def _mock_response(status_code=200, json_data=None, text="", content=b""):
+    """Create a mock httpx.Response."""
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.text = text
+    resp.content = content
+    if json_data is not None:
+        resp.json.return_value = json_data
+    else:
+        resp.json.return_value = {}
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Helper function tests
+# ---------------------------------------------------------------------------
+
+
+class TestValidateImageUri:
+    """Tests for _validate_image_uri."""
+
+    def test_valid_https_url(self):
+        assert _validate_image_uri("https://example.com/image.png") is None
+
+    def test_valid_http_url(self):
+        assert _validate_image_uri("http://example.com/image.jpg") is None
+
+    def test_empty_uri(self):
+        result = _validate_image_uri("")
+        assert result is not None
+        assert "error" in result
+
+    def test_whitespace_uri(self):
+        result = _validate_image_uri("   ")
+        assert result is not None
+        assert "error" in result
+
+    def test_missing_scheme(self):
+        result = _validate_image_uri("example.com/image.png")
+        assert result is not None
+        assert "missing scheme" in result["error"]
+
+    def test_disallowed_scheme_ftp(self):
+        result = _validate_image_uri("ftp://example.com/image.png")
+        assert result is not None
+        assert "Only" in result["error"]
+
+    def test_disallowed_scheme_javascript(self):
+        result = _validate_image_uri("javascript:alert(1)")
+        assert result is not None
+        assert "error" in result
+
+    def test_missing_domain(self):
+        result = _validate_image_uri("https://")
+        assert result is not None
+        assert "error" in result
+
+
+class TestGetDocumentEndIndex:
+    """Tests for _get_document_end_index."""
+
+    def test_returns_end_index_minus_one(self):
+        doc = {
+            "body": {
+                "content": [
+                    {"startIndex": 1, "endIndex": 50},
+                ]
+            }
+        }
+        assert _get_document_end_index(doc) == 49
+
+    def test_empty_content_returns_one(self):
+        doc = {"body": {"content": []}}
+        assert _get_document_end_index(doc) == 1
+
+    def test_no_body_returns_one(self):
+        doc = {}
+        assert _get_document_end_index(doc) == 1
+
+
+# ---------------------------------------------------------------------------
+# _GoogleDocsClient unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestGoogleDocsClientHeaders:
+    def test_headers_contain_bearer_token(self, client):
+        headers = client._headers
+        assert headers["Authorization"] == "Bearer test-token"
+        assert headers["Content-Type"] == "application/json"
+
+
+class TestGoogleDocsClientHandleResponse:
+    @pytest.mark.parametrize(
+        "status_code,expected_substr",
+        [
+            (401, "Invalid or expired"),
+            (403, "Insufficient permissions"),
+            (404, "not found"),
+            (429, "rate limit"),
+        ],
+    )
+    def test_known_error_codes(self, client, status_code, expected_substr):
+        resp = _mock_response(status_code=status_code)
+        result = client._handle_response(resp)
+        assert "error" in result
+        assert expected_substr in result["error"]
+
+    def test_generic_error_with_nested_message(self, client):
+        resp = _mock_response(
+            status_code=400,
+            json_data={"error": {"message": "Invalid request"}},
+        )
+        result = client._handle_response(resp)
+        assert "Invalid request" in result["error"]
+
+    def test_success_returns_json(self, client):
+        resp = _mock_response(200, {"documentId": "doc-1"})
+        assert client._handle_response(resp) == {"documentId": "doc-1"}
+
+
+class TestGoogleDocsClientCreateDocument:
+    def test_posts_title(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"documentId": "doc-1", "title": "My Doc"})
+            result = client.create_document("My Doc")
+            body = mock_post.call_args.kwargs["json"]
+            assert body == {"title": "My Doc"}
+            assert result["documentId"] == "doc-1"
+
+
+class TestGoogleDocsClientGetDocument:
+    def test_gets_correct_url(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"documentId": "doc-1"})
+            client.get_document("doc-1")
+            args, _ = mock_get.call_args
+            assert args[0] == f"{GOOGLE_DOCS_API_BASE}/documents/doc-1"
+
+
+class TestGoogleDocsClientBatchUpdate:
+    def test_batch_update_sends_requests(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            requests = [{"insertText": {"text": "hello", "location": {"index": 1}}}]
+            client.batch_update("doc-1", requests)
+            body = mock_post.call_args.kwargs["json"]
+            assert body["requests"] == requests
+
+
+class TestGoogleDocsClientInsertText:
+    def test_insert_at_index(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            client.insert_text("doc-1", "Hello", index=5)
+            body = mock_post.call_args.kwargs["json"]
+            req = body["requests"][0]["insertText"]
+            assert req["text"] == "Hello"
+            assert req["location"]["index"] == 5
+
+    def test_insert_at_end_fetches_doc(self, client):
+        with patch("httpx.get") as mock_get, patch("httpx.post") as mock_post:
+            mock_get.return_value = _mock_response(
+                200,
+                {"body": {"content": [{"startIndex": 1, "endIndex": 20}]}},
+            )
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            client.insert_text("doc-1", "Appended text")
+            # Should have fetched doc to determine end index
+            mock_get.assert_called_once()
+
+
+class TestGoogleDocsClientReplaceAllText:
+    def test_replace_sends_correct_request(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            client.replace_all_text("doc-1", "{{NAME}}", "Alice")
+            body = mock_post.call_args.kwargs["json"]
+            req = body["requests"][0]["replaceAllText"]
+            assert req["containsText"]["text"] == "{{NAME}}"
+            assert req["replaceText"] == "Alice"
+
+    def test_empty_find_text_returns_error(self, client):
+        result = client.replace_all_text("doc-1", "", "Alice")
+        assert "error" in result
+
+
+class TestGoogleDocsClientInsertImage:
+    def test_valid_image_insertion(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            client.insert_image("doc-1", "https://example.com/img.png", index=1)
+            body = mock_post.call_args.kwargs["json"]
+            req = body["requests"][0]["insertInlineImage"]
+            assert req["uri"] == "https://example.com/img.png"
+
+    def test_invalid_uri_returns_error(self, client):
+        result = client.insert_image("doc-1", "ftp://bad.com/img.png", index=1)
+        assert "error" in result
+
+    def test_image_with_dimensions(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            client.insert_image(
+                "doc-1",
+                "https://example.com/img.png",
+                index=1,
+                width_pt=200.0,
+                height_pt=100.0,
+            )
+            body = mock_post.call_args.kwargs["json"]
+            req = body["requests"][0]["insertInlineImage"]
+            assert req["objectSize"]["width"]["magnitude"] == 200.0
+
+
+class TestGoogleDocsClientFormatText:
+    def test_bold_formatting(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            client.format_text("doc-1", 1, 10, bold=True)
+            body = mock_post.call_args.kwargs["json"]
+            req = body["requests"][0]["updateTextStyle"]
+            assert req["textStyle"]["bold"] is True
+            assert "bold" in req["fields"]
+
+    def test_no_options_returns_error(self, client):
+        result = client.format_text("doc-1", 1, 10)
+        assert "error" in result
+        assert "No formatting" in result["error"]
+
+
+class TestGoogleDocsClientExportDocument:
+    def test_export_pdf(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, content=b"%PDF-1.4 content")
+            result = client.export_document("doc-1", "application/pdf")
+            assert result["mime_type"] == "application/pdf"
+            assert result["size_bytes"] == len(b"%PDF-1.4 content")
+            assert "content_base64" in result
+
+
+class TestGoogleDocsClientComments:
+    def test_add_comment(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"id": "comment-1", "content": "Nice work"}
+            )
+            result = client.add_comment("doc-1", "Nice work")
+            assert result["id"] == "comment-1"
+
+    def test_add_comment_with_quoted_text(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"id": "comment-1"})
+            client.add_comment("doc-1", "Fix this", quoted_text="typo here")
+            body = mock_post.call_args.kwargs["json"]
+            assert body["quotedFileContent"]["value"] == "typo here"
+
+    def test_list_comments(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(
+                200, {"comments": [{"id": "c1"}], "nextPageToken": "tok2"}
+            )
+            result = client.list_comments("doc-1", page_size=10)
+            assert len(result["comments"]) == 1
+
+
+# ---------------------------------------------------------------------------
+# Credential handling via register_tools
+# ---------------------------------------------------------------------------
+
+
+class TestGoogleDocsCredentials:
+    def test_no_credentials_returns_error(self, mcp, monkeypatch):
+        monkeypatch.delenv("GOOGLE_ACCESS_TOKEN", raising=False)
+        fn = _tool_fn(mcp, "google_docs_get_document")
+        result = fn(document_id="doc-1")
+        assert "error" in result
+        assert "not configured" in result["error"]
+
+    def test_env_var_credential(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "env-tok")
+        fn = _tool_fn(mcp, "google_docs_get_document")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"documentId": "doc-1"})
+            fn(document_id="doc-1")
+            headers = mock_get.call_args.kwargs["headers"]
+            assert headers["Authorization"] == "Bearer env-tok"
+
+    def test_credential_store_used(self, mcp):
+        creds = MagicMock()
+        creds.get.return_value = "store-tok"
+        fn = _tool_fn(mcp, "google_docs_get_document", credentials=creds)
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"documentId": "doc-1"})
+            fn(document_id="doc-1")
+            creds.get.assert_called_once_with("google")
+
+    def test_credential_store_non_string_raises(self, mcp):
+        creds = MagicMock()
+        creds.get.return_value = {"key": "value"}
+        fn = _tool_fn(mcp, "google_docs_get_document", credentials=creds)
+        with pytest.raises(TypeError, match="Expected string"):
+            fn(document_id="doc-1")
+
+    def test_credential_store_account_alias(self, mcp):
+        creds = MagicMock()
+        creds.get_by_alias.return_value = "alias-tok"
+        fn = _tool_fn(mcp, "google_docs_get_document", credentials=creds)
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"documentId": "doc-1"})
+            fn(document_id="doc-1", account="my-account")
+            creds.get_by_alias.assert_called_once_with("google", "my-account")
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Document Management
+# ---------------------------------------------------------------------------
+
+
+class TestGoogleDocsCreateDocument:
+    def test_success_returns_url(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_create_document")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"documentId": "new-doc", "title": "My Doc"}
+            )
+            result = fn(title="My Doc")
+            assert result["document_id"] == "new-doc"
+            assert "document_url" in result
+            assert "new-doc" in result["document_url"]
+
+    def test_timeout(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_create_document")
+        with patch("httpx.post", side_effect=httpx.TimeoutException("t")):
+            result = fn(title="Doc")
+            assert result == {"error": "Request timed out"}
+
+
+class TestGoogleDocsGetDocument:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_get_document")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"documentId": "doc-1", "title": "Test"})
+            result = fn(document_id="doc-1")
+            assert result["documentId"] == "doc-1"
+
+
+class TestGoogleDocsInsertText:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_insert_text")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            result = fn(document_id="doc-1", text="Hello", index=1)
+            assert "error" not in result
+
+
+class TestGoogleDocsReplaceAllText:
+    def test_success_with_count(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_replace_all_text")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200,
+                {"replies": [{"replaceAllText": {"occurrencesChanged": 3}}]},
+            )
+            result = fn(
+                document_id="doc-1",
+                find_text="{{NAME}}",
+                replace_text="Alice",
+            )
+            assert result["occurrences_replaced"] == 3
+
+
+class TestGoogleDocsInsertImage:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_insert_image")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            result = fn(
+                document_id="doc-1",
+                image_uri="https://example.com/img.png",
+                index=1,
+            )
+            assert "error" not in result
+
+    def test_invalid_uri(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_insert_image")
+        # This gets caught by the client-level validation
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            result = fn(
+                document_id="doc-1",
+                image_uri="ftp://bad.com/img.png",
+                index=1,
+            )
+            assert "error" in result
+
+
+class TestGoogleDocsFormatText:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_format_text")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            result = fn(
+                document_id="doc-1",
+                start_index=1,
+                end_index=10,
+                bold=True,
+            )
+            assert "error" not in result
+
+
+class TestGoogleDocsBatchUpdate:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_batch_update")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            requests = [{"insertText": {"text": "Hi", "location": {"index": 1}}}]
+            result = fn(
+                document_id="doc-1",
+                requests_json=json.dumps(requests),
+            )
+            assert "error" not in result
+
+    def test_invalid_json(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_batch_update")
+        result = fn(document_id="doc-1", requests_json="not json")
+        assert "error" in result
+        assert "Invalid JSON" in result["error"]
+
+    def test_non_array_json(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_batch_update")
+        result = fn(document_id="doc-1", requests_json='{"key": "value"}')
+        assert "error" in result
+        assert "JSON array" in result["error"]
+
+
+class TestGoogleDocsCreateList:
+    def test_bullet_list(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_create_list")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            result = fn(
+                document_id="doc-1",
+                start_index=1,
+                end_index=20,
+                list_type="bullet",
+            )
+            assert "error" not in result
+
+    def test_numbered_list(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_create_list")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"replies": []})
+            result = fn(
+                document_id="doc-1",
+                start_index=1,
+                end_index=20,
+                list_type="numbered",
+            )
+            assert "error" not in result
+
+
+class TestGoogleDocsAddComment:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_add_comment")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"id": "comment-1", "content": "Fix this"})
+            result = fn(document_id="doc-1", content="Fix this")
+            assert result["id"] == "comment-1"
+
+
+class TestGoogleDocsListComments:
+    def test_success_returns_structured(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_list_comments")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(
+                200,
+                {"comments": [{"id": "c1"}], "nextPageToken": "tok2"},
+            )
+            result = fn(document_id="doc-1")
+            assert result["document_id"] == "doc-1"
+            assert len(result["comments"]) == 1
+            assert result["next_page_token"] == "tok2"
+
+
+class TestGoogleDocsExportContent:
+    def test_export_pdf(self, mcp, monkeypatch):
+        monkeypatch.setenv("GOOGLE_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "google_docs_export_content")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, content=b"PDF data here")
+            result = fn(document_id="doc-1", format="pdf")
+            assert result["mime_type"] == "application/pdf"
+            assert "content_base64" in result
+
+
+# ---------------------------------------------------------------------------
+# Tool registration
+# ---------------------------------------------------------------------------
+
+
+class TestToolRegistration:
+    """Verify all Google Docs tools are registered."""
+
+    EXPECTED_TOOLS = [
+        "google_docs_create_document",
+        "google_docs_get_document",
+        "google_docs_insert_text",
+        "google_docs_replace_all_text",
+        "google_docs_insert_image",
+        "google_docs_format_text",
+        "google_docs_batch_update",
+        "google_docs_create_list",
+        "google_docs_add_comment",
+        "google_docs_list_comments",
+        "google_docs_export_content",
+    ]
+
+    def test_all_tools_registered(self, mcp):
+        tools = _register(mcp)
+        for name in self.EXPECTED_TOOLS:
+            assert name in tools, f"Tool {name} not registered"
+
+    def test_tool_count(self, mcp):
+        tools = _register(mcp)
+        gdocs_tools = [k for k in tools if k.startswith("google_docs_")]
+        assert len(gdocs_tools) == len(self.EXPECTED_TOOLS)

tools/tests/tools/test_hashline_edit.py

@@ -1304,3 +1304,96 @@ class TestPermissionsPreservation:
 
         assert result["success"] is True
         assert f.stat().st_mode & 0o777 == mode
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only ACL test")
+    def test_acl_preserved_after_edit_windows(
+        self, hashline_edit_fn, mock_workspace, mock_secure_path, tmp_path
+    ):
+        """Atomic replace preserves the target file's DACL on Windows."""
+        import ctypes
+
+        advapi32 = ctypes.windll.advapi32
+        kernel32 = ctypes.windll.kernel32
+        SE_FILE_OBJECT = 1
+        DACL_SECURITY_INFORMATION = 0x00000004
+
+        advapi32.GetNamedSecurityInfoW.argtypes = [
+            ctypes.wintypes.LPCWSTR,  # pObjectName
+            ctypes.c_uint,  # ObjectType (SE_OBJECT_TYPE enum)
+            ctypes.wintypes.DWORD,  # SecurityInfo
+            ctypes.c_void_p,  # ppsidOwner
+            ctypes.c_void_p,  # ppsidGroup
+            ctypes.c_void_p,  # ppDacl
+            ctypes.c_void_p,  # ppSacl
+            ctypes.c_void_p,  # ppSecurityDescriptor
+        ]
+        advapi32.GetNamedSecurityInfoW.restype = ctypes.wintypes.DWORD
+
+        advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW.argtypes = [
+            ctypes.c_void_p,  # SecurityDescriptor
+            ctypes.wintypes.DWORD,  # RequestedStringSDRevision
+            ctypes.wintypes.DWORD,  # SecurityInformation
+            ctypes.c_void_p,  # StringSecurityDescriptor (out)
+            ctypes.c_void_p,  # StringSecurityDescriptorLen (out, optional)
+        ]
+        advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW.restype = ctypes.wintypes.BOOL
+
+        kernel32.LocalFree.argtypes = [ctypes.c_void_p]
+        kernel32.LocalFree.restype = ctypes.c_void_p
+
+        f = tmp_path / "test.txt"
+        f.write_text("aaa\nbbb\n")
+
+        def _read_dacl_sddl(path):
+            sd = ctypes.c_void_p()
+            dacl = ctypes.c_void_p()
+            rc = advapi32.GetNamedSecurityInfoW(
+                str(path),
+                SE_FILE_OBJECT,
+                DACL_SECURITY_INFORMATION,
+                None,
+                None,
+                ctypes.byref(dacl),
+                None,
+                ctypes.byref(sd),
+            )
+            assert rc == 0, f"GetNamedSecurityInfoW failed: {rc}"
+            sddl = ctypes.c_wchar_p()
+            assert advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW(
+                sd,
+                1,
+                DACL_SECURITY_INFORMATION,
+                ctypes.byref(sddl),
+                None,
+            )
+            value = sddl.value
+            kernel32.LocalFree(sddl)
+            kernel32.LocalFree(sd)
+            return value
+
+        acl_before = _read_dacl_sddl(f)
+
+        edits = json.dumps([{"op": "set_line", "anchor": _anchor(1, "aaa"), "content": "AAA"}])
+        result = hashline_edit_fn(path="test.txt", edits=edits, **mock_workspace)
+        assert result["success"] is True
+
+        acl_after = _read_dacl_sddl(f)
+
+        assert acl_before == acl_after, f"ACL changed after edit: {acl_before} -> {acl_after}"
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only ACL test")
+    def test_edit_succeeds_when_dacl_unavailable_windows(
+        self, hashline_edit_fn, mock_workspace, mock_secure_path, tmp_path
+    ):
+        """Edit still works on volumes without ACL support (e.g. FAT32)."""
+        from aden_tools import _win32_atomic
+
+        f = tmp_path / "test.txt"
+        f.write_text("aaa\nbbb\n")
+
+        with patch.object(_win32_atomic, "snapshot_dacl", return_value=None):
+            edits = json.dumps([{"op": "set_line", "anchor": _anchor(1, "aaa"), "content": "AAA"}])
+            result = hashline_edit_fn(path="test.txt", edits=edits, **mock_workspace)
+
+        assert result["success"] is True
+        assert f.read_text().splitlines()[0].endswith("AAA")

tools/tests/tools/test_http_headers_scanner.py

@@ -0,0 +1,315 @@
+"""Tests for HTTP Headers Scanner tool."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.http_headers_scanner import register_tools
+
+
+@pytest.fixture
+def headers_tools(mcp: FastMCP):
+    """Register HTTP headers tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def scan_fn(headers_tools):
+    return headers_tools["http_headers_scan"]
+
+
+def _mock_response(
+    status_code: int = 200,
+    headers: dict | None = None,
+    url: str = "https://example.com",
+) -> MagicMock:
+    """Create a mock httpx.Response."""
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.url = url
+    resp.headers = httpx.Headers(headers or {})
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Input Validation
+# ---------------------------------------------------------------------------
+
+
+class TestInputValidation:
+    """Test URL input cleaning and validation."""
+
+    @pytest.mark.asyncio
+    async def test_auto_prefix_https(self, scan_fn):
+        mock_resp = _mock_response(headers={"strict-transport-security": "max-age=31536000"})
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("example.com")
+            assert "error" not in result
+            # Verify https was prefixed
+            mock_client.get.assert_called_once()
+            call_url = mock_client.get.call_args[0][0]
+            assert call_url.startswith("https://")
+
+
+# ---------------------------------------------------------------------------
+# Connection Errors
+# ---------------------------------------------------------------------------
+
+
+class TestConnectionErrors:
+    """Test error handling for connection failures."""
+
+    @pytest.mark.asyncio
+    async def test_connection_error(self, scan_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.side_effect = httpx.ConnectError("Connection refused")
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert "error" in result
+            assert "Connection failed" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_timeout_error(self, scan_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.side_effect = httpx.TimeoutException("Request timed out")
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert "error" in result
+            assert "timed out" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# Security Headers Detection
+# ---------------------------------------------------------------------------
+
+
+class TestSecurityHeaders:
+    """Test detection of OWASP security headers."""
+
+    @pytest.mark.asyncio
+    async def test_all_headers_present(self, scan_fn):
+        headers = {
+            "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+            "Content-Security-Policy": "default-src 'self'",
+            "X-Frame-Options": "DENY",
+            "X-Content-Type-Options": "nosniff",
+            "Referrer-Policy": "strict-origin-when-cross-origin",
+            "Permissions-Policy": "camera=(), microphone=()",
+        }
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert len(result["headers_present"]) == 6
+            assert len(result["headers_missing"]) == 0
+            assert result["grade_input"]["hsts"] is True
+            assert result["grade_input"]["csp"] is True
+
+    @pytest.mark.asyncio
+    async def test_missing_hsts(self, scan_fn):
+        headers = {
+            "Content-Security-Policy": "default-src 'self'",
+            "X-Frame-Options": "DENY",
+        }
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert result["grade_input"]["hsts"] is False
+            missing_names = [h["header"] for h in result["headers_missing"]]
+            assert "Strict-Transport-Security" in missing_names
+
+    @pytest.mark.asyncio
+    async def test_missing_csp(self, scan_fn):
+        headers = {
+            "Strict-Transport-Security": "max-age=31536000",
+        }
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert result["grade_input"]["csp"] is False
+            missing_names = [h["header"] for h in result["headers_missing"]]
+            assert "Content-Security-Policy" in missing_names
+
+
+# ---------------------------------------------------------------------------
+# Leaky Headers Detection
+# ---------------------------------------------------------------------------
+
+
+class TestLeakyHeaders:
+    """Test detection of information-leaking headers."""
+
+    @pytest.mark.asyncio
+    async def test_server_header_leaked(self, scan_fn):
+        headers = {"Server": "Apache/2.4.41 (Ubuntu)"}
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert len(result["leaky_headers"]) > 0
+            leaky_names = [h["header"] for h in result["leaky_headers"]]
+            assert "Server" in leaky_names
+            assert result["grade_input"]["no_leaky_headers"] is False
+
+    @pytest.mark.asyncio
+    async def test_x_powered_by_leaked(self, scan_fn):
+        headers = {"X-Powered-By": "PHP/8.1.0"}
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            leaky_names = [h["header"] for h in result["leaky_headers"]]
+            assert "X-Powered-By" in leaky_names
+
+    @pytest.mark.asyncio
+    async def test_no_leaky_headers(self, scan_fn):
+        headers = {
+            "Strict-Transport-Security": "max-age=31536000",
+            "Content-Type": "text/html",
+        }
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert len(result["leaky_headers"]) == 0
+            assert result["grade_input"]["no_leaky_headers"] is True
+
+
+# ---------------------------------------------------------------------------
+# Deprecated Headers
+# ---------------------------------------------------------------------------
+
+
+class TestDeprecatedHeaders:
+    """Test detection of deprecated headers."""
+
+    @pytest.mark.asyncio
+    async def test_xss_protection_deprecated(self, scan_fn):
+        headers = {"X-XSS-Protection": "1; mode=block"}
+        mock_resp = _mock_response(headers=headers)
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert "X-XSS-Protection (deprecated)" in result["headers_present"]
+
+
+# ---------------------------------------------------------------------------
+# Grade Input
+# ---------------------------------------------------------------------------
+
+
+class TestGradeInput:
+    """Test grade_input dict is properly constructed."""
+
+    @pytest.mark.asyncio
+    async def test_grade_input_keys_present(self, scan_fn):
+        mock_resp = _mock_response(headers={})
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert "grade_input" in result
+            grade = result["grade_input"]
+            assert "hsts" in grade
+            assert "csp" in grade
+            assert "x_frame_options" in grade
+            assert "x_content_type_options" in grade
+            assert "referrer_policy" in grade
+            assert "permissions_policy" in grade
+            assert "no_leaky_headers" in grade
+
+
+# ---------------------------------------------------------------------------
+# Response Metadata
+# ---------------------------------------------------------------------------
+
+
+class TestResponseMetadata:
+    """Test response metadata is captured."""
+
+    @pytest.mark.asyncio
+    async def test_status_code_captured(self, scan_fn):
+        mock_resp = _mock_response(status_code=200, headers={})
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert result["status_code"] == 200
+
+    @pytest.mark.asyncio
+    async def test_final_url_captured(self, scan_fn):
+        mock_resp = _mock_response(status_code=200, headers={}, url="https://www.example.com/")
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = mock_resp
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await scan_fn("https://example.com")
+            assert result["url"] == "https://www.example.com/"

tools/tests/tools/test_hubspot_tool.py

@@ -0,0 +1,596 @@
+"""Tests for HubSpot CRM tool with FastMCP.
+
+Covers:
+- Credential handling (credential store, env var, missing)
+- _HubSpotClient methods (search, get, create, update, delete, associations)
+- HTTP error handling (401, 403, 404, 429, 500, timeout)
+- All 12 MCP tool functions via register_tools
+- Input validation (delete_object object_type whitelist)
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.hubspot_tool.hubspot_tool import (
+    HUBSPOT_API_BASE,
+    _HubSpotClient,
+    register_tools,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def mcp():
+    """Create a FastMCP instance for testing."""
+    return FastMCP("test-server")
+
+
+@pytest.fixture
+def client():
+    """Create a _HubSpotClient with a test token."""
+    return _HubSpotClient("test-token")
+
+
+def _register(mcp, credentials=None):
+    """Helper to register tools and return the tool lookup dict."""
+    register_tools(mcp, credentials=credentials)
+    return mcp._tool_manager._tools
+
+
+def _tool_fn(mcp, name, credentials=None):
+    """Register tools and return a single tool function by name."""
+    tools = _register(mcp, credentials)
+    return tools[name].fn
+
+
+def _mock_response(status_code=200, json_data=None, text=""):
+    """Create a mock httpx.Response."""
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.text = text
+    if json_data is not None:
+        resp.json.return_value = json_data
+    else:
+        resp.json.return_value = {}
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# _HubSpotClient unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotClientHeaders:
+    """Verify client sends correct auth headers."""
+
+    def test_headers_contain_bearer_token(self, client):
+        headers = client._headers
+        assert headers["Authorization"] == "Bearer test-token"
+        assert headers["Content-Type"] == "application/json"
+        assert headers["Accept"] == "application/json"
+
+
+class TestHubSpotClientHandleResponse:
+    """Verify _handle_response maps HTTP codes to error dicts."""
+
+    @pytest.mark.parametrize(
+        "status_code,expected_substr",
+        [
+            (401, "Invalid or expired"),
+            (403, "Insufficient permissions"),
+            (404, "not found"),
+            (429, "rate limit"),
+        ],
+    )
+    def test_known_error_codes(self, client, status_code, expected_substr):
+        resp = _mock_response(status_code=status_code)
+        result = client._handle_response(resp)
+        assert "error" in result
+        assert expected_substr in result["error"]
+
+    def test_generic_4xx_with_json_message(self, client):
+        resp = _mock_response(
+            status_code=422,
+            json_data={"message": "Property not found"},
+        )
+        result = client._handle_response(resp)
+        assert "error" in result
+        assert "422" in result["error"]
+        assert "Property not found" in result["error"]
+
+    def test_generic_5xx_fallback_to_text(self, client):
+        resp = _mock_response(status_code=500, text="Internal Server Error")
+        resp.json.side_effect = Exception("not json")
+        result = client._handle_response(resp)
+        assert "error" in result
+        assert "500" in result["error"]
+
+    def test_success_returns_json(self, client):
+        resp = _mock_response(status_code=200, json_data={"id": "123"})
+        result = client._handle_response(resp)
+        assert result == {"id": "123"}
+
+
+class TestHubSpotClientSearchObjects:
+    """Tests for _HubSpotClient.search_objects."""
+
+    def test_search_posts_correct_url(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": [], "total": 0})
+            client.search_objects("contacts", query="test@example.com")
+            mock_post.assert_called_once()
+            args, kwargs = mock_post.call_args
+            assert args[0] == f"{HUBSPOT_API_BASE}/crm/v3/objects/contacts/search"
+
+    def test_search_sends_query_and_properties(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": []})
+            client.search_objects(
+                "contacts",
+                query="jane",
+                properties=["email", "firstname"],
+                limit=5,
+            )
+            body = mock_post.call_args.kwargs["json"]
+            assert body["query"] == "jane"
+            assert body["properties"] == ["email", "firstname"]
+            assert body["limit"] == 5
+
+    def test_search_clamps_limit_to_100(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": []})
+            client.search_objects("contacts", limit=999)
+            body = mock_post.call_args.kwargs["json"]
+            assert body["limit"] == 100
+
+
+class TestHubSpotClientGetObject:
+    """Tests for _HubSpotClient.get_object."""
+
+    def test_get_object_url(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "42"})
+            client.get_object("contacts", "42")
+            args, _ = mock_get.call_args
+            assert args[0] == f"{HUBSPOT_API_BASE}/crm/v3/objects/contacts/42"
+
+    def test_get_object_passes_properties(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "42"})
+            client.get_object("contacts", "42", properties=["email", "phone"])
+            params = mock_get.call_args.kwargs["params"]
+            assert params["properties"] == "email,phone"
+
+
+class TestHubSpotClientCreateObject:
+    """Tests for _HubSpotClient.create_object."""
+
+    def test_create_object_posts_properties(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"id": "99", "properties": {"email": "a@b.com"}}
+            )
+            result = client.create_object("contacts", {"email": "a@b.com", "firstname": "Alice"})
+            body = mock_post.call_args.kwargs["json"]
+            assert body == {"properties": {"email": "a@b.com", "firstname": "Alice"}}
+            assert result["id"] == "99"
+
+
+class TestHubSpotClientUpdateObject:
+    """Tests for _HubSpotClient.update_object."""
+
+    def test_update_object_uses_patch(self, client):
+        with patch("httpx.patch") as mock_patch:
+            mock_patch.return_value = _mock_response(200, {"id": "42"})
+            client.update_object("contacts", "42", {"phone": "+1234567890"})
+            mock_patch.assert_called_once()
+            args, kwargs = mock_patch.call_args
+            assert "/contacts/42" in args[0]
+            assert kwargs["json"] == {"properties": {"phone": "+1234567890"}}
+
+
+class TestHubSpotClientDeleteObject:
+    """Tests for _HubSpotClient.delete_object."""
+
+    def test_delete_returns_status_on_204(self, client):
+        with patch("httpx.delete") as mock_delete:
+            mock_delete.return_value = _mock_response(status_code=204)
+            result = client.delete_object("contacts", "42")
+            assert result["status"] == "deleted"
+            assert result["object_id"] == "42"
+
+    def test_delete_non_204_delegates_to_handle_response(self, client):
+        with patch("httpx.delete") as mock_delete:
+            mock_delete.return_value = _mock_response(
+                status_code=404, json_data={"message": "Not found"}
+            )
+            result = client.delete_object("contacts", "42")
+            assert "error" in result
+
+
+class TestHubSpotClientAssociations:
+    """Tests for association-related client methods."""
+
+    def test_list_associations_url(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"results": []})
+            client.list_associations("contacts", "1", "companies")
+            args, _ = mock_get.call_args
+            assert "/crm/v4/objects/contacts/1/associations/companies" in args[0]
+
+    def test_list_associations_clamps_limit(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"results": []})
+            client.list_associations("contacts", "1", "companies", limit=999)
+            params = mock_get.call_args.kwargs["params"]
+            assert params["limit"] == 500
+
+    def test_create_association_uses_put(self, client):
+        with patch("httpx.put") as mock_put:
+            mock_put.return_value = _mock_response(200, {"status": "ok"})
+            client.create_association("contacts", "1", "companies", "2")
+            mock_put.assert_called_once()
+            body = mock_put.call_args.kwargs["json"]
+            assert body[0]["associationCategory"] == "HUBSPOT_DEFINED"
+
+
+# ---------------------------------------------------------------------------
+# Credential handling via register_tools
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotCredentials:
+    """Tests for credential resolution in MCP tool functions."""
+
+    def test_no_credentials_returns_error(self, mcp, monkeypatch):
+        monkeypatch.delenv("HUBSPOT_ACCESS_TOKEN", raising=False)
+        fn = _tool_fn(mcp, "hubspot_search_contacts")
+        result = fn()
+        assert "error" in result
+        assert "not configured" in result["error"]
+        assert "help" in result
+
+    def test_env_var_credential(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "env-token")
+        fn = _tool_fn(mcp, "hubspot_search_contacts")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": []})
+            fn(query="test")
+            headers = mock_post.call_args.kwargs["headers"]
+            assert headers["Authorization"] == "Bearer env-token"
+
+    def test_credential_store_used_when_provided(self, mcp):
+        creds = MagicMock()
+        creds.get.return_value = "store-token"
+        fn = _tool_fn(mcp, "hubspot_search_contacts", credentials=creds)
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": []})
+            fn(query="test")
+            creds.get.assert_called_once_with("hubspot")
+            headers = mock_post.call_args.kwargs["headers"]
+            assert headers["Authorization"] == "Bearer store-token"
+
+    def test_credential_store_non_string_raises(self, mcp):
+        creds = MagicMock()
+        creds.get.return_value = {"access_token": "bad"}
+        fn = _tool_fn(mcp, "hubspot_search_contacts", credentials=creds)
+        with pytest.raises(TypeError, match="Expected string"):
+            fn(query="test")
+
+    def test_credential_store_account_alias(self, mcp):
+        creds = MagicMock()
+        creds.get_by_alias.return_value = "alias-token"
+        fn = _tool_fn(mcp, "hubspot_search_contacts", credentials=creds)
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": []})
+            fn(query="test", account="my-account")
+            creds.get_by_alias.assert_called_once_with("hubspot", "my-account")
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Contacts
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotSearchContacts:
+    """Tests for hubspot_search_contacts tool."""
+
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_search_contacts")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": [{"id": "1"}], "total": 1})
+            result = fn(query="jane")
+            assert result["total"] == 1
+
+    def test_timeout(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_search_contacts")
+        with patch("httpx.post", side_effect=httpx.TimeoutException("timeout")):
+            result = fn(query="jane")
+            assert result == {"error": "Request timed out"}
+
+    def test_network_error(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_search_contacts")
+        with patch("httpx.post", side_effect=httpx.RequestError("dns fail")):
+            result = fn(query="jane")
+            assert "Network error" in result["error"]
+
+
+class TestHubSpotGetContact:
+    """Tests for hubspot_get_contact tool."""
+
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_get_contact")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(
+                200, {"id": "42", "properties": {"email": "a@b.com"}}
+            )
+            result = fn(contact_id="42")
+            assert result["id"] == "42"
+
+    def test_404(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_get_contact")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(status_code=404)
+            result = fn(contact_id="999")
+            assert "error" in result
+            assert "not found" in result["error"]
+
+
+class TestHubSpotCreateContact:
+    """Tests for hubspot_create_contact tool."""
+
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_create_contact")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"id": "99", "properties": {"email": "new@example.com"}}
+            )
+            result = fn(properties={"email": "new@example.com"})
+            assert result["id"] == "99"
+
+
+class TestHubSpotUpdateContact:
+    """Tests for hubspot_update_contact tool."""
+
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_update_contact")
+        with patch("httpx.patch") as mock_patch:
+            mock_patch.return_value = _mock_response(200, {"id": "42"})
+            result = fn(contact_id="42", properties={"phone": "+1234567890"})
+            assert result["id"] == "42"
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Companies
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotSearchCompanies:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_search_companies")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": [{"id": "c1"}], "total": 1})
+            result = fn(query="Acme")
+            assert result["total"] == 1
+
+
+class TestHubSpotGetCompany:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_get_company")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(
+                200, {"id": "c1", "properties": {"name": "Acme"}}
+            )
+            result = fn(company_id="c1")
+            assert result["id"] == "c1"
+
+
+class TestHubSpotCreateCompany:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_create_company")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"id": "c2", "properties": {"name": "NewCo"}}
+            )
+            result = fn(properties={"name": "NewCo"})
+            assert result["id"] == "c2"
+
+
+class TestHubSpotUpdateCompany:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_update_company")
+        with patch("httpx.patch") as mock_patch:
+            mock_patch.return_value = _mock_response(200, {"id": "c1"})
+            result = fn(company_id="c1", properties={"industry": "Finance"})
+            assert result["id"] == "c1"
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Deals
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotSearchDeals:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_search_deals")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"results": [{"id": "d1"}], "total": 1})
+            result = fn(query="big deal")
+            assert result["total"] == 1
+
+
+class TestHubSpotGetDeal:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_get_deal")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(
+                200, {"id": "d1", "properties": {"dealname": "Big Deal"}}
+            )
+            result = fn(deal_id="d1")
+            assert result["id"] == "d1"
+
+
+class TestHubSpotCreateDeal:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_create_deal")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"id": "d2", "properties": {"dealname": "New Deal"}}
+            )
+            result = fn(properties={"dealname": "New Deal", "amount": "10000"})
+            assert result["id"] == "d2"
+
+
+class TestHubSpotUpdateDeal:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_update_deal")
+        with patch("httpx.patch") as mock_patch:
+            mock_patch.return_value = _mock_response(200, {"id": "d1"})
+            result = fn(deal_id="d1", properties={"amount": "15000"})
+            assert result["id"] == "d1"
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Delete
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotDeleteObject:
+    """Tests for hubspot_delete_object tool."""
+
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_delete_object")
+        with patch("httpx.delete") as mock_delete:
+            mock_delete.return_value = _mock_response(status_code=204)
+            result = fn(object_type="contacts", object_id="42")
+            assert result["status"] == "deleted"
+
+    def test_invalid_object_type(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_delete_object")
+        result = fn(object_type="tickets", object_id="1")
+        assert "error" in result
+        assert "Unsupported object_type" in result["error"]
+
+    @pytest.mark.parametrize("valid_type", ["contacts", "companies", "deals"])
+    def test_all_valid_object_types(self, mcp, monkeypatch, valid_type):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_delete_object")
+        with patch("httpx.delete") as mock_delete:
+            mock_delete.return_value = _mock_response(status_code=204)
+            result = fn(object_type=valid_type, object_id="1")
+            assert result["status"] == "deleted"
+
+    def test_timeout(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_delete_object")
+        with patch("httpx.delete", side_effect=httpx.TimeoutException("t")):
+            result = fn(object_type="contacts", object_id="1")
+            assert result == {"error": "Request timed out"}
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Associations
+# ---------------------------------------------------------------------------
+
+
+class TestHubSpotListAssociations:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_list_associations")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"results": [{"toObjectId": "c1"}]})
+            result = fn(
+                from_object_type="contacts",
+                from_object_id="1",
+                to_object_type="companies",
+            )
+            assert "results" in result
+
+    def test_timeout(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_list_associations")
+        with patch("httpx.get", side_effect=httpx.TimeoutException("t")):
+            result = fn(
+                from_object_type="contacts",
+                from_object_id="1",
+                to_object_type="companies",
+            )
+            assert result == {"error": "Request timed out"}
+
+
+class TestHubSpotCreateAssociation:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("HUBSPOT_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "hubspot_create_association")
+        with patch("httpx.put") as mock_put:
+            mock_put.return_value = _mock_response(200, {"status": "ok"})
+            result = fn(
+                from_object_type="contacts",
+                from_object_id="1",
+                to_object_type="companies",
+                to_object_id="2",
+            )
+            assert result == {"status": "ok"}
+
+
+# ---------------------------------------------------------------------------
+# Tool registration
+# ---------------------------------------------------------------------------
+
+
+class TestToolRegistration:
+    """Verify all 12 HubSpot tools are registered."""
+
+    EXPECTED_TOOLS = [
+        "hubspot_search_contacts",
+        "hubspot_get_contact",
+        "hubspot_create_contact",
+        "hubspot_update_contact",
+        "hubspot_search_companies",
+        "hubspot_get_company",
+        "hubspot_create_company",
+        "hubspot_update_company",
+        "hubspot_search_deals",
+        "hubspot_get_deal",
+        "hubspot_create_deal",
+        "hubspot_update_deal",
+        "hubspot_delete_object",
+        "hubspot_list_associations",
+        "hubspot_create_association",
+    ]
+
+    def test_all_tools_registered(self, mcp):
+        tools = _register(mcp)
+        for name in self.EXPECTED_TOOLS:
+            assert name in tools, f"Tool {name} not registered"
+
+    def test_tool_count(self, mcp):
+        tools = _register(mcp)
+        # Filter to only hubspot tools
+        hubspot_tools = [k for k in tools if k.startswith("hubspot_")]
+        assert len(hubspot_tools) == len(self.EXPECTED_TOOLS)

tools/tests/tools/test_intercom_tool.py

@@ -0,0 +1,543 @@
+"""Tests for Intercom tool with FastMCP.
+
+Covers:
+- Credential handling (credential store, env var, missing)
+- _IntercomClient methods (search, get, reply, assign, tag, close, create)
+- HTTP error handling (401, 403, 404, 429, 500, timeout)
+- All MCP tool functions via register_tools
+- Input validation (status, assignee_type, limit, role, tag exclusivity)
+- Admin ID lazy-fetch via /me
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.intercom_tool.intercom_tool import (
+    INTERCOM_API_BASE,
+    _IntercomClient,
+    register_tools,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def mcp():
+    """Create a FastMCP instance for testing."""
+    return FastMCP("test-server")
+
+
+@pytest.fixture
+def client():
+    """Create an _IntercomClient with a test token."""
+    return _IntercomClient("test-token")
+
+
+def _register(mcp, credentials=None):
+    """Helper to register tools and return the tool lookup dict."""
+    register_tools(mcp, credentials=credentials)
+    return mcp._tool_manager._tools
+
+
+def _tool_fn(mcp, name, credentials=None):
+    """Register tools and return a single tool function by name."""
+    tools = _register(mcp, credentials)
+    return tools[name].fn
+
+
+def _mock_response(status_code=200, json_data=None, text=""):
+    """Create a mock httpx.Response."""
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.text = text
+    if json_data is not None:
+        resp.json.return_value = json_data
+    else:
+        resp.json.return_value = {}
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# _IntercomClient unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestIntercomClientHeaders:
+    """Verify client sends correct auth and version headers."""
+
+    def test_headers_contain_bearer_token(self, client):
+        headers = client._headers
+        assert headers["Authorization"] == "Bearer test-token"
+        assert headers["Intercom-Version"] == "2.11"
+        assert headers["Content-Type"] == "application/json"
+
+
+class TestIntercomClientHandleResponse:
+    """Verify _handle_response maps HTTP codes to error dicts."""
+
+    @pytest.mark.parametrize(
+        "status_code,expected_substr",
+        [
+            (401, "Invalid or expired"),
+            (403, "Insufficient permissions"),
+            (404, "not found"),
+            (429, "rate limit"),
+        ],
+    )
+    def test_known_error_codes(self, client, status_code, expected_substr):
+        resp = _mock_response(status_code=status_code)
+        result = client._handle_response(resp)
+        assert "error" in result
+        assert expected_substr in result["error"]
+
+    def test_intercom_error_list_format(self, client):
+        resp = _mock_response(
+            status_code=422,
+            json_data={
+                "type": "error.list",
+                "errors": [{"message": "Field is required"}],
+            },
+        )
+        result = client._handle_response(resp)
+        assert "Field is required" in result["error"]
+
+    def test_generic_error_fallback_to_text(self, client):
+        resp = _mock_response(status_code=500, text="Server Error")
+        resp.json.side_effect = Exception("not json")
+        result = client._handle_response(resp)
+        assert "500" in result["error"]
+
+    def test_success_returns_json(self, client):
+        resp = _mock_response(200, {"id": "abc"})
+        assert client._handle_response(resp) == {"id": "abc"}
+
+
+class TestIntercomClientAdminId:
+    """Tests for lazy admin ID fetching via /me."""
+
+    def test_fetches_admin_id_on_first_call(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "admin-123"})
+            result = client._get_admin_id()
+            assert result == "admin-123"
+            mock_get.assert_called_once()
+            assert INTERCOM_API_BASE + "/me" in mock_get.call_args[0][0]
+
+    def test_caches_admin_id(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "admin-123"})
+            client._get_admin_id()
+            client._get_admin_id()
+            # Only called once due to caching
+            assert mock_get.call_count == 1
+
+    def test_returns_error_on_failure(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(401)
+            result = client._get_admin_id()
+            assert isinstance(result, dict)
+            assert "error" in result
+
+
+class TestIntercomClientSearchConversations:
+    def test_posts_to_correct_url(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"conversations": []})
+            client.search_conversations({"field": "state", "operator": "=", "value": "open"})
+            args, _ = mock_post.call_args
+            assert args[0] == f"{INTERCOM_API_BASE}/conversations/search"
+
+    def test_clamps_limit(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"conversations": []})
+            client.search_conversations({}, limit=999)
+            body = mock_post.call_args.kwargs["json"]
+            assert body["pagination"]["per_page"] == 150
+
+
+class TestIntercomClientGetConversation:
+    def test_url_and_plaintext_param(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "conv-1"})
+            client.get_conversation("conv-1")
+            args, kwargs = mock_get.call_args
+            assert "/conversations/conv-1" in args[0]
+            assert kwargs["params"]["display_as"] == "plaintext"
+
+
+class TestIntercomClientReplyToConversation:
+    def test_reply_sends_admin_id(self, client):
+        client._admin_id = "admin-1"
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"type": "conversation_part"})
+            client.reply_to_conversation("conv-1", body="Hello", message_type="comment")
+            body = mock_post.call_args.kwargs["json"]
+            assert body["admin_id"] == "admin-1"
+            assert body["message_type"] == "comment"
+            assert body["body"] == "Hello"
+
+
+class TestIntercomClientCreateContact:
+    def test_creates_with_role_and_email(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"id": "contact-1", "role": "user"})
+            client.create_contact(role="user", email="test@example.com")
+            body = mock_post.call_args.kwargs["json"]
+            assert body["role"] == "user"
+            assert body["email"] == "test@example.com"
+
+    def test_omits_none_fields(self, client):
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"id": "contact-1"})
+            client.create_contact(role="lead")
+            body = mock_post.call_args.kwargs["json"]
+            assert "email" not in body
+            assert "name" not in body
+
+
+class TestIntercomClientListConversations:
+    def test_passes_pagination_params(self, client):
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"conversations": []})
+            client.list_conversations(limit=10, starting_after="cursor-abc")
+            params = mock_get.call_args.kwargs["params"]
+            assert params["per_page"] == 10
+            assert params["starting_after"] == "cursor-abc"
+
+
+# ---------------------------------------------------------------------------
+# Credential handling via register_tools
+# ---------------------------------------------------------------------------
+
+
+class TestIntercomCredentials:
+    """Tests for credential resolution in MCP tool functions."""
+
+    def test_no_credentials_returns_error(self, mcp, monkeypatch):
+        monkeypatch.delenv("INTERCOM_ACCESS_TOKEN", raising=False)
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        result = fn()
+        assert "error" in result
+        assert "not configured" in result["error"]
+
+    def test_env_var_credential(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "env-tok")
+        fn = _tool_fn(mcp, "intercom_list_teams")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"teams": []})
+            fn()
+            headers = mock_get.call_args.kwargs["headers"]
+            assert headers["Authorization"] == "Bearer env-tok"
+
+    def test_credential_store_used(self, mcp):
+        creds = MagicMock()
+        creds.get.return_value = "store-tok"
+        fn = _tool_fn(mcp, "intercom_list_teams", credentials=creds)
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"teams": []})
+            fn()
+            creds.get.assert_called_once_with("intercom")
+
+    def test_credential_store_non_string_raises(self, mcp):
+        creds = MagicMock()
+        creds.get.return_value = 12345
+        fn = _tool_fn(mcp, "intercom_list_teams", credentials=creds)
+        with pytest.raises(TypeError, match="Expected string"):
+            fn()
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Conversations
+# ---------------------------------------------------------------------------
+
+
+class TestIntercomSearchConversations:
+    def test_no_filters_returns_recent(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"conversations": [{"id": "1"}]})
+            result = fn()
+            assert "conversations" in result
+
+    def test_invalid_status(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        result = fn(status="invalid")
+        assert "error" in result
+        assert "status" in result["error"]
+
+    def test_invalid_limit_too_high(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        result = fn(limit=200)
+        assert "error" in result
+        assert "limit" in result["error"]
+
+    def test_invalid_limit_too_low(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        result = fn(limit=0)
+        assert "error" in result
+
+    def test_status_filter_applied(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"conversations": []})
+            fn(status="open")
+            body = mock_post.call_args.kwargs["json"]
+            query = body["query"]
+            assert query["field"] == "state"
+            assert query["value"] == "open"
+
+    def test_invalid_created_after(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        result = fn(created_after="not-a-date")
+        assert "error" in result
+        assert "ISO date" in result["error"]
+
+    def test_timeout(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_conversations")
+        with patch("httpx.post", side_effect=httpx.TimeoutException("t")):
+            result = fn()
+            assert result == {"error": "Request timed out"}
+
+
+class TestIntercomGetConversation:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_get_conversation")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "conv-1", "state": "open"})
+            result = fn(conversation_id="conv-1")
+            assert result["id"] == "conv-1"
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Contacts
+# ---------------------------------------------------------------------------
+
+
+class TestIntercomGetContact:
+    def test_by_id(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_get_contact")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"id": "c1", "email": "a@b.com"})
+            result = fn(contact_id="c1")
+            assert result["id"] == "c1"
+
+    def test_by_email_fallback(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_get_contact")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(
+                200, {"data": [{"id": "c1", "email": "a@b.com"}]}
+            )
+            result = fn(email="a@b.com")
+            assert result["id"] == "c1"
+
+    def test_no_id_or_email(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_get_contact")
+        result = fn()
+        assert "error" in result
+        assert "contact_id or email" in result["error"]
+
+    def test_email_not_found(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_get_contact")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"data": []})
+            result = fn(email="missing@example.com")
+            assert "error" in result
+            assert "No contact found" in result["error"]
+
+
+class TestIntercomSearchContacts:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_contacts")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"data": [{"id": "c1"}]})
+            result = fn(query="jane")
+            assert "data" in result
+
+    def test_invalid_limit(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_search_contacts")
+        result = fn(query="test", limit=200)
+        assert "error" in result
+        assert "limit" in result["error"]
+
+
+class TestIntercomCreateContact:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_create_contact")
+        with patch("httpx.post") as mock_post:
+            mock_post.return_value = _mock_response(200, {"id": "new-c", "role": "user"})
+            result = fn(email="new@example.com")
+            assert result["id"] == "new-c"
+
+    def test_invalid_role(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_create_contact")
+        result = fn(role="admin")
+        assert "error" in result
+        assert "role" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# MCP tool function tests — Notes, Tags, Assignment
+# ---------------------------------------------------------------------------
+
+
+class TestIntercomAddNote:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_add_note")
+        with patch("httpx.get") as mock_get, patch("httpx.post") as mock_post:
+            mock_get.return_value = _mock_response(200, {"id": "admin-1"})
+            mock_post.return_value = _mock_response(200, {"type": "conversation_part"})
+            result = fn(conversation_id="conv-1", body="Internal note")
+            assert result["type"] == "conversation_part"
+
+
+class TestIntercomAddTag:
+    def test_must_provide_target(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_add_tag")
+        result = fn(name="vip")
+        assert "error" in result
+        assert "conversation_id or contact_id" in result["error"]
+
+    def test_cannot_provide_both_targets(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_add_tag")
+        result = fn(name="vip", conversation_id="c1", contact_id="ct1")
+        assert "error" in result
+        assert "not both" in result["error"]
+
+    def test_tag_conversation_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_add_tag")
+        with patch("httpx.get") as mock_get, patch("httpx.post") as mock_post:
+            mock_get.return_value = _mock_response(200, {"id": "admin-1"})
+            # First post: create_or_get_tag, second: tag_conversation
+            mock_post.side_effect = [
+                _mock_response(200, {"id": "tag-1", "name": "vip"}),
+                _mock_response(200, {"tags": {"tags": [{"id": "tag-1"}]}}),
+            ]
+            result = fn(name="vip", conversation_id="conv-1")
+            assert "error" not in result
+
+
+class TestIntercomAssignConversation:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_assign_conversation")
+        with patch("httpx.get") as mock_get, patch("httpx.post") as mock_post:
+            mock_get.return_value = _mock_response(200, {"id": "admin-1"})
+            mock_post.return_value = _mock_response(
+                200, {"id": "conv-1", "assignee": {"id": "admin-2"}}
+            )
+            result = fn(
+                conversation_id="conv-1",
+                assignee_id="admin-2",
+            )
+            assert "error" not in result
+
+    def test_invalid_assignee_type(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_assign_conversation")
+        result = fn(
+            conversation_id="conv-1",
+            assignee_id="1",
+            assignee_type="bot",
+        )
+        assert "error" in result
+        assert "assignee_type" in result["error"]
+
+
+class TestIntercomCloseConversation:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_close_conversation")
+        with patch("httpx.get") as mock_get, patch("httpx.post") as mock_post:
+            mock_get.return_value = _mock_response(200, {"id": "admin-1"})
+            mock_post.return_value = _mock_response(200, {"state": "closed"})
+            result = fn(conversation_id="conv-1")
+            assert "error" not in result
+
+    def test_empty_conversation_id(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_close_conversation")
+        result = fn(conversation_id="")
+        assert "error" in result
+        assert "required" in result["error"]
+
+
+class TestIntercomListTeams:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_list_teams")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(
+                200, {"teams": [{"id": "t1", "name": "Support"}]}
+            )
+            result = fn()
+            assert "teams" in result
+
+
+class TestIntercomListConversations:
+    def test_success(self, mcp, monkeypatch):
+        monkeypatch.setenv("INTERCOM_ACCESS_TOKEN", "tok")
+        fn = _tool_fn(mcp, "intercom_list_conversations")
+        with patch("httpx.get") as mock_get:
+            mock_get.return_value = _mock_response(200, {"conversations": [{"id": "conv-1"}]})
+            result = fn(limit=5)
+            assert "conversations" in result
+
+
+# ---------------------------------------------------------------------------
+# Tool registration
+# ---------------------------------------------------------------------------
+
+
+class TestToolRegistration:
+    """Verify all Intercom tools are registered."""
+
+    EXPECTED_TOOLS = [
+        "intercom_search_conversations",
+        "intercom_get_conversation",
+        "intercom_get_contact",
+        "intercom_search_contacts",
+        "intercom_add_note",
+        "intercom_add_tag",
+        "intercom_assign_conversation",
+        "intercom_list_teams",
+        "intercom_close_conversation",
+        "intercom_create_contact",
+        "intercom_list_conversations",
+    ]
+
+    def test_all_tools_registered(self, mcp):
+        tools = _register(mcp)
+        for name in self.EXPECTED_TOOLS:
+            assert name in tools, f"Tool {name} not registered"
+
+    def test_tool_count(self, mcp):
+        tools = _register(mcp)
+        intercom_tools = [k for k in tools if k.startswith("intercom_")]
+        assert len(intercom_tools) == len(self.EXPECTED_TOOLS)

tools/tests/tools/test_port_scanner.py

@@ -0,0 +1,282 @@
+"""Tests for Port Scanner tool."""
+
+from __future__ import annotations
+
+import socket
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.port_scanner import register_tools
+
+
+@pytest.fixture
+def port_tools(mcp: FastMCP):
+    """Register port scanner tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def scan_fn(port_tools):
+    return port_tools["port_scan"]
+
+
+# ---------------------------------------------------------------------------
+# Input Validation
+# ---------------------------------------------------------------------------
+
+
+class TestInputValidation:
+    """Test hostname and port input validation."""
+
+    @pytest.mark.asyncio
+    async def test_strips_https_prefix(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("https://example.com", ports="80")
+                assert result["hostname"] == "example.com"
+
+    @pytest.mark.asyncio
+    async def test_strips_path(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("example.com/path", ports="80")
+                assert result["hostname"] == "example.com"
+
+    @pytest.mark.asyncio
+    async def test_invalid_port_list(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            result = await scan_fn("example.com", ports="invalid,ports")
+            assert "error" in result
+            assert "Invalid port list" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_custom_port_list(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("example.com", ports="22,80,443")
+                assert result["ports_scanned"] == 3
+
+    @pytest.mark.asyncio
+    async def test_timeout_clamped(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                # Timeout > 10 should be clamped
+                result = await scan_fn("example.com", ports="80", timeout=100.0)
+                assert "error" not in result
+                assert mock_check.call_args[0][2] <= 10.0
+
+
+# ---------------------------------------------------------------------------
+# DNS Resolution Errors
+# ---------------------------------------------------------------------------
+
+
+class TestDnsResolution:
+    """Test DNS resolution error handling."""
+
+    @pytest.mark.asyncio
+    async def test_hostname_not_found(self, scan_fn):
+        with patch("socket.gethostbyname", side_effect=socket.gaierror("not found")):
+            result = await scan_fn("nonexistent.invalid")
+            assert "error" in result
+            assert "resolve hostname" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# Port Scanning
+# ---------------------------------------------------------------------------
+
+
+class TestPortScanning:
+    """Test port scanning functionality."""
+
+    @pytest.mark.asyncio
+    async def test_open_port_detected(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": True, "banner": ""}
+                result = await scan_fn("example.com", ports="80")
+                assert len(result["open_ports"]) == 1
+                assert result["open_ports"][0]["port"] == 80
+
+    @pytest.mark.asyncio
+    async def test_closed_port_detected(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("example.com", ports="12345")
+                assert len(result["open_ports"]) == 0
+                assert 12345 in result["closed_ports"]
+
+    @pytest.mark.asyncio
+    async def test_banner_captured(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": True, "banner": "SSH-2.0-OpenSSH_8.9"}
+                result = await scan_fn("example.com", ports="22")
+                assert result["open_ports"][0]["banner"] == "SSH-2.0-OpenSSH_8.9"
+
+
+# ---------------------------------------------------------------------------
+# Risky Port Detection
+# ---------------------------------------------------------------------------
+
+
+class TestRiskyPorts:
+    """Test detection of risky exposed ports."""
+
+    @pytest.mark.asyncio
+    async def test_database_port_flagged(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": True, "banner": ""}
+                result = await scan_fn("example.com", ports="3306")  # MySQL
+                assert result["open_ports"][0]["severity"] == "high"
+                assert "MySQL" in result["open_ports"][0]["finding"]
+                assert result["grade_input"]["no_database_ports_exposed"] is False
+
+    @pytest.mark.asyncio
+    async def test_admin_port_flagged(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": True, "banner": ""}
+                result = await scan_fn("example.com", ports="3389")  # RDP
+                assert result["open_ports"][0]["severity"] == "high"
+                assert result["grade_input"]["no_admin_ports_exposed"] is False
+
+    @pytest.mark.asyncio
+    async def test_legacy_port_flagged(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": True, "banner": ""}
+                result = await scan_fn("example.com", ports="23")  # Telnet
+                assert result["open_ports"][0]["severity"] == "medium"
+                assert result["grade_input"]["no_legacy_ports_exposed"] is False
+
+
+# ---------------------------------------------------------------------------
+# Grade Input
+# ---------------------------------------------------------------------------
+
+
+class TestGradeInput:
+    """Test grade_input dict is properly constructed."""
+
+    @pytest.mark.asyncio
+    async def test_grade_input_keys_present(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("example.com", ports="80")
+                assert "grade_input" in result
+                grade = result["grade_input"]
+                assert "no_database_ports_exposed" in grade
+                assert "no_admin_ports_exposed" in grade
+                assert "no_legacy_ports_exposed" in grade
+                assert "only_web_ports" in grade
+
+    @pytest.mark.asyncio
+    async def test_only_web_ports_true(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                # Only 80 and 443 open
+                async def check_port(ip, port, timeout):
+                    if port in (80, 443):
+                        return {"open": True, "banner": ""}
+                    return {"open": False}
+
+                mock_check.side_effect = check_port
+                result = await scan_fn("example.com", ports="22,80,443")
+                assert result["grade_input"]["only_web_ports"] is True
+
+    @pytest.mark.asyncio
+    async def test_only_web_ports_false(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                # SSH port also open
+                async def check_port(ip, port, timeout):
+                    if port in (22, 80, 443):
+                        return {"open": True, "banner": ""}
+                    return {"open": False}
+
+                mock_check.side_effect = check_port
+                result = await scan_fn("example.com", ports="22,80,443")
+                assert result["grade_input"]["only_web_ports"] is False
+
+
+# ---------------------------------------------------------------------------
+# Top20/Top100 Port Lists
+# ---------------------------------------------------------------------------
+
+
+class TestPortLists:
+    """Test predefined port lists."""
+
+    @pytest.mark.asyncio
+    async def test_top20_ports(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("example.com", ports="top20")
+                assert result["ports_scanned"] == 20
+
+    @pytest.mark.asyncio
+    async def test_top100_ports(self, scan_fn):
+        with patch("socket.gethostbyname", return_value="93.184.216.34"):
+            with patch(
+                "aden_tools.tools.port_scanner.port_scanner._check_port",
+                new_callable=AsyncMock,
+            ) as mock_check:
+                mock_check.return_value = {"open": False}
+                result = await scan_fn("example.com", ports="top100")
+                assert result["ports_scanned"] > 20

tools/tests/tools/test_risk_scorer.py

@@ -0,0 +1,316 @@
+"""Tests for Risk Scorer tool."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.risk_scorer import register_tools
+from aden_tools.tools.risk_scorer.risk_scorer import (
+    SSL_CHECKS,
+    _parse_json,
+    _score_category,
+    _score_to_grade,
+)
+
+
+@pytest.fixture
+def risk_tools(mcp: FastMCP):
+    """Register risk scorer tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def score_fn(risk_tools):
+    return risk_tools["risk_score"]
+
+
+# ---------------------------------------------------------------------------
+# Helper Function Tests
+# ---------------------------------------------------------------------------
+
+
+class TestScoreToGrade:
+    """Test _score_to_grade helper."""
+
+    def test_grade_a(self):
+        assert _score_to_grade(95) == "A"
+        assert _score_to_grade(90) == "A"
+
+    def test_grade_b(self):
+        assert _score_to_grade(85) == "B"
+        assert _score_to_grade(75) == "B"
+
+    def test_grade_c(self):
+        assert _score_to_grade(70) == "C"
+        assert _score_to_grade(60) == "C"
+
+    def test_grade_d(self):
+        assert _score_to_grade(55) == "D"
+        assert _score_to_grade(40) == "D"
+
+    def test_grade_f(self):
+        assert _score_to_grade(39) == "F"
+        assert _score_to_grade(0) == "F"
+
+
+class TestParseJson:
+    """Test _parse_json helper."""
+
+    def test_valid_json(self):
+        result = _parse_json('{"key": "value"}')
+        assert result == {"key": "value"}
+
+    def test_invalid_json(self):
+        result = _parse_json("not json")
+        assert result is None
+
+    def test_empty_string(self):
+        result = _parse_json("")
+        assert result is None
+
+    def test_whitespace_only(self):
+        result = _parse_json("   ")
+        assert result is None
+
+    def test_non_dict_json(self):
+        result = _parse_json("[1, 2, 3]")
+        assert result is None
+
+
+class TestScoreCategory:
+    """Test _score_category helper."""
+
+    def test_perfect_ssl_score(self):
+        grade_input = {
+            "tls_version_ok": True,
+            "cert_valid": True,
+            "cert_expiring_soon": False,  # inverted - False is good
+            "strong_cipher": True,
+            "self_signed": False,  # inverted - False is good
+        }
+        score, findings = _score_category(grade_input, SSL_CHECKS)
+        assert score == 100
+        assert len(findings) == 0
+
+    def test_failing_ssl_score(self):
+        grade_input = {
+            "tls_version_ok": False,
+            "cert_valid": False,
+            "cert_expiring_soon": True,  # inverted - True is bad
+            "strong_cipher": False,
+            "self_signed": True,  # inverted - True is bad
+        }
+        score, findings = _score_category(grade_input, SSL_CHECKS)
+        assert score == 0
+        assert len(findings) == 5
+
+    def test_missing_values_half_credit(self):
+        grade_input = {}  # All values missing
+        score, findings = _score_category(grade_input, SSL_CHECKS)
+        # Should get half credit for missing values
+        assert 45 <= score <= 55
+
+
+# ---------------------------------------------------------------------------
+# Full Scoring Flow
+# ---------------------------------------------------------------------------
+
+
+class TestFullScoring:
+    """Test full risk scoring."""
+
+    def test_empty_inputs_returns_zero(self, score_fn):
+        result = score_fn()
+        assert result["overall_score"] == 0
+        assert result["overall_grade"] == "F"
+
+    def test_all_categories_skipped(self, score_fn):
+        result = score_fn()
+        for cat in result["categories"].values():
+            assert cat["skipped"] is True
+
+    def test_ssl_results_only(self, score_fn):
+        ssl_data = {
+            "grade_input": {
+                "tls_version_ok": True,
+                "cert_valid": True,
+                "cert_expiring_soon": False,
+                "strong_cipher": True,
+                "self_signed": False,
+            }
+        }
+        result = score_fn(ssl_results=json.dumps(ssl_data))
+        assert result["categories"]["ssl_tls"]["score"] == 100
+        assert result["categories"]["ssl_tls"]["grade"] == "A"
+        assert result["categories"]["ssl_tls"]["skipped"] is False
+
+    def test_headers_results_only(self, score_fn):
+        headers_data = {
+            "grade_input": {
+                "hsts": True,
+                "csp": True,
+                "x_frame_options": True,
+                "x_content_type_options": True,
+                "referrer_policy": True,
+                "permissions_policy": True,
+                "no_leaky_headers": True,
+            }
+        }
+        result = score_fn(headers_results=json.dumps(headers_data))
+        assert result["categories"]["http_headers"]["score"] == 100
+        assert result["categories"]["http_headers"]["grade"] == "A"
+
+    def test_combined_results(self, score_fn):
+        ssl_data = {
+            "grade_input": {
+                "tls_version_ok": True,
+                "cert_valid": True,
+                "cert_expiring_soon": False,
+                "strong_cipher": True,
+                "self_signed": False,
+            }
+        }
+        headers_data = {
+            "grade_input": {
+                "hsts": True,
+                "csp": True,
+                "x_frame_options": True,
+                "x_content_type_options": True,
+                "referrer_policy": True,
+                "permissions_policy": True,
+                "no_leaky_headers": True,
+            }
+        }
+        result = score_fn(
+            ssl_results=json.dumps(ssl_data),
+            headers_results=json.dumps(headers_data),
+        )
+        # Both categories have perfect scores
+        assert result["categories"]["ssl_tls"]["score"] == 100
+        assert result["categories"]["http_headers"]["score"] == 100
+        # Overall should be 100 (weighted average of two 100s)
+        assert result["overall_score"] == 100
+        assert result["overall_grade"] == "A"
+
+
+# ---------------------------------------------------------------------------
+# Top Risks
+# ---------------------------------------------------------------------------
+
+
+class TestTopRisks:
+    """Test top_risks list generation."""
+
+    def test_top_risks_generated(self, score_fn):
+        ssl_data = {
+            "grade_input": {
+                "tls_version_ok": False,  # Failing
+                "cert_valid": True,
+                "cert_expiring_soon": False,
+                "strong_cipher": False,  # Failing
+                "self_signed": False,
+            }
+        }
+        result = score_fn(ssl_results=json.dumps(ssl_data))
+        assert len(result["top_risks"]) > 0
+        # Should mention TLS version and cipher issues
+        risks_text = " ".join(result["top_risks"])
+        assert "TLS" in risks_text or "cipher" in risks_text.lower()
+
+    def test_top_risks_limited_to_10(self, score_fn):
+        # Create data with many failures
+        ssl_data = {
+            "grade_input": {
+                "tls_version_ok": False,
+                "cert_valid": False,
+                "cert_expiring_soon": True,
+                "strong_cipher": False,
+                "self_signed": True,
+            }
+        }
+        headers_data = {
+            "grade_input": {
+                "hsts": False,
+                "csp": False,
+                "x_frame_options": False,
+                "x_content_type_options": False,
+                "referrer_policy": False,
+                "permissions_policy": False,
+                "no_leaky_headers": False,
+            }
+        }
+        dns_data = {
+            "grade_input": {
+                "spf_present": False,
+                "spf_strict": False,
+                "dmarc_present": False,
+                "dmarc_enforcing": False,
+                "dkim_found": False,
+                "dnssec_enabled": False,
+                "zone_transfer_blocked": False,
+            }
+        }
+        result = score_fn(
+            ssl_results=json.dumps(ssl_data),
+            headers_results=json.dumps(headers_data),
+            dns_results=json.dumps(dns_data),
+        )
+        # Should be capped at 10
+        assert len(result["top_risks"]) <= 10
+
+
+# ---------------------------------------------------------------------------
+# Grade Scale
+# ---------------------------------------------------------------------------
+
+
+class TestGradeScale:
+    """Test grade_scale is included in output."""
+
+    def test_grade_scale_present(self, score_fn):
+        result = score_fn()
+        assert "grade_scale" in result
+        assert "A" in result["grade_scale"]
+        assert "B" in result["grade_scale"]
+        assert "C" in result["grade_scale"]
+        assert "D" in result["grade_scale"]
+        assert "F" in result["grade_scale"]
+
+
+# ---------------------------------------------------------------------------
+# Category Weights
+# ---------------------------------------------------------------------------
+
+
+class TestCategoryWeights:
+    """Test category weights are applied correctly."""
+
+    def test_weights_included_in_output(self, score_fn):
+        ssl_data = {"grade_input": {"tls_version_ok": True}}
+        result = score_fn(ssl_results=json.dumps(ssl_data))
+        assert result["categories"]["ssl_tls"]["weight"] == 0.20
+
+
+# ---------------------------------------------------------------------------
+# Edge Cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    """Test edge cases and error handling."""
+
+    def test_invalid_json_ignored(self, score_fn):
+        result = score_fn(ssl_results="not valid json")
+        assert result["categories"]["ssl_tls"]["skipped"] is True
+
+    def test_missing_grade_input_key(self, score_fn):
+        # JSON without grade_input - should use the dict itself
+        data = {"tls_version_ok": True}
+        result = score_fn(ssl_results=json.dumps(data))
+        # Should not error
+        assert "overall_score" in result

tools/tests/tools/test_ssl_tls_scanner.py

@@ -0,0 +1,277 @@
+"""Tests for SSL/TLS Scanner tool."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.ssl_tls_scanner import register_tools
+
+
+@pytest.fixture
+def ssl_tools(mcp: FastMCP):
+    """Register SSL/TLS tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def scan_fn(ssl_tools):
+    return ssl_tools["ssl_tls_scan"]
+
+
+def _mock_cert_dict(
+    days_until_expiry: int = 365,
+    subject: str = "example.com",
+    issuer: str = "Let's Encrypt",
+    san: list[str] | None = None,
+):
+    """Create a mock certificate dict."""
+    now = datetime.now(UTC)
+    not_before = now - timedelta(days=30)
+    not_after = now + timedelta(days=days_until_expiry)
+
+    return {
+        "subject": ((("commonName", subject),),),
+        "issuer": ((("commonName", issuer),),),
+        "notBefore": not_before.strftime("%b %d %H:%M:%S %Y GMT"),
+        "notAfter": not_after.strftime("%b %d %H:%M:%S %Y GMT"),
+        "subjectAltName": tuple(("DNS", s) for s in (san or [subject])),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Input Validation
+# ---------------------------------------------------------------------------
+
+
+class TestInputValidation:
+    """Test hostname input cleaning."""
+
+    def test_strips_https_prefix(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_ctx.return_value.wrap_socket.side_effect = TimeoutError()
+            result = scan_fn("https://example.com")
+            assert "example.com" in result["error"]
+            assert "https://" not in result["error"]
+
+    def test_strips_http_prefix(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_ctx.return_value.wrap_socket.side_effect = TimeoutError()
+            result = scan_fn("http://example.com")
+            assert "example.com" in result["error"]
+            assert "http://" not in result["error"]
+
+    def test_strips_path(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_ctx.return_value.wrap_socket.side_effect = TimeoutError()
+            result = scan_fn("example.com/path/to/page")
+            assert "example.com" in result["error"]
+            assert "/path" not in result["error"]
+
+    def test_strips_port_from_hostname(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_ctx.return_value.wrap_socket.side_effect = TimeoutError()
+            result = scan_fn("example.com:8443")
+            assert "example.com:443" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# Connection Errors
+# ---------------------------------------------------------------------------
+
+
+class TestConnectionErrors:
+    """Test error handling for connection failures."""
+
+    def test_timeout_error(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.connect.side_effect = TimeoutError()
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert "error" in result
+            assert "timed out" in result["error"]
+
+    def test_connection_refused(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.connect.side_effect = ConnectionRefusedError()
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert "error" in result
+            assert "refused" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# TLS Version Detection
+# ---------------------------------------------------------------------------
+
+
+class TestTlsVersion:
+    """Test TLS version detection and validation."""
+
+    def test_tls13_ok(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.3"
+            mock_conn.cipher.return_value = ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256)
+            mock_conn.getpeercert.return_value = _mock_cert_dict()
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["tls_version"] == "TLSv1.3"
+            assert result["grade_input"]["tls_version_ok"] is True
+
+    def test_tls10_insecure(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1"
+            mock_conn.cipher.return_value = ("AES256-SHA", "TLSv1", 256)
+            mock_conn.getpeercert.return_value = _mock_cert_dict()
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["grade_input"]["tls_version_ok"] is False
+            issues = [i["finding"] for i in result.get("issues", [])]
+            assert any("TLS version" in i for i in issues)
+
+
+# ---------------------------------------------------------------------------
+# Cipher Suite Detection
+# ---------------------------------------------------------------------------
+
+
+class TestCipherSuite:
+    """Test cipher suite detection and validation."""
+
+    def test_strong_cipher(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.3"
+            mock_conn.cipher.return_value = ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256)
+            mock_conn.getpeercert.return_value = _mock_cert_dict()
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["grade_input"]["strong_cipher"] is True
+
+    def test_weak_cipher_rc4(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.2"
+            mock_conn.cipher.return_value = ("RC4-SHA", "TLSv1.2", 128)
+            mock_conn.getpeercert.return_value = _mock_cert_dict()
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["grade_input"]["strong_cipher"] is False
+
+
+# ---------------------------------------------------------------------------
+# Certificate Validation
+# ---------------------------------------------------------------------------
+
+
+class TestCertificateValidation:
+    """Test certificate validation checks."""
+
+    def test_valid_certificate(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.3"
+            mock_conn.cipher.return_value = ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256)
+            mock_conn.getpeercert.return_value = _mock_cert_dict(days_until_expiry=365)
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(days_until_expiry=365),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["grade_input"]["cert_valid"] is True
+
+    def test_expiring_soon(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.3"
+            mock_conn.cipher.return_value = ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256)
+            mock_conn.getpeercert.return_value = _mock_cert_dict(days_until_expiry=15)
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(days_until_expiry=15),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["grade_input"]["cert_expiring_soon"] is True
+
+    def test_self_signed_detected(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.3"
+            mock_conn.cipher.return_value = ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256)
+            # Self-signed: subject == issuer
+            mock_conn.getpeercert.return_value = _mock_cert_dict(
+                subject="example.com", issuer="example.com"
+            )
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(subject="example.com", issuer="example.com"),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert result["grade_input"]["self_signed"] is True
+
+
+# ---------------------------------------------------------------------------
+# Grade Input
+# ---------------------------------------------------------------------------
+
+
+class TestGradeInput:
+    """Test grade_input dict is properly constructed."""
+
+    def test_grade_input_keys_present(self, scan_fn):
+        with patch("ssl.create_default_context") as mock_ctx:
+            mock_conn = MagicMock()
+            mock_conn.version.return_value = "TLSv1.3"
+            mock_conn.cipher.return_value = ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256)
+            mock_conn.getpeercert.return_value = _mock_cert_dict()
+            mock_conn.getpeercert.side_effect = [
+                b"fake_der_cert",
+                _mock_cert_dict(),
+            ]
+            mock_ctx.return_value.wrap_socket.return_value = mock_conn
+
+            result = scan_fn("example.com")
+            assert "grade_input" in result
+            grade = result["grade_input"]
+            assert "tls_version_ok" in grade
+            assert "cert_valid" in grade
+            assert "cert_expiring_soon" in grade
+            assert "strong_cipher" in grade
+            assert "self_signed" in grade

tools/tests/tools/test_subdomain_enumerator.py

@@ -0,0 +1,294 @@
+"""Tests for Subdomain Enumerator tool."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.subdomain_enumerator import register_tools
+
+
+@pytest.fixture
+def subdomain_tools(mcp: FastMCP):
+    """Register subdomain enumeration tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def enumerate_fn(subdomain_tools):
+    return subdomain_tools["subdomain_enumerate"]
+
+
+def _mock_crtsh_response(subdomains: list[str], status_code: int = 200) -> MagicMock:
+    """Create a mock crt.sh response."""
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.json.return_value = [{"name_value": sub} for sub in subdomains]
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Input Validation
+# ---------------------------------------------------------------------------
+
+
+class TestInputValidation:
+    """Test domain input cleaning."""
+
+    @pytest.mark.asyncio
+    async def test_strips_https_prefix(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response([])
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("https://example.com")
+            assert result["domain"] == "example.com"
+
+    @pytest.mark.asyncio
+    async def test_strips_http_prefix(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response([])
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("http://example.com")
+            assert result["domain"] == "example.com"
+
+    @pytest.mark.asyncio
+    async def test_strips_path(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response([])
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com/path")
+            assert result["domain"] == "example.com"
+
+    @pytest.mark.asyncio
+    async def test_max_results_clamped(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response([])
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            # max_results should be clamped to 200
+            result = await enumerate_fn("example.com", max_results=500)
+            # Result should not error
+            assert "error" not in result
+
+
+# ---------------------------------------------------------------------------
+# Connection Errors
+# ---------------------------------------------------------------------------
+
+
+class TestConnectionErrors:
+    """Test error handling for crt.sh failures."""
+
+    @pytest.mark.asyncio
+    async def test_timeout_error(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.side_effect = httpx.TimeoutException("timeout")
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert "error" in result
+            assert "timed out" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_http_error(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response([], status_code=500)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert "error" in result
+            assert "500" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# Subdomain Discovery
+# ---------------------------------------------------------------------------
+
+
+class TestSubdomainDiscovery:
+    """Test subdomain extraction from CT logs."""
+
+    @pytest.mark.asyncio
+    async def test_subdomains_extracted(self, enumerate_fn):
+        subdomains = [
+            "www.example.com",
+            "api.example.com",
+            "mail.example.com",
+        ]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert result["total_found"] == 3
+            assert "www.example.com" in result["subdomains"]
+            assert "api.example.com" in result["subdomains"]
+
+    @pytest.mark.asyncio
+    async def test_wildcards_filtered(self, enumerate_fn):
+        subdomains = [
+            "*.example.com",
+            "www.example.com",
+            "*.api.example.com",
+        ]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            # Wildcards should be filtered out
+            assert "*.example.com" not in result["subdomains"]
+            assert "www.example.com" in result["subdomains"]
+
+    @pytest.mark.asyncio
+    async def test_duplicates_removed(self, enumerate_fn):
+        subdomains = [
+            "www.example.com",
+            "www.example.com",
+            "www.example.com",
+        ]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert result["total_found"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Interesting Subdomain Detection
+# ---------------------------------------------------------------------------
+
+
+class TestInterestingSubdomains:
+    """Test detection of security-relevant subdomains."""
+
+    @pytest.mark.asyncio
+    async def test_staging_flagged(self, enumerate_fn):
+        subdomains = ["staging.example.com", "www.example.com"]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert len(result["interesting"]) > 0
+            interesting_subs = [i["subdomain"] for i in result["interesting"]]
+            assert "staging.example.com" in interesting_subs
+
+    @pytest.mark.asyncio
+    async def test_admin_flagged(self, enumerate_fn):
+        subdomains = ["admin.example.com", "www.example.com"]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            interesting_subs = [i["subdomain"] for i in result["interesting"]]
+            assert "admin.example.com" in interesting_subs
+
+    @pytest.mark.asyncio
+    async def test_dev_flagged(self, enumerate_fn):
+        subdomains = ["dev.example.com", "www.example.com"]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            interesting_subs = [i["subdomain"] for i in result["interesting"]]
+            assert "dev.example.com" in interesting_subs
+
+
+# ---------------------------------------------------------------------------
+# Grade Input
+# ---------------------------------------------------------------------------
+
+
+class TestGradeInput:
+    """Test grade_input dict is properly constructed."""
+
+    @pytest.mark.asyncio
+    async def test_grade_input_keys_present(self, enumerate_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response([])
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert "grade_input" in result
+            grade = result["grade_input"]
+            assert "no_dev_staging_exposed" in grade
+            assert "no_admin_exposed" in grade
+            assert "reasonable_surface_area" in grade
+
+    @pytest.mark.asyncio
+    async def test_no_dev_staging_true_when_clean(self, enumerate_fn):
+        subdomains = ["www.example.com", "api.example.com"]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert result["grade_input"]["no_dev_staging_exposed"] is True
+
+    @pytest.mark.asyncio
+    async def test_reasonable_surface_area(self, enumerate_fn):
+        # Less than 50 subdomains = reasonable
+        subdomains = [f"sub{i}.example.com" for i in range(30)]
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = _mock_crtsh_response(subdomains)
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await enumerate_fn("example.com")
+            assert result["grade_input"]["reasonable_surface_area"] is True

tools/tests/tools/test_tech_stack_detector.py

@@ -0,0 +1,269 @@
+"""Tests for Tech Stack Detector tool."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+from fastmcp import FastMCP
+
+from aden_tools.tools.tech_stack_detector import register_tools
+from aden_tools.tools.tech_stack_detector.tech_stack_detector import (
+    _detect_cdn,
+    _detect_cms_from_html,
+    _detect_js_libraries,
+    _detect_server,
+)
+
+
+@pytest.fixture
+def tech_tools(mcp: FastMCP):
+    """Register tech stack tools and return tool functions."""
+    register_tools(mcp)
+    tools = mcp._tool_manager._tools
+    return {name: tools[name].fn for name in tools}
+
+
+@pytest.fixture
+def detect_fn(tech_tools):
+    return tech_tools["tech_stack_detect"]
+
+
+class FakeHeaders:
+    """Minimal stand-in for httpx.Headers."""
+
+    def __init__(self, headers: dict):
+        self._headers = {k.lower(): v for k, v in headers.items()}
+
+    def get(self, name: str, default=None):
+        return self._headers.get(name.lower(), default)
+
+    def get_list(self, name: str) -> list[str]:
+        val = self._headers.get(name.lower())
+        if val is None:
+            return []
+        if isinstance(val, list):
+            return val
+        return [val]
+
+
+# ---------------------------------------------------------------------------
+# Helper Function Tests
+# ---------------------------------------------------------------------------
+
+
+class TestDetectServer:
+    """Test _detect_server helper."""
+
+    def test_server_with_version(self):
+        headers = FakeHeaders({"server": "nginx/1.21.0"})
+        result = _detect_server(headers)
+        assert result["name"] == "nginx"
+        assert result["version"] == "1.21.0"
+
+    def test_server_without_version(self):
+        headers = FakeHeaders({"server": "cloudflare"})
+        result = _detect_server(headers)
+        assert result["name"] == "cloudflare"
+        assert result["version"] is None
+
+    def test_no_server_header(self):
+        headers = FakeHeaders({})
+        result = _detect_server(headers)
+        assert result is None
+
+
+class TestDetectCdn:
+    """Test _detect_cdn helper."""
+
+    def test_cloudflare_detected(self):
+        headers = FakeHeaders({"cf-ray": "123abc"})
+        result = _detect_cdn(headers)
+        assert result == "Cloudflare"
+
+    def test_vercel_detected(self):
+        headers = FakeHeaders({"x-vercel-id": "abc123"})
+        result = _detect_cdn(headers)
+        assert result == "Vercel"
+
+    def test_no_cdn(self):
+        headers = FakeHeaders({"content-type": "text/html"})
+        result = _detect_cdn(headers)
+        assert result is None
+
+
+class TestDetectJsLibraries:
+    """Test _detect_js_libraries helper."""
+
+    def test_react_detected(self):
+        html = '<script src="/static/react.min.js"></script>'
+        result = _detect_js_libraries(html)
+        assert "React" in result
+
+    def test_jquery_detected(self):
+        html = '<script src="https://cdn.example.com/jquery-3.6.0.min.js"></script>'
+        result = _detect_js_libraries(html)
+        assert any("jQuery" in lib for lib in result)
+
+    def test_nextjs_detected(self):
+        html = '<script id="__NEXT_DATA__" type="application/json">{}</script>'
+        result = _detect_js_libraries(html)
+        assert "Next.js" in result
+
+    def test_no_libraries(self):
+        html = "<html><body>Simple page</body></html>"
+        result = _detect_js_libraries(html)
+        assert len(result) == 0
+
+
+class TestDetectCms:
+    """Test _detect_cms_from_html helper."""
+
+    def test_wordpress_detected(self):
+        html = '<link href="/wp-content/themes/theme/style.css">'
+        result = _detect_cms_from_html(html)
+        assert result == "WordPress"
+
+    def test_shopify_detected(self):
+        html = '<script src="https://cdn.shopify.com/s/files/1/theme.js"></script>'
+        result = _detect_cms_from_html(html)
+        assert result == "Shopify"
+
+    def test_drupal_detected(self):
+        html = '<script src="/core/misc/drupal.js"></script>'
+        result = _detect_cms_from_html(html)
+        assert result == "Drupal"
+
+    def test_no_cms(self):
+        html = "<html><body>Custom site</body></html>"
+        result = _detect_cms_from_html(html)
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Connection Errors
+# ---------------------------------------------------------------------------
+
+
+class TestConnectionErrors:
+    """Test error handling for connection failures."""
+
+    @pytest.mark.asyncio
+    async def test_connection_error(self, detect_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.side_effect = httpx.ConnectError("Connection refused")
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await detect_fn("https://example.com")
+            assert "error" in result
+            assert "Connection failed" in result["error"]
+
+    @pytest.mark.asyncio
+    async def test_timeout_error(self, detect_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.side_effect = httpx.TimeoutException("timeout")
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await detect_fn("https://example.com")
+            assert "error" in result
+            assert "timed out" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# Full Detection Flow
+# ---------------------------------------------------------------------------
+
+
+class TestFullDetection:
+    """Test full tech stack detection."""
+
+    def _mock_response(
+        self,
+        html: str = "<html></html>",
+        headers: dict | None = None,
+        cookies: dict | None = None,
+    ):
+        resp = MagicMock()
+        resp.text = html
+        resp.url = "https://example.com"
+        resp.headers = httpx.Headers(headers or {})
+        resp.cookies = httpx.Cookies(cookies or {})
+        return resp
+
+    @pytest.mark.asyncio
+    async def test_detects_server(self, detect_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = self._mock_response(headers={"server": "nginx/1.21.0"})
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await detect_fn("https://example.com")
+            assert result["server"]["name"] == "nginx"
+
+    @pytest.mark.asyncio
+    async def test_detects_framework(self, detect_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = self._mock_response(headers={"x-powered-by": "Express"})
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await detect_fn("https://example.com")
+            assert result["framework"] == "Express"
+
+
+# ---------------------------------------------------------------------------
+# Grade Input
+# ---------------------------------------------------------------------------
+
+
+class TestGradeInput:
+    """Test grade_input dict is properly constructed."""
+
+    def _mock_response(self, html: str = "<html></html>", headers: dict | None = None):
+        resp = MagicMock()
+        resp.text = html
+        resp.url = "https://example.com"
+        resp.headers = httpx.Headers(headers or {})
+        resp.cookies = httpx.Cookies()
+        return resp
+
+    @pytest.mark.asyncio
+    async def test_grade_input_keys_present(self, detect_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = self._mock_response()
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await detect_fn("https://example.com")
+            assert "grade_input" in result
+            grade = result["grade_input"]
+            assert "server_version_hidden" in grade
+            assert "framework_version_hidden" in grade
+            assert "security_txt_present" in grade
+            assert "cookies_secure" in grade
+            assert "cookies_httponly" in grade
+
+    @pytest.mark.asyncio
+    async def test_server_version_exposed(self, detect_fn):
+        with patch("httpx.AsyncClient") as MockClient:
+            mock_client = AsyncMock()
+            mock_client.get.return_value = self._mock_response(headers={"server": "Apache/2.4.41"})
+            mock_client.__aenter__.return_value = mock_client
+            mock_client.__aexit__.return_value = None
+            MockClient.return_value = mock_client
+
+            result = await detect_fn("https://example.com")
+            assert result["grade_input"]["server_version_hidden"] is False