@floless/app 0.54.1 → 0.56.0

package/dist/schemas/steel.takeoff.v1.schema.json

@@ -39,6 +39,7 @@
     "plans": { "type": "array", "items": { "$ref": "#/$defs/plan" } },
     "filter": { "$ref": "#/$defs/filter", "description": "Layer/thickness/colour filter pre-stage. `sheets[]` holds per-framing-plan geometry; the facets + `mode` + on-flag selection are GLOBAL across sheets. The saved selection scopes which lines the reader binds profile labels to per sheet; replaces the length heuristic, fallback when absent. CONFIDENTIAL: each sheet's `page.bg_b64` is machine-local, never committed." },
     "connections": { "type": "array", "items": { "$ref": "#/$defs/connection" }, "description": "Vendor-neutral connection library: each row maps a connection type → the firm's design detail# → per-platform component ids. Member ends/columns reference a row by id via `ends[].conn` / `col.conn` (legacy `note`/`detail` = fallback when `conn` is empty)." },
+    "joints": { "type": "array", "items": { "$ref": "#/$defs/joint" }, "description": "Placed connections (base plates, …) the connection engine expands into real 3D parts (plate/bolt/weld/cut) bound to their members. A joint may cite a `connections[]` row via `conn` for its type/detail identity; `params` carries the geometry settings (engine defaults when absent)." },
     "dims3d": { "type": "array", "items": { "$ref": "#/$defs/dim3" }, "description": "Draft-only 3D dimensions (editor annotations, model-global). World-scene mm. NOT baked into the lock / 3D scene / IFC / BOM." }
   },
   "$defs": {
@@ -178,6 +179,23 @@
         "source": { "enum": ["company-rules", "user", "drawing"], "description": "Where the row came from (drives the connection confidence band)." }
       }
     },
+    "joint": {
+      "type": "object",
+      "required": ["id", "kind", "main"],
+      "additionalProperties": true,
+      "description": "A placed connection — the geometry-bearing recipe the connection engine expands into real 3D parts bound to its member(s). Distinct from the `connections[]` library (vendor-neutral type/detail/targets identities a joint can cite). The engine derives all geometry from this recipe + the live member positions, so a joint moves/re-solves with its members. v1 kinds: base-plate, shear-plate.",
+      "properties": {
+        "id": { "type": "string", "description": "Stable joint id, e.g. j-bp-1 / sp-b3-e0." },
+        "kind": { "type": "string", "description": "Connection kind the engine knows how to expand: base-plate, shear-plate (v1). end-plate / cap-plate / … follow." },
+        "main": { "type": "string", "description": "Id of the host member this joint hangs off. For a base-plate this is the column; for a shear-plate this is the SUPPORTED BEAM (the joint sits at one of the beam's ends — see `at`)." },
+        "secondaries": { "type": "array", "items": { "type": "string" }, "description": "Ids of the other members this joint binds — e.g. the SUPPORT a shear-plate frames into. Optional and inferred by geometry; the shear-plate engine does not require it (the fin plate is placed off the beam end + beam axis). Empty for a base-plate." },
+        "at": { "type": "string", "description": "Where on the main member the joint sits (kind-dependent): base-plate = base; shear-plate = end0 | end1 — the beam end framing into the support (end0 ↔ ends[0]/start, end1 ↔ ends[1]/end)." },
+        "conn": { "type": "string", "description": "Optional `connections[]` row id this joint cites for its type/detail identity (keeps the connection library + confidence scoring in play)." },
+        "params": { "type": "object", "additionalProperties": true, "description": "Geometry settings (mm) with engine defaults; absent = all defaults. base-plate: plateWidth/plateDepth/thickness, boltCols/boltRows/boltDia/edgeDist, weldLeg, anchor kit, levelingNut. shear-plate: plateThickness, plateWidth (along the beam), plateHeight (vertical), boltCols/boltRows/boltDia/boltPitch/edgeDist, weldLeg, clearance (the erection gap so the beam clears the support, ~½–¾\"; pulls the beam box back), webSide (+1/-1 — which face of the beam web the plate laps), boltGrade (A325 | A490 — the AISC bolt length auto-sizes from the grip), stiffener (bool — a full-height stiffener on the far side of a girder web)." },
+        "source": { "enum": ["auto", "user"], "description": "auto = proposed by auto-detail from the takeoff; user = placed/edited by hand." },
+        "verified": { "type": "boolean", "description": "True = a human confirmed this joint." }
+      }
+    },
     "point2": {
       "type": "array",
       "items": { "type": "number" },

package/dist/skills/floless-app-new-workflow/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: floless-app-new-workflow
+description: This skill should be used to build a brand-new FloLess .flo workflow from scratch, step by step, as the host terminal AI — interviewing the user about what they want, checking that the AWARE agents the workflow needs are installed (installing an available one on consent, or reporting a not-yet-existing agent as an idea), then authoring the .flo node by node and verifying each step with the real toolchain (plain-English descriptions, aware app validate, aware app compile, a real run) before installing it so it appears in the floless.app picker for Compile and Run. Use it on triggers like "build a new workflow", "create a workflow from scratch", "build me a workflow", "new workflow", the floless.app "New workflow…" menu item, a queued new-workflow request, or "/floless-app-new-workflow". It leans on floless-app-workflows for the exec contract and hands back a runnable, approved app.
+metadata:
+  version: 0.1.0
+---
+
+# Build a new floless.app workflow from scratch
+
+Guide the user from a blank slate to a **runnable, approved** `.flo` app, 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 builder — interview the user, confirm the agents the
+workflow needs exist, then author the `.flo` **one node at a time, verifying each step with the real
+toolchain before moving on**, and hand back an installed app the user can Compile and Run in the UI.
+
+This is the doing-skill the onboarding tour points to ("want to build your first workflow?"). It is
+the **create-from-scratch sibling** of the per-workflow guide (which explains an *existing* app).
+
+The contract details (exec globals, return shape, templating, layout, gotchas) live in
+**floless-app-workflows** — lean on it, do not re-derive it here. This skill owns the *interview →
+preflight → author-and-verify → hand-back* flow; the verification mechanics live in
+`references/build-and-verify.md` (read it when entering Step 3).
+
+## Operating principles (apply throughout)
+
+- **One step at a time, verified.** Author a node, then **run the real check that proves it** before
+  the next (description prose, `aware app validate`, `aware app compile`, a real `aware app run`).
+  Never stack three unverified nodes and hope. A failing check is the signal to fix *that* step.
+- **Drive live, don't lecture.** Probe the user's real state (`/api/health`, `aware agent list`) and
+  build against it. A real install→compile→run beats prose.
+- **Mutations need consent.** Installing an agent, writing the draft `.flo`, installing the app —
+  each is **offered, then done on an explicit yes**. Read-only probes run freely.
+- **Never invent.** Don't name an agent, command, or node kind that isn't real — verify against
+  `aware agent list` / `--available` and floless-app-workflows. A made-up agent fails at validate.
+- **Determinism is AWARE's.** The `.lock` is the approved contract; Run is gated on source-hash
+  freshness. Author the source; let `aware app compile` freeze it. Never teach around the gate.
+- **Plain-English descriptions are mandatory.** Every node's leading `//` comment is its Description
+  (non-coders read it). Author it as prose as you write each node — it is also a verified step.
+
+## Step 0 — Pick up the ask and orient
+
+1. **If launched from the UI**, a `new-workflow` request is queued. Fetch the authoritative spec and
+   clear it when done (the house handshake):
+   ```bash
+   curl -s http://127.0.0.1:4317/api/requests          # find the {"type":"new-workflow", id} entry
+   # …do the work below…
+   curl -s -X DELETE http://127.0.0.1:4317/api/requests/<id>   # only after the app is installed
+   ```
+   If invoked directly ("/floless-app-new-workflow", "build me a workflow"), skip the queue.
+2. **Confirm the ground** (read-only): `curl -s http://127.0.0.1:4317/api/health` →
+   `{"ok":true,"awareVersion":"<v>", ...}`. No response → the floless.app desktop app isn't running;
+   the user can still author from the terminal, but the final Compile/Run happens in the UI, so ask
+   them to start it. `license` not `valid` → the UI's Run sits behind a sign-in gate; mention it when
+   you reach Run, don't block authoring.
+
+## Step 1 — Interview (what should it do?)
+
+Pull the goal out in **one or two questions at a time**, plain English — never a wall:
+- "What do you want this workflow to do?" (e.g. "list parts by phase", "export a BOM", "write a
+  greeting"). Get the *outcome* first.
+- Then the shape: what **input(s)** does it take (a phase number? a file? nothing?), what **output**
+  the user wants to see (an HTML report in the Viewer? a value?), and which **host** (Tekla? none?).
+
+Restate it in one sentence and get a nod before authoring. Keep it small — the first version should
+**run**; extend it after. (Laziness: ship the one-node version that works, then grow it.)
+
+## Step 2 — Agent preflight (before writing any node)
+
+A node references an `agent` (e.g. `tekla`, `file`). **Confirm each one exists before authoring it** —
+a workflow built on a missing agent fails at validate. Read `references/build-and-verify.md` →
+"Agent preflight" and run the three-way check: **installed** (`aware agent list`) → use it;
+**available but not installed** (`aware agent describe <id> --available`) → offer to install it
+(consent); **truly absent from the catalogue** → it's a capability gap → offer to **report it as an
+idea** (the reference spells out the report relay + the `aware` label). Never silently substitute or
+invent an agent.
+
+## Step 3 — Author the `.flo`, verifying each step
+
+Read `references/build-and-verify.md` and follow the loop: write the draft under
+`~/.floless/drafts/<id>/<id>.flo`, scaffold the **smallest valid shape**, then build up node by node —
+**each node gets its plain-English `//` description and a real check before the next.** The reference
+maps every step to the command that proves it (`validate` → `compile` → `install` → real `run`, read
+the trace). For exec specifics (globals, `return`, no `System.Net`/Regex, no `{{ }}` in code
+comments, `layout: linear` vs `dag`), defer to **floless-app-workflows** — don't reinvent them.
+
+## Step 4 — Hand back to the UI (Compile → Run → approve)
+
+Once the app **installs and a real run is green**, hand it to the user in floless.app:
+1. It now appears in the **workflow picker** (top-right) — have them select it.
+2. **Set inputs** on the input node (if any), then **Compile** (freezes the approved `.lock`; the Run
+   gate opens only when source-hash matches).
+3. **▶ Run workflow** against the live host — the result renders in the canvas / HTML Viewer.
+4. The user **approves** what they see. Done — they built a workflow from nothing.
+
+Then DELETE the queued request (Step 0) if one launched this.
+
+## Close
+
+Recap in two lines what they built and how to grow it ("want a second node that exports a BOM?
+re-run /floless-app-new-workflow, or just tell me"). Offer the obvious next step — bake it into a
+reusable agent (**floless-app-rebake** / Bake), or automate it on a trigger (**floless-app-routines**).
+
+## Guardrails
+
+- **Verify every step — no "probably works".** A node isn't done until its check passes (description
+  prose, validate, compile, a real run with a green trace). `--simulate` does NOT count — it stubs
+  every node and emits no real output.
+- **Read-only by default; mutations on consent.** Installing an agent, writing the draft, installing
+  the app — offer, then act on an explicit yes.
+- **Never invent agents/nodes.** Verify against `aware agent list` / `--available`; report a real gap
+  as an idea, don't fake it.
+- **Don't contradict the architecture.** The UI never composes the workflow or calls an LLM; you (the
+  terminal AI) author it, AWARE compiles/runs it, the `.lock` is the approved contract.
+- **Lean on floless-app-workflows** for the exec contract and the run-trace details — this skill
+  orchestrates; it does not duplicate the contract reference.

package/dist/skills/floless-app-new-workflow/references/build-and-verify.md

@@ -0,0 +1,117 @@
+# Build-and-verify loop + agent preflight
+
+The mechanics behind Steps 2–3 of `SKILL.md`. Every step here maps to a **real command that proves
+it** — that is the whole point of this skill (build a workflow whose every step is checked, not
+guessed). For the exec contract itself (globals, `return`, templating, layout, gotchas) read
+**floless-app-workflows**; this file does not duplicate it.
+
+All paths resolve at runtime — `~` is the user's home; never hardcode an absolute `C:\…` / `D:\…`.
+
+## Where a new draft lives
+
+A user's brand-new workflow is **not** a repo demo — author it in a user-owned scratch dir, one
+directory per app (the install/compile/run verbs all take a *directory*, never a bare `.flo`):
+
+```
+~/.floless/drafts/<id>/<id>.flo
+```
+
+`<id>` is the app id (lowercase, `a–z 0–9 - _`), the same string as the `.flo`'s top-level `app:`
+field. Create the dir, write the `.flo` into it, and run every verb against `~/.floless/drafts/<id>`.
+
+## The smallest valid shape (scaffold, then grow)
+
+Start with the **one-node app that runs**, prove it, then add nodes. The minimal valid `.flo`:
+
+```yaml
+app: my-first              # required — the id; matches the folder name
+version: 0.1.0             # required — semver
+display-name: My First     # required for the picker label (validator doesn't enforce it)
+description: |             # required — plain-English paragraph for non-coders
+  What this workflow does, in one or two sentences.
+requires: []              # conventional — list the preflighted agents (e.g. [tekla@0.1.x]); every demo carries one
+layout: linear            # linear (node-order chain) | dag (explicit connections)
+nodes:
+  - id: hello
+    agent: tekla          # a REAL agent (preflight first); model-free exec needs no open model
+    command: exec
+    mode: read
+    config:
+      version: "2025.0"   # required for tekla/exec — the Tekla version
+      args: {}
+      code: |
+        // Plain-English description of what this node does — this IS the node's Description.
+        return new { ok = true };
+```
+
+Grow by adding nodes one at a time. Inputs → `inputs:` block, templated `{{ inputs.<name> }}`;
+cross-node data → `{{ <node-id>.result.<field> }}`. **Any branch (fan-out/fan-in) needs `layout: dag`
++ a `connections:` block** — a straight chain stays `linear`. (Details + footguns →
+floless-app-workflows. Critical one: **never write `{{` or `}}` inside a `code:` block**, even in a
+`//` comment — it is templated and a stray brace aborts the run.)
+
+## The verify-each-step loop
+
+Author a node (with its `//` description), then run the checks **in order** before the next node.
+Each command is the proof for that step:
+
+| Step | Command (run from anywhere; dir = the draft) | Proves |
+|---|---|---|
+| 1. Descriptions are plain English | eyeball the leading `//` of every node + the top-level `description:` — prose, ≥3 words, no raw code/markup. (The repo's `npm run verify:flo` enforces this for committed demos; a user draft lives outside `demos/`, so apply the rule yourself.) | non-coders can read the Inspect → Description tab |
+| 2. Structural validity | `aware app validate ~/.floless/drafts/<id>` | YAML parses; required fields present; node topology sound; **every referenced agent exists** (else `E_APP_AGENT_UNAVAILABLE` — back to preflight) |
+| 3. Install | `aware app install ~/.floless/drafts/<id>` (re-installing the same id? `aware app uninstall <id>` first — a same-id install errors `app <id> already installed`) | the app lands in `~/.aware/apps/<id>/` and shows in the floless.app picker |
+| 4. Compile → lock | `aware app compile ~/.floless/drafts/<id>` | resolves agents, stamps `source-hash`, writes `<id>.lock` into the installed app dir — the approved, runnable contract |
+| 5. Real run | `aware app run <id> --input k=v --json` | every node executes for real; trace at `~/.aware/logs/<id>/<instance>/<run>.jsonl` |
+| 6. Read the trace | open that `.jsonl` | every node emits `node-output` with `ok:true` and it ends `run-end · status:ok` |
+
+**`--simulate` is not a check** — it stubs every node, emits no real `result.<field>`, and renders
+templates as `undefined`. A green simulate proves nothing. Always do a real run.
+
+### No Tekla open? Still do a real run.
+
+A `tekla/exec` node runs Roslyn in the host bridge `aware-tekla.exe` — it needs the **bridge**, not a
+live model. A node that **never dereferences `model`** (builds a string/HTML, reads an arg, returns
+data) runs with nothing open in Tekla. So a from-scratch first workflow that just returns a value or
+builds an HTML report verifies end-to-end with no model. If the bridge is stale,
+`aware sidecar install tekla` refreshes it. (A C# compile error surfaces only as an opaque
+`agent tekla/exec failed (exit Some(2))` — isolate by checking your `code` compiles; no `System.Net`,
+**no `System.Text.RegularExpressions`**, manual HTML-escape. See floless-app-workflows.)
+
+When step 6 is green, the app is **installed, compiled, and proven** — hand back to the UI (SKILL.md
+Step 4). If a step fails, fix **that** node/field and re-run from the failed step; don't push past it.
+
+## Agent preflight (Step 2 in full)
+
+Before authoring a node on an `agent`, confirm that agent exists. Three outcomes:
+
+1. **Installed** — `aware agent list` shows it → use it. (`tekla` and `file` are the common ones.)
+2. **Available but not installed** — not in `list`, but `aware agent describe <id> --available` finds
+   it in the registry catalogue → **offer to install it** (consent, it's a mutation):
+   - host bridges (tekla, rhino, sketchup, revit) → `aware sidecar install <host>`
+   - other catalogue agents → `aware agent install <id>`
+   Before assuming a gap, `aware agent search <term>` so a **misspelling or a differently-named
+   existing agent** isn't mistaken for "missing" (e.g. the user says "spreadsheet" but it's `file`).
+3. **Truly absent** — not installed, and `aware agent describe <id> --available` reports not-found
+   (and `search` turns up nothing) → a genuine **AWARE capability gap**. Don't fake it, don't
+   substitute silently. Offer to **report it as an idea** (below), then either pick a different
+   approach with the agents that *do* exist, or pause that node until the agent ships.
+
+### Reporting a missing agent as an idea
+
+A not-yet-existing agent is a legitimate "missing-but-expected capability" — file it so it can be
+built. Route it through **floless-app-report-issue** (it owns the floless.io relay) as an **idea**:
+
+- `POST http://127.0.0.1:4317/api/report-issue` with `category: "idea"`, a title prefixed
+  `[AWARE agent] <id> —` and a body that states: the **capability needed** (what host/agent, what the
+  workflow would do with it), **why** (the user's real goal from Step 1), and the **proof it's
+  absent** (the `aware agent describe <id> --available` not-found / the `E_APP_AGENT_UNAVAILABLE`
+  from validate).
+- The relay files it into the **floless.app** issue tracker, tagged `idea` + `user-report` — so it is
+  known to come from a real floless user via the licensed relay, not an anonymous open-source report
+  (and the public `aware-aeco/aware` tracker stays clean). The maintainer triages these under the
+  `aware` label and promotes the real ones into actual AWARE agents.
+- This is **consent-gated and read-only to the user's machine** — it sends a report, it changes
+  nothing locally. Confirm the user wants it filed before sending.
+
+Discriminator (don't file noise): only a *genuinely absent* agent is an idea. A typo, a wrong
+capability guess, or a validate error caused by your own bad `code` is **not** a gap — fix the usage.

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

@@ -91,7 +91,8 @@ tell them how to come back:
 > 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).
+workflow?" (hand off to **floless-app-new-workflow**, the step-by-step from-scratch builder — or
+**floless-app-workflows** for the raw authoring reference) or "install one of those agents?" (A4).
 
 ## Guardrails
 

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

@@ -62,10 +62,14 @@ the project folder (a few files, **not** a framework):
   section / detail / schedule). This is the map the later stages classify against.
 - **`general-notes.md`** — the General Notes that bind the whole job: design spec, default
   connection type, bolt/weld standard, material grades, anything that overrides a single sheet.
-- **`company-rules.md`** *(ask first)* — **ask whether the firm has company-specific standards**
-  (e.g. "moment → detail 50S504 → Tekla component 146"). If yes, capture them here. This file feeds
-  the connection-library pre-fill in stage 6 (the editor's Connections panel reads these as
-  `source:"company-rules"`). If the firm has none, skip the file — don't invent rules.
+- **`company-rules.md`** *(ask first)* — **ask whether the firm has company-specific standards.** Two
+  kinds, both captured here: (1) **connection-library mappings** (e.g. "moment → detail 50S504 → Tekla
+  component 146") that feed the connection-library pre-fill in stage 6 (the editor's Connections panel
+  reads these as `source:"company-rules"`); and (2) **firm DETAILING standards** — default bolt grade +
+  length-from-grip, usual gages, near/far-side, shear-tab shape/edge/clearance — that the Steel Takeoff
+  reader applies to a connection's `joints[].params` when detailing (see `floless-app-steel-takeoff`
+  §5.5b). The file is machine-local / the firm's private IP (it may live in the user's own synced Drive)
+  — **never committed.** If the firm has none, skip it — don't invent rules.
 
 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

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

@@ -2,7 +2,7 @@
 name: floless-app-steel-takeoff
 description: Read a structural steel drawing into an editable steel.takeoff/v1 contract in floless.app — the "Steel Takeoff" reader. Triggers on a pending floless `rebake` request for the `steel-model` app (queued from its "Re-read & re-bake ▸" button), or asks like "read this framing plan into a takeoff", "turn this structural drawing into a takeoff", "bake my drawing into steel-model", "extract members from this PDF". Teaches the host AI to READ a steel drawing (PDF/image) with its own vision at COMPOSE time, build a steel.takeoff/v1 contract (members + profiles + elevations + weights from AISC lookup), write it to the contract store, and hand control to the editor — no model in the run path, no API key.
 metadata:
-  version: 0.1.0
+  version: 0.2.0
 ---
 
 # Steel Takeoff — read a drawing into a steel.takeoff/v1 contract
@@ -293,10 +293,93 @@ Key field rules:
   when `conn` is empty. `source` is `drawing` (read from a callout — best evidence), `company-rules`
   (the firm's standard), or `user`. Prefer a `conn` reference over free text when the connection is
   known — the editor's per-end picker and the Connections confidence card both key on it.
+- **Base-plate connections (`joints[]`) — the geometry recipe.** Where the set has a **base-plate
+  detail + schedule** (column size → base-plate THK×"N"×"B", anchor Ø×embed, weld "A", washer plate),
+  emit a top-level `joints[]` entry per column so FloLess renders the real plate + anchor kit + weld
+  in 3D: `{ id, kind:"base-plate", main:"<column member id>", at:"base", source:"auto", params:{…} }`.
+  The joint binds to the column by id and may CITE a `connections[]` row via `conn` for its
+  type/detail identity (build on the library, don't fork it). Map the schedule straight into `params`:
+
+  | Schedule callout | `params` key(s) |
+  |---|---|
+  | base-plate THK · "N" · "B" | `thickness` · `plateWidth` · `plateDepth` |
+  | anchor bolt Ø · count | `boltDia` · `boltCols`×`boltRows` |
+  | weld size "A" | `weldLeg` |
+  | "provide 1/4"×3"×3" PL washer w/ std hole" | `washerPlateThickness` · `washerPlateSide` |
+  | "anchor holes oversized: A-bolt Ø + 5/16"" | `holeClearance` (the +amount) |
+  | edge distance · embed | `edgeDist` · `projBelow` |
+
+  ⚠️ **UNITS: the *dimensional* `params` are MILLIMETRES** (the engine works in mm) — unlike the
+  contract's display/inch member coords — so convert the schedule's inches ×25.4. (`boltCols` /
+  `boltRows` are integer *counts*, not mm; `projBelow` is how far the rod renders below the plate — a
+  reasonable proxy for the embed.) Any omitted param falls back to a sensible default. Worked example
+  (a `W10x33 → 1"×18"×10", 1"Ø×12", 5/16"` schedule row):
+  `params: { thickness:25.4, plateWidth:457.2, plateDepth:254, boltDia:25.4, boltCols:2, boltRows:2, edgeDist:50.8, weldLeg:7.94, washerPlateThickness:6.35, washerPlateSide:76.2, holeClearance:7.94, projBelow:304.8 }`.
+  The weld automatically traces the column's **profile outline** (the I-shape for a W; a rectangle for
+  an HSS — square only when the section is square). *(The outline is engine-rendered: a wide-flange's
+  flange width is still approximate until a real AISC `bf` table lands, so a W renders a touch narrow —
+  the plate/anchor/weld sizes you set are exact.)*
+- **Shear-plate (fin-plate) connections (`joints[]`) — the bolted beam-end recipe.** Where a beam end
+  reads as a **shear / simple / fin-plate / shear-tab** connection (the per-end `note`/`conn`), emit a
+  `joints[]` entry **per beam end** so FloLess renders the vertical fin plate (bolted to the web) + the
+  bolt group + the plate-to-support weld in 3D:
+  `{ id, kind:"shear-plate", main:"<SUPPORTED BEAM member id>", at:"end0"|"end1", source:"auto", params:{…} }`.
+  ⚠️ **`main` is the BEAM** (not the support) — the joint sits at one of the beam's ends; `at:"end0"` =
+  the start end (`ends[0]`), `at:"end1"` = the far end (`ends[1]`). Optionally name the support in
+  `secondaries:["<column/girder id>"]` (metadata only — the geometry is placed off the beam end + beam
+  axis, so it's not required). May CITE a `connections[]` row via `conn` for its type/detail identity.
+  Map the schedule into `params`:
+
+  | Schedule callout | `params` key(s) |
+  |---|---|
+  | plate THK · width (along beam) · height | `plateThickness` · `plateWidth` · `plateHeight` |
+  | bolt Ø · rows×cols · pitch/gauge | `boltDia` · `boltRows`×`boltCols` · `boltPitch` |
+  | weld size | `weldLeg` |
+  | beam clearance / erection gap off the support (≈½–¾") | `clearance` |
+  | which face of the beam web the plate laps | `webSide` (+1 / -1) |
+  | bolt grade (AISC) — A325 or A490 | `boltGrade` ("A325" / "A490") |
+  | "stiffener / backing plate on the far side" | `stiffener: true` |
+
+  ⚠️ **UNITS: the *dimensional* `params` are MILLIMETRES** (×25.4 from inches) — `boltCols`/`boltRows`
+  are integer counts; `stiffener` is a boolean; `webSide` is +1/-1. The fin plate is VERTICAL (in the
+  beam-web plane) and **laps one face of the web** (not centred — `webSide` picks the face), cantilevered
+  toward the beam from the support edge; the **`clearance` pulls the beam back** so it clears the support
+  (the cope/cut is a later slice). Omitted params fall back to sensible defaults (10 mm plate, 1×3 M20
+  bolts at 70 mm, 6 mm weld, ~13 mm clearance; A325 grade). The bolt **length is not a param** — it
+  auto-sizes from the grip (clamped plies) per the AISC A325/A490 chart and rides the bolt callout (the
+  3D part label); `boltGrade` only picks A325 vs A490. For a beam-to-beam joint, name the supporting girder in
+  `secondaries:["<girderId>"]` so `stiffener:true` draws a full-height stiffener on the girder web.
+  Worked example (a 3/8"×4"×8" tab, 3×3/4" bolts @ 3", far end of beam b3): `{ id:"sp-b3-e1",
+  kind:"shear-plate", main:"b3", at:"end1", source:"auto", params:{ plateThickness:9.5, plateWidth:101.6,
+  plateHeight:203.2, boltCols:1, boltRows:3, boltDia:19.05, boltPitch:76.2, weldLeg:6.35, clearance:12.7 } }`.
 - **Company-rules pre-fill (§5.5).** If a firm-standard knowledge file is present (e.g.
   `company-rules.md`: "moment → 50S504 → Tekla 146"), read it and emit those rows in `connections[]`
   with `source: "company-rules"`, then PUT. The user reviews/edits them in the editor's
   **Connections** library panel and assigns a row per member end. No new agent verb — it's contract data.
+  - **Firm DETAILING standards → shear-plate `joints[].params` (§5.5b).** The same `company-rules.md` is
+    also the home for the firm's **detailing** standards (the firm's IP / AISC-*Manual* reference data —
+    kept **machine-local, NEVER committed**, and out of the public `aware` AISC agent, which is
+    free-source only). When detailing a **shear plate**, read these and set the matching `joints[].params`
+    (and say you applied the firm rule), instead of leaning on the engine defaults:
+    - **Bolt grade + length** — the firm's default grade → `boltGrade` ("A325"/"A490"). The bolt length
+      auto-sizes from grip in the engine per the firm's A325/A490 bolt-length chart; just confirm the
+      grade. *(The firm's chart in `company-rules.md` mirrors AISC Manual Table 7-18 add-to-grip — facts
+      for the firm's own use; do not republish the table.)*
+    - **Usual gages** — the firm's bolt gauge `g` by flange width / leg (W-beams, angles) → `boltPitch`
+      and the bolt grid; e.g. a W-beam web gage or a standard 3" pitch. Read the gage table.
+    - **Near-side / far-side (NS-FS)** — the firm's default web face the shear plate laps → `webSide`
+      (+1 near / -1 far). Many shops default NS unless the drawing says FS.
+    - **Knife-plate / shear-tab shape + edge distance + clearance** — the firm's standard plate
+      proportions, edge distance, and erection clearance → `plateWidth`/`plateHeight`/`edgeDist`/
+      `clearance`. Use the firm's value when it differs from the engine default.
+    - **Sizing stays detailing-not-design.** Apply the firm's DEFAULTS + flag a drawing value that
+      conflicts; never invent a number. The drawing's explicit callout still wins over the firm default.
+    - *(Base plates have their OWN firm keys — `plateWidth`/`plateDepth`/`thickness`/`edgeDist`/
+      `boltCols`×`boltRows`/`boltDia`/`weldLeg`/`holeClearance`/`projBelow` — no grade/pitch/webSide;
+      apply the firm's base-plate schedule there the same way.)*
+    Format in `company-rules.md`: plain headed sections the AI can read (e.g. `## Bolts` with the grade
+    default + the length chart, `## Gages`, `## Shear tab (NS-FS, edge, clearance)`). The author keeps it
+    private; FloLess just reads + applies it.
 - **Clickable callouts (`callouts[]`).** Harvest the cross-reference marks drawn ON the plan that
   point to ANOTHER sheet — **section cuts** (e.g. a circle with `A` over `A` and a sheet ref),
   **elevation/interior-elevation marks**, and **detail references** — as per-plan

package/dist/web/app.css

@@ -460,6 +460,15 @@
   /* 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; }
+  /* Quiet secondary first-run action — an inline text button, NOT a second filled
+     button, so "Start the guided tour" stays the dominant primary. Existing tokens only. */
+  .onb-build-btn {
+    background: none; border: none; padding: 0; cursor: pointer;
+    font-family: var(--ui); font-size: 12px; font-weight: 600; color: var(--accent);
+    letter-spacing: 0.01em;
+  }
+  .onb-build-btn:hover { color: var(--accent-bright); text-decoration: underline; }
+  .onb-build-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 2px; }
   /* "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). */
@@ -479,6 +488,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/app.js

@@ -131,7 +131,7 @@ function onboardingHtml() {
         step(3, 'Compile', '— freeze the approved lock') +
         step(4, 'Run', '— against the live host; results render here') +
       `</ol>` +
-      `<div class="onb-foot">No workflows yet? Just ask your terminal AI to build one.</div>` +
+      `<div class="onb-foot">No workflows yet? <button class="onb-build-btn" type="button" aria-label="Build your first workflow — hands off to your terminal AI to build one from scratch">Build your first workflow →</button></div>` +
     `</div>`
   );
 }
@@ -162,6 +162,11 @@ function wireOnboardingCopy() {
       }
     };
   }
+  // Secondary first-run action: "Build your first workflow" — the empty canvas is the
+  // highest-intent moment to create one, so surface the same relay the ≡ menu's "New
+  // workflow…" fires (handleMenuAction is reassigned in aware.js → requestNewWorkflow).
+  const build = $topology.querySelector('.onb-build-btn');
+  if (build) build.onclick = () => handleMenuAction('new-workflow');
 }
 
 function nodeIds(p) {