skillscript-runtime 0.19.11 → 0.19.13

package/docs/adopter-playbook.md

@@ -232,9 +232,9 @@ SKILLSCRIPT_HOME=/path/to/adopter skillfile dashboard --config /path/to/adopter/
 
 Each instance reads its own config; ports/paths/db files don't collide.
 
-## Shell binary allowlist (v0.18.8 — BREAKING)
+## Shell binary allowlist
 
-**v0.18.8 introduces a default-deny operator allowlist for binaries reachable via `shell(...)` ops.** Per the Scott + Perry decision (memory `7aab6f3f`): skill authors are agents, agents are a weak trust anchor (hallucination, prompt-injection, no human-in-loop at scale), and operator-side scoping converts "a human reviews every skill" from discipline into an enforced constraint at the language level.
+**The runtime enforces a default-deny operator allowlist for binaries reachable via `shell(...)` ops.** Skill authors are agents, agents are a weak trust anchor (hallucination, prompt-injection, no human-in-loop at scale), and operator-side scoping converts "a human reviews every skill" from discipline into an enforced constraint at the language level.
 
 ### The behavior
 
@@ -242,25 +242,41 @@ Two **independent** operator axes — do not conflate:
 
 | Axis | Operator switch | Controls |
 |---|---|---|
-| **Binary scope** | `SKILLSCRIPT_SHELL_ALLOWLIST` (v0.18.8 new) | Which binaries `shell(...)` can invoke |
-| **Syntax scope** | `SKILLSCRIPT_ENABLE_UNSAFE_SHELL` (existing) | Whether bash interpretation (pipes / `$VAR` / `$(...)`) is permitted |
+| **Binary scope** | `SKILLSCRIPT_SHELL_ALLOWLIST` | Which binaries `shell(...)` can invoke |
+| **Syntax scope** | `SKILLSCRIPT_ENABLE_UNSAFE_SHELL` | Whether bash interpretation (pipes / `$VAR` / `$(...)`) is permitted |
 
 Behavior matrix:
 
 | Skill op | Binary on allowlist | Binary off allowlist |
 |---|---|---|
-| `shell(command="X ...")` (safe) | runs | refused with `ShellBinaryNotAllowedError` |
+| `shell(command="X ...")` (structural) | runs | refused with `ShellBinaryNotAllowedError` |
+| `shell(argv=["X", ...])` (explicit token list) | runs | refused with `ShellBinaryNotAllowedError` |
 | `shell(command="X ...", unsafe=true)` with `enableUnsafeShell=true` | runs (if `bash` on allowlist) | refused (off-list `bash` blocks ALL unsafe shell) |
 | `shell(command="X ...", unsafe=true)` with `enableUnsafeShell=false` | refused with `UnsafeShellDisabledError` (syntax axis fires first) | — |
 
 **Off-allowlist is final.** The skill author has no in-skill mechanism to escape it — not the `unsafe` keyword, not `# Autonomous: true`, not `approved="reason"`. Binary scope is an operator boundary the author cannot talk past.
 
-### Pre-upgrade migration — run this BEFORE you upgrade
+### Three call shapes — `command=`, `argv=`, `unsafe=true`
 
-The default-deny posture means existing skills using `shell()` will refuse to run on first dispatch after upgrade. **Sequence the migration as a discovery step, not a recovery step:**
+Three ways to invoke a binary. Each picks a different point on the safety/expressiveness curve:
+
+| Form | When to reach for it |
+|---|---|
+| `shell(command="curl -s https://example.com/${ID}") -> R` | Simple commands, no spaces or quote-special chars in substituted values. The string is whitespace-tokenized + quote-stripped; structural spawn (no shell). |
+| `shell(argv=["say", "-v", "${VOICE}", "-f", "${PATH}"]) -> R` | **Args with spaces, JSON payloads, dynamic strings.** Each list element is exactly one argv token; substitution per element doesn't re-tokenize. Strictly safer than `unsafe=true` — no shell process, no metacharacter interpretation, injection-surface zero. The right tool when a `${VAR}` may contain whitespace. |
+| `shell(command="echo hi && date", unsafe=true) -> R` | Pipes, redirects, shell built-ins, command-substitution. Requires `enableUnsafeShell: true` at the runtime; lint flags every appearance (tier-2 `unsafe-shell-op`). |
+
+`argv=` is mutually exclusive with `command=` and with `unsafe=true` (parse errors on either combination — argv is execv-class, there's no shell to opt into). The same allowlist gate applies to `argv[0]`.
+
+### Quote-trap lint (`shell-quoted-var-in-command`)
+
+The pattern `shell(command="echo '${VAR}'")` looks safe — quotes around the substitution — but the structural tokenizer respects quotes during the *original* whitespace split, then strips them. After substitution, if VAR contains quote characters (`Jamie's`) the matching can drift. Tier-2 lint `shell-quoted-var-in-command` fires on this pattern and points at the `argv=` form as the safer answer. Works fine for known-simple values; the lint exists because the failure mode is silent-wrong, not loud-error.
+
+### Discovering your corpus's binaries
+
+The default-deny posture means a freshly-installed runtime with no allowlist wired refuses every `shell()` call. Use `skillfile shell-audit` to enumerate the binaries your skill corpus invokes:
 
 ```bash
-# 1. Run while still on v0.18.7 (or any prior version) — pre-upgrade discovery
 skillfile shell-audit
 
 # Sample output:
@@ -279,15 +295,9 @@ skillfile shell-audit
 #   Note: 'bash' is on the list because at least one skill uses
 #   shell(..., unsafe=true). To permit unsafe shell, ALSO set
 #   SKILLSCRIPT_ENABLE_UNSAFE_SHELL=true.
-
-# 2. Paste into your $SKILLSCRIPT_HOME/.env, review/narrow as desired
-
-# 3. NOW upgrade to v0.18.8 — skills find the allowlist already
-#    populated, no surprise refusals
-pnpm install skillscript-runtime@^0.18.8
 ```
 
-Running the audit *after* the break is fine but adopter-unfriendly — operators discover problems through runtime errors instead of explicit decisions. The CLI tool exists precisely to make pre-upgrade the canonical path.
+Paste into your `$SKILLSCRIPT_HOME/.env` (review/narrow as desired). The audit is the canonical path — running it lets you make explicit policy decisions instead of discovering refusals through runtime errors.
 
 ### Programmatic bootstrap path (`bootstrap()` adopters)
 
@@ -296,7 +306,7 @@ Running the audit *after* the break is fine but adopter-unfriendly — operators
 | Surface | CLI path | Programmatic path |
 |---|---|---|
 | `.env` (env vars in a dotfile) | auto-loaded from `$SKILLSCRIPT_HOME/.env` | call `process.loadEnvFile()` yourself BEFORE `bootstrap()` |
-| `SKILLSCRIPT_*` env vars | read from `process.env` automatically | read automatically once env is loaded (v0.18.9+ env fallback) |
+| `SKILLSCRIPT_*` env vars | read from `process.env` automatically | read automatically once env is loaded (`bootstrap()` env-fallback) |
 | `connectors.json` (MCP wiring) | auto-discovered at `$SKILLSCRIPT_HOME/connectors.json` | pass `connectorsConfigPath: "/path/to/connectors.json"` to `bootstrap()` |
 
 Skip any of these and you get silent-empty surprises — a missing env var, an undeclared connector, etc. — with no hint that the file wasn't loaded. This is intentional: `bootstrap()` stays decoupled from the dotenv + `SKILLSCRIPT_HOME` convention so embedders can drive every input explicitly. The cost is doc-prominence — three surfaces, all silent-empty on omission, all noted here.
@@ -326,7 +336,7 @@ const { mcpServer, scheduler } = bootstrap({
 });
 ```
 
-**`bootstrap()` env fallback semantics (v0.18.9+)**: when `opts.shellAllowlist === undefined`, the runtime reads `SKILLSCRIPT_SHELL_ALLOWLIST` from `process.env` (comma-separated, trimmed). When `opts.shellAllowlist` is supplied — including the explicit `[]` deny-all — the option is authoritative and **env does NOT widen it**. This is security-load-bearing: an adopter passing `shellAllowlist: []` to assert lockdown gets lockdown regardless of ambient env.
+**`bootstrap()` env fallback semantics**: when `opts.shellAllowlist === undefined`, the runtime reads `SKILLSCRIPT_SHELL_ALLOWLIST` from `process.env` (comma-separated, trimmed). When `opts.shellAllowlist` is supplied — including the explicit `[]` deny-all — the option is authoritative and **env does NOT widen it**. This is security-load-bearing: an adopter passing `shellAllowlist: []` to assert lockdown gets lockdown regardless of ambient env.
 
 | `opts.shellAllowlist` | `SKILLSCRIPT_SHELL_ALLOWLIST` env | Effective allowlist |
 |---|---|---|
@@ -356,13 +366,13 @@ Argument-level policy (host allowlists, URL pattern matching) and OS-level egres
 - `execve`/`seccomp` filters (kernel-level allowed-binary set)
 - Container with curated `/usr/bin` (immutable distroless image)
 
-Per Perry's reframe (memory `7aab6f3f`): parse-based binary enumeration of `bash -c <body>` would be unsound — `e=curl; $e ...`, `$(printf cur)l ...`, `eval`, `xargs`, var-built command names all defeat it. Against agent-author threat models, false confidence is worse than no enforcement.
+Parse-based binary enumeration of `bash -c <body>` would be unsound — `e=curl; $e ...`, `$(printf cur)l ...`, `eval`, `xargs`, var-built command names all defeat it. Against agent-author threat models, false confidence is worse than no enforcement.
 
-### Dashboard observability (v0.18.9)
+### Dashboard observability
 
 The dashboard SPA at `http://<host>:<port>` exposes two security-focused surfaces for the observe→promote loop:
 
-**Security view (`#security` route).** Cross-skill list of blocked shell attempts — `{skill, target, binary, body, timestamp}` per refused call. Aggregated by binary so you can see at a glance "what did skills try to invoke that I haven't allowlisted." Backed by the new `blocked_shell_attempts` MCP tool, which filters trace records by `blocked_reason: "binary-not-allowed"`. Pre-v0.18.9 runtimes don't expose this tool; the view degrades cleanly to an "upgrade to v0.18.9+" note.
+**Security view (`#security` route).** Cross-skill list of blocked shell attempts — `{skill, target, binary, body, timestamp}` per refused call. Aggregated by binary so you can see at a glance "what did skills try to invoke that I haven't allowlisted." Backed by the `blocked_shell_attempts` MCP tool, which filters trace records by `blocked_reason: "binary-not-allowed"`. Runtimes without the tool exposed degrade cleanly to an "unavailable" note.
 
 **Skill detail view — security signals + source highlighting.** Each skill's detail page (clicking a skill name from `#skills`) shows:
 - A **"Security signals"** panel at the top: aggregated counts of shell ops + binaries used, unsafe-shell count, `# Autonomous: true`, per-op `approved="..."` authorizations, mutation ops (`$ skill_write` / `$ data_write` / `file_write`), wake-class `@session` deliveries, cron triggers.
@@ -370,7 +380,7 @@ The dashboard SPA at `http://<host>:<port>` exposes two security-focused surface
 
 The two surfaces compose: summary panel tells you WHAT to look for; highlights tell you WHERE to look.
 
-### Future direction (NOT shipped in v0.18.8)
+### Future direction
 
 Per-skill capability declaration: skills declare what shell binaries they need in their frontmatter:
 
@@ -382,16 +392,16 @@ Per-skill capability declaration: skills declare what shell binaries they need i
 
 The operator policy validates `declared ∩ allowlist` — each skill's shell footprint becomes self-documenting and auditable. Slated for a future ring once the chokepoint + observability surfaces ship.
 
-## Trigger model (v0.19.0 — BREAKING)
+## Trigger model
 
-**v0.19.0 collapses the trigger surface to two primitives.** Per the Scott + Perry decision (memory `ceaf4579`):
+**The trigger surface is two primitives.**
 
 | Primitive | Purpose |
 |---|---|
 | `cron` | Time-based fires (unchanged) |
 | `event` | Generic external-signal fires via HTTP POST to `/event` |
 
-The previous sources (`session`, `agent-event`, `file-watch`, `sensor`) are **removed**. They were either parse-only stubs that never fired or substrate-coupled concepts that belong outside the runtime. Anything external becomes an adapter that POSTs to `/event` — including what would have been a session/agent-event/file-watch/sensor trigger. The `DeliveryMeta.origin.trigger_kind` receiver enum also drops `"session"` in lockstep (pre-v1.0 cleanup; the value was never functionally emitted).
+Concepts that look like triggers but aren't — session lifecycle, agent events, file-watch, sensors — are **adapter responsibilities**: external code POSTs `/event` when relevant. Keeps the runtime substrate-neutral; the trigger surface stays tight. The `DeliveryMeta.origin.trigger_kind` receiver enum exposes only `"cron" | "event" | "webhook" | "agent" | "cli" | "dashboard" | "inline"`.
 
 ### The `event` primitive
 
@@ -418,7 +428,7 @@ Authorization: Bearer <token>   # if SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN set
 
 {
   "event_name": "prox",
-  "params": { "ROOM": "kitchen", "USER": "scott" }
+  "params": { "ROOM": "kitchen", "USER": "alice" }
 }
 ```
 
@@ -444,8 +454,6 @@ The `run_id` is the runtime's `trace_id` — adopters paste it into the dashboar
 
 ### `# Autonomous: true` for event/cron skills doing mutations
 
-This is **not** a v0.19.0 regression — it's the pre-existing v0.14.x mutation gate. But it surfaces more visibly with event-fired skills, so worth calling out explicitly in this section.
-
 Skills fired by cron OR event have **no interactive author** to confirm mutation ops. The runtime's mutation gate (`$ data_write` / `$ skill_write` / `file_write` / mutating MCP tools) requires explicit authorization in non-interactive contexts. Three authorization paths exist:
 
 ```
@@ -498,7 +506,7 @@ SKILLSCRIPT_EVENT_INGRESS_ENABLED=true
 SKILLSCRIPT_EVENT_INGRESS_AUTH_TOKEN=<token>
 ```
 
-When `eventIngressEnabled=true`, the route mounts on the same HTTP server as the dashboard/RPC (no second port). Default bind is `127.0.0.1` (localhost-only) — adopters wanting `0.0.0.0` external reach pass `--host 0.0.0.0` explicitly. Per Perry's framing: "enforce the DMZ assumption by the bind, not by hope."
+When `eventIngressEnabled=true`, the route mounts on the same HTTP server as the dashboard/RPC (no second port). Default bind is `127.0.0.1` (localhost-only) — adopters wanting `0.0.0.0` external reach pass `--host 0.0.0.0` explicitly. The DMZ assumption is enforced by the bind, not by hope.
 
 ### Durability honesty
 
@@ -506,20 +514,20 @@ When `eventIngressEnabled=true`, the route mounts on the same HTTP server as the
 
 Durable / at-least-once delivery is a v2 if real adopter need surfaces. Don't oversell the 200 contract; build durable queueing on top yourself if you need it now.
 
-### Migration from removed sources
+### Bridging external sources
 
-If you have pre-v0.19.0 skills with `# Triggers: session: start` / `agent-event: X` / `file-watch: /path` / `sensor: X` declarations:
+Anything that isn't time-based is an external adapter that POSTs to `/event`:
 
-- **session start/end** → boot/shutdown lifecycle moved to the substrate (NanoClaw / your harness). If you need a runtime skill to fire at session-start, your harness POSTs to `/event` after boot.
-- **agent-event** → external bridge (your agent fires `POST /event` when relevant).
-- **file-watch** → external watcher script (inotify / chokidar / fswatch) POSTs to `/event`. The "how to call /event" pattern lives in the language reference call-example; the file-watching itself is standard OS plumbing — you own that script.
-- **sensor** → same pattern as file-watch; sensor adapter POSTs to `/event`.
+- **Session start/end** — your harness POSTs `/event` after boot or before shutdown if you want a skill to fire at session boundaries.
+- **Agent events** — your agent emits `POST /event` when the event of interest occurs.
+- **File-watch** — an external watcher script (`inotify` / `chokidar` / `fswatch`) POSTs to `/event` on changes. The file-watching itself is standard OS plumbing — you own that script.
+- **Sensors** — same pattern as file-watch; the sensor adapter POSTs to `/event`.
 
-Skills declaring removed sources fail to parse on v0.19.0 (tier-1 parse error). Run `skillfile lint` against your corpus pre-upgrade to find them.
+Skills declaring unsupported `# Triggers:` sources fail to parse with a tier-1 parse error. `skillfile lint` against your corpus surfaces them.
 
 ## Output template — body text IS the output
 
-A skill's body text — the prose between the frontmatter and the first target — is its declarative output template. The runtime interpolates `${VAR}` references against final vars and publishes the rendered string as the skill's canonical output (`outputs.text` or the agent/template/file payload, depending on `# Output:` kind). No `emit()` ceremony required for the common case.
+A skill's body text — prose lines that don't sit inside a target — is its declarative output template. The runtime interpolates `${VAR}` references against final vars and publishes the rendered string as the skill's canonical output (`outputs.text` or the agent/template/file payload, depending on `# Output:` kind). No `emit()` ceremony required for the common case. The template may appear **anywhere a target doesn't** — at the top, at the bottom, or split between targets — so authors can put output where their language instincts suggest (most write the output line *after* the compute that fills it in).
 
 ### The shape
 
@@ -550,7 +558,7 @@ Two independent output channels:
 
 When a skill defines both a template AND `emit(text=...)` calls, the template owns canonical output; `emit()` populates transcript only. This is intentional — emit is the debugging / reasoning channel. The `emit-with-template` advisory lint surfaces this to confirm intent.
 
-If you want emit to keep being your canonical output (the pre-v0.19.4 shape), don't write a body template. Emit-only skills work exactly as before.
+If you want emit to be your canonical output, don't write a body template. Emit-only skills route emissions to the canonical output channel.
 
 ### Output kinds
 
@@ -585,13 +593,60 @@ report: needs: fetch_issues
 
 The legacy `report: fetch_issues` shape (deps after colon, no `needs:` keyword) is still parsed as a target when an indented op-block follows on the next line, but `needs:` is the recommended form for new skills.
 
+### One template region per skill
+
+A skill may carry template prose in one region. Splitting it into two — some prose above the targets AND some below — raises a tier-1 parse error: "skill has body template content in two places (before targets AND after targets). Pick one location." Picking is loud over silent-concat; the author chooses where the template lives, the runtime doesn't guess.
+
 ### Lints to know
 
 - **`unset-template-var`** (tier-1) — every `${VAR}` in the template must resolve to a `# Vars:` / `# Requires:` input, an ambient ref (`NOW`, `USER`, ...), or a `$set` / `->` binding somewhere in the skill body. Tier-1 because an unbound ref renders empty silently.
 - **`template-looks-like-target`** (tier-2) — bare `<word>:` alone in the template region, no following op-block. Ambiguous shape — author may have meant a target.
+- **`connector-as-tool`** (tier-1) — `$ <connector> <tool>` space-separated catches the muscle-memory foot-gun (CLI-style `git status`). Bare-form dispatch treats the first token as the tool name, sending `name: "<connector>"` to the MCP server, which replies with a misdirecting "Tool '<connector>' not found." The two correct shapes are `$ <connector>.<tool> args` (dotted) or `$ <tool> args` (bare-tool; runtime resolves).
+- **`remote-result-needs-parse`** (tier-3) — `${R|length}` on an `R` bound by `$` dispatch. Per-MCP-server result shapes vary: if the server returns prose-wrapped or non-JSON text, the value binds as a STRING and `|length` returns the string's char-count instead of element-count. Add `$ json_parse ${R} -> P` after the dispatch and use `${P|length}`. Suppressed when the skill already does `$ json_parse ${R}` somewhere — your defensive parse is taken as intent.
 - **`body-template-detected`** (tier-3) — non-blank, non-`#` lines in the body region, no `${...}` interpolations, no text-consuming `# Output:` declaration. Suggests "I wrote prose; it became template by accident." Prefix with `#` to mark as comments, or add an interpolation / `# Output:` to confirm intent.
 - **`emit-with-template`** (tier-3) — skill has both a template AND `emit(text=...)` calls. Confirms the channel-shift is intentional.
 
+## Fallback semantics — `(fallback: ...)` op-trailer and `|fallback:` filter
+
+Two surfaces, **one emptiness predicate**. Both fire when the upstream value is any of:
+
+- empty string after `trim()`
+- empty array (`[]`)
+- `null` / `undefined`
+
+### Op-trailer — `(fallback: "value")`
+
+Trails the `-> R` binding on `$` dispatch ops, `shell(...)`, `file_read(...)`. Binds the fallback value to `R` when the op throws OR produces an empty result.
+
+```
+$ ticketing.search query="open" -> ISSUES (fallback: [])
+
+shell(argv=["gh", "pr", "list", "--repo", "owner/repo"]) -> PRS (fallback: "No current PRs.")
+
+file_read(path="/var/reports/today.md") -> REPORT (fallback: "no report")
+```
+
+When the fallback fires, the runtime pushes a record onto `result.fallbacks[]` so callers can distinguish "real value" from "fallback substituted." The original error message rides on the fallback record's `reason` field; the op completes cleanly.
+
+### Filter — `${VAR|fallback:"value"}`
+
+Substitution-time fallback inside a template or kwarg. Same emptiness predicate; binds to the filter argument when the upstream value is empty.
+
+```
+Open PRs: ${PRS|fallback:"none today"}.
+
+$ llm prompt="Triage this: ${INPUT|fallback:'(no input — skip)'}" -> JUDGMENT
+```
+
+The filter is positional in chains: `${RAW|trim|fallback:"-"}` applies trim first, then fallback if the trim left an empty string.
+
+### When to use which
+
+- **Op-trailer** for *binding-time* protection — the variable lands populated regardless of the op's outcome. Downstream consumers (other ops, template renders) don't need to know whether the value is real or fallback.
+- **Filter** for *substitution-time* defaulting — the variable may legitimately be empty/unset, you just want a placeholder at the render site.
+
+Most "no current results" patterns want the op-trailer (the variable becomes the canonical record of what happened). The filter is for "if the optional input wasn't supplied, show a placeholder" cases.
+
 ## Wiring the AgentConnector
 
 `AgentConnector` is the substrate-neutral delivery surface for `# Output: agent: X` / `# Output: template: X` lifecycle hooks and `notify()` / `exchange()` ops. The runtime calls into the contract; your impl decides where the payload lands (webhook, tmux session, file drop, IPC pipe, Slack thread, your own agent harness, etc.).
@@ -660,9 +715,9 @@ The canonical bundled example is `examples/connectors/HttpWebhookAgentConnector/
 
 Three patterns to copy when forking it for your substrate:
 
-**Pattern 1 — `agent@session` opaque composite.** Every messaging substrate needs either bare-identity OR specific-live-session addressing. The contract keeps `agent_id` opaque; sessions ride as `"perry@kitchen-terminal"` or via `WakeOpts.session_id`. Substrates that care decompose; substrates that don't ignore.
+**Pattern 1 — `agent@session` opaque composite.** Every messaging substrate needs either bare-identity OR specific-live-session addressing. The contract keeps `agent_id` opaque; sessions ride as `"<agent>@<session>"` (e.g. `"alice@laptop-tab-3"`) or via `WakeOpts.session_id`. Substrates that care decompose; substrates that don't ignore.
 
-As of v0.18.5, the runtime address-routes skill-author surfaces (`notify()` + `# Output: agent:` / `template:`) on `@session` presence: bare → your `deliver()`, composite → your `wake()`. You receive whichever method the runtime decided; your job is to honor what arrives. For `wake()`, expect the FULL composite (`"perry@kitchen-terminal"`) — decompose to route to the right session:
+The runtime address-routes skill-author surfaces (`notify()` + `# Output: agent:` / `template:`) on `@session` presence: bare → your `deliver()`, composite → your `wake()`. You receive whichever method the runtime decided; your job is to honor what arrives. For `wake()`, expect the FULL composite (`"<agent>@<session>"`) — decompose to route to the right session:
 
 ```typescript
 async wake(agent_id: string, opts?: WakeOpts): Promise<WakeReceipt> {
@@ -693,9 +748,9 @@ async wake(agent_id: string, _opts?: WakeOpts): Promise<WakeReceipt> {
 
 Callers reading `WakeReceipt.woken` distinguish "the substrate woke them" from "the substrate stored the payload for later" without needing per-substrate knowledge.
 
-**Pattern 3 — session echo on receipts.** When your substrate routes to a specific session, echo it back on `DeliveryReceipt.session_id` / `WakeReceipt.session_id`. Dashboards rendering "delivered to perry@kitchen-terminal" rather than just "delivered to perry" depend on this.
+**Pattern 3 — session echo on receipts.** When your substrate routes to a specific session, echo it back on `DeliveryReceipt.session_id` / `WakeReceipt.session_id`. Dashboards rendering "delivered to alice@laptop-tab-3" rather than just "delivered to alice" depend on this.
 
-**Pattern 4 — read `meta.origin.caller_agent_id` to attribute, not for scope.** The `DeliveryMeta` envelope your `deliver()` receives carries `origin.caller_agent_id` = the *authenticated caller* who fired the dispatch (not the skill's owner — those are separate semantics; see [Connector Contract Reference](connector-contract-reference.md) §field semantics). Use it for *attribution* — rendering "from cc" on the receiving end, audit logs, accountability — not for authorization scoping. Outbound substrate scoping should derive from the *skill owner* (which the runtime applies at the connector layer via `ctx.agentId`, not via the envelope). If `caller_agent_id` is undefined on a delivery you receive, it means the chain originated from a non-human trigger (cron / event / scheduler) — your substrate should attribute it as "system-fired" or similar, not assume an identity.
+**Pattern 4 — read `meta.origin.caller_agent_id` to attribute, not for scope.** The `DeliveryMeta` envelope your `deliver()` receives carries `origin.caller_agent_id` = the *authenticated caller* who fired the dispatch (not the skill's owner — those are separate semantics; see [Connector Contract Reference](connector-contract-reference.md) §field semantics). Use it for *attribution* — rendering "from <caller>" on the receiving end, audit logs, accountability — not for authorization scoping. Outbound substrate scoping should derive from the *skill owner* (which the runtime applies at the connector layer via `ctx.agentId`, not via the envelope). If `caller_agent_id` is undefined on a delivery you receive, it means the chain originated from a non-human trigger (cron / event / scheduler) — your substrate should attribute it as "system-fired" or similar, not assume an identity.
 
 **Pattern 5 — surface non-fatal notes via `DeliveryReceipt.warnings`.** When your substrate needs to signal something non-fatal about a delivery — "stripped @session because verb is deliver", "rate-limit hint", "fan-out: delivered to 3 sessions" — return them as `warnings: string[]` on the receipt instead of writing to stderr. The runtime echoes warnings onto `AgentDeliveryReceiptRecord.receipt.warnings`, where the dashboard can render them and observability tools can scrape them. Stderr noise gets lost; receipt warnings are structured + caller-visible.
 
@@ -722,7 +777,7 @@ How `author` is captured depends on how the skill gets written:
 
 Adopters whose `SkillStore` is backed by an addressable substrate (e.g., a memory store) can author skills by writing the substrate record directly — without going through the MCP `skill_write` handler. This captures `SkillMeta.author` from the substrate's own writer-identity (whatever the direct-write API authenticates as).
 
-**Gotcha:** direct-write must declare `# Status: Draft`, not `# Status: Approved`. The runtime's hash-token tamper gate (v0.9.0) rejects skills with `# Status: Approved` that lack a `vN:<token>` stamp; the stamp is computed by the runtime's `update_status` flow, not by the substrate. To publish:
+**Gotcha:** direct-write must declare `# Status: Draft`, not `# Status: Approved`. The runtime's hash-token tamper gate rejects skills with `# Status: Approved` that lack a `vN:<token>` stamp; the stamp is computed by the runtime's `update_status` flow, not by the substrate. To publish:
 
 1. Write the skill with `# Status: Draft` via your substrate's direct-write API.
 2. Call `skill_status({name, new_state: "Approved"})` via MCP (or the dashboard's Approve button). This stamps the token and preserves the captured author.
@@ -731,9 +786,9 @@ Write-Approved-without-stamp will fail at execute time with `ApprovalRejectedErr
 
 ## Identity propagation — for multi-agent hosts
 
-**Skip this section** if your runtime serves one agent (CLI tools, single-user dashboards, hobby deployments). The existing v0.16.8 default — `SkillMeta.author` captured from the SkillStore's writer identity — already attributes authorship correctly when there's only one writer.
+**Skip this section** if your runtime serves one agent (CLI tools, single-user dashboards, hobby deployments). The default — `SkillMeta.author` captured from the SkillStore's writer identity — already attributes authorship correctly when there's only one writer.
 
-This section is for adopters whose runtime is fronted by an MCP host that bridges multiple authenticated agents into one transport (e.g., a NanoClaw-style multi-agent gateway, or a multi-tenant SaaS where agents share a runtime pool).
+This section is for adopters whose runtime is fronted by an MCP host that bridges multiple authenticated agents into one transport (e.g., a multi-agent gateway, or a multi-tenant SaaS where agents share a runtime pool).
 
 ### The gap MCP doesn't close on its own
 
@@ -753,7 +808,7 @@ When you configure `dashboard.mcpCallerIdentityHeader`, the runtime reads that h
 }
 ```
 
-Multi-agent host (NanoClaw, custom MCP gateway, etc.) is responsible for setting the header on every outbound request:
+Multi-agent host (custom MCP gateway, etc.) is responsible for setting the header on every outbound request:
 
 ```http
 POST /rpc HTTP/1.1

package/docs/language-reference.md

@@ -379,7 +379,7 @@ Closed list of language-intrinsic ops the runtime knows directly. Each is a func
 | `notify` | `notify(agent="...", message="...", [event_type=...], [correlation_id=...]) -> ACK` | optional | Mid-skill agent alert; synchronous send via configured AgentConnector. |
 | `inline` | `inline(skill="<data-skill-name>")` | none | Compile-time inline of an Approved `# Type: data` skill. Resolves at compile, records `content_hash` in provenance. |
 | `execute_skill` | `execute_skill(skill_name="...", inputs={...}) -> R` | optional | Composition primitive. Runtime-resolved. See Composition section. |
-| `shell` | `shell(command="...") -> R` / `shell(command="...", unsafe=true) -> R` | optional | Sandboxed shell exec (default) or full-shell exec (`unsafe=true`, gated by `runtime.enable_unsafe_shell`). stdout binds. |
+| `shell` | `shell(command="...") -> R` / `shell(argv=[...]) -> R` / `shell(command="...", unsafe=true) -> R` | optional | Structural spawn (default), explicit-argv spawn (`argv=[...]`, no tokenizer), or full-shell exec (`unsafe=true`, gated by `runtime.enable_unsafe_shell`). Binary gated by the operator allowlist (see below). stdout binds. |
 | `file_read` | `file_read(path="...") -> R` | required | Read a file at `path`; binds string contents. |
 | `file_write` | `file_write(path="...", content="...")` | none | Write `content` to `path`. `mkdir -p` semantics for parent directories. Mutation-classified. |
 
@@ -431,18 +431,25 @@ Synchronous alert to a named agent via wired AgentConnector(s). **Contrast with
 
 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
+### `shell` — structural, explicit-argv, or unsafe exec
 
-**Sandboxed default:**
+Three forms.
+
+**1. `shell(command="...")` — structural spawn (default).** The command string is whitespace-tokenized and quote-stripped, then one binary is spawned with the resulting tokens. No shell, no metacharacters, no pipes/redirects. The tokenizer is **quote-aware**: quotes are respected during the whitespace split, so a literal `'hello world'` stays one token (the surrounding quotes are then stripped). stdout binds; non-zero exit → op-error routed through `else:` / `# OnError:`.
 
 ```
 shell(command="curl -s 'wttr.in/${LOCATION|url}?format=j1'") -> RAW
 shell(command="git status") -> STATUS
 ```
 
-Structured-spawn sandbox: one binary per call, args parsed structurally, no shell metacharacter interpretation. The structural constraints ARE the security model. stdout binds; non-zero exit → op-error routed through `else:` / `# OnError:`.
+**2. `shell(argv=["bin","arg1","${VAR}",...])` — explicit-argv spawn.** Each list element is exactly one argv token; `${VAR}` substitutes per element and the result is **not re-split**, so an arg containing whitespace, quote characters, JSON, or any dynamic content stays one intact arg. No tokenizer, no quote-matching, no shell — strictly safer than `unsafe=true` (injection-surface zero). This is the right form whenever an arg may contain dynamic or whitespace-bearing content. **Mutex:** `argv=` does not compose with `command=` or `unsafe=true` — it's an execv-class spawn, there is no shell to opt into.
+
+```
+shell(argv=["say","-v","${VOICE}","-f","${PATH}"]) -> OUT
+shell(argv=["jq","-c","${FILTER}","/tmp/data.json"]) -> RESULT
+```
 
-**Unsafe mode:**
+**3. `shell(command="...", unsafe=true)` — full bash.** Required for pipes, redirects, shell built-ins.
 
 ```
 shell(command="for i in $(seq 1 10); do echo $i; done", unsafe=true) -> R
@@ -452,11 +459,26 @@ shell(command="curl -s example.com | jq '.field' > /tmp/out", unsafe=true)
 - Lint flags every `unsafe=true` call as tier-2.
 - Runtime refuses with `UnsafeShellDisabledError` unless deployment sets `runtime.enable_unsafe_shell = true` (default `false`). Compile-time `unsafe-shell-disabled` tier-1 catches at authoring.
 - Audit-visible at every fire.
+- Bash's `$(command)` and arithmetic `$((expr))` pass through to bash without escape because skillscript's substitution is braced (`${VAR}`).
+
+**TWO security gates, not one — structural shape AND a binary allowlist.** The structural constraint (above) governs *how* a command runs (no shell/metacharacters on the safe path). It is HALF the model. The other half is an **operator-owned binary allowlist (default-deny)** governing *which* binary may run at all:
+
+- Every shell op's `argv[0]` (or the first token of `command=`) is checked against the allowlist; a non-allowlisted binary is refused with `ShellBinaryNotAllowedError`, regardless of safe-vs-`unsafe`.
+- **Default is deny-all** — if no allowlist is wired, *every* shell op is refused.
+- Configure via `SKILLSCRIPT_SHELL_ALLOWLIST` env (comma-separated), the `shellAllowlist` field in `skillscript.config.json`, or `bootstrap({ shellAllowlist: [...] })`. The runtime must **restart** to pick up changes. `skillfile shell-audit` scans the corpus and prints the binary union ready to paste.
+- For `unsafe=true`, `bash` itself must be on the allowlist (binary-scope is independent of unsafe-vs-safe).
+- The current allowlist is reported by `runtime_capabilities.shellExecution.allowlist`.
+- **This is an operator boundary the skill author cannot escape** — not via `unsafe`, not via any in-skill mechanism. It scopes *which binary*, not *what the binary does*: allowlisting a powerful authenticated CLI (e.g. `gh`) grants its whole surface, so wrap powerful binaries to least-privilege (a read-only wrapper script on the allowlist instead of the raw binary) before allowlisting.
 
-Bash's `$(command)` and arithmetic `$((expr))` pass through to bash without escape because skillscript's substitution is braced (`${VAR}`).
+**All three forms honor the universal op-level kwargs below**, including `(fallback:)` — the fallback fires on op throw OR empty stdout.
 
 **Pipes need unsafe; sandboxed multi-call + temp file is the unsafe-free alternative.** A pipe (`curl ... | jq ...`) is a shell metacharacter and requires `unsafe=true`. To compute-in-tools without unsafe, split into sequential sandboxed calls sharing a temp file: `shell(command="curl -s -o /tmp/x.json ...")` then `shell(command="jq -c '<filter>' /tmp/x.json") -> R`. Sequential sandboxed calls share the runtime's filesystem within an execution. Caveat: a fixed temp path races under concurrent invocation (no built-in uniquifier short of a `mktemp` call) — for a large fetched intermediate, keeping it in an execution-scoped var + filtering exports via `# Returns:` is usually cleaner than either shell form.
 
+**The `'${VAR}'` quote trap — works in test, breaks on edge input.** Because the structural tokenizer is quote-aware, `shell(command="say -v Jamie '${TEXT}'")` DOES pass a simple multi-word value as one argument — it works for `TEXT="Perry here now"`. That is the trap: it's fragile on the *content* of the substituted value. If `TEXT` contains a quote character (`Jamie's turn`) the quote-matching drifts and the arg breaks — and it fails silently, only on certain inputs, after the pattern already "worked" in testing. Tier-2 lint `shell-quoted-var-in-command` flags the `'${VAR}'`-in-`command=` pattern for exactly this reason and points at `argv=[...]`. Three safe ways to pass an arg that may contain whitespace or quote characters:
+- **`shell(argv=[...])` (preferred):** explicit-token list (form 2 above) — no tokenizer touches the value; the safest because there is no shell and no quote-matching at all.
+- **File-roundtrip:** `file_write(path="/tmp/x.txt", content="${TEXT}")` then `shell(command="say -f /tmp/x.txt")` — the binary reads the value off disk via its own file-input flag; no tokenizer involved. Good when the binary has a file-input mode.
+- **`unsafe=true` + `${TEXT|shell}`:** bash quoting via the POSIX-escape filter; tier-2 lint flags it; injection surface remains if `TEXT` is untrusted.
+
 ### `file_read` / `file_write` — file I/O
 
 ```
@@ -546,7 +568,7 @@ Typed-contract ops (`data_*`, `skill_*`, `json_parse`, `llm`) auto-wire from the
 
 ### Universal op-level kwargs
 
-Four surfaces apply to every `$` dispatch regardless of tool. The runtime intercepts these before forwarding the remaining kwargs to the connector.
+Four surfaces apply to every `$` dispatch and to `shell()` (notably `(fallback:)`), regardless of tool. The runtime intercepts these before forwarding the remaining kwargs to the connector.
 
 **`timeout=N`** — Per-op timeout in **seconds**. Integer literal or `${VAR}` ref. Resolution chain (most-specific wins):
 
@@ -566,13 +588,14 @@ $ amp.amp_olsen_task task_type="scan" timeout=120 -> DISPATCH
 $ data_write content="${REPORT}" tags=["oncall"] approved="morning roundup" -> ACK
 ```
 
-**`(fallback: "value")` trailer** — Fires on dispatch throw OR empty bound value (empty string after trim, empty array, null/undefined). Coerce-on-bind: the fallback value binds to the output var transparently, downstream targets need no conditional. Permissive value parsing — bare identifiers, quoted strings, bracketed array literals all accepted.
+**`(fallback: "value")` trailer** — Fires on dispatch throw OR empty bound value (empty string after trim, empty array, null/undefined). Honored on `$` dispatch and on `shell()` (fires on shell op throw or empty stdout). Coerce-on-bind: the fallback value binds to the output var transparently, downstream targets need no conditional. Permissive value parsing — bare identifiers, quoted strings, bracketed array literals all accepted. A fired fallback is recorded in `result.fallbacks[]`.
 
 Note: an envelope object like `{items: []}` is a non-empty object and does NOT trigger the fallback even though its contained array is empty. To handle envelope-empty downstream, test the contained collection (`if ${R.items|length} == "0":`) or apply a filter (`${R.items|fallback:[]}`).
 
 ```
 $ llm prompt="Classify: ${INPUT}" -> VERDICT (fallback: "unknown")
 $ amp.amp_query_memories query="${TOPIC}" -> RESULTS (fallback: [])
+shell(argv=["gh","pr","list","--repo","acme/foo"]) -> PRS (fallback: "No open PRs")
 $ ticketing.search query="..." -> ISSUES (fallback: "search-unavailable")
 ```
 
@@ -657,7 +680,7 @@ Tool args are unconstrained `key=value` pairs — the connector forwards them to
 
 See the adopter playbook for the substrate config reference + the full Case 2 tradeoff.
 
-**Discovery surface.** `runtime_capabilities` (MCP tool) exposes the registered substrate state. Every entry across all four substrate slots (SkillStore / DataStore / LocalModel / McpConnector) carries its instance `manifest()` payload alongside the static features. Three observable states per entry: working `manifest:{...}`, runtime failure `manifest:null, manifest_error:"..."`, structural absence `manifest:null, manifest_unsupported:true` (AgentConnector only — the contract has no `manifest()` method). The bridge `wraps` convention re-exposes the underlying substrate's full manifest, so adopters reading the discovery surface see the full bound state without traversing multiple entries.
+**Discovery surface.** `runtime_capabilities` (MCP tool) exposes the registered substrate state. Every entry across all four substrate slots (SkillStore / DataStore / LocalModel / McpConnector) carries its instance `manifest()` payload alongside the static features. Three observable states per entry: working `manifest:{...}`, runtime failure `manifest:null, manifest_error:"..."`, structural absence `manifest:null, manifest_unsupported:true` (AgentConnector only — the contract has no `manifest()` method). The bridge `wraps` convention re-exposes the underlying substrate's full manifest, so adopters reading the discovery surface see the full bound state without traversing multiple entries. The `shellExecution` entry reports the operator shell allowlist + mode.
 
 Connector entries also surface `features` declarations (`supports_identity_propagation`, `supports_streaming_responses`, `supports_batch`). Capability flags that span multiple layers — `supports_identity_propagation` requires both the connector's ctx-honoring AND the substrate's per-identity scope honoring — gate via `RuntimeCapabilitiesConformance` auto-coverage: declaring a feature flag true requires the adopter to wire both Level-1 (substrate-independent: ctx reaches transport) and Level-2 (substrate-coupled: distinct identities yield distinct observable scopes) probes via `flagProbes`. Missing probes fail the gate before runtime accepts the flag as true. This is the structural close that prevents the discipline-only-contract pattern (capability claim without honoring impl) from recurring at the capability-flag surface.
 
@@ -667,7 +690,7 @@ Connector entries also surface `features` declarations (`supports_identity_propa
 
 ## Per-op gating
 
-Mutation ops require an authorization signal. The signal is per-op, not a mode binary.
+Two independent authorization layers govern a shell op: **(0) the binary allowlist** — can this binary run at all (operator-owned, default-deny; see the shell section above; refusal is `ShellBinaryNotAllowedError`) — and **(1) the mutation gate** below. The allowlist is checked first and the author cannot bypass it. Beyond shell, mutation ops require an authorization signal. The signal is per-op, not a mode binary.
 
 **Mutation-classified ops:**
 - `file_write(...)` (runtime-intrinsic)
@@ -678,7 +701,7 @@ Mutation ops require an authorization signal. The signal is per-op, not a mode b
 
 **Read-only ops (always allowed, no authorization needed):**
 - `file_read`, `emit`, `notify`, `inline`, `execute_skill`
-- `shell(command=...)` with read-only verb
+- `shell(command=...)` with read-only verb (still subject to the binary allowlist)
 - `$ <connector>.<tool>` against tools declared `mutating: false` (or unspecified, default false for query-shaped tools)
 - `$set`, `$append`
 
@@ -718,7 +741,7 @@ deliver:
 | Runtime-intrinsic | `notify` | `notify(agent="...", [message=...], [event_type=...], [correlation_id=...]) -> ACK` | optional |
 | Runtime-intrinsic | `inline` | `inline(skill="<name>")` | none (compile-time) |
 | Runtime-intrinsic | `execute_skill` | `execute_skill(skill_name="...", inputs={...}) -> R` | optional |
-| Runtime-intrinsic | `shell` | `shell(command="...", [unsafe=true], [approved="..."]) -> R` | optional |
+| Runtime-intrinsic | `shell` | `shell(command="...", [unsafe=true], [approved="..."]) [-> R] [(fallback: "...")]` or `shell(argv=[...], [approved="..."]) [-> R] [(fallback: "...")]` (mutually exclusive forms; binary allowlist applies to both) | optional |
 | Runtime-intrinsic | `file_read` | `file_read(path="...") -> R` | required |
 | Runtime-intrinsic | `file_write` | `file_write(path="...", content="...", [approved="..."])` | none |
 | External MCP — substrate-specific | `$ <connector>.<tool>` | `$ <connector>.<tool> kwarg=value, ... [timeout=N] [approved="..."] [-> R] [(fallback: "...")]` | optional |
@@ -863,7 +886,7 @@ Pipe filters apply transforms to resolved variables before substitution. Syntax:
 | `trim` | Whitespace trim | `${VERDICT|trim}` for `"urgent\n"` | `urgent` |
 | `length` | Count of items (array) or characters (string) | `${ITEMS|length}` for `["a","b","c"]` | `3` |
 | `contains:"X"` | Boolean: type-aware substring / element membership | `${MSG|contains:"urgent"}` for `"Yes, urgent"` | `true` |
-| `fallback:"X"` | Coalesce on missing/undefined ref | `${VAR.missing|fallback:"-"}` | `-` |
+| `fallback:"X"` | Coalesce on missing/undefined/empty ref | `${VAR.missing|fallback:"-"}` | `-` |
 | `isodate` | Epoch seconds → ISO-8601 timestamp | `${EPOCH|isodate}` for `1779660000` | `2026-05-24T22:00:00.000Z` |
 
 ### `length` semantics
@@ -915,16 +938,17 @@ Empty-string match: `${VAR|contains:""}` returns `true` if VAR is bound. Documen
 
 ### `fallback:"X"` semantics
 
-Coalesce-on-missing. Emits the literal string `X` when the ref resolves to missing/null/undefined. Strict-by-default semantics preserved everywhere else; `|fallback:` is the explicit opt-out at the call site.
+Coalesce-on-empty-or-missing. Emits the literal string `X` when the ref resolves to missing/null/undefined OR to an empty string. Strict-by-default semantics preserved everywhere else; `|fallback:` is the explicit opt-out at the call site.
 
 ```
 emit:
-    emit(text="present: ${PRESENT|fallback:\"missing\"}")        # → "hello"  (PRESENT is bound)
-    emit(text="missing: ${NOT_DECLARED|fallback:\"-\"}")          # → "-"      (NOT_DECLARED isn't)
+    emit(text="present: ${PRESENT|fallback:\"missing\"}")        # → "hello"  (PRESENT is bound and non-empty)
+    emit(text="missing: ${NOT_DECLARED|fallback:\"-\"}")          # → "-"      (NOT_DECLARED isn't declared)
+    emit(text="empty:   ${BOUND_EMPTY|fallback:\"-\"}")           # → "-"      (bound to "")
     emit(text="nested:  ${ISSUE.customFields.Assignee|fallback:\"unassigned\"}")
 ```
 
-**Why filter-shape, not ref-level `(fallback:)`.** Op-level `(fallback: ...)` exists on `$` dispatch for **error recovery** (dispatch happened, failed). Ref-level `|fallback:` is **coalesce** (lookup found nothing). They rhyme but are adjacent concepts. The filter-chain attachment keeps composition clean (`${VAR|json_parse|fallback:"-"}` works as a chain step) and the vocabulary alignment with op-level `(fallback:)` lets cold authors learn "fallback" as the universal concept while the syntax disambiguates the attachment site.
+**Why filter-shape, not ref-level `(fallback:)`.** Op-level `(fallback: ...)` exists on `$` dispatch and `shell()` for **error/empty recovery** (the op ran, then failed or returned empty). Ref-level `|fallback:` is **coalesce** (the lookup itself found nothing — missing, null, or empty). They rhyme but are adjacent concepts. The filter-chain attachment keeps composition clean (`${VAR|json_parse|fallback:"-"}` works as a chain step) and the vocabulary alignment with op-level `(fallback:)` lets cold authors learn "fallback" as the universal concept while the syntax disambiguates the attachment site.
 
 **Closes the missing-field strict-error trap**: `${ISSUE.customFields.Assignee}` against an object without that key threw `UnresolvedVariableError` and aborted whole-render. The filter is the per-ref opt-out.
 
@@ -1422,6 +1446,15 @@ A skill may declare multiple output targets, one per line; each receives the sam
 # Output: agent: assistant
 ```
 
+## Output target resolution
+
+For the `agent:` and `template:` kinds, the runtime resolves the target agent_id via a **2-level chain** (first match wins):
+
+1. **Explicit name** — `# Output: agent: perry` delivers to agent_id `perry`.
+2. **`${VAR}` compile-time substitution** — `# Output: agent: ${RECIPIENT}` resolves against the resolved inputs map (`# Vars:` defaults, `# Requires:` cascade, caller-supplied `inputs`) at compile time. Only compile-time inputs resolve here — a runtime-bound ref (an op's `-> VAR` output, an ambient ref) passes through verbatim and fails at delivery if still unresolved.
+
+There is **no** invocation-context inheritance and **no** runtime `default_agent_id` fallback: a skill must name its target explicitly or pass it as an input var. See the Connectors section (AgentConnector) for the full delivery contract behind the resolved id.
+
 ## Per-kind output value semantics
 
 What each kind consumes as the output, in precedence order:
@@ -1595,16 +1628,17 @@ Nested `# OnError:` is *not* supported. If `# OnError: degraded-skill` fires and
 
 ## Layer 3: Op-level fallback values
 
-Inline fallback declared on the op line. Used when the call fails or returns empty. Supported on `$` (MCP dispatch) ops with coerce-on-bind semantics.
+Inline fallback declared on the op line. Used when the call fails or returns empty. Supported on `$` (MCP dispatch) ops and on `shell()` with coerce-on-bind semantics. For `shell()` the fallback fires on op throw OR empty stdout (e.g. `gh pr list` against a repo with no open PRs binds the fallback string).
 
 ```
 weather:
     $ data_read mode=fts query="weather ${LOCATION}" limit=1 -> CURRENT (fallback: "weather unavailable")
     $ llm prompt="Summarize: ${CURRENT}" -> SUMMARY (fallback: "summary unavailable")
     $ slack.post channel=${CHANNEL} text=${SUMMARY} (fallback: "post failed silently") -> ACK
+    shell(argv=["gh","pr","list","--repo","acme/foo"]) -> PRS (fallback: "No open PRs")
 ```
 
-Same pattern as the `# Requires:` cascade's `(fallback: ...)` syntax — consistent across compile-time (`# Requires:`) and runtime (`$` dispatch).
+Same pattern as the `# Requires:` cascade's `(fallback: ...)` syntax — consistent across compile-time (`# Requires:`) and runtime (`$` dispatch and `shell()`).
 
 **Fallback value parsing.** Permissive: bare identifiers, quoted strings, and bracketed array literals all accepted. Matches the `# Requires:` cascade convention.
 
@@ -1632,7 +1666,7 @@ Open spec question: should `${ERROR}` be ambient inside `else:` blocks (same sha
 
 Same idea at every scope:
 - Compile-time: `# Requires: ... (fallback: value)`
-- Runtime op: `$ dispatch ... (fallback: value)`
+- Runtime op: `$ dispatch ... (fallback: value)` and `shell(...) ... (fallback: value)`
 - Runtime target: `else:` block
 - Whole skill: `# OnError:` header
 
@@ -1640,7 +1674,7 @@ Authors composing complex skills use these in combination — op-level for trans
 
 ## Connection to runtime observability
 
-Per-op error contract is what makes cascading fallbacks work. When `$` returns `isError: true`, the executor throws via `makeOpError` rather than binding the error text to the output var. The throw routes through `else:` / `# OnError:` machinery and surfaces in `result.errors[]` for the scheduler to log. Without this discipline, op-level failures wouldn't propagate to the fallback layers and silent-fail would be the default.
+Per-op error contract is what makes cascading fallbacks work. When `$` returns `isError: true`, the executor throws via `makeOpError` rather than binding the error text to the output var. The throw routes through `else:` / `# OnError:` machinery and surfaces in `result.errors[]` for the scheduler to log. Without this discipline, op-level failures wouldn't propagate to the fallback layers and silent-fail would be the default. Op-level `(fallback:)` is distinct: it intercepts the throw/empty-result at the op and binds the fallback value rather than propagating — a fired fallback is recorded in `result.fallbacks[]`, not `result.errors[]`.
 
 ## Composition — skills calling skills
 
@@ -2208,5 +2242,5 @@ Hung dispatches hang the skill without explicit timeout configuration. Lean: ski
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-06-08 17:41 EDT*  
+*Rendered from `skillscript/skillscript-language-reference` — 2026-06-15 12:22 EDT*  
 *Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*

package/examples/skillscripts/classify-support-ticket.skill.md

@@ -1,5 +1,5 @@
 # Skill: classify-support-ticket
-# Status: Approved v1:670a94cf
+# Status: Approved v1:ae27d3f9
 # Autonomous: true
 # Description: Read an incoming support ticket and route it: severity-1 tickets get paged to ops-channel, billing tickets get tagged for finance review, everything else gets a draft reply queued for human review
 # Vars: TICKET_TEXT, TICKET_ID
@@ -14,13 +14,13 @@ severity_check:
 
 route:
     needs: severity_check
-    if ${CATEGORY|trim} == "sev-1":
+    if ${CATEGORY|contains:"sev-1"}:
         emit(text="PAGE: sev-1 ticket ${TICKET_ID} - ${TICKET_TEXT}")
         $ data_write content="sev-1 ticket ${TICKET_ID}: ${TICKET_TEXT}" tags=["support","sev-1","page"]
-    elif ${IS_SEV1|trim} == "yes":
+    elif ${IS_SEV1|contains:"yes"}:
         emit(text="PAGE: classifier said ${CATEGORY|trim} but severity-check flagged this as sev-1: ${TICKET_ID}")
         $ data_write content="sev-1 escalation ${TICKET_ID}: category=${CATEGORY|trim} but severity-check=yes" tags=["support","sev-1","disagreement"]
-    elif ${CATEGORY|trim} == "billing":
+    elif ${CATEGORY|contains:"billing"}:
         $set TAG_FOR = "finance"
         emit(text="Tagged for ${TAG_FOR} review: ${TICKET_ID}")
         $ data_write content="billing ticket ${TICKET_ID}: ${TICKET_TEXT}" tags=["support","billing"]