@floless/app 0.31.3 → 0.31.4

package/dist/floless-server.cjs

@@ -52835,7 +52835,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.31.3" : 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.3" : 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.31.3",
+  "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"
   },