PolicyEngine · MaxGhenis · Apr 27, 2026 · Apr 27, 2026
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -40,6 +40,15 @@ website:
           - outputs.md
           - regions.md
           - visualisation.md
+      - section: "Methodology"
+        contents:
+          - methodology/index.md
+          - methodology/model-architecture.md
+          - methodology/us-health-costs.md
+      - section: "Programs"
+        contents:
+          - programs/index.md
+          - programs/us-chip.md
       - section: "Reference"
         contents:
           - countries.md

diff --git a/docs/countries.md b/docs/countries.md
@@ -56,6 +56,12 @@ Parameter paths mirror the country's rule-making structure:
 
 See [Reforms](reforms.md) for how to express changes in either tree.
 
+## Methodology and programs
+
+Country-specific methodology pages explain model structure that is too broad for a generated variable reference. Current US pages include [health coverage and costs](methodology/us-health-costs.md).
+
+Program pages explain eligibility and benefit structure. Current US pages include [CHIP](programs/us-chip.md).
+
 ## Switching countries
 
 Most analysis patterns are identical — swap `pe.us` for `pe.uk`:

diff --git a/docs/index.md b/docs/index.md
@@ -38,6 +38,9 @@ result.household.household_net_income
 | Produce population estimates (budget cost, poverty) | [Microsimulation](microsim.md) |
 | See the full catalog of typed outputs | [Outputs](outputs.md) |
 | Run the canonical baseline-vs-reform bundle | [Impact analysis](impact-analysis.md) |
+| Understand model structure and assumptions | [Methodology](methodology/index.md) |
+| Understand US health coverage and costs | [US health coverage and costs](methodology/us-health-costs.md) |
+| Read program-level methodology | [Programs](programs/index.md) |
 | Break results down by state, constituency, district | [Regions](regions.md) |
 | Understand US vs UK differences | [Countries](countries.md) |
 | Build publication-ready charts | [Visualisation](visualisation.md) |

diff --git a/docs/methodology/index.md b/docs/methodology/index.md
@@ -0,0 +1,27 @@
+---
+title: "Methodology"
+---
+
+This section contains authored explanations of how PolicyEngine models policy systems. It complements program pages and generated reference pages: reference pages describe variables and parameters one by one, while methodology pages explain how the pieces fit together.
+
+## How to read this section
+
+PolicyEngine separates three documentation layers:
+
+| Layer | Source | Purpose |
+|---|---|---|
+| Tutorials | Authored examples in this repository | Show how to use `policyengine` |
+| Methodology | Authored pages in this section | Explain model structure, assumptions, and decomposition choices |
+| Programs | Authored pages in `programs/` | Explain eligibility, benefit value, and household-paid costs program by program |
+| Reference | Generated from country-model metadata | List variables, parameters, programs, source paths, and citations |
+
+The long-term goal is that generated pages come from the country model and data packages, while authored methodology and program pages live here with the user-facing Python package.
+
+## Current deep dives
+
+- [Model architecture](model-architecture.md)
+- [US health coverage and costs](us-health-costs.md)
+
+## Program pages
+
+- [US CHIP](../programs/us-chip.md)
diff --git a/docs/methodology/model-architecture.md b/docs/methodology/model-architecture.md
@@ -0,0 +1,73 @@
+---
+title: "Model architecture"
+---
+
+PolicyEngine models tax and benefit systems as a set of country packages wrapped by the `policyengine` Python interface. The country packages contain the policy rules; this package provides the user-facing calculation and analysis surface.
+
+This page describes the documentation structure we would choose if starting fresh.
+
+## Three layers
+
+PolicyEngine documentation should keep three layers separate:
+
+| Layer | Owns | Should answer |
+|---|---|---|
+| Methodology | Authored prose | Why the model is structured this way, how concepts flow, where assumptions enter |
+| Program pages | Authored prose plus generated links | What a program does, who qualifies, how values and household costs are represented |
+| Reference | Generated from code and data packages | What variables, parameters, programs, sources, and calibration targets exist in a release |
+
+This split avoids two common failure modes:
+
+- Long-form methodology pages becoming stale variable catalogs.
+- Generated reference pages trying to explain modeling choices that need narrative context.
+
+## Source of truth
+
+The source of truth should depend on content type:
+
+| Content | Source |
+|---|---|
+| Formulas, entities, variable metadata | Country model packages such as `policyengine-us` |
+| Parameter values, uprating, legislative references | Country model parameter YAML |
+| Microdata construction, imputations, calibration targets | Country data packages such as `policyengine-us-data` |
+| User tutorials, model-wide methodology, program narratives | `policyengine.py` docs |
+
+The documentation site should not manually copy reference metadata that can be regenerated from a release. It should explain how the generated pieces fit together.
+
+## Rules, data, calibration, outputs
+
+A complete model page should be explicit about four pieces:
+
+1. Rules: statutory formulas and administrative program rules.
+2. Data: the household or person records to which rules are applied.
+3. Calibration: adjustments that align the data and model outputs with external targets.
+4. Outputs: the resource, budget, poverty, inequality, and distributional concepts returned to users.
+
+For example, a program page should not stop at eligibility. It should say how benefit value is represented, whether household-paid costs are modeled, what data inputs are required, and how the program enters aggregate output concepts.
+
+## What belongs in generated reference
+
+Generated reference pages should include:
+
+- variable name, entity, period, unit, label, and documentation
+- `adds`, `subtracts`, and `defined_for` relationships
+- source file path and source line
+- parameter value history and references
+- program coverage metadata
+- calibration target source, vintage, unit, and current model fit
+
+The existing reference generator is a prototype for the variable and program parts. Parameter and data-lineage generation should follow the same pattern.
+
+## What belongs in authored methodology
+
+Authored methodology pages should focus on model choices:
+
+- why a decomposition exists
+- which entity owns a concept
+- how gross and net quantities differ
+- where a reform can change outcomes
+- what is intentionally left as an imputed residual
+- what current limitations users should know before interpreting outputs
+
+That is the structure used by the first new US health-cost page.
+
diff --git a/docs/methodology/us-health-costs.md b/docs/methodology/us-health-costs.md
@@ -0,0 +1,92 @@
+---
+title: "US health coverage and costs"
+---
+
+Health programs are unusual in a tax-benefit model because they often create both a benefit value and a household-paid cost. A CHIP enrollee receives health coverage, but the household may also pay a premium. A Marketplace enrollee may receive a premium tax credit, but still pay a net plan premium. The model needs to keep those concepts separate.
+
+This page describes the current US health-cost architecture and the next pieces the documentation should expose through generated reference.
+
+## Resource concepts
+
+PolicyEngine uses different resource concepts for different questions:
+
+| Concept | Purpose |
+|---|---|
+| Tax liability and credits | Federal and state tax calculation |
+| Health benefit value | Value of public or subsidized health coverage |
+| Household health costs | Household-paid health costs that should reduce resources when health benefits are counted |
+| SPM medical out-of-pocket expenses | Medical expenses subtracted from Supplemental Poverty Measure resources |
+
+Keeping these concepts separate avoids double-counting. A premium tax credit is not the same thing as a premium paid after the credit, and a public health benefit is not the same thing as the household's out-of-pocket cost.
+
+## Current release behavior
+
+The current pinned US model includes these health-cost pieces:
+
+| Component | Variables | Current treatment |
+|---|---|---|
+| Imputed medical spending | `medical_out_of_pocket_expenses` | Person-level CPS-imputed medical spending remains available unchanged |
+| Medicare Part B | `medicare_part_b_premiums`, `income_adjusted_part_b_premium` | SPM resources subtract imputed Part B and add rules-based Part B |
+| CHIP premiums | `chip_premium` | Added to SPM medical out-of-pocket expenses and to `household_health_costs` |
+| Medicaid premiums | `medicaid_premium` | Added to SPM medical out-of-pocket expenses |
+| Marketplace net premiums | `marketplace_net_premium` | Computed as a tax-unit variable; fuller resource integration depends on the data residualization and selected-plan assumptions described below |
+
+In the current release, `household_health_costs` is controlled by the parameter list at `gov.household.household_health_costs`; the pinned US model includes `chip_premium` in that list. The household-health-cost aggregate only affects net income when `gov.simulation.include_health_benefits_in_net_income` is enabled, so health benefits and health costs are added symmetrically.
+
+## SPM medical out-of-pocket decomposition
+
+The SPM-unit medical out-of-pocket variable currently follows this structure:
+
+```text
+spm_unit_medical_out_of_pocket_expenses
+    = imputed medical out-of-pocket expenses
+    - imputed Medicare Part B premiums
+    + computed Medicare Part B premiums
+    + computed CHIP premiums
+    + computed Medicaid premiums
+```
+
+This keeps person-level imputed medical spending available for rules that consume it directly, while making SPM resources more responsive to reforms that change rules-based premiums.
+
+The longer-run target is a residualized structure:
+
+```text
+resource medical costs
+    = imputed residual
+    + computed public-program premiums
+    + computed Marketplace net premiums
+```
+
+where the imputed residual is the survey-reported medical-cost total after subtracting baseline computed premiums during data construction.
+
+## Marketplace premiums
+
+Marketplace modeling has three distinct quantities:
+
+| Quantity | Meaning |
+|---|---|
+| `slcsp` | Gross second-lowest-cost silver plan premium, used as the PTC benchmark |
+| `aca_ptc` | Premium tax credit calculated from the benchmark and required household contribution |
+| `marketplace_net_premium` | Selected-plan premium paid after applying the used PTC |
+
+The current release includes `marketplace_net_premium`, defined as the selected-plan premium proxy minus the PTC actually used. The selected-plan premium proxy is based on the SLCSP and a selected-plan-to-benchmark ratio.
+
+Two modeling details should be documented clearly as this area evolves:
+
+- Gross Marketplace premiums should not be gated only on PTC eligibility. A household can be ineligible for the PTC and still buy an unsubsidized Marketplace plan.
+- Resource integration should avoid double-counting against CPS private-premium imputations. Marketplace premiums need data-side residualization before they can be cleanly layered into every resource concept.
+
+Those details belong in methodology pages; the exact variable graph and parameter values belong in generated reference pages.
+
+## Program pages
+
+Program pages should describe how each health program enters the model:
+
+- eligibility
+- benefit value
+- household-paid premiums or cost sharing
+- resource and poverty treatment
+- open limitations
+
+The first program page in this structure is [US CHIP](../programs/us-chip.md).
+
diff --git a/docs/programs/index.md b/docs/programs/index.md
@@ -0,0 +1,30 @@
+---
+title: "Programs"
+---
+
+Program pages explain eligibility, benefit amounts, household-paid costs, and links to model variables. They sit between high-level methodology pages and generated variable reference pages.
+
+A good program page should be short and structural. It should not manually reproduce every parameter table. Instead, it should explain what the program does, how the model represents it, and where generated reference pages should take over.
+
+The migration pattern is:
+
+| Content type | Preferred source |
+|---|---|
+| Narrative program explanation | Authored page in this section |
+| Variable metadata, source path, entity, unit, references | Generated from country-model metadata |
+| Parameter values and time series | Generated from parameter YAML |
+| Data lineage and calibration targets | Generated from country data packages where possible |
+
+## Page template
+
+Each program page should answer:
+
+1. Who can qualify?
+2. What value does the household or person receive?
+3. What costs, if any, does the household pay?
+4. Which resource concepts include the benefit or cost?
+5. What limitations should users know before interpreting results?
+
+## Current US pages
+
+- [CHIP](us-chip.md)
diff --git a/docs/programs/us-chip.md b/docs/programs/us-chip.md
@@ -0,0 +1,55 @@
+---
+title: "US CHIP"
+---
+
+The Children's Health Insurance Program provides health coverage to children, and in some states pregnant people, whose household income is above Medicaid eligibility limits but within state CHIP limits.
+
+PolicyEngine US represents CHIP as a health-coverage program with three distinct pieces: eligibility, benefit value, and household-paid premiums.
+
+## Eligibility
+
+`is_chip_eligible` is a person-level variable. It is true when the model determines that:
+
+- the person is age-eligible, or eligible through a pregnancy-related CHIP pathway
+- household MAGI as a share of the federal poverty line is at or below the state's CHIP income limit
+- the person is not income-eligible for Medicaid
+- immigration status is eligible
+
+State eligibility thresholds are parameterized in the country model. Generated reference pages should expose the exact parameter paths, values, and legislative references by state.
+
+## Benefit value
+
+`per_capita_chip` represents the state's net-of-cost-sharing spending per CHIP enrollee. `per_capita_chip_gross` adds back cost-sharing offsets where available to recover a gross service-value concept.
+
+`chip_gross` is the person-level gross value that can be summed to households or other entities.
+
+## Premiums
+
+`chip_premium` is the annual household-paid premium or enrollment fee at the tax-unit level. It aggregates state-specific variables because state schedules differ in structure.
+
+The important modeling choice is not the list of states; generated reference should provide that. The authored page should explain that a premium can be:
+
+- a household-level enrollment fee
+- a per-child monthly premium
+- a per-child premium with a family cap
+- a premium matrix that varies by family size and income band
+
+Those structures all produce the same tax-unit concept: an annual CHIP premium paid by the household.
+
+## SPM and household resources
+
+CHIP premiums are household-paid health costs. They reduce resources in concepts that include medical out-of-pocket expenses or health costs.
+
+The decomposition is described in [US health coverage and costs](../methodology/us-health-costs.md): computed CHIP premiums are layered into reform-responsive health-cost components, while non-modeled medical spending remains in an imputed residual.
+
+## Cost-sharing cap
+
+Federal rules cap total CHIP cost sharing, including premiums and copays, at 5 percent of family income. The model has premium schedules, but copays are not yet modeled as a separate component. A complete cost-sharing cap requires both pieces.
+
+## Data sources
+
+Primary sources for premium schedules vary by state. Parameter files in `policyengine-us` cite the relevant state handbook, regulation, or Medicaid agency fee schedule where available. Cross-state surveys can be useful for discovery, but encoded parameters should prefer primary state and federal sources.
+
+## See also
+
+- [US health coverage and costs](../methodology/us-health-costs.md)