@shardworks/spider-apparatus 0.1.226 → 0.1.228

package/README.md

@@ -125,7 +125,21 @@ Return the merged effective writ-type → template-name mapping. Config mappings
 
 ## Configuration
 
-The Spider reads its config from `guild.json["spider"]`:
+The Spider reads its config from `guild.json["spider"]`. Zero-config works out of the box for mandate dispatch — Spider's apparatus contributes a plugin-default rig template (`default`: draft → implement → review → revise → seal) and a default mapping (`mandate → default`) via its own supportKit. A minimal guild only needs to declare `spider.variables` so the default template can interpolate role / build command / test command:
+
+```json
+{
+  "spider": {
+    "variables": {
+      "role": "artificer",
+      "buildCommand": "pnpm -w build",
+      "testCommand": "pnpm -w test"
+    }
+  }
+}
+```
+
+Guilds that need a custom pipeline can override the plugin defaults by declaring their own `rigTemplates` and/or `rigTemplateMappings`:
 
 ```json
 {
@@ -166,14 +180,16 @@ The Spider reads its config from `guild.json["spider"]`:
 }
 ```
 
+A config-level template named `default` overrides the plugin-contributed `spider.default` for the `mandate → default` lookup: the registry resolves the kit mapping against the bare name first, then falls back to `${pluginId}.${templateName}` when the bare name is not claimed.
+
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `pollIntervalMs` | `number` | `5000` | Polling interval for the `crawl-continual` tool (ms). |
 | `buildCommand` | `string` | — | Build command forwarded to quick engines. |
 | `testCommand` | `string` | — | Test command forwarded to quick engines. |
-| `variables` | `Record<string, unknown>` | — | Named values available in rig template givens via `${vars.<path>}`. |
-| `rigTemplates` | `Record<string, RigTemplate>` | — | Named rig template definitions. |
-| `rigTemplateMappings` | `Record<string, string>` | — | Writ type → template name. `'default'` is the fallback. |
+| `variables` | `Record<string, unknown>` | — | Named values available in rig template givens via `${vars.<path>}`. The plugin-default template requires `role`, `buildCommand`, and `testCommand`. |
+| `rigTemplates` | `Record<string, RigTemplate>` | plugin default `default` (draft → seal) | Named rig template definitions. Config-level entries override plugin-contributed templates of the same name. |
+| `rigTemplateMappings` | `Record<string, string>` | plugin default `{ mandate: 'default' }` | Writ type → template name. Config-level entries override plugin-contributed mappings for the same writ type. |
 | `maxConcurrentEngines` | `number` | `3` | Maximum number of engines running concurrently across all rigs. When the limit is reached, runnable engines stay in `pending` and new rigs are not spawned until a slot frees. |
 | `maxConcurrentEnginesPerRig` | `number` | `1` | Maximum number of engines running concurrently within a single rig. Prevents race conditions with rig-local resources. |
 

package/dist/default-template.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Spider's plugin-default rig template (`default`).
+ *
+ * This is the canonical draft → implement → review → revise → seal
+ * pipeline that every guild used to declare inline under
+ * `spider.rigTemplates.default` in its `guild.json`. It is now
+ * contributed as a plugin default so mandate dispatch works out of the
+ * box with zero guild configuration — an operator only needs to declare
+ * `spider.variables` for the role and build/test commands.
+ *
+ * Guilds may still override this template by declaring their own
+ * `spider.rigTemplates.default` in guild.json; config entries win over
+ * plugin-contributed defaults via the RigTemplateRegistry's precedence
+ * rules.
+ *
+ * Per D7 in the plan-and-ship commission, this template has no fallback
+ * defaults for `${vars.role}`, `${vars.buildCommand}`, or
+ * `${vars.testCommand}` — a missing variable raises at dispatch time so
+ * misconfiguration is surfaced loudly rather than masked.
+ */
+import type { RigTemplate } from './types.ts';
+export declare const defaultRigTemplate: RigTemplate;
+//# sourceMappingURL=default-template.d.ts.map

package/dist/default-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-template.d.ts","sourceRoot":"","sources":["../src/default-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,kBAAkB,EAAE,WAsChC,CAAC"}

package/dist/default-template.js

@@ -0,0 +1,60 @@
+/**
+ * Spider's plugin-default rig template (`default`).
+ *
+ * This is the canonical draft → implement → review → revise → seal
+ * pipeline that every guild used to declare inline under
+ * `spider.rigTemplates.default` in its `guild.json`. It is now
+ * contributed as a plugin default so mandate dispatch works out of the
+ * box with zero guild configuration — an operator only needs to declare
+ * `spider.variables` for the role and build/test commands.
+ *
+ * Guilds may still override this template by declaring their own
+ * `spider.rigTemplates.default` in guild.json; config entries win over
+ * plugin-contributed defaults via the RigTemplateRegistry's precedence
+ * rules.
+ *
+ * Per D7 in the plan-and-ship commission, this template has no fallback
+ * defaults for `${vars.role}`, `${vars.buildCommand}`, or
+ * `${vars.testCommand}` — a missing variable raises at dispatch time so
+ * misconfiguration is surfaced loudly rather than masked.
+ */
+export const defaultRigTemplate = {
+    engines: [
+        {
+            id: 'draft',
+            designId: 'draft',
+            givens: { writ: '${writ}' },
+        },
+        {
+            id: 'implement',
+            designId: 'implement',
+            upstream: ['draft'],
+            givens: { writ: '${writ}', role: '${vars.role}' },
+        },
+        {
+            id: 'review',
+            designId: 'review',
+            upstream: ['implement'],
+            givens: {
+                writ: '${writ}',
+                role: 'reviewer',
+                buildCommand: '${vars.buildCommand}',
+                testCommand: '${vars.testCommand}',
+            },
+        },
+        {
+            id: 'revise',
+            designId: 'revise',
+            upstream: ['review'],
+            givens: { writ: '${writ}', role: '${vars.role}' },
+        },
+        {
+            id: 'seal',
+            designId: 'seal',
+            upstream: ['revise'],
+            givens: {},
+        },
+    ],
+    resolutionEngine: 'seal',
+};
+//# sourceMappingURL=default-template.js.map

package/dist/default-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-template.js","sourceRoot":"","sources":["../src/default-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAAgB;IAC7C,OAAO,EAAE;QACP;YACE,EAAE,EAAE,OAAO;YACX,QAAQ,EAAE,OAAO;YACjB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;SAC5B;QACD;YACE,EAAE,EAAE,WAAW;YACf,QAAQ,EAAE,WAAW;YACrB,QAAQ,EAAE,CAAC,OAAO,CAAC;YACnB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE;SAClD;QACD;YACE,EAAE,EAAE,QAAQ;YACZ,QAAQ,EAAE,QAAQ;YAClB,QAAQ,EAAE,CAAC,WAAW,CAAC;YACvB,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,UAAU;gBAChB,YAAY,EAAE,sBAAsB;gBACpC,WAAW,EAAE,qBAAqB;aACnC;SACF;QACD;YACE,EAAE,EAAE,QAAQ;YACZ,QAAQ,EAAE,QAAQ;YAClB,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE;SAClD;QACD;YACE,EAAE,EAAE,MAAM;YACV,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,MAAM,EAAE,EAAE;SACX;KACF;IACD,gBAAgB,EAAE,MAAM;CACzB,CAAC"}

package/dist/engines/implement.d.ts

@@ -1,11 +1,21 @@
 /**
  * Implement engine — quick (Animator-backed).
  *
- * Summons an anima to do the commissioned work. Wraps the writ body with
- * task-manifest-aware execution instructions, then calls animator.summon()
- * with the draft worktree as the working directory. Returns
- * `{ status: 'launched', sessionId }` so the Spider's collect step can poll
- * for completion on subsequent walks.
+ * Summons an anima to do the commissioned work. Wraps the writ body (or
+ * the optional `prompt` override given) with task-manifest-aware execution
+ * instructions, then calls animator.summon() with the draft worktree as
+ * the working directory. Returns `{ status: 'launched', sessionId }` so the
+ * Spider's collect step can poll for completion on subsequent walks.
+ *
+ * Givens:
+ *   - writ      (required) — the WritDoc for this rig.
+ *   - role      (required) — the anima role to summon.
+ *   - prompt    (optional) — a prompt string that replaces `writ.body` as
+ *                            the body of the execution prompt. The
+ *                            EXECUTION_EPILOGUE is still appended. Used by
+ *                            the combined plan-and-ship rig to hand the
+ *                            planning spec to the implementing anima;
+ *                            absent on the vanilla mandate path.
  */
 import type { EngineDesign } from '@shardworks/fabricator-apparatus';
 /**

package/dist/engines/implement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"implement.d.ts","sourceRoot":"","sources":["../../src/engines/implement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAKrE;;;;;GAKG;AACH,QAAA,MAAM,kBAAkB,usBASuB,CAAC;AAEhD,QAAA,MAAM,eAAe,EAAE,YAoBtB,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAe,eAAe,CAAC"}
+{"version":3,"file":"implement.d.ts","sourceRoot":"","sources":["../../src/engines/implement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAKrE;;;;;GAKG;AACH,QAAA,MAAM,kBAAkB,usBASuB,CAAC;AAEhD,QAAA,MAAM,eAAe,EAAE,YA4BtB,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAe,eAAe,CAAC"}

package/dist/engines/implement.js

@@ -1,11 +1,21 @@
 /**
  * Implement engine — quick (Animator-backed).
  *
- * Summons an anima to do the commissioned work. Wraps the writ body with
- * task-manifest-aware execution instructions, then calls animator.summon()
- * with the draft worktree as the working directory. Returns
- * `{ status: 'launched', sessionId }` so the Spider's collect step can poll
- * for completion on subsequent walks.
+ * Summons an anima to do the commissioned work. Wraps the writ body (or
+ * the optional `prompt` override given) with task-manifest-aware execution
+ * instructions, then calls animator.summon() with the draft worktree as
+ * the working directory. Returns `{ status: 'launched', sessionId }` so the
+ * Spider's collect step can poll for completion on subsequent walks.
+ *
+ * Givens:
+ *   - writ      (required) — the WritDoc for this rig.
+ *   - role      (required) — the anima role to summon.
+ *   - prompt    (optional) — a prompt string that replaces `writ.body` as
+ *                            the body of the execution prompt. The
+ *                            EXECUTION_EPILOGUE is still appended. Used by
+ *                            the combined plan-and-ship rig to hand the
+ *                            planning spec to the implementing anima;
+ *                            absent on the vanilla mandate path.
  */
 import { guild } from '@shardworks/nexus-core';
 /**
@@ -30,7 +40,15 @@ const implementEngine = {
         const animator = guild().apparatus('animator');
         const writ = givens.writ;
         const draft = context.upstream['draft'];
-        const prompt = `${writ.body}\n${EXECUTION_EPILOGUE}`;
+        // The `prompt` given, when supplied by the rig template, overrides
+        // `writ.body` as the execution body. The EXECUTION_EPILOGUE is appended
+        // either way so task-manifest-aware execution instructions travel with
+        // both paths. When `prompt` is omitted the engine's behaviour is
+        // byte-identical to the pre-refactor version.
+        const body = typeof givens.prompt === 'string' && givens.prompt.length > 0
+            ? givens.prompt
+            : writ.body;
+        const prompt = `${body}\n${EXECUTION_EPILOGUE}`;
         const handle = animator.summon({
             role: givens.role,
             prompt,

package/dist/engines/implement.js.map

@@ -1 +1 @@
-{"version":3,"file":"implement.js","sourceRoot":"","sources":["../../src/engines/implement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAM/C;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG;;;;;;;;;+CASoB,CAAC;AAEhD,MAAM,eAAe,GAAiB;IACpC,EAAE,EAAE,WAAW;IAEf,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO;QACvB,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,SAAS,CAAc,UAAU,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAe,CAAC;QACpC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB,CAAC;QAEvD,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;QAErD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC7B,IAAI,EAAE,MAAM,CAAC,IAAc;YAC3B,MAAM;YACN,GAAG,EAAE,KAAK,CAAC,IAAI;YACf,WAAW,EAAE,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC,EAAE,cAAc,EAAE;YAC3D,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE;SAC1D,CAAC,CAAC;QAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC7D,CAAC;CACF,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAe,eAAe,CAAC"}
+{"version":3,"file":"implement.js","sourceRoot":"","sources":["../../src/engines/implement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAM/C;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG;;;;;;;;;+CASoB,CAAC;AAEhD,MAAM,eAAe,GAAiB;IACpC,EAAE,EAAE,WAAW;IAEf,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO;QACvB,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,SAAS,CAAc,UAAU,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAe,CAAC;QACpC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB,CAAC;QAEvD,mEAAmE;QACnE,wEAAwE;QACxE,uEAAuE;QACvE,iEAAiE;QACjE,8CAA8C;QAC9C,MAAM,IAAI,GAAG,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YACxE,CAAC,CAAC,MAAM,CAAC,MAAM;YACf,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACd,MAAM,MAAM,GAAG,GAAG,IAAI,KAAK,kBAAkB,EAAE,CAAC;QAEhD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC7B,IAAI,EAAE,MAAM,CAAC,IAAc;YAC3B,MAAM;YACN,GAAG,EAAE,KAAK,CAAC,IAAI;YACf,WAAW,EAAE,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC,EAAE,cAAc,EAAE;YAC3D,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE;SAC1D,CAAC,CAAC;QAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC7D,CAAC;CACF,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,eAAe,eAAe,CAAC"}

package/dist/oculus-routes.d.ts

@@ -4,11 +4,17 @@
  * Contributes:
  * - GET /api/spider/config — aggregated snapshot of Spider config
  * - GET /api/spider/session-transcript — session transcript and status
- * - GET /api/spider/session-stream — SSE stream of real-time session chunks
  *
  * Does NOT import from @shardworks/oculus-apparatus to avoid a circular
  * package dependency. The route shape is compatible with RouteContribution
  * from the Oculus types.
+ *
+ * The former /api/spider/session-stream (SSE) route was removed when the
+ * Spider UI switched to uniform 2 s polling of /api/spider/session-transcript.
+ * The SSE path only worked for in-process (attached) sessions and silently
+ * dropped data for detached (cross-process) sessions because the Animator's
+ * subscribeToSession cannot bridge processes. Polling the Stacks-backed
+ * transcript works uniformly for both attached and detached sessions.
  */
 import type { Context } from 'hono';
 export declare const spiderRoutes: ({
@@ -48,6 +54,15 @@ export declare const spiderRoutes: ({
 } | {
     method: string;
     path: string;
-    handler: (c: Context) => Promise<Response>;
+    handler: (c: Context) => Promise<(Response & import("hono").TypedResponse<{
+        error: string;
+    }, 400, "json">) | (Response & import("hono").TypedResponse<{
+        error: string;
+    }, 404, "json">) | (Response & import("hono").TypedResponse<{
+        messages: {
+            [x: string]: import("hono/utils/types").JSONValue;
+        }[];
+        sessionStatus: "pending" | "running" | "completed" | "failed" | "cancelled" | "timeout";
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
 })[];
 //# sourceMappingURL=oculus-routes.d.ts.map

package/dist/oculus-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oculus-routes.d.ts","sourceRoot":"","sources":["../src/oculus-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAepC,eAAO,MAAM,YAAY;;;iBAIR,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiDD,OAAO;IAkF7B,CAAC"}
+{"version":3,"file":"oculus-routes.d.ts","sourceRoot":"","sources":["../src/oculus-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAcpC,eAAO,MAAM,YAAY;;;iBAIR,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBD,OAAO;;;;;;;;;;IA8B7B,CAAC"}

package/dist/oculus-routes.js

@@ -4,13 +4,18 @@
  * Contributes:
  * - GET /api/spider/config — aggregated snapshot of Spider config
  * - GET /api/spider/session-transcript — session transcript and status
- * - GET /api/spider/session-stream — SSE stream of real-time session chunks
  *
  * Does NOT import from @shardworks/oculus-apparatus to avoid a circular
  * package dependency. The route shape is compatible with RouteContribution
  * from the Oculus types.
+ *
+ * The former /api/spider/session-stream (SSE) route was removed when the
+ * Spider UI switched to uniform 2 s polling of /api/spider/session-transcript.
+ * The SSE path only worked for in-process (attached) sessions and silently
+ * dropped data for detached (cross-process) sessions because the Animator's
+ * subscribeToSession cannot bridge processes. Polling the Stacks-backed
+ * transcript works uniformly for both attached and detached sessions.
  */
-import { streamSSE } from 'hono/streaming';
 import { guild } from '@shardworks/nexus-core';
 export const spiderRoutes = [
     {
@@ -45,8 +50,8 @@ export const spiderRoutes = [
             }
             // Read transcript regardless of status. Detached sessions (babysitter)
             // write transcript chunks to SQLite incrementally while the session is
-            // still 'running' or 'pending'; the client polls this endpoint to
-            // refresh the engine view's session log in flight.
+            // still 'running' or 'pending'; the client polls this endpoint every
+            // 2 s to refresh the engine view's session log in flight.
             const transcriptsBook = stacks.readBook('animator', 'transcripts');
             const transcript = await transcriptsBook.get(sessionId);
             return c.json({
@@ -55,80 +60,5 @@ export const spiderRoutes = [
             });
         },
     },
-    {
-        method: 'GET',
-        path: '/api/spider/session-stream',
-        handler: async (c) => {
-            const sessionId = c.req.query('sessionId');
-            if (!sessionId) {
-                return c.json({ error: 'sessionId is required' }, 400);
-            }
-            const g = guild();
-            const stacks = g.apparatus('stacks');
-            const sessionsBook = stacks.readBook('animator', 'sessions');
-            const session = await sessionsBook.get(sessionId);
-            if (!session) {
-                return c.json({ error: 'Session not found' }, 404);
-            }
-            // For already-completed sessions, stream the full transcript and close.
-            if (session.status !== 'running') {
-                const transcriptsBook = stacks.readBook('animator', 'transcripts');
-                const transcript = await transcriptsBook.get(sessionId);
-                return streamSSE(c, async (stream) => {
-                    await stream.writeSSE({
-                        event: 'transcript',
-                        data: JSON.stringify({ messages: transcript?.messages ?? [] }),
-                    });
-                    await stream.writeSSE({
-                        event: 'done',
-                        data: JSON.stringify({ status: session.status }),
-                    });
-                });
-            }
-            // For running sessions, subscribe to the Animator's in-process broadcaster.
-            const animator = g.apparatus('animator');
-            const chunkStream = animator.subscribeToSession(sessionId);
-            if (!chunkStream) {
-                // The session is marked running in Stacks but has no in-memory broadcaster
-                // (e.g. a server restart happened). Return an empty stream so the UI can
-                // show a meaningful "no data" state and fall back gracefully.
-                return streamSSE(c, async (stream) => {
-                    await stream.writeSSE({
-                        event: 'done',
-                        data: JSON.stringify({ status: 'running', noStream: true }),
-                    });
-                });
-            }
-            return streamSSE(c, async (stream) => {
-                try {
-                    for await (const chunk of chunkStream) {
-                        await stream.writeSSE({
-                            event: 'chunk',
-                            data: JSON.stringify(chunk),
-                        });
-                    }
-                    // All chunks consumed — session has ended. Fetch and emit final transcript.
-                    const transcriptsBook = stacks.readBook('animator', 'transcripts');
-                    const transcript = await transcriptsBook.get(sessionId);
-                    await stream.writeSSE({
-                        event: 'transcript',
-                        data: JSON.stringify({ messages: transcript?.messages ?? [] }),
-                    });
-                    const finalSession = await sessionsBook.get(sessionId);
-                    await stream.writeSSE({
-                        event: 'done',
-                        data: JSON.stringify({ status: finalSession?.status ?? 'completed' }),
-                    });
-                }
-                catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    await stream.writeSSE({
-                        event: 'error',
-                        data: JSON.stringify({ error: message }),
-                    });
-                }
-            });
-        },
-    },
 ];
 //# sourceMappingURL=oculus-routes.js.map

package/dist/oculus-routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"oculus-routes.js","sourceRoot":"","sources":["../src/oculus-routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oculus-routes.js","sourceRoot":"","sources":["../src/oculus-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAa/C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;QACE,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,CAAC,CAAU,EAAE,EAAE;YACtB,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;YAClB,MAAM,UAAU,GAAG,CAAC,CAAC,SAAS,CAAgB,YAAY,CAAC,CAAC;YAC5D,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAY,QAAQ,CAAC,CAAC;YAEhD,OAAO,CAAC,CAAC,IAAI,CAAC;gBACZ,SAAS,EAAE,MAAM,CAAC,aAAa,EAAE;gBACjC,gBAAgB,EAAE,MAAM,CAAC,oBAAoB,EAAE;gBAC/C,aAAa,EAAE,UAAU,CAAC,iBAAiB,EAAE;gBAC7C,UAAU,EAAE,MAAM,CAAC,cAAc,EAAE;aACpC,CAAC,CAAC;QACL,CAAC;KACF;IACD;QACE,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,gCAAgC;QACtC,OAAO,EAAE,KAAK,EAAE,CAAU,EAAE,EAAE;YAC5B,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YAE3C,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,EAAE,GAAG,CAAC,CAAC;YACzD,CAAC;YAED,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAY,QAAQ,CAAC,CAAC;YAEhD,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAa,UAAU,EAAE,UAAU,CAAC,CAAC;YACzE,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAElD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,GAAG,CAAC,CAAC;YACrD,CAAC;YAED,uEAAuE;YACvE,uEAAuE;YACvE,qEAAqE;YACrE,0DAA0D;YAC1D,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAkB,UAAU,EAAE,aAAa,CAAC,CAAC;YACpF,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAExD,OAAO,CAAC,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,UAAU,EAAE,QAAQ,IAAI,EAAE;gBACpC,aAAa,EAAE,OAAO,CAAC,MAAM;aAC9B,CAAC,CAAC;QACL,CAAC;KACF;CACF,CAAC"}

package/dist/spider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spider.d.ts","sourceRoot":"","sources":["../src/spider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAwD,MAAM,wBAAwB,CAAC;AAQ3G,OAAO,KAAK,EACV,MAAM,EAUN,WAAW,EAOZ,MAAM,YAAY,CAAC;AAmDpB,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,oFAAoF;IACpF,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAyDD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM5D;AA2/BD,wBAAgB,YAAY,IAAI,MAAM,CAy0CrC"}
+{"version":3,"file":"spider.d.ts","sourceRoot":"","sources":["../src/spider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAwD,MAAM,wBAAwB,CAAC;AAQ3G,OAAO,KAAK,EACV,MAAM,EAUN,WAAW,EAOZ,MAAM,YAAY,CAAC;AAqDpB,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,oFAAoF;IACpF,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAyDD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM5D;AA0hCD,wBAAgB,YAAY,IAAI,MAAM,CAm1CrC"}

package/dist/spider.js

@@ -30,6 +30,7 @@ import { animaSessionEngine, draftEngine, implementEngine, implementLoopEngine,
 import { writPhaseBlockType, scheduledTimeBlockType, bookUpdatedBlockType, patronInputBlockType, } from "./block-types/index.js";
 import { crawlOneTool, crawlContinualTool, rigShowTool, rigListTool, rigForWritTool, rigResumeTool, inputRequestListTool, inputRequestShowTool, inputRequestAnswerTool, inputRequestCompleteTool, inputRequestRejectTool, inputRequestExportTool, inputRequestImportTool, engineDesignsTool, blockTypesTool, rigCancelTool, } from "./tools/index.js";
 import { spiderRoutes } from "./oculus-routes.js";
+import { defaultRigTemplate } from "./default-template.js";
 import { interpolateTemplate, extractExpressions, resolveDotPath, SKIP, } from "./template.js";
 // ── Helpers ────────────────────────────────────────────────────────────
 /**
@@ -633,12 +634,33 @@ class RigTemplateRegistry {
     templates = new Map();
     /** Config writ-type-to-template-name mappings */
     configMappings = new Map();
-    /** Kit-contributed mappings (first-registered wins) */
+    /**
+     * Kit-contributed mappings (first-registered wins). Each entry records
+     * the contributing pluginId so the registry can fall back from an
+     * unqualified templateName to the kit's own qualified `${pluginId}.${name}`
+     * when no config-level template has claimed the unqualified slot.
+     */
     kitMappings = new Map();
     /** Config-declared template names (for override checking) */
     configTemplateNames = new Set();
     /** designId → pluginId that contributed it */
     designSourceMap = new Map();
+    /**
+     * Resolve the actual template name stored in `templates` for a kit
+     * mapping entry. Prefer the literal value (so config-level overrides
+     * with the same name win); otherwise fall back to the kit's own
+     * qualified name. Returns undefined when neither form resolves.
+     */
+    resolveKitMappedName(entry) {
+        if (this.templates.has(entry.templateName))
+            return entry.templateName;
+        if (!entry.templateName.includes('.')) {
+            const qualified = `${entry.pluginId}.${entry.templateName}`;
+            if (this.templates.has(qualified))
+                return qualified;
+        }
+        return undefined;
+    }
     /**
      * Build the designId → pluginId map from all engine KitEntries.
      * Called once at startup before any kit registration.
@@ -895,7 +917,7 @@ class RigTemplateRegistry {
                 console.warn(`[spider] Kit "${pluginId}" rigTemplateMappings.${writType}: mapping for "${writType}" already registered by another kit — skipped`);
                 continue;
             }
-            this.kitMappings.set(writType, templateName);
+            this.kitMappings.set(writType, { templateName, pluginId });
         }
     }
     /**
@@ -909,10 +931,12 @@ class RigTemplateRegistry {
                 throw new Error(`[spider] rigTemplateMappings.${writType}: references unknown template "${templateName}"`);
             }
         }
-        // Kit mappings — warn and remove on dangling
-        for (const [writType, templateName] of [...this.kitMappings]) {
-            if (!this.templates.has(templateName)) {
-                console.warn(`[spider] Kit mapping "${writType}" → "${templateName}": template not found — removed`);
+        // Kit mappings — warn and remove on dangling. An unqualified templateName
+        // is considered resolved if either the bare name or the kit's own
+        // `${pluginId}.${templateName}` exists in the template registry.
+        for (const [writType, entry] of [...this.kitMappings]) {
+            if (this.resolveKitMappedName(entry) === undefined) {
+                console.warn(`[spider] Kit mapping "${writType}" → "${entry.templateName}": template not found — removed`);
                 this.kitMappings.delete(writType);
             }
         }
@@ -922,9 +946,9 @@ class RigTemplateRegistry {
      * Since deferred validation already ran, validate immediately.
      */
     validateIncrementalMappings() {
-        for (const [writType, templateName] of [...this.kitMappings]) {
-            if (!this.templates.has(templateName)) {
-                console.warn(`[spider] Kit mapping "${writType}" → "${templateName}": template not found — removed`);
+        for (const [writType, entry] of [...this.kitMappings]) {
+            if (this.resolveKitMappedName(entry) === undefined) {
+                console.warn(`[spider] Kit mapping "${writType}" → "${entry.templateName}": template not found — removed`);
                 this.kitMappings.delete(writType);
             }
         }
@@ -949,12 +973,18 @@ class RigTemplateRegistry {
                 return t;
             // Config points to nonexistent template — validated at startup, should not happen at runtime
         }
-        // Step 2: Kit mapping for this specific writ type
+        // Step 2: Kit mapping for this specific writ type. Unqualified
+        // templateName values resolve against the bare name first (so a
+        // config-level template of the same name wins), then fall back to the
+        // kit's own `${pluginId}.${templateName}` qualified form.
         const kitMapped = this.kitMappings.get(writType);
         if (kitMapped !== undefined) {
-            const t = this.templates.get(kitMapped);
-            if (t)
-                return t;
+            const resolved = this.resolveKitMappedName(kitMapped);
+            if (resolved !== undefined) {
+                const t = this.templates.get(resolved);
+                if (t)
+                    return t;
+            }
         }
         // No explicit mapping — writ type is inert by configuration, skip dispatch.
         return undefined;
@@ -984,8 +1014,11 @@ class RigTemplateRegistry {
      */
     listTemplateMappings() {
         const result = {};
-        for (const [writType, templateName] of this.kitMappings) {
-            result[writType] = templateName;
+        for (const [writType, entry] of this.kitMappings) {
+            // Report the resolved template name so callers can look it up
+            // directly in listTemplates() without re-implementing the
+            // bare-name-to-qualified-name fallback.
+            result[writType] = this.resolveKitMappedName(entry) ?? entry.templateName;
         }
         for (const [writType, templateName] of this.configMappings) {
             result[writType] = templateName;
@@ -1981,6 +2014,16 @@ export function createSpider() {
                     'book-updated': bookUpdatedBlockType,
                     'patron-input': patronInputBlockType,
                 },
+                rigTemplates: {
+                    default: defaultRigTemplate,
+                },
+                rigTemplateMappings: {
+                    // Unqualified reference — resolved via the registry's
+                    // config-overrides-kit fallback. If the guild declares its own
+                    // config-level `default` template, that value wins; otherwise the
+                    // registry falls back to Spider's own kit-qualified `spider.default`.
+                    mandate: 'default',
+                },
                 pages: [
                     { id: 'spider', title: 'Spider', dir: 'src/static' },
                     { id: 'feedback', title: 'Feedback', dir: 'src/static/feedback' },