Document OpenBao Browser CLI limits

docs/whynot-design-npm-publish-handoff.md

@@ -126,8 +126,17 @@ JSON
 bao write auth/netkingdom/role/whynot-design-workload-kv-read @"$role_payload_file"
 ```
 
-The OpenBao Web UI console may treat `bound_claims={...}` as a string. Use a
-raw JSON/API role editor when staying in the UI, or use the shell form above.
+The OpenBao Browser CLI cannot run this shell block and may treat
+`bound_claims={...}` as a string. When staying in the Web UI, open the API
+Explorer and submit the role payload JSON above with:
+
+```text
+method: PUT
+path: /v1/auth/netkingdom/role/whynot-design-workload-kv-read
+```
+
+If the API Explorer asks for a path without the API prefix, use
+`auth/netkingdom/role/whynot-design-workload-kv-read`.
 
 ## Non-Secret Reads
 

scripts/credential-change.py

@@ -388,6 +388,8 @@ def render_operator_commands(ccr: dict[str, Any]) -> str:
     lines = [
         f"# Operator handoff for {ccr['id']}: {ccr['title']}",
         "# Run from the railiance-platform repo with an approved OpenBao operator token.",
+        "# Do not paste this shell block into the OpenBao Browser CLI.",
+        f"# Web UI API Explorer path for the role JSON body: /v1/{auth_path}",
         "set -euo pipefail",
         f"bao policy write {shlex.quote(openbao['policy_name'])} {shlex.quote(openbao['policy_file'])}",
         'role_payload_file="$(mktemp)"',

tests/test_credential_change.py

@@ -144,6 +144,11 @@ class CredentialChangeTests(unittest.TestCase):
             "bao write auth/netkingdom/role/whynot-design-workload-kv-read",
             rendered,
         )
+        self.assertIn("# Do not paste this shell block into the OpenBao Browser CLI.", rendered)
+        self.assertIn(
+            "# Web UI API Explorer path for the role JSON body: /v1/auth/netkingdom/role/whynot-design-workload-kv-read",
+            rendered,
+        )
         self.assertIn('role_payload_file="$(mktemp)"', rendered)
         self.assertIn('"bound_claims": {', rendered)
         self.assertIn(