docs: address CodeRabbit review on release PR #1157

- API intro: generated clients must use /api as their base URL, and plain
  JSON calls only work for unary RPCs (not EventStream).
- StartActionByGet(AndWait): entity actions need the binding ID.
- Home Assistant: use StartActionByGet; explain the timeout and post-run
  log permission problems with StartActionByGetAndWait.
- Pocket ID: turn off showDiagnostics/showLogList for guests and enable
  them for the admin ACL only.
- Document that the container healthcheck uses PORT (default 1337).

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

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

@@ -18,9 +18,9 @@ The API is exposed at `/api/` on the single HTTP frontend (port 1337 by default)
 The OliveTin API is completely machine readable - every method, request and response message, field, and enum is defined in the Protobuf files. This makes it straightforward for code generators, API tooling, and LLMs / AI agents to discover and use the API without guessing.
 
 * **Source of truth**: link:https://github.com/OliveTin/OliveTin/tree/main/proto[`proto/`] on GitHub - the service is `olivetin.api.v1.OliveTinApiService` in link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[`olivetin/api/v1/olivetin.proto`].
-* **Generate a client**: use link:https://buf.build[buf] or `protoc` with the Connect, gRPC, or gRPC-Web plugins for your language of choice (Go, TypeScript, Python, Java, etc).
-* **Call it directly**: each RPC is available as `POST /api/<MethodName>` with a JSON body matching the request message, using protobuf JSON field names (lowerCamelCase, eg: `bindingId`).
-* **HTTP method**: every RPC is called with `POST` - a `GET` request returns `405 Method Not Allowed`.
+* **Generate a client**: use link:https://buf.build[buf] or `protoc` with the Connect, gRPC, or gRPC-Web plugins for your language of choice (Go, TypeScript, Python, Java, etc). Set the client's base URL to `http://olivetinServer:1337/api` (not the server root) - the API is only served under `/api/`, and requests to `/olivetin.api.v1.OliveTinApiService/<MethodName>` at the root go to the web UI instead.
+* **Call it directly**: each unary RPC is available as `POST /api/<MethodName>` with a JSON body matching the request message, using protobuf JSON field names (lowerCamelCase, eg: `bindingId`). Server-streaming RPCs (`EventStream`) use the Connect streaming protocol (enveloped `application/connect+json` messages), so they cannot be called with a plain JSON request - use a generated Connect client for those.
+* **HTTP method**: every unary RPC is called with `POST` - a `GET` request returns `405 Method Not Allowed`.
 * **OpenAPI**: the Swagger / OpenAPI links below are generated from the Protobuf files, and are also available for tools that prefer OpenAPI.
 
 == Links

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

@@ -6,6 +6,8 @@ This is the simplest method to start an action - you only need to send the actio
 * **Request Type**: xref:api/start_action.adoc#api-request-actionid[Action ID only] (`actionId`)
 * **Response Type**: Execution Tracking ID
 
+NOTE: For actions generated from xref:entities/intro.adoc[entities], `actionId` must be the entity's binding ID, not the action `id` from your `config.yaml` - see xref:api/start_action.adoc#api-ids[Action IDs vs Binding IDs]. For normal actions, the two are the same.
+
 [NOTE]
 ====
 Despite the name, in OliveTin 3k this method is called with `POST` and a JSON body, the same as every other API method. The OliveTin 2k style of putting the action ID in the URL (eg: `GET /api/StartActionByGet/pingGithub`) is no longer supported and returns `404`.

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

@@ -6,6 +6,8 @@ This method is also a very easy way to quickly start an action, but it waits for
 * **Request Type**: xref:api/start_action.adoc#api-request-actionid[Action ID only] (`actionId`)
 * **Response Type**: Log Entry (waits for the action to finish)
 
+NOTE: For actions generated from xref:entities/intro.adoc[entities], `actionId` must be the entity's binding ID, not the action `id` from your `config.yaml` - see xref:api/start_action.adoc#api-ids[Action IDs vs Binding IDs]. For normal actions, the two are the same.
+
 [NOTE]
 ====
 Despite the name, in OliveTin 3k this method is called with `POST` and a JSON body. The OliveTin 2k style of putting the action ID in the URL (eg: `GET /api/StartActionByGetAndWait/pingGithub`) is no longer supported and returns `404`.

docs/modules/ROOT/pages/install/podmandocker.adoc

@@ -29,4 +29,14 @@ OliveTin does not need to be run as a root, and does not need any special capabi
 
 To change the xref:advanced_configuration/timezones.adoc[changing the timezone requires a bound-mount] from the host. Olivetin ignores the TZ variable as it is non-standard.
 
+[#container-healthcheck]
+== Container healthcheck
+
+The OliveTin container image includes a Docker `HEALTHCHECK` that requests `http://127.0.0.1:$PORT/readyz` inside the container, with `PORT` defaulting to `1337`. The healthcheck cannot read your `config.yaml`, so if you change the port with `listenAddressSingleHTTPFrontend`, either:
+
+* set the xref:reference/network-ports.adoc[`PORT` environment variable] to the same port (`PORT` also overrides the port in `config.yaml`, so the two always match), or
+* override the healthcheck in your deployment (eg: `--health-cmd` with `docker run`, or `healthcheck:` in Docker Compose).
+
+Otherwise the container is reported as `unhealthy`, even though OliveTin is running normally.
+
 include::partial$install/post_container.adoc[]

docs/modules/ROOT/pages/integrations/homeassistant.adoc

@@ -19,9 +19,17 @@ actions:
     shell: ssh user@server "sudo systemctl suspend"
 ----
 
-You then need to know the URL to call to trigger this action. This is the OliveTin API URL plus the method name, and the action ID is sent in a JSON body. For example, if your OliveTin is running at `http://yourserver:1337`, you would `POST` `{"actionId": "server_sleep"}` to `http://yourserver:1337/api/StartActionByGetAndWait`.
+You then need to know the URL to call to trigger this action. This is the OliveTin API URL plus the method name, and the action ID is sent in a JSON body. For example, if your OliveTin is running at `http://yourserver:1337`, you would `POST` `{"actionId": "server_sleep"}` to `http://yourserver:1337/api/StartActionByGet`.
 
-You can learn more about starting actions via the OliveTin API by reading the link xref:api/start_action.adoc[Starting Actions via the API] page, but the method "StartActionByGetAndWait" is the one you will want to use for Home Assistant.
+You can learn more about starting actions via the OliveTin API by reading the link xref:api/start_action.adoc[Starting Actions via the API] page, but the method "StartActionByGet" is the one you will want to use for Home Assistant. It returns as soon as the action has started.
+
+[NOTE]
+====
+Avoid `StartActionByGetAndWait` for Home Assistant unless you need the action's output:
+
+* It only responds once the action has finished, and Home Assistant's `rest_command` gives up after 10 seconds by default, so longer actions are reported as failed even though they ran.
+* It checks that the caller can view the action's logs *after* the action has run. Without the `logs` permission, Home Assistant gets an error even though the action ran, and retrying runs it again.
+====
 
 == Add the REST API call to Home Assistant
 
@@ -45,7 +53,7 @@ From the file editor now in your sidebar, browse the filesystem to the configura
 ----
 rest_command:
   olivetin_sleep_mindstorm:
-    url: http://olivetin.example.com:1337/api/StartActionByGetAndWait
+    url: http://olivetin.example.com:1337/api/StartActionByGet
     method: post
     content_type: "application/json"
     payload: '{"actionId": "server_sleep"}'

docs/modules/ROOT/pages/reference/network-ports.adoc

@@ -57,6 +57,8 @@ If the `PORT` environment variable is set at startup, OliveTin uses it as the li
 
 When `PORT` is not set, OliveTin uses `listenAddressSingleHTTPFrontend` from the config, or `0.0.0.0:1337` if that setting is omitted.
 
+The container image's healthcheck also uses `PORT` (default `1337`), so if you run the container on a different port, see xref:install/podmandocker.adoc#container-healthcheck[Container healthcheck].
+
 == See also
 
 * xref:reference/multiple_instances[Running Multiple instances of OliveTin on the same server]

docs/modules/ROOT/pages/security/oauth2_pocketid.adoc

@@ -73,12 +73,21 @@ defaultPermissions:
   exec: false
   logs: false
 
+# showDiagnostics and showLogList default to true for everyone (including
+# guests), so turn them off here and enable them for admins only below.
+defaultPolicy:
+  showDiagnostics: false
+  showLogList: false
+
 accessControlLists:
   - name: admin
     permissions:
       view: true
       exec: true
       logs: true
+    policy:
+      showDiagnostics: true
+      showLogList: true
     matchUsergroups:
       - olivetin_admin
     addToEveryAction: true