Add dashboard layout plan and scenario validation rules documentation

requirements/FR-008.md

@@ -59,3 +59,15 @@ The following table inventories the core project and scenario attributes that mu
 | Scenario | `updated_at`       | datetime (UTC)    | No                 | Ignored on import; system manages.                                         | Export for audit purposes (read-only).       |
 
 Additional domain entities (financial inputs, simulation parameters, etc.) will be inventoried in subsequent iterations once their import/export scope is defined. This initial mapping focuses on the mandatory Project and Scenario records required to satisfy FR-008 and related reporting flows.
+
+## Import/Export File Format Guidelines
+
+- **Supported formats:** CSV (`.csv`) and Excel (`.xlsx`).
+- **Encoding:** All text-based files must use UTF-8 encoding without byte-order marks to ensure consistent parsing across environments.
+- **Header row:** The first row must contain column headers matching the field names defined in the mapping table (case-insensitive). Additional columns are ignored during import but preserved during export when possible.
+- **CSV specifics:** Values are comma-delimited, double-quoted when containing commas or line breaks, and line endings follow `\n`. Empty strings are treated as null when the field is optional.
+- **Excel specifics:** Importers read from the first worksheet. Each sheet must use the same header row convention. Cells containing formulas are evaluated before ingestion (using stored values, not formulas).
+- **Date/time:** Dates and timestamps must be supplied in ISO 8601 format (`YYYY-MM-DD` for dates, `YYYY-MM-DDTHH:MM:SSZ` for timestamps). Exporters always output UTC timestamps.
+- **Numeric fields:** Decimal values use `.` as the separator. Discount rates accept either raw decimals (`7.5`) or percentages (`7.5%`).
+- **Enumerations:** Enum columns accept canonical values or the friendly labels documented in the alias table. Exporters always emit canonical enum codes.
+- **Validation feedback:** Import workflows return structured error payloads indicating row number, column, and validation failure to guide remediation.

specifications/dashboard_layout.md

@@ -0,0 +1,45 @@
+# CalMiner Dashboard Layout Plan
+
+Last updated: 2025-11-09
+
+This document describes the intended layout structure for the CalMiner homepage/dashboard template.
+
+## Page Goals
+
+- Provide a concise overview of key project and scenario metrics immediately after sign-in.
+- Offer quick actions for creating or navigating to core workflows (projects, scenarios, data uploads).
+- Surface recent activity in a scan-friendly, responsive layout that works on desktop and tablet.
+
+## Layout Structure
+
+1. **Hero Header**
+
+   - Title block with optional welcome message and current environment badge.
+   - Primary CTA button group (e.g., "New Project", "Import Data").
+   - Optional quick filter chips for project categories.
+
+2. **Summary Metrics Row**
+
+   - Four metric cards showing: total projects, active scenarios, pending simulations, last import timestamp.
+   - Cards adapt to a two-column grid on screens < 960px.
+
+3. **Recent Activity Panels**
+
+   - Left column (2/3 width) displays a table of recent projects with status, updated timestamp.
+   - Right column (1/3 width) hosts scenario alerts (validation conflicts, approaching deadlines) in a stacked list.
+
+4. **Secondary Widgets**
+   - Simulation pipeline status timeline (if data present) or placeholder guidance.
+   - Documentation and support links card.
+
+## Responsiveness
+
+- Desktop: two-column layout for activity panels and secondary widgets.
+- Tablet: stacks columns vertically while keeping metric cards in two columns.
+- Mobile: single-column flow; CTA buttons collapse into a vertical stack.
+
+## Implementation Notes
+
+- Reuse existing `.card`, `.page-header`, and `.container` classes from `static/css/main.css`.
+- Introduce specialized dashboard classes (e.g., `.dashboard-metrics`, `.dashboard-grid`) scoped within a new `static/css/dashboard.css` file if needed.
+- Provide placeholder content for areas where backend data integrations are pending (e.g., empty state messages).

specifications/scenario_validation.md

@@ -0,0 +1,44 @@
+# Scenario Validation Rules
+
+Last updated: 2025-11-09
+
+This document captures the validation rules that must run before comparing two or more scenarios within the CalMiner application. The rules are enforced inside the scenario service layer and surfaced through the API and HTML workflows.
+
+## Comparison Preconditions
+
+All scenarios included in a comparison request **must** satisfy the following preconditions:
+
+| Rule                       | Description                                                                                                                                                              | Error Code                   | Client Message                                                         |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------------- |
+| Same project               | Every scenario must belong to the same project identifier.                                                                                                               | `SCENARIO_PROJECT_MISMATCH`  | "Selected scenarios do not belong to the same project."                |
+| Active status              | Only scenarios in `draft` or `active` status may be compared. Archived scenarios are rejected.                                                                           | `SCENARIO_STATUS_INVALID`    | "Archived scenarios cannot be compared."                               |
+| Shared currency            | Scenarios must share the same `currency` value when provided.                                                                                                            | `SCENARIO_CURRENCY_MISMATCH` | "Scenarios use different currencies and cannot be compared."           |
+| Timeline coherence         | When both scenarios provide date ranges, they must overlap or touch (inclusive). Non-overlapping ranges raise a conflict.                                                | `SCENARIO_TIMELINE_DISJOINT` | "Scenario timelines do not overlap; adjust the comparison window."     |
+| Primary resource alignment | Scenarios must declare the same `primary_resource` (if set). When one is unset, the non-null value is applied to both. If both are set but differ, the comparison fails. | `SCENARIO_RESOURCE_MISMATCH` | "Scenarios target different primary resources and cannot be compared." |
+
+## Error Response Contract
+
+When a validation rule fails, the service layer raises a `ScenarioValidationError` (to be implemented) containing:
+
+- a machine-readable `code` from the table above,
+- a human-readable `message` designed for UI display,
+- a list of related `scenario_ids` that triggered the rule (if available).
+
+The API adapts the error into an HTTP `422 Unprocessable Entity` payload:
+
+```jsonc
+{
+  "detail": {
+    "code": "SCENARIO_PROJECT_MISMATCH",
+    "message": "Selected scenarios do not belong to the same project.",
+    "scenario_ids": [12, 19]
+  }
+}
+```
+
+HTML form flows display the `message` as a banner and set the HTTP status to `400`.
+
+## Future Considerations
+
+- Expand rules to cover incompatible simulation parameter configurations once parameter taxonomy stabilises.
+- Provide localized error message variants when the internationalization framework is introduced.