@floless/app 0.5.1

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

@@ -0,0 +1,80 @@
+---
+name: floless-app-bridge
+description: This skill should be used when the user is driving the floless.app web UI (the local prompt-native front door at http://127.0.0.1:4317) and wants the terminal AI to act on what they did there — picking up queued Tweak requests, "use this template" requests, or the context of a node they selected/edited on the canvas. Use it when the user says things like "apply the tweak I just queued", "I clicked Tweak on the bom node — make that change", "pick up my floless request", "what's pending in floless", or after they double-click/Tweak a node in the UI. It reads the floless.app local API, applies the change to the app's .flo, recompiles, and clears the request.
+metadata:
+  version: 0.1.0
+---
+
+# floless.app ↔ terminal bridge
+
+floless.app is the **thin web UI**; the **terminal AI (you) is the brain**. The UI cannot
+edit `.flo` files or push into this terminal — instead it **queues requests** to a local API,
+and you **pull** them here, do the real work (edit the `.flo`, recompile), and clear them. This
+skill is that pull side. Pair it with the **`floless-app-workflows`** skill, which owns
+the actual `.flo` authoring / install → compile → run loop.
+
+## The local API (http://127.0.0.1:4317)
+
+The floless.app server runs locally on a **fixed port 4317** (override: `$PORT`). Confirm it's up
+first: `curl -s http://127.0.0.1:4317/api/health` → `{"ok":true,"awareVersion":"…"}`. If it's not
+running, the user starts it from the repo: `cd server && npm run dev` (or `npm run app`).
+
+| Call | Purpose |
+|---|---|
+| `GET /api/requests` | List pending UI requests → `{ ok, requests: [...] }` |
+| `DELETE /api/requests/:id` | **Clear** a request once you've handled it |
+| `GET /api/app/:id` | The app's normalized topology + source + lock (selected-node context) |
+| `POST /api/tweak` | (UI uses this to enqueue; you usually only read/clear) |
+
+### Request shapes (`/api/requests`)
+
+```jsonc
+// A node Tweak (the ✎ Tweak button): change ONE node in plain English.
+{ "id": "uuid", "type": "tweak", "status": "pending",
+  "appId": "tekla-bom-by-phase", "nodeId": "bom",
+  "instruction": "also group by ASSEMBLY_POS and add a per-assembly subtotal" }
+
+// A "use this template" request (a favorite dragged in / "Use in this app").
+{ "id": "uuid", "type": "use-template", "status": "pending",
+  "appId": "tekla-bom-by-phase", "templateId": "uuid",
+  "template": { "name": "…", "node": { "agent": "tekla", "command": "…", "config": {…} } } }
+```
+
+The **selected-node context** you need is carried *in the request* (`appId` + `nodeId`), so you do
+not need the UI's live selection — read that node's current source from the `.flo` to understand
+what to change.
+
+## Workflow — pull, apply, clear
+
+```dot
+digraph { "GET /api/requests" -> "for each pending" -> "read app .flo + node" ->
+  "apply change (edit .flo)" -> "recompile + reinstall" -> "DELETE /api/requests/:id" }
+```
+
+1. **Pull**: `curl -s http://127.0.0.1:4317/api/requests` → take the `pending` ones (oldest first).
+   Summarize them for the user before acting on anything destructive.
+2. **Locate the app source.** The editable `.flo` is the repo copy `demos/<appId>/<appId>.flo`
+   (preferred — it's version-controlled); the installed copy is `~/.aware/apps/<appId>/<appId>.flo`.
+   Edit the **repo** copy. `GET /api/app/<appId>` returns the parsed nodes + each node's
+   `config` (incl. the exec `code`) if you want the resolved view.
+3. **Apply the change** to the target `nodeId`:
+   - `type: tweak` → edit that node's `config.code` (exec C#) or `config.args` per the plain-English
+     `instruction`. Keep the node's contract (id, mode, edges) intact unless the instruction says
+     otherwise.
+   - `type: use-template` → add `template.node` as a new node and wire it in (see
+     `floless-app-workflows` for node/connection rules).
+4. **Recompile** so the UI's Run gate re-arms (it's gated on the lock's source-hash):
+   reinstall from the dir + `aware app compile <appId>` from `~/.aware/apps` (full loop +
+   gotchas live in `floless-app-workflows`).
+5. **Clear the request** so it leaves the UI's queue:
+   `curl -s -X DELETE http://127.0.0.1:4317/api/requests/<id>`. The UI's "requests" badge updates
+   live over SSE.
+6. **Verify** with a real run (the `verify`/Playwright standing rule) before reporting done.
+
+## Guardrails
+
+- **You are the brain, the UI is not.** Never ask the UI to compose or mutate the `.flo`; it only
+  queues intent. All authoring happens here, through the `.flo` + `aware` CLI.
+- Edit the **repo** `demos/<appId>/` source (tracked), then recompile into `~/.aware/apps/`.
+- Always **clear** a request after handling it, so the user's "requests" count reflects reality.
+- Don't invent node/command names — verify against the app's existing nodes (`GET /api/app/:id`).

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

@@ -0,0 +1,168 @@
+---
+name: floless-app-routines
+description: This skill should be used when the user wants to set up a floless.app workflow (.flo app) to run automatically — "routines" — either on a timer (schedule) or on a live event (trigger). Triggers on requests like "schedule tekla-bom-by-phase every weekday at 7am", "run this workflow every 2 hours", "run my BOM whenever the Tekla model changes", "watch the model and run X on each change", "set up a trigger routine", "list my routines", "disable the morning routine", "delete that routine". Covers the floless.app routines REST API (create / list / edit / enable-disable / delete / run-now), the schedule presets, the event-trigger kind, the confirm-first rule, and the runnable gate.
+metadata:
+  version: 0.1.0
+---
+
+# Setting up floless.app routines (automatic .flo runs)
+
+A **routine** runs an installed AWARE workflow (`.flo` app) automatically — the hands-off
+equivalent of clicking ▶ Run workflow in floless.app. There are two **kinds**, both authored
+through the same **`/api/routines`** REST surface:
+
+- **`schedule`** — a **time-trigger**: the floless.app server's internal scheduler fires the
+  workflow on a clock (every weekday at 7am, every 2 hours, …).
+- **`trigger`** — an **event-trigger**: a workflow whose source node is a *streaming*
+  `lifecycle:start` command (e.g. `tekla.watch`) runs once per emitted event. The server hosts a
+  long-lived `aware app run`; each change to the watched host (e.g. the Tekla model) fires the
+  chain. Only workflows that declare such a source are eligible.
+
+The floless.app server is a thin localhost host on **port 4317**. Both kinds serialize host work
+through the same run lock, and the server records/streams state. This skill drives that server so
+the terminal AI can author routines on the user's behalf.
+
+floless.app owns no engine: a routine is just a time- or event-trigger of `aware app run`. This
+skill never composes a workflow — it sets up automation for one that already exists.
+
+## When to use
+
+Use this skill when the user asks to **schedule / time / automate / trigger / watch-and-run** an
+existing floless.app workflow, or to manage existing routines (list, edit, enable/disable, delete,
+run now). Do **not** use it to build or edit a workflow itself — that is
+`floless-app-workflows`.
+
+**Which kind?** If the user names a clock ("at 7am", "every 2 hours", "daily") → **schedule**. If
+they describe an event ("whenever the model changes", "on each change", "watch X and run") →
+**trigger** — but a trigger only works if the workflow is trigger-eligible (see the trigger
+workflow below); if it isn't, say so and offer a schedule instead. When unsure, ask.
+
+## The base URL + preflight
+
+The server is at **`http://127.0.0.1:4317`** (the fixed floless.app port). Call it from the
+terminal with `curl` (a non-browser caller sends no `Origin`, which the server's cross-origin
+guard allows).
+
+Before any routine call, confirm the server is up and licensed:
+
+```bash
+curl -s http://127.0.0.1:4317/api/health
+# → {"ok":true,"license":"valid",...}.  If it doesn't respond, the floless.app desktop app
+#   isn't running — ask the user to start it. If license != valid/offline-grace, /api/routines
+#   returns 402; the user must sign in (the app surfaces a sign-in gate).
+```
+
+## The SCHEDULE workflow (always, in order)
+
+1. **Resolve + verify the workflow.** List installed apps and confirm the target exists:
+   `curl -s http://127.0.0.1:4317/api/apps`. Then confirm it is **runnable** (compiled, fresh
+   lock) — only runnable apps fire cleanly:
+   `curl -s http://127.0.0.1:4317/api/app/<id>` → check `app.runnable === true`. If it is not
+   runnable, tell the user it needs Compile first (don't schedule a broken app — the scheduler
+   would just record `skipped`).
+2. **Map the request to a structured schedule — never invent one.** The user says
+   "every weekday at 7am"; translate it to a `ScheduleSpec` (see below). If anything is ambiguous
+   (which days? what time? what inputs?), **ask before creating it.** Echo the parsed schedule and
+   inputs back in plain English ("Weekdays at 07:00, phase 3 — create this?") and wait for a yes.
+3. **Coerce inputs against the app's declared inputs.** Read `app.inputs` from
+   `/api/app/<id>`; pass only declared inputs, with the values the user gave (or omit one to use
+   the app's default). The server coerces values + drops unknown keys, but pass clean values.
+4. **Create it.** `POST /api/routines` with `{ name, workflow, schedule, inputs?, enabled? }` (see
+   the API reference). On success the routine appears live in the floless.app Routines panel (the
+   server broadcasts over SSE).
+5. **Confirm back to the user** what was scheduled and when it next fires (`routine.nextFireAt`).
+
+## The TRIGGER workflow (event-driven — always, in order)
+
+1. **Resolve + verify the workflow is trigger-eligible.** `curl -s http://127.0.0.1:4317/api/app/<id>`
+   and check **`app.triggerSource`** — it must be non-null (`{ nodeId, agent, command, inputs }`).
+   Null means the workflow has no streaming `lifecycle:start` source and **cannot** be a trigger
+   routine — tell the user, and offer a schedule instead. Also confirm `app.runnable === true`
+   (a not-runnable app starts `blocked` — needs Compile).
+2. **Confirm — never invent.** Echo back, in plain English, what will be watched and what runs
+   ("Run `tekla-bom-by-phase` whenever the Tekla model changes (tekla/watch) — set this up?") and
+   wait for a yes. **Source params are not settable in v1** (the watch's `filter` etc. live in the
+   workflow's node config, not as routine inputs) — don't promise to set them; if the user needs a
+   different filter, that's a workflow edit (`floless-app-workflows`), not a routine knob.
+3. **Coerce inputs** the same way as a schedule (only the app's declared top-level `inputs`). Many
+   watch apps declare none — then omit `inputs`.
+4. **Create it.** `POST /api/routines` with **`{ kind:"trigger", name, workflow, inputs?, enabled? }`**
+   — **no `schedule`**. The server validates eligibility (re-checks `app.triggerSource`), records the
+   source binding, and — if `enabled` — starts the live watcher session immediately.
+5. **Confirm back to the user.** A trigger routine has **no `nextFireAt`**; instead report its live
+   state from `routine.session` (`{ state, firedCount, lastEvent, error }`) — e.g. "Listening now;
+   it'll run on each change." Enable/disable is the control; **run-now does not apply** (the API
+   rejects it — see gotchas).
+
+## Schedule presets (structured, NOT cron)
+
+Pick exactly one shape. Times are **local machine time**, `HH:MM` 24-hour. The finest granularity
+is **hourly** by design (no sub-hour schedules).
+
+| User intent | ScheduleSpec |
+|---|---|
+| "every 2 hours" | `{"kind":"hourly","everyHours":2}` (must divide 24: 1, 2, 3, 4, 6, 8, 12, 24) |
+| "every day at 7am" | `{"kind":"daily","time":"07:00"}` |
+| "every weekday at 7am" | `{"kind":"weekdays","time":"07:00"}` (Mon–Fri) |
+| "Mondays and Thursdays at 7am" | `{"kind":"weekly","days":["mon","thu"],"time":"07:00"}` |
+| anything a preset can't express | `{"kind":"cron","expr":"0 4 * * 1"}` (5-field; local time) |
+
+Weekday tokens: `sun mon tue wed thu fri sat`.
+
+**Cron** is the "Custom" escape hatch — a standard 5-field expression
+(`min hour day-of-month month day-of-week`, e.g. `*/15 9-17 * * 1-5` = every 15 min,
+9am–5pm, weekdays). Prefer a preset when one fits (more readable); reach for cron only
+when none does. Granularity is bounded by the ~1-minute scheduler tick.
+
+## Quick examples
+
+```bash
+# Create a SCHEDULE: BOM every weekday at 07:00, phase 3
+curl -s -X POST http://127.0.0.1:4317/api/routines -H 'content-type: application/json' -d '{
+  "name":"Morning BOM export","workflow":"tekla-bom-by-phase",
+  "schedule":{"kind":"weekdays","time":"07:00"},"inputs":{"phase":3}}'
+
+# Create a TRIGGER: run a watch workflow on every model change (no schedule)
+curl -s -X POST http://127.0.0.1:4317/api/routines -H 'content-type: application/json' -d '{
+  "kind":"trigger","name":"Watch model","workflow":"tekla-watch-smoke","enabled":true}'
+
+# List (trigger routines carry a live `session`; schedule routines carry `nextFireAt`)
+curl -s http://127.0.0.1:4317/api/routines
+
+# Disable (or re-enable) — for a TRIGGER this STOPS / STARTS the live watcher
+curl -s -X PATCH http://127.0.0.1:4317/api/routines/<id> -H 'content-type: application/json' -d '{"enabled":false}'
+
+# Change a schedule's timing — PATCH only the fields that change (schedule kind only)
+curl -s -X PATCH http://127.0.0.1:4317/api/routines/<id> -H 'content-type: application/json' -d '{"schedule":{"kind":"daily","time":"06:30"}}'
+
+# Run now — SCHEDULE kind only (a trigger 400s: its control is enable/disable)
+curl -s -X POST http://127.0.0.1:4317/api/routines/<id>/run
+
+# Delete (a trigger's live watcher is stopped first)
+curl -s -X DELETE http://127.0.0.1:4317/api/routines/<id>
+```
+
+## Rules + gotchas
+
+- **Confirm before create.** Never invent a schedule, a trigger, or inputs; echo the parse and get
+  a yes. For a trigger, confirm the workflow is eligible (`app.triggerSource != null`) first.
+- **Cap is 15** routines per install (both kinds share the cap). The 16th `POST` returns **409**
+  with a clear message — relay it and offer to delete one.
+- **Workflow is fixed after create** (both kinds). `PATCH` cannot change a routine's workflow or its
+  `kind`. To switch workflows or convert schedule↔trigger, delete and recreate.
+- **Run-now is schedule-only.** `POST /api/routines/:id/run` on a trigger returns **400**
+  ("a trigger routine runs on its event — enable/disable it instead"). Don't offer run-now for a
+  trigger; the control is the enable/disable toggle (start/stop the live watcher).
+- **The server runs it, not Claude.** Once created, floless.app runs the routine locally — the
+  scheduler fires a schedule on its timer; a trigger's long-lived watcher runs as long as it's
+  enabled and the desktop app is up. A host-unavailable schedule fire records an honest `failed`
+  run; a trigger that can't start (uncompiled/drift, or a host-exclusivity conflict) reports
+  `session.state:"blocked"` with a reason. No AI interpretation of results in Phase 1.
+- **Host exclusivity (trigger).** A host-backed watcher (e.g. Tekla) and a manual/scheduled host run
+  are mutually exclusive — one live model, one consumer. Starting one while the other is live is
+  refused with a clear reason (surfaced as `blocked`). Generic/cloud sources are unconstrained.
+- **One seam, no drift.** This skill and the in-app Routines panel both write through
+  `/api/routines`, so validation, eligibility, and the cap apply identically.
+
+See `references/routines-api.md` for the full request/response shapes, both `Routine` kinds, the
+trigger `session` snapshot, run records, and error statuses.

package/dist/skills/floless-app-routines/references/routines-api.md

@@ -0,0 +1,130 @@
+# floless.app routines REST API
+
+Base URL: `http://127.0.0.1:4317`. All bodies are JSON (`content-type: application/json`).
+Every `/api/*` route requires a valid subscription (else `402`); the floless.app desktop app holds
+the token. A non-browser caller (curl) sends no `Origin`, so the cross-origin guard allows it.
+
+## The `Routine` object
+
+A routine is one of two **kinds**. `schedule` carries a `schedule` + `nextFireAt`; `trigger` carries
+a `trigger` binding and, in `GET /api/routines`, a live `session` snapshot (no `schedule`/`nextFireAt`).
+
+```jsonc
+// kind: "schedule" — a time-trigger
+{
+  "id": "morning-bom-export",          // slug, generated from the name (unique)
+  "name": "Morning BOM export",
+  "kind": "schedule",                  // "schedule" | "trigger" (defaults to schedule if omitted)
+  "workflow": "tekla-bom-by-phase",    // installed app id (immutable after create)
+  "inputs": { "phase": 3 },            // coerced to the app's declared input types
+  "schedule": { "kind": "weekdays", "time": "07:00" },
+  "enabled": true,
+  "created": "2026-05-28T14:54:03.859Z",
+  "updated": "2026-05-28T14:54:03.859Z",
+  "nextFireAt": "2026-05-29T05:00:00.000Z", // computed (UTC ISO); null when disabled/broken/trigger
+  "lastRun": { "at": "...", "status": "ok", "runId": "...", "durationMs": 42551 },
+  "history": [ /* most-recent 20 RunRecords */ ],
+  "broken": { "reason": "workflow not installed" }, // present only when the app is gone
+  "onResult": null                     // PHASE-2 reserved (AI handoff) — ignore in Phase 1
+}
+
+// kind: "trigger" — an event-trigger (streaming lifecycle:start source)
+{
+  "id": "watch-model",
+  "name": "Watch model",
+  "kind": "trigger",
+  "workflow": "tekla-watch-smoke",
+  "inputs": {},                        // app's declared top-level inputs only (often none)
+  "trigger": { "nodeId": "watch", "agent": "tekla", "command": "watch" }, // the streaming source
+  "enabled": true,
+  "created": "…", "updated": "…",
+  "nextFireAt": null,                  // always null for triggers (no clock)
+  "session": {                         // LIVE state — present in GET /api/routines only
+    "state": "listening",              // "listening" | "blocked" | "error" | "stopped"
+    "firedCount": 5,                   // events seen this session
+    "lastEvent": { "at": "ISO", "summary": "Beam modified · B/4" }, // newest fire, or null
+    "error": null                      // stderr tail when state==="error"/"blocked", else null
+  },
+  "lastRun": null, "history": [],
+  "broken": { "reason": "workflow not installed" }, // app gone / no longer trigger-eligible
+  "onResult": null
+}
+```
+
+### Trigger `session` states (live, server-pushed)
+
+- **`listening`** — the watcher process is up and watching; the healthy steady state. Each event
+  increments `firedCount` and updates `lastEvent`.
+- **`blocked`** — couldn't start: app not runnable (needs Compile / drift), or a host-exclusivity
+  refusal (a Tekla watcher and a manual/scheduled Tekla run can't both be live). `error` carries why.
+- **`error`** — the watcher exited non-zero; `error` carries the stderr tail. Re-enable to retry
+  (no auto-restart, to avoid flapping).
+- **`stopped`** — not running (disabled, or a finite stream ended). Enable to (re)start.
+
+### `ScheduleSpec` (structured presets, local machine time)
+
+```ts
+{ kind: "hourly",   everyHours: number }            // must evenly divide 24: 1,2,3,4,6,8,12,24
+{ kind: "daily",    time: "HH:MM" }
+{ kind: "weekdays", time: "HH:MM" }                 // Mon–Fri
+{ kind: "weekly",   days: Weekday[], time: "HH:MM" } // Weekday = sun|mon|tue|wed|thu|fri|sat
+{ kind: "cron",     expr: string }                  // standard 5-field: min hour dom month dow
+```
+
+`cron` is the "Custom" power-user variant (e.g. `"0 4 * * 1"` = Mondays 04:00,
+`"*/15 9-17 * * 1-5"` = every 15 min 9–5 on weekdays). Local time; granularity is
+bounded by the ~1-minute scheduler tick. Supports `* , - /` and lists.
+
+### `RunRecord`
+
+```jsonc
+{ "at": "ISO", "status": "ok" | "failed" | "skipped", "reason": "…?", "runId": "…?", "durationMs": 0 }
+```
+- `ok` — the run completed and no node reported failure.
+- `failed` — `aware app run` errored, or a node returned `{ ok:false }` (e.g. "No live Tekla model").
+- `skipped` — the app was not runnable at fire time (needs Compile / drift).
+
+## Endpoints
+
+| Method | Path | Body | Result |
+|---|---|---|---|
+| GET | `/api/routines` | — | `{ ok, routines: Routine[], max: 15 }` (trigger routines include a live `session`) |
+| POST | `/api/routines` | schedule: `{ name, workflow, schedule, inputs?, enabled? }` · trigger: `{ kind:"trigger", name, workflow, inputs?, enabled? }` | `201 { ok, routine }` · `400` invalid/ineligible · `409` at cap |
+| PATCH | `/api/routines/:id` | any of `{ name, schedule, inputs, enabled }` (a trigger ignores `schedule`; `enabled` start/stops its watcher) | `{ ok, routine }` · `404` · `400` |
+| DELETE | `/api/routines/:id` | — | `{ ok }` · `404` (stops the watcher first for a trigger) |
+| POST | `/api/routines/:id/run` | — | `{ ok }` (schedule: enqueues a real run now) · `400` for a **trigger** · `404` |
+
+Supporting reads (same server):
+- `GET /api/health` → `{ ok, license, ... }` — preflight.
+- `GET /api/apps` → `{ ok, apps: [{ id, nodes, layout, provider }] }` — does the workflow exist?
+- `GET /api/app/:id` → `{ ok, app }` — `app.runnable` (compiled+fresh) and `app.inputs`
+  (`[{ name, type, default, description }]`) to seed/validate routine inputs, **plus
+  `app.triggerSource`** (`{ nodeId, agent, command, inputs } | null`) — non-null = trigger-eligible.
+
+## Error statuses
+
+- `400` — validation: missing name, unknown/invalid workflow id, malformed schedule
+  (bad `HH:MM`, empty weekly `days`, `everyHours` not a divisor of 24); a `kind:"trigger"` create
+  on a workflow that is **not trigger-eligible** (`{ "error": "workflow is not trigger-eligible …" }`);
+  or `POST /:id/run` on a **trigger** (`{ "error": "a trigger routine runs on its event — enable/disable it instead" }`).
+- `402` — no valid subscription (the app must be signed in).
+- `404` — no routine with that id.
+- `409` — `{ "error": "Routine limit reached (15). Delete one first." }` — the cap (both kinds share
+  it). Relay it and offer to delete an existing routine.
+
+## Notes on behavior (so expectations are right)
+
+- **Local time, DST-safe.** Schedules are wall-clock local; 07:00 stays 07:00 across a DST change.
+- **Missed fires skip forward.** If the server was down at fire time, the next fire is the next
+  future occurrence (no catch-up burst on boot).
+- **Serialized.** Scheduled runs share the single active-run lock with manual ▶ Run; a fire that
+  coincides with another run waits its turn (the host bridge does one exec at a time).
+- **Inputs.** Only the app's declared inputs are kept, coerced to their declared type; omit an
+  input to use the app's default. Keys are validated `[A-Za-z0-9._-]`.
+- **Triggers (event-driven).** A `kind:"trigger"` routine hosts a long-lived `aware app run` of a
+  streaming `lifecycle:start` source (outside the schedule run-lock); `enabled` start/stops that
+  watcher. State is **ephemeral** — `session` is recomputed live (server restart re-derives it) and
+  pushed over the `trigger-session-changed` SSE event. **v1 sets no source params**: the watch's
+  `filter` etc. live in the workflow's node config, not as routine inputs — to change them, edit the
+  workflow (`floless-app-workflows`), not the routine. A host-backed watcher is mutually
+  exclusive with manual/scheduled host runs (one live model = one consumer).