specs for rewrite

docs/anforderungs-abgleich.md

@@ -0,0 +1,68 @@
+# Anforderungs-Abgleich (Dokumentation vs. Code)
+
+Dieses Dokument ergänzt die Hauptdokumentation und listet transparent auf:
+
+1. Was laut Anforderungen noch nicht vollständig umgesetzt ist.
+2. Was bereits im Code existiert, aber im ursprünglichen Requirements-Dokument nicht oder nur als offener Punkt erwähnt war.
+
+Basisvergleich:
+- Anforderungen: `docs/electrical-load-balance-requirements-context-dump.md`
+- Ist-Stand: aktueller Code in `src/`
+
+## A) Anforderungen, die noch nicht vollständig umgesetzt sind
+
+### 1) Bericht/Export/Print für Leistungsbilanzen
+- Erwartung: später nutzbarer Report-Export/Print.
+- Stand: Noch nicht umgesetzt.
+- Wirkung: Der Fokus liegt aktuell auf Erfassung, Bearbeitung und Berechnung im Web-UI.
+
+### 2) „Keine Pflichtfelder“ vollständig im UI-Flow
+- Erwartung: Einträge sollen auch ohne zwingende Felder erfassbar sein.
+- Stand: Backend-seitig weitgehend erfüllt (optionale Felder + Defaults), UI-Schnellerfassung verlangt derzeit einen Namen.
+- Wirkung: Fachlich ist unvollständige Speicherung möglich, aber die Standard-UI bremst diesen speziellen Fall noch.
+
+### 3) Einheitliche Textqualität (Mojibake-frei) im gesamten Frontend
+- Erwartung: saubere Umlaute/UTF-8.
+- Stand: In mehreren UI-Dateien sind weiterhin fehlerhafte Kodierungsreste vorhanden (z. B. „Gerät“).
+- Wirkung: Funktionalität ist gegeben, UX/Textqualität ist noch nachzuziehen.
+
+## B) Bereits umgesetzt, aber im ursprünglichen Requirements-Dokument nicht klar ausformuliert
+
+### 1) Feste Domänen-Auswahllisten sind final definiert
+- Im Requirements-Dokument war das als „noch festzulegen“ markiert.
+- Im Code jetzt vorhanden:
+  - `src/shared/constants/consumer-option-lists.ts`
+  - Validierung in `src/shared/validation/consumer.schemas.ts`
+  - Select-Felder in `src/app/projects/[projectId]/circuit-lists/page.tsx`
+
+### 2) Sortieren, Filtern und Bulk-Edit sind bereits implementiert
+- Im Requirements-Dokument als mögliche Zusatzfunktion erwähnt.
+- Im Code umgesetzt in `src/app/projects/[projectId]/circuit-lists/page.tsx`.
+
+### 3) Projekt-Spannungsstandards (1-phasig / 3-phasig) inkl. Berechnungsintegration
+- Im Requirements-Dokument nicht so detailliert als Projekt-Feature beschrieben.
+- Im Code umgesetzt:
+  - Projekteinstellungen im Projekt-Detail
+  - Verwendung in Berechnungslogik (effektive Spannung je Verbraucher)
+
+### 4) 1–3 parallele Stromkreislisten mit responsiver Aufteilung
+- Im Requirements-Dokument nicht als konkrete UI-Regel spezifiziert.
+- Im Code umgesetzt in `src/app/projects/[projectId]/circuit-lists/page.tsx`.
+
+### 5) Gerätekopie global ↔ projektbezogen in beide Richtungen
+- Fachlich erwähnt, aber technisch konkretisiert im API-Design:
+  - `POST /api/project-devices/projects/:projectId/import-global/:globalDeviceId`
+  - `POST /api/global-devices/import-project/:projectId/:projectDeviceId`
+
+## C) Offene fachliche Entscheidungen mit bereits getroffener Code-Interpretation
+
+### 1) Verhalten beim Kopieren von Stromkreiseinträgen zwischen Listen
+- Offener Punkt in den Anforderungen: Link beibehalten oder trennen?
+- Aktuelle Code-Interpretation: Link-Information wird mitkopiert (`projectDeviceId`, `isLinkedToDevice`).
+- Relevanz: Sollte fachlich explizit bestätigt werden, damit spätere Änderungen keine Regression verursachen.
+
+## D) Empfehlung für nächste Dokumentationsrunde
+
+1. Das Requirements-Dokument um die inzwischen finalen Auswahllistenwerte ergänzen.
+2. Die Kopierlogik (Link beibehalten/trennen) fachlich eindeutig festschreiben.
+3. Einen eigenen Abschnitt für bekannte UX-/Textqualitätspunkte (Kodierung/Umlaute) ergänzen.

docs/spec/01-domain-context.md

@@ -0,0 +1,38 @@
+# Domain Context: Distribution Board Circuit List
+
+## Purpose
+
+In electrical building design, especially during detailed design / execution planning, a circuit list is created for each distribution board.
+
+The circuit list documents all consumers, devices and circuits supplied by or installed in a specific distribution board. It supports:
+
+- construction of the distribution board by the electrical contractor
+- execution planning and technical coordination
+- quantity takeoff for tendering and cost estimation
+- determination of required protective devices, terminals, modular DIN rail devices and related components
+- structured documentation of the internal electrical path inside the distribution board
+
+Although the term "circuit list" is used, the list does not only contain final outgoing circuits. It may also contain or later support devices and functional components such as:
+
+- main switches
+- surge protection devices
+- KNX devices
+- control devices
+- modular DIN rail devices
+- reserve circuits
+- other distribution board components
+
+## Important Domain Rule
+
+A circuit list entry is not always just a single independent circuit.
+
+A circuit can contain one or more device rows.
+
+If a circuit contains one device, it can be displayed as one compact row.
+
+If a circuit contains multiple devices, the UI displays:
+
+- one circuit summary row
+- one or more indented device rows below it
+
+Circuit-level data such as protection device, cable type and cable length belongs to the circuit, not to each individual device.

docs/spec/02-functional-requirements.md

@@ -0,0 +1,144 @@
+# Functional Requirements: Circuit List Inside a Distribution Board
+
+## Scope
+
+This specification focuses only on the circuit list inside one distribution board.
+
+Out of scope for this document:
+
+- project management
+- user accounts
+- permissions
+- full tender export
+- CAD integration
+- full norm-compliant electrical calculation
+- cloud deployment
+
+The first goal is a fast, spreadsheet-like editor for creating, editing, sorting and restructuring circuit lists.
+
+## Sections
+
+The circuit list is grouped into sections.
+
+Default sections:
+
+| Section | Default prefix |
+|---|---|
+| Lighting | `-1F` |
+| Single-phase circuits | `-2F` |
+| Three-phase circuits | `-3F` |
+
+Sections are displayed as separator rows in the table, not as normal visible data columns.
+
+Example:
+
+```text
+Lighting
+-1F1  Beleuchtung Flur
+-1F2  Beleuchtung Außen
+
+Single-phase circuits
+-2F1  Arbeitsplatzsteckdosen Büro
+-2F2  Handtrockner WC
+
+Three-phase circuits
+-3F1  Durchlauferhitzer
+```
+
+Internally, every circuit belongs to a section. In the UI, the section is shown as a grouping separator.
+
+## Future Section Configuration
+
+Sections and numbering prefixes should later be configurable per project.
+
+Future project configurations may support:
+
+- one continuous numbering sequence without lighting/single-phase/three-phase separation
+- numbering grouped by RCD
+- numbering grouped by functional area
+- custom prefixes and suffixes
+- custom section names
+
+The first implementation may use the default sections, but the structure must not permanently hardcode them.
+
+## Circuit Numbering / Equipment Identifiers
+
+Each circuit has an equipment identifier.
+
+Examples:
+
+- `-1F1`
+- `-1F2`
+- `-2F1`
+- `-2F2`
+- `-3F1`
+
+Default convention:
+
+- `-1Fx` = lighting circuits
+- `-2Fx` = single-phase circuits
+- `-3Fx` = three-phase circuits
+
+When a new circuit is created, the next identifier is calculated as:
+
+```text
+highest existing number in the section + 1
+```
+
+Example:
+
+Existing identifiers in single-phase section:
+
+- `-2F1`
+- `-2F2`
+- `-2F5`
+
+New circuit receives:
+
+- `-2F6`
+
+Gaps are not filled automatically.
+
+Gaps may be closed only by:
+
+- manually editing equipment identifiers
+- explicitly using a renumbering action
+
+## Renumbering
+
+The app must never automatically renumber existing circuits after:
+
+- inserting a circuit
+- deleting a circuit
+- moving a circuit
+- moving a device
+- sorting a section
+- dragging rows
+- changing a device
+- synchronizing a linked project device
+
+Renumbering only happens through an explicit user action.
+
+Each section has a "Renumber section" action.
+
+The renumbering action:
+
+- keeps the current visual order
+- updates only circuits in that section
+- ignores device rows for numbering
+- does not affect other sections
+- uses the section prefix
+
+## Reserve / Empty Circuits
+
+Empty circuits are allowed.
+
+An empty circuit may be used as a reserve circuit.
+
+If the last device is removed from a circuit, the user may choose:
+
+- keep empty circuit as reserve
+- delete circuit completely
+- cancel
+
+Reserve circuits remain visible and keep their equipment identifier unless manually changed or explicitly renumbered.

docs/spec/03-data-model-concept.md

@@ -0,0 +1,171 @@
+# Data Model Concept
+
+This is a conceptual model for Codex. It is not a final database schema, but the implementation must preserve these domain relationships.
+
+## Core Concept
+
+A distribution board contains a circuit list.
+
+A circuit list contains sections.
+
+A section contains circuits.
+
+A circuit contains zero, one or multiple device rows.
+
+A device row may be:
+
+- linked to a project device
+- manually entered without a linked project device
+
+## ProjectDevice
+
+A project device is a reusable project-specific consumer or consumer group.
+
+A project device can represent:
+
+- one physical device
+- a recurring device type
+- a consumer group, for example six workstation sockets
+
+User-facing fields:
+
+- `name`
+- `displayName`
+- `phaseType`
+- `connectionKind`
+- `costGroup`
+- `category`
+- `quantity`
+- `powerPerUnit`
+- `simultaneityFactor`
+- `cosPhi`
+- `totalPower`
+- `remark`
+
+Notes:
+
+- `name` is the technical or product-related name, for example `E-Line Pro`.
+- `displayName` is a default display name used when inserting the device into the circuit list.
+- After insertion, the circuit list display name is local and not automatically synchronized.
+- `quantity` is allowed on project devices because a project device may represent a consumer group.
+- Project devices must not define final cable or protection data.
+
+## Circuit
+
+A circuit represents one outgoing circuit / equipment identifier in a distribution board section.
+
+User-facing fields:
+
+- `equipmentIdentifier`
+- `section`
+- `displayName` optional
+- `circuitTotalPower`
+- `protectionType`
+- `protectionRatedCurrent`
+- `protectionCharacteristic`
+- `cableType`
+- `cableCrossSection`
+- `cableLength`
+- `rcdAssignment` optional
+- `terminalDesignation` optional
+- `voltage` optional
+- `status` optional
+- `isReserve` optional
+- `remark` optional
+
+Circuit-level fields only:
+
+- protection type
+- protection rated current
+- protection characteristic
+- cable type
+- cable cross-section
+- cable length
+- RCD assignment
+- terminal designation
+- circuit total power
+
+Reason:
+
+Protection and cable data are dimensioned for the complete circuit. They depend on the combined load, installation context, cable length, voltage drop and planning rules.
+
+## CircuitDeviceRow
+
+A circuit device row represents a device assigned to a circuit.
+
+User-facing fields:
+
+- `linkedProjectDeviceId` optional
+- `name`
+- `displayName`
+- `phaseType`
+- `connectionKind` optional
+- `costGroup` optional
+- `category` optional
+- `level`
+- `roomNumber`
+- `roomName`
+- `quantity`
+- `powerPerUnit`
+- `simultaneityFactor`
+- `cosPhi`
+- `rowTotalPower`
+- `remark`
+- `overriddenFields`
+
+A circuit device row can be manual.
+
+A manual row has no linked project device.
+
+A manual row can later be saved as a project device. After saving, the row becomes linked to the newly created project device.
+
+## Single-Device vs Multi-Device Display
+
+If a circuit has exactly one device row, it is displayed as one compact circuit row.
+
+If a circuit has multiple device rows, it is displayed as:
+
+- one circuit summary row
+- indented device rows below it
+
+The circuit summary row shows:
+
+- equipment identifier
+- optional circuit display name
+- circuit total power
+- circuit-level protection data
+- circuit-level cable data
+
+The device rows show:
+
+- individual device values
+- quantity
+- power
+- cost group
+- category
+- room data
+- remarks
+
+## Load Calculation
+
+Device row load:
+
+```text
+rowTotalPower = quantity × powerPerUnit × simultaneityFactor
+```
+
+Circuit total:
+
+```text
+circuitTotalPower = sum(rowTotalPower of all device rows assigned to the circuit)
+```
+
+`cosPhi` is stored even if it is not visible in the default table view.
+
+Later apparent power calculation:
+
+```text
+apparentPower = totalActivePower / cosPhi
+```
+
+For circuits with multiple devices, apparent power should be calculated per device row and then summed. This avoids losing information when different devices have different power factors.

docs/spec/04-ui-interaction-requirements.md

@@ -0,0 +1,304 @@
+# UI and Interaction Requirements
+
+## UI Philosophy
+
+The circuit list editor should feel spreadsheet-like and efficient.
+
+The main interaction surface is the table itself.
+
+The table should not look like a form with permanently visible input fields in every cell.
+
+Cells are displayed as static text by default and become editable only when the user intentionally edits them.
+
+The editor should support both:
+
+- efficient keyboard-based editing
+- low-click mouse interaction
+- drag-and-drop workflows
+
+## Cell Editing
+
+Cells are displayed as static text by default.
+
+A cell enters edit mode when the user:
+
+- double-clicks it
+- presses Enter while it is selected
+- starts typing while it is selected
+- presses F2 while it is selected
+
+Editing behavior:
+
+- Enter confirms the edit
+- Tab confirms and moves to the next editable cell
+- Shift + Tab confirms and moves to the previous editable cell
+- Escape cancels the edit
+- Arrow keys navigate between cells when not editing
+- Arrow keys move the cursor inside text while editing
+
+## Row Insertion Shortcuts
+
+The editor should support fast row insertion.
+
+Required shortcuts:
+
+- Ctrl + Plus inserts a new row below the selected row
+- Ctrl + Shift + Plus should be treated the same where keyboard layouts require Shift for `+`
+- Insert may optionally insert a new row below the selected row
+
+Insert behavior:
+
+- if a circuit or row is selected, insert below it
+- if no row is selected, insert at the end of the active section
+- the new row should immediately focus the display name or device cell
+
+## Project Device Sidebar
+
+The distribution board editor should show the project device list near the circuit list.
+
+Preferred layout:
+
+- left sidebar: searchable project device list
+- right main area: circuit list table
+
+The project device sidebar should support:
+
+- search by name
+- filter by category
+- filter by phase type
+- filter by cost group
+- showing device name
+- showing default display name
+- showing phase type
+- showing quantity and power if available
+- dragging devices into the circuit list
+
+## Drag Project Device into Circuit List
+
+Project devices can be dragged from the project device sidebar into the circuit list.
+
+### Drop into a valid section or free circuit placeholder
+
+Creates a new circuit.
+
+The new circuit:
+
+- receives the next equipment identifier of the target section
+- is inserted at the drop position
+- contains one device row linked to the dragged project device
+- receives an initial display name copied from the project device
+- keeps this copied display name locally
+
+### Drop onto an existing circuit identifier / circuit target
+
+Adds the device to that existing circuit.
+
+The app creates another device row inside that circuit.
+
+The device row:
+
+- has no own equipment identifier
+- is linked to the project device
+- contributes to the circuit total power
+- appears indented when the circuit contains multiple devices
+
+## Free Circuit Placeholder
+
+Each section should show a free circuit placeholder at the end.
+
+Example:
+
+```text
+Lighting
+-1F1  Beleuchtung Flur
+-1F2  Beleuchtung Außen
+-frei-
+```
+
+If a device is dropped onto `-frei-`, a new circuit is created.
+
+After creation, a new `-frei-` placeholder appears at the end of the section.
+
+## Valid Drop Zones
+
+A project device may only be dropped into technically valid sections.
+
+Default rules:
+
+| Condition | Valid section | Prefix |
+|---|---|---|
+| Category = Lighting | Lighting | `-1F` |
+| Phase type = single-phase and not Lighting | Single-phase circuits | `-2F` |
+| Phase type = three-phase and not Lighting | Three-phase circuits | `-3F` |
+
+Invalid drop targets should visually reject the dragged item.
+
+If the user tries to move a device into another section, show a confirmation dialog.
+
+The dialog should explain that moving to another section may change technical classification fields such as:
+
+- phase type
+- category
+- numbering section
+
+The user can confirm or cancel.
+
+The app must not silently change project device data.
+
+## Drag Handle Behavior
+
+Different drag start areas trigger different behavior.
+
+### Drag from equipment identifier / circuit handle
+
+Moves the entire circuit.
+
+All device rows assigned to the circuit move together.
+
+The equipment identifier remains unchanged.
+
+### Drag from device area
+
+Moves only the selected device row or selected device rows.
+
+A device can be:
+
+- reordered inside the same circuit
+- moved to another existing circuit
+- moved into the next free circuit placeholder
+- moved to another valid section after confirmation
+
+## Moving Devices Between Circuits
+
+A device row can be moved from one circuit to another.
+
+When moved:
+
+- it is removed from the old circuit
+- it is assigned to the new circuit
+- it keeps its own device values
+- it contributes to the new circuit total
+- both old and new circuit totals are recalculated
+- no automatic renumbering happens
+
+## Convert Device to Own Circuit
+
+A device row can be moved to a free circuit placeholder.
+
+When this happens:
+
+- a new circuit is created
+- the device becomes the first device row of the new circuit
+- the new circuit receives the next equipment identifier in the section
+- a new free placeholder appears at the end
+
+## Multi-Row Selection and Dragging
+
+The table should support selecting multiple rows.
+
+Selection behavior:
+
+- Ctrl + click selects or deselects individual rows
+- Shift + click selects a continuous row range
+- selected rows can be dragged together
+
+When multiple selected device rows are moved:
+
+- they remain together
+- their internal order is preserved
+- they are inserted as one block
+
+When multiple selected circuits are moved:
+
+- each selected circuit moves with all assigned device rows
+- internal circuit/device structure is preserved
+- equipment identifiers remain unchanged unless explicitly renumbered
+
+Dropping rows at the end of a section compacts visual row order. It does not renumber equipment identifiers.
+
+## Delete Behavior
+
+Deleting a device row deletes only that device.
+
+The circuit itself remains as long as at least one device is assigned to it.
+
+If the first visible device of a circuit is deleted and other devices remain, the next device moves up visually.
+
+If the last device of a circuit is deleted, ask the user whether to:
+
+- keep the empty circuit as reserve
+- delete the circuit completely
+- cancel
+
+Deleting never triggers automatic renumbering.
+
+## Filtering and Sorting
+
+The table should support Excel-like filtering and sorting through column headers.
+
+### Filtering
+
+Each column header can open a filter menu.
+
+The filter menu shows available values in that column.
+
+The user can select one or more values.
+
+Examples:
+
+- filter by room number
+- filter by room name
+- filter by cost group
+- filter by category
+- filter by phase type
+- filter by connection type
+
+### Sorting
+
+Each column can be sorted ascending or descending.
+
+Sorting via table headers sorts complete circuits as blocks.
+
+A circuit and its assigned device rows stay together.
+
+Sorting must not split devices away from their circuit.
+
+Sorting changes only the visual order.
+
+Equipment identifiers are not changed by sorting.
+
+After sorting, the user may explicitly press "Renumber section".
+
+## Column Configuration
+
+The table should support configurable columns.
+
+Users can:
+
+- show columns
+- hide columns
+- reorder columns by drag and drop
+- reset to default column layout
+
+Column visibility and order should be stored per user or per project.
+
+Hidden columns remain stored and available for calculations.
+
+## Undo / Redo
+
+Undo and redo should be implemented from the beginning for structural and destructive operations.
+
+At minimum, undo / redo must support:
+
+- insert circuit
+- insert device
+- delete circuit
+- delete device
+- move circuit
+- move device
+- move multiple selected rows
+- renumber section
+- edit equipment identifier
+- edit cell value
+- synchronize linked project device fields
+- disconnect linked project device

docs/spec/05-linked-devices-and-sync.md

@@ -0,0 +1,127 @@
+# Linked Project Devices and Synchronization
+
+## Concept
+
+Circuit device rows may be linked to project devices.
+
+Manual rows may exist without a linked project device.
+
+A manual row can later be saved as a project device.
+
+## Name vs Display Name
+
+Project devices and circuit list device rows use separate naming fields.
+
+### ProjectDevice.name
+
+The technical or product-related name.
+
+Examples:
+
+- `E-Line Pro`
+- `Arbeitsplatzsteckdosen`
+- `Durchlauferhitzer 21 kW`
+
+This field may be synchronized to linked circuit list rows where a technical source name is shown.
+
+### ProjectDevice.displayName
+
+A default display name used when inserting the device into a circuit list.
+
+Example:
+
+- `Lichtband`
+- `Arbeitsplatzsteckdosen`
+- `Handtrockner`
+
+### CircuitDeviceRow.displayName
+
+The circuit-list-specific display name.
+
+Examples:
+
+- `Lichtband Seminarraum`
+- `Beleuchtung Flur`
+- `Steckdosen Arbeitsplatz Büro 2.14`
+
+When a project device is inserted, the row display name is prefilled from the project device.
+
+After insertion, `displayName` remains local and must not be synchronized automatically.
+
+## Default Synchronization Rule
+
+By default, these fields may be synchronized from project device to linked circuit list rows:
+
+- `name`
+- `phaseType`
+- `connectionKind`
+- `costGroup`
+- `category`
+- `quantity`
+- `powerPerUnit`
+- `simultaneityFactor`
+- `cosPhi`
+- `totalPower`
+- `remark`
+
+Default excluded field:
+
+- `displayName`
+
+## Synchronization Dialog
+
+When a project device is changed, the app should show a synchronization dialog.
+
+The dialog should display affected linked rows.
+
+For each affected row, show:
+
+- distribution board
+- section
+- circuit identifier
+- row display name
+- changed fields
+- current row value
+- new project device value
+- whether the row value was locally overridden
+
+The user can choose:
+
+- apply change to one linked row
+- apply change to all linked rows
+- exclude specific fields
+- disconnect selected linked rows from the project device
+- cancel synchronization
+
+The app must not silently overwrite locally edited values without user control.
+
+## Local Overrides
+
+A linked circuit device row may override inherited values locally.
+
+The implementation should track overridden fields.
+
+If a field is locally overridden, the synchronization dialog should mark it clearly.
+
+The user may still choose to overwrite it.
+
+## Disconnecting a Linked Device
+
+A linked device row can be disconnected from its source project device.
+
+After disconnecting:
+
+- the row remains in the circuit list
+- existing local values stay unchanged
+- future changes to the project device no longer affect this row
+
+## Manual Row to Project Device
+
+Manual rows can be saved as project devices.
+
+When this action is used:
+
+- create a new project device from the row data
+- link the row to the new project device
+- preserve the existing circuit list display name
+- apply synchronization rules from that point onward

docs/spec/06-future-sizing-and-calculations.md

@@ -0,0 +1,97 @@
+# Future Sizing and Calculation Requirements
+
+These requirements are not part of the first implementation, but the structure should support them.
+
+## Goal
+
+The app should later support rule-based protection and cable sizing.
+
+Future suggestions or checks may include:
+
+- protection device type
+- rated current
+- tripping characteristic
+- cable type
+- number of cores
+- cable cross-section
+- minimum cable cross-section based on current
+- maximum permissible cable length based on voltage drop
+- warning messages if cable length, cross-section or protection device do not match
+
+Users must remain able to manually override suggestions.
+
+## Initial Design Rule Examples
+
+These are common planning defaults, not a replacement for full norm-compliant calculation.
+
+### Lighting Circuits
+
+Lighting circuits in section `-1Fx` usually use:
+
+- protection rated current: 10 A
+- cable cross-section: 1.5 mm²
+
+Typical cable type:
+
+- non-DALI lighting: 3x1.5 mm²
+- DALI-capable lighting: 5x1.5 mm²
+
+The app should later suggest the cable type based on whether the connected luminaires require DALI or additional control cores.
+
+### Standard Single-Phase Circuits
+
+Standard single-phase circuits in section `-2Fx` usually use:
+
+- protection rated current: 16 A
+- cable cross-section: 2.5 mm²
+
+This applies to many typical socket circuits and standard single-phase loads.
+
+### Special Loads and Long Cable Runs
+
+For non-standard loads or long cable runs, voltage drop becomes more important.
+
+Examples:
+
+- instantaneous water heaters
+- socket combinations with higher connected load
+- outdoor circuits with long cable routes
+- lighting circuits with looped-through luminaires and cable lengths of 80 to 100 m
+
+The app should later show warnings or require review if voltage drop becomes critical.
+
+## Future Field: Control Requirement
+
+To support cable suggestions for lighting circuits, devices or circuits may later include a control requirement.
+
+Example values:
+
+- none
+- DALI
+- KNX
+- switched only
+- dimmable
+- other
+
+For lighting circuits:
+
+- no additional control cores: suggest 3x1.5 mm²
+- DALI required: suggest 5x1.5 mm²
+
+This must be configurable and manually overridable.
+
+## Future Voltage Drop Check
+
+A future voltage drop check may use:
+
+- phase type
+- voltage
+- circuit total power
+- apparent power or current
+- cable material
+- cable cross-section
+- cable length
+- protection rated current
+- allowed voltage drop
+
+The result should be shown as a warning or status indicator, not as an automatic forced change.

docs/spec/07-implementation-phases-todo.md

@@ -0,0 +1,241 @@
+# Implementation Phases and Todo List
+
+## Important Strategy
+
+There is already an existing codebase.
+
+Do not blindly continue with the current implementation if it conflicts with this specification.
+
+Do not blindly delete the current codebase either.
+
+First audit the existing code against this specification, then refactor or replace the parts that conflict with the target model.
+
+The most important architectural correction is:
+
+A circuit is not the same thing as one device row.
+
+A circuit contains zero, one or multiple device rows.
+
+## Phase 0: Audit Existing Codebase
+
+Goal:
+
+Determine which parts of the current codebase can be kept.
+
+Tasks:
+
+- identify current data model
+- identify whether rows are modeled as circuits, devices or mixed entities
+- identify hardcoded section logic
+- identify current drag-and-drop implementation
+- identify current table/editing implementation
+- identify current project device concept
+- identify persistence layer and migrations
+- list conflicts with the new specification
+- propose refactor plan before changing code
+
+Deliverable:
+
+- short audit report
+- keep/refactor/delete recommendation per major module
+
+## Phase 1: Core Data Model and Basic Table
+
+Goal:
+
+Implement the stable foundation.
+
+Tasks:
+
+- define sections
+- define circuits
+- define circuit device rows
+- define project devices
+- allow manual rows
+- allow empty/reserve circuits
+- calculate row total power
+- calculate circuit total power
+- display sections as separator rows
+- display single-device circuits as compact rows
+- display multi-device circuits with summary row and indented device rows
+- implement manual equipment identifier editing
+- implement next identifier generation as highest number + 1
+- prevent automatic renumbering
+
+Acceptance criteria:
+
+- a section can contain multiple circuits
+- a circuit can contain zero, one or multiple device rows
+- deleting a device does not automatically delete the circuit unless the user chooses so
+- circuit total power is calculated from all device rows
+- equipment identifiers are stable unless manually changed or explicitly renumbered
+
+## Phase 2: Spreadsheet-Like Editing
+
+Goal:
+
+Make the table efficient to edit.
+
+Tasks:
+
+- static text cells by default
+- inline editing on double click / Enter / typing / F2
+- Enter, Tab, Shift+Tab, Escape behavior
+- keyboard navigation
+- Ctrl + Plus row insertion
+- Ctrl + Shift + Plus support
+- Delete behavior
+- validation warnings for duplicate identifiers
+
+Acceptance criteria:
+
+- common values can be edited without opening full forms
+- keyboard workflow is usable for repetitive entry
+- accidental edits can be cancelled
+
+## Phase 3: Project Device Sidebar
+
+Goal:
+
+Allow dragging project devices into the circuit list.
+
+Tasks:
+
+- implement project device list
+- search project devices
+- filter project devices
+- show basic technical values
+- drag project device into valid section
+- drop onto free placeholder to create a circuit
+- drop onto existing circuit to add device
+- create linked device rows
+- prefill display name but keep it local after insertion
+
+Acceptance criteria:
+
+- project devices can create new circuits
+- project devices can be added to existing circuits
+- invalid sections reject drops or require confirmation
+- linked rows keep the source relationship
+
+## Phase 4: Drag-and-Drop Restructuring
+
+Goal:
+
+Allow restructuring circuits and device assignments.
+
+Tasks:
+
+- drag from circuit handle moves whole circuit
+- drag from device area moves device row
+- move device between circuits
+- move device to free placeholder to create new circuit
+- move circuit inside section
+- visual drop indicator
+- valid/invalid drop zone feedback
+- multi-row selection with Ctrl + click and Shift + click
+- multi-row drag preserving internal order
+
+Acceptance criteria:
+
+- circuits can be reordered without renumbering
+- devices can be reassigned to other circuits
+- circuit totals recalculate after moves
+- multi-row movement does not break circuit/device grouping
+
+## Phase 5: Filtering, Sorting and Columns
+
+Goal:
+
+Add Excel-like table management.
+
+Tasks:
+
+- filter menu per column header
+- sort ascending/descending per column
+- sorting circuits as complete blocks
+- preserve device grouping when sorting
+- column visibility configuration
+- column reorder by drag and drop
+- reset default column layout
+
+Acceptance criteria:
+
+- user can filter by room, cost group, category, phase type, etc.
+- user can sort within sections
+- sorting does not split circuits
+- sorting does not renumber
+- user can renumber explicitly after sorting
+
+## Phase 6: Undo / Redo
+
+Goal:
+
+Make structural editing safe.
+
+Tasks:
+
+- implement undo/redo stack
+- support insert circuit
+- support insert device
+- support delete circuit
+- support delete device
+- support move circuit
+- support move device
+- support multi-row move
+- support renumber section
+- support cell edits
+- support sync operations
+- support disconnect linked project device
+
+Acceptance criteria:
+
+- destructive changes can be reverted
+- renumbering can be undone
+- drag-and-drop restructuring can be undone
+
+Note:
+
+Undo/redo should be considered from the beginning. Implement technically as early as possible if the architecture allows it.
+
+## Phase 7: Linked Device Synchronization
+
+Goal:
+
+Control updates from project devices to circuit list rows.
+
+Tasks:
+
+- track linked project devices
+- track overridden fields
+- show affected rows when a project device changes
+- implement sync dialog
+- allow field-level selection
+- apply to one / selected / all linked rows
+- allow disconnecting selected rows
+
+Acceptance criteria:
+
+- displayName is not synchronized by default
+- user sees affected distribution boards and circuits
+- user controls which fields are overwritten
+- local values are not silently lost
+
+## Phase 8: Future Sizing Preparation
+
+Goal:
+
+Prepare for future electrical sizing logic.
+
+Tasks:
+
+- keep circuit-level protection and cable fields
+- keep voltage and cosPhi
+- support future control requirement
+- structure sizing rules separately from UI
+- add warning/status concept
+
+Acceptance criteria:
+
+- the codebase can later add rule-based sizing without redesigning circuits/devices
+- users can manually override calculated suggestions

docs/spec/08-codex-prompts.md

@@ -0,0 +1,200 @@
+# Codex Prompt Templates
+
+Use these prompts step by step. Do not ask Codex to build the whole application in one pass.
+
+## Prompt 1: Audit Existing Codebase
+
+```text
+Audit the existing codebase against the specification files in this repository.
+
+Focus on the distribution board circuit list editor.
+
+Do not write code yet.
+
+Produce a concise audit report with:
+
+1. current data model summary
+2. current UI/editor behavior summary
+3. current project device handling
+4. conflicts with the new specification
+5. modules/files that can be kept
+6. modules/files that should be refactored
+7. modules/files that should be replaced
+8. recommended implementation plan
+
+Important target model:
+- a circuit is not the same thing as one device row
+- a circuit contains zero, one or multiple device rows
+- sections are configurable grouping separators
+- equipment identifiers are stable and never automatically renumbered
+- protection and cable data belong to the circuit, not to individual devices
+
+Wait for confirmation before making code changes.
+```
+
+## Prompt 2: Implement Core Model
+
+```text
+Implement Phase 1 only.
+
+Goal:
+Create the core circuit list model and basic table display according to the specification.
+
+Required:
+- sections
+- circuits
+- circuit device rows
+- project devices
+- manual rows
+- reserve circuits
+- row total power calculation
+- circuit total power calculation
+- equipment identifier generation as highest existing number + 1
+- no automatic renumbering
+
+Do not implement advanced drag-and-drop yet.
+Do not implement sync dialog yet.
+Do not implement future cable/protection sizing yet.
+
+Before coding, propose the files you will change and the migration/data-model changes.
+```
+
+## Prompt 3: Spreadsheet-Like Editing
+
+```text
+Implement Phase 2 only.
+
+Goal:
+Make the circuit list table spreadsheet-like.
+
+Required:
+- static text cells by default
+- inline editing on double click, Enter, typing and F2
+- Enter confirms edit
+- Escape cancels edit
+- Tab and Shift+Tab navigate editable cells
+- Arrow keys navigate cells when not editing
+- Ctrl+Plus inserts a row
+- Ctrl+Shift+Plus also inserts a row
+- Delete behavior must be safe
+- duplicate equipment identifiers must be visually warned
+
+Do not change the domain model unless required.
+Do not implement unrelated features.
+```
+
+## Prompt 4: Project Device Sidebar and Drag Insert
+
+```text
+Implement Phase 3 only.
+
+Goal:
+Add the project device sidebar and drag insertion into the circuit list.
+
+Required:
+- searchable project device sidebar
+- draggable project device items
+- drop onto valid section/free placeholder creates a new circuit
+- drop onto existing circuit adds the device to that circuit
+- inserted row remains linked to the project device
+- displayName is prefilled but remains local after insertion
+- invalid drop zones must be rejected or require confirmation
+- existing equipment identifiers must not change
+
+Do not implement multi-row drag yet.
+Do not implement sync dialog yet.
+```
+
+## Prompt 5: Drag-and-Drop Restructuring
+
+```text
+Implement Phase 4 only.
+
+Goal:
+Support restructuring by drag and drop.
+
+Required:
+- dragging from circuit handle moves entire circuit
+- dragging from device area moves only the device row
+- device rows can move between circuits
+- device rows can move to the free placeholder to create a new circuit
+- moving rows recalculates affected circuit totals
+- no automatic renumbering
+- visual drop indicator
+- valid and invalid drop target feedback
+
+Then add multi-row selection and multi-row drag:
+- Ctrl+click
+- Shift+click
+- selected rows move together
+- internal order is preserved
+```
+
+## Prompt 6: Filtering, Sorting, Columns
+
+```text
+Implement Phase 5 only.
+
+Goal:
+Add Excel-like filtering, sorting and column configuration.
+
+Required:
+- filter menu per column header
+- filter by values present in the column
+- sort ascending/descending per column
+- sorting works inside sections
+- sorting moves complete circuits as blocks
+- sorting must not split devices away from their circuit
+- sorting must not renumber
+- column visibility configuration
+- column reorder by drag and drop
+- reset default column layout
+```
+
+## Prompt 7: Undo / Redo
+
+```text
+Implement Phase 6 only.
+
+Goal:
+Add undo/redo for structural and destructive operations.
+
+Required undo/redo support:
+- insert circuit
+- insert device
+- delete circuit
+- delete device
+- move circuit
+- move device
+- multi-row move
+- renumber section
+- edit equipment identifier
+- edit cell value
+- synchronize linked project device fields
+- disconnect linked project device
+
+Keep the implementation maintainable.
+Do not introduce global state management unless it is justified.
+```
+
+## Prompt 8: Linked Device Synchronization
+
+```text
+Implement Phase 7 only.
+
+Goal:
+Add controlled synchronization from project devices to linked circuit list rows.
+
+Required:
+- track linked rows
+- track overridden fields
+- when editing a project device, show affected linked rows
+- show distribution board, circuit identifier and row display name
+- show changed fields with old and new values
+- displayName excluded by default
+- user can apply changes to one, selected or all linked rows
+- user can exclude fields
+- user can disconnect linked rows
+
+Do not silently overwrite local values.
+```