skillscript-runtime 0.19.7 → 0.19.9

package/docs/language-reference.md

@@ -18,12 +18,9 @@ These are features designed or anticipated but not yet implemented in the curren
 
 - **Array aggregation primitives** — `|max`, `|min`, `|sum`, `|reduce` over arrays. Today the language tops out at "shape one record" — aggregating across an array requires `foreach` accumulator ceremony. Planned as a design question: is `foreach` the deliberate ceiling for aggregation, or do we add primitives?
 
-## Triggers (parse-clean today, don't fire — no event-bus surface yet)
+## Triggers — note
 
-- `event:` — generic event-bus subscription
-- `agent-event:` — agent-emitted events
-- `file-watch:` — filesystem change events
-- `sensor:` — continuous sensor channels
+Trigger sources are `cron` + `event` only (see the Triggers section). There is no separate `agent-event:` / `file-watch:` / `sensor:` trigger source — anything that isn't time-based is an external adapter that POSTs to the `/event` ingress. So there's nothing pending here on the trigger axis; the entry remains only to point readers who expect those sources at the adapter-POST pattern.
 
 ## Synchronous agent exchange
 
@@ -48,7 +45,9 @@ $set NAME = value scope=session
 
 Scopes: skill-local (persists across fires of this skill, not visible to other skills), agent-global (visible to all skills of the same agent), session (alive for the duration of the current session, cleared at session end). Backed by a configured data-records connector.
 
-## Sensors as a language category
+## Sensors as a read-channel category
+
+> `sensor:` is not a trigger source — to fire a skill on a sensor signal, a sensor adapter POSTs to `/event` (see Triggers). The concept below is the separate *read-channel* idea — continuous values an agent reads, distinct from triggering — which remains a future possibility if demand surfaces.
 
 Distinct from triggers. Sensors are continuous channels the agent reads but doesn't emit on. Planned syntax:
 
@@ -72,7 +71,7 @@ Most "right time" reasoning is relative, not wall-clock.
 
 ## Other planned
 
-- **Absence-as-trigger** — `# Triggers: idle: 5m` fire-on-quiet primitive
+- **Absence-as-trigger** — `# Triggers: idle: 5m` fire-on-quiet primitive (would be a new trigger source beyond `cron`|`event`, or an adapter that POSTs on a timer)
 - **Time-windowed aggregation** — filter-like primitives across firings (e.g., "user has shown frustration in 3 of 5 recent turns")
 - **Debounce / rate-limit / coalesce** — declarative queueing policy headers
 - **Suppression as valid output** — explicit "fire-and-suppress" (different from `# Output: none`)
@@ -95,35 +94,37 @@ Skillscript is a constrained domain-specific language for authoring agent workfl
 
 Every skill follows the same shape:
 
-1. **Trigger** — what fires the skill: cron, command, session-start, agent-event, file-watch, webhook, etc.
+1. **Trigger** — what fires the skill autonomously: `cron` (time-based) or `event` (an external HTTP POST to the runtime's `/event` ingress). (A skill can also be invoked explicitly — by an agent mid-conversation or via the execute API — with no trigger at all.)
 2. **Process** — pull data (MCP / data store / file), classify or compose via sub-LLM + iteration, build the deliverable.
-3. **Deliver** — emit the result via one or more delivery channels (see below).
+3. **Deliver** — produce the result via the **body-text output template** (declarative — the skill body *is* the output) or via `emit()` (imperative, for dynamic output), then route it through one or more delivery channels (see below; production detail in Output).
 
 Skillscript's job is to express this pipeline declaratively. When there is an agent above the skill, the agent's job is to act on the delivered artifact. When there isn't (autonomous fires), the delivery channel IS the outcome.
 
 **Declarative DAG, not imperative script.** A skillscript declares targets and their dependencies (`needs:` keyword); the interpreter topologically sorts and executes them in dependency order. Write blocks in any order — the runtime walks the graph.
 
-**Goal-directed, not entry-point-directed.** The `default:` declaration names the *goal target* — the terminal node whose result is the skill's output. The runtime walks dependencies backward from the goal through the topo-sort. A skill with a single target obscures this (goal == entry trivially); skills with multi-target DAGs make the shape visible.
+**Goal-directed, not entry-point-directed.** The `default:` declaration names the *goal target* — the terminal node whose result is the skill's output. The runtime walks dependencies backward from the goal through the topo-sort. A skill with a single target obscures this (goal == entry trivially); skills with multi-target DAGs make the shape visible. (A skill with *no* target is also valid — a body-template-only skill; see Output.)
 
 ## Two execution paths
 
-**Runtime-mediated** — the interpreter walks ops and dispatches them directly through configured connectors. Used for autonomous fires (cron, session-triggered, event-triggered). Safety boundary is the connector config + per-op gating (see Ops Reference).
+**Runtime-mediated** — the interpreter walks ops and dispatches them directly through configured connectors. Used for autonomous fires (cron- or event-triggered). Safety boundary is the connector config + per-op gating (see Ops Reference).
 
 **Agent-mediated** — the compiler renders the skill as a prompt; an agent reads the prompt and executes ops through its own tools. Used when an agent invokes a skill mid-conversation. Safety boundary is the agent's harness tool permissions.
 
 The language is identical in both paths. The execution model is a deployment-time + invocation-time decision.
 
-## Three delivery channels
+## Output production and delivery channels
+
+**Production:** a skill's output is produced either declaratively by the **body-text template** (the skill body, with `${var}` interpolation — the clean default for fixed-shape output) or imperatively by **`emit()`** (for variable-cardinality / conditional-shape / transcript output). See Output for the when-which rule. The template, when present, is the canonical output; `emit` feeds the transcript.
 
-A skill delivers its work via one or more of three channels. Delivery channel is not a property of skill type — it's just which ops a skill ends with.
+**Delivery:** the produced output is routed by the `# Output:` kind to one or more channels. Delivery channel is not a property of skill type — it's just the `# Output:` declaration.
 
-| Channel | Op | When you'd use it |
+| Channel | Declaration | When you'd use it |
 |---|---|---|
-| **Augmenting (context to agent)** | `emit(text="...")` + `# Output: agent: <name>` | Skill output is augment-kind payload for the receiving agent's next turn; joined emit stream becomes the delivered context. Pattern: agent-augmenting skills (briefing skills, session-start prepared context). |
-| **Template (playbook to agent)** | `emit(text="...")` + `# Output: template: <name>` | Skill output is a template-kind payload (recipe/playbook) the receiving agent executes. Pattern: instructional skills, reusable recipes. |
+| **Augmenting (context to agent)** | body template or `emit()` + `# Output: agent: <name>` | Output is augment-kind payload for the receiving agent's next turn. Pattern: agent-augmenting skills (briefings, session-start prepared context). |
+| **Template (playbook to agent)** | body template or `emit()` + `# Output: template: <name>` | Output is a template-kind payload (recipe/playbook) the receiving agent executes. Pattern: instructional skills, reusable recipes. |
 | **Data handoff** | `$ data_write content="..." recipients=[<agent>] -> R` | Skill writes data the target agent picks up via mailbox at next session. Pattern: async carrier skills, autonomous fires that hand off to a future session. |
 
-A single skill can use any combination. An autonomous cron-fired sweep might write data to one agent AND emit augment-kind context to another. The combinations are unconstrained — the per-op gating model governs which mutating ops are authorized, not which channels a skill uses.
+A single skill can use any combination. An autonomous cron-fired sweep might write data to one agent AND deliver augment-kind context to another. The combinations are unconstrained — the per-op gating model governs which mutating ops are authorized, not which channels a skill uses.
 
 ## Three op classes
 
@@ -160,12 +161,12 @@ Substrate config syntax + the three-form configuration shape lives in the adopte
 
 ## Anatomy of a skill
 
-A canonical example exercising trigger → process → deliver against the augmenting channel:
+A canonical example exercising trigger → process → deliver against the augmenting channel. (Output here is built with `emit()` because the per-issue count is variable — the right case for `emit`; a fixed-shape skill would use a body template instead.)
 
 ```
 # Skill: morning-showstopper-sweep
 # Description: Pre-triage open showstoppers before the human arrives; deliver as augmenting context to the on-call agent.
-# Triggers: cron:"0 8 * * MON-FRI"
+# Triggers: cron: 0 8 * * MON-FRI
 # Output: agent: oncall
 # Vars: PROJECT = "INFRA"
 
@@ -187,7 +188,7 @@ sweep:
 default: sweep
 ```
 
-The joined `emit()` stream becomes the augment-kind payload delivered to the on-call agent (per `# Output: agent: oncall` declaration). The agent sees the briefing inline at next-turn dispatch.
+The joined `emit()` stream becomes the augment-kind payload delivered to the on-call agent (per `# Output: agent: oncall`). The agent sees the briefing inline at next-turn dispatch.
 
 **Three layers of declaration:**
 1. **Header metadata** (`# Key: value` lines) — name, description, declared variables (`# Vars:`), declared returns (`# Returns:` — the export surface, output-side mirror of `# Vars:`; see Composition), triggers, `# Output:` routing, optional `# Autonomous:` flag, error fallbacks
@@ -276,7 +277,7 @@ The conditional grammar (`==` / `<` / `>` / `in` / `and` / `or` / `not`) lives i
 
 When you reach for a primitive that isn't in the language (`|max` over an array, modular arithmetic, regex substitution, date math), the stopping rule isn't "feature shelved." It's: *can a tool do this work, and can the skill body invoke that tool via `$` or `shell`?* Almost always yes.
 
-**The universal computation escape is `shell + standard CLI tools.**
+**The universal computation escape is `shell` + standard CLI tools.**
 
 ```
 shell(command="echo ${RAW|shell} | jq -r '[.weather[0].hourly[] | .chanceofrain | tonumber] | max'", unsafe=true) -> MAX_RAIN
@@ -418,20 +419,17 @@ Per-output-kind consumption semantics: presentation surfaces (`# Output: agent:
 ```
 notify(agent="oncall", message="Threshold breached at ${COUNT}")
 notify(agent="ops", message="ticket TR-1234 is a showstopper", event_type="ticket-911", correlation_id="${INCIDENT_ID}")
-notify(agent="cc@kitchen-terminal", message="look here now")
 ```
 
 Synchronous alert to a named agent via wired AgentConnector(s). **Contrast with `emit`:** `emit` accumulates into end-of-skill bulk delivery via the `# Output: agent: <name>` lifecycle hook; `notify` fires mid-execution to interrupt or page an agent before the skill completes.
 
-- `agent` — target agent id (required). **Address-routing**: a bare identifier (`"perry"`) routes to `AgentConnector.deliver()` (mailbox-class — the agent's inbox); an `agent@session` composite (`"cc@kitchen-terminal"`) routes to `AgentConnector.wake()` (session-targeted interrupt). The `@session` suffix IS the wake signal — there's no `wake=true` kwarg. Substrate sees the opaque composite on `wake()` and decomposes per the v0.18.2 contract.
-- `message` — alert body (optional; defaults to accumulated emissions so far). For wake-routed dispatches, the message rides as `WakeOpts.context` (preamble for the interrupt signal).
-- `event_type` — adopter-defined routing label (optional; flows to `DeliveryMeta.event_type` on deliver-class dispatches; ignored on wake-class since wake has no envelope).
-- `correlation_id` — reply-correlation id (optional; required for future `exchange()` / `request_response()` paths).
-- `connectors` — JSON array restricting which wired AgentConnector(s) receive the dispatch (optional).
-
-Returns ACK `{agent, dispatched: [{connector, ok, route?, error?}]}` — `route` is `"deliver"` or `"wake"` per address-routing. Fire-and-forget callers ignore the binding; check-delivery callers inspect ACK.
+- `agent` — target agent id (required)
+- `message` — alert body (optional; defaults to accumulated emissions so far)
+- `event_type` — adopter-defined routing label (optional; flows to `DeliveryMeta.event_type`; overrides `# Event-type:` frontmatter)
+- `correlation_id` — reply-correlation id (optional; required for future `exchange()` / `request_response()` paths)
+- `connectors` — JSON array restricting which wired AgentConnector(s) receive the dispatch (optional)
 
-The same address rule applies to lifecycle hooks: `# Output: agent: perry` routes to deliver; `# Output: agent: cc@kitchen-terminal` routes to wake. See Output targets below.
+Returns ACK `{agent, dispatched: [{connector, ok, error?}]}` — fire-and-forget callers ignore the binding; check-delivery callers inspect ACK.
 
 ### `shell` — sandboxed or unsafe shell exec
 
@@ -1224,36 +1222,32 @@ Skills are orchestration, not computation. When the conditional logic feels Turi
 
 ## Triggers — # Triggers: header, declarative + imperative registration, source types
 
-Triggers declare what events fire a skill autonomously. A skill without triggers must be invoked explicitly (via a compile/execute API call); a skill with triggers fires automatically when matching events occur.
+Triggers declare what fires a skill autonomously. A skill without triggers must be invoked explicitly (the compile/execute API); a skill with triggers fires automatically when its trigger condition occurs.
 
-## Declarative registration via `# Triggers:` header
+The trigger surface is **two sources: `cron` (time) and `event` (external signal)**. `session`, `agent-event`, `file-watch`, and `sensor` are not trigger sources — anything that isn't time-based is an external adapter that POSTs to the `/event` ingress. The runtime owns time (`cron`) and the event endpoint; source-specific watching (a file-watcher, a sensor stream, an agent-event bridge) is the adapter's job.
 
-The skill body declares triggers via metadata header. Multiple triggers permitted, comma-separated or one per line.
+## Declarative registration via `# Triggers:` header
 
 ```
-# Triggers: cron: 0 8 * * *, session: start
+# Triggers: cron: 0 8 * * *
+# Triggers: event: deploy-finished
 ```
 
-On skill write, the runtime's trigger registry parses the header and auto-registers each trigger. Editing the skill body updates registrations.
+The trigger registry parses the header and registers each trigger. A skill re-registering **its own** event_name is a silent upsert — the declarative re-save path stays friction-free.
 
 ## Imperative registration
 
-For dynamic, one-shot, or runtime-decided triggers, use the imperative `registerTrigger` API:
-
 ```
 registerTrigger({
-  skill_name: "my-skill",
-  source: "cron",
-  name: "55 2 * * *",
-  expires_at: 1779107400  // optional auto-cleanup
+  skill_name: "notify-deploy",
+  source: "event",          // "cron" | "event"
+  name: "deploy-finished"   // cron expression for cron; the event_name for event
 })
 ```
 
-Imperative triggers default to a 30-day expiration (cleanup via expiry sweep). Pass `null` for indefinite retention; author must clean up via the corresponding `unregisterTrigger` API.
+Imperative triggers default to 30-day expiry (`expires_at`); pass `null` for indefinite and clean up via `unregisterTrigger`.
 
-## Trigger sources
-
-### `cron: <expression>` — time-based
+## Source: `cron: <expr>` — time-based
 
 Standard 5-field cron. Sliding-window evaluation by a 30s poll loop. No catch-up replay if the runtime was down at fire time.
 
@@ -1261,184 +1255,212 @@ Standard 5-field cron. Sliding-window evaluation by a 30s poll loop. No catch-up
 # Triggers: cron: 0 3 * * *
 ```
 
-### `session: start | end` — session lifecycle hooks
+## Source: `event: <event_name>` — external HTTP signal
 
-Fires when an agent session begins (`session: start`) or ends (`session: end`). The load-bearing primitive for prepping context at session boundaries — a session-start skill produces `agent:` output that prepends to the next inference.
+A skill fires when an external caller POSTs its `event_name` to the runtime's `/event` ingress.
 
-```
-# Triggers: session: start
-# Output: agent: <agent-name>
-```
+**`event_name` is the public contract.**
+- Case-insensitive (normalized at register + lookup).
+- **1:1** — one `event_name` → exactly one skill, unique per deployment.
+- Posters address the **event_name**, never the skill — so you can swap the skill behind an event without breaking callers, and no POST can reach an arbitrary skill.
+- **Rebind:** re-registering an already-bound `event_name` is allowed (last-write-wins). Same skill → silent upsert. A repoint to a **different** skill is **audit-logged** (`event_name 'X' rebound: skill A → skill B`), so a cross-skill takeover is never silent.
 
-### `event: <event-name>` — runtime-host-emitted events (parse-only)
+**Params auto-derive from the skill's `# Vars:`.** You do NOT declare params separately on the trigger — the event's accepted parameter set *is* the skill's declared `# Vars:`. A POST supplies values for those names. (Both the declarative and imperative registration paths derive params from `# Vars:`.)
 
-Header parses cleanly today but the event bus that would emit `event:` triggers isn't wired yet. Cross-reference: see "Not yet implemented, but planned" at top.
+```
+# Skill: notify-deploy
+# Vars: SERVICE="", VERSION=""
+# Triggers: event: deploy-finished
+```
+→ the `deploy-finished` event accepts params `SERVICE`, `VERSION`.
 
-Example event categories (deployment-defined):
-- `event: thread.replied` — a thread receives a new reply
-- `event: mailbox.dangle` — an addressed item expires unprocessed
-- `event: classifier.flagged` — a background classifier surfaces an urgent finding
-- (extensible via runtime-host event registration)
+## The `/event` HTTP ingress
 
-### `agent-event: <agent>.<event>` — cross-agent event hooks (parse-only)
+- **Off by default.** Enable with `SKILLSCRIPT_EVENT_INGRESS_ENABLED=true`.
+- Runs on the **DashboardServer** (reuses the dashboard port — no second server).
+- **Binds localhost by default.** Reach beyond localhost only via explicit bind config.
+- **Optional bearer auth:** set `SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN`; when set, every POST must carry `Authorization: Bearer <token>`.
 
-Subscribes to another agent's events. Same parse-only status as `event:`.
+**Request:** `POST /event`, JSON body `{ "event_name": "...", "params": { ... } }`.
 
-```
-# Triggers: agent-event: builder.task.completed
-```
+**Param validation (strict):** all declared params present, no unknown params, no defaults, no type coercion (JSON types pass through; a type mismatch surfaces at the consuming op, not at the ingress).
 
-### `file-watch: <path>` — filesystem change (parse-only)
+**Responses:**
+- `200` — accepted + queued. Body: `{ "run_id": "<trace_id>", "durability": "in-process" }`
+- `400` — missing or unknown params (body names the offending set)
+- `401` — missing/wrong bearer token (when auth is configured)
+- `404` — unknown `event_name`
+- `405` — wrong method
 
-Fires when the named path changes. Relies on inotify (Linux) or kqueue (macOS) on the host.
+**Async semantics (important):** `200` means **accepted into the in-process queue, NOT skill-completed.** The skill runs asynchronously; the response never reflects skill success/failure. `durability: "in-process"` is self-describing: the queue is **best-effort, not durable across a restart** — the same property `cron` has (no catch-up replay). For at-least-once delivery the caller retries; durable queuing is not provided.
 
-Open spec question: recursive vs directory-only default. Current lean: directory-only by default, opt-in via `file-watch-recursive:` or `file-watch: <path> (recursive)`.
+**`run_id` = `trace_id`.** The `run_id` in the 200 is the fire's `trace_id` — it round-trips to the fire record (the `fires` query / dashboard `/fires` view / the trace file on disk), so a caller can later check whether its fire completed.
 
-### `sensor: <sensor-name>` — external sensor stream (parse-only)
+## Canonical example — calling `/event`
 
-Extension surface for multimodal inputs — camera, microphone, presence, screen state. Designed as a category distinct from tools: sensors are continuous channels the agent reads but doesn't emit on. Privacy gating is a structural precondition.
+The `notify-deploy` skill above, fired by an external deploy pipeline:
 
 ```
-# Triggers: sensor: presence
+curl -X POST http://localhost:7878/event \
+  -H "Authorization: Bearer $SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"event_name":"deploy-finished","params":{"SERVICE":"api","VERSION":"1.2.3"}}'
+# → 200  {"run_id":"7f3c...","durability":"in-process"}
 ```
 
-## Trigger context
+**This is the pattern for every external trigger source.** A file-watcher, a sensor stream, an agent-event bridge, a webhook relay — each is just an external adapter that watches its source and POSTs to `/event`. (A file-watch adapter, e.g.: watch a path; on change, `POST {event_name, params:{path, kind}}`.)
 
-When a skill fires from a trigger, the runtime populates ambient refs accessible inside the skill body:
+## Trigger context
 
-- `${TRIGGER_TYPE}` — the trigger source (`cron`, `session`, etc.)
+When a skill fires from a trigger, the runtime populates ambient refs:
+- `${TRIGGER_TYPE}` — `cron` | `event`
 - `${TRIGGER_PAYLOAD}` — source-specific data
-- `${EVENT.*}` — event-payload fields for `event:` / `agent-event:` triggers
+- For event fires, the POSTed params land in the skill's vars (per `# Vars:`).
 
 ## Trigger lifecycle
 
-- **Registration:** declarative via header (auto on skill write) or imperative via the `registerTrigger` API
-- **Storage:** registered triggers are records owned by the registering agent, indexed by source + name + agent_id + skill_id; the storage backend is connector-defined
-- **Inspection:** `listTriggers({ skill_name?, agent_id?, source? })` returns the live registry
-- **Archival:** `unregisterTrigger(trigger_id)` archives the trigger (audit trail preserved); declarative triggers are removed by editing the skill body to drop the declaration
+- **Register:** declarative (auto on skill write) or imperative (`registerTrigger`).
+- **Inspect:** `listTriggers({ skill?, source? })`.
+- **Remove:** `unregisterTrigger(trigger_id)` (archives; audit trail preserved). Declarative triggers are removed by editing the `# Triggers:` line out of the skill body.
 
 ## Multiple triggers
 
-A skill may declare multiple triggers; each fires an independent execution. The compiled output is identical regardless of trigger; the runtime distinguishes via `${TRIGGER_TYPE}`.
-
-Open spec question: dedup on near-simultaneous fires. If `cron: 0 8 * * *` and `event: user.present` both fire within seconds, the runtime currently runs the skill twice (one per trigger). Author dedups via state if needed.
+A skill may declare multiple triggers; each fires an independent execution. The compiled output is identical regardless of trigger; the runtime distinguishes via `${TRIGGER_TYPE}`. Near-simultaneous dedup is the author's responsibility (via state).
 
 ## Output targets — # Output: header, delivery kinds
 
-The `# Output:` header declares where a skill's result is delivered. Default behavior (no header) is `text` — return string to caller.
+A skill's **body text is its output template**, and the `# Output:` header declares where that output is delivered. Default delivery (no `# Output:` header) is `text` — returned to the caller.
 
-## Output kinds
+## Two ways to produce output: the template vs `emit` — and when to use each
 
-### `text` (default, bare-only)
+A skill produces output two ways. Choosing the right one is the difference between a clean skill and a confusing one:
+
+- **Body-text template (declarative) — for fixed-shape output.** Write the output literally in the body, interpolating `${vars}`. Use it when you know the output's shape and are just filling in values.
+- **`emit(...)` (imperative) — for output whose shape or count is decided at runtime.** `emit` is NOT deprecated; it's the right tool for:
+  1. **Variable-cardinality output** — `foreach IT in ${LIST}: emit(...)` produces a number of lines decided at runtime, which a single template can't express.
+  2. **Conditional whole-output** — branches that produce genuinely different output *shapes* (not merely different values).
+  3. **Reasoning / transcript trace** — `emit` always writes to the transcript channel for debugging.
+
+**Rule of thumb:** if you can write the output as one block of text with `${vars}` filled in, use the template. If the output's *shape or count* varies at runtime, use `emit`.
+
+**They are complementary channels, not competitors.** When a body template is present, it owns the *canonical output*; `emit` always feeds the *transcript* channel. A skill may use both — a clean declarative output plus a rich transcript — with no conflict.
 
-Returns the skill's result as a string to whatever invoked the skill via API or read the compiled prompt artifact. Bare-only — no target accepted; parse error if a target is supplied.
+## The body-text output template
+
+Body text — at the top, the bottom, or between targets — is the output template (it may appear **anywhere a target doesn't**; see Grammar). It interpolates, at runtime:
+- `# Vars:` declared inputs, and
+- any variable bound by the body (`$set`, `-> VAR`).
 
 ```
-# Output: text
+# Skill: get-weather
+# Vars: LOCATION="", UNITS="imperial"
+
+${AREA}: ${TEMP}${UNIT} and ${DESC}. High ${HIGH}${UNIT}, low ${LOW}${UNIT}.
+
+fetch:
+    shell(command="curl -s --max-time 10 https://wttr.in/${LOCATION|url}?format=j1") -> RAW
+    $ json_parse ${RAW} -> W
+    $set AREA = "${W.nearest_area.0.areaName.0.value}"
+    $set DESC = "${W.current_condition.0.weatherDesc.0.value|trim}"
+    if ${UNITS} == "metric":
+        $set TEMP = "${W.current_condition.0.temp_C}"  $set UNIT = "°C"  # + HIGH/LOW
+    else:
+        $set TEMP = "${W.current_condition.0.temp_F}"  $set UNIT = "°F"  # + HIGH/LOW
+default: fetch
 ```
+Renders to the canonical output: `Valdese: 81°F and Sunny. High 93°F, low 64°F.` — no `emit`.
 
-### `agent: <agent-name>` — augmenting context to a named agent
+**Lint:** every `${var}` in the template must be a `# Vars:` input or bound by the body. An unbound reference is a tier-1 error (`unset-template-var`). The coupling is mechanical (variable names), so it is checkable.
 
-The Augmenting-kind delivery. Output prepends to the named agent's next-turn prompt context as augment-kind payload.
+**Branching stays single-shape:** resolve a fork *inside the block* into vars (metric/imperial → `TEMP`/`UNIT`) so the template is one shape. Whole-output conditionals are an `emit` job, not a template job.
 
+**A body-template-only skill is valid.** A skill that is just a template + inputs, with **no compute block / no target**, compiles and runs — the template alone is the skill. `hello-world` is exactly this:
 ```
-# Output: agent: <agent-name>
-# Output: agent: cc@kitchen-terminal
+# Skill: hello-world
+# Status: Approved
+# Vars: WHO=world
+
+Hello, ${WHO}!
 ```
+No target required. (A tier-3 `body-template-detected` advisory fires on a static template with no `${...}` interpolations and no text-consuming `# Output:` — a gentle "is this output, or did you mean a `#` comment?" intent check; harmless on a genuinely-static line.)
 
-Used to bring an agent into the next turn pre-shaped — context that would normally require a session-start retrieval is pre-positioned. Wired end-to-end via the runtime host's prompt-prepend surface + a synchronous trigger-fire endpoint with timeout-fallback so the next-turn dispatch isn't blocked on slow skill execution.
+## `# Output:` delivery kinds
 
-**Address-routing** — same rule as `notify()`. A bare `<agent-name>` routes to `AgentConnector.deliver()` (mailbox-class). An `<agent>@<session>` composite routes to `AgentConnector.wake()` (session-targeted interrupt); the joined emit stream rides as `WakeOpts.context`. The `@session` suffix IS the wake signal — no separate `wake=true` form.
+The body template (or, absent one, the emit/`-> VAR` result) is delivered according to the `# Output:` kind:
 
-### `template: <agent-name>` — playbook delivered to a named agent
+### `text` (default, bare-only)
+Returns the result as a string to whatever invoked the skill via API or read the compiled artifact. Bare-only — a target is a parse error.
+```
+# Output: text
+```
 
-The Template-kind delivery. Output renders as a playbook the named agent executes itself — the runtime doesn't dispatch the ops, it hands the agent a recipe to follow.
+### `agent: <agent-name>` — augmenting context to a named agent
+The output prepends to the named agent's next-turn prompt context as augment-kind payload — bringing an agent into the next turn pre-shaped. Wired via the runtime host's prompt-prepend surface + a synchronous trigger-fire endpoint with timeout-fallback so next-turn dispatch isn't blocked on slow execution.
+```
+# Output: agent: <agent-name>
+```
 
+### `template: <agent-name>` — playbook delivered to a named agent
+The output renders as a playbook the named agent executes itself — the runtime hands over a recipe rather than dispatching the ops.
 ```
 # Output: template: <agent-name>
-# Output: template: cc@browser-tab-3
 ```
 
-Used for reusable recipes: a skill that, when compiled, produces instructions another agent follows.
-
-**Address-routing**: same as `agent:` above. Bare → deliver(); `@session` → wake().
-
 ### `file: <path>` — write to file
-
-Header parses; file router not yet implemented. See "Not yet implemented, but planned" at top.
+Header parses; file router not yet implemented. See "Not yet implemented, but planned."
 
 ### `none` (bare-only)
-
-Side-effects only — the skill's purpose is the writes / shell ops it performs, not the returned value. Bare-only; parse error if a target is supplied.
-
+Side-effects only — the skill's purpose is its writes / shell ops, not a returned value. Bare-only.
 ```
 # Output: none
 ```
 
 ## Multiple output targets
-
-A skill may declare multiple output targets, one per line. Each target receives the same content.
-
+A skill may declare multiple output targets, one per line; each receives the same content.
 ```
 # Output: agent: ops-channel
 # Output: agent: assistant
 ```
 
-A morning-brief skill, for example, can deliver to a team-channel agent and to an assistant agent's session-start prompt context simultaneously.
-
-## Skill categories — Augmenting / Template / Headless
-
-The output kind declaration determines the skill's category for discovery purposes (see SkillStore `skill_list` discovery surface):
-
-| Category | Determined by | Discovery group |
-|---|---|---|
-| **Augmenting** | Has `# Output: agent: <name>` declared | `receives` |
-| **Template** | Has `# Output: template: <name>` declared OR no agent/template output but agent-invokable (no triggers) | `skills` |
-| **Headless** | Output is `text` / `file:` / `none` AND has autonomous triggers | `headless` (filtered out of default agent discovery) |
-
-The derivation: ANY `output.kind === "agent"` → Augmenting; else ANY `output.kind === "template"` → Template; else if no autonomous triggers → Template (agent-invokable inference); else → Headless.
-
-Agent discovery via `skill_list()` defaults to `receives` + `skills` groups. Headless skills are filtered out of the default view (admin views can opt in via `filter: { audience: "all" }`).
-
 ## Per-kind output value semantics
 
-Different output kinds consume the skill's execution result differently:
+What each kind consumes as the output, in precedence order:
+- **Presentation surfaces** (`agent:`, `template:`): the body template if present; otherwise joined emissions (all `emit()` ops concatenated in execution order).
+- **Programmatic surfaces** (`text`, `file:`): the body template if present; otherwise the `lastBoundVar` (most recent `-> VAR`).
 
-- **Presentation surfaces** (`agent:`, `template:`) consume joined emissions — all `emit()` ops in the skill body concatenated in execution order
-- **Programmatic surfaces** (`text`, `file:`) consume the `lastBoundVar` — the most recently bound `-> VAR` value from any op
+A present body template is the canonical output for every kind; `emit` output continues to populate the transcript independently. Single source of truth in the executor's `perKindOutput()`; routers stay dumb. (Note: the `lastBoundVar` fallback is forgiving — a skill that binds a value but writes no template still outputs that last value — but it *masks* a forgotten template; prefer an explicit template when the output is fixed-shape.)
 
-Single source of truth in the executor's `perKindOutput()` function; routers stay dumb (just consume what the executor hands them per kind).
+## Skill categories — Augmenting / Template / Headless
 
-## Augmenting / Template companion header
+The output kind determines the skill's discovery category (see `skill_list`):
 
-Skills with `agent:` or `template:` output kinds can declare a companion header that rides along with the delivery payload. Optional; has no effect on Headless skills.
+| Category | Determined by | Discovery group |
+|---|---|---|
+| **Augmenting** | Has `# Output: agent: <name>` | `receives` |
+| **Template** | Has `# Output: template: <name>`, OR no agent/template output but agent-invokable (no triggers) | `skills` |
+| **Headless** | Output is `text` / `file:` / `none` AND has autonomous triggers | `headless` (filtered from default agent discovery) |
 
-### `# Event-type: <string>`
+Derivation: ANY `output.kind === "agent"` → Augmenting; else ANY `template` → Template; else no autonomous triggers → Template; else → Headless. `skill_list()` defaults to `receives` + `skills`; headless is opt-in via `filter:{audience:"all"}`.
 
-Adopter-defined routing vocabulary; flows to `DeliveryMeta.event_type` on lifecycle-hook deliveries as the frontmatter fallback. `notify(event_type=...)` kwarg takes precedence per-emit.
+## Augmenting / Template companion header — `# Event-type:`
 
+Skills with `agent:`/`template:` output may declare a routing tag that rides with the delivery payload (no effect on Headless):
 ```
 # Output: agent: perry
 # Event-type: ticket-911
 ```
-
-The receiving agent reads `event_type` for routing decisions ("this is a 911 — surface immediately" vs "this is a routine check — fold into next brief").
-
-### Lint coverage
-
-A tier-2 lint rule `unused-augmenting-header` fires when `# Event-type:` appears on a Headless skill (no `agent:` or `template:` output declared). Headless skills have no AgentConnector dispatch path, so the header would silently no-op — the lint warns the author to either change the output kind or remove the header.
-
-Legacy `# Delivery-context:` header was renamed to `# Event-type:` for vocab consistency. A tier-2 advisory `legacy-frontmatter-header` fires on the legacy form with a rename suggestion.
+The receiving agent reads `event_type` for routing ("911 — surface now" vs "routine — fold into next brief"). Flows to `DeliveryMeta.event_type`; `notify(event_type=...)` takes precedence per-emit. A tier-2 lint `unused-augmenting-header` fires when `# Event-type:` appears on a Headless skill. (Legacy `# Delivery-context:` → renamed `# Event-type:`; tier-2 `legacy-frontmatter-header` advisory on the old form.)
 
 ## Grammar
 
-- Kinds with no target (`text`, `none`) are bare-only — `# Output: text` is valid, `# Output: text: anything` is a parse error.
-- Kinds with a target (`agent`, `template`, `file`) require `<kind>: <target>` — `# Output: agent` without a target is a parse error.
-- Authoring friction-fix: parse errors on bare-only kinds suggest the corrected shape inline.
+- Bare-only kinds (`text`, `none`): `# Output: text` valid; `# Output: text: anything` is a parse error.
+- Targeted kinds (`agent`, `template`, `file`): require `<kind>: <target>`; bare form is a parse error.
+- **Template/target boundary (position-free):** a **target** is a `<name>:` line followed by an indented op-block. **Any other line** — including a `word: value` line with no op-block beneath it (`Summary: hot today`) — is **template text**, wherever it sits (top, bottom, or between targets). So the output template can go where the author's instinct puts it. Declaring **two separate template regions** in one skill is an error — pick one location.
+- Parse errors on bare-only kinds suggest the corrected shape inline.
 
 ## Output routing failures
 
-If `# Output: agent: <name>` fires and the wired AgentConnector throws, the delivery routes through `else:` / `# OnError:` machinery. The receipt surface (`agent_delivery_receipts[]`) records the failure for the scheduler to log.
+If `# Output: agent: <name>` fires and the wired AgentConnector throws, delivery routes through `else:` / `# OnError:`; the failure is recorded on `agent_delivery_receipts[]` for the scheduler to log.
 
 ## Lifecycle and status — # Status: header, six canonical states, compile + runtime enforcement
 
@@ -1966,16 +1988,18 @@ Skill discovery via `skill_list()` (see SkillStore docs) closes the related visi
 
 Design rationale for planned features. The user-facing list of "what's coming" lives in the "Not yet implemented, but planned" section at top; this section documents the *why* behind each planned addition. When the language extends, the relevant grammar moves into its canonical section (Ops reference, Variables, Triggers, etc.) and the design-rationale entry here is replaced with a cross-reference.
 
-## Sensors as a language category
+## Sensors as a read-channel category
 
-Currently `# Triggers:` includes `sensor:` as a trigger source. The planned redesign splits sensors into their own category:
+> `sensor:` is **not a trigger source** — to *fire* a skill on a sensor signal, a sensor adapter POSTs to the `/event` ingress like any other external source (see Triggers). What remains a future idea is the separate concept below: sensors as a continuous **read channel**, decoupled from triggering.
+
+The read-channel idea: a skill declares sensors it reads, distinct from what fires it:
 
 ```
 # Sensors: presence, screen-state, voice-prosody
 # Triggers: cron: 0 8 * * *
 ```
 
-**Distinction:** Sensors are continuous channels the agent reads but doesn't emit on. Triggers are discrete events that fire the skill. Conflating them in one header produces a worse language for both — sensors need different semantics (continuous read, accessible via ambient refs, privacy-gated) than triggers (discrete fire, dispatch semantics).
+**Distinction:** Sensors (read-channel) are continuous values the agent reads but doesn't emit on. Triggers are discrete signals that fire the skill. The two are different semantics — sensors need continuous read, ambient-ref access, and privacy gating; triggers need discrete fire + dispatch. (Conflating them in one `sensor:` trigger source was the old design; the trigger half folds into `event`, the read-channel half stays future.)
 
 Pending: ambient refs for sensor values (`${SENSOR.presence}`, `${SENSOR.voice-prosody.affect}`) and the privacy-gating discipline that determines when a sensor is readable.
 
@@ -1999,7 +2023,7 @@ Different shape from event triggers — "fire if user hasn't messaged in N minut
 # Triggers: idle: 5m
 ```
 
-Runtime tracks the relevant idleness counter and fires when the threshold crosses. Separate dispatch mechanism from event triggers.
+Runtime tracks the relevant idleness counter and fires when the threshold crosses. Would be a **new trigger source beyond the current `cron`|`event`** — or, absent a new source, an adapter that POSTs to `/event` on a timer. Separate dispatch mechanism from event triggers either way.
 
 ## Time-windowed aggregation
 
@@ -2132,7 +2156,7 @@ Runtime fails-fast on missing capabilities. Trust precondition for sensor work
 ## Build order rationale
 
 Some features depend on others:
-- Suppression + persistent state should land before sensors (sensor work would compound problems without them)
+- Suppression + persistent state should land before the sensor read-channel (sensor work would compound problems without them)
 - Pub-sub needs sensors producing traffic before it has anything to route
 - Introspection is ergonomic, not foundational — useful but skippable
 - Capability declarations are the trust gate that makes sensor + privacy work socially defensible
@@ -2158,33 +2182,31 @@ Should `${ERROR}` be an ambient ref inside `else:` blocks, populated with the er
 
 ## 3. Multiple triggers — concurrency
 
-If `cron: 0 8 * * *` and `event: user.present` both fire within seconds, does the skill run twice (independent) or get deduped? Lean: independent. Author dedups via state if needed. Affects dispatch layer.
+If `cron: 0 8 * * *` and `event: user-present` both fire within seconds, does the skill run twice (independent) or get deduped? Lean: independent. Author dedups via state if needed. Affects dispatch layer.
 
 ## 4. `execute_skill()` invocation vs trigger firing
 
 When skill A invokes skill B via `execute_skill()`, do skill B's `# Triggers:` fire? Almost certainly no — `execute_skill()` is direct invocation, distinct from the trigger event surface. Worth saying explicitly.
 
-## 5. File-watch path semantics
-
-Recursive or directory-only by default? Inotify supports both. Lean: directory-only default; offer recursive via `file-watch-recursive:` or `file-watch: <path> (recursive)`. Affects dispatch layer when the file-watch trigger source actually fires (currently parse-only).
-
-## 6. Output target delivery failures
+## 5. Output target delivery failures
 
 If a delivery target is unreachable when the skill fires, what happens? Lean: delivery failure is its own retryable error; queue if possible, else error to caller. Worth a separate small spec section. Affects dispatch layer.
 
-## 7. Skill versioning rollback UX
+## 6. Skill versioning rollback UX
 
 Edits via upsert preserve history through substrate versioning (SqliteSkillStore's `skill_versions` table, FilesystemSkillStore's git history), but no first-class "rollback" affordance. Probably needs a `--version <N>` flag on the compile API or a sister tool.
 
-## 8. Connector capability declarations
+## 7. Connector capability declarations
 
 Skills can declare required connector capabilities via `# Requires:` for var resolution. Extending this to "needs semantic search" / "needs structured-extraction model with 32K context" capabilities would be useful for the substrate-portable story. Pending design.
 
-## 9. Per-op timeouts
+## 8. Per-op timeouts
+
+Hung dispatches hang the skill without explicit timeout configuration. Lean: skill-level `# Timeout:` header + per-op `timeout=N` kwarg + runtime defaults. Pending implementation; see "Not yet implemented, but planned" at top.
 
-Hung dispatches hang the skill without explicit timeout configuration. Lean: skill-level `# Timeout:` header + per-op `timeoutSeconds=N` kwarg + runtime defaults. Pending implementation; see "Not yet implemented, but planned" at top.
+*(The former "file-watch path semantics" question was removed — `file-watch` is no longer a trigger source; filesystem watching is now an external adapter that POSTs to the `/event` ingress, so there are no in-language file-watch path semantics to settle.)*
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-06-04 11:28 EDT*  
-*Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*
+*Rendered from `skillscript/skillscript-language-reference` — 2026-06-08 17:41 EDT*  
+*Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-08T18:14:44.579Z",
+  "compiled_at": "2026-06-09T13:43:10.260Z",
   "source_skill": {
     "name": "hello-world"
   },