Make TrueNAS diagnostics safe and distinguish missing telemetry

Replace token and API-key shell arguments with private header and payload files, verify the exact test/save recipes with synthetic credentials, and separate hardware capacity from actual usage and History. Bound local logs and keep sanitized evidence and trusted HTTPS as the troubleshooting path.

Contract-Neutral: Documentation and synthetic recipe checks only; no runtime, API, transport or metric contract changes.
Change-source: pulse-maintainer

docs/TRUENAS.md

@@ -89,24 +89,51 @@ All endpoints require admin authentication.
 | `DELETE` | `/api/truenas/connections/{id}` | Remove a TrueNAS connection |
 | `POST` | `/api/truenas/connections/test` | Test a connection before saving |
 
-### Adding a connection (API)
+### Testing and adding a connection (API)
+
+The **Settings → TrueNAS** flow is the simplest option. For an API client,
+prepare the private Pulse header file as described in the
+[API authentication guide](API.md). The Pulse API token authenticates to
+Pulse; the separate TrueNAS API key belongs in the connection's JSON file.
+Do not put either credential in shell arguments, URLs or a public thread.
+
+Create or protect the connection file before opening it in a trusted editor:
 
 ```bash
-curl -X POST http://localhost:7655/api/truenas/connections \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"nas-1","host":"https://truenas.local","username":"key-owner","apiKey":"your-api-key"}'
+umask 077
+mkdir -p "$HOME/.config/pulse"
+touch "$HOME/.config/pulse/truenas-connection.json"
+chmod 600 "$HOME/.config/pulse/truenas-connection.json"
+vi "$HOME/.config/pulse/truenas-connection.json"
 ```
 
-### Testing a connection (API)
+In that file, enter a JSON object with `name`, `host` (the TrueNAS HTTPS URL),
+`username` (the key owner) and `apiKey`. Keep both credential files private;
+do not paste their contents into a terminal command or upload them.
+
+Test the connection before saving it:
 
 ```bash
-curl -X POST http://localhost:7655/api/truenas/connections/test \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"nas-1","host":"https://truenas.local","username":"key-owner","apiKey":"your-api-key"}'
+curl --fail-with-body --silent --show-error \
+  --header "@$HOME/.config/pulse/api-header" \
+  --header 'Content-Type: application/json' \
+  --data-binary "@$HOME/.config/pulse/truenas-connection.json" \
+  http://127.0.0.1:7655/api/truenas/connections/test
 ```
 
+After checking the test response, save the connection with:
+
+```bash
+curl --fail-with-body --silent --show-error \
+  --header "@$HOME/.config/pulse/api-header" \
+  --header 'Content-Type: application/json' \
+  --data-binary "@$HOME/.config/pulse/truenas-connection.json" \
+  http://127.0.0.1:7655/api/truenas/connections
+```
+
+These Pulse URLs are loopback-only examples. For a remote Pulse server, use
+its trusted HTTPS origin without disabling certificate verification.
+
 ## Troubleshooting
 
 ### "TrueNAS service unavailable"
@@ -122,21 +149,43 @@ curl -X POST http://localhost:7655/api/truenas/connections/test \
 
 ### No data appearing after adding connection
 - Wait at least 30 seconds for the first poll cycle.
-- Check Pulse logs for TrueNAS-related errors:
+- **Test Connection** checks authentication and the selected transport, not
+  successful collection of every metric. The legacy REST diagnostic is
+  expected for recognized CORE 13 systems; it is not itself a connection error.
+- Inspect a bounded local log excerpt for TrueNAS-related errors:
   ```bash
-  journalctl -u pulse | grep -i truenas
+  journalctl -u pulse -n 100 --no-pager | grep -i truenas
   # or
-  docker logs pulse | grep -i truenas
+  docker logs --tail 100 pulse 2>&1 | grep -i truenas
   ```
+- If collection is safe, **Settings → Diagnostics → Export for GitHub
+  (sanitized)** can provide connection evidence. Review the export or log
+  excerpt before sharing: remove credentials, cookies, private hostnames,
+  addresses and webhook URLs. Do not upload configuration or credential files.
+
+### Inventory works but CPU, memory or History is missing
+
+Services, uptime, hardware capacity and disk temperatures can be collected
+without CPU or memory usage. A Host panel showing core count and total memory
+does not establish a live reading; check the CPU/memory usage columns and
+History series separately. A disk-utilisation line does not establish that
+CPU, memory or network History is available.
+
+Check whether the corresponding graphs work in the TrueNAS web UI. If Pulse
+still shows missing readings, report the affected panels, running Pulse and
+TrueNAS versions, and the relevant sanitized evidence above. Do not replace
+an otherwise working key or clear stored History merely because a graph is
+empty. When sharing a requested native graph response, include only its graph
+name, `legend`, timing fields and one `data` row or error; omit authentication
+messages and identifying details. Do not upload a full browser network capture.
 
 ### Stale TrueNAS data
 - If TrueNAS data stops updating, the source status transitions to `stale` after ~120 seconds.
 - Check TrueNAS connectivity and API key validity.
-- Verify with the API:
-  ```bash
-  curl -H "Authorization: Bearer $TOKEN" http://localhost:7655/api/resources \
-    | jq '.resources[] | select(.platformType == "truenas")'
-  ```
+- In your signed-in Pulse browser session, open `/api/resources` on the same
+  Pulse origin and inspect the entries with `platformType: "truenas"`. This
+  uses your existing session without copying a token or cookie. Do not post
+  the full response; use the sanitized export or a reviewed relevant excerpt.
 
 ### Disabling TrueNAS integration
 Set `PULSE_ENABLE_TRUENAS=false` and restart Pulse. Existing connection data is preserved but polling stops.