docs: design proposal for YAML-driven cost calculator

[Copilot]

Adds docs/design-proposal.md as the formal response to Discussion #2, establishing the architecture for the next development stage of the cost calculator.

YAML model file spec

Four top-level sections per model file:

metadata:        # title, description, authors, introduction (Markdown)
parameters:      # sidebar widgets — name, label, default, min, max, unit_label, type, references
equations:       # named Python expressions; may reference other equation ids
table:           # scenarios (columns) + rows (ordered equation references)

Key design choices:

• parameters[].name doubles as the Python identifier injected into equation expressions
• equations[].equation is a plain Python expression string evaluated at runtime; equations may compose each other via their id
• table.scenarios[].variables injects free variables (e.g. n_cases) not covered by parameters, enabling multi-column outbreak-size comparisons from a single equation set

Report structure spec

Standardises output as an ordered sections list consumed by the existing render_sections renderer:

• Results table — rows = equations, columns = scenarios; cell formatting driven by output_type (integer / double)
• Parameters table — auto-generated from parameters[] (name, current value, unit, description, references)
• References — auto-collected from parameters[].references

Workflows (Mermaid)

Two flowcharts covering the full lifecycle:

1. YAML parsing — file discovery → yaml.safe_load → section extraction → sidebar widget construction + equation registry → session state
2. Cost calculator build — Run Simulation → param resolution → per-scenario equation evaluation (with recursive equation-id resolution) → DataFrame assembly → cell formatting → render_sections → guardrail warnings for out-of-bounds values

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.