From a614b17e054e0f2df5a00dc58513b8e7b0c242fa Mon Sep 17 00:00:00 2001
From: artheru <artheru@gmail.com>
Date: Wed, 10 Jun 2026 07:59:39 +0800
Subject: [PATCH] booth: actionable 'bring it online' instance modal (0.55.0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- the instance-created modal was a terse field list; now it's a 2-step
  broker onboarding guide at the point of need:
  1. Heartbeat — a copy-pasteable curl loop (real instance id + accesskey)
     that keeps the instance online (<30s check-in, verified from the API)
  2. Relay — the broker WebSocket + note that the amerc webagent speaks it
- color-coded offline status, code block with copy button
- removes the supply-side last-mile guesswork for publishers
- verified end-to-end via the real publish flow (register → class → instance)
---
 index.html            |  2 +-
 package.json          |  2 +-
 src/AgentPlatform.jsx | 30 ++++++++++++++++++++----------
 src/Scene2D.jsx       |  2 +-
 src/styles.css        |  9 +++++++++
 5 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/index.html b/index.html
index 734fa7f..d733291 100644
--- a/index.html
+++ b/index.html
@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#0e0a14" />
     <meta name="description" content="amerc is the agent mercenary tavern — hire, run, publish, and remotely deliver AI agents across software boundaries. No infrastructure, just skills." />
-    <meta name="version" content="0.54.0-discover" />
+    <meta name="version" content="0.55.0-broker" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <link rel="icon" href="/app-192.png" type="image/png" sizes="192x192" />
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
diff --git a/package.json b/package.json
index 836cb1d..d4e2982 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "amerc-site",
-  "version": "0.54.0-discover",
+  "version": "0.55.0-broker",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/src/AgentPlatform.jsx b/src/AgentPlatform.jsx
index 061e49c..6b802c9 100644
--- a/src/AgentPlatform.jsx
+++ b/src/AgentPlatform.jsx
@@ -308,17 +308,27 @@ export function BoothDashboard({ auth, setRoute }) {
         </div>
       </div>
       <KeysCard />
-      {newInst && (
-        <div className="ap-modal" onClick={() => setNewInst(null)}>
-          <div className="ap-modal-box" onClick={(e) => e.stopPropagation()}>
-            <div className="ap-modal-head"><h3>Instance #{newInst.id} created</h3><button onClick={() => setNewInst(null)}>✕</button></div>
-            <p className="ap-hint">Run your broker against this instance, then it shows online. The accesskey is the relay token.</p>
-            <label className="ap-field">accesskey<code className="ap-token" onClick={() => copyToast(newInst.accesskey)}>{newInst.accesskey} ⧉</code></label>
-            <label className="ap-field">broker WS<code className="ap-token" onClick={() => copyToast(newInst.relayWs)}>{newInst.relayWs} ⧉</code></label>
-            <label className="ap-field">heartbeat<code className="ap-token">POST /api/agents/instances/{newInst.id}/heartbeat {'{'}accesskey,broker,tui{'}'}</code></label>
+      {newInst && (() => {
+        const hb = `while true; do curl -s -XPOST https://amerc.ai/api/agents/instances/${newInst.id}/heartbeat -H 'content-type: application/json' -d '{"accesskey":"${newInst.accesskey}","status":"online","broker":"my-broker"}' >/dev/null; sleep 10; done`;
+        return (
+          <div className="ap-modal" onClick={() => setNewInst(null)}>
+            <div className="ap-modal-box" onClick={(e) => e.stopPropagation()}>
+              <div className="ap-modal-head"><h3>Instance #{newInst.id} — bring it online</h3><button onClick={() => setNewInst(null)}>✕</button></div>
+              <p className="ap-hint">Registered, but <b style={{ color: '#ff9f5a' }}>offline</b> until a broker checks in. Two steps bring it to life:</p>
+              <ol className="ap-steps">
+                <li><b>Heartbeat</b> — keeps it marked online (check in every &lt;30s). Paste this anywhere with <code>curl</code>:
+                  <div className="ap-codeblock"><code>{hb}</code><button className="px-action" onClick={() => copyToast(hb, 'Heartbeat loop copied')}>copy</button></div>
+                </li>
+                <li><b>Relay</b> — bridge your agent so live sessions reach it, over the broker WebSocket:
+                  <code className="ap-token" onClick={() => copyToast(newInst.relayWs)}>{newInst.relayWs} ⧉</code>
+                  <span className="ap-hint">The amerc webagent broker speaks this relay for you — point it at the accesskey below.</span>
+                </li>
+              </ol>
+              <label className="ap-field">accesskey · your broker's secret<code className="ap-token" onClick={() => copyToast(newInst.accesskey)}>{newInst.accesskey} ⧉</code></label>
+            </div>
           </div>
-        </div>
-      )}
+        );
+      })()}
     </div>
   );
 }
diff --git a/src/Scene2D.jsx b/src/Scene2D.jsx
index 828c29d..37c7ce3 100644
--- a/src/Scene2D.jsx
+++ b/src/Scene2D.jsx
@@ -7,7 +7,7 @@ import Account from './Account.jsx';
 import TavernGame from './TavernGame.jsx';
 import { api } from './api.js';
 
-const RELEASE = '0.54.0-discover';
+const RELEASE = '0.55.0-broker';
 
 const NAV = [
   { id: 'home', label: 'Tavern' },
diff --git a/src/styles.css b/src/styles.css
index 75767c6..435e310 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -1393,3 +1393,12 @@ button {
 .px-ver:hover { color: var(--cyan); }
 .ft-status { font-family: inherit; cursor: pointer; transition: border-color .15s, transform .15s; }
 .ft-status:hover { transform: translateY(-1px); border-color: rgba(54,240,176,0.6); }
+
+/* booth "bring it online" instance modal (0.55) */
+.ap-steps { margin: 4px 0 14px; padding-left: 20px; display: flex; flex-direction: column; gap: 13px; }
+.ap-steps li { color: #d6ccec; font-size: 13px; line-height: 1.6; }
+.ap-steps li b { color: #fff; }
+.ap-steps li > code { background: #07060c; color: #7fe9ff; padding: 1px 5px; border-radius: 4px; font-size: 11.5px; }
+.ap-codeblock { display: flex; align-items: center; gap: 8px; margin-top: 7px; background: #07060c; border: 1px solid #241a36; border-radius: 8px; padding: 8px 10px; }
+.ap-codeblock code { flex: 1; color: #7fe9ff; font-family: ui-monospace, monospace; font-size: 11px; line-height: 1.5; word-break: break-all; white-space: pre-wrap; background: none; padding: 0; }
+.ap-codeblock .px-action { flex: 0 0 auto; }