@shardworks/nexus-core 0.1.17 → 0.1.19

package/dist/engine.js

@@ -6,30 +6,40 @@
  * Static engines (manifest, ledger-migrate, etc.) do NOT use this factory —
  * they have bespoke APIs and are called directly by framework code.
  *
- * @example
+ * A package can export a single engine or an array of engines:
+ *
+ * @example Single engine
  * ```typescript
  * import { engine } from '@shardworks/nexus-core';
  *
  * export default engine({
+ *   name: 'my-engine',
  *   handler: async (event, { home }) => {
- *     // event is the triggering GuildEvent when invoked by a standing order
- *     // event is null when invoked directly (CLI, import)
  *     if (event) {
  *       console.log(`Handling ${event.name}`, event.payload);
  *     }
  *   }
  * });
  * ```
+ *
+ * @example Engine collection
+ * ```typescript
+ * export default [
+ *   engine({ name: 'workshop-prepare', handler: async (event, { home }) => { ... } }),
+ *   engine({ name: 'workshop-merge', handler: async (event, { home }) => { ... } }),
+ * ];
+ * ```
  */
 /**
  * Define a clockwork engine.
  *
- * This is the SDK entry point for event-driven engines. Pass a handler
- * function that receives a GuildEvent (or null for direct invocation)
+ * This is the SDK entry point for event-driven engines. Pass a name and a
+ * handler function that receives a GuildEvent (or null for direct invocation)
  * and an EngineContext.
  */
 export function engine(def) {
     return {
+        name: def.name,
         __clockwork: true,
         handler: def.handler,
     };
@@ -42,4 +52,38 @@ export function isClockworkEngine(obj) {
         obj.__clockwork === true &&
         typeof obj.handler === 'function');
 }
+/**
+ * Resolve a single EngineDefinition from a module's default export.
+ *
+ * Handles both single-engine and array-of-engines exports:
+ * - Single engine: `export default engine({...})` → returned directly
+ * - Array: `export default [engine({...}), engine({...})]` → find by name
+ *
+ * @param moduleDefault - The module's default export
+ * @param engineName - The engine name to find (required for array exports)
+ * @returns The matching EngineDefinition, or null if not found
+ */
+export function resolveEngineFromExport(moduleDefault, engineName) {
+    // Single engine export
+    if (isClockworkEngine(moduleDefault)) {
+        if (!engineName || moduleDefault.name === engineName)
+            return moduleDefault;
+        return null;
+    }
+    // Array of engines — find by name
+    if (Array.isArray(moduleDefault)) {
+        for (const item of moduleDefault) {
+            if (!isClockworkEngine(item))
+                continue;
+            if (item.name === engineName)
+                return item;
+        }
+        // If no name match but array has exactly one engine, return it
+        const engines = moduleDefault.filter(isClockworkEngine);
+        if (engines.length === 1 && !engineName)
+            return engines[0];
+        return null;
+    }
+    return null;
+}
 //# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA6BH;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,GAEtB;IACC,OAAO;QACL,WAAW,EAAE,IAAI;QACjB,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,aAAa,IAAI,GAAG;QACnB,GAAwB,CAAC,WAAW,KAAK,IAAI;QAC9C,OAAQ,GAAwB,CAAC,OAAO,KAAK,UAAU,CACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA+BH;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,GAGtB;IACC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,IAAI;QACjB,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,aAAa,IAAI,GAAG;QACnB,GAAwB,CAAC,WAAW,KAAK,IAAI;QAC9C,OAAQ,GAAwB,CAAC,OAAO,KAAK,UAAU,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CACrC,aAAsB,EACtB,UAAmB;IAEnB,uBAAuB;IACvB,IAAI,iBAAiB,CAAC,aAAa,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,aAAa,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC;gBAAE,SAAS;YACvC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;QAC5C,CAAC;QACD,+DAA+D;QAC/D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACxD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/guild-config.d.ts

@@ -15,7 +15,7 @@ export interface RoleDefinition {
 }
 /** A reference to a tool or engine registered in guild.json. */
 export interface ToolEntry {
-    /** Upstream package identifier, e.g. "@shardworks/tool-dispatch@1.11.3". Null for locally-built tools. */
+    /** Upstream package identifier, e.g. "@shardworks/tool-commission@1.11.3". Null for locally-built tools. */
     upstream: string | null;
     /** ISO-8601 timestamp of when the tool was installed. */
     installedAt: string;

package/dist/guild-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guild-config.d.ts","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"guild-config.d.ts","sourceRoot":"","sources":["../src/guild-config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 export declare const VERSION: string;
-export { type ToolContext, type ToolDefinition, tool, } from './tool.ts';
-export { type GuildEvent, type EngineContext, type EngineDefinition, engine, isClockworkEngine, } from './engine.ts';
+export { type ToolContext, type ToolDefinition, tool, isToolDefinition, resolveToolFromExport, resolveAllToolsFromExport, } from './tool.ts';
+export { type GuildEvent, type EngineContext, type EngineDefinition, engine, isClockworkEngine, resolveEngineFromExport, } from './engine.ts';
 export { signalEvent, validateCustomEvent, isFrameworkEvent, readPendingEvents, readEvent, markEventProcessed, recordDispatch, } from './events.ts';
-export { type TickResult, type DispatchSummary, type ClockRunResult, clockTick, clockRun, } from './clockworks.ts';
+export { type TickResult, type DispatchSummary, type ClockRunResult, type SummonHandler, clockTick, clockRun, registerSummonHandler, } from './clockworks.ts';
 export { createLedger } from './ledger.ts';
 export { type GuildConfig, type RoleDefinition, type ToolEntry, type TrainingEntry, type WorkshopEntry, type EventDeclaration, type StandingOrder, type ClockworksConfig, createInitialGuildConfig, guildConfigPath, readGuildConfig, writeGuildConfig, } from './guild-config.ts';
 export { findGuildRoot, nexusDir, ledgerPath, worktreesPath, workshopsPath, workshopBarePath, } from './nexus-home.ts';
 export { type InstallToolOptions, type InstallResult, type SourceKind, classifySource, installTool, } from './install-tool.ts';
 export { type RemoveToolOptions, type RemoveResult, removeTool, } from './remove-tool.ts';
-export { type DispatchOptions, type DispatchResult, dispatch, } from './dispatch.ts';
+export { type CommissionOptions, type CommissionResult, commission, updateCommissionStatus, readCommission, } from './commission.ts';
 export { type InstantiateOptions, type InstantiateResult, instantiate, } from './instantiate.ts';
 export { initGuild } from './init-guild.ts';
 export { type BundleManifest, type BundlePackageEntry, type BundleContentEntry, type BundleMigrationEntry, type InstallBundleOptions, type InstallBundleResult, readBundleManifest, installBundle, isBundleDir, } from './bundle.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO,EAAE,MAAqB,CAAC;AAE5C,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,IAAI,GACL,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,MAAM,EACN,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,WAAW,EACX,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO,EAAE,MAAqB,CAAC;AAE5C,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,IAAI,EACJ,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,MAAM,EACN,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,SAAS,EACT,QAAQ,EACR,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,UAAU,EACV,sBAAsB,EACtB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,WAAW,EACX,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -3,16 +3,16 @@ import { createRequire } from 'node:module';
 const _require = createRequire(import.meta.url);
 const _pkg = _require('../package.json');
 export const VERSION = _pkg.version;
-export { tool, } from "./tool.js";
-export { engine, isClockworkEngine, } from "./engine.js";
+export { tool, isToolDefinition, resolveToolFromExport, resolveAllToolsFromExport, } from "./tool.js";
+export { engine, isClockworkEngine, resolveEngineFromExport, } from "./engine.js";
 export { signalEvent, validateCustomEvent, isFrameworkEvent, readPendingEvents, readEvent, markEventProcessed, recordDispatch, } from "./events.js";
-export { clockTick, clockRun, } from "./clockworks.js";
+export { clockTick, clockRun, registerSummonHandler, } from "./clockworks.js";
 export { createLedger } from "./ledger.js";
 export { createInitialGuildConfig, guildConfigPath, readGuildConfig, writeGuildConfig, } from "./guild-config.js";
 export { findGuildRoot, nexusDir, ledgerPath, worktreesPath, workshopsPath, workshopBarePath, } from "./nexus-home.js";
 export { classifySource, installTool, } from "./install-tool.js";
 export { removeTool, } from "./remove-tool.js";
-export { dispatch, } from "./dispatch.js";
+export { commission, updateCommissionStatus, readCommission, } from "./commission.js";
 export { instantiate, } from "./instantiate.js";
 export { initGuild } from "./init-guild.js";
 export { readBundleManifest, installBundle, isBundleDir, } from "./bundle.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC;AAE5C,OAAO,EAGL,IAAI,GACL,MAAM,WAAW,CAAC;AAEnB,OAAO,EAIL,MAAM,EACN,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAIL,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EASL,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIL,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAGL,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAGL,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAOL,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAML,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,WAAW,EACX,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAOL,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC;AAE5C,OAAO,EAGL,IAAI,EACJ,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAIL,MAAM,EACN,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAKL,SAAS,EACT,QAAQ,EACR,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EASL,wBAAwB,EACxB,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIL,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAGL,UAAU,EACV,sBAAsB,EACtB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAOL,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAML,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,WAAW,EACX,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAOL,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/init-guild.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-guild.d.ts","sourceRoot":"","sources":["../src/init-guild.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAmFzE"}
+{"version":3,"file":"init-guild.d.ts","sourceRoot":"","sources":["../src/init-guild.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAuJzE"}

package/dist/init-guild.js

@@ -60,8 +60,55 @@ export function initGuild(home, name, model) {
     // Write codex placeholder
     fs.writeFileSync(path.join(home, 'codex/all.md'), '');
     // Write default role instruction files
-    fs.writeFileSync(path.join(home, 'roles/advisor.md'), '# Advisor\n\nYou are a guild advisor — a standing member who helps the patron understand and operate the guild.\n');
-    // Write guild.json — with default advisor role, empty registries
+    fs.writeFileSync(path.join(home, 'roles/advisor.md'), [
+        '# Advisor',
+        '',
+        'You are a guild advisor — a standing member who helps the patron understand and operate the guild.',
+        '',
+        '## Purpose',
+        '',
+        'You are the patron\'s primary point of contact with the guild. You explain how things work, report on guild state, suggest next steps, and help the patron frame their intentions as commissions. You are the guild\'s institutional memory made conversational.',
+        '',
+        '## What You Do',
+        '',
+        '- **Answer questions** about guild structure, capabilities, and current state.',
+        '- **Report status** — animas on the roster, active commissions, workshop state, tool inventory.',
+        '- **Help frame commissions** — when the patron has a vague idea, help them refine it into a clear brief that an artificer can act on.',
+        '- **Explain outcomes** — when a commission completes or fails, help the patron understand what happened and what to do next.',
+        '- **Suggest actions** — if you see something that needs attention (a failed commission, a missing tool, an empty roster), proactively surface it.',
+        '',
+        '## What You Don\'t Do',
+        '',
+        '- **You do not implement.** You don\'t write code, build features, or modify workshops. If the patron asks you to build something, help them commission it instead.',
+        '- **You do not modify guild state** without explicit direction from the patron. You read and report; you don\'t unilaterally change things.',
+        '- **You do not speak for other animas.** Report what the ledger says, not what you imagine another anima would think.',
+        '',
+    ].join('\n'));
+    fs.writeFileSync(path.join(home, 'roles/artificer.md'), [
+        '# Artificer',
+        '',
+        'You are a guild artificer — you undertake commissions and build the works the patron has asked for.',
+        '',
+        '## Purpose',
+        '',
+        'You are the guild\'s hands. When the patron commissions work, you receive the brief (and sage advice, if a sage is active), and you build the thing. Your output is the guild\'s works — running software, usable tools, solved problems.',
+        '',
+        '## What You Do',
+        '',
+        '- **Execute commissions** — receive a brief, understand the requirements, and deliver working results.',
+        '- **Work in workshops** — your work happens in commission worktrees. Each commission gives you an isolated workspace branched from main.',
+        '- **Write clear code** with useful comments and commit messages. Your primary audience is the next anima who continues the work.',
+        '- **Test your work** before marking a commission complete. Verify that what you built actually works.',
+        '- **Signal events** when notable things happen during your work — use `craft.question` for design decisions outside your scope, and `craft.debt` for tech debt or code smells you observe but intentionally leave alone.',
+        '',
+        '## What You Don\'t Do',
+        '',
+        '- **You do not plan commissions.** That\'s the sage\'s job. If a brief is unclear, ask for clarification rather than inventing requirements.',
+        '- **You do not modify guild infrastructure.** You work in workshops, not in the guildhall. Tools, roles, and configuration are not your concern.',
+        '- **You do not contradict sage advice.** If a sage has provided a plan, follow it. If you believe the plan has a flaw, record your concern in a commit message or comment, but execute the plan as given.',
+        '',
+    ].join('\n'));
+    // Write guild.json — with default roles, clockworks events, empty registries
     const config = createInitialGuildConfig(name, VERSION, model);
     config.roles = {
         advisor: {
@@ -69,6 +116,28 @@ export function initGuild(home, name, model) {
             tools: [],
             instructions: 'roles/advisor.md',
         },
+        artificer: {
+            seats: null,
+            tools: [],
+            instructions: 'roles/artificer.md',
+        },
+    };
+    config.clockworks = {
+        events: {
+            'craft.question': {
+                description: 'An artificer encountered a design decision outside the commission scope that needs attention.',
+                schema: { summary: 'string', workshop: 'string', commission: 'string?', context: 'string?' },
+            },
+            'craft.debt': {
+                description: 'An artificer observed tech debt or a code smell but intentionally did not address it.',
+                schema: { summary: 'string', workshop: 'string', commission: 'string?', location: 'string?' },
+            },
+        },
+        standingOrders: [
+            { on: 'commission.posted', run: 'workshop-prepare' },
+            { on: 'commission.ready', summon: 'artificer' },
+            { on: 'commission.session.ended', run: 'workshop-merge' },
+        ],
     };
     fs.writeFileSync(path.join(home, 'guild.json'), JSON.stringify(config, null, 2) + '\n');
     // Make the guildhall an npm package so guild tools can be installed as

package/dist/init-guild.js.map

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

package/dist/ledger.d.ts

@@ -1,5 +1,5 @@
 /** SQL for the initial Ledger schema (001). Creates all base tables with WAL mode and foreign keys. */
-export declare const INITIAL_SCHEMA = "\nPRAGMA journal_mode = WAL;\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE animas (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    name        TEXT    NOT NULL UNIQUE,\n    status      TEXT    NOT NULL CHECK(status IN ('aspirant', 'active', 'retired')),\n    created_at  TEXT    NOT NULL DEFAULT (datetime('now')),\n    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE anima_compositions (\n    id                    INTEGER PRIMARY KEY AUTOINCREMENT,\n    anima_id              INTEGER NOT NULL UNIQUE REFERENCES animas(id),\n    curriculum_name       TEXT    NOT NULL,\n    curriculum_version    TEXT    NOT NULL,\n    temperament_name      TEXT    NOT NULL,\n    temperament_version   TEXT    NOT NULL,\n    curriculum_snapshot   TEXT    NOT NULL,\n    temperament_snapshot  TEXT    NOT NULL,\n    composed_at           TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE roster (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    anima_id    INTEGER NOT NULL REFERENCES animas(id),\n    role        TEXT    NOT NULL,\n    standing    INTEGER NOT NULL DEFAULT 0,\n    assigned_at TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE commissions (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    content     TEXT    NOT NULL,\n    status      TEXT    NOT NULL CHECK(status IN ('posted', 'assigned', 'in_progress', 'completed', 'failed')),\n    workshop    TEXT    NOT NULL,\n    created_at  TEXT    NOT NULL DEFAULT (datetime('now')),\n    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE commission_assignments (\n    id              INTEGER PRIMARY KEY AUTOINCREMENT,\n    commission_id   INTEGER NOT NULL REFERENCES commissions(id),\n    anima_id        INTEGER NOT NULL REFERENCES animas(id),\n    assigned_at     TEXT    NOT NULL DEFAULT (datetime('now')),\n    UNIQUE(commission_id, anima_id)\n);\n\nCREATE TABLE audit_log (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    actor       TEXT    NOT NULL,\n    action      TEXT    NOT NULL,\n    target_type TEXT,\n    target_id   INTEGER,\n    detail      TEXT,\n    timestamp   TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n";
+export declare const INITIAL_SCHEMA = "\nPRAGMA journal_mode = WAL;\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE animas (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    name        TEXT    NOT NULL UNIQUE,\n    status      TEXT    NOT NULL CHECK(status IN ('aspirant', 'active', 'retired')),\n    created_at  TEXT    NOT NULL DEFAULT (datetime('now')),\n    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE anima_compositions (\n    id                    INTEGER PRIMARY KEY AUTOINCREMENT,\n    anima_id              INTEGER NOT NULL UNIQUE REFERENCES animas(id),\n    curriculum_name       TEXT    NOT NULL,\n    curriculum_version    TEXT    NOT NULL,\n    temperament_name      TEXT    NOT NULL,\n    temperament_version   TEXT    NOT NULL,\n    curriculum_snapshot   TEXT    NOT NULL,\n    temperament_snapshot  TEXT    NOT NULL,\n    composed_at           TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE roster (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    anima_id    INTEGER NOT NULL REFERENCES animas(id),\n    role        TEXT    NOT NULL,\n    standing    INTEGER NOT NULL DEFAULT 0,\n    assigned_at TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE commissions (\n    id             INTEGER PRIMARY KEY AUTOINCREMENT,\n    content        TEXT    NOT NULL,\n    status         TEXT    NOT NULL CHECK(status IN ('posted', 'assigned', 'in_progress', 'completed', 'failed')),\n    status_reason  TEXT,\n    workshop       TEXT    NOT NULL,\n    created_at     TEXT    NOT NULL DEFAULT (datetime('now')),\n    updated_at     TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE commission_assignments (\n    id              INTEGER PRIMARY KEY AUTOINCREMENT,\n    commission_id   INTEGER NOT NULL REFERENCES commissions(id),\n    anima_id        INTEGER NOT NULL REFERENCES animas(id),\n    assigned_at     TEXT    NOT NULL DEFAULT (datetime('now')),\n    UNIQUE(commission_id, anima_id)\n);\n\nCREATE TABLE audit_log (\n    id          INTEGER PRIMARY KEY AUTOINCREMENT,\n    actor       TEXT    NOT NULL,\n    action      TEXT    NOT NULL,\n    target_type TEXT,\n    target_id   INTEGER,\n    detail      TEXT,\n    timestamp   TEXT    NOT NULL DEFAULT (datetime('now'))\n);\n";
 /**
  * Create a new Ledger database at the given path and apply the initial schema.
  * @param dbPath - Absolute path where the SQLite file will be created.

package/dist/ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAEA,uGAAuG;AACvG,eAAO,MAAM,cAAc,ipEA0D1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOjD"}
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAEA,uGAAuG;AACvG,eAAO,MAAM,cAAc,6rEA2D1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOjD"}

package/dist/ledger.js

@@ -33,12 +33,13 @@ CREATE TABLE roster (
 );
 
 CREATE TABLE commissions (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    content     TEXT    NOT NULL,
-    status      TEXT    NOT NULL CHECK(status IN ('posted', 'assigned', 'in_progress', 'completed', 'failed')),
-    workshop    TEXT    NOT NULL,
-    created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
-    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    content        TEXT    NOT NULL,
+    status         TEXT    NOT NULL CHECK(status IN ('posted', 'assigned', 'in_progress', 'completed', 'failed')),
+    status_reason  TEXT,
+    workshop       TEXT    NOT NULL,
+    created_at     TEXT    NOT NULL DEFAULT (datetime('now')),
+    updated_at     TEXT    NOT NULL DEFAULT (datetime('now'))
 );
 
 CREATE TABLE commission_assignments (

package/dist/ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,uGAAuG;AACvG,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0D7B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,uGAAuG;AACvG,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2D7B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/tool.d.ts

@@ -5,22 +5,33 @@
  * The returned definition is what the MCP engine imports and registers as a tool,
  * what the CLI uses to auto-generate subcommands, and what engines import directly.
  *
- * @example
+ * A package can export a single tool or an array of tools:
+ *
+ * @example Single tool
  * ```typescript
  * import { tool } from '@shardworks/nexus-core';
  * import { z } from 'zod';
  *
  * export default tool({
+ *   name: 'lookup',
  *   description: 'Look up an anima by name',
+ *   instructionsFile: './instructions.md',
  *   params: {
  *     name: z.string().describe('Anima name'),
  *   },
  *   handler: async ({ name }, { home }) => {
- *     // ... look up anima using home to find the guild ...
  *     return { found: true, status: 'active' };
  *   },
  * });
  * ```
+ *
+ * @example Tool collection
+ * ```typescript
+ * export default [
+ *   tool({ name: 'commission', description: '...', params: {...}, handler: ... }),
+ *   tool({ name: 'signal', description: '...', params: {...}, handler: ... }),
+ * ];
+ * ```
  */
 import { z } from 'zod';
 type ZodShape = Record<string, z.ZodType>;
@@ -42,15 +53,38 @@ export interface ToolContext {
  * Engines call `.handler` directly.
  */
 export interface ToolDefinition<TShape extends ZodShape = ZodShape> {
+    /** Tool name — used for resolution when a package exports multiple tools. */
+    readonly name: string;
     readonly description: string;
+    /** Per-tool instructions injected into the anima's session context (inline text). */
+    readonly instructions?: string;
+    /**
+     * Path to an instructions file, relative to the package root.
+     * Resolved by the manifest engine at session time.
+     * Mutually exclusive with `instructions`.
+     */
+    readonly instructionsFile?: string;
     readonly params: z.ZodObject<TShape>;
     readonly handler: (params: z.infer<z.ZodObject<TShape>>, context: ToolContext) => unknown | Promise<unknown>;
 }
+/** Input to `tool()` — instructions are either inline text or a file path, not both. */
+type ToolInput<TShape extends ZodShape> = {
+    name: string;
+    description: string;
+    params: TShape;
+    handler: (params: z.infer<z.ZodObject<TShape>>, context: ToolContext) => unknown | Promise<unknown>;
+} & ({
+    instructions?: string;
+    instructionsFile?: never;
+} | {
+    instructions?: never;
+    instructionsFile?: string;
+});
 /**
  * Define a Nexus tool.
  *
  * This is the primary SDK entry point for module-based tools. Pass a
- * description, a params object of Zod schemas, and a handler function.
+ * name, description, a params object of Zod schemas, and a handler function.
  * The framework handles the rest — MCP registration, CLI generation, validation.
  *
  * The handler receives two arguments:
@@ -59,11 +93,32 @@ export interface ToolDefinition<TShape extends ZodShape = ZodShape> {
  *
  * Return any JSON-serializable value. The MCP engine wraps it as tool output;
  * the CLI prints it; engines use it directly.
+ *
+ * Instructions can be provided inline or as a file path:
+ * - `instructions: 'Use this tool when...'` — inline text
+ * - `instructionsFile: './instructions.md'` — resolved at manifest time
  */
-export declare function tool<TShape extends ZodShape>(def: {
-    description: string;
-    params: TShape;
-    handler: (params: z.infer<z.ZodObject<TShape>>, context: ToolContext) => unknown | Promise<unknown>;
-}): ToolDefinition<TShape>;
+export declare function tool<TShape extends ZodShape>(def: ToolInput<TShape>): ToolDefinition<TShape>;
+/**
+ * Resolve a single ToolDefinition from a module's default export.
+ *
+ * Handles both single-tool and array-of-tools exports:
+ * - Single tool: `export default tool({...})` → returned directly
+ * - Array: `export default [tool({...}), tool({...})]` → find by name
+ *
+ * @param moduleDefault - The module's default export
+ * @param toolName - The tool name to find (required for array exports)
+ * @returns The matching ToolDefinition, or null if not found
+ */
+export declare function resolveToolFromExport(moduleDefault: unknown, toolName?: string): ToolDefinition | null;
+/**
+ * Resolve all ToolDefinitions from a module's default export.
+ *
+ * Handles both single-tool and array-of-tools exports.
+ * Returns an array in either case.
+ */
+export declare function resolveAllToolsFromExport(moduleDefault: unknown): ToolDefinition[];
+/** Type guard: is this value a ToolDefinition? */
+export declare function isToolDefinition(obj: unknown): obj is ToolDefinition;
 export {};
 //# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,QAAQ,GAAG,QAAQ;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAChB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,EAAE,WAAW,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,QAAQ,EAAE,GAAG,EAAE;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,EAAE,WAAW,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,cAAc,CAAC,MAAM,CAAC,CAMzB"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,QAAQ,GAAG,QAAQ;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAChB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,EAAE,WAAW,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,wFAAwF;AACxF,KAAK,SAAS,CAAC,MAAM,SAAS,QAAQ,IAAI;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EACpC,OAAO,EAAE,WAAW,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,CACA;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,KAAK,CAAA;CAAE,GACnD;IAAE,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CACtD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,QAAQ,EAAE,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAS5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,OAAO,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB,cAAc,GAAG,IAAI,CAoBvB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,OAAO,GACrB,cAAc,EAAE,CAUlB;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAYpE"}

package/dist/tool.js

@@ -5,29 +5,40 @@
  * The returned definition is what the MCP engine imports and registers as a tool,
  * what the CLI uses to auto-generate subcommands, and what engines import directly.
  *
- * @example
+ * A package can export a single tool or an array of tools:
+ *
+ * @example Single tool
  * ```typescript
  * import { tool } from '@shardworks/nexus-core';
  * import { z } from 'zod';
  *
  * export default tool({
+ *   name: 'lookup',
  *   description: 'Look up an anima by name',
+ *   instructionsFile: './instructions.md',
  *   params: {
  *     name: z.string().describe('Anima name'),
  *   },
  *   handler: async ({ name }, { home }) => {
- *     // ... look up anima using home to find the guild ...
  *     return { found: true, status: 'active' };
  *   },
  * });
  * ```
+ *
+ * @example Tool collection
+ * ```typescript
+ * export default [
+ *   tool({ name: 'commission', description: '...', params: {...}, handler: ... }),
+ *   tool({ name: 'signal', description: '...', params: {...}, handler: ... }),
+ * ];
+ * ```
  */
 import { z } from 'zod';
 /**
  * Define a Nexus tool.
  *
  * This is the primary SDK entry point for module-based tools. Pass a
- * description, a params object of Zod schemas, and a handler function.
+ * name, description, a params object of Zod schemas, and a handler function.
  * The framework handles the rest — MCP registration, CLI generation, validation.
  *
  * The handler receives two arguments:
@@ -36,12 +47,80 @@ import { z } from 'zod';
  *
  * Return any JSON-serializable value. The MCP engine wraps it as tool output;
  * the CLI prints it; engines use it directly.
+ *
+ * Instructions can be provided inline or as a file path:
+ * - `instructions: 'Use this tool when...'` — inline text
+ * - `instructionsFile: './instructions.md'` — resolved at manifest time
  */
 export function tool(def) {
     return {
+        name: def.name,
         description: def.description,
+        ...(def.instructions ? { instructions: def.instructions } : {}),
+        ...(def.instructionsFile ? { instructionsFile: def.instructionsFile } : {}),
         params: z.object(def.params),
         handler: def.handler,
     };
 }
+/**
+ * Resolve a single ToolDefinition from a module's default export.
+ *
+ * Handles both single-tool and array-of-tools exports:
+ * - Single tool: `export default tool({...})` → returned directly
+ * - Array: `export default [tool({...}), tool({...})]` → find by name
+ *
+ * @param moduleDefault - The module's default export
+ * @param toolName - The tool name to find (required for array exports)
+ * @returns The matching ToolDefinition, or null if not found
+ */
+export function resolveToolFromExport(moduleDefault, toolName) {
+    // Single tool export
+    if (isToolDefinition(moduleDefault)) {
+        if (!toolName || moduleDefault.name === toolName)
+            return moduleDefault;
+        return null;
+    }
+    // Array of tools — find by name
+    if (Array.isArray(moduleDefault)) {
+        for (const item of moduleDefault) {
+            if (!isToolDefinition(item))
+                continue;
+            if (item.name === toolName)
+                return item;
+        }
+        // If no name match but array has exactly one tool, return it
+        const tools = moduleDefault.filter(isToolDefinition);
+        if (tools.length === 1 && !toolName)
+            return tools[0];
+        return null;
+    }
+    return null;
+}
+/**
+ * Resolve all ToolDefinitions from a module's default export.
+ *
+ * Handles both single-tool and array-of-tools exports.
+ * Returns an array in either case.
+ */
+export function resolveAllToolsFromExport(moduleDefault) {
+    if (isToolDefinition(moduleDefault)) {
+        return [moduleDefault];
+    }
+    if (Array.isArray(moduleDefault)) {
+        return moduleDefault.filter(isToolDefinition);
+    }
+    return [];
+}
+/** Type guard: is this value a ToolDefinition? */
+export function isToolDefinition(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'name' in obj &&
+        'description' in obj &&
+        'params' in obj &&
+        'handler' in obj &&
+        typeof obj.name === 'string' &&
+        typeof obj.description === 'string' &&
+        typeof obj.handler === 'function');
+}
 //# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiCxB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,IAAI,CAA0B,GAO7C;IACC,OAAO;QACL,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyDxB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAA0B,GAAsB;IAClE,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,aAAsB,EACtB,QAAiB;IAEjB,qBAAqB;IACrB,IAAI,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,aAAa,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;gBAAE,SAAS;YACtC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;QAC1C,CAAC;QACD,6DAA6D;QAC7D,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACrD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,aAAsB;IAEtB,IAAI,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,aAAa,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,OAAO,aAAa,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACb,aAAa,IAAI,GAAG;QACpB,QAAQ,IAAI,GAAG;QACf,SAAS,IAAI,GAAG;QAChB,OAAQ,GAAsB,CAAC,IAAI,KAAK,QAAQ;QAChD,OAAQ,GAAsB,CAAC,WAAW,KAAK,QAAQ;QACvD,OAAQ,GAAsB,CAAC,OAAO,KAAK,UAAU,CACtD,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/nexus-core",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "license": "ISC",
   "repository": {
     "type": "git",

package/dist/dispatch.d.ts

@@ -1,26 +0,0 @@
-export interface DispatchOptions {
-    /** Absolute path to the guild root. */
-    home: string;
-    /** Commission specification — what needs to be done. */
-    spec: string;
-    /** Target workshop for the commission. */
-    workshop: string;
-    /** Target anima name. If provided, the commission is assigned immediately. */
-    anima?: string;
-}
-export interface DispatchResult {
-    /** The ID of the created commission. */
-    commissionId: number;
-    /** Whether the commission was assigned to an anima. */
-    assigned: boolean;
-    /** The anima name if assigned. */
-    assignedTo?: string;
-}
-/**
- * Post a commission to the guild.
- *
- * Creates a commission in the Ledger. If an anima is specified, validates that
- * the anima exists and is active, then creates an assignment record.
- */
-export declare function dispatch(opts: DispatchOptions): DispatchResult;
-//# sourceMappingURL=dispatch.d.ts.map