WealthOS Guide

This guide explains every major system in WealthOS: what it is for, what you track, how to use it day to day, and — where it matters — how the product thinks under the hood. It is written for people using the product, not for developers integrating an API.

• Use the table of contents to jump to any module.
• Each section covers purpose, what you enter, and practical usage.
• “How it works” panels describe the engines behind goals, investments, forecasts, budgets, journey, and insights — in plain language.

1. 01

   Create your account

   Sign up with email or Google. Your session is authenticated; every query is scoped to your account.

2. 02

   Set preferences

   Choose currency, pay frequency, and display defaults in Settings so goals and budgets speak in your terms.

3. 03

   Add the basics

   Start with income and a few recurring expenses, then add cash, debts, and one goal. Completeness matters more than perfection on day one.

4. 04

   Check the dashboard

   Confirm net worth and cash flow look sane. Then deepen assets, investments, and forecasting when you are ready.

Net worth is recalculated from assets, investments, savings, and liabilities you track. The dashboard surfaces progress on goals, budget health, journey milestones, and quiet insights so you do not have to hunt across modules.

• Scan net worth and recent movement before diving into details.
• Use relevance cues and notifications to focus on what changed.
• Treat the dashboard as a cockpit — modules are where you edit the underlying picture.

Net worth

The sum of what you own (assets, investments, savings balances) minus what you owe (liabilities). Live, not a once-a-year spreadsheet.

Cash Flow brings income and expenses together. Log paychecks, side income, and spending so you know what is available to allocate toward budgets, savings, debt, and investments.

• Record income with frequency so monthly views stay accurate.
• Categorize expenses so budget health and insights can reason about them.
• Watch the gap between inflows and outflows — that surplus is decision fuel.

Budgets turn income into intentional allocations. Track spending against envelopes or categories for a period, and spot overspend before the month ends.

• Set a period allocation that matches how you get paid.
• Log expenses against the right buckets.
• Watch utilization: room left, on pace, or over.

Goals cover emergency funds, deposits, purchases, and other targets. You set how much you need, when you need it, and how much you have already saved. WealthOS tells you what to put aside each paycheck to stay on track.

• Create a goal with target amount, target date, and starting balance.
• Update current amount as contributions land.
• Watch completion percent, remaining amount, and required contribution.

Savings tracks liquid cushions and dedicated pools. Some savings feed goals; others are standing balances (emergency cash, sinking funds) you want visible in net worth without a hard deadline.

• Record balances so net worth stays honest.
• Link contributions to goals when a pool has a destination.
• Keep emergency cash separate from investment risk when that matches your plan.

Savings vs goals

Savings is where money sits. A goal is a destination and a pace. Many people use both: a savings balance that funds a goal over time.

Investments cover brokerage and similar portfolios: initial value, recurring contributions, expected return, compounding frequency, fees, and inflation assumptions for planning views.

• Enter what you already have invested and what you add regularly.
• Set a reasonable expected return and fee drag for projections.
• Compare nominal future value with inflation-adjusted purchasing power.

Assets include homes, vehicles, and other valuables you choose to track. Logging them with current values (and notes you care about) keeps net worth from understating your position.

• Add the asset with a current estimate of value.
• Update values when something material changes.
• Use detail views for history and context when you revisit a purchase.

Liabilities (debts & loans) subtract from net worth. Track balances, rates, and progress so payoff is measurable and insights can notice when pressure eases.

• Log each debt with current balance and key terms you care about.
• Update balances as you pay down principal.
• Pair debt payoff with cash flow and budgets so plans stay honest.

Forecasting projects net worth over a multi-year horizon using your current picture and planning assumptions. Use it to stress-test pace, not to pretend the future is certain.

• Review the mid path as a baseline story.
• Read low/high bands as uncertainty — not guarantees.
• Run what-if style thinking when you change contribution or debt payoff habits.

Journey turns decisions into a timeline: emergency fund halfway, first investment habit, debt reduced, net worth thresholds crossed. It is the story layer on top of the numbers.

• Review milestones as they appear from real progress.
• Capture memories when a moment mattered beyond the math.
• Use year-in-review style summaries when you want the chapter, not just the chart.

Insights surface timely cues from cash flow, goals, budgets, and liabilities: surplus to redirect, goal pace, debt pressure easing. The point is attention, not overwhelm.

• Check insights when the dashboard flags something new.
• Act on surplus by routing it to goals, debt, or investments.
• Treat insights as suggestions grounded in your data — not third-party advice.

Reports turn a stretch of time into something shareable with yourself: what moved, what finished, what is still in motion. Use them for reviews, archives, or a clean export when you want a durable record.

• Generate a period or annual summary when you want the chapter.
• Export when you need a copy outside the app.
• Pair reports with Journey for the story behind the totals.

People lets you associate income, expenses, or contributions with individuals in your household picture. It is for clarity and shared context — not a full multi-tenant household product.

• Add the people who matter to your money picture.
• Attribute entries when splitting context helps you understand the month.
• Keep the primary account owner’s privacy model in mind — your data stays under your account.

Settings hold preferences that ripple across goals, budgets, and formatting. Set them early so per-paycheck math and money displays match how you actually get paid and think about currency.

• Pick a primary currency for displays and demos of your own data.
• Set pay frequency so goal and budget pacing align with reality.
• Revisit preferences when your income rhythm changes.
• Use Connect AI agent to link Cursor or Claude after you are signed in — no uploading of project keys.

WealthOS is AI-native. Agents talk to your finances through the Model Context Protocol (MCP). Connection is simple: sign in to WealthOS, open Settings → Connect AI agent, create a token, and paste the generated config into Cursor or Claude Desktop.

• Sign in to WealthOS (same account as the web app).
• Go to Settings → Connect AI agent.
• Choose Full access or Read only, then Create connection token.
• Copy the token (shown once) or the ready-made Cursor / Claude config.
• If you already have an mcp.json, use Inject into existing and paste the wealthos block under mcpServers. Hosted MCP (Render) needs only the URL and token — no local project path.
• Ask the agent something like “What’s my net worth?” or “Dry-run allocate my paycheck.”
• Revoke a connection anytime from the same Settings card.

WealthOS uses encrypted authentication in transit, cloud storage with access controls, and row-level security so every query is scoped to your account. Other users do not see your balances, goals, or journey. AI connection tokens are stored as hashes only; the plaintext token is shown once when you create it.

• Private by default — your ledger is not a marketing feed.
• You own the data — export and leave when you want.
• Revoke AI connections from Settings if a device or agent is no longer trusted.
• Read the full Privacy Policy and Terms for legal detail.

Allocation

How much of a period’s income you intend for a budget category or envelope.

Compounding

Growth on growth — returns earning returns as contributions and interest accumulate over time.

Connection token

A personal access credential (wos_pat_…) that lets an AI agent act as you via MCP. Stored hashed; revoke from Settings.

Inflation-adjusted

A future dollar amount expressed in today’s purchasing power, after assuming a rate of inflation.

Liability

Money you owe — loans, credit balances, and other debts that reduce net worth.

MCP

Model Context Protocol — how AI agents call WealthOS capabilities (snapshot, missions, reports) under your account.

Milestone

A remembered moment of progress on your Financial Journey (for example, finishing an emergency fund).

Net worth

Assets + investments + savings − liabilities.

Pay frequency

How often you are paid (monthly, biweekly, etc.) — used to express required contributions per paycheck.

Utilization

How much of a budget allocation you have used in the period, usually as a percent.

What-if

A planning scenario that explores how changing contributions or debt payoff would bend a forecast — without immediately rewriting live balances.