Your First Flight: Understanding Civitas and Running Your First Simulation

Introduction: What is Civitas?

Civitas is a macroeconomic flight simulator built for citizens, policymakers, and researchers who want to understand how federal policy impacts real households. Unlike traditional economic models locked away in government agencies or academic institutions, Civitas puts the power of policy simulation directly in your hands.

Built on .NET MAUI with a sophisticated multi-tier architecture, Civitas runs as a cross-platform desktop application (Windows, macOS, iOS, Android) and features:

• ~30 policy levers spanning fiscal, monetary, trade, immigration, and AI labor displacement
• Monthly-step projections over 120 months (10 years)
• Persona-based modeling representing different wealth quintiles and life stages
• Historical bill library with 15+ actual US legislation pieces (TCJA, CARES Act, ACA, etc.)
• AI-assisted analysis via streaming chat with Claude, OpenAI, or Gemini
• Hazard modeling for climate events, pandemics, war, and opioid crisis impacts

At its core, Civitas answers a simple question: What happens to Maya (bottom quintile, single mother) versus Charles (top 0.1%, retiree) when we change tax policy, implement UBI, or impose tariffs?

Whether you're a policy wonk, a concerned citizen, or a student learning economics, Civitas makes macroeconomic modeling accessible, transparent, and actionable.

Understanding the Flight Simulator Metaphor

Why call it a "flight simulator"? The metaphor is deliberate and powerful.

Just as pilots train in simulators before taking the controls of a real aircraft, policymakers and citizens can now test federal policies before they impact real households. You can:

• Test hypotheses → What if we doubled the child tax credit?
• Compare alternatives → UBI vs. expanded EITC—which helps Maya more?
• Learn from history → How did the 2017 Tax Cuts and Jobs Act (TCJA) play out versus CBO expectations?
• Explore extremes → What happens if we impose 60% tariffs on all imports?

The Cockpit Analogy

In a flight simulator, you have:

• Controls (throttle, yaw, pitch) → In Civitas, these are policy levers (tax rates, spending, tariffs)
• Instruments (altimeter, airspeed, fuel gauge) → In Civitas, these are KPIs (GDP, inflation, deficit)
• Scenarios (crosswind landing, engine failure) → In Civitas, these are policy scenarios (recession response, climate adaptation)
• Passengers → In Civitas, these are personas (Maya, Jamal, Aisha, Charles)

The key insight: You can crash the economy in Civitas without harming a single real person. You can test radical policies, learn from failure, and iterate toward better outcomes.

Why This Matters

Policy debates often devolve into ideology or soundbites. Civitas offers a third way: evidence-based experimentation. Instead of arguing whether a policy will "help the middle class," you can run the simulation and see the projected impact on Jamal (Q3, mid-career) over 10 years.

The flight simulator metaphor reminds us: training matters, practice matters, and simulation prevents catastrophe.

Navigating the Dashboard

The Dashboard is your cockpit—a control center where you select scenarios, choose comparison groups, and watch 120 months of economic projections unfold. Let's walk through the interface.

The Main Components

When you open Civitas, the DashboardViewModel drives the main screen. It features:

1. Scenario Selectors (left panel)

   • Baseline Scenario: The reference case (e.g., "Current Policy")
   • Counterfactual Scenario: The policy you're testing (e.g., "Universal Basic Income")
   • Scenarios can be presets (built-in) or saved bills you've designed

2. Comparison Group Picker (top bar)

   • Quintile Representatives: Maya (Q1), Jamal (Q3), Charles (Top 0.1%)
   • Life Stage Archetypes: Young professional, mid-career parent, retiree
   • Hazard Archetypes: Climate-vulnerable, pandemic-exposed, war-impacted
   • Custom Groups: Your own persona sets

3. KPI Tiles (center top)

   • GDP Growth, Inflation, Deficit, Unemployment
   • Color-coded deltas (green = improvement, red = deterioration)

4. Persona Impact Chart (center)

   • Pie chart showing relative wealth impact across selected personas
   • Click a slice to isolate that persona's trajectory

5. Timeline Scrubber (bottom)

   • Drag to any month (0–120) to see point-in-time outcomes
   • Play button auto-advances through the projection

6. Right Panel Tabs

   • Details: Numerical breakdown of selected persona's outcomes
   • Ask AI: Streaming chat to explain results, suggest follow-ups

Navigation Tips

• Start simple: Compare "Current Policy" (baseline) to a single preset like "Universal Basic Income"
• Use quintile groups first: See how Maya (Q1) vs. Charles (Top 0.1%) fare
• Scrub the timeline: Don't just look at month 120—watch how outcomes evolve
• Ask AI: Click "Ask AI" and type "Why does Maya's wealth drop in year 3?" for context-aware explanations

The Dashboard is designed for exploration. There's no "wrong" way to use it—click around, try different scenarios, and build intuition.

Running Your First Preset Scenario

Let's run your first simulation. We'll compare Current Policy (baseline) to Universal Basic Income (counterfactual) and see how it impacts quintile representatives.

Step-by-Step Guide

1. Launch Civitas

Open the app. You'll land on the Dashboard.

2. Select Baseline Scenario

• In the left panel, find the Baseline Scenario dropdown
• Select "Current Policy" (this represents the status quo with no major changes)

3. Select Counterfactual Scenario

• In the Counterfactual Scenario dropdown, select "Universal Basic Income"
• This preset typically includes:
  • $1,000/month per adult
  • Funded by a combination of VAT and wealth tax
  • Phases in over 12 months

4. Choose Comparison Group

• In the top bar, select "Quintile Representatives"
• This will show outcomes for:
  • Maya (Q1, bottom 20%, single mother, $28K income)
  • Jamal (Q3, middle 60%, mid-career, $65K income)
  • Aisha (Q4, upper-middle, $120K income)
  • Charles (Top 0.1%, retiree, $18M wealth)

5. Run the Simulation

• The simulation runs automatically when you change scenarios
• You'll see a loading indicator, then results populate

6. Observe the Results

The Dashboard updates with:

KPI Tiles (example output):

• GDP Growth: +0.8% (green) → UBI boosts consumption
• Inflation: +1.2% (yellow) → Demand surge
• Deficit: +$1.2T (red) → Funding gap
• Unemployment: -0.3% (green) → Labor force participation increases

Persona Impact Chart (pie chart):

• Maya: +$45K wealth (10-year cumulative, largest slice)
• Jamal: +$22K wealth
• Aisha: +$8K wealth
• Charles: -$120K wealth (negative slice, wealth tax impact)

Trajectory Lines (if you scroll down):

• Maya's wealth climbs steadily from month 1
• Charles's wealth dips slightly but remains in the millions

What Just Happened?

Under the hood, Civitas:

1. Loaded policy events for "Universal Basic Income" from Fed.Core.Scenarios
2. Merged provisions into composite EconomyLevers (tax rates, transfers, spending)
3. Ran 120-month projections for each persona in the quintile group
4. Calculated deltas between baseline and counterfactual
5. Classified distributional impact (progressive, since Maya gains more than Charles)

Try These Next

Now that you've run one scenario, experiment with:

• "Medicare for All" → How does single-payer healthcare shift outcomes?
• "60% Tariffs" → Extreme trade protectionism
• "AI Labor Displacement (High)" → 30% job automation over 10 years
• "Green New Deal" → Climate investment + jobs guarantee

Each preset is carefully designed to represent a coherent policy package. You can also clone and modify presets in the BillBuilder (we'll cover that in future guides).

Reading the Results: KPIs and Persona Impacts

You've run a simulation—now what do the numbers mean? Let's decode the results.

Understanding KPI Tiles

The KPI tiles at the top of the Dashboard show macroeconomic aggregates. Here's how to interpret them:

GDP Growth

• What it measures: Real GDP growth rate (annualized, inflation-adjusted)
• Green (+): Policy boosts economic output (demand stimulus, productivity gains)
• Red (-): Policy contracts the economy (austerity, trade barriers)
• Example: UBI shows +0.8% because cash transfers boost consumption

Inflation

• What it measures: Change in consumer price index (CPI) growth rate
• Green (-): Policy reduces inflation (supply-side reforms, demand cooling)
• Red (+): Policy increases inflation (demand surge, supply shocks)
• Example: UBI shows +1.2% because $1,000/month increases aggregate demand

Deficit

• What it measures: Federal budget deficit (positive = deficit, negative = surplus)
• Green (-): Policy reduces deficit (revenue increases, spending cuts)
• Red (+): Policy increases deficit (spending increases, tax cuts)
• Example: UBI shows +$1.2T because transfers exceed new tax revenue

Unemployment

• What it measures: Unemployment rate (% of labor force)
• Green (-): Policy reduces unemployment (job creation, labor demand)
• Red (+): Policy increases unemployment (recession, automation)
• Example: UBI shows -0.3% because some recipients start businesses or retrain

Understanding Persona Impacts

The persona impact chart (pie chart) shows relative wealth changes across selected personas. But raw percentages can mislead—this is where Civitas's Lived Impact Classifier shines.

The "Ending Wealth Tier" Principle

Civitas frames outcomes by ending wealth tier, not just percentage change, because a 90% loss on $18M still leaves someone wealthy—context matters.

Consider two scenarios:

Scenario A: Wealth Tax

• Maya (Q1): Wealth increases from $5K → $50K (+900%)
• Charles (Top 0.1%): Wealth decreases from $18M → $1.8M (-90%)

Naive interpretation: "Charles lost 90%, Maya gained 900%—huge redistribution!"

Lived reality:

• Maya moved from precarious to stable (life-changing)
• Charles moved from ultra-wealthy to still very wealthy (lifestyle barely affected)

The LivedImpactClassifier (referenced in codebase context) categorizes outcomes by ending tier:

• Precarious (< $10K): Vulnerable to shocks
• Stable ($10K–$100K): Emergency fund, minor resilience
• Comfortable ($100K–$1M): Retirement security
• Wealthy ($1M–$10M): Financial independence
• Ultra-Wealthy (> $10M): Generational wealth

This prevents misleading narratives and focuses on material impact.

Reading the Pie Chart

Each slice represents a persona's cumulative wealth change over 120 months:

• Slice size: Proportional to absolute dollar change (not percentage)
• Color: Persona-specific (Maya = blue, Jamal = green, etc.)
• Tooltip: Hover to see exact numbers

Example (UBI scenario):

• Maya: +$45K (largest slice, even though Charles has more wealth)
• Jamal: +$22K
• Aisha: +$8K
• Charles: -$120K (negative slice, but still ends at $17.88M)

Distributional Verdict: Progressive (bottom quintile gains most in absolute terms relative to baseline wealth).

Trajectory Lines

Scroll down to see wealth trajectories over 120 months. These line charts show:

• X-axis: Months (0–120)
• Y-axis: Wealth (log scale to show all personas on one chart)
• Lines: One per persona, color-coded
• Shaded area: Baseline (reference) vs. counterfactual (policy scenario)

Look for:

• Divergence points: When do outcomes start to differ?
• Crossovers: Does a persona overtake another?
• Volatility: Are there boom-bust cycles?

Ask AI for Context

If any result surprises you, click "Ask AI" in the right panel:

Example prompts:

• "Why does Maya's wealth drop in year 3?"
• "How does inflation affect Jamal differently than Aisha?"
• "What's driving the deficit increase?"

The AI can suggest follow-up questions (via suggest_followups tool) like:

• "Compare this to the 2017 Tax Cuts and Jobs Act"
• "What if we doubled the UBI amount?"
• "Show me climate-vulnerable personas"

Red Flags to Watch For

• Extreme inflation (> 5%/year): Policy may be overheating the economy
• Runaway deficit (> $2T/year sustained): Fiscal sustainability concerns
• Regressive outcomes: Top 0.1% gains while Q1 loses
• Volatility: Wild swings in KPIs suggest model instability or extreme policy shocks

Civitas is a tool for learning, not a crystal ball. Treat results as plausible projections informed by historical data, not prophecy.

Next Steps

Congratulations—you've run your first Civitas simulation! Here's how to deepen your skills and explore advanced features.

1. Explore the Historical Bill Library

Navigate to Bills (left sidebar) to browse 15+ actual US legislation pieces:

• Tax Cuts and Jobs Act (2017): Compare CBO-scored expectations vs. Civitas projections
• CARES Act (2020): Pandemic relief—how did it stabilize the economy?
• Affordable Care Act (2010): Healthcare reform impacts on personas
• Omnibus Budget Bill (OBBBA 2025): Recent legislation

Each bill includes:

• Expected outcomes (CBO scores for deficit, inflation)
• Validation markers (✓ / ≈ / ✗) comparing modeled vs. expected
• AI chat to explain provisions and historical context

Try this: Load the TCJA, run it against "Current Policy," and ask the AI: "Did the tax cuts pay for themselves?"

2. Design Your Own Bill

Click BillBuilder to compose custom legislation:

1. Add provisions: Choose from 100+ builtin policy events (tax reforms, spending programs, trade policies)
2. Set parameters: Adjust amounts, phase-in schedules, sunset dates
3. Preview impact: See lever changes before running the full simulation
4. Save and share: Export as JSON or embed in a URL (no backend required!)

Send the URL to a colleague, and they can decode and run the same scenario.

3. Create Custom Personas

Navigate to Personas to model yourself or specific households:

1. Clone a template: Start with Maya, Jamal, or another archetype
2. Edit attributes: Income, wealth, age, household size, geographic exposure
3. Set hazard weights: Climate vulnerability, pandemic exposure, war impact
4. Save and group: Create custom comparison sets (e.g., "My Family" vs. "National Average")

Personas are stored in Fed.Core.Persistence (SQLite) and sync across all app hosts (Desktop, API, MCP).

4. Dive into Hazard Modeling

Civitas models four hazard channels:

• Climate (heat, storms, wildfires): Personas with high HeatExposure suffer wealth/income shocks
• Pandemic: Healthcare costs, job loss for service workers
• War: Defense spending, supply chain disruption, veteran impacts
• Opioid Crisis: Healthcare costs, lost productivity

Try the "Hazard Archetypes" comparison group to see how climate policy affects coastal vs. inland households.

5. Integrate with Claude Code (MCP)

If you use Claude Desktop, connect Civitas via the Model Context Protocol:

1. Go to Settings → MCP Integration
2. Click "Connect to Claude Code"
3. Civitas writes .claude.json with the MCP server config
4. Restart Claude Desktop

Now you can chat with Claude and ask:

• "Run a simulation comparing Medicare for All to Current Policy"
• "Score the Infrastructure Investment and Jobs Act"
• "Create a custom provision that phases in a carbon tax over 5 years"

Claude will invoke Civitas tools (SimulationTools, BillTools, ProvisionTools) and return results inline.

6. Learn the Lever Taxonomy

Civitas exposes ~30 policy levers. To master the simulator, study the lever taxonomy (available via MCP get_help tool):

Fiscal Levers:

• IncomeTaxRate, CorporateTaxRate, CapitalGainsTaxRate, EstateTaxRate
• ChildTaxCredit, EarnedIncomeTaxCredit
• InfrastructureSpending, EducationSpending, DefenseSpending

Monetary Levers:

• FederalFundsRate, QuantitativeEasing

Trade Levers:

• TariffRate, TradeAgreementImpact

Labor & Immigration:

• MinimumWage, ImmigrationQuota, AILaborDisplacement

Transfers:

• UniversalBasicIncome, SocialSecurityBenefit, MedicareExpansion

Hazards:

• HeatIntensity, PandemicIntensity, WarIntensity, OpioidCrisisIntensity

Each lever has a baseline value (status quo) and can be adjusted in provisions.

8. Understand the Limits

Civitas is a model, not a crystal ball. It:

• Simplifies complex systems (e.g., no international capital flows, no endogenous innovation)
• Assumes rational actors and equilibrium-seeking behavior
• Ignores political feasibility and implementation challenges
• Projects based on historical correlations, which may not hold in unprecedented scenarios

Use Civitas to build intuition, test hypotheses, and compare alternatives—not to predict the future with certainty.

9. Experiment Fearlessly

The beauty of a simulator: you can't break anything real.

• Set tariffs to 100% and watch the economy collapse
• Give everyone $10,000/month UBI and see hyperinflation
• Eliminate all federal spending and observe the chaos

These extreme scenarios teach you how the system works—where feedback loops amplify, where stabilizers kick in, where tipping points lie.

10. Share Your Insights

Once you've run interesting scenarios:

• Export results (CSV, JSON) for further analysis
• Screenshot the Dashboard and share on social media
• Write a blog post explaining your findings
• Embed bills in URLs and send to policymakers

Civitas is designed for transparent, reproducible policy analysis. Every simulation can be shared, audited, and debated.

Ready for Takeoff

You now have the foundation to explore Civitas confidently:

✅ You understand the flight simulator metaphor
✅ You can navigate the Dashboard
✅ You've run your first preset scenario
✅ You can read KPIs and persona impacts
✅ You know the next steps to deepen your skills

Your mission: Run three more scenarios this week. Compare progressive vs. regressive policies. Test your own policy ideas. Ask the AI hard questions.

Welcome aboard. The economy is yours to explore.

Happy simulating! ✈️```