devops-bot-sdk 1.6.86__tar.gz → 1.6.89__tar.gz

{devops_bot_sdk-1.6.86 → devops_bot_sdk-1.6.89}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.86
+Version: 1.6.89
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.86 → devops_bot_sdk-1.6.89}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.86
+Version: 1.6.89
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.86 → devops_bot_sdk-1.6.89}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.86
+Version: 1.6.89
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.86"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.89"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.6.86 → devops_bot_sdk-1.6.89}/sdk/helpdesk_kb.md

@@ -101,6 +101,45 @@ the fix is not in their code, `agentos-auto update` installs the latest.
   unresolved".** The `agentId` on the ticket could not be resolved
   (`handlers._resolve_ticket_agent`); check the agent exists with
   `agentos agent list`, or run with an explicit `--agent NAME`.
+- **AI Draftsman fallback (`ad`) fails with `RATE_LIMIT: 429 RESOURCE_EXHAUSTED`.**
+  The text is Vertex's, but measured on 2026-10-24 the cause was Azure: the
+  gateway's `gpt-5.4` deployment (eastus) over its tokens-per-minute quota, then
+  every fallback model, with only the last error shown. Client side, `ad` 1.1.2
+  retries that error itself (5/10/20/40s); the SDK keeps machines on it —
+  `local_exec.FALLBACK_MIN_VERSION` is `(1, 1, 2)` and an older `ad` is upgraded
+  on `agentos-auto update`, or now with `agentos fallback install`. Check with
+  `agentos fallback status`. Server side (ai-draftsman-ml-b2b), rate-limited
+  deployments cool down and requests wait for capacity instead of failing, once
+  that change is deployed. Large prompts (a long ticket, `agentos help`) hit the
+  limit sooner; retrying a minute later usually works.
+- **`agentos-auto update` says "still on vX — the upgrade did not take" but pip
+  exited 0.** Fixed in `updater._fresh_python_argv`: the post-install check ran
+  `python -c`, which reads the current directory first, so run from inside a
+  checkout of this repo it read the checkout's leftover `devops_bot_sdk.egg-info`
+  instead of the install. On an older SDK: run the update from any other folder,
+  or delete `devops_bot_sdk.egg-info` in the checkout (generated, git-ignored).
+  The install itself had worked.
+- **After `agentos-auto update`: "no systemd unit 'agentos-ui' — restart the panel
+  manually", "could not read the firewall state (needs root …) … sudo ufw allow
+  8765/tcp", "VPS health: not reported — not_assigned_vps".** Not errors. The
+  update restarts the panel so it runs the new code (`sdk/ui/service.py`), checks
+  the panel's port is open for remote access (`sdk/firewall.py` — it never runs
+  sudo itself, so unprivileged it prints the command instead), and reports VPS
+  health only from the VPS assigned to the account (`sdk/vps_health.py`). On a
+  laptop or any machine that is not the assigned VPS all three are expected and
+  need no action; on the VPS, open the port with the printed command if the panel
+  must be reachable remotely, and restart `agentos-ui` if it runs by hand.
+
+## Help in the control panel
+
+The panel's **Help** page (`/help.html`, "Help" in the nav; `sdk/ui/static/help.html`)
+is the same helper as `agentos help`: describe the problem, the answer shows which
+engine answered (claude or the AI Draftsman fallback), follow-ups stay in the same
+case. **Collect diagnostics only** = `agentos doctor`; **Download bundle for your
+admin** = a zip of the case's diagnostics, errors and logs (no SDK source). API:
+`POST /api/ui/help/ask` (a job), `POST /api/ui/help/doctor`,
+`GET /api/ui/help/case/{name}/bundle` (`sdk/ui/api.py`). It runs on the machine the
+panel runs on, so it reads that machine's logs.
 
 ## Useful commands (all verified to exist)
 

{devops_bot_sdk-1.6.86 → devops_bot_sdk-1.6.89}/sdk/ui/static/app.js

@@ -220,7 +220,12 @@
        <span id="loop-badge" class="badge idle"><span class="pulse"></span> …</span>
        <a class="btn" href="/setup.html">Setup</a>`;
     const link = host.querySelector(`[data-nav="${active}"]`);
-    if (link) link.classList.add("active");
+    if (link) {
+      link.classList.add("active");
+      // The nav scrolls sideways rather than wrapping when the window is narrow;
+      // keep the page you are on visible.
+      link.scrollIntoView({ block: "nearest", inline: "nearest" });
+    }
   }
 
   async function pollBadge() {
@@ -1216,10 +1221,14 @@
 
   async function start() {
     if (TOKEN) { boot(); return; }
+    let unlocked = false;
     try {
       const res = await fetch("/api/ui/session-token");
-      if (res.ok) { const d = await res.json(); if (d && d.token !== undefined) { setToken(d.token || "loopback"); boot(); return; } }
+      if (res.ok) { const d = await res.json(); if (d && d.token !== undefined) { setToken(d.token || "loopback"); unlocked = true; } }
     } catch (e) { /* fall through */ }
+    // boot() OUTSIDE the try: a page whose init throws must show that error in the
+    // console, not be swallowed here and turned into a misleading token prompt.
+    if (unlocked) { boot(); return; }
     showGate();
   }
 
@@ -2036,81 +2045,242 @@
   }
 
   // ── HELP: DevOps Bot Help (`agentos help` / `agentos doctor` in the panel) ──
+  // A real answer is plain text with light markdown: "Diagnosis / Evidence / Fix /
+  // If that doesn't work" sections, lists, `code`, ``` blocks and ⚠ lines.
+  // renderHelpAnswer() ESCAPES FIRST and only then adds markup, so nothing the
+  // model writes can become HTML.
+  const HP_SECTIONS = [
+    [/^diagnosis$/i, "diagnosis", "Diagnosis"],
+    [/^evidence$/i, "evidence", "Evidence"],
+    [/^fix$/i, "fix", "Fix"],
+    [/^if that does(?:n'|n’|n)?t work$|^if that doesn't work$|^if it still fails$/i, "next", "If that doesn't work"],
+  ];
+
+  function hpInline(t) {
+    return t
+      .replace(/`([^`]+)`/g, "<code>$1</code>")
+      .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  }
+
+  function renderHelpAnswer(text) {
+    const parts = String(text || "").split(/```[^\n]*\n?/);
+    let html = "", list = null, section = null;
+    const closeList = () => { if (list) { html += `</${list}>`; list = null; } };
+    const closeSection = () => { closeList(); if (section) { html += "</section>"; section = null; } };
+    const openSection = (cls, label) => {
+      closeSection();
+      html += `<section class="hp-sec hp-sec-${cls}"><div class="hp-sec-label">${label}</div>`;
+      section = cls;
+    };
+    parts.forEach((part, i) => {
+      if (i % 2 === 1) {                       // inside a ``` block
+        closeList();
+        // Drop blank edge lines and the indent the block was nested at.
+        const lines = part.replace(/^\s*\n/, "").replace(/\s+$/, "").split("\n");
+        const indent = Math.min(...lines.filter(l => l.trim()).map(l => l.match(/^\s*/)[0].length));
+        const code = esc(lines.map(l => l.slice(indent)).join("\n"));
+        html += `<div class="hp-code"><pre><code>${code}</code></pre>` +
+                `<button type="button" class="hp-copy" data-copy="${code}">Copy</button></div>`;
+        return;
+      }
+      esc(part).split("\n").forEach(raw => {
+        const line = raw.trimEnd();
+        if (!line.trim()) { closeList(); return; }
+        const head = line.match(/^\s*\**([A-Za-z' ’]+?)\**\s*(?::|—|–|-)\s*(.*)$/);
+        const sec = head && HP_SECTIONS.find(([re]) => re.test(head[1].trim()));
+        if (sec) {
+          openSection(sec[1], sec[2]);
+          if (head[2]) html += `<p>${hpInline(head[2])}</p>`;
+          return;
+        }
+        const bullet = line.match(/^\s*[-*•]\s+(.*)$/);
+        const num = line.match(/^\s*(\d+)[.)]\s+(.*)$/);
+        if (bullet || num) {
+          const kind = bullet ? "ul" : "ol";
+          if (list !== kind) { closeList(); html += `<${kind}>`; list = kind; }
+          html += `<li>${hpInline(bullet ? bullet[1] : num[2])}</li>`;
+          return;
+        }
+        closeList();
+        if (/^\s*(⚠|&lt;!|warning:)/i.test(line)) {
+          html += `<div class="hp-warn">${hpInline(line.replace(/^\s*⚠\s*/, ""))}</div>`;
+        } else {
+          html += `<p>${hpInline(line)}</p>`;
+        }
+      });
+    });
+    closeSection();
+    return html;
+  }
+
+  async function hpCopy(text, btn) {
+    try { await navigator.clipboard.writeText(text); }
+    catch (e) {                                  // http:// on a remote box: no clipboard API
+      const ta = document.createElement("textarea");
+      ta.value = text; document.body.appendChild(ta); ta.select();
+      try { document.execCommand("copy"); } catch (_) { /* nothing more to try */ }
+      ta.remove();
+    }
+    if (btn) { const was = btn.textContent; btn.textContent = "Copied"; setTimeout(() => { btn.textContent = was; }, 1200); }
+  }
+
   function initHelp() {
-    let caseName = "";
-
-    function show(res, question) {
-      const host = $("hp-thread");
-      const notes = (res.notes || []).map(n => `<div class="hp-note">${esc(n)}</div>`).join("");
-      host.insertAdjacentHTML("beforeend", `
-        <div class="hp-q"><span class="muted">You</span><div>${esc(question)}</div></div>
-        <div class="hp-a">
-          <div class="muted">DevOps Bot Help · ${esc(res.engine === "ad" ? "AI Draftsman fallback" : "claude")}
-            · case <code>${esc(res.case || "")}</code></div>
-          ${res.ok ? `<pre class="hp-answer">${esc(res.answer || "(empty answer)")}</pre>`
-                   : `<div class="hp-err">${esc(res.error || "the helper could not finish")}</div>`}
-          ${notes}
-        </div>`);
-      host.lastElementChild.scrollIntoView({ behavior: "smooth", block: "start" });
+    const $ = (id) => document.getElementById(id);
+    let caseName = "", jobId = null, timer = null, busy = false;
+
+    function fmt(secs) { return `${Math.floor(secs / 60)}:${String(secs % 60).padStart(2, "0")}`; }
+
+    function working(on, followUp) {
+      busy = on;
+      $("hp-working").style.display = on ? "" : "none";
+      $("hp-ask").disabled = on; $("hp-follow-btn").disabled = on; $("hp-doctor").disabled = on;
+      clearInterval(timer);
+      if (!on) { jobId = null; return; }
+      const started = Date.now();
+      const tick = () => {
+        const secs = Math.round((Date.now() - started) / 1000);
+        $("hp-elapsed").textContent = fmt(secs);
+        $("hp-status").textContent = followUp ? "Thinking about your follow-up…"
+          : secs < 6 ? "Collecting diagnostics and recent logs…"
+          : secs < 20 ? "Reading your logs and the SDK source…"
+          : "Working out the cause — usually 30 seconds to 2 minutes…";
+      };
+      tick(); timer = setInterval(tick, 1000);
+    }
+
+    // During a conversation only the follow-up box shows; "New question" brings
+    // the main box back. Two inputs at once read as two different things.
+    function conversation(on) {
+      document.querySelector(".hp-composer").style.display = on ? "none" : "";
+      $("hp-follow").style.display = on ? "" : "none";
+      $("hp-empty").style.display = on ? "none" : "";
+    }
+
+    function addQuestion(question) {
+      $("hp-empty").style.display = "none";
+      document.querySelector(".hp-composer").style.display = "none";
+      $("hp-thread").insertAdjacentHTML("beforeend",
+        `<div class="hp-q"><div class="hp-bubble">${esc(question)}</div></div>`);
+    }
+
+    function addAnswer(res) {
+      const fallback = res.engine === "ad";
+      const engine = !res.engine ? "" : fallback
+        ? `<span class="hp-engine hp-engine-ad" title="claude was not available, so the AI Draftsman CLI answered">AI Draftsman fallback</span>`
+        : `<span class="hp-engine">claude</span>`;
+      const notes = (res.notes || []).map(n => `<div class="hp-note">${hpInline(esc(n))}</div>`).join("");
+      const body = res.ok
+        ? `<div class="hp-body">${renderHelpAnswer(res.answer || "(the helper returned an empty answer)")}</div>`
+        : `<div class="hp-err"><strong>The helper couldn't finish.</strong> ${esc(res.error || "")}</div>`;
+      const card = document.createElement("div");
+      card.className = "hp-a";
+      card.innerHTML = `
+        <div class="hp-a-head">
+          <span class="hp-avatar" aria-hidden="true">🤖</span>
+          <strong>DevOps Bot Help</strong>${engine}
+          <span class="spacer"></span>
+          ${res.case ? `<span class="muted hp-case" title="Case folder on this machine">${esc(res.case)}</span>` : ""}
+          ${res.ok ? `<button type="button" class="btn hp-copy-all">Copy answer</button>` : ""}
+        </div>${notes}${body}`;
+      $("hp-thread").appendChild(card);
+      card.querySelectorAll(".hp-copy").forEach(b =>
+        b.addEventListener("click", () => {
+          const t = document.createElement("textarea"); t.innerHTML = b.getAttribute("data-copy");
+          hpCopy(t.value, b);
+        }));
+      const all = card.querySelector(".hp-copy-all");
+      if (all) all.addEventListener("click", () => hpCopy(res.answer || "", all));
+      card.scrollIntoView({ behavior: "smooth", block: "start" });
     }
 
     async function ask(question, followUp) {
-      const btn = followUp ? $("hp-follow-btn") : $("hp-ask");
-      btn.disabled = true;
-      $("hp-status").textContent = followUp
-        ? "Thinking about your follow-up…"
-        : "Collecting diagnostics and logs, then reading the SDK source… (a minute or two)";
+      if (busy) return;
+      addQuestion(question);
+      working(true, followUp);
       try {
         const res = await runJob("/api/ui/help/ask",
-          { question, case: followUp ? caseName : "" }, "agentos_help_job");
+          { question, case: followUp ? caseName : "" },
+          { persistKey: "agentos_help_job", onStart: (id) => { jobId = id; } });
         if (res.case) caseName = res.case;
-        show(res, question);
-        $("hp-follow").style.display = res.ok ? "" : "none";
-        $("hp-bundle").style.display = caseName ? "" : "none";
+        addAnswer(res);
+        conversation(true);
+        $("hp-bundle-2").style.display = caseName ? "" : "none";
+        $("hp-follow-q").focus();
       } catch (e) {
-        if (!e.cancelled) toast(e.message, "err");
+        addAnswer({ ok: false, error: e.cancelled ? "Stopped." : e.message });
+        conversation(true);
       } finally {
-        btn.disabled = false;
-        $("hp-status").textContent = "";
+        working(false);
       }
     }
 
-    async function download() {
-      if (!caseName) return;
-      const res = await fetch(`/api/ui/help/case/${encodeURIComponent(caseName)}/bundle`,
-                              { headers: { "Authorization": "Bearer " + TOKEN } });
-      if (!res.ok) { toast("Could not build the bundle", "err"); return; }
-      const url = URL.createObjectURL(await res.blob());
-      const a = document.createElement("a");
-      a.href = url; a.download = caseName + ".zip"; a.click();
-      setTimeout(() => URL.revokeObjectURL(url), 5000);
-    }
-
-    $("hp-ask").addEventListener("click", () => {
+    function askNew() {
       const q = $("hp-question").value.trim();
-      if (!q) { toast("Describe the problem first", "err"); return; }
+      if (!q) { toast("Describe the problem first", "err"); $("hp-question").focus(); return; }
       $("hp-thread").innerHTML = "";
       caseName = "";
+      $("hp-question").value = "";
       ask(q, false);
-    });
-    $("hp-follow-btn").addEventListener("click", () => {
+    }
+
+    function askFollowUp() {
       const q = $("hp-follow-q").value.trim();
       if (!q) return;
       $("hp-follow-q").value = "";
       ask(q, true);
+    }
+
+    async function download() {
+      if (!caseName) return;
+      const btn = $("hp-bundle"); btn.disabled = true;
+      try {
+        const res = await fetch(`/api/ui/help/case/${encodeURIComponent(caseName)}/bundle`,
+                                { headers: { "Authorization": "Bearer " + TOKEN } });
+        if (!res.ok) throw new Error("could not build the bundle");
+        const url = URL.createObjectURL(await res.blob());
+        const a = document.createElement("a");
+        a.href = url; a.download = caseName + ".zip"; a.click();
+        setTimeout(() => URL.revokeObjectURL(url), 5000);
+      } catch (e) { toast(e.message, "err"); }
+      finally { btn.disabled = false; }
+    }
+
+    $("hp-ask").addEventListener("click", askNew);
+    $("hp-question").addEventListener("keydown", (e) => {
+      if (e.key === "Enter" && (e.ctrlKey || e.metaKey)) { e.preventDefault(); askNew(); }
+    });
+    $("hp-follow-btn").addEventListener("click", askFollowUp);
+    $("hp-follow-q").addEventListener("keydown", (e) => {
+      if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); askFollowUp(); }
+    });
+    $("hp-new").addEventListener("click", () => {
+      $("hp-thread").innerHTML = ""; caseName = "";
+      $("hp-bundle").style.display = "none";
+      conversation(false); $("hp-question").focus();
     });
+    $("hp-stop").addEventListener("click", () => { if (jobId) cancelJob(jobId); });
+    document.querySelectorAll(".hp-chip").forEach(chip =>
+      chip.addEventListener("click", () => {
+        $("hp-question").value = chip.textContent.trim();
+        $("hp-question").focus();
+      }));
     $("hp-doctor").addEventListener("click", async () => {
       const btn = $("hp-doctor"); btn.disabled = true;
+      const was = btn.textContent; btn.textContent = "Collecting…";
       try {
         const d = await api("/api/ui/help/doctor", { method: "POST", body: {} });
         caseName = d.case;
         $("hp-diag").textContent = d.diagnostics + "\n" + d.errors;
         $("hp-diag-wrap").style.display = "";
+        $("hp-diag-wrap").open = true;
         $("hp-bundle").style.display = "";
+        $("hp-diag-wrap").scrollIntoView({ behavior: "smooth", block: "start" });
       } catch (e) { toast(e.message, "err"); }
-      finally { btn.disabled = false; }
+      finally { btn.disabled = false; btn.textContent = was; }
     });
     $("hp-bundle").addEventListener("click", download);
+    $("hp-bundle-2").addEventListener("click", download);
+    $("hp-question").focus();
   }
 
   // ── RUN & LOGS: command buttons + live log ───────────────────────────────

devops_bot_sdk-1.6.89/sdk/ui/static/help.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AgentOS — Help</title>
+  <link rel="stylesheet" href="/styles.css" />
+</head>
+<body data-page="help">
+  <div id="topbar"></div>
+
+  <div class="wrap hp-wrap">
+    <div class="hp-head">
+      <div>
+        <h1>DevOps Bot Help</h1>
+        <p class="muted">
+          Describe what's going wrong. The helper reads this machine's diagnostics and recent
+          logs, checks them against the installed SDK, and tells you the cause and the fix —
+          with the log or code line behind every claim.
+        </p>
+      </div>
+      <span class="hp-readonly" title="It can read files only: no commands, no edits, no web.">🔒 Read-only</span>
+    </div>
+
+    <div id="hp-thread" class="hp-thread"></div>
+
+    <div id="hp-empty" class="hp-empty">
+      <div class="muted hp-empty-label">Common problems — click one to start</div>
+      <div class="hp-chips">
+        <button type="button" class="hp-chip">My agentos-auto loop isn't picking up tickets</button>
+        <button type="button" class="hp-chip">agentos-auto update says the upgrade did not take</button>
+        <button type="button" class="hp-chip">Tickets are stuck In Progress and set-status fails</button>
+        <button type="button" class="hp-chip">The AI Draftsman fallback fails with 429 RESOURCE_EXHAUSTED</button>
+        <button type="button" class="hp-chip">A scheduled ticket run never started</button>
+        <button type="button" class="hp-chip">agentos-auto stop crashes on Windows</button>
+      </div>
+    </div>
+
+    <div id="hp-working" class="hp-working" style="display:none">
+      <span class="hp-spinner" aria-hidden="true"></span>
+      <span id="hp-status">Working…</span>
+      <span id="hp-elapsed" class="muted hp-elapsed">0:00</span>
+      <button id="hp-stop" class="btn" type="button">Stop</button>
+    </div>
+
+    <div class="hp-composer panelbox">
+      <div class="bd">
+        <label for="hp-question" class="hp-label">Your problem</label>
+        <textarea id="hp-question" rows="3"
+          placeholder="e.g. agentos-auto stop crashes with AttributeError getpgid and tickets stay In Progress"></textarea>
+        <div class="hp-actions">
+          <button id="hp-ask" class="btn primary">Ask</button>
+          <span class="muted hp-kbd">Ctrl / ⌘ + Enter</span>
+          <span class="spacer"></span>
+          <button id="hp-doctor" class="btn" type="button" title="Collect this machine's diagnostics without asking the AI">Collect diagnostics only</button>
+          <button id="hp-bundle" class="btn" type="button" style="display:none"
+            title="A zip of the diagnostics, errors and logs — no source code, secrets removed">⬇ Bundle for your admin</button>
+        </div>
+      </div>
+    </div>
+
+    <div id="hp-follow" class="hp-follow panelbox" style="display:none">
+      <div class="bd hp-follow-row">
+        <input id="hp-follow-q" type="text" placeholder="Ask a follow-up about the same problem (Enter to send)" />
+        <button id="hp-follow-btn" class="btn primary">Send</button>
+        <button id="hp-bundle-2" class="btn" type="button" style="display:none"
+          title="A zip of the diagnostics, errors and logs — no source code, secrets removed">⬇ Bundle</button>
+        <button id="hp-new" class="btn" type="button">New question</button>
+      </div>
+    </div>
+
+    <details id="hp-diag-wrap" class="hp-diag panelbox" style="display:none">
+      <summary>Diagnostics collected from this machine</summary>
+      <pre id="hp-diag"></pre>
+    </details>
+  </div>
+  <script src="/app.js"></script>
+</body>
+</html>

{devops_bot_sdk-1.6.86 → devops_bot_sdk-1.6.89}/sdk/ui/static/styles.css

@@ -53,10 +53,12 @@ a { color: var(--accent); }
 .wrap { max-width: 1160px; margin: 0 auto; padding: 22px; }
 
 /* ── Main nav ── */
-.mainnav { display: flex; gap: 4px; margin-left: 10px; }
+.mainnav { display: flex; gap: 4px; margin-left: 10px; min-width: 0; overflow-x: auto; scrollbar-width: none; }
+.mainnav::-webkit-scrollbar { display: none; }
 .mainnav a {
+  white-space: nowrap; flex: none;
   text-decoration: none; color: var(--muted); font-weight: 600; font-size: 14px;
-  padding: 7px 13px; border-radius: 8px; transition: .12s;
+  padding: 7px 10px; border-radius: 8px; transition: .12s;
 }
 .mainnav a:hover { background: var(--panel-2); color: var(--text); }
 .mainnav a.active { background: color-mix(in srgb, var(--accent) 14%, transparent); color: var(--accent); }
@@ -444,10 +446,99 @@ tr:last-child td { border-bottom: none; }
 .sc-tk-list .empty { padding: 10px; }
 
 /* Help page */
-#hp-question { width: 100%; }
-#hp-follow-q { flex: 1; min-width: 200px; }
-.hp-q, .hp-a { border: 1px solid var(--border); border-radius: 8px; padding: 10px 12px; margin-top: 10px; }
-.hp-q > div { margin-top: 4px; white-space: pre-wrap; }
-.hp-answer { white-space: pre-wrap; word-break: break-word; margin: 8px 0 0; max-height: 70vh; overflow: auto; }
-.hp-note { margin-top: 8px; color: var(--muted); }
-.hp-err { margin-top: 8px; color: var(--red); }
+.hp-wrap { max-width: 920px; }
+.hp-head { display: flex; gap: 16px; align-items: flex-start; margin: 4px 0 18px; }
+.hp-head h1 { margin: 0 0 6px; font-size: 22px; }
+.hp-head p { margin: 0; max-width: 680px; }
+.hp-readonly { flex: none; font-size: 12px; font-weight: 600; color: var(--green);
+  border: 1px solid color-mix(in srgb, var(--green) 40%, var(--border)); border-radius: 999px; padding: 4px 10px; }
+
+.hp-empty { margin-bottom: 14px; }
+.hp-empty-label { font-size: 13px; margin-bottom: 8px; }
+.hp-chips { display: flex; flex-wrap: wrap; gap: 8px; }
+.hp-chip { font: inherit; font-size: 13px; color: var(--text); background: var(--panel); cursor: pointer;
+  border: 1px solid var(--border); border-radius: 999px; padding: 6px 12px; transition: .12s; }
+.hp-chip:hover { border-color: var(--accent); color: var(--accent); }
+
+.hp-composer .bd, .hp-follow .bd { padding: 14px 16px; }
+.hp-label { display: block; font-weight: 600; font-size: 13px; margin-bottom: 6px; }
+#hp-question { width: 100%; font: inherit; font-size: 15px; color: var(--text); background: var(--panel-2);
+  border: 1px solid var(--border); border-radius: 10px; padding: 10px 12px; resize: vertical; min-height: 84px; }
+#hp-question:focus, #hp-follow-q:focus { outline: none; border-color: var(--accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 18%, transparent); }
+.hp-actions { display: flex; align-items: center; gap: 8px; margin-top: 10px; flex-wrap: wrap; }
+.hp-kbd { font-size: 12px; }
+
+.hp-thread { display: flex; flex-direction: column; gap: 12px; margin-bottom: 14px; }
+.hp-thread:empty { display: none; }
+.hp-q { display: flex; justify-content: flex-end; }
+.hp-bubble { max-width: 80%; background: var(--accent); color: var(--accent-ink); padding: 9px 14px;
+  border-radius: 14px 14px 4px 14px; white-space: pre-wrap; word-break: break-word; }
+.hp-a { background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius);
+  box-shadow: var(--shadow); padding: 14px 16px; }
+.hp-a-head { display: flex; align-items: center; gap: 8px; margin-bottom: 10px; flex-wrap: wrap; }
+.hp-avatar { font-size: 18px; }
+.hp-engine { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .4px;
+  color: var(--accent); background: color-mix(in srgb, var(--accent) 12%, transparent);
+  border-radius: 6px; padding: 2px 7px; }
+.hp-engine-ad { color: var(--amber); background: color-mix(in srgb, var(--amber) 14%, transparent); }
+.hp-case { font-size: 12px; font-family: ui-monospace, Menlo, Consolas, monospace; }
+.hp-a .btn { padding: 4px 10px; font-size: 12px; }
+
+.hp-body { font-size: 14.5px; line-height: 1.55; }
+.hp-body p { margin: 4px 0; }
+.hp-body ul, .hp-body ol { margin: 4px 0 6px; padding-left: 22px; }
+.hp-body li { margin: 3px 0; }
+.hp-body code { font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 12.5px;
+  background: var(--panel-2); border: 1px solid var(--border); border-radius: 5px; padding: 1px 5px;
+  word-break: break-word; }
+.hp-sec { border-left: 3px solid var(--border); padding: 2px 0 2px 12px; margin: 10px 0; }
+.hp-sec-label { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .5px;
+  color: var(--muted); margin-bottom: 2px; }
+.hp-sec-diagnosis { border-left-color: var(--accent); background: color-mix(in srgb, var(--accent) 7%, transparent);
+  border-radius: 0 8px 8px 0; padding: 8px 12px; }
+.hp-sec-diagnosis .hp-sec-label { color: var(--accent); }
+.hp-sec-diagnosis p { font-size: 15px; font-weight: 500; }
+.hp-sec-fix { border-left-color: var(--green); }
+.hp-sec-fix .hp-sec-label { color: var(--green); }
+.hp-sec-next { border-left-color: var(--amber); }
+.hp-code { position: relative; margin: 6px 0; }
+.hp-code pre { margin: 0; background: var(--panel-2); border: 1px solid var(--border); border-radius: 8px;
+  padding: 10px 12px; overflow-x: auto; font-size: 12.5px; }
+.hp-code pre code { background: none; border: 0; padding: 0; }
+.hp-copy { position: absolute; top: 6px; right: 6px; font: inherit; font-size: 11px; cursor: pointer;
+  color: var(--muted); background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 2px 8px; }
+.hp-copy:hover { color: var(--accent); border-color: var(--accent); }
+.hp-warn { margin: 6px 0; padding: 7px 10px; border-radius: 8px; font-size: 13.5px;
+  background: color-mix(in srgb, var(--amber) 12%, transparent); border: 1px solid color-mix(in srgb, var(--amber) 35%, transparent); }
+.hp-warn::before { content: "⚠ "; }
+.hp-note { margin: 0 0 8px; padding: 7px 10px; border-radius: 8px; font-size: 13px; color: var(--text);
+  background: color-mix(in srgb, var(--amber) 10%, transparent); }
+.hp-err { padding: 8px 10px; border-radius: 8px; color: var(--red);
+  background: color-mix(in srgb, var(--red) 8%, transparent); }
+
+.hp-working { display: flex; align-items: center; gap: 10px; margin: 0 0 14px; padding: 10px 14px;
+  background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); }
+.hp-spinner { width: 16px; height: 16px; border-radius: 50%; flex: none;
+  border: 2px solid color-mix(in srgb, var(--accent) 25%, transparent); border-top-color: var(--accent);
+  animation: hp-spin .8s linear infinite; }
+@keyframes hp-spin { to { transform: rotate(360deg); } }
+.hp-elapsed { font-variant-numeric: tabular-nums; margin-left: auto; }
+
+.hp-follow { margin-top: 0; }
+.hp-follow-row { display: flex; gap: 8px; align-items: center; }
+#hp-follow-q { flex: 1; min-width: 0; font: inherit; color: var(--text); background: var(--panel-2);
+  border: 1px solid var(--border); border-radius: 10px; padding: 9px 12px; }
+
+.hp-diag { margin-top: 14px; }
+.hp-diag summary { cursor: pointer; padding: 12px 16px; font-weight: 600; }
+.hp-diag pre { margin: 0; padding: 0 16px 16px; white-space: pre-wrap; word-break: break-word;
+  font-size: 12px; max-height: 60vh; overflow: auto; }
+
+@media (max-width: 640px) {
+  .hp-head { flex-direction: column; }
+  .hp-bubble { max-width: 92%; }
+  .hp-follow-row { flex-wrap: wrap; }
+  #hp-follow-q { flex: 1 1 100%; }
+  .hp-kbd { display: none; }
+}