skillscript-runtime 0.19.12 → 0.19.14

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}`).
 
-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.
+
+**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:
@@ -1462,6 +1495,290 @@ The receiving agent reads `event_type` for routing ("911 — surface now" vs "ro
 
 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.
 
+## Connectors — substrate routing, the five connector types, agent_id resolution
+
+The substrate-routing ops (`$ connector.tool`, `$ data_read`, `$ llm`) and the agent-bound `# Output:` kinds (`agent:`, `template:`) don't call any specific backend directly. They route through thin connector interfaces. Skill source persistence follows the same pattern via a dedicated contract. This is the programmable surface through which authors compose information topology per skill and per moment. Skills are portable across substrates because the language doesn't bake substrate identity into the source.
+
+## Five connector types
+
+### MemoryStore
+
+Routes `$ data_read` retrieval ops. Interface: `MemoryStore.query(filters) → PortableMemory[]`.
+
+Implementations vary by deployment — a knowledge-substrate-backed store, a SQLite-backed store, a vector-DB-backed store, an in-memory test store. All conform to the `MemoryStore.query` contract and return `PortableMemory[]`.
+
+### LocalModel
+
+Routes `$ llm` local-model ops. Interface: `LocalModel.run(prompt, opts) → string`.
+
+Default impl wraps a local-model HTTP service (e.g., Ollama). Constructor takes `{ model: string }` (required) — no class-level implicit default. Multiple instances by name in the registry; each backed by a distinct model tag.
+
+### McpConnector
+
+Routes `$ connector.tool` MCP-tool ops. Interface: `McpConnector.call(toolName, args, ctxOverrides?) → unknown`.
+
+Implementations include adapters wrapping in-process tool dispatch (when the runtime is embedded in a host that already has MCP tools) and HTTP-based MCP clients (when calling out to remote MCP servers). All conform to the `McpConnector.call` contract.
+
+**Bare-name dispatch.** `$ TOOL` (no connector prefix) routes through the `primary` McpConnector entry in the registry. If no `primary` is wired, the runtime throws `ConnectorNotFoundError` at runtime AND fires tier-1 `unwired-primary-connector` lint at compile time. The remediation diagnostic includes both fix paths: add `primary` to connectors.json, or qualify the op as `$ named.TOOL`. Failing loud is the correct mode for autonomous-pattern skills — a silent stub would let an autonomous skill appear to succeed while doing nothing.
+
+### AgentConnector
+
+Routes the agent-bound `# Output:` kinds — `agent:` (Augmenting) and `template:` (Template) per the skill-kind taxonomy in Section 1. Interface:
+
+```typescript
+interface AgentConnector {
+  list_agents(): Promise<AgentDescriptor[]>;
+  deliver(agent_id: string, payload: DeliveryPayload): Promise<DeliveryReceipt>;
+  wake(agent_id: string, opts?: WakeOpts): Promise<WakeReceipt>;
+  agent_status?(agent_id: string): Promise<AgentStatus>;
+}
+
+type DeliveryPayload =
+  | { kind: "augment"; content: string; format?: "text" | "markdown"; source_skill?: string; triggered_by?: TriggerProvenance; delivery_context?: string; templates?: string[] }
+  | { kind: "template"; prompt: string; source_skill?: string; triggered_by?: TriggerProvenance; delivery_context?: string; templates?: string[] };
+
+type TriggerProvenance = {
+  source: "cron" | "session" | "event" | "agent-event" | "file-watch" | "sensor" | "manual";
+  name: string;            // e.g. "0 8 * * *", "session:start", "manual"
+  fired_at_ms: number;     // unix ms timestamp
+};
+
+type DeliveryReceipt = { delivered_at: number; delivery_id?: string };
+
+type WakeOpts = {
+  context?: string;
+  when?: "immediate" | number;
+};
+
+type WakeReceipt = { woken_at: number; session_id?: string };
+
+type AgentDescriptor = {
+  agent_id: string;
+  agent_name?: string;
+  capabilities?: ("deliver" | "wake" | "augment" | "template")[];
+};
+
+type AgentStatus = "active" | "idle" | "asleep" | "unknown";
+```
+
+The `agent:` Output kind produces a `DeliveryPayload` of kind `augment`; `template:` produces one of kind `template`.
+
+Two primary verbs (`deliver` + `wake`), one mandatory discovery method (`list_agents`), one optional status method. The contract is substrate-neutral; adopters wire any delivery mechanism behind it:
+
+| Substrate | `deliver` impl | `wake` impl |
+|---|---|---|
+| tmux session | `tmux send-keys` to a pane | `tmux send-keys` with wake prompt |
+| webhook | POST to `/augment` or `/template` endpoint | POST to `/wake` endpoint |
+| memory store | write a memory record with delivery tag | write addressed memory + push notification |
+| file-watch | write to `<path>/augment-<id>.txt` | write to `<path>/wake-<id>.txt` |
+| chat thread | post to monitored thread | post + @mention |
+| IPC named pipe | write to delivery pipe | write to wake pipe |
+
+Default impl `NoOpAgentConnector` logs warnings and resolves; lets the runtime ship without an agent-delivery substrate wired. Adopter impls run the bundled `AgentConnectorConformance` suite to verify their substrate wiring.
+
+#### DeliveryPayload provenance fields
+
+Every `deliver` call carries optional provenance the receiving agent uses to disambiguate the source and context of the delivery:
+
+- `source_skill?: string` — name of the skill that produced this delivery. Lets the receiver attribute the content to a specific authored skill, distinguishing "this is from the stock-monitor skill" from "this is from the news-brief skill."
+- `triggered_by?: TriggerProvenance` — why the skill fired. Receiver disambiguates cron tick (autonomous), session-start (lifecycle), event-driven (external signal), manual (user-requested), etc. Carries the trigger source + name + unix-ms timestamp.
+- `delivery_context?: string` — prose explanation of why the agent is being notified and what to do with the content. Populated from the `# Delivery-context:` header (see Section 7).
+- `templates?: string[]` — list of Template-kind skill names the receiver can fetch as follow-on actions. Populated from the `# Templates:` header (see Section 7).
+
+The runtime threads these from `ExecuteContext.triggerCtx` (set at dispatch) and `ParsedSkill.deliveryContext` / `ParsedSkill.templates` (set at parse) through to the `deliver` call site.
+
+#### `agent_id` resolution
+
+When `# Output: agent:` or `# Output: template:` fires, the runtime resolves the target agent_id via a 2-level chain (first match wins):
+
+1. **Explicit name in the `# Output:` line** — `# Output: agent: perry` dispatches 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. Caveat: only compile-time inputs resolve here — runtime-bound refs (a target's output var, ambient refs) pass through verbatim and fail at delivery if still unresolved.
+
+Invocation-context inheritance and a runtime-config `default_agent_id` fallback are NOT implemented: `# Output: agent:` does not auto-inherit the caller's identity, and there is no default-agent fallback. A skill must name its target explicitly or pass it as an input var.
+
+#### Output-kind classification in the runtime
+
+The runtime's `TEXT_COERCED_OUTPUT_KINDS` set classifies output kinds by payload shape (text vs structured), not by semantic destination. Membership controls payload coercion; it doesn't bake destination identity into the runtime.
+
+### SkillStore
+
+Routes skill source persistence. Interface:
+
+```typescript
+interface SkillStore {
+  get(name: string): Promise<SkillRecord | null>;
+  write(name: string, body: string): Promise<void>;
+  list(): Promise<SkillDescriptor[]>;
+  delete(name: string): Promise<void>;
+}
+```
+
+Bundled impls: `FilesystemSkillStore` reads and writes `.skill.md` source plus `.skill` compiled output and `.skill.provenance.json` sidecar in a configured directory; the standard for file-backed deployments. Substrate-specific impls live in adopter packages (memory-backed stores live in the substrate's adapter repo).
+
+Skill records are infrastructure, not knowledge atoms — adopter impls should treat skills as first-class long-lived records, not as candidates for substrate-level garbage collection.
+
+## Capabilities discovery
+
+All connector types expose `capabilities()` for runtime discovery. Consumers:
+1. `# Requires:` matching against the registered set
+2. Dynamic queries via `listMemoryStores()` / `listLocalModels()` / `listMcpConnectors()` / `listAgentConnectors()` to pick a connector for the moment
+3. Authoring tools that surface the registered set
+
+## Multi-instance by design
+
+Multiple instances of the same connector type are the *normal case*, not the exception.
+
+```
+{
+  primary: MemoryStoreImplA,
+  project: SqliteProjectStore,
+  scratch: InMemoryStore
+}
+```
+
+```
+{
+  default: OllamaLocalModel({model: "gemma2:9b"}),
+  gemma2:  OllamaLocalModel({model: "gemma2:9b"}),
+  qwen:    OllamaLocalModel({model: "qwen2.5:7b"})
+}
+```
+
+```
+{
+  primary: PrimaryMcpConnector,
+  personal: HttpMcpConnector,
+  project: HttpMcpConnector
+}
+```
+
+Per-skill resolution against named connectors is first-class; an unnamed lookup returns the configured default. Multiple keys pointing at the same underlying instance configuration are allowed and useful — see the `default`/`gemma2` alias below.
+
+## Model selection — choosing among LocalModel instances
+
+The LocalModel registry holds multiple instances by design. Skill authors choose which to dispatch to via `$ llm model="<name>"`. Two layers of indirection are involved, and the distinction matters for both authoring and adopter configuration:
+
+1. **Skillscript name → registered instance.** `$ llm model="qwen"` references the instance keyed `qwen` in the registry. The registry resolves to the configured connector implementation.
+2. **Registered instance → underlying model.** Each `OllamaLocalModel` is constructed with the actual model tag (e.g. `qwen2.5:7b`). The skill never sees the tag directly.
+
+### Example instance names
+
+| Name | Underlying model | Notes |
+| --- | --- | --- |
+| `default` | `gemma2:9b` | Resolved when `model=` is omitted; alias of `gemma2` |
+| `gemma2` | `gemma2:9b` | Explicit name; matches the convention below |
+| `qwen` | `qwen2.5:7b` | Interactive, latency-sensitive |
+
+`default` and `gemma2` can point at the same `OllamaLocalModel` configuration. The alias exists so skill syntax can match a tier convention ("use gemma2 for batch") rather than the back-compat name (`default`). Skills that write `model="default"` work unchanged; prefer the explicit name.
+
+### Convention: model tier by use case
+
+- **Small classification-class model** (e.g., `gemma2`) for *batch and scan work* — atomization, large-batch classification, anything async or background-scheduled.
+- **Longer-context dispatch-class model** (e.g., `qwen`) for *interactive verdicts in skills* — single-shot decisions inside an active dispatch where latency matters and queue contention with batch work would block forward progress.
+
+When in doubt: small model if the call is asynchronous from a user/agent's perspective, larger model if a downstream op depends on the response.
+
+### Contention property
+
+Any skill that calls `$ llm` shares the underlying local-model service with every other process on the deployment that dispatches to the same model. Most local-model services serialize per-model dispatch. A skill that fires asynchronous batch work via `$` (e.g. invoking a batch-classification tool that dispatches N calls to model X) and then immediately calls `$ llm model="X"` will race itself — the synchronous call queues behind the dispatched batch.
+
+The runtime does not promise concurrency-safe model dispatch. Skill authors and operators own model-tier allocation. The canonical mitigation: use distinct models for the synchronous and asynchronous paths (a smaller model for interactive verdicts, a larger model for batch).
+
+### Adopter deployments
+
+Adopters override the bundled set via `connectors.json`:
+
+```jsonc
+{
+  "localModels": {
+    "default": { "type": "OllamaLocalModel", "model": "llama3.2:3b" },
+    "fast":    { "type": "OllamaLocalModel", "model": "phi3:mini" }
+  }
+}
+```
+
+Adopters with no local models register no LocalModel instances. Skills with `$ llm` ops fail at dispatch with `LocalModel '<name>' not registered`. A `# Requires:` capability declaration promotes this to a compile-time fail-fast — a skill that requires LocalModel won't compile if none is configured. Substrate-blind skills (no `$ llm` ops) work unchanged.
+
+## Configuration: substrate selection vs operator config
+
+Two distinct concerns, often conflated. Keep them separate.
+
+**Substrate-class selection** — *which* connector implementation fills each slot. Configured via `connectors.json` `substrate.<slot>` entries, or programmatically via `bootstrap()` options. This is what makes a skill portable: the slot is named in config, never in the skill source. Connectors are runtime-resolved — the compiler stays pure read+transform, and compiled artifacts are generic, so any runtime can dispatch them through whatever substrates it has wired.
+
+**Operator-runtime config** — the per-knob runtime settings: `SKILLSCRIPT_*` env vars, `skillscript.config.json`, and `bootstrap()` options. These tune runtime behavior; they do not select substrate classes.
+
+Precedence (first wins): explicit `bootstrap()` option > env var > config file > bundled default.
+
+Per-deployment naming lives in config, not the contract. A given deployment registers concrete instances under whatever names make sense locally; skill authors reference those names.
+
+The `connectors.json` loader handles literal + `${ENV_VAR}` credential resolution, file-discovery via `$SKILLSCRIPT_HOME`, and a class registry recognizing the bundled connector classes (including `CallbackMcpConnector` and `RemoteMcpConnector`). The per-connector `allowed_tools` field constrains dispatch surface for safe defaults — a cold-author skill against the connector can only invoke allowlisted tools. See ERD §3 + §4 for the full credential-discipline contract.
+
+## Per-call identity overrides (McpConnector)
+
+A skill running under one identity can dispatch against a personal MCP server under a different identity without needing connector-internal state. The merge order at dispatch (top wins):
+
+1. **Registry-configured per-connector identity** — set in `connectors.json` (`identity: { agentId: "<id>", isAdmin: false }`) at connector instantiation. Locks an identity to a connector.
+2. **Per-call `ctxOverrides`** — threaded by the runtime per the security boundary contract. A skill running as agent X passes `{ agentId: "X", isAdmin: false }` into every `$` op.
+3. **(no intrinsic identity)** — adapter forwards whatever the merge produces.
+
+Configured identity is a *partial merge* — unmentioned keys (e.g., `isAdmin`) flow through from the per-call ctx. Lets a connector lock `agentId` without clobbering the runtime's admin-drop discipline. Default connectors should configure no intrinsic identity, so `ctxOverrides` always wins — preserving the runtime's authority-flow guarantees intact.
+
+## Portable shapes
+
+```typescript
+interface PortableMemory {
+  // Core fields — mandatory on every connector return.
+  id: string;
+  summary: string;
+  detail?: string;
+  score?: number;
+
+  // Curated substrate subset — concept-portable, value-substrate-specific.
+  // Top-level access via $(MEMORY.field). Connectors populate when the
+  // concept applies. MUST NOT also be duplicated into metadata.
+  thread_status?: string;
+  pinned?: boolean;
+  confidence?: number;
+  domain_tags?: string[];
+  payload_type?: string;
+  knowledge_type?: string;
+  recipients?: string[];
+  expires_at?: number;
+  created_at?: number;
+  agent_id?: string;
+  vault?: string;
+
+  // Substrate-specific bag. Accessed via $(MEMORY.metadata.X).
+  metadata?: Record<string, unknown>;
+}
+
+interface QueryFilters {
+  query: string;
+  limit: number;
+  mode: "fts" | "semantic" | "rerank" | string;
+  [key: string]: unknown;
+}
+
+interface McpDispatchCtx {
+  agentId?: string;
+  isAdmin?: boolean;
+}
+```
+
+## Field access semantics
+
+`$(MEMORY.field)` resolves in tiers:
+1. Core fields (id, summary, detail, score)
+2. Curated substrate subset (thread_status, pinned, etc.)
+3. `metadata.X` for everything else
+4. Ambient passthrough as literal `$(MEMORY.field)` if unresolved
+
+**Connector duplication is a contract violation.** If a field is in the curated subset, the connector populates it at top-level only — `metadata.<same_name>` MUST be absent. Otherwise `$(M.thread_status)` and `$(M.metadata.thread_status)` can return different values (silent data divergence). Connectors enforce.
+
+## Why connector abstraction matters
+
+Hard-coupling skills to specific substrates would make information-flow decisions infrastructural rather than skill-authored, defeating the point of skills as the agent's programming language. The connector layer is what lets the same skill body run against substrate A today and run against substrate B tomorrow without rewriting.
+
 ## Lifecycle and status — # Status: header, six canonical states, compile + runtime enforcement
 
 Skillscripts carry an explicit lifecycle state via the `# Status:` header. The compiler and runtime enforce status — a Disabled skillscript cannot fire under any path, regardless of who invokes it.
@@ -1595,16 +1912,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 +1950,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 +1958,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 +2526,5 @@ Hung dispatches hang the skill without explicit timeout configuration. Lean: ski
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-06-08 17:41 EDT*  
-*Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*
+*Rendered from `skillscript/skillscript-language-reference` — 2026-06-15 18:44 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"]

package/examples/skillscripts/feedback-sentiment-scan.skill.md

@@ -1,29 +1,18 @@
 # Skill: feedback-sentiment-scan
-# Status: Approved v1:4484f7e0
-# Autonomous: true
-# Description: Each night, scan the previous 24h of customer feedback records, classify sentiment via local model, surface entries where sentiment is "frustrated" or "blocking" so the team sees them at start-of-day; skip entries already seen on prior nights
+# Status: Approved v1:2b4868c1
+# Description: Each night, scan the previous 24h of customer feedback records, classify sentiment via the local model, and surface entries that read 'frustrated' or 'blocking' so the team sees them at start-of-day.
 # Triggers: cron: 0 3 * * *
 # Vars: SCAN_LIMIT=50
 # Output: agent: support-lead
 
-fetch_new:
+scan:
     $ data_read mode=fts query="customer feedback" limit=${SCAN_LIMIT} -> FEEDBACK
-
-fetch_seen:
-    $ data_read mode=fts query="sentiment-scan seen marker" limit=200 domain_tags=["sentiment-scan-seen"] -> SEEN_MARKERS
-
-classify_and_emit:
-    needs: fetch_new, fetch_seen
     emit(text="Sentiment scan results for ${NOW}:")
     foreach F in ${FEEDBACK.items}:
-        if ${F.id|trim} in ${SEEN_MARKERS.items}:
-            emit(text="- skipped (already classified): ${F.id|trim}")
-        elif ${F.id|trim} not in ${SEEN_MARKERS.items}:
-            $ llm prompt="Classify the sentiment of this customer feedback. Respond with ONE word: 'frustrated', 'blocking', 'satisfied', 'neutral'. No explanation.\n\nFeedback: ${F.summary}\nDetail: ${F.detail}" maxTokens=10 -> VERDICT
-            if ${VERDICT|trim} == "frustrated":
-                emit(text="- FRUSTRATED [${F.id|trim}] ${F.summary}")
-            elif ${VERDICT|trim} == "blocking":
-                emit(text="- BLOCKING [${F.id|trim}] ${F.summary}")
-            $ data_write content="sentiment-scan seen ${F.id|trim} verdict=${VERDICT|trim} on ${EVENT.fired_at_unix}" tags=["sentiment-scan-seen"] expires_at=${EVENT.fired_at_plus_7d_unix} -> ACK
+        $ llm prompt="Classify the sentiment of this customer feedback. Respond with ONE word: 'frustrated', 'blocking', 'satisfied', 'neutral'. No explanation.\n\nFeedback: ${F.summary}\nDetail: ${F.detail}" maxTokens=10 -> VERDICT
+        if ${VERDICT|contains:"frustrated"}:
+            emit(text="- FRUSTRATED [${F.id|trim}] ${F.summary}")
+        elif ${VERDICT|contains:"blocking"}:
+            emit(text="- BLOCKING [${F.id|trim}] ${F.summary}")
 
-default: classify_and_emit
+default: scan

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-14T23:43:07.465Z",
+  "compiled_at": "2026-06-15T23:23:33.053Z",
   "source_skill": {
     "name": "hello-world"
   },

package/examples/skillscripts/morning-brief.skill.md

@@ -1,6 +1,6 @@
 # Skill: morning-brief
-# Status: Approved v1:b79223f1
-# Description: Compose a daily morning brief from calendar, mailbox, and overnight data writes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc. The `model=qwen` value below is a representative alias — adopters register a LocalModel under whatever name fits their setup (the bundled bootstrap registers one as `default`).
+# Status: Approved v1:1530981d
+# Description: Compose a daily morning brief from calendar, mailbox, and overnight notes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc. Requires a `calendar` connector configured in connectors.json (the dotted `$ calendar.*` form). `model=qwen` is a representative LocalModel alias — adopters register one under whatever name fits (the bundled bootstrap registers `default`).
 # Vars: AGENT, BRIEF_HORIZON_HOURS=24
 # Triggers: cron: 0 7 * * *
 # OnError: morning-brief-degraded
@@ -12,10 +12,10 @@ calendar:
     $ calendar.list_events horizon_hours=${BRIEF_HORIZON_HOURS} -> EVENTS
 
 mailbox:
-    $ data_read mode=fts query="addressed:${AGENT} created_after:${EVENT.fired_at_unix}" limit=10 -> MAIL
+    $ data_read mode=fts query="messages for ${AGENT}" limit=10 -> MAIL
 
 overnight:
-    $ data_read mode=rerank query="overnight writes since:${EVENT.fired_at_plus_1d_unix}" limit=15 -> NOTES
+    $ data_read mode=rerank query="overnight notes and writes" limit=15 -> NOTES
 
 compose: needs: calendar, mailbox, overnight
     $ llm prompt="Compose a concise morning brief. Calendar: ${EVENTS|json}. Mailbox: ${MAIL|json}. Overnight notes: ${NOTES|json}. Three sections, six bullets max each." model=qwen maxTokens=1200 -> BRIEF

package/examples/skillscripts/queue-length-monitor.skill.md

@@ -1,6 +1,6 @@
 # Skill: queue-length-monitor
-# Description: Count pending items in a queue and alert when the count exceeds threshold
-# Status: Approved v1:1ad57c87
+# Status: Approved v1:c6bc06df
+# Description: Count pending items in a queue and alert when the count exceeds threshold. Requires `cat` on the operator's shell allowlist (default-deny: a non-allowlisted binary is refused).
 # Vars: QUEUE_PATH=/var/queue/pending.json, THRESHOLD=10
 # Triggers: cron: */5 * * * *