delimit-cli 3.15.1 → 3.15.2

package/gateway/ai/playbook.py

@@ -0,0 +1,187 @@
+"""Prompt Playbook — versioned, reusable prompt templates (STR-048).
+
+Save prompts as named commands that work across any AI assistant.
+Share them with your team. Version them per model.
+
+Storage: ~/.delimit/playbooks/
+Format: YAML files with name, prompt, variables, model hints.
+
+Focus group origin: "Prompt management is a total disaster.
+Slack channels, Notion docs, personal text files."
+"""
+
+import json
+import time
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+PLAYBOOKS_DIR = Path.home() / ".delimit" / "playbooks"
+
+
+def _ensure_dir():
+    PLAYBOOKS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _playbook_path(name: str) -> Path:
+    safe = re.sub(r'[^a-zA-Z0-9_-]', '_', name.lower().strip())
+    return PLAYBOOKS_DIR / f"{safe}.json"
+
+
+def save_playbook(
+    name: str,
+    prompt: str,
+    description: str = "",
+    variables: Optional[List[str]] = None,
+    model_hint: str = "",
+    tags: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Save a named prompt template.
+
+    Variables use {{var_name}} syntax in the prompt text.
+    Example: "Generate tests for {{file_path}} using {{framework}}"
+    """
+    if not name or not name.strip():
+        return {"error": "name is required"}
+    if not prompt or not prompt.strip():
+        return {"error": "prompt is required"}
+
+    name = name.strip()
+    _ensure_dir()
+
+    # Auto-detect variables from {{var}} patterns
+    detected_vars = re.findall(r'\{\{(\w+)\}\}', prompt)
+    all_vars = list(set((variables or []) + detected_vars))
+
+    playbook = {
+        "name": name,
+        "prompt": prompt,
+        "description": description or f"Playbook: {name}",
+        "variables": all_vars,
+        "model_hint": model_hint,
+        "tags": tags or [],
+        "version": 1,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+
+    pb_path = _playbook_path(name)
+
+    # If exists, increment version
+    if pb_path.exists():
+        try:
+            existing = json.loads(pb_path.read_text())
+            playbook["version"] = existing.get("version", 0) + 1
+            playbook["created_at"] = existing.get("created_at", playbook["created_at"])
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    pb_path.write_text(json.dumps(playbook, indent=2))
+
+    return {
+        "status": "saved",
+        "name": name,
+        "version": playbook["version"],
+        "variables": all_vars,
+        "path": str(pb_path),
+        "message": f"Playbook '{name}' saved (v{playbook['version']})",
+    }
+
+
+def run_playbook(
+    name: str,
+    variables: Optional[Dict[str, str]] = None,
+) -> Dict[str, Any]:
+    """Load and render a named playbook with variables filled in.
+
+    Returns the rendered prompt ready to send to an AI model.
+    """
+    if not name or not name.strip():
+        return {"error": "name is required"}
+
+    pb_path = _playbook_path(name.strip())
+    if not pb_path.exists():
+        # Try fuzzy match
+        matches = list(PLAYBOOKS_DIR.glob("*.json"))
+        suggestions = []
+        for m in matches:
+            try:
+                pb = json.loads(m.read_text())
+                suggestions.append(pb["name"])
+            except:
+                pass
+        return {
+            "error": f"Playbook '{name}' not found",
+            "available": suggestions[:10],
+        }
+
+    try:
+        playbook = json.loads(pb_path.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        return {"error": f"Failed to read playbook: {e}"}
+
+    prompt = playbook["prompt"]
+    vars_used = variables or {}
+
+    # Fill in variables
+    missing = []
+    for var in playbook.get("variables", []):
+        if var in vars_used:
+            prompt = prompt.replace(f"{{{{{var}}}}}", vars_used[var])
+        else:
+            missing.append(var)
+
+    return {
+        "status": "ready",
+        "name": playbook["name"],
+        "version": playbook["version"],
+        "rendered_prompt": prompt,
+        "model_hint": playbook.get("model_hint", ""),
+        "missing_variables": missing,
+        "message": f"Playbook '{name}' ready" + (f" (missing: {', '.join(missing)})" if missing else ""),
+    }
+
+
+def list_playbooks(tag: str = "") -> Dict[str, Any]:
+    """List all saved playbooks, optionally filtered by tag."""
+    _ensure_dir()
+    playbooks = []
+
+    for pb_file in sorted(PLAYBOOKS_DIR.glob("*.json")):
+        try:
+            pb = json.loads(pb_file.read_text())
+            if tag and tag not in pb.get("tags", []):
+                continue
+            playbooks.append({
+                "name": pb["name"],
+                "description": pb.get("description", ""),
+                "version": pb.get("version", 1),
+                "variables": pb.get("variables", []),
+                "model_hint": pb.get("model_hint", ""),
+                "tags": pb.get("tags", []),
+            })
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return {
+        "status": "ok",
+        "playbooks": playbooks,
+        "total": len(playbooks),
+    }
+
+
+def delete_playbook(name: str) -> Dict[str, Any]:
+    """Delete a named playbook."""
+    if not name:
+        return {"error": "name is required"}
+
+    pb_path = _playbook_path(name.strip())
+    if not pb_path.exists():
+        return {"error": f"Playbook '{name}' not found"}
+
+    pb_path.unlink()
+    return {
+        "status": "deleted",
+        "name": name,
+        "message": f"Playbook '{name}' deleted",
+    }

package/gateway/ai/server.py

@@ -19,6 +19,30 @@ All tools follow the Adapter Boundary Contract v1.0:
 - Stateless between calls
 """
 
+# ── Founder Voice Doctrine ──────────────────────────────────────────────
+# Applies to ALL outward-facing text generated by any tool in this server.
+# Full doctrine: /home/delimit/delimit-private/style/FOUNDER_VOICE_DOCTRINE.md
+#
+# Core: serious builder/operator, not a marketer. Credibility over persuasion.
+# Truth over excitement. Concrete mechanisms, not vague benefits.
+# No hype words (revolutionary, seamless, unlock, supercharge, game-changing).
+# Sound earned. Respect the reader. Acknowledge tradeoffs.
+# "Measured conviction" not "sales energy."
+# "Serious founder/architect/controller" not "visionary hype founder."
+#
+# Quality bar: Does this sound like a real operator with consequences
+# attached to decisions? Would this still read well a year from now?
+# ────────────────────────────────────────────────────────────────────────
+
+FOUNDER_VOICE_HYPE_WORDS = {
+    "revolutionary", "game-changing", "world-class", "cutting-edge",
+    "best-in-class", "seamless", "unlock", "supercharge", "next-generation",
+    "magical", "delightful", "effortless", "frictionless", "transformative",
+    "paradigm shift", "visionary", "category-defining", "industry-leading",
+    "innovative", "reimagine", "future of", "changing the game",
+    "empowering teams", "built for everyone",
+}
+
 import json
 import logging
 import os
@@ -899,7 +923,10 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     "version": [],
     "help": [],
     "diagnose": [],
-    "activate": [],
+    "activate": [
+        {"tool": "delimit_init", "reason": "Initialize governance if not set up", "suggested_args": {"preset": "default"}, "is_premium": False},
+        {"tool": "delimit_diagnose", "reason": "Deep-dive into any failing checks", "suggested_args": {}, "is_premium": False},
+    ],
     "license_status": [],
 }
 
@@ -1131,6 +1158,7 @@ def _detect_environment() -> Dict[str, Any]:
 
 
 _inbox_daemon_autostarted = False
+_toolcard_cache_autoregistered = False
 
 
 def _with_next_steps(tool_name: str, result: Dict[str, Any]) -> Dict[str, Any]:
@@ -1138,6 +1166,7 @@ def _with_next_steps(tool_name: str, result: Dict[str, Any]) -> Dict[str, Any]:
 
     The governance loop:
     1. Auto-start inbox daemon on first tool call (model-agnostic)
+    1b. Auto-register tool schemas with toolcard cache (LED-219)
     2. Emit event for dashboard tracking
     3. STR-052: Policy kernel gate (blocks high-risk actions without approval)
     4. Check Pro license gate (blocks if not authorized)
@@ -1156,6 +1185,44 @@ def _with_next_steps(tool_name: str, result: Dict[str, Any]) -> Dict[str, Any]:
         except Exception as e:
             logger.warning("Inbox daemon auto-start failed: %s", e)
 
+    # LED-219: Auto-register tool schemas with toolcard cache on first call
+    global _toolcard_cache_autoregistered
+    if not _toolcard_cache_autoregistered:
+        _toolcard_cache_autoregistered = True
+        try:
+            from ai.toolcard_cache import get_cache
+            _tc = get_cache()
+            # Build schema list from mcp's registered tools
+            _tool_schemas = []
+            for _tname, _tfn in getattr(mcp, '_tool_manager', {}).items() if hasattr(mcp, '_tool_manager') else []:
+                _tool_schemas.append({"name": _tname})
+            if not _tool_schemas:
+                # Fallback: just record the current tool call
+                _tc.record_call(tool_name)
+            logger.info("Toolcard cache auto-registered on first tool call")
+        except Exception as e:
+            logger.warning("Toolcard cache auto-register failed: %s", e)
+
+    # LED-219: Track every tool call for session analytics
+    try:
+        from ai.toolcard_cache import get_cache as _get_tc
+        _get_tc().record_call(tool_name)
+    except Exception:
+        pass
+
+    # Voice doctrine check — flag hype words in outgoing text
+    if isinstance(result, dict):
+        _text_fields = [result.get("text", ""), result.get("message", ""),
+                        result.get("explanation", ""), result.get("changelog", ""),
+                        result.get("content", "")]
+        _all_text = " ".join(str(f) for f in _text_fields if f).lower()
+        _found_hype = [w for w in FOUNDER_VOICE_HYPE_WORDS if w in _all_text]
+        if _found_hype:
+            result.setdefault("voice_warnings", []).append(
+                f"VOICE DOCTRINE: Hype words detected: {', '.join(_found_hype)}. "
+                f"Rewrite with concrete mechanisms, not vague benefits."
+            )
+
     # Emit event for real-time dashboard
     _emit_event(tool_name, result)
 
@@ -3532,33 +3599,92 @@ TOOL_HELP = {
 
 STANDARD_WORKFLOWS = [
     {
-        "name": "Project Onboarding",
-        "description": "Set up governance for a new project",
-        "steps": ["delimit_init", "delimit_gov_health", "delimit_lint", "delimit_test_coverage", "delimit_security_scan"],
+        "name": "Resume Work",
+        "pain": "You switched models or sessions and lost all context",
+        "fix": "Pick up exactly where you left off",
+        "steps": ["delimit_session_history", "delimit_ledger_context", "delimit_memory_search"],
     },
     {
-        "name": "Pre-Commit Check",
-        "description": "Validate changes before committing",
-        "steps": ["delimit_lint", "delimit_test_coverage", "delimit_semver"],
+        "name": "Catch Breaking Changes",
+        "pain": "Your AI agent deployed a breaking API change and nobody caught it",
+        "fix": "Detect and block breaking changes before merge",
+        "steps": ["delimit_lint", "delimit_diff", "delimit_semver"],
     },
     {
-        "name": "Security Audit",
-        "description": "Full security scan with evidence collection",
-        "steps": ["delimit_security_scan", "delimit_evidence_collect", "delimit_evidence_verify"],
+        "name": "Remember Across Models",
+        "pain": "Every new session starts from zero — your agent forgot everything",
+        "fix": "Store and recall context across any AI assistant",
+        "steps": ["delimit_memory_store", "delimit_memory_search", "delimit_session_handoff"],
     },
     {
-        "name": "API Change Review",
-        "description": "Review and document an API change",
-        "steps": ["delimit_diff", "delimit_semver", "delimit_explain", "delimit_lint"],
+        "name": "Track What Needs Doing",
+        "pain": "Tasks get lost when context windows fill up",
+        "fix": "Persistent ledger that survives session resets",
+        "steps": ["delimit_ledger_add", "delimit_ledger_context", "delimit_ledger_done"],
     },
     {
-        "name": "Deploy Pipeline",
-        "description": "Build, publish, and verify a deployment",
-        "steps": ["delimit_deploy_build", "delimit_deploy_publish", "delimit_deploy_verify"],
+        "name": "Watch for Drift",
+        "pain": "Your API spec changed without governance review",
+        "fix": "Continuous monitoring with alerts on drift",
+        "steps": ["delimit_drift_check", "delimit_scan", "delimit_gov_health"],
     },
 ]
 
 
+@mcp.tool()
+def delimit_playbook(action: str = "list", name: str = "", prompt: str = "",
+                      description: str = "", variables: str = "",
+                      model_hint: str = "", tags: str = "") -> Dict[str, Any]:
+    """Manage reusable prompt templates — save, run, list, delete.
+
+    Save your best prompts as named commands. Use {{variables}} for dynamic parts.
+    Works across all AI assistants through the shared MCP workspace.
+
+    Examples:
+      Save: delimit_playbook(action="save", name="test-gen", prompt="Generate Jest tests for {{file}}")
+      Run:  delimit_playbook(action="run", name="test-gen", variables="file=src/auth.ts")
+      List: delimit_playbook(action="list")
+
+    Args:
+        action: "save", "run", "list", or "delete".
+        name: Playbook name (required for save/run/delete).
+        prompt: Prompt template with {{variable}} placeholders (save only).
+        description: Short description of what this playbook does.
+        variables: For run: comma-separated key=value pairs. For save: comma-separated variable names.
+        model_hint: Suggested model (e.g. "claude-opus" for complex tasks).
+        tags: Comma-separated tags for organization.
+    """
+    from ai.playbook import save_playbook, run_playbook, list_playbooks, delete_playbook
+
+    action = action.lower().strip()
+
+    if action == "save":
+        tag_list = [t.strip() for t in tags.split(",") if t.strip()] if tags else None
+        var_list = [v.strip() for v in variables.split(",") if v.strip()] if variables else None
+        return _with_next_steps("playbook", _safe_call(
+            save_playbook, name=name, prompt=prompt, description=description,
+            variables=var_list, model_hint=model_hint, tags=tag_list,
+        ))
+
+    if action == "run":
+        var_dict = {}
+        if variables:
+            for pair in variables.split(","):
+                if "=" in pair:
+                    k, v = pair.split("=", 1)
+                    var_dict[k.strip()] = v.strip()
+        return _with_next_steps("playbook", _safe_call(
+            run_playbook, name=name, variables=var_dict,
+        ))
+
+    if action == "delete":
+        return _with_next_steps("playbook", _safe_call(delete_playbook, name=name))
+
+    # Default: list
+    tag_filter = tags.strip() if tags else ""
+    return _with_next_steps("playbook", _safe_call(list_playbooks, tag=tag_filter))
+
+
 @mcp.tool()
 def delimit_help(tool_name: str = "") -> Dict[str, Any]:
     """Get help for a Delimit tool — what it does, parameters, and examples.
@@ -3569,12 +3695,13 @@ def delimit_help(tool_name: str = "") -> Dict[str, Any]:
     if not tool_name:
         total = _count_registered_tools()
         return _with_next_steps("help", {
-            "message": f"Delimit has {total} tools. Here are the most useful ones to start with:",
+            "message": "What problem are you solving?",
+            "workflows": [
+                {"name": w["name"], "pain": w["pain"], "start_with": w["steps"][0]}
+                for w in STANDARD_WORKFLOWS
+            ],
+            "tip": "Tell me what you're trying to do — I'll suggest the right workflow.",
             "total_tools": total,
-            "essential_tools": {k: v["desc"] for k, v in TOOL_HELP.items()},
-            "workflows": STANDARD_WORKFLOWS,
-            "tip": "Run delimit_help(tool_name='lint') for detailed help on a specific tool.",
-            "all_tools": "Run delimit_version() for the complete list.",
         })
 
     # Normalize name
@@ -3721,14 +3848,22 @@ def delimit_diagnose(project_path: str = ".") -> Dict[str, Any]:
 
 
 @mcp.tool()
-def delimit_activate(license_key: str) -> Dict[str, Any]:
-    """Activate a Delimit Pro license key.
+def delimit_activate(license_key: str = "", project_path: str = ".", auto_permissions: bool = True) -> Dict[str, Any]:
+    """Activate Delimit and run a readiness checklist.
+
+    Performs a comprehensive activation check: license validation, MCP server
+    status, governance init, test smoke, permission auto-config, and premium
+    feature availability.  Skipped checks (premium on free tier, no test
+    framework) do NOT count against the score.
 
     Args:
-        license_key: The license key to activate (e.g. DELIMIT-XXXX-XXXX-XXXX).
+        license_key: Optional license key to activate Pro (e.g. DELIMIT-XXXX-XXXX-XXXX). Leave empty to check free-tier readiness.
+        project_path: Project directory to check.
+        auto_permissions: Auto-configure AI assistant permissions for Delimit tools (default True).
     """
-    from ai.license import activate_license
-    return _with_next_steps("activate", activate_license(license_key))
+    from ai.activate_helpers import build_checklist
+    result = build_checklist(license_key=license_key, project_path=project_path, auto_permissions=auto_permissions)
+    return _with_next_steps("activate", result)
 
 
 @mcp.tool()
@@ -4089,6 +4224,85 @@ def delimit_ventures() -> Dict[str, Any]:
     return list_ventures()
 
 
+# ═══════════════════════════════════════════════════════════════════════
+#  SESSION PHOENIX — Cross-Model Resurrection (LED-218)
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+def delimit_soul_capture(
+    active_task: str = "",
+    decisions: str = "",
+    key_context: str = "",
+    blockers: str = "",
+    next_steps: str = "",
+    task_status: str = "in_progress",
+    tokens_used: int = 0,
+    context_fullness: float = 0.0,
+) -> Dict[str, Any]:
+    """Capture current session state as a 'soul' for cross-model resurrection (Pro).
+
+    Save what you're working on so the next session (in any model) picks up
+    where you left off. Auto-detects git state and files changed.
+
+    Args:
+        active_task: What you're currently working on (one line).
+        decisions: Comma-separated key decisions made this session.
+        key_context: Comma-separated important context for next session.
+        blockers: Comma-separated blockers.
+        next_steps: Comma-separated next steps.
+        task_status: in_progress, blocked, or almost_done.
+        tokens_used: Estimated tokens consumed this session.
+        context_fullness: 0.0-1.0 how full the context window is.
+    """
+    from ai.session_phoenix import capture_soul as _capture
+
+    def _split(val: str) -> List[str]:
+        if not val or not val.strip():
+            return []
+        return [s.strip() for s in val.split(",") if s.strip()]
+
+    soul = _capture(
+        active_task=active_task,
+        decisions=_split(decisions),
+        key_context=_split(key_context),
+        blockers=_split(blockers),
+        next_steps=_split(next_steps),
+        source_model=_detect_model(),
+        task_status=task_status,
+        tokens_used=tokens_used,
+        context_fullness=context_fullness,
+    )
+
+    from dataclasses import asdict
+    return _with_next_steps("soul_capture", {
+        "status": "captured",
+        "soul_id": soul.soul_id,
+        "project": soul.project_path,
+        "active_task": soul.active_task,
+        "files_modified": len(soul.files_modified),
+        "files_created": len(soul.files_created),
+        "uncommitted_changes": soul.uncommitted_changes,
+        "message": f"Soul {soul.soul_id} captured. Run delimit_revive in any model to restore.",
+    })
+
+
+@mcp.tool()
+def delimit_revive(project_path: str = "", soul_id: str = "") -> Dict[str, Any]:
+    """Revive the last session's state in any model (Pro).
+
+    Run this at the start of a new session to pick up where you left off.
+    Works across Claude Code, Codex, Gemini CLI, and Cursor.
+
+    Args:
+        project_path: Project to revive. Auto-detects from cwd.
+        soul_id: Specific soul to revive. Empty = latest.
+    """
+    from ai.session_phoenix import revive as _revive
+    result = _revive(project_path=project_path, soul_id=soul_id)
+    return _with_next_steps("revive", result)
+
+
 # ═══════════════════════════════════════════════════════════════════════
 #  DELIBERATION (Multi-Round Consensus)
 # ═══════════════════════════════════════════════════════════════════════
@@ -4352,6 +4566,59 @@ def _extract_deliberation_actions(result: Dict, question: str) -> List[Dict[str,
     return actions[:10]
 
 
+@mcp.tool()
+def delimit_audit(
+    target: str = "",
+    target_type: str = "file",
+    lenses: str = "",
+) -> Dict[str, Any]:
+    """Cross-model code audit -- 3 models, 3 lenses, synthesized findings (Pro).
+
+    Run security, correctness, and governance reviews through different AI models
+    simultaneously. Agreements are high-confidence. Disagreements surface tradeoffs.
+
+    "Trust through triangulation."
+
+    Args:
+        target: File path, git diff output, or code snippet to audit.
+        target_type: "file" (reads file), "diff" (git diff text), "snippet" (inline code).
+        lenses: Comma-separated lenses to apply (security, correctness, governance). Default: all.
+    """
+    from ai.license import require_premium
+    gate = require_premium("audit")
+    if gate:
+        return gate
+
+    if not target.strip():
+        return {"status": "error", "error": "No target provided. Pass a file path, diff, or code snippet."}
+
+    from ai.cross_model_audit import audit as run_audit
+
+    lens_list = [l.strip() for l in lenses.split(",") if l.strip()] if lenses else None
+
+    result = run_audit(
+        target=target,
+        target_type=target_type,
+        lenses=lens_list,
+    )
+
+    if result.get("status") == "error":
+        return result
+
+    synthesis = result.get("synthesis", {})
+    return _with_next_steps("audit", {
+        "status": "ok",
+        "formatted_output": result.get("formatted", ""),
+        "agreements": len(synthesis.get("agreements", [])),
+        "unique_findings": len(synthesis.get("unique_findings", [])),
+        "disagreements": len(synthesis.get("disagreements", [])),
+        "summary": synthesis.get("summary", ""),
+        "saved_to": result.get("saved_to", ""),
+        "elapsed_seconds": result.get("elapsed_seconds", 0),
+        "note": "Review the formatted output above. Agreements are high-confidence. Unique findings may be blind-spot catches.",
+    })
+
+
 @mcp.tool()
 def delimit_release_sync(action: str = "audit") -> Dict[str, Any]:
     """Audit or sync all public surfaces for consistency (Pro)."""
@@ -5477,6 +5744,66 @@ def delimit_social_target_config(
     return {"error": f"Unknown action: {action}. Supported: status, detect, update, add_subreddits"}
 
 
+@mcp.tool()
+def delimit_reddit_scan(sort: str = "hot", limit: int = 10) -> Dict[str, Any]:
+    """Bulk scan 25+ subreddits for outreach targets (Pro).
+
+    Scans via residential proxy. Rate limited to 1 req/2sec.
+    Returns ranked, categorized targets ready for comment drafting.
+
+    IMPORTANT -- TOOL CHAINING RULE:
+    After scanning, the AI MUST process high_priority targets:
+    1. Draft replies via delimit_social_post or delimit_notify
+    2. Create ledger items for strategic opportunities via delimit_ledger_add
+    Never just return targets and stop. Always chain to the next action.
+
+    Args:
+        sort: Reddit sort order (hot, new, top).
+        limit: Posts per subreddit (default 10, max 25).
+    """
+    from ai.reddit_scanner import scan_all
+
+    capped_limit = min(max(1, limit), 25)
+    if sort not in ("hot", "new", "top", "rising"):
+        sort = "hot"
+
+    result = scan_all(limit_per_sub=capped_limit, sort=sort)
+    return _with_next_steps("social_target", result)
+
+
+@_internal_tool()
+@mcp.tool()
+def delimit_github_scan(
+    cadence: str = "pulse",
+    limit: int = 20,
+) -> Dict[str, Any]:
+    """Scan GitHub for adoption leads, competitive intel, and repo health (Pro).
+
+    Three cadences:
+      pulse: Own repo health (stars, forks, issues, traffic). Fast, run often.
+      hunter: Competitor users, adoption leads, pain threads. Medium, run hourly.
+      deep: Full ecosystem intel. Slow, run daily.
+
+    IMPORTANT -- TOOL CHAINING RULE:
+    After scanning, the AI MUST process high-score findings:
+    1. Auto-ledger items (score >= 75 competitor users) via delimit_ledger_add
+    2. Pain threads with existing_feature relevance via delimit_notify
+    Never just return findings and stop. Always chain to the next action.
+
+    Args:
+        cadence: pulse, hunter, or deep.
+        limit: Max results per search query (default 20, max 30).
+    """
+    from ai.github_scanner import scan
+
+    if cadence not in ("pulse", "hunter", "deep"):
+        cadence = "pulse"
+    capped_limit = min(max(1, limit), 30)
+
+    result = scan(cadence=cadence, limit=capped_limit)
+    return _with_next_steps("github_scan", result)
+
+
 # ═══════════════════════════════════════════════════════════════════════
 #  CONTENT ENGINE — Autonomous video + tweet pipeline (Pro)
 # ═══════════════════════════════════════════════════════════════════════
@@ -5886,9 +6213,9 @@ def delimit_notify(channel: str = "webhook", message: str = "",
         subject: Subject line (email only). Use [ACTION], [INFO], [ALERT] prefix.
         event_type: Event category for filtering.
         to: Recipient email address (email only). Overrides default DELIMIT_SMTP_TO.
-            Send to any address — leave empty for default (configured-email@example.com).
+            Send to any address — leave empty for default (owner@example.com).
         from_account: Sender account key from ~/.delimit/secrets/smtp-all.json
-            (e.g. 'pro@delimit.ai', '<configured-email>'). Email only.
+            (e.g. 'pro@example.com', 'admin@example.com'). Email only.
     """
     from ai.notify import send_notification
     return _with_next_steps("notify", _safe_call(
@@ -5994,7 +6321,7 @@ def delimit_notify_inbox(action: str = "status", limit: int = 10,
     """Check inbound email inbox, classify, and route (Pro).
 
     Polls pro@delimit.ai via IMAP. Classifies emails as owner-action
-    (forwards to configured-email@example.com) or non-owner (stays in inbox).
+    (forwards to owner@example.com) or non-owner (stays in inbox).
 
     Args:
         action: 'status' (show inbox state), 'poll' (classify and optionally forward),
@@ -6344,6 +6671,253 @@ def delimit_loop_config(session_id: str = "", max_iterations: int = 0,
     return _with_next_steps("loop_config", r)
 
 
+# ═══════════════════════════════════════════════════════════════════════
+#  LED-219: Toolcard Delta Cache — reduce MCP tool schema token waste
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+def delimit_toolcard_cache(
+    action: str = "status",
+    tool_schemas: Optional[str] = None,
+    tool_names: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Manage the tool schema cache to reduce token waste (Pro).
+
+    MCP servers dump full tool definitions every session. This cache
+    stores schemas and sends only diffs, cutting context bloat.
+
+    Actions:
+        status: Show cache stats (tools cached, hit rate, token savings)
+        register: Register tool schemas (JSON array string). Auto-runs on first call.
+        delta: Get only changed/new tool names since last session (comma-separated names)
+        clear: Clear the cache (forces full schema send next session)
+        estimate: Estimate token savings for a tool set (JSON array string)
+        flush: Write session stats to disk log
+
+    Args:
+        action: One of: status, register, delta, clear, estimate, flush
+        tool_schemas: JSON array of tool schema objects (for register/estimate)
+        tool_names: Comma-separated tool names (for delta)
+    """
+    from ai.license import require_premium
+    gate = require_premium("toolcard_cache")
+    if gate:
+        return gate
+
+    from ai.toolcard_cache import get_cache
+    cache = get_cache()
+
+    if action == "status":
+        r = cache.get_stats()
+    elif action == "register":
+        if not tool_schemas:
+            return _with_next_steps("toolcard_cache", {
+                "error": "missing_param",
+                "message": "register action requires tool_schemas (JSON array of tool schema objects)"
+            })
+        try:
+            schemas = json.loads(tool_schemas)
+        except json.JSONDecodeError as e:
+            return _with_next_steps("toolcard_cache", {
+                "error": "invalid_json", "message": str(e)
+            })
+        r = cache.register_tools(schemas)
+    elif action == "delta":
+        names = [n.strip() for n in (tool_names or "").split(",") if n.strip()]
+        r = cache.get_delta(names)
+    elif action == "clear":
+        r = cache.clear()
+    elif action == "estimate":
+        if not tool_schemas:
+            return _with_next_steps("toolcard_cache", {
+                "error": "missing_param",
+                "message": "estimate action requires tool_schemas (JSON array of tool schema objects)"
+            })
+        try:
+            schemas = json.loads(tool_schemas)
+        except json.JSONDecodeError as e:
+            return _with_next_steps("toolcard_cache", {
+                "error": "invalid_json", "message": str(e)
+            })
+        r = cache.estimate_savings(schemas)
+    elif action == "flush":
+        r = cache.flush_session()
+    else:
+        r = {"error": "unknown_action", "message": f"Unknown action: {action}. Use: status, register, delta, clear, estimate, flush"}
+
+    return _with_next_steps("toolcard_cache", r)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  HANDOFF RECEIPTS — Agent-to-Agent Structured Handoffs (LED-220)
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+def delimit_handoff_create(
+    task_description: str = "",
+    completed: str = "",
+    not_completed: str = "",
+    assumptions: str = "",
+    blockers: str = "",
+    files_modified: str = "",
+    in_scope: str = "",
+    out_of_scope: str = "",
+    next_action: str = "",
+    priority: str = "P1",
+    to_model: str = "any",
+) -> Dict[str, Any]:
+    """Create a handoff receipt when transitioning between agents/sessions (Pro).
+
+    Documents what was done, what wasn't, and what the next agent should do.
+    The receiving agent should acknowledge before starting work.
+
+    Args:
+        task_description: What the task was (one line).
+        completed: Comma-separated list of completed items.
+        not_completed: Comma-separated list of items not completed (with reasons).
+        assumptions: Comma-separated assumptions made during work.
+        blockers: Comma-separated blockers encountered.
+        files_modified: JSON list of {path, change_type, summary} dicts, or empty for auto-detect.
+        in_scope: Comma-separated items that were in scope.
+        out_of_scope: Comma-separated items explicitly excluded.
+        next_action: What the receiving agent should do first.
+        priority: P0/P1/P2.
+        to_model: Target model (or "any").
+    """
+    from ai.handoff_receipts import create_receipt as _create, format_receipt
+
+    def _split(val: str) -> List[str]:
+        if not val or not val.strip():
+            return []
+        return [s.strip() for s in val.split(",") if s.strip()]
+
+    # Parse files_modified as JSON if provided
+    parsed_files = None
+    if files_modified and files_modified.strip():
+        try:
+            parsed_files = json.loads(files_modified)
+            if not isinstance(parsed_files, list):
+                parsed_files = None
+        except json.JSONDecodeError:
+            parsed_files = None
+
+    receipt = _create(
+        task_description=task_description,
+        completed=_split(completed),
+        not_completed=_split(not_completed),
+        assumptions=_split(assumptions),
+        blockers=_split(blockers),
+        files_modified=parsed_files,
+        in_scope=_split(in_scope),
+        out_of_scope=_split(out_of_scope),
+        next_action=next_action,
+        priority=priority,
+        from_model=_detect_model(),
+        to_model=to_model,
+    )
+
+    formatted = format_receipt(receipt)
+    return _with_next_steps("handoff_create", {
+        "status": "created",
+        "receipt_id": receipt.receipt_id,
+        "project": receipt.project_path,
+        "task_description": receipt.task_description,
+        "completed_count": len(receipt.completed),
+        "not_completed_count": len(receipt.not_completed),
+        "files_count": len(receipt.files_modified),
+        "next_action": receipt.next_action,
+        "priority": receipt.priority,
+        "formatted": formatted,
+        "message": f"Handoff receipt {receipt.receipt_id} created. Receiving agent should run delimit_handoff_acknowledge(receipt_id=\"{receipt.receipt_id}\").",
+    })
+
+
+@mcp.tool()
+def delimit_handoff_acknowledge(
+    receipt_id: str = "",
+    notes: str = "",
+) -> Dict[str, Any]:
+    """Acknowledge a handoff receipt before starting work (Pro).
+
+    Run this at the start of a session if there are pending handoff receipts.
+
+    Args:
+        receipt_id: The receipt ID to acknowledge.
+        notes: Optional notes from the receiving agent.
+    """
+    from ai.handoff_receipts import acknowledge_receipt as _ack
+
+    if not receipt_id or not receipt_id.strip():
+        return _with_next_steps("handoff_acknowledge", {
+            "status": "error",
+            "message": "receipt_id is required.",
+        })
+
+    result = _ack(
+        receipt_id=receipt_id.strip(),
+        model=_detect_model(),
+        notes=notes,
+    )
+    return _with_next_steps("handoff_acknowledge", result)
+
+
+@mcp.tool()
+def delimit_handoff_list(
+    status: str = "pending",
+) -> Dict[str, Any]:
+    """List handoff receipts (Pro).
+
+    Args:
+        status: "pending" (unacknowledged), "acknowledged", or "all".
+    """
+    from ai.handoff_receipts import get_receipts, format_receipt
+    from dataclasses import asdict
+
+    if status not in ("pending", "acknowledged", "all"):
+        status = "pending"
+
+    receipts = get_receipts(status=status)
+
+    if not receipts:
+        return _with_next_steps("handoff_list", {
+            "status": "empty",
+            "filter": status,
+            "count": 0,
+            "message": f"No {status} handoff receipts found.",
+        })
+
+    formatted_list = []
+    for r in receipts:
+        formatted_list.append({
+            "receipt_id": r.receipt_id,
+            "created_at": r.created_at,
+            "task_description": r.task_description,
+            "from_model": r.from_model,
+            "to_model": r.to_model,
+            "priority": r.priority,
+            "acknowledged": r.acknowledged,
+            "completed_count": len(r.completed),
+            "not_completed_count": len(r.not_completed),
+            "next_action": r.next_action,
+        })
+
+    # Format the first pending receipt in full for immediate context
+    display = ""
+    if status == "pending" and receipts:
+        display = format_receipt(receipts[0])
+
+    return _with_next_steps("handoff_list", {
+        "status": "ok",
+        "filter": status,
+        "count": len(receipts),
+        "receipts": formatted_list,
+        "display": display,
+        "message": f"{len(receipts)} {status} receipt(s) found.",
+    })
+
+
 # ═══════════════════════════════════════════════════════════════════════
 #  ENTRY POINT
 # ═══════════════════════════════════════════════════════════════════════

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
   "mcpName": "io.github.delimit-ai/delimit-mcp-server",
-  "version": "3.15.1",
+  "version": "3.15.2",
   "description": "Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.",
   "main": "index.js",
   "files": [