docs: entity display names, live reload, and Docker watch limits

Document which fields become entity instance names, clarify JSON vs
docker field names, describe live reload behaviour for entity files and
new config entries, and note Docker Desktop file-watch limitations.

Part of #996

Co-authored-by: Cursor <cursoragent@cursor.com>

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. It is not repeated again in the entity details field list.
+
+[#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 (from OliveTin 3k builds including the #996 live-reload fix).
+* **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. 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. Either map it 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 (add `title` or `name` for OliveTin display 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

@@ -63,7 +63,7 @@ When `properties` is omitted or empty, the Entities page shows a simple list of
 
 === 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
 ----
-