@songsid/agend 2.2.0-alpha.2 → 2.2.0-alpha.4

package/dist/ui/chat-thread.js

@@ -8,6 +8,7 @@
 // Unrelated updates (a new message, another message's tick) stop nothing (#1306 §6.2, #1408 §4).
 import "./chat-render.js";
 import "./preview.js";
+import { loadHtmlAttachment } from "./html-attachment.js";
 
 const R = () => globalThis.AgendChatRender;
 const P = () => globalThis.AgendPreview;
@@ -44,7 +45,23 @@ export function createThread(list, scroller, opts) {
     // renderMarkdown escapes the whole text before it adds any tag of its own (chat-render.js).
     const ticks = u && x.delivery ? R().deliveryHtml(x.delivery, TICKS()) : "";
     const tools = u ? "" : `<div class="msg-tools"><button type="button" class="chip-btn icon-only" data-act="copyMsg" data-arg="${escAttr(msgKey(x))}" title="${escAttr(tr("chat.copyMessage"))}" aria-label="${escAttr(tr("chat.copyMessage"))}">${COPY}</button></div>`;
-    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span><span class="time">${time}</span>${ticks}</div><div class="body"><div class="md">${R().renderMarkdown(x.text, x.role === "agent" ? { htmlCards: true } : undefined)}</div>${R().attachmentsHtml(x.attachments)}</div>${tools}</div>`;
+    const buttons = x.role === "agent" ? replyButtonsHtml(x.buttons) : "";
+    return `<div class="msg ${u ? "user" : "agent"}"><div class="meta"><span class="sender">${escAttr(x.sender)}</span><span class="time">${time}</span>${ticks}</div><div class="body"><div class="md">${R().renderMarkdown(x.text, x.role === "agent" ? { htmlCards: true } : undefined)}</div>${R().attachmentsHtml(x.attachments, x.role === "agent" ? { htmlCards: true } : undefined)}${buttons}</div>${tools}</div>`;
+  }
+  /**
+   * #1266: an agent reply's buttons. Labels are text (escaped, never Markdown); the click names the set and the index,
+   * nothing else. Ended (chosen / expired) or a click in flight: every button off; the chosen one marked, and who.
+   */
+  function replyButtonsHtml(b) {
+    if (!b || typeof b.id !== "string" || !Array.isArray(b.labels) || !b.labels.length) return "";
+    const busy = !!(opts.replyButtonBusy && opts.replyButtonBusy(b.id));
+    const off = b.state !== "open" || busy;
+    const items = b.labels.map((label, i) => {
+      const chosen = b.state === "chosen" && b.chosen === i;
+      return `<button type="button" class="btn btn-sm rb-btn${chosen ? " chosen" : ""}" data-act="replyButton" data-arg="${escAttr(`${b.id}:${i}`)}"${off ? " disabled" : ""}>${escAttr(chosen ? `✓ ${label}` : label)}</button>`;
+    }).join("");
+    const note = b.state === "chosen" ? trf("chat.rbChosen", b.by || "") : b.state === "expired" ? tr("chat.rbExpired") : "";
+    return `<div class="rb-row" role="group" aria-label="${escAttr(tr("chat.rbGroup"))}">${items}${note ? `<span class="rb-note">${escAttr(note)}</span>` : ""}</div>`;
   }
   function msgNode(html, x, stoppedKeys) {
     const tpl = list.ownerDocument.createElement("template");
@@ -76,72 +93,108 @@ export function createThread(list, scroller, opts) {
     }
   }
 
-  // HTML cards (#1306): each ```html fence of a server-marked agent message gets a card under its code block. Building
-  // a card makes no frame; Preview does (AgendPreview.start → mountPreview).
+  // HTML cards (#1306): each ```html fence of a server-marked agent message gets a card under its code block, and each
+  // .html/.htm file it attached gets one under its files (§6.1, Q4). Building a card makes no frame and fetches
+  // nothing; Preview does (AgendPreview.start → mountPreview), after reading an attachment's HTML on that click.
   function decorateHtmlCards(node, x, stoppedKeys) {
     const doc = list.ownerDocument;
     const fences = R().htmlFences(x.text);
     for (const ph of node.querySelectorAll(".html-card[data-card]")) {
       const n = Number(ph.dataset.card), fence = fences[n];
       if (!fence) continue;
-      const key = `${msgKey(x)}:f${n}`;
       ph.textContent = "";
       if (ph.classList.contains("truncated") || !fence.terminated) {
         const note = doc.createElement("div"); note.className = "pv-note"; note.textContent = tr("chat.pvTruncated"); ph.append(note);
         continue;
       }
-      const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
-      const head = el("div", "pv-head");
-      const label = el("span", "pv-label", tr("chat.pvHtml"));
-      const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
-      const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
-      const dl = el("button", "btn btn-sm btn-ghost pv-dl", tr("chat.pvDownload")); dl.type = "button";
-      const panel = opts.panel || null;
-      const toPanel = panel ? el("button", "btn btn-sm btn-ghost pv-open", tr("chat.pvOpenPanel")) : null;
-      if (toPanel) toPanel.type = "button";
-      const menu = el("details", "pv-menu");
-      const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
-      const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
-      const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
-      menu.append(sum, optB, neverB);
-      head.append(label, run, stopB, ...(toPanel ? [toPanel] : []), dl, menu);
-      const note = el("div", "pv-note");
-      const banner = el("div", "pv-banner", P().BANNER); banner.hidden = true;
-      const holder = el("div", "pv-holder");
-      ph.append(head, note, banner, holder);
-      let state = "idle";
-      const refresh = (reason) => {
-        const a = P().availability();
-        const going = state === "starting" || state === "running";
-        const inPanel = !!panel && panel.shown() === key;   // #1481: the panel shows this block; the card points there
-        run.hidden = !a.ok || going || inPanel;
-        if (toPanel) toPanel.hidden = inPanel;
-        stopB.hidden = !going;
-        banner.hidden = !going;
-        note.textContent = reason != null ? reason : going ? (state === "starting" ? tr("chat.pvStarting") : "") : inPanel ? tr("chat.pvInPanel") : a.ok ? "" : a.reason;
-        optB.textContent = P().optedIn() ? tr("chat.pvDisallow") : tr("chat.pvAllow");
-        neverB.textContent = P().never() ? tr("chat.pvNeverUndo") : tr("chat.pvNever");
-      };
-      const ui = { state: (name, reason) => { state = name === "starting" || name === "running" ? name : "idle"; refresh(reason || null); } };
-      run.onclick = () => P().start(key, holder, fence.code, ui);
-      stopB.onclick = () => P().stop(key, "stopped", "");
-      // A running preview moves: it stops here and starts in the panel (the click that ran it). An idle one opens the
-      // panel with its own Preview to click.
-      if (toPanel) toPanel.onclick = () => {
-        const moving = P().running(key);
-        if (moving) P().stop(key, "stopped", "");
-        panel.open({ key, instance: x.instance, msgKey: msgKey(x), n, code: fence.code, sender: x.sender, ts: x.ts }, { run: moving });
-      };
-      dl.onclick = () => opts.download(fence.code);
-      optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
-      neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
-      cardRefresh.set(ph, refresh);
-      refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
+      buildCard(ph, x, `${msgKey(x)}:f${n}`, { n, code: fence.code }, stoppedKeys);
+    }
+    const atts = Array.isArray(x.attachments) ? x.attachments : [];
+    for (const ph of node.querySelectorAll(".html-card[data-att]")) {
+      const att = atts.find(a => a && a.id === ph.dataset.att);
+      if (!att || !R().isHtmlAttachment(att)) continue;
+      ph.textContent = "";
+      buildCard(ph, x, `${msgKey(x)}:a${att.id}`, { att: { id: att.id, name: att.name, size: att.size } }, stoppedKeys);
     }
   }
+  /** Why an attachment's HTML could not be read, for the card's note. */
+  const attReason = (reason) => tr(reason === "over" ? "chat.pvAttOver" : reason === "gone" ? "chat.pvAttGone" : "chat.pvAttFailed");
+  /** One card: `source` is { n, code } for a fence or { att } for an attachment (its HTML read on the first click). */
+  function buildCard(ph, x, key, source, stoppedKeys) {
+    const doc = list.ownerDocument;
+    const el = (tag, cls, text) => { const e = doc.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
+    const att = source.att || null;
+    let code = att ? null : source.code;
+    const head = el("div", "pv-head");
+    const label = el("span", "pv-label", att ? `${tr("chat.pvHtml")} · ${att.name}` : tr("chat.pvHtml"));
+    const run = el("button", "btn btn-sm pv-run", tr("chat.pvPreview")); run.type = "button";
+    const stopB = el("button", "btn btn-sm pv-stop", tr("chat.pvStop")); stopB.type = "button"; stopB.hidden = true;
+    // An attachment already has its download link (the file itself) right above the card.
+    const dl = att ? null : el("button", "btn btn-sm btn-ghost pv-dl", tr("chat.pvDownload"));
+    if (dl) dl.type = "button";
+    const panel = opts.panel || null;
+    const toPanel = panel ? el("button", "btn btn-sm btn-ghost pv-open", tr("chat.pvOpenPanel")) : null;
+    if (toPanel) toPanel.type = "button";
+    const menu = el("details", "pv-menu");
+    const sum = el("summary", null, "⋯"); sum.title = tr("chat.pvMenu"); sum.setAttribute("aria-label", tr("chat.pvMenu"));
+    const optB = el("button", "chip-btn pv-opt"); optB.type = "button";
+    const neverB = el("button", "chip-btn pv-never"); neverB.type = "button";
+    menu.append(sum, optB, neverB);
+    head.append(label, run, stopB, ...(toPanel ? [toPanel] : []), ...(dl ? [dl] : []), menu);
+    const note = el("div", "pv-note");
+    const banner = el("div", "pv-banner", P().banner()); banner.hidden = true;
+    const holder = el("div", "pv-holder");
+    ph.append(head, note, banner, holder);
+    let state = "idle";
+    // Reading an attachment: one read per card at a time (a second click while it reads does nothing), and a read
+    // whose card was stopped, replaced or left meanwhile is dropped (`reading` moved on, or the card left the page).
+    let reading = 0, reads = 0;
+    const refresh = (reason) => {
+      const a = P().availability();
+      const going = state === "starting" || state === "running";
+      const inPanel = !!panel && panel.shown() === key;   // #1481: the panel shows this block; the card points there
+      run.hidden = !a.ok || going || inPanel || !!reading;
+      if (toPanel) toPanel.hidden = inPanel || !!reading;
+      stopB.hidden = !going && !reading;
+      banner.hidden = !going;
+      note.textContent = reason != null ? reason : reading ? tr("chat.pvLoading") : going ? (state === "starting" ? tr("chat.pvStarting") : "") : inPanel ? tr("chat.pvInPanel") : a.ok ? "" : a.reason;
+      optB.textContent = P().optedIn() ? tr("chat.pvDisallow") : tr("chat.pvAllow");
+      neverB.textContent = P().never() ? tr("chat.pvNeverUndo") : tr("chat.pvNever");
+    };
+    /** The HTML, then `then(code)`: at once for a fence or an attachment already read; otherwise read it first. */
+    const withCode = async (then) => {
+      if (code != null) { then(code); return; }
+      if (reading) return;
+      const mine = reading = ++reads;
+      refresh();
+      const r = await loadHtmlAttachment(att);
+      if (reading !== mine || !ph.isConnected) return;
+      reading = 0;
+      if (!r.ok) { refresh(attReason(r.reason)); return; }
+      code = r.code;
+      refresh();
+      then(code);
+    };
+    const ui = { state: (name, reason) => { state = name === "starting" || name === "running" ? name : "idle"; refresh(reason || null); } };
+    // Nothing is read for Preview on a device that does not allow previews: the button is not even shown there.
+    run.onclick = () => { if (P().availability().ok) withCode((c) => P().start(key, holder, c, ui)); };
+    stopB.onclick = () => { if (reading) { reading = 0; refresh(); } else P().stop(key, "stopped", ""); };
+    // A running preview moves: it stops here and starts in the panel (the click that ran it). An idle one opens the
+    // panel with its own Preview to click.
+    if (toPanel) toPanel.onclick = () => {
+      const moving = P().running(key);
+      if (moving) P().stop(key, "stopped", "");
+      withCode((c) => panel.open({ key, instance: x.instance, msgKey: msgKey(x), ...(att ? { att } : { n: source.n }), code: c, sender: x.sender, ts: x.ts }, { run: moving }));
+    };
+    if (dl) dl.onclick = () => opts.download(code);
+    optB.onclick = () => { menu.open = false; opts.setPreviewOptIn(!P().optedIn()); };
+    neverB.onclick = () => { menu.open = false; P().setNever(!P().never()); refreshCards(); };
+    cardRefresh.set(ph, refresh);
+    refresh(stoppedKeys.includes(key) ? tr("chat.pvChanged") : null);
+  }
   /** Re-read this device's preview choice on every card in this thread. */
   function refreshCards() {
-    for (const node of list.querySelectorAll(".html-card[data-card]")) { const f = cardRefresh.get(node); if (f) f(); }
+    for (const node of list.querySelectorAll(".html-card[data-card], .html-card[data-att]")) { const f = cardRefresh.get(node); if (f) f(); }
   }
 
   const nearBottom = () => R().isNearBottom(scroller.scrollTop, scroller.clientHeight, scroller.scrollHeight);
@@ -233,6 +286,10 @@ export function createThread(list, scroller, opts) {
       const folded = box.classList.toggle("folded");
       el.textContent = folded ? trf("chat.showAll", el.dataset.lines) : tr("chat.showLess");
     } else if (act === "toggleWrap") opts.toggleWrap();
+    else if (act === "replyButton") {
+      const m = /^([0-9a-f]{32}):(\d{1,2})$/.exec(el.dataset.arg || "");
+      if (m && opts.clickReplyButton) opts.clickReplyButton(m[1], Number(m[2]));
+    }
   }
 
   /** The thread goes (the chat left, or another instance opened): every preview in it stops first. */

package/dist/ui/first-run.js

@@ -0,0 +1,64 @@
+// #1519 P7 (docs/design/ux-onboarding-walkthrough.md §5.1): the first-run card. A fleet with no chat connection (a
+// web-only fleet) opens Chat and Settings with it: "Connect a chat app" opens the setup wizard (in Settings, where its
+// progress is shown), "Use the web only" hides it in this browser. It stays until a connection exists or it is dismissed.
+import { html } from "/assets/app-html.js";
+import { register, t } from "/assets/app-i18n.js";
+import { appStore, createStore, useStore } from "/assets/app-store.js";
+import { navigate } from "/assets/app-nav.js";
+import { settingsPath } from "/assets/app-route.js";
+import { Icon } from "/assets/ui-icons.js";
+
+register("firstRun", {
+  en: {
+    title: "Connect a chat app",
+    body: "AgEnD works in this browser on its own. To talk to your agents from Telegram or Discord too, add a bot: the setup wizard checks its token and connects it to an agent.",
+    connect: "Connect a chat app", webOnly: "Use the web only",
+  },
+  "zh-TW": {
+    title: "連接聊天應用程式",
+    body: "AgEnD 只用這個瀏覽器也能運作。想同時從 Telegram 或 Discord 跟你的 agent 對話，就加一個機器人：設定精靈會檢查它的 token，並把它接到一個 agent。",
+    connect: "連接聊天應用程式", webOnly: "只用網頁",
+  },
+});
+
+export const DISMISS_KEY = "agend_firstrun_dismissed";
+function readDismissed() { try { return localStorage.getItem(DISMISS_KEY) === "1"; } catch { return false; } }
+// `dismissed`: this page's own answer (it holds even when the browser keeps no storage); a stored one is read each time.
+const local = createStore({ dismissed: false, wizard: false });
+
+export function dismissFirstRun() {
+  try { localStorage.setItem(DISMISS_KEY, "1"); } catch { /* this page only */ }
+  local.set({ dismissed: true });
+}
+
+/** For the tests: a fresh page's state. */
+export function resetFirstRun() { local.set({ dismissed: false, wizard: false }); }
+
+/** Settings asks once, when it has its data: was it opened by "Connect a chat app" (open the wizard)? */
+export function takeWizardRequest() {
+  if (!local.get().wizard) return false;
+  local.set({ wizard: false });
+  return true;
+}
+
+/** Shown on a known web-only fleet (no connection) until dismissed. */
+export function useFirstRun() {
+  const app = useStore(appStore);
+  const { dismissed } = useStore(local);
+  return app.ready && app.connections === 0 && !dismissed && !readDismissed();
+}
+
+/** onConnect: Settings opens its wizard in place; elsewhere the card goes to Settings, which opens it. */
+export function FirstRunCard({ onConnect }) {
+  const shown = useFirstRun();
+  if (!shown) return null;
+  const connect = onConnect || (() => { local.set({ wizard: true }); navigate(settingsPath("bots")); });
+  return html`<section class="card first-run" aria-labelledby="first-run-title">
+    <h3 id="first-run-title"><${Icon} name="plug" size=${14} /> ${t("firstRun.title")}</h3>
+    <p>${t("firstRun.body")}</p>
+    <div class="dlg-inline-actions">
+      <button type="button" class="btn btn-primary" onClick=${connect}>${t("firstRun.connect")}</button>
+      <button type="button" class="btn btn-ghost" onClick=${dismissFirstRun}>${t("firstRun.webOnly")}</button>
+    </div>
+  </section>`;
+}

package/dist/ui/html-attachment.js

@@ -0,0 +1,26 @@
+// #1306 §6.1 (Q4): an agent's .html / .htm attachment gets the same preview card as a ```html block. Its HTML is read
+// from /ui/file/<id> — same origin, this session's cookie — only on a click (Preview, Open in panel), never to show a
+// card. What runs is then handed to the preview frame exactly like a block's (AgendPreview.start): the file URL itself
+// is never opened or framed on the dashboard's origin.
+
+/** The same cap as a block's (preview.js LIMITS.maxBytes): UTF-8 bytes of the HTML. */
+export const HTML_ATTACHMENT_MAX = 1024 * 1024;
+
+/**
+ * Read an attachment's HTML: { ok: true, code } or { ok: false, reason } with reason "over" (the file is over the
+ * cap: its listed size is checked before anything is fetched, the bytes again after), "gone" (the fleet no longer
+ * serves that id — the file changed, or the fleet restarted), or "failed".
+ */
+export async function loadHtmlAttachment(att, fetchImpl = globalThis.fetch) {
+  if (!att || typeof att.id !== "string" || !/^[0-9a-f]{32}$/.test(att.id)) return { ok: false, reason: "failed" };
+  if (typeof att.size === "number" && att.size > HTML_ATTACHMENT_MAX) return { ok: false, reason: "over" };
+  let res;
+  try { res = await fetchImpl(`/ui/file/${att.id}`, { credentials: "same-origin", cache: "no-store" }); }
+  catch { return { ok: false, reason: "failed" }; }
+  if (!res || !res.ok) return { ok: false, reason: res && res.status === 404 ? "gone" : "failed" };
+  let bytes;
+  try { bytes = await res.arrayBuffer(); } catch { return { ok: false, reason: "failed" }; }
+  if (bytes.byteLength > HTML_ATTACHMENT_MAX) return { ok: false, reason: "over" };
+  // UTF-8, as a block's text is; a BOM is dropped.
+  return { ok: true, code: new TextDecoder("utf-8").decode(bytes) };
+}

package/dist/ui/icons/favicon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
+  <title>AgEnD — Ag</title>
+  <rect x="1" y="1" width="62" height="62" rx="12" fill="#e5eaf0" stroke="#617386" stroke-width="2"/>
+  <g transform="translate(0 -2)"><g fill="#14273d" fill-rule="evenodd">
+    <path d="M8.5 43 17 18h6l8.5 25H26l-2-6h-8l-2 6Zm9-10.5h5l-2.5-8Z"/>
+    <path transform="translate(2 0)" d="M49.5 27v18.8c0 5-3.1 7.2-8.2 7.2h-6.8v-4.8H41c2.6 0 3.7-.9 3.7-3.2v-3.3c-1.3 1.5-3.1 2.3-5.6 2.3-5.8 0-9-3.7-9-8.9 0-5.1 3.2-8.9 9-8.9 2.5 0 4.3.8 5.6 2.3V27Zm-9.7 3.8c-3 0-4.6 1.8-4.6 4.3s1.6 4.3 4.6 4.3 4.6-1.8 4.6-4.3-1.6-4.3-4.6-4.3Z"/>
+  </g></g>
+</svg>

package/dist/ui/panel-chat.js

@@ -10,7 +10,7 @@ import { html, useEffect, useLayoutEffect, useRef, useState } from "/assets/app-
 import { t } from "/assets/app-i18n.js";
 import { appStore, useStore } from "/assets/app-store.js";
 import { useLease } from "/assets/app-ctx.js";
-import { PanelHeader, onPanelKey, setTitle, addFooterItem, statusClass, statusLabel, openDrawer } from "/assets/app-shell.js";
+import { PanelHeader, onPanelKey, setTitle, addFooterItem, statusClass, statusLabel, openDrawer, requestNewInstance } from "/assets/app-shell.js";
 import { navigate } from "/assets/app-nav.js";
 import { Menu } from "/assets/ui-menu.js";
 import { Dialog } from "/assets/ui-dialog.js";
@@ -25,6 +25,7 @@ import { createThread, msgKey } from "./chat-thread.js";
 import { PreviewPanel, openPanel, panelStore, shownKey } from "./preview-panel.js";
 import { needsArgument, paletteFor, parseCommandLine } from "./chat-commands.js";
 import { installTour, refreshTourSpot, startTour } from "./chat-tour.js";
+import { FirstRunCard } from "./first-run.js";
 
 const R = () => globalThis.AgendChatRender;
 const P = () => globalThis.AgendPreview;
@@ -63,7 +64,8 @@ export function boot({ stream, boot: bootData, deps = {} }) {
   store.attach(stream);
   // #1306: what the server said about previews for this load. The page-wide message and storage listeners this adds
   // belong to the app, once (they are never per mount).
-  if (P() && bootData) P().init(bootData);
+  // #1554: its words in the page's language (chat.pv*); a key the dictionary does not have keeps preview.js's English.
+  if (P() && bootData) P().init(bootData, { text: (key, ...v) => { const k = `chat.${key}`, s = t(k, ...v); return s === k ? null : s; } });
   addFooterItem("previews", PreviewOptIn);
   addFooterItem("tour", TourButton);
   installTour();
@@ -99,9 +101,9 @@ async function copyText(text) {
   return ok;
 }
 /** The HTML as a file: a blob of the source as application/octet-stream, saved as reply.html — never opened. */
-function downloadHtml(code) {
+function downloadHtml(code, name) {
   const url = URL.createObjectURL(new Blob([code], { type: "application/octet-stream" }));
-  const a = document.createElement("a"); a.href = url; a.download = "reply.html"; a.className = "offscreen";
+  const a = document.createElement("a"); a.href = url; a.download = typeof name === "string" && name.trim() ? name.trim() : "reply.html"; a.className = "offscreen";
   document.body.appendChild(a); a.click(); a.remove();
   URL.revokeObjectURL(url);
 }
@@ -127,9 +129,14 @@ export function ChatPanel({ route, navKey }) {
   }, [name, !!inst]);
   useEffect(() => { setTitle(name || t("app.chat")); }, [name, navKey]);
   if (!name) {
+    // #1519 P7: a web-only fleet starts here with the first-run card; with no agent at all, the way to make one.
+    const none = app.ready && !app.instances.length;
     return html`<div class="panel p-chat"><${PanelHeader} title=${t("app.chat")} />
-      <div class="panel-body center"><${Empty} icon="chat" title=${t("chat.pick")} hint=${t("chat.pickHint")}
-        action=${html`<button type="button" class="btn only-narrow" onClick=${openDrawer}>${t("chat.backToList")}</button>`} /></div></div>`;
+      <div class="panel-body center"><div class="first-run-stack"><${FirstRunCard} />
+        ${none ? html`<${Empty} icon="bot" title=${t("app.noInstances")} hint=${t("app.noInstancesHint")}
+          action=${html`<button type="button" class="btn btn-primary" onClick=${requestNewInstance}><${Icon} name="plus" size=${16} />${t("app.newInstance")}</button>`} />`
+        : html`<${Empty} icon="chat" title=${t("chat.pick")} hint=${t("chat.pickHint")}
+          action=${html`<button type="button" class="btn only-narrow" onClick=${openDrawer}>${t("chat.backToList")}</button>`} />`}</div></div></div>`;
   }
   if (!app.ready) return html`<div class="panel p-chat"><${PanelHeader} title=${name} /><div class="panel-body"><${Skeleton} lines=${5} /></div></div>`;
   if (!inst) return html`<${NotFound} name=${name} />`;
@@ -204,7 +211,7 @@ function ChatView({ name, inst, lease, exec, awaiting }) {
         <${Dock} name=${name} inst=${inst} lease=${lease} exec=${exec} awaiting=${awaiting} />
       </div>
       <${PreviewPanel} name=${name} split=${split} msgs=${() => store.state.msgs[name] || []} subscribe=${(fn) => store.subscribe(fn)}
-        keyOf=${msgKey} reveal=${(k) => thread.current && thread.current.reveal(k)} download=${downloadHtml} />
+        keyOf=${msgKey} reveal=${(k) => thread.current && thread.current.reveal(k)} download=${downloadHtml} allow=${() => setPreviewOptIn(true)} />
     </div>
     <div class="drop-overlay" aria-hidden="true"><div class="drop-card"><${Icon} name="attach" size=${32} /><span>${t("chat.dropHere")}</span></div></div>
     ${dialog === "details" ? html`<${DetailsDialog} name=${name} onClose=${() => setDialog(null)} />` : null}
@@ -221,6 +228,8 @@ function Thread({ name, th }) {
     const thread = createThread(list.current, scroller.current, {
       t, tf: t, isUser: (x) => store.isUser(x, name), onJump: setJump, onEmpty: setEmpty,
       setPreviewOptIn, copyText, download: downloadHtml, toggleWrap,
+      clickReplyButton: (id, index) => store.clickReplyButton(name, id, index),      // #1266
+      replyButtonBusy: (id) => store.state.rbBusy.has(id),
       panel: { shown: shownKey, open: (spec, o) => openPanel(spec, o) },   // #1481
     });
     th.current = thread;

package/dist/ui/panel-fleet.js

@@ -36,8 +36,8 @@ register("fleet", {
     channel: "Channel", type: "Type", tokenEnv: "Bot token env", groupId: "Group ID", show: "Show", hide: "Hide", access: "Access control", mode: "Mode", locked: "Locked", open: "Open",
     allowedUsers: "Allowed users", allowedUsersNote: "Comma-separated user IDs", defaults: "Defaults", backend: "Backend", roots: "Project roots", addRoot: "Add root", removeRoot: "Remove",
     saveNote: "Saving rewrites fleet.yaml (its comments are lost).",
-    newInstance: "New instance", directory: "Directory", directoryHint: "Optional — a workspace is created if empty", topic: "Topic name", topicHint: "From the directory name",
-    topicRequired: "Topic name is required when Directory is empty", description: "Description", descriptionHint: "What this instance does", model: "Model", modelHint: "e.g. sonnet, opus, gpt-5",
+    newInstance: "New instance", directory: "Directory", directoryHint: "Optional — a workspace is created if empty", topic: "Name", topicHint: "From the directory name",
+    topicRequired: "Name is required when Directory is empty", description: "Description", descriptionHint: "What this instance does", model: "Model", modelHint: "e.g. sonnet, opus, gpt-5",
     branch: "Branch (git worktree)", branchHint: "e.g. feature-x", tags: "Tags", tagsHint: "comma-separated, e.g. dev, review", systemPrompt: "System prompt", systemPromptHint: "Custom instructions for this instance",
     fleetDefault: "Use the fleet default", notInstalled: "(not installed)", deprecated: "(deprecated)", instanceCreated: "Instance created",
   },
@@ -56,8 +56,8 @@ register("fleet", {
     channel: "頻道", type: "類型", tokenEnv: "Bot token 環境變數", groupId: "Group ID", show: "顯示", hide: "隱藏", access: "存取控制", mode: "模式", locked: "鎖定", open: "開放",
     allowedUsers: "允許的使用者", allowedUsersNote: "以逗號分隔的使用者 ID", defaults: "預設值", backend: "Backend", roots: "專案根目錄", addRoot: "新增根目錄", removeRoot: "移除",
     saveNote: "儲存會改寫 fleet.yaml（其中的註解會遺失）。",
-    newInstance: "新增 instance", directory: "目錄", directoryHint: "可留空——留空會自動建立工作區", topic: "Topic 名稱", topicHint: "預設取自目錄名稱",
-    topicRequired: "目錄留空時必須填寫 Topic 名稱", description: "說明", descriptionHint: "這個 instance 做什麼", model: "模型", modelHint: "例如 sonnet、opus、gpt-5",
+    newInstance: "新增 instance", directory: "目錄", directoryHint: "可留空——留空會自動建立工作區", topic: "名稱", topicHint: "預設取自目錄名稱",
+    topicRequired: "目錄留空時必須填寫名稱", description: "說明", descriptionHint: "這個 instance 做什麼", model: "模型", modelHint: "例如 sonnet、opus、gpt-5",
     branch: "分支（git worktree）", branchHint: "例如 feature-x", tags: "標籤", tagsHint: "以逗號分隔，例如 dev, review", systemPrompt: "System prompt", systemPromptHint: "這個 instance 的自訂指示",
     fleetDefault: "使用 fleet 預設", notInstalled: "（未安裝）", deprecated: "（已淘汰）", instanceCreated: "Instance 已建立",
   },
@@ -359,7 +359,7 @@ function CreateTeam({ onClose, onDone }) {
   </${FormDialog}>`;
 }
 
-/** "New instance": the sidebar's ✎ opens it from anywhere (#1408 step 3 merges it with Settings' create flow). */
+/** "New instance": the sidebar's + opens it from anywhere (#1408 step 3 merges it with Settings' create flow). */
 export function CreateInstanceDialog({ onClose }) {
   const lease = useLease("create-instance");
   const [backends, setBackends] = useState(null);

package/dist/ui/panel-settings.js

@@ -25,7 +25,7 @@ import { api, attach, confirmedWrite, newKey } from "./settings-confirm.js";
 import { dismissOperation, operationActive, restartFleet, startOperation, takeLeftover } from "./settings-apply.js";
 import {
   ACCESS_MODES, AGENT_MODES, DEFAULT_SCHEMA, LOG_LEVELS, TOOL_PROGRESS, TOOL_SETS, VISIBILITY_MODES, batchImpact,
-  changedFields, channelId, channelsOf, chLabel, effectiveSummary, fleetModel, fromYaml, fullModelRequests, groupAgents,
+  changedFields, channelId, channelsOf, chLabel, connectionState, effectiveSummary, fleetModel, fromYaml, fullModelRequests, groupAgents,
   hasOwn, impactOf, localeOptions, defaultsImpact, requestImpact, nonNegative, positive, replyGuardSupported, shortName, STATUS_ORDER, toYaml,
   visibilityDefault, worstImpact,
 } from "./settings-model.js";
@@ -35,6 +35,7 @@ import {
 } from "./settings-dialogs.js";
 import { SetupWizard } from "./settings-wizard.js";
 import { CreateInstanceDialog } from "./panel-fleet.js";
+import { FirstRunCard, takeWizardRequest } from "./first-run.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
 const ICONS = { agents: "bot", bots: "plug", classic: "room", general: "sliders", advanced: "code" };
@@ -197,6 +198,8 @@ export function SettingsPanel({ route, navKey }) {
   };
 
   const ctx = data && !data.error ? makeCtx(data, setData, stage, unstage, reload, reloadLive, () => mount.current()) : null;
+  // #1519 P7: "Connect a chat app" on the first-run card elsewhere came here for the wizard: it opens once the data is in.
+  useEffect(() => { if (ctx && takeWizardRequest()) setDialog({ kind: "wizard", key: navKey }); }, [!!ctx, navKey]);
   const sectionBody = !data ? html`<${Skeleton} lines=${6} />`
     : data.error ? html`<${ErrorState} message=${tn("configLoadFailed")} onRetry=${reload} />`
     : section === "agents" ? html`<${Agents} ctx=${ctx} search=${search} openDialog=${(d) => setDialog({ ...d, key: navKey })} />`
@@ -220,6 +223,7 @@ export function SettingsPanel({ route, navKey }) {
         <input type="search" value=${search} placeholder=${tn("searchAll")} onInput=${(e) => setSearch(e.target.value)} /></label></div>` : null}
       ${op ? html`<${OperationCard} op=${op} schema=${data && data.schema} />` : null}
       <${PendingChanges} inline=${true} />
+      ${ctx && (section === "agents" || section === "bots") ? html`<${FirstRunCard} onConnect=${() => setDialog({ kind: "wizard", key: navKey })} />` : null}
       ${sectionBody}
     </div></div>
     ${staged.size ? html`<${PendingBar} staged=${staged} busy=${opBusy(op)} onApply=${apply} onDiscard=${discard} />` : null}
@@ -378,7 +382,12 @@ function Bots({ ctx, search, openDialog }) {
   return html`${head}
     ${!rows.length ? html`<${Empty} icon="plug" title=${needle ? tn("noAgentMatch", search.trim()) : tn("noBots")} />` : html`<div class="s-list">${rows.map(({ ch, i }) => {
       const users = (ch.access && ch.access.allowed_users) || [];
-      const token = (ctx.connections.find((c, j) => channelId(c, j) === channelId(ch, i)) || {}).token_present;
+      const meta = ctx.connections.find((c, j) => channelId(c, j) === channelId(ch, i)) || {};
+      const token = meta.token_present;
+      // #1519 P6: this connection's own state (not the fleet's "Connected") — a stopped one says so; a known problem says
+      // what to do (P3: Message Content intent; a rejected token).
+      const state = connectionState(meta, ctx.fleetUp);
+      const stateText = tn(state.key, state.bot);
       // #1408 step 5: one line on a desktop — who it is, its facts in one clipped line (all of them in its tooltip),
       // then the cluster; on a phone the facts go under it. It no longer wraps fact by fact.
       const facts = [ch.bot_token_env || tn("noTokenEnv"),
@@ -386,13 +395,13 @@ function Bots({ ctx, search, openDialog }) {
         tn("accessTag", (ch.access && ch.access.mode) || "locked"),
         users.length ? `${users.slice(0, 3).join(", ")}${users.length > 3 ? ` +${users.length - 3}` : ""}` : tn("noAllowedUsers")].filter(Boolean).join(" · ");
       return html`<div key=${channelId(ch, i)} class="s-row s-conn">
-        <span class="s-ident"><span class=${`dot ${ctx.fleetUp ? "ok" : "bad"}`} title=${ctx.fleetUp ? tn("connected") : tn("problem")} aria-hidden="true"></span>
+        <span class="s-ident"><span class=${`dot ${state.cls}`} title=${stateText} aria-hidden="true"></span>
           <span class="s-name">${ch.type === "telegram" ? "Telegram" : "Discord"}</span>
           <span class=${`tag${i === 0 ? "" : " persona"}`}>${ch.id || chLabel(i)}</span></span>
         <span class="s-facts" title=${facts}>${facts}</span>
         <span class="s-actions">
           <span class=${`tag${token ? "" : " warn"}`}>${token ? tn("tokenConfigured") : tn("tokenMissing")}</span>
-          <span class=${`s-state ${ctx.fleetUp ? "ok" : "bad"}`}>${ctx.fleetUp ? tn("connected") : tn("problem")}</span>
+          <span class=${`s-state ${state.cls}`} title=${stateText}>${stateText}</span>
           <button type="button" class="btn btn-sm" onClick=${() => openDialog({ kind: "bot", id: channelId(ch, i) })}>${tn("settingsButton")}</button></span>
       </div>`;
     })}</div>`}
@@ -671,7 +680,7 @@ function Developer({ ctx }) {
         ${["yaml", "json"].map((k) => html`<button key=${k} type="button" class=${`btn btn-sm${fmt === k ? " on" : ""}`} aria-pressed=${fmt === k ? "true" : "false"} onClick=${() => setFmt(k)}>${k.toUpperCase()}</button>`)}</div>
       <button type="button" class="btn btn-sm" onClick=${() => setEditing(!editing)}>${editing ? tn("viewMode") : tn("editMode")}</button>
       <button type="button" class="btn btn-sm" title=${tn("copy")} onClick=${copy}><${Icon} name="copy" size=${14} /><span class="lbl">${tn("copy")}</span></button>
-      <button type="button" class="btn btn-sm" title="fleet.yaml" onClick=${download}><${Icon} name="download" size=${14} /><span class="lbl">fleet.yaml</span></button>
+      <button type="button" class="btn btn-sm" title=${tn("devDownload")} onClick=${download}><${Icon} name="download" size=${14} /><span class="lbl">${tn("devDownload")}</span></button>
     </div>
     ${editing ? html`<textarea class="s-yaml" aria-label=${tn("devEditor")} spellcheck="false" wrap="off" value=${draft} onInput=${(e) => setDraft(e.target.value)}></textarea>
         <div class="save-row"><button type="button" class="btn btn-primary" onClick=${save}>${tn("devApply")}</button><span class="note">${tn("devApplyHint")}</span></div>`
@@ -699,7 +708,8 @@ function OperationCard({ op, schema }) {
   const phaseBusy = ["writing", "posting", "watching"].includes(op.phase);
   const job = op.job;
   const rows = (job && job.targets) || [];
-  const fleetRestarting = job && job.status === "running" && rows.some((r) => r.target === "fleet" && r.status === "running");
+  // A fleet row of kind "hot" is connections starting without a restart (#1519 P6), not AgEnD restarting.
+  const fleetRestarting = job && job.status === "running" && rows.some((r) => r.target === "fleet" && r.status === "running" && r.kind !== "hot");
   const needsRestart = rows.some((r) => r.status === "restart-required");
   const failedRows = rows.some((r) => r.status === "failed");
   const mismatch = schema && schema.fleet_signature_mismatch;
@@ -732,11 +742,11 @@ function OperationCard({ op, schema }) {
     ${op.steps.length ? html`<ul class="s-op-steps">${op.steps.map((s, i) => html`<li key=${i} class=${`s-step ${s.status}`}>
       <span class="s-step-icon" aria-hidden="true">${icon(s.status) ? html`<${Icon} name=${icon(s.status)} size=${14} />` : "·"}</span>
       <span class="grow">${s.label}</span>
-      <span class="note">${s.status === "waiting" ? tn("stepWaiting") : s.status === "skipped" ? tn("stepSkipped") : s.status === "failed" ? (s.error || tn("applyFailed")) : impactText(s.impact)}</span></li>`)}</ul>` : null}
+      <span class="note">${s.status === "waiting" ? tn("stepWaiting") : s.status === "skipped" ? tn("stepSkipped") : s.status === "failed" ? (s.error || tn("applyFailed")) : s.note || impactText(s.impact)}</span></li>`)}</ul>` : null}
     ${rows.length ? html`<ul class="s-op-steps">${rows.map((r) => html`<li key=${r.target} class=${`s-step ${r.status}`}>
       <span class="s-step-icon" aria-hidden="true">${r.status === "done" ? html`<${Icon} name="check" size=${14} />` : r.status === "failed" ? html`<${Icon} name="alert" size=${14} />` : r.status === "restart-required" ? html`<${Icon} name="restart" size=${14} />` : "·"}</span>
       <span class="grow">${r.target === "fleet" ? "AgEnD" : shortName(r.target, {})}</span>
-      <span class="note">${r.target === "fleet" && r.status === "running" ? tn("restartFleetTitle") : r.status === "restart-required" ? tn("applyRestartNeeded")
+      <span class="note">${r.target === "fleet" && r.status === "running" ? tn(r.kind === "hot" ? "connStartingNow" : "restartFleetTitle") : r.status === "restart-required" ? tn("applyRestartNeeded")
         : r.settled_by === "no-change" ? tn("applyNoChange") : r.settled_by === "fleet-restart" ? tn("viaRestart") : r.kind === "hot" ? tn("impactNow") : tn("impactAgent")}</span>
       ${r.error ? html`<span class="feedback error">${r.error}</span>` : null}</li>`)}</ul>` : null}
     ${job && job.error ? html`<p class="feedback error">${job.error}</p>` : null}