@nestpilot/mcp-app 1.0.0

package/dist/server.d.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AuthContext } from "./tools/mcp-helpers.js";
+export type { AuthContext } from "./tools/mcp-helpers.js";
+/**
+ * Auto-derive skill tool names from manifest.json (auto-registration convention).
+ * Adding a new tool only requires updating manifest.json — no server.ts edits needed.
+ * Exported for test access.
+ */
+export declare function loadSkillToolNames(skillsDir?: string): string[];
+/**
+ * Creates a new MCP server instance with all NestPilot tools and resources.
+ * When `authCtx` is provided (HTTP transport), it is threaded through to all
+ * tool registrations so backend calls carry the user's JWT.
+ *
+ * Mode detection (FEAT-0087):
+ *  - NESTPILOT_MODE=cloud (default) → proxy all tools to Spring Boot API
+ *  - NESTPILOT_MODE=local → local data layer + cloud compute for PII-free payloads
+ */
+export declare function createServer(authCtx?: AuthContext): McpServer;

package/dist/server.js

@@ -0,0 +1,245 @@
+/**
+ * NestPilot MCP Server — Orchestrator
+ *
+ * Creates the MCP server and registers tool groups by domain:
+ *   - Medicare tools (medicare-guardian, medicare-analyze, email-subscribe)
+ *   - Planning tools (create_plan, run_forecast, run_scenario, verify_forecast, coach)
+ *   - Roth tools (optimize_roth_conversion) — FEAT-0066
+ *   - Report tools (generate_retirement_report)
+ *   - Agent Runtime tools (list_skills, run_skill, run_plan)
+ *   - Views (retirement-planner, verification-packet, medicare-guardian)
+ *
+ * Unified MCP gateway — consolidates apps/mcp-edge into apps/mcp-app (FEAT-0053).
+ * Production features: security, rate-limit, telemetry.
+ */
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { registerAgentTools } from "./tools/agent-tools.js";
+import { registerForecastManagementTools } from "./tools/forecast-management-tools.js";
+import { registerLocalPlanTools } from "./tools/local-plan-tools.js";
+import { registerMedicareTools } from "./tools/medicare-tools.js";
+import { registerRothTools } from "./tools/optimize-roth-tools.js";
+import { registerPlanManagementTools } from "./tools/plan-management-tools.js";
+import { registerPlanningTools } from "./tools/planning-tools.js";
+import { registerProposalTools } from "./tools/proposal-tools.js";
+import { registerReportTools } from "./tools/report-tools.js";
+import { registerScenarioManagementTools } from "./tools/scenario-management-tools.js";
+import { loadLocalConfig, EncryptionService, LocalPlanStore, CloudComputeClient, createKeychainProvider, } from "./src/local/local-data-layer.js";
+// ── Skill resource constants (MCP Appliance — FEAT-0065 Phase 1) ────────
+const SKILLS_DIR = path.join(import.meta.dirname, "skills");
+const SKILL_MANIFEST_URI = "resource://skill/manifest.json";
+const SKILL_MAIN_URI = "resource://skill/SKILL.md";
+/**
+ * Auto-derive skill tool names from manifest.json (auto-registration convention).
+ * Adding a new tool only requires updating manifest.json — no server.ts edits needed.
+ * Exported for test access.
+ */
+export function loadSkillToolNames(skillsDir = SKILLS_DIR) {
+    try {
+        const manifestPath = path.join(skillsDir, "manifest.json");
+        const raw = fsSync.readFileSync(manifestPath, "utf-8");
+        const manifest = JSON.parse(raw);
+        return Object.keys(manifest.skill.tool_skills);
+    }
+    catch (e) {
+        console.warn("[server] Failed to load skill tool names from manifest.json:", e.message);
+        return [];
+    }
+}
+const SKILL_TOOL_NAMES = loadSkillToolNames();
+// Works both from source (*.ts) and compiled (dist/)
+const DIST_DIR = import.meta.filename.endsWith(".ts")
+    ? path.join(import.meta.dirname, "dist")
+    : path.join(import.meta.dirname);
+/**
+ * Creates a new MCP server instance with all NestPilot tools and resources.
+ * When `authCtx` is provided (HTTP transport), it is threaded through to all
+ * tool registrations so backend calls carry the user's JWT.
+ *
+ * Mode detection (FEAT-0087):
+ *  - NESTPILOT_MODE=cloud (default) → proxy all tools to Spring Boot API
+ *  - NESTPILOT_MODE=local → local data layer + cloud compute for PII-free payloads
+ */
+export function createServer(authCtx) {
+    const localConfig = loadLocalConfig();
+    const server = new McpServer({
+        name: "NestPilot",
+        version: "1.0.0",
+    });
+    if (localConfig.mode === "local") {
+        // ── Local mode (FEAT-0087) ────────────────────────────────────────
+        console.log("[server] Starting in LOCAL mode — data stays on this machine");
+        const keychain = createKeychainProvider(localConfig.dataDir);
+        const encryption = new EncryptionService(keychain);
+        const store = new LocalPlanStore(localConfig.dataDir, encryption);
+        const computeClient = new CloudComputeClient(localConfig.cloudApiUrl, localConfig.apiKey ?? "");
+        console.log("Registering Local Plan tools...");
+        registerLocalPlanTools(server, store, computeClient);
+        // Cloud-backed tools that use PII-free payloads
+        console.log("Registering Medicare tools (cloud)...");
+        registerMedicareTools(server, authCtx);
+        console.log("Registering Roth tools (cloud)...");
+        registerRothTools(server, authCtx);
+        console.log("Registering Report tools (cloud)...");
+        registerReportTools(server, authCtx);
+    }
+    else {
+        // ── Cloud mode (default — existing behavior) ──────────────────────
+        console.log("[server] Starting in CLOUD mode — proxy to Spring Boot API");
+        console.log("Registering Medicare tools...");
+        registerMedicareTools(server, authCtx);
+        console.log("Registering Planning tools...");
+        registerPlanningTools(server, authCtx);
+        console.log("Registering Roth tools...");
+        registerRothTools(server, authCtx);
+        console.log("Registering Agent tools...");
+        registerAgentTools(server, authCtx);
+        console.log("Registering Plan Management tools...");
+        registerPlanManagementTools(server, authCtx);
+        console.log("Registering Forecast Management tools...");
+        registerForecastManagementTools(server, authCtx);
+        console.log("Registering Scenario Management tools...");
+        registerScenarioManagementTools(server, authCtx);
+        console.log("Registering Proposal tools...");
+        registerProposalTools(server, authCtx);
+        console.log("Registering Report tools...");
+        registerReportTools(server, authCtx);
+    }
+    // ── Shared registrations (both modes) ─────────────────────────────────
+    console.log("Registering views...");
+    registerPlannerView(server);
+    registerVerificationPacketView(server);
+    registerSkillResources(server);
+    console.log("Server registration complete");
+    return server;
+}
+// ── Retirement Planner view ─────────────────────────────────────────────
+function registerPlannerView(server) {
+    // Keep stable URI for host compatibility and support the old cache-busting alias.
+    const resourceUri = "ui://retirement-planner/planner.html";
+    const resourceUriAlias = "ui://retirement-planner/planner-v2.html";
+    // Tool that launches the interactive planner view
+    registerAppTool(server, "retirement-planner", {
+        title: "Retirement Planner",
+        description: `Opens an interactive retirement planner with plan creation form, forecast charts, and scenario comparison.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to create or edit a retirement plan interactively
+- Asks to see their retirement forecast as charts
+- Wants a visual retirement planning experience
+- Says "show me my retirement plan" or "open the planner"
+
+The view supports three modes:
+- editor (default): Input form for quick plan creation
+- forecast: Displays forecast charts for an existing plan
+- scenario: Shows baseline vs candidate scenario comparison`,
+        inputSchema: {
+            mode: z
+                .enum(["editor", "forecast", "scenario"])
+                .default("editor")
+                .describe("View mode: 'editor' (plan form), 'forecast' (charts), or 'scenario' (comparison)"),
+        },
+        _meta: {
+            ui: {
+                resourceUri,
+                visibility: ["model", "app"],
+            },
+            // Host compatibility fallback for clients that still read OpenAI-style keys.
+            "openai/outputTemplate": resourceUri,
+            "openai/widgetAccessible": true,
+        },
+    }, async (args) => {
+        const { mode = "editor" } = args;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        mode,
+                        message: `Retirement planner opened in ${mode} mode`,
+                    }),
+                },
+                {
+                    type: "resource_link",
+                    uri: resourceUri,
+                    name: "NestPilot Retirement Planner",
+                    title: "Open Retirement Planner",
+                    description: `Interactive planner view (${mode} mode)`,
+                    mimeType: RESOURCE_MIME_TYPE,
+                },
+            ],
+            _meta: {
+                "openai/outputTemplate": resourceUri,
+                "openai/widgetDescription": "Interactive retirement planner with editor, forecast chart, and scenario comparison.",
+            },
+        };
+    });
+    // UI resource: serves the bundled single-file HTML for the planner view
+    registerAppResource(server, resourceUri, resourceUri, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const html = await fs.readFile(path.join(DIST_DIR, "planner.html"), "utf-8");
+        return {
+            contents: [
+                { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+            ],
+        };
+    });
+    // Alias registration for hosts that still reference the previous URI.
+    registerAppResource(server, resourceUriAlias, resourceUriAlias, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const html = await fs.readFile(path.join(DIST_DIR, "planner.html"), "utf-8");
+        return {
+            contents: [
+                { uri: resourceUriAlias, mimeType: RESOURCE_MIME_TYPE, text: html },
+            ],
+        };
+    });
+}
+// ── Verification Packet view ─────────────────────────────────────────────
+function registerVerificationPacketView(server) {
+    const resourceUri = "ui://verification-packet/verification-packet.html";
+    registerAppResource(server, resourceUri, resourceUri, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const html = await fs.readFile(path.join(DIST_DIR, "views", "verification-packet.html"), "utf-8");
+        return {
+            contents: [
+                { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+            ],
+        };
+    });
+}
+// ── Skill resources (MCP Appliance — FEAT-0065 Phase 1) ─────────────────
+//
+// Registers well-known skill URIs so any MCP host can discover and load
+// NestPilot's operational skills via the resource://skill/ convention.
+// All files are read lazily (on resource/read request) so createServer()
+// stays synchronous and fast.
+function registerSkillResources(server) {
+    // Tier 0: manifest — AI host discovers skill capabilities
+    server.resource("skill-manifest", SKILL_MANIFEST_URI, { mimeType: "application/json" }, async () => {
+        const text = await fs.readFile(path.join(SKILLS_DIR, "manifest.json"), "utf-8");
+        return {
+            contents: [
+                { uri: SKILL_MANIFEST_URI, mimeType: "application/json", text },
+            ],
+        };
+    });
+    // Tier 2: main skill document — workflow overview and boundaries
+    server.resource("skill-main", SKILL_MAIN_URI, { mimeType: "text/markdown" }, async () => {
+        const text = await fs.readFile(path.join(SKILLS_DIR, "SKILL.md"), "utf-8");
+        return {
+            contents: [{ uri: SKILL_MAIN_URI, mimeType: "text/markdown", text }],
+        };
+    });
+    // Tier 2: per-tool skill documents — tool-specific guidance loaded on demand
+    for (const toolName of SKILL_TOOL_NAMES) {
+        const uri = `resource://skill/tools/${toolName}.md`;
+        server.resource(`skill-tool-${toolName}`, uri, { mimeType: "text/markdown" }, async () => {
+            const text = await fs.readFile(path.join(SKILLS_DIR, "tools", `${toolName}.md`), "utf-8");
+            return {
+                contents: [{ uri, mimeType: "text/markdown", text }],
+            };
+        });
+    }
+}

package/dist/skills/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: nestpilot-retirement
+version: "1.0.0"
+description: "Retirement planning, forecasting, scenario analysis, Medicare enrollment, and AI coaching"
+tools:
+  - medicare-guardian
+  - create_plan
+  - run_forecast
+  - verify_forecast
+  - run_scenario
+  - retirement-planner
+  - nestpilot_run_plan
+  - coach
+  - optimize_roth_conversion
+  - optimize_ss_claiming
+  - generate_proposal
+references:
+  - tools/medicare-guardian.md
+  - tools/create_plan.md
+  - tools/run_forecast.md
+  - tools/verify_forecast.md
+  - tools/run_scenario.md
+  - tools/retirement-planner.md
+  - tools/nestpilot_run_plan.md
+  - tools/coach.md
+  - tools/optimize_roth_conversion.md
+  - tools/optimize_ss_claiming.md
+  - tools/generate_proposal.md
+---
+
+# NestPilot Retirement Planning Skill
+
+NestPilot is an independent retirement planning and verification platform for mass affluent
+Americans navigating the saving-to-spending transition. It is NOT a product seller — it is a
+client-side verification and planning engine with no conflicts of interest.
+
+## Core Principles
+
+1. **Show the math.** Always explain calculations, not just results. Users trust verifiable numbers.
+2. **Assumptions are first-class.** Make every assumption explicit. Users should be able to see what
+   drives the forecast (return rate, withdrawal rate, life expectancy, inflation).
+3. **Independent verification.** NestPilot verifies plans mathematically — do not recommend specific
+   products. Say "the math shows X" not "you should buy Y."
+4. **Decumulation focus.** The critical problem is the saving-to-spending transition: tax-efficient
+   withdrawal sequencing, Medicare timing, longevity risk management.
+
+## Workflow Overview
+
+### Quick Retirement Projection
+
+1. Gather user inputs: current age, target retirement age, life expectancy, current balance,
+   monthly contribution, expected return rate, withdrawal rate, target annual spending.
+2. Call `create_plan` with the gathered inputs.
+3. Present the result focusing on: projected balance at retirement, estimated monthly income,
+   readiness score, sustainability years.
+4. Offer to open the interactive planner (`retirement-planner`) for visual exploration.
+
+### Comprehensive Forecast
+
+- Use `run_forecast` when the user has detailed financial data: multiple accounts (401k, IRA,
+  Roth, taxable), multiple income streams (salary, Social Security, pension), spouse data.
+- The forecast returns year-by-year projections, portfolio runway, legacy value, and success
+  probability.
+- Present as a narrative: "Based on your plan, here is how your portfolio is projected to evolve..."
+
+### What-If Scenario Analysis
+
+- Use `run_scenario` for what-if analysis: "What if I retire 3 years earlier?" "What if markets
+  return 5% instead of 7%?" "What if I add an annuity?"
+- Always present the difference vs. the base case: delta metrics for readiness score, legacy value.
+- Frame scenarios as exploration: "If X, then Y" not "you should do X."
+- Supports historical stress tests (2008 crisis, dot-com bust, 1929 crash).
+
+### Verifying a Forecast
+
+- Use `verify_forecast` when the user wants to double-check their advisor's numbers
+  or validate a scenario.
+- The verification packet includes the assumptions, the calculation trace, and the verdict.
+- Present the verdict clearly: "The math checks out" or "The projection is optimistic because..."
+- NEVER suggest the advisor was wrong — present verification as confirmation or a starting
+  point for a conversation with the advisor.
+
+### Interactive Retirement Planner
+
+- Use `retirement-planner` when the user wants a visual, interactive planning experience.
+- Supports three modes: editor (plan input form), forecast (charts), scenario (comparison view).
+- The planner renders as a full interactive UI in the host application.
+- Offer this after running `create_plan` or `run_forecast` for visual exploration.
+
+### Medicare Guardian
+
+- Use `medicare-guardian` when the user is approaching 65 or asking about Medicare.
+- The tool opens an interactive Medicare enrollment readiness view.
+- Key outputs: enrollment window (IEP/SEP/GEP), penalty risk, IRMAA income surcharge exposure.
+- CRITICAL: Never recommend specific Medicare plans (Part C/D plans). Only clarify enrollment
+  timing rules, penalty risks, and income thresholds. This is an educational tool.
+
+### AI Coach
+
+- Use `coach` for open-ended retirement guidance and personalized advice.
+- Coach is powered by AI and provides explanations, not calculations.
+- Use coach for: "Explain Roth conversions", "Should I delay Social Security?",
+  "What is the tax torpedo?"
+- Coach output is advisory — always suggest verifying with `run_forecast` or `verify_forecast`
+  for quantitative decisions.
+
+### Agent-Powered Retirement Readiness
+
+- Use `nestpilot_run_plan` for a complete retirement readiness assessment powered by the agent
+  runtime. This combines skill execution, context gathering, and structured analysis.
+- Use when the user provides their retirement situation in natural language and wants a full
+  assessment without manually providing structured inputs.
+
+### Roth Conversion Optimization
+
+- Use `optimize_roth_conversion` when asking about Roth conversions, tax bracket optimization,
+  or Traditional-to-Roth IRA strategies.
+- The tool analyzes multi-year conversion windows: bracket headroom, IRMAA thresholds, RMD
+  impact, and break-even timing.
+- Present results as: "Based on your tax situation, converting $X over Y years could save
+  $Z in lifetime taxes."
+- CRITICAL: This is tax-related analysis. Always include: "Consult a tax professional before
+  making conversion decisions." The tool provides math, not tax advice.
+- Flag IRMAA cliff warnings when income approaches Medicare surcharge thresholds.
+
+### Social Security Claiming Optimization
+
+- Use `optimize_ss_claiming` when the user asks "When should I claim Social Security?" or
+  wants to compare claiming ages.
+- The tool simulates claiming at ages 62-70, shows break-even ages, and calculates NPV of
+  lifetime benefits.
+- For couples, it analyzes spousal and survivor benefit strategies.
+- Present break-even analysis in plain language: "If you delay from 62 to 67, you break even
+  at age 78. If you live past 78, delaying pays off."
+- Coordinate with Roth conversion windows: "The years you delay SS may create low-income
+  years ideal for Roth conversions."
+- NEVER predict government policy changes. Note that benefit formulas may change.
+
+### Proposal Generation (Advisor)
+
+- Use `generate_proposal` when an advisor wants to create a client-ready proposal package.
+- The tool assembles: plan summary PDF, scenario comparisons, optional Roth and SS analyses,
+  AI recommendations, and an evidence packet.
+- Always confirm with the advisor before releasing to the client (`autoRelease` defaults to false).
+- Present the draft for review first: "Here's your proposal draft. Shall I release it to the client?"
+
+## Response Formatting
+
+- Lead with the user's outcome in plain language ("You are on track for retirement at 65").
+- Follow with the key numbers (balance, income, years of coverage).
+- Explain the 1-2 most important assumptions that drive the result.
+- Offer a next step: scenario to explore, planner to open, or forecast to run.
+- Keep responses concise. Users are busy adults making important decisions — respect their time.
+
+## Boundaries
+
+- Do NOT recommend specific investment products, funds, or advisors.
+- Do NOT provide tax advice (explain tax concepts, but say "consult a tax professional for your
+  specific situation").
+- Do NOT make predictions about market returns — use the user's provided return rate assumption.
+- Do NOT recommend specific Medicare Advantage or Medigap plans.
+- Do NOT discuss NestPilot pricing, subscriptions, or business model unless asked directly.

package/dist/skills/manifest.json

@@ -0,0 +1,51 @@
+{
+  "skill": {
+    "name": "nestpilot-retirement",
+    "version": "1.0.0",
+    "description": "Retirement planning, forecasting, verification, scenario analysis, Medicare enrollment, AI coaching, interactive planner UI, and agent-powered retirement readiness.",
+    "entry_point": "resource://skill/SKILL.md",
+    "loading_strategy": "on_demand",
+    "priority": "primary",
+    "tool_skills": {
+      "medicare-guardian": "resource://skill/tools/medicare-guardian.md",
+      "create_plan": "resource://skill/tools/create_plan.md",
+      "run_forecast": "resource://skill/tools/run_forecast.md",
+      "verify_forecast": "resource://skill/tools/verify_forecast.md",
+      "run_scenario": "resource://skill/tools/run_scenario.md",
+      "retirement-planner": "resource://skill/tools/retirement-planner.md",
+      "nestpilot_run_plan": "resource://skill/tools/nestpilot_run_plan.md",
+      "coach": "resource://skill/tools/coach.md",
+      "optimize_roth_conversion": "resource://skill/tools/optimize_roth_conversion.md",
+      "optimize_ss_claiming": "resource://skill/tools/optimize_ss_claiming.md",
+      "generate_proposal": "resource://skill/tools/generate_proposal.md",
+      "list_plans": "resource://skill/tools/list_plans.md",
+      "get_plan": "resource://skill/tools/get_plan.md",
+      "get_active_plan": "resource://skill/tools/get_active_plan.md",
+      "create_saved_plan": "resource://skill/tools/create_saved_plan.md",
+      "save_plan": "resource://skill/tools/save_plan.md",
+      "activate_plan": "resource://skill/tools/activate_plan.md",
+      "delete_plan": "resource://skill/tools/delete_plan.md",
+      "rename_plan": "resource://skill/tools/rename_plan.md",
+      "get_plan_components": "resource://skill/tools/get_plan_components.md",
+      "run_saved_forecast": "resource://skill/tools/run_saved_forecast.md",
+      "get_baseline_forecast": "resource://skill/tools/get_baseline_forecast.md",
+      "save_scenario": "resource://skill/tools/save_scenario.md",
+      "list_scenarios": "resource://skill/tools/list_scenarios.md",
+      "get_scenario": "resource://skill/tools/get_scenario.md",
+      "delete_scenario": "resource://skill/tools/delete_scenario.md",
+      "comprehensive_plan": "resource://skill/tools/comprehensive_plan.md",
+      "generate_retirement_report": "resource://skill/tools/generate_retirement_report.md"
+    },
+    "composes_with": [
+      "data-analysis",
+      "document-creator"
+    ],
+    "model_hints": {
+      "min_context_window": 8000,
+      "supports": [
+        "claude-3+",
+        "gpt-4+"
+      ]
+    }
+  }
+}

package/dist/skills/tools/activate_plan.md

@@ -0,0 +1,36 @@
+# Tool Skill: activate_plan
+
+Sets a specific saved plan as the user's active (default) plan. The active plan is the one
+returned by `get_active_plan` and used as the implicit context when the user says "my plan."
+
+## When to Use
+
+Use `activate_plan` when the user:
+- Says "Make this my main plan" or "Set [plan name] as active"
+- Wants to switch their default plan after comparing options
+- Just created a new plan and wants it to be the primary one
+- Asks "Use this plan going forward"
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the plan to activate
+
+If the user refers to a plan by name, resolve the ID via `list_plans` first.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "Done — '[name]' is now your active plan."
+
+2. **Context**: "Future requests like 'run a forecast' or 'show my plan' will use this
+   plan by default unless you specify another."
+
+3. **Previous Active** (if known): "Your previous active plan was '[old name]'. It's
+   still saved and accessible."
+
+## Common Follow-Up Patterns
+
+- User wants to see the plan → `get_active_plan`
+- User wants a forecast on it → `run_saved_forecast`
+- User realizes they picked the wrong one → `list_plans` then `activate_plan` again

package/dist/skills/tools/coach.md

@@ -0,0 +1,59 @@
+# Tool Skill: coach
+
+Provides AI-powered retirement coaching — conversational guidance, explanations of retirement
+concepts, and personalized next-step suggestions. Coach is advisory; it explains and frames
+decisions but does not replace quantitative tools.
+
+## When to Use
+
+Use `coach` for:
+- Explaining retirement concepts ("What is a Roth conversion?", "How does the 4% rule work?")
+- Personalized guidance when the user has described their situation and wants advice
+- Synthesizing insights after running forecasts or scenarios ("What does this mean for me?")
+- Behavioral nudges ("I'm worried I'm saving too little — what should I think about?")
+- Open-ended questions that need narrative answers, not calculations
+
+## When NOT to Use
+
+- Do NOT use coach for calculation requests — use `run_forecast` or `create_plan` instead
+- Do NOT use coach for Medicare enrollment timing — use `medicare_guardian` instead
+- Do NOT use coach for "verify my advisor's numbers" — use `verify_forecast` instead
+
+## Sending a Good Coaching Request
+
+Provide as much context as possible in the `content` field:
+- User's age, retirement timeline, and current savings (if known from prior conversation)
+- Specific question or concern
+- Any plan or scenario results from prior tool calls (to give coach the math context)
+
+Example: "User is 58, wants to retire at 63, has $850K saved, asking about Roth conversion
+ladder strategy to reduce RMDs."
+
+Pass `planId` if there is a saved plan — coach will use it as context.
+
+## Presenting Coach Output
+
+Coach output is narrative guidance. Present it as:
+- A direct, empathetic response to the user's question
+- Explanation of the relevant concept in plain language
+- Actionable next step (run a scenario, consult an advisor, make a specific change)
+
+Always end coaching responses with a bridge to quantitative verification:
+"To see the numbers, we can run a [forecast / scenario / verification] — want me to set that
+up for you?"
+
+## Tone and Boundaries
+
+- Be empathetic but not patronizing. Users are intelligent adults making complex decisions.
+- Be honest about uncertainty: "The math depends on your return assumption — here's the range."
+- Do NOT tell users what to do — frame as "here are the options and trade-offs."
+- Do NOT recommend specific financial products, advisors, or tax strategies.
+- For questions beyond NestPilot's scope (estate planning, insurance selection, tax filing),
+  recommend consulting a CFP, CPA, or estate attorney.
+
+## Error Handling
+
+If the backend returns an error, acknowledge the issue and offer to answer the conceptual
+question from general knowledge while the service recovers:
+"I'm having trouble reaching the coaching service right now. Based on what you've described,
+here's what I can share from general retirement planning principles: [response]"

package/dist/skills/tools/comprehensive_plan.md

@@ -0,0 +1,65 @@
+# Tool Skill: comprehensive_plan
+
+Executes a combined coaching analysis and retirement forecast in a single call. Takes a full
+PlanContract payload, runs the coaching engine for qualitative guidance and the forecast engine
+for quantitative projections, and returns both results together.
+
+## When to Use
+
+Use `comprehensive_plan` when the user:
+- Wants a complete picture: both actionable advice and hard numbers in one pass
+- Says "Give me the full analysis" or "What should I do and where do I stand?"
+- Is a new user providing all their data at once and wants immediate value
+- Wants coaching recommendations alongside projected outcomes
+- Asks "How can I improve my plan?" (needs both diagnosis and projection)
+
+Use `run_forecast` or `run_saved_forecast` instead when the user only needs numbers.
+Use `coach` instead when the user only needs qualitative advice without projections.
+
+## Required Inputs to Gather
+
+This tool accepts a full PlanContract payload — the same structure used by `run_forecast`:
+
+**Required:**
+- `household.primary.currentAge` — integer
+- `household.primary.retireAge` — integer
+- `goals.retirement.targetSpending.amountMonthly` — target monthly spending
+- `accounts` — at least one: `{type, balance, annualContribution?, realReturn?}`
+- `incomeStreams` — at least one: `{type, amountMonthly, startAge?, endAge?}`
+
+**Optional but improves coaching quality:**
+- `household.primary.socialSecurity` — claiming age and estimated benefit
+- `household.spouse` — enables household-level coaching
+- `goals.retirement.safeWithdrawalRate` — default 0.04
+- `goals.retirement.withdrawalStrategy` — `"taxable_first"` or `"traditional_first"`
+- `riskProfile` — conservative, moderate, aggressive (influences coaching tone)
+
+## Presenting the Results
+
+Structure the response in two sections:
+
+1. **Coaching Summary**:
+   - Top 3 recommendations ranked by impact
+   - Each with a plain-language explanation and estimated benefit
+   - e.g., "Delay Social Security from 62 to 67 — adds ~$450/mo to your benefit"
+
+2. **Forecast Summary**:
+   - Readiness score: X/100
+   - Portfolio runway: X years
+   - Legacy value: $X
+   - Success probability: X%
+
+3. **Integrated Insight**: Connect the coaching to the numbers:
+   "Your readiness score of 72 reflects the gap between your $6,000/mo target and your
+   projected $4,800/mo sustainable withdrawal. The top recommendation (delaying SS) would
+   close roughly half that gap."
+
+4. **Next Steps**: Offer to save as a plan, run a specific scenario from the coaching
+   recommendations, or explore the planner visually.
+
+## Common Follow-Up Patterns
+
+- User wants to save the plan → `create_saved_plan`
+- User wants to explore a recommendation → `run_scenario` with the suggested delta
+- User wants just the coaching detail → `coach`
+- User wants year-by-year breakdown → `run_forecast` or `retirement-planner`