macOS Desktop Installer (.dmg)

1. Download AIFamilyOffice-macOS-arm64.dmg from GitHub Releases.
2. Open the disk image and drag AI Family Office.app into your /Applications folder.
3. First Launch (Gatekeeper): If macOS displays an unverified developer prompt on first launch, right-click AI Family Office.app in /Applications and click Open, or run:

Windows Desktop Installer (.exe)

1. Download AIFamilyOffice-Windows-x64-Setup.exe from GitHub Releases.
2. Run the installer. It installs per-user into %LOCALAPPDATA%\Programs\AIFamilyOffice — no Administrator privileges required.
3. Windows SmartScreen: If SmartScreen appears on first launch, click More info → Run anyway.
4. Launch from your Desktop or Start Menu shortcut.

First-Run Vault PIN & Recovery Key

• On first launch, create a local PIN or Passphrase (4–128 characters). This wraps your household's 256-bit AES Family Encryption Key (FEK) using PBKDF2-HMAC-SHA256 (600,000 iterations).
• Important — Save Your Recovery Key: Once inside the dashboard, open Settings → Household & Access → Local Desktop Vault and click Copy Recovery Key. Store that 44-character key in your password manager so you can recover your vault if you ever forget your PIN.

Option A: SimpleFIN Bridge (Direct Bank Sync)

SimpleFIN connects directly to 12,000+ North American banks and brokerages via read-only tokens without sharing your banking passwords with this app:

1. Create a SimpleFIN Bridge account at beta-bridge.simplefin.org and link your financial institutions.
2. Generate a single-use Base64 Setup Token in SimpleFIN.
3. In AI Family Office, open Settings → Data Integrations & AI Key (or Step 2 of the Guided Setup Wizard), paste the Setup Token, and click Connect SimpleFIN.
4. The app exchanges your Setup Token once for an encrypted Access URL and syncs balances and holdings automatically.

Option B: Monarch Money Integration

If you already aggregate your household accounts in Monarch Money:

1. Open Settings → Data Integrations & AI Key.
2. Sign in with your Monarch email, password, and MFA code (or paste an existing Monarch session token).
3. Click Sync Now in the sidebar anytime to pull updated account balances, individual ticker holdings, and historical spending/cash-flow averages.

Option C: 100% Manual Entry & Account Roles

• Zero External Connections Needed: You can add accounts, holdings, equity grants, real estate, and forecast scenarios manually in the Accounts, Company Equity, and Forecasting tabs.
• Assigning Account Roles: In Settings → Account Roles, classify each account (Taxable Brokerage, Pre-Tax 401k/IRA, Roth IRA, 529 College, Primary Residence, HELOC/Debt, or Hidden) so the forecasting and tax engines apply the right tax treatment.

Which IRS Transcript to Download

1. Sign in to your individual account at irs.gov/individuals/get-transcript.
2. Download the Record of Account Transcript or Return Transcript PDF for each tax year (these contain your Adjusted Gross Income, Taxable Income, Total Tax, and Withholding lines).
3. Upload the PDFs in Compensation & Taxes → IRS Transcripts (or Step 3 of Guided Setup).

Form W-2 Upload & Safe Harbor

• Upload employer Form W-2 PDFs in Compensation & Taxes to extract Box 1 wages, Box 2 federal withholding, Box 12 retirement deferrals, Box 14 RSU/other items, and Box 16/17 state wages/tax.
• Zero Disk Persistence: Uploaded W-2 and IRS Transcript PDFs are parsed strictly in RAM and immediately discarded—raw PDF files are never saved to disk.
• Safe Harbor Penalty Protection: Compares your year-to-date withholding against the statutory 100% / 110% of Prior-Year Tax and 90% of Current-Year Tax thresholds.

Quarterly RSU Supplemental Withholding Gap

• Employers typically withhold federal tax on RSU vests at the flat statutory supplemental rate (22% up to the statutory threshold, 37% above) rather than your true marginal bracket.
• The Compensation & Taxes engine calculates your exact quarterly under-withholding gap across Q1–Q4 (Apr 15, Jun 15, Sep 15, Jan 15) so you can adjust W-4 Line 4(c) or make estimated payments.

How to Configure Your Free Gemini API Key

1. Visit Google AI Studio (aistudio.google.com/apikey) and sign in with your Google account.
2. Click Create API key and copy the key string (starts with AIza...).
3. In AI Family Office, open Settings → Data Integrations & AI Key, paste your key, and click Save Gemini Key.
4. Your key is encrypted with your household's AES-256 Fernet FEK and stored only inside your vault.

How Deterministic Tool-Calling Works

• When you ask a question (e.g., "Can we retire at age 52 if we relocate to Washington?" or "How much 1040-ES tax do we owe for Q3?"), the Advisor invokes verified Python tools (`get_tax_summary`, `compare_scenarios`, `get_rsu_vesting_schedule`, `get_estate_exposure`, `get_holdings_allocation`).
• All tax brackets, IRMAA surcharges, RMD tables, and Monte Carlo percentiles are computed by the deterministic Python/NumPy engines first, and Gemini synthesizes the verified numbers into a clear recommendation.

Where Your Vault Files Live on Disk

• macOS: ~/Library/Application Support/AIFamilyOffice/
• Windows: %LOCALAPPDATA%\AIFamilyOffice\
• Linux / Docker: ~/.local/share/AIFamilyOffice/ (or /app/data)
• Inside this folder: global.db (auth directory), families/1.db (your encrypted household database), .mm/.secret.key (44-char local root recovery key), and backups/.
• Click Open Data Folder in Settings anytime to reveal this folder in Finder or Windows Explorer.

Backing Up, Restoring & Moving Computers

• Export Backup: In Settings → Household & Access → Local Desktop Vault, click Backup (.fovault) to download a single-file encrypted snapshot of your household.
• Restore or Move to a New Computer: Install AI Family Office on the new machine, open Settings → Local Desktop Vault, and click Restore (.fovault). The app automatically saves a backups/pre_restore_*.fovault safety snapshot before restoring.

How App Updates Work

• Click Check for Updates in Settings to check GitHub Releases for a newer version.
• Download and install the new .dmg or .exe right over your existing app—your vault folder in Application Support / AppData is never overwritten by the installer.
• On first launch of the new version, the app automatically stops any older background daemon, creates a timestamped backups/pre_upgrade_vX_to_vY.fovault backup, and runs schema migrations in-place.

Changing or Recovering a Forgotten PIN

• While Logged In: Open Settings → Household & Access → Change PIN / Passphrase to set a new PIN anytime.
• If You Forget Your PIN on /login: To prevent walk-up browser users from bypassing your PIN, resetting a forgotten PIN requires proof of ownership:
  1. Click "Forgot PIN or Passphrase?" on /login and paste your 44-character Local Recovery Key (copied via Copy Recovery Key in Settings, or read from .mm/.secret.key inside your local vault folder), OR
  2. Click Sign in with Google on /login and update your PIN in Settings.

Mobile Phone Pairing over Home Wi-Fi

• In Settings → Local Desktop Vault, click Connect Phone (Wi-Fi Link) to generate a single-use, 10-minute cryptographic login URL (e.g., http://192.168.1.x:5050/api/desktop/qr-claim/...).
• Troubleshooting Wi-Fi Access: Ensure your phone and computer are on the same Wi-Fi subnet (or Tailscale VPN), and allow incoming local network connections for AI Family Office / Python on TCP port 5050 in macOS Firewall or Windows Defender Firewall.

Building the Desktop Installer from Source

After cloning or running git pull, you can compile your own native macOS .dmg or Windows .exe installer:

Outputs are written to dist/AIFamilyOffice-macOS-arm64.dmg (macOS) or dist/AIFamilyOffice-Windows-x64-Setup.exe (Windows with Inno Setup 6).

Forecasting & Parent/Child Scenario Trees

Simulates 50-year liquid net worth, cash flows, and retirement readiness (2026–2076). Create a Baseline Parent Plan and branch lightweight Child Plans (e.g., early retirement, state relocation, private vs. public college) that inherit parent accounts while isolating decision overrides. Includes a 1,000+ trial Monte Carlo engine with historical crisis replays (2008 GFC, 1970s stagflation, 2000 tech crash).

Company Equity (RSUs, ISOs, NSOs & Buybacks)

Models multi-tranche RSU vesting schedules, ISO/NSO option strike spreads, AMT preference adjustments (IRC § 56(b)(3)), and secondary tender cashless buybacks—deducting exercise costs and federal/state withholdings to compute net reinvestment proceeds.

Education & 529 Depletion Waterfall

Tracks K–12, undergraduate, and graduate tuition schedules per child. Applies a strict custodial drawdown waterfall that depletes each student's tax-free IRC § 529 account first before drawing remaining tuition from parent taxable brokerage cash flows, and evaluates SECURE 2.0 Act § 126 Roth IRA rollovers for unused funds.

Estate Taxes & Irrevocable Trusts

Computes federal estate tax exposure (including TCJA exemption sunset toggles) alongside state-specific estate tax brackets and cliff rules (WA, NY, MA, OR, etc.). Simulates transferring appreciating assets into SLATs, IDGTs (with IRC § 671 grantor tax burn), GRATs, and ILITs.

Multi-State Tax Arbitrage

Compares net take-home cash flow and 10-year compounding deltas across Washington, California, New York, Texas, and Florida across W-2 salary, RSU/option vesting, long-term capital gains (including WA RCW 82.87 excise tax), and portfolio yield.

Investments, Philanthropy & Form 709 Gifting

Audits portfolio asset allocation against target IPS presets (Three-Fund Boglehead, Endowment, Cash-Flow Barbelled), models Donor-Advised Fund (DAF) appreciated-stock bunching vs. standard deductions, and tracks annual IRC § 2503(b) gift exclusions per recipient.