docs: entity display names, live reload, and Docker watch limits (#1114)

docs/modules/ROOT/pages/config.adoc

@@ -37,7 +37,7 @@ All configuration options are covered in the solution sections
 | Option | Description | Default | Live Reloadable | Documentation
 
 | `actions` | The list of available actions. | `-` | Live Reloadable, but refreshing the web browser is recommended. | xref:action_examples/intro.adoc[Action examples]
-| `entities` | A list of "things" you can attach actions to. | `-` | Live Reloadable, but restart is recommended. | xref:entities/intro.adoc[Entities]
+| `entities` | A list of "things" you can attach actions to. | `-` | Entity data files reload live; new entity definitions in config reload live. Restart if removing types or changing file paths. | xref:entities/intro.adoc[Entities]
 | `dashboards` | A grouping of actions, with optional displays, or actions generated from entities. | `-` | Live Reloadable | xref:dashboards/intro.adoc[Dashboards]
 |===
 

docs/modules/ROOT/pages/entities/intro.adoc

@@ -7,7 +7,30 @@ This is really useful if you want to generate wake on lan or poweroff actions fo
 
 A very popular use case that entities were designed for was for `container` entities - in a similar way you could generate `start`, `stop`, and `restart` container actions.
 
-Entities are just loaded from files on disk, OliveTin will also watch these files for updates while OliveTin is running, and update entities.
+Entities are just loaded from files on disk. OliveTin watches these files for updates while it is running and refreshes dashboards, actions, and the Entities page when data changes.
+
+[#display-names]
+=== Display names
+
+Each entity instance needs a human-readable name in the UI. OliveTin picks the first matching string field from this list (case-insensitive field names):
+
+`title`, `name`, `id`, `hostname`, `host`, `label`
+
+If none of those fields contain a string value, the instance appears as **Untitled Entity**. Add one of those fields to every row in your entity file — for example `title: My Vehicle` or `name: server1`.
+
+The chosen field is shown as the instance name in lists and dashboards. On the entity details page, it appears in the page heading; see xref:entities/properties.adoc#entity-details-page[Entity details page] for which other fields are listed.
+
+[#entity-live-reload]
+=== Live reload
+
+* **Entity file content** — when a watched data file is updated on disk, OliveTin reloads instances and notifies the web UI. No restart is required.
+* **New entity types in `config.yaml`** — when you add a new entry under `entities:` and reload config, OliveTin starts watching that file without a full restart.
+* **Removing or renaming entity types** — restart OliveTin if you remove an entity definition or change its file path.
+
+[NOTE]
+====
+On **Docker Desktop for Windows**, bind-mounted entity files may not trigger file-watch events when updated from the host (for example by a cron job writing through a volume). If live reload does not pick up changes, restart the container after updating the file, run OliveTin on Linux, or write the file in place on the same filesystem OliveTin watches.
+====
 
 Entity data files can contain any fields you need. Those values are available in action templates as `{{ .CurrentEntity.field }}` — for example, `{{ .CurrentEntity.status }}` or `{{ .CurrentEntity.hostname }}`.
 

docs/modules/ROOT/pages/entities/json.adoc

@@ -3,10 +3,22 @@
 
 JSON files are parsed as if each line is a single JSON object. This can be super helpful for getting a list of containers, for example; `docker ps -a --format=json > /etc/OliveTin/containers.json`.
 
+== Display names in JSON
+
+OliveTin uses the first string value found in fields named `title`, `name`, `id`, `hostname`, `host`, or `label` as the instance name in the UI. Matching is case-insensitive. See xref:entities/intro.adoc#display-names[Display names] in the entities overview.
+
+Docker's JSON output uses `Names`, which is **not** one of those fields. Without `title` or `name`, OliveTin falls back to Docker's `ID` field (matched as `id`) and shows the container ID instead of the human-readable name. Either map `Names` when generating the file (for example with `jq` to add a `name` field) or include an explicit `title` or `name` key in each object.
+
+[source,json]
+.Example with an explicit display name
+----
+{"title":"media-indexing-container","ID":"4bafe6f9f956","Image":"fedora","State":"exited"}
+{"title":"media-playback-container","ID":"d25f37c49c35","Image":"fedora","State":"exited"}
+----
+
 [source,json]
-.`/etc/OliveTin/containers.json`
+.Raw `docker ps --format=json` lines (without `title` or `name`, OliveTin shows `ID` instead of `Names`)
 ----
 {"Command":"\"/opt/entrypoint.sh\"","CreatedAt":"2024-02-08 15:27:42 +0000 GMT","ID":"4bafe6f9f956","Image":"fedora","Labels":"?","LocalVolumes":"0","Mounts":"","Names":"media-indexing-container","Networks":"bridge","Ports":"","RunningFor":"13 days ago","Size":"0B","State":"exited","Status":"Exited (128) 13 days ago"}
 {"Command":"\"/opt/entrypoint.sh\"","CreatedAt":"2023-12-17 20:58:03 +0000 GMT","ID":"d25f37c49c35","Image":"fedora","Labels":"?","LocalVolumes":"0","Mounts":"","Names":"media-playback-container","Networks":"bridge","Ports":"","RunningFor":"27 days ago","Size":"0B","State":"exited","Status":"Exited (137) 27 days ago"}
 ----
-

docs/modules/ROOT/pages/entities/properties.adoc

@@ -61,9 +61,10 @@ When `properties` is configured, the Entities page shows a searchable, paginated
 
 When `properties` is omitted or empty, the Entities page shows a simple list of instance names and a total count instead of a table.
 
+[#entity-details-page]
 === Entity details page
 
-The entity details view shows only the fields listed in `properties`, plus type and title.
+The entity details view shows only the fields listed in `properties`, plus type. The instance name appears in the page title, not again in the field list.
 
 If `properties` is not configured, all top-level fields from the entity data file are shown.
 

docs/modules/ROOT/pages/entities/yaml.adoc

@@ -1,7 +1,9 @@
 [#entities-yaml]
 = YAML entity files
 
-YAML files are the default expected format, so you can use .yml, .yaml, or even .txt - as long as the file contains a valid yaml LIST, then it will be loaded. 
+YAML files are the default expected format, so you can use .yml, .yaml, or even .txt - as long as the file contains a valid yaml LIST, then it will be loaded.
+
+Each list item should include a display name field (`title`, `name`, `id`, `hostname`, `host`, or `label`). The example below uses `name`. See xref:entities/intro.adoc#display-names[Display names].
 
 .`/etc/OliveTin/servers.yaml`
 [source,yaml]
@@ -19,4 +21,3 @@ YAML files are the default expected format, so you can use .yml, .yaml, or even
   hostname: server3.example.com
   ip: 192.168.0.3
 ----
-