feat: add functional requirements for profitability, Monte Carlo simulation, and Capex/Opex management; enhance user guide with planners

userguide/initial_capex_planner.md

@@ -0,0 +1,59 @@
+# Initial Capex Planner
+
+The Initial Capex Planner helps project teams capture upfront capital requirements, categorize spend, and produce a shareable breakdown that feeds downstream profitability analysis. The feature implements the acceptance criteria described in [FR-013](../requirements/FR-013.md) and persists calculation snapshots for both projects and scenarios when context is provided.
+
+## Access Paths
+
+- **Workspace sidebar**: Navigate to _Workspace → Initial Capex Planner_.
+- **Scenario detail page**: Use the _Initial Capex Planner_ button in the scenario header to open the planner pre-loaded with the selected project and scenario.
+
+## Prerequisites
+
+- Authenticated CalMiner account with at least _viewer_ permissions on the target project/scenario.
+- Baseline pricing settings seeded through the database initializer (the GET route resolves pricing metadata for defaults).
+
+## Planner Workflow
+
+1. **Open the planner** via the sidebar or scenario action button. Query parameters (`project_id`, `scenario_id`) preload metadata for the selected context.
+2. **Review defaults** in the form header: currency code, contingency, discount rate, and evaluation horizon pull from the scenario, project, or system defaults.
+3. **Capture capex components** by adding rows to the components table. Each row records:
+   - Category (equipment, infrastructure, land, miscellaneous, etc.)
+   - Component name and optional internal identifier
+   - Amount and currency (defaults to scenario or project currency)
+   - Planned spend year and notes
+4. **Adjust global parameters** in the sidebar panel for contingency percentage, discount rate, and evaluation horizon years.
+5. **Run the calculation** with _Save & Calculate_. The POST request validates the payload, aggregates totals, applies contingency, and produces categorized and time-phased results.
+6. **Review results** in the Capex Summary cards, category table, and timeline table. Optional chart containers are rendered for future visualization enhancements.
+
+## Persistence Behaviour
+
+- When a `project_id` or `scenario_id` is supplied, the POST handler stores a snapshot via `ProjectCapexSnapshot` and/or `ScenarioCapexSnapshot` before rendering results.
+- Snapshots include aggregate totals, contingency metrics, component counts, and the normalized payload, enabling auditing and downstream financial modelling.
+- JSON clients can set `options[persist]=0` to skip persistence in future iterations (HTML form defaults to persist enabled).
+
+## API Reference
+
+| Route                                               | Method | Description                                                                                                                                    |
+| --------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/calculations/capex` (`calculations.capex_form`)   | GET    | Renders the planner template with defaults for the provided project/scenario context.                                                          |
+| `/calculations/capex` (`calculations.capex_submit`) | POST   | Accepts form or JSON payload matching `CapexCalculationRequest`, returns HTML or JSON results, and persists snapshots when context is present. |
+
+Key schemas and services:
+
+- `schemas.calculations.CapexCalculationRequest`, `CapexComponentInput`, `CapexParameters`
+- `services.calculations.calculate_initial_capex`
+- `_persist_capex_snapshots` helper in `routes/calculations.py`
+
+Refer to `tests/integration/test_capex_calculations.py` for example payloads and persistence assertions.
+
+## Troubleshooting
+
+- **Validation errors**: Field-level messages appear above the components table for row-specific issues and in the global error alert for general problems.
+- **Currency mismatch**: The service enforces a single currency across all components; ensure component rows use the same ISO-4217 code or adjust the default currency.
+- **Timeline gaps**: Rows without a `spend_year` are excluded from the timeline but still contribute to totals.
+
+## Related Resources
+
+- [Initial Capex Planner template](../../calminer/templates/scenarios/capex.html)
+- [Capex snapshot models](../../calminer/models/capex_snapshot.py)
+- [FR-013 Requirement](../requirements/FR-013.md)