docs: refresh API token scope guidance

docs/API.md

@@ -319,7 +319,7 @@ GET /install-docker-agent.sh          # Download the installation convenience sc
 GET /download/pulse-docker-agent      # Download the standalone Docker agent binary
 ```
 
-Agent routes require authentication. Use an API token or an authenticated session when calling them from automation. The payload reports restart loops, exit codes, memory pressure, and health probes per container, and Pulse de-duplicates heartbeats per agent ID so you can fan out to multiple Pulse instances safely. Host responses mirror the `/api/state` data, including `issues`, `recentExitCodes`, and `lastSeen` timestamps so external tooling can mimic the built-in Docker workspace.
+Agent routes require authentication. Use an API token or an authenticated session when calling them from automation. When authenticating with tokens, grant `docker:report` for `POST /api/agents/docker/report`, `docker:manage` for Docker host lifecycle endpoints, and `host-agent:report` for host agent submissions. The payload reports restart loops, exit codes, memory pressure, and health probes per container, and Pulse de-duplicates heartbeats per agent ID so you can fan out to multiple Pulse instances safely. Host responses mirror the `/api/state` data, including `issues`, `recentExitCodes`, and `lastSeen` timestamps so external tooling can mimic the built-in Docker workspace.
 
 ## Monitoring Data
 
@@ -491,7 +491,9 @@ Request body:
 #### API Token Management
 Manage API tokens for automation workflows, Docker agents, and tool integrations.
 
-Authentication: Requires an admin session or an existing admin-scoped API token.
+Authentication: Requires an admin session or an API token with the scope(s) below:
+- `settings:read` for `GET /api/security/tokens`
+- `settings:write` for `POST /api/security/tokens` and `DELETE /api/security/tokens/{id}`
 
 **List tokens**
 ```bash
@@ -508,7 +510,8 @@ Response:
       "prefix": "pulse_1a2b",
       "suffix": "c3d4",
       "createdAt": "2025-10-14T12:12:34Z",
-      "lastUsedAt": "2025-10-14T12:21:05Z"
+      "lastUsedAt": "2025-10-14T12:21:05Z",
+      "scopes": ["docker:report", "monitoring:read"]
     }
   ]
 }
@@ -519,10 +522,13 @@ Response:
 POST /api/security/tokens
 Content-Type: application/json
 {
-  "name": "ansible"
+  "name": "ansible",
+  "scopes": ["monitoring:read"]
 }
 ```
 
+> Omit the `scopes` field to mint a full-access token (`["*"]`). When present, the array must include one or more known scopes—see `docs/CONFIGURATION.md` for the canonical list and descriptions.
+
 Response (token value is returned once):
 ```json
 {
@@ -533,7 +539,8 @@ Response (token value is returned once):
     "prefix": "pulse_1a2b",
     "suffix": "c3d4",
     "createdAt": "2025-10-14T12:12:34Z",
-    "lastUsedAt": null
+    "lastUsedAt": null,
+    "scopes": ["monitoring:read"]
   }
 }
 ```

docs/DOCKER_MONITORING.md

@@ -18,6 +18,7 @@ Data is pushed to Pulse over HTTPS using your existing API token – no inbound
 ## Prerequisites
 
 - Pulse v4.22.0 or newer with an API token enabled (`Settings → Security`)
+- API token with the `docker:report` scope (add `docker:manage` if you use remote lifecycle commands)
 - Docker 20.10+ on Linux (the agent uses the Docker Engine API via the local socket)
 - Access to the Docker socket (`/var/run/docker.sock`) or a configured `DOCKER_HOST`
 - Go 1.24+ if you plan to build the binary from source
@@ -38,7 +39,7 @@ Copy the binary to your Docker host (e.g. `/usr/local/bin/pulse-docker-agent`) a
 
 ### Quick install from your Pulse server
 
-Use the bundled installation script (ships with Pulse v4.22.0+) to deploy and manage the agent. Replace the token placeholder with an API token generated in **Settings → Security**. Create a dedicated token for each Docker host so you can revoke individual credentials without touching others—sharing one token across many hosts makes incident response much harder.
+Use the bundled installation script (ships with Pulse v4.22.0+) to deploy and manage the agent. Replace the token placeholder with an API token generated in **Settings → Security**. Create a dedicated token for each Docker host so you can revoke individual credentials without touching others—sharing one token across many hosts makes incident response much harder. Tokens used here should include the `docker:report` scope so the agent can submit telemetry (add `docker:manage` only if you plan to issue lifecycle commands remotely).
 
 ```bash
 curl -fsSL http://pulse.example.com/install-docker-agent.sh \
@@ -130,7 +131,7 @@ docker run -d \
 | Flag / Env var          | Description                                               | Default         |
 | ----------------------- | --------------------------------------------------------- | --------------- |
 | `--url`, `PULSE_URL`    | Pulse base URL (http/https).                              | `http://localhost:7655` |
-| `--token`, `PULSE_TOKEN`| Pulse API token (required).                               | —               |
+| `--token`, `PULSE_TOKEN`| Pulse API token with `docker:report` scope (required).    | —               |
 | `--target`, `PULSE_TARGETS` | One or more `url|token[|insecure]` entries to fan-out reports to multiple Pulse servers. Separate entries with `;` or repeat the flag. | — |
 | `--interval`, `PULSE_INTERVAL` | Reporting cadence (supports `30s`, `1m`, etc.).     | `30s`           |
 | `--hostname`, `PULSE_HOSTNAME` | Override host name reported to Pulse.              | Docker info / OS hostname |

docs/HOST_AGENT.md

@@ -81,7 +81,7 @@ A Windows build will ship shortly. In the meantime run the Linux/WSL binary or c
 | Flag | Description |
 |------|-------------|
 | `--url` | Pulse base URL (defaults to `http://localhost:7655`) |
-| `--token` | API token with monitoring write access |
+| `--token` | API token with the `host-agent:report` scope |
 | `--interval` | Polling interval (`30s` default) |
 | `--hostname` | Override reported hostname |
 | `--agent-id` | Override agent identifier (used as dedupe key) |