JarbasAl · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026 · coderabbitai
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -63,6 +63,17 @@ DB, listener protocol) are injected via `init_injected_objects()`, so
 `/config/restart` works. In standalone admin mode those endpoints fall back to
 config-only / mock data, and restart is unavailable.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Every panel screen is this API with a face on it (widescreen)](img/dashboard.png)
+
+**Mobile**
+
+![Every panel screen is this API with a face on it (mobile)](img/dashboard-mobile.png)
+
 ---
 
 ## 1. Health & status

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -77,5 +77,16 @@ can consume. This would also let the panel run fully **out-of-process or remote*
 rather than only in-process. Until then, treat `/connections` live data as
 advisory and rely on the database-backed views for authoritative state.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Topology, the architecture as the running system sees it (widescreen)](img/topology.png)
+
+**Mobile**
+
+![Topology, the architecture as the running system sees it (mobile)](img/topology-mobile.png)
+
 ---
 [← Test Chat](test-chat.md) · [Home](index.md) · [Extending →](extending.md)
diff --git a/docs/bridges.md b/docs/bridges.md
@@ -75,5 +75,19 @@ you can revoke it like any other client (which immediately drops it).
 - Give bridges a recognizable client name. The `bridge:<platform>` tag is what
   the panel uses to label them, so keep it if you edit tags.
 
+
+### What it looks like
+
+Bridges are configured per bridge, but they all answer through the agent
+selected here:
+
+**Widescreen**
+
+![Agent Protocol, where the backend a bridge talks to is chosen (widescreen)](img/agents.png)
+
+**Mobile**
+
+![Agent Protocol, where the backend a bridge talks to is chosen (mobile)](img/agents-mobile.png)
+
 ---
 [← OVOS servers](ovos-servers.md) · [Home](index.md) · [Test Chat →](test-chat.md)
diff --git a/docs/cli.md b/docs/cli.md
@@ -89,5 +89,16 @@ Press `Ctrl-C` (SIGINT) to shut down cleanly. In the default hivemind-core + pan
 hivemind-core runs on the main thread and installs the SIGINT/SIGTERM handlers, so the signal
 is handled there and both hivemind-core and panel stop together.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Anything the CLI does to clients is visible here too (widescreen)](img/clients.png)
+
+**Mobile**
+
+![Anything the CLI does to clients is visible here too (mobile)](img/clients-mobile.png)
+
 ---
 [← Running](running.md) · [Home](index.md) · [Configuration →](configuration.md)
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -109,5 +109,24 @@ You now know the vocabulary. Next:
 - **[Tutorial](tutorial.md)** — do it all end-to-end.
 - **[Glossary](glossary.md)** — any term, defined.
 
+
+### What it looks like
+
+A persona is the character the hive answers as:
+
+![Personas: the character the hive answers as (widescreen)](img/personas.png)
+
+![Personas: the character the hive answers as (mobile)](img/personas-mobile.png)
+
+and the topology is every node currently attached:
+
+**Widescreen**
+
+<!-- duplicate screenshot removed -->
+
+**Mobile**
+
+![Topology: every node currently attached to the hive (mobile)](img/topology-mobile.png)
+
 ---
 [Home](index.md) · [Getting started →](getting-started.md)
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -84,7 +84,9 @@ speech configs as [presets](presets.md) and select them here.
 Which serialization encodings and ciphers clients may use. At least one of each must
 stay enabled.
 
-![Encodings &amp; ciphers](img/encodings.png)
+![Encodings and ciphers, widescreen](img/encodings.png)
+
+![Encodings and ciphers on a phone](img/encodings-mobile.png)
 
 ## Other config
 
@@ -151,5 +153,16 @@ client-impersonation variant that goes through the hub.
 The same persona JSON can be hosted over an OpenAI or Ollama HTTP API by
 **ovos-persona-server**. See [OVOS servers](ovos-servers.md).
 
+
+### What it looks like
+
+**Widescreen**
+
+![Presets: saved configurations you can apply in one click (widescreen)](img/presets.png)
+
+**Mobile**
+
+![Presets: saved configurations you can apply in one click (mobile)](img/presets-mobile.png)
+
 ---
 [← CLI](cli.md) · [Home](index.md) · [Plugin presets →](presets.md)
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -104,5 +104,24 @@ sudo systemctl enable --now hivemind-admin-panel
 This single unit runs hivemind-core and the panel together. Add `--no-core` to the
 `ExecStart` line if hivemind-core is managed by a separate service on the host.
 
+
+### What it looks like
+
+Audio streaming is configured in the binary protocol screen:
+
+![Binary Protocol: the audio transport and its STT, TTS and VAD plugins (widescreen)](img/binary.png)
+
+![Binary Protocol: the audio transport and its STT, TTS and VAD plugins (mobile)](img/binary-mobile.png)
+
+and the listeners a deployment exposes are here:
+
+**Widescreen**
+
+![Network: the listeners a deployment exposes (widescreen)](img/network.png)
+
+**Mobile**
+
+![Network: the listeners a deployment exposes (mobile)](img/network-mobile.png)
+
 ---
 [← Security](security.md) · [Home](index.md) · [OVOS servers →](ovos-servers.md)
diff --git a/docs/development.md b/docs/development.md
@@ -77,5 +77,16 @@ The end-to-end suite runs in `build-tests` and `coverage` on every PR.
   to `master`. `dev` is the default branch.
 - License: Apache-2.0. Keep the SPDX header on new source files.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Monitor: live message flow, the fastest way to see your change work (widescreen)](img/monitor.png)
+
+**Mobile**
+
+![Monitor: live message flow, the fastest way to see your change work (mobile)](img/monitor-mobile.png)
+
 ---
 [← API reference](api-reference.md) · [Home](index.md) · [Roadmap →](roadmap.md)
diff --git a/docs/extending.md b/docs/extending.md
@@ -112,5 +112,16 @@ hand-edit `version.py`, and work on a feature branch and let CI (the gh-automati
 workflows) run build-tests, coverage, lint, and license-check. See
 [Development](development.md).
 
+
+### What it looks like
+
+**Widescreen**
+
+![OpenVoiceOS Plugins: what the panel can install and configure (widescreen)](img/voice-plugins.png)
+
+**Mobile**
+
+![OpenVoiceOS Plugins: what the panel can install and configure (mobile)](img/voice-plugins-mobile.png)
+
 ---
 [← Architecture](architecture.md) · [Home](index.md) · [API reference →](api-reference.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -62,5 +62,16 @@ See [Running](running.md) for the difference between the two modes.
 - [API reference](api-reference.md): drive everything over REST.
 - [Deployment](deployment.md): Docker, Compose, or reverse proxy.
 
+
+### What it looks like
+
+**Widescreen**
+
+<!-- duplicate screenshot removed -->
+
+**Mobile**
+
+![The sign-in screen you meet first (mobile)](img/login-mobile.png)
+
 ---
 [← Concepts](concepts.md) · [Home](index.md) · [Tutorial →](tutorial.md)
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -133,5 +133,16 @@ Plain-language definitions of the terms a newcomer meets when running or operati
 
 **XDG config**: the XDG Base Directory convention the panel follows for on-disk state. The shared hivemind-core config is `server.json` at `~/.config/hivemind-core/server.json` (honoring `XDG_CONFIG_HOME`). Personas, database profiles, and server registries live under sibling `~/.config/...` paths. See [Configuration](configuration.md).
 
+
+### What it looks like
+
+**Widescreen**
+
+![Most terms in this glossary are labels on this screen (widescreen)](img/dashboard.png)
+
+**Mobile**
+
+![Most terms in this glossary are labels on this screen (mobile)](img/dashboard-mobile.png)
+
 ---
 [← Tutorial](tutorial.md) · [Home](index.md) · [Troubleshooting →](troubleshooting.md)
diff --git a/docs/img/acl-mobile.png b/docs/img/acl-mobile.png
diff --git a/docs/img/acl.png b/docs/img/acl.png
diff --git a/docs/img/agents-mobile.png b/docs/img/agents-mobile.png
diff --git a/docs/img/agents.png b/docs/img/agents.png
diff --git a/docs/img/binary-mobile.png b/docs/img/binary-mobile.png
diff --git a/docs/img/binary.png b/docs/img/binary.png
diff --git a/docs/img/chat-mobile.png b/docs/img/chat-mobile.png
diff --git a/docs/img/chat.png b/docs/img/chat.png
diff --git a/docs/img/clients-mobile.png b/docs/img/clients-mobile.png
diff --git a/docs/img/clients.png b/docs/img/clients.png
diff --git a/docs/img/dashboard-mobile.png b/docs/img/dashboard-mobile.png
diff --git a/docs/img/dashboard.png b/docs/img/dashboard.png
diff --git a/docs/img/database-mobile.png b/docs/img/database-mobile.png
diff --git a/docs/img/database.png b/docs/img/database.png
diff --git a/docs/img/encodings-mobile.png b/docs/img/encodings-mobile.png
diff --git a/docs/img/encodings.png b/docs/img/encodings.png
diff --git a/docs/img/login-mobile.png b/docs/img/login-mobile.png
diff --git a/docs/img/login.png b/docs/img/login.png
diff --git a/docs/img/monitor-mobile.png b/docs/img/monitor-mobile.png
diff --git a/docs/img/monitor.png b/docs/img/monitor.png
diff --git a/docs/img/nav-drawer-mobile.png b/docs/img/nav-drawer-mobile.png
diff --git a/docs/img/network-mobile.png b/docs/img/network-mobile.png
diff --git a/docs/img/network.png b/docs/img/network.png
diff --git a/docs/img/ops-mobile.png b/docs/img/ops-mobile.png
diff --git a/docs/img/ops.png b/docs/img/ops.png
diff --git a/docs/img/personas-mobile.png b/docs/img/personas-mobile.png
diff --git a/docs/img/personas.png b/docs/img/personas.png
diff --git a/docs/img/presets-mobile.png b/docs/img/presets-mobile.png
diff --git a/docs/img/presets.png b/docs/img/presets.png
diff --git a/docs/img/servers-mobile.png b/docs/img/servers-mobile.png
diff --git a/docs/img/servers.png b/docs/img/servers.png
diff --git a/docs/img/topology-mobile.png b/docs/img/topology-mobile.png
diff --git a/docs/img/topology.png b/docs/img/topology.png
diff --git a/docs/img/voice-plugins-mobile.png b/docs/img/voice-plugins-mobile.png
diff --git a/docs/img/voice-plugins.png b/docs/img/voice-plugins.png
diff --git a/docs/index.md b/docs/index.md
@@ -10,6 +10,17 @@ New here? Read **[Concepts](concepts.md)** first, then follow the
 
 ![Dashboard](img/dashboard.png)
 
+
+### What it looks like
-### What it looks like
+## What it looks like
-### What it looks like
+## What it looks like
+
+**Widescreen**
+
+<!-- duplicate screenshot removed -->
+
+**Mobile**
+
+![The dashboard: security posture, live counts, and the plugins in use (mobile)](img/dashboard-mobile.png)
+
 ---
 
 ## Zero to running (newcomers)
@@ -23,7 +34,11 @@ Start here if you've never run HiveMind. No prior knowledge assumed.
    your first satellite with a QR code, lock it down with an ACL, give it a
    personality, and watch messages flow live.
 4. **[Glossary](glossary.md)**: every term, defined.
-5. **[Troubleshooting & FAQ](troubleshooting.md)**: when something does not work.
+5. **[Troubleshooting & FAQ](troubleshooting.md)**: when something does not
+   work. Covers the failures people actually hit — a reinstalled satellite that
+   will not reconnect, two services fighting over port 5678, an upgrade that
+   leaves the hub on an old version, and a crash loop after a plugin goes
+   missing.
 
 ## Operate it (running a real deployment)
 

diff --git a/docs/operations.md b/docs/operations.md
@@ -137,5 +137,24 @@ gracefully.
 - **Config dry-run**: `POST /config/diff` previews added, removed, and changed keys
   before you apply a config.
 
+
+### What it looks like
+
+The client store behind all of it:
+
+![Database: the client storage backend (widescreen)](img/database.png)
+
+![Database: the client storage backend (mobile)](img/database-mobile.png)
+
+and the operations screen itself:
+
+**Widescreen**
+
+![Operations: restart, backups, and log inspection (widescreen)](img/ops.png)
+
+**Mobile**
+
+![Operations: restart, backups, and log inspection (mobile)](img/ops-mobile.png)
+
 ---
 [← Plugin presets](presets.md) · [Home](index.md) · [Security →](security.md)
diff --git a/docs/ovos-servers.md b/docs/ovos-servers.md
@@ -79,5 +79,16 @@ agent/STT/TTS/database plugins hivemind-core uses.
 - The broader OVOS server list also includes `ovos-bus-server`, `ovos-ww-server`,
   and `ovos-opendata-server`.
 
+
+### What it looks like
+
+**Widescreen**
+
+![OVOS Servers: the STT, TTS and other services in use (widescreen)](img/servers.png)
+
+**Mobile**
+
+![OVOS Servers: the STT, TTS and other services in use (mobile)](img/servers-mobile.png)
+
 ---
 [← Deployment](deployment.md) · [Home](index.md) · [Chat bridges →](bridges.md)
diff --git a/docs/presets.md b/docs/presets.md
@@ -63,5 +63,16 @@ restart):
 Types: `stt` · `tts` · `ww` · `vad` · `agent` · `network`. Stored under
 `~/.config/hivemind-core/plugin_presets/{type}/{name}.json`.
 
+
+### What it looks like
+
+**Widescreen**
+
+<!-- duplicate screenshot removed -->
+
+**Mobile**
+
+![Presets: saved configurations you can apply in one click (mobile)](img/presets-mobile.png)
+
 ---
 [← Configuration](configuration.md) · [Home](index.md) · [Operations →](operations.md)
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -56,5 +56,16 @@ to hivemind-core. In `--no-core` mode these degrade gracefully (no live hivemind
 - Passwords now support PBKDF2 hashes (`pbkdf2_sha256$...`) while still accepting
   legacy plaintext for back-compat. Change one through `POST /auth/password`.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Where the panel stands today (widescreen)](img/dashboard.png)
+
+**Mobile**
+
+![Where the panel stands today (mobile)](img/dashboard-mobile.png)
+
 ---
 [← Development](development.md) · [Home](index.md)
diff --git a/docs/running.md b/docs/running.md
@@ -76,5 +76,16 @@ hivemind-admin-panel --no-core --reload
 | `--reload` | off | dev auto-reload (implies `--no-core`) |
 | `--log-level` | `INFO` | log level for the in-process hivemind-core |
 
+
+### What it looks like
+
+**Widescreen**
+
+<!-- duplicate screenshot removed -->
+
+**Mobile**
+
+![The dashboard reports which run mode the panel is in (mobile)](img/dashboard-mobile.png)
+
 ---
 [← Troubleshooting](troubleshooting.md) · [Home](index.md) · [CLI →](cli.md)
diff --git a/docs/security.md b/docs/security.md
@@ -105,5 +105,16 @@ These are known and worth accounting for when deploying:
 3. Network-isolate the host; the panel and the OVOS bus it can reach are trusted
    surfaces.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Permissions: what each client is allowed to send (widescreen)](img/acl.png)
+
+**Mobile**
+
+![Permissions: what each client is allowed to send (mobile)](img/acl-mobile.png)
+
 ---
 [← Operations](operations.md) · [Home](index.md) · [Deployment →](deployment.md)
diff --git a/docs/test-chat.md b/docs/test-chat.md
@@ -69,5 +69,16 @@ or an [OVOS server](ovos-servers.md), or run your OVOS skills.
 
 See the [API reference](api-reference.md) for details.
 
+
+### What it looks like
+
+**Widescreen**
+
+![Test Chat: talk to the hive without a satellite (widescreen)](img/chat.png)
+
+**Mobile**
+
+![Test Chat: talk to the hive without a satellite (mobile)](img/chat-mobile.png)
+
 ---
 [← Chat bridges](bridges.md) · [Home](index.md) · [Architecture →](architecture.md)