skillscript-runtime 0.23.1 → 0.25.0

package/dist/secrets.js

@@ -0,0 +1,153 @@
+/**
+ * Secret references (v0.25.0). A skill names a secret with `{{secret.NAME}}`;
+ * the runtime resolves it ONLY at a sink (a `shell(...)` op or a `$`
+ * connector dispatch) and injects the value use-only — the resolved value
+ * never binds to a skill variable, never lands in a trace, an emit, an
+ * `# Output:`, or any other readable surface. This is deliberately distinct
+ * from `${VAR}` readable substitution (`substituteRuntime`), which resolves
+ * the skill var scope (inputs / `$set` / op outputs / built-ins) and CANNOT
+ * reach a secret: `substituteRuntime` never touches a `{{...}}` marker, so a
+ * marker that slips onto a readable surface stays an inert literal rather
+ * than leaking a value.
+ *
+ * Source abstraction. `SecretProvider.resolve(name, ctx)` is the single seam.
+ * The `.env`-backed `EnvSecretProvider` ships today; a vault-backed provider
+ * drops in later with no caller change because `ctx` ALREADY carries the
+ * principal (`skillName`) that a per-script-sealed vault provider will key on.
+ * Nothing about the call sites assumes the env backing.
+ *
+ * See the dev-log secret-references design (memory 232bcfc9) for the full
+ * arc; this module is its first buildable slice.
+ */
+/** Thrown by a provider when a referenced secret has no provisioned value. */
+export class SecretNotProvisionedError extends Error {
+    secretName;
+    remediation;
+    constructor(secretName, 
+    /** Operator-facing remediation (how to provision it). */
+    remediation) {
+        super(`Secret '${secretName}' is referenced but not provisioned. ${remediation}`);
+        this.secretName = secretName;
+        this.remediation = remediation;
+        this.name = "SecretNotProvisionedError";
+    }
+}
+/**
+ * Environment-variable secret backing. A `{{secret.NAME}}` marker resolves
+ * the env var `SKILLSCRIPT_SECRET_NAME`. The prefix is deliberate: it scopes
+ * which environment is secret-reachable, so a skill cannot pull an arbitrary
+ * process env var (`{{secret.PATH}}` looks for `SKILLSCRIPT_SECRET_PATH`, not
+ * `$PATH`). The operator provisions secrets in `.env`; a skill author names
+ * them but cannot read them back.
+ */
+export class EnvSecretProvider {
+    env;
+    /** Env prefix that scopes which vars are reachable as secrets. */
+    static PREFIX = "SKILLSCRIPT_SECRET_";
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    async resolve(name, _ctx) {
+        const key = EnvSecretProvider.PREFIX + name;
+        const value = this.env[key];
+        if (value === undefined || value === "") {
+            throw new SecretNotProvisionedError(name, `Set ${key} in the runtime environment (the operator's .env) and restart the runtime. ` +
+                `Secrets are operator-provisioned; a skill author references them by name but cannot set or read them.`);
+        }
+        return value;
+    }
+}
+/**
+ * Op kinds permitted to contain `{{secret.NAME}}` markers — the "sinks."
+ * A marker in any OTHER position (emit, `$set`, `# Output:`, conditions,
+ * `file_*`, notify) is a lint tier-1 error, because the value would land on a
+ * readable or emittable surface. Adding a new sink (e.g. a future `notify`
+ * that needs a key) is two edits with no redesign: wire that handler to call
+ * {@link expandSecretMarkers} and append its op kind here. Kept minimal on
+ * purpose (Scott 2026-06-28: "don't design yourself into a corner" — a list,
+ * not a rewrite). This is the single source of truth shared by lint + runtime.
+ */
+export const SECRET_SINK_OP_KINDS = ["shell", "$"];
+/**
+ * Secret placement marker: `{{secret.NAME}}`, whitespace-tolerant inside the
+ * braces. NAME is an identifier (`[A-Za-z_]\w*`); the `secret.` namespace is
+ * reserved. Double-brace + reserved namespace keeps it disjoint from `${VAR}`
+ * / `$(VAR)` readable refs so the two resolution passes never collide.
+ * Global flag: used for both scan and replace.
+ */
+const SECRET_MARKER = /\{\{\s*secret\.([A-Za-z_]\w*)\s*\}\}/g;
+/** True iff `text` contains at least one `{{secret.NAME}}` marker. */
+export function hasSecretMarker(text) {
+    SECRET_MARKER.lastIndex = 0;
+    return SECRET_MARKER.test(text);
+}
+/** Distinct secret names referenced by `{{secret.NAME}}` markers in `text`. */
+export function extractSecretRefs(text) {
+    // SECRET_MARKER is a shared global regex; `matchAll` copies its `lastIndex`,
+    // so reset first or a prior `.test()` (hasSecretMarker) would start the scan
+    // mid-string and miss leading markers.
+    SECRET_MARKER.lastIndex = 0;
+    const names = new Set();
+    for (const m of text.matchAll(SECRET_MARKER))
+        names.add(m[1]);
+    return [...names];
+}
+/**
+ * Detects any `{{secret.…}}` occurrence that is NOT a well-formed static
+ * `{{secret.NAME}}` marker — a dynamic interior (`{{secret.${VAR}}}`), an
+ * empty name, a filter/extra content, etc. The secret name MUST be a
+ * compile-time literal: a dynamically-built name would let `${VAR}`
+ * substitution choose (or fabricate) the secret at runtime, evading the
+ * declare-before-spend gate and the approver-visible `# Requires` reach.
+ * Returns the offending raw substrings (empty when all markers are static).
+ * (Perry red-team `d8a5ad0a` Bug A, fix #3.)
+ */
+export function findMalformedSecretMarkers(text) {
+    const out = [];
+    // `[^}]*` so a `{{secret.${NM}}}` dynamic interior is captured (not skipped).
+    const anyMarker = /\{\{\s*secret\.[^}]*\}\}/g;
+    for (const m of text.matchAll(anyMarker)) {
+        if (!/^\{\{\s*secret\.[A-Za-z_]\w*\s*\}\}$/.test(m[0]))
+            out.push(m[0]);
+    }
+    return out;
+}
+/**
+ * Replace every `{{secret.NAME}}` marker in `text` with its resolved value.
+ * Async — a vault provider does I/O. Returns `text` unchanged when it holds
+ * no markers, so a sink handler may call this unconditionally on any input.
+ * Fails closed: an unprovisioned secret throws (never substitutes empty).
+ *
+ * The returned string is USE-ONLY: pass it straight to the sink (spawn argv,
+ * connector arg) and never bind it to a var, emit it, or write it to a trace.
+ * Resolve happens here, at the sink boundary, precisely so the value's
+ * lifetime is the single dispatch call.
+ */
+export async function expandSecretMarkers(text, provider, ctx, 
+/** Optional sink for each resolved value — lets a caller build a redaction
+ * set so a leaked value can be scrubbed from error/trace output (Perry
+ * Bug B fix #2, belt-and-suspenders). */
+onResolve) {
+    if (!hasSecretMarker(text))
+        return text;
+    // Resolve each distinct name once (a marker may repeat), then splice.
+    const resolved = new Map();
+    for (const name of extractSecretRefs(text)) {
+        const value = await provider.resolve(name, ctx);
+        resolved.set(name, value);
+        onResolve?.(name, value);
+    }
+    return text.replace(SECRET_MARKER, (_m, name) => resolved.get(name));
+}
+/**
+ * {@link expandSecretMarkers} over a list (the `shell(...)` argv form, where
+ * each element is substituted independently). Markerless elements pass
+ * through untouched.
+ */
+export async function expandSecretMarkersInList(items, provider, ctx, onResolve) {
+    const out = [];
+    for (const item of items)
+        out.push(await expandSecretMarkers(item, provider, ctx, onResolve));
+    return out;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"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"}

package/dist/skill-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-catalog.d.ts","sourceRoot":"","sources":["../src/skill-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnG,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,aAAa,CAAC;AAaxE;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,UAAU,EACtB,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAyEvB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC5B,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAsBZ"}
+{"version":3,"file":"skill-catalog.d.ts","sourceRoot":"","sources":["../src/skill-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnG,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,aAAa,CAAC;AAaxE;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,UAAU,EACtB,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,YAAY,CAAC,CA0EvB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC5B,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAuBZ"}

package/dist/skill-catalog.js

@@ -73,6 +73,7 @@ export async function buildSkillCatalog(skillStore, filter = {}) {
                 triggers: [],
                 returns: [],
                 requires: [],
+                secret_requires: [],
                 effectful_footprint: EMPTY_FOOTPRINT,
                 ...(meta.author !== undefined ? { author: meta.author } : { author: null }),
             });
@@ -111,6 +112,7 @@ export function buildEntry(name, description, status, parsed, author) {
         // capability gate uses). All free — the source is already parsed.
         returns: parsed.returns,
         requires: parsed.requires,
+        secret_requires: parsed.secretRequires,
         effectful_footprint: extractEffectfulFootprint(parsed),
         // v0.18.6 — surface author when the substrate populated it; null
         // when not (substrate-neutral graceful degradation).

package/dist/skill-catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-catalog.js","sourceRoot":"","sources":["../src/skill-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill-catalog.js","sourceRoot":"","sources":["../src/skill-catalog.ts"],"names":[],"mappings":"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"}

package/docs/adopter-playbook.md

@@ -149,7 +149,7 @@ $ my_store.search query="customer feedback" region="eu-west" cluster="prod" -> C
 
 This skill body is locked to `my_store` — its specific kwargs (`region`, `cluster`) and response shape. To move to a different substrate, every call site has to be rewritten.
 
-**⚠ Programmatic `bootstrap()` adopters: `connectors.json` is NOT auto-loaded.** The CLI (`skillfile dashboard` / `serve`) discovers and loads `$SKILLSCRIPT_HOME/connectors.json` automatically. The programmatic path does NOT — `bootstrap()` only reads `connectors.json` when you pass `connectorsConfigPath`. Skip it and your `$ name.tool` calls fail at runtime with `unknown-connector` and no hint that the file simply wasn't read. See §"Programmatic bootstrap path" below for the explicit-wiring pattern. (Same CLI-auto-vs-programmatic-explicit asymmetry as `.env` and `SKILLSCRIPT_*` env vars — three instances of the same pattern now.)
+**⚠ Programmatic adopters:** use **`bootstrapFromEnv()`** and it loads `$SKILLSCRIPT_HOME/connectors.json` (plus `.env` + `SKILLSCRIPT_*`) for you, exactly like the CLI. Only **raw `bootstrap()`** skips them — it reads `connectors.json` solely when you pass `connectorsConfigPath`, and skipping it makes `$ name.tool` calls fail at runtime with `unknown-connector` and no hint that the file simply wasn't read. See §"Programmatic bootstrap path" below — `bootstrapFromEnv()` is the recommended default; the raw-`bootstrap()` explicit-wiring pattern is for hand-assembled custom substrates.
 
 ### Picking — the tradeoff
 
@@ -481,9 +481,44 @@ skillfile shell-audit
 
 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)
+### Programmatic bootstrap path
 
-**The CLI-auto-vs-programmatic-explicit asymmetry.** The CLI (`skillfile dashboard` / `serve`) does several discovery steps automatically — load `$SKILLSCRIPT_HOME/.env`, read `SKILLSCRIPT_*` env vars, load `$SKILLSCRIPT_HOME/connectors.json`. The programmatic path (`bootstrap()` from your own embedder code) does NOT do any of these automatically. Each surface needs explicit wiring on the programmatic path:
+**Most adopters operate via the web dashboard** after a one-time `skillfile init`. To stand that dashboard up from your own code, use **`bootstrapFromEnv()`** — the blessed entry point that wires a full runtime + `DashboardServer` from `$SKILLSCRIPT_HOME` *exactly the way the CLI does*: it loads `.env`, `skillscript.config.json`, and `connectors.json`, resolves the whole `SKILLSCRIPT_*` env cascade, calls `bootstrap()`, wires declarative triggers, and assembles the server.
+
+```typescript
+import { bootstrapFromEnv } from "skillscript-runtime";
+
+const { wired, server } = await bootstrapFromEnv({ mode: "dashboard" /* or "serve" */ });
+wired.scheduler.start();
+await server.start();
+// On shutdown, reap stdio-bridged connector children (RemoteMcpConnector):
+process.on("SIGTERM", async () => {
+  await wired.scheduler.stop();
+  await server.stop();
+  await wired.registry.disposeAll();
+});
+```
+
+Both are returned **unstarted** — you decide when to `start()`. Options: `mode`, `home` (default `$SKILLSCRIPT_HOME`), `configPath`, `connectorsConfigPath`, `port`, `host`, and `overrides`. **Precedence**: explicit option > `overrides` (passed to `bootstrap()`, wins last) > `SKILLSCRIPT_*` env > `skillscript.config.json` > default.
+
+To wire your **own custom substrate** (e.g. a remote `SkillStore`), two paths:
+- **Declarative** — if it's expressible in `connectors.json` via the `{ "type": "custom", "module": "./my-store.js", "export": "MyStore" }` substrate form, just declare it; `bootstrapFromEnv()` honors `substrate.*` like the CLI.
+- **Instance injection** — pass a pre-built instance through `overrides`, the common path for a store that needs constructor wiring you hold in code:
+  ```typescript
+  const { wired, server } = await bootstrapFromEnv({
+    mode: "dashboard",
+    overrides: { skillStore: new MyRemoteSkillStore({ /* client, auth, ... */ }) },
+  });
+  ```
+  Everything else (data store, models, connectors, env cascade) still auto-wires from `$SKILLSCRIPT_HOME`. `overrides` accepts any `bootstrap()` option (`skillStore` / `dataStore` / `localModel` / `agentConnector` / allowlists / …).
+
+This closes the silent CLI-vs-programmatic asymmetry described below; reach for raw `bootstrap()` only when you're hand-assembling a registry that neither `connectors.json` nor `overrides` can express.
+
+**⚠ Migrating an existing hand-assembled bootstrap to `bootstrapFromEnv()`?** Move any options you previously hardcoded on `bootstrap()` / `new DashboardServer({...})` to their `SKILLSCRIPT_*` env equivalents — `bootstrapFromEnv()` resolves them from env, so a value you drop reverts to the default. Two to watch (adopter-verified, 0.24.0): `enableUnsafeShell: true` → `SKILLSCRIPT_ENABLE_UNSAFE_SHELL=true` (fails **loud** — unsafe ops just refuse, you'll notice); and **`mcpCallerIdentityHeader: "X-Agent-Id"` → `SKILLSCRIPT_MCP_CALLER_IDENTITY_HEADER=X-Agent-Id`, which fails *silently*** — drop it and skill-author attribution quietly reverts to the store's default writer identity, with no error. (`bootstrap()`-level opts like `enableUnsafeShell` can instead go through `overrides`; the `DashboardServer`-level `mcpCallerIdentityHeader` is env-only via `bootstrapFromEnv` — set the env var.) Verify after migrating: send your identity header on a `/rpc` `skill_write` and confirm the captured `author`.
+
+#### Raw `bootstrap()` — the CLI-auto-vs-programmatic-explicit asymmetry
+
+`bootstrapFromEnv()` does the discovery steps below for you. If you call **`bootstrap()` directly** instead (hand-assembling substrates), be aware the CLI (`skillfile dashboard` / `serve`) does several discovery steps automatically — load `$SKILLSCRIPT_HOME/.env`, read `SKILLSCRIPT_*` env vars, load `$SKILLSCRIPT_HOME/connectors.json` — that raw `bootstrap()` does NOT. Each surface then needs explicit wiring:
 
 | Surface | CLI path | Programmatic path |
 |---|---|---|
@@ -594,6 +629,45 @@ SKILLSCRIPT_FS_ALLOWLIST=/srv/skillscript/workspace,/var/skillscript/events
 
 TOCTOU note: the check resolves the real path at call time; a symlink swapped between check and open is a residual closed by fd-based opens later. Checking the resolved real path is the standard mitigation shipped today.
 
+## Secrets
+
+**A skill can reference an operator-provisioned secret by name, use it at a sink, and never read it back.** This is how a credential (a bearer token, an API key) reaches a `shell(...)` or `$ connector.tool` call without living in the skill source, the transcript, or a trace.
+
+Three parts:
+
+```
+# Skill: send-mail
+# Requires: secret.AGENTMAIL_KEY        # 1. declare — an approver sees which credentials the skill reaches
+# Status: Draft
+
+default: run
+run:
+    shell(command="curl -sS -H 'Authorization: Bearer {{secret.AGENTMAIL_KEY}}' https://api.agentmail.to/...") -> R
+```
+
+1. **Declare** with `# Requires: secret.NAME`.
+2. **Place** with a `{{secret.NAME}}` marker — only inside a sink (a `shell(...)` op or a `$ connector.tool` arg). It is deliberately distinct from `${VAR}`: `${VAR}` is readable substitution over the skill's variable scope and **cannot** reach a secret; `{{secret.NAME}}` resolves *only* at the sink and is never bound to a variable.
+3. **Provision** the value as an env var (operator side, e.g. `.env`):
+
+```bash
+SKILLSCRIPT_SECRET_AGENTMAIL_KEY=am_live_...
+```
+
+| Operator switch | Controls |
+|---|---|
+| `SKILLSCRIPT_SECRET_<NAME>` | The value `{{secret.NAME}}` resolves to. The `SKILLSCRIPT_SECRET_` prefix scopes which env is secret-reachable — `{{secret.PATH}}` looks for `SKILLSCRIPT_SECRET_PATH`, never `$PATH`. |
+
+**Use-only, enforced.** A marker is legal only in a sink; the runtime injects the value for that one call and never lets it reach a readable surface. Three lint rules block misuse at compile (`secret-use-only` — a marker in `emit`/`$set`/a condition/an `# Output:` template/a `file_*`/`notify` op/an op `(fallback:)`; `secret-undeclared` — a marker with no `# Requires`; `secret-dynamic-name` — a non-literal name like `{{secret.${VAR}}}`). The **runtime** is the authoritative gate (it survives a lint bypass): it resolves only names declared in `# Requires`, only at the sink, and the trace + any error message render the `{{marker}}`, never the value. Fail-closed — an unprovisioned or undeclared secret aborts the op.
+
+**Provisioning is operator-only.** A skill author *names* a secret; only the operator *sets* it (in the runtime env / `.env`). Keep secret values out of skill source and out of the fs allowlist, exactly like the approval key.
+
+**Threat-model boundary — read this before granting a secret.** A secret you authorize a skill to *use* in a shell, that skill can also *exfiltrate* — e.g. `shell("echo {{secret.X}}") -> OUT` then `emit("${OUT}")`, or a `curl` that POSTs it to any host. This is inherent to passing a credential into a shell command and is **not** prevented by the runtime. Two controls:
+
+- **Approval review.** In secured mode a human approves the skill before it runs — review shell-sink skills for exactly this (a command that echoes or forwards the credential).
+- **Prefer a connector sink.** A `$ connector.tool` where the connector holds the credential out of band is stronger than a shell `curl`: the value never round-trips through skill-visible stdout. Use a connector sink for any credential whose exposure you can't accept.
+
+(On the shell path the resolved value is also briefly visible in the host process list via `ps`; a future vault-backed `SecretProvider` closes that with sink-aware injection. The `SecretProvider` seam is already in place — an adopter can supply a vault-backed provider via `bootstrap({ secretProvider })` or `bootstrapFromEnv`'s `overrides` with no skill changes.)
+
 ## Trigger model
 
 **The trigger surface is two primitives.**
@@ -1103,7 +1177,9 @@ The `// ADOPTER:myorg —` prefix is greppable across merges; your future-self c
 
 ### 4. Treat `src/bootstrap.ts` as reference, not canonical
 
-The bundled `bootstrap()` is a starting point. For deployments with custom substrates, write your own bootstrap that imports the public APIs (`Registry`, the connector classes, `loadConnectorsConfig`, `loadSkillscriptConfig`, etc.). Modifying the bundled bootstrap creates churn on every upstream release.
+For the standard "wire the whole runtime + dashboard from `$SKILLSCRIPT_HOME` like the CLI does" case — which is most adopters — call **`bootstrapFromEnv()`** (see §"Programmatic bootstrap path"). It's the supported public entry point; you don't hand-assemble anything, and you swap substrates declaratively via `connectors.json`. Remember to `await wired.registry.disposeAll()` on shutdown so stdio-bridged connector children (RemoteMcpConnector) are reaped, not orphaned — `bootstrapFromEnv()` callers own teardown (the CLI does it for you).
+
+Drop to raw `bootstrap()` + `Registry` only when you're hand-assembling a substrate that `connectors.json` can't express — import the public APIs (`Registry`, the connector classes, `loadConnectorsConfig`, `loadSkillscriptConfig`, etc.) rather than modifying the bundled bootstrap, which churns on every upstream release.
 
 See `examples/custom-bootstrap.example.ts` for a worked walkthrough.
 

package/docs/configuration.md

@@ -375,7 +375,7 @@ Underscore-prefixed top-level keys (`_comment`, `_note_security`, etc.) are igno
 
 Write `class FooSkillStore implements SkillStore { ... }` (or DataStore, LocalModel). Wire it via either:
 
-**(a) Programmatic bootstrap (recommended today)** — write your own bootstrap script that constructs the registry directly:
+**(a) Programmatic bootstrap (recommended today)** — for the common case (wire everything from `$SKILLSCRIPT_HOME` like the CLI does), call **`bootstrapFromEnv()`** and declare your substrate in `connectors.json`; it loads `.env` + config + `connectors.json`, resolves the env cascade, and returns a fully-wired `{ wired, server }` (both unstarted). Reach for the raw-`Registry` assembly below only when hand-constructing a substrate `connectors.json` can't express:
 
 ```typescript
 import { Registry, McpServer, Scheduler } from "skillscript-runtime";
@@ -386,7 +386,7 @@ registry.registerSkillStore("primary", new FooSkillStore({ /* config */ }));
 // ... register other substrates, then construct Scheduler + McpServer + DashboardServer
 ```
 
-See [`docs/adopter-playbook.md`](adopter-playbook.md) for the full pattern.
+See [`docs/adopter-playbook.md`](adopter-playbook.md) §"Programmatic bootstrap path" for both — `bootstrapFromEnv()` (recommended) and the raw pattern.
 
 **(b) `connectors.json` custom form** (deferred to follow-up):
 

package/docs/connector-contract-reference.md

@@ -270,6 +270,10 @@ Adopter substrates with their own ownership concept (e.g., AMP's `author:<id>` t
 
 **`delete()` is destructive in the bundled impls — permanent, name-reclaiming.** The contract signature is `delete(name): Promise<void>`. The bundled stores erase rather than tombstone: `FilesystemSkillStore` unlinks the skill file + version sidecar, `SqliteSkillStore` hard-cascades both tables. After delete the skill is gone from `query()`/`load()`/`metadata()`/`versions()`, the name frees up immediately for a fresh `store()` (clean history, no orphan rows), and there is no trash and no restore. Delete is **operator-only** (CLI `skillfile delete` / the dashboard) — there is no agent/MCP delete surface — and both surfaces gate it behind a confirm + reverse-dependency check. Your impl *may* soft-delete instead (tombstone + filter from normal views); the runtime only requires "remove from normal views," and recovery semantics are your store's concern.
 
+**`version()` — OPTIONAL cheap change-token (helps remote stores).** A `version(): Promise<string>` method returns a store-wide token that fingerprints the whole namespace **without loading any skill bodies**. `skill_list` returns it as `catalog_version` and honors a caller's `if_none_match`: when the token still matches, the response is `{ not_modified: true }` and the catalog rebuild is skipped. That rebuild otherwise costs one `load()` *per skill* (to parse each entry's effectful footprint) — free against a local store, but a network round-trip per entry against a remote one, so a polling dashboard hammers the substrate. **Optional**: a store without `version()` just always rebuilds (today's behavior, no change).
+
+**The contract invariant** — `version()` MUST change whenever the catalog's *observable content* changes: an add, a remove, a status change, **and a body edit even if the status is unchanged**. A token that fails this serves a stale catalog. ⚠ **The subtle trap:** a token over only `(id, status)` is exact in **secured mode** (an edit forces the skill back to `Draft`, so status moves) but goes **stale in unsecured mode** on a body-edit-with-unchanged-status. So fold a per-skill **content revision** (a content hash, version, or `updated_at`) into the fingerprint — don't ship a status-only token unless your deployment is secured-mode-only, and if it is, document that limitation. Bundled impls satisfy the invariant in *both* modes: `FilesystemSkillStore` hashes each skill file's `(name, mtime)` (a rewrite moves the mtime); `SqliteSkillStore` hashes `(name, status, current_version)` — `current_version` is the content hash. **Implement it on any network-backed SkillStore**, fingerprinting whatever your substrate exposes cheaply (a list ETag, a max-revision/seq, or a metadata digest), as long as every observable change moves it.
+
 ### DataStore conventions
 
 **`summary`/`detail` split is convention, not contract field.** The DataStore contract gives `write()` a single `content: string`. Bundled `SqliteDataStore` maps this to `summary = first line (≤200 chars)` and `detail = full content`. Adopter substrates with native summary/detail concepts (AMP's `summary` + `detail` columns) can pre-compose and pass via `metadata`, but the basic mapping convention is "first line is the preview." Diverge and the dashboard's memory rendering looks weird, but skills still work.

package/docs/language-reference.md

@@ -511,7 +511,7 @@ $ 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). 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[]`.
+**`(fallback: "value")` trailer** — Fires on dispatch throw (including a `timeout=N` expiry) 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:[]}`).
 
@@ -541,11 +541,11 @@ Routes through the wired LocalModel.
 
 | Kwarg | Required | Notes |
 |---|---|---|
-| `prompt="..."` | yes | Non-empty string. Substitution-resolved at runtime. |
-| `maxTokens=N` | no | Positive integer (number or numeric string). Forwarded as `runOpts.maxTokens`. |
+| `prompt="..."` | yes | Non-empty string (empty/missing throws). Substitution-resolved at runtime. Must be a kwarg — there is no bare-string positional form (`$ llm "..."` is invalid; see the all-kwargs rule at the top of this section). |
+| `maxTokens=N` | no | Positive integer (number or numeric string). Forwarded as `runOpts.maxTokens`. **camelCase — it's `maxTokens`, NOT `max_tokens`; the snake_case form is an unknown kwarg the bridge silently drops, caught by the `unknown-llm-arg` lint.** |
 | `model="X"` | no | Per-call model selection. Resolves against registered LocalModel aliases via `registry.getLocalModel(X)`; falls through to the default LocalModel with `model=X` passed as an upstream hint (e.g., Ollama tag) when X doesn't resolve. See `unknown-llm-model` lint below. |
 
-Plus the universal op-level kwargs (`timeout`, `approved`, `(fallback:)`, `-> R`).
+Plus the universal op-level kwargs (`timeout`, `approved`, `(fallback:)`, `-> R`). `timeout` is runtime-enforced (popped before the connector sees it); a timeout expiry is a throw, so a `(fallback:)` trailer catches it.
 
 Canonical shape:
 
@@ -795,6 +795,83 @@ Missing-ref in the RHS produces a tier-1 runtime error.
 - `foreach IDENT in EXPR:` iterator vars are loop-local — `$set` bindings inside the loop don't persist after the loop ends
 - Target outputs (`${target.output}`) are accessible after the target completes
 
+## Secrets — secret.NAME references, {{secret.NAME}} sink markers, SKILLSCRIPT_SECRET_ provisioning, use-only enforcement
+
+## Secrets
+
+Skills routinely need a credential — an API token, a deploy key — to reach an external service. Skillscript handles secrets **by reference, never by value**. A skill declares which secrets it may use and marks exactly where each is injected, but it can never read, bind, or print the value. The runtime resolves a secret only at the instant it is handed to a *sink* (a `shell` op or a `$ connector.tool` dispatch).
+
+This is what lets a human approve a skill knowing the full set of credentials it can reach — and lets an agent-authored skill run without ever exposing the key to the agent. The author holds a *use*-capability (invoke a skill that reaches the key) without the *access*-capability (read the key).
+
+### Three steps
+
+**1. Declare it in frontmatter.** List every secret the skill may reach. An approver reading the skill sees the whole credential surface up front.
+
+```
+# Skill: send-email
+# Requires: secret.AGENTMAIL_KEY
+# Status: Draft
+```
+
+**2. Place it with a `{{secret.NAME}}` marker — only inside a sink.** A secret may appear only where it is *used*: inside a `shell(...)` op or a `$ connector.tool` dispatch.
+
+```
+run:
+    shell(command="curl -H 'Authorization: Bearer {{secret.AGENTMAIL_KEY}}' https://api.agentmail.to/...") -> R
+```
+
+…or into a connector argument:
+
+```
+$ http.post url="https://api..." authorization={{secret.AGENTMAIL_KEY}} -> R
+```
+
+**3. Provision it as an env var**, named with the `SKILLSCRIPT_SECRET_` prefix:
+
+```
+SKILLSCRIPT_SECRET_AGENTMAIL_KEY=am_us_...
+```
+
+### Semantics — the rules that matter
+
+- **`{{secret.NAME}}` is not `${VAR}`.** `${VAR}` is readable substitution in the skill's variable scope — it can be bound, emitted, branched on, and it appears in the execution trace. A secret can do none of that. `${VAR}` cannot reach a secret; a `{{secret.NAME}}` marker is never readable as a var.
+- **The name is a compile-time literal.** `${VAR}` substitution never reaches inside a `{{secret.…}}` marker (markers are opaque to substitution), and the runtime resolves a marker only against the declared `# Requires` set by exact-literal match. You cannot build a secret name dynamically.
+- **Use-only, resolved at the sink.** The value is injected at the moment the shell op spawns or the connector dispatches — never bound to a variable, never emitted, never written to a trace. The trace records the *marker* (`{{secret.AGENTMAIL_KEY}}`), not the value. The binary/allowlist gate runs *before* resolution, so a refused op never even resolves the secret, and error/trace output is redacted to the marker form.
+- **Misuse is a compile-time error (tier-1), not a runtime surprise:**
+  - `{{secret.NAME}}` in `emit`, `$set`, a condition, an `# Output:` template, a `file_*` / `notify` op, or a `(fallback: ...)` → **`secret-use-only`**.
+  - A `{{secret.NAME}}` marker with no matching `# Requires: secret.NAME` declaration → **`secret-undeclared`**.
+  - A marker whose name isn't a clean literal (e.g. `{{secret.${NM}}}`) → **`secret-dynamic-name`**.
+
+### Worked example
+
+A skill that checks an inbox over a REST API. The key is declared once and used once, at the curl sink — it never touches a variable, the output, or the trace:
+
+```
+# Skill: inbox-check
+# Requires: secret.AGENTMAIL_KEY
+# Returns: COUNT
+
+check:
+    shell(argv=["curl","-s","-H","Authorization: Bearer {{secret.AGENTMAIL_KEY}}","https://api.agentmail.to/v0/inboxes/me/messages?labels=unread"]) -> RAW (fallback: "{\"count\":0}")
+    $ json_parse ${RAW} -> P
+    $set COUNT = ${P.count}
+    emit(text="Unread: ${COUNT}")
+
+default: check
+```
+
+### Threat-model boundary — what this does NOT protect
+
+The guarantees above stop *accidental* leakage and *undeclared* access: a secret is never bound, emitted, traced, leaked through a refused op, or reachable via a dynamically-built or undeclared name. They do **not** stop a *malicious skill author*. A skill authorized to use a secret in a **shell** sink can also make that sink exfiltrate it — e.g. `shell(command="printf %s {{secret.FLAG}}") -> OUT` then `emit(${OUT})` launders the secret through the skill's own stdout, and a `curl` could send it anywhere. This is inherent: once a command may *use* a secret, it may *misuse* it.
+
+The controls for that boundary are:
+- **Human approval review** — an approver who sees `printf {{secret}}` followed by `emit` rejects the skill. The `# Requires:` line + the visible sink are exactly what makes this reviewable.
+- **Prefer connector sinks over raw shell.** A connector holds the credential out-of-band and applies it inside the dispatch, so the secret never round-trips through skill-visible output (`$ http.post ... authorization={{secret.NAME}}` returns the API's *data*, not the key). Use a `shell` secret only when no connector is available, and review such skills accordingly.
+
+### Why this shape
+
+The marker/var split *is* the security model: the runtime is the reference monitor, the human approval is the grant, and the `# Requires:` line is the auditable statement of reach. Capability without access — the agent can act through the credential without ever holding it.
+
 ## Pipe filters — url, shell, json, trim, fallback, isodate
 
 Pipe filters apply transforms to resolved variables before substitution. Syntax: `${VAR|filter}` or `${VAR|filter:"arg"}` for parameterized filters. Filters operate at compile time for static values; for runtime-bound variables, filters apply at substitution time.
@@ -2479,5 +2556,5 @@ When any of these primitives ship, the relevant grammar moves into its canonical
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-06-16 15:46 EDT*  
+*Rendered from `skillscript/skillscript-language-reference` — 2026-06-28 15:20 EDT*  
 *Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*

package/docs/sqlite-skill-store.md

@@ -141,7 +141,7 @@ SqliteSkillStore is the storage layer. Authoring happens above:
 - **MCP tool**: agents call `skill_write` directly; same path as the dashboard
 - **Programmatic**: your code calls `store.store(name, source, metadata?)` directly
 
-The dashboard does NOT default to SqliteSkillStore today — `skillfile dashboard` bootstraps with FilesystemSkillStore. If you want a SqliteSkillStore-backed dashboard, write a custom bootstrap (small surface; see the runtime `Registry` API).
+The dashboard defaults to FilesystemSkillStore. For a SqliteSkillStore-backed dashboard, set `substrate.skill_store: "sqlite"` in `connectors.json` — both `skillfile dashboard` and the programmatic `bootstrapFromEnv()` honor it; no custom bootstrap needed.
 
 ---
 
@@ -164,6 +164,7 @@ When forking into your codebase:
 2. Replace the SQL with your substrate's API (HTTP, DataStore, vector DB, etc.)
 3. Update `staticCapabilities()` to match what your substrate actually supports — drop `supports_versioning` if you can't track history, drop `supports_tag_filter` if querying tags isn't tractable
 4. Update `manifest()` to describe your substrate (`kind: "amp"` or whatever)
-5. Tests: copy `tests/SqliteSkillStore.test.ts` as a starting point + run the conformance suite (`SkillStoreConformance.buildTests()` from `skillscript-runtime/testing`)
+5. **Optional but high-value for network-backed forks: implement `version()`** — a cheap store-wide change-token computed WITHOUT loading bodies (a list ETag, max-revision, or metadata digest), where any add/remove/edit/status-change moves it. It lets `skill_list` skip its N+1 catalog rebuild on unchanged polls (each entry otherwise costs a `load()` — one network round-trip per skill against a remote store). `SqliteSkillStore` hashes `(name, status, current_version)` in one body-free query. Skip it and `skill_list` just always rebuilds.
+6. Tests: copy `tests/SqliteSkillStore.test.ts` as a starting point + run the conformance suite (`SkillStoreConformance.buildTests()` from `skillscript-runtime/testing`)
 
 The conformance suite catches drift from the contract surface. If your fork passes, the runtime treats it interchangeably with FilesystemSkillStore / SqliteSkillStore / etc.

package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts

@@ -222,4 +222,23 @@ export class SkillStoreTemplate implements SkillStore {
     //   - Return VersionInfo with previous_status populated
     throw new Error("TODO: update_status() — atomic status transition + audit row.");
   }
+
+  // OPTIONAL (v0.24.0) — implement this on a NETWORK-BACKED store. It returns a
+  // cheap store-wide change-token computed WITHOUT loading skill bodies. The MCP
+  // `skill_list` tool returns it as `catalog_version` and honors a caller's
+  // `if_none_match`: when the token is unchanged it replies `{ not_modified: true }`
+  // and skips the catalog rebuild — which otherwise loads EVERY skill body (one
+  // network round-trip per skill) to parse its effectful footprint. For a remote
+  // store this is the difference between a chatty poll and a single cheap probe.
+  //
+  // Fingerprint whatever your substrate exposes cheaply (a list ETag, a
+  // max-revision/seq, or a metadata digest), as long as ANY add/remove/edit/
+  // status-change moves the token. DELETE this method if you can't compute one
+  // cheaply — it's optional, and `skill_list` just always rebuilds without it.
+  async version(): Promise<string> {
+    // TODO — e.g. a single metadata-only list:
+    //   const rows = await this.api.list({ fields: ["id", "status", "rev"] }); // NO bodies
+    //   return sha256(rows.map(r => `${r.id}:${r.status}:${r.rev}`).join("\n")).slice(0, 16);
+    throw new Error("TODO: version() — optional cheap change-token (no body loads). Delete if unsupported.");
+  }
 }

package/examples/custom-bootstrap.example.ts

@@ -1,13 +1,23 @@
 // Worked example: writing a custom bootstrap that wires adopter-specific
 // substrates against skillscript-runtime's public APIs.
 //
-// **When to write your own bootstrap.** The bundled `bootstrap()` from
-// `skillscript-runtime` wires `FilesystemSkillStore` + `OllamaLocalModel` +
-// `SqliteDataStore` + the typed-contract bridges. If your deployment uses
-// different substrates (your own data store, a hosted LLM API, an MCP
-// server for agent delivery, etc.), write your own bootstrap rather than
-// modifying the bundled one. Prevents merge conflicts on every upstream
-// release that touches `src/bootstrap.ts`.
+// **First: do you even need this?** For the common case — wire the whole
+// runtime + dashboard from `$SKILLSCRIPT_HOME` exactly like the CLI does —
+// call `bootstrapFromEnv()` instead (it loads `.env` + `skillscript.config.json`
+// + `connectors.json`, resolves the SKILLSCRIPT_* env cascade, and returns
+// `{ wired, server }` unstarted). You can swap substrates declaratively via
+// `connectors.json` (`substrate.skill_store: "sqlite"`, a custom class, etc.)
+// without writing any of the assembly below. See docs/adopter-playbook.md
+// §"Programmatic bootstrap path".
+//
+// **When to write your own bootstrap (this file).** Reach for raw `bootstrap()`
+// + `Registry` only when hand-assembling a substrate `connectors.json` can't
+// express. The bundled `bootstrap()` from `skillscript-runtime` wires
+// `FilesystemSkillStore` + `OllamaLocalModel` + `SqliteDataStore` + the typed-
+// contract bridges. If your deployment uses different substrates (your own data
+// store, a hosted LLM API, an MCP server for agent delivery, etc.), assemble
+// your own here rather than modifying the bundled one. Prevents merge conflicts
+// on every upstream release that touches `src/bootstrap.ts`.
 //
 // **What to copy from this file.** Take what fits your deployment and
 // drop the rest. The shape is: construct a Registry, register your

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-23T19:04:21.352Z",
+  "compiled_at": "2026-06-28T19:30:48.982Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",

package/scaffold/.env.example

@@ -56,6 +56,19 @@
 # SKILLSCRIPT_SHELL_ALLOWLIST=curl,git,jq,grep
 
 
+# ─── Secrets ───────────────────────────────────────────────────────────
+
+# Provision a secret a skill can USE but never READ. A skill declares it with
+# `# Requires: secret.NAME` and places it with a `{{secret.NAME}}` marker; the
+# runtime injects the value only at a sink (a shell() op or a `$ connector.tool`
+# dispatch) and never lets it reach an emit, a $set, a trace, or any readable
+# surface. Name each secret SKILLSCRIPT_SECRET_<NAME> — the prefix scopes which
+# env is secret-reachable (so {{secret.PATH}} can't pull $PATH). Operator-only:
+# a skill author references a secret by name but cannot set or read it.
+# SKILLSCRIPT_SECRET_AGENTMAIL_KEY=sk-live-...
+# SKILLSCRIPT_SECRET_GITHUB_TOKEN=ghp_...
+
+
 # ─── Network / bind config ─────────────────────────────────────────────
 
 # HTTP bind address. Default 127.0.0.1 (localhost-only). Set 0.0.0.0 for