@nestpilot/mcp-app 1.0.0

package/host-configs/cowork.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "nestpilot": {
+      "command": "npx",
+      "args": ["nestpilot-mcp-server"],
+      "env": {
+        "NESTPILOT_MODE": "local"
+      }
+    }
+  }
+}

package/host-configs/goose.yaml

@@ -0,0 +1,22 @@
+# NestPilot MCP Server — Goose Host Configuration
+#
+# Add this to your Goose profile configuration:
+#   ~/.config/goose/profiles.yaml
+#
+# Under the `extensions:` section of your active profile,
+# paste the following block.
+#
+# @feature FEAT-0088
+
+extensions:
+  nestpilot:
+    type: mcp
+    transport: stdio
+    command: npx
+    args: ["nestpilot-mcp-server"]
+    env:
+      NESTPILOT_MODE: local
+      # Optional overrides:
+      # NESTPILOT_DATA_DIR: "~/.nestpilot"
+      # NESTPILOT_CLOUD_API_URL: "https://api.nestpilot.com"
+      # NESTPILOT_API_KEY: "your-api-key"

package/host-configs/openclaw-manifest.json

@@ -0,0 +1,16 @@
+{
+  "name": "nestpilot",
+  "version": "1.0.0",
+  "description": "Local-first retirement planning — your data stays on your machine",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["nestpilot-mcp-server"],
+  "env": {
+    "NESTPILOT_MODE": "local"
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": true,
+    "apps": true
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nestpilot/mcp-app",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "NestPilot MCP App — Retirement planning tools and interactive views",
+  "bin": {
+    "nestpilot-mcp-server": "dist/cli/index.js",
+    "nestpilot": "dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "host-configs/",
+    "README.md"
+  ],
+  "scripts": {
+    "build:medicare": "vite build",
+    "build:planner": "vite build --config vite.planner.config.ts",
+    "build:verification": "vite build --config vite.verification.config.ts",
+    "build": "npm run build:medicare && npm run build:planner && npm run build:verification",
+    "build:package": "tsx scripts/build-npm-package.ts",
+    "serve": "tsx main.ts",
+    "serve:auth": "node ./scripts/start-auth.mjs",
+    "serve:auth:stdio": "node ./scripts/start-auth.mjs --stdio",
+    "start": "npm run build && npm run serve",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.0.1",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/sdk-trace-node": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "commander": "^13.1.0",
+    "cors": "^2.8.6",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "lucide-react": "^0.563.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "recharts": "^3.7.0",
+    "tailwind-merge": "^3.4.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.25",
+    "@types/node": "^22.10.5",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.24",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.19",
+    "tailwindcss-animate": "^1.0.7",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.1",
+    "vite-plugin-singlefile": "^2.3.0",
+    "vitest": "^3.0.0"
+  }
+}

package/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/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/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/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/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`

package/skills/tools/create_plan.md

@@ -0,0 +1,59 @@
+# Tool Skill: create_plan
+
+Creates a quick retirement plan projection given basic inputs. Returns projected balance at
+retirement, safe withdrawal amount, readiness score, and sustainability years.
+
+## When to Use
+
+Use `create_plan` when the user:
+- Wants a quick retirement projection given basic inputs
+- Asks "Am I on track to retire?" or "How much will I have at retirement?"
+- Provides their age, retirement age, savings balance, and contribution amounts
+- Wants to understand their withdrawal rate feasibility
+- Is doing an initial assessment before a detailed forecast
+
+Use `run_forecast` instead when the user has:
+- Multiple accounts (401k, IRA, Roth, taxable)
+- Multiple income streams (salary + Social Security + pension)
+- Spouse data or household-level analysis needs
+- Interest in year-by-year projections
+
+## Required Inputs to Gather
+
+- `currentAge` — current age (integer)
+- `retireAge` — target retirement age (integer)
+- `lifeExpectancy` — planning horizon / life expectancy (integer)
+- `realReturnRate` — expected real annual return (decimal, e.g., 0.05 for 5%)
+- `withdrawalRate` — planned annual withdrawal rate in retirement (decimal, e.g., 0.04)
+
+Helpful optional inputs:
+- `currentBalance` — current total savings in dollars
+- `monthlyContribution` — monthly savings contribution in dollars
+- `targetAnnualSpending` — desired annual spending in retirement
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Headline**: "Based on your inputs, you are [on track / at risk / needs attention] for
+   retirement at [age]."
+
+2. **Key Numbers**:
+   - Projected balance at retirement: $X
+   - Safe withdrawal amount (monthly): $X (= projectedBalance × withdrawalRate / 12)
+   - Readiness score: X/100
+   - Sustainability years: X years (how long the portfolio covers spending)
+
+3. **Key Assumptions** (always surface these):
+   - Return rate: X% real (after inflation)
+   - Withdrawal rate: X%
+   - Years until retirement: X
+
+4. **Next Step**: Offer to run a scenario or open the interactive planner:
+   "Want to see what happens if you [retire earlier / save more / adjust return rate]?"
+
+## Common Follow-Up Patterns
+
+- User asks "what if I retire earlier?" → use `run_scenario` with retirement age delta
+- User wants visual charts → use `retirement-planner` in `forecast` mode
+- User has more detailed financial data → use `run_forecast`

package/skills/tools/create_saved_plan.md

@@ -0,0 +1,49 @@
+# Tool Skill: create_saved_plan
+
+Creates and persists a new retirement plan in the user's account. Unlike `create_plan` (which
+is stateless and returns a quick projection), this tool saves the plan to the database so it
+can be retrieved, forecasted, and iterated on over time.
+
+## When to Use
+
+Use `create_saved_plan` when the user:
+- Wants to build a new plan and keep it for future sessions
+- Says "Save this as a new plan" or "Create a plan called [name]"
+- Is starting fresh and wants to set up their financial profile
+- Has provided enough data to construct a PlanContract (household, accounts, goals)
+
+Use `create_plan` instead for a quick one-off projection that doesn't need to persist.
+
+## Required Inputs to Gather
+
+- `name` (string) — a label for the plan (e.g., "Conservative 65", "Early Retirement")
+- `household.primary.currentAge` — integer
+- `household.primary.retireAge` — integer
+- `accounts` — at least one: `{type, balance, annualContribution?, realReturn?}`
+- `goals.retirement.targetSpending.amountMonthly` — target monthly spend
+
+**Optional but recommended:**
+- `household.primary.lifeExpectancy` — default 95
+- `incomeStreams` — salary, Social Security, pension, etc.
+- `household.spouse` — partner data for household-level planning
+- `setActive` (boolean) — whether to make this the active plan immediately
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "I've created your plan '[name]' (ID: [planId])."
+
+2. **Summary**: Brief recap of household, total balances, and target spending.
+
+3. **Active Status**: "This plan [is / is not] set as your active plan."
+
+4. **Next Step**: "Want me to run a forecast on this plan, or add more accounts
+   and income streams?"
+
+## Common Follow-Up Patterns
+
+- User wants projections → `run_saved_forecast`
+- User wants to add components → `save_plan` with updated accounts/streams
+- User wants it as default → `activate_plan`
+- User wants a quick comparison → `comprehensive_plan`

package/skills/tools/delete_plan.md

@@ -0,0 +1,42 @@
+# Tool Skill: delete_plan
+
+Soft-deletes a saved retirement plan. The plan is marked as deleted and hidden from
+`list_plans` but can potentially be recovered by support. Associated forecasts and
+scenarios are preserved but become inaccessible through normal API calls.
+
+## When to Use
+
+Use `delete_plan` when the user:
+- Says "Delete my [plan name] plan" or "Remove this plan"
+- Wants to clean up old or duplicate plans
+- Confirms deletion after being prompted
+
+**Always confirm before deleting.** Ask: "Are you sure you want to delete '[name]'?
+This will hide the plan and its associated forecasts."
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the plan to delete
+
+If the user refers to a plan by name, resolve the ID via `list_plans` first.
+
+Never delete the active plan without warning. If the target is the active plan, say:
+"This is currently your active plan. Deleting it means you won't have a default plan.
+Want to proceed, or would you rather activate a different plan first?"
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "Your plan '[name]' has been deleted."
+
+2. **Active Plan Impact**: If the deleted plan was active, note that no plan is
+   currently active and offer to activate another.
+
+3. **Remaining Plans**: "You have [N] remaining plan(s). Want to see them?"
+
+## Common Follow-Up Patterns
+
+- User needs a new active plan → `list_plans` then `activate_plan`
+- User wants to create a replacement → `create_saved_plan`
+- User deleted by mistake → advise contacting support for recovery