@nestpilot/mcp-app 1.0.0

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

package/dist/skills/tools/delete_scenario.md

@@ -0,0 +1,38 @@
+# Tool Skill: delete_scenario
+
+Deletes a saved what-if scenario permanently. Unlike plan deletion (which is a soft delete),
+scenario deletion is immediate. The scenario will no longer appear in `list_scenarios` and
+cannot be used in future forecast runs.
+
+## When to Use
+
+Use `delete_scenario` when the user:
+- Says "Delete my [scenario name] scenario" or "Remove that scenario"
+- Wants to clean up old or irrelevant what-if explorations
+- Confirms deletion after being prompted
+
+**Always confirm before deleting.** Ask: "Are you sure you want to delete the '[label]'
+scenario? This cannot be undone."
+
+## Required Inputs to Gather
+
+- `scenarioId` (string, required) — UUID of the scenario to delete
+
+If the user refers to a scenario by label, resolve via `list_scenarios`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Confirmation**: "The scenario '[label]' has been deleted."
+
+2. **Impact Note**: "Any forecast runs that used this scenario are still saved, but you
+   won't be able to re-run the scenario."
+
+3. **Remaining Scenarios**: "You have [N] scenario(s) remaining. Want to see them?"
+
+## Common Follow-Up Patterns
+
+- User wants to see remaining scenarios → `list_scenarios`
+- User wants to create a replacement → `save_scenario`
+- User wants to clean up more → `list_scenarios` then `delete_scenario` again

package/dist/skills/tools/generate_proposal.md

@@ -0,0 +1,63 @@
+# Tool Skill: generate_proposal
+
+Assembles a client-ready advisor proposal by orchestrating the NestPilot plan summary
+and proposal record APIs. Produces a structured deliverable an advisor can share with
+(or release to) a client. **Advisor tier only** (FEAT-0063 entitlement gate).
+
+## When to Use
+
+Use `generate_proposal` when an **advisor** wants to:
+- Package analysis results into a formal client deliverable
+- Bundle forecast + optional Roth / SS analyses into one proposal document
+- Create a proposal record that can be released to a client
+- Generate a PDF summary alongside a structured proposal
+
+Do **not** use for ad-hoc analysis — use `run_forecast`, `optimize_roth_conversion`, or
+`run_scenario` first, then call this tool to assemble the proposal.
+
+## Required Inputs
+
+| Input | Description |
+|---|---|
+| `planId` | UUID of the plan to base the proposal on |
+| `clientUserId` | UUID of the client the proposal is for |
+| `title` | Proposal title shown to the client |
+
+## Optional Inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `subtitle` | — | Optional tagline |
+| `advisorNotes` | — | Custom notes appended to the proposal |
+| `includeScenarios` | `[]` | Scenario IDs to include in comparison |
+| `includeRothAnalysis` | `false` | Annotate that Roth analysis was performed |
+| `includeSsAnalysis` | `false` | Annotate that SS analysis was performed |
+| `unlockPriceCents` | `0` | Client unlock price (0 = free) |
+| `autoRelease` | `false` | Release to client immediately |
+
+## Workflow
+
+1. **Gather context**: Advisor has reviewed the plan, run scenarios, and is ready to share.
+2. **Confirm release preference**: Ask the advisor whether to release immediately or keep as draft.
+3. **Call the tool** with gathered inputs.
+4. **Present result**: Show `proposalId`, `status` (draft / released), `summaryUrl`, and `evidencePacket`.
+
+## Safety Gates
+
+- Proposal is **NOT released** unless `autoRelease: true` is explicitly provided.
+- If `autoRelease` is true, prompt the advisor to confirm before proceeding.
+- Compliance disclaimers are automatically included in the evidence packet.
+
+## Presenting Results
+
+Structure the response in three parts:
+1. **Status**: `proposalId`, `status` (draft/released), whether summary PDF was generated.
+2. **Evidence packet**: What analyses were included, assumptions, disclaimers, `generatedAt`.
+3. **Next steps**: If draft, how to release. If released, client can view it in their portal.
+
+## Error Handling
+
+- If summary generation fails: report the error; no proposal record is created.
+- If proposal creation fails: report the error; advise the advisor to retry.
+- If release fails after creation: proposal is saved as draft; advise manual release from the
+  Proposal Manager UI (`/advisor/proposals`).

package/dist/skills/tools/generate_retirement_report.md

@@ -0,0 +1,50 @@
+# Tool Skill: generate_retirement_report
+
+Generates a comprehensive retirement planning PDF report. Loads a saved plan, runs a forecast,
+optionally includes saved scenarios, and produces a professional PDF with plan details, charts,
+year-by-year projections, and recommendations.
+
+## When to Use
+
+Use `generate_retirement_report` when the user wants to:
+- Create a PDF document summarizing their retirement plan and forecast
+- Generate a shareable/printable retirement analysis
+- Export their plan details, projections, and charts to a document
+- Produce a retirement readiness report in PDF format
+
+## How It Works
+
+The tool orchestrates several steps internally:
+1. Resolves the plan ID (supports "active", "default", "current" aliases)
+2. Loads the full plan via `GET /api/plans/{planId}`
+3. Runs a forecast using the plan data
+4. Optionally loads saved scenarios for comparison
+5. Invokes the Python PDF generator (`generate_report.py`) with all data
+6. Returns the PDF file path and metadata
+
+## Presenting Results
+
+After the tool returns successfully:
+1. **Confirm generation**: "Your retirement report has been generated at [path]."
+2. **Summarize contents**: Mention what sections are included (plan details, forecast KPIs,
+   charts, scenario comparison if applicable).
+3. **Offer next steps**: Suggest opening the PDF, running additional scenarios, or using
+   the interactive planner for real-time exploration.
+
+## Input Tips
+
+- **planId**: Omit or pass "active" to use the user's active plan. Pass a UUID for a specific plan.
+- **clientName**: Optional personalization for the report header (e.g., "John & Jane Doe").
+- **includeScenarios**: Defaults to true. Set to false to skip the scenario comparison section.
+- **outputPath**: Optional custom path. If omitted, generates in a temp directory.
+
+## Error Handling
+
+- If no plan is found, prompt the user to create or activate a plan first.
+- If the forecast fails, report the backend error and suggest checking plan inputs.
+- If Python/reportlab is not available, report the dependency requirement.
+
+## Prerequisites
+
+- Requires Python 3 with `reportlab` installed (`pip install reportlab`).
+- Requires a saved plan in the system.

package/dist/skills/tools/get_active_plan.md

@@ -0,0 +1,44 @@
+# Tool Skill: get_active_plan
+
+Retrieves the user's currently active (default) retirement plan. Returns the full PlanContract
+just like `get_plan`, but without requiring a plan ID.
+
+## When to Use
+
+Use `get_active_plan` when the user:
+- Says "my plan" or "my current plan" without naming a specific one
+- Asks "What does my plan look like?" or "Show me my retirement plan"
+- Starts a conversation wanting to run a forecast but hasn't specified which plan
+- Asks about their current retirement readiness without further context
+
+Use `get_plan` instead when the user references a specific plan by name or ID.
+Use `list_plans` when the user wants to see all their plans.
+
+## Required Inputs to Gather
+
+No inputs required. The API resolves the active plan from the authenticated user's profile.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Plan Identity**: "Your active plan is '[name]', last updated [date]."
+
+2. **Quick Snapshot**:
+   - Retirement age: X
+   - Total account balances: $X across N accounts
+   - Target monthly spending: $X
+   - Readiness score (if cached from last forecast): X/100
+
+3. **Offer Next Steps**: "Would you like me to run a fresh forecast, explore a what-if
+   scenario, or update any of these assumptions?"
+
+If no active plan exists, say: "You don't have an active plan set. Would you like to
+create one, or pick from your existing plans?"
+
+## Common Follow-Up Patterns
+
+- User wants a forecast → `run_saved_forecast` using the returned `planId`
+- User wants to change assumptions → `save_plan` with updated fields
+- User wants a different plan as default → `list_plans` then `activate_plan`
+- User wants a combined analysis → `comprehensive_plan`

package/dist/skills/tools/get_baseline_forecast.md

@@ -0,0 +1,47 @@
+# Tool Skill: get_baseline_forecast
+
+Retrieves the most recent baseline forecast results for a saved plan. Returns cached metrics
+and yearly projections without re-running the forecast engine.
+
+## When to Use
+
+Use `get_baseline_forecast` when the user:
+- Asks "What were my last forecast results?" or "Show me my numbers"
+- Needs baseline metrics for comparison without waiting for a fresh run
+- Wants to reference previous projections during a conversation
+- Asks about readiness score, legacy value, or runway from their last forecast
+
+Use `run_saved_forecast` instead when the user wants fresh projections, especially after
+making plan changes. Stale results may not reflect recent edits.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the saved plan
+
+If the user doesn't specify, resolve via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Freshness Note**: "These results are from your last forecast run on [date].
+   Your plan [has / has not] changed since then."
+
+2. **Key Metrics**:
+   - Readiness score: X/100
+   - Portfolio runway: X years
+   - Legacy value at [horizon age]: $X
+   - Peak portfolio value: $X at age X
+
+3. **Year-by-Year Highlights**: Summarize key inflection points — when contributions
+   stop, when withdrawals begin, when portfolio peaks, and when it depletes (if ever).
+
+4. **Staleness Warning** (if plan was modified after the forecast):
+   "Your plan has been updated since this forecast. Want me to run a fresh one?"
+
+## Common Follow-Up Patterns
+
+- Results look stale → `run_saved_forecast` with `runType: "baseline"`
+- User wants to compare with a scenario → `run_saved_forecast` with `runType: "scenario"`
+- User wants to drill into components → `get_plan_components`
+- User wants charts → `retirement-planner` with the `planId`

package/dist/skills/tools/get_plan.md

@@ -0,0 +1,44 @@
+# Tool Skill: get_plan
+
+Retrieves a single saved retirement plan by its unique ID. Returns the full PlanContract
+including household data, accounts, income streams, goals, and metadata.
+
+## When to Use
+
+Use `get_plan` when the user:
+- Refers to a specific plan by name or ID and you need the full details
+- Wants to review or edit a plan before running a forecast
+- Needs to inspect plan components, assumptions, or configuration
+- Asks "Show me my [plan name] plan" after you have resolved the ID via `list_plans`
+
+Use `get_active_plan` instead when the user simply says "my plan" without specifying which one.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — the UUID of the saved plan
+
+If the user refers to a plan by name, first call `list_plans` to resolve the name to a `planId`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Plan Summary**: "Here is your '[name]' plan, last updated [date]."
+
+2. **Household**: Primary age, retirement age, life expectancy. Spouse if present.
+
+3. **Accounts**: List each account with type, balance, and annual contribution.
+
+4. **Income Streams**: List each stream with type, monthly amount, and start/end ages.
+
+5. **Goals**: Target monthly spending, withdrawal strategy, safe withdrawal rate.
+
+6. **Offer Next Steps**: "Want me to run a forecast on this plan, tweak any assumptions,
+   or compare it with a scenario?"
+
+## Common Follow-Up Patterns
+
+- User wants projections → `run_saved_forecast` with the `planId`
+- User wants to change something → `save_plan` with updated fields
+- User wants to make it the default → `activate_plan`
+- User wants to see attached components → `get_plan_components`

package/dist/skills/tools/get_plan_components.md

@@ -0,0 +1,50 @@
+# Tool Skill: get_plan_components
+
+Returns the financial components attached to a saved plan — accounts, income streams,
+expenses, and insurance policies. Each component includes its type, configuration, and
+link back to the parent plan.
+
+## When to Use
+
+Use `get_plan_components` when the user:
+- Asks "What accounts are in my plan?" or "Show me my income streams"
+- Wants a detailed breakdown of plan building blocks without the full PlanContract
+- Needs to verify which components exist before adding or removing one
+- Asks about a specific component type (e.g., "Do I have a Roth in this plan?")
+
+Use `get_plan` instead if you need the full plan including household, goals, and metadata.
+
+## Required Inputs to Gather
+
+- `planId` (string, required) — UUID of the plan
+
+If the user doesn't specify, resolve from the active plan via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response by component type:
+
+1. **Accounts**:
+   - Type | Balance | Annual Contribution | Return Rate
+   - e.g., "Traditional 401(k): $320,000, contributing $22,500/yr at 6% real return"
+
+2. **Income Streams**:
+   - Type | Monthly Amount | Start Age | End Age
+   - e.g., "Social Security: $2,800/mo starting at age 67"
+
+3. **Expenses** (if present):
+   - Label | Monthly Amount | Start Age | End Age
+   - e.g., "Healthcare: $800/mo from age 65 to 95"
+
+4. **Insurance** (if present):
+   - Type | Coverage | Premium
+
+5. **Offer Next Steps**: "Want to add a new account, adjust an income stream, or
+   run a forecast with these components?"
+
+## Common Follow-Up Patterns
+
+- User wants to add a component → `save_plan` with the new component appended
+- User wants to remove one → `save_plan` with the component removed
+- User wants to run numbers → `run_saved_forecast`
+- User wants to see the full plan → `get_plan`

package/dist/skills/tools/get_scenario.md

@@ -0,0 +1,46 @@
+# Tool Skill: get_scenario
+
+Retrieves a single saved what-if scenario by ID. Returns the full scenario definition
+including label, deltas, overrides, bundle, linked plan, and metadata.
+
+## When to Use
+
+Use `get_scenario` when the user:
+- Wants to review what a saved scenario contains before running it
+- Asks "What's in my [scenario name] scenario?"
+- Needs to verify scenario details before applying it to a different plan
+- Refers to a scenario by name and you need the full definition
+
+Use `list_scenarios` first if you need to resolve a name to an ID.
+
+## Required Inputs to Gather
+
+- `scenarioId` (string, required) — UUID of the scenario
+
+If the user refers to a scenario by label, call `list_scenarios` to resolve the ID.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Scenario Identity**: "Scenario '[label]', created [date]."
+
+2. **Changes Defined**:
+   - **Deltas**: List each change in plain language:
+     "Retirement age changed to 60" / "Target spending increased to $7,000/mo"
+   - **Overrides**: List toggled components:
+     "Pension income: disabled" / "Rental income: enabled"
+   - **Stress Test**: Historical scenario if present:
+     "Applies 2008 financial crisis to equity returns"
+   - **Bundle**: Named preset if used
+
+3. **Linked Plan**: "Associated with plan '[name]'" or "Standalone (can apply to any plan)."
+
+4. **Next Step**: "Want me to run a forecast with this scenario, or modify it?"
+
+## Common Follow-Up Patterns
+
+- User wants to run it → `run_saved_forecast` with `runType: "scenario"` and the `scenarioId`
+- User wants to change it → `save_scenario` with updated fields or delete and recreate
+- User wants to delete it → `delete_scenario`
+- User wants to apply it to a different plan → `run_saved_forecast` with a different `planId`

package/dist/skills/tools/list_plans.md

@@ -0,0 +1,44 @@
+# Tool Skill: list_plans
+
+Returns all saved retirement plans belonging to the authenticated user. Each entry includes the
+plan ID, name, creation date, last-modified date, and whether it is the active plan.
+
+## When to Use
+
+Use `list_plans` when the user:
+- Asks "What plans do I have?" or "Show me my saved plans"
+- Wants to pick a plan before running a forecast or scenario
+- Needs to compare or manage multiple plans (e.g., "conservative" vs. "aggressive")
+- Refers to a plan by name and you need to resolve the plan ID
+
+Do NOT call this if the user already provided a specific `planId` — go straight to `get_plan`.
+
+## Required Inputs to Gather
+
+No inputs required. The API identifies the user from the auth token.
+
+Optional query hints the user might provide:
+- A name fragment to filter on (client-side filtering after retrieval)
+- Whether they only want the active plan — prefer `get_active_plan` in that case
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Count**: "You have [N] saved plan(s)."
+
+2. **Plan List** (table or bullet list):
+   - Name | Created | Last Modified | Active?
+   - Highlight the currently active plan with a label like "(active)".
+
+3. **Prompt for Action**: "Which plan would you like to work with? I can open it,
+   run a forecast, or compare scenarios."
+
+If the list is empty, say: "You don't have any saved plans yet. Would you like to create one?"
+
+## Common Follow-Up Patterns
+
+- User picks a plan by name → resolve to `planId`, then `get_plan`
+- User wants to create a new plan → `create_saved_plan`
+- User asks which plan is active → `get_active_plan`
+- User wants to delete or rename → `delete_plan` / `rename_plan`

package/dist/skills/tools/list_scenarios.md

@@ -0,0 +1,42 @@
+# Tool Skill: list_scenarios
+
+Returns all saved what-if scenarios for the authenticated user, optionally filtered to a
+specific plan. Each entry includes the scenario ID, label, associated plan (if any),
+and creation date.
+
+## When to Use
+
+Use `list_scenarios` when the user:
+- Asks "What scenarios do I have?" or "Show me my saved what-ifs"
+- Wants to pick a scenario before running a forecast
+- Needs to compare or manage their scenario library
+- Asks "What scenarios are attached to this plan?"
+
+## Required Inputs to Gather
+
+- `planId` (string, optional) — if provided, returns only scenarios linked to that plan;
+  if omitted, returns all scenarios across all plans plus standalone ones
+
+If the user says "scenarios for my plan" without specifying which, resolve via `get_active_plan`.
+
+## Presenting the Results
+
+Structure the response:
+
+1. **Count**: "You have [N] saved scenario(s) [for plan '[name]' / total]."
+
+2. **Scenario List** (table or bullets):
+   - Label | Linked Plan | Created | Key Changes
+   - Summarize the deltas briefly, e.g., "Retire at 60, no pension"
+
+3. **Prompt for Action**: "Which scenario would you like to run, view, or delete?"
+
+If no scenarios exist: "You don't have any saved scenarios yet. Would you like to
+create one? Tell me what change you'd like to explore."
+
+## Common Follow-Up Patterns
+
+- User picks a scenario → `get_scenario` for details, or `run_saved_forecast` to execute
+- User wants to create a new one → `save_scenario`
+- User wants to delete one → `delete_scenario`
+- User wants to compare two → run `run_saved_forecast` for each and compare results