@floless/app 0.31.2 → 0.31.4

package/dist/floless-server.cjs

@@ -52835,7 +52835,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.31.2" : void 0,
+    define: true ? "0.31.4" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52845,7 +52845,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.31.2" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.31.4" : void 0 });
 }
 
 // oauth-presets.ts

package/dist/skills/floless-app-workflows/SKILL.md

@@ -166,6 +166,31 @@ Two rules that bite immediately:
   whatever the node returns.
 - **No `System.Net`** (so no `WebUtility.HtmlEncode`) — escape with a manual lambda.
 
+## Every node's Description must be plain English (HARD guardrail)
+
+The Inspect → **Description** tab is written **for non-coders**: it must always say, in plain
+English, *what the node does* — never raw code, markup, or jargon (CLAUDE.md standing rule).
+When authoring a `.flo`, that is **your** job, node by node:
+
+- **Each `exec` node's Description IS its leading `//` comment.** `web/aware.js` `leadingComment()`
+  derives both the Description paragraph and the card blurb from the comment block at the top of
+  `config.code`. So **start every exec `code:` with a 1–2 sentence plain-English comment** that
+  explains what the node does for someone who can't read C# — e.g.
+  `// Reads the chosen phase and builds the bill of materials as an HTML table.` A node with no
+  leading comment falls back to a generic "read-mode exec node" line — that's the rubbish this
+  rule forbids. (You may *mention* a `{{ upstream.result.x }}` knob in the prose, but never let a
+  description be *only* a bare `{{ … }}` ref — and remember braces inside `code` are a run-time
+  footgun, see the templating note above.)
+- **The workflow itself needs a plain-English top-level `description:`** (a paragraph saying what
+  the app is for) — it's required, not decorative.
+- **Don't rely on the display layer to save you.** The Inspect tab summarizes oversized/baked blob
+  *inputs* (e.g. a baked `args.html` → `baked HTML · 223 KB`) so they never dump raw markup — but
+  that's a safety net for input *values*, not a license to skip the node's own plain-English
+  description.
+- **Enforced in CI:** `npm run verify:flo` (`server/build/verify-flo-descriptions.mjs`) fails the
+  build if any committed `demos/*/*.flo` ships a node with no plain-English Description. Run it
+  before you call a `.flo` done.
+
 ## The build loop (install → validate → compile → run)
 
 Resolve the `aware` CLI the same way the adapter does: prefer the npm global
@@ -377,6 +402,9 @@ past a few hard facts, split it into a `references/` file and link it.
 
 ## Guardrails (do not drift)
 
+- **Every node's Description is plain English** — each exec node opens with a 1–2 sentence
+  plain-English `//` comment (its Description), and the app has a plain-English `description:`.
+  Enforced by `npm run verify:flo` in CI. See "Every node's Description must be plain English".
 - Determinism is AWARE's: `<app>.lock` is the approved artifact; Run is gated on a fresh
   source-hash. Never let the UI run on drift.
 - Any change under `web/` requires a Playwright pass (visual + interaction), not just a check of

package/dist/web/aware.js

@@ -171,6 +171,57 @@
       .join('')}</table>`;
   }
 
+  // The Description tab is for non-coders — it must read as plain English about what a
+  // node does, never a wall of code/markup. Short scalar inputs (phase: 1, version:
+  // '2025.0') are the real knobs and show verbatim; but a baked blob (HTML markup, a
+  // large JSON payload pre-built at compile time, e.g. a steel overlay's `args.html`)
+  // is NOT plain English — dumping it raw is the "rubbish" this view must never show.
+  // So anything oversized collapses to a dimmed one-line summary ("baked HTML · 210.0 KB").
+  const DESC_BLOB_CHARS = 500;
+  function summarizeInputValue(v) {
+    const isStr = typeof v === 'string';
+    const raw = isStr ? v : v == null ? '' : JSON.stringify(v);
+    // Summarize on size OR on any markup/code shape — a non-coder must never see raw
+    // markup, however short. (The slice bounds the scan to 500 chars; the regex is
+    // already linear — a single [^>]* with a disjoint `>` terminator — so no ReDoS.)
+    const markup = /<\/?[a-z!][^>]*>/i.test(raw.slice(0, 500));
+    if (raw.length <= DESC_BLOB_CHARS && !markup) return { text: raw, blob: false };
+    const size = raw.length >= 1024 ? (raw.length / 1024).toFixed(1) + ' KB' : raw.length + ' chars';
+    const kind = markup ? 'HTML' : isStr ? 'content' : 'JSON';
+    return { text: `baked ${kind} · ${size}`, blob: true };
+  }
+
+  // Exec nodes receive their inputs wrapped in an `args` object (an AWARE implementation
+  // detail of how exec passes data in). Flatten that one level so a non-coder sees the
+  // real knobs (phase, html…) directly instead of an `args: {…}` row. `code` is the
+  // implementation, never an input, so it's dropped; a flattened member that collides
+  // with a real top-level input yields to the top-level value.
+  function flattenInputs(inputs) {
+    const out = Object.create(null); // null-proto: keys like `constructor`/`__proto__` stay plain data
+    for (const [k, v] of Object.entries(inputs || {})) {
+      if (k === 'code') continue;
+      if (k === 'args' && v && typeof v === 'object' && !Array.isArray(v)) {
+        for (const [ak, av] of Object.entries(v)) if (ak !== 'code' && !Object.hasOwn(out, ak)) out[ak] = av;
+      } else {
+        out[k] = v;
+      }
+    }
+    return out;
+  }
+
+  // Description-tab Inputs block: flattened, plain-English, baked blobs summarized and
+  // dimmed (meta, not data). Empty inputs → no block at all.
+  function descInputs(inputs) {
+    const rows = Object.entries(flattenInputs(inputs));
+    if (!rows.length) return '';
+    const body = rows.map(([k, v]) => {
+      const s = summarizeInputValue(v);
+      const cell = s.blob ? `<span class="dim-note">${escapeHtml(s.text)}</span>` : escapeHtml(s.text);
+      return `<tr><th>${escapeHtml(k)}</th><td>${cell}</td></tr>`;
+    }).join('');
+    return `<p><strong>Inputs</strong></p><table class="kv">${body}</table>`;
+  }
+
   // Plain-text summary of one declared command input (for the Skill tab's inputs
   // table — kvTable escapes it, so this stays text, no markup): "type (enum vals)
   // · default X — description".
@@ -308,8 +359,6 @@
     // EXCLUDES the code (code belongs to the Code tab, never dumped here).
     const plainDesc = execSource ? leadingComment(execSource) : '';
     const blurbText = plainDesc && (s => s.length > 80 ? s.slice(0, 79) + '…' : s)(plainDesc.replace(/\.\s+.*/, '.').trim());
-    const inputsNoCode = {};
-    for (const [k, v] of Object.entries(inputs || {})) if (k !== 'code') inputsNoCode[k] = v;
     return {
       _mode: n.mode,
       _runtimeModel: !!n.runtimeModel, // B2: lock stamped runtime-model → card badge
@@ -321,7 +370,7 @@
       title: escapeHtml(n.id),
       subtitle: `${agentLabel}${cmd ? '/' + cmd : ''} · ${mode}`,
       blurb: blurbText ? escapeHtml(blurbText) : n.notes[0] ? escapeHtml(humanizeNote(n.notes[0].text)) : `${mode}-mode ${cmd ? '<code>' + cmd + '</code>' : escapeHtml(n.kind)} node`,
-      description: `${plainDesc ? `<p>${escapeHtml(plainDesc)}</p>` : ''}<p>Resolves to ${modeBadge} via <code>${escapeHtml(n.agent || n.kind)}${n.command ? '.' + escapeHtml(n.command) : ''}</code>.</p>${Object.keys(inputsNoCode).length ? `<p><strong>Inputs</strong></p>${kvTable(inputsNoCode)}` : ''}${execSource ? `<p class="dim-note">Full source in the <strong>Code</strong> tab.</p>` : ''}${notesHtml}`,
+      description: `${plainDesc ? `<p>${escapeHtml(plainDesc)}</p>` : ''}<p>Resolves to ${modeBadge} via <code>${escapeHtml(n.agent || n.kind)}${n.command ? '.' + escapeHtml(n.command) : ''}</code>.</p>${descInputs(inputs)}${execSource ? `<p class="dim-note">Full source in the <strong>Code</strong> tab.</p>` : ''}${notesHtml}`,
       // Rich agent/command detail when the manifest is installed (n.skill); else
       // the lock-pointer fallback below (exec/agent-less nodes, uninstalled agents).
       skill: skillBody(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.31.2",
+  "version": "0.31.4",
   "type": "module",
   "description": "Thin localhost host for floless.app — serves web/ and shells the aware CLI. No engine, no LLM.",
   "bin": {
@@ -24,6 +24,7 @@
     "build": "node build/bundle.mjs",
     "build:exe": "node build/bundle.mjs && node build/make-sea.mjs",
     "verify:skills": "node build/verify-shipped-skills.mjs",
+    "verify:flo": "node build/verify-flo-descriptions.mjs",
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build"
   },