pigeongov 0.2.0

package/AGENTS.md

@@ -0,0 +1,258 @@
+# AGENTS.md — pigeongov
+
+## What This Is
+
+`PigeonGov` is a local-first government workflow platform for the United States. 34 workflows across 13 domains — tax, immigration, healthcare, benefits, education, veterans, identity, legal, estate, retirement, unemployment, business, and permits. The engine is exposed through both a CLI (with `--json` structured output) and an MCP server so agents can call the same workflows programmatically.
+
+This repository targets the 2025 tax year for returns filed in 2026. Tax constants reflect the IRS filing values in force for 2025 returns.
+
+## Architecture
+
+```text
+CLI       -> human interaction, file I/O, terminal display
+MCP       -> agent interface, structured tool results (20 tools)
+Engine    -> pure tax math, validation, and mapping
+Advisory  -> life events, eligibility screener, decision support
+Schemas   -> versioned form definitions by tax year
+Workflows -> domain-specific workflow definitions and bundle builders
+```
+
+Rules:
+- The engine never does I/O.
+- The CLI and MCP layers handle all I/O.
+- Every output that can be reviewed by a human or agent includes `flaggedFields`.
+- No user data is logged.
+
+## MCP Tools (20)
+
+### Workflow tools
+| Tool | Description |
+|------|-------------|
+| `list-workflows` | List all workflows with optional domain filter |
+| `describe-workflow` | Get full workflow description with sections, fields, starter data, and schema |
+| `start-workflow` | Get starter data JSON for a workflow |
+| `fill-workflow` | Fill a workflow with data and return the complete bundle |
+| `validate-workflow` | Validate a filled workflow bundle |
+| `review-workflow` | Get a structured review summary with flagged fields |
+| `build-packet` | Build a complete packet from a filled bundle |
+| `explain-flag` | Explain a specific flagged field with suggested next steps |
+
+### Form tools (legacy)
+| Tool | Description |
+|------|-------------|
+| `list-forms` | List available form schemas by tax year |
+| `describe-form` | Describe a specific form schema |
+| `fill-form` | Fill a form with data |
+| `validate-form` | Validate a form |
+| `review-form` | Review a form |
+| `extract-document` | Extract structured data from a source PDF |
+| `calculate-tax` | Run the deterministic tax calculator |
+
+### Advisory tools
+| Tool | Description |
+|------|-------------|
+| `plan-life-event` | Get prioritized workflow plan for a life event |
+| `screen-eligibility` | Run eligibility screening for a benefits workflow |
+| `deadlines` | Get filing deadlines and key dates for a workflow |
+| `fees` | Get filing fees, processing times, and cost breakdowns |
+| `glossary` | Look up government terminology with official definitions |
+
+## CLI Commands for Agents
+
+All commands support `--json` for structured output.
+
+```bash
+# Core workflow operations
+pigeongov workflows list --json
+pigeongov workflows describe tax/1040 --json
+pigeongov fill tax/1040 --json --data ./input.json
+pigeongov validate ./bundle.json --json
+pigeongov review ./bundle.json --json
+pigeongov start tax/1040 --json
+
+# Advisory commands
+pigeongov life-event job-loss --json
+pigeongov screen benefits/snap --json --data ./household.json
+pigeongov deadlines tax/1040 --json
+pigeongov fees immigration/naturalization --json
+pigeongov glossary "adjusted gross income" --json
+
+# Utility commands
+pigeongov doctor --json
+pigeongov drafts list --json
+pigeongov testdata tax/1040 --json
+pigeongov merge bundle1.json bundle2.json --json
+```
+
+## Structured Output Contract
+
+Every `--json` response follows this shape:
+
+```json
+{
+  "success": true,
+  "workflowId": "tax/1040",
+  "data": { ... },
+  "validation": {
+    "valid": false,
+    "flaggedFields": [
+      {
+        "field": "wages",
+        "severity": "warning",
+        "message": "Wages are zero but filing status is not dependent."
+      }
+    ]
+  },
+  "review": {
+    "headline": "...",
+    "sections": [ ... ]
+  }
+}
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success. Bundle is valid. |
+| 1 | Validation errors. Bundle has flagged fields with `severity: "error"`. |
+| 2 | Input error. Missing or malformed input data. |
+| 3 | System error. Unexpected failure. |
+
+## Pipeline Composition
+
+Agents can compose workflows into multi-step pipelines:
+
+```bash
+# 1. Get starter data
+pigeongov start tax/1040 --json > starter.json
+
+# 2. Fill with data
+pigeongov fill tax/1040 --json --data starter.json > bundle.json
+
+# 3. Validate
+pigeongov validate bundle.json --json
+
+# 4. Review
+pigeongov review bundle.json --json
+
+# 5. Life event planning
+pigeongov life-event marriage --json
+
+# 6. Eligibility screening
+pigeongov screen benefits/snap --json --data household.json
+```
+
+MCP tools follow the same pipeline -- `start-workflow` -> `fill-workflow` -> `validate-workflow` -> `review-workflow` -> `build-packet`.
+
+## Current Scope — 34 Workflows
+
+### Tax (1)
+- `tax/1040` — Federal individual return (1040, Schedule 1, B, C, D, Form 8949)
+
+### Immigration (5)
+- `immigration/family-visa-intake` — Family visa packet
+- `immigration/naturalization` — N-400 eligibility
+- `immigration/green-card-renewal` — I-90 filing
+- `immigration/daca-renewal` — DACA renewal
+- `immigration/work-authorization` — I-765 EAD
+
+### Healthcare (2)
+- `healthcare/aca-enrollment` — ACA marketplace
+- `healthcare/medicare-enrollment` — Medicare with IRMAA
+
+### Benefits (6)
+- `benefits/snap` — SNAP eligibility
+- `benefits/section8` — Section 8 voucher
+- `benefits/wic` — WIC program
+- `benefits/liheap` — LIHEAP energy
+- `benefits/medicaid` — Medicaid eligibility
+- `benefits/ssdi-application` — SSDI intake
+
+### Education (3)
+- `education/fafsa` — FAFSA readiness
+- `education/student-loan-repayment` — IDR comparison
+- `education/529-planner` — 529 projections
+
+### Veterans (3)
+- `veterans/disability-claim` — VA disability
+- `veterans/gi-bill` — GI Bill estimation
+- `veterans/va-healthcare` — VA healthcare
+
+### Identity (4)
+- `identity/passport` — Passport application
+- `identity/name-change` — Name change
+- `identity/voter-registration` — Voter registration
+- `identity/real-id` — REAL ID readiness
+
+### Legal (3)
+- `legal/small-claims` — Small claims filing
+- `legal/expungement` — Expungement eligibility
+- `legal/child-support-modification` — Child support modification
+
+### Estate (3)
+- `estate/basic-will` — Will planner
+- `estate/power-of-attorney` — POA planner
+- `estate/advance-directive` — Advance directive
+
+### Retirement (1)
+- `retirement/ssa-estimator` — Social Security estimator
+
+### Unemployment (1)
+- `unemployment/claim-intake` — Unemployment claim
+
+### Business (1)
+- `business/license-starter` — Business license *(preview)*
+
+### Permits (1)
+- `permits/local-permit-planner` — Local permits *(preview)*
+
+## State Tax Coverage
+
+**Full calculators:** CA, NY, IL, PA, NC, MI, GA, VA, NJ, OH
+
+**No income tax:** AK, FL, NV, NH, SD, TN, TX, WA, WY
+
+## Coding Conventions
+
+- Use strict TypeScript.
+- Use Zod for schema boundaries.
+- Keep tax math deterministic and pure.
+- Prefer local file operations over network activity.
+- Mask SSNs in terminal prompts.
+- Display currency with `$` and commas.
+
+## 2025 Tax-Year Notes
+
+- Use the current IRS 2025 filing values, not older inflation-only estimates where later 2025 law changed the number.
+- Standard deduction, brackets, child tax credit, and self-employment tax rules should match the current IRS 2025 filing guidance.
+- If a value is ambiguous, prefer the current IRS filing page or form instructions over an older bulletin.
+
+## Adding a New Workflow
+
+1. Create a workflow definition in `src/workflows/domains/`.
+2. Define Zod input schema, starter data, sections, evidence logic, and validation/review rules.
+3. Register the domain in `src/workflows/registry.ts`.
+4. The shared bundle contract means CLI, TUI, site, and MCP inherit automatically.
+5. Add tests for registry behavior, CLI output, and MCP tool integration.
+
+## Adding a New Tax Year
+
+1. Create a new directory under `src/schemas/<year>/`.
+2. Add the form definitions for that year.
+3. Register the year in the schema index.
+4. Keep engine math pure so the same calculator can be validated independently.
+5. Add test fixtures for the new year before changing behavior.
+
+## Privacy Expectations
+
+- No telemetry.
+- No cloud uploads.
+- No hidden network calls with user data.
+- No PII in logs or error output.
+
+## Documentation Expectations
+
+- Keep README, PRIVACY, and AGENTS aligned with the actual product behavior.
+- Document any new forms, workflows, or tax-year changes when they land.
+- Prefer concise, practical explanations over marketing language.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pigeongov contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRIVACY.md

@@ -0,0 +1,38 @@
+# Privacy policy
+
+`PigeonGov` is designed to be local-first and privacy-preserving across the CLI, TUI, browser planner/reviewer, and MCP server.
+
+## What this means
+
+- Form and workflow data stays on your machine unless you explicitly choose to move the files yourself.
+- The CLI, TUI, local MCP server, and browser planner should not send application data to cloud services.
+- No telemetry should be collected.
+- No analytics should be embedded.
+- No user tax or application data should be written to logs.
+- Sensitive fields such as SSNs should be masked in terminal input.
+
+## File handling
+
+- Input PDFs, JSON files, generated outputs, and workflow bundles are read and written locally.
+- You control where files are stored.
+- The tool should not upload documents anywhere.
+
+## Browser planner and reviewer
+
+- The public website is a client-side planner and reviewer, not a hosted filing backend.
+- Uploaded bundle JSON in the reviewer is processed in the browser session for local inspection.
+- The planner generates local starter payloads and sample bundle downloads. It does not submit forms to agencies.
+
+## MCP behavior
+
+- The MCP server is an interface to the same local engine and workflow registry.
+- Agent requests should be processed without exfiltrating user data.
+- Any future network activity must be opt-in and must never include return or application contents by default.
+
+## Third-party libraries
+
+The project may rely on open-source libraries for CLI, PDF, schema, and MCP support. These libraries should be used locally and should not receive user form data unless a specific feature explicitly requires it and the user opts in.
+
+## What to do if privacy is at risk
+
+If any feature would require sending user data off-device, it should be treated as a separate, explicit opt-in workflow and documented clearly before use.

package/README.md

@@ -0,0 +1,234 @@
+# PigeonGov
+
+`PigeonGov` is a local-first government workflow platform for the United States. 34 workflows across 13 domains: tax, immigration, healthcare, benefits, education, veterans, identity, legal, estate, retirement, unemployment, business, and permits. Humans use it through the CLI and Bubble Tea TUI. Agents use the same workflows through MCP. The public Vercel root hosts a product site, workflow catalog, planner, and browser-side reviewer while preserving the MCP endpoint at `/mcp`.
+
+This project targets the 2025 federal tax year for returns filed in 2026, while the broader product design follows 2026-era agentic CLI and TUI conventions.
+
+## Install
+
+```bash
+npm install -g pigeongov
+```
+
+Or run it without installing:
+
+```bash
+npx pigeongov
+```
+
+To use the full-screen Go terminal UI from source, install Go 1.26+ and run:
+
+```bash
+pnpm build:tui
+```
+
+## Quick start
+
+```bash
+# List all 34 workflows
+$ npx pigeongov workflows list
+
+# Fill a federal tax return
+$ npx pigeongov fill tax/1040
+
+# Fill with JSON input/output
+$ npx pigeongov fill immigration/family-visa-intake --json --data ./visa-input.json
+
+# Life event action plan
+$ npx pigeongov life-event job-loss
+
+# Eligibility screening
+$ npx pigeongov screen benefits/snap
+
+# Check your environment
+$ npx pigeongov doctor --json
+```
+
+## Workflows
+
+### Tax (1)
+- `tax/1040` — Federal individual return (Schedule 1, B, C, D, Form 8949)
+
+### Immigration (5)
+- `immigration/family-visa-intake` — Family visa packet intake
+- `immigration/naturalization` — N-400 eligibility review
+- `immigration/green-card-renewal` — I-90 filing organizer
+- `immigration/daca-renewal` — DACA renewal eligibility
+- `immigration/work-authorization` — I-765 EAD application
+
+### Healthcare (2)
+- `healthcare/aca-enrollment` — ACA marketplace enrollment
+- `healthcare/medicare-enrollment` — Medicare with IRMAA calculation
+
+### Benefits (6)
+- `benefits/snap` — SNAP eligibility and benefit estimation
+- `benefits/section8` — Section 8 Housing Choice Voucher
+- `benefits/wic` — WIC program eligibility
+- `benefits/liheap` — LIHEAP energy assistance
+- `benefits/medicaid` — Medicaid eligibility (MAGI-based)
+- `benefits/ssdi-application` — SSDI application intake
+
+### Education (3)
+- `education/fafsa` — FAFSA readiness planner
+- `education/student-loan-repayment` — IDR comparison (SAVE, PAYE, IBR, ICR)
+- `education/529-planner` — 529 savings projections
+
+### Veterans (3)
+- `veterans/disability-claim` — VA disability with combined rating
+- `veterans/gi-bill` — Post-9/11 GI Bill estimation
+- `veterans/va-healthcare` — VA healthcare priority groups
+
+### Identity (4)
+- `identity/passport` — Passport application readiness
+- `identity/name-change` — Name change with cascading updates
+- `identity/voter-registration` — Voter registration guide
+- `identity/real-id` — REAL ID readiness checker
+
+### Legal (3)
+- `legal/small-claims` — Small claims court filing
+- `legal/expungement` — Criminal record expungement
+- `legal/child-support-modification` — Child support modification
+
+### Estate (3)
+- `estate/basic-will` — Basic will planner
+- `estate/power-of-attorney` — Power of attorney planner
+- `estate/advance-directive` — Advance directive planner
+
+### Retirement (1)
+- `retirement/ssa-estimator` — Social Security benefit estimator
+
+### Unemployment (1)
+- `unemployment/claim-intake` — Unemployment claim intake
+
+### Business (1)
+- `business/license-starter` — Business license planner *(preview)*
+
+### Permits (1)
+- `permits/local-permit-planner` — Local permit planner *(preview)*
+
+## State tax coverage
+
+**Full calculators:** CA, NY, IL, PA, NC, MI, GA, VA, NJ, OH
+
+**No income tax (returns $0):** AK, FL, NV, NH, SD, TN, TX, WA, WY
+
+## Decision support
+
+- **What-if scenarios** — Compare filing statuses, deduction strategies, income levels
+- **Audit risk scorer** — IRS DIF-inspired heuristics
+- **Missed deduction detector** — Profile-based deduction suggestions
+- **Contribution optimizer** — Optimal 401k, IRA, HSA strategy
+- **Multi-year carryforward** — Track carryforward items across tax years
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `workflows list` | List all workflows |
+| `workflows describe <id>` | Describe a workflow |
+| `fill <id>` | Interactive workflow fill |
+| `validate <file>` | Validate a bundle |
+| `review <file>` | Review summary |
+| `extract <pdf>` | Extract from source PDFs |
+| `serve` | Start MCP server |
+| `tui` | Launch Bubble Tea TUI |
+| `doctor` | Environment check |
+| `drafts` | Manage local drafts |
+| `vault` | Encrypted credential storage |
+| `profile` | Reusable identity profiles |
+| `deadlines` | Filing deadlines |
+| `fees` | Filing fees and costs |
+| `glossary` | Government terminology |
+| `life-event <id>` | Life event action plan |
+| `screen <id>` | Eligibility screening |
+| `merge` | Merge bundles |
+| `scaffold` | Generate workflow plugin |
+| `plugins` | Manage plugins |
+| `testdata` | Generate test data |
+| `schemas` | List form schemas |
+| `start` | Get starter data |
+
+All commands support `--json` for structured output and deterministic exit codes (0=success, 1=validation, 2=input, 3=system).
+
+## Agent integration
+
+```bash
+# Claude Code
+claude mcp add pigeongov -- npx pigeongov serve
+
+# Codex
+codex mcp add pigeongov -- npx pigeongov serve
+
+# Remote MCP endpoint
+https://pigeongov.vercel.app/mcp
+```
+
+Agent discovery files:
+- [`agents.json`](https://pigeongov.vercel.app/agents.json) — Structured capability manifest
+- [`llms.txt`](https://pigeongov.vercel.app/llms.txt) — Plain-text agent instructions
+
+See the [full docs](https://pigeongov.vercel.app/docs/) for MCP tool reference and structured output contracts.
+
+## Vercel deployment
+
+```bash
+vercel deploy -y --public
+```
+
+The live MCP endpoint: `https://pigeongov.vercel.app/mcp`
+
+The public site: `https://pigeongov.vercel.app/`
+
+For local HTTP testing:
+
+```bash
+npx pigeongov serve --http
+# Listens on http://127.0.0.1:3847/mcp
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+  WEB["Web: landing, docs, planner, reviewer"]
+  CLI["CLI: commander + @inquirer/prompts + chalk"]
+  TUI["TUI: Bubble Tea + Huh + Lip Gloss"]
+  MCP["MCP: xmcp tools"]
+  WORKFLOWS["Workflow registry + shared bundle model"]
+  ENGINE["Engine: tax math, validation, extraction, review"]
+  ADVISORY["Advisory: life events, screener, decision support"]
+
+  WEB --> WORKFLOWS
+  CLI --> WORKFLOWS
+  TUI --> CLI
+  MCP --> WORKFLOWS
+  WORKFLOWS --> ENGINE
+  WORKFLOWS --> ADVISORY
+```
+
+## Privacy
+
+- All processing happens locally on your machine.
+- No cloud account is required for the CLI, TUI, or local MCP server.
+- No telemetry is sent.
+- No user data is logged.
+- SSNs are masked in terminal prompts.
+- The browser planner and reviewer are client-side only — no server submission.
+
+Read the full policy in [`PRIVACY.md`](./PRIVACY.md).
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm build:mcp
+pnpm build:mcp:vercel
+vercel deploy -y --public
+```
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/agents.json

@@ -0,0 +1,72 @@
+{
+  "name": "pigeongov",
+  "version": "0.2.0",
+  "description": "Local-first, privacy-preserving government workflow platform for U.S. forms and applications",
+  "capabilities": ["cli", "mcp", "rest"],
+  "cli": {
+    "binary": "pigeongov",
+    "install": "npm install -g pigeongov",
+    "globalOptions": ["--json", "--jsonl", "--compact", "--full", "--fields", "--non-interactive", "--yes", "--dry-run", "--quiet", "--stdin", "--locale"],
+    "exitCodes": {
+      "0": "success",
+      "1": "runtime error",
+      "2": "has validation warnings",
+      "3": "has validation errors",
+      "4": "invalid input",
+      "5": "not found",
+      "6": "permission denied",
+      "7": "conflict",
+      "8": "schema error",
+      "9": "dependency missing",
+      "10": "timeout"
+    },
+    "commands": {
+      "list": { "description": "List available workflows", "args": "[--domain <domain>]" },
+      "fill": { "description": "Execute a workflow interactively or from JSON input", "args": "<workflow-id> [--input <file>]" },
+      "validate": { "description": "Validate a saved workflow bundle", "args": "<bundle-file>" },
+      "review": { "description": "Print human-readable review of a bundle", "args": "<bundle-file>" },
+      "extract": { "description": "Extract structured data from PDF documents", "args": "<pdf-file...>" },
+      "start": { "description": "Get starter data for a workflow", "args": "<workflow-id>" },
+      "schema": { "description": "Get JSON Schema for a workflow's input", "args": "<workflow-id>" },
+      "deadlines": { "description": "Show upcoming government deadlines", "args": "[--workflow <id>] [--ics <output>]" },
+      "fees": { "description": "Show filing fees for a workflow", "args": "[--workflow <id>]" },
+      "glossary": { "description": "Look up government terminology", "args": "[term] [--domain <domain>]" },
+      "screen": { "description": "Universal eligibility screener", "args": "" },
+      "life-event": { "description": "Get action plan for a life event", "args": "[event-name]" },
+      "drafts": { "description": "Manage saved workflow drafts", "args": "list|delete|cleanup" },
+      "vault": { "description": "Manage encrypted document vault", "args": "add|list|get|link" },
+      "profile": { "description": "Manage household profile", "args": "show|set|import" },
+      "merge": { "description": "Merge multiple PDFs with cover page", "args": "<files...> --output <path>" },
+      "serve": { "description": "Start MCP server", "args": "[--port <port>]" },
+      "doctor": { "description": "System diagnostics", "args": "" }
+    }
+  },
+  "mcp": {
+    "endpoint": "http://127.0.0.1:3847/mcp",
+    "transport": ["stdio", "streamable-http"],
+    "auth": ["api-key"],
+    "tools": [
+      "pigeongov_fill_workflow",
+      "pigeongov_validate_workflow",
+      "pigeongov_review_workflow",
+      "pigeongov_list_workflows",
+      "pigeongov_describe_workflow",
+      "pigeongov_extract_document",
+      "pigeongov_calculate_tax",
+      "pigeongov_explain_flag",
+      "pigeongov_list_deadlines",
+      "pigeongov_list_fees",
+      "pigeongov_lookup_term",
+      "pigeongov_screen_eligibility",
+      "pigeongov_plan_life_event",
+      "pigeongov_list_drafts",
+      "pigeongov_load_draft"
+    ]
+  },
+  "privacy": {
+    "localFirst": true,
+    "noTelemetry": true,
+    "noCloudUploads": true,
+    "noPiiInLogs": true
+  }
+}

package/dist/bin/pigeongov.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/pigeongov.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli/index.js";
+await runCli(process.argv);
+//# sourceMappingURL=pigeongov.js.map

package/dist/bin/pigeongov.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pigeongov.js","sourceRoot":"","sources":["../../bin/pigeongov.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/src/advisory/decision-support/contribution-optimizer.d.ts

@@ -0,0 +1,36 @@
+export interface ContributionScenario {
+    vehicleName: string;
+    currentContribution: number;
+    maxContribution: number;
+    additionalRoom: number;
+    taxSavingsPerDollar: number;
+    estimatedTaxSavings: number;
+    notes: string;
+}
+export interface ContributionOptimization {
+    marginalRate: number;
+    scenarios: ContributionScenario[];
+    totalPotentialSavings: number;
+    recommendation: string;
+}
+interface ContributionInput {
+    marginalRate: number;
+    age: number;
+    filingStatus: string;
+    agi: number;
+    has401k: boolean;
+    current401k: number;
+    hasIra: boolean;
+    currentIra: number;
+    iraType: "traditional" | "roth";
+    hasHsa: boolean;
+    currentHsa: number;
+    hsaCoverage: "individual" | "family";
+    hasEmployerPlan: boolean;
+}
+/**
+ * Analyze retirement contribution optimization opportunities.
+ * Shows how much more could be contributed and the estimated tax savings.
+ */
+export declare function optimizeContributions(input: ContributionInput): ContributionOptimization;
+export {};