Config repository structure

A Home Assistant config repo is just a git repository whose root sits at /config inside the running HA instance. Below is the layout Craftama Smart Home expects when it tracks an instance — most of it is plain HA convention, with a couple of extras (vendir, ESPHome includes) that streamline custom components.

Required files

Path	Type	Purpose
`configuration.yaml`	YAML	Main entry point. Loads core config, splits per-domain blocks, includes packages.
`secrets.yaml`	YAML	Secret values referenced via `!secret name`. Never committed to a public repo — use `.gitignore`.
`.gitignore`	Other	At minimum: `secrets.yaml`, `.db`, `home-assistant_v2.db`, `.storage/`, `deps/`, `tts/`, `www/community/`.

Conventional split

Path	Type	Purpose
`automations.yaml`	YAML	Automations (UI-editable when referenced as `automation: !include automations.yaml`).
`scripts.yaml`	YAML	Reusable scripts.
`scenes.yaml`	YAML	Scenes (entity-state snapshots).
`scripts/`	YAML	Hand-edited scripts split per file (`scripts: !include_dir_merge_named scripts/`).
`packages/`	YAML	Self-contained domain packages, included via `homeassistant.packages: !include_dir_named packages/`.
`lights/` · `climate/` · `media_players/`	YAML	Per-domain or per-room splits. Often loaded as packages.
`templates/`	Jinja	Reusable Jinja templates referenced from automations / scripts.
`themes/`	YAML	UI themes. Linked by `frontend.themes: !include_dir_merge_named themes/`.
`dashboards/`	YAML	Lovelace YAML dashboards (declared under `lovelace.dashboards`).

Custom components & frontend

Path	Type	Purpose
`custom_components/`	Python	HACS-style or hand-installed integrations. Each subdir is one integration with its own `manifest.json`.
`www/`	Other	Static assets served at `/local/`. Custom Lovelace cards live under `www/custom_lovelace/`.
`blueprints/`	YAML	Blueprint sources (automation, script, template). Imported via UI or shared via the community.
`vendir.yml`	YAML	Declarative manifest of upstream sources (GitHub release tags + paths). `vendir sync` populates the dirs above. Craftama parses this file to populate the custom-component catalog.

ESPHome (optional)

Path	Type	Purpose
`esphome/`	YAML	Per-device ESPHome configs (`kitchen.yaml`, `garage.yaml`, …).
`esphome/components/`	Python	Custom ESPHome components vendored in.
`esphome/includes/`	YAML	Re-usable YAML/header snippets pulled in via `!include`.
`esphome/packages/`	YAML	Re-usable ESPHome package fragments (mixins, common sensors).

AppDaemon (optional)

If you outgrow Home Assistant's YAML-only automation, AppDaemon lets you write Python automations against the same state machine. The convention used by the Craftama config layout:

Path	Type	Purpose
`appdaemon/`	YAML	AppDaemon root. `appdaemon.yaml` wires HA + MQTT plugins, log levels, dashboard.
`appdaemon/apps/`	Python	Each subdir is one AppDaemon app (e.g. `appdaemon/apps/controllerx`). Each app has its own `apps.yaml` declaring class, module, and config.
`appdaemon/apps/controllerx`	Python	Example: ControllerX — turns dimmable Z2M / Zigbee remotes into multi-tap, hold-to-dim, scene-cycle controllers without writing automations. Vendir entry: `githubRelease.slug: xaviml/controllerx` → `appdaemon/apps/controllerx/`.
`appdaemon/dashboards/`	YAML	Optional HADashboard panels (legacy — most installs run Lovelace instead).

Connecting to Craftama

When you onboard an instance via /config/onboard/, Craftama clones the repo using your SSH deploy key and tracks every file in this layout. Custom components imported via vendir.yml automatically appear in the custom integrations catalog.