skillscript-runtime 0.23.1 → 0.24.0

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,42 @@ 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.
+
+#### 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 |
 |---|---|---|
@@ -1103,7 +1136,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/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-25T13:19:55.700Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.23.1",
+  "version": "0.24.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>",