From a86fc610e3478980887204e26d8fef09228b7ff0 Mon Sep 17 00:00:00 2001
From: mrhid6 <mrhid6@gmail.com>
Date: Fri, 7 Aug 2026 09:09:18 +0100
Subject: [PATCH] docs: document the workload registry

---
 docs/vantage/workloads.md | 90 +++++++++++++++++++++++++++++++++++++++
 sidebars.ts               |  1 +
 2 files changed, 91 insertions(+)
 create mode 100644 docs/vantage/workloads.md

diff --git a/docs/vantage/workloads.md b/docs/vantage/workloads.md
new file mode 100644
index 0000000..bef6975
--- /dev/null
+++ b/docs/vantage/workloads.md
@@ -0,0 +1,90 @@
+---
+id: workloads
+title: Workloads
+sidebar_label: Workloads
+---
+
+A **workload** is one Docker container or one systemd service. Each Linux
+server reports what it runs, and you can start, stop and restart those
+workloads — and read a snapshot of their logs — without opening a console.
+
+Available on every instance. No licence feature is required.
+
+## What gets reported
+
+Linux servers only. Agents report every 60 seconds, and an unchanged list costs
+a single small message rather than the whole thing again.
+
+- **Containers** — every container, running or not, with its image, published
+  ports, health, restart count and the compose stack it belongs to.
+- **Services** — systemd units that are running or failed, plus units that are
+  enabled but currently stopped. The platform's own units (`systemd-*`,
+  `user@*`, `session-*`) are filtered out; a typical host has 300 of them and
+  they bury the ten you care about.
+
+Windows servers report no workloads at all.
+
+## Docker not in use is not an error
+
+Three different things look identical if you are careless, and only one of them
+is a problem:
+
+| What you see | What it means |
+| ------------ | ------------- |
+| "Docker is not in use on this server" | Docker is not installed. Normal, and not a fault |
+| "Docker is installed but not responding" | The daemon is down or the socket is unreachable |
+| An empty container list | Docker is running and there are no containers |
+
+## Stacks are grouped
+
+Compose stacks appear first, grouped under the stack name, then loose
+containers, then services. A stack is one thing even when it is six containers,
+and a flat list turns one decision into six rows.
+
+The stack name comes from Docker's own `com.docker.compose.project` label. No
+compose file is read from disk — a file on disk may not be what is running.
+
+## Controlling a workload
+
+Start, stop and restart are **owner or admin only**, and every action is
+written to the audit log naming you, the server and the target.
+
+The agent refuses to act on itself. `vantage-agent.service` is shown with its
+buttons disabled: a server that stops its own agent goes offline, and the only
+way back is SSH or physical access — which is exactly what this page exists to
+avoid needing.
+
+A stop that never finishes is not reported as success. Both `docker stop` and
+`systemctl stop` run under a 90-second limit, and a timeout comes back as a
+real error.
+
+## Reading logs
+
+Logs are **owner or admin only** and every read is audited. Unlike workflow
+logs, a container's output cannot be masked: it is arbitrary, and a startup
+banner or a stack trace may contain credentials nobody declared.
+
+A log read returns a snapshot of at most **500 lines or 256KB**, whichever
+limit is reached first, with the most recent output kept. When either limit
+binds, the dialog says so — a truncated log must never be read as a complete
+one.
+
+There is no live following. The [browser console](./browser-console.md) already
+gives you a real terminal on the same server, where `docker logs -f` works
+properly with its own scrollback.
+
+## Refreshing
+
+Opening a server's Workloads panel asks its agent to report immediately, so
+what is on screen is current rather than up to a minute old. That matters
+because the panel has a Restart button on it: a stale row is not just a wrong
+impression, it is a wrong action aimed at something that already died.
+
+If the agent is offline the refresh fails visibly rather than queueing. A
+command whose target cannot be reached must say so.
+
+## Fleet view
+
+**Workloads** in the sidebar searches the whole fleet by image, stack or state
+— "which of these servers is still on the old image" — and links each result
+back to its server.
diff --git a/sidebars.ts b/sidebars.ts
index 716c1a4..7d5756d 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -27,6 +27,7 @@ const sidebars: SidebarsConfig = {
                 "vantage/workflows",
                 "vantage/monitors",
                 "vantage/vulnerabilities",
+                "vantage/workloads",
                 "vantage/notification-channels",
                 "vantage/secrets",
                 "vantage/browser-console",