diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index ac12883..9e6d7da 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -98,6 +98,8 @@
 ** xref:logs/queue.adoc[Queue view]
 ** xref:logs/saving.adoc[Saving logs]
 * xref:entities/intro.adoc[Entities]
+** xref:entities/properties.adoc[Entity Properties]
+** xref:entities/icons.adoc[Entity Icons]
 ** xref:entities/examples.adoc[Examples]
 ** xref:entities/yaml.adoc[YAML Entity Files]
 ** xref:entities/json.adoc[JSON Entity Files]
diff --git a/docs/modules/ROOT/pages/entities/icons.adoc b/docs/modules/ROOT/pages/entities/icons.adoc
new file mode 100644
index 0000000..2a1635d
--- /dev/null
+++ b/docs/modules/ROOT/pages/entities/icons.adoc
@@ -0,0 +1,115 @@
+[#entity-icons]
+= Entity icons
+
+The `icon` field is configured on each entity definition in `config.yaml`. It sets an icon for the entity *type* (for example, all `server` instances share the same icon).
+
+Entity icons use the same icon system as actions. See xref:action_customization/icons.adoc[Icons] for the full range of supported formats — Unicode aliases, HTML entities, Iconify, image paths, and custom-webui assets.
+
+== Configuration
+
+Add `icon` under an entity definition alongside `file`, `name`, and `properties`:
+
+[source,yaml]
+----
+entities:
+  - file: /etc/OliveTin/servers.yaml
+    name: server
+    icon: ssh
+    properties:
+      - name: hostname
+        title: Hostname
+
+  - file: /etc/OliveTin/containers.json
+    name: container
+    icon: <iconify-icon icon="logos:docker-icon"></iconify-icon>
+----
+
+If `icon` is omitted or empty, no icon is shown for that entity type. Unlike actions, entity types do not get a default icon.
+
+=== Short-name aliases
+
+OliveTin resolves a few common short names to Unicode HTML entities at config load time. These are convenient for entity types that match common action categories:
+
+[cols="1,1", options="header"]
+|===
+| Alias | Typical use
+
+| `ssh`
+| Servers accessed over SSH
+
+| `ping`
+| Network hosts
+
+| `box`
+| Containers or packages
+
+| `backup`
+| Backup targets
+
+| `restart` / `reboot`
+| Systems or services
+
+| `light`
+| Lights or switches
+
+| `robot`
+| Automation targets
+|===
+
+The full alias list is in the xref:action_customization/icons.adoc#icons[Icons] documentation and in the source file `service/internal/config/emoji.go`.
+
+=== Custom-webui image paths
+
+A path containing `/` (that does not start with `<`) is expanded to an `<img>` tag pointing at `/custom-webui/`. For example, `icons/server.png` becomes an image served from `<config-dir>/custom-webui/icons/server.png`.
+
+== Where icons appear
+
+Entity icons are shown in the web UI next to the entity type name, not next to individual instances.
+
+=== Entities page
+
+On the Entities page, each entity type section heading shows the configured icon beside the type name (for example, `Entity: server`).
+
+=== Entity details page
+
+When viewing a single entity instance, the icon appears in the page title beside the instance name. The icon comes from the entity type definition, not from fields in the entity data file.
+
+=== API
+
+The `icon` field is included on:
+
+* `EntityDefinition` — returned by `GetEntities` for each entity type
+* `Entity` — returned by `GetEntity` for a single instance (same type-level icon)
+
+== What entity icons do not affect
+
+* **Individual instances** — icons are per entity type in `config.yaml`, not per row in the entity data file. You cannot give `server1` a different icon from `server2` through entity configuration alone.
+* **Dashboards** — entity fieldsets and directories use their own `icon` fields on dashboard components. See xref:dashboards/intro.adoc[Dashboards].
+* **Action buttons** — actions have their own `icon` field. An entity-bound action does not inherit the entity type icon automatically.
+
+== Example
+
+[source,yaml]
+----
+entities:
+  - file: entities/servers.yaml
+    name: server
+    icon: ssh
+    properties:
+      - name: hostname
+        title: Hostname
+      - name: ip
+        title: IP
+
+  - file: entities/containers.json
+    name: container
+    icon: box
+----
+
+With this configuration, the Entities page shows a key icon beside the `server` section and a box icon beside the `container` section. Opening any server instance shows the same key icon in the details page title.
+
+== What's next?
+
+* xref:action_customization/icons.adoc[Icons] — full icon format reference (Iconify, Unicode, images, and offline hosting)
+* xref:entities/intro.adoc[Entities] — overview of entities in OliveTin
+* xref:entities/properties.adoc[Entity properties] — configure which fields appear in the entity list
diff --git a/docs/modules/ROOT/pages/entities/intro.adoc b/docs/modules/ROOT/pages/entities/intro.adoc
index 401a2a2..42cd355 100644
--- a/docs/modules/ROOT/pages/entities/intro.adoc
+++ b/docs/modules/ROOT/pages/entities/intro.adoc
@@ -9,7 +9,9 @@ A very popular use case that entities were designed for was for `container` enti
 
 Entities are just loaded from files on disk, OliveTin will also watch these files for updates while OliveTin is running, and update entities.
 
-Entities can have properties defined in those files, and those can be used in your configuration as variables. For example; `container.status`, or `vm.hostname`.
+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 }}`.
+
+To control which fields appear in the Entities page table and entity details view, configure `properties` on the entity definition in `config.yaml`. See xref:entities/properties.adoc[Entity properties] for details.
 
 [source,yaml]
 ----
@@ -19,6 +21,12 @@ entities:
 
   - file: /etc/OliveTin/servers.yaml
     name: server
+    icon: ssh
+    properties:
+      - name: hostname
+        title: Hostname
+      - name: ip
+        title: IP
 ----
 
 Entity Actions can only be used on xref:dashboards/intro.adoc[Dashboards].
@@ -27,6 +35,8 @@ Entity Actions can only be used on xref:dashboards/intro.adoc[Dashboards].
 
 Now that you understand entities, here's how to use them effectively:
 
+* xref:entities/properties.adoc[Configure entity properties] - Choose which fields appear in the UI and API
+* xref:entities/icons.adoc[Configure entity icons] - Set an icon for each entity type
 * xref:entities/yaml.adoc[Create YAML entity files] - Learn the YAML format for entity files
 * xref:entities/json.adoc[Create JSON entity files] - Learn the JSON format for entity files
 * xref:entities/examples.adoc[View entity examples] - See complete examples of entity configurations
diff --git a/docs/modules/ROOT/pages/entities/properties.adoc b/docs/modules/ROOT/pages/entities/properties.adoc
new file mode 100644
index 0000000..4f89c4d
--- /dev/null
+++ b/docs/modules/ROOT/pages/entities/properties.adoc
@@ -0,0 +1,120 @@
+[#entity-properties]
+= Entity properties
+
+The `properties` field is configured on each entity definition in `config.yaml`. It does not live in the entity data files themselves.
+
+Use it to choose which fields from your entity data files are shown in the web UI and API. Property *values* come from the entity file on disk; `properties` only controls which of those values OliveTin exposes when listing or viewing entities.
+
+== Configuration
+
+Add `properties` under an entity definition alongside `file`, `name`, and `icon`:
+
+[source,yaml]
+----
+entities:
+  - file: /etc/OliveTin/servers.yaml
+    name: server
+    icon: ssh
+    properties:
+      - name: hostname
+        title: Hostname
+      - name: ip
+        title: IP
+----
+
+Each entry has two fields:
+
+[cols="1,3", options="header"]
+|===
+| Field | Description
+
+| `name`
+| The key to read from each entity instance in the data file. Matching is case-insensitive.
+
+| `title`
+| The column heading shown in the entity list table. If omitted, OliveTin uses `name`.
+|===
+
+The entity data file supplies the values. For example, with the configuration above and this data file:
+
+[source,yaml]
+.`/etc/OliveTin/servers.yaml`
+----
+- name: server1
+  hostname: server1.example.com
+  ip: 192.168.0.1
+- name: server2
+  hostname: server2.example.com
+  ip: 192.168.0.2
+----
+
+OliveTin shows `server1` and `server2` as instance names (from the `name` field) and displays `hostname` and `ip` in the configured columns.
+
+== Effects
+
+=== Entity list in the web UI
+
+When `properties` is configured, the Entities page shows a searchable, paginated table for that entity type. Columns are:
+
+* **Name** — the instance title (derived from fields such as `name`, `title`, `hostname`, and so on)
+* One column per configured property, labelled with `title`
+
+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
+
+The entity details view shows only the fields listed in `properties`, plus type and title.
+
+If `properties` is not configured, all top-level fields from the entity data file are shown.
+
+=== API responses
+
+`properties` controls which fields appear in `fields` on entity instances returned by the API:
+
+* `GetEntity` — returns only configured property values in `fields` when `properties` is set; otherwise returns all top-level fields from the data file.
+* `GetEntities` — always includes the property definitions on `EntityDefinition`. When `properties` is set, instance rows in list responses include only those configured fields. The unfiltered list request omits instance rows (it returns `totalInstances` only); use a filtered request with `entityType` to fetch paginated instances for the table view.
+
+Search and pagination on the entity list operate over instance titles and the configured property values.
+
+=== What `properties` does not affect
+
+`properties` is a display and API filtering setting. It does **not** limit what you can use in action templates.
+
+Actions bound to an entity still have access to the full entity record through `{{ .CurrentEntity.field }}`, including fields you did not list under `properties`. See xref:args/templates.adoc[Templates in actions] and xref:action_customization/enabledExpression.adoc[Enabled Expression].
+
+Legacy template syntax such as `{{ server.hostname }}` is still migrated automatically to `{{ .CurrentEntity.hostname }}`.
+
+== Example
+
+This configuration pairs with the server data file shown above:
+
+[source,yaml]
+----
+entities:
+  - file: entities/servers.yaml
+    name: server
+    icon: ssh
+    properties:
+      - name: hostname
+        title: Hostname
+      - name: ip
+        title: IP
+----
+
+An action can still reference any field from the data file, even ones not listed in `properties`:
+
+[source,yaml]
+----
+actions:
+  - title: Wake server
+    shell: wakeonlan {{ .CurrentEntity.ip }}
+    entity: server
+----
+
+== What's next?
+
+* xref:entities/yaml.adoc[YAML entity files] — format for entity data files
+* xref:entities/json.adoc[JSON entity files] — line-delimited JSON entity files
+* xref:entities/icons.adoc[Entity icons] — configure an icon for each entity type
+* xref:entities/intro.adoc[Entities] — overview of entities in OliveTin
+* xref:dashboards/entity-directories.adoc[Entity directories] — generate per-entity dashboards