@floless/app 0.54.0 → 0.55.0

package/dist/floless-server.cjs

@@ -52856,7 +52856,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.54.0" : void 0,
+    define: true ? "0.55.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52866,7 +52866,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.54.0" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.55.0" : void 0 });
 }
 
 // workflow-update.ts
@@ -60685,8 +60685,10 @@ var PRODUCT_SKILLS = [
   //            compose Custom Panels (~/.floless/ui/extensions.json) for the Dashboard
   "floless-app-workflows",
   //     author/run .flo workflows
-  "reading-structural-drawings"
+  "reading-structural-drawings",
   // the drawing-set reading discipline (non-namespace) the steel guide + reader lean on; shipped so users get it too
+  "steel-drawing-abbreviations"
+  // default US/AISC abbreviations+shapes legend (non-namespace) the steel reader falls back to when a set omits its own legend sheet
 ];
 function selectShippedSkillNames(names) {
   const present = new Set(names);
@@ -63874,6 +63876,13 @@ async function startServer() {
     broadcast({ type: "request-added", request });
     return { ok: true, request };
   });
+  app.post("/api/guide", async (req, reply) => {
+    const { appId } = req.body ?? {};
+    if (!appId) return reply.status(400).send({ ok: false, error: "appId required" });
+    const request = addRequest({ type: "guide", appId });
+    broadcast({ type: "request-added", request });
+    return { ok: true, request };
+  });
   app.delete("/api/requests/:id", async (req, reply) => {
     if (!deleteRequest(req.params.id)) return reply.status(404).send({ ok: false, error: "request not found" });
     broadcast({ type: "requests-changed" });

package/dist/skills/floless-app-steel-model/SKILL.md

@@ -26,13 +26,16 @@ the run path and no API key.
 what was found and get an OK before spending effort on the next stage. Resume at any stage on
 re-invoke ("we already set up the folder, provision the agents").
 
-> Companion skills (both ship with floless.app — invoke them, don't duplicate them):
+> Companion skills (all ship with floless.app — invoke them, don't duplicate them):
 > - **`reading-structural-drawings`** — the reading *discipline* (massing + coordinate frame FIRST,
 >   members LAST, cross-validate every view). Follow it whenever skimming or classifying the set
 >   (stages 2 and 5) — it stops the classic failures (two buildings read as one, a sloped roof read
 >   as flat, grids conflated across sheets).
 > - **`floless-app-steel-takeoff`** — reads one framing plan into the contract (the heavy vision
 >   pipeline, the filter pre-stage, the AISC/EN/BS lookup, the contract write + editor hand-off).
+> - **`steel-drawing-abbreviations`** — the default US/AISC abbreviations + shape-designation legend.
+>   The fallback for note/profile codes (TYP, TOS, UON, `(E)`/`(N)`, HSS, WT) when the set omits its
+>   own abbreviations sheet (stage 2).
 
 ---
 
@@ -66,7 +69,9 @@ the project folder (a few files, **not** a framework):
 
 Read the set with the terminal AI's own vision, following the **`reading-structural-drawings`**
 discipline while skimming (massing + coordinate frame first — it's what makes the sheet
-classification reliable).
+classification reliable). If the set has **no abbreviations/legend sheet** (a partial set is common),
+fall back to **`steel-drawing-abbreviations`** — the standard US/AISC abbreviations + shape legend —
+for note/profile codes (TYP, TOS, UON, `(E)`/`(N)`, HSS, WT). The project's own legend always overrides.
 
 **Gate:** show `set-index.md` (the sheet map) and confirm the classification looks right — the user
 knows their set better than any read.

package/dist/skills/floless-app-steel-takeoff/SKILL.md

@@ -366,3 +366,8 @@ never committed). Clip title blocks from any embedded preview.
   sizes or grid positions the drawing does not show.
 - **Resolve the port** from the running floless.app the same way other floless-app skills do
   (check `~/.floless/port` or the active server port).
+- **Decode unfamiliar note/profile codes** with **`steel-drawing-abbreviations`** (the default
+  US/AISC abbreviations + shape legend) when the set lacks its own abbreviations sheet — for TYP
+  profiles, TOS/UON defaults, `(E)`/`(N)` scope, and shape designations. The project's own legend
+  always overrides; never expand a member *mark* (`MF`/`BF`/`D1`) from it — resolve those from the
+  schedules/elevations.

package/dist/skills/reading-structural-drawings/SKILL.md

@@ -46,7 +46,9 @@ one with a curved roof — both obvious in the elevations, invisible in the plan
 Read the **cover / drawing index** and **general notes** first. Build a sheet list classified by
 type (index, notes, foundation plan, framing plans per level, frame elevations, sections, details,
 **schedules**). Confirm the set is complete + current revision. Grab the legend, datum, material
-defaults, and the **abbreviations** (FC/MF/BF/(E)/(N)/matchline symbols). Trust PyMuPDF page_count over
+defaults, and the **abbreviations** (FC/MF/BF/(E)/(N)/matchline symbols). If the set ships **no
+abbreviations/legend sheet** (or only partial sheets), fall back to the **`steel-drawing-abbreviations`**
+default US/AISC legend for the standard codes. Trust PyMuPDF page_count over
 any external count.
 
 ### Pass 1 — MASSING (how many buildings, what shape) — from elevations/sections, not plans
@@ -114,6 +116,9 @@ Only then build the scene / overlay / IFC. If unsure, present the **massing + gr
   skill is the *reading discipline*; that one is the *reader*. The **`floless-app-steel-model`** guide
   (the front-door orchestrator) wraps the whole flow and references this discipline at the
   classify-and-verify gates rather than re-deriving it.
+- **`steel-drawing-abbreviations`** — the default US/AISC abbreviations + shape-designation legend.
+  Consult it in Pass 0 when the set omits its own legend sheet, and whenever a note code (TYP, TOS,
+  UON, `(E)`/`(N)`) or profile designation needs decoding.
 - There is no off-the-shelf OSS tool that does the whole drawing→model job — floorplan vectorisers
   (e.g. CubiCasa5k) are residential-trained and won't read steel framing — which is why the order +
   validation discipline above, not a single tool, is the method.

package/dist/skills/steel-drawing-abbreviations/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: steel-drawing-abbreviations
+description: Default legend of standard US (AISC, imperial) structural-steel drawing abbreviations, note conventions, and shape designations — the fallback meaning when a drawing set omits or only partially supplies its own abbreviations/legend sheet. This skill should be used while reading a structural steel drawing whenever an abbreviation, note code, or profile designation needs expanding (TYP, TOS, UON, EQ, (E)/(N), SIM, HSS, WT, and so on), or when the steel reader (floless-app-steel-takeoff / floless-app-steel-model) meets a note or label whose meaning is not defined on the supplied sheets. The project's own legend always overrides these defaults.
+metadata:
+  version: "0.1.0"
+---
+
+# Steel drawing abbreviations — default legend
+
+## What this is
+
+A reusable **fallback legend** of the standard abbreviations, note conventions, and steel-shape
+designations that appear on the General Notes / legend sheet (usually `S-001` / `S-100`) of most
+**US (AISC, imperial)** structural sets. These are an industry convention — largely identical from
+project to project — so they fill the gap when a set does not ship its own abbreviations sheet, or
+when only some sheets are provided.
+
+The full glossary lives in **`references/standard-us-abbreviations.md`** (abbreviations A–Z, the
+structural-steel shape table, the high-value note conventions for takeoff, and a marks-vs-abbreviations
+warning). Keep this SKILL.md lean; load the reference when an actual lookup is needed.
+
+## When to consult it
+
+- A structural plan, section, or **General Note** uses an abbreviation or code that is not spelled
+  out on the supplied sheets, and its meaning is needed to read geometry or metadata correctly
+  (e.g. a "T.O.S. = 16'-6" UON" note, a "TYP" profile, an `(E)` member).
+- The **steel reader** (`floless-app-steel-takeoff`) or the **guide** (`floless-app-steel-model`) is
+  learning a set and the user did **not** provide the abbreviations/legend sheet — use this as the
+  default while still reading the rest of the set.
+- A profile designation needs decoding (what `HSS6X6X3/8`, `WT`, `C`, `MC`, `PIPE-XX` mean and which
+  ones carry their weight in the name vs. need an AISC table).
+
+## How to use it
+
+1. **Read the project legend first.** If the set HAS an abbreviations sheet or a note that defines the
+   code, use *that* — this file is only the fallback. The project's own definition always wins.
+2. **Look up the code** in `references/standard-us-abbreviations.md` (grep the abbreviation, e.g.
+   `grep -i 'TOS' references/standard-us-abbreviations.md`).
+3. **Respect context over the table.** Several codes are context-dependent (`WT` = WEIGHT or a tee
+   shape; `PT` = POST-TENSIONED / PRESSURE-TREATED / POINT). Choose the structurally sensible meaning;
+   if it is genuinely ambiguous, flag it as an RFI rather than guess.
+4. **Do not expand marks.** `MF` / `BF` / `D1` / `C1` / `B12` are project member/frame marks resolved
+   from the frame elevations and schedules — never from this glossary (see the reference's
+   "Marks vs abbreviations" section).
+5. **Mind the region.** This is the US/AISC legend. For EU (EN) or UK (BS) sets, defer to the project
+   legend and the region-specific detailer agent (`steel-detailer-eu` / `steel-detailer-uk`); the
+   shape designations especially differ.
+
+## Companion skills
+
+- **`reading-structural-drawings`** — the reading discipline; its Pass 0 (inventory & legend) consults
+  this default legend when the set's own abbreviations sheet is missing.
+- **`floless-app-steel-takeoff`** — the reader; uses this while reading notes/labels into the
+  `steel.takeoff/v1` contract (TYP profiles, TOS defaults, connection-type words, `(E)`/`(N)` scope).
+- **`floless-app-steel-model`** — the front-door guide; references this at the "learn the set" stage so
+  a partial set without a legend sheet still reads correctly.
+- **`steel-detailer-us` / `-eu` / `-uk`** (AWARE agents) — own the section *tables and weights*; this
+  skill only decodes the *labels and notes*.

package/dist/skills/steel-drawing-abbreviations/references/standard-us-abbreviations.md

@@ -0,0 +1,296 @@
+# Standard US structural-steel drawing abbreviations & symbols (default legend)
+
+These are the **de-facto standard abbreviations** that appear on the General Notes / legend sheet
+(usually `S-001` / `S-100`) of most **US (AISC, imperial)** structural sets. They are an industry
+convention, not any one firm's property, so they serve as a **fallback default** when a drawing set
+does not include its own abbreviations/legend sheet (or only ships partial sheets).
+
+**Rules of use (read before applying any expansion):**
+- **The project's own legend ALWAYS wins.** If the set has an abbreviations sheet or a plan/general
+  note that defines a code, use *that* meaning — never override it with this list.
+- **Context can override.** The same code means different things by context (e.g. `WT` = WEIGHT or a
+  structural-tee shape; `PT` = POST-TENSIONED or PRESSURE-TREATED or POINT). Pick the meaning that
+  fits the structural context; if genuinely ambiguous, flag it (RFI) rather than guess.
+- **Region differs.** This is the US/AISC set. EU (EN) and UK (BS) sets use different shape
+  designations and some different abbreviations — defer those to the project legend and the
+  region-specific detailer agent (`steel-detailer-eu` / `steel-detailer-uk`).
+- **Marks are NOT abbreviations.** Member/frame *marks* like `MF`, `BF`, `D1`, `C1`, `B12` are
+  project-specific labels resolved from the frame elevations / schedules — not from this glossary.
+  See "Marks vs abbreviations" below.
+
+---
+
+## Abbreviations (A–Z)
+
+| Abbr | Meaning |
+|------|---------|
+| `AB` | ANCHOR BOLT |
+| `ACI` | AMERICAN CONCRETE INSTITUTE |
+| `ADD'L` | ADDITIONAL |
+| `ADJ` | ADJACENT / ADJUSTABLE |
+| `AESS` | ARCHITECTURALLY EXPOSED STRUCTURAL STEEL |
+| `AGGR` | AGGREGATE |
+| `AISC` | AMERICAN INSTITUTE OF STEEL CONSTRUCTION |
+| `AITC` | AMERICAN INSTITUTE OF TIMBER CONSTRUCTION |
+| `ALT` | ALTERNATE |
+| `ALUM` | ALUMINUM |
+| `ANCH` | ANCHOR |
+| `ANSI` | AMERICAN NATIONAL STANDARDS INSTITUTE |
+| `APA` | AMERICAN PLYWOOD ASSOCIATION |
+| `APPROX` | APPROXIMATE |
+| `ARCH` | ARCHITECTURAL / ARCHITECT |
+| `ASD` | ALLOWABLE STRENGTH DESIGN |
+| `ASTM` | AMERICAN SOCIETY FOR TESTING AND MATERIALS |
+| `AWPA` | AMERICAN WOOD PRESERVERS ASSOCIATION |
+| `AWS` | AMERICAN WELDING SOCIETY |
+| `AVG` | AVERAGE |
+| `@` | AT |
+| `&` | AND |
+| `BLDG` | BUILDING |
+| `BLK` | BLOCK |
+| `BLKG` | BLOCKING |
+| `BM` | BEAM |
+| `BN` | BOUNDARY NAIL |
+| `BNDRY` | BOUNDARY |
+| `BOT` (or `B`) | BOTTOM |
+| `BRC` | BRACE |
+| `BRG` | BEARING |
+| `BT` | BENT |
+| `BTWN` | BETWEEN |
+| `CANT` | CANTILEVER |
+| `CAM` (or `C`) | CAMBER |
+| `CG` | CENTER OF GRAVITY |
+| `CIP` | CAST-IN-PLACE |
+| `CJ` | CONSTRUCTION JOINT; CONTROL JOINT |
+| `CJP` | COMPLETE JOINT PENETRATION (WELD) |
+| `CL` (or `℄`) | CENTER LINE |
+| `CLR` | CLEAR |
+| `CMU` | CONCRETE MASONRY UNIT |
+| `COL` | COLUMN |
+| `COMP` | COMPRESSION / COMPOSITE |
+| `CONC` | CONCRETE |
+| `CONN` | CONNECTION |
+| `CONST` / `CONSTR` | CONSTRUCTION |
+| `CONT` | CONTINUOUS / CONTINUE |
+| `CTR` | CENTER |
+| `CTSK` | COUNTERSUNK |
+| `CU FT` | CUBIC FOOT |
+| `d` | PENNY (nail size, e.g. `16d`) |
+| `DBL` | DOUBLE |
+| `DEPT` | DEPARTMENT |
+| `DET` | DETAIL |
+| `DIA` (or `Ø`) | DIAMETER |
+| `DIAG` | DIAGONAL |
+| `DIAPH` | DIAPHRAGM |
+| `DIM` | DIMENSION |
+| `DN` | DOWN |
+| `DO` | DITTO |
+| `DWG` | DRAWING |
+| `DWL` | DOWEL |
+| `EA` | EACH |
+| `EF` | EACH FACE |
+| `EJ` | EXPANSION JOINT |
+| `EL` / `ELEV` | ELEVATION |
+| `ELEC` | ELECTRICAL |
+| `EMBED` | EMBEDMENT |
+| `EN` | EDGE NAIL |
+| `EQ` | EQUAL / EQUALLY (SPACED) |
+| `EQUIP` | EQUIPMENT |
+| `ES` | EACH SIDE |
+| `EW` | EACH WAY |
+| `EXP` | EXPANSION |
+| `EXT` | EXTERIOR |
+| `(E)` | EXISTING (often out of new-work scope) |
+| `FDN` | FOUNDATION |
+| `FF` | FAR FACE |
+| `FIN` | FINISH(ED) |
+| `FLR` | FLOOR |
+| `FN` | FIELD NAIL |
+| `FOC` | FACE OF CONCRETE |
+| `FOS` | FACE OF STUD / FACE OF SLAB |
+| `FOW` | FACE OF WALL |
+| `FP` | FIRE PROOFING |
+| `FRMG` | FRAMING |
+| `FS` | FAR SIDE / FULL SIZE |
+| `FT` | FOOT / FEET |
+| `FTG` | FOOTING |
+| `GA` | GAUGE |
+| `GALV` | GALVANIZED |
+| `GB` | GRADE BEAM |
+| `GLB` | GLUE-LAMINATED BEAM |
+| `GR` | GRADE |
+| `GRTG` | GRATING |
+| `HDR` | HEADER |
+| `HGR` | HANGER |
+| `HGT` / `HT` | HEIGHT |
+| `HK` | HOOK |
+| `HORIZ` (or `H`) | HORIZONTAL |
+| `HP` | HIGH POINT |
+| `HS` | HIGH STRENGTH |
+| `HSS` | HOLLOW STRUCTURAL SECTION |
+| `ID` | INSIDE DIAMETER |
+| `IF` | INSIDE FACE |
+| `IN` | INCH |
+| `INCL` | INCLUDE / INCLUDED |
+| `INFO` | INFORMATION |
+| `INSP` | INSPECTION |
+| `INT` | INTERIOR |
+| `JST` | JOIST |
+| `JT` | JOINT |
+| `K` | KIPS (1000 lb) |
+| `KSI` | KIPS PER SQUARE INCH |
+| `LAB` | LABORATORY |
+| `LB(S)` (or `#`) | POUNDS |
+| `LH` | LEFT HAND |
+| `LLH` | LONG LEG HORIZONTAL |
+| `LLV` | LONG LEG VERTICAL |
+| `LP` | LOW POINT |
+| `LT WT` | LIGHTWEIGHT |
+| `MAS` | MASONRY |
+| `MATL` | MATERIAL |
+| `MAX` | MAXIMUM |
+| `MB` | MACHINE BOLT |
+| `MECH` | MECHANICAL |
+| `MFR` | MANUFACTURER |
+| `MIN` | MINIMUM |
+| `MISC` | MISCELLANEOUS |
+| `N` | NORTH |
+| `(N)` | NEW |
+| `NF` | NEAR FACE |
+| `NIC` | NOT IN CONTRACT |
+| `NOM` | NOMINAL |
+| `NO` (or `#`) | NUMBER |
+| `NS` | NEAR SIDE |
+| `NTS` | NOT TO SCALE |
+| `OC` | ON CENTER |
+| `OD` | OUTSIDE DIAMETER |
+| `OF` | OUTSIDE FACE |
+| `OH` | OPPOSITE HAND |
+| `OPNG` | OPENING |
+| `OPP` | OPPOSITE |
+| `OSB` | ORIENTED STRAND BOARD |
+| `PARA` (or `∥`) | PARALLEL |
+| `PERP` (or `⊥`) | PERPENDICULAR |
+| `PJP` | PARTIAL JOINT PENETRATION (WELD) |
+| `PL` | PLATE |
+| `PLF` | POUNDS PER LINEAR FOOT |
+| `PLYWD` | PLYWOOD |
+| `PNL` | PANEL |
+| `PSF` | POUNDS PER SQUARE FOOT |
+| `PSI` | POUNDS PER SQUARE INCH |
+| `PT` | POST-TENSIONED / PRESSURE-TREATED / POINT |
+| `R` / `RAD` | RADIUS |
+| `RD` | ROOF DRAIN |
+| `REF` | REFERENCE |
+| `REINF` | REINFORCING / REINFORCEMENT |
+| `REQ'D` | REQUIRED |
+| `RET` | RETAINING |
+| `RM` | ROOM |
+| `RO` | ROUGH OPENING |
+| `SCHED` | SCHEDULE |
+| `SECT` | SECTION |
+| `SF` | SQUARE FEET |
+| `SHT` | SHEET |
+| `SHTHG` | SHEATHING |
+| `SIM` | SIMILAR |
+| `SLBB` | SHORT LEGS BACK-TO-BACK |
+| `SOG` | SLAB ON GRADE |
+| `SPCG` | SPACING |
+| `SPECS` | SPECIFICATIONS |
+| `SQ` | SQUARE |
+| `SS` | SELECT STRUCTURAL / STAINLESS STEEL |
+| `SSL` | SHORT SLOTTED HOLES |
+| `STAGG` | STAGGERED |
+| `STD` | STANDARD |
+| `STIFF` | STIFFENER |
+| `STIRR` | STIRRUP |
+| `STL` | STEEL |
+| `STRUCT` | STRUCTURAL |
+| `SYM` | SYMMETRICAL |
+| `T&B` | TOP AND BOTTOM |
+| `T&G` | TONGUE AND GROOVE |
+| `TB` | TIE BEAM |
+| `TEMP` | TEMPORARY / TEMPERATURE |
+| `THK` | THICK / THICKNESS |
+| `THR` | THREADED |
+| `THRU` | THROUGH |
+| `TN` | TOE NAIL |
+| `TOC` | TOP OF CONCRETE / TOP OF CURB |
+| `TOF` | TOP OF FOOTING |
+| `TOS` | TOP OF STEEL / TOP OF SLAB |
+| `TOW` | TOP OF WALL |
+| `TYP` | TYPICAL |
+| `UON` / `UNO` | UNLESS OTHERWISE NOTED |
+| `VERT` (or `V`) | VERTICAL |
+| `VIF` | VERIFY IN FIELD |
+| `W` | WEST |
+| `W/` | WITH |
+| `WD` | WOOD |
+| `WP` | WORK POINT (also WATERPROOF) |
+| `WT` | WEIGHT (also a structural-tee shape — see below) |
+| `WWF` | WELDED WIRE FABRIC |
+
+---
+
+## Structural steel shape designations
+
+How a profile label decodes (the label sits on/near the member centerline, usually mid-span):
+
+| Designation | Shape |
+|-------------|-------|
+| `W` | Wide-flange (W-shape) — e.g. `W16X26` |
+| `M` | Miscellaneous I-shape |
+| `S` | American Standard (S-shape / "I-beam") |
+| `HP` | Bearing pile (HP-shape) |
+| `C` | American Standard Channel |
+| `MC` | Miscellaneous Channel |
+| `L` | Angle (equal/unequal leg) — e.g. `L4X4X1/4` |
+| `WT` / `MT` / `ST` | Structural Tee (cut from W / M / S) |
+| `HSS` | Hollow Structural Section (rectangular/square/round) — e.g. `HSS6X6X3/8` |
+| `PIPE` | Standard pipe; `PIPE-X` extra-strong; `PIPE-XX` double-extra-strong |
+| `TS` | Tube Steel (older designation for HSS) |
+| `PL` | Plate — e.g. `PL1/2X8` |
+
+**Reading the size numbers:**
+- **W/M/S/HP/C/MC and WT/MT/ST:** the trailing number after the `X` IS the weight in **lb/ft (plf)** —
+  no table needed. `W16X26` = nominal depth **16"** × **26 lb/ft**; `WT6X25` (a tee cut from a W) =
+  **25 lb/ft**; `C12X20.7` = **20.7 lb/ft**. (Tees inherit weight-based naming from their parent
+  W/M/S shape.)
+- **HSS / PIPE / L / PL:** the numbers are **dimensions**, not the weight (e.g. `HSS6X6X3/8` =
+  6"×6"×3/8" wall, `L4X4X1/4` = 4"×4"×1/4" leg) — look the weight up in an AISC shapes table
+  (or via the `steel-detailer-us` agent).
+
+---
+
+## Note conventions most useful to a takeoff
+
+When reading the General Notes and plan notes, these drive member geometry/metadata directly:
+
+- **`TYP`** — a value/detail shown once applies to all like conditions. A "TYP" profile or spacing in
+  the notes is the **default** for unlabeled members of that kind.
+- **`TOS` / `TOC` / `TOF` / `BOS`** — top/bottom-of-steel/concrete/footing elevations. A plan default
+  TOS ("ALL STEEL T.O.S. = 16'-6" UON") sets every member's elevation unless a local callout overrides.
+- **`UON` / `UNO`** — the stated value holds everywhere *unless* a local note says otherwise. Treat a
+  "TYP … UON" note as the fallback and watch for the exceptions.
+- **`EQ`** — equally-spaced members between two references (no explicit dimension).
+- **`SIM`** — a detail is repeated similarly elsewhere (mirror/rotate as needed).
+- **`(N)` / `(E)`** — new vs existing. `(E)` members are frequently **out of the new-steel takeoff**;
+  confirm against line weight/scope before counting them.
+- **Connection-type words in notes** — `MOMENT`, `DRAG`, `SHEAR`, `BRACED`, `PINNED`, `FIXED` name the
+  connection type at member ends; feed them into the member-end connection note + the connection
+  library (type → design detail# → platform component).
+
+---
+
+## Marks vs abbreviations (do not confuse)
+
+A *mark* identifies a specific member or frame and is defined **by the project's schedules/elevations**,
+not by this glossary:
+
+- `MF` / `BF` — Moment Frame / Braced Frame member marks (resolved from the Frame Elevation sheets;
+  the AISC size comes from the moment-frame schedule, not from "MF").
+- `D1`, `D2`, `BR1` — brace/diagonal marks.
+- `C1`, `B12`, `G3` — column/beam/girder marks keyed to a schedule.
+
+Never expand a mark using this abbreviation list. Resolve it from the frame elevations / column &
+beam schedules, and if unresolved, leave it as an RFI.

package/dist/web/app.css

@@ -479,6 +479,152 @@
   .onb-tour-btn:disabled { cursor: default; opacity: 0.85; box-shadow: none; }
   .onb-tour-ico { font-size: 11px; opacity: 0.7; margin-left: 6px; }
 
+  /* ===== Per-workflow onboarding beacon ("Start here") ===== */
+  /* A header pill in the run cluster. Calm by default (accent-soft, like the
+     wf-update pill); pulses while the open workflow is new to the user. Accent —
+     NOT warn — because it's positive/new, and warn is already the drift colour. */
+  .guide-beacon {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    border: 1px solid var(--accent-dim);
+    background: var(--accent-soft);
+    color: var(--accent-bright);
+    font-family: var(--ui);
+    font-size: 11px;
+    letter-spacing: 0.02em;
+    padding: 3px 11px;
+    border-radius: 999px;
+    cursor: pointer;
+    white-space: nowrap;
+    flex-shrink: 0; /* the workflow picker shrinks first; the beacon never squashes */
+    transition: border-color 0.15s, color 0.15s, background 0.15s;
+  }
+  .guide-beacon[hidden] { display: none; }
+  .guide-beacon:hover { border-color: var(--accent); color: var(--accent); }
+  .guide-beacon:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .guide-beacon-ico { font-size: 11px; line-height: 1; }
+  /* "New to you": a slow box-shadow bloom (GPU-composited, no layout repaint) reading
+     as a calm invitation, not an alarm. Same motion dialect as the rest of the app. */
+  .guide-beacon.is-new {
+    border-color: var(--accent);
+    color: var(--accent-bright);
+    animation: guide-pulse 2.8s ease-in-out infinite;
+  }
+  @keyframes guide-pulse {
+    0%, 100% { box-shadow: 0 0 0 0 var(--accent-glow); }
+    50%      { box-shadow: 0 0 0 6px rgba(74, 158, 255, 0); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    /* No pulse — a steady ring (shape + contrast, not colour alone) marks "new". */
+    .guide-beacon.is-new { animation: none; box-shadow: 0 0 0 1px var(--accent-dim); }
+  }
+  /* Spotlit (first-open): raised above the dim, opaque, ringed. The header creates no
+     stacking context, so z-index here lifts it above the fixed spotlight overlay. */
+  .guide-beacon.spotlit {
+    position: relative;
+    z-index: 95;
+    animation: none;
+    background: var(--surface-3);
+    border-color: var(--accent);
+    color: var(--accent-bright);
+    box-shadow: 0 0 0 3px var(--accent-glow), 0 0 20px 4px var(--accent-glow);
+  }
+
+  /* ===== First-open spotlight ===== */
+  .guide-spotlight {
+    position: fixed;
+    inset: 0;
+    z-index: 90; /* below modals (100), above the page; the beacon (.spotlit, 95) sits over it */
+    background: rgba(7, 10, 15, 0.72);
+    backdrop-filter: blur(2px);
+    -webkit-backdrop-filter: blur(2px);
+    display: none;
+  }
+  .guide-spotlight:not([hidden]) { display: block; animation: fade-in 0.18s ease-out; }
+  .guide-spotlight-bubble {
+    position: fixed;
+    z-index: 91;
+    max-width: 280px;
+    background: var(--surface);
+    border: 1px solid var(--accent-dim);
+    border-radius: 8px;
+    padding: 12px 14px;
+    box-shadow: 0 16px 48px rgba(0, 0, 0, 0.5);
+  }
+  .guide-spotlight-text { font-size: 12.5px; line-height: 1.5; color: var(--text); }
+  .guide-spotlight-text strong { color: var(--accent-bright); }
+  .guide-spotlight-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 11px; }
+  .guide-spotlight-actions button { padding: 5px 13px; font-size: 12px; }
+  .guide-spotlight-actions .ghost { background: var(--surface-2); color: var(--text-muted); }
+  .guide-spotlight-actions .ghost:hover { color: var(--text); border-color: var(--accent-dim); }
+  .guide-spotlight-actions .primary { background: var(--accent); color: #fff; border-color: var(--accent); font-weight: 600; }
+  .guide-spotlight-actions .primary:hover { background: var(--accent-bright); box-shadow: 0 0 14px var(--accent-glow); }
+
+  /* ===== Guide panel (modal) ===== */
+  .modal.guide {
+    width: 520px;
+    max-width: 92vw;
+    max-height: 82vh;
+    display: flex;
+    flex-direction: column;
+  }
+  .guide-eyebrow {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.16em;
+    color: var(--accent-bright);
+    margin-bottom: 6px;
+  }
+  /* The body scrolls between the pinned title and the pinned actions; theme its
+     scrollbar so no native white bar leaks against the dark surface. */
+  #guide-body {
+    overflow-y: auto;
+    flex: 1 1 auto;
+    min-height: 0;
+    margin-top: 2px;
+    scrollbar-width: thin;
+    scrollbar-color: var(--border-strong) transparent;
+  }
+  #guide-body::-webkit-scrollbar { width: 7px; }
+  #guide-body::-webkit-scrollbar-thumb { background: var(--border-strong); border-radius: 7px; }
+  #guide-body::-webkit-scrollbar-track { background: transparent; }
+  .guide-section-label {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.14em;
+    color: var(--text-muted);
+    margin: 14px 0 7px;
+  }
+  .guide-section-label:first-child { margin-top: 2px; }
+  .guide-desc { font-size: 12.5px; line-height: 1.55; color: var(--text); }
+  .guide-desc p { margin: 0 0 8px; }
+  .guide-desc p:last-child { margin-bottom: 0; }
+  .guide-desc code { font-family: var(--mono); background: var(--surface-2); padding: 1px 5px; border-radius: 3px; color: var(--text-muted); font-size: 11px; }
+  .guide-desc-empty { color: var(--text-muted); font-style: italic; }
+  .guide-steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 9px; }
+  .guide-step { display: flex; gap: 10px; align-items: baseline; }
+  .guide-box { font-family: var(--mono); font-size: 13px; min-width: 16px; color: var(--text-dim); line-height: 1.3; }
+  .guide-step-label { font-size: 12.5px; color: var(--text); }
+  .guide-step-note { font-size: 11px; color: var(--text-dim); font-style: italic; }
+  /* Done: ✓ in ok-green + struck/dimmed label, so the current step stands out on
+     shape + contrast, not colour alone. Current: → in accent + bold label. */
+  .guide-step.done .guide-box { color: var(--ok); }
+  .guide-step.done .guide-step-label { color: var(--text-dim); text-decoration: line-through; text-decoration-color: var(--text-dim); }
+  .guide-step.current .guide-box { color: var(--accent); }
+  .guide-step.current .guide-step-label { color: var(--text); font-weight: 600; }
+  .guide-walk-hint {
+    font-size: 11px;
+    line-height: 1.5;
+    color: var(--text-muted);
+    margin-top: 14px;
+    padding-top: 12px;
+    border-top: 1px solid var(--border);
+  }
+  .guide-walk-hint strong { color: var(--text); font-weight: 600; }
+  .modal.guide .modal-actions { margin-top: 16px; }
+  .modal.guide .modal-actions #guide-got-it { margin-right: auto; }
+
   .agent-card {
     background: var(--surface);
     border: 1px solid var(--border-strong);

package/dist/web/aware.js

@@ -531,11 +531,193 @@
     });
   }
 
+  // ── Per-workflow onboarding beacon ──────────────────────────────────────────
+  // "New to you" = the user hasn't completed a first real Run of this workflow and
+  // hasn't dismissed its guide. Three bits per app id, persisted per origin; all
+  // default false, so every workflow starts new. Never touches the .flo or lock.
+  const LS_GUIDE = 'floless:guide';
+  function guideStateAll() {
+    try { const v = JSON.parse(localStorage.getItem(LS_GUIDE) || '{}'); return (v && typeof v === 'object') ? v : {}; }
+    catch { return {}; }
+  }
+  function guideFor(id) { return guideStateAll()[id] || {}; }
+  function setGuide(id, patch) {
+    if (!id) return;
+    try {
+      const all = guideStateAll();
+      all[id] = { ...(all[id] || {}), ...patch };
+      localStorage.setItem(LS_GUIDE, JSON.stringify(all));
+    } catch { /* private mode / quota */ }
+  }
+  // The beacon pulses while a workflow is new to the user.
+  function beaconIsNew(id) { const g = guideFor(id); return !g.firstRunDone && !g.dismissed; }
+
+  function paintBeacon(app) {
+    const $b = document.getElementById('guide-beacon');
+    if (!$b) return;
+    if (!app) { $b.hidden = true; $b.classList.remove('is-new', 'spotlit'); return; }
+    const isNew = beaconIsNew(app.id);
+    $b.hidden = false;
+    $b.classList.toggle('is-new', isNew);
+    const ico = $b.querySelector('.guide-beacon-ico');
+    const label = $b.querySelector('.guide-beacon-label');
+    // Monochrome dingbats (✦ / ?), not colour emoji — the locked baseline uses text
+    // glyphs (★, ▸); the pulse, not an emoji, is the "new" signal.
+    if (ico) ico.textContent = isNew ? '✦' : '?';
+    if (label) label.textContent = isNew ? 'Start here' : 'Guide';
+    $b.dataset.tip = isNew
+      ? 'New here? See what this workflow does and how to run it.'
+      : 'Open the guide for this workflow.';
+    $b.setAttribute('aria-label', (isNew ? 'Start here — guide for ' : 'Guide for ') + (app.displayName || app.id));
+  }
+
+  // Record a completed real run → the workflow is no longer new; calm the beacon (and
+  // refresh an open guide so the Run step ticks). Idempotent.
+  function markFirstRunDone(id) {
+    if (!id || guideFor(id).firstRunDone) return;
+    setGuide(id, { firstRunDone: true });
+    if (id === currentId) {
+      const app = apps.get(id);
+      if (app) paintBeacon(app);
+      const $m = document.getElementById('guide-modal');
+      if ($m && $m.classList.contains('show')) renderGuide();
+    }
+  }
+
+  // The guide panel's live checklist — each step ticks from real app state. The
+  // "Set inputs" row is omitted for a workflow with no declared inputs.
+  function guideSteps(app) {
+    const steps = [];
+    if (Array.isArray(app.inputs) && app.inputs.length) {
+      const vals = currentInputs();
+      const allSet = app.inputs.every((i) => {
+        const v = vals[i.name];
+        return v !== undefined && v !== null && String(v).trim() !== '';
+      });
+      steps.push({ label: 'Set inputs', note: 'the values this workflow runs with', done: allSet });
+    }
+    steps.push({ label: 'Compile', note: 'freeze the approved lock', done: app.runState === 'ready' });
+    steps.push({ label: 'Run', note: 'against the live host — results render here', done: !!guideFor(app.id).firstRunDone });
+    return steps;
+  }
+
+  function renderGuide() {
+    const app = currentId && apps.get(currentId);
+    const $body = document.getElementById('guide-body');
+    const $title = document.getElementById('guide-title');
+    const $eyebrow = document.getElementById('guide-eyebrow');
+    if (!app || !$body) return;
+    if ($title) $title.textContent = app.displayName || app.id;
+    if ($eyebrow) $eyebrow.textContent = beaconIsNew(app.id) ? '✦ Start here' : '✦ Workflow guide';
+    const desc = (app.description || '').trim();
+    const descHtml = desc
+      ? `<div class="guide-desc">${desc.split(/\n{2,}/).map((p) => `<p>${mdInline(escapeHtml(p.trim()))}</p>`).join('')}</div>`
+      : `<div class="guide-desc guide-desc-empty"><p>A ${app.nodes.length}-step workflow. Set its inputs, Compile to freeze the approved lock, then Run it against your live host.</p></div>`;
+    const steps = guideSteps(app);
+    const curIdx = steps.findIndex((s) => !s.done);
+    const stepsHtml = `<ol class="guide-steps" role="list">${steps.map((s, i) => {
+      const state = s.done ? 'done' : i === curIdx ? 'current' : 'todo';
+      // Shape carries state, not colour alone: ✓ done · → current · ☐ to-do.
+      const box = s.done ? '✓' : i === curIdx ? '→' : '☐';
+      const cur = i === curIdx ? ' aria-current="step"' : '';
+      return `<li class="guide-step ${state}"${cur}><span class="guide-box" aria-hidden="true">${box}</span>` +
+        `<span class="guide-step-text"><span class="guide-step-label">${escapeHtml(s.label)}</span> ` +
+        `<span class="guide-step-note">— ${escapeHtml(s.note)}</span></span>` +
+        `<span class="sr-only">${s.done ? '(done)' : i === curIdx ? '(next step)' : '(to do)'}</span></li>`;
+    }).join('')}</ol>`;
+    const walkHint = `<div class="guide-walk-hint">A bigger workflow? <strong>Walk me through it</strong> hands off to your terminal AI for a step-by-step tour using this workflow's own skill.</div>`;
+    $body.innerHTML =
+      `<div class="guide-section-label">What this does</div>` + descHtml +
+      `<div class="guide-section-label">How to go through it</div>` + stepsHtml + walkHint;
+  }
+
+  function openGuide() {
+    if (!currentId) { showToast('open a workflow first', 'warn'); return; }
+    renderGuide();
+    const $m = document.getElementById('guide-modal');
+    showModal($m);
+    // Focus the dialog shell (not a button) so the checklist is read first; Tab then
+    // moves to Got it → Walk me through it. Focus returns to the beacon on close.
+    const shell = $m && $m.querySelector('.modal.guide');
+    if (shell) { try { shell.focus(); } catch { /* not focusable */ } }
+  }
+  // Closing the guide (Got it / backdrop / Esc) marks it seen → the beacon stops
+  // pulsing even before a first run (the user has looked; don't nag).
+  function closeGuide() {
+    if (currentId) {
+      setGuide(currentId, { dismissed: true });
+      const app = apps.get(currentId);
+      if (app) paintBeacon(app);
+    }
+    hideModal(document.getElementById('guide-modal'));
+    const $b = document.getElementById('guide-beacon');
+    if ($b && !$b.hidden) { try { $b.focus(); } catch { /* */ } }
+  }
+
+  // "Walk me through it" → relay the ask to the terminal AI, the house way: queue a
+  // request AND copy the prompt, toast, light the footer requests pill, list it in the
+  // Requests window. The UI never guides itself; it hands intent to the assistant.
+  async function requestGuide() {
+    if (!currentId) { showToast('open a workflow first', 'warn'); return; }
+    try {
+      const { request } = await api('/api/guide', { method: 'POST', body: JSON.stringify({ appId: currentId }) });
+      const copied = await copyToClipboard(markedInstruction(request));
+      showToast(copied ? 'Sent to your assistant · copied to clipboard' : 'Sent to your assistant', 'ok');
+      appendNarration(`Asked your terminal AI to walk you through <code>${escapeHtml(currentId)}</code> — watch the glowing <strong>requests</strong> pill (bottom-right), or switch to your terminal.${copied ? ' The prompt is also on your clipboard.' : ''}`);
+      loadRequests();
+      closeGuide(); // engaging with the guidance also calms the beacon
+    } catch (e) { reportErr(e); }
+  }
+
+  // ── First-open spotlight (one-time per workflow) ────────────────────────────
+  // Dims the canvas, raises the beacon, and points a small caption at it; Esc /
+  // click-away / either button dismiss it for good. Slice 2 of the onboarding beacon.
+  let _spotlightKey = null;
+  function maybeSpotlight(app) {
+    if (!app) return;
+    const g = guideFor(app.id);
+    if (g.spotlightShown || g.dismissed || g.firstRunDone) return;
+    if (document.querySelector('.modal-backdrop.show')) return; // don't pile on a dialog
+    if ($contractEditor && !$contractEditor.hidden) return;
+    setTimeout(() => {
+      if (currentId !== app.id) return; // switched away during the delay
+      if (guideFor(app.id).spotlightShown) return;
+      if (document.querySelector('.modal-backdrop.show')) return;
+      showSpotlight(app);
+    }, 700);
+  }
+  function showSpotlight(app) {
+    const $sp = document.getElementById('guide-spotlight');
+    const $b = document.getElementById('guide-beacon');
+    if (!$sp || !$b || $b.hidden) return;
+    setGuide(app.id, { spotlightShown: true });
+    $b.classList.add('spotlit');
+    $sp.hidden = false;
+    // Anchor the caption bubble just under the beacon, right-aligned to it.
+    const bubble = $sp.querySelector('.guide-spotlight-bubble');
+    if (bubble) {
+      const r = $b.getBoundingClientRect();
+      bubble.style.top = (r.bottom + 10) + 'px';
+      bubble.style.right = Math.max(8, window.innerWidth - r.right) + 'px';
+    }
+    _spotlightKey = (e) => { if (e.key === 'Escape') { e.preventDefault(); hideSpotlight(); } };
+    document.addEventListener('keydown', _spotlightKey);
+    if (bubble) { try { bubble.focus(); } catch { /* */ } }
+  }
+  function hideSpotlight() {
+    const $sp = document.getElementById('guide-spotlight');
+    const $b = document.getElementById('guide-beacon');
+    if ($sp) $sp.hidden = true;
+    if ($b) $b.classList.remove('spotlit');
+    if (_spotlightKey) { document.removeEventListener('keydown', _spotlightKey); _spotlightKey = null; }
+  }
+
   // ── load / select / compile / run ───────────────────────────────────────────
 
   let _wfUpdates = []; // workflow updates available, keyed by app id — polled by refreshWorkflowUpdates() below
 
   async function loadApp(id) {
+    hideSpotlight(); // a spotlight pointing at the previous app's beacon must clear on switch
     const { app } = await api(`/api/app/${encodeURIComponent(id)}`);
     apps.set(id, app);
     currentId = id;
@@ -555,8 +737,10 @@
     seedAppInputs(app);
     markSpecialNodes();
     paintGate(app);
+    paintBeacon(app); // pulse "Start here" while this workflow is new to the user
     refreshDirtyIndicator(); // clean app → dot off; switched back to a dirty one → dot on
     renderWfUpdatePill(); // show the "↑ Update to vX" pill when THIS app has a newer published version
+    maybeSpotlight(app); // one-time first-open spotlight pointing at the beacon (slice 2)
   }
 
   async function loadApps() {
@@ -574,6 +758,8 @@
       if ($menuBakeItem) $menuBakeItem.disabled = true;
       if ($wfTrigger) $wfTrigger.disabled = true;
       setComboTriggerLabel('no workflows installed');
+      paintBeacon(null); // no workflow open → hide the per-workflow beacon
+      hideSpotlight();
       renderCanvasPlaceholder('empty');
       return;
     }
@@ -814,8 +1000,18 @@
       if (v != null) localStorage.setItem(lsInputsKey(toId), v);
     } catch { /* private mode / quota */ }
   }
+  // A rename is the SAME workflow under a new id → carry its onboarding-seen state so it
+  // doesn't re-pulse "Start here" / re-show the spotlight. (Not done on duplicate: a copy
+  // is a genuinely new workflow that the user hasn't run, so it should start new.)
+  function migrateGuideLS(fromId, toId) {
+    try {
+      const all = guideStateAll();
+      if (all[fromId]) { all[toId] = all[fromId]; localStorage.setItem(LS_GUIDE, JSON.stringify(all)); }
+    } catch { /* private mode / quota */ }
+  }
   function dropClientAppState(id) {
     try { localStorage.removeItem(lsInputsKey(id)); } catch { /* ignore */ }
+    try { const all = guideStateAll(); if (all[id]) { delete all[id]; localStorage.setItem(LS_GUIDE, JSON.stringify(all)); } } catch { /* ignore */ }
     appInputValues.delete(id); dirtyBaseline.delete(id); apps.delete(id);
   }
 
@@ -843,6 +1039,7 @@
       // so a rename never silently drops the user's inputs (#85 review). loadApp() only seeds
       // inputs when the id is absent, so pre-setting them here preserves unsaved edits.
       migrateInputsLS(oldId, r.id);
+      migrateGuideLS(oldId, r.id); // carry onboarding-seen state so the renamed workflow doesn't re-pulse
       if (appInputValues.has(oldId)) appInputValues.set(r.id, appInputValues.get(oldId));
       if (dirtyBaseline.has(oldId)) dirtyBaseline.set(r.id, dirtyBaseline.get(oldId));
       const wasOpen = currentId === oldId;
@@ -1767,6 +1964,7 @@
         $reportSub.innerHTML = `Live 3D view from <code>${escapeHtml(nodeId)}</code>${inputBadge ? ' · ' + escapeHtml(inputBadge) : ''} — drag to orbit, scroll to zoom, click an element to inspect.`;
       }
       paintReport(html, interactive);
+      markFirstRunDone(app.id); // a real run rendered → this workflow is no longer "new" (app captured pre-await; a mid-run switch must not mark the wrong workflow)
       lastReportByApp.set(currentId, { nodeId, label: inputBadge, html, interactive });
       $reportModal.dataset.html = '1';
       appendNarration(`Rendered the ${interactive ? '3D view' : 'report'} from <strong>${escapeHtml(nodeId)}</strong>${inputBadge ? ' (' + escapeHtml(inputBadge) + ')' : ''} — live run against the model.`);
@@ -3215,6 +3413,7 @@
       appendNarration(simulate
         ? `Simulated run complete · ${steps} node${steps === 1 ? '' : 's'} stubbed (no host needed) · see the <strong>Execution</strong> tab.`
         : `Run complete · ${steps} node${steps === 1 ? '' : 's'} against the live model · see the <strong>Execution</strong> tab.`);
+      if (!simulate) markFirstRunDone(app.id); // a real run completed → calm the beacon (app captured pre-await)
     } catch (e) {
       const msg = (e && e.message) ? e.message : String(e);
       if (cancelRequested) {
@@ -4116,6 +4315,9 @@
         : '';
       return `In floless app "${req.appId}", re-read & re-bake${where} per the floless-app-rebake skill: ${req.instruction}${snaps}`;
     }
+    if (req.type === 'guide') {
+      return `Walk me through the floless workflow "${req.appId}" — explain in plain English what it does and how to run it (set its inputs → Compile → ▶ Run). Use your floless-app-${req.appId} skill if one exists; otherwise read the workflow's own description and node notes from GET /api/app/${req.appId} and explain from those. This is a guided explanation — don't change anything.`;
+    }
     return '';
   }
 
@@ -4126,6 +4328,9 @@
     tweak: 'floless-app-workflows',
     'ui-customize': 'floless-app-ui',
     rebake: 'floless-app-rebake',
+    // The guided-tour ask is picked up by onboarding; the instruction body names the
+    // per-app floless-app-<appId> skill for depth when one exists.
+    guide: 'floless-app-onboarding',
   };
 
   // The COPIED form of a request: instructionFor() prefixed with a self-identifying
@@ -4220,7 +4425,7 @@
       return;
     }
     $list.innerHTML = pendingRequests.map((r) => {
-      const label = r.type === 'use-template' ? 'template' : r.type === 'ui-customize' ? 'dashboard' : r.type === 'rebake' ? 're-bake' : 'tweak';
+      const label = r.type === 'use-template' ? 'template' : r.type === 'ui-customize' ? 'dashboard' : r.type === 'rebake' ? 're-bake' : r.type === 'guide' ? 'guide' : 'tweak';
       const badgeCls = r.type === 'tweak' || r.type === 'ui-customize' || r.type === 'rebake' ? 'req-type req-type-tweak' : 'req-type';
       const target = r.type === 'tweak' && r.nodeId
         ? ` · node <code>${escapeHtml(r.nodeId)}</code>`
@@ -5034,6 +5239,7 @@
     try {
       const res = await api('/api/trigger-run', { method: 'POST', body: JSON.stringify({ id, inputs: currentInputs() }) });
       foregroundTrigger = { appId: id, sessionId: res.sessionId, firedCount: 0 };
+      markFirstRunDone(id); // a real live session started → a streaming workflow's "first run" is no longer new
       syncRunControls(); // header ■ Stop run becomes reachable; Run disabled while live
       paintForegroundListening();
       appendNarration(`Live session started for <strong>${escapeHtml(id)}</strong> — the report updates on every event. Click <strong>■ Stop run</strong> (top right) to end it.`);
@@ -5718,6 +5924,25 @@
     if (e.key === 'Escape' && $reqModal && $reqModal.classList.contains('show')) $reqModal.classList.remove('show');
   });
 
+  // Per-workflow onboarding beacon + guide panel + first-open spotlight.
+  const $guideBeaconBtn = document.getElementById('guide-beacon');
+  if ($guideBeaconBtn) $guideBeaconBtn.onclick = () => { hideSpotlight(); openGuide(); };
+  const $guideModal = document.getElementById('guide-modal');
+  const $guideGot = document.getElementById('guide-got-it');
+  if ($guideGot) $guideGot.onclick = () => closeGuide();
+  const $guideWalk = document.getElementById('guide-walk');
+  if ($guideWalk) $guideWalk.onclick = () => requestGuide();
+  if ($guideModal) onBackdropDismiss($guideModal, () => closeGuide());
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && $guideModal && $guideModal.classList.contains('show')) closeGuide();
+  });
+  const $spotGot = document.getElementById('guide-spotlight-got');
+  if ($spotGot) $spotGot.onclick = () => hideSpotlight();
+  const $spotShow = document.getElementById('guide-spotlight-show');
+  if ($spotShow) $spotShow.onclick = () => { hideSpotlight(); openGuide(); };
+  const $spotlightEl = document.getElementById('guide-spotlight');
+  if ($spotlightEl) $spotlightEl.onclick = (e) => { if (e.target === $spotlightEl) hideSpotlight(); };
+
   // Pull all workspace data (agents/templates/requests + the apps list). Factored
   // out of bootWorkspace so the health poll can re-pull it after the server comes
   // back from a boot-time outage (setServerStatus → recovery).

package/dist/web/index.html

@@ -58,6 +58,13 @@
         <!-- Agents (⊞) and Routines (⏱) buttons moved into the ≡ menu in #149
              (Ctrl+G / Ctrl+R); the toolbar keeps only the run-critical controls. -->
         <span class="ctl-sep" aria-hidden="true"></span>
+        <!-- Per-workflow onboarding beacon. Pulses "✨ Start here" while this workflow is
+             new to the user (no first Run completed, not dismissed); calms to a quiet
+             "❔ Guide" after — always clickable for re-reference. Hidden until an app loads. -->
+        <button id="guide-beacon" class="guide-beacon" type="button" hidden aria-haspopup="dialog" data-tip="New here? See what this workflow does and how to run it.">
+          <span class="guide-beacon-ico" aria-hidden="true">✦</span>
+          <span class="guide-beacon-label">Start here</span>
+        </button>
         <span class="run-state" id="run-state" role="status" aria-live="polite"></span>
         <button id="compile-btn" data-tip="Compile + approve → freeze the .lock">⎙ Compile</button>
         <button id="sim-btn" data-tip="Simulate: stub every node from its output schema — no live host is contacted. Validates the workflow's composition end-to-end, even when the real agents aren't connected yet.">Simulate</button>
@@ -511,6 +518,37 @@
     </div>
   </div>
 
+  <!-- Per-workflow onboarding "Start here" guide. Surfaces the workflow's plain-English
+       description + a live "Set inputs → Compile → Run" checklist (ticks from real state),
+       and relays a "walk me through it" ask to the terminal AI. A styled modal — never a
+       native dialog; body (#guide-body) is rendered per-open in aware.js. -->
+  <div class="modal-backdrop" id="guide-modal">
+    <div class="modal guide" role="dialog" aria-modal="true" aria-labelledby="guide-title" tabindex="-1">
+      <div class="guide-eyebrow" id="guide-eyebrow">✦ Start here</div>
+      <div class="modal-title" id="guide-title">Workflow</div>
+      <div class="modal-sub">What this workflow does, and how to go through it.</div>
+      <div id="guide-body"></div>
+      <div class="modal-actions">
+        <button id="guide-got-it">Got it</button>
+        <button id="guide-walk" class="primary">Walk me through it →</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- One-time first-open spotlight: dims the canvas and points at the "Start here"
+       beacon, then collapses into it. Shown once per workflow; Esc / click-away / either
+       button dismiss it. The beacon gets .spotlit so it sits above the dim. The bubble is
+       positioned next to the beacon at open time (aware.js). -->
+  <div id="guide-spotlight" class="guide-spotlight" hidden>
+    <div class="guide-spotlight-bubble" role="dialog" aria-modal="false" aria-label="New workflow tip" tabindex="-1">
+      <div class="guide-spotlight-text">New to this workflow? <strong>Start here</strong> — see what it does and how to run it.</div>
+      <div class="guide-spotlight-actions">
+        <button type="button" id="guide-spotlight-got" class="ghost">Got it</button>
+        <button type="button" id="guide-spotlight-show" class="primary">Show me</button>
+      </div>
+    </div>
+  </div>
+
   <!-- Routines — scheduled .flo runs. The list; the add/edit form is its own modal. -->
   <div class="modal-backdrop" id="routines-modal">
     <div class="modal routines">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "type": "module",
   "description": "Thin localhost host for floless.app — serves web/ and shells the aware CLI. No engine, no LLM.",
   "bin": {