homeos/rules.md

rules.md — HomeOS STRICT RULES

Carried over 1:1 from the user's Clusev project. Non-negotiable. On any conflict between a rule and a request: STOP and ask. Full examples live in the Clusev rules.md; this is the compact, authoritative list.

Core rules

• R1 Pages = full-page class-based Livewire components mapped directly in routes/web.php. No page controllers.
• R2 Livewire class + separate Blade view. Volt forbidden (never make:volt).
• R3 All colors/design tokens in @theme (resources/css/app.css); markup uses token utilities only — no raw hex/rgb.
• R4 No inline style= — single exception: progress-bar width.
• R5 Destructive/confirm actions via wire-elements/modal — never confirm() / Alpine popups.
• R6 Files exactly per the folder map (handoff §7).
• R7 Responsive verified at 375 / 768 / 1280; touch targets ≥ 44 px.
• R8 Every PHP / Composer / Node / artisan command inside the container — the host has only Docker.
• R9 UI copy German, terse/operational, no emoji; status via color/dots/pills; technical tokens (MAC, IP, model) stay native.
• R10 Reuse @theme tokens + the Blade component kit — no ad-hoc colors/widgets.
• R11 URL-exposed records addressed by UUID, never integer PK (getRouteKeyName(): 'uuid').
• R12 Every touched page verified in a real browser: HTTP 200, zero console errors, zero failed requests; the loaded state of lazy pages (not the skeleton); inspect the rendered DOM for leaked @ / {{ }} / group.key literals. A green Livewire::test ≠ done.
• R13 Route paths + names English (/devices, not /geraete); German only in visible labels.
• R14 Fonts self-hosted (resources/fonts/*.woff2, relative url('../fonts/…') + @font-face) — no Google Fonts / CDN link or import.
• R15 Codex review (/codex:review) after every change — no errors, no security findings, else fix and re-run. Task not done until clean.
• R16 Every UI string localized in lang/{de,en}/<group>.php, identical keys in both languages, accessed via __('group.key') — no hard-coded copy anywhere.
• R17 Blade: block @php … @endphp only (no inline @php(...)); never write the literal directive tokens in comments/text.
• Secrets: .env*, tokens, keys are never staged; check git status before every commit. Feature branches, never commit directly to main.

HomeOS-specific additions

• H1 UI / Livewire never publishes to protocol topics directly — every command goes through DeviceCommandService → driver, and every command is written to the commands audit table.
• H2 MQTT subscriber callbacks: parse + dispatch only. No DB aggregation, no HTTP calls in the loop.
• H3 Vendor specifics (topics, payload shapes) live only in app/Support/Mqtt + app/Support/Drivers. Models, Livewire and views stay protocol-agnostic.
• H4 Telemetry writes go through one ingest path that enforces retention/compression policies.
• H5 Automations always carry cooldown_seconds; the engine has a dry-run mode (log instead of switch) for development — never develop automations against the live home.