skillscript-runtime 0.10.0 → 0.13.5

package/docs/sqlite-skill-store.md

@@ -0,0 +1,167 @@
+# SqliteSkillStore — example
+
+Worked example of `SkillStore` against a SQLite database. Copy this directory into your codebase, customize per your storage needs, register with skillscript-runtime's `Registry`. This README is written for the agent implementing your adopter's connector — including the human reviewing the PR.
+
+**What this demonstrates**: the locked SkillStore contract surface (8 methods + `staticCapabilities`) wired through real SQL with two-table versioning, transactional status transitions, and JSON-extract tag filters.
+
+---
+
+## The three-leg model
+
+SkillStore is pluggable. Three legs ship out of the box, but the third is the open one:
+
+```
+SkillStore (choose which connector)
+   ├── FilesystemSkillStore (bundled, FS-backed)
+   ├── SqliteSkillStore     (this example, DB-backed)
+   └── Adopter-custom        (you write your own)
+```
+
+If your substrate is AMP, Pinecone, S3, Postgres, or anything else, write a `class FooSkillStore implements SkillStore { ... }` and call `registry.registerSkillStore("primary", new FooSkillStore(...))`. The runtime is none the wiser.
+
+This SqliteSkillStore is one such impl — useful as a copy-paste starting point, or directly usable if your needs match.
+
+---
+
+## Quick start
+
+```typescript
+import { Registry } from "skillscript-runtime";
+import { SqliteSkillStore } from "./SqliteSkillStore.js";
+
+const registry = new Registry();
+registry.registerSkillStore("primary", new SqliteSkillStore({ dbPath: "skills.db" }));
+
+// Wire the rest of the runtime (scheduler, mcpServer) using the registry.
+```
+
+Author skills programmatically:
+
+```typescript
+const store = registry.getSkillStore("primary");
+await store.store("morning-status", `# Skill: morning-status
+# Status: Approved
+t:
+    ! report status
+default: t
+`);
+```
+
+Or via the dashboard, or via `skill_write` MCP tool — same backend, same result.
+
+---
+
+## When to use SqliteSkillStore (and when not)
+
+**Use it when**:
+
+- You're embedding skillscript-runtime as a library and want skills in a database rather than `.skill.md` files
+- Your deployment has no persistent filesystem (container-only) but does have SQLite
+- You need richer query semantics than filesystem listing (tag filters, transactional status transitions)
+
+**Don't use it when**:
+
+- You're using the bundled CLI (`skillfile compile`, `skillfile lint`, `skillfile list`). The CLI is filesystem-first by design — `vim foo.skill.md && skillfile lint foo` is the natural authoring loop. The CLI does NOT use SqliteSkillStore. Sqlite-backed skills are authored via dashboard or `skill_write` MCP tool.
+- Your skills are authored as files-on-disk and committed to git as part of the source tree. FilesystemSkillStore is the right choice there.
+
+This is "first-class" in the **programmatic-embedding** sense, not the CLI sense. Treat the example as a substrate-portability proof point + a copy-paste starting point.
+
+---
+
+## Schema
+
+Two tables:
+
+```sql
+CREATE TABLE skills (
+  name TEXT PRIMARY KEY,
+  current_version TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  status TEXT NOT NULL,                  -- 'Draft' | 'Approved' | 'Disabled'
+  source TEXT NOT NULL,                  -- the .skill.md body bytes
+  description TEXT,                      -- extracted from `# Description:` header
+  metadata_json TEXT,                    -- optional metadata bag (tags, author, etc.)
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  status_changed_at INTEGER
+);
+
+CREATE TABLE skill_versions (
+  name TEXT NOT NULL,
+  version TEXT NOT NULL,                 -- short hash (12 chars)
+  content_hash TEXT NOT NULL,
+  source TEXT NOT NULL,                  -- full body, preserved per version
+  status TEXT NOT NULL,
+  previous_status TEXT,                  -- populated by update_status
+  changed_at INTEGER NOT NULL,
+  changed_by TEXT,
+  PRIMARY KEY (name, version)
+);
+```
+
+`skills` is the fast-path read for `load()` / `metadata()` / `query()`. `skill_versions` is the append-only history for `versions()` — and unlike FilesystemSkillStore, it preserves full body bytes per version, so `load(name, version)` can return historical content.
+
+WAL is enabled at bootstrap so concurrent readers don't block writers.
+
+---
+
+## Footgun guard: `delete()` is hard-cascade
+
+**`delete()` removes both the `skills` row AND its `skill_versions` rows.** If you need recovery, back up adopter-side BEFORE calling delete. Skill names can be reused after delete (no orphan history left behind).
+
+This is the locked semantic. If your adopter substrate has compliance requirements (audit-grade retention) or you hit a "wait, I deleted that" moment, the upgrade path is soft-delete (tombstone `status='Deleted'` + filter from query results) — but that's an adopter-side choice; the bundled SqliteSkillStore stays hard-cascade.
+
+---
+
+## Feature flags
+
+`staticCapabilities()` declares:
+
+| Feature | Value | What it means |
+|---|---|---|
+| `supports_writes` | ✓ | `store()` / `update_status()` / `delete()` mutate state |
+| `supports_versioning` | ✓ | `versions()` returns history; `load(name, version)` returns historical bytes |
+| `supports_tag_filter` | ✓ | `query({ tag: "foo" })` works via `json_extract(metadata_json, '$.tags')` (O(n) scan) |
+| `supports_audit_trail` | ✓ | `update_status()` populates `previous_status` on every transition |
+| `supports_atomic_status_transitions` | ✓ | UPDATE skills + INSERT skill_versions wrapped in a transaction |
+
+The atomic transitions are the SQL advantage over FilesystemSkillStore (which declares `supports_atomic_status_transitions: false` because filesystem writes can tear between body rewrite + sidecar append).
+
+---
+
+## Authoring loop
+
+SqliteSkillStore is the storage layer. Authoring happens above:
+
+- **Dashboard**: visit `http://localhost:7878`, create/edit skills through the UI; dashboard writes via `skill_write` MCP tool → SqliteSkillStore
+- **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).
+
+---
+
+## Approval-token stamping
+
+Skill bodies that declare `# Status: Approved` get a token stamped on `store()` automatically: `# Status: Approved v1:<hex>`. Same behavior as FilesystemSkillStore. Transitions to `Approved` via `update_status()` stamp the token; transitions away strip it.
+
+Adopters who want a stronger `f()` for the token (HMAC-SHA256 instead of the default) can register a custom approval fn before calling `store()`/`update_status()`:
+
+```typescript
+import { registerApprovalFn } from "skillscript-runtime";
+registerApprovalFn("v2", (body) => hmacSha256(SECRET, body));
+```
+
+---
+
+## Forking checklist
+
+When forking into your codebase:
+
+1. Rename the class (e.g., `PostgresSkillStore`, `AmpSkillStore`)
+2. Replace the SQL with your substrate's API (HTTP, MemoryStore, 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`)
+
+The conformance suite catches drift from the contract surface. If your fork passes, the runtime treats it interchangeably with FilesystemSkillStore / SqliteSkillStore / etc.

package/examples/README.md

@@ -1,18 +1,18 @@
 # Examples
 
-Curated production-quality skills demonstrating distinct language patterns. Each compiles + lints clean and can be run directly via `skillfile run examples/<name>.skill.md` (some require connectors — see the per-skill notes below).
+Curated production-quality skills demonstrating distinct language patterns. The `.skill.md` files live in [`skillscripts/`](./skillscripts/); each compiles + lints clean and can be run directly via `skillfile run examples/skillscripts/<name>.skill.md` (some require connectors — see the per-skill notes below).
 
 For full language semantics, see [`../docs/language-reference.md`](../docs/language-reference.md).
 
 | Example | Patterns demonstrated |
 |---|---|
-| [`hello.skill.md`](./hello.skill.md) | Three-command first run; `! emit`; default target; `# Vars:` declared inputs |
-| [`morning-brief.skill.md`](./morning-brief.skill.md) | Multi-target with `needs:`; cron-fired with `EVENT.fired_at_*`; `# OnError:` fallback; dual `# Output:` (slack + prompt-context); `# Requires:` user-var cascade with fallback; LocalModel + retrieval composition |
-| [`doc-qa-with-citations.skill.md`](./doc-qa-with-citations.skill.md) | Single-target retrieval; `(fallback: [])` op-level fallback; LLM-with-citation pattern; pipe filter `\|json` for prompt embedding |
-| [`classify-support-ticket.skill.md`](./classify-support-ticket.skill.md) | `if`/`elif`/`else` multi-branch routing; classifier-cascade pattern; MemoryStore `$` writes with structured `domain_tags`; `$set` literal binding |
-| [`cut-release-tag.skill.md`](./cut-release-tag.skill.md) | `??` interactive ask-for-input; `else:` short-circuit on multiple targets; `@` shell ops with per-op error fallback; rollback-on-failure flow |
-| [`service-health-watch.skill.md`](./service-health-watch.skill.md) | `foreach` iteration; cron-fired with `expires_at=$(EVENT.fired_at_plus_1d_unix)` TTL math; classifier-gated MemoryStore writes; pipe filter `\|url` for path-safe interpolation |
-| [`feedback-sentiment-scan.skill.md`](./feedback-sentiment-scan.skill.md) | `in` / `not in` set-membership ops; dedupe-via-seen-markers idiom; nested `if`/`elif` classification cascade; TTL on bookkeeping writes |
+| [`hello.skill.md`](./skillscripts/hello.skill.md) | Three-command first run; `! emit`; default target; `# Vars:` declared inputs |
+| [`morning-brief.skill.md`](./skillscripts/morning-brief.skill.md) | Multi-target with `needs:`; cron-fired with `EVENT.fired_at_*`; `# OnError:` fallback; dual `# Output:` (slack + prompt-context); `# Requires:` user-var cascade with fallback; LocalModel + retrieval composition |
+| [`doc-qa-with-citations.skill.md`](./skillscripts/doc-qa-with-citations.skill.md) | Single-target retrieval; `(fallback: [])` op-level fallback; LLM-with-citation pattern; pipe filter `\|json` for prompt embedding |
+| [`classify-support-ticket.skill.md`](./skillscripts/classify-support-ticket.skill.md) | `if`/`elif`/`else` multi-branch routing; classifier-cascade pattern; MemoryStore `$` writes with structured `domain_tags`; `$set` literal binding |
+| [`cut-release-tag.skill.md`](./skillscripts/cut-release-tag.skill.md) | `??` interactive ask-for-input; `else:` short-circuit on multiple targets; `@` shell ops with per-op error fallback; rollback-on-failure flow |
+| [`service-health-watch.skill.md`](./skillscripts/service-health-watch.skill.md) | `foreach` iteration; cron-fired with `expires_at=$(EVENT.fired_at_plus_1d_unix)` TTL math; classifier-gated MemoryStore writes; pipe filter `\|url` for path-safe interpolation |
+| [`feedback-sentiment-scan.skill.md`](./skillscripts/feedback-sentiment-scan.skill.md) | `in` / `not in` set-membership ops; dedupe-via-seen-markers idiom; nested `if`/`elif` classification cascade; TTL on bookkeeping writes |
 
 ## Connector requirements
 
@@ -31,20 +31,20 @@ Skills that talk to MCP tools (like `calendar.list_events`) need that tool wired
 
 ```sh
 # Cold install — no Ollama, no MCP, no external state
-skillfile run examples/hello.skill.md
+skillfile run examples/skillscripts/hello.skill.md
 
 # With overrides
-skillfile run examples/hello.skill.md --input WHO=Scott
+skillfile run examples/skillscripts/hello.skill.md --input WHO=Scott
 
 # Preview the compiled artifact without execution
-skillfile compile examples/hello.skill.md
+skillfile compile examples/skillscripts/hello.skill.md
 
 # Mechanical preview — $/~/> ops short-circuit (useful for examining flow
 # without firing real LLM calls)
-skillfile run examples/morning-brief.skill.md --mechanical
+skillfile run examples/skillscripts/morning-brief.skill.md --mechanical
 
 # Render the control-flow graph
-skillfile diagram examples/cut-release-tag.skill.md
+skillfile diagram examples/skillscripts/cut-release-tag.skill.md
 ```
 
 ## Programmatic example

package/examples/connectors/LocalModelTemplate/LocalModelTemplate.ts

@@ -0,0 +1,138 @@
+/**
+ * LocalModelTemplate — fork-me skeleton for writing your own LocalModel impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error.
+ * Adopters writing OpenAI-compat / Anthropic-compat / vLLM / TGI / SGLang /
+ * hosted-LLM / any-other LocalModel substrate fork this directory.
+ *
+ * The bundled `OllamaLocalModel` (in `src/connectors/local-model.ts`) is
+ * Ollama-specific. When that doesn't fit, fork from here.
+ *
+ * Forking workflow:
+ *   1. Copy this directory: `cp -r examples/connectors/LocalModelTemplate examples/connectors/MyLocalModel`
+ *   2. Rename the class — typically `<Substrate>LocalModel` (e.g., `OpenAICompatLocalModel`, `AnthropicLocalModel`, `VllmLocalModel`)
+ *   3. Implement `run()` against your transport
+ *   4. Implement `manifest()` returning substrate metadata
+ *   5. Update `staticCapabilities()` to declare what your impl supports
+ *   6. Register from your adopter bootstrap:
+ *        `registry.registerLocalModel("default", new MyLocalModel({ ... }))`
+ *   7. Validate via the conformance suite:
+ *        `LocalModelConformance.buildTests({ build: () => new MyLocalModel(...), ctor: MyLocalModel })`
+ *
+ * See `src/connectors/local-model.ts` (`OllamaLocalModel`) for a working
+ * reference implementation against the Ollama HTTP API. The full contract
+ * spec lives in `src/connectors/types.ts` (`LocalModel` interface).
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever LocalModel impl
+ * you register. The auto-wired `$ llm` MCP bridge wraps your impl
+ * transparently — once registered, `$ llm prompt="..."` dispatches through
+ * your fork without any additional wiring.
+ *
+ * **Note on declarative wiring**: LocalModel is intrinsically *singleton* per
+ * deployment (one default per runtime), unlike McpConnector which is
+ * multi-instance. There's no `registerLocalModelClass()` equivalent of
+ * `registerConnectorClass()` — adopters wire their LocalModel
+ * programmatically via `registry.registerLocalModel()` from their bootstrap.
+ * Declarative custom-LocalModel via `connectors.json` substrate `{type:
+ * "custom", module, export, config}` form is deferred until async-bootstrap
+ * support lands (cross-cutting limitation across all three substrate slots).
+ */
+
+import type {
+  LocalModel,
+  LocalModelCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your substrate's connection config (endpoint, auth, model selection, etc.). */
+export interface LocalModelTemplateConfig {
+  // TODO — declare the fields your substrate needs to connect.
+  // Examples:
+  //   endpoint?: string;           // OpenAI-compat / vLLM / TGI URL
+  //   apiKey?: string;             // hosted services
+  //   defaultModel?: string;       // model name / tag
+  //   timeoutMs?: number;
+  exampleConfigField?: string;
+}
+
+export class LocalModelTemplate implements LocalModel {
+  /**
+   * Declare what your impl supports. The runtime + lint consult these flags.
+   * Set conservatively — overclaiming triggers cryptic downstream failures;
+   * underclaiming hides usable features.
+   */
+  static staticCapabilities(): LocalModelCapabilities {
+    return {
+      connector_type: "local_model",
+      implementation: "LocalModelTemplate", // ← rename to your class name
+      contract_version: "1.0.0",
+      features: {
+        // TODO — set each flag based on what your substrate can actually do.
+        supports_max_tokens: false,  // can opts.maxTokens cap output?
+        supports_timeout: false,     // do you honor a per-call timeout?
+        supports_streaming: false,   // does your run() stream tokens? (v1 contract is non-streaming — flag for forward-compat)
+        supports_embedding: false,   // does your substrate also expose embeddings?
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: LocalModelTemplateConfig) {
+    // TODO — establish your substrate connection. For HTTP: store base URL
+    // + auth headers + default model. For SDK: cache the client instance.
+    throw new Error("LocalModelTemplate is a fork-me skeleton; replace with your impl.");
+  }
+
+  /**
+   * Dispatch a prompt and return the model's response text.
+   *
+   * `prompt` — the substituted prompt body (template substitution already
+   * resolved by the runtime; you get the final string).
+   *
+   * `opts`:
+   *   - `maxTokens` — optional cap on output length. Honor if `supports_max_tokens: true`.
+   *   - `model` — optional override of the configured default. Honor if your
+   *     substrate supports multiple models per instance.
+   *
+   * Return the response text directly (not wrapped in an envelope). The
+   * `LocalModelMcpConnector` bridge exposes this as `$ llm prompt="..." -> R`
+   * where R binds to your string return value.
+   *
+   * On dispatch failure: throw. Don't return error envelopes silently — the
+   * runtime's op-level `(fallback: ...)` machinery catches throws cleanly.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async run(_prompt: string, _opts: { maxTokens?: number; model?: string }): Promise<string> {
+    // TODO — dispatch via your transport.
+    //   - Map prompt + opts to your substrate's wire format (chat completion / completion / etc.)
+    //   - Apply your per-call timeout
+    //   - Parse the response; extract the text
+    //   - Throw on dispatch failure (don't return error envelope silently)
+    throw new Error("TODO: run() — dispatch prompt + return response text.");
+  }
+
+  /**
+   * Capability snapshot for `runtime_capabilities` discovery. Return free-form
+   * substrate-specific metadata.
+   *
+   * Per `LocalModelManifest` in `src/connectors/types.ts`, known curated fields:
+   *   - `kind`: string tag for substrate flavor ("openai-compat", "vllm", etc.)
+   *   - `default_model`: configured default model name
+   *   - `endpoint`: URL the impl connects to
+   *   - `models_available`: list when introspectable (e.g., `/v1/models` for OpenAI-compat)
+   *   - `fetch_error`: set when introspection failed (don't silently cache empty array)
+   * Plus `[key: string]: unknown` for substrate extensions.
+   *
+   * The bundled `OllamaLocalModel.manifest()` returns:
+   *   { capabilities_version: "1", manifest: { kind: "ollama",
+   *     endpoint: "...", default_model: "gemma2:9b", models_available: [...] } }
+   */
+  async manifest(): Promise<ManifestInfo<"local_model">> {
+    // TODO — return a snapshot of your substrate's metadata.
+    //   - kind: identify the substrate
+    //   - endpoint: where you connect
+    //   - default_model: what model you'll dispatch to
+    //   - models_available: list if you can introspect; surface fetch_error if introspection fails
+    throw new Error("TODO: manifest() — return substrate metadata snapshot.");
+  }
+}

package/examples/connectors/LocalModelTemplate/README.md

@@ -0,0 +1,134 @@
+# LocalModelTemplate — fork-me skeleton
+
+A skeleton `LocalModel` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
+
+**Use this when you want LocalModel inference backed by:**
+- An OpenAI-compat HTTP endpoint (vLLM, TGI, SGLang, llama.cpp server)
+- A hosted LLM API (OpenAI, Anthropic, Cohere — though most adopters wire those via `RemoteMcpConnector` + the provider's MCP server instead)
+- A custom transport (gRPC, WebSocket, in-process inference)
+- A multi-model gateway
+
+The bundled `OllamaLocalModel` (in `src/connectors/local-model.ts`) is Ollama-specific. Fork from here when that doesn't fit.
+
+## The two legs
+
+```
+LocalModel (choose which connector)
+   ├── OllamaLocalModel (bundled, Ollama HTTP — src/connectors/local-model.ts)
+   └── Your fork from this template
+```
+
+LocalModel is the narrowest contract — just 2 methods + staticCapabilities. Most of the work in a fork is substrate-specific (auth, wire format, response parsing), not contract conformance.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/LocalModelTemplate examples/connectors/MyLocalModel
+```
+
+1. **Rename the class.** Convention: `<Substrate>LocalModel` (e.g., `OpenAICompatLocalModel`, `AnthropicLocalModel`, `VllmLocalModel`).
+2. **Define your config interface.** Edit `LocalModelTemplateConfig` to declare what your substrate needs (endpoint URL, API key, default model, timeout, etc.).
+3. **Implement `run()`** — translate `(prompt, opts)` to your substrate's wire format; dispatch; parse the response text.
+4. **Implement `manifest()`** — return substrate metadata (kind, endpoint, default model, available models when introspectable).
+5. **Update `staticCapabilities()`** to declare what your impl supports.
+6. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyLocalModel } from "./MyLocalModel.js";
+
+   const registry = new Registry();
+   registry.registerLocalModel("default", new MyLocalModel({ /* config */ }));
+   ```
+
+   The auto-wired `$ llm` MCP bridge wraps your impl transparently — once registered, `$ llm prompt="..."` dispatches through your fork without additional wiring.
+
+7. **Validate via the conformance suite:**
+
+   ```typescript
+   import { describe, it } from "vitest";
+   import { LocalModelConformance } from "skillscript-runtime/testing";
+   import { MyLocalModel } from "./MyLocalModel.js";
+
+   describe("MyLocalModel conformance", () => {
+     const tests = LocalModelConformance.buildTests({
+       build: () => new MyLocalModel({ /* test config */ }),
+       ctor: MyLocalModel,
+     });
+     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+   });
+   ```
+
+## Reference implementation
+
+The bundled `OllamaLocalModel` at `src/connectors/local-model.ts` is the canonical reference (164 LOC):
+
+- Ollama HTTP API (`POST /api/generate`, `GET /api/tags`)
+- AbortController timeout pattern
+- Manifest caches successful introspection but NOT failures (retries on next call)
+- Deduped stderr warning for fetch errors
+- Surfaces `fetch_error` in manifest when `/api/tags` introspection fails
+
+The error-handling patterns (don't silently cache failures; surface in manifest; dedupe-log) apply to any LocalModel substrate that introspects.
+
+## Contract surface (2 methods)
+
+LocalModel is the narrowest contract surface in skillscript:
+
+| Method | What it does | When called |
+|---|---|---|
+| `run(prompt, opts)` | Dispatch a prompt; return response text | Every `$ llm prompt="..." -> R` op (via the LocalModelMcpConnector bridge) |
+| `manifest()` | Substrate metadata for discovery | At startup + on-demand from MCP clients |
+
+Plus `staticCapabilities()` (required static).
+
+### `run()` semantics
+
+- **`prompt`** — already-substituted prompt body. Template substitution (`${VAR}` resolution) happens before your impl is called; you get the final string.
+- **`opts.maxTokens`** — optional output length cap. Honor if `supports_max_tokens: true`.
+- **`opts.model`** — optional per-call model override. Useful for adopters with multi-model gateways. Honor if your substrate supports it.
+- **Return** — the response text directly. NOT wrapped in an envelope. The bridge passes this through to skill source as `$(R)`.
+
+On dispatch failure: **throw**. The runtime's op-level `(fallback: ...)` machinery catches throws cleanly. Don't return error envelopes silently — that's the silent-recovery footgun pattern.
+
+### `manifest()` semantics
+
+Surface enough substrate metadata for adopters running `runtime_capabilities` to understand what's wired. Curated fields per `LocalModelManifest`:
+
+- `kind` — substrate flavor tag (`"openai-compat"`, `"vllm"`, `"anthropic"`, etc.)
+- `default_model` — configured default model name
+- `endpoint` — URL your impl connects to (helps debugging)
+- `models_available` — list when introspectable
+- `fetch_error` — set when introspection failed; don't silently cache empty array
+
+Plus `[key: string]: unknown` for substrate extensions.
+
+## A note on declarative wiring
+
+Unlike `McpConnector` (which has `registerConnectorClass()` for adopter-extensible declarative wiring via `connectors.json`), `LocalModel` is intrinsically *singleton* per deployment — one default per runtime. There's no equivalent class registry.
+
+Adopters wire their custom LocalModel **programmatically** from their bootstrap:
+
+```typescript
+registry.registerLocalModel("default", new MyLocalModel({ /* config */ }));
+```
+
+Declarative custom-LocalModel via `connectors.json` `substrate.local_model: {type: "custom", module, export, config}` form is **deferred** until async-bootstrap support lands. Same limitation applies to `SkillStore` and `MemoryStore` custom forms — sync `bootstrap()` can't `await import()`. Not LocalModel-specific.
+
+## Wiring against the dashboard / MCP
+
+Runtime hosts (MCP server + web dashboard) honor whichever LocalModel impl you register. To make your fork visible through `skillfile dashboard`:
+
+- Write a custom bootstrap that constructs the runtime with your LocalModel
+- Or register via `registry.registerLocalModel("default", new MyLocalModel(...))` before `bootstrap()` returns
+
+The auto-wired `$ llm` MCP bridge picks up your registration automatically — skills writing `$ llm prompt="..." -> R` get your impl without additional config.
+
+## Further reading
+
+- **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
+- **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — programmatic-bootstrap patterns
+- **`src/connectors/types.ts`** — authoritative `LocalModel` interface + `LocalModelManifest` curated fields
+- **`src/connectors/local-model.ts`** — `OllamaLocalModel` reference impl
+- **`src/connectors/local-model-mcp.ts`** — the `LocalModelMcpConnector` bridge that wraps your impl as `$ llm`
+- **`src/testing/conformance.ts`** — the per-contract conformance test suites