docs(api): address review feedback on API docs

- Document uniqueTrackingId format, and that invalid or reused IDs are
  replaced; use a valid UUID in the example.
- Note that actionId is looked up as a binding ID (matters for entities).
- Warn that the *AndWait methods check log permission after the action
  has run, so retrying a permission error can re-run the action.
- DumpVars writes to stdout; the API response only contains an alert.
- Show `jq -r .alert` to get readable server diagnostics.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/modules/ROOT/pages/api/start_action.adoc

@@ -13,6 +13,8 @@ All request and response field names below are the protobuf JSON names (lowerCam
 * `actionId` is the `id` you set on the action in your `config.yaml`. To find your Action ID, and understand how Action IDs work, see the xref:action_customization/ids.adoc[Action ID] documentation.
 * `bindingId` identifies one button/instance of an action. For a normal action this is the same as the action ID. For actions generated from xref:entities/intro.adoc[entities], each entity gets its own binding ID. Binding IDs are returned by `GetDashboard` (as `action.bindingId`).
 
+NOTE: Despite its name, the `actionId` field used by `StartActionAndWait`, `StartActionByGet` and `StartActionByGetAndWait` is looked up as a binding ID. For normal actions this makes no difference, but for entity-generated actions you must send the entity's binding ID - sending the configured action `id` returns `not_found`.
+
 [#api-request-actionid]
 == Request type: Action ID only
 
@@ -60,7 +62,7 @@ This is the request the OliveTin web UI uses, and gives you the most control ove
 
 * `bindingId` (required) - see <<api-ids>>.
 * `arguments` (optional) - values for the action's xref:args/intro.adoc[arguments].
-* `uniqueTrackingId` (optional) - if you set this, it is used as the execution tracking ID, otherwise one is generated for you.
+* `uniqueTrackingId` (optional) - if you set this, it is used as the execution tracking ID, otherwise one is generated for you. It must be up to 36 characters of hex digits and dashes (eg: a UUID), and must not already have been used. An invalid or previously used ID is silently replaced with a generated UUID, so always track the execution using the `executionTrackingId` returned in the response.
 * `justification` (optional) - the reason for running the action, for actions that require a justification.
 
 [source,json]
@@ -69,7 +71,7 @@ This is the request the OliveTin web UI uses, and gives you the most control ove
 {
   "bindingId": "generate_cryptocurrency",
   "arguments": [],
-  "uniqueTrackingId": "my-tracking-id"
+  "uniqueTrackingId": "0f8b1c2e-6d3a-4e5f-9a7b-1c2d3e4f5a6b"
 }
 ----
 

docs/modules/ROOT/pages/troubleshooting/advanced.adoc

@@ -17,7 +17,7 @@ All these configuration options are `false` by default, and should be deleted fr
 
 [#dump-vars]
 == Dump Vars
-`insecureAllowDumpVars: true` - will allow dumping all the "string variables" from a map that is mainly used for entities, eg: `curl http://server:1337/api/DumpVars --json '{}'`
+`insecureAllowDumpVars: true` - will allow dumping all the "string variables" from a map that is mainly used for entities, eg: `curl http://server:1337/api/DumpVars --json '{}'`. The variables are written to the OliveTin process standard output (ie: the OliveTin logs); the API response only contains an alert.
 
 [#dump-jwt]
 == Dump JWT Claims

docs/modules/ROOT/pages/troubleshooting/server-diagnostics.adoc

@@ -52,6 +52,13 @@ There is a configuration option you can set in your `config.yaml` that allows th
 insecureAllowDumpServerDiagnostics: true
 ----
 
+With this enabled, the diagnostics text is returned in the `alert` field of the JSON response, with its newlines escaped. Use `jq -r` to print it as readable text you can copy:
+
+[source,bash]
+----
+curl -sS http://myserver:1337/api/ServerDiagnostics --json '{}' | jq -r .alert
+----
+
 == Default: Diagnostics dump to logs
 
 You should get a simple JSON message saying something like;

docs/modules/ROOT/partials/api/start_action_methods.adoc

@@ -27,4 +27,6 @@ There are 4 main methods to start an action in OliveTin, which can be used in sc
 
 |======================================================
 
+NOTE: The waiting methods (`StartActionAndWait` and `StartActionByGetAndWait`) check that the caller is allowed to view the action's logs *after* the action has finished. A caller that can start an action but cannot view its logs receives a permission error, even though the action has already run - so retrying on that error can run the action again. Use `StartAction` or `StartActionByGet` when you do not need the log entry.
+
 You can also browse these methods in the link:https://docs.olivetin.app/api/swagger/3k/[OpenAPI/Swagger] docs if you prefer. The link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[Protobuf definition] is the source of truth for all request and response fields.