Initial commit

docs/config_schema.md

@@ -0,0 +1,87 @@
+# Config Schema
+
+## Primary File
+
+The example project file is [config/project.example.toml](../config/project.example.toml).
+
+## Root Objects
+
+- `metadata`
+- `topology`
+- `transport_profiles`
+- `safety_profiles`
+- `presets`
+
+## `metadata`
+
+- `project_name`
+- `schema_version`
+- `default_transport_profile`
+- `default_safety_profile`
+
+## `topology`
+
+- `expected_node_count`
+- `outputs_per_node`
+- `leds_per_output`
+- `nodes`
+- `layout_panels`
+- `groups`
+
+## `topology.nodes[]`
+
+- `node_id`
+- `display_name`
+- `network.reserved_ip`
+- `network.telemetry_label`
+- `outputs`
+
+## `topology.nodes[].outputs[]`
+
+Required:
+
+- `panel_position`
+- `physical_output_name`
+- `driver_channel.kind`
+- `driver_channel.reference`
+- `led_count`
+- `direction`
+- `color_order`
+- `enabled`
+- `validation_state`
+
+Optional:
+
+- `logical_panel_name`
+
+## Activation Rules
+
+Structural validation accepts `pending_validation` so the system can model unresolved wiring.
+
+Activation validation rejects any output that is still:
+
+- `driver_channel.kind = "pending_validation"`
+- `validation_state != "validated"`
+
+This is intentional and prevents accidental deployment against guessed hardware assumptions.
+
+## Groups
+
+`topology.groups[]` keeps grouping explicit and simple:
+
+- `group_id`
+- `tags`
+- `members[] = { node_id, panel_position }`
+
+## Layout
+
+`topology.layout_panels[]` is optional and only needed for preview or spatial effects:
+
+- `node_id`
+- `panel_position`
+- `row`
+- `column`
+- `rotation_degrees`
+- `mirror_x`
+- `mirror_y`
+