Repository Guidelines

Project Structure & Module Organization

LuCI apps (luci-app-secubox, luci-app-*) store views in htdocs/luci-static/resources and RPC logic in root/usr/libexec/rpcd; package/secubox/ holds the SDK-ready copies of those modules.
luci-theme-secubox, templates/, and plugins/ provide shared CSS, gradients, and widgets that should be referenced via require secubox/* instead of duplicating assets.
Automation lives in secubox-tools/, scripts/, and the deploy-*.sh wrappers, while documentation sits in docs/ (MkDocs) and DOCS/ (deep dives).

./secubox-tools/local-build.sh build <module> performs cached SDK builds; use make package/<module>/compile V=s when reproducing CI exactly.
./secubox-tools/validate-modules.sh must pass before commits; it checks RPC naming, menu paths, permissions, JSON, and orphaned views.
./secubox-tools/quick-deploy.sh --profile luci-app --src luci-app-secubox syncs both root/ and htdocs/ trees to a router; add --list-apps to discover valid IDs or --app <name> to target one.
./deploy-to-router.sh rebuilds secubox-core + luci-app-secubox-admin, uploads the latest IPKs to $ROUTER_IP, installs them, and restarts rpcd.

LuCI views stick with ES5: 'use strict';, grouped 'require ...', tab indentation, and return view.extend({ ... }) + E('div', ...) rendering; move business logic into helpers like secubox/api.
Menu JSON "path": \"system-hub/overview\" must resolve to htdocs/.../view/system-hub/overview.js, and RPC scripts inside root/usr/libexec/rpcd/ must match their ubus object names while shipping with executable (755) permissions.
Run ./secubox-tools/fix-permissions.sh --local to keep CSS/JS files at 644, and keep design vocabulary consistent (sh-*, sb-*, Inter/JetBrains fonts, gradients stored in theme files).

Run ./secubox-tools/validate-modules.sh plus jsonlint file.json and shellcheck root/usr/libexec/rpcd/* for every touchpoint.
Execute scripts/smoke_test.sh on hardware to confirm Zigbee2MQTT services, container health, and MQTT.
Drop test-direct.js or test-modules-simple.js into LuCI to verify menu wiring, then remove the file and record any ubus -S call luci.secubox ... commands in the PR.

Follow the observed history style: type(scope): change (e.g., fix(luci-app-secubox-admin): add RPC fallback).
PRs must highlight the affected module, list the validation commands run, and attach screenshots for UI tweaks.
Link issues or TODO entries, update docs/ + DOCS/ when behavior or APIs change, and call out router IP assumptions.

Run the validator and ./secubox-tools/fix-permissions.sh --local before pushing to avoid HTTP 403s, and restart rpcd plus purge LuCI caches (rm -f /tmp/luci-*) if you skip deploy-to-router.sh.