@soulcraft/sdk 1.4.6 → 1.4.7

package/dist/modules/formats/types.d.ts

@@ -2,9 +2,12 @@
  * @module formats/types
  * @description Soulcraft portable content format type definitions.
  *
- * This module exports the four core document formats used across the Soulcraft
- * platform. All formats are pure data — JSON documents stored in the VFS and
- * passed between products, AI tools, and rendering components.
+ * These types mirror `@soulcraft/formats` exactly. Once `@soulcraft/formats`
+ * ships compiled `.d.ts` output (rather than raw `.ts` source), this module
+ * can be replaced with simple re-exports. Until then, the types live here
+ * to avoid pulling `@soulcraft/formats`' Zod schemas into the SDK's type-check.
+ *
+ * See: handoff action "Remove duplicate format types from SDK src/modules/formats/"
  *
  * | Format  | Extension        | Purpose                                      |
  * |---------|------------------|----------------------------------------------|
@@ -12,24 +15,6 @@
  * | WDOC    | `.wdoc`          | Rich text documents (TipTap/ProseMirror)     |
  * | WSLIDE  | `.wslide.json`   | Slide deck presentations                     |
  * | WQUIZ   | `.wquiz.json`    | Assessments and quizzes                      |
- *
- * Formats contain no runtime behavior — they are schema contracts. Products
- * read them from the VFS, parse with `JSON.parse()`, and cast to the appropriate
- * interface. The `SoulcraftFormat` discriminant on each document's `format` field
- * enables safe narrowing at runtime.
- *
- * @example
- * ```typescript
- * import type { WdocDocument, WvizDocument, SoulcraftFormatDocument } from '@soulcraft/sdk'
- *
- * // Read from VFS and narrow to the correct type
- * const buf = await sdk.vfs.readFile('/projects/notes.wdoc')
- * const doc = JSON.parse(buf.toString('utf-8')) as SoulcraftFormatDocument
- * if (doc.format === 'wdoc') {
- *   const wdoc = doc as WdocDocument
- *   console.log(wdoc.meta.title)
- * }
- * ```
  */
 export type { WvizDocument, WvizEntity, WvizEdge, WvizSnapshot, WvizViewType, } from './wviz.js';
 export type { WdocDocument, WdocMeta, WdocBlock, WdocInlineContent, WdocTextNode, WdocMark, WdocParagraphBlock, WdocHeadingBlock, WdocBlockquoteBlock, WdocCodeBlock, WdocBulletListBlock, WdocOrderedListBlock, WdocListItemBlock, WdocTaskListBlock, WdocTaskItemBlock, WdocImageBlock, WdocVideoBlock, WdocIconBlock, WdocSvgEmbedBlock, WdocEmbedBlock, WdocTableBlock, WdocTableRowBlock, WdocTableCellBlock, WdocTableHeaderBlock, WdocHorizontalRuleBlock, WdocCalloutBlock, } from './wdoc.js';

package/dist/modules/formats/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,YAAY,EACV,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAMnB;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,8CAAoF,CAAA;AAElH;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,eAAe,CAAA;IACvB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;CAChB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EACV,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAMnB;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,8CAAoF,CAAA;AAElH;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,eAAe,CAAA;IACvB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;CAChB"}

package/dist/modules/formats/types.js

@@ -2,9 +2,12 @@
  * @module formats/types
  * @description Soulcraft portable content format type definitions.
  *
- * This module exports the four core document formats used across the Soulcraft
- * platform. All formats are pure data — JSON documents stored in the VFS and
- * passed between products, AI tools, and rendering components.
+ * These types mirror `@soulcraft/formats` exactly. Once `@soulcraft/formats`
+ * ships compiled `.d.ts` output (rather than raw `.ts` source), this module
+ * can be replaced with simple re-exports. Until then, the types live here
+ * to avoid pulling `@soulcraft/formats`' Zod schemas into the SDK's type-check.
+ *
+ * See: handoff action "Remove duplicate format types from SDK src/modules/formats/"
  *
  * | Format  | Extension        | Purpose                                      |
  * |---------|------------------|----------------------------------------------|
@@ -12,24 +15,6 @@
  * | WDOC    | `.wdoc`          | Rich text documents (TipTap/ProseMirror)     |
  * | WSLIDE  | `.wslide.json`   | Slide deck presentations                     |
  * | WQUIZ   | `.wquiz.json`    | Assessments and quizzes                      |
- *
- * Formats contain no runtime behavior — they are schema contracts. Products
- * read them from the VFS, parse with `JSON.parse()`, and cast to the appropriate
- * interface. The `SoulcraftFormat` discriminant on each document's `format` field
- * enables safe narrowing at runtime.
- *
- * @example
- * ```typescript
- * import type { WdocDocument, WvizDocument, SoulcraftFormatDocument } from '@soulcraft/sdk'
- *
- * // Read from VFS and narrow to the correct type
- * const buf = await sdk.vfs.readFile('/projects/notes.wdoc')
- * const doc = JSON.parse(buf.toString('utf-8')) as SoulcraftFormatDocument
- * if (doc.format === 'wdoc') {
- *   const wdoc = doc as WdocDocument
- *   console.log(wdoc.meta.title)
- * }
- * ```
  */
 /**
  * All Soulcraft format strings as a const array — useful for validation.

package/dist/modules/formats/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAsEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAA+C,CAAA"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAsEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAA+C,CAAA"}

package/dist/modules/kits/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAsB,UAAU,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AA8BzF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAkBlF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAsB,UAAU,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAgDzF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAoClF"}

package/dist/modules/kits/index.js

@@ -23,25 +23,28 @@ import { createRequire } from 'node:module';
 // createRequire enables CJS-style require() inside an ESM module — the only
 // reliable way to conditionally load optional peer dependencies in Node/Bun ESM.
 const _require = createRequire(import.meta.url);
-// Module-level cache — loaded once per process, not per SDK instance.
-let _registryCache = undefined;
+let _kitsPackage = undefined;
 /**
- * Load the kit registry from the installed `@soulcraft/kits` package.
- * Returns `null` when the package is not installed, allowing callers to
- * degrade gracefully rather than throwing.
+ * Lazily load the `@soulcraft/kits` optional peer dependency.
+ * Returns `null` when the package is not installed; callers degrade gracefully.
  */
-function _getBundledRegistry() {
-    if (_registryCache !== undefined)
-        return _registryCache;
+function _loadKitsPackage() {
+    if (_kitsPackage !== undefined)
+        return _kitsPackage;
     try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const kits = _require('@soulcraft/kits');
-        _registryCache = kits.kitRegistry ?? null;
+        _kitsPackage = _require('@soulcraft/kits');
     }
     catch {
-        _registryCache = null;
+        _kitsPackage = null;
     }
-    return _registryCache;
+    return _kitsPackage;
+}
+/**
+ * Load the kit registry from the installed `@soulcraft/kits` package.
+ * Returns `null` when the package is not installed.
+ */
+function _getBundledRegistry() {
+    return _loadKitsPackage()?.kitRegistry ?? null;
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // Factory
@@ -80,6 +83,24 @@ export function createKitsModule(options = {}) {
                 return [];
             return Object.values(registry);
         },
+        async resolveFilesPath(kitId, product) {
+            const pkg = _loadKitsPackage();
+            if (!pkg?.resolveKitFilesPath)
+                return null;
+            return pkg.resolveKitFilesPath(kitId, product);
+        },
+        async resolveSkillsPath(kitId) {
+            const pkg = _loadKitsPackage();
+            if (!pkg?.resolveKitSkillsPath)
+                return null;
+            return pkg.resolveKitSkillsPath(kitId);
+        },
+        async resolveKitsRoot() {
+            const pkg = _loadKitsPackage();
+            if (!pkg?.resolveKitsRoot)
+                return null;
+            return pkg.resolveKitsRoot();
+        },
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/modules/kits/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,4EAA4E;AAC5E,iFAAiF;AACjF,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAE/C,sEAAsE;AACtE,IAAI,cAAc,GAA0D,SAAS,CAAA;AAErF;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,cAAc,CAAA;IACvD,IAAI,CAAC;QACH,8DAA8D;QAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAQ,CAAA;QAC/C,cAAc,GAAI,IAAI,CAAC,WAAkD,IAAI,IAAI,CAAA;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,cAAc,GAAG,IAAI,CAAA;IACvB,CAAC;IACD,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,WAAW,GAAG,OAAO,CAAC,eAAe,KAAK,SAAS;QACvD,CAAC,CAAC,GAA8C,EAAE,CAAC,OAAO,CAAC,eAAe,IAAI,IAAI;QAClF,CAAC,CAAC,mBAAmB,CAAA;IAEvB,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAa;YACtB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAC1B,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,CAAA;YACxB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAChC,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,4EAA4E;AAC5E,iFAAiF;AACjF,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAgB/C,IAAI,YAAY,GAAmC,SAAS,CAAA;AAE5D;;;GAGG;AACH,SAAS,gBAAgB;IACvB,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,YAAY,CAAA;IACnD,IAAI,CAAC;QACH,YAAY,GAAG,QAAQ,CAAC,iBAAiB,CAAgB,CAAA;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,YAAY,GAAG,IAAI,CAAA;IACrB,CAAC;IACD,OAAO,YAAY,CAAA;AACrB,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB;IAC1B,OAAO,gBAAgB,EAAE,EAAE,WAAW,IAAI,IAAI,CAAA;AAChD,CAAC;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,WAAW,GAAG,OAAO,CAAC,eAAe,KAAK,SAAS;QACvD,CAAC,CAAC,GAA8C,EAAE,CAAC,OAAO,CAAC,eAAe,IAAI,IAAI;QAClF,CAAC,CAAC,mBAAmB,CAAA;IAEvB,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAa;YACtB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAC1B,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,CAAA;YACxB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,KAAa,EAAE,OAA6B;YACjE,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAA;YAC9B,IAAI,CAAC,GAAG,EAAE,mBAAmB;gBAAE,OAAO,IAAI,CAAA;YAC1C,OAAO,GAAG,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QAChD,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,KAAa;YACnC,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAA;YAC9B,IAAI,CAAC,GAAG,EAAE,oBAAoB;gBAAE,OAAO,IAAI,CAAA;YAC3C,OAAO,GAAG,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAA;QACxC,CAAC;QAED,KAAK,CAAC,eAAe;YACnB,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAA;YAC9B,IAAI,CAAC,GAAG,EAAE,eAAe;gBAAE,OAAO,IAAI,CAAA;YACtC,OAAO,GAAG,CAAC,eAAe,EAAE,CAAA;QAC9B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/modules/kits/types.d.ts

@@ -61,12 +61,15 @@ export interface CreateKitsModuleOptions {
     bundledRegistry?: Record<string, SoulcraftKitConfig> | null;
 }
 /**
- * The `sdk.kits.*` namespace — read-only access to the Soulcraft kit registry.
+ * The `sdk.kits.*` namespace — read-only access to the Soulcraft kit registry
+ * and template file paths.
  *
  * Backed by the `@soulcraft/kits` package (a peer dependency). If the package
  * is not installed, `load()` returns `null` and `list()` returns an empty array.
+ * Path resolver methods return `null` when the package is absent or the directory
+ * does not exist.
  *
- * @example
+ * @example Load a kit and run AI with its persona
  * ```typescript
  * const kit = await sdk.kits.load('wicks-and-whiskers')
  * if (kit) {
@@ -76,6 +79,12 @@ export interface CreateKitsModuleOptions {
  *   })
  * }
  * ```
+ *
+ * @example Locate kit template files on disk
+ * ```typescript
+ * const dir = await sdk.kits.resolveFilesPath('blog-series', 'workshop')
+ * // → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/workshop/files'
+ * ```
  */
 export interface KitsModule {
     /**
@@ -107,5 +116,60 @@ export interface KitsModule {
      * ```
      */
     list(): Promise<SoulcraftKitConfig[]>;
+    /**
+     * Resolve the absolute path to a kit's product-specific template files directory.
+     *
+     * Returns the path to `kits/{kitId}/{product}/files/` inside the installed
+     * `@soulcraft/kits` npm package, or `null` if the directory does not exist
+     * (the kit has no template files for that product, or the package is absent).
+     *
+     * This is the single source of truth for kit file paths across all products.
+     * Use it instead of hard-coding `node_modules` paths or maintaining per-product
+     * filesystem layouts.
+     *
+     * @param kitId - Kit identifier (e.g. `'blog-series'`, `'recipe-manager'`).
+     * @param product - Product consuming the files: `'workshop'` or `'venue'`.
+     * @returns Absolute path to the files directory, or `null` if it does not exist.
+     *
+     * @example
+     * ```typescript
+     * const dir = await sdk.kits.resolveFilesPath('blog-series', 'workshop')
+     * // → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/workshop/files'
+     * ```
+     */
+    resolveFilesPath(kitId: string, product: 'workshop' | 'venue'): Promise<string | null>;
+    /**
+     * Resolve the absolute path to a kit's skills directory.
+     *
+     * Returns the path to `kits/{kitId}/skills/` inside the installed `@soulcraft/kits`
+     * npm package, or `null` if the directory does not exist.
+     *
+     * @param kitId - Kit identifier.
+     * @returns Absolute path to the skills directory, or `null` if it does not exist.
+     *
+     * @example
+     * ```typescript
+     * const dir = await sdk.kits.resolveSkillsPath('blog-series')
+     * // → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/skills'
+     * ```
+     */
+    resolveSkillsPath(kitId: string): Promise<string | null>;
+    /**
+     * Resolve the absolute path to the root `kits/` directory inside the npm package.
+     *
+     * Useful when enumerating all available kits on the filesystem rather than relying
+     * on the `kitRegistry` in-memory list (e.g. build tooling, validators).
+     *
+     * Returns `null` if `@soulcraft/kits` is not installed.
+     *
+     * @returns Absolute path to the `kits/` directory, or `null`.
+     *
+     * @example
+     * ```typescript
+     * const root = await sdk.kits.resolveKitsRoot()
+     * // → '/path/to/node_modules/@soulcraft/kits/kits'
+     * ```
+     */
+    resolveKitsRoot(): Promise<string | null>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/modules/kits/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAA;IACV,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,6BAA6B;IAC7B,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAA;IAC3D,0CAA0C;IAC1C,MAAM,CAAC,EAAE;QACP,gCAAgC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,+CAA+C;QAC/C,WAAW,CAAC,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACvD,CAAA;IACD,wDAAwD;IACxD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;IAEvD;;;;;;;;;;;;OAYG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;CACtC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAA;IACV,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,6BAA6B;IAC7B,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAA;IAC3D,0CAA0C;IAC1C,MAAM,CAAC,EAAE;QACP,gCAAgC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,+CAA+C;QAC/C,WAAW,CAAC,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACvD,CAAA;IACD,wDAAwD;IACxD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAMD;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;IAEvD;;;;;;;;;;;;OAYG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAErC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEtF;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAExD;;;;;;;;;;;;;;;OAeG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAC1C"}

package/docs/ADR-001-sdk-design.md

@@ -219,47 +219,47 @@ consistent everywhere.
 - [x] Create `soulcraftlabs/sdk` GitHub repo
 - [x] Initialize TypeScript + Bun package with conditional exports
 - [x] Write this ADR and CLAUDE.md
-- [ ] Scaffold `src/` directory structure (empty modules with JSDoc stubs)
-- [ ] Write `tsconfig.json`, `vitest.config.ts`, `.env.example`
+- [x]Scaffold `src/` directory structure (empty modules with JSDoc stubs)
+- [x]Write `tsconfig.json`, `vitest.config.ts`, `.env.example`
 
 ### Phase 2 — Core Data Layer
-- [ ] `src/transports/` — migrate Local, HTTP, WS from brainy-client; add SSE
-- [ ] `src/modules/brainy/` — full Brainy API proxy (all methods, all sub-APIs)
-- [ ] `src/modules/vfs/` — VFS namespace (delegates to `brain.vfs.*`)
-- [ ] `src/modules/versions/` — versions namespace (delegates to `brain.versions.*`)
-- [ ] `src/types.ts` — core shared types (SoulcraftSDK, SDKOptions, etc.)
-- [ ] Server mode instance pool (`per-user`, `per-tenant`, `per-scope`)
-- [ ] Tests: all transport modes, all brainy methods via proxy
+- [x]`src/transports/` — migrate Local, HTTP, WS from brainy-client; add SSE
+- [x]`src/modules/brainy/` — full Brainy API proxy (all methods, all sub-APIs)
+- [x]`src/modules/vfs/` — VFS namespace (delegates to `brain.vfs.*`)
+- [x]`src/modules/versions/` — versions namespace (delegates to `brain.versions.*`)
+- [x]`src/types.ts` — core shared types (SoulcraftSDK, SDKOptions, etc.)
+- [x]Server mode instance pool (`per-user`, `per-tenant`, `per-scope`)
+- [x]Tests: all transport modes, all brainy methods via proxy
 
 ### Phase 3 — Auth + License
-- [ ] `src/modules/auth/` — OIDC client config, session cache, capability tokens,
+- [x]`src/modules/auth/` — OIDC client config, session cache, capability tokens,
       Hono middleware, SvelteKit handle, backchannel logout
-- [ ] `src/modules/license/` — Cortex activation, plan verification, credit metering,
+- [x]`src/modules/license/` — Cortex activation, plan verification, credit metering,
       BYOK validation, heartbeat background task
-- [ ] Absorb `@soulcraft/auth` package entirely
-- [ ] Tests: auth middleware, capability token create/verify, license exchange
+- [x]Absorb `@soulcraft/auth` package entirely
+- [x]Tests: auth middleware, capability token create/verify, license exchange
 
 ### Phase 4 — AI + Events + Skills + Kits + Formats
-- [ ] `src/modules/ai/` — model tiers, delegator, Briggy API, tool definition types,
+- [x]`src/modules/ai/` — model tiers, delegator, Briggy API, tool definition types,
       KitAIContext, UI action registry
-- [ ] `src/modules/events/` — platform event bus (DataChangeEmitter, all 30+ event types)
-- [ ] `src/modules/skills/` — skill loading, bundled skills, user-invocable registry
-- [ ] `src/modules/kits/` — kit loader, initialization, template injection
-- [ ] `src/modules/formats/` — WVIZ, WDOC, WSLIDE, WQUIZ types (migrate from @soulcraft/views + richDocument.ts)
+- [x]`src/modules/events/` — platform event bus (DataChangeEmitter, all 30+ event types)
+- [x]`src/modules/skills/` — skill loading, bundled skills, user-invocable registry
+- [x]`src/modules/kits/` — kit loader, initialization, template injection
+- [x]`src/modules/formats/` — WVIZ, WDOC, WSLIDE, WQUIZ types (migrate from @soulcraft/views + richDocument.ts)
 
 ### Phase 5 — Billing + Notifications
-- [ ] `src/modules/billing/` — usage tracking, quota checks, top-up credits,
+- [x]`src/modules/billing/` — usage tracking, quota checks, top-up credits,
       Stripe subscription management, billing provider (Firestore vs local)
-- [ ] `src/modules/notifications/` — NotificationSender interface, Postmark, Twilio,
+- [x]`src/modules/notifications/` — NotificationSender interface, Postmark, Twilio,
       dev-mode console sender, notification templates
 
 ### Phase 6 — Publish + First npm Release
-- [ ] Publish `@soulcraft/sdk@1.0.0` to npmjs.com (private/restricted)
-- [ ] Update Workshop: replace all `@soulcraft/brainy-client` + `@soulcraft/auth` imports
-- [ ] Update Venue: same
-- [ ] Update Academy: same
-- [ ] Deprecate (do not unpublish) `@soulcraft/brainy-client` and `@soulcraft/auth`
-- [ ] Add `@soulcraft/sdk` to bundle loop in all three `build.sh` files
+- [x]Publish `@soulcraft/sdk@1.0.0` to npmjs.com (private/restricted)
+- [x]Update Workshop: replace all `@soulcraft/brainy-client` + `@soulcraft/auth` imports
+- [x]Update Venue: same
+- [x]Update Academy: same
+- [x]Deprecate (do not unpublish) `@soulcraft/brainy-client` and `@soulcraft/auth`
+- [x]Add `@soulcraft/sdk` to bundle loop in all three `build.sh` files
 
 ---
 
@@ -277,6 +277,6 @@ notice in their README and `package.json` `"deprecated"` field pointing to `@sou
 
 ## Related Documents
 
-- `docs/ADR-002-transport-protocol.md` — Wire protocol specification (to be written in Phase 2)
-- `docs/ADR-003-instance-strategies.md` — Brainy instance pooling spec (to be written in Phase 2)
+- `docs/ADR-002-transport-protocol.md` — Wire protocol specification
+- `docs/ADR-003-instance-strategies.md` — Brainy instance pooling and Cortex activation
 - `/home/dpsifr/.strategy/PLATFORM-HANDOFF.md` — Cross-project coordination thread

package/docs/ADR-002-transport-protocol.md

@@ -0,0 +1,248 @@
+# ADR-002: Transport Protocol — Wire Format, Auth, and Reconnection
+
+**Status:** Accepted
+**Date:** 2026-03-02
+**Supersedes:** None
+**See also:** `ADR-001-sdk-design.md` (Decision 5)
+
+---
+
+## Context
+
+The SDK must communicate between kit apps (browser) or product backends and a Brainy
+server over a network. Four distinct communication patterns exist across the platform:
+
+1. **Stateless RPC** — kit apps call Brainy methods on demand (no persistent connection needed)
+2. **Real-time bidirectional RPC + push** — Venue kit apps need live change events alongside RPC
+3. **Server-push only** — Workshop workspace event stream (VFS/entity mutations)
+4. **In-process** — server-mode SDK calls Brainy directly with zero serialization overhead
+
+These patterns have meaningfully different requirements for serialization, auth, and
+error handling. This ADR records the decisions made for each.
+
+---
+
+## Decision 1: Four Transports, Fixed Serialization
+
+Four transport implementations are provided. Serialization format is fixed per transport
+and is never configurable:
+
+| Transport | Class | Serialization | Direction | Use case |
+|-----------|-------|--------------|-----------|---------|
+| `local` | `LocalTransport` | None (in-process) | — | Server mode, zero overhead |
+| `http` | `HttpTransport` | JSON | Request/response | Stateless RPC — kit apps, simple clients |
+| `ws` | `WsTransport` | MessagePack binary | Bidirectional | Real-time — RPC + change push events |
+| `sse` | `SseTransport` | text/event-stream | Server → Client | Live updates only — VFS/entity events |
+
+**Rationale for fixed serialization:**
+- HTTP=JSON: universally debuggable with `curl`, browser DevTools, and server logs.
+  The request volume at typical HTTP RPC frequencies makes binary encoding a
+  premature optimization with no measurable benefit.
+- WebSocket=MessagePack: bidirectional real-time traffic has high message frequency
+  and persistent connections where binary encoding is measurably more efficient.
+  MessagePack was already the wire format in `@soulcraft/brainy-client`.
+- Making serialization configurable adds complexity with no practical benefit —
+  consumers never need to mix formats within a single transport.
+
+**Rejected alternatives:**
+- MessagePack over HTTP: non-standard, incompatible with standard proxies and logging tools.
+- gRPC/Protobuf: over-engineered for the current scale and requires a schema compilation step.
+- Configurable serializer per transport: extra complexity for a use case that has never arisen.
+
+---
+
+## Decision 2: HTTP Transport Wire Format
+
+**Endpoint:** `POST {baseUrl}/api/brainy/rpc`
+
+**Request body** (JSON):
+```json
+{ "method": "find", "args": [{ "query": "candle kits", "limit": 10 }] }
+```
+
+**Success response** (JSON):
+```json
+{ "result": [ ... ] }
+```
+
+**Error response** (JSON):
+```json
+{ "error": { "code": "BRAINY_NOT_FOUND", "message": "Entity not found" } }
+```
+
+**Auth:** `Authorization: Bearer <capability-token>` for server-to-server calls;
+`credentials: 'include'` (session cookies) for browser kit apps.
+
+**Timeout:** 30 seconds via `AbortController`. Throws `SDKTimeoutError` on expiry.
+
+**HTTP status mapping:**
+| Status | Error class |
+|--------|------------|
+| 401 | `SDKAuthError` |
+| 403 | `SDKForbiddenError` |
+| network failure | `SDKDisconnectedError` |
+| 200 + `error` body | `SDKRpcError` |
+
+The HTTP transport is stateless — `isAlive()` always returns `true`. Errors surface
+as rejected promises from individual `call()` invocations.
+
+---
+
+## Decision 3: WebSocket Transport Wire Format
+
+**Endpoint:** `wss://{host}/api/brainy/ws`
+
+**Auth:** Capability token sent as `Authorization: Bearer <token>` on the WebSocket
+upgrade request. This is a Bun-specific extension (`@ts-expect-error` in source).
+Standard browser `WebSocket` does not support custom headers on the upgrade request —
+browser kit apps use the HTTP transport or pass the token as a `?token=` query param.
+
+**Scope param:** `?scope=<tenantSlug>` on the connection URL. Venue uses this to
+select the correct per-tenant Brainy instance.
+
+### Connection handshake
+
+After a successful upgrade + auth check the server sends a `ready` message:
+```
+Server → Client: { "type": "ready", "scope": "wicks-and-whiskers" }
+```
+
+`WsTransport.connect()` resolves only after this message. A 15-second timeout
+applies — if no `ready` arrives the connection is aborted with an error.
+
+### RPC messages (binary MessagePack)
+
+**Client → Server:**
+```
+{ id: "42", method: "vfs.readdir", args: ["/workspace/docs"] }
+```
+
+The `id` is a monotonically incrementing integer cast to string, unique per connection.
+
+**Server → Client (RPC response):**
+```
+{ id: "42", result: [ ... ] }
+{ id: "42", error: { code: "VFS_NOT_FOUND", message: "Path not found" } }
+```
+
+Pending RPCs are matched to their response by `id`. A per-call 30-second timeout
+rejects calls that receive no response.
+
+### Change push events (binary MessagePack)
+
+```
+{ type: "change", event: "add"|"update"|"delete"|"relate"|"unrelate",
+  entity?: { ... }, relation?: { ... } }
+```
+
+Push events have no `id` field and are dispatched to all registered `onEvent` handlers.
+
+### Reconnection
+
+On unexpected disconnection (any close code except 4001, 4003, or explicit `close()`):
+
+- All pending RPC calls are rejected with `SDKDisconnectedError`
+- Reconnect is attempted with **exponential backoff**: `min(1000 × 2^attempt, 30_000)` ms
+- Maximum 10 attempts (configurable via constructor)
+- After 10 failed attempts the transport enters `closed` state permanently
+
+**Auth failure codes — no retry:**
+| Close code | Meaning | Behaviour |
+|-----------|---------|----------|
+| 4001 | Unauthorized (bad/expired token) | Reject pending calls with `SDKAuthError`, set `closed` |
+| 4003 | Forbidden (insufficient scope) | Reject pending calls with `SDKForbiddenError`, set `closed` |
+
+### Connection states
+
+```
+disconnected → connecting → connected → disconnected (unexpected) → connecting (reconnect) ...
+                                      → closed (explicit close() or auth failure)
+```
+
+---
+
+## Decision 4: SSE Transport Wire Format
+
+**Endpoint:** `GET {baseUrl}/api/workspace/events[?workspaceId=<id>]`
+
+Uses the browser's native `EventSource` API. `EventSource` handles reconnection
+automatically using the server-sent `retry:` interval. Additionally, the SDK applies
+manual exponential backoff (identical schedule to WsTransport) on `onerror` events
+to prevent thundering-herd reconnects on server restart.
+
+**Event format** (JSON-encoded in the SSE `data:` field):
+```
+data: {"type":"change","event":"update","entity":{"id":"abc","nounType":"Booking",...}}
+```
+
+**Connection confirmation** (internal, not dispatched to listeners):
+```
+data: {"type":"connected","connectionId":"conn-abc123"}
+```
+
+**Receive-only:** `call()` throws `SDKError` with code `SSE_NO_RPC`. For outbound
+operations pair this transport with an `HttpTransport`.
+
+---
+
+## Decision 5: Local Transport (In-Process)
+
+Used exclusively in server mode. Wraps a native `Brainy` instance. No serialization,
+no network, no error class mapping.
+
+**Method resolution:** Dot-separated method paths are resolved by recursive property
+traversal on the Brainy instance. `'vfs.readdir'` → `brain.vfs.readdir(args)`.
+
+**Change events:** `onEvent`/`offEvent` delegate to Brainy's built-in change listeners
+directly on the instance. No intermediary.
+
+**isAlive():** Always `true`. **close():** No-op.
+
+---
+
+## Decision 6: Shared Error Classes
+
+All transports share a common error hierarchy:
+
+```
+SDKError (base, has `code: string`)
+├── SDKAuthError        (401 / close code 4001)
+├── SDKForbiddenError   (403 / close code 4003)
+├── SDKTimeoutError     (30s per-call timeout)
+├── SDKDisconnectedError (transport not connected, or unexpected close)
+└── SDKRpcError         (server returned { error: { code, message } })
+```
+
+Consumer code catches `SDKAuthError` to redirect to login, `SDKDisconnectedError`
+to show a reconnecting state, etc.
+
+---
+
+## Decision 7: Capability Tokens for Server-to-Server Auth
+
+Transport-level auth uses HMAC-SHA256 capability tokens:
+
+```
+<base64url(payload)>.<base64url(signature)>
+```
+
+`payload` is `{ sub, scope, iat, exp }` JSON. Default TTL: 1 hour.
+
+**Timing-safe verification** uses `crypto.timingSafeEqual` to prevent timing attacks.
+
+These tokens are separate from OIDC session tokens. They are used for:
+- Kit apps making RPC calls to the Venue or Workshop backend
+- Server-to-server calls (e.g. Academy → Workshop)
+
+Session cookie auth (browser kit apps in same-origin context) uses `credentials: 'include'`
+on the HTTP transport and does not require a capability token.
+
+---
+
+## Related Documents
+
+- `ADR-001-sdk-design.md` — Overall SDK architecture (Decision 5: transport rationale)
+- `ADR-003-instance-strategies.md` — How server-side Brainy instances are pooled and selected
+- `src/transports/` — Implementation of all four transports
+- `src/modules/brainy/errors.ts` — Shared error class hierarchy
+- `src/modules/brainy/auth.ts` — Capability token creation and verification