@floless/app 0.5.1

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

@@ -0,0 +1,352 @@
+---
+name: floless-app-workflows
+description: This skill should be used when building, modifying, or reasoning about AWARE .flo workflows for floless.app — especially reusable apps that take inputs (e.g. a phase number) and run across different Tekla models, exec nodes that run Roslyn C# against the live model, the in-app HTML Viewer, the Code tab, or "Debug in VS". Covers the exec contract, the install→validate→compile→run loop, app inputs templating, and the server seams (aware-adapter, app-reader, index).
+metadata:
+  version: 0.1.0
+---
+
+# Building reusable .flo workflows in floless.app
+
+## What floless.app is (and is not)
+
+floless.app is a **thin web UI over the `aware` CLI**. It owns **no engine and no LLM**.
+Every capability is either `aware <verb>` (shelled through one adapter) or reading AWARE
+state off disk. The browser is just the window. Never make the UI compose workflows or call
+an LLM — it renders AWARE state, triggers `aware` verbs, and relays user intent.
+
+The deliverable floless.app produces is a **reusable AWARE `.flo` app**: one that declares
+`inputs:` with defaults and runs unchanged across different models. The canonical example
+lives at `demos/tekla-bom-by-phase/` — study it before building a new one.
+
+## The reusable-app shape
+
+An app becomes reusable by declaring a top-level `inputs:` block and templating those inputs
+into node config with `{{ inputs.<name> }}`. The canonical `tekla-bom-by-phase.flo` models the
+**desktop-floless 3-node shape** — a Phase **input** node → the Tekla **core logic** node → an
+HTML Report **viewer** node — as **three real `tekla/exec` nodes whose data flows along the
+edges** (the canvas story and the data flow are the same thing):
+
+```yaml
+app:           tekla-bom-by-phase
+version:       0.3.0
+display-name:  Tekla BOM by Phase
+description: |
+  <one paragraph — required>
+exposes-as-agent: false
+inputs:
+  phase:
+    type: integer
+    default: 1        # keeps the app runnable with no user action
+    description: Construction phase number to report on (Tekla PHASE) — editable per run.
+requires:
+  - tekla@0.1.x
+layout: linear
+nodes:
+  - id: phase-input               # NODE 1 — Phase input: scope the run
+    agent: tekla
+    command: exec
+    mode: read                    # author intent (see exec-mode note below)
+    config:
+      version: "2025.0"
+      args: { phase: "{{ inputs.phase }}" }            # from the app-input knob
+      code: |
+        <Roslyn C# — reads args["phase"], returns new { ok, phase, partsInPhase, modelName }>
+  - id: bom                       # NODE 2 — the Tekla core logic
+    agent: tekla
+    command: exec
+    mode: read
+    config:
+      version: "2025.0"
+      args: { phase: "{{ phase-input.result.phase }}" } # CARRIES node 1's output along the edge
+      code: |
+        <Roslyn C# — reads args["phase"], returns new { ok, phase, html, ... }>
+  - id: viewer                    # NODE 3 — HTML Report Viewer terminal
+    agent: tekla
+    command: exec
+    mode: read
+    config:
+      version: "2025.0"
+      args:
+        html:  "{{ bom.result.html }}"                 # CARRIES the report along the edge
+        phase: "{{ bom.result.phase }}"
+      code: |
+        <Roslyn C# — returns new { ok, phase, html = args["html"] } (the terminal)>
+connections:
+  - { from: phase-input, to: bom }
+  - { from: bom, to: viewer }
+```
+
+At run time the user (or the UI) supplies `--input phase=2`; the runtime substitutes it into
+node 1's `config.args.phase`; the bridge hands it to the C# as the `args` global. Node 1 emits
+the phase, node 2 consumes it and emits the report HTML, node 3 carries that HTML as the
+terminal — the edges carry real data.
+
+### `layout:` must match the topology (`linear` vs `dag`) — VERIFIED
+
+The top-level `layout:` field is **load-bearing for the UI**, not a cosmetic hint. The canvas
+(`renderTopology` in `web/aware.js`) only honors the `connections:` block when `layout: dag`;
+under `layout: linear` it **ignores `connections` and draws a node-order chain** (each node → the
+next, in file order), pulling only edge *labels* positionally. So: a straight chain → keep
+`layout: linear`; **any branch — fan-out, fan-in, a node feeding two — → use `layout: dag`**, or
+the real edges won't render (a fan-out `message-input → A` + `message-input → B` shows as the
+chain `message-input → A → B`). `dag` triggers `layoutDag` (longest-path layering over the real
+`connections`). Verified on aware 0.51.0 against the live UI; `college-phase-exporter` ships `dag`.
+
+### Cross-node templating (how data flows along an edge) — VERIFIED
+
+A downstream node references an upstream node's returned object as **`{{ <node-id>.result.<field> }}`**
+(empirically verified on aware 0.46.0). The `.result.` segment is required: the host bridge
+wraps an exec script's `return` value under `result` (the node output is
+`{ ok, result: {...}, host, host_version, ... }`), so `{{ bom.html }}` resolves to **empty** but
+`{{ bom.result.html }}` resolves to the value. Large strings carry intact (an ~12 KB BOM HTML
+travels node 2 → node 3 unchanged). exec output is dynamic, so no `output-schema` is needed for
+the reference to resolve. (The `app-spec.md` example's `{{ runtime: <node>.<field> }}` prefix
+form is stale — the no-prefix `{{ <node>.result.<field> }}` is what runs.)
+
+**FOOTGUN — `{{ }}` is rendered across the WHOLE node config, including the exec `code`
+(comments too) — VERIFIED on 0.51.0.** The template engine doesn't skip the `code` block, so any
+`{{ … }}` in C# (even inside a `//` comment) is parsed/rendered at run start and aborts the run:
+- a `{{ }}` literal (empty) → `template parse: syntax error: unexpected end of variable block`;
+- a self-reference like `{{ <thisNode>.result.x }}` in the node's own comment → `template render:
+  undefined value` (a node's own `result` doesn't exist during its own execution).
+The failure surfaces as `aware app run … failed (exit 3)` on the FIRST node, which reads like a
+host-attach error but isn't. **Rule: never write `{{` or `}}` anywhere inside `code`** — describe
+templates in prose without braces (e.g. "reads `node.result.x`"). The only legitimate `{{ }}` live
+in `config.args` values. (`tekla-bom`'s comments dodge this only because they reference an
+*upstream* node that has already run — fragile; prefer no braces in code at all.)
+
+### Why all three nodes are `tekla/exec` (hard constraints — predicates can't carry data)
+
+- **Inline nodes can't carry data.** Only `inline.kind: predicate` runs, and predicates return a
+  **boolean** — they cannot emit a value to a downstream node. `kind: shape`/`map` (which could
+  reshape/pass data) are **rejected at validate + compile** on aware 0.46 (`E_APP_INLINE_KIND`,
+  closed #160) and marked reserved/not-yet-runtime-supported. So a genuine input→logic→viewer
+  **data flow** can only be built from real host (`exec`) nodes.
+- **The `html-report` agent ships no binary** and on aware 0.46 is marked `status: planned` and
+  **rejected** at validate/install/compile/run (`E_APP_AGENT_UNAVAILABLE`, closed #161) — never
+  use it as the viewer. The viewer is a `tekla/exec` node that **forwards `{{ bom.result.html }}`**
+  and returns it, so the report HTML is the terminal node's own output. `extractReportHtml`
+  scans the trace and takes the **last** node carrying `data.result.html`; floless's HTML Viewer
+  binds to the chain **terminal** (`reportNodeId()` = last node when any node has exec code), so
+  the forwarded HTML is what renders.
+- **Cost of the 3-exec shape:** 3 bridge round-trips per run (~10–15 s) and the report HTML
+  crosses the bridge twice (built in node 2, echoed by node 3). Acceptable for the
+  data-carrying canvas; the alternative (a single exec + UI-only "input"/"viewer" chrome)
+  doesn't honor "3 visible nodes".
+
+### exec mode label: declare `mode: read`, but AWARE overrides it (issue #165)
+
+Declare `mode: read` on every read-only exec node (author intent). **AWARE ignores it for
+`exec`:** the compiler can't resolve an exec command's mode, so the lock stamps `mode: write`
+with the note *"…command exec not found; defaulting to write-mode for safety"* (filed as
+aware-aeco/aware#165 — silent override of a documented field). It's cosmetic — read-only exec
+runs fine with no `safety:` block. floless reconciles this in `app-reader.ts`: when the source
+declares `mode: read` and the lock defaulted an exec node to write, the UI shows **read** and
+rewrites the cryptic note into a plain-English one — surfacing AWARE's default, not hiding it.
+
+## The exec contract (tekla `agent: tekla, command: exec`)
+
+The exec node runs Roslyn C# in the host bridge (`aware-tekla.exe`) against the **live model**.
+Globals injected: `dynamic model` (a `Tekla.Structures.Model.Model`) and
+`IDictionary<string, object> args` (the `config.args` block, JSON-typed). The script ends with
+`return <object>;`. Read `references/exec-contract.md` for the full contract, the available/
+unavailable references (no `System.Net`, no `System.Diagnostics.Process`; manual HTML-escape),
+the part-NAME categorization, and phase filtering.
+
+Two rules that bite immediately:
+- **Return the report HTML inline** as `return new { ok = true, html = sb.ToString(), ... };`.
+  Do **not** write a file. AWARE ships no html-report render binary, and inline HTML keeps the
+  app model-agnostic (no filesystem permission, no hardcoded path). The HTML Viewer renders
+  whatever the node returns.
+- **No `System.Net`** (so no `WebUtility.HtmlEncode`) — escape with a manual lambda.
+
+## The build loop (install → validate → compile → run)
+
+Resolve the `aware` CLI the same way the adapter does: prefer the npm global
+`@aware-aeco/cli/scripts/bin/aware.js` run via `node`. Then:
+
+1. **Install from the app's *directory*** (not the `.flo` file — registry-hosted/path-to-file is
+   rejected): `aware app install ./demos/tekla-bom-by-phase`. **Reinstalling an updated app first
+   needs `aware app uninstall <id>`** — a same-id `app install` errors `conflict: app <id> already
+   installed` and silently leaves the OLD source in place (a stale compile/run will mislead you).
+2. **Validate** — `aware app validate <PATH>` takes the app's **directory** (NOT an app id, and
+   NOT the `.flo` file): `aware app validate ./demos/tekla-bom-by-phase`. Verified on 0.51.0:
+   passing an id errors `io: cannot find the path` (os error 3); passing the `.flo` file errors
+   `directory name is invalid` (os error 267).
+3. **Compile** — `aware app compile <PATH>` also takes the app **directory** and writes
+   `<app>.lock` **into that same directory**. To refresh what the UI reads, compile the installed
+   copy (`aware app compile ~/.aware/apps/<id>`); or compile the editable source
+   (`aware app compile ./demos/<id>`) and copy the `.lock` across. If the `.lock` is missing/stale
+   in `~/.aware/apps/<id>/`, app-reader reports `uncompiled` and the UI Run gate stays disabled.
+   (Older docs said `compile <id>` resolved relative to CWD — stale; it's a `<PATH>` arg now.)
+4. **Run for real — MANDATORY before calling ANY `.flo` change done.** `aware app run <id> --input
+   k=v --json` (`run` takes the app **id**, unlike `validate`/`compile` which take a path). The
+   trace lands at `~/.aware/logs/<id>/<instance>/<run>.jsonl`; the exec result is at `data.result`
+   (the bridge wraps the script's return under `result`). **Read the trace** and confirm every node
+   emitted `node-output` with `ok:true` and the run ends `run-end · status:ok`. A clean compile and
+   a correctly-rendered canvas do **NOT** prove the `.flo` runs — a bad cross-node template or a
+   stray `{{ }}` in `code` only surfaces at run (it aborts the FIRST node with a misleading exit-3
+   "host" error). Then drive the same **▶ Run workflow** in the UI per the project's real-E2E rule.
+
+   **`--simulate` is NOT a substitute for exec apps.** Verified on 0.51.0: `--simulate` aborts at
+   the first template (`template render: undefined value (in t:1)`) for BOTH `hello-world` AND
+   `tekla-bom-by-phase` (the latter runs fine for real) — stubs carry no `result.<field>` and even
+   `{{ inputs.* }}` isn't seeded, so the first template renders undefined regardless of correctness.
+   A simulate "failure" on an exec-data-carrying app therefore proves nothing. Simulate only helps
+   for schema-backed (non-exec) compositions and for catching template *parse* errors; the real
+   gate is a live `aware app run` + trace check (above).
+
+Keep both copies in sync: the editable source under `demos/<id>/` (committed) and the installed
+copy under `~/.aware/apps/<id>/`. Copy the freshly compiled `.lock` back into `demos/<id>/`.
+
+## Bake a workflow into a reusable agent (`exposes-as-agent`) — VERIFIED, AWARE 0.52.0+
+
+A multi-node `.flo` can be **baked into a single callable agent** so another app drops it in as one
+node and still sets its inputs. Declarative (no `aware bake` verb): add two manifest fields to the
+`.flo`. Wired end-to-end by aware-aeco/aware#178 (shipped 0.52.0); inert/dead-code on ≤0.51 — gate on
+the CLI version. Verified on 0.52.0 (see `docs/plans/2026-05-29-bake-workflow-into-agent-design.md`).
+
+```yaml
+exposes-as-agent: true
+exposed-commands:
+  run:                       # the command other apps call: agent: <app>, command: run
+    lifecycle: single        # single = one-shot, returns the terminal node's output;
+                             # start  = long-running, streams terminal outputs (event source)
+    inputs:
+      phase: { type: integer }   # ← becomes the agent's parameter; caller sets it, type-validated
+    outputs: { type: single, schema: { ok: bool, phase: integer } }
+nodes: [ ... the normal chain ... ]
+```
+
+Mechanics (all confirmed against the substrate + a real run):
+- **`aware app install`** of an exposes-as-agent app **synthesizes a callable agent** under
+  `~/.aware/agents/<app>/manifest.yaml` — it then shows in `aware agent list` and resolves as
+  `agent: <app>`. `aware app uninstall` removes it. (No new install flag; it's automatic.)
+- **A consumer node** `{ agent: <app>, command: run, config: { phase: 7 } }` dispatches into the
+  nested chain; the caller's `config` inputs **route into the baked app's `{{ inputs.<name> }}`** and
+  are **type-validated** (wrong type → `validation failed: exposed command 'run' input 'phase':
+  expected integer, got string`). Observable proof: the nested run-start trace carries
+  `config:{phase:7}` (logs under `~/.aware/logs/<app>/nested/…jsonl`).
+- **Guards:** an exposed app **cannot** compose another exposed app (`E_APP_EXPOSED_COMPOSES_EXPOSED`)
+  nor reference its own id; `exposes-as-agent: true` with no `exposed-commands` →
+  `E_APP_EXPOSES_NO_COMMANDS`. The caller inherits the backing app's `requires`/permissions union.
+- **Test-without-a-host:** make the inner chain a single `inline.kind: predicate` node (runs with no
+  bridge) and assert the nested run-start `config`, or assert the type-rejection — both prove routing
+  without a live Tekla. (An `exec` inner node needs the real host.) Note: an inline predicate sees the
+  upstream *event* as `e.<field>`, NOT `inputs.<field>` — don't assert routing via the predicate body.
+
+floless.app play (designed, now unblocked): a "Bake into agent" affordance that rewrites a working
+`.flo` to add `exposes-as-agent` + `exposed-commands` mirroring the app's `inputs:`. Thin-UI: a
+manifest edit + recompile, no engine. See the design doc for the Stage-1 plan.
+
+## How the UI surfaces map to AWARE state
+
+- **Code tab** shows the node's real source: `node.config.code` (the exec C#), not lockfile
+  YAML. Pure-agent / inline nodes (no inline code) fall back to the resolved-lock YAML. The C#
+  is syntax-highlighted by a small dependency-free scanner in `web/aware.js`
+  (`highlightCSharp`) that reuses the demo's token classes (`kw`/`ty`/`st`/`cm` + `nu` for
+  numbers). No highlighting library — extend the scanner, don't add a dependency.
+- **Inputs live on the input node** (the old above-canvas strip was removed). The input node
+  (`inputNodeId()` — first node with `{{ inputs.x }}` in `config.args`) carries a **"Set inputs ▸"**
+  button (styled dialog, not `window.prompt`) and an at-a-glance **value chip** ("phase 5",
+  refreshed via `markSpecialNodes`). The report node carries a **"View report ▸"** button. Both
+  are first-class buttons injected by `markSpecialNodes` in `web/aware.js`; double-click the node
+  still works as a shortcut.
+- **One Run, single model** (the approved baseline has ONE `▶ Run workflow`; never add a second
+  run control). The header **`▶ Run workflow`** does the **REAL** run: `POST /api/run
+  {simulate:false, inputs}`. If the app has a report node (`reportNodeId()` — the exec terminal),
+  it renders the returned `html` in the HTML Viewer and caches it; otherwise it fills the Execution
+  trace. The secondary **`Simulate`** header button is `simulate:true` (every node stubbed from its
+  output-schema, no host) — a composition check.
+- **Per-node run status on the canvas + a Stop button.** During a run each node card paints
+  running → ✓ done / ✗ failed from the trace (`pushTrace`), and the report-run overlay shows a
+  **Stop** button. See `references/dev-server-and-run-trace.md` for the trace event kinds, the live
+  fs-watcher streaming, and the cancel mechanics.
+- **HTML Viewer** (in-app modal): **load vs run is split** (mirrors the desktop floless HTML
+  Viewer — the node displays the last result; it does not recompute).
+  - **Double-click the viewer node (or "View report ▸") → LOADS the last report** from an in-memory
+    per-app cache (`lastReportByApp`), instantly, **no run**. If nothing has run yet, it shows a
+    "click ▶ Run workflow" prompt (never a spinner). Do NOT make this trigger a run — a live run is
+    ~15s and showing a spinner over stale content reads as "stuck".
+  - Rendered in a **sandboxed iframe `srcdoc`** (`sandbox="allow-same-origin"`, scripts
+    disabled). The UI never builds the HTML; it relays exactly what the exec returned.
+  - **`Simulate` can't run an exec-data-carrying app**: stubs have no `result.<field>`, so the
+    cross-node templates (`{{ bom.result.html }}`) render undefined and the run aborts
+    (`template render: undefined value`, exit 3). `/api/run` returns that **in-band** (HTTP 200
+    `{ok:false}`) so the console stays clean and the UI explains it. Use `▶ Run app` for exec apps.
+- **Debug in VS** (HTML Viewer header) reproduces the desktop floless action. There is no
+  `aware exec` verb for ad-hoc code, so `POST /api/debug-node` injects
+  `System.Diagnostics.Debugger.Launch(); Debugger.Break();` (after the last `using` directive)
+  and sends the code **straight to the bridge** (`~/.aware/bridges/aware-tekla.exe`). The .NET
+  JIT picker pops; the user attaches Visual Studio to `aware-tekla.exe`. It debugs the
+  **decompiled** Roslyn submission, not source.
+
+## Server seams (where to make changes)
+
+- `server/aware-adapter.ts` — the **only** place that shells `aware` *and* the host bridge.
+  `run(id, {dryRun, simulate, inputs})` passes `--input k=v`; `execTekla(code, {version, args,
+  debug})` talks to the bridge directly (resolves `~/.aware/bridges`, injects the debugger when
+  `debug`). Nothing else touches raw `aware`/bridge argv. **`run()` serializes through a single
+  promise-chain run lock** — manual (UI) runs and scheduled (routine) runs share it, since the host
+  bridge does one exec at a time and `cancelActiveRun()` assumes a single active run.
+- `server/routines.ts` + `/api/routines` (in `index.ts`) — `.flo` runs on a trigger. Two `kind`s
+  share the store (`~/.floless/routines.json`) and the **⏱ Routines** panel:
+  - **`schedule`** — a time-trigger; the in-server scheduler fires due routines through
+    `aware.run()` (the shared run lock above). Carries a `schedule` + `nextFireAt`.
+  - **`trigger`** — an event-trigger of a streaming `lifecycle:start` source (e.g. `tekla.watch`).
+    A long-lived `aware app run` lives in `server/trigger-sessions.ts` **outside** the run lock; the
+    row renders a live `session` snapshot `{state:'listening'|'blocked'|'error'|'stopped',
+    firedCount, lastEvent, error}` pushed over the `trigger-session-changed` SSE event. The enabled
+    toggle = start/stop the session (not "arm a timer"); run-now is refused (the UI hides ▶). The
+    create body is `{kind:'trigger', name, workflow, inputs, enabled}` (no `schedule`) — eligibility
+    is `app.triggerSource != null` (computed by `app-reader.detectTriggerSource`); `createRoutine`
+    records the binding (`trigger:{nodeId,agent,command}`) from `app.triggerSource` so the row's
+    "On trigger · agent/command" descriptor survives a reload. v1 sets **no** source params (the
+    watch's `filter` etc. live in node config — see `references/dev-server-and-run-trace.md`).
+  Authoring path for the terminal AI = the `floless-app-routines` skill. Both kinds are still
+  thin-UI: an event-/time-trigger of `aware app run`, never composing a workflow or calling an LLM.
+- `server/app-reader.ts` — reads `~/.aware/apps/<id>/` off disk (the CLI's `app show` is
+  text-only). Parses the top-level `inputs:` block into `app.inputs`, exposes `node.config`
+  (incl. `code`), and computes the Run gate from the `.lock` source-hash. **Reconciles the exec
+  write-mode default** (issue #165): when the source declares `mode: read` and the lock defaulted
+  an `exec` node to `write`, it reports `read` and rewrites the cryptic compile note — so the
+  canvas isn't littered with false write-mode badges.
+- `server/index.ts` — routes. `/api/run` accepts `inputs` and returns `report` via
+  `extractReportHtml(events)` (scans the trace for `data.result.html`); it surfaces a user Stop
+  in-band as `{ cancelled:true }`. `/api/run/stop` → `cancelActiveRun()` (kills the in-flight
+  run's process tree). `/api/debug-node` resolves `{{ inputs.x }}` in `config.args` and dispatches
+  via `execTekla(..., {debug:true})`.
+
+## Keeping this skill current (self-learning)
+
+This skill is **self-learning**: it must improve every time a floless.app session surfaces a
+new, non-obvious fact. Treat the skill as the living memory of how floless.app works.
+
+At the end of any session that touched floless.app, before reporting done, ask: *did I learn
+something a future session would waste time rediscovering?* If yes, fold it in **now**:
+
+- A new AWARE constraint or footgun (e.g. "only inline predicate runs", "html-report has no
+  binary", a CLI arg quirk) → add it to the relevant section here or to `references/`.
+- A new exec-contract detail / Tekla API gotcha → `references/exec-contract.md`.
+- A new UI seam or pattern (a route, a render path, a token class) → the UI / server-seams
+  sections.
+- A corrected assumption → fix the stale text so the wrong version never resurfaces.
+
+How to update (do not hand-edit around the process):
+1. Route the change through the `skill-creator` skill (the project's standing rule —
+   `feedback_skill_creator_required.md`).
+2. Keep SKILL.md lean; push long detail into `references/`. Avoid duplicating a fact in both.
+3. Re-validate: `python <skill-creator>/scripts/quick_validate.py .claude/skills/floless-app-workflows`.
+4. Commit with the code it documents, or as a `docs(skill):` commit.
+
+Keep entries terse and concrete (the constraint + why + where), not prose. If a section grows
+past a few hard facts, split it into a `references/` file and link it.
+
+## Guardrails (do not drift)
+
+- Determinism is AWARE's: `<app>.lock` is the approved artifact; Run is gated on a fresh
+  source-hash. Never let the UI run on drift.
+- Any change under `web/` requires a Playwright pass (visual + interaction), not just a check of
+  the request body — see the project's standing rule.
+- When a real `aware`/bridge bug surfaces, file it on `aware-aeco/aware` (don't file your own
+  misuse).

package/dist/skills/floless-app-workflows/references/dev-server-and-run-trace.md

@@ -0,0 +1,119 @@
+# Dev server + run trace (verifying floless.app changes)
+
+Concrete, easily-rediscovered facts for verifying UI/server changes against a live host.
+
+## Running the dev server for verification
+
+The repo's TypeScript host serves `web/` and shells `aware`. To verify changes you run it
+on **port 4317** and drive it with Playwright (the standing real-E2E rule).
+
+- **Command:** `tsx main.ts --serve` from `server/` (this is the `start` script). The `dev`
+  script is `tsx watch …` (auto-reload) but the server is usually launched with **`start`
+  (NO watch)** — so **server TS edits (`index.ts`, `aware-adapter.ts`, `app-reader.ts`) need a
+  manual restart**; a 404 on a route you just added means the old process is still running.
+- **License env (the shared-dir trick) — REQUIRED:** the dev server's license dir
+  (`licensing.ts storeDir()`) defaults to `~/.aware`, which has **no token**, so without an
+  override the dev server is signed-out and the UI is gated. Start it with
+  `FLOLESS_LICENSE_DIR=%LOCALAPPDATA%\FlolessApp-data` (git-bash: `"$LOCALAPPDATA/FlolessApp-data"`)
+  so it shares the **installed SEA app's** token + `floless-install-id` (so no seat takeover —
+  single-session/newest-login-wins). Token lives at
+  `%LOCALAPPDATA%\FlolessApp-data\floless-license.json`.
+- **`web/` is served fresh from disk per request** — edits to `web/*.js|css|html` need only a
+  browser **reload**, no server restart. Only server TS needs a restart.
+- **Restart recipe (Windows):** find the listener (`netstat -ano | grep :4317`), get its tree
+  (`Get-CimInstance Win32_Process`), `taskkill //PID <tsx-pid> //T //F`, then relaunch
+  `FLOLESS_LICENSE_DIR="$LOCALAPPDATA/FlolessApp-data" npx tsx main.ts --serve` in the background.
+
+## The run trace (what `aware app run` emits)
+
+Verified event kinds in the JSONL trace (`~/.aware/logs/<id>/<instance>/<run>.jsonl`), in order:
+`run-start` → per node `node-start` then **`node-output`** → `run-end` (`status:"ok"|…`).
+
+- The completion kind is **`node-output`**, NOT `output`/`write` (those legacy kinds don't appear
+  from current aware — a `switch` that only cased `output`/`write` silently misclassifies them).
+- Each per-node event carries **`ev.node`** (the node id) + `ev.agent`/`ev.command`. Keep the raw
+  `node` on trace rows if anything downstream (e.g. the Execution-tab node filter) needs it.
+
+### The trace streams LIVE for report runs (non-obvious)
+
+floless watches `~/.aware/logs` and broadcasts a `trace-file` SSE event as the runtime writes the
+JSONL — replaying the file cumulatively. That branch is gated `!state.running`; a **report run
+sets `reportRunning` (NOT `state.running`)**, so the branch fires and per-node canvas status
+(running → done) lights up **in real time** behind the modal. Non-report/`simulate` runs set
+`state.running`, so they paint from the **batched** trace that `/api/run` broadcasts after the CLI
+returns. Either way, painting per-node status in `pushTrace` (in `web/aware.js`) covers both,
+plus terminal-driven runs.
+
+## Verification gotchas (driving the localhost API + Playwright on Windows)
+
+Two traps that waste time when verifying server changes against `http://127.0.0.1:4317`:
+
+- **Rapid-fire `curl` to the localhost API returns `000` (connection failed) for all but the last
+  call in a tight loop.** It's Windows ephemeral-port / TIME_WAIT pressure from many short-lived
+  connections, NOT a server bug (the route works — a single call returns 200). To drive the API in
+  bulk (seeding/cleanup), use ONE `python - <<'PY' … urllib.request …` process (keeps the work in
+  one process, no connection storm) or space `curl`s out. The browser's SSE/keepalive connection is
+  unaffected, so real UI verification is fine.
+- **Playwright MCP "Browser is already in use for …mcp-chrome…".** After a crash/disconnect the
+  MCP can't relaunch because an orphan Chrome still holds the profile. Recover: find the orphan
+  chrome (`Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | ? CommandLine -like
+  '*mcp-chrome*'`), `taskkill /PID <pid> /T /F` it (its parent is the active `@playwright/mcp`
+  node process), optionally delete a stale `%LOCALAPPDATA%\ms-playwright\<profile>\lockfile`, then
+  `browser_navigate` again — the MCP relaunches cleanly. The MCP browser can drop mid-session here;
+  re-attach with the same recipe and re-assert via a DOM probe (`browser_evaluate`).
+
+## Verifying "On trigger" (event-driven) routines without live Tekla
+
+The trigger-routine UI (the **⏱ Routines** panel's `trigger` kind) is real-E2E-verifiable on any
+machine via a `self_test:true` watch fixture — no Tekla, no `--simulate`:
+
+- **Fixture:** `demos/tekla-watch-smoke/` — one `tekla.watch` node with `config.self_test:true`
+  (+ `filter:welded` etc.) → the bridge emits one `listening` then **5 synthetic `fired` events**
+  through the real watch code path. Install/compile like any app (`aware app install ./demos/…`;
+  reinstall needs `aware app uninstall` first; compile from `~/.aware/apps`). The watch's `filter`
+  lives in **node config**, not top-level `inputs:`, so v1 trigger routines take no source params
+  (an eligible app with no `inputs:` renders zero input fields — fine).
+- **Eligibility:** `GET /api/app/:id` → `app.triggerSource` is non-null when the source node runs a
+  `lifecycle:start` + `stream` command. The Add/Edit form keys the schedule-vs-trigger chooser off
+  this; `tekla-watch-smoke` is eligible.
+- **Live row state to assert:** create `{kind:'trigger', workflow, inputs:{}, enabled:true}` → the
+  row's `.rtn-next` goes `listening` → (events) → ends `stopped` (self_test exits after 5; a real
+  never-ending watch stays `listening · N×`). `GET /api/routines` annotates each trigger routine
+  with `session:{state,firedCount,lastEvent,error}` and the persisted `trigger:{nodeId,agent,command}`
+  — assert `firedCount>=5` there (the label may have already settled to `stopped` by the time you
+  poll, so gate the pass on the **API** firedCount, not only the transient label).
+
+### Driving the licensed dev server + Playwright (what actually works here)
+
+- **The installed SEA server usually already holds :4317** (and it 404s `/api/status` — different
+  build). Don't fight it: `index.ts` honors `PORT`, so run the dev server on a free port —
+  `PORT=4318 FLOLESS_LICENSE_DIR="$LOCALAPPDATA/FlolessApp-data" npx tsx main.ts --serve` (from
+  `server/`, background). Without the license dir it serves the **sign-in gate** (no `#routines-btn`)
+  — assert `document.getElementById('routines-btn')` exists before driving the panel.
+- **The Playwright MCP browser is flaky/locked here** ("Browser is already in use…"). A **standalone
+  Node script is more reliable**: `playwright-core` resolves at
+  `C:/Users/Pawel/AppData/Roaming/npm/node_modules/@playwright/cli/node_modules/playwright-core`;
+  the registry's default `chrome-headless-shell` is often missing, so pass an explicit
+  `executablePath` to an installed chromium build under
+  `%LOCALAPPDATA%/ms-playwright/chromium-<rev>/chrome-win64/chrome.exe` (1217/1208 seen). Have the
+  script write a `report.txt` + screenshots and `process.exit(pass?0:1)`; **run it as a background
+  Bash task** — the run-tool's output buffer here lags badly, but the background-task *completion
+  notification* reliably flushes the result. **Exercise real clicks** (e.g. click both
+  `.rtn-mode-btn`s and assert the layout toggles) — a default-path-only run misses dead-control bugs
+  (an unwired chooser shipped exactly because the first pass relied on the auto-default).
+- **Footgun — a failing Bash command cancels its sibling tool calls in the same assistant turn.**
+  Don't batch an `Edit`/`Write` with a `grep -c`/`[ ]` test that can exit non-zero (it cancels the
+  edits). Append `; true` to verification one-liners, or isolate risky commands in their own turn.
+
+## Stop / cancel an in-flight run
+
+`aware app run` blocks; the escape hatch for a hung/unattached host:
+- `aware-adapter.ts` tracks the active run's child; `cancelActiveRun()` kills it. On Windows kill
+  the **whole tree** with `taskkill /pid <pid> /T /F` — `aware` spawns `node` → the host bridge,
+  so a bare `child.kill()` orphans the bridge.
+- `run()` throws a distinct `AwareError(..., { cancelled: true })` when killed; `/api/run` surfaces
+  it **in-band** (HTTP 200 `{ cancelled:true }`) so it reads as "cancelled", not a fault.
+- `POST /api/run/stop` → `cancelActiveRun()`. `api()` drops the `cancelled` flag (throws a bare
+  Error), so the UI keeps a local `cancelRequested` flag to render "Run cancelled" vs "Run failed",
+  and `pushTrace` stops painting the canvas once it's set (late fs-watcher events would otherwise
+  re-pulse a node "running" after the wipe).

package/dist/skills/floless-app-workflows/references/exec-contract.md

@@ -0,0 +1,104 @@
+# The tekla `exec` contract (Roslyn C# against the live model)
+
+The `tekla` agent's `exec` command runs a C# **script** (Roslyn scripting, not a full program)
+inside the host bridge `aware-tekla.exe`, which is connected to a running Tekla Structures
+instance with a model open. Reference impl: `demos/tekla-bom-by-phase/bom-by-phase.exec.cs`.
+
+## Globals injected into the script
+
+| Global | Type | Notes |
+|---|---|---|
+| `model` | `dynamic` (`Tekla.Structures.Model.Model`) | `null` if no live model — guard it. |
+| `args` | `IDictionary<string, object?>` | The node's `config.args` block, JSON-decoded. |
+
+`args` values are JSON-typed by the bridge: a JSON number arrives as `int`/`long`/`double`, a
+string as `string`, etc. **Read defensively** — a templated `{{ inputs.phase }}` may arrive as a
+number or a string depending on how it was supplied:
+
+```csharp
+int phase = 1;
+if (args != null && args.TryGetValue("phase", out var pv) && pv != null) {
+    if (pv is int pi) phase = pi;
+    else if (pv is long pl) phase = (int)pl;
+    else if (pv is double pd) phase = (int)pd;
+    else { int.TryParse(pv.ToString(), out var ps); if (ps != 0) phase = ps; }
+}
+```
+
+## Return value
+
+End the script with `return <object>;`. The bridge serializes it and wraps it under `result`:
+
+```json
+{ "ok": true, "result": { "ok": true, "phase": 2, "html": "<!doctype html>…" },
+  "host": "tekla", "host_version": "2025.0", "host_pid": 47016 }
+```
+
+For a report node, return the HTML **inline**:
+`return new { ok = true, phase, html = sb.ToString(), modelName, totalParts, … };`
+floless extracts `data.result.html` for the HTML Viewer.
+
+## References available / NOT available
+
+- **Available:** `System`, `System.Collections.Generic`, `System.Linq`, `System.Text`,
+  `System.IO`, `System.Diagnostics.Debugger`, and the Tekla Open API
+  (`Tekla.Structures.Model`, etc. — discovered/probed from the running install).
+- **NOT referenced:** `System.Net` (so **no** `WebUtility.HtmlEncode` — escape manually),
+  `System.Diagnostics.Process`. Don't rely on them.
+
+Manual HTML escape (since `System.Net` is unavailable):
+
+```csharp
+Func<string,string> E = s => (s ?? "")
+    .Replace("&","&amp;").Replace("<","&lt;").Replace(">","&gt;").Replace("\"","&quot;");
+```
+
+## Enumerating + filtering parts
+
+Use the selector and filter with `as Part` (there is no `GetAllObjectsWithType(typeof(Part))`
+overload that takes a `Type` — that's a CS1503; `GetAllObjects()` + `as Part` is the way):
+
+```csharp
+var en = ((Model)model).GetModelObjectSelector().GetAllObjects();
+while (en.MoveNext()) {
+    var part = en.Current as Part; if (part == null) continue;
+    Phase ph = null; try { part.GetPhase(out ph); } catch { ph = null; }
+    if (ph == null || ph.PhaseNumber != phase) continue;     // phase filter
+    string name = "";    part.GetReportProperty("NAME", ref name);     // BEAM/COLUMN/PLATE/…
+    string profile = ""; part.GetReportProperty("PROFILE", ref profile);
+    string material = "";part.GetReportProperty("MATERIAL", ref material);
+    double w = 0;        part.GetReportProperty("WEIGHT", ref w);
+    double l = 0;        part.GetReportProperty("LENGTH", ref l);
+    // aggregate: category(NAME) → "profile|material" → {qty,weight,length}
+}
+string modelName; try { modelName = ((Model)model).GetInfo().ModelName; } catch { modelName = "Tekla model"; }
+```
+
+**Categorize by `NAME`, not the .NET class.** The .NET class (`Beam`, `ContourPlate`,
+`PolyBeam`) lumps beams + columns together; the report property `NAME` carries the detailer's
+intent (`BEAM`, `COLUMN`, `CHANNEL`, `EMBED PLATE`, `ANGLE`, `PLATE`, `STIFF. PLATE`, …), which
+is what users want grouped. Group by `NAME` (category) then by `profile|material` within each.
+
+## Verifying against a live model (direct bridge call)
+
+To test exec C# without the full app runtime, send it straight to the bridge over its
+JSON-stdin contract:
+
+```bash
+BIN="C:/Users/Pawel/.aware/bridges/aware-tekla.exe"   # post-#148 persistent location
+python -c "import json,io; print(json.dumps({'code': io.open('x.cs',encoding='utf-8').read(), 'args':{'phase':2}}))" \
+  | "$BIN" exec --version 2025.0 --json-stdin
+```
+
+The bridge reads `version`, `code`, and `args` from the stdin JSON (or `--version` flag). One
+instance serves one model; if the bridge is busy (e.g. a debug session holding it), wait for it
+to free.
+
+## Gotchas observed
+
+- A model may have **no phase 1** (College Desert has phases 2 and 3001). A `default: 1` that
+  returns an empty report is correct behavior — the user changes the phase per model. Always
+  render an empty-state message rather than failing.
+- `GetReportProperty` returns by `ref`; initialize the target first (`string x = "";`).
+- The bridge commits changes only when the script wrote and the connection is live; pure-read
+  scripts (like BOM) need no `safety:` block. Write-mode nodes do (`*.create`, `*.update`, …).