@floless/app 0.7.1 → 0.9.0

package/dist/floless-server.cjs

@@ -72,7 +72,7 @@ var require_queue = __commonJS({
       if (!(_concurrency >= 1)) {
         throw new Error("fastqueue concurrency must be equal to or greater than 1");
       }
-      var cache = reusify(Task);
+      var cache2 = reusify(Task);
       var queueHead = null;
       var queueTail = null;
       var _running = 0;
@@ -151,7 +151,7 @@ var require_queue = __commonJS({
         return _running === 0 && self.length() === 0;
       }
       function push(value, done) {
-        var current = cache.get();
+        var current = cache2.get();
         current.context = context;
         current.release = release;
         current.value = value;
@@ -172,7 +172,7 @@ var require_queue = __commonJS({
         }
       }
       function unshift(value, done) {
-        var current = cache.get();
+        var current = cache2.get();
         current.context = context;
         current.release = release;
         current.value = value;
@@ -194,7 +194,7 @@ var require_queue = __commonJS({
       }
       function release(holder) {
         if (holder) {
-          cache.release(holder);
+          cache2.release(holder);
         }
         var next = queueHead;
         if (next && _running <= _concurrency) {
@@ -6621,12 +6621,12 @@ var require_levels = __commonJS({
     function genLsCache(instance) {
       const formatter = instance[formattersSym].level;
       const { labels } = instance.levels;
-      const cache = {};
+      const cache2 = {};
       for (const label in labels) {
         const level = formatter(labels[label], Number(label));
-        cache[label] = JSON.stringify(level).slice(0, -1);
+        cache2[label] = JSON.stringify(level).slice(0, -1);
       }
-      instance[lsCacheSym] = cache;
+      instance[lsCacheSym] = cache2;
       return instance;
     }
     function isStandardLevel(level, useOnlyCustomLevels) {
@@ -25430,7 +25430,7 @@ var require_range = __commonJS({
       parseRange(range) {
         const memoOpts = (this.options.includePrerelease && FLAG_INCLUDE_PRERELEASE) | (this.options.loose && FLAG_LOOSE);
         const memoKey = memoOpts + ":" + range;
-        const cached = cache.get(memoKey);
+        const cached = cache2.get(memoKey);
         if (cached) {
           return cached;
         }
@@ -25464,7 +25464,7 @@ var require_range = __commonJS({
           rangeMap.delete("");
         }
         const result = [...rangeMap.values()];
-        cache.set(memoKey, result);
+        cache2.set(memoKey, result);
         return result;
       }
       intersects(range, options) {
@@ -25503,7 +25503,7 @@ var require_range = __commonJS({
     };
     module2.exports = Range;
     var LRU = require_lrucache();
-    var cache = new LRU();
+    var cache2 = new LRU();
     var parseOptions = require_parse_options();
     var Comparator = require_comparator();
     var debug = require_debug2();
@@ -26445,12 +26445,12 @@ var require_plugin_utils = __commonJS({
       if (display) {
         return display;
       }
-      const cache = require.cache;
-      if (cache) {
-        const keys = Object.keys(cache);
+      const cache2 = require.cache;
+      if (cache2) {
+        const keys = Object.keys(cache2);
         for (let i = 0; i < keys.length; i++) {
           const key = keys[i];
-          if (cache[key].exports === func) {
+          if (cache2[key].exports === func) {
             return key;
           }
         }
@@ -42463,10 +42463,10 @@ var require_accept_negotiator = __commonJS({
       }
       const {
         supportedValues = [],
-        cache
+        cache: cache2
       } = options && typeof options === "object" && options || {};
       this.supportedValues = supportedValues;
-      this.cache = cache;
+      this.cache = cache2;
     }
     Negotiator.prototype.negotiate = function(header) {
       if (typeof header !== "string") {
@@ -51392,6 +51392,49 @@ function parseRunHandle(stdout) {
 function traceLogPath(id, instance, runId, logsRoot = LOGS_DIR) {
   return (0, import_node_path3.join)(logsRoot, id, instance, `${runId}.jsonl`);
 }
+function latestTracePath(id, logsRoot = LOGS_DIR) {
+  const appDir2 = (0, import_node_path3.join)(logsRoot, id);
+  if (!(0, import_node_fs4.existsSync)(appDir2)) return null;
+  let best = null;
+  let instances;
+  try {
+    instances = (0, import_node_fs4.readdirSync)(appDir2);
+  } catch {
+    return null;
+  }
+  for (const instance of instances) {
+    const instDir = (0, import_node_path3.join)(appDir2, instance);
+    let entries;
+    try {
+      if (!(0, import_node_fs4.statSync)(instDir).isDirectory()) continue;
+      entries = (0, import_node_fs4.readdirSync)(instDir);
+    } catch {
+      continue;
+    }
+    for (const f of entries) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = (0, import_node_path3.join)(instDir, f);
+      try {
+        const m = (0, import_node_fs4.statSync)(p).mtimeMs;
+        if (!best || m > best.mtimeMs) best = { path: p, mtimeMs: m };
+      } catch {
+      }
+    }
+  }
+  return best ? best.path : null;
+}
+function readLatestTrace(id, logsRoot = LOGS_DIR) {
+  const p = latestTracePath(id, logsRoot);
+  if (!p) return null;
+  let text;
+  try {
+    text = (0, import_node_fs4.readFileSync)(p, "utf8");
+  } catch {
+    return null;
+  }
+  const runId = p.split(/[\\/]/).pop()?.replace(/\.jsonl$/, "") ?? "";
+  return { runId, path: p, text };
+}
 function startTrigger(id, opts = {}) {
   assertId(id);
   const invoker = currentInvoker();
@@ -52050,9 +52093,15 @@ function mapUserStatus(u) {
 function signInUrl() {
   return `${env().webBase}/login?app=floless`;
 }
+function webBaseUrl() {
+  return env().webBase;
+}
 function updateApiBase() {
   return `${env().apiBase}/updates/releases`;
 }
+function apiBaseUrl() {
+  return env().apiBase;
+}
 async function accessToken() {
   return ensureFreshToken();
 }
@@ -52308,7 +52357,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.7.1" : void 0,
+    define: true ? "0.9.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52318,7 +52367,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.7.1" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.9.0" : void 0 });
 }
 
 // oauth-presets.ts
@@ -53844,6 +53893,150 @@ async function applyUpdate(check, opts) {
   return { applied: true, message: `updating to v${check.targetVersion}\u2026 the app will relaunch` };
 }
 
+// report-relay.ts
+var REPORT_TIMEOUT_MS = 15e3;
+async function reportIssue(input) {
+  let token;
+  try {
+    token = await accessToken();
+  } catch {
+    return { ok: false, error: "offline" };
+  }
+  if (!token) return { ok: false, error: "signed_out" };
+  const url = `${apiBaseUrl()}/issues`;
+  let res;
+  try {
+    res = await authedFetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(REPORT_TIMEOUT_MS)
+    });
+  } catch {
+    return { ok: false, error: "offline" };
+  }
+  if (res.status === 401) return { ok: false, error: "signed_out" };
+  if (res.status === 429) return { ok: false, error: "rate_limited" };
+  if (!res.ok) return { ok: false, error: "offline" };
+  let ref = "";
+  try {
+    const b = await res.json();
+    if (typeof b.ref === "string") ref = b.ref;
+  } catch {
+  }
+  return { ok: true, ref };
+}
+
+// release-notes.ts
+var FETCH_TIMEOUT_MS = 8e3;
+var AWARE_REPO = "aware-aeco/aware";
+var CHANGE_RE = /^[-*]\s+\*\*?(Added|Changed|Fixed|Removed|Security)\*\*?:\s+(.+)$/gim;
+function parseBulletChanges(body) {
+  const out = [];
+  let m;
+  CHANGE_RE.lastIndex = 0;
+  while ((m = CHANGE_RE.exec(body)) !== null) out.push({ type: m[1].toLowerCase(), description: m[2].trim() });
+  return out;
+}
+var cache = /* @__PURE__ */ new Map();
+var CACHE_TTL_MS = 5 * 6e4;
+async function getJson(url, headers = {}) {
+  try {
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+    }
+    return { status: res.status, json };
+  } catch {
+    return null;
+  }
+}
+async function getAppReleaseNotes(version, deps = {}) {
+  const useCache = !deps.changelogUrl;
+  const key = `app:${version}`;
+  if (useCache) {
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS) return hit.notes;
+  }
+  const url = deps.changelogUrl ?? `${webBaseUrl()}/changelog.json`;
+  const r = await getJson(url);
+  let notes;
+  if (!r || r.status >= 400 || !Array.isArray(r.json)) {
+    notes = { ok: false, reason: "unavailable" };
+  } else {
+    const e = r.json.find(
+      (x) => typeof x === "object" && x !== null && x.version === version
+    );
+    notes = e ? {
+      ok: true,
+      component: "app",
+      version,
+      title: String(e.title ?? `v${version}`),
+      summary: String(e.description ?? ""),
+      changes: Array.isArray(e.changes) ? e.changes.filter((c) => typeof c === "object" && c !== null).map((c) => ({ type: String(c.type ?? ""), description: String(c.description ?? "") })) : [],
+      url: typeof e.url === "string" ? e.url : `${webBaseUrl()}/changelog#v${version}`
+    } : { ok: false, reason: "not-found" };
+  }
+  if (useCache && (notes.ok || notes.reason === "not-found")) cache.set(key, { at: Date.now(), notes });
+  return notes;
+}
+async function getAwareReleaseNotes(version, deps = {}) {
+  const useCache = !deps.apiBase;
+  const key = `aware:${version}`;
+  if (useCache) {
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS) return hit.notes;
+  }
+  const base = deps.apiBase ?? "https://api.github.com";
+  const r = await getJson(`${base}/repos/${AWARE_REPO}/releases/tags/v${version}`, {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "floless.app"
+  });
+  let notes;
+  if (!r || r.status >= 400 || typeof r.json !== "object" || r.json === null) {
+    notes = r && r.status === 404 ? { ok: false, reason: "not-found" } : { ok: false, reason: "unavailable" };
+  } else {
+    const rel = r.json;
+    const body = typeof rel.body === "string" ? rel.body : "";
+    const changes = parseBulletChanges(body);
+    const summary = body.split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#") && !l.startsWith("-") && !l.startsWith("*")) ?? "";
+    notes = { ok: true, component: "aware", version, title: rel.name ?? `AWARE ${version}`, summary, changes, url: rel.html_url ?? `https://github.com/${AWARE_REPO}/releases/tag/v${version}` };
+  }
+  if (useCache && (notes.ok || notes.reason === "not-found")) cache.set(key, { at: Date.now(), notes });
+  return notes;
+}
+
+// run-summary.ts
+var clampMsg = (s) => {
+  const t = s.trim();
+  return t.length > 1e3 ? t.slice(0, 1e3) : t;
+};
+function summarizeRun(events) {
+  const runEnd = [...events].reverse().find((e) => e.kind === "run-end");
+  const status = runEnd && typeof runEnd.status === "string" ? runEnd.status : events.length ? "unknown" : "none";
+  let errorNodeId = null;
+  let errorMessage = null;
+  for (const e of events) {
+    if (e.kind === "node-error" && typeof e.node === "string") {
+      errorNodeId = e.node;
+      const err = e.error;
+      errorMessage = typeof err === "string" && err.trim() ? clampMsg(err) : null;
+      break;
+    }
+    const data = e.data;
+    const result = data?.result ?? data;
+    if (result && result.ok === false && typeof e.node === "string") {
+      errorNodeId = e.node;
+      const err = result.error;
+      errorMessage = typeof err === "string" && err.trim() ? clampMsg(err) : null;
+      break;
+    }
+  }
+  return { status, errorNodeId, errorMessage };
+}
+
 // launch.mjs
 var import_node_child_process5 = require("node:child_process");
 var import_node_path14 = require("node:path");
@@ -54321,13 +54514,15 @@ var import_yaml5 = __toESM(require_dist6(), 1);
 // build/ship-skills.mjs
 var PRODUCT_SKILLS = [
   "floless-app-bridge",
-  //     drive the floless.app CLI / desktop bridge from the user's AI
+  //        drive the floless.app CLI / desktop bridge from the user's AI
   "floless-app-onboarding",
-  // guided, re-runnable tour of AWARE + floless.app for new users
+  //    guided, re-runnable tour of AWARE + floless.app for new users
+  "floless-app-report-issue",
+  //  file a diagnosed bug/idea/question to the private log via the floless.io relay
   "floless-app-routines",
-  //   author event-driven ("on trigger") routines
+  //      author event-driven ("on trigger") routines
   "floless-app-workflows"
-  //  author/run .flo workflows
+  //     author/run .flo workflows
 ];
 function selectShippedSkillNames(names) {
   const present = new Set(names);
@@ -56318,7 +56513,12 @@ async function startServer() {
   });
   app.addHook("onRequest", async (req, reply) => {
     if (!req.url.startsWith("/api/")) return;
-    if (req.url.startsWith("/api/health") || req.url.startsWith("/api/license/") || req.url.startsWith("/api/bootstrap/") || req.url.startsWith("/api/autostart") || req.url.startsWith("/api/update") || req.url.startsWith("/api/aware/update")) return;
+    if (req.url.startsWith("/api/health") || req.url.startsWith("/api/license/") || req.url.startsWith("/api/bootstrap/") || req.url.startsWith("/api/autostart") || // Report-an-issue is a support lifeline: a user whose subscription lapsed must still be
+    // able to report "I got locked out". It touches no workspace data and the relay still
+    // requires a valid SESSION token (so it's not open abuse — see report-relay.ts).
+    req.url.startsWith("/api/report-issue") || req.url.startsWith("/api/update") || req.url.startsWith("/api/aware/update") || // Release notes are a read-only display surface for the update pills — a local control,
+    // no workspace data, never spawns `aware`. Exempt like the other update routes.
+    req.url.startsWith("/api/release-notes")) return;
     const { state: state2, signInUrl: signInUrl2 } = await getLicenseStatus();
     if (state2 !== "valid" && state2 !== "offline-grace") {
       return reply.status(402).send({ ok: false, error: "subscription required", state: state2, signInUrl: signInUrl2 });
@@ -56337,6 +56537,8 @@ async function startServer() {
       ok: true,
       appVersion: appVersion(),
       // the installed build (sq.version), so it's scriptable
+      webBase: webBaseUrl(),
+      // channel-correct public site base, for the changelog deep-link
       awareVersion: awareInstalledVersion() ?? bs.awareVersion,
       // fresh (TTL-cached) install version; the boot snapshot is only a fallback
       awareReady: bs.awareReady,
@@ -56355,6 +56557,24 @@ async function startServer() {
     logout();
     return { ok: true };
   });
+  app.post(
+    "/api/report-issue",
+    async (req, reply) => {
+      const b = req.body ?? {};
+      const category = b.category === "idea" || b.category === "question" ? b.category : "bug";
+      const title = typeof b.title === "string" ? b.title.trim() : "";
+      const body = typeof b.body === "string" ? b.body.trim() : "";
+      if (!title || !body) {
+        return reply.status(400).send({ ok: false, error: "title and body are required" });
+      }
+      const clamp = (s, n) => s.length > n ? s.slice(0, n) : s;
+      const context = b.context && typeof b.context === "object" && !Array.isArray(b.context) && JSON.stringify(b.context).length <= 16e3 ? b.context : void 0;
+      const result = await reportIssue({ category, title: clamp(title, 200), body: clamp(body, 12e3), context });
+      if (result.ok) return { ok: true, ref: result.ref };
+      const status = result.error === "signed_out" ? 401 : result.error === "rate_limited" ? 429 : 503;
+      return reply.status(status).send({ ok: false, error: result.error });
+    }
+  );
   app.get("/api/autostart", async () => {
     const supported = autostartSupported();
     return { ok: true, supported, enabled: supported ? autostartPresent() : false };
@@ -56408,6 +56628,13 @@ async function startServer() {
       awareInstallInFlight = false;
     }
   });
+  app.get("/api/release-notes", async (req, reply) => {
+    const component = req.query.component === "aware" ? "aware" : "app";
+    const version = typeof req.query.version === "string" ? req.query.version.trim().replace(/^v/, "") : "";
+    if (!/^\d+\.\d+\.\d+(?:[-+][\w.]+)?$/.test(version)) return reply.status(400).send({ ok: false, reason: "unavailable" });
+    const notes = component === "aware" ? await getAwareReleaseNotes(version) : await getAppReleaseNotes(version);
+    return notes;
+  });
   app.post("/api/bootstrap/retry", async () => {
     const st = getBootstrapState().status;
     if (st === "failed" || st === "idle") {
@@ -56675,6 +56902,18 @@ async function startServer() {
     const running = cancelActiveRun();
     return { ok: true, running };
   });
+  app.get("/api/latest-run/:id", async (req, reply) => {
+    const id = req.params.id;
+    if (!/^[A-Za-z0-9._-]+$/.test(id)) {
+      return reply.status(400).send({ ok: false, error: "invalid app id" });
+    }
+    const latest = readLatestTrace(id);
+    if (!latest) {
+      return { ok: true, id, runId: null, status: "none", errorNodeId: null, errorMessage: null, events: [] };
+    }
+    const events = parseTrace(latest.text);
+    return { ok: true, id, runId: latest.runId, ...summarizeRun(events), events };
+  });
   function resolveArgs(configArgs, inputs) {
     const out = {};
     for (const [k, v] of Object.entries(configArgs)) {

package/dist/skills/floless-app-report-issue/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: floless-app-report-issue
+description: File a diagnosed bug / idea / question from floless.app into the PRIVATE product log via the floless.io relay. Use when the user invokes /floless-app-report-issue, clicks "Report an issue" in the floless.app UI (a queued report or a copied prompt), or says "report this", "file a bug", "something broke in floless", "send feedback / a feature idea". It READS the live run evidence first (latest run trace, failing node + error, the .flo, exec code), offers a workaround when one exists, then composes a maintainer-ready report and sends it — always showing the exact text and confirming first. Read-only: it never re-runs a workflow node.
+metadata:
+  version: 0.1.0
+---
+
+# floless.app — report an issue
+
+You are not a feedback form. You are the **on-device incident responder**: a capable AI already
+running on the user's machine, with its hands on the exact thing that broke — the workflow, the
+run trace, the `.flo`, the exec code. A report you file should arrive **diagnosed, not described**.
+
+The destination is floless.app's **private** product log. End users can't file there directly
+(it's a private repo), so the local server **relays** the report to floless.io, which files it
+on their behalf under the signed-in session. You compose + send; you never touch GitHub directly.
+
+## Preconditions
+
+- The local server is up: `curl -s http://127.0.0.1:4317/api/health` → `{"ok":true,…}` (fixed port
+  4317; override `$PORT`). It returns `appVersion`, `awareVersion`, and `license`. If it's down,
+  the user starts it from the repo (`cd server && npm run dev`).
+- A signed-in session is required to file (the relay authenticates with it). If a send returns
+  `signed_out`, tell the user to sign in (menu → the license state in the footer) and retry — do
+  not try to work around it.
+
+## Safety contract — READ-ONLY (non-negotiable)
+
+Diagnosing must never change the user's model or data.
+
+- **Never re-run an individual exec node.** Exec nodes run Roslyn C# against a **live Tekla/Trimble
+  host** and can mutate the model. There is no "re-run just this node" — don't invent one.
+- **Only** offer a *full-workflow* re-run when **all** hold: the user explicitly asks, the app is
+  `runnable`, and the latest trace shows the previous run was **non-mutating** (read-only nodes).
+  Otherwise diagnose from the evidence already on disk.
+- Everything below (`/api/health`, `/api/latest-run/:id`, `/api/app/:id`, reading the `.flo`/exec
+  source) is read-only. Stay there.
+
+## Discriminator + routing — keep the trackers clean
+
+Everything from a user funnels into the **one private floless log**; the maintainer triages and
+escalates from there. The user never has to decide "is this AWARE or floless?".
+
+- File here for: anything in the floless.app experience — the UI, a workflow/app behaving wrong, a
+  confusing result, a feature idea, a question.
+- The one exception (maintainers only): if it is *plainly* an AWARE **runtime** defect (a compiler
+  panic, a CLI bug) **and** you're operating with repo access, prefer `/aware-log-issue`
+  (→ `aware-aeco`). For an ordinary user, still file here — the maintainer escalates.
+
+## Workflow — read, diagnose, confirm, send
+
+```dot
+digraph { "health + identify app" -> "read evidence (READ-ONLY)" -> "root-cause hypothesis" ->
+  "offer workaround" -> "compose report" -> "privacy scrub + SHOW + confirm" ->
+  "POST /api/report-issue" -> "report the ref" }
+```
+
+1. **Health + identify the app.** `GET /api/health` for versions + license. Establish which app/
+   workflow the report is about (ask if unclear, or take it from a queued UI request).
+2. **Read the evidence (the killer step — READ-ONLY):**
+   - `GET /api/latest-run/<appId>` → structured trace: `runId`, `status`, `errorNodeId`,
+     `errorMessage`, `events`. This is the spine of the diagnosis.
+   - `GET /api/app/<appId>` → the normalized topology + `.flo` source + each node's `config`
+     (incl. exec `code`). Read the failing node's code; pin `file:line`.
+   - Form a concrete **root-cause hypothesis** — not "it failed", but *why*.
+3. **Offer a fix/workaround in the moment** when the evidence supports one. The user often leaves
+   already unstuck — that's the point.
+4. **Compose** the report from the template below: a diagnosed body, problem-first title.
+5. **Privacy scrub + confirm (ALWAYS).** The private log is still real: include versions + a
+   sanitized summary by default. **Ask before** attaching the `.flo`, raw logs, a screenshot, or
+   any model/company names. **Show the user the exact title + body**, then wait for an explicit
+   yes. Nothing sends without it.
+6. **Send** via the local relay:
+   ```bash
+   curl -s -X POST http://127.0.0.1:4317/api/report-issue \
+     -H 'Content-Type: application/json' \
+     -d '{"category":"bug","title":"…","body":"…","context":{ "appId":"…","appVersion":"…","awareVersion":"…","runId":"…","errorNodeId":"…" }}'
+   ```
+   → `{ "ok": true, "ref": "#123" }`. Errors: `signed_out` (sign in), `rate_limited` (wait), or
+   `offline` (check connection) — relay them plainly; the user's text is not lost.
+7. **Report** the `ref` to the user, plus any workaround you already gave. Because the repo is
+   private, there is no link to open — say so; the maintainer follows up.
+
+### Local API
+
+| Call | Purpose |
+|---|---|
+| `GET /api/health` | versions + license state |
+| `GET /api/latest-run/:id` | **read-only** structured trace of the app's most recent run |
+| `GET /api/app/:id` | normalized topology + `.flo` source + node config/exec code |
+| `POST /api/report-issue` | send the composed report through the relay → `{ ok, ref }` |
+
+## Report body template
+
+```
+**Summary** — <one line, problem-first>
+
+**Observed** (with evidence)
+- <what happened> — node `<errorNodeId>` · `<errorMessage>`
+- <file:line in the exec code, quoted, when relevant>
+
+**Root-cause hypothesis**
+- <why it happened — your diagnosis, marked as hypothesis if unconfirmed>
+
+**Repro**
+- app `<appId>` (FloLess v<appVersion>, AWARE v<awareVersion>), run `<runId>`
+- <steps / inputs>  ← attach the .flo only with consent
+
+**Expected**
+- <what AWARE/floless should have done>
+
+**Workaround given** (if any)
+- <what you told the user to do right now>
+```
+
+The local route stamps category → label and the relay adds `user-report` + the reporter id.
+
+## Guardrails
+
+- **Read-only.** Diagnose from evidence on disk; never re-run a node (live-host mutation risk).
+- **Relay only.** This skill never calls `gh` — the user has no access to the private repo; the
+  relay files on their behalf. (The maintainer `gh` runbook is the separate `floless-app-log-issue`.)
+- **Always confirm** the exact text before sending; default to versions + sanitized summary, and
+  ask before attaching anything richer.
+- **Don't invent** node ids, errors, or a fix you can't support from the evidence. A wrong-but-
+  confident diagnosis is worse than an honest "couldn't reproduce — here's what I see."
+- **One report per concern.** Don't bundle a bug and a feature idea into one.