@soulcraft/sdk 1.0.0

package/dist/modules/skills/index.js

@@ -0,0 +1,253 @@
+/**
+ * @module modules/skills
+ * @description Skill loading and registry for @soulcraft/sdk.
+ *
+ * Skills are SKILL.md files that define an AI persona, capabilities, and workflow
+ * for a kit domain. This module provides a unified `load()`/`list()`/`install()`
+ * API backed by two sources:
+ *
+ * 1. **VFS** (priority) — `/skills/{kitId}/{skillId}.md` in the Brainy VFS.
+ *    Managed at runtime via `install()` or the kit initialization pipeline.
+ * 2. **Bundled** (fallback) — skills shipped with `@soulcraft/kits`.
+ *    Loaded dynamically via `require` so the kits package is an optional dependency.
+ *
+ * ## VFS path convention
+ * ```
+ * /skills/{kitId}/{skillId}.md
+ * ```
+ * Example: `/skills/wicks-and-whiskers/inventory-health.md`
+ *
+ * ## Bundled fallback
+ *
+ * If `@soulcraft/kits` is installed, `skillRegistry[kitId]` is a Record mapping
+ * skill IDs to their raw SKILL.md content strings. The skills module reads from
+ * this registry when VFS lookup misses. If `@soulcraft/kits` is not installed,
+ * bundled lookup silently returns nothing.
+ */
+import { createRequire } from 'node:module';
+// ESM-compatible require for loading CJS packages like @soulcraft/kits.
+const _require = createRequire(import.meta.url);
+/**
+ * Creates a `SkillsModule` backed by a Brainy VFS instance and the bundled
+ * `@soulcraft/kits` skill registry.
+ *
+ * @param brain - An initialized Brainy instance. Required for VFS operations.
+ *   Pass `null` to disable VFS skill loading (bundled registry only).
+ * @param options - Optional configuration including a registry override for tests.
+ * @returns A configured {@link SkillsModule}.
+ *
+ * @example
+ * ```typescript
+ * const brain = await pool.forUser(user.emailHash, workspaceId)
+ * const skills = createSkillsModule(brain)
+ *
+ * const skill = await skills.load('inventory-health', 'wicks-and-whiskers')
+ * ```
+ */
+export function createSkillsModule(brain, options = {}) {
+    const getRegistry = options.bundledRegistry !== undefined
+        ? () => options.bundledRegistry ?? null
+        : _getBundledRegistry;
+    return {
+        async load(id, kitId) {
+            // 1. Try VFS first
+            if (brain) {
+                const vfsSkill = await _loadFromVfs(brain, id, kitId);
+                if (vfsSkill)
+                    return vfsSkill;
+            }
+            // 2. Fall back to bundled registry
+            return _loadBundled(id, kitId, getRegistry);
+        },
+        async list(options = {}) {
+            const { kitId, includeVfs = true, includeBundled = true } = options;
+            const results = [];
+            // Collect VFS skills
+            if (includeVfs && brain) {
+                const vfsSkills = await _listFromVfs(brain, kitId);
+                results.push(...vfsSkills);
+            }
+            // Collect bundled skills
+            if (includeBundled) {
+                const bundledSkills = _listBundled(kitId, getRegistry);
+                results.push(...bundledSkills);
+            }
+            return results;
+        },
+        async install(options) {
+            if (!brain) {
+                throw new Error('sdk.skills.install() requires a Brainy instance with VFS support. ' +
+                    'Ensure the SDK was created with a valid brain parameter.');
+            }
+            const { id, kitId, content } = options;
+            const vfsPath = `/skills/${kitId}/${id}.md`;
+            await brain.vfs.writeFile(vfsPath, content);
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// VFS helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Load a skill from the VFS at `/skills/{kitId}/{id}.md`.
+ *
+ * @param brain - Initialized Brainy instance.
+ * @param id - Skill ID.
+ * @param kitId - Kit ID.
+ * @returns The skill if found, or `null`.
+ */
+async function _loadFromVfs(brain, id, kitId) {
+    const vfsPath = `/skills/${kitId}/${id}.md`;
+    try {
+        const raw = await brain.vfs.readFile(vfsPath);
+        const content = Buffer.isBuffer(raw) ? raw.toString('utf-8') : String(raw);
+        return { id, kitId, content, source: 'vfs' };
+    }
+    catch {
+        // File not found in VFS — normal, fall through to bundled
+        return null;
+    }
+}
+/**
+ * List all skills installed in the VFS, optionally filtered by kit ID.
+ *
+ * @param brain - Initialized Brainy instance.
+ * @param kitId - Optional kit filter. If omitted, all skills are returned.
+ * @returns Array of VFS-sourced skills.
+ */
+async function _listFromVfs(brain, kitId) {
+    const results = [];
+    try {
+        if (kitId) {
+            // List skills for a specific kit
+            const dir = `/skills/${kitId}`;
+            const entries = await brain.vfs.readdir(dir);
+            for (const entry of entries) {
+                if (typeof entry === 'string' && entry.endsWith('.md')) {
+                    const id = entry.slice(0, -3); // strip .md
+                    const vfsPath = `${dir}/${entry}`;
+                    try {
+                        const raw = await brain.vfs.readFile(vfsPath);
+                        const content = Buffer.isBuffer(raw) ? raw.toString('utf-8') : String(raw);
+                        results.push({ id, kitId, content, source: 'vfs' });
+                    }
+                    catch {
+                        // Skip unreadable files
+                    }
+                }
+                else if (typeof entry === 'object' && 'name' in entry) {
+                    const name = entry.name;
+                    if (name.endsWith('.md')) {
+                        const id = name.slice(0, -3);
+                        const vfsPath = `${dir}/${name}`;
+                        try {
+                            const raw = await brain.vfs.readFile(vfsPath);
+                            const content = Buffer.isBuffer(raw) ? raw.toString('utf-8') : String(raw);
+                            results.push({ id, kitId, content, source: 'vfs' });
+                        }
+                        catch {
+                            // Skip unreadable files
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            // List all kits then list skills per kit
+            const skillsDir = '/skills';
+            let kitEntries;
+            try {
+                kitEntries = await brain.vfs.readdir(skillsDir);
+            }
+            catch {
+                return results; // /skills doesn't exist yet
+            }
+            for (const kitEntry of kitEntries) {
+                const kitName = typeof kitEntry === 'string' ? kitEntry
+                    : typeof kitEntry === 'object' && kitEntry !== null && 'name' in kitEntry
+                        ? kitEntry.name
+                        : null;
+                if (!kitName)
+                    continue;
+                const kitSkills = await _listFromVfs(brain, kitName);
+                results.push(...kitSkills);
+            }
+        }
+    }
+    catch {
+        // VFS unavailable or /skills not initialized — return empty
+    }
+    return results;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Bundled registry helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Load a single skill from the bundled `@soulcraft/kits` skill registry.
+ *
+ * @param id - Skill ID.
+ * @param kitId - Kit ID.
+ * @param getRegistry - Function that returns the bundled registry (or null).
+ * @returns The skill if found in the bundled registry, or `null`.
+ */
+function _loadBundled(id, kitId, getRegistry) {
+    const registry = getRegistry();
+    if (!registry)
+        return null;
+    const kitSkills = registry[kitId];
+    if (!kitSkills)
+        return null;
+    const content = kitSkills[id];
+    if (!content)
+        return null;
+    return { id, kitId, content, source: 'bundled' };
+}
+/**
+ * List skills from the bundled registry, optionally filtered by kit ID.
+ *
+ * @param kitId - Optional kit filter.
+ * @param getRegistry - Function that returns the bundled registry (or null).
+ * @returns Array of bundled skills.
+ */
+function _listBundled(kitId, getRegistry) {
+    const registry = getRegistry();
+    if (!registry)
+        return [];
+    const results = [];
+    const kitsToList = kitId ? [kitId] : Object.keys(registry);
+    for (const kit of kitsToList) {
+        const kitSkills = registry[kit];
+        if (!kitSkills)
+            continue;
+        for (const [skillId, content] of Object.entries(kitSkills)) {
+            results.push({ id: skillId, kitId: kit, content, source: 'bundled' });
+        }
+    }
+    return results;
+}
+// Lazily-resolved bundled registry cache.
+// `undefined` = not yet attempted; `null` = @soulcraft/kits not installed.
+let _registryCache = undefined;
+/**
+ * Return the bundled `@soulcraft/kits` skill registry, loading it on first call.
+ *
+ * Uses `createRequire` (ESM-compatible CJS require) to load the package. Returns
+ * `null` and degrades gracefully if `@soulcraft/kits` is not installed — VFS
+ * skills continue to work normally.
+ *
+ * @returns The skill registry (kitId → skillId → content), or null.
+ */
+function _getBundledRegistry() {
+    if (_registryCache !== undefined)
+        return _registryCache;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const kits = _require('@soulcraft/kits');
+        _registryCache = (kits.skillRegistry ?? null);
+    }
+    catch {
+        _registryCache = null;
+    }
+    return _registryCache;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,127 @@
+/**
+ * @module modules/skills/types
+ * @description Type definitions for `sdk.skills.*` — the skill loading and registry system.
+ *
+ * Skills are Markdown files (SKILL.md convention) that define an AI persona,
+ * capabilities, glossary, and workflow steps for a specific domain. They drive
+ * Briggy's system prompt construction and define what Claude knows how to do
+ * within a kit's context.
+ *
+ * ## Skill sources (in priority order)
+ *
+ * 1. **VFS** — `/skills/{kitId}/{skillId}.md` in the Brainy VFS. Installed by the
+ *    user or kit initialization pipeline. Takes priority over bundled skills.
+ * 2. **Bundled** — skills shipped with `@soulcraft/kits` as part of the kit manifest.
+ *    Available without any VFS setup.
+ *
+ * ## Skill ID convention
+ *
+ * Skill IDs are kebab-case strings matching the `id:` frontmatter field in the
+ * SKILL.md file. Examples: `'inventory-health'`, `'session-flow'`, `'daily-brief'`.
+ */
+/**
+ * A parsed skill loaded from VFS or the bundled skill registry.
+ */
+export interface Skill {
+    /** Kebab-case skill identifier (matches the `id:` frontmatter field). */
+    id: string;
+    /** The kit this skill belongs to (`null` for global/shared skills). */
+    kitId: string | null;
+    /** The full SKILL.md content including YAML frontmatter. */
+    content: string;
+    /** Where this skill was loaded from. */
+    source: 'vfs' | 'bundled';
+}
+/**
+ * Options for listing skills.
+ */
+export interface SkillListOptions {
+    /**
+     * Filter by kit ID. When omitted, all skills across all kits are returned.
+     */
+    kitId?: string;
+    /**
+     * Whether to include VFS-installed skills in the results.
+     *
+     * @default true
+     */
+    includeVfs?: boolean;
+    /**
+     * Whether to include bundled skills from `@soulcraft/kits` in the results.
+     *
+     * @default true
+     */
+    includeBundled?: boolean;
+}
+/**
+ * Options for installing a skill into the VFS.
+ */
+export interface SkillInstallOptions {
+    /** The skill ID (kebab-case). */
+    id: string;
+    /** The kit this skill belongs to. */
+    kitId: string;
+    /** The full SKILL.md content including YAML frontmatter. */
+    content: string;
+}
+/**
+ * The `sdk.skills` namespace.
+ *
+ * Provides a unified interface for loading, listing, and installing skills
+ * across VFS and the bundled `@soulcraft/kits` registry.
+ *
+ * @example Loading a specific skill
+ * ```typescript
+ * const skill = await sdk.skills.load('inventory-health', 'wicks-and-whiskers')
+ * if (skill) {
+ *   const systemPrompt = buildSystemPrompt(kit, [skill.content])
+ * }
+ * ```
+ *
+ * @example Listing all skills for a kit
+ * ```typescript
+ * const skills = await sdk.skills.list({ kitId: 'wicks-and-whiskers' })
+ * const systemPrompt = buildSystemPrompt(kit, skills.map(s => s.content))
+ * ```
+ *
+ * @example Installing a skill into VFS
+ * ```typescript
+ * await sdk.skills.install({
+ *   id: 'custom-flow',
+ *   kitId: 'wicks-and-whiskers',
+ *   content: `---\nid: custom-flow\ntitle: Custom Flow\n---\n...`,
+ * })
+ * ```
+ */
+export interface SkillsModule {
+    /**
+     * Load a single skill by ID, searching VFS first then bundled registry.
+     *
+     * @param id - Kebab-case skill ID (e.g. `'inventory-health'`).
+     * @param kitId - The kit the skill belongs to.
+     * @returns The skill, or `null` if not found in VFS or bundled registry.
+     */
+    load(id: string, kitId: string): Promise<Skill | null>;
+    /**
+     * List skills matching the given options.
+     *
+     * Skills are returned in VFS-first order: VFS skills appear before bundled skills
+     * with the same ID (deduplication is not applied — callers may see both if a
+     * skill exists in both sources and both `includeVfs` and `includeBundled` are true).
+     *
+     * @param options - Filtering options.
+     * @returns An array of matching skills.
+     */
+    list(options?: SkillListOptions): Promise<Skill[]>;
+    /**
+     * Install a skill into the VFS, making it available to all future `load()` calls.
+     *
+     * Writes the skill content to `/skills/{kitId}/{id}.md` in the Brainy VFS.
+     * Overwrites any existing skill at that path.
+     *
+     * @param options - The skill to install.
+     * @throws {Error} If the VFS is not available on this SDK instance.
+     */
+    install(options: SkillInstallOptions): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAA;IACV,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,MAAM,EAAE,KAAK,GAAG,SAAS,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IAEtD;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;IAElD;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrD"}

package/dist/modules/skills/types.js

@@ -0,0 +1,23 @@
+/**
+ * @module modules/skills/types
+ * @description Type definitions for `sdk.skills.*` — the skill loading and registry system.
+ *
+ * Skills are Markdown files (SKILL.md convention) that define an AI persona,
+ * capabilities, glossary, and workflow steps for a specific domain. They drive
+ * Briggy's system prompt construction and define what Claude knows how to do
+ * within a kit's context.
+ *
+ * ## Skill sources (in priority order)
+ *
+ * 1. **VFS** — `/skills/{kitId}/{skillId}.md` in the Brainy VFS. Installed by the
+ *    user or kit initialization pipeline. Takes priority over bundled skills.
+ * 2. **Bundled** — skills shipped with `@soulcraft/kits` as part of the kit manifest.
+ *    Available without any VFS setup.
+ *
+ * ## Skill ID convention
+ *
+ * Skill IDs are kebab-case strings matching the `id:` frontmatter field in the
+ * SKILL.md file. Examples: `'inventory-health'`, `'session-flow'`, `'daily-brief'`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * @module modules/versions/types
+ * @description Type definitions for `sdk.versions.*` — the entity version history namespace.
+ *
+ * `VersionsModule` is derived from `Brainy['versions']` so it stays in sync with
+ * the installed `@soulcraft/brainy` version automatically.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+/**
+ * The `sdk.versions` namespace — a type-safe handle to Brainy's VersioningAPI.
+ *
+ * At runtime this is implemented by the Brainy proxy. Derived from `Brainy['versions']`
+ * directly so it tracks Brainy's own VersioningAPI type without duplication.
+ *
+ * @example
+ * ```typescript
+ * // Save a snapshot before a bulk edit
+ * const version = await sdk.versions.save(entityId, { tag: 'pre-edit' })
+ *
+ * // List all versions
+ * const history = await sdk.versions.list(entityId)
+ *
+ * // Restore to a previous version
+ * await sdk.versions.restore(entityId, 3)
+ *
+ * // Diff two versions
+ * const diff = await sdk.versions.compare(entityId, 2, 5)
+ * ```
+ */
+export type VersionsModule = Brainy['versions'];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/versions/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA"}

package/dist/modules/versions/types.js

@@ -0,0 +1,9 @@
+/**
+ * @module modules/versions/types
+ * @description Type definitions for `sdk.versions.*` — the entity version history namespace.
+ *
+ * `VersionsModule` is derived from `Brainy['versions']` so it stays in sync with
+ * the installed `@soulcraft/brainy` version automatically.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * @module modules/vfs/types
+ * @description Type definitions for `sdk.vfs.*` — the Virtual Filesystem namespace.
+ *
+ * `VfsModule` is derived from `Brainy['vfs']` so it stays in sync with the installed
+ * `@soulcraft/brainy` version automatically. Sub-path types (VFSStats, VFSDirent, etc.)
+ * are re-exported from Brainy's internal vfs/types path so consumers only need a
+ * single `@soulcraft/sdk` import.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+/**
+ * The `sdk.vfs` namespace — a type-safe handle to Brainy's VirtualFileSystem API.
+ *
+ * At runtime this is implemented by the Brainy proxy. Derived from `Brainy['vfs']`
+ * directly so it tracks Brainy's own VirtualFileSystem type without any duplication.
+ *
+ * @example
+ * ```typescript
+ * const content = await sdk.vfs.readFile('/documents/spec.md')
+ * await sdk.vfs.writeFile('/notes/todo.txt', 'Buy more candles')
+ * const entries = await sdk.vfs.readdir('/documents')
+ * const info = await sdk.vfs.stat('/documents/spec.md')
+ * ```
+ */
+export type VfsModule = Brainy['vfs'];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/vfs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA"}

package/dist/modules/vfs/types.js

@@ -0,0 +1,11 @@
+/**
+ * @module modules/vfs/types
+ * @description Type definitions for `sdk.vfs.*` — the Virtual Filesystem namespace.
+ *
+ * `VfsModule` is derived from `Brainy['vfs']` so it stays in sync with the installed
+ * `@soulcraft/brainy` version automatically. Sub-path types (VFSStats, VFSDirent, etc.)
+ * are re-exported from Brainy's internal vfs/types path so consumers only need a
+ * single `@soulcraft/sdk` import.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/dist/server/create-sdk.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module server/create-sdk
+ * @description `createSDK` factory for server-mode @soulcraft/sdk.
+ *
+ * Assembles a complete `SoulcraftSDK` instance from a live Brainy instance.
+ * In server mode the SDK uses the {@link LocalTransport} — zero overhead, no
+ * serialization, in-process method dispatch directly into the Brainy instance.
+ *
+ * The returned SDK object is scoped to a single Brainy instance. In a typical
+ * server request handler the caller resolves the correct Brainy instance from a
+ * {@link BrainyInstancePool} and then calls `createSDK({ brain })`. A new SDK
+ * object per request is cheap — it's a thin wrapper, not a connection.
+ *
+ * @example Workshop request handler
+ * ```typescript
+ * import { BrainyInstancePool, createSDK } from '@soulcraft/sdk/server'
+ *
+ * const pool = new BrainyInstancePool({ storage: 'filesystem', dataPath: './data', strategy: 'per-user' })
+ *
+ * app.get('/api/inventory', requireAuth, async (c) => {
+ *   const user = c.get('user')!
+ *   const brain = await pool.forUser(user.emailHash, 'main')
+ *   const sdk = createSDK({ brain })
+ *
+ *   const items = await sdk.brainy.find({ query: 'inventory items', type: 'Product' })
+ *   const readme = await sdk.vfs.readFile('/projects/my-project/README.md')
+ *   return c.json({ items })
+ * })
+ * ```
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { SoulcraftSDK } from '../types.js';
+/**
+ * Options for the server-mode {@link createSDK} factory.
+ */
+export interface CreateSDKOptions {
+    /**
+     * A fully initialized Brainy instance.
+     *
+     * Typically resolved from a {@link BrainyInstancePool} for the current user
+     * or tenant. The SDK wraps this instance in a {@link LocalTransport} so all
+     * `sdk.brainy.*` and `sdk.vfs.*` calls dispatch directly into it.
+     */
+    brain: Brainy;
+}
+/**
+ * Create a server-mode `SoulcraftSDK` wrapping a live Brainy instance.
+ *
+ * All `sdk.brainy.*` and `sdk.vfs.*` calls are dispatched in-process with zero
+ * serialization overhead via {@link LocalTransport}.
+ *
+ * `sdk.ai.*` calls go directly to the Anthropic API (requires `ANTHROPIC_API_KEY`).
+ * `sdk.skills.*` reads from the Brainy VFS and falls back to `@soulcraft/kits`.
+ * `sdk.events` is a local EventEmitter — events do not cross process boundaries.
+ *
+ * @param options - SDK creation options.
+ * @returns A fully assembled `SoulcraftSDK` instance.
+ *
+ * @example
+ * ```typescript
+ * const brain = await pool.forUser(user.emailHash, workspaceId)
+ * const sdk = createSDK({ brain })
+ *
+ * const results = await sdk.brainy.find({ query: 'candle inventory' })
+ * const readme = await sdk.vfs.readFile('/projects/README.md')
+ * await sdk.events.emit('kit:session-completed', { userId, sessionId, kitId })
+ * ```
+ */
+export declare function createSDK(options: CreateSDKOptions): SoulcraftSDK;
+//# sourceMappingURL=create-sdk.d.ts.map

package/dist/server/create-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-sdk.d.ts","sourceRoot":"","sources":["../../src/server/create-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAO/C,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,aAAa,CAAA;AAOtF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;CACd;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAiDjE"}