@soulcraft/sdk 3.1.1 → 3.2.0

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

@@ -2,38 +2,69 @@
  * @module kits
  * @description Factory for sdk.kits.* — the Soulcraft kit registry module.
  *
- * Provides read-only access to kit configurations from the `@soulcraft/kits`
- * package. The package is an optional peer dependency loaded lazily via
- * `createRequire` so that the SDK compiles and runs without it installed;
- * calls gracefully return `null` / empty array when it is absent.
+ * Supports two operating modes:
  *
- * The factory accepts an optional `bundledRegistry` override (used in tests)
- * to inject a mock registry without needing the real package.
+ * **Registry mode** (recommended) — fetches kits from the Forge Kit Registry
+ * (`forge.soulcraft.com`) over HTTP. Archives (.sck) are downloaded, unpacked
+ * to a local disk cache, and served as local filesystem paths. ETag-based
+ * revalidation minimizes network traffic. Set `registryUrl` to enable.
  *
- * @example
+ * **Bundled mode** (legacy) — loads kits from the `@soulcraft/kits` npm
+ * package via `createRequire()`. This is the backwards-compatible default
+ * that products use today. Will be removed once all products migrate to
+ * registry mode.
+ *
+ * The factory returns the same `KitsModule` interface regardless of mode.
+ * Callers never need to know which backing store is active.
+ *
+ * @example Registry mode (production)
  * ```typescript
  * import { createKitsModule } from '@soulcraft/sdk/server'
  *
+ * const kits = createKitsModule({
+ *   registryUrl: process.env.FORGE_REGISTRY_URL,  // 'https://forge.soulcraft.com'
+ *   cachePath: '/home/app/.soulcraft/kits-cache',
+ * })
+ * const kit = await kits.load('wicks-and-whiskers')
+ * ```
+ *
+ * @example Bundled mode (legacy, no registryUrl)
+ * ```typescript
  * const kits = createKitsModule()
  * const kit = await kits.load('wicks-and-whiskers')
- * console.log(kit?.name) // "Wicks & Whiskers"
  * ```
  */
 import type { KitsModule, CreateKitsModuleOptions } from './types.js';
 /**
  * Create the `sdk.kits.*` module.
  *
- * @param options - Optional overrides, primarily for testing.
- * @returns A `KitsModule` backed by the `@soulcraft/kits` registry.
+ * The mode is determined by the options:
+ * - `bundledRegistry` set → static in-memory registry (for tests)
+ * - `registryUrl` set → HTTP-based registry mode (production)
+ * - Neither set → legacy bundled mode via `@soulcraft/kits` package
  *
- * @example
+ * @param options - Configuration for the kits module.
+ * @returns A `KitsModule` instance.
+ *
+ * @example Registry mode (production)
+ * ```typescript
+ * const kits = createKitsModule({
+ *   registryUrl: 'https://forge.soulcraft.com',
+ *   cachePath: '/home/app/.soulcraft/kits-cache',
+ * })
+ * ```
+ *
+ * @example Bundled mode (legacy — no options needed)
  * ```typescript
- * // In production:
  * const kits = createKitsModule()
+ * ```
  *
- * // In tests — inject a mock registry to avoid the peer dep:
+ * @example Test mode — inject mock kits
+ * ```typescript
  * const kits = createKitsModule({
- *   bundledRegistry: { 'test-kit': { id: 'test-kit', name: 'Test Kit', ... } }
+ *   bundledRegistry: {
+ *     'test-kit': { id: 'test-kit', name: 'Test Kit', version: '1.0.0', ... }
+ *   }
  * })
  * ```
  */

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;AAgDzF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAoClF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAMH,OAAO,KAAK,EAEV,UAAU,EACV,uBAAuB,EAExB,MAAM,YAAY,CAAA;AA2YnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAoBlF"}

package/dist/modules/kits/index.js

@@ -2,31 +2,51 @@
  * @module kits
  * @description Factory for sdk.kits.* — the Soulcraft kit registry module.
  *
- * Provides read-only access to kit configurations from the `@soulcraft/kits`
- * package. The package is an optional peer dependency loaded lazily via
- * `createRequire` so that the SDK compiles and runs without it installed;
- * calls gracefully return `null` / empty array when it is absent.
+ * Supports two operating modes:
  *
- * The factory accepts an optional `bundledRegistry` override (used in tests)
- * to inject a mock registry without needing the real package.
+ * **Registry mode** (recommended) — fetches kits from the Forge Kit Registry
+ * (`forge.soulcraft.com`) over HTTP. Archives (.sck) are downloaded, unpacked
+ * to a local disk cache, and served as local filesystem paths. ETag-based
+ * revalidation minimizes network traffic. Set `registryUrl` to enable.
  *
- * @example
+ * **Bundled mode** (legacy) — loads kits from the `@soulcraft/kits` npm
+ * package via `createRequire()`. This is the backwards-compatible default
+ * that products use today. Will be removed once all products migrate to
+ * registry mode.
+ *
+ * The factory returns the same `KitsModule` interface regardless of mode.
+ * Callers never need to know which backing store is active.
+ *
+ * @example Registry mode (production)
  * ```typescript
  * import { createKitsModule } from '@soulcraft/sdk/server'
  *
+ * const kits = createKitsModule({
+ *   registryUrl: process.env.FORGE_REGISTRY_URL,  // 'https://forge.soulcraft.com'
+ *   cachePath: '/home/app/.soulcraft/kits-cache',
+ * })
+ * const kit = await kits.load('wicks-and-whiskers')
+ * ```
+ *
+ * @example Bundled mode (legacy, no registryUrl)
+ * ```typescript
  * const kits = createKitsModule()
  * const kit = await kits.load('wicks-and-whiskers')
- * console.log(kit?.name) // "Wicks & Whiskers"
  * ```
  */
 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.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+// ─────────────────────────────────────────────────────────────────────────────
+// Bundled mode — load from @soulcraft/kits npm package (legacy)
+// ─────────────────────────────────────────────────────────────────────────────
 const _require = createRequire(import.meta.url);
+/** Module-level cache — loaded once per process. */
 let _kitsPackage = undefined;
 /**
- * Lazily load the `@soulcraft/kits` optional peer dependency.
- * Returns `null` when the package is not installed; callers degrade gracefully.
+ * @description Lazily load the `@soulcraft/kits` optional peer dependency.
+ * Returns `null` when the package is not installed.
  */
 function _loadKitsPackage() {
     if (_kitsPackage !== undefined)
@@ -40,36 +60,20 @@ function _loadKitsPackage() {
     return _kitsPackage;
 }
 /**
- * Load the kit registry from the installed `@soulcraft/kits` package.
- * Returns `null` when the package is not installed.
+ * @description Get the bundled registry from the @soulcraft/kits package.
+ * @returns The kit registry, or null if the package is absent.
  */
 function _getBundledRegistry() {
     return _loadKitsPackage()?.kitRegistry ?? null;
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// Factory
-// ─────────────────────────────────────────────────────────────────────────────
 /**
- * Create the `sdk.kits.*` module.
- *
- * @param options - Optional overrides, primarily for testing.
- * @returns A `KitsModule` backed by the `@soulcraft/kits` registry.
- *
- * @example
- * ```typescript
- * // In production:
- * const kits = createKitsModule()
+ * @description Create a KitsModule backed by the @soulcraft/kits npm package.
+ * This is the legacy mode, retained for backwards compatibility.
  *
- * // In tests — inject a mock registry to avoid the peer dep:
- * const kits = createKitsModule({
- *   bundledRegistry: { 'test-kit': { id: 'test-kit', name: 'Test Kit', ... } }
- * })
- * ```
+ * @param getRegistry - Function that returns the bundled registry (or null).
+ * @returns A KitsModule that reads from the installed npm package.
  */
-export function createKitsModule(options = {}) {
-    const getRegistry = options.bundledRegistry !== undefined
-        ? () => options.bundledRegistry ?? null
-        : _getBundledRegistry;
+function _createBundledKitsModule(getRegistry) {
     return {
         async load(kitId) {
             const registry = getRegistry();
@@ -103,4 +107,324 @@ export function createKitsModule(options = {}) {
         },
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry mode — fetch from Forge Kit Registry over HTTP
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default cache freshness: 5 minutes. */
+const DEFAULT_CACHE_TTL_MS = 300_000;
+/** Default local cache directory: ~/.soulcraft/kits-cache */
+const DEFAULT_CACHE_PATH = join(homedir(), '.soulcraft', 'kits-cache');
+/**
+ * @description Read the cache metadata file for a kit.
+ * @param cachePath - Root cache directory.
+ * @param kitId - Kit identifier.
+ * @returns Parsed CacheMeta, or null if missing or invalid.
+ */
+function _readCacheMeta(cachePath, kitId) {
+    const metaPath = join(cachePath, kitId, '_cache-meta.json');
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(metaPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description Write cache metadata for a kit.
+ * @param cachePath - Root cache directory.
+ * @param kitId - Kit identifier.
+ * @param meta - Metadata to persist.
+ */
+function _writeCacheMeta(cachePath, kitId, meta) {
+    const metaPath = join(cachePath, kitId, '_cache-meta.json');
+    mkdirSync(join(cachePath, kitId), { recursive: true });
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+}
+/**
+ * @description Read a cached kit manifest from disk.
+ * @param cachePath - Root cache directory.
+ * @param kitId - Kit identifier.
+ * @returns Parsed manifest, or null if kit.json is missing.
+ */
+function _readCachedManifest(cachePath, kitId) {
+    const kitJsonPath = join(cachePath, kitId, 'kit.json');
+    if (!existsSync(kitJsonPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(kitJsonPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description Unpack a .sck (ZIP) archive buffer to a target directory.
+ *
+ * Uses dynamic import of `fflate` to avoid adding it as a hard SDK dependency.
+ * All Soulcraft products have fflate installed (Venue uses it for .sca archives,
+ * the registry uses it for .sck archives). If fflate is unavailable, the unpack
+ * fails with an actionable error message.
+ *
+ * @param buffer - The .sck archive as a Uint8Array.
+ * @param targetDir - Directory to extract into.
+ */
+async function _unpackArchive(buffer, targetDir) {
+    // Dynamic import avoids a hard dependency on fflate in the SDK package.json.
+    // The type assertion is safe because we only call unzipSync which is stable API.
+    let unzipSync;
+    try {
+        const fflate = await Function('return import("fflate")')();
+        unzipSync = fflate.unzipSync;
+    }
+    catch {
+        throw new Error('[sdk.kits] Cannot unpack .sck archive: fflate is not installed. ' +
+            'Run: bun add fflate (or npm install fflate)');
+    }
+    const files = unzipSync(buffer);
+    for (const [relPath, content] of Object.entries(files)) {
+        const fullPath = join(targetDir, relPath);
+        const dir = join(fullPath, '..');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(fullPath, content);
+    }
+}
+/**
+ * @description Create a KitsModule backed by the Forge Kit Registry.
+ *
+ * Downloads .sck archives over HTTP, unpacks them to a local disk cache,
+ * and serves filesystem paths from the cache. Uses ETag-based revalidation
+ * to minimize bandwidth.
+ *
+ * @param registryUrl - Base URL of the registry (e.g. 'https://forge.soulcraft.com').
+ * @param cachePath - Absolute path to the local cache directory.
+ * @param cacheTtlMs - Cache freshness duration in milliseconds.
+ * @returns A KitsModule that fetches kits from the registry.
+ */
+function _createRegistryKitsModule(registryUrl, cachePath, cacheTtlMs) {
+    /** In-memory manifest cache — avoids disk reads on repeated calls. */
+    const memCache = new Map();
+    /** Strip trailing slash from registry URL for consistent URL building. */
+    const baseUrl = registryUrl.replace(/\/+$/, '');
+    mkdirSync(cachePath, { recursive: true });
+    /**
+     * @description Ensure a kit is available in the local cache.
+     *
+     * Cache flow:
+     * 1. Check in-memory cache → if within TTL, return immediately.
+     * 2. Check disk cache meta → if within TTL, load manifest from disk.
+     * 3. Send HEAD with If-None-Match → if 304, refresh TTL and return cached.
+     * 4. GET /api/kits/:id/archive → download, unpack, write cache meta.
+     *
+     * @param kitId - Kit identifier.
+     * @returns CachedKitEntry, or null if the kit doesn't exist.
+     */
+    async function ensureCached(kitId) {
+        const now = Date.now();
+        // 1. In-memory cache hit within TTL
+        const mem = memCache.get(kitId);
+        if (mem && (now - mem.fetchedAt) < cacheTtlMs) {
+            return mem;
+        }
+        // 2. Disk cache hit within TTL
+        const diskMeta = _readCacheMeta(cachePath, kitId);
+        if (diskMeta && (now - new Date(diskMeta.fetchedAt).getTime()) < cacheTtlMs) {
+            const manifest = _readCachedManifest(cachePath, kitId);
+            if (manifest) {
+                const entry = {
+                    manifest,
+                    etag: diskMeta.etag,
+                    localPath: join(cachePath, kitId),
+                    fetchedAt: new Date(diskMeta.fetchedAt).getTime()
+                };
+                memCache.set(kitId, entry);
+                return entry;
+            }
+        }
+        // 3. Revalidate with ETag (conditional GET on archive endpoint)
+        const existingEtag = diskMeta?.etag || mem?.etag || null;
+        try {
+            const archiveUrl = `${baseUrl}/api/kits/${encodeURIComponent(kitId)}/archive`;
+            const headers = {};
+            if (existingEtag) {
+                headers['If-None-Match'] = existingEtag;
+            }
+            const response = await fetch(archiveUrl, { headers });
+            // 304 Not Modified — cache is still valid
+            if (response.status === 304) {
+                const manifest = _readCachedManifest(cachePath, kitId) || mem?.manifest || null;
+                if (manifest) {
+                    const entry = {
+                        manifest,
+                        etag: existingEtag,
+                        localPath: join(cachePath, kitId),
+                        fetchedAt: now
+                    };
+                    memCache.set(kitId, entry);
+                    _writeCacheMeta(cachePath, kitId, {
+                        etag: existingEtag,
+                        fetchedAt: new Date(now).toISOString(),
+                        version: manifest.version
+                    });
+                    return entry;
+                }
+            }
+            // 404 — kit doesn't exist
+            if (response.status === 404) {
+                memCache.delete(kitId);
+                return null;
+            }
+            // 200 — download and unpack
+            if (response.ok) {
+                const buffer = new Uint8Array(await response.arrayBuffer());
+                const etag = response.headers.get('etag');
+                const kitDir = join(cachePath, kitId);
+                // Clear existing cache for this kit (preserve _cache-meta.json)
+                if (existsSync(kitDir)) {
+                    rmSync(kitDir, { recursive: true, force: true });
+                }
+                await _unpackArchive(buffer, kitDir);
+                const manifest = _readCachedManifest(cachePath, kitId);
+                if (!manifest) {
+                    console.error(`[sdk.kits] Downloaded archive for "${kitId}" has no kit.json`);
+                    return null;
+                }
+                const entry = {
+                    manifest,
+                    etag,
+                    localPath: kitDir,
+                    fetchedAt: now
+                };
+                memCache.set(kitId, entry);
+                _writeCacheMeta(cachePath, kitId, {
+                    etag,
+                    fetchedAt: new Date(now).toISOString(),
+                    version: manifest.version
+                });
+                return entry;
+            }
+            // Other errors — log and fall through to cached data
+            console.error(`[sdk.kits] Registry returned ${response.status} for "${kitId}"`);
+        }
+        catch (err) {
+            // Network error — use stale cache if available
+            console.error(`[sdk.kits] Failed to reach registry for "${kitId}":`, err);
+        }
+        // Stale cache fallback — return whatever we have
+        if (mem)
+            return mem;
+        const manifest = _readCachedManifest(cachePath, kitId);
+        if (manifest) {
+            const entry = {
+                manifest,
+                etag: diskMeta?.etag ?? null,
+                localPath: join(cachePath, kitId),
+                fetchedAt: diskMeta ? new Date(diskMeta.fetchedAt).getTime() : 0
+            };
+            memCache.set(kitId, entry);
+            return entry;
+        }
+        return null;
+    }
+    return {
+        async load(kitId) {
+            const entry = await ensureCached(kitId);
+            return entry?.manifest ?? null;
+        },
+        async list() {
+            try {
+                const response = await fetch(`${baseUrl}/api/kits`);
+                if (!response.ok)
+                    return [];
+                const data = await response.json();
+                return data.kits ?? [];
+            }
+            catch {
+                // Offline fallback — read manifests from all cached kit directories
+                if (!existsSync(cachePath))
+                    return [];
+                const dirs = readdirSync(cachePath, { withFileTypes: true })
+                    .filter(d => d.isDirectory() && !d.name.startsWith('.') && !d.name.startsWith('_'));
+                const results = [];
+                for (const dir of dirs) {
+                    const manifest = _readCachedManifest(cachePath, dir.name);
+                    if (manifest)
+                        results.push(manifest);
+                }
+                return results;
+            }
+        },
+        async resolveFilesPath(kitId, product) {
+            const entry = await ensureCached(kitId);
+            if (!entry)
+                return null;
+            const filesDir = join(entry.localPath, product, 'files');
+            return existsSync(filesDir) ? filesDir : null;
+        },
+        async resolveSkillsPath(kitId) {
+            const entry = await ensureCached(kitId);
+            if (!entry)
+                return null;
+            const skillsDir = join(entry.localPath, 'skills');
+            return existsSync(skillsDir) ? skillsDir : null;
+        },
+        async resolveKitsRoot() {
+            return cachePath;
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create the `sdk.kits.*` module.
+ *
+ * The mode is determined by the options:
+ * - `bundledRegistry` set → static in-memory registry (for tests)
+ * - `registryUrl` set → HTTP-based registry mode (production)
+ * - Neither set → legacy bundled mode via `@soulcraft/kits` package
+ *
+ * @param options - Configuration for the kits module.
+ * @returns A `KitsModule` instance.
+ *
+ * @example Registry mode (production)
+ * ```typescript
+ * const kits = createKitsModule({
+ *   registryUrl: 'https://forge.soulcraft.com',
+ *   cachePath: '/home/app/.soulcraft/kits-cache',
+ * })
+ * ```
+ *
+ * @example Bundled mode (legacy — no options needed)
+ * ```typescript
+ * const kits = createKitsModule()
+ * ```
+ *
+ * @example Test mode — inject mock kits
+ * ```typescript
+ * const kits = createKitsModule({
+ *   bundledRegistry: {
+ *     'test-kit': { id: 'test-kit', name: 'Test Kit', version: '1.0.0', ... }
+ *   }
+ * })
+ * ```
+ */
+export function createKitsModule(options = {}) {
+    // Test mode — static in-memory registry takes highest precedence
+    if (options.bundledRegistry !== undefined) {
+        const getRegistry = () => options.bundledRegistry ?? null;
+        return _createBundledKitsModule(getRegistry);
+    }
+    // Registry mode — fetch from Forge Kit Registry over HTTP
+    if (options.registryUrl) {
+        const cachePath = options.cachePath
+            ? resolve(options.cachePath)
+            : DEFAULT_CACHE_PATH;
+        const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        return _createRegistryKitsModule(options.registryUrl, cachePath, cacheTtlMs);
+    }
+    // Bundled mode (legacy) — load from @soulcraft/kits npm package
+    return _createBundledKitsModule(_getBundledRegistry);
+}
 //# 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;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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACjG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAQjC,gFAAgF;AAChF,gEAAgE;AAChE,gFAAgF;AAEhF,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAU/C,oDAAoD;AACpD,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;;;;;;GAMG;AACH,SAAS,wBAAwB,CAC/B,WAA4D;IAE5D,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;AAED,gFAAgF;AAChF,0DAA0D;AAC1D,gFAAgF;AAEhF,0CAA0C;AAC1C,MAAM,oBAAoB,GAAG,OAAO,CAAA;AAEpC,6DAA6D;AAC7D,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,YAAY,CAAC,CAAA;AAetE;;;;;GAKG;AACH,SAAS,cAAc,CAAC,SAAiB,EAAE,KAAa;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAA;IAC3D,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAc,CAAA;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,SAAiB,EAAE,KAAa,EAAE,IAAe;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAA;IAC3D,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACtD,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;AACxD,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,SAAiB,EAAE,KAAa;IAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,CAAA;IACtD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IACzC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAuB,CAAA;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,cAAc,CAAC,MAAkB,EAAE,SAAiB;IACjE,6EAA6E;IAC7E,iFAAiF;IACjF,IAAI,SAA2D,CAAA;IAC/D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAO,QAAQ,CAAC,yBAAyB,CAAC,EAA+C,CAAA;QACxG,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,kEAAkE;YAClE,6CAA6C,CAC9C,CAAA;IACH,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;IAE/B,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QAChC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACnC,aAAa,CAAC,QAAQ,EAAE,OAAgC,CAAC,CAAA;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,yBAAyB,CAChC,WAAmB,EACnB,SAAiB,EACjB,UAAkB;IAElB,sEAAsE;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAA;IAElD,0EAA0E;IAC1E,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAE/C,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAEzC;;;;;;;;;;;OAWG;IACH,KAAK,UAAU,YAAY,CAAC,KAAa;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,oCAAoC;QACpC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,UAAU,EAAE,CAAC;YAC9C,OAAO,GAAG,CAAA;QACZ,CAAC;QAED,+BAA+B;QAC/B,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QACjD,IAAI,QAAQ,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC;YAC5E,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YACtD,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,KAAK,GAAmB;oBAC5B,QAAQ;oBACR,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;oBACjC,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;iBAClD,CAAA;gBACD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;gBAC1B,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;QAED,gEAAgE;QAChE,MAAM,YAAY,GAAG,QAAQ,EAAE,IAAI,IAAI,GAAG,EAAE,IAAI,IAAI,IAAI,CAAA;QAExD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,GAAG,OAAO,aAAa,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAA;YAC7E,MAAM,OAAO,GAA2B,EAAE,CAAA;YAC1C,IAAI,YAAY,EAAE,CAAC;gBACjB,OAAO,CAAC,eAAe,CAAC,GAAG,YAAY,CAAA;YACzC,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;YAErD,0CAA0C;YAC1C,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC5B,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,GAAG,EAAE,QAAQ,IAAI,IAAI,CAAA;gBAC/E,IAAI,QAAQ,EAAE,CAAC;oBACb,MAAM,KAAK,GAAmB;wBAC5B,QAAQ;wBACR,IAAI,EAAE,YAAY;wBAClB,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;wBACjC,SAAS,EAAE,GAAG;qBACf,CAAA;oBACD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;oBAC1B,eAAe,CAAC,SAAS,EAAE,KAAK,EAAE;wBAChC,IAAI,EAAE,YAAY;wBAClB,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE;wBACtC,OAAO,EAAE,QAAQ,CAAC,OAAO;qBAC1B,CAAC,CAAA;oBACF,OAAO,KAAK,CAAA;gBACd,CAAC;YACH,CAAC;YAED,0BAA0B;YAC1B,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC5B,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACtB,OAAO,IAAI,CAAA;YACb,CAAC;YAED,4BAA4B;YAC5B,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;gBAC3D,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;gBACzC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;gBAErC,gEAAgE;gBAChE,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBACvB,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;gBAClD,CAAC;gBAED,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;gBAEpC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;gBACtD,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,CAAC,KAAK,CAAC,sCAAsC,KAAK,mBAAmB,CAAC,CAAA;oBAC7E,OAAO,IAAI,CAAA;gBACb,CAAC;gBAED,MAAM,KAAK,GAAmB;oBAC5B,QAAQ;oBACR,IAAI;oBACJ,SAAS,EAAE,MAAM;oBACjB,SAAS,EAAE,GAAG;iBACf,CAAA;gBACD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;gBAC1B,eAAe,CAAC,SAAS,EAAE,KAAK,EAAE;oBAChC,IAAI;oBACJ,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE;oBACtC,OAAO,EAAE,QAAQ,CAAC,OAAO;iBAC1B,CAAC,CAAA;gBAEF,OAAO,KAAK,CAAA;YACd,CAAC;YAED,qDAAqD;YACrD,OAAO,CAAC,KAAK,CAAC,gCAAgC,QAAQ,CAAC,MAAM,SAAS,KAAK,GAAG,CAAC,CAAA;QACjF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,+CAA+C;YAC/C,OAAO,CAAC,KAAK,CAAC,4CAA4C,KAAK,IAAI,EAAE,GAAG,CAAC,CAAA;QAC3E,CAAC;QAED,iDAAiD;QACjD,IAAI,GAAG;YAAE,OAAO,GAAG,CAAA;QACnB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QACtD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,KAAK,GAAmB;gBAC5B,QAAQ;gBACR,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,IAAI;gBAC5B,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;gBACjC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;aACjE,CAAA;YACD,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;YAC1B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAa;YACtB,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,CAAA;YACvC,OAAO,KAAK,EAAE,QAAQ,IAAI,IAAI,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,WAAW,CAAC,CAAA;gBACnD,IAAI,CAAC,QAAQ,CAAC,EAAE;oBAAE,OAAO,EAAE,CAAA;gBAC3B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAoC,CAAA;gBACpE,OAAO,IAAI,CAAC,IAAI,IAAI,EAAE,CAAA;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,oEAAoE;gBACpE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;oBAAE,OAAO,EAAE,CAAA;gBACrC,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;qBACzD,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;gBACrF,MAAM,OAAO,GAAyB,EAAE,CAAA;gBACxC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,CAAA;oBACzD,IAAI,QAAQ;wBAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;gBACtC,CAAC;gBACD,OAAO,OAAO,CAAA;YAChB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,KAAa,EAAE,OAA6B;YACjE,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,CAAA;YACvC,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAA;YACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;YACxD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAA;QAC/C,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,KAAa;YACnC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,CAAA;YACvC,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAA;YACvB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;YACjD,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;QACjD,CAAC;QAED,KAAK,CAAC,eAAe;YACnB,OAAO,SAAS,CAAA;QAClB,CAAC;KACF,CAAA;AACH,CAAC;AAED,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IACpE,iEAAiE;IACjE,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,WAAW,GAAG,GAA8C,EAAE,CAClE,OAAO,CAAC,eAAe,IAAI,IAAI,CAAA;QACjC,OAAO,wBAAwB,CAAC,WAAW,CAAC,CAAA;IAC9C,CAAC;IAED,0DAA0D;IAC1D,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS;YACjC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;YAC5B,CAAC,CAAC,kBAAkB,CAAA;QACtB,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,oBAAoB,CAAA;QAE7D,OAAO,yBAAyB,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAA;IAC9E,CAAC;IAED,gEAAgE;IAChE,OAAO,wBAAwB,CAAC,mBAAmB,CAAC,CAAA;AACtD,CAAC"}

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

@@ -2,12 +2,22 @@
  * @module kits/types
  * @description Type definitions for sdk.kits.* — the kit loader and registry module.
  *
- * Kits (`@soulcraft/kits`) are pure configuration packages: `kit.json` manifests
- * and `SKILL.md` prompt files that describe a domain, persona, glossary, and
- * workflow. They contain no TypeScript logic, no server code, and no SDK imports.
+ * Kits are pure configuration packages: `kit.json` manifests, `SKILL.md` prompt
+ * files, template files, and optional station bundles that describe a domain,
+ * persona, glossary, and workflow. They contain no TypeScript logic, no server
+ * code, and no SDK imports.
  *
- * The `KitsModule` provides read-only access to the kit registry: loading a single
- * kit by ID, listing all available kits, and accessing the raw skill registry.
+ * The `KitsModule` provides read-only access to the kit registry. It supports
+ * two backing stores:
+ *
+ * 1. **Registry mode** — when `registryUrl` is provided, kits are fetched from
+ *    the Forge Kit Registry (`forge.soulcraft.com`) over HTTP. Archives (.sck)
+ *    are unpacked to a local disk cache for filesystem access. ETag-based cache
+ *    validation avoids re-downloading unchanged kits.
+ *
+ * 2. **Bundled mode** (legacy) — when no `registryUrl` is provided, kits are
+ *    loaded from the `@soulcraft/kits` npm package via `createRequire()`. This
+ *    is the backwards-compatible fallback used during migration.
  *
  * Kit initialization (populating a workspace's Brainy and VFS from a kit's
  * `starterFiles`) is a product-level concern and lives in each product's
@@ -49,14 +59,94 @@ export interface SoulcraftKitConfig {
     [key: string]: unknown;
 }
 /**
- * Options passed to `createKitsModule()` to override the bundled registry.
- * Primarily useful in tests.
+ * Internal cache entry for a kit fetched from the registry.
+ * Stored in-memory with its ETag for conditional revalidation.
+ */
+export interface CachedKitEntry {
+    /** Parsed kit.json manifest. */
+    manifest: SoulcraftKitConfig;
+    /** ETag from the registry for conditional requests (If-None-Match). */
+    etag: string | null;
+    /** Absolute path to the unpacked kit directory on local disk. */
+    localPath: string;
+    /** Timestamp (ms) when this entry was last fetched or validated. */
+    fetchedAt: number;
+}
+/**
+ * Options for `createKitsModule()`.
+ *
+ * Two modes of operation:
+ *
+ * **Registry mode** — set `registryUrl` to fetch kits from the Forge Kit Registry.
+ * The SDK downloads `.sck` archives, unpacks them to `cachePath`, and serves
+ * filesystem paths from the local cache. ETag-based revalidation avoids
+ * re-downloading unchanged kits.
+ *
+ * **Bundled mode** (legacy) — omit `registryUrl` to load kits from the
+ * `@soulcraft/kits` npm package. This is the backwards-compatible default
+ * used during migration. Set `bundledRegistry` to inject a mock registry
+ * for testing.
+ *
+ * @example Registry mode (production)
+ * ```typescript
+ * const kits = createKitsModule({
+ *   registryUrl: 'https://forge.soulcraft.com',
+ *   cachePath: '/home/app/.soulcraft/kits-cache',
+ * })
+ * ```
+ *
+ * @example Bundled mode (legacy)
+ * ```typescript
+ * const kits = createKitsModule() // uses @soulcraft/kits if installed
+ * ```
+ *
+ * @example Test mode
+ * ```typescript
+ * const kits = createKitsModule({
+ *   bundledRegistry: { 'test-kit': { id: 'test-kit', name: 'Test', ... } }
+ * })
+ * ```
  */
 export interface CreateKitsModuleOptions {
     /**
-     * Override the kit registry loaded from `@soulcraft/kits`.
-     * When provided, the module uses this registry directly instead of requiring
-     * the package. Set to `null` to simulate the package being absent.
+     * Base URL of the Forge Kit Registry (e.g. `'https://forge.soulcraft.com'`).
+     *
+     * When set, the module operates in **registry mode**: kits are fetched over
+     * HTTP, cached locally as unpacked `.sck` archives, and revalidated via ETags.
+     * The `@soulcraft/kits` npm package is not needed.
+     *
+     * When omitted, the module falls back to **bundled mode** using the
+     * `@soulcraft/kits` package.
+     */
+    registryUrl?: string;
+    /**
+     * Absolute path to the local disk cache for unpacked kit archives.
+     *
+     * Defaults to `~/.soulcraft/kits-cache` when `registryUrl` is set.
+     * Each kit is stored at `{cachePath}/{kitId}/` with its full directory tree.
+     *
+     * **Important:** This path must NOT be inside a Brainy data directory to
+     * avoid interfering with entity storage and indexing.
+     */
+    cachePath?: string;
+    /**
+     * Cache freshness duration in milliseconds.
+     *
+     * When a kit is loaded, the SDK checks if the cached copy is younger than
+     * this TTL. If so, it returns the cached manifest without a network request.
+     * When the TTL expires, the SDK sends an `If-None-Match` request — if the
+     * registry returns 304, the cache is refreshed without re-downloading.
+     *
+     * Defaults to `300_000` (5 minutes).
+     */
+    cacheTtlMs?: number;
+    /**
+     * Override the kit registry with a static in-memory map. Used in tests to
+     * avoid both the registry and the `@soulcraft/kits` package.
+     *
+     * Set to `null` to simulate no kits being available.
+     *
+     * **Note:** When `bundledRegistry` is set, `registryUrl` is ignored.
      */
     bundledRegistry?: Record<string, SoulcraftKitConfig> | null;
 }
@@ -64,10 +154,14 @@ export interface CreateKitsModuleOptions {
  * 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.
+ * In **registry mode** (recommended), kits are fetched from the Forge Kit
+ * Registry at `forge.soulcraft.com`, cached locally, and served from disk.
+ * In **bundled mode** (legacy), kits are loaded from the `@soulcraft/kits`
+ * npm package.
+ *
+ * The interface is identical in both modes — callers don't know or care
+ * where kits come from. The `registryUrl` option in `createKitsModule()`
+ * controls the backing store.
  *
  * @example Load a kit and run AI with its persona
  * ```typescript
@@ -83,14 +177,17 @@ 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'
+ * // Registry mode: '~/.soulcraft/kits-cache/blog-series/workshop/files'
+ * // Bundled mode:  '/path/to/node_modules/@soulcraft/kits/kits/blog-series/workshop/files'
  * ```
  */
 export interface KitsModule {
     /**
      * Load a single kit configuration by ID.
      *
-     * Returns `null` if the kit is not found or `@soulcraft/kits` is not installed.
+     * In registry mode, this fetches the manifest from the registry (or returns
+     * a cached copy if within the TTL). In bundled mode, it reads from the
+     * `@soulcraft/kits` package.
      *
      * @param kitId - The kit identifier (e.g. `'wicks-and-whiskers'`).
      * @returns The kit configuration, or `null` if not found.
@@ -105,69 +202,67 @@ export interface KitsModule {
     /**
      * List all available kits from the registry.
      *
-     * Returns an empty array if `@soulcraft/kits` is not installed.
+     * In registry mode, this fetches the full kit listing from the registry.
+     * In bundled mode, it returns all kits from the `@soulcraft/kits` package.
      *
      * @returns All kit configurations as an array.
      *
      * @example
      * ```typescript
      * const kits = await sdk.kits.list()
-     * console.log(kits.map(k => k.name))
+     * console.log(`${kits.length} kits available`)
      * ```
      */
     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).
+     * In registry mode, the path points into the local cache at
+     * `{cachePath}/{kitId}/{product}/files/`. The kit is downloaded and unpacked
+     * if not already cached. In bundled mode, the path points into the npm package.
      *
-     * 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.
+     * Returns `null` if the kit is not found or the files directory doesn't exist.
      *
-     * @param kitId - Kit identifier (e.g. `'blog-series'`, `'recipe-manager'`).
+     * @param kitId - Kit identifier (e.g. `'blog-series'`).
      * @param product - Product consuming the files: `'workshop'` or `'venue'`.
-     * @returns Absolute path to the files directory, or `null` if it does not exist.
+     * @returns Absolute path to the files directory, or `null` if not found.
      *
      * @example
      * ```typescript
      * const dir = await sdk.kits.resolveFilesPath('blog-series', 'workshop')
-     * // → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/workshop/files'
+     * // → '~/.soulcraft/kits-cache/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.
+     * In registry mode, the path points into the local cache at
+     * `{cachePath}/{kitId}/skills/`. In bundled mode, the path points into
+     * the npm package.
      *
      * @param kitId - Kit identifier.
-     * @returns Absolute path to the skills directory, or `null` if it does not exist.
+     * @returns Absolute path to the skills directory, or `null` if not found.
      *
      * @example
      * ```typescript
      * const dir = await sdk.kits.resolveSkillsPath('blog-series')
-     * // → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/skills'
+     * // → '~/.soulcraft/kits-cache/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).
+     * Resolve the absolute path to the root kits cache or package directory.
      *
-     * Returns `null` if `@soulcraft/kits` is not installed.
+     * In registry mode, returns the `cachePath` directory. In bundled mode,
+     * returns the `kits/` directory inside the npm package.
      *
-     * @returns Absolute path to the `kits/` directory, or `null`.
+     * @returns Absolute path to the kits root, or `null` if unavailable.
      *
      * @example
      * ```typescript
      * const root = await sdk.kits.resolveKitsRoot()
-     * // → '/path/to/node_modules/@soulcraft/kits/kits'
+     * // → '~/.soulcraft/kits-cache'
      * ```
      */
     resolveKitsRoot(): Promise<string | null>;

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;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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,cAAc;IAC7B,gCAAgC;IAChC,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;IAEvD;;;;;;;;;;;;;OAaG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAErC;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAEtF;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAExD;;;;;;;;;;;;;OAaG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAC1C"}

package/dist/modules/kits/types.js

@@ -2,12 +2,22 @@
  * @module kits/types
  * @description Type definitions for sdk.kits.* — the kit loader and registry module.
  *
- * Kits (`@soulcraft/kits`) are pure configuration packages: `kit.json` manifests
- * and `SKILL.md` prompt files that describe a domain, persona, glossary, and
- * workflow. They contain no TypeScript logic, no server code, and no SDK imports.
+ * Kits are pure configuration packages: `kit.json` manifests, `SKILL.md` prompt
+ * files, template files, and optional station bundles that describe a domain,
+ * persona, glossary, and workflow. They contain no TypeScript logic, no server
+ * code, and no SDK imports.
  *
- * The `KitsModule` provides read-only access to the kit registry: loading a single
- * kit by ID, listing all available kits, and accessing the raw skill registry.
+ * The `KitsModule` provides read-only access to the kit registry. It supports
+ * two backing stores:
+ *
+ * 1. **Registry mode** — when `registryUrl` is provided, kits are fetched from
+ *    the Forge Kit Registry (`forge.soulcraft.com`) over HTTP. Archives (.sck)
+ *    are unpacked to a local disk cache for filesystem access. ETag-based cache
+ *    validation avoids re-downloading unchanged kits.
+ *
+ * 2. **Bundled mode** (legacy) — when no `registryUrl` is provided, kits are
+ *    loaded from the `@soulcraft/kits` npm package via `createRequire()`. This
+ *    is the backwards-compatible fallback used during migration.
  *
  * Kit initialization (populating a workspace's Brainy and VFS from a kit's
  * `starterFiles`) is a product-level concern and lives in each product's

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/kits/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/sdk",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
   "type": "module",
   "publishConfig": {