@floless/app 0.5.2 → 0.6.0

package/dist/floless-server.cjs

@@ -16329,7 +16329,7 @@ var require_core = __commonJS({
     };
     var MAX_EXPRESSION = 200;
     function requiredOptions(o) {
-      var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0;
+      var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v2, _w, _x, _y, _z, _0;
       const s = o.strict;
       const _optz = (_a = o.code) === null || _a === void 0 ? void 0 : _a.optimize;
       const optimize = _optz === true || _optz === void 0 ? 1 : _optz || 0;
@@ -16347,7 +16347,7 @@ var require_core = __commonJS({
         meta: (_s = o.meta) !== null && _s !== void 0 ? _s : true,
         messages: (_t = o.messages) !== null && _t !== void 0 ? _t : true,
         inlineRefs: (_u = o.inlineRefs) !== null && _u !== void 0 ? _u : true,
-        schemaId: (_v = o.schemaId) !== null && _v !== void 0 ? _v : "$id",
+        schemaId: (_v2 = o.schemaId) !== null && _v2 !== void 0 ? _v2 : "$id",
         addUsedSchema: (_w = o.addUsedSchema) !== null && _w !== void 0 ? _w : true,
         validateSchema: (_x = o.validateSchema) !== null && _x !== void 0 ? _x : true,
         validateFormats: (_y = o.validateFormats) !== null && _y !== void 0 ? _y : true,
@@ -51362,6 +51362,9 @@ function cancelActiveRun() {
   killTree(run.child);
   return true;
 }
+function isRunActive() {
+  return activeRun !== null;
+}
 var LOGS_DIR = process.env.AWARE_HOME ? (0, import_node_path3.join)(process.env.AWARE_HOME, "logs") : (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".aware", "logs");
 var TRIGGER_POLL_MS = 250;
 function parseRunHandle(stdout) {
@@ -51797,12 +51800,12 @@ function cmpVersions(a, b) {
   return 0;
 }
 function decideBootstrap(input) {
-  const { toolchain, aware: aware2, pin, skip } = input;
+  const { toolchain, aware: aware2, floor, skip } = input;
   if (!toolchain.hasNode) return { kind: "fail", reason: "no-node" };
   if (skip) return aware2.installed ? { kind: "ready" } : { kind: "fail", reason: "absent-and-skipped" };
-  if (aware2.installed && isValidVersion(aware2.version) && cmpVersions(aware2.version, pin) >= 0) return { kind: "ready" };
+  if (aware2.installed && isValidVersion(aware2.version) && cmpVersions(aware2.version, floor) >= 0) return { kind: "ready" };
   if (!toolchain.hasNpm) return aware2.installed ? { kind: "ready" } : { kind: "fail", reason: "no-npm" };
-  return { kind: "install", version: pin };
+  return { kind: "install", version: "latest" };
 }
 var REMEDIATION = {
   "no-node": "AWARE needs Node.js 20+. Install it from https://nodejs.org and relaunch floless.app.",
@@ -51840,7 +51843,7 @@ function runBootstrap(deps) {
       set(deps, { status: "probing", awareReady: false, awareVersion: null, reason: null, remediation: null });
       const aware0 = deps.getAware();
       version = aware0.version;
-      const decision = decideBootstrap({ toolchain: deps.probeToolchain(), aware: aware0, pin: deps.pin, skip: deps.skip });
+      const decision = decideBootstrap({ toolchain: deps.probeToolchain(), aware: aware0, floor: deps.floor, skip: deps.skip });
       if (decision.kind === "fail") return fail(deps, decision.reason, version);
       if (decision.kind === "install") {
         set(deps, { status: "installing", awareReady: false, awareVersion: version, reason: null, remediation: null });
@@ -52251,7 +52254,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.5.2" : void 0,
+    define: true ? "0.6.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52261,7 +52264,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.5.2" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.6.0" : void 0 });
 }
 
 // bake.ts
@@ -53730,12 +53733,95 @@ async function applyUpdate(check, opts) {
   return { applied: true, message: `updating to v${check.targetVersion}\u2026 the app will relaunch` };
 }
 
+// aware-update.ts
+var REGISTRY_LATEST = "https://registry.npmjs.org/@aware-aeco/cli/latest";
+var FEED_TIMEOUT_MS2 = 15e3;
+var VERSION_TTL_MS = 5e3;
+var _v = null;
+function awareInstalledVersion(probe = aware.npmVersion) {
+  const now = Date.now();
+  if (_v && now - _v.at < VERSION_TTL_MS) return _v.val;
+  _v = { at: now, val: probe() };
+  return _v.val;
+}
+function invalidateAwareVersion() {
+  _v = null;
+}
+function versionGt2(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+function decideAwareUpdate(cur, latest) {
+  const base = { supported: true, currentVersion: cur };
+  if (!latest) return { ...base, updateAvailable: false, reason: "could not read the npm registry latest" };
+  if (!cur) return { ...base, updateAvailable: false, targetVersion: latest, reason: "AWARE not installed yet" };
+  if (versionGt2(latest, cur)) return { ...base, updateAvailable: true, targetVersion: latest };
+  return { ...base, updateAvailable: false, targetVersion: latest, reason: `already up to date (v${cur})` };
+}
+async function fetchAwareLatest() {
+  try {
+    const res = await fetch(REGISTRY_LATEST, { redirect: "follow", signal: AbortSignal.timeout(FEED_TIMEOUT_MS2) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+async function checkAwareUpdate() {
+  const cur = awareInstalledVersion();
+  const latest = await fetchAwareLatest();
+  return decideAwareUpdate(cur, latest);
+}
+async function applyAwareUpdate(deps) {
+  try {
+    await deps.install("latest");
+    deps.refresh();
+    invalidateAwareVersion();
+    return { ok: true, version: deps.probe() };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function awareApplyDeps(install) {
+  return { install, refresh: refreshInvoker, probe: aware.npmVersion };
+}
+function awareUpgradeBlockReason(s) {
+  if (s.bootstrapInstalling || s.installInFlight) return "an AWARE install is already in progress \u2014 try again in a moment";
+  if (s.runActive) return "a workflow run is in progress \u2014 wait for it to finish before upgrading AWARE";
+  if (s.hostWatcherActive) return "a live trigger/watch session is using the host \u2014 stop it before upgrading AWARE";
+  return null;
+}
+
 // skill-sync.ts
 var import_node_fs15 = require("node:fs");
 var import_node_os9 = require("node:os");
 var import_node_path13 = require("node:path");
 var import_node_url = require("node:url");
 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
+  "floless-app-onboarding",
+  // guided, re-runnable tour of AWARE + floless.app for new users
+  "floless-app-routines",
+  //   author event-driven ("on trigger") routines
+  "floless-app-workflows"
+  //  author/run .flo workflows
+];
+function selectShippedSkillNames(names) {
+  const present = new Set(names);
+  return PRODUCT_SKILLS.filter((name) => present.has(name));
+}
+
+// skill-sync.ts
 var __dirname2 = (0, import_node_path13.dirname)((0, import_node_url.fileURLToPath)(__import_meta_url));
 function bundledSkillsRoot() {
   const candidates = [
@@ -53799,7 +53885,7 @@ function decideAction(installed, bundled) {
 function bundledSkills(root) {
   let entries = [];
   try {
-    entries = (0, import_node_fs15.readdirSync)(root).filter((n) => n.startsWith("floless-app-"));
+    entries = selectShippedSkillNames((0, import_node_fs15.readdirSync)(root));
   } catch {
     return [];
   }
@@ -55645,7 +55731,7 @@ async function startServer() {
     }
   });
   await app.register(import_static.default, { root: WEB_ROOT, prefix: "/" });
-  const KNOWN_GOOD_AWARE = "0.51.0";
+  const MIN_AWARE = "0.51.0";
   const isWin3 = process.platform === "win32";
   const has = (cmd) => {
     try {
@@ -55655,14 +55741,10 @@ async function startServer() {
       return false;
     }
   };
-  const bootstrapDeps = {
-    probeToolchain: () => ({ hasNode: has("node"), hasNpm: has("npm") }),
-    getAware: () => {
-      const v = aware.npmVersion();
-      return { installed: v !== null, version: v };
-    },
-    installAware: (version, onLine) => new Promise((resolve4, reject) => {
-      const child = (0, import_node_child_process5.spawn)("npm", ["i", "-g", `@aware-aeco/cli@${version}`], { shell: isWin3, windowsHide: true });
+  function installAwareGlobal(spec, onLine = () => {
+  }) {
+    return new Promise((resolve4, reject) => {
+      const child = (0, import_node_child_process5.spawn)("npm", ["i", "-g", `@aware-aeco/cli@${spec}`], { shell: isWin3, windowsHide: true });
       let stderrTail = "";
       let combinedTail = "";
       const tail = (buf, s) => (buf + s).slice(-4e3);
@@ -55679,11 +55761,19 @@ async function startServer() {
       });
       child.on("error", (e) => reject(e));
       child.on("close", (code) => code === 0 ? resolve4() : reject(new Error(`npm exited ${code}: ${stderrTail || combinedTail}`)));
-    }),
+    });
+  }
+  const bootstrapDeps = {
+    probeToolchain: () => ({ hasNode: has("node"), hasNpm: has("npm") }),
+    getAware: () => {
+      const v = aware.npmVersion();
+      return { installed: v !== null, version: v };
+    },
+    installAware: installAwareGlobal,
     smoke: () => aware.smoke(),
     refreshInvoker,
     emit: broadcast,
-    pin: KNOWN_GOOD_AWARE,
+    floor: MIN_AWARE,
     skip: process.env.AWARE_SKIP_BOOTSTRAP === "1"
   };
   app.setErrorHandler((err, _req, reply) => {
@@ -55715,7 +55805,7 @@ 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")) 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;
     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 });
@@ -55734,7 +55824,8 @@ async function startServer() {
       ok: true,
       appVersion: appVersion(),
       // the installed build (sq.version), so it's scriptable
-      awareVersion: bs.awareVersion,
+      awareVersion: awareInstalledVersion() ?? bs.awareVersion,
+      // fresh (TTL-cached) install version; the boot snapshot is only a fallback
       awareReady: bs.awareReady,
       bootstrap: bs.status,
       bootstrapReason: bs.reason,
@@ -55781,6 +55872,27 @@ async function startServer() {
     reply.send({ ok: true, ...result });
     setTimeout(() => process.exit(0), 250);
   });
+  app.get("/api/aware/update", async () => {
+    return { ok: true, ...await checkAwareUpdate() };
+  });
+  let awareInstallInFlight = false;
+  app.post("/api/aware/update/apply", async (_req, reply) => {
+    const block = awareUpgradeBlockReason({
+      bootstrapInstalling: getBootstrapState().status === "installing",
+      installInFlight: awareInstallInFlight,
+      runActive: isRunActive(),
+      hostWatcherActive: hostWatcherActive()
+    });
+    if (block) return reply.status(409).send({ ok: false, error: block });
+    awareInstallInFlight = true;
+    try {
+      const res = await applyAwareUpdate(awareApplyDeps(installAwareGlobal));
+      if (!res.ok) return reply.status(409).send({ ok: false, error: res.error ?? "aware upgrade failed" });
+      return { ok: true, version: res.version };
+    } finally {
+      awareInstallInFlight = false;
+    }
+  });
   app.post("/api/bootstrap/retry", async () => {
     const st = getBootstrapState().status;
     if (st === "failed" || st === "idle") {

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

@@ -0,0 +1,106 @@
+---
+name: floless-app-onboarding
+description: This skill should be used to onboard a user into floless.app and its AWARE runtime as a guided, re-runnable walkthrough. It first explains what AWARE is (the runtime), checks the installed AWARE version and offers an update, maps the command surface, and shows the AVAILABLE agents via the `aware agent catalog` command (installing one on request); then it tours floless.app (the 3-column chat/canvas/inspect UI, the Compile-Approve-Run gate, Simulate vs real Run, Templates, Routines, the Agents library, Bake and Graft, the Inspect tabs, the version footer) and the three floless skills (bridge, routines, workflows). Use it when the user is new or wants a refresher, on triggers like "onboard me", "get me started", "I'm new to floless.app or AWARE", "give me a tour", "how do I use this", "walk me through floless.app", "what can AWARE do", "show me the agents", or "/floless-app-onboarding". It can be re-invoked anytime for the whole tour or a single section.
+metadata:
+  version: 0.1.0
+---
+
+# Onboarding a user into floless.app + AWARE
+
+Guide the user through the whole program end-to-end, as the **host terminal AI** they are talking
+to. floless.app is a **thin web UI**; the terminal AI (you) is the brain and AWARE is the runtime.
+This skill makes you the tour guide: explain AWARE first (the runtime everything sits on), then
+floless.app (the window onto it), driving the user's **real** environment as you go.
+
+Two arcs, with detail pushed to references (read each one when entering its arc):
+
+- **Arc A — AWARE, the runtime** → `references/aware-runtime.md`
+- **Arc B — floless.app, the UI** → `references/floless-app-tour.md`
+
+## Operating principles (apply throughout)
+
+- **Drive live, don't just lecture.** Run the read-only probes as they come up (`/api/health`, the
+  AWARE version, `aware agent catalog`) and narrate the user's **actual** state — their version,
+  their agents, what's on their canvas. A tour of the real thing beats prose.
+- **Mutations need consent.** Anything that changes the machine — updating AWARE, installing an
+  agent — is **offered, then run only on an explicit yes**. Read-only probes run freely.
+- **Degrade gracefully, never block.** Features land at different times. If a command or endpoint is
+  missing (e.g. an older AWARE without `aware agent catalog`, or the in-app AWARE-upgrade pill not
+  yet present), say so plainly, fall back to what exists, and keep going. Each arc's reference spells
+  out its fallback.
+- **Stay faithful to the architecture.** The UI never becomes the brain; determinism is AWARE's (the
+  `.lock` is the approved contract, Run is gated on source-hash freshness). Never teach anything that
+  contradicts this.
+- **One concept at a time; check in often.** This is a walkthrough, not a wall of text. After each
+  section, pause — "make sense? want to go deeper, or move on?" Let the user steer the pace.
+
+## Step 0 — Orient and route
+
+1. **Confirm the ground.** Probe the floless.app server and the installed AWARE version (read-only):
+   ```bash
+   curl -s http://127.0.0.1:4317/api/health
+   # → {"ok":true,"license":"valid","awareVersion":"<installed>", ...}
+   ```
+   - No response → the floless.app desktop app isn't running. Ask the user to start it (so the tour
+     can drive its UI). The AWARE arc still works without it.
+   - `awareVersion` is the AWARE version the app reports. On current builds it's freshly re-probed
+     and trustworthy; an **older app build can show a stale snapshot**, so when the exact version
+     matters (e.g. deciding whether to update), confirm it against npm in A2 — `npm ls -g
+     @aware-aeco/cli` is the source of truth. Note the version for Arc A.
+   - `license` not `valid`/`offline-grace` → some UI actions sit behind a sign-in gate; mention it
+     when the UI arc reaches a gated action, don't block the tour.
+
+2. **Pick the path.** Ask the user once:
+   > "Want the **full guided tour** (AWARE → floless.app), or **jump to one section**?"
+   - **New user / unsure → full tour:** run Arc A then Arc B, in order, top to bottom.
+   - **Refresher → menu:** show the section map below and run only the chosen section(s).
+   - The user can always say "skip ahead", "go deeper on X", or "stop" — honor it.
+
+## The section map (also the re-run menu)
+
+Offer this list when the user wants to jump. Each item maps to a section in a reference file.
+
+**Arc A — AWARE (the runtime)** — `references/aware-runtime.md`
+- **A1 · What AWARE is** — the substrate; where it lives (`~/.aware`); build-once / run-forever.
+- **A2 · Version & update** — show the installed version, check for newer, offer the update (consent).
+- **A3 · The command surface** — the `aware` verbs worth knowing (apps, agents, sidecars, logs).
+- **A4 · Available agents** — browse `aware agent catalog`, search, capability-check, install one (consent).
+
+**Arc B — floless.app (the UI)** — `references/floless-app-tour.md`
+- **B1 · The 3-column window** — chat│canvas│inspect; the app is the prompt, the browser is the window.
+- **B2 · The gate** — Compile → Approve → Run; the source-hash Run gate; Simulate vs real Run.
+- **B3 · Templates, Routines, Agents, Inspect** — the panels and tabs the user will actually click.
+- **B4 · The footer** — installed AWARE version + app version; updating AWARE / the app from here.
+- **B5 · Bake & Graft** — export a workflow as an agent (Bake); import your own tool as an agent (Graft).
+- **B6 · The floless skills** — bridge / routines / workflows, and how to drive them from the terminal.
+- **B7 · How to run + best practices** — the everyday loop and the habits that keep it deterministic.
+
+## Running an arc
+
+When entering **Arc A**, read `references/aware-runtime.md` and walk A1→A4 (or the chosen item).
+When entering **Arc B**, read `references/floless-app-tour.md` and walk B1→B7 (or the chosen item).
+Each reference carries the exact commands, the talking points, the consent prompts, and the
+fallbacks. Narrate the user's real output; do not paste a reference verbatim.
+
+## Close
+
+When the tour (or chosen section) is done, recap in two or three lines what the user now knows, and
+tell them how to come back:
+
+> "That's the tour. Re-run **/floless-app-onboarding** anytime — for the whole thing, or just name a
+> section ('the agents part', 'Bake & Graft', 'routines') and I'll jump straight there."
+
+Then offer a concrete next step grounded in what they have — e.g. "want to build your first
+workflow?" (hand off to **floless-app-workflows**) or "install one of those agents?" (A4).
+
+## Guardrails
+
+- **Read-only by default; mutations on consent.** Never update AWARE or install an agent without an
+  explicit yes.
+- **Never invent.** Don't name agents, commands, or UI elements that aren't really there — probe and
+  report what exists. If `aware agent catalog` is unavailable, say so and use `aware agent list`.
+- **Don't contradict the architecture.** The UI renders AWARE state and triggers `aware` verbs; it
+  never composes workflows or calls an LLM. Determinism is AWARE's `.lock`.
+- **Hand off for depth.** Onboarding orients; it does not replace the doing-skills. Point to
+  **floless-app-workflows** (build/run `.flo` apps), **floless-app-routines** (automate them), and
+  **floless-app-bridge** (apply UI tweaks/templates) when the user wants to actually do the thing.

package/dist/skills/floless-app-onboarding/references/aware-runtime.md

@@ -0,0 +1,159 @@
+# Arc A — AWARE, the runtime
+
+The detail behind Arc A. Walk A1→A4 (or the one section the user picked). Run the read-only probes
+live and narrate the user's real output; offer mutations (update, install) and run them only on a
+yes. Keep each section short and check in before moving on.
+
+---
+
+## A1 · What AWARE is
+
+**The pitch (say it in plain terms):** AWARE is the open-source **agentic substrate for AECO**
+([github.com/aware-aeco/aware](https://github.com/aware-aeco/aware)) — the runtime everything in
+floless.app sits on. You describe what you want; the terminal AI composes a plain-text **`.flo`**
+workflow; AWARE **compiles** it into a frozen, version-pinned **`.lock`** (the approved contract) and
+**runs** it. floless.app is just the window onto this — it holds no engine and no LLM of its own.
+
+**Build once, run forever** (the core idea — make sure it lands):
+- `aware app compile` freezes a workflow's source into `<app>.lock` and pins the agent versions.
+- `aware app run` **refuses to run** if the source changed since that compile (a "source-hash drift").
+  So an approved app stays exactly as approved until you deliberately recompile. That gate is what
+  makes runs reproducible — and it's the same gate the floless.app **Run** button enforces (B2).
+- Determinism is layered: the `.lock` at the **app** level, and compiled code (an `exec` node's C#,
+  a Smart Node) at the **node** level.
+
+**Where it lives** (show them — read-only):
+```bash
+ls ~/.aware
+# apps/        installed workflows (<id>/<app>.flo + <app>.lock)
+# agents/      installed capabilities apps can call
+# bridges/     host connectors (e.g. aware-tekla.exe)
+# logs/        per-run JSONL execution traces
+# credentials/ connection secrets (opaque; never through the model)
+```
+AWARE itself is installed as the npm global **`@aware-aeco/cli`** (not bundled into floless.app —
+floless.app installs/repairs it on first start). That detail matters for A2.
+
+---
+
+## A2 · Version & update
+
+**Show the installed version.** The **authoritative source is the installed npm package** (a file
+read of what's actually on disk, not a guess):
+```bash
+npm ls -g @aware-aeco/cli         # the installed global — the source of truth
+```
+The floless.app footer and `/api/health` (`awareVersion`, captured in Step 0) also surface it —
+freshly re-probed on current builds, but an **older app build can show a stale boot snapshot**. If
+the app's number and npm disagree, trust npm. State the version back to the user.
+
+**Check for a newer release** (read-only):
+```bash
+npm view @aware-aeco/cli version  # the latest published on npm
+```
+Compare to the installed version. If they match, say "you're on the latest" and move on.
+
+**If newer exists, offer the update (consent — don't run it unprompted):**
+> "AWARE v<new> is out (you're on v<cur>). Update now?"
+
+The reliable path on **every** build is the npm global — lead with it:
+```bash
+npm i -g @aware-aeco/cli@latest    # always works; no running app required
+```
+**Newer floless.app builds also add an in-app shortcut:** a footer **`↑ Upgrade AWARE to v<target>`**
+pill next to the version (clicking it reinstalls in place, no relaunch) — programmatically
+`GET /api/aware/update` then `POST /api/aware/update/apply`. If that pill isn't there, the app isn't
+running, or `GET /api/aware/update` 404s, the build predates the shortcut — just use the npm command
+above.
+
+After applying, **re-probe** (`npm ls -g @aware-aeco/cli`) and confirm the new version to the user.
+
+**Why there's a button at all:** floless.app installs `@aware-aeco/cli@latest` above a minimum floor
+on first run, but it deliberately does **not** force-upgrade an existing install on every boot (no
+surprise upgrades, no slow starts). Moving an up-to-date-enough install to the newest release is
+exactly what this on-demand update is for.
+
+---
+
+## A3 · The command surface
+
+Give a **map**, not an exhaustive dump. Most of these the user will drive through floless.app's
+buttons (B2) — the CLI is the same machinery underneath. Group it like this, then suggest
+`aware --help` (and `aware app --help` / `aware agent --help`) to see the live surface for *their*
+version rather than enumerating flags they may not have.
+
+**Apps — the workflows (`aware app …`):**
+- `list` — installed apps. `show <id>` — an app's manifest. `inspect <dir>` — the "Glass Box" plan
+  (takes the app **path**, like `validate`/`compile`).
+- `install <dir>` — install from an app **directory**. `uninstall <id>`.
+- `validate <dir>` / `compile <dir>` — check / freeze to `<app>.lock` (compile is "Approve").
+- `run <id> [--input k=v] [--json]` — execute the approved app (run takes the **id**).
+- `logs` — past runs (traces also land at `~/.aware/logs/<id>/…`).
+
+**Agents — the capabilities apps call (`aware agent …`):**
+- `list` — **installed** agents. `describe <id>` — an installed agent's commands + skills.
+- `install <id>` / `uninstall <id>` — add/remove a capability.
+- …plus the **catalog** commands for discovering agents you *don't* have yet — that's A4.
+
+**Sidecars / bridges — host connectors (`aware sidecar …`):**
+- `install <host>` — fetch a host bridge (e.g. `tekla`, `rhino`, `sketchup`, `revit`) so workflows
+  can drive that application. Required before a real host run against, say, a live Tekla model.
+
+**Build — graft a tool into an agent (`aware build agent --from-…`):**
+- Turns a foreign tool you own (a DLL, an OpenAPI spec, a NuGet/npm package, a COM ProgID, a CLI…)
+  into a first-class AWARE agent. This is the **Graft** capability — covered in B5.
+
+**Connections / credentials (`aware connect …`):** wire up external services; secrets live as opaque
+handles under `~/.aware/credentials/`, never passed through the model.
+
+---
+
+## A4 · Available agents (browse before you install)
+
+**The gap to explain:** `aware agent list` and `aware agent describe` only see agents you've
+**already installed**. To discover *what agents exist* before installing — and what each one does —
+use the **catalog** — a searchable index of available agents across architecture, construction,
+engineering, and visualization (the live count is whatever `aware agent catalog` prints for the
+user; don't quote a fixed number).
+
+**Browse — run it live and narrate the result:**
+```bash
+aware agent catalog
+# ID · DISPLAY-NAME · VERSION · STATUS · COMMANDS · SKILLS · DESCRIPTION (one line)
+```
+Point out a few agents relevant to the user's domain (for an AEC user: `tekla`, `rhino`, `revit`,
+etc.). Add `--json` for machine-readable output.
+
+**Search by functionality:**
+```bash
+aware agent search "steel connection"
+aware agent search "macro" --capability   # --capability biases to command names/methods
+```
+
+**Describe one you haven't installed:**
+```bash
+aware agent describe <id> --available      # full description + commands + skills for a NOT-installed agent
+```
+(Plain `aware agent describe <id>` stays installed-only; `--available` reaches into the catalog.)
+
+**Capability check (scriptable, exits 0/1):**
+```bash
+aware agent has <agent> <capability>       # exit 0 if it exposes that capability, nonzero if not
+```
+
+**Install on request (consent — this changes the machine):**
+> "Want me to install `<id>`?"
+```bash
+aware agent install <id>
+```
+It lands under `~/.aware/agents/<id>/`, then appears in `aware agent list` and is usable as a
+workflow node (`agent: <id>`). It also shows up in floless.app's **`⊞ Agents`** library (B3).
+
+**Degradation — older AWARE has no catalog (handle this gracefully):**
+The catalog commands are newer than some installs. If `aware agent catalog` errors, is an unknown
+subcommand, or prints something like *"this AWARE's registry has no catalog yet — update AWARE"*,
+then the user's AWARE predates the feature. Don't push through it:
+1. Say so plainly: "Your AWARE is a bit older and doesn't have the agent catalog yet."
+2. Point back to **A2** and offer the update (`npm i -g @aware-aeco/cli@latest`) — on consent.
+3. Until they update, fall back to `aware agent list` (installed-only) so the section still delivers
+   *something* — show what they already have, and note the catalog unlocks discovery once updated.

package/dist/skills/floless-app-onboarding/references/floless-app-tour.md

@@ -0,0 +1,149 @@
+# Arc B — floless.app, the UI
+
+The detail behind Arc B. Walk B1→B7 (or the one section the user picked). Point the user at the
+real elements in their browser (floless.app at `http://127.0.0.1:4317`) and, where useful, show the
+live state. Keep each section short; check in before moving on. If the app isn't running, ask the
+user to start it first.
+
+Throughout: floless.app is a **thin UI** — it renders AWARE state and triggers `aware` verbs. It
+never composes workflows or calls an LLM. The terminal AI (you) is the brain.
+
+---
+
+## B1 · The 3-column window
+
+The layout is **header / `chat │ canvas │ inspect` / footer**:
+- **Left — chat (~340px):** "the app is the prompt; it lives in your AI terminal; the browser is the
+  window." This panel is a relay/echo of the terminal session, **not a second chatbot** — the real
+  conversation is where you're typing now, in the terminal.
+- **Center — canvas:** the open workflow's **topology** — nodes and the edges between them, rendered
+  from the `.flo`. Zoom / fit controls; click a node to inspect it; **star ★** a node to save it as a
+  reusable Template (B3).
+- **Right — inspect (~420px):** details of the selected node (B3).
+- **Top-left — the workflow switcher:** pick which installed app is on the canvas. A small dot marks
+  unsaved edits.
+
+Have the user pick a workflow from the switcher so there's something real on the canvas to tour.
+
+---
+
+## B2 · The gate (Compile → Approve → Run)
+
+The header carries the run controls and a **state** chip. This is "build once, run forever" (A1)
+made visible:
+
+- **`⎙ Compile`** — freezes the current `.flo` into its **`.lock`**. This *is* "Approve": the lock is
+  the contract that will run. After any edit, the Run gate **locks** until you Compile again (the
+  source-hash changed — a "drift").
+- **`▶ Run workflow`** — the **real** run: executes the approved app against your live host. Each node
+  paints progress on the canvas (running → ✓ done / ✗ failed); if the app produces a report, the HTML
+  Viewer opens with the result. Run always executes the single open workflow against your one live
+  host — there's no parallel or multi-target run.
+- **`Simulate`** — a **composition check**: every node is stubbed from its schema, no host touched.
+  Great for sanity-checking a workflow's *shape* fast. Caveat to mention: Simulate can't truly run
+  data-carrying `exec` apps (stubs carry no real values) — for those, use the real Run.
+- **state chip** — shows where the gate is (needs compile / ready / running).
+
+The everyday rhythm: **edit → Compile/Approve → Run**. Run stays disabled on drift until you
+re-Compile. That gate is what keeps runs reproducible.
+
+---
+
+## B3 · Templates, Routines, Agents, Inspect
+
+The panels and buttons the user will actually click:
+
+- **Templates (★):** star any node on the canvas — or, inside the Agents library, any command — to
+  save it as a reusable **Template**. It appears in the template bar and is reusable in **any**
+  workflow, and persists across projects. The terminal AI is *template-aware*: when a plain-English
+  request matches a saved Template, it reuses that saved logic instead of rebuilding it.
+- **Routines (`⏱ Routines`):** run a workflow **automatically** — on a **schedule** (e.g. weekdays at
+  07:00) or on a **trigger** (a live event, e.g. *whenever your Tekla model changes*). Runs happen on
+  this machine through your live host, exactly like clicking ▶ Run. Authoring path: the
+  **floless-app-routines** skill (B6).
+- **Agents (`⊞ Agents`):** the **Agents library** — every installed agent, each command starrable as a
+  Template. Agents you install (A4) show up here. It's also the entry point to **Graft** (B5).
+- **Inspect (right panel):** click any node → its details. The tabs surface the node's
+  **Description / Skill**, its **Code** (the real source — an `exec` node's C#, syntax-highlighted),
+  and the live **Execution** trace while a run is in flight. A report/viewer node carries a
+  **"View report ▸"** button that opens the in-app **HTML Viewer** (a sandboxed iframe showing the
+  last result — load is split from run, so it shows the last report instantly without recomputing).
+- **Tweak (✎):** select a node and queue a plain-English change ("also group by assembly"). The
+  terminal AI picks it up (via **floless-app-bridge**, B6), edits just that one node, and recompiles —
+  the UI itself never edits the `.flo`.
+
+---
+
+## B4 · The footer
+
+The bottom strip shows the **installed AWARE version** and the **floless.app version**.
+- On current builds the AWARE version is **live** — it re-stamps if AWARE changes out of band (e.g.
+  you updated it from the terminal). On older builds it can be a boot-time snapshot, so if it ever
+  looks off, npm is the source of truth (A2).
+- Update affordances live here too: an **app self-update** pill (`↑ Update to v…`) when a newer
+  floless.app is published, and — on builds that include it — an **`↑ Upgrade AWARE to v…`** pill (the
+  in-app AWARE update from A2). If you don't see the AWARE pill, your build predates it; the reliable
+  path is always the CLI (`npm i -g @aware-aeco/cli@latest`).
+
+---
+
+## B5 · Bake & Graft (the two killer moves)
+
+A matched pair — the input and output sides of "turn things into agents":
+
+- **Bake — export a workflow as an agent.** (Reachable from the workflow menu as **"Bake into
+  agent"**; the confirm action carries the **⊙ Bake** glyph.) Takes a working multi-node `.flo` and
+  packages it as a single **callable agent** whose inputs become the agent's parameters. AWARE
+  reinstalls it with that exposed interface; it then appears in the **Agents library** as one callable
+  node that other workflows can drop in. (Mechanism: `exposes-as-agent` + `exposed-commands` in the
+  `.flo`.) Use it to turn a proven workflow into a reusable building block.
+- **Graft — import your own tool as an agent.** (Reachable from the **`⊞ Agents`** library —
+  **"Graft new agent"** — or the workflow menu.) The input-side mirror of Bake. Turn a foreign tool
+  you already own — a .NET DLL (or a whole folder of them), an OpenAPI spec, a NuGet/npm package, a
+  COM ProgID, a CLI — into a first-class AWARE agent you can compose. The hero case: an in-house Tekla
+  plugin becomes a headless command you can run across an entire model at 2am. (Mechanism: AWARE's
+  `aware build agent --from-…`, A3; floless stages a preview of the discovered commands before you
+  commit.)
+
+The full arc: **Graft your tool → compose it into a workflow → Bake the workflow → distribute.** That
+is how floless.app turns "use the agents we ship" into "any tool you own becomes composable AI
+infrastructure." Keep it concept-level here; the deep authoring lives in **floless-app-workflows**.
+
+---
+
+## B6 · The floless skills (how to drive it from the terminal)
+
+floless.app ships three skills into the AI terminal — they are how the terminal AI acts on the
+user's behalf. When the user wants to *do* something, invoke the matching one:
+
+- **floless-app-workflows** — build / modify / run `.flo` workflows: the install→validate→compile→run
+  loop, `exec` nodes (Roslyn C# against a live host), app inputs, the HTML Viewer. The doing-skill for
+  authoring.
+- **floless-app-routines** — set up automatic runs (schedule or trigger) through the Routines API.
+- **floless-app-bridge** — pick up what the user did in the UI (a queued **Tweak**, a "use this
+  Template" request), apply the change to the `.flo`, recompile, and clear the request.
+
+All three talk to the same local server (port 4317) and preserve the contract: the UI queues intent;
+the terminal AI does the real authoring. The user drives by **asking you in the terminal**, then
+watching and approving in the browser.
+
+---
+
+## B7 · How to run + best practices
+
+**The everyday loop:** pick a workflow (switcher) → set its inputs (on the input node) →
+**`⎙ Compile`/Approve** → **`▶ Run workflow`** → read the result (HTML Viewer, or the Execution tab).
+Edit → recompile → run.
+
+**Habits that keep it good:**
+- **Compile after every edit.** Run is gated on a fresh lock — determinism is AWARE's, not the UI's.
+- **Trust the real Run, not a clean compile.** `Simulate` checks shape; only a real `▶ Run` proves a
+  workflow works against the host.
+- **Tweak, don't rebuild.** To change one node, select it and **✎ Tweak** — the AI edits just that
+  node and recompiles.
+- **Automate the repeat.** Once a workflow is solid, make it a **Routine** (schedule or trigger).
+- **Reuse aggressively.** ★ star nodes/commands as **Templates**; **Bake** proven workflows into
+  agents; **Graft** your own tools in.
+- **Keep AWARE current (A2).** New releases bring new agents and features.
+- **Remember who's the brain.** Ask the terminal AI to build and change things; watch, approve, and
+  run in the browser. The UI is the window, not the engine.

package/dist/web/app.css

@@ -158,9 +158,12 @@
      quietest tier. Label kept — an unlabeled icon would be an unclear affordance. */
   #browse-btn { background: transparent; border-color: transparent; color: var(--text-dim); }
   #browse-btn:hover { background: var(--surface-2); border-color: var(--border-strong); color: var(--text); }
-  #sim-btn { background: var(--surface-2); color: var(--text-muted); }
-  #sim-btn:hover { color: var(--text); }
-  #sim-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+  /* Simulate mirrors Compile (outline-accent tier) — a consistent secondary
+     sibling; Run stays the only filled (primary) button, so the two outline
+     buttons reading alike is the correct hierarchy, not a lost signal. */
+  #sim-btn { color: var(--text); border-color: var(--accent-dim); }
+  #sim-btn:hover { color: var(--text); border-color: var(--accent); }
+  #sim-btn:disabled { color: var(--text-dim); border-color: var(--border-strong); cursor: default; opacity: 0.6; }
   #run-btn {
     background: var(--accent);
     color: #ffffff;
@@ -396,18 +399,27 @@
   .onb-num { font-family: var(--mono); font-size: 11px; font-weight: 600; color: var(--accent); min-width: 14px; }
   .onb-step-label { font-size: 12px; color: var(--text); }
   .onb-step-note { font-size: 11px; color: var(--text-dim); font-style: italic; }
-  .onb-cmd-label { font-size: 11px; color: var(--text-dim); margin: 18px 0 6px; }
-  .onb-cmd {
-    display: flex; justify-content: space-between; align-items: center; gap: 10px;
-    background: var(--bg); border: 1px solid var(--border-strong); border-radius: 4px;
-    padding: 9px 12px;
-  }
-  .onb-cmd code { font-family: var(--mono); font-size: 12px; color: var(--text-muted); }
-  .onb-copy {
-    background: transparent; border: none; color: var(--text-dim);
-    font-size: 14px; line-height: 1; cursor: pointer; padding: 2px 4px; border-radius: 4px;
-  }
-  .onb-copy:hover { color: var(--text); }
+  /* Secondary AI-native pointer (replaces the old raw `aware app install` chip — confusing for a
+     newcomer and off-message against "your terminal AI builds the workflows"). */
+  .onb-foot { font-size: 12px; color: var(--text-muted); margin-top: 16px; line-height: 1.5; }
+  /* "Start the guided tour" — the primary first-run action (copies the onboarding launch prompt).
+     Accent-soft region + filled-accent button mirror the .agent-card.selected / #run-btn primary
+     tier; all tokens existing (locked baseline — no new fonts/colors). */
+  .onb-tour {
+    display: flex; align-items: center; justify-content: space-between; gap: 12px;
+    margin-top: 14px; padding: 11px 14px;
+    background: var(--accent-soft); border: 1px solid var(--accent-dim); border-radius: 6px;
+  }
+  .onb-tour-hint { flex: 1; font-size: 11px; color: var(--text-dim); font-style: italic; line-height: 1.45; }
+  .onb-tour-btn {
+    flex: none; background: var(--accent); color: #ffffff; border: 1px solid var(--accent);
+    border-radius: 4px; font-family: var(--ui); font-size: 12px; font-weight: 600;
+    padding: 7px 14px; letter-spacing: 0.02em; cursor: pointer; white-space: nowrap;
+    transition: background 0.15s, border-color 0.15s, box-shadow 0.15s;
+  }
+  .onb-tour-btn:hover { background: var(--accent-bright); border-color: var(--accent-bright); box-shadow: 0 0 14px var(--accent-glow); }
+  .onb-tour-btn:disabled { cursor: default; opacity: 0.85; box-shadow: none; }
+  .onb-tour-ico { font-size: 11px; opacity: 0.7; margin-left: 6px; }
 
   .agent-card {
     background: var(--surface);
@@ -1198,7 +1210,11 @@
   .sep { color: var(--text-dim); opacity: 0.4; }
   .version-info { display: inline-flex; align-items: center; gap: 8px; }
   .aware-version, .app-version { font-family: var(--mono); font-size: 11px; color: var(--text-muted); letter-spacing: 0.02em; }
-  .aware-version:not(:empty) + .app-version::before { content: '·'; margin-right: 8px; opacity: 0.4; }
+  /* Separator between the AWARE runtime version and the app build version. An explicit
+     .ver-sep span (revealed once versions stamp) — robust to the upgrade pill sitting
+     between the two versions, which a `+`-adjacency ::before could not span. Flex `gap`
+     on .version-info spaces it on both sides. */
+  .ver-sep { font-size: 11px; }
 
   /* ========== TOOLTIPS (styled, app-themed; replaces native title="") ========== */
   #tooltip {
@@ -1589,15 +1605,27 @@
      header dirty-dot so the menu reinforces it without a new component. */
   .menu-item-dirty .menu-icon { color: var(--warn); }
   .menu-item-dirty .menu-label::after { content: " ●"; color: var(--warn); font-size: 9px; vertical-align: 1px; }
+  /* Icon column. Glyphs are inline Lucide stroke SVGs (shadcn's icon family),
+     not Unicode characters — ad-hoc symbols rendered at wildly different ink
+     sizes (7–19px tall at the same font-size); a uniform 15px SVG box fixes it.
+     stroke:currentColor keeps the dirty-state recolor (.menu-item-dirty) working. */
   .menu-icon {
     width: 18px;
-    font-size: 13px;
     color: var(--text-muted);
     display: inline-flex;
     align-items: center;
     justify-content: center;
     flex-shrink: 0;
   }
+  .menu-icon svg {
+    width: 15px;
+    height: 15px;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 1.5;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
   .menu-label { flex: 1; }
   .menu-kbd {
     font-family: var(--mono);
@@ -1871,7 +1899,7 @@ body {
 
 /* Compile / approve — the gated step before Run. Outline-accent tier: an
    accent-dim border pairs it visually with the filled Run button, so the eye
-   reads "Compile → Run" as the spine, above the muted Simulate. */
+   reads "Compile → Run" as the spine; Simulate is a matching outline sibling. */
 #compile-btn { color: var(--text); border-color: var(--accent-dim); }
 #compile-btn:hover { color: var(--text); border-color: var(--accent); }
 #compile-btn:disabled { color: var(--text-dim); border-color: var(--border-strong); cursor: default; opacity: 0.6; }
@@ -2066,12 +2094,45 @@ body {
 .agent-card .node-inputs .ni-val { color: var(--accent); font-weight: 600; }
 
 /* Per-node run status, painted from the live trace (running → done / error).
-   Uses a box-shadow ring (composes with the left mode-stripe ::after) plus a
-   text pip — colour is never the only signal. */
-.agent-card.node-running { box-shadow: 0 0 0 1px var(--accent), 0 0 12px var(--accent-glow); animation: nodePulse 1.3s ease-in-out infinite; }
-@keyframes nodePulse {
-  0%, 100% { box-shadow: 0 0 0 1px var(--accent), 0 0 5px var(--accent-glow); }
-  50%      { box-shadow: 0 0 0 1px var(--accent), 0 0 16px var(--accent-glow); }
+   Running = a STATIC accent ring + glow (set once, never animated — so the
+   compositor isn't recalculating box-shadow blur on every node every frame)
+   plus a bright accent band that travels left→right across the card face. Colour
+   is never the only signal — the spinner + "running" text pip and the filled
+   stat bar are static cues alongside the sweep. */
+.agent-card.node-running { box-shadow: 0 0 0 1px var(--accent), 0 0 14px var(--accent-glow); }
+/* Repurpose ::before (the hover/selected corner-wash) ONLY while running: it
+   becomes a traveling light band. The card is overflow:hidden + radius:8px, so
+   the band clips to the rounded rect for free. position/inset/pointer-events
+   come from the base ::before rule; we override background + animation and kill
+   the inherited opacity transition so the band shows instantly (no 0.25s fade). */
+.agent-card.node-running::before {
+  opacity: 1;
+  /* Wide soft band with a bright (but glow-cored, not hard-line) centre, so the
+     sweep reads clearly without washing out the text it passes over. */
+  background: linear-gradient(100deg,
+    transparent 0%, transparent 28%,
+    var(--accent-soft) 38%,
+    color-mix(in srgb, var(--accent) 78%, transparent) 47%,
+    color-mix(in srgb, var(--accent-bright) 85%, transparent) 50%,
+    color-mix(in srgb, var(--accent) 78%, transparent) 53%,
+    var(--accent-soft) 62%,
+    transparent 72%, transparent 100%);
+  background-size: 235% 100%;
+  background-repeat: no-repeat;
+  background-position: -30% 0;
+  animation: nodeSweep 1.7s linear infinite;
+  transition: none;
+}
+/* Off the left edge → off the right edge, no idle gap, constant speed. */
+@keyframes nodeSweep {
+  0%   { background-position: -30% 0; }
+  100% { background-position: 130% 0; }
+}
+/* Selected + running: keep BOTH rings (.node-running would otherwise clobber the
+   .selected ring). The sweep ::before overrides the static .selected::before wash. */
+.agent-card.selected.node-running {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 1px var(--accent), 0 0 14px var(--accent-glow), 0 8px 32px -8px var(--accent-glow);
 }
 .agent-card.node-done  { box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--ok)  50%, transparent); }
 .agent-card.node-error { box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--err) 60%, transparent); }
@@ -2082,8 +2143,46 @@ body {
   border-top: 1px solid var(--border);
 }
 .agent-card.node-running .node-stat { color: var(--accent); background: var(--accent-soft); }
+/* "running" gets a real working indicator — a small ring spinner before the
+   label, reusing the global `spin` keyframe + the .rtn-spinner recipe (so it
+   speaks the same "in-flight" language as the routines panel). No arbitrary
+   glyph. done/error keep their meaningful ✓/✗ text marks. */
+.agent-card.node-running .node-stat::before {
+  content: "";
+  display: inline-block;
+  width: 10px; height: 10px;
+  border: 1.5px solid var(--border-strong);
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+  vertical-align: middle;
+  margin-right: 5px;
+  position: relative; top: -1px; /* nudge the ring onto the 10px text midline */
+}
 .agent-card.node-done    .node-stat { color: var(--ok);  background: color-mix(in srgb, var(--ok)  12%, transparent); }
 .agent-card.node-error   .node-stat { color: var(--err); background: color-mix(in srgb, var(--err) 14%, transparent); }
+/* Reduced motion — no traveling band, no spin. The node still reads as running
+   via the static ring + glow, the filled accent-soft stat bar, and the "running"
+   label; the card ::before falls back to the native 135deg wash, and the stat
+   spinner becomes a static accent dot (active via colour, no implied motion).
+   Mirrors the .rtn-fired-flash / .so-spinner reduced-motion precedents. */
+@media (prefers-reduced-motion: reduce) {
+  .agent-card.node-running::before {
+    animation: none;
+    background: linear-gradient(135deg, var(--accent-soft), transparent 60%);
+    background-size: auto;
+    background-position: 0 0;
+    opacity: 1;
+    transition: none;
+  }
+  .agent-card.node-running .node-stat::before {
+    animation: none;
+    width: 5px; height: 5px;
+    border: none;
+    background: var(--accent);
+    top: 0;
+  }
+}
 /* Description-tab pointer to the Code tab (not the code itself). */
 .dim-note { color: var(--text-dim); font-size: 12px; margin-top: 8px; }
 

package/dist/web/app.js

@@ -97,10 +97,14 @@ function renderCanvasPlaceholder(kind) {
     `</div>`;
 }
 
-// First-run onboarding card (the 'empty' placeholder). Purely informational —
-// the only action is copying the install command (the steps' real controls live
-// in the header and are already disabled). No repeated brand mark (not a splash).
-const ONB_INSTALL_CMD = 'aware app install <folder>';
+// First-run onboarding card (the 'empty' placeholder). The primary action is "Start the guided tour"
+// — it copies a prompt the user pastes into their terminal AI to launch onboarding. No raw CLI command
+// is shown: the AI builds the workflows (per the headline), so the card stays AI-native, not "go run
+// this command yourself". No repeated brand mark (not a splash).
+// The natural-language launch prompt the "Start the guided tour" button copies. Phrased to match the
+// floless-app-onboarding skill's auto-trigger ("onboard me", "guided tour") so pasting it into Claude
+// Code / Codex starts the tour. Plain language (not a slash command) = portable across terminal hosts.
+const ONB_TOUR_PROMPT = 'Onboard me into floless.app and AWARE — give me the guided tour.';
 function onboardingHtml() {
   const step = (n, label, note) =>
     `<li><span class="onb-num">${n}</span><span class="onb-step"><span class="onb-step-label">${label}</span> <span class="onb-step-note">${note}</span></span></li>`;
@@ -108,6 +112,11 @@ function onboardingHtml() {
     `<div class="canvas-empty onboarding" data-kind="empty">` +
       `<div class="onb-headline">Your terminal AI builds the workflows.<br>You run and inspect them here.</div>` +
       `<div class="onb-sub">floless.app shows the canvas, triggers runs, and streams results. Compose in Claude Code or Codex; the browser is the window.</div>` +
+      `<div class="onb-tour">` +
+        `<span class="onb-tour-hint">New here? Copies a prompt — paste it into Claude Code or Codex.</span>` +
+        `<button class="onb-tour-btn" type="button" aria-label="Start the guided tour — copies the onboarding prompt to your clipboard"><span class="onb-tour-label">Start the guided tour</span><span class="onb-tour-ico" aria-hidden="true">⎘</span></button>` +
+        `<span class="sr-only onb-tour-live" aria-live="polite"></span>` +
+      `</div>` +
       `<div class="onb-divider"></div>` +
       `<ol class="onb-steps">` +
         step(1, 'Pick a workflow', '— the picker, top right') +
@@ -115,26 +124,37 @@ function onboardingHtml() {
         step(3, 'Compile', '— freeze the approved lock') +
         step(4, 'Run', '— against the live host; results render here') +
       `</ol>` +
-      `<div class="onb-cmd-label">Add a workflow from your terminal:</div>` +
-      `<div class="onb-cmd"><code>${ONB_INSTALL_CMD.replace('<', '&lt;').replace('>', '&gt;')}</code>` +
-        `<button class="onb-copy" type="button" data-tip="Copy command" aria-label="Copy command">⎘</button></div>` +
+      `<div class="onb-foot">No workflows yet? Just ask your terminal AI to build one.</div>` +
     `</div>`
   );
 }
 function wireOnboardingCopy() {
-  const btn = $topology.querySelector('.onb-copy');
-  if (!btn) return;
-  btn.onclick = async () => {
-    try {
-      await navigator.clipboard.writeText(ONB_INSTALL_CMD);
-      const prev = btn.textContent;
-      btn.textContent = '✓';
-      showToast('Copied: ' + ONB_INSTALL_CMD, 'ok');
-      setTimeout(() => { btn.textContent = prev; }, 1200);
-    } catch {
-      showToast('Could not copy — select the command and copy manually.', 'warn');
-    }
-  };
+  // The primary first-run action: copy the natural-language onboarding prompt so the user can paste it
+  // into their terminal AI to launch the guided tour (the floless-app-onboarding skill).
+  const tour = $topology.querySelector('.onb-tour-btn');
+  if (tour) {
+    const live = $topology.querySelector('.onb-tour-live');
+    const label = tour.querySelector('.onb-tour-label');
+    const ico = tour.querySelector('.onb-tour-ico');
+    tour.onclick = async () => {
+      try {
+        await navigator.clipboard.writeText(ONB_TOUR_PROMPT);
+        tour.disabled = true;
+        if (label) label.textContent = 'Copied';
+        if (ico) ico.textContent = '✓';
+        if (live) live.textContent = 'Copied to clipboard';
+        showToast('Copied — paste it into your terminal AI', 'ok');
+        setTimeout(() => {
+          if (label) label.textContent = 'Start the guided tour';
+          if (ico) ico.textContent = '⎘';
+          tour.disabled = false;
+          if (live) live.textContent = '';
+        }, 1600);
+      } catch {
+        showToast('Could not copy — select and paste the prompt manually.', 'warn');
+      }
+    };
+  }
 }
 
 function nodeIds(p) {

package/dist/web/aware.js

@@ -1521,6 +1521,61 @@
     setInterval(refreshUpdate, 6 * 60 * 60 * 1000); // re-check every 6h so a long-running window notices
   }
 
+  // ── AWARE runtime upgrade tag ─────────────────────────────────────────────────
+  // Surface aware-update.ts: poll GET /api/aware/update (on load + every 6h); when a
+  // newer @aware-aeco/cli exists, show a footer pill → confirm → POST apply, which
+  // reinstalls AWARE in place (no relaunch — the app stays open) and re-stamps the
+  // version live. Mirrors the app self-update pill; differs in that success is silent
+  // (the live version re-stamp IS the confirmation) and there is no relaunch.
+  const $awareUpdate = document.getElementById('aware-update');
+  // After a successful upgrade, briefly trust the upgraded version: a /api/health request that
+  // was in flight before the reinstall finished could resolve with the OLD version and momentarily
+  // revert the footer. The live re-stamp (health poll) honors this short settle window.
+  let awareUpgradeFloor = null, awareUpgradeFloorUntil = 0;
+  async function refreshAwareUpdate() {
+    if (!$awareUpdate) return;
+    try {
+      const r = await fetch('/api/aware/update');
+      const d = await r.json();
+      if (r.ok && d.updateAvailable && d.targetVersion) {
+        $awareUpdate.textContent = '↑ Upgrade AWARE to v' + d.targetVersion;
+        $awareUpdate.dataset.target = d.targetVersion;
+        $awareUpdate.dataset.tip = 'A newer AWARE runtime (v' + d.targetVersion + ') is available — click to install it in place (no relaunch)';
+        $awareUpdate.hidden = false;
+      } else {
+        $awareUpdate.hidden = true; // up-to-date / absent / registry error → no pill
+      }
+    } catch { $awareUpdate.hidden = true; }
+  }
+  if ($awareUpdate) {
+    $awareUpdate.onclick = async () => {
+      const v = $awareUpdate.dataset.target || '';
+      if (!window.confirm('Upgrade AWARE runtime to v' + v + '? This reinstalls the npm package in place — the app stays open and the version restamps automatically.')) return;
+      $awareUpdate.disabled = true;
+      $awareUpdate.textContent = '↑ Upgrading…';
+      try {
+        // Cap the wait so the pill never sticks disabled if the global npm install wedges.
+        const r = await fetch('/api/aware/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' }, signal: AbortSignal.timeout(120000) });
+        const d = await r.json().catch(() => ({}));
+        if (!r.ok || !d.ok) throw new Error(d.error || 'aware upgrade failed');
+        // Success is silent: the pill disappears and the AWARE version re-stamps live.
+        $awareUpdate.hidden = true;
+        $awareUpdate.disabled = false;
+        const wv = document.getElementById('aware-version');
+        if (wv && d.version) { wv.textContent = 'AWARE ' + d.version; awareUpgradeFloor = d.version; awareUpgradeFloorUntil = Date.now() + 10000; }
+      } catch (e) {
+        $awareUpdate.disabled = false;
+        const msg = (e && e.name === 'TimeoutError')
+          ? 'AWARE upgrade is taking a while — it may still be installing; the version updates when it finishes'
+          : 'AWARE upgrade failed — ' + String((e && e.message) || e).slice(0, 80);
+        showToast(msg, 'warn');
+        refreshAwareUpdate(); // restore the pill text for retry
+      }
+    };
+    refreshAwareUpdate();
+    setInterval(refreshAwareUpdate, 6 * 60 * 60 * 1000); // re-check every 6h
+  }
+
   // ONE Run (the approved single-Run model). "▶ Run workflow" does a REAL run against
   // the live host, using the app inputs. If the app has a report node, it drives
   // the in-app HTML Viewer (renders + caches the returned HTML); otherwise it
@@ -1603,7 +1658,7 @@
   // — that's the during-run feedback; pushTrace then refines each node to
   // done/error as the (batched) trace arrives. Covers UI runs, report runs (the
   // canvas paints behind the modal), and terminal-driven runs (trace-file).
-  const NODE_STAT_LABEL = { running: '◆ running', done: '✓ done', error: '✗ failed' };
+  const NODE_STAT_LABEL = { running: 'running', done: '✓ done', error: '✗ failed' };
   function setNodeStatus(nodeId, status) {
     if (!nodeId) return;
     const card = document.querySelector(`.agent-card[data-agent-id="${(window.CSS && CSS.escape) ? CSS.escape(nodeId) : nodeId}"]`);
@@ -2059,13 +2114,22 @@
           // stale install or AWARE mismatch is self-diagnosable). appVersion is
           // the real sq.version on an install (package.json only from source);
           // awareVersion is the aware npm package this app drives.
-          if (!shownVersion) {
-            const av = document.getElementById('app-version');
-            if (av && h && h.appVersion) av.textContent = 'v' + h.appVersion;
-            const wv = document.getElementById('aware-version');
-            if (wv && h && h.awareVersion) wv.textContent = 'AWARE ' + h.awareVersion;
-            if (h && (h.appVersion || h.awareVersion)) shownVersion = true;
+          // The app BUILD version is immutable at runtime → stamp once. The AWARE RUNTIME
+          // version CAN change (an out-of-band `npm i -g`, or the in-app upgrade), so
+          // re-stamp it whenever /api/health reports a different value — never show a
+          // stale runtime version in the footer.
+          const av = document.getElementById('app-version');
+          if (av && h && h.appVersion && !shownVersion) { av.textContent = 'v' + h.appVersion; shownVersion = true; }
+          const wv = document.getElementById('aware-version');
+          if (wv && h && h.awareVersion) {
+            const next = 'AWARE ' + h.awareVersion;
+            // During the post-upgrade settle window, ignore a stale health value that disagrees
+            // with the version we just upgraded to (a poll in flight during the reinstall).
+            const settling = awareUpgradeFloor && Date.now() < awareUpgradeFloorUntil && h.awareVersion !== awareUpgradeFloor;
+            if (!settling && wv.textContent !== next) wv.textContent = next;
           }
+          const sep = document.getElementById('ver-sep');
+          if (sep && h && (h.appVersion || h.awareVersion)) sep.hidden = false;
           // Bootstrap BACKSTOP: reconcile the setup overlay from cached health
           // state in case an SSE event was missed. ready → finish the beat &
           // dismiss; failed/installing/probing → (re)render that state.

package/dist/web/index.html

@@ -147,6 +147,8 @@
       </div>
       <span class="version-info">
         <span class="aware-version" id="aware-version" data-tip="AWARE runtime version — the aware CLI/npm package this app drives"></span>
+        <button id="aware-update" class="app-update" hidden data-tip="An AWARE runtime upgrade is available — reinstalls in place, no relaunch"></button>
+        <span class="sep ver-sep" id="ver-sep" hidden>·</span>
         <span class="app-version" id="app-version" data-tip="floless.app build serving this window (installed build, or the dev build when run from source)"></span>
         <button id="app-update" class="app-update" hidden></button>
       </span>
@@ -155,38 +157,38 @@
 
   <div class="menu" id="menu" role="menu">
     <button class="menu-item" data-action="open" role="menuitem">
-      <span class="menu-icon">⌸</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="m6 14 1.5-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.54 6a2 2 0 0 1-1.95 1.5H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H18a2 2 0 0 1 2 2v2"/></svg></span>
       <span class="menu-label">Open</span>
       <span class="menu-kbd">Ctrl+O</span>
     </button>
     <button class="menu-item" data-action="save" role="menuitem">
-      <span class="menu-icon">⤓</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M15.2 3a2 2 0 0 1 1.4.6l3.8 3.8a2 2 0 0 1 .6 1.4V19a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z"/><path d="M17 21v-7a1 1 0 0 0-1-1H8a1 1 0 0 0-1 1v7"/><path d="M7 3v4a1 1 0 0 0 1 1h7"/></svg></span>
       <span class="menu-label">Save inputs</span>
       <span class="menu-kbd">Ctrl+S</span>
     </button>
     <div class="menu-divider"></div>
     <button class="menu-item" data-action="find" role="menuitem">
-      <span class="menu-icon">⌕</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/></svg></span>
       <span class="menu-label">Find on canvas</span>
       <span class="menu-kbd">Ctrl+F</span>
     </button>
     <div class="menu-divider"></div>
     <button class="menu-item" data-action="graft" role="menuitem">
-      <span class="menu-icon">⊕</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M12 22v-5"/><path d="M15 8V2"/><path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z"/><path d="M9 8V2"/></svg></span>
       <span class="menu-label">Graft into agent</span>
     </button>
     <button class="menu-item" data-action="bake" id="menu-bake-item" role="menuitem">
-      <span class="menu-icon">⊙</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z"/><path d="M12 22V12"/><polyline points="3.29 7 12 12 20.71 7"/><path d="m7.5 4.27 9 5.15"/></svg></span>
       <span class="menu-label" id="menu-bake-label">Bake into agent</span>
     </button>
     <div class="menu-divider"></div>
     <button class="menu-item" data-action="integrations" role="menuitem">
-      <span class="menu-icon">⊟</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg></span>
       <span class="menu-label">Integrations</span>
       <span class="menu-kbd">Ctrl+I</span>
     </button>
     <button class="menu-item" data-action="routines" role="menuitem">
-      <span class="menu-icon">⏱</span>
+      <span class="menu-icon" aria-hidden="true"><svg viewBox="0 0 24 24"><line x1="10" x2="14" y1="2" y2="2"/><line x1="12" x2="15" y1="14" y2="11"/><circle cx="12" cy="14" r="8"/></svg></span>
       <span class="menu-label">Routines</span>
     </button>
     <!-- Start-on-login + Theme are sibling machine preferences (no divider between

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "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 @@
     "app:restart": "node launch.mjs restart",
     "build": "node build/bundle.mjs",
     "build:exe": "node build/bundle.mjs && node build/make-sea.mjs",
+    "verify:skills": "node build/verify-shipped-skills.mjs",
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build"
   },