# Working on a Light module

This module extends Light, the simple admin for Mage-OS and Magento Open Source. The Light developer guide is the
authority: https://light.magerex.nl/llms-full.txt holds all of it as Markdown, and
https://light.magerex.nl/md/developer/<page>.md holds one page.

## Rules

- Register pool items as DI arguments in the area where core declares the pool. Almost every pool is in
  etc/adminhtml/di.xml; role_areas, role_presets and payment_switches go in etc/di.xml.
- Light pages live on the admin front name light. Join it in etc/adminhtml/routes.xml with
  <module name="Vendor_Module" before="Mrx_Light"/>, in a controller folder named after the module.
- Gate every item on the module it needs: the key module on array items, #[RequiresModule('Vendor_Module')] on
  classes and controllers, and \Proxy for object items whose constructor needs that module.
- Declare the Light API range in composer.json under extra.mrx-light-api: ^0.4 during the beta. A module with Light
  PHP repeats that range in the range guard of its registration.php.
- Name only @api Light types. Never edit app/code/Mrx, and never add a preference or a plugin on a Light class that
  isn't @api.
- CSS uses the --mrx-* tokens, never a literal colour. JavaScript is a RequireJS module: no inline scripts, no on*=
  attributes.
- Keep Light simple: place a screen under the section whose job it does, count only work (null at 0, tone
  attention), show only everyday settings in simple mode, set no default pins, and write warm Dutch with "je" in
  i18n/nl_NL.csv.
- Call an LLM through Disrex\Ai\Api\LlmClientInterface with a purpose of your own; the Settings > AI limits apply.

## Check your work

- bin/magento mrx:light:doctor --module=Vendor_Module reports no errors, private_api included.
- bin/magento cache:clean config layout after a change to di.xml or layout.
- The module's browser test skips itself while the module is disabled.