skillscript-runtime 0.9.9 → 0.13.2

package/examples/connectors/McpConnectorTemplate/README.md

@@ -0,0 +1,153 @@
+# McpConnectorTemplate — fork-me skeleton
+
+A skeleton `McpConnector` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
+
+**Most adopters don't need this template.** Four bundled impls already cover the common cases:
+
+| Bundled impl | What it covers |
+|---|---|
+| `RemoteMcpConnector` | Stdio bridging to remote MCP servers (`npx mcp-remote ...`). YouTrack, GitHub, Linear, most adopter MCP wiring goes through this. JSON-configurable via `connectors.json`. |
+| `CallbackMcpConnector` | Wraps a JS function. Test rigs + embedder-wired transports where the dispatch is local code. |
+| `LocalModelMcpConnector` | Bridges a registered `LocalModel` as `$ llm prompt=...`. Auto-wired when `substrate.local_model` is set. |
+| `MemoryStoreMcpConnector` | Bridges a registered `MemoryStore` as `$ memory mode=...`. Auto-wired when `substrate.memory_store` is set. |
+
+**Fork this template only when none of those fit** — e.g.:
+
+- Direct HTTP MCP (JSON-RPC over HTTP, no child process)
+- WebSocket MCP
+- In-process MCP (call methods directly without IPC)
+- Custom transport that doesn't match stdio framing
+- Cross-thread / worker-pool dispatch
+
+If you're trying to wire a remote MCP server like YouTrack or GitHub, **you want `RemoteMcpConnector` in `connectors.json`**, not this template. See `connectors.json.example` for the wiring pattern.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/McpConnectorTemplate examples/connectors/MyMcpConnector
+```
+
+1. **Rename the class.** Convention: `<Transport>McpConnector` (e.g., `HttpMcpConnector`, `WebSocketMcpConnector`, `InProcessMcpConnector`).
+2. **Define your config interface.** Edit `McpConnectorTemplateConfig` to declare what your transport needs (URL, auth, timeouts, etc.).
+3. **Implement `call()`** — translate `(toolName, args)` to your transport's wire format; dispatch; return the result.
+4. **Implement `manifest()`** — return transport metadata for `runtime_capabilities` discovery.
+5. **Update `staticCapabilities()`** to declare what your impl supports.
+6. **(Optional) Implement `staticTools()`** — return the closed-set list of tools your connector exposes if static; lint validates `$ name.tool` against this list. Return `null` (or omit) if the surface is runtime-discovered.
+7. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyMcpConnector } from "./MyMcpConnector.js";
+
+   const registry = new Registry();
+   registry.registerMcpConnector("mytool", new MyMcpConnector({ /* config */ }));
+   ```
+
+8. **(Optional) For `connectors.json` JSON-instantiability** — add a static `fromConfig(config)` factory + register the class via `registerConnectorClass()`:
+
+   ```typescript
+   import { registerConnectorClass } from "skillscript-runtime/connectors";
+
+   registerConnectorClass("MyMcpConnector", {
+     ctor: MyMcpConnector,
+     fromConfig: (cfg) => MyMcpConnector.fromConfig(cfg),
+   });
+   ```
+
+   Call this BEFORE `loadConnectorsConfig` runs in your bootstrap. Then adopters can declare instances in `connectors.json`:
+
+   ```json
+   {
+     "myinstance": {
+       "class": "MyMcpConnector",
+       "config": { "endpoint": "https://...", "authToken": "${MY_TOKEN}" }
+     }
+   }
+   ```
+
+## Reference implementations
+
+The bundled impls are the canonical reference:
+
+- **`src/connectors/mcp-remote.ts`** — `RemoteMcpConnector`. Most comprehensive: stdio framing (LSP and newline), child process lifecycle (spawn → initialize → tools/list cache → SIGTERM/SIGKILL on dispose), `fromConfig` factory with strict validation, per-message timeout discipline. The closest reference for any transport that needs robust lifecycle management.
+- **`src/connectors/mcp.ts`** — `CallbackMcpConnector`. Minimal reference: 60 LOC. The closest reference for embedder-wired transports.
+
+When in doubt, read both + the bridge classes (`local-model-mcp.ts`, `memory-store-mcp.ts`) for how single-substrate bridges work.
+
+## Contract surface (2 methods)
+
+McpConnector is the narrowest of the five contracts:
+
+| Method | What it does | When called |
+|---|---|---|
+| `call(toolName, args, ctx?)` | Dispatch a tool call to your transport | Every `$ <connector> ...` op |
+| `manifest()` | Transport metadata for discovery | At startup + on-demand from MCP clients |
+
+Plus `staticCapabilities()` (required static) and `staticTools()` (optional static).
+
+### `call()` semantics
+
+- **`toolName`** — the tool the caller wants:
+  - `$ youtrack.search_issues query="..."` → `toolName = "search_issues"`
+  - `$ youtrack query="..."` (bare form) → `toolName` is the *unqualified op name* (typically the connector's auto-routing target)
+- **`args`** — kwargs from the skill source as a plain object
+- **`ctxOverrides`** — optional identity propagation (`agentId`, `isAdmin`). Connectors that support identity-propagation thread these to upstream
+- **Return** — whatever the upstream MCP returns. Skills bind via `-> R`; if the return shape isn't statically discoverable, lint emits a tier-3 advisory when callers descend (`$(R.field)`)
+
+On dispatch failure, **throw** — the runtime's op-level `(fallback: ...)` machinery handles it cleanly. Don't return error envelopes silently; the v0.5.0+ contract surfaces inner-tool errors via throw.
+
+### `staticTools()` lint integration
+
+If your connector exposes a known closed set of tools (e.g., a JIRA wrapper that only exposes `search_issues`, `get_issue`, `create_issue`), implementing `staticTools()` lets lint validate `$ name.tool` references at authoring time:
+
+```typescript
+static staticTools(): string[] {
+  return ["search_issues", "get_issue", "create_issue"];
+}
+```
+
+Skills that write `$ jira.unknown_tool ...` fail lint with `unknown-tool-on-connector` (tier-1 error).
+
+If your surface is runtime-discovered (e.g., `RemoteMcpConnector` wrapping an arbitrary upstream MCP), return `null` or omit the method. Lint emits a tier-3 advisory on dotted dispatch instead of green-lighting.
+
+## Wiring against the dashboard / MCP
+
+Runtime hosts (MCP server + web dashboard) honor whichever McpConnector instances your registry has. There's no `substrate` slot for McpConnector — that's intentional, because McpConnector is intrinsically *instanced* (you'll have multiple: `youtrack`, `github`, `jira`, ...) not singleton.
+
+Two registration paths:
+
+- **Programmatic** (your bootstrap):
+  ```typescript
+  registry.registerMcpConnector("youtrack", new RemoteMcpConnector({ command: "npx", args: ["mcp-remote", "..."] }));
+  registry.registerMcpConnector("github", new RemoteMcpConnector({ ... }));
+  ```
+- **Declarative** (`connectors.json`):
+  ```json
+  {
+    "youtrack": { "class": "RemoteMcpConnector", "config": { "command": "npx", ... } },
+    "github":   { "class": "RemoteMcpConnector", "config": { ... } }
+  }
+  ```
+
+The declarative path is the canonical adopter pattern for stdio-bridged remote MCPs. Your fork is for transports the declarative path can't express.
+
+## McpConnector vs. SkillStore / MemoryStore differences
+
+| Aspect | McpConnector | SkillStore / MemoryStore |
+|---|---|---|
+| Methods | 2 (call, manifest) | 3-8 (more state machine) |
+| Cardinality | Many instances per deployment | One singleton per slot |
+| Substrate config | Per-instance via top-level keys | `substrate` section short/object/custom |
+| Class extensibility | `registerConnectorClass()` for adopter-custom classes | Programmatic bootstrap (or `substrate.skill_store: {type: "custom", ...}` once async-bootstrap lands) |
+| Auto-wired bridges | `llm` + `memory` + `memory_write` (LocalModel + MemoryStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
+
+McpConnector is fundamentally the "dispatch to external tools" surface — narrowest contract, broadest range of impls.
+
+## Further reading
+
+- **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — `connectors.json` wiring (substrate + named MCP instances)
+- **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — Case 1 vs Case 2 wiring patterns; substrate-portable vs substrate-locked
+- **`src/connectors/types.ts`** — authoritative `McpConnector` interface
+- **`src/connectors/mcp-remote.ts`** — full-featured reference impl with stdio framing + lifecycle
+- **`src/connectors/mcp.ts`** — minimal reference impl
+- **`src/connectors/config.ts`** — `registerConnectorClass()` + `loadConnectorsConfig()`

package/examples/connectors/MemoryStoreTemplate/MemoryStoreTemplate.ts

@@ -0,0 +1,155 @@
+/**
+ * MemoryStoreTemplate — fork-me skeleton for writing your own MemoryStore impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error. The
+ * purpose is to surface the MemoryStore contract surface in a copy-and-customize
+ * shape so adopters writing AMP-, Pinecone-, Weaviate-, Qdrant-, or
+ * Postgres-backed MemoryStores have a starting skeleton.
+ *
+ * Forking workflow:
+ *   1. Copy this directory into your codebase (`cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore`)
+ *   2. Rename the class — typically `<Substrate>MemoryStore` (e.g., `PineconeMemoryStore`, `AmpMemoryStore`)
+ *   3. Implement each method against your substrate's API
+ *   4. Update `staticCapabilities()` to declare what your impl actually supports
+ *   5. Register from your adopter bootstrap:
+ *        `registry.registerMemoryStore("primary", new MyMemoryStore({ ... }))`
+ *   6. Validate via the conformance suite:
+ *        `MemoryStoreConformance.buildTests({ build: () => new MyMemoryStore(...), ctor: MyMemoryStore })`
+ *
+ * See `src/connectors/memory-store.ts` for the working reference implementation
+ * (`SqliteMemoryStore` — SQLite + FTS5 backing). The full contract spec lives in
+ * `src/connectors/types.ts` (`MemoryStore` interface + `PortableMemory` +
+ * `QueryFilters` + `MemoryWrite` types).
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever MemoryStore impl
+ * you register via the registry, so once your fork passes the conformance
+ * suite the entire `$ memory` / `$ memory_write` dispatch path reads + writes
+ * against your substrate.
+ */
+
+import type {
+  MemoryStore,
+  QueryFilters,
+  PortableMemory,
+  MemoryWrite,
+  MemoryWriteRecord,
+  MemoryStoreCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your substrate's connection config (host, dbName, API key, etc.). */
+export interface MemoryStoreTemplateConfig {
+  // TODO — declare the fields your substrate needs to connect.
+  // Examples:
+  //   pineconeApiKey?: string;
+  //   pineconeEnvironment?: string;
+  //   weaviateUrl?: string;
+  //   ampVault?: string;
+  exampleConfigField?: string;
+}
+
+export class MemoryStoreTemplate implements MemoryStore {
+  /**
+   * Declare what your impl supports. The runtime + lint consult these flags
+   * before exercising features. Set conservatively — overclaiming triggers
+   * cryptic downstream failures; underclaiming hides usable features.
+   */
+  static staticCapabilities(): MemoryStoreCapabilities {
+    return {
+      connector_type: "memory_store",
+      implementation: "MemoryStoreTemplate", // ← rename to your class name
+      contract_version: "1.0.0",
+      features: {
+        // TODO — set each flag based on what your substrate can actually do.
+        supports_writes: false,                  // can write() persist new memories?
+        supports_tag_filter: false,              // can query() filter by domain_tags?
+        supports_semantic: false,                // mode="semantic" supported?
+        supports_rerank: false,                  // mode="rerank" supported?
+        supports_thread_status_filter: false,    // can query() filter by thread_status?
+        supports_pinning: false,                 // does the substrate track pinned: true?
+        supports_decay_model: false,             // does the substrate honor decay_model?
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: MemoryStoreTemplateConfig) {
+    // TODO — establish your substrate connection. For SQL: open the database
+    // + run schema migrations. For vector DB: cache the SDK client + index
+    // name. For HTTP: store the base URL + auth headers.
+    throw new Error("MemoryStoreTemplate is a fork-me skeleton; replace with your impl.");
+  }
+
+  /**
+   * Capability snapshot for `runtime_capabilities` discovery. Return free-form
+   * substrate-specific metadata (kind, version, supported modes, score range, etc.).
+   *
+   * The bundled `SqliteMemoryStore.manifest()` returns:
+   *   { capabilities_version: "1", manifest: { kind: "sqlite-fts",
+   *       supported_modes: ["fts"], score_range: "unbounded",
+   *       supported_filters: ["domain_tags"], supports_write: true } }
+   */
+  async manifest(): Promise<ManifestInfo<"memory_store">> {
+    // TODO — return a snapshot of your substrate's capabilities.
+    throw new Error("TODO: manifest() — return substrate-specific capability snapshot.");
+  }
+
+  /**
+   * Query memories by mode + filter. Return `PortableMemory[]` ordered by
+   * relevance (most relevant first). Empty result is fine; never throw "not
+   * found" — return [].
+   *
+   * `QueryFilters` shape:
+   *   - `query`: string (search terms; substrate-specific interpretation)
+   *   - `limit`: number (max results)
+   *   - `mode`: "fts" | "semantic" | "rerank" | substrate-specific string
+   *   - Plus arbitrary additional filter fields (`domain_tags`, `thread_status`,
+   *     `payload_type`, `pinned`, `agent_id`, etc.) — substrate honors what
+   *     it supports, ignores the rest. Per the curated-subset framing in
+   *     `types.ts`, these top-level fields are first-class for substrates
+   *     that have them.
+   *
+   * `PortableMemory` core fields:
+   *   - Always: `id`, `summary`, `created_at`
+   *   - Often: `detail`, `score`, `domain_tags`, `payload_type`
+   *   - Per-substrate (curated): `pinned`, `confidence`, `thread_status`,
+   *     `recipients`, `expires_at`, `agent_id`, `vault`
+   *   - Catch-all: `metadata` object for substrate-specific extensions
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(_filters: QueryFilters): Promise<PortableMemory[]> {
+    // TODO — translate `filters` to your substrate's query API.
+    //   - Reject unsupported `mode` values with a clear error (don't silently
+    //     fall back; cold authors will be confused)
+    //   - Apply curated-subset filters (domain_tags, payload_type, etc.) where
+    //     the substrate supports them
+    //   - Map your substrate's result rows into `PortableMemory` shape
+    //   - Order by relevance (most relevant first)
+    //   - Honor `limit`
+    throw new Error("TODO: query() — return PortableMemory[] ordered by relevance.");
+  }
+
+  /**
+   * Persist a new memory entry. Return the substrate-assigned `id` +
+   * `created_at` (unix seconds).
+   *
+   * `MemoryWrite` shape:
+   *   - `content`: string (required; the memory body)
+   *   - `tags`: string[] (optional; routed to substrate's tag mechanism)
+   *   - `recipients`: string[] (optional advisory — substrates with alerting
+   *     machinery use this to route notifications, e.g., AMP's mailbox model)
+   *   - `expires_at`: number (optional; unix seconds — substrate-side TTL)
+   *   - `metadata`: Record<string, unknown> (catch-all for substrate-specific
+   *     extensions like `vault`, `payload_type`, `confidence`)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async write(_entry: MemoryWrite): Promise<MemoryWriteRecord> {
+    // TODO — persist the memory via your substrate.
+    //   - Generate or accept an id (substrate-dependent)
+    //   - Persist content + tags + metadata
+    //   - Apply recipients hint if your substrate has alerting
+    //   - Apply expires_at if your substrate has TTL
+    //   - Return { id, created_at }
+    throw new Error("TODO: write() — persist memory; return { id, created_at }.");
+  }
+}

package/examples/connectors/MemoryStoreTemplate/README.md

@@ -0,0 +1,169 @@
+# MemoryStoreTemplate — fork-me skeleton
+
+A skeleton `MemoryStore` 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 skillscript memories backed by:
+- A vector database (Pinecone, Weaviate, Qdrant, Chroma)
+- A memory system (AMP, hosted memory API)
+- A different SQL flavor (Postgres + pgvector, MySQL)
+- An HTTP CRUD service
+- Anything else with query + write semantics
+
+## The three legs
+
+```
+MemoryStore (choose which connector)
+   ├── SqliteMemoryStore (bundled, SQLite + FTS5 — src/connectors/memory-store.ts)
+   ├── (no other bundled impl — vector DBs and remote services are adopter-side)
+   └── Your fork from this template
+```
+
+The runtime is substrate-agnostic. Memories don't know which backend they're stored against — the contract is the `MemoryStore` interface, and any class implementing it works.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore
+```
+
+1. **Rename the class.** Convention: `<Substrate>MemoryStore` (e.g., `PineconeMemoryStore`, `PostgresMemoryStore`, `AmpMemoryStore`).
+2. **Define your config interface.** Edit `MemoryStoreTemplateConfig` to declare what your substrate needs (connection URL, API key, vault name, index name, etc.).
+3. **Implement each method.** Three methods + `staticCapabilities()`. Each has a TODO comment in the skeleton explaining what to do.
+4. **Update `staticCapabilities()`** to declare what your impl actually supports. The runtime + lint consult these flags before exercising features.
+5. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyMemoryStore } from "./MyMemoryStore.js";
+
+   const registry = new Registry();
+   registry.registerMemoryStore("primary", new MyMemoryStore({
+     // your config
+   }));
+   ```
+
+6. **Validate via the conformance suite:**
+
+   ```typescript
+   import { describe, it } from "vitest";
+   import { MemoryStoreConformance } from "skillscript-runtime/testing";
+   import { MyMemoryStore } from "./MyMemoryStore.js";
+
+   describe("MyMemoryStore conformance", () => {
+     const tests = MemoryStoreConformance.buildTests({
+       build: () => new MyMemoryStore({ /* test config */ }),
+       ctor: MyMemoryStore,
+     });
+     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+   });
+   ```
+
+   The conformance suite verifies your impl honors the contract: method presence, return-type shape, capability flag self-consistency. Passes → runtime treats your impl interchangeably with `SqliteMemoryStore`.
+
+## Reference implementation
+
+When in doubt about semantics, read the bundled impl:
+
+- **`src/connectors/memory-store.ts`** — `SqliteMemoryStore`, SQLite + FTS5-backed. Schema lives in `bootstrap()` (memories table + FTS virtual table + AFTER INSERT/UPDATE/DELETE triggers). Single-process. Capability flags: `supports_writes: true`, `supports_tag_filter: true`, FTS only (semantic / rerank false).
+
+## Contract surface (3 methods)
+
+The MemoryStore contract is narrower than SkillStore. Three methods + `staticCapabilities()`:
+
+| Method | What it does | When called |
+|---|---|---|
+| `query(filters)` | Read memories by mode + filter; return `PortableMemory[]` | Every `$ memory mode=... query=...` op |
+| `write(entry)` | Persist a new memory; return `{id, created_at}` | Every `$ memory_write content=... -> R` op + `memory_write` skill notify routes |
+| `manifest()` | Capability snapshot for `runtime_capabilities` discovery | At startup + on-demand from MCP clients |
+
+Per the curated-subset framing in `src/connectors/types.ts`, `PortableMemory` has a 4-tier field model:
+
+1. **Core fields** — `id`, `summary`, `detail`, `score` (always-meaningful)
+2. **Curated substrate subset** — top-level fields with portable concepts: `domain_tags`, `payload_type`, `knowledge_type`, `pinned`, `confidence`, `thread_status`, `recipients`, `expires_at`, `agent_id`, `vault`
+3. **Substrate-specific** — accessed via `metadata.X` (catch-all)
+4. **Ambient passthrough** — literal `$(MEMORY.field)` references for unknowns
+
+**Connector duplication discipline**: a curated-subset field must be at top-level only, never also in `metadata`. Silent divergence otherwise.
+
+## Query modes
+
+`QueryFilters.mode` is the dispatch axis:
+
+- **`"fts"`** — full-text search; substrate-defined (BM25, BM25F, etc.). `SqliteMemoryStore` supports this via FTS5.
+- **`"semantic"`** — embedding-based similarity. Vector-DB substrates support this; `SqliteMemoryStore` does not.
+- **`"rerank"`** — substrate-defined hybrid (e.g., FTS retrieve + embedding rerank). Optional.
+- **substrate-specific strings** — your fork can define its own modes; document them in `manifest().manifest.supported_modes`.
+
+Throw a clear error on unsupported modes (don't silently fall back; cold authors will be confused).
+
+## Filter fields
+
+`QueryFilters` extends a base shape with arbitrary additional filter keys. Common filters substrates honor:
+
+- **`domain_tags`** — string or array; substrate-specific match semantics (substring vs exact; AND vs OR)
+- **`payload_type`** — usually exact match
+- **`thread_status`** — usually exact match (set if your substrate has thread lifecycle)
+- **`pinned`** — boolean
+- **`agent_id`** — adopter-side scoping
+- **`recipients`** — array match (any-of)
+
+Honor what your substrate supports; ignore the rest. Document the supported set in `manifest().manifest.supported_filters`.
+
+## `write()` semantics
+
+The `MemoryWrite` shape:
+
+- **`content`** (required) — the memory body
+- **`tags`** (optional) — routed to your substrate's tag mechanism
+- **`recipients`** (optional) — advisory hint; substrates with alerting (e.g., AMP's mailbox model) use it
+- **`expires_at`** (optional) — unix seconds; substrates with TTL honor it
+- **`metadata`** (optional) — catch-all for substrate extensions (`vault`, `payload_type`, `confidence`, etc.)
+
+Return `{id, created_at}` — the substrate-assigned identifier + creation timestamp (unix seconds).
+
+If your substrate doesn't support writes (read-only memory like a search index over a static corpus), set `supports_writes: false` in `staticCapabilities()` and throw from `write()`. The runtime + lint will respect the flag.
+
+## Wiring against the dashboard / MCP
+
+Runtime hosts honor whichever MemoryStore impl your registry has. To make your fork visible through `skillfile dashboard`:
+
+- Write a custom bootstrap that constructs the runtime with your MemoryStore (see `src/bootstrap.ts` for the reference shape)
+- OR (planned future) declare in `~/.skillscript/connectors.json`:
+
+  ```json
+  {
+    "substrate": {
+      "memory_store": {
+        "type": "custom",
+        "module": "./my-memory-store.js",
+        "export": "MyMemoryStore",
+        "config": { "pineconeApiKey": "${PINECONE_KEY}" }
+      }
+    }
+  }
+  ```
+
+  Current limitation: sync `bootstrap()` can't dynamic-import, so the `custom` form surfaces an error today. Programmatic bootstrap is the path until async-bootstrap support lands.
+
+## MemoryStore vs SkillStore differences
+
+Both are substrate-agnostic, but they differ in shape:
+
+| Aspect | SkillStore | MemoryStore |
+|---|---|---|
+| Methods | 8 (load, query, metadata, versions, store, delete, update_status, manifest) | 3 (query, write, manifest) |
+| Versioning | First-class (`versions()`, `load(name, version)`) | Substrate-side (e.g., `supersededById` in AMP); not in contract |
+| Status lifecycle | Draft/Approved/Disabled with approval-token stamping | None |
+| Mutation gates | Approved transitions require approval token | None — writes are append-only |
+| Curated-subset fields | None | Many (`domain_tags`, `pinned`, `confidence`, `recipients`, etc.) |
+| Forking complexity | Higher (multi-method state machine) | Lower (three methods, simpler semantics) |
+
+The narrower contract is why MemoryStoreTemplate ships sooner + smaller than SkillStoreTemplate.
+
+## Further reading
+
+- **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
+- **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — programmatic-bootstrap patterns; two-instance posture
+- **`src/connectors/types.ts`** — authoritative `MemoryStore` interface, `PortableMemory`, `QueryFilters`, `MemoryWrite` types
+- **`src/testing/conformance.ts`** — the per-contract conformance test suites
+- **`src/connectors/memory-store.ts`** — `SqliteMemoryStore` reference impl + schema

package/examples/connectors/README.md

@@ -0,0 +1,47 @@
+# examples/connectors/
+
+Worked examples + fork-me templates for adopter-written connectors. The bundled defaults live in `src/connectors/`; this directory holds patterns for adopters writing their own.
+
+## Connector landscape
+
+| Contract | Bundled defaults | Worked example | Fork template |
+|---|---|---|---|
+| `SkillStore` | `FilesystemSkillStore`, `SqliteSkillStore` (in `src/connectors/`) | — | **[SkillStoreTemplate/](./SkillStoreTemplate/)** |
+| `MemoryStore` | `SqliteMemoryStore` (in `src/connectors/`) | — | **[MemoryStoreTemplate/](./MemoryStoreTemplate/)** |
+| `LocalModel` | `OllamaLocalModel` (in `src/connectors/`; opt-in via substrate config) | — | **[LocalModelTemplate/](./LocalModelTemplate/)** |
+| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `MemoryStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
+| `AgentConnector` | `NoOpAgentConnector` (in `src/connectors/`) | **[HttpWebhookAgentConnector/](./HttpWebhookAgentConnector/)** | — |
+
+**Bundled defaults** are runnable out of the box — wired through `connectors.json` substrate config or programmatic bootstrap.
+
+**Worked examples** are real implementations for substrates that aren't bundled — copy + customize for your specific deployment. HttpWebhookAgentConnector demonstrates the AgentConnector contract against a generic HTTP-webhook substrate.
+
+**Fork templates** are skeletons (every method throws TODO). Useful when you want the bare contract surface without any specific substrate assumptions. SkillStoreTemplate is the starting point for Postgres-, MongoDB-, AMP-, or vector-DB-backed SkillStore impls.
+
+## Forking workflow (any connector type)
+
+1. **Pick your starting point**:
+   - Fork from a worked example if it's close to your substrate (e.g., another HTTP service → fork HttpWebhookAgentConnector)
+   - Fork from a template if you're targeting a substrate type not yet demonstrated (e.g., Postgres SkillStore → fork SkillStoreTemplate)
+   - Fork from `src/connectors/` if you want the bundled default's behavior as a starting point (e.g., another SQL flavor → adapt sqlite-skill-store.ts)
+2. **Copy the directory** into your codebase
+3. **Implement against your substrate** (each method has a TODO comment)
+4. **Update `staticCapabilities()`** to declare what your impl actually supports
+5. **Register via `Registry.register*`** from your bootstrap
+6. **Validate via the conformance suite** (`<Contract>Conformance.buildTests()` from `skillscript-runtime/testing`)
+
+## Reference materials
+
+- **[`docs/configuration.md`](../../docs/configuration.md)** — substrate selection via `connectors.json`; programmatic-bootstrap vs declarative patterns
+- **[`docs/adopter-playbook.md`](../../docs/adopter-playbook.md)** — Case 1 vs Case 2 wiring decisions; two-instance posture; upstream-merge-friendly conventions
+- **[`docs/connector-contract-reference.md`](../../docs/connector-contract-reference.md)** — interface contracts for adopter agents writing connector impls
+- **`src/connectors/types.ts`** — authoritative contract interfaces (SkillStore, MemoryStore, LocalModel, McpConnector)
+- **`src/testing/conformance.ts`** — the per-contract conformance test suites
+
+## Naming convention
+
+Bundled defaults in `src/connectors/`: `<Substrate><Contract>` (e.g., `FilesystemSkillStore`, `SqliteSkillStore`, `OllamaLocalModel`).
+
+Worked examples + adopter forks in `examples/connectors/`: same `<Substrate><Contract>` pattern (e.g., `HttpWebhookAgentConnector`, your `PostgresSkillStore`).
+
+Templates: `<Contract>Template` (e.g., `SkillStoreTemplate`).