Fpa Scaffold Model

---
name: fpa-scaffold-model
description: Use when building a new openfpa forecast model from a company's financials - a trial balance, a P&L export, or a pasted income statement - and you need a runnable config to exist before any forecasting or analysis.
---

# Scaffold a Model (Phase 1)

## Overview

Turn a company's financials into a runnable `pyfpa` config. Read the business profile first (see **fpa-learn-business**), infer the chart-of-accounts → model-line mapping, and write a validated `EntityConfig` YAML following openfpa conventions. Output a runnable skeleton plus an explicit list of assumptions to confirm.

**Core principle:** Convention over invention. Map the real numbers onto the existing engine shape; don't design a new one.

## When to use

- A trial balance / P&L (CSV, XLSX, or pasted) needs to become a forecast model
- Onboarding follow-on after `.fpa/business-profile.md` exists

## Workflow

1. **Ingest** the financials: `pyfpa.read_pl_csv(path)` (or a `pyfpa.io.adapters` source) → `{account: amount}`.
2. **Map accounts to model lines** of the `EntityConfig` schema:
   - revenue accounts → `channels[]` (one `Channel` per channel/segment, with `annual_revenue`, a 12-month `seasonality` weight list, `growth_rate`, `cogs_pct`)
   - cost accounts → `opex[]` as `OpexLine(kind="fixed", monthly_amount=…)` or `kind="variable", pct_of_revenue=…`
   - debt → `debt[]` (`term_loan` with `monthly_principal`, or interest-only `loc`)
   - balance-sheet rhythm → `working_capital(dso_days, dpo_days, dio_days)` and `opening_balances`
3. **Write** the company model and config under `models/generated/`. Validate
   config with `pyfpa.load_config(path)`, which raises on any bad field.
4. **Create a runnable command** such as
   `python3 models/generated/run_forecast.py`. Keep the runner thin and make its
   output locations explicit.
5. **Run and validate it.** Confirm the model executes, reconciles its inputs,
   and writes the expected outputs.
6. **Register the tested command** with `openfpa entrypoint-register`, including
   its inputs and outputs. Registration publishes the command for agent
   discovery; it does not run it.
7. **Surface assumptions**: list the 6-10 inferences a human must confirm
   (seasonality shape, fixed vs variable splits, cogs_pct per channel, opening
   balances). Do not bury them.

## Conventions (match the engine)

- For a config-backed generated model, keep assumptions in validated YAML rather
  than scattering company numbers through code.
- Set `opening_balances` AR/AP/inventory to the **first forecast month's** DSO/DPO/DIO-implied balances - the engine diffs each month against the prior, seeding month 1 against opening, so use month-1 projected revenue/COGS, NOT the annual average. Get this wrong and month-1 cash swings on a one-time artifact (see **fpa-cfo-judgment** working-capital seam).
- `"total"` is a reserved channel/opex name (the engine adds a `total` column).

A live-formula Excel edition of the model is available via **fpa-excel-model**.

## Next

Runnable config confirmed → **fpa-configure-actuals** to wire live/real numbers, then the operate skills.