skillscript-runtime 0.13.2 → 0.13.5

package/docs/adopter-playbook.md

@@ -0,0 +1,240 @@
+# Adopter playbook
+
+How to wire skillscript-runtime into your deployment. Written for Joe-Programmer: you have your own substrate stack (memory system, agent harness, LLM endpoint, filesystem), and you want skillscript to slot in rather than dictate.
+
+This playbook covers the load-bearing decisions, the two wiring patterns, and the conventions that keep your local modifications upstream-merge-friendly.
+
+## The four substrates skillscript expects
+
+Skillscript-runtime is substrate-neutral and assumes you have (or will choose):
+
+1. **A filesystem** — for skill source files (`.skill.md`), trace records, possibly a memory database. Sandbox via container, chroot, or limited-privilege process — operator's call.
+2. **A memory system** — for knowledge retrieval and memory writes. Could be SQLite-FTS (bundled), a vector database, an in-house store, an Obsidian-style notes system — whatever you already have.
+3. **An LLM endpoint** — Ollama running locally (bundled), a hosted API like OpenAI / Anthropic / Azure, or your own inference server.
+4. **An agent harness** — where skill output is delivered. Could be tmux sessions, a webhook receiver, an in-house agent runtime, or no harness at all (skills run for their text output only).
+
+Each of these maps to a typed connector contract: `SkillStore`, `MemoryStore`, `LocalModel`, `AgentConnector`. Plus `McpConnector` for any external tool you want to invoke from a skill body.
+
+## Case 1 vs Case 2 — the load-bearing wiring decision
+
+This is the most important architectural choice you'll make.
+
+### Case 1 — typed-contract wiring (substrate-portable)
+
+You implement the typed connector contracts (`MemoryStore`, `LocalModel`, etc.) against your substrate. The bridge classes (`MemoryStoreMcpConnector`, `LocalModelMcpConnector`) surface them as canonical `$ memory` / `$ llm` dispatch.
+
+```typescript
+class MyMemoryStore implements MemoryStore {
+  async query(filters: QueryFilters): Promise<PortableMemory[]> { /* ... */ }
+  async manifest(): Promise<ManifestInfo> { /* ... */ }
+}
+
+registry.registerMemoryStore("primary", new MyMemoryStore());
+registry.registerMcpConnector("memory", new MemoryStoreMcpConnector(new MyMemoryStore()));
+```
+
+**In skills:**
+```
+$ memory mode=fts query="customer feedback" limit=10 -> CONTEXT
+```
+
+This same skill body runs unchanged against your substrate, against SQLite-FTS (bundled), against Pinecone, against any substrate that conforms to the typed contract. **Skills are portable.**
+
+### Case 2 — MCP-tools wiring (substrate-locked)
+
+Your substrate exposes itself as MCP tools (via a local MCP server or remote one). You wire it as an `McpConnector` (typically `RemoteMcpConnector` for spawned MCP processes) and skills reference its tools by name with substrate-specific kwargs.
+
+```typescript
+// connectors.json:
+{
+  "my_memory": {
+    "class": "RemoteMcpConnector",
+    "config": {
+      "command": "my-memory-mcp-server",
+      "args": ["--db", "/var/memory"]
+    }
+  }
+}
+```
+
+**In skills:**
+```
+$ my_memory.search query="customer feedback" vault="team" tags=["urgent"] -> CONTEXT
+```
+
+This skill body is locked to `my_memory` — its specific kwargs (`vault`, `tags`) and response shape. To move to a different substrate, every call site has to be rewritten.
+
+### Picking — the tradeoff
+
+| Aspect | Case 1 (typed) | Case 2 (MCP) |
+|---|---|---|
+| Skill portability | ✓ portable | ✗ substrate-locked |
+| Substrate feature coverage | Limited to typed contract | Full substrate surface |
+| Implementation effort | Implement typed interface | Wire existing MCP server |
+| Best for | Skills you want to ship | Substrate-specific power features |
+
+**The choice is per-skill, not per-substrate.** You can wire both — register `memory` (typed-contract via bridge) AND `my_memory` (MCP) — and let skills opt into portability by which connector name they reference.
+
+For the substrate-portability claim to hold, **the substrates you care about must be Case-1-wired**.
+
+## Joe Programmer setup walkthrough
+
+### 1. Install + initialize
+
+```bash
+npm install -g skillscript-runtime
+skillfile init --here
+```
+
+This creates `~/.skillscript/` with `skills/`, `traces/`, an empty `connectors.json`, and a `config.toml` stub.
+
+### 2. Decide on substrate wiring
+
+For each of the four substrates (memory, LLM, agent harness, MCP tools), decide Case 1 or Case 2. The onboarding scaffold (`examples/onboarding-scaffold/`) is Case 1 end-to-end against file-backed memory + OpenAI + tmux.
+
+### 3. Configure runtime knobs
+
+Create `skillscript.config.json` in your `$SKILLSCRIPT_HOME`:
+
+```json
+{
+  "skillsDir": "${SKILLSCRIPT_HOME}/skills",
+  "traceDir": "${SKILLSCRIPT_HOME}/traces",
+  "memoryDbPath": "${SKILLSCRIPT_HOME}/memory.json",
+  "dashboard": { "port": 7878 }
+}
+```
+
+`${VAR}` substitutes against `process.env`. See `skillscript.config.json.example` in the repo for the full surface.
+
+### 4. Wire your substrates
+
+**For the bundled CLI path** (no custom code): use `connectors.json` to declare your MCP servers; use `OPENAI_API_KEY` / `OLLAMA_BASE_URL` env vars; run `skillfile dashboard --config ./skillscript.config.json`.
+
+**For custom substrates**: write your own bootstrap. See `examples/custom-bootstrap.example.ts` and `examples/onboarding-scaffold/bootstrap.ts` for complete worked walkthroughs.
+
+If you have a custom JSON-instantiable `McpConnector` class, register it with `registerConnectorClass` before loading config:
+
+```typescript
+import { registerConnectorClass, loadConnectorsConfig } from "skillscript-runtime";
+import { MyAdopterConnector } from "./my-adopter-connector.js";
+
+registerConnectorClass("MyAdopterConnector", {
+  ctor: MyAdopterConnector,
+  fromConfig: (cfg) => new MyAdopterConnector(cfg),
+});
+
+const { connectors } = loadConnectorsConfig({ path: "./connectors.json" });
+```
+
+### 5. Two-instance posture
+
+Running dev-skillscript alongside an adopter-wiring instance on the same machine:
+
+```bash
+# dev
+skillfile dashboard
+
+# adopter (different port + paths)
+SKILLSCRIPT_HOME=/path/to/adopter skillfile dashboard --config /path/to/adopter/skillscript.config.json
+```
+
+Each instance reads its own config; ports/paths/db files don't collide.
+
+## Conventions for upstream-merge-friendly modifications
+
+If your wiring needs require modifying skillscript-runtime source (rather than just configuration), follow these conventions to minimize merge friction:
+
+### 1. Prefer dedicated adopter files over editing upstream
+
+Put your code in dedicated paths upstream won't touch:
+
+```
+src/connectors/local/my-memory-adapter.ts    ← adopter-owned
+src/connectors/local/my-llm-adapter.ts       ← adopter-owned
+```
+
+Upstream changes to `src/connectors/memory-store.ts` won't conflict with your `local/` files.
+
+### 2. Use the public registration API; don't edit the closed-set Map
+
+`KNOWN_CONNECTOR_CLASSES` in `src/connectors/config.ts` is upstream-owned. Add your classes via `registerConnectorClass(name, entry)` from your bootstrap instead. Closes the merge-conflict bait of editing that file every release.
+
+### 3. Mark unavoidable upstream-file edits with sentinels
+
+When you genuinely have to edit an upstream file, mark the change:
+
+```typescript
+// ADOPTER:myorg — extend dispatch to call our auditor before forward
+if (process.env["MYORG_AUDIT"] === "1") { /* ... */ }
+```
+
+The `// ADOPTER:myorg —` prefix is greppable across merges; your future-self can re-evaluate whether the modification is still needed when upstream changes the surrounding code.
+
+### 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.
+
+See `examples/custom-bootstrap.example.ts` for a worked walkthrough.
+
+## Substrate ship-status
+
+| Substrate | Shipped contract | Shipped impls | Shipped bridge |
+|---|---|---|---|
+| SkillStore | ✓ `load`/`query`/`store`/`update_status`/`delete`/`versions`/`metadata`/`staticCapabilities` | `FilesystemSkillStore`, `SqliteSkillStore` | n/a |
+| MemoryStore | ✓ `query`/`write` | `SqliteMemoryStore` | ✓ `MemoryStoreMcpConnector` |
+| LocalModel | ✓ `run` | `OllamaLocalModel` | ✓ `LocalModelMcpConnector` |
+| McpConnector | ✓ `call` | `RemoteMcpConnector`, `CallbackMcpConnector` | n/a |
+| AgentConnector | ✓ `list_agents`/`deliver`/`wake`/`health_check`/`request_response`; optional `agent_status` | `NoOpAgentConnector` (default), `HttpWebhookAgentConnector` | n/a |
+
+**Notable gaps the playbook should be honest about:**
+
+- **4 of 6 trigger sources parse but don't fire.** `cron` and `session: start` work; `event`, `agent-event`, `file-watch`, `sensor` are parser-only stubs awaiting the event-bus surface.
+- **Output kinds are intentionally substrate-neutral.** `# Output:` accepts `text` / `agent: <name>` / `template: <name>` / `file: <path>` / `none`. Substrate-specific values (`slack:`, `card:`, etc.) are deliberately out of scope — adopters wanting Slack / WhatsApp / Discord / etc. delivery use either `$ slack.post ...` MCP dispatch inside the skill body OR deliver via `agent: <name>` and let the receiving agent decide.
+- **Authorization is hash-token approval.** Skills must carry `# Status: Approved vN:<token>` where the token re-computes from the body minus its `# Status:` line. Bundled `v1:` is CRC32 — discipline-barrier strength, suited to single-operator deployments. Adversarial threat models swap a stronger function:
+
+  ```ts
+  import { registerApprovalFn, setPreferredApprovalVersion } from "skillscript-runtime";
+  import { createHmac } from "node:crypto";
+
+  // v2: HMAC-SHA256 with operator-held key. Agent that knows the algorithm
+  // can no longer self-stamp without the key.
+  const key = process.env["APPROVAL_HMAC_KEY"]!;
+  registerApprovalFn("v2", (body) => createHmac("sha256", key).update(body).digest("hex"));
+  setPreferredApprovalVersion("v2"); // dashboard now stamps v2 on Approve clicks
+  ```
+
+  Wire this in your bootstrap BEFORE any skill is stamped — otherwise existing skills carry `v1:` tokens that still verify (CRC32 stays registered) but new approvals use the upgraded function. The runtime maintains a per-version registry, so mixed-version skill bodies coexist cleanly.
+
+## Skill discovery + cross-agent composition
+
+Under Case-1 wiring against a memory substrate that holds skill payloads (e.g., AMP's payload_type model where compiled `.skill.md` artifacts live alongside thread / prose / document entries), skill discovery uses the canonical `$ memory` surface:
+
+```
+$ memory mode=fts query="incident triage" limit=5 -> SKILLS
+foreach S in ${SKILLS.items}:
+    execute_skill(skill_name="${S.name}", ...) -> RESULT
+```
+
+This works *only* when the memory substrate is Case-1 wired (typed-contract via bridge). Under Case-2 wiring, you'd need substrate-specific tool calls (`$ amp.search query=... payload_type=skill`) which are non-portable.
+
+## Contributing — dispatch-shape discipline
+
+The multi-layer-promise pattern (lint passes; runtime fails, or vice versa) is the recurring failure mode for dispatch-shape work. `validateQualifiedDispatch` is the shared validator lint and runtime both call. To prevent the next recurrence, every PR that introduces a new dispatch shape (a new way of writing `$ ...` ops, a new connector class entry point, a new lifecycle hook on `# Output:`) must land with:
+
+1. **Lint test** — fixture that exercises the shape with lint only (`lint(source, {registry})`)
+2. **Runtime test** — same shape executed end-to-end (`executeSkillByName` or `executeSkillFromSource`)
+3. **E2E test** — the full user path (write skill → store → execute via MCP, or trigger fire → dispatch)
+
+PR description must call out which dispatch shape is exercised. If you can't write all three for a shape, that's a signal the shape is incompletely specified — file a thread before merging.
+
+Connector class authors implementing new `McpConnectorClass`-shaped contracts should also implement `staticTools(): string[] | null` whenever the tool surface is closed and knowable at compile time. Lift `unknown-tool-on-connector` from "advisory you fix at runtime" to "tier-1 error caught at compile time" for every adopter who wires your class.
+
+## Resources
+
+- **Onboarding scaffold** — `examples/onboarding-scaffold/` — complete adopter deployment with file-backed memory + OpenAI + tmux
+- **Custom bootstrap walkthrough** — `examples/custom-bootstrap.example.ts` — registering custom MCP connector classes
+- **Connectors example** — `scaffold/connectors.json` — annotated `connectors.json` shape
+- **Language reference** — `docs/language-reference.md` — skill syntax + frontmatter + lint codes
+- **Connector contracts** — `docs/connector-contract-reference.md` — substrate-neutral contract surfaces
+- **Configuration** — `docs/configuration.md` — `connectors.json` shape + substrate selection

package/docs/configuration.md

@@ -0,0 +1,296 @@
+# Configuration
+
+How to configure a skillscript-runtime deployment.
+
+The single config file is **`~/.skillscript/connectors.json`** (or any path passed via `--connectors`). It has two top-level concerns:
+
+1. **`substrate`** — which `SkillStore`, `MemoryStore`, and `LocalModel` the runtime hosts (MCP server + web dashboard) use.
+2. **Named MCP connector instances** — `youtrack`, `github`, etc. — invoked via `$ <name>` in skill source.
+
+The runtime loads `connectors.json` at startup. Missing file → graceful empty config (substrate defaults to filesystem skills + conditional sqlite memories; no MCP connectors). Malformed JSON or unknown fields → structured errors surfaced at bootstrap.
+
+---
+
+## Quick start
+
+A typical out-of-the-box `~/.skillscript/connectors.json`:
+
+```json
+{
+  "substrate": {
+    "skill_store": "filesystem",
+    "memory_store": "sqlite",
+    "local_model": null
+  }
+}
+```
+
+Equivalent to omitting the file entirely — these are the base config defaults.
+
+To switch skills storage to SQLite:
+
+```json
+{
+  "substrate": {
+    "skill_store": "sqlite"
+  }
+}
+```
+
+Restart `skillfile dashboard` (or `skillfile serve`). The MCP server + dashboard UI now read/write skills from `~/.skillscript/skills/skills.db` instead of `.skill.md` files.
+
+> **Heads up on startup logs.** Sqlite-backed substrates use the built-in `node:sqlite` module, which is still flagged experimental in Node 22. Expect this line on every launch until Node de-experimentalizes it: `ExperimentalWarning: SQLite is an experimental feature and might change at any time`. Harmless; can be silenced per-process with `NODE_OPTIONS="--disable-warning=ExperimentalWarning"` if it clutters your logs.
+
+---
+
+## The substrate section
+
+Singleton substrate connectors. Each slot accepts one of four shapes:
+
+### Short form — bare string
+
+```json
+"skill_store": "sqlite"
+```
+
+Wires the bundled implementation for that type with default config (e.g., dbPath under `~/.skillscript/`).
+
+Valid short-form values per slot:
+
+| Slot | Values |
+|---|---|
+| `skill_store` | `"filesystem"` \| `"sqlite"` |
+| `memory_store` | `"sqlite"` |
+| `local_model` | (none — `"ollama"` requires the object form with `defaultModelTag`; see below) |
+
+### Null — explicit "no substrate"
+
+```json
+"local_model": null
+```
+
+The runtime doesn't register a connector for this slot. Useful for explicitly disabling LocalModel when nothing local is available.
+
+### Object form — override defaults
+
+```json
+"skill_store": {
+  "type": "sqlite",
+  "config": {
+    "dbPath": "/var/skillscript/skills.db"
+  }
+}
+```
+
+`type` picks the bundled impl; `config` is passed to its constructor. Per-type config fields:
+
+| Type | Config fields |
+|---|---|
+| `filesystem` (skill_store) | none — uses the CLI's `skillsDir` |
+| `sqlite` (skill_store) | `dbPath` (default: `<skillsDir>/skills.db`) |
+| `sqlite` (memory_store) | `dbPath` (default: CLI's `MEMORY_DB` or `<skillsDir>/memories.db`) |
+| `ollama` (local_model) | `baseUrl` (default: `OLLAMA_BASE_URL` env or `http://localhost:11434`), **`defaultModelTag` (required — e.g., `"gemma2:9b"`, `"llama3.1:8b"`)** |
+
+Worked Ollama example (because the short form isn't valid for `local_model`):
+
+```json
+{
+  "substrate": {
+    "local_model": {
+      "type": "ollama",
+      "config": {
+        "defaultModelTag": "gemma2:9b"
+      }
+    }
+  }
+}
+```
+
+Pin the model tag explicitly — must be a tag your Ollama instance has pulled (`ollama pull gemma2:9b`). Bare `"local_model": "ollama"` errors out at bootstrap because the model name is too important to silently default.
+
+### Custom form — adopter-written impl
+
+```json
+"skill_store": {
+  "type": "custom",
+  "module": "./my-amp-skill-store.js",
+  "export": "AmpSkillStore",
+  "config": {
+    "vault": "team"
+  }
+}
+```
+
+References an adopter-written class implementing the relevant contract. `module` is the path to the JS file; `export` is the named export (defaults to `default`); `config` is passed to the constructor.
+
+> **Limitation**: sync `bootstrap()` can't dynamic-import. Custom-via-connectors.json surfaces a clear error and falls back to the default. Adopters wanting custom impls today write a programmatic bootstrap that calls `registry.registerSkillStore("primary", new AmpSkillStore(...))` directly — same pattern as the runtime's reference `bootstrap()`. Async-bootstrap with dynamic-import support is planned.
+
+---
+
+## Precedence
+
+When multiple config sources speak:
+
+1. **Programmatic opts** (`opts.skillStore` passed to `bootstrap()`) — explicit, highest priority
+2. **`connectors.json` substrate section** — declarative, deployment-durable
+3. **Built-in default** — fallback (filesystem skill_store; conditional sqlite memory_store; no local_model)
+
+If two configs disagree, the higher-priority one wins; lower-priority is ignored without error.
+
+---
+
+## Which surfaces honor substrate config?
+
+| Surface | Honors substrate? | Reasoning |
+|---|---|---|
+| **MCP server** (`skillfile serve`, dashboard `/rpc`) | ✓ | MCP is the agent-facing surface; must read/write whichever store the deployment chose |
+| **Web dashboard** (`skillfile dashboard`) | ✓ | Same as MCP — agents and humans connect to the same runtime |
+| **Programmatic embed** (your own bootstrap) | ✓ | You pass `opts.skillStore` directly; the runtime takes whatever |
+| `skillfile compile` | ✗ filesystem-only | Authoring loop: `vim foo.skill.md && skillfile compile foo`. Only coherent against FS. |
+| `skillfile lint` | ✗ filesystem-only | Same as compile. |
+| `skillfile audit` | ✗ filesystem-only | Operates on a provenance file + the FS-authored source. |
+| `skillfile list` | ✗ filesystem-only | Filesystem listing of `.skill.md` files. |
+
+The four authoring CLI commands stay FS-pinned by design — they're the filesystem-first authoring loop. Sqlite-backed skills are authored via the dashboard UI or the `skill_write` MCP tool, not these CLI commands.
+
+---
+
+## Named MCP connector instances
+
+Per-host MCP connector wiring. Each top-level key (other than `substrate`) defines a named connector referenced via `$ <name>` in skill source.
+
+```json
+{
+  "substrate": { "skill_store": "sqlite" },
+
+  "youtrack": {
+    "class": "RemoteMcpConnector",
+    "config": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://example.youtrack.cloud/mcp"],
+      "env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" }
+    }
+  },
+
+  "github": {
+    "class": "RemoteMcpConnector",
+    "config": { /* ... */ },
+    "allowed_tools": ["search_repos", "get_issue"]
+  }
+}
+```
+
+Each entry needs:
+
+- **`class`** — a class from the closed-set registry. Today: `RemoteMcpConnector` (stdio-bridged remote MCP). Adopters can register custom classes via `registerConnectorClass()` from their bootstrap.
+- **`config`** — passed to the class's `fromConfig()` factory. Schema is class-specific.
+- **`allowed_tools`** (optional) — per-connector tool allowlist. `undefined` = allow all; `[]` = allow none; listed array = exactly those.
+
+### Credential discipline
+
+`connectors.json` is secret-bearing. The repo `.gitignore` excludes it by default; `connectors.json.example` (not real values) is committed as a template. For deployments, prefer `${VAR}` env-var substitution over literals — commit the `${...}` references; keep secrets in deployment environment.
+
+Skillscript warns at bootstrap if `connectors.json` lives in a git-tracked directory without a `.gitignore` entry.
+
+### `${VAR}` substitution
+
+```json
+"env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" }
+```
+
+`${NAME}` resolves from `process.env` at load time. Missing env var → clear startup error (not silent empty string).
+
+The `config.env` block is itself resolved first, then merged into the substitution scope for the rest of the config — letting you compose values:
+
+```json
+"config": {
+  "env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" },
+  "args": ["--header", "Authorization:${AUTH_HEADER}"]
+}
+```
+
+This matches the Claude Desktop `mcp.json` convention.
+
+### Inline comments
+
+Underscore-prefixed top-level keys (`_comment`, `_note_security`, etc.) are ignored by the parser. Use them inline to document your config without external comments — the JSON spec doesn't natively support comments, so the runtime treats `_*` keys as the convention.
+
+```json
+{
+  "_comment": "Last edited 2026-05-28 — switched skill_store to sqlite for AMP-style dogfooding",
+  "substrate": { "skill_store": "sqlite" }
+}
+```
+
+---
+
+## Adopter-custom substrate impls
+
+Write `class FooSkillStore implements SkillStore { ... }` (or MemoryStore, LocalModel). Wire it via either:
+
+**(a) Programmatic bootstrap (recommended today)** — write your own bootstrap script that constructs the registry directly:
+
+```typescript
+import { Registry, McpServer, Scheduler } from "skillscript-runtime";
+import { FooSkillStore } from "./foo-skill-store.js";
+
+const registry = new Registry();
+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.
+
+**(b) `connectors.json` custom form** (deferred to follow-up):
+
+```json
+"skill_store": {
+  "type": "custom",
+  "module": "./foo-skill-store.js",
+  "export": "FooSkillStore",
+  "config": { ... }
+}
+```
+
+Currently surfaces an error and falls back to the default — sync `bootstrap()` can't dynamic-import. Track the async-bootstrap promotion as future work.
+
+---
+
+## Operational tips
+
+### Switching substrates without losing data
+
+The substrate switch is a runtime wiring change, not a data migration. Switching from `filesystem` to `sqlite` doesn't move your `.skill.md` files into the Sqlite db automatically — the dashboard will show an empty skill list because the new Sqlite db is fresh.
+
+To preserve your skills across a switch:
+
+1. Read each `.skill.md` file from `~/.skillscript/skills/` (or your `skillsDir`)
+2. Call `skill_write` MCP tool (or `store.store(name, source)` programmatically) to land them in the new substrate
+
+A bundled migration tool isn't shipped — different adopters want different things (rename normalization, metadata enrichment, dry-run safety).
+
+### Multi-instance posture
+
+Running both a dev instance (filesystem) and an adopter instance (sqlite or custom) side by side is common. Use separate `--port` + `--connectors` paths:
+
+```bash
+# Dev — filesystem skills, port 7878
+skillfile dashboard --host 127.0.0.1 --port 7878
+
+# Adopter — sqlite skills, port 7879
+skillfile dashboard --host 127.0.0.1 --port 7879 --connectors ~/.skillscript/adopter-connectors.json
+```
+
+See [`docs/adopter-playbook.md`](adopter-playbook.md) § "Two-instance posture" for the broader pattern.
+
+### Verifying which substrate is wired
+
+After a config change + restart, verify via `runtime_capabilities`:
+
+```bash
+curl -s -X POST http://localhost:7878/rpc \
+  -H "content-type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"runtime_capabilities","arguments":{"include":["skillStores"]}}}' | jq
+```
+
+Output includes the wired SkillStore's `implementation` field (`FilesystemSkillStore` or `SqliteSkillStore`).