@shardworks/nexus-stdlib 0.1.20

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/engines/workshop-merge.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("@shardworks/nexus-core").EngineDefinition;
+export default _default;
+//# sourceMappingURL=workshop-merge.d.ts.map

package/dist/engines/workshop-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workshop-merge.d.ts","sourceRoot":"","sources":["../../src/engines/workshop-merge.ts"],"names":[],"mappings":";AAqBA,wBAmFG"}

package/dist/engines/workshop-merge.js

@@ -0,0 +1,91 @@
+/**
+ * Workshop Merge Engine (clockwork)
+ *
+ * Standing order handler for commission.session.ended events. Merges the
+ * commission branch back into main in the workshop bare repo, tears down
+ * the worktree, and signals the outcome.
+ *
+ * Event flow:
+ *   commission.session.ended { commissionId, workshop, exitCode }
+ *     → merges commission branch into main in bare repo
+ *     → on success: teardown worktree, status → completed, signal commission.completed
+ *     → on conflict: teardown worktree, status → failed, signal commission.failed
+ */
+import { execFileSync } from 'node:child_process';
+import { engine, signalEvent, updateCommissionStatus, workshopBarePath } from '@shardworks/nexus-core';
+import { teardownWorktree } from '@shardworks/engine-worktree-setup';
+function git(args, cwd) {
+    return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+export default engine({
+    name: 'workshop-merge',
+    handler: async (event, { home }) => {
+        if (!event) {
+            throw new Error('workshop-merge requires an event (cannot be invoked directly).');
+        }
+        const payload = event.payload;
+        if (!payload || typeof payload.commissionId !== 'number' || typeof payload.workshop !== 'string') {
+            throw new Error(`workshop-merge expected payload with { commissionId, workshop }, got: ${JSON.stringify(payload)}`);
+        }
+        const commissionId = payload.commissionId;
+        const workshop = payload.workshop;
+        const branch = `commission-${commissionId}`;
+        const bareRepo = workshopBarePath(home, workshop);
+        try {
+            // Attempt to merge the commission branch into main.
+            // In a bare repo, we use a temporary index to do the merge.
+            // First check if the branch has any commits ahead of main.
+            const mergeBase = git(['merge-base', 'main', branch], bareRepo);
+            const branchTip = git(['rev-parse', branch], bareRepo);
+            if (mergeBase === branchTip) {
+                // No new commits on the branch — nothing to merge
+                teardownWorktree(home, workshop, commissionId);
+                updateCommissionStatus(home, commissionId, 'completed', 'no changes — nothing to merge');
+                signalEvent(home, 'commission.completed', { commissionId, workshop }, 'framework');
+                return;
+            }
+            // Try a fast-forward merge first
+            const mainTip = git(['rev-parse', 'main'], bareRepo);
+            if (mainTip === mergeBase) {
+                // Fast-forward: main hasn't moved since the branch was created
+                git(['update-ref', 'refs/heads/main', branchTip], bareRepo);
+                teardownWorktree(home, workshop, commissionId);
+                updateCommissionStatus(home, commissionId, 'completed', `merged to main (fast-forward to ${branchTip.slice(0, 7)})`);
+                signalEvent(home, 'commission.completed', { commissionId, workshop }, 'framework');
+                return;
+            }
+            // Non-fast-forward: main has diverged. Attempt a real merge.
+            // Use a temporary worktree for the merge operation since we can't
+            // merge directly in a bare repo.
+            //
+            // For now, fail on non-fast-forward merges. A real three-way merge
+            // in a bare repo requires a temporary index/worktree dance that adds
+            // significant complexity. This is the safe choice: the commission
+            // fails cleanly, and the patron can review and resolve manually.
+            teardownWorktree(home, workshop, commissionId);
+            updateCommissionStatus(home, commissionId, 'failed', `main has diverged — fast-forward merge not possible (main: ${mainTip.slice(0, 7)}, branch: ${branchTip.slice(0, 7)}, base: ${mergeBase.slice(0, 7)})`);
+            signalEvent(home, 'commission.failed', {
+                commissionId,
+                workshop,
+                error: 'main has diverged — fast-forward merge not possible',
+            }, 'framework');
+        }
+        catch (err) {
+            // Git operation failed — tear down worktree and fail the commission
+            try {
+                teardownWorktree(home, workshop, commissionId);
+            }
+            catch {
+                // Worktree may already be gone; ignore cleanup errors
+            }
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            updateCommissionStatus(home, commissionId, 'failed', `merge error: ${errorMsg}`);
+            signalEvent(home, 'commission.failed', {
+                commissionId,
+                workshop,
+                error: errorMsg,
+            }, 'framework');
+        }
+    },
+});
+//# sourceMappingURL=workshop-merge.js.map

package/dist/engines/workshop-merge.js.map

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

package/dist/engines/workshop-prepare.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("@shardworks/nexus-core").EngineDefinition;
+export default _default;
+//# sourceMappingURL=workshop-prepare.d.ts.map

package/dist/engines/workshop-prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workshop-prepare.d.ts","sourceRoot":"","sources":["../../src/engines/workshop-prepare.ts"],"names":[],"mappings":";AAgBA,wBA8CG"}

package/dist/engines/workshop-prepare.js

@@ -0,0 +1,45 @@
+/**
+ * Workshop Prepare Engine (clockwork)
+ *
+ * Standing order handler for commission.posted events. Creates an isolated
+ * git worktree for the commission and signals commission.ready so the next
+ * standing order (summon artificer) can launch the session.
+ *
+ * Event flow:
+ *   commission.posted { commissionId, workshop }
+ *     → creates worktree from workshop bare repo
+ *     → updates commission status → in_progress
+ *     → signals commission.ready { commissionId, workshop, worktreePath }
+ */
+import { engine, signalEvent, updateCommissionStatus, readCommission } from '@shardworks/nexus-core';
+import { setupWorktree } from '@shardworks/engine-worktree-setup';
+export default engine({
+    name: 'workshop-prepare',
+    handler: async (event, { home }) => {
+        if (!event) {
+            throw new Error('workshop-prepare requires an event (cannot be invoked directly).');
+        }
+        const payload = event.payload;
+        if (!payload || typeof payload.commissionId !== 'number' || typeof payload.workshop !== 'string') {
+            throw new Error(`workshop-prepare expected payload with { commissionId, workshop }, got: ${JSON.stringify(payload)}`);
+        }
+        const commissionId = payload.commissionId;
+        const workshop = payload.workshop;
+        // Verify commission exists
+        const commission = readCommission(home, commissionId);
+        if (!commission) {
+            throw new Error(`Commission #${commissionId} not found in the Ledger.`);
+        }
+        // Create the worktree
+        const worktree = setupWorktree({
+            home,
+            workshop,
+            commissionId,
+        });
+        // Update commission status
+        updateCommissionStatus(home, commissionId, 'in_progress', `worktree ready on branch ${worktree.branch}`);
+        // Signal ready for the next standing order (summon artificer)
+        signalEvent(home, 'commission.ready', { commissionId, workshop, worktreePath: worktree.path }, 'framework');
+    },
+});
+//# sourceMappingURL=workshop-prepare.js.map

package/dist/engines/workshop-prepare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workshop-prepare.js","sourceRoot":"","sources":["../../src/engines/workshop-prepare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE,eAAe,MAAM,CAAC;IACpB,IAAI,EAAE,kBAAkB;IACxB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;QACtF,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAyC,CAAC;QAChE,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,YAAY,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjG,MAAM,IAAI,KAAK,CACb,2EAA2E,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CACrG,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,OAAO,CAAC,YAAsB,CAAC;QACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAkB,CAAC;QAE5C,2BAA2B;QAC3B,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QACtD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,eAAe,YAAY,2BAA2B,CAAC,CAAC;QAC1E,CAAC;QAED,sBAAsB;QACtB,MAAM,QAAQ,GAAG,aAAa,CAAC;YAC7B,IAAI;YACJ,QAAQ;YACR,YAAY;SACb,CAAC,CAAC;QAEH,2BAA2B;QAC3B,sBAAsB,CACpB,IAAI,EACJ,YAAY,EACZ,aAAa,EACb,4BAA4B,QAAQ,CAAC,MAAM,EAAE,CAC9C,CAAC;QAEF,8DAA8D;QAC9D,WAAW,CACT,IAAI,EACJ,kBAAkB,EAClB,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,IAAI,EAAE,EACvD,WAAW,CACZ,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/engines.d.ts

@@ -0,0 +1,5 @@
+export { default as workshopPrepare } from './engines/workshop-prepare.ts';
+export { default as workshopMerge } from './engines/workshop-merge.ts';
+declare const _default: import("@shardworks/nexus-core").EngineDefinition[];
+export default _default;
+//# sourceMappingURL=engines.d.ts.map

package/dist/engines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.d.ts","sourceRoot":"","sources":["../src/engines.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,6BAA6B,CAAC;;AAKvE,wBAAgD"}

package/dist/engines.js

@@ -0,0 +1,6 @@
+export { default as workshopPrepare } from "./engines/workshop-prepare.js";
+export { default as workshopMerge } from "./engines/workshop-merge.js";
+import workshopPrepare from "./engines/workshop-prepare.js";
+import workshopMerge from "./engines/workshop-merge.js";
+export default [workshopPrepare, workshopMerge];
+//# sourceMappingURL=engines.js.map

package/dist/engines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.js","sourceRoot":"","sources":["../src/engines.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,eAAe,MAAM,+BAA+B,CAAC;AAC5D,OAAO,aAAa,MAAM,6BAA6B,CAAC;AAExD,eAAe,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC"}

package/dist/tools/commission.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    spec: z.ZodString;
+    workshop: z.ZodString;
+}>;
+export default _default;
+//# sourceMappingURL=commission.d.ts.map

package/dist/tools/commission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commission.d.ts","sourceRoot":"","sources":["../../src/tools/commission.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAExB,wBAWG"}

package/dist/tools/commission.js

@@ -0,0 +1,22 @@
+/**
+ * commission tool.
+ *
+ * Posts a commission to the guild and signals commission.posted for the
+ * Clockworks. Everything downstream (worktree setup, anima summoning,
+ * merge) is handled by standing orders.
+ */
+import { tool, commission } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    name: 'commission',
+    description: 'Post a commission to the guild for an artificer to work on',
+    instructionsFile: './instructions/commission.md',
+    params: {
+        spec: z.string().describe('Commission specification — what needs to be done'),
+        workshop: z.string().describe('Target workshop for the commission'),
+    },
+    handler: (params, { home }) => {
+        return commission({ home, ...params });
+    },
+});
+//# sourceMappingURL=commission.js.map

package/dist/tools/commission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commission.js","sourceRoot":"","sources":["../../src/tools/commission.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,4DAA4D;IACzE,gBAAgB,EAAE,8BAA8B;IAChD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;QAC7E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;KACpE;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,OAAO,UAAU,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/install.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    source: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    link: z.ZodOptional<z.ZodBoolean>;
+}>;
+export default _default;
+//# sourceMappingURL=install.d.ts.map

package/dist/tools/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/tools/install.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;;;AAuBxB,wBAqBG"}

package/dist/tools/install.js

@@ -0,0 +1,56 @@
+/**
+ * install-tool tool.
+ *
+ * This is the canonical implementation — called by the MCP engine (for animas),
+ * the CLI (for humans), and importable by engines. All access paths execute
+ * the same logic.
+ *
+ * Detects bundles automatically: if the source package contains a
+ * nexus-bundle.json, delegates to installBundle instead of installTool.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { tool, installTool, installBundle, classifySource, isBundleDir } from '@shardworks/nexus-core';
+import { z } from 'zod';
+/**
+ * For registry/git-url sources, npm-install the package (no-save) and check
+ * if it contains a bundle manifest. Returns the package dir if bundle, null otherwise.
+ */
+function detectBundle(home, source) {
+    const sourceKind = classifySource(source, false);
+    if (sourceKind !== 'registry' && sourceKind !== 'git-url')
+        return null;
+    execFileSync('npm', ['install', '--no-save', source], { cwd: home, stdio: 'pipe' });
+    let packageName = source;
+    if (packageName.startsWith('@') && packageName.lastIndexOf('@') > 0) {
+        packageName = packageName.substring(0, packageName.lastIndexOf('@'));
+    }
+    else if (packageName.includes('@') && !packageName.startsWith('@')) {
+        packageName = packageName.split('@')[0];
+    }
+    const packageDir = path.join(home, 'node_modules', packageName);
+    return isBundleDir(packageDir) ? packageDir : null;
+}
+export default tool({
+    name: 'install-tool',
+    description: 'Install a tool, engine, curriculum, temperament, or bundle into the guild',
+    instructionsFile: './instructions/install.md',
+    params: {
+        source: z.string().describe('npm package specifier, git URL, workshop ref, tarball path, or bundle specifier'),
+        name: z.string().optional().describe('Override the tool name (defaults to package name or directory name)'),
+        roles: z.array(z.string()).optional().describe('Roles for tool access gating'),
+        link: z.boolean().optional().describe('Symlink local directory instead of copying (for active development)'),
+    },
+    handler: (params, { home }) => {
+        // Check if source is a bundle
+        if (!params.link) {
+            const bundleDir = detectBundle(home, params.source);
+            if (bundleDir) {
+                return installBundle({ home, bundleDir, bundleSource: params.source });
+            }
+        }
+        return installTool({ home, ...params });
+    },
+});
+//# sourceMappingURL=install.js.map

package/dist/tools/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/tools/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACvG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,MAAc;IAChD,MAAM,UAAU,GAAG,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACjD,IAAI,UAAU,KAAK,UAAU,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAEvE,YAAY,CAAC,KAAK,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAEpF,IAAI,WAAW,GAAG,MAAM,CAAC;IACzB,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACpE,WAAW,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IACvE,CAAC;SAAM,IAAI,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IAC3C,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAChE,OAAO,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC;AAED,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,2EAA2E;IACxF,gBAAgB,EAAE,2BAA2B;IAC7C,MAAM,EAAE;QACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iFAAiF,CAAC;QAC9G,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qEAAqE,CAAC;QAC3G,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QAC9E,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qEAAqE,CAAC;KAC7G;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,8BAA8B;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YACpD,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,aAAa,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/instantiate.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    name: z.ZodString;
+    roles: z.ZodArray<z.ZodString>;
+    curriculum: z.ZodOptional<z.ZodString>;
+    temperament: z.ZodOptional<z.ZodString>;
+}>;
+export default _default;
+//# sourceMappingURL=instantiate.d.ts.map

package/dist/tools/instantiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instantiate.d.ts","sourceRoot":"","sources":["../../src/tools/instantiate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;;;AAExB,wBAaG"}

package/dist/tools/instantiate.js

@@ -0,0 +1,24 @@
+/**
+ * instantiate tool.
+ *
+ * This is the canonical implementation — called by the MCP engine (for animas),
+ * the CLI (for humans), and importable by engines. All access paths execute
+ * the same logic.
+ */
+import { tool, instantiate } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    name: 'instantiate',
+    description: 'Instantiate a new anima in the guild with assigned curriculum, temperament, and roles',
+    instructionsFile: './instructions/instantiate.md',
+    params: {
+        name: z.string().describe('Name for the new anima'),
+        roles: z.array(z.string()).describe('Roles the anima will hold (e.g. artificer, sage)'),
+        curriculum: z.string().optional().describe('Curriculum to assign (by name, must be registered in guild.json)'),
+        temperament: z.string().optional().describe('Temperament to assign (by name, must be registered in guild.json)'),
+    },
+    handler: (params, { home }) => {
+        return instantiate({ home, ...params });
+    },
+});
+//# sourceMappingURL=instantiate.js.map

package/dist/tools/instantiate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instantiate.js","sourceRoot":"","sources":["../../src/tools/instantiate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,uFAAuF;IACpG,gBAAgB,EAAE,+BAA+B;IACjD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACnD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;QACvF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kEAAkE,CAAC;QAC9G,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mEAAmE,CAAC;KACjH;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/nexus-version.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    verbose: z.ZodOptional<z.ZodBoolean>;
+}>;
+export default _default;
+//# sourceMappingURL=nexus-version.d.ts.map

package/dist/tools/nexus-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-version.d.ts","sourceRoot":"","sources":["../../src/tools/nexus-version.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;AAExB,wBA6CG"}

package/dist/tools/nexus-version.js

@@ -0,0 +1,42 @@
+/**
+ * nexus-version tool.
+ *
+ * Reports the guild's Nexus framework version and the registered versions
+ * of all base tools and engines. Reads from guild.json to reflect
+ * what's actually installed, not just what the framework ships with.
+ */
+import { tool, VERSION, readGuildConfig } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    name: 'nexus-version',
+    description: "Report version information for the guild's Nexus installation and base tools",
+    instructionsFile: './instructions/nexus-version.md',
+    params: {
+        verbose: z.boolean().optional().describe('Include full guild.json tool entries with timestamps'),
+    },
+    handler: (params, { home }) => {
+        const config = readGuildConfig(home);
+        /** Tools delivered by a @shardworks bundle are considered "base" (framework) tools. */
+        const isBase = (entry) => entry.bundle != null && entry.bundle.startsWith('@shardworks/');
+        // Collect base (framework) implement names
+        const baseTools = Object.keys(config.tools).filter(name => isBase(config.tools[name]));
+        // Collect base (framework) engine names
+        const baseEngines = Object.keys(config.engines).filter(name => isBase(config.engines[name]));
+        if (params.verbose) {
+            return {
+                nexus: VERSION,
+                model: config.model,
+                tools: Object.fromEntries(Object.entries(config.tools)
+                    .filter(([, e]) => isBase(e))),
+                engines: Object.fromEntries(Object.entries(config.engines)
+                    .filter(([, e]) => isBase(e))),
+            };
+        }
+        return {
+            nexus: VERSION,
+            tools: baseTools,
+            engines: baseEngines,
+        };
+    },
+});
+//# sourceMappingURL=nexus-version.js.map

package/dist/tools/nexus-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-version.js","sourceRoot":"","sources":["../../src/tools/nexus-version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE,8EAA8E;IAC3F,gBAAgB,EAAE,iCAAiC;IACnD,MAAM,EAAE;QACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;KACjG;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QAErC,uFAAuF;QACvF,MAAM,MAAM,GAAG,CAAC,KAA0B,EAAE,EAAE,CAC5C,KAAK,CAAC,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QAElE,2CAA2C;QAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAChD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CACnC,CAAC;QAEF,wCAAwC;QACxC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CACpD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACrC,CAAC;QAEF,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO;gBACL,KAAK,EAAE,OAAO;gBACd,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;qBACzB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAChC;gBACD,OAAO,EAAE,MAAM,CAAC,WAAW,CACzB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;qBAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAChC;aACF,CAAC;QACJ,CAAC;QAED,OAAO;YACL,KAAK,EAAE,OAAO;YACd,KAAK,EAAE,SAAS;YAChB,OAAO,EAAE,WAAW;SACrB,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/remove.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    name: z.ZodString;
+    category: z.ZodOptional<z.ZodEnum<{
+        tools: "tools";
+        engines: "engines";
+        curricula: "curricula";
+        temperaments: "temperaments";
+    }>>;
+}>;
+export default _default;
+//# sourceMappingURL=remove.d.ts.map

package/dist/tools/remove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove.d.ts","sourceRoot":"","sources":["../../src/tools/remove.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;;;;;;AAExB,wBAYG"}

package/dist/tools/remove.js

@@ -0,0 +1,23 @@
+/**
+ * remove-tool tool.
+ *
+ * This is the canonical implementation — called by the MCP engine (for animas),
+ * the CLI (for humans), and importable by engines. All access paths execute
+ * the same logic.
+ */
+import { tool, removeTool } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    name: 'remove-tool',
+    description: 'Remove a guild-managed tool, engine, curriculum, or temperament',
+    instructionsFile: './instructions/remove.md',
+    params: {
+        name: z.string().describe('Name of the tool to remove'),
+        category: z.enum(['tools', 'engines', 'curricula', 'temperaments']).optional()
+            .describe('Restrict to a specific category (searches all if omitted)'),
+    },
+    handler: (params, { home }) => {
+        return removeTool({ home, name: params.name, category: params.category });
+    },
+});
+//# sourceMappingURL=remove.js.map

package/dist/tools/remove.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove.js","sourceRoot":"","sources":["../../src/tools/remove.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,iEAAiE;IAC9E,gBAAgB,EAAE,0BAA0B;IAC5C,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;QACvD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC,QAAQ,EAAE;aAC3E,QAAQ,CAAC,2DAA2D,CAAC;KACzE;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,OAAO,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5E,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/signal.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+declare const _default: import("@shardworks/nexus-core").ToolDefinition<{
+    name: z.ZodString;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}>;
+export default _default;
+//# sourceMappingURL=signal.d.ts.map

package/dist/tools/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/tools/signal.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;AAExB,wBAiBG"}

package/dist/tools/signal.js

@@ -0,0 +1,26 @@
+/**
+ * signal tool.
+ *
+ * Signals a custom guild event. The event is persisted to the Ledger's events
+ * table and will be processed by the Clockworks runner. Validates that the
+ * event name is declared in guild.json and is not in a reserved namespace.
+ */
+import { tool, validateCustomEvent, signalEvent } from '@shardworks/nexus-core';
+import { z } from 'zod';
+export default tool({
+    name: 'signal',
+    description: 'Signal a custom guild event for the Clockworks',
+    instructionsFile: './instructions/signal.md',
+    params: {
+        name: z.string().describe('Event name (must be declared in guild.json clockworks.events)'),
+        payload: z.record(z.string(), z.unknown()).optional().describe('Event payload (JSON object)'),
+    },
+    handler: (params, { home }) => {
+        // Validate the event name is declared and not reserved
+        validateCustomEvent(home, params.name);
+        // Persist the event
+        const eventId = signalEvent(home, params.name, params.payload ?? null, 'anima');
+        return { eventId, name: params.name };
+    },
+});
+//# sourceMappingURL=signal.js.map

package/dist/tools/signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/tools/signal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAe,IAAI,CAAC;IAClB,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,gDAAgD;IAC7D,gBAAgB,EAAE,0BAA0B;IAC5C,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+DAA+D,CAAC;QAC1F,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;KAC9F;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QAC5B,uDAAuD;QACvD,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAEvC,oBAAoB;QACpB,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,CAAC,CAAC;QAEhF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;CACF,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,35 @@
+export { default as commission } from './tools/commission.ts';
+export { default as signal } from './tools/signal.ts';
+export { default as install } from './tools/install.ts';
+export { default as remove } from './tools/remove.ts';
+export { default as instantiate } from './tools/instantiate.ts';
+export { default as nexusVersion } from './tools/nexus-version.ts';
+declare const _default: (import("@shardworks/nexus-core").ToolDefinition<{
+    spec: import("zod").ZodString;
+    workshop: import("zod").ZodString;
+}> | import("@shardworks/nexus-core").ToolDefinition<{
+    name: import("zod").ZodString;
+    payload: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+}> | import("@shardworks/nexus-core").ToolDefinition<{
+    source: import("zod").ZodString;
+    name: import("zod").ZodOptional<import("zod").ZodString>;
+    roles: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    link: import("zod").ZodOptional<import("zod").ZodBoolean>;
+}> | import("@shardworks/nexus-core").ToolDefinition<{
+    name: import("zod").ZodString;
+    category: import("zod").ZodOptional<import("zod").ZodEnum<{
+        tools: "tools";
+        engines: "engines";
+        curricula: "curricula";
+        temperaments: "temperaments";
+    }>>;
+}> | import("@shardworks/nexus-core").ToolDefinition<{
+    name: import("zod").ZodString;
+    roles: import("zod").ZodArray<import("zod").ZodString>;
+    curriculum: import("zod").ZodOptional<import("zod").ZodString>;
+    temperament: import("zod").ZodOptional<import("zod").ZodString>;
+}> | import("@shardworks/nexus-core").ToolDefinition<{
+    verbose: import("zod").ZodOptional<import("zod").ZodBoolean>;
+}>)[];
+export default _default;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASnE,wBAAgF"}

package/dist/tools.js

@@ -0,0 +1,14 @@
+export { default as commission } from "./tools/commission.js";
+export { default as signal } from "./tools/signal.js";
+export { default as install } from "./tools/install.js";
+export { default as remove } from "./tools/remove.js";
+export { default as instantiate } from "./tools/instantiate.js";
+export { default as nexusVersion } from "./tools/nexus-version.js";
+import commission from "./tools/commission.js";
+import signal from "./tools/signal.js";
+import install from "./tools/install.js";
+import remove from "./tools/remove.js";
+import instantiate from "./tools/instantiate.js";
+import nexusVersion from "./tools/nexus-version.js";
+export default [commission, signal, install, remove, instantiate, nexusVersion];
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,MAAM,MAAM,mBAAmB,CAAC;AACvC,OAAO,OAAO,MAAM,oBAAoB,CAAC;AACzC,OAAO,MAAM,MAAM,mBAAmB,CAAC;AACvC,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,YAAY,MAAM,0BAA0B,CAAC;AAEpD,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC"}

package/instructions/commission.md

@@ -0,0 +1,21 @@
+# commission
+
+Post a commission to the guild. The Clockworks handles everything downstream — worktree setup, anima summoning, and post-session merge.
+
+## Usage
+
+```
+commission <spec> --workshop <workshop>
+```
+
+## Arguments
+
+- `<spec>` — Commission specification describing what needs to be done. Include a clear problem statement and acceptance criteria.
+- `--workshop <workshop>` — Target workshop where the work will be done.
+
+## Guidance
+
+- Write clear, specific commission specs. The artificer receives this as their entire brief.
+- Include acceptance criteria so the artificer knows when the work is done.
+- After posting, use `nsg clock run` to process the commission through the Clockworks pipeline.
+- The commission flows through standing orders: workshop-prepare → summon artificer → workshop-merge.

package/instructions/install.md

@@ -0,0 +1,44 @@
+# install-tool
+
+Install a new tool into the guild from a local directory, npm package, or tarball.
+
+## Usage
+
+```
+install-tool <source> [--name <name>] [--roles <roles>] [--link]
+```
+
+## Arguments
+
+- `<source>` — Local directory path, npm package specifier (e.g. `foo@1.0`, `@scope/tool`), or tarball path (`.tgz`)
+- `--name <name>` — Override the tool name (defaults to package name or directory basename)
+- `--roles <roles>` — Comma-separated roles for tool access gating
+- `--link` — Symlink a local directory instead of copying (for active development)
+
+## Source types
+
+The source is automatically classified:
+
+- **Local directory with `package.json`** — installed via `npm install` into the guild's `node_modules`. Dependencies are resolved automatically.
+- **Local directory without `package.json`** — copied directly to the guild. No dependency resolution.
+- **npm specifier** (e.g. `my-tool@1.0`, `@scope/tool`) — installed from the npm registry.
+- **Tarball** (`.tgz`/`.tar.gz`) — installed via npm from a local archive.
+
+## Examples
+
+Install a locally-built implement:
+```
+install-tool ./path/to/my-tool --roles artificer
+```
+
+Install from npm registry:
+```
+install-tool some-published-tool@1.2.0 --roles herald
+```
+
+Link a tool for active development (changes are live):
+```
+install-tool ~/projects/my-tool --link --roles artificer
+```
+
+The tool will detect the descriptor type (implement, engine, curriculum, or temperament), install it to the correct location, and register it in guild.json.

package/instructions/instantiate.md

@@ -0,0 +1,22 @@
+# instantiate
+
+Create a new anima in the guild — recording its composition (curriculum, temperament, roles) in the Ledger so it can be manifested for sessions.
+
+## Usage
+
+```
+instantiate <name> --roles <roles> [--curriculum <curriculum>] [--temperament <temperament>]
+```
+
+## Arguments
+
+- `<name>` — Name for the new anima
+- `--roles <roles>` — Comma-separated roles the anima will hold (e.g. artificer, sage)
+- `--curriculum <curriculum>` — Curriculum to assign (must be registered in guild.json)
+- `--temperament <temperament>` — Temperament to assign (must be registered in guild.json)
+
+## Guidance
+
+- The anima's name should be unique within the guild.
+- Roles determine which implements the anima can access (via role gating).
+- Curriculum and temperament must already be installed in the guild before they can be assigned.

package/instructions/nexus-version.md

@@ -0,0 +1,25 @@
+# nexus-version
+
+Report version information about the guild's Nexus installation.
+
+## Usage
+
+```
+nexus-version
+```
+
+No arguments required. Returns the framework version and a list of all base tools and engines.
+
+## When to use
+
+- When diagnosing compatibility issues or unexpected behavior
+- When reporting bugs or requesting support
+- When verifying that a guild upgrade completed successfully
+- Before installing a tool that declares a `nexusVersion` requirement
+
+## Output
+
+Returns a JSON object with:
+- `nexus` — the framework version
+- `implements` — base tool names
+- `engines` — base engine names

package/instructions/remove.md

@@ -0,0 +1,18 @@
+# remove-tool
+
+Remove a guild-managed tool — deregisters it from guild.json and removes its on-disk directory.
+
+## Usage
+
+```
+remove-tool <name>
+```
+
+## Arguments
+
+- `<name>` — Name of the tool to remove
+
+## Constraints
+
+- If the tool was installed via npm, the package is also removed from `node_modules`.
+- Linked tools have their symlink removed.

package/instructions/signal.md

@@ -0,0 +1,13 @@
+# signal
+
+Signal a custom guild event. The event is recorded in the Ledger and will be processed by the Clockworks runner when `nsg clock tick` or `nsg clock run` is invoked.
+
+## Usage
+
+- The event name **must** be declared in `guild.json` under `clockworks.events`.
+- You **cannot** signal framework events (`anima.*`, `commission.*`, `tool.*`, `migration.*`, `guild.*`, `standing-order.*`) — those are emitted automatically by the framework.
+- The optional payload is a JSON object with event-specific data.
+
+## When to use
+
+Signal an event when something meaningful has happened that other parts of the guild should know about. Standing orders in `guild.json` determine what happens in response.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@shardworks/nexus-stdlib",
+  "version": "0.1.20",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus-mk2",
+    "directory": "packages/stdlib"
+  },
+  "description": "Standard tools and engines for the Nexus guild system",
+  "type": "module",
+  "exports": {
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./engines": {
+      "types": "./dist/engines.d.ts",
+      "import": "./dist/engines.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@shardworks/nexus-core": "0.1.20",
+    "@shardworks/engine-worktree-setup": "0.1.20"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist",
+    "instructions"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}