Docs: document the Bearer API (endpoints, scopes) in README + admin page

- README: Bearer API table (list/read/comment/status), scope explanation,
  and the new endpoints in the API Endpoints table.
- /admin/api-keys API Usage section: scopes note + copy-paste cURL examples
  for create, list/triage, read-one, comment, and close (uses APP_DOMAIN).

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

views/admin/ApiKeysView.php

@@ -169,17 +169,56 @@ include __DIR__ . '/../../views/layout_header.php';
       </div>
       <pre><code>Authorization: Bearer YOUR_API_KEY</code></pre>
     </div>
-    <p class="lt-text-xs lt-text-muted" style="margin-top:0.5rem">
-      Example — create a ticket via cURL:<br>
+    <?php $apiBase = 'https://' . htmlspecialchars($GLOBALS['config']['APP_DOMAIN'] ?? 'your-instance', ENT_QUOTES); ?>
+    <p class="lt-text-sm lt-text-muted" style="margin-top:0.75rem">
+      <strong>Scopes:</strong> a <code>read</code> key may only use the <code>GET</code> endpoints;
+      a <code>read_write</code> key may also create tickets, post comments, and change status.
+      All endpoints are Bearer-authenticated and rate-limited. Comments and status changes made via
+      the API are attributed to the key's name.
     </p>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Create a ticket</strong> (read_write):</p>
     <div class="lt-code-block">
       <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
-      <pre><code>curl -X POST https://your-instance/create_ticket_api.php \
+      <pre><code>curl -X POST <?= $apiBase ?>/create_ticket_api.php \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"title":"My ticket","category":"General","type":"Issue","priority":3}'</code></pre>
     </div>
-    <p class="lt-text-xs lt-text-muted" style="margin-top:0.5rem">API keys provide programmatic access to create and manage tickets. Keep keys secure and rotate them regularly.</p>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>List / triage the queue</strong> (read). Filters: <code>status</code>, <code>priority</code> (1-5), <code>host</code> (title match), <code>page</code>, <code>limit</code>:</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl "<?= $apiBase ?>/api/tickets_api.php?status=Open&priority=2&limit=25" \
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Read one ticket + its comments</strong> (read):</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl "<?= $apiBase ?>/api/tickets_api.php?ticket_id=123456789" \
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Post a comment</strong> (read_write). <code>markdown_enabled</code> is optional:</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl -X POST <?= $apiBase ?>/api/ticket_comment_api.php \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"ticket_id":"123456789","comment_text":"Investigating.","markdown_enabled":true}'</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Change / close status</strong> (read_write, workflow-validated). <code>comment</code> is required for transitions that require one (e.g. closing) and is posted as the reason:</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl -X POST <?= $apiBase ?>/api/ticket_status_api.php \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"ticket_id":"123456789","status":"Closed","comment":"Resolved: disk replaced."}'</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem">Keep keys secure and rotate them regularly. Scope automation keys to <code>read</code> unless they need to write.</p>
   </div>
 </div>